@hominis/fireforge 0.32.0 → 0.34.0

package/dist/src/core/register-scaffold.js

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Manifest scaffolding for `fireforge register --create-manifest`
+ * (0.34.0 field report): registering a module under a directory with no
+ * moz.build used to fail with "Manifest not found" because `register`
+ * only inserts into EXISTING manifests. This module owns the two
+ * scaffolding primitives:
+ *
+ *  - creating a directory `moz.build` (license header + the requested
+ *    list directive) and wiring the parent chain's `DIRS` entries up to
+ *    the nearest existing moz.build;
+ *  - wiring an `XPCSHELL_TESTS_MANIFESTS` entry for a (possibly freshly
+ *    created) `xpcshell.toml` into the nearest existing moz.build.
+ *
+ * All writers reuse the tokenizer + alphabetical-position helpers the
+ * existing register writers use, so inserted entries respect mozbuild's
+ * case-insensitive StrictOrderingOnAppendList rule.
+ */
+import { dirname, join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { getLicenseHeader } from './license-headers.js';
+import { findAlphabeticalMozBuildPosition } from './manifest-helpers.js';
+import { tokenizeMozBuildList } from './manifest-tokenizers.js';
+/**
+ * moz.build files use Firefox's canonical MPL-2.0 hash-comment header
+ * regardless of the fork's own project license — they live in the engine
+ * tree among upstream MPL files.
+ */
+function mozBuildHeader() {
+    return getLicenseHeader('MPL-2.0', 'hash');
+}
+/**
+ * Inserts `value` into the named moz.build list directive, creating the
+ * `NAME += [ ... ]` block at the end of the file when the directive does
+ * not exist yet. Returns the updated content, or null when the value is
+ * already present.
+ */
+export function upsertMozBuildListEntry(content, directive, value) {
+    if (content.includes(`"${value}"`))
+        return null;
+    const lines = content.split('\n');
+    const listResult = tokenizeMozBuildList(lines, new RegExp(`^${directive}\\b`));
+    if (listResult) {
+        const { insertIndex } = findAlphabeticalMozBuildPosition(listResult.tokens, value);
+        lines.splice(insertIndex, 0, `    "${value}",`);
+        return lines.join('\n');
+    }
+    // No existing list: append a fresh block, keeping exactly one blank
+    // line between the previous content and the new directive.
+    while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
+        lines.pop();
+    const block = [`${directive} += [`, `    "${value}",`, `]`];
+    return [...lines, ...(lines.length > 0 ? [''] : []), ...block, ''].join('\n');
+}
+/**
+ * Ensures every parent directory between `childRelDir` and the nearest
+ * existing moz.build carries a `DIRS` entry pointing at the next segment
+ * down, creating intermediate moz.build files as needed. Walks upward
+ * from the child's parent; throws when no moz.build exists anywhere up
+ * to the engine root (an engine checkout always has one at the root, so
+ * this indicates a bogus path).
+ */
+export async function ensureParentDirsWiring(engineDir, childRelDir, dryRun) {
+    const actions = [];
+    let childName = childRelDir.split('/').at(-1) ?? childRelDir;
+    let parentRel = dirname(childRelDir).replace(/\\/g, '/');
+    for (;;) {
+        if (parentRel === '.' || parentRel === '' || parentRel === '/') {
+            throw new GeneralError(`No moz.build found in any parent of ${childRelDir} up to the engine root; ` +
+                'cannot wire the DIRS chain. Check the path.');
+        }
+        const parentManifestRel = `${parentRel}/moz.build`;
+        const parentManifestPath = join(engineDir, parentManifestRel);
+        if (await pathExists(parentManifestPath)) {
+            const content = await readText(parentManifestPath);
+            const updated = upsertMozBuildListEntry(content, 'DIRS', childName);
+            if (updated !== null) {
+                if (!dryRun)
+                    await writeText(parentManifestPath, updated);
+                actions.push({ manifest: parentManifestRel, change: `DIRS += ["${childName}"]` });
+            }
+            return actions;
+        }
+        // Parent has no moz.build either: scaffold one carrying the DIRS
+        // entry and keep walking up until an existing manifest anchors the
+        // chain.
+        const scaffold = `${mozBuildHeader()}\n\nDIRS += [\n    "${childName}",\n]\n`;
+        if (!dryRun)
+            await writeText(parentManifestPath, scaffold);
+        actions.push({ manifest: parentManifestRel, change: `created with DIRS += ["${childName}"]` });
+        childName = parentRel.split('/').at(-1) ?? parentRel;
+        parentRel = dirname(parentRel).replace(/\\/g, '/');
+    }
+}
+/**
+ * Creates `<moduleDir>/moz.build` with an `EXTRA_JS_MODULES.<namespace>`
+ * list containing `fileName`, and wires the parent DIRS chain. The
+ * namespace is the module directory's basename (the fork's binary name
+ * for `browser/modules/<binaryName>/`), matching Firefox's convention of
+ * mapping `EXTRA_JS_MODULES.<ns>` into `resource:///modules/<ns>/`.
+ */
+export async function scaffoldModuleMozBuild(engineDir, moduleDir, fileName, dryRun) {
+    const namespace = moduleDir.split('/').at(-1) ?? moduleDir;
+    const manifestRel = `${moduleDir}/moz.build`;
+    const content = `${mozBuildHeader()}\n\nEXTRA_JS_MODULES.${namespace} += [\n    "${fileName}",\n]\n`;
+    if (!dryRun)
+        await writeText(join(engineDir, manifestRel), content);
+    const actions = [
+        {
+            manifest: manifestRel,
+            change: `created with EXTRA_JS_MODULES.${namespace} += ["${fileName}"]`,
+        },
+    ];
+    actions.push(...(await ensureParentDirsWiring(engineDir, moduleDir, dryRun)));
+    return actions;
+}
+/**
+ * Wires an `XPCSHELL_TESTS_MANIFESTS` entry for `manifestRelPath` (an
+ * engine-relative `.../xpcshell.toml`) into the nearest EXISTING
+ * moz.build above it. Returns the performed actions (empty when the
+ * entry already exists).
+ */
+export async function ensureXpcshellManifestWiring(engineDir, manifestRelPath, dryRun) {
+    let dirRel = dirname(manifestRelPath).replace(/\\/g, '/');
+    for (;;) {
+        if (dirRel === '.' || dirRel === '' || dirRel === '/') {
+            throw new GeneralError(`No moz.build found in any parent of ${manifestRelPath} up to the engine root; ` +
+                'cannot wire XPCSHELL_TESTS_MANIFESTS. Check the path.');
+        }
+        const mozBuildRel = `${dirRel}/moz.build`;
+        const mozBuildPath = join(engineDir, mozBuildRel);
+        if (await pathExists(mozBuildPath)) {
+            const relEntry = manifestRelPath.slice(dirRel.length + 1);
+            const content = await readText(mozBuildPath);
+            const updated = upsertMozBuildListEntry(content, 'XPCSHELL_TESTS_MANIFESTS', relEntry);
+            if (updated === null)
+                return [];
+            if (!dryRun)
+                await writeText(mozBuildPath, updated);
+            return [{ manifest: mozBuildRel, change: `XPCSHELL_TESTS_MANIFESTS += ["${relEntry}"]` }];
+        }
+        dirRel = dirname(dirRel).replace(/\\/g, '/');
+    }
+}
+//# sourceMappingURL=register-scaffold.js.map

package/dist/src/core/register-test-manifest.js

@@ -27,7 +27,9 @@ function registerTestManifestTokenized(content, testDir, entry) {
 function legacyRegisterTestManifest(content, testDir, entry) {
     const lines = content.split('\n');
     const extractKey = (line) => {
-        const match = /"content\/test\/([^/]+)\/browser\.toml"/.exec(line);
+        // Nested manifests (`content/test/a/b/browser.toml`) are supported —
+        // capture the whole directory chain, not just one segment.
+        const match = /"content\/test\/(.+)\/browser\.toml"/.exec(line);
         return match?.[1];
     };
     let sectionStart = -1;

package/dist/src/core/register-xpcshell-test.d.ts

@@ -0,0 +1,30 @@
+/**
+ * xpcshell test-file registration (0.34.0 field report): xpcshell test
+ * files (e.g. `<module-dir>/test/unit/test_*.js`) were rejected by
+ * `fireforge register` as "Unknown file pattern". This writer inserts the
+ * `["test_*.js"]` section into the directory's `xpcshell.toml`
+ * (alphabetically, idempotently) and — with `--create-manifest` — creates
+ * the manifest and wires `XPCSHELL_TESTS_MANIFESTS` into the nearest
+ * moz.build.
+ */
+import type { RegisterResult } from './register-result.js';
+/**
+ * Checks whether the test file is listed in its directory's
+ * `xpcshell.toml`. Throws a "Manifest not found" error when the manifest
+ * does not exist (status catches that prefix and reports the manifest as
+ * missing rather than the file as unregistered).
+ */
+export declare function isXpcshellTestRegistered(engineDir: string, dirRel: string, fileName: string): Promise<boolean>;
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content in
+ * mozbuild's case-insensitive sort order relative to the other test
+ * sections, keeping one blank line between sections. Exported for direct
+ * unit testing.
+ */
+export declare function insertXpcshellManifestSection(content: string, fileName: string): string;
+/**
+ * Registers an xpcshell test file in its directory's `xpcshell.toml`.
+ * With `createManifest`, a missing manifest is scaffolded and wired into
+ * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
+ */
+export declare function registerXpcshellTest(engineDir: string, dirRel: string, fileName: string, dryRun?: boolean, createManifest?: boolean): Promise<RegisterResult>;

package/dist/src/core/register-xpcshell-test.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * xpcshell test-file registration (0.34.0 field report): xpcshell test
+ * files (e.g. `<module-dir>/test/unit/test_*.js`) were rejected by
+ * `fireforge register` as "Unknown file pattern". This writer inserts the
+ * `["test_*.js"]` section into the directory's `xpcshell.toml`
+ * (alphabetically, idempotently) and — with `--create-manifest` — creates
+ * the manifest and wires `XPCSHELL_TESTS_MANIFESTS` into the nearest
+ * moz.build.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { mozbuildSortCompare } from './manifest-helpers.js';
+import { ensureXpcshellManifestWiring } from './register-scaffold.js';
+function manifestMissingError(manifestRel) {
+    return new GeneralError(`Manifest not found: ${manifestRel}. ` +
+        'Pass --create-manifest to scaffold the xpcshell.toml and wire XPCSHELL_TESTS_MANIFESTS ' +
+        'into the nearest moz.build.');
+}
+/**
+ * Checks whether the test file is listed in its directory's
+ * `xpcshell.toml`. Throws a "Manifest not found" error when the manifest
+ * does not exist (status catches that prefix and reports the manifest as
+ * missing rather than the file as unregistered).
+ */
+export async function isXpcshellTestRegistered(engineDir, dirRel, fileName) {
+    const manifestRel = `${dirRel}/xpcshell.toml`;
+    const manifestPath = join(engineDir, manifestRel);
+    if (!(await pathExists(manifestPath))) {
+        throw manifestMissingError(manifestRel);
+    }
+    const content = await readText(manifestPath);
+    return content.includes(`["${fileName}"]`);
+}
+/**
+ * Inserts the `["<fileName>"]` section into the manifest content in
+ * mozbuild's case-insensitive sort order relative to the other test
+ * sections, keeping one blank line between sections. Exported for direct
+ * unit testing.
+ */
+export function insertXpcshellManifestSection(content, fileName) {
+    const lines = content.split('\n');
+    const sectionHeaderPattern = /^\["([^"]+)"\]\s*$/;
+    let insertIndex = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        const match = sectionHeaderPattern.exec(lines[i] ?? '');
+        if (!match)
+            continue;
+        if (insertIndex === -1 && mozbuildSortCompare(fileName, match[1] ?? '') < 0) {
+            insertIndex = i;
+        }
+    }
+    if (insertIndex !== -1) {
+        lines.splice(insertIndex, 0, `["${fileName}"]`, '');
+        return lines.join('\n');
+    }
+    // Append after the last section (or at end of file when there are no
+    // sections yet), keeping exactly one trailing newline.
+    while (lines.length > 0 && (lines.at(-1) ?? '').trim() === '')
+        lines.pop();
+    return [...lines, '', `["${fileName}"]`, ''].join('\n');
+}
+/**
+ * Registers an xpcshell test file in its directory's `xpcshell.toml`.
+ * With `createManifest`, a missing manifest is scaffolded and wired into
+ * the nearest moz.build via `XPCSHELL_TESTS_MANIFESTS`.
+ */
+export async function registerXpcshellTest(engineDir, dirRel, fileName, dryRun = false, createManifest = false) {
+    const manifestRel = `${dirRel}/xpcshell.toml`;
+    const manifestPath = join(engineDir, manifestRel);
+    const entry = `["${fileName}"]`;
+    if (!(await pathExists(manifestPath))) {
+        if (!createManifest) {
+            throw manifestMissingError(manifestRel);
+        }
+        const scaffoldActions = [
+            { manifest: manifestRel, change: `created with ${entry}` },
+        ];
+        if (!dryRun) {
+            await writeText(manifestPath, `[DEFAULT]\n\n${entry}\n`);
+        }
+        scaffoldActions.push(...(await ensureXpcshellManifestWiring(engineDir, manifestRel, dryRun)));
+        return { manifest: manifestRel, entry, skipped: false, scaffoldActions };
+    }
+    const content = await readText(manifestPath);
+    if (content.includes(entry)) {
+        return { manifest: manifestRel, entry, skipped: true };
+    }
+    const updated = insertXpcshellManifestSection(content, fileName);
+    if (!dryRun) {
+        await writeText(manifestPath, updated);
+    }
+    return { manifest: manifestRel, entry, skipped: false };
+}
+//# sourceMappingURL=register-xpcshell-test.js.map

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

@@ -32,7 +32,32 @@ export interface HarnessCrashSignature {
 export interface HarnessRunVerdict {
     kind: HarnessRunClassification;
     signature?: HarnessCrashSignature;
+    /**
+     * Set when a non-zero mach exit code was overridden because the output
+     * embeds a completed green summary — the exit code followed harness
+     * noise, not a test result. Callers should surface a note.
+     */
+    greenSummaryOverride?: boolean;
 }
+/**
+ * Strips non-signal noise from captured output before crash-signature
+ * matching: resource-monitor degradation warnings, and traceback blocks
+ * that mach caught itself (telemetry submission tracebacks are printed but
+ * never abort the run). The stripped text is used ONLY as crash evidence —
+ * classification of test results still reads the full output.
+ */
+export declare function stripNonSignalNoise(output: string): string;
+/**
+ * True when the output embeds a COMPLETED, GREEN suite summary: an
+ * execution signal, `Unexpected results: 0` (and no non-zero unexpected
+ * count), a `SUITE_END` marker, and no real `TEST-UNEXPECTED-*` lines.
+ * Such a run finished its suite; any startup-traceback-shaped noise in the
+ * same output is by definition non-fatal, so this vetoes signature-based
+ * crash classification (field report: fully green sharded runs reported
+ * `CRASH (N attempts)` because degradation warnings matched the psutil
+ * signals). Exported for direct unit testing.
+ */
+export declare function hasCompletedGreenSummary(output: string): boolean;
 /**
  * Detects the known harness-crash shapes in captured mach output.
  * Returns undefined for anything that looks like a genuine test result.
@@ -44,15 +69,18 @@ export declare function detectHarnessCrashSignature(output: string): HarnessCras
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run;
  *    the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No `TEST-START` with explicit paths requested means no test ran —
- *    `no-tests`, even when the exit code is zero. Summary lines are not
- *    trusted as evidence of execution.
+ * 2. No execution signal with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. The execution signal is
+ *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
+ *    OR the suite-specific xpcshell result-summary block (the xpcshell
+ *    dispatch prints no `TEST-START`). Bare `Passed:`/`Failed:` summary
+ *    lines are still not trusted as evidence of execution.
  * 3. Exit code zero with tests started is a pass; anything else is a
  *    test failure for the regular diagnosis chain.
  */
 export declare function classifyHarnessRun(exitCode: number, output: string, requestedPaths: readonly string[]): HarnessRunVerdict;
 /** Builds the operator-facing failure message after retries are exhausted. */
-export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number): string;
+export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`

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

@@ -23,6 +23,29 @@
  * of reporting phantom test failures (or phantom passes).
  */
 const TEST_START_PATTERN = /\bTEST-START\b/;
+/**
+ * Structured-log execution marker (`mach xpcshell-test` mozlog output uses
+ * `TEST_START`/`SUITE_END` with underscores, not the hyphenated
+ * `TEST-START` the browser-chrome dispatch prints).
+ */
+const STRUCTURED_TEST_START_PATTERN = /\bTEST_START\b/;
+const SUITE_END_PATTERN = /\bSUITE_END\b/;
+const GREEN_UNEXPECTED_SUMMARY_PATTERN = /\bUnexpected results:\s*0\b/;
+const NONZERO_UNEXPECTED_SUMMARY_PATTERN = /\bUnexpected results:\s*[1-9]/;
+/**
+ * Execution signals emitted by the suite-specific xpcshell dispatch
+ * (`mach xpcshell-test`), which does NOT print `TEST-START` lines the way
+ * the generic `mach test` / browser-chrome dispatch does. A passing
+ * single-file xpcshell run prints a result-summary block instead
+ * (`TEST_END: Test PASS`, `Ran 16 checks`, `Unexpected results: 0`), so
+ * keying execution purely on `TEST-START` mis-reads a green xpcshell run as
+ * "no tests started" (field report: a single-file xpcshell pass exited 1).
+ *
+ * These markers are xpcshell-specific on purpose: the bare
+ * `Passed: 0` / `Failed: 0` summary that the no-output hang shape prints is
+ * deliberately NOT matched here — that case must still read as `no-tests`.
+ */
+const XPCSHELL_RESULT_SUMMARY_PATTERN = /\bTEST_END\b|\bRan \d+ checks?\b|\bResult summary:/i;
 const UNEXPECTED_LINE_PATTERN = /^.*\bTEST-UNEXPECTED-[A-Z-]+\b.*$/gm;
 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;
@@ -49,6 +72,97 @@ function findLine(output, patterns) {
     }
     return undefined;
 }
+/**
+ * Non-signal noise lines: the resource-monitor degrade path (FireForge's
+ * own guard plus mozlog's `_collect failed`) prints warnings on runs that
+ * then complete green. Field report (0.34.0 cycle): every multi-file suite
+ * was reported CRASH because these lines matched the startup-traceback
+ * signals even though the embedded summary was fully green. They are
+ * excluded from crash evidence entirely.
+ */
+const NOISE_LINE_PATTERNS = [
+    /\bUserWarning\b/,
+    /psutil failed to run/i,
+    /_collect failed/i,
+    /FireForge: host resource monitor degraded/i,
+    /warnings\.warn\(/,
+];
+/** Matches the caught/telemetry context that marks a traceback as benign. */
+const BENIGN_TRACEBACK_CONTEXT = /telemetry|glean/i;
+/**
+ * Strips non-signal noise from captured output before crash-signature
+ * matching: resource-monitor degradation warnings, and traceback blocks
+ * that mach caught itself (telemetry submission tracebacks are printed but
+ * never abort the run). The stripped text is used ONLY as crash evidence —
+ * classification of test results still reads the full output.
+ */
+export function stripNonSignalNoise(output) {
+    const lines = output.split(/\r?\n/);
+    const kept = [];
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? '';
+        if (NOISE_LINE_PATTERNS.some((p) => p.test(line)))
+            continue;
+        if (TRACEBACK_PATTERN.test(line)) {
+            // Collect the whole traceback block: the header, indented frame/code
+            // lines, and the trailing unindented exception line.
+            const block = [line];
+            let j = i + 1;
+            for (; j < lines.length; j += 1) {
+                const blockLine = lines[j] ?? '';
+                block.push(blockLine);
+                const isIndented = /^\s/.test(blockLine) || blockLine.trim().length === 0;
+                if (!isIndented)
+                    break; // unindented exception line terminates the block
+            }
+            if (BENIGN_TRACEBACK_CONTEXT.test(block.join('\n'))) {
+                i = j; // drop the whole caught-telemetry traceback block
+                continue;
+            }
+            // A real traceback stays in evidence line-by-line (minus noise lines
+            // already filtered above).
+        }
+        kept.push(line);
+    }
+    return kept.join('\n');
+}
+/**
+ * True when the output carries any execution signal: the browser-chrome
+ * `TEST-START` marker, the structured-log `TEST_START` marker, or the
+ * suite-specific xpcshell result-summary block.
+ */
+function hasExecutionSignal(output) {
+    return (TEST_START_PATTERN.test(output) ||
+        STRUCTURED_TEST_START_PATTERN.test(output) ||
+        hasXpcshellResultSummary(output));
+}
+/**
+ * True when the output embeds a COMPLETED, GREEN suite summary: an
+ * execution signal, `Unexpected results: 0` (and no non-zero unexpected
+ * count), a `SUITE_END` marker, and no real `TEST-UNEXPECTED-*` lines.
+ * Such a run finished its suite; any startup-traceback-shaped noise in the
+ * same output is by definition non-fatal, so this vetoes signature-based
+ * crash classification (field report: fully green sharded runs reported
+ * `CRASH (N attempts)` because degradation warnings matched the psutil
+ * signals). Exported for direct unit testing.
+ */
+export function hasCompletedGreenSummary(output) {
+    return (hasExecutionSignal(output) &&
+        SUITE_END_PATTERN.test(output) &&
+        GREEN_UNEXPECTED_SUMMARY_PATTERN.test(output) &&
+        !NONZERO_UNEXPECTED_SUMMARY_PATTERN.test(output) &&
+        realUnexpectedFailureLines(output).length === 0);
+}
+/**
+ * True when the captured output carries the suite-specific xpcshell
+ * result-summary block, which proves tests executed even though the
+ * xpcshell dispatch emits no `TEST-START` line. Used alongside
+ * `TEST_START_PATTERN` so a green single-file xpcshell run is not
+ * mis-classified as `no-tests`. Exported for direct unit testing.
+ */
+function hasXpcshellResultSummary(output) {
+    return XPCSHELL_RESULT_SUMMARY_PATTERN.test(output);
+}
 /** Unexpected-failure lines that are NOT the shutdown re-entry artifact. */
 function realUnexpectedFailureLines(output) {
     const matches = output.match(UNEXPECTED_LINE_PATTERN) ?? [];
@@ -59,13 +173,22 @@ function realUnexpectedFailureLines(output) {
  * Returns undefined for anything that looks like a genuine test result.
  */
 export function detectHarnessCrashSignature(output) {
-    const hasTestStart = TEST_START_PATTERN.test(output);
+    const hasTestStart = hasExecutionSignal(output);
     const realFailures = realUnexpectedFailureLines(output);
-    // Startup traceback cluster (resource monitor / psutil). Real test
-    // failures take precedence: a traceback printed during teardown of a
-    // genuinely failing run must not get the whole run retried.
-    if (TRACEBACK_PATTERN.test(output) && realFailures.length === 0) {
-        const signalLine = findLine(output, STARTUP_TRACEBACK_SIGNALS);
+    // A completed green embedded summary vetoes signature-based crash
+    // classification outright: the suite finished, so any startup-shaped
+    // noise in the same output was non-fatal. (The post-green shutdown
+    // re-entry shape below is exempt — it is deliberately a crash verdict on
+    // an otherwise-green log, keyed on its own explicit markers.)
+    const greenSummaryVeto = hasCompletedGreenSummary(output);
+    // Startup traceback cluster (resource monitor / psutil), scanned over
+    // noise-stripped evidence so degradation warnings and caught telemetry
+    // tracebacks never count. Real test failures take precedence: a
+    // traceback printed during teardown of a genuinely failing run must not
+    // get the whole run retried.
+    const evidence = stripNonSignalNoise(output);
+    if (!greenSummaryVeto && TRACEBACK_PATTERN.test(evidence) && realFailures.length === 0) {
+        const signalLine = findLine(evidence, STARTUP_TRACEBACK_SIGNALS);
         if (signalLine) {
             return { reason: 'harness startup traceback (resource monitor/psutil)', line: signalLine };
         }
@@ -74,7 +197,7 @@ export function detectHarnessCrashSignature(output) {
     // the no-output timeout. A trailing "Passed: 0" summary is part of this
     // shape and must not be read as a result.
     if (!hasTestStart) {
-        const timeoutLine = findLine(output, [NO_OUTPUT_TIMEOUT_PATTERN]);
+        const timeoutLine = findLine(evidence, [NO_OUTPUT_TIMEOUT_PATTERN]);
         if (timeoutLine) {
             return { reason: 'no-output timeout before any test started', line: timeoutLine };
         }
@@ -95,9 +218,12 @@ export function detectHarnessCrashSignature(output) {
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run;
  *    the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No `TEST-START` with explicit paths requested means no test ran —
- *    `no-tests`, even when the exit code is zero. Summary lines are not
- *    trusted as evidence of execution.
+ * 2. No execution signal with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. The execution signal is
+ *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
+ *    OR the suite-specific xpcshell result-summary block (the xpcshell
+ *    dispatch prints no `TEST-START`). Bare `Passed:`/`Failed:` summary
+ *    lines are still not trusted as evidence of execution.
  * 3. Exit code zero with tests started is a pass; anything else is a
  *    test failure for the regular diagnosis chain.
  */
@@ -106,14 +232,26 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     if (signature) {
         return { kind: 'harness-crash', signature };
     }
-    if (!TEST_START_PATTERN.test(output) && requestedPaths.length > 0) {
+    const ranTests = hasExecutionSignal(output);
+    if (!ranTests && requestedPaths.length > 0) {
         return { kind: 'no-tests' };
     }
-    return exitCode === 0 ? { kind: 'tests-ran-ok' } : { kind: 'test-failures' };
+    if (exitCode === 0) {
+        return { kind: 'tests-ran-ok' };
+    }
+    // Exit codes follow the corrected verdict: a run whose embedded summary
+    // completed green is a pass even when the wrapper exit code went
+    // non-zero on harness noise (field report: a fully green --no-shard run
+    // exited 1). Real failures always carry a non-zero unexpected count or
+    // TEST-UNEXPECTED lines, both of which fail the green-summary check.
+    if (hasCompletedGreenSummary(output)) {
+        return { kind: 'tests-ran-ok', greenSummaryOverride: true };
+    }
+    return { kind: 'test-failures' };
 }
 /** Builds the operator-facing failure message after retries are exhausted. */
-export function buildHarnessCrashMessage(signature, attempts) {
-    return (`mach test crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
+export function buildHarnessCrashMessage(signature, attempts, commandLabel = 'mach test') {
+    return (`${commandLabel} crashed in the harness itself (not in your tests) on all ${attempts} attempt(s).\n\n` +
         `Detected shape: ${signature.reason}\n` +
         `Evidence line: ${signature.line}\n\n` +
         'This failure mode is environmental (mozlog resource monitor / psutil on macOS, focus-stall ' +

package/dist/src/core/token-dark-mode.d.ts

@@ -38,6 +38,15 @@ export declare function stripBlockCommentsInLines(lines: string[]): string[];
  * can splice into the original `lines` array at the returned index.
  */
 export declare function findDarkRootInsertionIndex(lines: string[]): number | null;
+/**
+ * Depth-counts braces from `startLine` (whose lines must already have
+ * block comments stripped), returning the index of the line on which the
+ * block opened there returns to its entry depth — i.e. the line carrying
+ * the block's closing `}` — or -1 when the block never closes. The first
+ * `{` encountered sets the entry depth, so the scan may start on the
+ * selector/at-rule line itself rather than on the opener.
+ */
+export declare function findBlockCloseIndex(stripped: string[], startLine: number): number;
 /**
  * Finds the closing `}` of the outermost
  * `@media (prefers-color-scheme: dark)` block. Used as the fallback

package/dist/src/core/token-dark-mode.js

@@ -122,7 +122,7 @@ export function findDarkRootInsertionIndex(lines) {
  * `{` encountered sets the entry depth, so the scan may start on the
  * selector/at-rule line itself rather than on the opener.
  */
-function findBlockCloseIndex(stripped, startLine) {
+export function findBlockCloseIndex(stripped, startLine) {
     let depth = 0;
     let entryDepth = 0;
     let enteredBlock = false;

package/dist/src/core/token-docs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Documentation-table updates for `fireforge token add`. Extracted from
+ * `token-manager.ts` so the CSS-mutation path and the Markdown-table path
+ * each stay within the per-file line budget. Consumed only by token-manager.
+ */
+/**
+ * Minimal token shape the docs updater needs. Declared locally (rather than
+ * importing `AddTokenOptions`) so this module has no edge back to
+ * `token-manager.ts` — `AddTokenOptions` is structurally compatible.
+ */
+export interface TokenDocInput {
+    tokenName: string;
+    value: string;
+    category: string;
+    mode: string;
+    description?: string | undefined;
+}
+/**
+ * Adds a token row to the main token table, the unmapped table (for
+ * literal values), and bumps the mode count table. Each sub-update runs
+ * against a freshly parsed view of the document so that splice indices
+ * stay valid as rewrites are layered.
+ *
+ * @param annotation - The mode annotation string the caller already computed
+ *   (kept here as a parameter so this module needs no dependency on
+ *   token-manager's `getModeAnnotation`).
+ */
+export declare function addTokenToDocs(engineDir: string, options: TokenDocInput, annotation: string): Promise<{
+    docsAdded: boolean;
+    unmappedAdded: boolean;
+    countUpdated: boolean;
+}>;