@hominis/fireforge 0.44.1 → 0.44.3

package/CHANGELOG.md

@@ -20,6 +20,10 @@
   `binaryStagingLock` never covered it — it is a module-level promise chain, so it serializes within one process while `--parallel-verify` lanes are separate processes. The staging now writes a per-call PRIVATE index (`mintDisposableGitIndex`) and throws it away, so the primary `.git/index` never moves, nothing is restored because nothing shared changed, and two concurrent callers get two indexes rather than contending. The 0.43.0 private-index work closed this for read-only commands; this path is the deliberate writer it did not cover, and it could not have been fixed by leaning on that scope — `export` and `re-export` install none, and `withPrivateGitIndex` is fail-open by design, which on a write path means silently mutating the primary checkout.
   The seed is load-bearing rather than tidy: a tracked, unmodified binary reaches the same branch (its `diff HEAD` is empty), and against an empty index it would report as a fresh add. The shared-index path survives as a fallback for when no private index can be minted — refusing there would fail an export over an optimisation. A real-git test polls `git status` throughout the call and asserts the transient entry is never observable; it fails on the old implementation, which is what makes it worth having.
 
+- **`--wait-lock` governed only ONE of the two locks a furnace mutation takes.** `furnace apply`/`deploy`/`sync` routed the resolved budget into the engine session lock and stopped there. `runFurnaceMutation` then acquired `.fireforge/furnace.lock` through `withFileLock`, passing `timeoutMs` only when `options.lockTimeoutMs` was set — and **no production caller ever set it**: the field's only other occurrences were its own declaration and one test, and its doc comment cited a watch-mode caller that does not exist. So the file lock always fell to `DEFAULT_LOCK_TIMEOUT_MS`, a fixed 30 s. A contended `deploy --wait-lock 1800` therefore died at 30 s while its operator believed a half-hour budget was in force, which is the worst shape a budget can have: it pays the entire advertised wait and still refuses. `FIREFORGE_WAIT_LOCK` did not help — it feeds the same resolver into the same single sink.
+  The resolved budget now reaches both. It is threaded explicitly into the three commands that declare the flag (`waitLockMutationOptions` does the seconds-to-milliseconds conversion once, rather than at three call sites where dropping the factor is a silent 1000× error), and `runFurnaceMutation` falls back to `sessionWaitLockMs()` — the environment budget — so the twelve furnace mutators with no flag to thread (`create`, `remove`, `rename`, `refresh`, `scan`, `override`, `chrome-doc`, …) are covered too. An explicit `lockTimeoutMs` still wins, and absent both the ~1 s fail-fast and the 30 s default are untouched.
+  The invisibility was the other half of the defect: the flag's help text said "the contended lock", singular, and the furnace refusal named neither the lock nor the flag — it advised removing a stale lock directory. The help now says the budget covers every lock the command takes, and the refusal names the FURNACE lock, says it is the second of two, and points at `--wait-lock`/`FIREFORGE_WAIT_LOCK`. A test asserts the budget reaches the command options, and a sibling asserts nothing is threaded without the flag.
+
 ### Exit codes
 
 - **Red, never-ran and thrown-away were three facts sharing two exit codes.** `reason=inconclusive` — a suite whose verdict was DISCARDED because `engine/` moved under it — exited **1** beside real test failures' **5**, and a summary line reading `FAIL — exit 1` next to `FAIL — exit 5` invites treating opposites as the same kind of fact: one suite failed, the other's healthy result was thrown away. It now exits **14** (`InconclusiveVerdictError`). `LockContentionError` moves from 1 to **15**: a lock timeout means the run never started, so a script should re-queue it rather than report a failure of the work it asked for. That re-codes patch-directory, build and furnace lock timeouts too — deliberately, since the fact is the same whichever lock was contended. See `docs/exit-codes.md`.
@@ -39,6 +43,15 @@
 - **The packaging-coverage refusal never mentioned `--extend-coverage`.** The cumulative claim shipped in 0.43.0, but under concurrent sessions the operator meets it at the moment a peer's scoped build has replaced coverage they still hold — and the refusal pointed only at a full rebuild. It now offers the union, and states the anchor conditions (unchanged engine HEAD and `engine/mozconfig`) so the operator knows when it will refuse. Coverage still REPLACES by default, for the reason documented on `BuildBaseline.testPackagingCoverage`: a blind union whitewashes an earlier scope's edited fixtures while `obj-*/_tests/` still holds that scope's stale staging.
 - **The no-output-stall census asserted a mechanism it had no evidence for, and its third cause carried no discriminating step.** The `chrome://`-image entry shipped in 0.43.0 stating that a broken image URI on the startup page "stalls first paint"; that mechanism was never established here — it was written on top of a single downstream report which explicitly did not root-cause it, and it is doubtful on its own terms, since a failed image load in Gecko fires `error` without gating the document load event. The entry now states the correlation it actually rests on (one consumer, reproduced and un-reproduced on one variable) and says the mechanism is open, so nobody inherits a guess as a fact. Separately, its remedy — run a known-good control — is the correct opening move for **all three** causes, so attaching it to one entry made reaching that entry informationally empty; the control step is hoisted above the list, and cause 3 gains a probe that actually separates it from the other two (`fireforge run --smoke-exit … --capture-console`, which starts the same browser outside the test harness). No detector is claimed: no log line is known to key on, and `mach-error-hints.ts` sets the bar at an established diagnosis rather than a plausible one. The census moved to `src/core/test-stall-triage.ts` — it is operator advice, not classification, and the rules for editing it are not the rules for editing a classifier.
 
