@hominis/fireforge 0.39.0 → 0.41.0

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

@@ -1,8 +1,19 @@
 /**
  * Filesystem-based lock for serializing patch directory mutations.
  */
+export interface PatchDirectoryLockOptions {
+    /**
+     * Wait up to this many seconds for the patch directory lock instead of the
+     * default ~30 s budget. Enables exponential poll backoff (100 ms → 2 s)
+     * and a holder-identified progress line roughly every 5 s. `undefined`
+     * preserves the historical behavior exactly.
+     */
+    waitLockSeconds?: number | undefined;
+    /** Command name recorded in the lock's owner metadata for holder diagnostics. */
+    command?: string | undefined;
+}
 /**
  * Runs a patch directory mutation while holding an exclusive filesystem lock.
  * This serializes filename allocation and manifest writes across parallel exports.
  */
-export declare function withPatchDirectoryLock<T>(patchesDir: string, operation: () => Promise<T>): Promise<T>;
+export declare function withPatchDirectoryLock<T>(patchesDir: string, operation: () => Promise<T>, options?: PatchDirectoryLockOptions): Promise<T>;

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

@@ -6,18 +6,54 @@ import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { PatchError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
+import { info } from '../utils/logger.js';
 import { withFileLock } from './file-lock.js';
 const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
+/**
+ * Formats the periodic operator-facing waiting line printed while
+ * `--wait-lock` polls a contended patch directory lock. Mirrors the engine
+ * session lock's progress line so operators read one shape for both locks.
+ */
+function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    if (holder === undefined) {
+        return `Waiting for the FireForge patch directory lock — ${progress}.`;
+    }
+    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
+    return `Waiting for the FireForge patch directory lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+}
 /**
  * Runs a patch directory mutation while holding an exclusive filesystem lock.
  * This serializes filename allocation and manifest writes across parallel exports.
  */
-export async function withPatchDirectoryLock(patchesDir, operation) {
+export async function withPatchDirectoryLock(patchesDir, operation, options = {}) {
     const lockDir = join(patchesDir, PATCH_DIRECTORY_LOCK);
+    const { waitLockSeconds, command } = options;
     return withFileLock(lockDir, operation, {
-        onTimeoutMessage: `Timed out waiting for another patch export to finish in ${patchesDir}.\n` +
-            `If no other fireforge process is running, the lock may be stale. ` +
-            `Remove it manually:\n  rm -rf "${lockDir}"`,
+        ...(waitLockSeconds !== undefined
+            ? {
+                timeoutMs: waitLockSeconds * 1000,
+                pollMs: 100,
+                pollMaxMs: 2000,
+                waitProgressMs: 5000,
+                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                },
+            }
+            : {}),
+        ...(command !== undefined
+            ? { ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`] }
+            : {}),
+        // Reason first, remedy second (FORGE H5). The remedy is waiting, not
+        // deleting: bulk exports/re-exports legitimately hold this lock for
+        // minutes, FireForge reaps genuinely stale locks on its own, and the
+        // old advice ("rm -rf" while a holder was alive) destroyed a live
+        // lock. The leading sentence is a message contract; extend, don't
+        // reword. withFileLock appends the holder identification.
+        onTimeoutMessage: `Timed out waiting for another FireForge command mutating ${patchesDir}.\n` +
+            `Pass --wait-lock [seconds] to wait longer (bare --wait-lock waits up to 60 seconds). ` +
+            `FireForge removes genuinely stale locks automatically; only if no other fireforge ` +
+            `process is running and the timeout persists, remove the lock manually:\n  rm -rf "${lockDir}"`,
         onStaleLockMessage: (ageMs) => `Removing stale patch lock (age: ${Math.round(ageMs / 1000)}s). ` +
             'A previous fireforge process may have crashed.',
     }).catch((error) => {

package/dist/src/core/patch-manifest-consistency.js

@@ -112,10 +112,22 @@ async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVers
         return Number.isFinite(patch.order) ? Math.max(highest, patch.order) : highest;
     }, 0);
     let nextRecoveredOrder = highestFiniteOrder + 1;
