@hominis/fireforge 0.44.3 → 0.45.0

package/dist/src/core/patch-lint-unmanaged-companion.js

@@ -0,0 +1,214 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Recognizes the one shape where the undefined-identifier hint sends the
+ * operator at the wrong remedy — and where taking that remedy would MASK a
+ * real bug.
+ *
+ * The shape: helpers are hoisted out of duplicated test files into a new
+ * `head_settings.js` that a managed `head.js` pulls in with
+ * `loadSubScript`. Until that companion is exported it belongs to no patch,
+ * so the per-patch checkJs program — which only ever loads patch-owned
+ * roots — cannot see any of its declarations. Every use of every hoisted
+ * helper is then reported as `Cannot find name`, and the generic hint
+ * offers three remedies of which the shim is the easiest: adding the
+ * globals to `extraShim` makes all of the warnings disappear AND makes a
+ * genuinely missing helper undetectable forever after.
+ *
+ * The warnings themselves are correct — the per-patch program's honest view
+ * of a file that is in no patch. Only the advice is wrong. FireForge
+ * already knows ownership, so when every undefined name in a file is
+ * declared at the top level of an UNMANAGED file that a managed head loads,
+ * it can name that file and the adoption command instead.
+ *
+ * Detection is deliberately conservative on both halves: a companion must
+ * be reachable from an actual `loadSubScript` call, and EVERY undefined
+ * name must resolve inside it. One unresolved name means the file may
+ * genuinely be missing a helper, and the generic hint stays.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UNDEFINED_IDENTIFIER_HINT } from './typecheck-shim.js';
+/**
+ * String literals passed anywhere inside a `loadSubScript(...)` call.
+ *
+ * The mochitest idiom is
+ * `Services.scriptloader.loadSubScript(getRootDirectory(gTestPath) + "head_settings.js", this)`,
+ * so the useful signal is the `.js` literal inside the call, not a
+ * resolvable URL — the path half is computed at runtime.
+ */
+export function findLoadSubScriptTargets(source) {
+    const targets = [];
+    // Scanned to the statement terminator rather than to a closing paren:
+    // the idiomatic argument is itself a call (`getRootDirectory(gTestPath) +
+    // "head_settings.js"`), so a non-greedy `\)` stops on the INNER paren and
+    // never reaches the literal.
+    for (const call of source.matchAll(/loadSubScript\s*\(/g)) {
+        const from = call.index + call[0].length;
+        const semicolon = source.indexOf(';', from);
+        const to = semicolon === -1 ? from + CALL_SCAN_LIMIT : Math.min(semicolon, from + CALL_SCAN_LIMIT);
+        for (const literal of source.slice(from, to).matchAll(/["'`]([^"'`]*\.js)["'`]/g)) {
+            const value = literal[1];
+            if (value !== undefined && value.length > 0)
+                targets.push(value);
+        }
+    }
+    return targets;
+}
+/** How far past a `loadSubScript(` the argument scan looks. */
+const CALL_SCAN_LIMIT = 400;
+/**
+ * Top-level declaration names in a script-scope file.
+ *
+ * Regex rather than a TS program on purpose: this runs only to decide the
+ * WORDING of a hint, the file is by definition outside every program the
+ * pass built, and a missed declaration degrades to the generic hint rather
+ * than to a wrong answer. Matching is anchored at column zero so a nested
+ * declaration inside a function body is not mistaken for a global.
+ */
+export function collectTopLevelDeclarations(source) {
+    const names = new Set();
+    const patterns = [
+        /^(?:async\s+)?function\s*\*?\s*([A-Za-z_$][\w$]*)/gm,
+        /^(?:const|let|var)\s+([A-Za-z_$][\w$]*)/gm,
+        /^class\s+([A-Za-z_$][\w$]*)/gm,
+    ];
+    for (const pattern of patterns) {
+        for (const match of source.matchAll(pattern)) {
+            const name = match[1];
+            if (name !== undefined)
+                names.add(name);
+        }
+    }
+    return names;
+}
+/**
+ * Extracts the identifier from a `Cannot find name 'X'` diagnostic message,
+ * or undefined when the message is not one.
+ */
+function extractUndefinedIdentifier(message) {
+    const match = /Cannot find name '([^']+)'/.exec(message);
+    return match?.[1];
+}
+/**
+ * Resolves the unmanaged companions reachable from a set of managed head
+ * files, given a reader for repo-relative file content.
+ *
+ * A candidate qualifies only when it is NOT in `ownedFiles` and its content
+ * can be read — an unreadable or absent target is simply not a companion,
+ * and the generic hint applies.
+ *
+ * @param heads - Repo-relative managed head files, with their sources
+ * @param ownedFiles - Every patch-owned repo-relative path
+ * @param readFile - Reads a repo-relative file, or returns undefined
+ */
+export async function resolveUnmanagedCompanions(heads, ownedFiles, readFile) {
+    const companions = [];
+    const seen = new Set();
+    for (const head of heads) {
+        const dir = head.file.slice(0, head.file.lastIndexOf('/') + 1);
+        for (const target of findLoadSubScriptTargets(head.source)) {
+            // Only same-directory targets: the runtime path is computed from the
+            // test's own directory, and a bare basename is what that idiom yields.
+            const candidate = `${dir}${target.slice(target.lastIndexOf('/') + 1)}`;
+            if (candidate === head.file || ownedFiles.has(candidate) || seen.has(candidate))
+                continue;
+            seen.add(candidate);
+            const source = await readFile(candidate);
+            if (source === undefined)
+                continue;
+            companions.push({
+                file: candidate,
+                loadedBy: head.file,
+                declarations: collectTopLevelDeclarations(source),
+            });
+        }
+    }
+    return companions;
+}
+/**
+ * The replacement hint, when every undefined name resolves in one
+ * unmanaged companion.
+ *
+ * States the ownership fact first (that is the diagnosis), then the
+ * adoption command, and explicitly rules the shim OUT — the shim is what an
+ * operator reaches for by default here, and it is the one remedy that
+ * permanently hides a genuinely missing helper.
+ */
+export function formatUnmanagedCompanionHint(companion) {
+    return (`(undefined identifier — every one of them is declared in ${companion.file}, which ` +
+        `${companion.loadedBy} loads via loadSubScript but which NO patch owns yet, so the ` +
+        `per-patch program cannot see it. Adopt it with ` +
+        `"fireforge re-export <patch> --scan --scan-file ${companion.file}". Do NOT add these ` +
+        `globals to the extra shim: that silences these warnings and every future genuinely ` +
+        `missing helper with them.)`);
+}
+/**
+ * Picks the companion that explains EVERY undefined identifier in
+ * `messages`, or undefined when none does.
+ *
+ * @param messages - Diagnostic messages reported for one file
+ * @param companions - Candidates from {@link resolveUnmanagedCompanions}
+ */
+export function explainUndefinedIdentifiers(messages, companions) {
+    const names = messages
+        .map((message) => extractUndefinedIdentifier(message))
+        .filter((name) => name !== undefined);
+    if (names.length === 0)
+        return undefined;
+    // Only the undefined-identifier diagnostics are explained here; a file
+    // carrying OTHER type errors still gets those reported untouched.
+    return companions.find((companion) => names.every((name) => companion.declarations.has(name)));
+}
+/**
+ * Reads the head files in the owned test set and resolves the UNMANAGED
+ * companions they pull in with `loadSubScript`. Hoisting shared helpers
+ * into such a companion leaves it unowned until export, and every use of
+ * every helper then reports `Cannot find name` from an honest per-patch
+ * program — see `patch-lint-unmanaged-companion.ts` for why the generic
+ * hint is actively harmful there.
+ *
+ * Best-effort: an unreadable head simply contributes no companions.
+ */
+export async function collectUnmanagedCompanions(repoDir, files, ownedFiles) {
+    const heads = [];
+    for (const file of files) {
+        const base = file.split('/').pop() ?? '';
+        if (!/^head(?:_.*)?\.js$/.test(base))
+            continue;
+        try {
+            heads.push({ file, source: await readFile(join(repoDir, file), 'utf8') });
+        }
+        catch {
+            continue;
+        }
+    }
+    if (heads.length === 0)
+        return [];
+    return resolveUnmanagedCompanions(heads, ownedFiles, async (rel) => {
+        try {
+            return await readFile(join(repoDir, rel), 'utf8');
+        }
+        catch {
+            return undefined;
+        }
+    });
+}
+/**
+ * Swaps the generic undefined-identifier hint for the ownership hint when
+ * one unmanaged companion explains EVERY undefined name in the file. Any
+ * other issue in the list is returned untouched.
+ */
+export function retargetUnmanagedCompanionHints(issues, companions) {
+    if (companions.length === 0)
+        return [...issues];
+    const undefinedIssues = issues.filter((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT));
+    if (undefinedIssues.length === 0)
+        return [...issues];
+    const companion = explainUndefinedIdentifiers(undefinedIssues.map((issue) => issue.message), companions);
+    if (!companion)
+        return [...issues];
+    const hint = formatUnmanagedCompanionHint(companion);
+    return issues.map((issue) => issue.message.includes(UNDEFINED_IDENTIFIER_HINT)
+        ? { ...issue, message: issue.message.replace(UNDEFINED_IDENTIFIER_HINT, hint) }
+        : issue);
+}

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

@@ -8,11 +8,13 @@ import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
+import { formatFileTooLargeMessage, resolveFileSizeThresholds } from './patch-lint-file-size.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
 import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
 import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
+import { invokePatchLintPrettier } from './patch-lint-prettier.js';
 // ---------------------------------------------------------------------------
 // Cross-patch lint re-exports
 // ---------------------------------------------------------------------------
@@ -31,10 +33,6 @@ export { lintPatchedCss };
 // Helpers
 // ---------------------------------------------------------------------------
 const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
-const FILE_SIZE_THRESHOLDS = {
-    general: { notice: 500, warning: 750, error: 900 },
-    test: { notice: 1200, warning: 1400, error: 1600 },
-};
 /**
  * Counts the lines of `content` the way `wc -l` reports them: a trailing
  * newline terminates the last line rather than starting an empty extra one.
@@ -407,31 +405,22 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         if (isNew) {
             const lineCount = countContentLines(content);
             const isTest = isTestFile(file);
-            const thresholds = isTest ? FILE_SIZE_THRESHOLDS.test : FILE_SIZE_THRESHOLDS.general;
+            const thresholds = resolveFileSizeThresholds(config.patchLint?.fileSizeThresholds, isTest);
             const label = isTest ? 'Test file' : 'New file';
             const verb = isTest ? 'splitting' : 'decomposing';
-            if (lineCount > thresholds.error) {
-                issues.push({
-                    file,
-                    check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'error',
-                });
-            }
-            else if (lineCount > thresholds.warning) {
+            const band = lineCount > thresholds.error
+                ? 'error'
+                : lineCount > thresholds.warning
+                    ? 'warning'
+                    : lineCount > thresholds.notice
+                        ? 'notice'
+                        : undefined;
+            if (band !== undefined) {
                 issues.push({
                     file,
                     check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'warning',
-                });
-            }
-            else if (lineCount > thresholds.notice) {
-                issues.push({
-                    file,
-                    check: 'file-too-large',
-                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
-                    severity: 'notice',
+                    message: formatFileTooLargeMessage({ label, lineCount, thresholds, band, verb }),
+                    severity: band,
                 });
             }
         }
@@ -715,6 +704,16 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
             }
         }
     }
+    // Prettier over patch-owned .sys.mjs. Deliberately NOT part of the
+    // precomputedCheckJs short-circuit: it is a separate tool with its own
+    // gate, and a queue-wide program has no equivalent to share. Scoped to
+    // the files THIS patch owns, run from engine/ so the engine's own config
+    // and ignore file decide (see `patch-lint-prettier.ts`).
+    const prettierGate = config.patchLint?.prettier ?? 'off';
+    if (prettierGate !== 'off' && patchOwnedFiles.size > 0) {
+        const scoped = [...patchOwnedFiles].filter((file) => !options?.checkJsReportScope || options.checkJsReportScope.has(file));
+        issues.push(...(await invokePatchLintPrettier(repoDir, dirname(repoDir), scoped.sort(), prettierGate)));
+    }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not
     // reclassify severities — an ignored error simply drops, mirroring how

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

@@ -18,6 +18,27 @@
  *   binary new-file conflicts as unresolvable rather than auto-resolving.
  */
 export declare function extractNewFileContentFromDiff(diff: string, targetFile?: string): string;
+/**
+ * Projects every TEXT new file a diff creates into a path → content map, for
+ * the cross-patch lint projections that build a synthetic patch-queue entry.
+ *
+ * Binary new files are SKIPPED rather than refused. The map feeds only the
+ * forward-import rule, which scans content for import statements — a binary
+ * blob authors none, so omitting it contributes exactly what including it
+ * would. Refusing instead (which is what
+ * {@link extractNewFileContentFromDiff} correctly does for a caller that
+ * named ONE file) made vendoring a new binary impossible: every projection
+ * site fed it every detected new file, so `export --order`, `re-export
+ * --scan --scan-file`, `patch move-files-into` and `patch split` all died on
+ * a file the export half had just written a valid `GIT binary patch` for.
+ * Nothing is lost by skipping: binary bodies are covered independently by the
+ * `binary-body-not-reconstructable` queue lint, and
+ * `buildPatchQueueContext` already tolerates them for real queue entries.
+ *
+ * One parse for the whole diff, rather than one per new file as the five
+ * call sites previously did.
+ */
+export declare function buildNewFileTextProjection(diff: string): Map<string, string>;
 /**
  * Extracts the complete file content from a "new file" patch.
  * When targetFile is provided, only extracts content for that file

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

@@ -27,6 +27,15 @@ export function extractNewFileContentFromDiff(diff, targetFile) {
     if (binary) {
         throw new PatchError(`Cannot extract text content from binary patch section for ${binary.targetPath}`, binary.targetPath);
     }
+    return contentFromSections(sections);
+}
+/**
+ * Walks the added (`+`) lines of already-parsed sections into file content.
+ * Shared by {@link extractNewFileContentFromDiff} and
+ * {@link buildNewFileTextProjection} so the two cannot drift on the empty-file
+ * and no-trailing-newline cases below.
+ */
+function contentFromSections(sections) {
     // An empty new file is a legitimate git diff: `new file mode` with no
     // hunks at all. It must extract as '' — the historical line-walker
     // returned '\n' for it, creating a one-byte file that failed checksum
@@ -51,6 +60,35 @@ export function extractNewFileContentFromDiff(diff, targetFile) {
     const result = contentLines.join('\n');
     return hasNoNewlineMarker ? result : result + '\n';
 }
+/**
+ * Projects every TEXT new file a diff creates into a path → content map, for
+ * the cross-patch lint projections that build a synthetic patch-queue entry.
+ *
+ * Binary new files are SKIPPED rather than refused. The map feeds only the
+ * forward-import rule, which scans content for import statements — a binary
+ * blob authors none, so omitting it contributes exactly what including it
+ * would. Refusing instead (which is what
+ * {@link extractNewFileContentFromDiff} correctly does for a caller that
+ * named ONE file) made vendoring a new binary impossible: every projection
+ * site fed it every detected new file, so `export --order`, `re-export
+ * --scan --scan-file`, `patch move-files-into` and `patch split` all died on
+ * a file the export half had just written a valid `GIT binary patch` for.
+ * Nothing is lost by skipping: binary bodies are covered independently by the
+ * `binary-body-not-reconstructable` queue lint, and
+ * `buildPatchQueueContext` already tolerates them for real queue entries.
+ *
+ * One parse for the whole diff, rather than one per new file as the five
+ * call sites previously did.
+ */
+export function buildNewFileTextProjection(diff) {
+    const newFiles = new Map();
+    for (const section of parseDiffSections(diff)) {
+        if (!section.isNewFile || section.isBinary)
+            continue;
+        newFiles.set(section.targetPath, contentFromSections([section]));
+    }
+    return newFiles;
+}
 /**
  * Extracts the complete file content from a "new file" patch.
  * When targetFile is provided, only extracts content for that file

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

@@ -29,6 +29,18 @@ export const SMOKE_ERROR_PATTERNS = [
     /^\s*\[JavaScript (Error|Warning)\]/i,
     // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
     /^\s*###!!! \[Parent\]/,
+    // A chrome:// or resource:// URL that resolves to nothing. Outside
+    // automation Gecko only PRINTS this (printf_stderr in
+    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp); under
+    // `xpc::IsInAutomation()` the same condition is a
+    // `MOZ_CRASH_UNSAFE_PRINTF` in whichever process opened the channel. So
+    // the smoke probe — which runs OUTSIDE automation — sees the printed
+    // line for the same defect that hard-crashes every harness run, and a
+    // probe that exits 0 on it reports "startup is healthy" for a build that
+    // hangs at "Waiting for browser…". Both spellings are matched: the
+    // non-automation singular `URL:` and the automation plural `URLs:`.
+    // Allowlistable through `--console-allow` like any other pattern.
+    /^\s*Missing chrome or resource URLs?:/,
 ];
 /**
  * Returns `true` when `line` matches any pattern in

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

@@ -23,6 +23,7 @@
  * reporting phantom test failures (or phantom passes).
  */
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
+import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.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.
@@ -487,12 +488,22 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     // shutdown-re-entry shape, or a requested file that never started keeps
     // the run failing. Only the missing shutdown marker is forgiven, and only
     // when the recognized teardown traceback explains it.
-    if (isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths)) {
+    const teardownOverride = evaluateGreenTeardownOverride(output, counts, realFailures, requestedPaths);
+    if (teardownOverride.accepted) {
         return { kind: 'tests-ran-ok', note: 'harness teardown noise ignored', ...counts };
     }
+    // A run that carried the recognized teardown noise and still failed says
+    // WHICH condition rejected the override, on the one greppable line.
+    const teardownNote = teardownOverride.rejectedBy !== undefined
+        ? `green-teardown override rejected: ${teardownOverride.rejectedBy}`
+        : undefined;
+    const withNotes = (verdict, extra) => {
+        const notes = [teardownNote, extra].filter((n) => n !== undefined);
+        return notes.length > 0 ? { ...verdict, note: notes.join('; ') } : verdict;
+    };
     const signature = detectHarnessCrashSignature(output);
     if (signature) {
-        return { kind: 'harness-crash', signature, ...counts };
+        return withNotes({ kind: 'harness-crash', signature, ...counts });
     }
     const ranTests = hasExecutionSignal(output);
     if (!ranTests && requestedPaths.length > 0) {
@@ -518,7 +529,7 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
         if (crashLine !== undefined ||
             completeness.neverStarted.length > 0 ||
             completeness.neverEnded.length > 0) {
-            return {
+            return withNotes({
                 kind: 'test-failures',
                 ...counts,
                 ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
@@ -529,43 +540,18 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
                     neverStarted: completeness.neverStarted,
                     neverEnded: completeness.neverEnded,
                 },
-            };
+            });
         }
         return { kind: 'tests-ran-ok', greenSummaryOverride: true, ...counts };
     }
     const wordMatchNote = unmarkedFailureEvidenceNote(counts, realFailures);
-    return {
+    return withNotes({
         kind: 'test-failures',
         ...counts,
         ...(firstRealFailure !== undefined ? { realFailureLine: firstRealFailure } : {}),
         ...(failureBlocks.length > 0 ? { realFailureBlocks: failureBlocks } : {}),
         ...(secondaryHarnessSignature !== undefined ? { secondaryHarnessSignature } : {}),
-        ...(wordMatchNote !== undefined ? { note: wordMatchNote } : {}),
-    };
-}
-/**
- * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
- * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
- * `Unexpected results: 0`, yet the run is still classified `test-failures`
- * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
- *
- * `unexpected=0` printed beside `reason=test-failures` is the tell that the
- * verdict rests on pattern matching rather than on a harness result, and a
- * reader who cannot see that spends hours attributing a red run to the
- * change under test. The note says so on the verdict line itself.
- *
- * Deliberately a NOTE and not a reclassification: a non-zero exit with no
- * green-shaped summary is still a failing run, and inventing a new `reason`
- * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
- */
-function unmarkedFailureEvidenceNote(counts, realFailures) {
-    if (counts.unexpected !== 0)
-        return undefined;
-    if (realFailures.length === 0)
-        return undefined;
-    if (realFailures.some((line) => UNEXPECTED_LINE_SINGLE.test(line)))
-        return undefined;
-    return 'summary reported 0 unexpected; no TEST-UNEXPECTED marker in the matched evidence';
+    }, wordMatchNote);
 }
 /**
  * True when the capture shows a substantively GREEN suite whose only
@@ -577,29 +563,56 @@ function unmarkedFailureEvidenceNote(counts, realFailures) {
  * unexpected count anywhere; no real `TEST-UNEXPECTED-*`/assertion line;
  * no crash marker; every requested test file both started and ended; and
  * the recognized teardown traceback is present. Anything short of that
- * falls through to the normal (failing) chain.
+ * falls through to the normal (failing) chain — with the failing condition
+ * NAMED, so the next occurrence is a filed bug rather than another
+ * undiagnosable re-run.
+ *
+ * The conditions are evaluated in a fixed order and the FIRST failing one
+ * is reported; a run can violate several, and reporting one deterministic
+ * condition beats an unordered list of everything that happened to be true.
  */
-function isGreenSuiteEndedByKnownTeardownNoise(output, counts, realFailures, requestedPaths) {
+function evaluateGreenTeardownOverride(output, counts, realFailures, requestedPaths) {
     if (!hasKnownTeardownNoise(output))
-        return false;
+        return { accepted: false };
+    const reject = (rejectedBy) => ({ accepted: false, rejectedBy });
     if (!hasExecutionSignal(output))
-        return false;
-    if (counts.checks === undefined || counts.unexpected !== 0)
-        return false;
-    if (!GREEN_UNEXPECTED_SUMMARY_PATTERN.test(output))
-        return false;
-    if (NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output))
-        return false;
-    if (realFailures.length > 0)
-        return false;
-    if (findCrashMarkerLine(output) !== undefined)
-        return false;
+        return reject('no execution signal (no TEST-START/TEST_START)');
+    if (counts.checks === undefined)
+        return reject('summary printed no "Ran N checks" line');
+    // `counts.unexpected === 0` IS the explicit-`Unexpected results: 0` test
+    // the previous revision spelled a second time with
+    // GREEN_UNEXPECTED_SUMMARY_PATTERN: the count is parsed from the same
+    // line and an absent line leaves it undefined. The two are kept apart in
+    // the message because "printed no such line" and "printed a non-zero one"
+    // are different findings for the reader.
+    if (counts.unexpected === undefined) {
+        return reject('summary printed no "Unexpected results:" line');
+    }
+    if (counts.unexpected !== 0) {
+        return reject(`summary reported unexpected=${String(counts.unexpected)}`);
+    }
+    if (NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output)) {
+        return reject('a non-zero "Unexpected results:" line is present somewhere in the output');
+    }
+    if (realFailures.length > 0) {
+        return reject(`${String(realFailures.length)} matched failure line(s), first: ${truncateEvidence(realFailures[0] ?? '')}`);
+    }
+    const crashLine = findCrashMarkerLine(output);
+    if (crashLine !== undefined)
+        return reject(`crash marker present: ${truncateEvidence(crashLine)}`);
     // The post-green shutdown re-entry shape is deliberately a crash verdict
     // on an otherwise-green log; it must not be swept up here.
-    if (SHUTDOWN_REENTRY_PATTERN.test(output))
-        return false;
+    if (SHUTDOWN_REENTRY_PATTERN.test(output)) {
+        return reject('post-green shutdown re-entry shape present');
+    }
     const completeness = analyzeTestCompleteness(output, requestedPaths);
-    return completeness.neverStarted.length === 0 && completeness.neverEnded.length === 0;
+    if (completeness.neverStarted.length > 0) {
+        return reject(`requested file(s) never started: ${completeness.neverStarted.join(', ')}`);
+    }
+    if (completeness.neverEnded.length > 0) {
+        return reject(`requested file(s) never ended: ${completeness.neverEnded.join(', ')}`);
+    }
+    return { accepted: true };
 }
 /**
  * Parses the numeric counts from the harness's embedded result summary

package/dist/src/core/test-harness-verdict-notes.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Verdict-note helpers for the harness classifier.
+ *
+ * Split out of `test-harness-crash.ts` (at its per-file line budget). These
+ * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * of them changes a status or a reason key, which the verdict contract's
+ * consumers parse.
+ */
+/**
+ * The only part of the classifier's summary counts these notes read.
+ * Structural rather than an import of `HarnessSummaryCounts`: a type edge
+ * back into `test-harness-crash.ts` is still an edge, and the cycle gate
+ * rejects it.
+ */
+interface SummaryCountsView {
+    unexpected?: number;
+}
+/**
+ * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
+ * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
+ * `Unexpected results: 0`, yet the run is still classified `test-failures`
+ * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
+ *
+ * `unexpected=0` printed beside `reason=test-failures` is the tell that the
+ * verdict rests on pattern matching rather than on a harness result, and a
+ * reader who cannot see that spends hours attributing a red run to the
+ * change under test. The note says so on the verdict line itself.
+ *
+ * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * green-shaped summary is still a failing run, and inventing a new `reason`
+ * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
+ */
+export declare function unmarkedFailureEvidenceNote(counts: SummaryCountsView, realFailures: readonly string[]): string | undefined;
+/** Caps an evidence line so the one-line verdict note stays one line. */
+export declare function truncateEvidence(line: string): string;
+/**
+ * Outcome of the green-teardown belt.
+ *
+ * `accepted` is the pass. A rejection carries `rejectedBy` ONLY when the
+ * recognized teardown noise was present — i.e. when the belt was the thing
+ * that could have applied and did not. That distinction is the whole point
+ * of the field: a run with no teardown traceback was never a candidate and
+ * naming a "rejecting condition" for it would be noise, whereas a run that
+ * DOES carry the traceback and still fails is the shape an operator
+ * otherwise cannot diagnose from outside — every condition is
+ * all-or-nothing, so the failing verdict looks identical whichever one
+ * rejected it, and a downstream report spent a re-run and a filed-bug's
+ * worth of effort guessing between them.
+ */
+export interface GreenTeardownOverride {
+    accepted: boolean;
+    /** Which single condition rejected, when the teardown noise was present. */
+    rejectedBy?: string;
+}
+export {};

package/dist/src/core/test-harness-verdict-notes.js

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Verdict-note helpers for the harness classifier.
+ *
+ * Split out of `test-harness-crash.ts` (at its per-file line budget). These
+ * decide the ADVISORY parenthetical on the `FIREFORGE-VERDICT:` line; none
+ * of them changes a status or a reason key, which the verdict contract's
+ * consumers parse.
+ */
+/**
+ * A single `TEST-UNEXPECTED-*` marker. Local copy of the classifier's line
+ * pattern: importing the value would draw a runtime edge back into
+ * `test-harness-crash.ts` and make the split circular.
+ */
+const UNEXPECTED_MARKER = /TEST-UNEXPECTED-\w+/;
+/**
+ * Belt for the residual case the tightened {@link FAIL_LINE_PATTERN} /
+ * {@link ASSERTION_LINE_PATTERN} cannot reach: the summary reported
+ * `Unexpected results: 0`, yet the run is still classified `test-failures`
+ * on evidence lines that carry NO `TEST-UNEXPECTED-*` marker.
+ *
+ * `unexpected=0` printed beside `reason=test-failures` is the tell that the
+ * verdict rests on pattern matching rather than on a harness result, and a
+ * reader who cannot see that spends hours attributing a red run to the
+ * change under test. The note says so on the verdict line itself.
+ *
+ * Deliberately a NOTE and not a reclassification: a non-zero exit with no
+ * green-shaped summary is still a failing run, and inventing a new `reason`
+ * would break the `FIREFORGE-VERDICT:` contract its consumers parse.
+ */
+export function unmarkedFailureEvidenceNote(counts, realFailures) {
+    if (counts.unexpected !== 0)
+        return undefined;
+    if (realFailures.length === 0)
+        return undefined;
+    if (realFailures.some((line) => UNEXPECTED_MARKER.test(line)))
+        return undefined;
+    return 'summary reported 0 unexpected; no TEST-UNEXPECTED marker in the matched evidence';
+}
+/** Caps an evidence line so the one-line verdict note stays one line. */
+export function truncateEvidence(line) {
+    const flat = line.trim().replace(/\s+/g, ' ');
+    return flat.length <= GREEN_TEARDOWN_EVIDENCE_LIMIT
+        ? flat
+        : `${flat.slice(0, GREEN_TEARDOWN_EVIDENCE_LIMIT)}…`;
+}
+/** Character budget for an evidence excerpt inside the verdict note. */
+const GREEN_TEARDOWN_EVIDENCE_LIMIT = 80;