+- **A run's only copy of its own diagnosis died with the pipe.** `fireforge test … 2>&1 | tail -40` keeps the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT broke; it also launders the exit code. Nothing else held the output — `runMachCapture` keeps a 2 MB in-memory tail that dies with the process, and the shard retry loop discards earlier attempts outright — so one downstream failure is now permanently undiagnosable and cost two further full runs to pin as "unreproduced". The operator rule ("never pipe a run") had been written down three times and broken after each writing, which is the tell that it is not an operator problem: piping is the ergonomic default when output is long, and the tool is the only party that can make the log survive the mistake.
+  `test` and `build` now write their own complete output to `.fireforge/logs/<command>-<timestamp>.log` as they stream, retained 20 deep per command kind (per-kind, so a busy `test` loop cannot evict the `build` log an operator needs to read beside it). The tee sits at the two mach capture funnels rather than at the commands, so it covers every dispatch — the three test dispatchers, `package`, and the stdio-inheriting path `mach build` uses, which rides the collectors' existing `mirror` hook rather than growing a second one. The log gets the RAW bytes, never the echo filter's collapsed form: the artifact exists to be re-read by whoever is diagnosing the run, so shortening it would reintroduce the loss it prevents.
+  The path rides the `FIREFORGE-VERDICT:` line as an additive `log=<path>` key. That is deliberate and not a free choice — the verdict must stay the run's LAST stdout write, so a separate announcement after it would break the contract and one before it is the first thing a `tail` cuts. `build`, which prints no verdict line, announces the path directly. Everything here is best-effort: a log that cannot be opened, written or pruned degrades to no log, because a run must never fail over a diagnostic. Opened before any preflight, so a refusal is logged too — those are exactly the runs whose only output a `tail` throws away.
+- **Post-rebuild failure diagnosis promoted recognized teardown noise over the real assertion.** An export shard failed on its file-count assertion; the diagnosis named the known `AttributeError: 'SystemResourceMonitor' object has no attribute 'stop_time'` instead. The raw Error Summary had the assertion right, so the information was present and the SELECTION was wrong — the expensive kind, because the named cause is a real, documented, unrelated upstream defect and therefore reads as an answer.
+  0.44.0 already ships `mach-known-noise-filter.ts`, whose module doc says exactly the right thing about closing the presentation gap — but `findFirstUsefulFailureLine` never consulted it. It matched a bare `/AttributeError:\s+/` among its patterns and selected by first-matching-LINE, not first-matching-pattern, so that arm had precisely the same standing as `TEST-UNEXPECTED-FAIL` and whichever appeared earlier won. The selector now runs two passes: candidates excluding the recognized noise first, the full set only if that finds nothing. The narrowness is preserved exactly — the exclusion is gated on `hasKnownTeardownNoise` for the whole capture, so it still requires both the closed `stop_time`/`poll_interval` allowlist AND a `resourcemonitor.py` frame, and a novel attribute or a traceback from anywhere else stays a real failure. Three tests pin those escape hatches; the one that pins the fix fails on the old code.
+  Worth recording that the misdiagnosis was CONDITIONAL, not universal: the classifier reads stdout then stderr, and the traceback usually lands on stderr while the suite output lands on stdout, so a real `TEST-UNEXPECTED-*` normally won on ordering alone. It bites when the traceback shares or precedes the stream, or when the real failure matches none of the other patterns. The reporter could not have known that, and it does not change the fix — but a defect described as always-firing gets re-opened as "not reproducible" by the next reader.
+- **mozbuild's AI-agent output limiter quieted test runs, not just builds.** `is_running_under_coding_agent()` keys on `CLAUDECODE`, which FireForge inherited into every mach dispatch verbatim — it had no handling of the variable anywhere. The build half of that quieting is genuinely useful; the test half removes `TEST_START` and console INFO, exactly the lines a hang diagnosis needs, and the ones FireForge's own classifier reads (`Ran N checks`, `Unexpected results:`, `TEST-UNEXPECTED-*`), so suppression pushes a run toward `reason=no-tests`. Unsetting the variable for the whole process gives up the build half too.
+  `fireforge test --full-output` now unsets the marker for TEST dispatches only; the build path is untouched. It is opt-in rather than automatic because it changes how much a third party prints, and an operator who wants the quieting should keep it. The exec layer gained an explicit `envUnset` for this: `env` can only add or overwrite, and a variable read for its PRESENCE is not unset by an empty value — and the removal is a real delete rather than a `Record<string, string | undefined>` widening, because relying on Node dropping `undefined` env entries would be a semantics gamble at the one layer that must not have any.
+
 ### Build output resolution
 
 - **A second `obj-*` directory made FireForge refuse every command, even when the mozconfig said which one to use.** The refusal is correct where the choice is genuinely ambiguous — building a dev test against a release objdir is exactly the silent corruption it prevents — but `MOZ_OBJDIR` was never read, so an operator whose active configuration had already answered the question was sent to rename a directory to satisfy a scan. An ambiguous glob now consults `engine/mozconfig` (`mk_add_options MOZ_OBJDIR=…` or a bare `export`, `@TOPSRCDIR@` and relative forms resolved to a path segment) and proceeds when the declaration resolves to exactly one candidate — into the existing `mozinfo.json` verification, which is the real safety net. Everything else still refuses, and a declaration that named something the scan cannot see is reported, because that is itself the diagnosis.
@@ -63,6 +76,17 @@
 - The signal-time furnace lock sweeper removed lock directories without checking ownership, so it could delete a lock another process had acquired in the window between our operation dying and the sweep running. It now uses `releaseLockIfOwned`.
 - `killProcessTree`'s POSIX branch swallowed `ESRCH`/`EPERM` from the group kill without falling through to a direct `child.kill`, so a failed group kill left the child running.
 
