@hominis/fireforge 0.44.4 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.45.0
+
+### Patch bodies
+
+- **A NEW binary file could not be vendored into a patch at all.** Adopting eight WOFF2 faces through `re-export --scan --scan-file` failed, after a clean lint pass, with `Cannot extract text content from binary patch section for …` — and the faces stayed unmanaged, so a `fireforge reset` left the patch's `@font-face` and `jar.inc.mn` lines pointing at missing files. The export half was never at fault: `generateBinaryFilePatch` wrote a correct, replayable `GIT binary patch`. The refusal came from the FORWARD-IMPORT PROJECTION downstream of it. `detectNewFilesInDiff` keys purely on `new file mode`, so binaries entered the loop, and every one of the five projection sites then handed each detected new file to `extractNewFileContentFromDiff`, which refuses binary sections — correctly, since the base85 alphabet includes `+` and "extract the + lines" would write garbage over a binary target.
+  The projection never needed the bytes. It feeds one rule, which scans content for import statements, and a binary blob authors none — so skipping a binary contributes exactly what including it would. The asymmetry was the tell: `buildPatchQueueContext` already tolerated binary new files for REAL queue entries (a per-file try/catch), and only the projections did not. The five duplicated loops are now one `buildNewFileTextProjection`, which skips binary sections and parses the diff once instead of once per new file. `extractNewFileContentFromDiff` still refuses a binary section named explicitly: a caller that asked for THIS file's text must be told no, not silently handed nothing. Nothing is given up by skipping — binary bodies are covered independently by the `binary-body-not-reconstructable` queue lint.
+  Worth recording that the reported symptom was narrower than stated in one direction and wider in another. Plain `fireforge export` of a new binary always worked; the export half fails only behind a placement flag (`--order`/`--before`/`--after`), which is what routes it through `projectPlacementForLint`. But the same projection sits under `patch move-files-into` and `patch split`, so a binary could not be moved between patches or split out either.
+- **The new-file conflict recovery could not handle a binary target, and restored text where it should have restored bytes.** When `git apply` fails because a patch creates a file that is already on disk, FireForge resolves the conflict by putting the patch's intended content in place and retrying. For a binary there is nothing to extract — but nothing needs to be: `git apply` decodes the payload itself, so the resolution is to REMOVE the blocking file and let the retry create it. A `Binary files … differ` body, which records that the bytes changed and carries none of them, is refused instead of deleted, because nothing could put the file back. The saved originals are now raw `Buffer`s rather than utf-8 text, which also closes a latent corruption on the pre-existing path: a binary file overwritten by this recovery was previously restored through a `readText`/`writeText` round-trip that mangles it.
+
+### Refusals
+
+- **`--expect <path>` warned "showed no drift" over a path that did drift and was captured.** The notice was the only feedback that the belt looked at the right files, and none of the causes it named held; the reporter's workaround was `grep -c` on the written body. The measurement was never stated, and stating it is the diagnosis: the comparison is CONTENT, per patch, on the body about to be written and never against post-write state — and it is ONE-DIRECTIONAL, reporting only the payload lines the refreshed body carries that the old body did not. Removing a line from an engine file makes the refreshed body DROP that file's `+` line, so nothing is absorbed and by design there is no drift to see. The notice now says what it compares and when, leads with that one-directional cause, and adds the `--scan-file` adoption case as a named cause (adopting a file also captures that patch's other drifted files, so a scripted scan-less re-export afterwards legitimately sees nothing left — informational at exit 0, and a chain treating the warning as an error will false-red on it). Widening the comparison was considered and rejected: it would turn every ordinary line removal into a refusal, and the belt exists to catch a concurrent session's edits being swallowed INTO a body.
+- **The coverage refusal left its own triage step to the reader.** Adding a test to `xpcshell.toml` while the packaged runtime came from a browser-chrome `test --build` was refused correctly, naming the covered paths, the requested paths, the rebuild command and `--extend-coverage`. What it did not say is WHY this run needed new coverage: a MANIFEST gained an entry, and a browser-chrome build claim never covers xpcshell. FireForge can see both facts. The refusal now names the test manifests changed since the recorded build that sit in an uncovered request path's directory. Behaviour is unchanged; the probe is best-effort and a failure renders exactly the previous text.
+- **`--refuse-adjacent-unmanaged` was all-or-nothing against a recorded exception.** A project with a reviewed, deliberately unmanaged path beside a patch's ownership had no way to say so, so every re-export of every adjacent patch had to drop the flag entirely and substitute a hand-read of the notice — a weaker belt than the one being disarmed, recurring on every touch. `--expect-unmanaged <path>` (repeatable, requires `--refuse-adjacent-unmanaged`) names an approved exception: the belt stays armed for everything else. Approved paths are still LISTED, as an explicit note that they were admitted rather than dropped, because a carve-out nobody can see is how one quietly widens. A path that is never met is reported at the end of the run, for the same reason `--expect` reports its unseen entries: a typo'd carve-out silently leaves the refusal armed for the path it was meant to admit, while reading as an approval that is in force. Deliberately a flag and not a config list — a standing exception nobody re-reads is exactly what this refusal exists to prevent.
+
+### Diagnostics
+
+- **`run --smoke-exit` gave a clean window over the one line that predicts a crash under automation.** The 0.44.1 discriminator (`run --smoke-exit 60 --headless --capture-console <file>`) was run against a build whose startpage pointed at a nonexistent `chrome://` image. It exited 0 with `Unallowed errors: 0` — the "startup is healthy" answer — for a build that hung EVERY browser-chrome run at "Waiting for browser…", while the capture it wrote held the discriminating line: `Missing chrome or resource URL: chrome://…`. That is Gecko's non-automation spelling (`printf_stderr` in `CheckForBrokenChromeURL`, `netwerk/base/nsNetUtil.cpp`); under `xpc::IsInAutomation()` the identical condition is `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. So the probe did discriminate — but only for a reader who grepped the capture, and the exit code said the opposite. `^Missing chrome or resource URLs?:` is now a smoke error pattern, allowlistable through `--console-allow` like any other.
+- **The no-output-stall triage told operators to read a log that structurally cannot carry the evidence.** Cause (3) was recorded as an un-root-caused correlation with a broken `chrome://` image URI. It is now root-caused, and the mechanism explains why the log is empty: under automation the `MOZ_CRASH` lands in whichever process opened the channel, and in the downstream reproduction that was a CONTENT process (`plugin-container`) with the crash reporter compiled out — so the harness log carried neither the message nor a crash line, only the 370 s timeout, `Ran 0 checks`, and mochitest's "Can't trigger Breakpad, just killing process". The only artefact was `~/Library/Logs/DiagnosticReports/plugin-container-*.ips`, faulting frame `CheckForBrokenChromeURL`, which is the symbolicated diagnosis the census bar asks for. The census now names that artefact and the smoke probe together, and states that the log naming nothing is the expected shape rather than an absence of evidence. Detection by log line is still deliberately not specified, and the module doc now records why.
+- **The green-suite teardown belt could reject a run without saying which condition rejected it.** On a composed gate's tiles step: exit 1, 201 `TEST_END`, zero `Test FAIL`, zero `TEST-UNEXPECTED`, only the recognized `mozsystemmonitor` teardown traceback in the tail, FireForge's own "Known upstream …" note printed — and `FIREFORGE-VERDICT: FAIL reason=test-failures … unexpected=0`. The re-run was green and the log had rotated. Every condition in the belt is all-or-nothing, so from outside the failing verdict looks identical whichever one rejected it, and diagnosis reduced to guessing. A rejected run that DID carry the recognized teardown noise now names the first failing condition on the verdict line — `green-teardown override rejected: 2 matched failure line(s), first: …`. A run with no teardown noise was never a candidate for the belt and says nothing, because naming a rejecting condition there would be pure noise. Advisory only: the status and `reason` keys the verdict contract's consumers parse are unchanged.
+- **The undefined-identifier hint named the shim when the cause was an unmanaged companion — and taking the hint would have masked a real bug.** Hoisting duplicated test helpers into a new `head_settings.js` that a managed `head.js` loads via `loadSubScript` leaves the companion owned by no patch until export, so the per-patch program reports every helper use as `Cannot find name` (157 warnings, in the reported case) with a hint offering to add the globals to the extra shim. That remedy makes all 157 disappear AND makes a genuinely missing helper undetectable forever after; the actual fix, `re-export <patch> --scan --scan-file <file>`, the hint never mentioned. When EVERY undefined name in a file is declared at the top level of an unmanaged file that a managed head loads, the hint now names that file, its loader and the adoption command, and rules the shim out explicitly. One unresolved name and the generic hint stays — the file may genuinely be missing a helper, which is the bug this detection exists not to hide.
+- **A test-suite red rendered a build-shaped remedy list.** A failing assertion exited through `BuildError`, so the operator was told to "check the build output above", run `fireforge bootstrap`, and delete `obj-*` directories. None of the three applies to a failing test, and the first points at the wrong half of the log — the half a `tail` keeps. `TestFailureError` now carries remedies that name the failing tests (the `TEST-UNEXPECTED-*` blocks the verdict already collected and, until now, only logged), the `FIREFORGE-VERDICT:` line as ground truth, and the run log path, which is the one artifact that survives the pipe that caused the confusion. It subclasses `BuildError` and **keeps exit 5** deliberately: `docs/exit-codes.md` documents 5 as "a suite that FAILED" and consumers key CI on it, so only the message changes. The `--json` error code does move, from `build` to `test-failure`, because `machineErrorCode` derives it from the class name. `'Test process failed to start'` stays a `BuildError` — a harness that never spawned genuinely can be a build or environment problem, and the build remedies are apt there.
+- **The known-teardown-noise filter covered the test path and not the build path — and could not simply be extended to it.** The `SystemResourceMonitor` `AttributeError` at teardown is recognized, documented upstream noise, and `mach build` surfaced it unannotated, where it reached one consumer as an unexplained build-log traceback during a 153.2.0esr drill. Threading the existing `annotateKnownTeardownNoise` option through the protected build dispatch was the obvious fix and is the wrong one, twice over. It would be a silent NO-OP: recognition requires a previously-seen `SUITE_END`, and a build never prints one. And relaxing that gate would be wrong on its own terms — the marker is what separates teardown from work still in progress, a build has no equivalent boundary, so FireForge cannot tell the known-cosmetic case from a real build-time traceback and must not withhold the block. Separately, the inherit path has no per-chunk hook, only a mirror that feeds the terminal and the run log the same string, so filtering there would strip the traceback from the raw log — the opposite of the "raw into the log, filtered into the echo" invariant the filter was built around.
+  So the build path RECOGNIZES rather than collapses: the traceback prints verbatim and one labeled line names it, using the same closed allowlist (two attributes, plus a `resourcemonitor.py` frame). A novel attribute stays unannotated, because it is a new upstream defect. The filter's module doc now states the test-only scope and both reasons for it, `MachOptions.annotateKnownTeardownNoise` documents that the inherit path ignores it (it type-checked and did nothing, which is how this reads as an oversight from outside), and the signature is documented in `docs/testing.md` — resolving the annotation's dangling "See FireForge docs.", which pointed at documentation that did not exist.
+- **`fireforge source set` wrote a pin that a routine revert silently lost.** The pin lands in `fireforge.json` beside hand-maintained policy sections, so `git checkout -- fireforge.json` — undoing an accidental whole-file reformat, say — also reverts an uncommitted pin, and nothing afterwards reported that the pin and the engine checkout had diverged. The field tell was a gate flipping green with no change that should have made it green. `fireforge doctor` now reports the configured pin beside what the checkout actually is — the engine's own `browser/config/version.txt` and the version the last download recorded into state — and warns when they disagree. A report, not a lock and not a new refusal: a tree may legitimately be mid-migration, and the only thing missing was visibility. Scope is limited by what is actually recorded: `product`, `sha256` and `candidate` have no counterpart on disk (state holds only `downloadedVersion` and `baseCommit`), so the check says nothing about them rather than implying it verified them. A blank or whitespace-only `version.txt` — a truncated write, a partial extraction — reads as absent rather than as a mismatch against the empty string. The check reuses `getFirefoxVersion`, which had been sitting in `firefox-extract.ts` with no production caller.
+
+### Builds
+
+- **The jar-only full-build escalation was over-broad.** `requiresFullBuildForIncrementalTest` was exactly `isJarManifestPath`, so ANY changed jar manifest escalated the pre-test build to a full `mach build` — ~10 minutes against ~20 s for a chrome-only slice, paid twice per green/no-change pair on a Furnace-touching slice. A downstream experiment (two clean runs against 0.44.4) settled the common case: a jar-only registration of a NEW content file added to an EXISTING `dist/bin` manifest was installed by a plain `fireforge build --ui` both times — `faster/install_dist_bin_browser` named the destination, the file landed in `dist/bin/…/content/browser/` and in the `.app` bundle, and a plain `fireforge test` fetched it over `chrome://` at runtime. Neither run escalated. The escalation is now narrowed to the two halves nobody has run: a NEW `jar.mn` (untracked in the engine repo — no install manifest exists for it yet) and a manifest whose jar declaration carries a bracketed base-directory prefix, which redirects the install destination away from the default chrome root. Every probe failure still escalates, so the error direction stays slow-but-correct, and the notice now names the manifest AND the reason instead of saying "a jar.mn registration changed".
+- **Post-build packaging notices could not be triaged on a shared checkout.** The missing-artifact notice keys on "was touched", which on a checkout several sessions share means any of their dirty files — so an operator got a registration-shaped warning about a file they never edited and had to census ownership by hand to dismiss it. Each notice now carries the owning patch, or an explicit `unmanaged` mark. Resolution is best-effort and shares `status --ownership`'s source (the manifest's `filesAffected`); with no queue or an unreadable manifest the notice renders exactly as before, because "unmanaged" has to mean "checked and unowned" rather than "could not check".
+
+### Test harness
+
+- **Nothing could see or reap orphaned harness processes.** Stopping a 45-minute tiles run mid-flight left `xpcshell` (the harness httpd, pegged at 100% CPU), `pywebsocket`, `ssltunnel` and `moz-http2` alive for an hour. Later runs crawled — a three-second suite took six minutes of wall clock, audio-start waits timed out — and nothing in the output connected the slowness to the survivors; the hour went into mis-attributing it to the change under test. Every `fireforge test` dispatch now runs a census of harness helper processes anchored to this project's objdir, naming each with its elapsed time and the `kill` command. It runs at PREFLIGHT, before this run spawns anything, so every hit is by construction a survivor and no age heuristic is needed. A match must be objdir-anchored: `xpcshell` and `server.js` are far too generic to report on their own, the same rule the mochitest server-port preflight already applies. Report-only by default; `--reap-orphans` opts into terminating them. It never refuses a run — a survivor degrades performance rather than making the run dispatch against the wrong server, so the right response is to say so loudly, not to stop.
+
+### Patch lint
+
+- **Per-patch lint ran no Prettier on `.sys.mjs`, so module formatting drift was invisible to every gate** — which is how it survived to a human reviewer. `patchLint.prettier` (`'off'` by default) runs the project's configured Prettier over patch-owned `.sys.mjs` modules. It runs with `cwd` set to `engine/`, which is the half that matters: a fork's ROOT `.prettierignore` typically excludes `engine/`, so the same `prettier --check --config engine/.prettierrc.js <engine files>` run from the repo root reports "all files use Prettier code style" for files that fail the identical check from inside `engine/` — a root-level spot-check falsely refuted a correct reviewer finding on exactly this. Prettier is resolved from `engine/node_modules` first, then the project's, then `npx --no-install`. Exit 2 is reported as prettier failing rather than as formatting drift, since `--write` cannot fix it. Left off, formatting is explicitly out of scope for the per-patch tier — that is now the stated contract rather than an accident.
+- **The `file-too-large` thresholds were module constants, and the soft tier was effectively hard.** Nothing in `fireforge.json` could move `500/750/900` (general) or `1200/1400/1600` (test), and because the recommended gate posture is `--max-warnings 0`, the 750 "soft limit" is a hard failure — a controller sitting at 751 lines failed a gate with a message calling 750 soft, at exactly the moment someone is deciding whether to restructure a file. `patchLint.fileSizeThresholds.{general,test}.{notice,warning,error}` now tunes them (each field optional, merged over the defaults, validated as positive integers ordered `notice <= warning <= error` against the MERGED triple). The message drops the soft/hard vocabulary for what the band actually is — a warning — and names the consequence: a gate running `--max-warnings 0` treats it as a failure. The patch-SIZE thresholds keep their existing wording; only the file-size rule was reported.
+
 ## 0.44.0
 
 ### Gates

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.4",
-  "commit": "b8742ddc056124f81624d9c13d182d0b0c57c86c",
-  "shortCommit": "b8742ddc0561",
+  "version": "0.45.0",
+  "commit": "19d461eb43b89962970510f9a2e655704e9fb952",
+  "shortCommit": "19d461eb43b8",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-28T23:48:06.918Z"
+  "buildTime": "2026-09-01T10:47:47.465Z"
 }

