@hominis/fireforge 0.45.0 → 0.46.0

package/dist/src/core/run-log.d.ts

@@ -22,7 +22,11 @@
 export interface RunLog {
     /** Absolute path to the log file. */
     path: string;
-    /** Appends raw output. Silently drops on any stream error. */
+    /**
+     * Appends output. Complete lines pass through {@link redactRunLogText}
+     * before hitting disk; a trailing partial line is held until its newline
+     * arrives (or until `close`). Silently drops on any stream error.
+     */
     write: (chunk: string) => void;
     /** Flushes and closes. Resolves even when the stream already failed. */
     close: () => Promise<void>;
@@ -45,7 +49,14 @@ export declare function setActiveRunLog(log: RunLog | undefined): void;
 export declare function getActiveRunLogPath(): string | undefined;
 /** Appends to the active run log. A no-op when none is open. */
 export declare function writeToActiveRunLog(chunk: string): void;
-/** Closes and clears the active run log. Resolves even when none is open. */
+/**
+ * Closes and clears the active run log. Resolves even when none is open.
+ *
+ * Also called from the entry point's SIGINT/SIGTERM path: the held partial
+ * line and anything queued in the stream would otherwise be lost across
+ * `process.exit`, and a killed run's last line is usually the one that
+ * says what it was doing.
+ */
 export declare function closeActiveRunLog(): Promise<void>;
 /**
  * A writable that forwards to `base` AND to the active run log.

package/dist/src/core/run-log.js

@@ -23,8 +23,11 @@ import { createWriteStream } from 'node:fs';
 import { mkdir, readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Writable } from 'node:stream';
+import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
+import { redactRunLogText } from './run-log-redact.js';
+import { fileSafeTimestamp } from './state-file.js';
 /** Directory under `.fireforge/` holding run logs. */
 const LOGS_DIRNAME = 'logs';
 /**
@@ -33,20 +36,34 @@ const LOGS_DIRNAME = 'logs';
  * most often needs to read together.
  */
 const RETAINED_LOGS_PER_COMMAND = 20;
+/**
+ * Cap on the partial line held back between writes. A child emitting one
+ * enormous unterminated line (a minified dump on stderr) would otherwise
+ * grow the buffer without bound — and, because each write rebuilds
+ * `pending + chunk`, quadratically — with nothing reaching disk until
+ * close. Past the cap the tail is redacted and written as-is; a `KEY=value`
+ * split exactly at the cap boundary is the accepted cost. Same figure as
+ * `line-dispatch.ts` uses for the stream matchers.
+ */
+const MAX_PENDING_LINE_SIZE = 1024 * 1024;
+/**
+ * Index just past the last line terminator in `text`, or -1 when there is
+ * none. `\n` and lone `\r` both terminate — progress-bar output (mach,
+ * cargo) repaints a line with carriage returns and may never send a
+ * newline, which would otherwise pin the whole run in `pending`. A single
+ * trailing `\r` is NOT a terminator yet: it may be the first half of a
+ * `\r\n` split across chunks.
+ */
+function lastLineEnd(text) {
+    const lastNewline = text.lastIndexOf('\n');
+    const lastReturn = text.lastIndexOf('\r');
+    const cut = lastReturn > lastNewline && lastReturn < text.length - 1 ? lastReturn : lastNewline;
+    return cut === -1 ? -1 : cut + 1;
+}
 /** `.fireforge/logs` under `projectRoot`. */
 export function getRunLogDir(projectRoot) {
     return join(projectRoot, FIREFORGE_DIR, LOGS_DIRNAME);
 }
-/**
- * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
- *
- * Colons are not portable in filenames (Windows rejects them outright), so
- * the ISO form is punctuated with dashes only. Lexical order still equals
- * chronological order, which is what the pruning below relies on.
- */
-function logTimestamp(now) {
-    return now.toISOString().replace(/[:.]/g, '-');
-}
 /**
  * Makes room for one new log by deleting the oldest, so that at most
  * {@link RETAINED_LOGS_PER_COMMAND} logs for `command` exist once the new
@@ -76,7 +93,7 @@ async function pruneRunLogs(dir, command) {
         }));
     }
     catch (error) {
-        verbose(`Run-log pruning skipped: ${String(error)}`);
+        verbose(`Run-log pruning skipped: ${toError(error).message}`);
     }
 }
 /**
@@ -91,14 +108,14 @@ async function pruneRunLogs(dir, command) {
 export async function openRunLog(projectRoot, command, now = new Date()) {
     const dir = getRunLogDir(projectRoot);
     let stream;
-    const path = join(dir, `${command}-${logTimestamp(now)}.log`);
+    const path = join(dir, `${command}-${fileSafeTimestamp(now)}.log`);
     try {
         await mkdir(dir, { recursive: true });
         await pruneRunLogs(dir, command);
         stream = createWriteStream(path, { flags: 'a' });
     }
     catch (error) {
-        verbose(`Run log unavailable (${path}): ${String(error)}`);
+        verbose(`Run log unavailable (${path}): ${toError(error).message}`);
         return undefined;
     }
     // A stream error after open (disk full, a removed directory) must not
@@ -109,19 +126,44 @@ export async function openRunLog(projectRoot, command, now = new Date()) {
         broken = true;
         verbose(`Run log write failed (${path}): ${error.message}`);
     });
+    // Redaction is per LINE, and chunks arrive at arbitrary byte boundaries,
+    // so a `KEY=value` split across two chunks would slip past a per-chunk
+    // pass. Hold the trailing partial line until its terminator arrives (or
+    // it outgrows MAX_PENDING_LINE_SIZE, or the log is closed).
+    let pending = '';
+    const emit = (text) => {
+        if (broken || text.length === 0)
+            return;
+        try {
+            stream.write(redactRunLogText(text));
+        }
+        catch {
+            broken = true;
+        }
+    };
     return {
         path,
         write: (chunk) => {
             if (broken)
                 return;
-            try {
-                stream.write(chunk);
+            const buffered = pending + chunk;
+            const lineEnd = lastLineEnd(buffered);
+            if (lineEnd === -1) {
+                pending = buffered;
             }
-            catch {
-                broken = true;
+            else {
+                pending = buffered.slice(lineEnd);
+                emit(buffered.slice(0, lineEnd));
+            }
+            if (pending.length > MAX_PENDING_LINE_SIZE) {
+                emit(pending);
+                pending = '';
             }
         },
         close: async () => {
+            const tail = pending;
+            pending = '';
+            emit(tail);
             await new Promise((resolve) => {
                 stream.end(() => {
                     resolve();
@@ -155,7 +197,14 @@ export function getActiveRunLogPath() {
 export function writeToActiveRunLog(chunk) {
     activeRunLog?.write(chunk);
 }
-/** Closes and clears the active run log. Resolves even when none is open. */
+/**
+ * Closes and clears the active run log. Resolves even when none is open.
+ *
+ * Also called from the entry point's SIGINT/SIGTERM path: the held partial
+ * line and anything queued in the stream would otherwise be lost across
+ * `process.exit`, and a killed run's last line is usually the one that
+ * says what it was doing.
+ */
 export async function closeActiveRunLog() {
     const log = activeRunLog;
     activeRunLog = undefined;

package/dist/src/core/signal-critical.js

@@ -18,6 +18,7 @@
  * itself. The bin entry point is responsible for awaiting
  * `waitForActiveCriticalSections` before terminating.
  */
+import { sleep } from '../utils/sleep.js';
 const activeSections = new Set();
 /**
  * Runs `fn` inside a signal-deferred critical section. The CLI entry point's
@@ -57,8 +58,5 @@ export async function waitForActiveCriticalSections(timeoutMs) {
     if (activeSections.size === 0)
         return;
     const snapshot = [...activeSections].map((s) => s.promise);
-    await Promise.race([
-        Promise.allSettled(snapshot).then(() => undefined),
-        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
-    ]);
+    await Promise.race([Promise.allSettled(snapshot).then(() => undefined), sleep(timeoutMs)]);
 }

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

@@ -10,7 +10,6 @@
  * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
  * the prefix and should not trip the scanner.
  */
-export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 /**
  * Returns `true` when `line` matches any pattern in
  * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step

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

@@ -20,7 +20,7 @@
  * smoke run into noise for operators and every CI run into flake.
  */
 import { toError } from '../utils/errors.js';
-export const SMOKE_ERROR_PATTERNS = [
+const SMOKE_ERROR_PATTERNS = [
     // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
     // Some log paths prefix browser-console `console.error(...)` with the literal label below.
@@ -63,12 +63,7 @@ export function matchesSmokeError(line) {
  * allowlist (always returns -1).
  */
 export function matchAllowlist(line, allow) {
-    for (let i = 0; i < allow.length; i++) {
-        if (allow[i]?.pattern.test(line)) {
-            return i;
-        }
-    }
-    return -1;
+    return allow.findIndex((entry) => entry.pattern.test(line));
 }
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
@@ -88,12 +83,12 @@ export function compileAllowlistFromFile(body, sourcePath) {
             compiled.push({
                 pattern: new RegExp(line),
                 source: line,
-                origin: `${sourcePath}:${String(index + 1)}`,
+                origin: `${sourcePath}:${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
+            throw new Error(`Invalid allowlist regex at ${sourcePath}:${index + 1}: ${message}`, {
                 cause: error,
             });
         }
@@ -111,12 +106,12 @@ export function compileAllowlistFromStrings(sources) {
             compiled.push({
                 pattern: new RegExp(source),
                 source,
-                origin: `--console-allow #${String(index + 1)}`,
+                origin: `--console-allow #${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
+            throw new Error(`Invalid --console-allow regex at position ${index + 1} ("${source}"): ${message}`, { cause: error });
         }
     });
     return compiled;

package/dist/src/core/state-file.d.ts

@@ -1,5 +1,16 @@
 /** Runs an operation while holding the sidecar lock for a FireForge state file. */
 export declare function withStateFileLock<T>(statePath: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export declare function fileSafeTimestamp(now: Date): string;
 /** Renames a state file out of the way while preserving it for later inspection. */
 export declare function quarantineStateFile(statePath: string, reason?: string): Promise<string | undefined>;
 /**
@@ -15,7 +26,7 @@ export declare function quarantineStateFile(statePath: string, reason?: string):
  * inside that tree.
  *
  * `furnace.json` is the pattern the rest should follow: it refuses a newer
- * version by name and tells the operator to upgrade (`migrateFurnaceConfig`
+ * version by name and tells the operator to upgrade (`validateConfigVersion`
  * in `furnace-config.ts`).
  */
 export type DocumentVersionCheck = {

package/dist/src/core/state-file.js

@@ -12,12 +12,25 @@ export async function withStateFileLock(statePath, operation) {
             `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
     });
 }
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export function fileSafeTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
 /** Renames a state file out of the way while preserving it for later inspection. */
 export async function quarantineStateFile(statePath, reason = 'corrupt') {
     if (!(await pathExists(statePath))) {
         return undefined;
     }
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const timestamp = fileSafeTimestamp(new Date());
     const quarantinedPath = `${statePath}.${reason}-${timestamp}`;
     await rename(statePath, quarantinedPath);
     return basename(quarantinedPath);

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

@@ -11,6 +11,7 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { toError } from '../utils/errors.js';
 import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isBrandingManagedPath } from './branding.js';
 import { createPatchedContentContext } from './patch-apply.js';
 import { classifyBinaryOwnedFile } from './status-binary.js';
@@ -56,7 +57,7 @@ export function getPrimaryStatusCode(status) {
  * visible as unmanaged (the Assets.car precedent).
  */
 export function isGeneratedBrandingPath(file, binaryName) {
-    const normalized = file.replace(/\\/g, '/');
+    const normalized = normalizePathSlashes(file);
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
         normalized === `${brandingRoot}/configure.sh` ||

package/dist/src/core/test-changed-prefs.js

@@ -46,6 +46,30 @@ const CHANGED_PREF_BLOCK_PATTERN = /pref(?:erence)?s?\b/i;
  * @returns Operator-facing explanation, or undefined
  */
 export function describeChangedPrefNoise(output) {
+    const namesSeen = matchedTimeDrivenPrefNames(output);
+    if (namesSeen === undefined)
+        return undefined;
+    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
+        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
+        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
+        'change under test or with the build. The first probe is to halve the chunk size ' +
+        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
+        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
+        'check — it belongs to the harness — only tell you which kind of failure you are ' +
+        'looking at.');
+}
+/** Failure blocks inspected before the changed-pref shape is abandoned. */
+const CHANGED_PREF_BLOCK_LIMIT = 20;
+/**
+ * The RECOGNIZER half of the shape, split from the formatting so a caller
+ * that only needs the yes/no answer does not build the ~500-character
+ * explanation to throw it away.
+ *
+ * @param output - Combined harness stdout+stderr
+ * @returns The time-driven pref names seen, or undefined when the shape does
+ *   not apply
+ */
+function matchedTimeDrivenPrefNames(output) {
     const blocks = collectUnexpectedFailureBlocks(output, CHANGED_PREF_BLOCK_LIMIT).filter((block) => !block.startsWith('…'));
     if (blocks.length === 0)
         return undefined;
@@ -59,20 +83,11 @@ export function describeChangedPrefNoise(output) {
         for (const name of matched)
             namesSeen.add(name);
     }
-    return (`Every unexpected result in this run is a changed-preference check on ${[...namesSeen].join(' / ')}. ` +
-        'Those preferences are TIME-DRIVEN: they move once a run is long enough to cross the ' +
-        'cold-startup check interval, so they correlate with run LENGTH rather than with the ' +
-        'change under test or with the build. The first probe is to halve the chunk size ' +
-        '(`--chunk 8` where a 40-row chunk tripped it) and see whether the same work passes; ' +
-        'if it does, this was harness noise, not a regression. FireForge cannot forgive the ' +
-        'check — it belongs to the harness — only tell you which kind of failure you are ' +
-        'looking at.');
+    return namesSeen;
 }
-/** Failure blocks inspected before the changed-pref shape is abandoned. */
-const CHANGED_PREF_BLOCK_LIMIT = 20;
 /** Short verdict-line note for the changed-preference-noise shape. */
 export function changedPrefNoiseVerdictNote(output) {
-    return describeChangedPrefNoise(output) === undefined
+    return matchedTimeDrivenPrefNames(output) === undefined
         ? undefined
         : 'all unexpected results are time-driven changed-pref checks';
 }

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

@@ -589,13 +589,13 @@ function evaluateGreenTeardownOverride(output, counts, realFailures, requestedPa
         return reject('summary printed no "Unexpected results:" line');
     }
     if (counts.unexpected !== 0) {
-        return reject(`summary reported unexpected=${String(counts.unexpected)}`);
+        return reject(`summary reported unexpected=${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] ?? '')}`);
+        return reject(`${realFailures.length} matched failure line(s), first: ${truncateEvidence(realFailures[0] ?? '')}`);
     }
     const crashLine = findCrashMarkerLine(output);
     if (crashLine !== undefined)

package/dist/src/core/test-stale-check.d.ts

@@ -1,6 +1,4 @@
-import { isXpcomManifestPath } from './build-audit.js';
 import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
-export { isXpcomManifestPath };
 /** Result of the stale-build preflight probe. */
 export interface StaleBuildResult {
     /** True when at least one packageable engine file changed since the baseline. */

package/dist/src/core/test-stale-check.js

@@ -24,11 +24,11 @@
  */
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
+import { normalizePathSlashes } from '../utils/paths.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
-export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
 const STALE_PATHS_LIMIT = 10;
 /**
@@ -138,7 +138,7 @@ function toManifestGranule(path) {
 }
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
-    return path.trim().replace(/\\/g, '/').replace(/\/+$/, '');
+    return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
 }
 /**
  * Formats the refusal shown when a non-`--build` run requests paths the

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

@@ -1,14 +1,33 @@
-import { type MachCommandResult } from './mach.js';
+import { type MachCommandResult, type MachTestSuiteKind } from './mach.js';
 export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
-export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>, fullOutput?: boolean) => Promise<MachCommandResult>;
+export interface XpcshellRetryOptions {
+    /** Engine checkout the run happened in. */
+    engineDir: string;
+    /** Object directory the run used, when one is configured. */
+    objDir: string | undefined;
+    /** Result of the run that may need repairing and retrying. */
+    result: MachCommandResult;
+    /** Which of the requested paths are xpcshell tests, and which are not. */
+    classification: XpcshellRetryClassification;
+    /** Test paths, normalized, as handed to mach. */
+    normalizedPaths: string[];
+    /** Extra mach arguments the run was started with. */
+    extraArgs: string[];
+    /** Environment overlay for the retried run. */
+    env?: Record<string, string> | undefined;
+    /** Mach command kind to retry with. Defaults to the generic `test`. */
+    kind?: MachTestSuiteKind | undefined;
+    /** Whether the run was started with full harness output. */
+    fullOutput?: boolean | undefined;
+}
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch, fullOutput?: boolean): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(options: XpcshellRetryOptions): Promise<MachCommandResult>;

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

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { testWithOutput } from './mach.js';
+import { runMachTestSuite } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput, fullOutput) {
+export async function retryAfterXpcshellSymlinkRepair(options) {
+    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, } = options;
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
@@ -15,12 +17,13 @@ export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result,
         if (repaired) {
             // The repaired re-run is the same logical invocation, so it keeps
             // the verbosity the run was started with.
-            if (fullOutput === true) {
-                return dispatch(engineDir, normalizedPaths, extraArgs, env, true);
-            }
-            return env
-                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
-                : dispatch(engineDir, normalizedPaths, extraArgs);
+            return runMachTestSuite(kind, {
+                engineDir,
+                testPaths: normalizedPaths,
+                args: extraArgs,
+                env,
+                fullOutput,
+            });
         }
     }
     return result;

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

@@ -5,6 +5,32 @@
  * agree on what "exists" means.
  */
 export declare function categoryHeaderExists(lines: string[], category: string): boolean;
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+/**
+ * Category name declared by the banner STARTING at `index`, or `undefined`
+ * when that line opens no banner.
+ *
+ * The single reader for both banner shapes, so the inventory walk, the
+ * "available categories" error body and the section finder cannot drift on
+ * what counts as a header.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param index - 0-based line index to test
+ * @returns The declared category name, or undefined
+ */
+export declare function categoryBannerNameAt(lines: string[], index: number): string | undefined;
 /**
  * Asserts the category banner exists (or that creation was requested).
  * Throws a GeneralError naming the available categories and the
@@ -23,6 +49,13 @@ export declare function findCategorySection(lines: string[], category: string, t
     categoryLine: number;
     sectionEnd: number;
 };
+/** 0-based open/close line indices of the base `:root {` block. */
+export declare function findBaseRootBounds(lines: string[]): {
+    open: number;
+    close: number;
+} | undefined;
+/** Masks block-comment content per line so declarations inside comments never match. */
+export declare function maskCommentLines(lines: string[]): string[];
 /** Location of an existing base-`:root` token declaration. */
 export interface TokenDeclarationLocation {
     /** 1-based line number in the tokens CSS file. */