@hominis/fireforge 0.36.0 → 0.38.0

package/dist/src/core/furnace-stale-export.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
+ *
+ * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * the `components/` sources. Editing a component source and re-exporting
+ * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy — per-patch lint then flags the old line
+ * count and the patch body lags the source. This gate detects that
+ * sequence by comparing component source directories against the checksums
+ * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
+ * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
+ * unless the operator passes `--allow-stale-furnace`.
+ *
+ * Checksum-based on purpose: git checkouts and `furnace refresh` churn
+ * mtimes without content changes, so an mtime comparison would misfire.
+ *
+ * Probe failures (broken furnace config, missing state) degrade to a
+ * verbose log and an empty result — a broken furnace setup must never
+ * block non-furnace patch work.
+ */
+/** One furnace component whose source drifted from its deployed copy. */
+export interface StaleFurnaceComponent {
+    /** Component name (furnace.json key). */
+    name: string;
+    /** Component flavor — resolves the source directory root. */
+    type: 'custom' | 'override';
+    /** Engine-relative deployed prefix (`/`-terminated) the component owns. */
+    prefix: string;
+}
+/**
+ * Returns the furnace components whose deployed engine copies the given
+ * files fall under AND whose `components/` sources have changed since the
+ * last apply. Empty when furnace is not configured, never applied, or the
+ * probe fails.
+ *
+ * Files are attributed per component: the custom `targetPath` / override
+ * `basePath` prefixes, plus — for a localized non-sharedFtl custom
+ * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed; sibling files there belong to other
+ * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
+ * prunes a dangling per-widget jar.mn line), so they have no deployed copy
+ * to go stale and get no candidate by design. The storybook stories prefix
+ * is likewise skipped.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ */
+export declare function findStaleFurnaceComponentsForFiles(projectRoot: string, files: readonly string[]): Promise<StaleFurnaceComponent[]>;
+/**
+ * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
+ * any exported file belongs to a furnace component whose source changed
+ * since the last apply — the export would capture the stale deployed copy.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ * @param allow - True when the operator passed `--allow-stale-furnace`
+ * @param command - Which command runs the gate (message wording only)
+ */
+export declare function enforceFreshFurnaceSources(projectRoot: string, files: readonly string[], allow: boolean, command: 'export' | 're-export'): Promise<void>;