package/dist/src/commands/doctor-source-pin.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * engine checkout actually is.
+ *
+ * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
+ * beside hand-maintained policy sections. That is convenient and it is also
+ * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
+ * accidental reformat, say — silently reverts an uncommitted pin along with
+ * it, and nothing afterwards reports that the pin and the checkout have
+ * diverged. The tell in the field was a gate flipping green with no change
+ * that should have made it green.
+ *
+ * This is deliberately not a lock and not a refusal: a tree may legitimately
+ * be mid-migration between two versions. It only makes a mismatched tree
+ * VISIBLE, which is all that was missing.
+ *
+ * Scope is limited by what is actually recorded. `firefox.product`,
+ * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
+ * disk — `.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit` — so there is nothing to compare them against and the check
+ * says nothing about them rather than implying it verified them.
+ */
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/**
+ * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
+ * dependency on the config check that populates `ctx.config`; skipped
+ * entirely without an engine, where there is nothing to compare.
+ */
+export declare const SOURCE_PIN_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-source-pin.js

@@ -0,0 +1,81 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Doctor check comparing the CONFIGURED Firefox source pin against what the
+ * engine checkout actually is.
+ *
+ * `fireforge source set` lands `firefox.version` inside `fireforge.json`,
+ * beside hand-maintained policy sections. That is convenient and it is also
+ * the whole problem: a routine `git checkout -- fireforge.json` — undoing an
+ * accidental reformat, say — silently reverts an uncommitted pin along with
+ * it, and nothing afterwards reports that the pin and the checkout have
+ * diverged. The tell in the field was a gate flipping green with no change
+ * that should have made it green.
+ *
+ * This is deliberately not a lock and not a refusal: a tree may legitimately
+ * be mid-migration between two versions. It only makes a mismatched tree
+ * VISIBLE, which is all that was missing.
+ *
+ * Scope is limited by what is actually recorded. `firefox.product`,
+ * `firefox.sha256` and `firefox.candidate` have NO counterpart anywhere on
+ * disk — `.fireforge/state.json` records only `downloadedVersion` and
+ * `baseCommit` — so there is nothing to compare them against and the check
+ * says nothing about them rather than implying it verified them.
+ */
+import { getFirefoxVersion } from '../core/firefox.js';
+import { toError } from '../utils/errors.js';
+import { ok, warning } from './doctor-check-core.js';
+const CHECK_NAME = 'Source pin matches engine';
+/**
+ * Reports the configured pin beside the two facts that can contradict it:
+ * the engine's own `browser/config/version.txt`, and the version the last
+ * download recorded into state.
+ */
+async function runSourcePinCheck(ctx) {
+    const pinned = ctx.config?.firefox.version;
+    if (pinned === undefined) {
+        // The config failed to load (its own check already reported that), so
+        // there is no pin to compare. Silence beats a second complaint.
+        return ok(CHECK_NAME, 'Skipped: no configured source version');
+    }
+    let actual;
+    try {
+        // A blank or whitespace-only version.txt (a truncated write, a partial
+        // extraction) carries no version to compare — treat it as absent rather
+        // than reporting the engine as being at version "".
+        actual = (await getFirefoxVersion(ctx.paths.engine))?.trim() || undefined;
+    }
+    catch (error) {
+        // Best-effort: an unreadable version.txt is not a pin mismatch, and a
+        // diagnostic must never turn into a failure of its own.
+        return ok(CHECK_NAME, `Configured ${pinned}; engine version could not be read (${toError(error).message})`);
+    }
+    const downloaded = ctx.state.downloadedVersion;
+    const mismatches = [];
+    if (actual !== undefined && actual !== pinned) {
+        mismatches.push(`engine/browser/config/version.txt reads ${actual}`);
+    }
+    if (downloaded !== undefined && downloaded !== pinned) {
+        mismatches.push(`the last download recorded ${downloaded}`);
+    }
+    if (mismatches.length === 0) {
+        const observed = actual ?? downloaded;
+        return ok(CHECK_NAME, observed === undefined
+            ? `Configured ${pinned}; no engine version to compare against yet`
+            : `Configured ${pinned}, engine ${observed}`);
+    }
+    return warning(CHECK_NAME, `fireforge.json pins Firefox ${pinned}, but ${mismatches.join(' and ')}.`, 'If the pin is right, run "fireforge download" to bring the checkout to it. If the ' +
+        'CHECKOUT is right, run "fireforge source set --version <version>" to record it — a ' +
+        'pin set but not committed is lost by any revert of fireforge.json, which is the most ' +
+        'common way these diverge.');
+}
+/**
+ * Pin-vs-checkout reporting. Needs the loaded config, so it declares the
+ * dependency on the config check that populates `ctx.config`; skipped
+ * entirely without an engine, where there is nothing to compare.
+ */
+export const SOURCE_PIN_DOCTOR_CHECK = {
+    name: CHECK_NAME,
+    skipIf: (ctx) => !ctx.engineExists,
+    dependsOn: ['fireforge.json is valid'],
+    run: runSourcePinCheck,
+};

