@hominis/fireforge 0.42.0 → 0.43.0

package/dist/src/core/furnace-operation.js

@@ -2,14 +2,32 @@
 import { rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
+import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
-import { withFileLock } from './file-lock.js';
+import { readLockStatus, withFileLock } from './file-lock.js';
 import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
 import { restoreRollbackJournal } from './furnace-rollback.js';
 /** Sidecar lock filename used to serialize concurrent furnace mutations. */
 const FURNACE_LOCK_FILENAME = 'furnace.lock';
+/**
+ * Claims the rollback for one operation, or reports that another path
+ * already has it.
+ *
+ * Must stay synchronous and must be called before the caller's first
+ * await — that is what makes the claim atomic against the signal handler.
+ *
+ * @param operation - The in-flight operation to claim
+ * @returns True when the caller now owns the rollback
+ */
+function claimRollback(operation) {
+    if (operation.rollbackState !== undefined) {
+        return false;
+    }
+    operation.rollbackState = 'in-flight';
+    return true;
+}
 const activeOperations = new Map();
 let nextOperationToken = 1;
 let signalRollbackInFlight = false;
@@ -69,6 +87,13 @@ export async function rollbackActiveOperationsForSignal(signal) {
     signalRollbackInFlight = true;
     warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
     for (const op of snapshot) {
+        // The body may already be rolling back on its own throw path. Claim the
+        // operation (or skip it) before the first await so the two paths cannot
+        // both restore the same journal.
+        if (!claimRollback(op)) {
+            verbose(`Rollback for ${op.kind} already in progress; leaving it to the throw path.`);
+            continue;
+        }
         const cleanupErrors = [];
         // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
         // engine is in its tidiest possible shape before the journal restore
@@ -98,6 +123,7 @@ export async function rollbackActiveOperationsForSignal(signal) {
         catch (error) {
             rollbackError = toError(error).message;
         }
+        op.rollbackState = 'done';
         // A clean signal-driven rollback is not itself a repairable problem:
         // preview/apply/deploy/remove were interrupted, but the engine was restored
         // successfully and the next `doctor` run should remain green. Persist a
@@ -119,6 +145,75 @@ export async function rollbackActiveOperationsForSignal(signal) {
         }
     }
 }
+/**
+ * Rolls back one operation whose body threw, mirroring the signal path.
+ *
+ * Never throws: the body's own error is what the operator needs to see, so
+ * a rollback failure becomes a `pendingRepair` marker plus a warning
+ * rather than replacing it. Skips entirely when the body already restored
+ * its own journal and said so via `ctx.markRolledBack()`.
+ *
+ * @param operation - The in-flight operation whose body threw
+ */
+async function rollbackOperationForThrow(operation) {
+    if (!claimRollback(operation)) {
+        return;
+    }
+    const cleanupErrors = [];
+    // Cleanups before the journal restore, for the same reason the signal path
+    // does it in that order: the restore writes original contents back, and it
+    // should do so over the tidiest possible tree.
+    for (const cleanup of operation.cleanups) {
+        try {
+            await withTimeout(cleanup(), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Cleanup callback');
+        }
+        catch (error) {
+            cleanupErrors.push(toError(error).message);
+        }
+    }
+    if (!operation.journal) {
+        // Nothing was captured, so there is nothing to restore. Unlike the signal
+        // path we do NOT write a pendingRepair marker here: a body that threw
+        // before registering a journal is overwhelmingly a refusal raised during
+        // pre-flight (a validation failure, a missing file), and marking the root
+        // as needing repair would block every later furnace mutation behind a
+        // `doctor --repair-furnace` that has nothing to reconcile. Bodies that
+        // genuinely mutate before registering a journal are the ones the
+        // journal-before-mutation assertions catch.
+        operation.rollbackState = 'done';
+        if (cleanupErrors.length > 0) {
+            warn(`Cleanup after a failed ${operation.kind} reported: ${cleanupErrors.join('; ')}`);
+        }
+        return;
+    }
+    let rollbackError;
+    try {
+        await withTimeout(restoreRollbackJournal(operation.journal), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Rollback journal restore');
+    }
+    catch (error) {
+        rollbackError = toError(error).message;
+    }
+    operation.rollbackState = 'done';
+    if (!rollbackError && cleanupErrors.length === 0) {
+        verbose(`Rolled back ${operation.kind} after a failure; engine restored.`);
+        return;
+    }
+    const reasonParts = [`${operation.kind} failed`];
+    if (rollbackError) {
+        reasonParts.push(`automatic rollback failed: ${rollbackError}`);
+        warn(`Automatic rollback after a failed ${operation.kind} did not complete: ${rollbackError}. ` +
+            'Run "fireforge doctor --repair-furnace" to reconcile.');
+    }
+    else {
+        reasonParts.push('automatic rollback succeeded');
+    }
+    if (cleanupErrors.length > 0) {
+        reasonParts.push(`cleanup errors: ${cleanupErrors.join('; ')}`);
+    }
+    await persistPendingRepair(operation.root, operation.kind, reasonParts.join('; ')).catch((error) => {
+        warn(`Could not persist pending-repair marker: ${toError(error).message}`);
+    });
+}
 async function persistPendingRepair(root, operation, reason) {
     await updateFurnaceState(root, (state) => ({
         ...state,
@@ -189,6 +284,7 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
         return body({
             registerJournal: () => undefined,
             registerCleanup: () => undefined,
+            markRolledBack: () => undefined,
         });
     }
     // Pre-flight: refuse to mutate when a previous operation left the engine in
@@ -214,6 +310,16 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
             'A previous fireforge process may have crashed.',
     };
     return withFileLock(lockPath, async () => {
+        // Everything the body does from here is serialized only by the furnace
+        // lock, so confirm we are actually inside it before registering as a
+        // live mutation. The owner record is deliberately best-effort in
+        // `withFileLock` (a live holder can legitimately have no readable PID),
+        // so the PID half only tightens the check when a record is present —
+        // asserting on its existence would fire on a lock we really do hold.
+        const lockStatus = await readLockStatus(lockPath);
+        assert(lockStatus.held, 'furnace lock held before the mutation body runs');
+        assert(lockStatus.holder === undefined || lockStatus.holder.pid === process.pid, () => `furnace lock is owned by this process ` +
+            `(held by PID ${String(lockStatus.holder?.pid)}, we are ${String(process.pid)})`);
         activeOperations.set(token, operation);
         try {
             return await body({
@@ -223,8 +329,26 @@ export async function runFurnaceMutation(root, kind, body, options = {}) {
                 registerCleanup: (cleanup) => {
                     operation.cleanups.push(cleanup);
                 },
+                markRolledBack: () => {
+                    operation.rollbackState = 'done';
+                },
             });
         }
+        catch (error) {
+            // A thrown error leaves the engine mutated exactly as a signal does,
+            // so it gets the same treatment. Before 0.43.0 this was a bare
+            // finally: the throw path deregistered the operation and marked it
+            // completed, which removed it from the signal handler's view too, so
+            // a body that threw outside its own catch (notably anywhere in
+            // `applyAllComponents` outside its two per-component try blocks) left
+            // the checkout torn with no marker.
+            //
+            // This runs inside the withFileLock callback, so the furnace lock is
+            // still held for the duration of the restore — a competing process
+            // cannot start mutating half-way through it.
+            await rollbackOperationForThrow(operation);
+            throw error;
+        }
         finally {
             operation.completed = true;
             activeOperations.delete(token);

package/dist/src/core/furnace-rollback.d.ts

@@ -24,6 +24,23 @@ export declare function recordCreatedDir(journal: RollbackJournal, dirPath: stri
 export declare function snapshotDir(journal: RollbackJournal, dirPath: string): Promise<void>;
 /** Snapshots a file once so rollback can restore its previous contents or absence. */
 export declare function snapshotFile(journal: RollbackJournal, filePath: string): Promise<void>;
+/**
+ * Asserts that a file about to be mutated was already snapshotted into the
+ * journal that will undo the mutation.
+ *
+ * The snapshot list and the mutation list are separately maintained in every
+ * caller that writes conditionally, and they drift: a new conditional write
+ * whose matching snapshot condition was not updated produces a file the
+ * rollback cannot restore, and nothing notices until a real failure. This
+ * checks the pairing at the point of the write, where the two lists are
+ * supposed to agree.
+ *
+ * @param journal - The journal that will restore this file
+ * @param filePath - Absolute path about to be written
+ * @param context - What is about to write it, for the failure message
+ * @throws {@link InternalInvariantError} when the file was never snapshotted.
+ */
+export declare function assertSnapshotted(journal: RollbackJournal, filePath: string, context: string): void;
 /** Restores all snapshotted files and removes directories created during the operation. */
 export declare function restoreRollbackJournal(journal: RollbackJournal): Promise<void>;
 /** Restores a rollback journal and wraps rollback failures in a FurnaceError. */

package/dist/src/core/furnace-rollback.js

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { chmod, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
+import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 /** Creates an empty rollback journal for tracking touched files and created directories. */
@@ -45,6 +46,13 @@ export async function snapshotDir(journal, dirPath) {
 }
 /** Snapshots a file once so rollback can restore its previous contents or absence. */
 export async function snapshotFile(journal, filePath) {
+    // Journal keys are the paths rollback will later write back to, and the
+    // restore runs from whatever cwd the process happens to be in by then. A
+    // relative key would therefore restore somewhere other than where the
+    // snapshot was taken — silently, and only on the failure path where nobody
+    // is watching. Every caller composes an absolute path already; this keeps
+    // it that way.
+    assert(isAbsolute(filePath), () => `snapshot path is absolute (got "${filePath}")`);
     if (journal.files.has(filePath)) {
         return;
     }
@@ -59,6 +67,25 @@ export async function snapshotFile(journal, filePath) {
         mode: fileStat.mode,
     });
 }
+/**
+ * Asserts that a file about to be mutated was already snapshotted into the
+ * journal that will undo the mutation.
+ *
+ * The snapshot list and the mutation list are separately maintained in every
+ * caller that writes conditionally, and they drift: a new conditional write
+ * whose matching snapshot condition was not updated produces a file the
+ * rollback cannot restore, and nothing notices until a real failure. This
+ * checks the pairing at the point of the write, where the two lists are
+ * supposed to agree.
+ *
+ * @param journal - The journal that will restore this file
+ * @param filePath - Absolute path about to be written
+ * @param context - What is about to write it, for the failure message
+ * @throws {@link InternalInvariantError} when the file was never snapshotted.
+ */
+export function assertSnapshotted(journal, filePath, context) {
+    assert(journal.files.has(filePath), () => `${context} snapshotted "${filePath}" before mutating it`);
+}
 async function restoreFile(filePath, snapshot) {
     if (!snapshot.existed) {
         await rm(filePath, { force: true });
@@ -119,6 +146,13 @@ export async function restoreRollbackJournal(journal) {
         const summary = errors.map((e) => `${e.path}: ${e.error}`).join('; ');
         throw new FurnaceError(`Rollback failed to restore ${errors.length} file(s): ${summary}`);
     }
+    // Directory removal is only safe once every file is back where it belongs:
+    // a created directory may hold a restored file, and removing it recursively
+    // would undo the restore we just performed. The throw above is what
+    // normally enforces this; the assertion names it so a future early-return
+    // or error-swallowing edit cannot quietly reach the rm loop with failures
+    // outstanding.
+    assert(errors.length === 0, 'all journal files restored before created directories are removed');
     const createdDirs = [...journal.createdDirs].sort((left, right) => right.length - left.length);
     for (const dirPath of createdDirs) {
         await rm(dirPath, { recursive: true, force: true });

package/dist/src/core/git-base.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { GitError, GitNotFoundError } from '../errors/git.js';
 import { exec, executableExists } from '../utils/process.js';
+import { readOnlyGitIndexEnv } from './git-readonly-index.js';
 /**
  * Environment variable that overrides the monolithic `git add -A` timeout
  * (milliseconds). 2026-04-24 eval Finding 10: operators on slow or loaded
@@ -63,8 +64,12 @@ export async function git(args, cwd, options) {
     if (options?.timeout !== undefined) {
         execOptions.timeout = options.timeout;
     }
-    if (options?.env !== undefined) {
-        execOptions.env = options.env;
+    // A read-only command's private-index scope overlays GIT_INDEX_FILE so
+    // index refreshes never touch the primary checkout.
+    // Merged UNDER the caller's own env so an explicit override still wins.
+    const readOnlyIndexEnv = readOnlyGitIndexEnv(cwd);
+    if (options?.env !== undefined || readOnlyIndexEnv !== undefined) {
+        execOptions.env = { ...readOnlyIndexEnv, ...options?.env };
     }
     const result = await exec('git', args, execOptions);
     if (result.exitCode !== 0) {

package/dist/src/core/git-diff.js

@@ -9,9 +9,18 @@ import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { chunkPathspecs, ensureGit, git } from './git-base.js';
 import { fileExistsInHead, hashObjectBatch, isBinaryFile, listTrackedInHead, } from './git-file-ops.js';
+import { readOnlyGitIndexEnv } from './git-readonly-index.js';
 import { getUntrackedFiles, getUntrackedFilesInDir } from './git-status.js';
 async function execGitWithAllowedExitCodes(repoDir, args, allowedExitCodes = [0]) {
-    const result = await exec('git', args, { cwd: repoDir });
+    // Honour a read-only command's private-index scope: the `--intent-to-add`
+    // / `update-index` staging dance below is a genuine
+    // index write, and inside a read-only command it must land on the
+    // private index, not the primary checkout's.
+    const readOnlyIndexEnv = readOnlyGitIndexEnv(repoDir);
+    const result = await exec('git', args, {
+        cwd: repoDir,
+        ...(readOnlyIndexEnv !== undefined ? { env: readOnlyIndexEnv } : {}),
+    });
     if (allowedExitCodes.includes(result.exitCode)) {
         return result;
     }
@@ -466,7 +475,7 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
         // *removing* whatever entry the index carried, so any staged state that
         // arrived between the read-only diff above and this staging block (a
         // concurrent writer, or a staged-add whose worktree file was deleted)
-        // was silently discarded (FORGE H1). Restoring the captured entry
+        // was silently discarded. Restoring the captured entry
         // instead makes the cleanup exact regardless of how the entry got there.
         const priorEntry = (await execGitWithAllowedExitCodes(repoDir, ['ls-files', '--stage', '--', filePath])).stdout;
         try {

package/dist/src/core/git-readonly-index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Private-index scope for FireForge's READ-ONLY git plumbing.
+ *
+ * `git status` and `git diff HEAD` are read-only in the sense operators
+ * care about — they never change tracked content — but they are NOT
+ * read-only to git: both refresh the index's stat cache and write
+ * `.git/index` (through `.git/index.lock`) when a file's stat data has
+ * moved. That makes `fireforge verify` / `lint --per-patch` / `typecheck`
+ * a second WRITER of the primary `engine/` checkout, even when the command
+ * was pointed at a CoW tree clone.
+ *
+ * The consequence is not cosmetic. A concurrent `fireforge test`
+ * fingerprints `engine/` before and after the harness run and refuses a
+ * verdict taken across a change (`FAIL reason=inconclusive`). That refusal
+ * is CORRECT and stays; the defect is that FireForge's own read-only
+ * commands were tripping it. Measured downstream: perfect correlation
+ * between lane overlap and inconclusive verdicts, on suites that had
+ * actually passed.
+ *
+ * The fix is the standard git one: point the plumbing at a PRIVATE index
+ * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp
+ * directory. Refreshes land there and are thrown away; the primary
+ * `.git/index` — and `.git/index.lock`, which is what made a concurrent
+ * `git status` fail outright rather than merely churn — is never touched.
+ *
+ * Fail-open by design: if the git dir or the index cannot be resolved or
+ * copied, the scope simply does not activate and the commands behave
+ * exactly as before. A read-only command must not start failing because
+ * an optimisation could not be set up.
+ *
+ * The scope is process-global and non-reentrant on purpose: FireForge
+ * commands are one-shot CLI invocations, and nesting two different private
+ * indexes for the same run has no meaning. A nested call reuses the outer
+ * scope.
+ */
+/**
+ * Environment overlay a git invocation in `cwd` must carry, or undefined
+ * when no private-index scope covers it.
+ *
+ * Matching is by resolved path prefix: plumbing frequently runs with `cwd`
+ * set to a subdirectory of the scoped repository, and those invocations
+ * share the same index.
+ *
+ * @param cwd - Working directory the git process will run in
+ * @returns `{ GIT_INDEX_FILE }` when scoped, otherwise undefined
+ */
+export declare function readOnlyGitIndexEnv(cwd: string): Record<string, string> | undefined;
+/** True while a private-index scope is installed (diagnostics and tests). */
+export declare function hasReadOnlyGitIndexScope(): boolean;
+/**
+ * Runs `operation` with FireForge's git plumbing pointed at a private
+ * index seeded from `repoDir`'s own, so the primary checkout's
+ * `.git/index` (and `.git/index.lock`) are never written.
+ *
+ * @param repoDir - Repository whose plumbing should use a private index
+ * @param operation - The read-only command body
+ * @returns Whatever `operation` returns
+ */
+export declare function withPrivateGitIndex<T>(repoDir: string, operation: () => Promise<T>): Promise<T>;

package/dist/src/core/git-readonly-index.js

@@ -0,0 +1,137 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Private-index scope for FireForge's READ-ONLY git plumbing.
+ *
+ * `git status` and `git diff HEAD` are read-only in the sense operators
+ * care about — they never change tracked content — but they are NOT
+ * read-only to git: both refresh the index's stat cache and write
+ * `.git/index` (through `.git/index.lock`) when a file's stat data has
+ * moved. That makes `fireforge verify` / `lint --per-patch` / `typecheck`
+ * a second WRITER of the primary `engine/` checkout, even when the command
+ * was pointed at a CoW tree clone.
+ *
+ * The consequence is not cosmetic. A concurrent `fireforge test`
+ * fingerprints `engine/` before and after the harness run and refuses a
+ * verdict taken across a change (`FAIL reason=inconclusive`). That refusal
+ * is CORRECT and stays; the defect is that FireForge's own read-only
+ * commands were tripping it. Measured downstream: perfect correlation
+ * between lane overlap and inconclusive verdicts, on suites that had
+ * actually passed.
+ *
+ * The fix is the standard git one: point the plumbing at a PRIVATE index
+ * (`GIT_INDEX_FILE`) seeded from the repository's own, in a temp
+ * directory. Refreshes land there and are thrown away; the primary
+ * `.git/index` — and `.git/index.lock`, which is what made a concurrent
+ * `git status` fail outright rather than merely churn — is never touched.
+ *
+ * Fail-open by design: if the git dir or the index cannot be resolved or
+ * copied, the scope simply does not activate and the commands behave
+ * exactly as before. A read-only command must not start failing because
+ * an optimisation could not be set up.
+ *
+ * The scope is process-global and non-reentrant on purpose: FireForge
+ * commands are one-shot CLI invocations, and nesting two different private
+ * indexes for the same run has no meaning. A nested call reuses the outer
+ * scope.
+ */
+import { copyFile } from 'node:fs/promises';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+/** The active private-index scope, when a read-only command installed one. */
+let activeScope;
+/** Bound on the git-dir probe so a wedged git cannot stall a read-only run. */
+const GIT_DIR_PROBE_TIMEOUT_MS = 30_000;
+/**
+ * Environment overlay a git invocation in `cwd` must carry, or undefined
+ * when no private-index scope covers it.
+ *
+ * Matching is by resolved path prefix: plumbing frequently runs with `cwd`
+ * set to a subdirectory of the scoped repository, and those invocations
+ * share the same index.
+ *
+ * @param cwd - Working directory the git process will run in
+ * @returns `{ GIT_INDEX_FILE }` when scoped, otherwise undefined
+ */
+export function readOnlyGitIndexEnv(cwd) {
+    if (activeScope === undefined)
+        return undefined;
+    const resolved = resolve(cwd);
+    const scoped = activeScope.repoDir;
+    if (resolved !== scoped && !resolved.startsWith(`${scoped}/`))
+        return undefined;
+    return { GIT_INDEX_FILE: activeScope.indexFile };
+}
+/** True while a private-index scope is installed (diagnostics and tests). */
+export function hasReadOnlyGitIndexScope() {
+    return activeScope !== undefined;
+}
+/**
+ * Resolves a repository's git directory. Returns undefined for anything
+ * that is not a readable git checkout — `engine/` is not always one
+ * (`fireforge download` extracts a source tarball).
+ */
+async function resolveGitDir(repoDir) {
+    try {
+        const result = await exec('git', ['rev-parse', '--absolute-git-dir'], {
+            cwd: repoDir,
+            timeout: GIT_DIR_PROBE_TIMEOUT_MS,
+        });
+        if (result.exitCode !== 0)
+            return undefined;
+        const gitDir = result.stdout.trim();
+        return gitDir.length > 0 ? gitDir : undefined;
+    }
+    catch (error) {
+        verbose(`Private git index: could not resolve the git dir — ${toError(error).message}`);
+        return undefined;
+    }
+}
+/**
+ * Runs `operation` with FireForge's git plumbing pointed at a private
+ * index seeded from `repoDir`'s own, so the primary checkout's
+ * `.git/index` (and `.git/index.lock`) are never written.
+ *
+ * @param repoDir - Repository whose plumbing should use a private index
+ * @param operation - The read-only command body
+ * @returns Whatever `operation` returns
+ */
+export async function withPrivateGitIndex(repoDir, operation) {
+    if (activeScope !== undefined)
+        return operation();
+    const gitDir = await resolveGitDir(repoDir);
+    if (gitDir === undefined)
+        return operation();
+    let tempDir;
+    try {
+        tempDir = await mkdtemp(join(tmpdir(), 'fireforge-roindex-'));
+        const privateIndex = join(tempDir, 'index');
+        const sourceIndex = join(gitDir, 'index');
+        // A repository with no index yet (a fresh init) is fine: git creates
+        // the private one on first use.
+        if (await pathExists(sourceIndex)) {
+            await copyFile(sourceIndex, privateIndex);
+        }
+        activeScope = { repoDir: resolve(repoDir), indexFile: privateIndex };
+        verbose(`Private git index active for ${repoDir} (${privateIndex}).`);
+    }
+    catch (error) {
+        // Fail-open: an unset-up scope must never fail a read-only command.
+        verbose(`Private git index unavailable — ${toError(error).message}`);
+        activeScope = undefined;
+        if (tempDir !== undefined)
+            await rm(tempDir, { recursive: true, force: true });
+        return operation();
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        activeScope = undefined;
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}

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

@@ -86,7 +86,7 @@ export declare function containsUpstreamLicenseText(content: string, maxLines?:
  * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
  * comment style. Used by `export` to treat such files as vendored: offering
  * to prepend the project's own license header onto a byte-identity-pinned
- * upstream bundle would mislicense third-party code (FORGE F15).
+ * upstream bundle would mislicense third-party code.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 30 — full

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

@@ -257,7 +257,7 @@ export function containsUpstreamLicenseText(content, maxLines = 10) {
  * permissive license banner (MIT / ISC / BSD-2 / BSD-3 / Apache-2.0), in any
  * comment style. Used by `export` to treat such files as vendored: offering
  * to prepend the project's own license header onto a byte-identity-pinned
- * upstream bundle would mislicense third-party code (FORGE F15).
+ * upstream bundle would mislicense third-party code.
  *
  * @param content  - File content to check
  * @param maxLines - Number of leading lines to inspect (default 30 — full

package/dist/src/core/lint-cache.d.ts

@@ -1,15 +1,20 @@
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type PatchQueueContext } from './patch-lint.js';
-export declare const LINT_CACHE_SCHEMA_VERSION = 3;
+export declare const LINT_CACHE_SCHEMA_VERSION = 4;
 export interface PerPatchLintCacheEntry {
     key: string;
     patchFilename: string;
     issues: PatchLintIssue[];
-    /** Issues dropped by the patch's lintIgnore waivers (FORGE G10). */
+    /** Issues dropped by the patch's lintIgnore waivers. */
     suppressed: PatchLintIssue[];
     /** Non-binary diff line count measured by the cached lint run. */
     lineCount: number;
+    /**
+     * Sorted lint-ignore waiver ids in force when this entry was computed
+     *. A lookup presenting a different effective set misses.
+     */
+    lintIgnore: string[];
     updatedAt: string;
 }
 export interface PerPatchLintCacheFile {
@@ -46,7 +51,12 @@ export interface CachedPerPatchLint {
     suppressed: PatchLintIssue[];
     lineCount: number;
 }
-/** Returns the cached lint payload for a patch when the stored key still matches. */
-export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): CachedPerPatchLint | undefined;
+/**
+ * Returns the cached lint payload for a patch when the stored key still
+ * matches AND the entry was computed under the same lint-ignore waiver set
+ *. A waiver change makes a replayed verdict actively wrong, so
+ * the waiver set is compared explicitly rather than trusted to the key.
+ */
+export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, lintIgnore?: Iterable<string>): CachedPerPatchLint | undefined;
 /** Stores the per-patch lint payload after a successful lint calculation. */
-export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[], suppressed: PatchLintIssue[], lineCount: number): void;
+export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[], suppressed: PatchLintIssue[], lineCount: number, lintIgnore?: Iterable<string>): void;