+- **A DELETION of an upstream file could not be made durable through `re-export`, and the failure was silent.** With eighteen retired files, `rm` left `fireforge status --json` reporting `"status": "D"` with `"classification": "unmanaged"` — correct as a description, fatal as a state, because `check-engine-clean` refuses an unmanaged file precisely because it is not durable through a reset, and a reset would restore every deleted file. No re-export path captured it: `--scan` pruned the path from `filesAffected` and emitted no deletion hunk, `--scan-file` refused it outright, and **`--files` accepted the path and emitted no hunk** — the dangerous shape, because the run reported success while writing a patch that silently CLAIMED a file it did not restore. On a fresh clone that patch applies cleanly and resurrects exactly what the change meant to remove.
+  The cause was one conflation. All three paths filtered "absent from disk" out of the diff scope, on a comment asserting the diff "would fail" on a missing path — true only for a path that was NEVER TRACKED. For a tracked file deleted in the worktree, `git diff HEAD -- <path>` emits a proper `deleted file mode` section, and every downstream consumer already branches on `isDeletedFile`. The two cases are now split by `listTrackedInHead`: a tracked absent path stays in the diff scope and is captured, an untracked one is refused rather than warned about, since the patch cannot express it either way. A captured deletion KEEPS its `filesAffected` entry — the patch is what performs the deletion, so pruning it would leave the body deleting a file the manifest says the patch has nothing to do with — and it still requires the confirmation, because the patch will now remove those files wherever it is applied.
+  The report's priority-1 item — make the silent success LOUD — turned out to need two words, not a feature: the `--files` path already refused when a requested path produced no hunk, but its domain was the post-filter subset, so anything dropped upstream was invisible to the check by construction. It now runs against the full requested list. A real-git test asserts the emitted patch contains `deleted file mode`; it fails on the old implementation.
+  Recorded because the report says otherwise and the next reader should not chase it: **`export` was never affected.** It accepts a `D` status from `getStatusWithCodes` and routes a HEAD-tracked path to `git diff --binary HEAD`, which has always carried the deletion. Only the batched `re-export` paths dropped it.
+- **`token add --mode override` silently skipped a QUALIFIED `[data-theme="light"]` block.** The override path mirrors into both `:root[data-theme="dark"]` and `:root[data-theme="light"]`, guarded by `variantBlockExists` — and that guard compared canonically against a fragment sliced to the LAST `]` before the opening brace. For `:root[data-theme="light"]:not([data-private]) { }` the last `]` is the one inside `:not(…)`, so the computed fragment was `:root[data-theme="light"]:not([data-private]` and the comparison could never match. The unqualified dark block beside it matched fine. That asymmetry was the whole bug: the override wrote dark, skipped light, and said nothing — so a Light choice under a dark OS inherited the new dark token, and the operator met the gap as a theme bug rather than as tool output. `THEME_ATTRIBUTE_VARIANTS`' own doc comment names the failure this feature exists to prevent — "a guaranteed half-finished edit" — and the half-finished edit is what shipped.
+  The last-`]` slice was deliberate, not sloppy: it avoids a `js/polynomial-redos` regex, and taking the last `]` rather than the first keeps a multi-attribute selector comparing as a whole instead of colliding with a single-attribute variant that is its prefix. Both properties survive. The selector is now parsed structurally — consume consecutive `[…]` groups after `:root`, stop at the first character that is not `[` — which is still linear and still matches multi-attribute blocks whole, but excludes a pseudo-class tail instead of swallowing it. A regression test uses a two-attribute block to pin that.
+  The qualifier is reported rather than applied silently. `:not([data-private])` is semantically load-bearing — writing through it narrows where the declaration applies, and that may not be what the operator meant — but matching it is still the right call, because silently skipping it is the worse failure and the one that shipped. So the write happens and a warning names the selector it went through. The pinning test fails on the old matcher.
+- **`token add --variant` required a flag that described nothing, rejected its companion, and reported a no-op as success.** Three separate frictions, all in the variant path. `--category` was an unconditional `requiredOption` that had to name a REAL category even under `--variant`, where the declaration is routed into a `:root<selector>` block and never into a category section — the requirement existed so the argument would not be "silently discarded", a fair goal whose effect was a mandatory argument saying nothing about where the token lands. It is now optional there (still validated when supplied, so a typo is not accepted just because the flag is inert), and its absence on a BASE declaration is refused with the REASON stated rather than commander's bare "required option not specified".
+  `--create-category` is still rejected with `--variant` — the two really are incompatible — but the working create-then-variant order (author the category with the base token, then add each variant) was discoverable only by failing twice. It is now in both the error and `--variant`'s help text.
+  And a token already present in the target variant block was skipped with a bare `{ added: false }`, so a re-run intending to CHANGE a value exited 0 having changed nothing, while the base path had been reporting the category and line for the same situation all along. The variant path now returns the location too, and the skip reads `already exists in :root[…] (line N), unchanged` — the block being the location, since a variant declaration has no category to name.
+
 ### Security
 
 - **Six scanners over `tokens.css` were super-linear in the length of a single line** (`js/polynomial-redos`). Worth stating plainly what the input is: `tokens.css` and `docs/design/SRC_TOKENS.md` are files FireForge reads out of a CONSUMER's engine tree, so "attacker-controlled" is the wrong frame — a minified, generated or merge-mangled line that happens to repeat `:root`, `:root[`, `var(` or `/*=` is enough to wedge `token add` with nobody doing anything hostile. Measured on the witnesses now pinned as tests: 4 000 `=` after a `/*` cost the category scanner **8.2 s**, and 20 000-40 000 repetitions cost the other five between **0.8 s and 3.6 s** each. Two distinct causes, and they want different remedies:
@@ -125,6 +149,9 @@
 - **`fireforge test --doctor` printed the same preflight line three times** on a terminal: a 2026-04-24 fix added an emission for non-TTY capture without removing the two it superseded. The raw writes are gated on non-TTY, which is where the capture requirement applies; the clack framing stays for terminals.
 - **All seven** `--wait-lock` commands that take the patch-directory lock now honour it: `patch tier`, `patch lint-ignore`, `patch staged-dependency`, `export-all`, `resolve`, `doctor` and `rebase`. Each routes through a different lock entry point, so the budget is threaded through `updatePatchMetadata`, `mutatePatchMetadata`, `commitExportedPatch`, `updatePatchAndMetadata`, `rebuildPatchesManifest` and the rebase patch loop.
 - `status --json` outside a project wrote a clack-styled block to **stdout** and exited 2, because the config error is raised before the command body engages machine mode. The boundary now engages it from the flag, so stdout carries exactly one JSON envelope and the human guidance goes to stderr — rule 3 of `docs/machine-output.md`, which was aspirational until now. A payload that already owns stdout (`status --json --fail-on`) suppresses the envelope, so the "exactly one document" half of the contract holds too.
+- **`--variant` refused selectors the matcher had just learned to find.** 0.44.2 widened `rootAttributeSelector` to consume consecutive `[…]` groups and to stop at a pseudo-class tail, so `:root[data-skin="humanist"][data-theme="dark"]` and `:root[data-theme="light"]:not([data-private])` became blocks FireForge can locate and write through. The CLI validator did not move with it: its own regex still accepted exactly one `[attr]` fragment, so `token add --variant '[data-skin=humanist]:not([data-private])'` was refused as "must be a single attribute selector" — a block the tool can FIND was one it would not let you NAME, and the private-exclusion selectors the widening exists for are precisely that shape. Downstream the values were maintained by hand in the allowlisted block instead.
+  The validator now runs the MATCHER'S parse and requires it to consume the whole fragment, rather than carrying a second grammar that can drift from the first again. Character safety stays a separate check, because that parse finds bracket boundaries and validates no characters at all — it is applied one bracket group at a time rather than as a repeated pattern, which is the shape that backtracks (`js/polynomial-redos`), and a linearity test pins that alongside the matcher's own. Normalization to `="value"` now covers every fragment in a run and the `:not(…)` argument, not just a trailing one.
+  `findVariantBlock` had to move with it: it compared a request against a block's ATTRIBUTE run only, so a variant carrying its own qualifier would have matched nothing and spliced a fresh duplicate block on every add. Request and candidate go through the same parse and are compared tail-to-tail. An UNqualified request still matches a qualified block — that is the 0.44.2 behaviour `variantBlockQualifier` exists to report out loud, since silently skipping the block is the worse failure — but a request that names a qualifier means it.
 - `tree list --json` gained the failure envelope `status --json` already emitted, so a scripted consumer no longer gets a parseable refusal from one and a bare non-zero exit from the other. The contract is written down in `docs/machine-output.md`.
 
 ### More correctness
@@ -141,9 +168,14 @@
 - **`furnace diff` reported every overridden file as a new file.** The engine-relative path it hands `git show <ref>:<path>` came from slicing a native path, and git's `ref:path` form only understands forward slashes — so every baseline read missed and the command showed nothing to diff.
 - **Engine-relative paths were recorded in two spellings at once.** `furnace-apply-helpers.ts` and `furnace-apply-ftl.ts` pushed `relative(engineDir, …)` results — backslashes on Windows — into lists whose sibling entries are POSIX literals, and those lists are identifiers: they go to git, into furnace state, and are compared against the POSIX paths `furnace.json` and `jar.mn` already carry. Normalized at the five producing sites.
 - **`build-audit` collapsed to one path segment**, so the same-basename collision heuristic and the stale/missing classification stopped discriminating; **`removeTree` refused every removal** as an escape from the trees directory, because it compared a `join`ed prefix against a `resolve`d root and only the latter carries a drive letter; and **`initRepository` never pinned `core.autocrlf`**, so on a host with git's Windows default the checkout rewrote LF to CRLF — shifting the blob hashes `hashObjectBatch` delegates to git, and with them the bytes patches are exported from and applied to.