package/dist/src/commands/doctor.js

@@ -20,6 +20,7 @@ import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
 import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
 import { PATCH_MANIFEST_CONSISTENCY_CHECK } from './doctor-patch-manifest.js';
 import { POST_REBASE_AUDIT_CHECK } from './doctor-post-rebase-audit.js';
+import { SOURCE_PIN_DOCTOR_CHECK } from './doctor-source-pin.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 import { collectPatchQueueHealth } from './verify.js';
 /**
@@ -211,6 +212,7 @@ const DOCTOR_CHECKS = [
             return failure('Pending Resolution', `You are currently resolving a conflict for patch ${patchFilename}.`, 'Build and Export commands may behave unexpectedly until "fireforge resolve" is completed. If the queue now verifies cleanly, run "fireforge doctor --clear-resolution" to discard the stale marker.');
         },
     },
+    SOURCE_PIN_DOCTOR_CHECK,
     {
         name: 'Engine is git repository',
         skipIf: (ctx) => !ctx.engineExists,

package/dist/src/commands/export-flow.js

@@ -12,12 +12,12 @@ import {} from '../core/destructive.js';
 import { detectMovedCodeOverlaps, formatAdoptThenSplitRemedy, } from '../core/export-moved-code-shape.js';
 import { normalizePatchArtifact } from '../core/patch-artifact-normalize.js';
 import { findAllPatchesForFilesWithDetails, patchNameSlug, planExport, } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, lintPatchQueue, } from '../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
 import { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
 import { requirePatchOrder } from '../core/patch-parse.js';
 import { applyRenameMapToManifest, buildProjectedManifest, enforcePatchPolicy, } from '../core/patch-policy.js';
-import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
@@ -166,21 +166,6 @@ export async function resolvePlacementPlan(patchesDir, options, category, name,
     assertPlacementAvoidsReservedRanges(plan, existingPatches, config);
     return plan;
 }
-/**
- * Extracts the newly-created files a diff would produce and builds the
- * `newFiles` map in the shape expected by {@link PatchQueueEntry}. Used
- * to build a faithful synthetic entry for the pending patch when
- * projecting through cross-patch lint — without this the forward-import
- * rule cannot see imports authored by the new patch itself.
- */
-function buildNewFilesFromDiff(diff) {
-    const newFiles = new Map();
-    const newFilePaths = detectNewFilesInDiff(diff);
-    for (const path of newFilePaths) {
-        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
-    }
-    return newFiles;
-}
 /**
  * Projects the placement through cross-patch lint to detect forward-imports
  * the renumber would introduce *or* that the new patch itself would
@@ -206,7 +191,7 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         order: plan.insertionOrder,
         metadata: null,
         diff,
-        newFiles: buildNewFilesFromDiff(diff),
+        newFiles: buildNewFileTextProjection(diff),
         modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff),
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));

package/dist/src/commands/patch/move-files-into.js

@@ -17,11 +17,11 @@
 import { join } from 'node:path';
 import { appendHistory, assertConfirmationAvailable, confirmDestructive, } from '../../core/destructive.js';
 import { normalizePatchArtifact } from '../../core/patch-artifact-normalize.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, savePatchesManifest, validatePatchesManifest, } from '../../core/patch-manifest.js';
-import { extractNewFileContentFromDiff } from '../../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { readText, writeText } from '../../utils/fs.js';
@@ -30,10 +30,7 @@ import { resolveWaitLockSeconds } from '../../utils/options.js';
 import { runPatchLint } from '../export-shared.js';
 import { buildSplitDiff, findOwnerRewriteHolders, mergeStagedForwardImports, rewriteSplitOwners, } from './split-plan.js';
 function projectEntryBody(diff) {
-    const newFiles = new Map();
-    for (const path of detectNewFilesInDiff(diff)) {
-        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
-    }
+    const newFiles = buildNewFileTextProjection(diff);
     return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
 }
 /**

package/dist/src/commands/patch/split-plan.js

@@ -10,12 +10,12 @@ import { join } from 'node:path';
 import {} from '../../core/destructive.js';
 import { getDiffForFilesAgainstHead } from '../../core/git-diff.js';
 import { extractAffectedFiles } from '../../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, collectForwardImportEdges, formatPatchLintIssue, lintPatchQueue, } from '../../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../../core/patch-lint-projection.js';
 import { rewriteStagedDependencyOwners } from '../../core/patch-manifest.js';
 import { applyRenameMapToManifest, buildProjectedManifest } from '../../core/patch-policy.js';
 import { buildPatchSourceMetadata } from '../../core/patch-source-metadata.js';
-import { extractNewFileContentFromDiff } from '../../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { pathExists } from '../../utils/fs.js';
 import { warn } from '../../utils/logger.js';
@@ -82,10 +82,7 @@ export function rewriteSplitOwners(patch, sourceFilename, movedSet, newFilename)
     };
 }
 function buildEntryProjection(diff) {
-    const newFiles = new Map();
-    for (const path of detectNewFilesInDiff(diff)) {
-        newFiles.set(path, extractNewFileContentFromDiff(diff, path));
-    }
+    const newFiles = buildNewFileTextProjection(diff);
     return { diff, newFiles, modifiedFileAdditions: buildModifiedFileAdditionsFromDiff(diff) };
 }
 /** Builds the projected post-split queue entries (renumber + shrunken source + new patch). */