-    for (const patch of patches) {
+    // Prefetch the two independent per-patch reads concurrently. This runs
+    // while the patch-directory lock is held, and it was two serialised awaits
+    // per patch across the whole queue — 58 round-trips on a 29-patch queue.
+    // The fold below stays sequential because `nextRecoveredOrder` is
+    // loop-carried: parallelising the assignment would scramble the recovered
+    // ordinals.
+    const prefetched = await Promise.all(patches.map(async (patch) => ({
+        filesAffected: normalizeFiles(await getAllTargetFilesFromPatch(patch.path)),
+        patchStats: await stat(patch.path),
+    })));
+    for (const [index, patch] of patches.entries()) {
         const existing = existingEntries.get(patch.filename);
-        const filesAffected = normalizeFiles(await getAllTargetFilesFromPatch(patch.path));
-        const patchStats = await stat(patch.path);
+        const prefetch = prefetched[index];
+        if (!prefetch)
+            continue;
+        const { filesAffected, patchStats } = prefetch;
         const inferred = inferPatchMetadataFromFilename(patch.filename);
         const recoveredOrder = Number.isFinite(patch.order) ? patch.order : nextRecoveredOrder++;
         if (!existing) {

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

@@ -5,7 +5,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

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

@@ -60,6 +60,14 @@ export interface DiffSection {
      * refuse them rather than treat base85 lines starting with `+` as content.
      */
     isBinary: boolean;
+    /**
+     * Old-side blob hash from the section's `index <old>..<new>` line
+     * (possibly abbreviated). Undefined when the metadata zone carries no
+     * parseable index line (hand-written diffs, `Binary files … differ`).
+     */
+    indexOldHash?: string;
+    /** New-side blob hash from the `index` line; see {@link indexOldHash}. */
+    indexNewHash?: string;
     /** Parsed hunks, in file order. Empty for binary or metadata-only sections. */
     hunks: ParsedHunk[];
 }

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

@@ -169,6 +169,16 @@ export function parseDiffSections(diffContent) {
                 current.isBinary = true;
                 continue;
             }
+            // `git diff --binary` always records full blob hashes here (git
+            // apply requires them); text sections carry abbreviated ones. The
+            // hashes let binary sections be compared by identity when their
+            // payload cannot be applied as text (FORGE J3).
+            const indexMatch = /^index ([0-9a-f]{7,64})\.\.([0-9a-f]{7,64})(?: \d{6})?$/.exec(line);
+            if (indexMatch?.[1] !== undefined && indexMatch[2] !== undefined) {
+                current.indexOldHash = indexMatch[1];
+                current.indexNewHash = indexMatch[2];
+                continue;
+            }
         }
         if (current.isBinary)
             continue;

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

@@ -23,6 +23,13 @@ export interface PatchPolicyEnforcementInput {
     manifest: PatchesManifest;
     command: string;
     forceUnsafe?: boolean;
+    /**
+     * Per-issue-code remediation lines appended to matching details, so a
+     * refusal can name the exact flag or command that fixes it on the
+     * command it was raised from (e.g. `--description` on
+     * `patch move-files --create`).
+     */
+    hints?: Partial<Record<PatchPolicyIssueCode, string>>;
 }
 /** Returns valid categories for prompts and CLI validation under the config. */
 export declare function getPatchPolicyCategories(config: FireForgeConfig): string[];

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

@@ -341,7 +341,10 @@ export function enforcePatchPolicy(input) {
     if (issues.length === 0)
         return;
     const mode = mutationMode(input.config);
-    const details = issues.map((issue) => `  [${issue.code}] ${issue.message}`);
+    const details = issues.map((issue) => {
+        const hint = input.hints?.[issue.code];
+        return `  [${issue.code}] ${issue.message}${hint ? `\n      → ${hint}` : ''}`;
+    });
     if (mode === 'warn') {
         warn(`${input.command}: patch policy warning(s):`);
         for (const detail of details)

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

@@ -35,3 +35,13 @@ export declare function extractNewFileContent(patchPath: string, targetFile?: st
  * @returns Modified content
  */
 export declare function applyPatchToContent(content: string | null, patchPath: string, targetFile: string): Promise<string>;
+/**
+ * Applies an already-read patch body to content. Batched callers that hold
+ * many (patch, file) pairs use this to read each patch body once instead of
+ * once per pair.
+ * @param content - Original content (null for new files)
+ * @param patchContent - Full text of the patch body
+ * @param targetFile - The file path within the patch
+ * @returns Modified content
+ */
+export declare function applyPatchTextToContent(content: string | null, patchContent: string, targetFile: string): string;

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

@@ -71,11 +71,22 @@ export async function extractNewFileContent(patchPath, targetFile) {
  * @returns Modified content
  */
 export async function applyPatchToContent(content, patchPath, targetFile) {
-    const patchContent = await readText(patchPath);
+    return applyPatchTextToContent(content, await readText(patchPath), targetFile);
+}
+/**
+ * Applies an already-read patch body to content. Batched callers that hold
+ * many (patch, file) pairs use this to read each patch body once instead of
+ * once per pair.
+ * @param content - Original content (null for new files)
+ * @param patchContent - Full text of the patch body
+ * @param targetFile - The file path within the patch
+ * @returns Modified content
+ */
+export function applyPatchTextToContent(content, patchContent, targetFile) {
     // Check if this is a new file patch for the target file specifically
     if (content === null) {
         if (isNewFileInPatch(patchContent, targetFile)) {
-            return await extractNewFileContent(patchPath, targetFile);
+            return extractNewFileContentFromDiff(patchContent, targetFile);
         }
         // If not a new file patch but content is null, return empty
         return '';

package/dist/src/core/rebase-session.d.ts

@@ -35,7 +35,47 @@ export interface RebaseSession {
     currentIndex: number;
 }
 /**
- * Loads an existing rebase session, or returns `null` if none exists.
+ * Outcome of reading the session file, following the {@link LockOwner}
+ * discriminated-union form rather than collapsing three states into `null`.
+ *
+ * Distinguishing `present: false` from `present: true, valid: false` is
+ * load-bearing. Before 0.41.0 both returned `null` while
+ * {@link hasActiveRebaseSession} reported liveness from `pathExists` alone, so
+ * an invalid session file wedged the operator in a closed cycle: `rebase` said
+ * "already in progress — use --continue or --abort", and both of those said
+ * "no rebase session in progress". No CLI path deleted the file and no message
+ * named it, so the only escape was knowing to `rm` it by hand.
+ */
+export type RebaseSessionRead = {
+    present: false;
+} | {
+    present: true;
+    valid: true;
+    session: RebaseSession;
+} | {
+    present: true;
+    valid: false;
+    reason: string;
+};
+/** Absolute path of the session file, for messages that must name it. */
+export declare function getRebaseSessionPath(projectRoot: string): string;
+/**
+ * Reads the session file, reporting absent, valid, and corrupt as three
+ * distinct outcomes. Never throws for a malformed file: `readJson` calls
+ * `JSON.parse` with no guard of its own, so an interrupted write surfaced a
+ * raw `SyntaxError` out of `--continue`/`--abort` before 0.41.0.
+ *
+ * A single read determines liveness and validity: only ENOENT/ENOTDIR from
+ * that read mean `absent`. A pathExists pre-probe both raced deletion (a file
+ * removed between probe and read misreported an absent session as corrupt)
+ * and swallowed EACCES (an unreadable `.fireforge/` misreported a session as
+ * absent) — the same failure `readTreeMarkerState` fixed for tree markers.
+ */
+export declare function readRebaseSession(projectRoot: string): Promise<RebaseSessionRead>;
+/**
+ * Loads an existing rebase session, or returns `null` when none exists or the
+ * file on disk is unusable. Callers that must tell those two apart — every
+ * command that reports to an operator — should use {@link readRebaseSession}.
  */
 export declare function loadRebaseSession(projectRoot: string): Promise<RebaseSession | null>;
 /**
@@ -47,6 +87,8 @@ export declare function saveRebaseSession(projectRoot: string, session: RebaseSe
  */
 export declare function clearRebaseSession(projectRoot: string): Promise<void>;
 /**
- * Returns `true` when an active rebase session exists on disk.
+ * Returns `true` when a rebase session file exists on disk, valid or not.
+ * Test-facing convenience — production code reads `readRebaseSession` once
+ * instead, so liveness and validity come from the same read.
  */
 export declare function hasActiveRebaseSession(projectRoot: string): Promise<boolean>;

package/dist/src/core/rebase-session.js

@@ -6,8 +6,9 @@
  * resume with `fireforge rebase --continue`.
  */
 import { join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { pathExists, readJson, removeFile, writeJson } from '../utils/fs.js';
-import { isArray, isObject, isString } from '../utils/validation.js';
+import { isArray, isNumber, isObject, isString, isValidFirefoxProduct, isValidFirefoxVersion, } from '../utils/validation.js';
 import { getProjectPaths } from './config-paths.js';
 import { createSiblingLockPath, withFileLock } from './file-lock.js';
 // ── Helpers ──
@@ -15,28 +16,122 @@ const SESSION_FILENAME = 'rebase-session.json';
 function sessionPath(projectRoot) {
     return join(getProjectPaths(projectRoot).fireforgeDir, SESSION_FILENAME);
 }
+const REBASE_PATCH_STATUSES = [
+    'pending',
+    'applied-clean',
+    'applied-fuzz',
+    'failed',
+    'resolved',
+    'skipped',
+];
+/** Validates one `patches[]` element to its declared shape. */
+function isValidPatchEntry(value) {
+    if (!isObject(value))
+        return false;
+    if (!isString(value['filename']) || value['filename'].length === 0)
+        return false;
+    if (!REBASE_PATCH_STATUSES.includes(value['status']))
+        return false;
+    if (value['fuzzFactor'] !== undefined && !isNumber(value['fuzzFactor']))
+        return false;
+    if (value['error'] !== undefined && !isString(value['error']))
+        return false;
+    const conflicting = value['conflictingFiles'];
+    if (conflicting !== undefined && (!isArray(conflicting) || !conflicting.every(isString))) {
+        return false;
+    }
+    return true;
+}
+/** Optional product field: absent is legal, present must be a real product. */
+function isValidOptionalProduct(value) {
+    return value === undefined || (isString(value) && isValidFirefoxProduct(value));
+}
+/**
+ * Validates a session file against the shape the rebase commands actually
+ * consume — not merely against broad field types.
+ *
+ * The looser predicate this replaces checked six `typeof`s and nothing else,
+ * which admitted sessions the resume path then acted on. `patches: [null]`
+ * reached `patch-loop.ts`, which reads `.filename` off each entry and hands it
+ * to `stampPatchVersions`. A `currentIndex` of `NaN` (legal for
+ * `typeof === 'number'`) made the resume loop run zero iterations and report
+ * success; a negative one indexed out of range in `continue.ts`. `toVersion:
+ * ""` passed `isString` and was stamped verbatim onto every Furnace override's
+ * `baseVersion`. `fromProduct`/`toProduct` were not checked at all despite
+ * being typed `FirefoxProduct`.
+ *
+ * The session file is written only by `rebase/index.ts` from validated CLI and
+ * config values, so every one of these is a corrupt-file or hand-edit case —
+ * which is exactly the case this predicate exists to catch.
+ */
 function isValidSession(data) {
     if (!isObject(data))
         return false;
-    return (isString(data['startedAt']) &&
-        isString(data['fromVersion']) &&
-        isString(data['toVersion']) &&
-        isString(data['preRebaseCommit']) &&
-        isArray(data['patches']) &&
-        typeof data['currentIndex'] === 'number');
+    if (!isString(data['startedAt']) || Number.isNaN(Date.parse(data['startedAt'])))
+        return false;
+    // 4 is git's own minimum abbreviation length; 40/64 are full SHA-1/SHA-256.
+    if (!isString(data['preRebaseCommit']) || !/^[0-9a-f]{4,64}$/i.test(data['preRebaseCommit'])) {
+        return false;
+    }
+    if (!isString(data['fromVersion']) || !isValidFirefoxVersion(data['fromVersion']))
+        return false;
+    if (!isString(data['toVersion']) || !isValidFirefoxVersion(data['toVersion']))
+        return false;
+    if (!isValidOptionalProduct(data['fromProduct']))
+        return false;
+    if (!isValidOptionalProduct(data['toProduct']))
+        return false;
+    const patches = data['patches'];
+    if (!isArray(patches) || !patches.every(isValidPatchEntry))
+        return false;
+    // `<= patches.length` because the resume point legally sits one past the
+    // last entry once every patch has been processed.
+    const currentIndex = data['currentIndex'];
+    if (!isNumber(currentIndex) || !Number.isInteger(currentIndex))
+        return false;
+    return currentIndex >= 0 && currentIndex <= patches.length;
+}
+/** Absolute path of the session file, for messages that must name it. */
+export function getRebaseSessionPath(projectRoot) {
+    return sessionPath(projectRoot);
 }
-// ── Public API ──
 /**
- * Loads an existing rebase session, or returns `null` if none exists.
+ * Reads the session file, reporting absent, valid, and corrupt as three
+ * distinct outcomes. Never throws for a malformed file: `readJson` calls
+ * `JSON.parse` with no guard of its own, so an interrupted write surfaced a
+ * raw `SyntaxError` out of `--continue`/`--abort` before 0.41.0.
+ *
+ * A single read determines liveness and validity: only ENOENT/ENOTDIR from
+ * that read mean `absent`. A pathExists pre-probe both raced deletion (a file
+ * removed between probe and read misreported an absent session as corrupt)
+ * and swallowed EACCES (an unreadable `.fireforge/` misreported a session as
+ * absent) — the same failure `readTreeMarkerState` fixed for tree markers.
  */
-export async function loadRebaseSession(projectRoot) {
+export async function readRebaseSession(projectRoot) {
     const path = sessionPath(projectRoot);
-    if (!(await pathExists(path)))
-        return null;
-    const data = await readJson(path);
-    if (!isValidSession(data))
-        return null;
-    return data;
+    let data;
+    try {
+        data = await readJson(path);
+    }
+    catch (error) {
+        const code = getNodeErrorCode(error);
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { present: false };
+        return { present: true, valid: false, reason: toError(error).message };
+    }
+    if (!isValidSession(data)) {
+        return { present: true, valid: false, reason: 'the file is not a valid rebase session' };
+    }
+    return { present: true, valid: true, session: data };
+}
+/**
+ * Loads an existing rebase session, or returns `null` when none exists or the
+ * file on disk is unusable. Callers that must tell those two apart — every
+ * command that reports to an operator — should use {@link readRebaseSession}.
+ */
+export async function loadRebaseSession(projectRoot) {
+    const result = await readRebaseSession(projectRoot);
+    return result.present && result.valid ? result.session : null;
 }
 /**
  * Persists a rebase session atomically.
@@ -57,7 +152,9 @@ export async function clearRebaseSession(projectRoot) {
     }
 }
 /**
- * Returns `true` when an active rebase session exists on disk.
+ * Returns `true` when a rebase session file exists on disk, valid or not.
+ * Test-facing convenience — production code reads `readRebaseSession` once
+ * instead, so liveness and validity come from the same read.
  */
 export async function hasActiveRebaseSession(projectRoot) {
     return pathExists(sessionPath(projectRoot));

package/dist/src/core/register-browser-content.js

@@ -5,6 +5,7 @@
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { findAlphabeticalPosition, findAlphabeticalTokenPosition } from './manifest-helpers.js';
 import { tokenizeJarMn } from './manifest-tokenizers.js';
 import { withParserFallback } from './parser-fallback.js';
@@ -18,7 +19,7 @@ function registerBrowserContentTokenized(content, fileName, entry, after) {
     let insertIndex;
     let previousEntry;
     if (after) {
-        const afterPattern = new RegExp(`(?:^|/)${after.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|\\)|$)`);
+        const afterPattern = new RegExp(`(?:^|/)${escapeRegex(after)}(?:\\s|\\)|$)`);
         const afterToken = tokens.find((t) => afterPattern.test(t.raw));
         if (afterToken) {
             insertIndex = afterToken.lineIndex + 1;

package/dist/src/core/register-shared-css.js

@@ -5,6 +5,7 @@
 import { basename, join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
 import { findAlphabeticalPosition, findAlphabeticalTokenPosition } from './manifest-helpers.js';
 import { tokenizeJarMn } from './manifest-tokenizers.js';
 import { withParserFallback } from './parser-fallback.js';
@@ -18,7 +19,7 @@ function registerSharedCSSTokenized(content, name, entry, after) {
     let insertIndex;
     let previousEntry;
     if (after) {
-        const afterPattern = new RegExp(`(?:^|/)${after.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?:\\s|\\)|$)`);
+        const afterPattern = new RegExp(`(?:^|/)${escapeRegex(after)}(?:\\s|\\)|$)`);
         const afterToken = tokens.find((t) => afterPattern.test(t.raw));
         if (afterToken) {
             insertIndex = afterToken.lineIndex + 1;

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

@@ -10,36 +10,44 @@
  * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
  * the prefix and should not trip the scanner.
  */
-/**
- * Line prefixes that signal an actual runtime error in a Firefox chrome
- * process. A hit on any of these patterns is a smoke failure unless the
- * line also matches the caller-supplied allowlist.
- *
- * Additions here should be conservative — false positives turn every
- * smoke run into noise for operators and every CI run into flake.
- */
 export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 /**
  * Returns `true` when `line` matches any pattern in
  * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
- * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export declare function matchesSmokeError(line: string): boolean;
 /**
- * Returns `true` when `line` matches any regex in `allow`. Safe to call
- * with an empty allowlist (always returns `false`).
+ * One compiled allowlist entry with its provenance retained so the smoke
+ * summary can attribute hits per entry (FORGE G8) — an entry that silently
+ * stops matching (its suppressed shape changed upstream) is only
+ * detectable when zero-hit entries are visible.
+ */
+export interface CompiledAllowlistEntry {
+    pattern: RegExp;
+    /** Verbatim source text of the entry. */
+    source: string;
+    /** Human-readable origin: `allow.txt:12` or `--console-allow #2`. */
+    origin: string;
+}
+/**
+ * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
+ * First-match attribution is deterministic and cheap; a line matching
+ * several entries credits the earliest one. Safe to call with an empty
+ * allowlist (always returns -1).
  */
-export declare function matchesAllowlist(line: string, allow: readonly RegExp[]): boolean;
+export declare function matchAllowlist(line: string, allow: readonly CompiledAllowlistEntry[]): number;
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
- * compiled as a RegExp. A bad pattern throws immediately — better to fail
- * fast at CLI parse time than to silently let a typo match nothing.
+ * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
+ * pattern throws immediately — better to fail fast at CLI parse time than
+ * to silently let a typo match nothing.
  */
-export declare function compileAllowlistFromFile(body: string, sourcePath: string): RegExp[];
+export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];
 /**
  * Compiles an array of regex-string inputs (e.g. repeated `--console-allow`
  * flag values). Same fail-fast semantics as {@link compileAllowlistFromFile}.
  */
-export declare function compileAllowlistFromStrings(sources: readonly string[]): RegExp[];
+export declare function compileAllowlistFromStrings(sources: readonly string[]): CompiledAllowlistEntry[];

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

@@ -19,6 +19,7 @@
  * Additions here should be conservative — false positives turn every
  * smoke run into noise for operators and every CI run into flake.
  */
+import { toError } from '../utils/errors.js';
 export const SMOKE_ERROR_PATTERNS = [
     // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
@@ -32,7 +33,7 @@ export const SMOKE_ERROR_PATTERNS = [
 /**
  * Returns `true` when `line` matches any pattern in
  * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
- * lives in {@link matchesAllowlist}, so the smoke runner can count
+ * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export function matchesSmokeError(line) {
@@ -44,22 +45,25 @@ export function matchesSmokeError(line) {
     return false;
 }
 /**
- * Returns `true` when `line` matches any regex in `allow`. Safe to call
- * with an empty allowlist (always returns `false`).
+ * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
+ * First-match attribution is deterministic and cheap; a line matching
+ * several entries credits the earliest one. Safe to call with an empty
+ * allowlist (always returns -1).
  */
-export function matchesAllowlist(line, allow) {
-    for (const pattern of allow) {
-        if (pattern.test(line)) {
-            return true;
+export function matchAllowlist(line, allow) {
+    for (let i = 0; i < allow.length; i++) {
+        if (allow[i]?.pattern.test(line)) {
+            return i;
         }
     }
-    return false;
+    return -1;
 }
 /**
  * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
- * compiled as a RegExp. A bad pattern throws immediately — better to fail
- * fast at CLI parse time than to silently let a typo match nothing.
+ * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
+ * pattern throws immediately — better to fail fast at CLI parse time than
+ * to silently let a typo match nothing.
  */
 export function compileAllowlistFromFile(body, sourcePath) {
     const lines = body.split(/\r?\n/);
@@ -69,10 +73,14 @@ export function compileAllowlistFromFile(body, sourcePath) {
         if (!line || line.startsWith('#'))
             return;
         try {
-            compiled.push(new RegExp(line));
+            compiled.push({
+                pattern: new RegExp(line),
+                source: line,
+                origin: `${sourcePath}:${String(index + 1)}`,
+            });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = toError(error).message;
             throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
                 cause: error,
             });
@@ -88,10 +96,14 @@ export function compileAllowlistFromStrings(sources) {
     const compiled = [];
     sources.forEach((source, index) => {
         try {
-            compiled.push(new RegExp(source));
+            compiled.push({
+                pattern: new RegExp(source),
+                source,
+                origin: `--console-allow #${String(index + 1)}`,
+            });
         }
         catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = toError(error).message;
             throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
         }
     });