+- **`furnace init` accepted `--ftl-base-path ../escape/path` on Windows.** The traversal guard normalized the value and then tested it for a `../` prefix, but the platform `normalize` emits backslashes there, so `..\escape\path` failed the check and the escape was written into `furnace.json`. The guard normalizes with the POSIX rules regardless of host; the sibling absolute-path and null-byte checks were already separator-agnostic.
+- **`furnace` jsconfig sync did nothing on Windows.** `isManagedEntry` decided whether a `compilerOptions.paths` entry pointed into the components workspace with `target.startsWith(resolve(customDir) + '/')`. The hard-coded `/` never matches what `resolve` produces there, so every Furnace-managed entry was classified as hand-written and preserved verbatim: entries whose helper was deleted were never pruned and entries whose target moved were never updated. Containment now goes through `isPathInsideRoot`, the same `relative`-based check the rest of the codebase uses. The failure was silent in the worst way — a clean `+0 added, ~0 updated, -0 pruned` summary reads as "already in sync".
+- **The `build-audit` segment-splitting defect had a second site.** `pathSegments` was normalized above, but `isConfidentMatch` still split candidates on `/` alone, so the non-generic-segment bonus — the signal that keeps a cross-tree re-root like `branding/<name>/content/aboutDialog.css` → `chrome/<area>/content/branding/aboutDialog.css` classified as `stale` — could never fire on Windows, and real staleness was reported as `missing`.
 
 On the test side: path expectations and mock keys are rendered through a new `nativePath()` test helper rather than hard-coded POSIX literals; fixture repos pin `core.autocrlf=false` / `core.eol=lf`; the three modules that branch on `process.platform` directly now have that branch forced rather than inherited from the runner; and the doctor summary count is derived rather than pinned at 16, since the orphaned-harness check is `skipIf` win32. The genuinely POSIX-only suites — `tree`, `tree exec`, `run --smoke-exit`, and the `chmod`-as-refusal tests — are skipped explicitly, and each skip is paired with a new platform-stubbed test that pins the win32 refusal itself, which nothing did before.
 
+`nativePath()` turned out to be the wrong tool for part of that job, and applying it uniformly produced failures of its own. It swaps separators only, which is correct for a value the code built with `join` but wrong for one it passed through `resolve`: on Windows `resolve` also prefixes the current drive, so the expectation has to be `D:\project\x`, not `\project\x`. A sibling `nativeAbsPath()` covers that case, and the assertions that were wrapped despite never touching a separator at all — pure suffix concatenation, a pass-through argument, and a suite whose `getProjectPaths` mock returns POSIX literals on every platform — go back to comparing the literal. Four doctor summary assertions had also kept their POSIX counts inline while the clean-run count next to them was already derived, so the derivation now covers every summary line in the suite. Two more `chmod`-as-refusal tests joined the skip list: they were skipped for `root` but not for Windows, where mode bits are ignored outright, so the "unreadable" setup was a no-op and the code correctly reported success.
+
 ### Test infrastructure
 
 - **`createLoggerMock()` and `createFsMock()`** in `src/test-utils/module-mocks.ts` replace hand-rolled `vi.mock` factories at 110 sites. `utils/logger.js` was mocked in 118 files by 113 full-replacement factories across 55 distinct key-sets, 34 appearing exactly once; `utils/fs.js` had 89 more. Each enumerated a SUBSET of the real module, so adding one export turned it `undefined` everywhere the factory omitted it — which happened twice while writing this release, 106 files each time.