package/dist/src/core/furnace-stale-export.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
+ *
+ * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * the `components/` sources. Editing a component source and re-exporting
+ * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy — per-patch lint then flags the old line
+ * count and the patch body lags the source. This gate detects that
+ * sequence by comparing component source directories against the checksums
+ * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
+ * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
+ * unless the operator passes `--allow-stale-furnace`.
+ *
+ * Checksum-based on purpose: git checkouts and `furnace refresh` churn
+ * mtimes without content changes, so an mtime comparison would misfire.
+ *
+ * Probe failures (broken furnace config, missing state) degrade to a
+ * verbose log and an empty result — a broken furnace setup must never
+ * block non-furnace patch work.
+ */
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+/**
+ * Returns the furnace components whose deployed engine copies the given
+ * files fall under AND whose `components/` sources have changed since the
+ * last apply. Empty when furnace is not configured, never applied, or the
+ * probe fails.
+ *
+ * Files are attributed per component: the custom `targetPath` / override
+ * `basePath` prefixes, plus — for a localized non-sharedFtl custom
+ * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed; sibling files there belong to other
+ * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
+ * prunes a dangling per-widget jar.mn line), so they have no deployed copy
+ * to go stale and get no candidate by design. The storybook stories prefix
+ * is likewise skipped.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ */
+export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
+    try {
+        if (files.length === 0)
+            return [];
+        if (!(await furnaceConfigExists(projectRoot)))
+            return [];
+        const config = await loadFurnaceConfig(projectRoot);
+        const state = await loadFurnaceState(projectRoot);
+        if (!state.appliedChecksums)
+            return [];
+        const furnacePaths = getFurnacePaths(projectRoot);
+        const ftlDir = resolveFtlDir(config.ftlBasePath);
+        const ftlPrefix = ftlDir.endsWith('/') ? ftlDir : `${ftlDir}/`;
+        const candidates = [
+            ...Object.entries(config.overrides).map(([name, cfg]) => ({
+                name,
+                type: 'override',
+                prefix: cfg.basePath.endsWith('/') ? cfg.basePath : `${cfg.basePath}/`,
+                exactFiles: [],
+            })),
+            ...Object.entries(config.custom).map(([name, cfg]) => ({
+                name,
+                type: 'custom',
+                prefix: cfg.targetPath.endsWith('/') ? cfg.targetPath : `${cfg.targetPath}/`,
+                // A localized non-sharedFtl component also owns exactly one
+                // deployed file in the shared FTL dir (applyCustomFtlFile copies
+                // `<name>.ftl` there). sharedFtl bundles are not furnace-deployed.
+                exactFiles: cfg.localized && cfg.sharedFtl === undefined ? [`${ftlPrefix}${name}.ftl`] : [],
+            })),
+        ];
+        const stale = [];
+        for (const candidate of candidates) {
+            if (!files.some((file) => file.startsWith(candidate.prefix) || candidate.exactFiles.includes(file)))
+                continue;
+            const sourceRoot = candidate.type === 'override' ? furnacePaths.overridesDir : furnacePaths.customDir;
+            const sourceDir = `${sourceRoot}/${candidate.name}`;
+            if (!(await pathExists(sourceDir)))
+                continue;
+            const previous = extractComponentChecksums(state.appliedChecksums, candidate.type, candidate.name);
+            if (await hasComponentChanged(sourceDir, previous)) {
+                stale.push({ name: candidate.name, type: candidate.type, prefix: candidate.prefix });
+            }
+        }
+        return stale;
+    }
+    catch (error) {
+        verbose(`Stale-furnace export gate skipped due to an error: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+/**
+ * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
+ * any exported file belongs to a furnace component whose source changed
+ * since the last apply — the export would capture the stale deployed copy.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ * @param allow - True when the operator passed `--allow-stale-furnace`
+ * @param command - Which command runs the gate (message wording only)
+ */
+export async function enforceFreshFurnaceSources(projectRoot, files, allow, command) {
+    const stale = await findStaleFurnaceComponentsForFiles(projectRoot, files);
+    if (stale.length === 0)
+        return;
+    const list = stale
+        .map((component) => `${component.name} (components/${component.type === 'custom' ? 'custom' : 'overrides'}/${component.name}/ → ${component.prefix})`)
+        .join(', ');
+    const message = `Component source${stale.length === 1 ? '' : 's'} changed since the last furnace apply: ${list}. ` +
+        `The deployed engine cop${stale.length === 1 ? 'y is' : 'ies are'} stale, so this ${command} would ` +
+        'capture the OLD component content into the patch. Run "fireforge furnace deploy" (or ' +
+        '"fireforge furnace apply") first so the export captures the current source, or pass ' +
+        '--allow-stale-furnace to export the deployed copy anyway.';
+    if (allow) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}

package/dist/src/core/furnace-validate-compatibility.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
-async function validateMjsCompatibility(mjsPath, tagName) {
+async function validateMjsCompatibility(mjsPath, tagName, isLibrary) {
     if (!(await pathExists(mjsPath)))
         return [];
     const mjsContent = await readText(mjsPath);
@@ -11,6 +11,12 @@ async function validateMjsCompatibility(mjsPath, tagName) {
     if (hasRelativeModuleImport(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'relative-import', 'Imports must use chrome:// URIs, not relative paths.'));
     }
+    // A library component (kind: "library") deliberately defines no element:
+    // it exports a base class + helpers for other components to extend, so
+    // the define/extends requirements do not apply.
+    if (isLibrary) {
+        return issues;
+    }
     if (!hasCustomElementDefineCall(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'no-custom-element-define', 'Missing customElements.define() call. Component will not be registered.'));
     }
@@ -124,7 +130,8 @@ export async function validateCompatibility(componentDir, tagName, type, config,
     const issues = [];
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     const cssPath = join(componentDir, `${tagName}.css`);
-    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName);
+    const isLibrary = type === 'custom' && config?.custom[tagName]?.kind === 'library';
+    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName, isLibrary);
     issues.push(...mjsIssues);
     const cssIssues = await validateCssCompatibility(cssPath, tagName, type, config, root);
     issues.push(...cssIssues);

package/dist/src/core/furnace-validate-helpers.js

@@ -27,10 +27,33 @@ export function hasPositiveTabindex(content) {
         return value !== undefined && parseInt(value, 10) > 0;
     });
 }
+/**
+ * Collects `[start, end)` spans of `<label>…</label>` elements whose content
+ * includes actual label text. Labels cannot nest per HTML, so the non-greedy
+ * inner match is sound. A span qualifies only when the inner content minus
+ * tags still contains non-whitespace — an empty or tag-only wrapper provides
+ * no accessible name. A `${…}` Lit binding counts as label text: dynamic
+ * (usually localized) text is a legitimate accessible name.
+ */
+function collectLabelledSpans(content) {
+    const spans = [];
+    const labelPattern = /<label\b[^>]*>([\s\S]*?)<\/label>/gi;
+    let labelMatch;
+    while ((labelMatch = labelPattern.exec(content)) !== null) {
+        const inner = labelMatch[1] ?? '';
+        if (/\S/.test(inner.replace(/<[^>]*>/g, ' '))) {
+            spans.push({ start: labelMatch.index, end: labelMatch.index + labelMatch[0].length });
+        }
+    }
+    return spans;
+}
 /** Detects form inputs without associated labels. */
 export function hasUnlabelledFormInput(content) {
     // Look for <input> or <select> or <textarea> without aria-label, aria-labelledby, or id
-    // (id implies an external <label for="..."> could exist)
+    // (id implies an external <label for="..."> could exist). A control wrapped
+    // in a <label> that carries actual text is implicitly associated and is
+    // exempt as well.
+    const labelledSpans = collectLabelledSpans(content);
     const inputPattern = /<(input|select|textarea)\b([^>]*)>/gi;
     let inputMatch;
     while ((inputMatch = inputPattern.exec(content)) !== null) {
@@ -41,6 +64,10 @@ export function hasUnlabelledFormInput(content) {
             /type\s*=\s*["']hidden["']/i.test(attrs)) {
             continue;
         }
+        const index = inputMatch.index;
+        if (labelledSpans.some((span) => index >= span.start && index < span.end)) {
+            continue;
+        }
         return true;
     }
     return false;

package/dist/src/core/furnace-validate-structure.js

@@ -37,8 +37,9 @@ export async function validateStructure(componentDir, tagName, type, customConfi
             message: `Required file ${tagName}.mjs not found.`,
         });
     }
-    // .css should exist
-    if (!(await pathExists(cssPath))) {
+    // .css should exist — except for library components (base class + helpers,
+    // no element of their own), which render nothing and need no stylesheet.
+    if (!(await pathExists(cssPath)) && customConfig?.kind !== 'library') {
         issues.push({
             component: tagName,
             severity: 'warning',

package/dist/src/core/license-headers.d.ts

@@ -34,6 +34,11 @@ export declare function getLicenseHeader(license: ProjectLicense, style: Comment
  * on lines 1–2 with the MPL header on lines 3+, which the raw
  * `startsWith` check would otherwise miss.
  *
+ * The MPL-2.0 header is additionally matched on normalized whitespace
+ * (see {@link normalizeCommentHead}) so upstream files using the older
+ * Mozilla wrap — breaking after "file," instead of "with this" — are
+ * accepted too; only the wrap position differs, never the wording.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
@@ -51,6 +56,13 @@ export declare function hasAnyLicenseHeader(content: string, style: CommentStyle
  * patch-lint, making it dead code for every other project license and
  * forcing repo-side audit workarounds.
  *
+ * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
+ * leading block comment is compared on normalized whitespace (see
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking
+ * after "file," instead of "with this", as `ext-browser.js` ships —
+ * passes too. Only the line-break position may differ; altered wording
+ * still rejects.
+ *
  * @param content - File content to check
  */
 export declare function hasUpstreamMplBlockHeader(content: string): boolean;

package/dist/src/core/license-headers.js

@@ -86,6 +86,59 @@ function stripLeadingEditorDirectives(content) {
     } while (result !== prev);
     return result;
 }
+/**
+ * Collapses all whitespace runs to single spaces and trims, so header
+ * comparisons ignore the exact line-break/wrap positions.
+ */
+function normalizeText(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/**
+ * The canonical upstream MPL-2.0 notice as a single normalized sentence
+ * (including the `http://mozilla.org/MPL/2.0/.` URL). Wrap-agnostic
+ * header checks match against this instead of an exact rendering.
+ */
+const MPL_HEADER_NORMALIZED = normalizeText(HEADER_LINES['MPL-2.0'].join(' '));
+/**
+ * Extracts ONLY the leading comment span of `content` for the given
+ * comment style and returns it whitespace-normalized:
+ *
+ * - `js`:   a leading run of `//` lines (markers stripped), or — when the
+ *           file opens with a block comment instead — the first
+ *           `/* … *\/` block;
+ * - `css`:  the first `/* … *\/` block, with the ` * ` continuation-line
+ *           prefixes stripped (same collapsing
+ *           {@link normalizeLicenseHeadForScan} does);
+ * - `hash`: a leading run of `#` lines (markers stripped).
+ *
+ * A non-comment first line yields `''`. This lets callers accept a known
+ * header text regardless of where upstream wrapped its lines (e.g. the
+ * older Mozilla wrap that breaks after "file,"), without ever matching
+ * text beyond the leading comment.
+ */
+function normalizeCommentHead(content, style) {
+    const src = content.replace(/\r\n?/g, '\n');
+    const collectLineRun = (marker) => {
+        const parts = [];
+        for (const line of src.split('\n')) {
+            const m = marker.exec(line);
+            if (!m)
+                break;
+            parts.push(m[1] ?? '');
+        }
+        return normalizeText(parts.join(' '));
+    };
+    if (style === 'hash') {
+        return collectLineRun(/^[ \t]*#[ \t]?(.*)$/);
+    }
+    if (style === 'js' && /^[ \t]*\/\//.test(src)) {
+        return collectLineRun(/^[ \t]*\/\/[ \t]?(.*)$/);
+    }
+    const block = /^[ \t]*\/\*([\s\S]*?)\*\//.exec(src);
+    if (!block)
+        return '';
+    return normalizeText((block[1] ?? '').replace(/\n[ \t]*\*[ \t]*/g, ' '));
+}
 /**
  * Returns true if `content` starts with any known license header for the
  * given comment style.
@@ -103,6 +156,11 @@ function stripLeadingEditorDirectives(content) {
  * on lines 1–2 with the MPL header on lines 3+, which the raw
  * `startsWith` check would otherwise miss.
  *
+ * The MPL-2.0 header is additionally matched on normalized whitespace
+ * (see {@link normalizeCommentHead}) so upstream files using the older
+ * Mozilla wrap — breaking after "file," instead of "with this" — are
+ * accepted too; only the wrap position differs, never the wording.
+ *
  * @param content - File content to check
  * @param style   - Comment syntax of the file
  */
@@ -116,6 +174,9 @@ export function hasAnyLicenseHeader(content, style) {
         if (style === 'js' && candidate.startsWith(getLicenseHeader('MPL-2.0', 'css'))) {
             return true;
         }
+        if (normalizeCommentHead(candidate, style).startsWith(MPL_HEADER_NORMALIZED)) {
+            return true;
+        }
     }
     return false;
 }
@@ -132,11 +193,25 @@ export function hasAnyLicenseHeader(content, style) {
  * patch-lint, making it dead code for every other project license and
  * forcing repo-side audit workarounds.
  *
+ * Matching is wrap-agnostic: after the exact `startsWith` fast path, the
+ * leading block comment is compared on normalized whitespace (see
+ * {@link normalizeCommentHead}) so the older upstream wrap — breaking
+ * after "file," instead of "with this", as `ext-browser.js` ships —
+ * passes too. Only the line-break position may differ; altered wording
+ * still rejects.
+ *
  * @param content - File content to check
  */
 export function hasUpstreamMplBlockHeader(content) {
     const blockHeader = getLicenseHeader('MPL-2.0', 'css');
-    return (content.startsWith(blockHeader) || stripLeadingEditorDirectives(content).startsWith(blockHeader));
+    const candidates = [content, stripLeadingEditorDirectives(content)];
+    for (const candidate of candidates) {
+        if (candidate.startsWith(blockHeader))
+            return true;
+        if (normalizeCommentHead(candidate, 'css').startsWith(MPL_HEADER_NORMALIZED))
+            return true;
+    }
+    return false;
 }
 /**
  * Returns true if `content` starts with any known license header in any

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Terminal-echo filter for the KNOWN upstream mozsystemmonitor teardown
+ * traceback (0.37.0 item 8).
+ *
+ * Every headless test run against the 153-beta engine ends with an
+ * `AttributeError: 'SystemResourceMonitor' object has no attribute
+ * 'stop_time'` traceback at harness teardown — upstream noise that sits
+ * exactly where a reader looks for the failure summary. 0.36.0 already made
+ * real failure lines beat this traceback in CLASSIFICATION; this filter
+ * closes the PRESENTATION gap by collapsing the echoed traceback to one
+ * labeled line.
+ *
+ * Scope is deliberately narrow:
+ *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
+ *     stay raw — the classifier (`test-harness-crash.ts`) depends on the
+ *     raw traceback for its green-summary override and secondary-noise
+ *     detection.
+ *   - Only the exact documented incident is collapsed, and every condition
+ *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
+ *     of the two known attributes (`stop_time`, `poll_interval` — the
+ *     0.34.0 guard family), AND a `mozsystemmonitor/resourcemonitor.py`
+ *     stack frame, AND a previously-seen SUITE_END shutdown marker (shared
+ *     across the run's stdout/stderr filter instances — the marker usually
+ *     lands on stdout while the traceback lands on stderr). A novel
+ *     attribute, a novel exception type in resourcemonitor.py, or a
+ *     pre-shutdown occurrence is echoed verbatim, always.
+ *   - The hold buffer is bounded; on overflow the block is flushed verbatim
+ *     and the filter returns to pass-through, so output is never lost.
+ */
+/**
+ * Shared across the stdout and stderr filter instances of ONE mach run:
+ * SUITE_END typically arrives on stdout while the teardown traceback lands
+ * on stderr, so the shutdown-seen flag must be visible to both. The two
+ * pipes are independent, so a traceback can theoretically beat the marker
+ * through — the block then prints verbatim, the correct failure direction.
+ */
+export interface TeardownNoiseContext {
+    shutdownSeen: boolean;
+}
+/** Fresh per-run context — hand the same instance to both stream filters. */
+export declare function createTeardownNoiseContext(): TeardownNoiseContext;
+/** One line replaces the whole recognized traceback block in the echo. */
+export declare const KNOWN_TEARDOWN_NOISE_ANNOTATION: string;
+/** Chunk-safe, line-buffered echo filter. See module doc. */
+export interface KnownTeardownNoiseFilter {
+    /** Feed a raw chunk; returns the text to echo now (possibly empty). */
+    transform(chunk: string): string;
+    /** Flush any buffered residue verbatim (call after the stream closes). */
+    flush(): string;
+}
+/**
+ * Creates a stateful filter for one output stream. Complete lines outside a
+ * traceback pass straight through (only the trailing partial line is held
+ * back); a `Traceback (most recent call last)` header switches to hold mode
+ * until the block ends, then either the one-line annotation (recognized
+ * signature after a seen shutdown marker) or the verbatim block (anything
+ * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
+ * both stream filters see the same shutdown flag.
+ */
+export declare function createKnownTeardownNoiseFilter(context?: TeardownNoiseContext): KnownTeardownNoiseFilter;

package/dist/src/core/mach-known-noise-filter.js

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Terminal-echo filter for the KNOWN upstream mozsystemmonitor teardown
+ * traceback (0.37.0 item 8).
+ *
+ * Every headless test run against the 153-beta engine ends with an
+ * `AttributeError: 'SystemResourceMonitor' object has no attribute
+ * 'stop_time'` traceback at harness teardown — upstream noise that sits
+ * exactly where a reader looks for the failure summary. 0.36.0 already made
+ * real failure lines beat this traceback in CLASSIFICATION; this filter
+ * closes the PRESENTATION gap by collapsing the echoed traceback to one
+ * labeled line.
+ *
+ * Scope is deliberately narrow:
+ *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
+ *     stay raw — the classifier (`test-harness-crash.ts`) depends on the
+ *     raw traceback for its green-summary override and secondary-noise
+ *     detection.
+ *   - Only the exact documented incident is collapsed, and every condition
+ *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
+ *     of the two known attributes (`stop_time`, `poll_interval` — the
+ *     0.34.0 guard family), AND a `mozsystemmonitor/resourcemonitor.py`
+ *     stack frame, AND a previously-seen SUITE_END shutdown marker (shared
+ *     across the run's stdout/stderr filter instances — the marker usually
+ *     lands on stdout while the traceback lands on stderr). A novel
+ *     attribute, a novel exception type in resourcemonitor.py, or a
+ *     pre-shutdown occurrence is echoed verbatim, always.
+ *   - The hold buffer is bounded; on overflow the block is flushed verbatim
+ *     and the filter returns to pass-through, so output is never lost.
+ */
+const TRACEBACK_HEADER_PATTERN = /^Traceback \(most recent call last\)/;
+const CHAINED_EXCEPTION_CONNECTOR_PATTERN = /^(?:During handling of the above exception, another exception occurred:|The above exception was the direct cause of the following exception:)\s*$/;
+/**
+ * Closed allowlist of the documented teardown family's attributes:
+ * `stop_time` (the 0.37.0 item-8 incident) and `poll_interval` (the same
+ * mozsystemmonitor init failure the 0.34.0 resource-guard family covers —
+ * `test-harness-crash.ts` already classifies it as recognized noise). Any
+ * other missing attribute is a NEW upstream defect and must print verbatim.
+ */
+const KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN = /AttributeError: 'SystemResourceMonitor' object has no attribute '(?:stop_time|poll_interval)'/;
+const RESOURCEMONITOR_FRAME_PATTERN = /mozsystemmonitor[/\\]resourcemonitor\.py/;
+/**
+ * Shutdown marker: the harness's SUITE_END line. Matches the shape
+ * `test-harness-crash.ts` keys its summary parsing on (module-private
+ * there; duplicated here with this cross-reference rather than exported).
+ */
+const SHUTDOWN_MARKER_PATTERN = /\bSUITE_END\b/;
+/** Whole-block recognition — every signal must hold (see module doc). */
+function isRecognizedTeardownNoise(block) {
+    return (KNOWN_TEARDOWN_ATTRIBUTE_ERROR_PATTERN.test(block) && RESOURCEMONITOR_FRAME_PATTERN.test(block));
+}
+/** Fresh per-run context — hand the same instance to both stream filters. */
+export function createTeardownNoiseContext() {
+    return { shutdownSeen: false };
+}
+/** One line replaces the whole recognized traceback block in the echo. */
+export const KNOWN_TEARDOWN_NOISE_ANNOTATION = '[FireForge] Known upstream mozsystemmonitor teardown noise (SystemResourceMonitor ' +
+    'AttributeError at harness shutdown) — not a test failure. See FireForge docs.\n';
+/** Bounds on the held traceback block before flushing verbatim. */
+const HOLD_LINE_LIMIT = 100;
+const HOLD_BYTE_LIMIT = 16 * 1024;
+/**
+ * Creates a stateful filter for one output stream. Complete lines outside a
+ * traceback pass straight through (only the trailing partial line is held
+ * back); a `Traceback (most recent call last)` header switches to hold mode
+ * until the block ends, then either the one-line annotation (recognized
+ * signature after a seen shutdown marker) or the verbatim block (anything
+ * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
+ * both stream filters see the same shutdown flag.
+ */
+export function createKnownTeardownNoiseFilter(context = createTeardownNoiseContext()) {
+    /** Partial (no trailing newline yet) input line. */
+    let partial = '';
+    /** Held traceback lines (each WITH its newline) while in hold mode. */
+    let held = [];
+    let heldBytes = 0;
+    /**
+     * State machine:
+     *   'pass'    — outside any traceback; lines echo through.
+     *   'inside'  — between a Traceback header and its closing exception line.
+     *   'closed'  — saw the closing `SomeError: …` line; still holding in
+     *               case a chained-exception connector continues the block
+     *               (the real fixture chains two tracebacks — the whole
+     *               chain must be evaluated as ONE block or the second half
+     *               would print raw after the annotation).
+     */
+    let state = 'pass';
+    const resetHold = () => {
+        const block = held.join('');
+        held = [];
+        heldBytes = 0;
+        state = 'pass';
+        return block;
+    };
+    const releaseHeld = () => {
+        const block = resetHold();
+        if (block.length === 0)
+            return '';
+        return context.shutdownSeen && isRecognizedTeardownNoise(block)
+            ? KNOWN_TEARDOWN_NOISE_ANNOTATION
+            : block;
+    };
+    const hold = (line) => {
+        held.push(line);
+        heldBytes += line.length;
+        if (held.length > HOLD_LINE_LIMIT || heldBytes > HOLD_BYTE_LIMIT) {
+            // Pathological block: flush verbatim rather than risk withholding
+            // output; do not attempt recognition on oversized blocks.
+            return { out: resetHold(), overflowed: true };
+        }
+        return { out: '', overflowed: false };
+    };
+    const processLine = (line) => {
+        const content = line.replace(/\r?\n$/, '');
+        if (state === 'pass') {
+            if (TRACEBACK_HEADER_PATTERN.test(content)) {
+                state = 'inside';
+                return hold(line).out;
+            }
+            if (SHUTDOWN_MARKER_PATTERN.test(content))
+                context.shutdownSeen = true;
+            return line;
+        }
+        if (state === 'inside') {
+            const isContinuation = content.trim().length === 0 ||
+                /^[ \t]/.test(content) ||
+                TRACEBACK_HEADER_PATTERN.test(content);
+            const { out, overflowed } = hold(line);
+            // The first unindented line is the closing `SomeError: …` line; keep
+            // holding in case a chained connector extends the block.
+            if (!overflowed && !isContinuation) {
+                state = 'closed';
+            }
+            return out;
+        }
+        // state === 'closed': only a blank line, a chained-exception connector,
+        // or another Traceback header continues the block.
+        if (content.trim().length === 0 || CHAINED_EXCEPTION_CONNECTOR_PATTERN.test(content)) {
+            return hold(line).out;
+        }
+        if (TRACEBACK_HEADER_PATTERN.test(content)) {
+            const { out, overflowed } = hold(line);
+            if (!overflowed)
+                state = 'inside';
+            return out;
+        }
+        return releaseHeld() + processLineInPass(line);
+    };
+    // Re-dispatch a line through pass-mode handling after a block release —
+    // the line that ended the block may itself start a new traceback.
+    const processLineInPass = (line) => {
+        const content = line.replace(/\r?\n$/, '');
+        if (TRACEBACK_HEADER_PATTERN.test(content)) {
+            state = 'inside';
+            return hold(line).out;
+        }
+        if (SHUTDOWN_MARKER_PATTERN.test(content))
+            context.shutdownSeen = true;
+        return line;
+    };
+    return {
+        transform(chunk) {
+            let out = '';
+            let buffer = partial + chunk;
+            partial = '';
+            let newlineIndex = buffer.indexOf('\n');
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex + 1);
+                buffer = buffer.slice(newlineIndex + 1);
+                out += processLine(line);
+                newlineIndex = buffer.indexOf('\n');
+            }
+            partial = buffer;
+            return out;
+        },
+        flush() {
+            let out = '';
+            if (state !== 'pass') {
+                // A stream that closes mid-block: fold the trailing partial line in
+                // and evaluate — the final exception line is often the last thing
+                // printed, without a trailing newline.
+                if (partial.length > 0) {
+                    held.push(partial);
+                    partial = '';
+                }
+                out += releaseHeld();
+            }
+            out += partial;
+            partial = '';
+            return out;
+        },
+    };
+}