package/dist/src/commands/re-export-adjacent.d.ts

@@ -10,6 +10,14 @@ export interface AdjacentUnmanagedContext {
     binaryName: string;
     furnacePrefixes: ReadonlySet<string>;
     refuseAdjacentUnmanaged: boolean;
+    /**
+     * Engine-relative paths named by `--expect-unmanaged`: reviewed, recorded
+     * exceptions that are reported but never refuse. Normalized once by the
+     * caller so the comparison matches git's engine-relative output.
+     */
+    approvedUnmanaged: ReadonlySet<string>;
+    /** Approved paths actually met this run, so unused ones can be surfaced. */
+    approvedSeen: Set<string>;
     refusals: {
         patchFilename: string;
         files: string[];

package/dist/src/commands/re-export-adjacent.js

@@ -64,6 +64,26 @@ async function findAdjacentUnmanagedFiles(args) {
     }
     return [...candidates].sort();
 }
+/**
+ * Splits the candidates into the ones that refuse and the ones a
+ * `--expect-unmanaged` carve-out admits. Approved paths are recorded as seen
+ * so an unused carve-out can be reported, and are RETURNED rather than
+ * dropped: an exception nobody can see is how a carve-out quietly widens.
+ */
+function partitionApproved(files, ctx) {
+    const refusing = [];
+    const approved = [];
+    for (const file of files) {
+        if (ctx.approvedUnmanaged.has(file)) {
+            ctx.approvedSeen.add(file);
+            approved.push(file);
+        }
+        else {
+            refusing.push(file);
+        }
+    }
+    return { refusing, approved };
+}
 /**
  * Emits the scan-less advisory for one patch: missing manifest files and
  * unmanaged files adjacent to the patch's ownership. When
@@ -83,13 +103,18 @@ export async function reportAdjacentUnmanagedFiles(args) {
             `  Re-run with --scan to reconcile filesAffected with the current worktree, ` +
             `or pass --files <paths> to set the list explicitly.`);
     }
-    const unmanagedFiles = await findAdjacentUnmanagedFiles({
+    const allUnmanaged = await findAdjacentUnmanagedFiles({
         currentFilesAffected,
         engineDir: paths.engine,
         manifest,
         patchFilename: patch.filename,
         ctx,
     });
+    const { refusing: unmanagedFiles, approved } = partitionApproved(allUnmanaged, ctx);
+    if (approved.length > 0) {
+        info(`${patch.filename}: ${String(approved.length)} adjacent unmanaged file(s) admitted by ` +
+            `--expect-unmanaged (${approved.join(', ')}) — reported, not refused.`);
+    }
     if (unmanagedFiles.length === 0)
         return false;
     const firstFew = unmanagedFiles.slice(0, 3).join(', ');

package/dist/src/commands/re-export-drift.d.ts

@@ -72,3 +72,11 @@ export declare function reportForeignDrift(args: {
     newDiffContent: string;
     ctx: ForeignDriftContext;
 }): Promise<boolean>;
+/**
+ * Names `--expect` paths that never drifted this run. A typo'd
+ * `--expect` path silently degrades the flag back to refusing the slice it
+ * was meant to admit, so surface the mismatch — but only as a warning: an
+ * expected file legitimately shows no drift in several shapes, all named
+ * below.
+ */
+export declare function warnUnseenExpectedDrift(driftCtx: ForeignDriftContext): void;

package/dist/src/commands/re-export-drift.js

@@ -271,3 +271,64 @@ function refuseUnreadableBaseline(ctx, patchFilename, detail) {
     warn(`${patchFilename}: skipped (--refuse-foreign-drift) — ${detail}; the drift comparison cannot run, refusing fail-closed.`);
     return true;
 }
+/**
+ * States, verbatim in the notice, WHAT the `--expect` whitelist is compared
+ * against and WHEN. This notice is the only feedback an operator gets that
+ * the drift belt looked at the files they named, and a downstream report
+ * showed the previous copy actively misleading: it warned "showed no drift"
+ * over an edit that WAS captured correctly, and none of the causes it named
+ * held, so the operator's only recourse was `grep -c` on the written body.
+ *
+ * The measurement, stated exactly:
+ *
+ *  - COMPARED: for each file already in the patch's `filesAffected`, the
+ *    `+`/`-` payload lines the REFRESHED body carries that the OLD patch
+ *    body did not (`computeForeignDrift`). It is a content comparison, and
+ *    it is ONE-DIRECTIONAL: excess in the new body only.
+ *  - WHEN: per patch, on the body about to be written, BEFORE the write —
+ *    never against post-write state.
+ *
+ * The one-directional half is what the earlier copy hid, and it is the
+ * cause the report's first shape actually hit: deleting a line from an
+ * engine file makes the refreshed body DROP that file's `+` line. Nothing
+ * is absorbed, so by design there is no drift to see — the belt exists to
+ * catch a concurrent session's edits being silently swallowed INTO a body,
+ * not every difference between two bodies. Naming it is the fix; widening
+ * the comparison would turn every ordinary line removal into a refusal.
+ */
+const EXPECT_MEASUREMENT_NOTE = '--expect is evaluated against CONTENT, before the write: for each file already in the ' +
+    "patch's filesAffected, the payload lines the refreshed body carries that the old patch " +
+    'body did not. It never looks at post-write state.';
+/**
+ * Names `--expect` paths that never drifted this run. A typo'd
+ * `--expect` path silently degrades the flag back to refusing the slice it
+ * was meant to admit, so surface the mismatch — but only as a warning: an
+ * expected file legitimately shows no drift in several shapes, all named
+ * below.
+ */
+export function warnUnseenExpectedDrift(driftCtx) {
+    const unseen = [...driftCtx.expectedDriftFiles].filter((file) => !driftCtx.expectedSeen.has(file));
+    if (unseen.length === 0)
+        return;
+    if (driftCtx.evaluationRuns === 0) {
+        warn(`--expect path(s) were not evaluated because no selected patch reached the drift check (for example, an earlier refusal): ${unseen.join(', ')}`);
+        return;
+    }
+    warn('--expect path(s) showed no drift this run: ' +
+        `${unseen.join(', ')}.\n` +
+        `${EXPECT_MEASUREMENT_NOTE}\n` +
+        'Causes, in rough order of likelihood:\n' +
+        '  1. Your edit only REMOVED lines from the body (you deleted a line from the engine ' +
+        'file). The comparison is one-directional — it reports lines ABSORBED into the body — ' +
+        'so a correctly captured deletion is not drift and never will be. Confirm the capture ' +
+        'with "grep -c" on the written patch body.\n' +
+        "  2. A typo in the path, or a path not in the patch's filesAffected (files adopted " +
+        'this run via --scan/--scan-file are excluded from the comparison by design).\n' +
+        '  3. Adoption already captured it: a "re-export <p> --scan --scan-file <f>" run also ' +
+        "captures that patch's other drifted files, so a scan-less re-export afterwards " +
+        'legitimately sees nothing left to absorb. Informational — a chain that treats this ' +
+        'warning as an error will false-red on it.\n' +
+        '  4. The slice was already captured by an earlier export in this session.\n' +
+        '  5. The engine content already matches the patch body — a concurrent session may have ' +
+        'exported the same change, so the drift converged before this run looked.');
+}

package/dist/src/commands/re-export-files.js

@@ -7,11 +7,11 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { updatePatchAndMetadata } from '../core/patch-export.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, formatPatchLintIssue, lintPatchQueue, } from '../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from '../core/patch-policy.js';
-import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { pathExists } from '../utils/fs.js';
 import { info, outro, success, warn } from '../utils/logger.js';
@@ -42,10 +42,7 @@ function resolveEffectiveTierAndLintIgnore(target, options) {
  */
 async function runProjectedCrossPatchLint(patchesDir, targetFilename, projectedDiff) {
     const baseCtx = await buildPatchQueueContext(patchesDir);
-    const projectedNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(projectedDiff)) {
-        projectedNewFiles.set(path, extractNewFileContentFromDiff(projectedDiff, path));
-    }
+    const projectedNewFiles = buildNewFileTextProjection(projectedDiff);
     const projectedModifiedFileAdditions = buildModifiedFileAdditionsFromDiff(projectedDiff);
     const projectedEntries = baseCtx.entries.map((entry) => {
         if (entry.filename !== targetFilename)

package/dist/src/commands/re-export-options.js

@@ -45,6 +45,24 @@ export function applyReExportFilesPositionalFolding(patches, options) {
     }
     return { patches: normalized.patches, options: normalized.options };
 }
+/**
+ * Each carve-out flag is inert without the refusal it modifies, and a
+ * silently-inert whitelist is the worst shape: the operator believes an
+ * exception is in force while the refusal it was meant to relax was never
+ * armed. Refuse the combination instead of ignoring it.
+ */
+function validateWhitelistFlagDependencies(options) {
+    if (options.expect !== undefined &&
+        options.expect.length > 0 &&
+        options.refuseForeignDrift !== true) {
+        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
+    }
+    if (options.expectUnmanaged !== undefined &&
+        options.expectUnmanaged.length > 0 &&
+        options.refuseAdjacentUnmanaged !== true) {
+        throw new InvalidArgumentError('--expect-unmanaged names approved exceptions to --refuse-adjacent-unmanaged and has no effect without it. Pass --refuse-adjacent-unmanaged, or drop --expect-unmanaged.', '--expect-unmanaged');
+    }
+}
 /** Validates mutually exclusive `re-export` targeting and metadata options. */
 export function validateReExportOptionCombinations(patches, options) {
     if (options.files !== undefined) {
@@ -83,11 +101,7 @@ export function validateReExportOptionCombinations(patches, options) {
     if (options.refuseForeignDrift === true && (options.scan || options.files !== undefined)) {
         throw new InvalidArgumentError('--refuse-foreign-drift applies to the scan-less path only and cannot be combined with --scan or --files (those explicitly capture the current engine state).', '--refuse-foreign-drift');
     }
-    if (options.expect !== undefined &&
-        options.expect.length > 0 &&
-        options.refuseForeignDrift !== true) {
-        throw new InvalidArgumentError('--expect names files whose drift is expected under --refuse-foreign-drift and has no effect without it. Pass --refuse-foreign-drift, or drop --expect.', '--expect');
-    }
+    validateWhitelistFlagDependencies(options);
     const usingTierFlag = options.tier !== undefined;
     const usingLintIgnoreFlag = options.lintIgnore !== undefined && options.lintIgnore.length > 0;
     if (options.all && (usingTierFlag || usingLintIgnoreFlag)) {

package/dist/src/commands/re-export-register.js

@@ -29,6 +29,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .option('--refuse-adjacent-unmanaged', 'Refuse a scan-less re-export (non-zero exit, patch not written) when unmanaged files exist adjacent to the patch ownership, instead of warning. Mutually exclusive with --scan and --files.')
         .option('--refuse-foreign-drift', "Refuse a scan-less re-export (non-zero exit, patch not written) when the refreshed body would absorb engine lines not present in the old patch body — protects multi-session checkouts from silently capturing another session's uncommitted edits. Mutually exclusive with --scan and --files.")
         .option('--expect <path>', "With --refuse-foreign-drift, name an engine-relative file whose drift is this session's intended edit: drift confined to --expect files proceeds, drift anywhere else still refuses. Repeatable, and the whitelist applies across EVERY patch in this invocation, not per patch — so pass all the patches and all their --expect paths in one call rather than looping one patch at a time.", ...stringListOption())
+        .option('--expect-unmanaged <path>', 'With --refuse-adjacent-unmanaged, name an engine-relative file that is a REVIEWED, recorded exception to the adjacency refusal: an approved unmanaged path is still listed, but no longer refuses. Repeatable, and the carve-out applies across EVERY patch in this invocation, not per patch. Use it to keep the belt armed for everything else instead of dropping --refuse-adjacent-unmanaged entirely.', ...stringListOption())
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes for this re-export')
@@ -40,7 +41,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .addOption(new Option('--tier <tier>', 'Force a tier override on the selected patch (only "branding" recognised). Mutually exclusive with --all.').choices(['branding']))
         .option('--lint-ignore <check-id>', 'Append a lint check ID to the patch\'s PatchMetadata.lintIgnore (union, de-duped, repeatable). Mutually exclusive with --all. Use "fireforge patch lint-ignore" for --remove / --clear.', ...stringListOption());
     addWaitLockOption(reExport).action(withErrorHandling(async (patches, options) => {
-        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, ...rest } = options;
+        const { tier, lintIgnore, scanFile, scanFiles, cache, expect, expectUnmanaged, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 're-export', () => reExportCommand(projectRoot, patches, {
             ...pickDefined(rest),
@@ -49,6 +50,9 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
             ...(expect !== undefined && expect.length > 0 ? { expect } : {}),
+            ...(expectUnmanaged !== undefined && expectUnmanaged.length > 0
+                ? { expectUnmanaged }
+                : {}),
             ...(cache === false ? { noCache: true } : {}),
         }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));

package/dist/src/commands/re-export-scan.js

@@ -5,10 +5,10 @@ import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { listTrackedInHead } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
+import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, lintPatchQueue, } from '../core/patch-lint.js';
 import { computeProjectedLintRegressions } from '../core/patch-lint-projection.js';
 import { getClaimedFiles } from '../core/patch-manifest.js';
-import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
+import { buildNewFileTextProjection } from '../core/patch-transform.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { mapWithConcurrency } from '../utils/concurrency.js';
 import { pathExists } from '../utils/fs.js';
@@ -176,10 +176,7 @@ export async function assertScanAdoptionsHaveNoForwardImports(args) {
     const candidateDiff = await getDiffForFilesAgainstHead(engineDir, [...added]);
     if (!candidateDiff.trim())
         return;
-    const candidateNewFiles = new Map();
-    for (const path of detectNewFilesInDiff(candidateDiff)) {
-        candidateNewFiles.set(path, extractNewFileContentFromDiff(candidateDiff, path));
-    }
+    const candidateNewFiles = buildNewFileTextProjection(candidateDiff);
     const candidateAdditions = buildModifiedFileAdditionsFromDiff(candidateDiff);
     const baseCtx = await buildPatchQueueContext(patchesDir);
     const projectedEntries = baseCtx.entries.map((entry) => {