@@ -151,8 +183,18 @@ On the test side: path expectations and mock keys are rendered through a new `na
 - **`test.test.ts` was 2,943 lines under one `describe`.** What made it unsplittable was its own 190-line `vi.mock` header: any split either duplicated the header into each new file or did not happen. The header moved to `test-command-mocks.ts` as one factory per mocked module, called from inside each file's own `vi.mock` callback — hoisting is unaffected and every suite still gets fresh `vi.fn()`s rather than shared call history. The file is now six, largest 952 lines, split on the seams the tests already formed: discovery and failure rewriting, staleness and packaging coverage, xpcshell/mochitest hints, Marionette forwarding, harness resilience, verdict contract.
   The split exposed a real test-isolation bug: `keeps the Marionette preflight for xpcshell-only --doctor runs` had never set a preflight result, and passed only because an `it` roughly 1,000 lines earlier had left one on the shared mock with `mockResolvedValue`. It sets its own now. Coverage of `src/commands/test.ts` is byte-identical before and after the split (95.12 / 94.28 / 100 / 86.23), which is the check that the mock rewiring did not quietly stop exercising anything.
 - Five rollback tests moved from asserting a module-level spy to asserting the persisted pending-repair marker. The spy stopped working when the sequence moved into `completeJournalRollback` (its call to the recorder is intra-module), and the outcome is the better assertion anyway.
+- **Fourteen verdict assertions passed only because writing to a filesystem root fails.** The command suites pass `/project` as the project root and assert the `FIREFORGE-VERDICT:` line by exact string — which holds only while no run log is open, since the line carries an open log's path as a ` log=<path>` key. On POSIX `mkdir('/project/.fireforge/logs')` fails at the root, the best-effort open degrades to "no log", and the assertions passed for a reason none of them stated. On Windows the same path resolves against the CURRENT DRIVE, the mkdir succeeds, and all fourteen failed — while the run also created real `C:\project\.fireforge\logs` directories on the runner. `createRunLogMock()` joins the two factories in `module-mocks.ts` and the five suites state the precondition instead of inheriting it from a permission error. Because mocking the module away removes the suffix's only coverage, `test-verdict.test.ts` gains the opposite assertion: with a log open, the path rides the line, once, as the run's last stdout write.
+- **A lock-wait test decided its result on a `readdir`.** `a wait whose queue position keeps improving > survives a drain longer than its budget` runs on real timers and a real filesystem, and gave each probe about 20 ms of slack inside a 100 ms budget; it also retired its simulated queue with un-awaited `rm` calls, so a retirement could land after the probe meant to observe it and a release could leave `mkdir` seeing `EEXIST` past the intended free. On a Windows runner the second probe missed the deadline, no extension was ever granted, and the wait expired still three from the head — the exact refusal the test exists to prove does NOT happen. The retirement and release are synchronous now (the callback returns `void` and cannot await), and the constants are scaled to ~100 ms of slack per probe while keeping the two invariants that fix them: the budget must span two probes, and the drain must outlast the budget or the sibling test would acquire instead of expiring. No production change — `withFileLock` checking its deadline before probing is correct, since a wait must not extend itself on a probe taken after it expired.
 - `git-readonly-index.test.ts` carried a latent racy-clean flake: it edited `const b = 2;` to `const b = 3;` — the same byte length, within the same second as the index entry — without invalidating the stat cache, so git could report the file unmodified. Its sibling test already guarded for this.
 
+### Documentation
+
+- **README.md had become the reference manual.** Its "Regular Workflow" section had grown into fourteen paragraphs of flag semantics — scan manifests, shard behaviour, packaging-coverage anchors, tree CoW, shim configuration — read by nobody starting out and found by nobody looking for a specific rule, because prose in a getting-started page has no index. The reference material moves to `docs/`, split by the thing a reader is actually doing: `patch-workflow.md`, `testing.md`, `furnace.md`, `verification-trees.md`, `configuration.md`, plus `docs/README.md` as the index. README keeps installation, the loop's shape, rebasing, Furnace's premise, the roadmap and the licence — the parts that are project statement rather than manual — and links out for the rest.
+- **`docs/run-logs.md`** states the `.fireforge/logs/` contract that previously existed only as a table cell in `machine-output.md`: raw bytes rather than the echo filter's form, opened before any preflight, retained 20 deep per command kind, best-effort throughout, and the tee sitting at the two mach capture funnels rather than at the commands.
+- Two documents had gone stale against the code. `machine-output.md`'s surface table omitted `status --raw`, which engages the same stdout discipline through the same argv check in `cli.ts` — a machine surface to which rules 3 and 4 apply and rules 1 and 2 do not — and omitted `build`'s direct log announcement, which exists precisely because `build` prints no verdict line to carry a `log=` key. `lifecycle-invariants.md` still described `--wait-lock` as the engine-session lock's budget alone, which stopped being true when the budget was threaded into the furnace lock as well; both lock rows now state the resolution order (`lockTimeoutMs` → `FIREFORGE_WAIT_LOCK` → the 30 s default) and which mutators each covers.
+- **The package did not ship the `docs/` tree its own README links to.** The `files` allowlist was `dist/`, `templates/` and the three root markdown files, so `node_modules/@hominis/fireforge/docs` did not exist and all eleven relative `docs/…` links dead-ended for a consumer — against a doctrine that names the INSTALLED package as the authority, precisely so an agent never has to leave its repo to answer a tool question. The links resolved on GitHub and on the registry page, which rewrites them, which is why nothing caught it. `docs/` is now published (~100 KB of markdown against a package that already ships `dist/`), and `wrapper-smoke.test.ts` asserts the tree is both packed and present after install, the way it already did for `templates/` — so a future `files` edit that drops it fails the gate rather than the reader.
+- `FIREFORGE_WAIT_LOCK` and the three other environment variables FireForge reads were documented only in help text and JSDoc. They are tabulated in `configuration.md` with their defaults and their behaviour on a malformed value.
+
 ## 0.43.0
 
 ### Verdict correctness

package/README.md

@@ -55,113 +55,15 @@ After setup you should have a `fireforge.json`, an `engine/` directory containin
 npx fireforge status
 npx fireforge export browser/base/content/browser.js --name custom-toolbar --category ui
 npx fireforge re-export custom-toolbar
-npx fireforge re-export --scan --scan-files generated-assets.json --dry-run
 npx fireforge lint --per-patch
-npx fireforge lint --per-patch --max-warnings 0
 npx fireforge verify
-npm run whitespace:check
 npx fireforge build
 npx fireforge test browser/base/content/test/browser/
 ```
 
-Use `fireforge --help` for the full set of commands.
-
-For large generated asset batches, `re-export --scan --scan-files <manifest>` assigns files to
-their owner patches without broad directory scanning. The manifest is JSON:
-
-```json
-{
-  "assignments": [
-    { "patch": "002-branding-runtime-icons.patch", "files": ["browser/branding/hominis/icon.svg"] }
-  ]
-}
-```
-
-The command is dry-runnable, refuses ambiguous ownership, and reports each file-to-patch
-assignment before refreshing the patch. For release whitespace checks, use
-`npm run whitespace:check`; it still checks source diffs while excluding generated
-`patches/*.patch` diff syntax.
-
-Queue maintenance lives under `fireforge patch`: `patch compact` closes ordinal gaps
-(range-aware when `patchPolicy.ranges` is configured), `patch reorder` moves a patch, and
-`patch split <source> --files <paths...> --name <name>` carves files out of a patch into a
-new one as a single transaction — including staged-dependency owner rewrites — with
-`--dry-run` support. `patch rename` also supports `--category` and `--order`; every
-queue-mutating patch command accepts `--wait-lock [seconds]`.
-
-`fireforge test <directory>` runs exactly that directory: FireForge enumerates the
-directory's test files and passes the explicit file list to mach in one invocation, so
-mach's prefix-based path matching cannot silently sweep in sibling directories sharing the
-name prefix (excluded siblings are echoed with their test-file counts). Multiple path
-arguments run as sequential shards by default — one browser instance per argument, with a
-directory argument keeping its files together — announced with a notice, since isolated
-instances do not exercise cross-argument state (`--no-shard` restores one combined
-invocation). Recognized harness crashes retry up to `--harness-retries <n>` times (default
-2), and `--perf-samples <path>` publishes a perf-sample artifact path to the harness
-(exported as `<BINARYNAME>_PERF_SAMPLE_JSON`).
-Every test run ends with one machine-readable `FIREFORGE-VERDICT: PASS|FAIL ...` line;
-automation should use it instead of the raw process code and treat a missing verdict as
-failure.
-Pathless test runs must choose a mode: `--auto` forwards mach's own auto-selection,
-`--doctor` runs the Marionette preflight only, and `--canary [path]` runs one short
-browser-chrome canary (`test.canaryPath` / `test.canaryTimeoutSeconds` in `fireforge.json`
-provide defaults). When packageable engine files changed since the last successful
-FireForge build, `test` fails before launching stale artifacts; use `--build` to refresh
-or `--allow-stale-build` only for intentional out-of-band rebuilds. `--build-only`
-packages mixed-harness paths once; `--extend-coverage` safely retains prior scoped
-coverage. `--kill-stale-marionette` terminates recognized stale browsers. In dev builds,
-files under `obj-*/dist/bin`
-may be symlinks back into the source tree (notably prefs), so edit source prefs directly
-and keep a backup before bisection experiments.
-
-Patch names are normalized on export/rename: `window-chrome-tests`,
-`ui-window-chrome-tests`, and `235-ui-window-chrome-tests` all resolve to the same
-`<order>-ui-window-chrome-tests.patch` shape. For focused queue checks,
-`lint --per-patch --patches` accepts repeated flags, comma lists, full filenames/stems,
-manifest names, category-prefixed slugs, and bare slugs.
-
-Projects with generated asset prerequisites can declare opt-in `externalToolchains` in
-`fireforge.json`; `fireforge doctor` reports missing required tools as errors and missing
-optional tools as warnings. Seasonal branding on macOS, for example, can declare Apple's
-Icon Composer tool at
-`/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
-plus `actool` via `xcrun`, `sips`, and `iconutil`.
-Design tokens are managed with `fireforge token add`; pass `--create-category` to declare a
-new category banner and insert the token in one step.
-
-For unattended smoke checks, `fireforge run --smoke-exit <s> --headless` launches the
-browser headless — a headed smoke window on a shared desktop absorbs live input, which
-contaminates the console capture (headed non-CI launches print a warning saying so).
-
-Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals shim that
-tracks upstream WebIDL additions per release; a project's `patchLint.checkJsExtraShim` can
-add members to the structured shim globals via TypeScript interface merging (e.g.
-`interface ChromeUtilsShim { newApi(): any }`). Opting into
-`patchLint.checkJsTestFiles: true` extends the pass to patch-owned test `.js` files
-(`browser_*`/`test_*`/`xpcshell_*` and `/test/` paths), each checked as its own small
-script-scope program against a loose built-in harness shim; `patchLint.checkJsTestShim`
-points at a project `.d.ts` whose typed declarations (e.g. a real `TestUtils` interface)
-override the loose baseline so calls to nonexistent harness members fail at export time.
-
-For CI enforcement, `fireforge status --check` exits non-zero when any unmanaged,
-drifted, or conflicted file exists (`--fail-on <class,...>` tunes the policy set, and
-`--json` composes — the JSON stays parseable and its `files[]` entries name the owning
-`patch`). `--include-ownership` adds ownership rows to JSON status output. Scan-less
-`re-export` previews drift; `--refuse-foreign-drift --expect <path>` restricts it to
-intended files. `lint --per-patch --report <path>` writes a machine-readable JSON report with
-each patch's line count, tier, active size thresholds, issues, and lintIgnore-suppressed
-issues; the size metrics (`countNonBinaryDiffLines`, `resolvePatchSizeTier`,
-`getPatchSizeThresholds`) are also exported on the programmatic API.
-
-For concurrent read-mostly verification beside a busy primary checkout,
-`fireforge tree create <name>` snapshots the project — applied engine tree included,
-`obj-*` excluded — into `.fireforge/trees/<name>` using filesystem copy-on-write (APFS
-clonefile / btrfs-XFS reflink; ~3 s for a 156 MB applied browser tree). Read-only commands
-and export/re-export dry runs work inside a tree; mutations are refused. `--with-objdir`
-adds a safely relocated build for build-less tests. `tree list` reports staleness,
-`tree remove` deletes (refusing active locks), and `tree exec <name> -- <cmd>` runs a
-command inside a tree. Filesystems without CoW support refuse unless `--force-copy`
-explicitly accepts a full physical copy.
+Use `fireforge --help` for the full set of commands, and
+[`docs/patch-workflow.md`](docs/patch-workflow.md) for what the loop actually
+guarantees.
 
 ## Rebasing Firefox Source
 
@@ -188,16 +90,22 @@ npx fireforge furnace status
 npx fireforge furnace preview
 ```
 
-Use `fireforge furnace --help` for the full set of component commands.
+Use `fireforge furnace --help` for the full set of component commands, and
+[`docs/furnace.md`](docs/furnace.md) for shared CSS fragments and typed
+cross-module imports.
+
+## Documentation
+
+[`docs/`](docs/README.md) holds the reference material:
 
-Cross-widget CSS can be single-sourced as shared fragments: place the fragment in
-`components/shared/` and reference it from a widget stylesheet with a
-`/* @fireforge-include <fragment>.css */` comment — deploy expands it into the deployed
-copy only, and editing the fragment surfaces as component drift until the next deploy.
-For typed cross-module imports of multi-file components, set
-`furnace.json#typecheckJsconfig` to a consumer-owned jsconfig and deploy will maintain
-`compilerOptions.paths` entries mapping each deployed
-`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
+- [Patch workflow](docs/patch-workflow.md) — export, re-export, queue maintenance, per-patch lint, CI gating
+- [Testing](docs/testing.md) — `fireforge test` scope, modes, build freshness, the verdict line
+- [Furnace](docs/furnace.md) — components, shared CSS fragments, typed imports
+- [Verification trees](docs/verification-trees.md) — CoW snapshots for concurrent verification
+- [Configuration](docs/configuration.md) — `fireforge.json`, design tokens, lock waits, environment variables
+- [Exit codes](docs/exit-codes.md) and [machine-readable output](docs/machine-output.md) — the contract for scripts and CI
+- [Run logs](docs/run-logs.md) — what `test` and `build` leave behind
+- [Lifecycle invariants](docs/lifecycle-invariants.md) — locking, rollback and signal handling internals
 
 ## Roadmap
 

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.1",
-  "commit": "b77a037425f19e19c43a64a5bb1ff79d949af92e",
-  "shortCommit": "b77a037425f1",
+  "version": "0.44.3",
+  "commit": "760172104f6bfe523f63adfe08b8c6e63fd5d1f0",
+  "shortCommit": "760172104f6b",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-27T22:08:53.928Z"
+  "buildTime": "2026-08-28T15:34:58.794Z"
 }

package/dist/src/commands/build.js

@@ -8,6 +8,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineExists } from '../core/engine-precondition.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
+import { closeActiveRunLog, getActiveRunLogPath, openRunLog, setActiveRunLog, } from '../core/run-log.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -170,6 +171,22 @@ export async function buildCommand(projectRoot, options) {
     const buildType = options.ui ? 'UI-only' : 'Full';
     const brandInfo = options.brand ? ` [${options.brand}]` : '';
     intro(`FireForge Build (${buildType}${brandInfo})`);
+    // A build's own complete output, kept independently of whatever the
+    // operator piped the run through. `build` prints no FIREFORGE-VERDICT
+    // line, so the path is announced directly at the end of the run.
+    setActiveRunLog(await openRunLog(projectRoot, 'build'));
+    try {
+        await runBuildCommandBody(projectRoot, options);
+    }
+    finally {
+        const logPath = getActiveRunLogPath();
+        await closeActiveRunLog();
+        if (logPath !== undefined)
+            info(`Full build output: ${logPath}`);
+    }
+}
+async function runBuildCommandBody(projectRoot, options) {
+    const buildType = options.ui ? 'UI-only' : 'Full';
     // Load configuration
     const config = await loadConfig(projectRoot);
     const paths = getProjectPaths(projectRoot);

package/dist/src/commands/furnace/apply.js

@@ -5,7 +5,7 @@ import { applyAllComponents, computeComponentChecksums } from '../../core/furnac
 import { logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths } from '../../core/furnace-config.js';
 import { isComponentSourceFile } from '../../core/furnace-constants.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { getPersistableAppliedEntry, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
@@ -294,7 +294,7 @@ export async function furnaceApplyCommand(projectRoot, name, options = {}) {
             await persistSingleComponentState(projectRoot, getPersistableAppliedEntry('Apply', name, applyResult.applied[0]), getFurnacePaths(projectRoot));
         }
         return applyResult;
-    }, { dryRun });
+    }, { dryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
     if (applySpinner) {
         applySpinner.stop('Components applied');
     }

package/dist/src/commands/furnace/deploy.js

@@ -4,7 +4,7 @@ import { applyAllComponents } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions, } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { getPersistableAppliedEntry, getStepFailureCount, persistSingleComponentState, shouldPersistSingleComponentState, } from '../../core/furnace-state-persist.js';
 import { hasBlockingStepErrors } from '../../core/furnace-step-errors.js';
@@ -177,7 +177,7 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
             operationContext: ctx,
         });
         return { kind: 'result', result: allResult };
-    }, { dryRun: isDryRun });
+    }, { dryRun: isDryRun, ...waitLockMutationOptions(options.waitLockSeconds) });
     if (applyOutcome.kind === 'stock') {
         applySpinner.stop('Apply skipped');
         warn(`"${name}" is a stock component. Stock components are not applied locally.`);

package/dist/src/commands/furnace/index.js

@@ -35,13 +35,17 @@ function registerFurnaceApplyCommand(furnace, context) {
         .option('-w, --watch', 'Watch component directories and re-apply on changes');
     addWaitLockOption(apply).action(withErrorHandling(async (name, options) => {
         const { waitLock, ...rest } = options ?? {};
-        const parsed = pickDefined(rest);
+        // Resolved ONCE and used twice: the engine session lock below, and
+        // the furnace lock the mutation takes inside it. Resolving twice
+        // would be the same value today and a drift risk tomorrow.
+        const waitLockSeconds = resolveWaitLockSeconds(waitLock);
+        const parsed = pickDefined({ ...rest, waitLockSeconds });
         const run = (projectRoot) => furnaceApplyCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace apply', run, resolveWaitLockSeconds(waitLock));
+        await runEngineLockedFurnaceCommand(context, 'furnace apply', run, waitLockSeconds);
     }));
 }
 function registerFurnaceDeployCommand(furnace, context) {
@@ -54,13 +58,14 @@ function registerFurnaceDeployCommand(furnace, context) {
         .option('--skip-validate', 'Skip the validation step (apply only)');
     addWaitLockOption(deploy).action(withErrorHandling(async (name, options) => {
         const { waitLock, ...rest } = options ?? {};
-        const parsed = pickDefined(rest);
+        const waitLockSeconds = resolveWaitLockSeconds(waitLock);
+        const parsed = pickDefined({ ...rest, waitLockSeconds });
         const run = (projectRoot) => furnaceDeployCommand(projectRoot, name, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run, resolveWaitLockSeconds(waitLock));
+        await runEngineLockedFurnaceCommand(context, 'furnace deploy', run, waitLockSeconds);
     }));
 }
 function registerFurnaceSyncCommand(furnace, context) {
@@ -72,13 +77,14 @@ function registerFurnaceSyncCommand(furnace, context) {
         .addOption(new Option('-s, --strategy <strategy>', 'Auto-resolve merge conflicts (ours = keep local, theirs = accept upstream)').choices(['ours', 'theirs']));
     addWaitLockOption(sync).action(withErrorHandling(async (options) => {
         const { waitLock, ...rest } = options;
-        const parsed = pickDefined(rest);
+        const waitLockSeconds = resolveWaitLockSeconds(waitLock);
+        const parsed = pickDefined({ ...rest, waitLockSeconds });
         const run = (projectRoot) => furnaceSyncCommand(projectRoot, parsed);
         if (parsed.dryRun === true) {
             await run(getProjectRoot());
             return;
         }
-        await runEngineLockedFurnaceCommand(context, 'furnace sync', run, resolveWaitLockSeconds(waitLock));
+        await runEngineLockedFurnaceCommand(context, 'furnace sync', run, waitLockSeconds);
     }));
 }
 /**

package/dist/src/commands/furnace/init.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { stat } from 'node:fs/promises';
-import { basename, dirname, isAbsolute, join, normalize } from 'node:path';
+import { basename, dirname, isAbsolute, join, posix } from 'node:path';
 import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
 import { stdioIsInteractive } from '../../core/destructive.js';
@@ -61,7 +61,10 @@ async function validateFtlBasePath(value, engineDir) {
     if (isAbsolute(value) || /^[a-zA-Z]:[\\/]/.test(value)) {
         throw new FurnaceError(`ftlBasePath "${value}" must be a relative path inside the engine checkout, not absolute.`);
     }
-    const normalized = normalize(value.replace(/\\/g, '/'));
+    // Normalize with the POSIX rules regardless of host: `normalize` on Windows
+    // emits backslashes, so a `../`-prefix test against the platform `normalize`
+    // silently passes every traversal attempt there.
+    const normalized = posix.normalize(value.replace(/\\/g, '/'));
     if (normalized === '..' || normalized.startsWith('../')) {
         throw new FurnaceError(`ftlBasePath "${value}" must not escape the engine checkout via parent-directory segments.`);
     }

package/dist/src/commands/furnace/sync.js

@@ -6,7 +6,7 @@ import { applyAllComponents } from '../../core/furnace-apply.js';
 import { logApplyResult } from '../../core/furnace-apply-output.js';
 import { getFurnacePaths, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { reportJsconfigPathsSync } from '../../core/furnace-jsconfig.js';
-import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { runFurnaceMutation, waitLockMutationOptions } from '../../core/furnace-operation.js';
 import { assertFurnaceReady } from '../../core/furnace-precondition.js';
 import { countEntriesWithBlockingStepErrors } from '../../core/furnace-step-errors.js';
 import { containsMergeConflictMarkers } from '../../core/furnace-validate-structure.js';
@@ -127,7 +127,7 @@ export async function furnaceSyncCommand(projectRoot, options = {}) {
     if (!options.dryRun) {
         info('\nApplying all components to engine...');
         const applySpinner = spinner('Applying components...');
-        const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }), { dryRun: false });
+        const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }), { dryRun: false, ...waitLockMutationOptions(options.waitLockSeconds) });
         applySpinner.stop('Components applied');
         logApplyResult(result, false);
         const appliedWithStepErrorsCount = countEntriesWithBlockingStepErrors(result.applied);

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

@@ -4,6 +4,7 @@ import { getProjectPaths } from '../core/config.js';
 import { appendHistory, confirmDestructive, } from '../core/destructive.js';
 import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 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';
@@ -88,7 +89,7 @@ function buildFilesModeMetadataUpdates(actualProjectedFiles, options, effectiveL
     return updates;
 }
 async function confirmFilesModeProjection(args) {
-    const { target, retained, removed, added, actualProjectedFiles, missingFiles, options, conflicts, } = args;
+    const { target, retained, removed, added, actualProjectedFiles, deletedFiles, options, conflicts, } = args;
     const isDryRun = options.dryRun === true;
     const summary = [
         `re-export ${target.filename} with --files scope`,
@@ -102,8 +103,8 @@ async function confirmFilesModeProjection(args) {
     if (added.length > 0) {
         summary.push(`newly included files (${added.length}): ${added.join(', ')}`);
     }
-    if (missingFiles.length > 0) {
-        summary.push(`missing on disk (will be dropped): ${missingFiles.join(', ')}`);
+    if (deletedFiles.length > 0) {
+        summary.push(`deleted on disk (captured as deletions the patch will replay): ${deletedFiles.join(', ')}`);
     }
     if (!isDryRun && removed.length > 0 && options.allowShrink !== true) {
         warn(`Refusing to shrink ${target.filename} without --allow-shrink.`);
@@ -118,12 +119,60 @@ async function confirmFilesModeProjection(args) {
         operation: 're-export-files',
         title: `Re-export ${target.filename} with --files`,
         summary,
-        yes: removed.length === 0 && missingFiles.length === 0 ? true : options.yes === true,
+        // A captured deletion still needs the confirmation: the patch will now
+        // REMOVE those files wherever it is applied, which is the same class of
+        // consequence as shrinking the scope.
+        yes: removed.length === 0 && deletedFiles.length === 0 ? true : options.yes === true,
         dryRun: isDryRun,
         unsafeOverride: options.forceUnsafe === true,
         conflicts,
     });
 }
+/**
+ * Splits the requested paths into what can be diffed and what is a deletion.
+ *
+ * A path absent from disk is one of two very different things, and
+ * collapsing them is what made a DELETION impossible to capture.
+ *
+ * Tracked in HEAD: a deletion. `git diff HEAD -- <path>` renders it as a
+ * proper `deleted file mode` section, so it STAYS in the diff scope. (The
+ * comment this replaces claimed the diff "would fail" on any missing path —
+ * true only for the never-tracked case.) Dropping these produced the
+ * dangerous shape: a re-export that reported success while writing a patch
+ * whose own file list claimed a path it did not restore, so a fresh clone
+ * would apply it and resurrect exactly what the change meant to remove.
+ *
+ * Never tracked in HEAD: nothing on disk and nothing to diff against, so
+ * there is no hunk to be had. Refused rather than warned about, because the
+ * patch cannot express it either way.
+ *
+ * @param requested - The `--files` scope
+ * @param engineDir - Absolute path to the engine checkout
+ * @param patchFilename - Target patch, for the refusal message
+ * @returns The diffable scope and the subset captured as deletions
+ */
+async function classifyRequestedPaths(requested, engineDir, patchFilename) {
+    const absentFiles = [];
+    for (const file of requested) {
+        if (!(await pathExists(join(engineDir, file)))) {
+            absentFiles.push(file);
+        }
+    }
+    const trackedAbsent = await listTrackedInHead(engineDir, absentFiles);
+    const untrackedAbsent = absentFiles.filter((f) => !trackedAbsent.has(f));
+    const deletedFiles = absentFiles.filter((f) => trackedAbsent.has(f));
+    if (untrackedAbsent.length > 0) {
+        throw new InvalidArgumentError(`Refusing to re-export ${patchFilename} with --files because ${untrackedAbsent.length} requested path${untrackedAbsent.length === 1 ? ' is' : 's are'} ` +
+            `neither on disk nor tracked in engine HEAD (${untrackedAbsent.join(', ')}). ` +
+            'There is no content to diff and no deletion to record, so the patch could not ' +
+            'honour the file list it would claim. Remove those paths from --files.', '--files');
+    }
+    for (const file of deletedFiles) {
+        info(`${patchFilename}: capturing deletion of ${file}`);
+    }
+    const untrackedSet = new Set(untrackedAbsent);
+    return { diffableFiles: requested.filter((f) => !untrackedSet.has(f)), deletedFiles };
+}
 /**
  * Handles `re-export --files` end-to-end: computes the projected diff, runs
  * the per-patch and cross-patch lint against a context in which the target
@@ -152,22 +201,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     const removed = target.filesAffected.filter((f) => !requested.includes(f));
     const added = requested.filter((f) => !target.filesAffected.includes(f));
     const retained = target.filesAffected.filter((f) => requested.includes(f));
-    // Filter out paths that no longer exist on disk; we cannot include
-    // them in the new diff because getDiffForFilesAgainstHead would fail.
-    // Missing files are still dropped from the manifest so the resulting
-    // filesAffected reflects reality.
-    const missingFiles = [];
-    for (const file of requested) {
-        const filePath = join(paths.engine, file);
-        if (!(await pathExists(filePath))) {
-            missingFiles.push(file);
-        }
-    }
-    const missingSet = new Set(missingFiles);
-    const diffableFiles = requested.filter((f) => !missingSet.has(f));
-    for (const file of missingFiles) {
-        warn(`${target.filename}: requested file is missing on disk and will be dropped: ${file}`);
-    }
+    const { diffableFiles, deletedFiles } = await classifyRequestedPaths(requested, paths.engine, target.filename);
     // Compute the projected diff up front. This is the same diff the real
     // write would produce, so we get an exact preview through the lint
     // gate and avoid computing it twice.
@@ -179,7 +213,13 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
     }
     const actualProjectedFiles = extractAffectedFiles(projectedDiff);
     const actualProjectedSet = new Set(actualProjectedFiles);
-    const noDiffFiles = diffableFiles.filter((file) => !actualProjectedSet.has(file));
+    // Domain is the FULL requested list, not the diffable subset. When the
+    // subset was used, any path filtered out upstream was invisible to this
+    // check by construction — which is exactly how a dropped deletion slipped
+    // through while the run reported success. A patch that does not do what
+    // its own file list claims is the one property a manifest must never get
+    // wrong, so an explicitly named path that produced no hunk is a refusal.
+    const noDiffFiles = requested.filter((file) => !actualProjectedSet.has(file));
     if (noDiffFiles.length > 0) {
         throw new InvalidArgumentError(`Refusing to re-export ${target.filename} with --files because ${noDiffFiles.length} requested path${noDiffFiles.length === 1 ? '' : 's'} produced no diff hunks (${noDiffFiles.join(', ')}). ` +
             'Keeping them in filesAffected would desync patches.json from the patch body. ' +
@@ -216,7 +256,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         removed,
         added,
         actualProjectedFiles,
-        missingFiles,
+        deletedFiles,
         options,
         conflicts,
     });
@@ -243,7 +283,7 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
                 filename: target.filename,
                 files: actualProjectedFiles,
                 previousFiles: target.filesAffected,
-                missingFilesDropped: missingFiles,
+                deletionsCaptured: deletedFiles,
             },
             ...(options.yes === true ? { yes: true } : {}),
             ...(options.forceUnsafe === true ? { unsafeOverride: true } : {}),