@hominis/fireforge 0.36.0 → 0.38.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.38.0
+
+- **`status --ownership` reports a furnace-deployed file whose owning patch body went stale as drift** (friction-log item 1, bug — after `furnace deploy` refreshed 12 deployed widget copies, the pre-export "consult ownership" step read clean while the composed gate caught the staleness later on the re-export path): the classifier no longer short-circuits every furnace-prefixed path into the `furnace` bucket — a furnace path claimed by exactly ONE patch now runs the same expected-content comparison as any patch-owned file (`computePatchedContent` vs the deployed copy, deletion and error branches included), classifying as `patch-owned-drift` on divergence and staying `furnace` on a match. Multi-owner and unowned furnace paths keep the old bucket (cross-patch conflicts are already surfaced independently), so the only behavioral change is that stale widget patches now show as drift in the table and in `--json` (machine consumers see those paths move from `"furnace"` to `"patch-owned-drift"`). An integration test pins the exact observed sequence: deploy, export the patch, edit the component source, deploy again, and `status --ownership` reports the owning patch drifted.
+- **Scoped `test --build` and build-less runs refuse a `components.conf` changed since the last FULL build** (friction-log item 2, bug — a new about: module packaged fine under a scoped `test --build` but the child process resolved `NS_ERROR_MALFORMED_URI`, because `components.conf` entries bake into the compiled StaticComponents table that only a full build regenerates; the failure was silent and read as a test bug): the baseline gains `staticComponentsBaseline` (`engineHeadSha` + per-manifest content fingerprints), written fresh only by full-coverage builds and carried forward verbatim through scoped `test --build` writes — so the guard always anchors to the last full build, not the last scoped one. Any scoped `test --build` or non-`--build` run over a changed `components.conf` is refused up front with a message naming the manifest(s), explaining the compiled-table mechanism and the misleading error shape, and advising `fireforge build`; `--allow-stale-build` deliberately does NOT bypass it (it accepts stale packaged content, not a stale compiled registration), while the new `--allow-stale-components` downgrades the refusal to a warning for out-of-band rebuilds. Detection keys on the `components.conf` basename (`isXpcomManifestPath` is the single documented extension point; parsing `moz.build` `XPCOM_MANIFESTS` wiring is out of scope), pre-0.38.0 baselines lack the anchor and degrade to fresh, and probe failures never block a run.
+- **Per-patch size lint agrees with `wc -l` and fires only ABOVE the soft limit** (friction-log item 3, lint bug — three independent recurrences: a file counted one line more than `wc -l` from patch-hunk trailing-newline accounting, and `file-too-large` fired at "750 lines (soft limit: 750)" while a wc-1499 patch reported 1500/1500, each costing 1–2 trim/re-export/lint cycles): line counting now drops the phantom element a trailing newline adds (`countContentLines` for on-disk content, the same correction inside `countNonBinaryDiffLines` for patch bodies, with binary-hunk subtraction kept consistent), and every tier of `file-too-large` and `large-patch-lines` compares strictly (`>`), matching the already-strict `large-patch-files`, so a file or patch sitting exactly AT a notice/soft/hard limit is clean. Boundary tests pin limit−1 / limit / limit+1 for both rules across the general, test, and branding tiers, plus the trailing-newline agreement cases.
+- **Patch-lint accepts both established upstream MPL header wraps** (friction-log item 4, lint — derived files keeping the genuine upstream header of files like `ext-browser.js`, which wrap after "file," instead of the canonical break after "this", were flagged `missing EUPL-1.2 license header`): the upstream-MPL acceptance in `hasAnyLicenseHeader`/`hasUpstreamMplBlockHeader` keeps its exact-prefix fast path and adds a whitespace-normalized fallback — the leading comment span (line-comment run, first block comment, or hash run; anything else never matches) is collapsed to single spaces and must still begin with the full canonical MPL sentence including the URL — so any line-break position within the verbatim text passes while altered wording still fails. Both wraps are tested on JS and CSS comment styles, with and without leading editor directives.
+- **The packaged-test coverage guard accepts same-manifest siblings instead of demanding the exact recorded path set** (friction-log item 5, test inefficiency — a run scoped to `…/hominis-webext/file_A.js` refused `file_B.js` of the SAME manifest, forcing a ~1–2 min repackage per alternation): coverage is now matched at manifest granularity — mozbuild manifests are per-directory and mach stages support-files per manifest, so a request whose manifest granule (a file's containing directory; a directory itself) equals a covered entry's granule is accepted, as are subset paths of a covered directory; genuinely uncovered manifests keep the existing refusal verbatim, and the recorded baseline format is unchanged so 0.37.0 and 0.38.0 baselines interoperate both ways. The entry's second suggestion — unioning covered sets across successive scoped builds to stop concurrent-session ping-pong — was evaluated and rejected as UNSOUND: every baseline write refreshes content fingerprints for ALL dirty packageable paths, so a union would whitewash an earlier scope's edited fixtures while `obj-*/_tests/` still holds that scope's stale staging — precisely the silent-hang class the guard exists to refuse. The verdict is recorded on `testPackagingCoverage`'s doc contract; coverage REPLACES.
+- **Positional inserts refuse with ONE actionable error when they would renumber a reserved range, `patch move-files --create --order <n>` bootstraps a split in one step, and `re-export --scan` refuses forward-import adoptions** (friction-log item 6, patch-tooling ergonomics, three parts): (a) `patch split --before` / positional `export` on a dense queue that would shift patches through a `patchPolicy.reservedRanges` block no longer sprays per-patch reserved-range findings — the placement plan is gated up front (`assertPlacementAvoidsReservedRanges`, subsuming the old inside-range check) with a single error naming the range and computing the remedy: `pass --order <first free number below the reserved block>`, or explicit guidance when no free order exists. (b) `patch move-files` gains `--create --order <n>`: creating the target patch and moving the files is one transaction through the split pipeline (same placement gate, projected cross-patch lint, and staged-dependency owner repointing the manual shrink-then-export dance needed by hand), while the flag-less preview behavior is unchanged. (c) `re-export --scan`/`--scan-file`/`--scan-files` run the forward-import check per adoption candidate BEFORE adopting: a candidate importing a module created by a LATER patch is refused with the later patch and closest legal ordinal named, advising `export --order` / `patch split --order` / `patch staged-dependency --add`; declared staged dependencies and lint-ignores are honored because the gate runs the real cross-patch rule on a projected queue.
+- **Engine-mutating commands can wait for the engine lock instead of failing fast** (friction-log item 7, missing-feature — two sessions on one engine tree had operators hand-rolling `for i in $(seq 1 60); do CMD; sleep 25; done` around "Another FireForge engine-mutating command is already running"): `test`, `build`, `export`, `re-export`, and the engine-locked furnace subcommands gain `--wait-lock [seconds]` (bare flag = 60, validated 1–3600), which polls the lock with exponential backoff (100 ms doubling to a 2 s cap) up to the bound, printing a progress line about every 5 s identifying the holder from the lock's owner metadata (`Waiting for the FireForge engine lock held by PID … (command=…, started=…) — 10s of up to 60s.`), then proceeds when the lock frees or fails with the unchanged standard message. Without the flag, behavior is byte-identical to the 1 s fail-fast; the lock-ownership invariants and their doc (`docs/lifecycle-invariants.md`) are updated to cover the bounded wait.
+- **`furnace validate` credits the implicit wrapping `<label>` association** (friction-log item 8, false positive — `[unlabelled-form-input]` fired on the accessible `<label><input type="radio">…</label>` pattern although the control has an accessible name per the HTML spec): an input/select/textarea nested inside a `<label>` whose content includes real text (tags stripped; a `${…}` binding deliberately counts as text since it is legitimate dynamic label content) is now treated as labelled; a bare input, or one wrapped in an empty or tags-only `<label>`, still warns, and the explicit `for`/`aria-label`/`aria-labelledby` paths are unchanged.
+- **`furnace create --shared-ftl <path>` was already shipped; its validation is now pinned by tests** (friction-log item 9, missing-feature — verified already implemented on current main: the flag sets `sharedFtl` in furnace.json, skips the component-local FTL scaffold, emits the `insertFTLIfNeeded` line for the given path verbatim, and rejects the contradictory `--no-localized` combination): 0.38.0 adds the previously missing direct unit tests for `validateSharedFtl` (trimming, empty/non-string rejection, unsafe-character rejection, localized requirement) and a command-level test pinning the exact CLI rejection wording.
+- **`source set --candidate <buildN>` fetches release-candidate archives** (friction-log item 10, missing-feature — `resolveArchive` hardcoded `pub/firefox/releases/`, so a `candidates/<version>-candidates/buildN/` source, the normal shape for pre-release verification, forced hand-seeding `.fireforge/cache/` with an independently verified tarball + sidecar): `firefox.candidate` (validated `buildN`, also settable via `fireforge config firefox.candidate` and cleared with `--clear-candidate`) switches resolution to `pub/<product>/candidates/<version>-candidates/<buildN>/source/…` with the matching `SHA256SUMS` alongside the build directory; devedition and ESR fall out of the existing product/version handling, cache filenames gain a `-<buildN>` suffix so candidate artifacts never collide with release artifacts, and the sha256-pin trust model is unchanged (an explicit `firefox.sha256` pin still fails closed and takes precedence over the published checksums). Recording the candidate in exported patches' source provenance was considered and deferred — it cascades into `PatchMetadata` schema/validation churn across the manifest round-trip surface.
+
+## 0.37.0
+
+- **`fireforge test --build` now records the stale-build baseline** (friction-log item 1, inefficiency — "stale-build guard re-arms across invocation shapes"): a green pre-test build refreshes `.fireforge/last-build.json` through the same `writeBuildBaseline` path as `fireforge build`/`build --ui`, so after one `test --build` over a set of edited files, a subsequent plain `fireforge test` over the same files — per-file, per-directory, or full suite — passes the gate without a second redundant `--build` round trip. The baseline is content-fingerprint-based and project-scoped, which is also per-obj-dir (multi-objdir checkouts are already refused up front), so no per-invocation-shape keying is needed; both directions (file-scoped rebuild → full-suite run, and full/directory rebuild → file run) are covered by tests.
+- **The stale-build gate no longer refuses a plain `test` right after a green `test --build`** (friction-log item 2, bug — "test --build must update last-build.json"): this was the same defect — `runPreTestBuild` ran the identical protected `mach build faster` as `build --ui` but never wrote the baseline, so the immediately following plain `fireforge test` was refused listing the very files the embedded build had just rebuilt (workaround was a redundant ~1-min `fireforge build --ui`). The write happens only on build exit 0, mirrors `fireforge build`'s ordering and failure tolerance exactly, and a failed pre-test build keeps the prior baseline.
+- **Every non-`--build` test run now tracks packaged-runtime COVERAGE, not just tree state** (friction-log item 3, gotcha — file-scoped `--build` + `--allow-stale-build` over other manifests hangs on unpackaged fixtures): the baseline gains `testPackagingCoverage` (`'full'` from `fireforge build`/`build --ui`/path-less `test --build`; the normalized requested paths from a scoped `test --build`). Any non-`--build` run whose requested paths fall outside the recorded coverage is refused up front — with or without `--allow-stale-build` (the flag only accepts stale CONTENT; missing coverage is a hang risk either way), and regardless of whether the tree is stale, since the hang reproduces with an unchanged tree — with a message naming the uncovered manifests, the recorded coverage, and both remediations (`test --build <paths>` or `fireforge build`); a covered re-run still proceeds, with the usual stale warning under the flag. A path-less `test --doctor` is exempt from the coverage gate — it stops at the Marionette health check and dispatches no test, so it needs no packaging coverage (the stale-content refusal still applies to it, and `--doctor` combined with test paths is checked like any other run). Baselines written before 0.37.0 lack the field and are treated as full coverage, so existing flows are unchanged.
+- **`export`/`re-export` refuse to capture a stale furnace deploy** (friction-log item 4, inefficiency — re-export after editing `components/custom/` without `furnace deploy` exports the old deployed copy): when a patch's exported files fall under a furnace component's deployed prefix (custom `targetPath` / override `basePath`, plus a localized component's exact deployed `<ftlDir>/<name>.ftl` in the shared FTL directory; `sharedFtl` bundles are not furnace-deployed and stay unattributed by design) and that component's `components/` source has changed since the last `furnace apply`/`deploy` (checksum comparison against `appliedChecksums` — mtime is deliberately not trusted), the export is refused with a message naming the component and suggesting `fireforge furnace deploy` first; the new `--allow-stale-furnace` flag on both commands downgrades the refusal to a warning. A deploy-then-re-export sequence is untouched, and a broken/absent furnace setup never blocks non-furnace patch work.
+- **`stagedDependencies` gains a registration-kind entry shape** (friction-log item 5, missing-feature — jar.mn packaging lines flagged `staged-dependency-unused`): `PatchStagedDependencies.registrations` entries (`{file, line, creates, owner?, reason?}`) declare a packaging/registration LINE — a jar.mn entry, a customElements registration, an actor registration — that references a later-created file. Lint validates them by matching the declared line (whitespace-trimmed) against the patch's added content in the declaring file instead of looking for an import specifier — and, mirroring forward-import validation, by requiring `creates` to resolve to a file a later-ordered patch actually creates and `owner`, when set, to name that patch (each failure kind gets its own message) — so mid-queue buildability facts for registration files (e.g. patch 200's jar.mn line packaging `hominis-history-ui.js` owned by patch 248) are machine-recordable: a matching entry lints clean, an import-kind entry still requires a real import, and a registration entry whose line is absent still flags `staged-dependency-unused`. CLI: `fireforge patch staged-dependency --add/--remove --kind registration --file … --line … --creates …`; owner-rename rewriting covers the new array.
+- **`furnace validate` accepts `kind: "library"` components** (friction-log item 6, missing-feature — define-less base-class modules failed `no-custom-element-define`): a custom component manifest may declare `kind: "library"` (base class + helpers, no element of its own — e.g. a shared `moz-hominis-shared` module), which skips the `no-custom-element-define` / `not-moz-lit-element` compatibility errors and the `missing-css` structural advisory while keeping headers, module shape, `relative-import`, FTL rules, and the CSS compatibility rules when a stylesheet exists. `kind: "library"` requires `register: false` (rejected at config parse otherwise); a default-kind component without a define still errors, so the inert-element workaround can be retired.
+- **The failure summary echoes the failing TEST-UNEXPECTED lines with their assertion text** (friction-log item 7, papercut — "First real test failure: Unexpected results: 1" was undiagnosable after the fact): `test-failures` verdicts now carry the first 5 `TEST-UNEXPECTED-*` lines verbatim, each with its trailing assertion/diff context (`Got …`/`Expected …`/Assert message/stack head), echoed under the `First real test failure:` headline in single runs and prepended to shard diagnoses; more than 5 append a `…(+N more)` note, and the shutdown-reentry artifact is excluded. A one-off chrome-suite failure that does not reproduce is now diagnosable from the summary block alone.
+- **The known mozsystemmonitor teardown traceback is collapsed to one labeled line in the output tail** (friction-log item 8, bug/upstream — every headless run ended with the raw `AttributeError: 'SystemResourceMonitor' object has no attribute 'stop_time'` traceback sitting where the summary is read): the test dispatchers now route their terminal echo through a line-buffered filter that recognizes the exact documented signature — an `AttributeError` naming `stop_time` or `poll_interval` on `SystemResourceMonitor` AND a `mozsystemmonitor/resourcemonitor.py` frame AND a previously-seen `SUITE_END` shutdown marker (the flag is shared across the run's stdout/stderr filter pair, since the marker and the traceback usually land on different streams), including the chained-exception pair — and replaces the block with `[FireForge] Known upstream mozsystemmonitor teardown noise … — not a test failure`. Unrecognized tracebacks always print in full, the captured output stays raw for the 0.36.0 classifier (real-failure precedence and green-summary override are untouched), and oversized or truncated blocks flush verbatim rather than being withheld.
+- **Mach dispatches reap their whole process GROUP, and `doctor` detects pre-existing orphaned harness workers** (friction-log item 9, severe — a mach that died at harness startup stranded a Python `multiprocessing` spawn worker that busy-spun at 100% CPU for ~26 days): (a) every mach-wrapping dispatch (test suites, protected builds, bootstrap, watch, package, run) now spawns mach as a POSIX process-group leader, forwards parent SIGINT/SIGTERM to the group (with the existing grace→SIGKILL escalation), group-kills on abort, and sweeps the group after every exit — survivors are named (multiprocessing workers highlighted), group-SIGTERMed, and SIGKILLed after a 2s grace, so a startup death leaves zero surviving multiprocessing children; a healthy run costs one `pgrep`. Windows stays best-effort tree-kill via `taskkill /T /F`. (b) A new `doctor` check ("Orphaned harness workers") scans `ps` for the detection recipe that found the incident — PPID 1 + ≥10 min accumulated CPU time + a `multiprocessing.spawn`/`forkserver`/`resource_tracker` command line, parsing both linux `dd-hh:mm:ss` and darwin `mm:ss.cc` TIME dialects — and reports each match with its PID, CPU time, command line, and a `kill <pid>` suggestion; report-only by design (FireForge never kills pre-existing processes), warning severity so it cannot fail doctor, skipped on Windows.
+- **Follow-up findings** (pre-release review of the items above; the behavioral corrections are folded into their bullets): the packaging-coverage refusal now guards EVERY non-`--build` run, not just `--allow-stale-build` ones, with a path-less `test --doctor` exempted since it dispatches no test (item 3 — a plain run over an unchanged tree after a scoped `test --build` sailed through the gate into the very fixture hang the feature targets, while the widened gate would otherwise have refused a doctor-only Marionette probe as an uncovered full-suite request); the stale-furnace export gate attributes a localized component's deployed `<ftlDir>/<name>.ftl` (item 4 — exporting only the deployed FTL file never probed its component source); registration-kind staged dependencies validate `creates`/`owner`/ordering like the import kind (item 5 — metadata naming a nonexistent file or wrong owner linted clean); the teardown-noise echo filter is narrowed to the exact `stop_time`/`poll_interval` signature with a resourcemonitor.py frame after a seen `SUITE_END` (item 8 — it previously collapsed ANY traceback mentioning resourcemonitor.py, hiding novel upstream defects from live output); and the process-group reaper's grace timer is no longer `unref()`'d (item 9a — the timer was awaited from a child `close` handler after the signal forwarder was disposed, so Node could exit mid-grace and skip the SIGKILL escalation; a regression test pins the timer's ref-ness).
+
 ## 0.36.0
 
 - **Review-findings remediation for the 0.36.0 release gate**: `fireforge test` no longer has a pathless dead-end — no-path runs now require `--auto`, `--doctor`, or `--canary`, `--auto` forwards mach's own selection mode, stale packaged-engine drift fails fast unless `--build` or `--allow-stale-build` is used, `--kill-stale-marionette` can terminate a recognized stale browser listener, and `--canary [path]` / `test.canaryPath` provides a short green/hang/crash harness probe. Harness verdicts now let real failure lines (`FAIL`, `TEST-UNEXPECTED-*`, nonzero unexpected summaries, assertions) beat resource-monitor traceback classification, while still noting the traceback as secondary noise. Patch naming is normalized consistently for `export --name` and `patch rename --to` (bare, category-prefixed, and full stems converge), and `lint --per-patch --patches` accepts repeated flags, comma lists, filenames, stems, manifest names, category-prefixed slugs, and bare slugs. Furnace-managed jsconfig edits are JSONC-preserving via `jsonc-parser`, the Firefox globals shim now includes JSWindowActor bases and `ChromeUtils.registerWindowActor`, `doctor` can validate opt-in `externalToolchains`, and CLI engine-mutating commands take a `.fireforge/engine-session.lock` plus test-run tree-generation checks to catch concurrent engine mutation.

package/README.md

@@ -4,7 +4,7 @@
 [![license](https://img.shields.io/npm/l/@hominis/fireforge)](LICENSE.md)
 [![node](https://img.shields.io/node/v/@hominis/fireforge)](package.json)
 
-FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, lets you export changes as patches, helps apply them and has some neat/mad code quality enforcement, built by taking a lot of learnings from the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.
+FireForge is a CLI tool for maintaining Firefox-based browser forks. It downloads Firefoxs source code, lets you export changes as patches, helps apply them and has some neat/mad code quality enforcement, built by taking a lot of learnings from the existing Firefox source code and trying to make the process as robust as can be. Ideally, FireForge makes everything from managing custom UI components to enforcing some rudimentary typechecking much easier, but I'll be honest, there is only so much one can do, so understanding upstream is advised, especially once future updates come into the mix. ~~I cannot guarantee how reliably these will apply, but I did try to assist in that process as much as I can by learning from prior Firefox versions which had major changes made to them, though this is of course still no guarantee for future success or that the methods will remain reliable. Beware of that.~~ Edit 16.07.2026: I have now upgraded and downgraded and sidegraded, really all the graded, across all the versions in many scenarios with modifications so far removed from upstream that I think it's fair to say upgrading is fairly reliable.
 
 Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 

package/dist/src/commands/build.js

@@ -14,7 +14,7 @@ import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
 import { checkDiskSpace, pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { pickDefined } from '../utils/options.js';
+import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../utils/options.js';
 import { isPositiveInteger } from '../utils/validation.js';
 function parseJobCount(value) {
     const parsed = Number(value);
@@ -327,7 +327,7 @@ export async function buildCommand(projectRoot, options) {
     // against this build's HEAD. A failed build keeps the prior baseline so
     // the next attempt still catches long-standing packaging drops.
     try {
-        await writeBuildBaseline(projectRoot, paths.engine, config.binaryName);
+        await writeBuildBaseline(projectRoot, paths.engine, config.binaryName, 'full');
     }
     catch (baselineError) {
         verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
@@ -336,7 +336,7 @@ export async function buildCommand(projectRoot, options) {
 }
 /** Registers the build command on the CLI program. */
 export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const build = program
         .command('build')
         .description('Build the browser (auto-applies Furnace components first)')
         .option('--ui', 'Fast UI-only rebuild')
@@ -360,9 +360,9 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
         'and runs mach configure — preserving up to ~20 GB of obj-* artefacts on',
         'a relocation. The rewriter refuses any change that is not a pure prefix',
         'move, in which case a clean rebuild is still required.',
-    ].join('\n'))
-        .action(withErrorHandling(async (options) => {
+    ].join('\n'));
+    addWaitLockOption(build).action(withErrorHandling(async (options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)));
+        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }

package/dist/src/commands/config.js

@@ -35,6 +35,7 @@ const STRING_TYPED_KEYS = new Set([
     'firefox.version',
     'firefox.product',
     'firefox.sha256',
+    'firefox.candidate',
     'license',
     'wire.subscriptDir',
 ]);

package/dist/src/commands/doctor-orphaned-harness.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
+ * item 9b).
+ *
+ * Field incident: a mach invocation that died at harness startup stranded a
+ * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
+ * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
+ * days (~415 CPU-hours) undetected. The dispatch-side fix is the
+ * process-group reaping in `utils/process.ts`; this check covers orphans
+ * that predate it (or leaked from non-FireForge invocations), using the
+ * detection recipe that found the incident process: PPID 1 + large
+ * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
+ * command line.
+ *
+ * Report-only by design: FireForge never kills pre-existing processes it
+ * did not spawn — the check names each candidate and suggests the kill.
+ *
+ * Canary integration was deliberately skipped: the friction log asked for
+ * doctor AND/OR `test --canary`, and adding a system-wide process scan to
+ * the canary hot path buys no extra coverage over the doctor check.
+ */
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/** One process matching the orphaned-harness-worker shape. */
+export interface OrphanedHarnessWorker {
+    pid: number;
+    ppid: number;
+    /** Raw TIME column as `ps` printed it. */
+    cpuTime: string;
+    /** Parsed accumulated CPU seconds. */
+    cpuSeconds: number;
+    command: string;
+}
+/**
+ * Parses a `ps` TIME value in either dialect:
+ *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
+ *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
+ * Returns NaN for unrecognized shapes.
+ */
+export declare function parseCpuTime(time: string): number;
+/**
+ * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
+ * workers: PPID 1 (reparented to init/launchd), a multiprocessing
+ * worker/tracker command line, and at least `minCpuSeconds` of accumulated
+ * CPU time. Pure — fixture-testable without spawning anything.
+ */
+export declare function findOrphanedHarnessWorkers(psOutput: string, minCpuSeconds?: number): OrphanedHarnessWorker[];
+/**
+ * Doctor check reporting orphaned harness workers. Windows has no `ps`;
+ * the check is skipped there (best-effort platform gap, matching the
+ * process-group reaper's POSIX-only sweep).
+ */
+export declare const ORPHANED_HARNESS_DOCTOR_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-orphaned-harness.js

@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Doctor check for PRE-EXISTING orphaned test-harness workers (0.37.0
+ * item 9b).
+ *
+ * Field incident: a mach invocation that died at harness startup stranded a
+ * Python 3.14 `multiprocessing` spawn worker plus its resource tracker; the
+ * worker reparented to launchd (PPID 1) and busy-spun at 100% CPU for ~26
+ * days (~415 CPU-hours) undetected. The dispatch-side fix is the
+ * process-group reaping in `utils/process.ts`; this check covers orphans
+ * that predate it (or leaked from non-FireForge invocations), using the
+ * detection recipe that found the incident process: PPID 1 + large
+ * accumulated CPU TIME + a `multiprocessing.spawn`/`resource_tracker`
+ * command line.
+ *
+ * Report-only by design: FireForge never kills pre-existing processes it
+ * did not spawn — the check names each candidate and suggests the kill.
+ *
+ * Canary integration was deliberately skipped: the friction log asked for
+ * doctor AND/OR `test --canary`, and adding a system-wide process scan to
+ * the canary hot path buys no extra coverage over the doctor check.
+ */
+import { exec } from '../utils/process.js';
+import { ok, warning } from './doctor-check-core.js';
+/**
+ * Command-line shapes of Python multiprocessing helper processes: the
+ * spawn/forkserver worker bootstrap (`from multiprocessing.spawn import
+ * spawn_main; spawn_main(...)`) and the resource tracker.
+ */
+const HARNESS_WORKER_COMMAND_PATTERN = /multiprocessing\.(?:spawn|forkserver)\b|multiprocessing\.resource_tracker|from multiprocessing\.\w+ import/;
+/** Minimum accumulated CPU time before a match is reported (10 minutes). */
+const DEFAULT_MIN_CPU_SECONDS = 600;
+/**
+ * Parses a `ps` TIME value in either dialect:
+ *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
+ *   - darwin/BSD `mm:ss.cc` with cumulative minutes (e.g. `38412:07.55`)
+ * Returns NaN for unrecognized shapes.
+ */
+export function parseCpuTime(time) {
+    const trimmed = time.trim();
+    let days = 0;
+    let rest = trimmed;
+    const dayMatch = /^(\d+)-(.*)$/.exec(trimmed);
+    if (dayMatch) {
+        days = Number(dayMatch[1]);
+        rest = dayMatch[2] ?? '';
+    }
+    const parts = rest.split(':');
+    if (parts.length === 3) {
+        // hh:mm:ss (linux; seconds may not carry fractions but tolerate them)
+        const [h, m, s] = parts.map(Number);
+        if ([h, m, s].some((n) => Number.isNaN(n)))
+            return NaN;
+        return days * 86400 + (h ?? 0) * 3600 + (m ?? 0) * 60 + (s ?? 0);
+    }
+    if (parts.length === 2) {
+        // mm:ss.cc (darwin — the minutes field accumulates without wrapping)
+        const [m, s] = parts.map(Number);
+        if ([m, s].some((n) => Number.isNaN(n)))
+            return NaN;
+        return days * 86400 + (m ?? 0) * 60 + (s ?? 0);
+    }
+    return NaN;
+}
+/**
+ * Scans `ps -axo pid=,ppid=,time=,command=` output for orphaned harness
+ * workers: PPID 1 (reparented to init/launchd), a multiprocessing
+ * worker/tracker command line, and at least `minCpuSeconds` of accumulated
+ * CPU time. Pure — fixture-testable without spawning anything.
+ */
+export function findOrphanedHarnessWorkers(psOutput, minCpuSeconds = DEFAULT_MIN_CPU_SECONDS) {
+    const workers = [];
+    for (const line of psOutput.split('\n')) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(\S+)\s+(.+)$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        const ppid = Number(match[2]);
+        const cpuTime = match[3] ?? '';
+        const command = (match[4] ?? '').trim();
+        if (ppid !== 1)
+            continue;
+        if (!HARNESS_WORKER_COMMAND_PATTERN.test(command))
+            continue;
+        const cpuSeconds = parseCpuTime(cpuTime);
+        if (Number.isNaN(cpuSeconds) || cpuSeconds < minCpuSeconds)
+            continue;
+        workers.push({ pid, ppid, cpuTime, cpuSeconds, command });
+    }
+    return workers;
+}
+/** Thin exec wrapper for the process listing (tests mock `exec` instead). */
+async function listSystemProcesses() {
+    const result = await exec('ps', ['-axo', 'pid=,ppid=,time=,command='], { timeout: 10000 });
+    if (result.exitCode !== 0) {
+        throw new Error(`ps exited ${String(result.exitCode)}`);
+    }
+    return result.stdout;
+}
+const CHECK_NAME = 'Orphaned harness workers';
+async function runOrphanedHarnessCheck() {
+    let psOutput;
+    try {
+        psOutput = await listSystemProcesses();
+    }
+    catch (error) {
+        return warning(CHECK_NAME, `Could not scan system processes (${error instanceof Error ? error.message : String(error)}); skipping the orphaned-worker check.`);
+    }
+    const orphans = findOrphanedHarnessWorkers(psOutput);
+    if (orphans.length === 0) {
+        return ok(CHECK_NAME);
+    }
+    const rows = orphans
+        .map((w) => `PID ${String(w.pid)} (CPU time ${w.cpuTime}): ${w.command.slice(0, 160)}`)
+        .join('; ');
+    const pids = orphans.map((w) => String(w.pid)).join(' ');
+    return warning(CHECK_NAME, `Found ${String(orphans.length)} orphaned Python multiprocessing worker(s) — PPID 1 with ` +
+        `high accumulated CPU time, the shape a test harness that died at startup leaves behind ` +
+        `(field incident: one such worker busy-spun for ~26 days). ${rows}`, `These look like workers orphaned by a crashed test harness. Verify each command line, ` +
+        `then terminate with: kill ${pids} (or kill -9 if a process survives). ` +
+        'FireForge never kills pre-existing processes automatically.');
+}
+/**
+ * Doctor check reporting orphaned harness workers. Windows has no `ps`;
+ * the check is skipped there (best-effort platform gap, matching the
+ * process-group reaper's POSIX-only sweep).
+ */
+export const ORPHANED_HARNESS_DOCTOR_CHECK = {
+    name: CHECK_NAME,
+    skipIf: () => process.platform === 'win32',
+    run: runOrphanedHarnessCheck,
+};

package/dist/src/commands/doctor.js

@@ -16,6 +16,7 @@ import { POST_REBASE_AUDIT_CHECK } from './doctor/post-rebase-audit.js';
 import { failure, ok, warning } from './doctor-check-core.js';
 import { EXTERNAL_TOOLCHAIN_DOCTOR_CHECK } from './doctor-external-toolchains.js';
 import { FURNACE_DOCTOR_CHECKS } from './doctor-furnace.js';
+import { ORPHANED_HARNESS_DOCTOR_CHECK } from './doctor-orphaned-harness.js';
 import { inspectEngineWorkingTree } from './doctor-working-tree.js';
 import { collectPatchQueueHealth } from './verify.js';
 /**
@@ -264,6 +265,7 @@ const DOCTOR_CHECKS = [
             return warning('Watchman available', 'watchman is not installed or not on PATH. "fireforge watch" requires it.', 'Install watchman (brew install watchman / dnf install watchman / https://facebook.github.io/watchman/), then re-run doctor.');
         },
     },
+    ORPHANED_HARNESS_DOCTOR_CHECK,
     {
         name: 'Patches directory exists',
         run: async (ctx) => {

package/dist/src/commands/download.js

@@ -160,7 +160,7 @@ async function restorePreviousEngine(args) {
     }
 }
 async function downloadAndExtractFirefox(args) {
-    const { version, product, engineDir, cacheDir, sha256 } = args;
+    const { version, product, engineDir, cacheDir, sha256, candidate } = args;
     let s = spinner(`Downloading Firefox ${version}...`);
     let lastPercent = 0;
     const phaseState = { value: 'download' };
@@ -181,7 +181,7 @@ async function downloadAndExtractFirefox(args) {
             }
         }, sha256, (message) => {
             s.message(message);
-        });
+        }, candidate);
         s.stop(phaseState.value === 'extract'
             ? `Firefox ${version} extracted`
             : `Firefox ${version} downloaded`);
@@ -402,6 +402,9 @@ export async function downloadCommand(projectRoot, options) {
                 engineDir: installEngineDir,
                 cacheDir,
                 ...(config.firefox.sha256 !== undefined ? { sha256: config.firefox.sha256 } : {}),
+                ...(config.firefox.candidate !== undefined
+                    ? { candidate: config.firefox.candidate }
+                    : {}),
             });
             if (replacementEngineDir && backupEngineDir) {
                 warn('Activating replacement engine directory...');

package/dist/src/commands/export-flow.d.ts

@@ -39,8 +39,12 @@ export declare function computePlacementPlan(manifestPatches: PatchMetadata[], n
 export declare function computeExactPlacementPlan(manifestPatches: PatchMetadata[], newPatchCategory: PatchCategory, newPatchName: string, requestedOrder: number): PlacementPlan;
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
+ * When `config` is provided, positional plans (`--before`/`--after`) are
+ * refused up front if their renumber would touch a reserved range — one
+ * error for the whole shift instead of per-patch policy findings. The
+ * exact `--order` branch never renames, so it bypasses that gate.
  */
-export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string): Promise<PlacementPlan>;
+export declare function resolvePlacementPlan(patchesDir: string, options: ExportOptions, category: PatchCategory, name: string, config?: FireForgeConfig): Promise<PlacementPlan>;
 /**
  * Projects the placement through cross-patch lint to detect forward-imports
  * the renumber would introduce *or* that the new patch itself would

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

@@ -20,7 +20,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
 import { info, warn } from '../utils/logger.js';
-import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
+import { assertPlacementAvoidsReservedRanges } from './export-placement-policy.js';
 import { findPartialOwnershipOverlap } from './export-shared.js';
 function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
@@ -113,8 +113,12 @@ export function computeExactPlacementPlan(manifestPatches, newPatchCategory, new
 }
 /**
  * Resolves a placement plan from CLI flags against the current manifest.
+ * When `config` is provided, positional plans (`--before`/`--after`) are
+ * refused up front if their renumber would touch a reserved range — one
+ * error for the whole shift instead of per-patch policy findings. The
+ * exact `--order` branch never renames, so it bypasses that gate.
  */
-export async function resolvePlacementPlan(patchesDir, options, category, name) {
+export async function resolvePlacementPlan(patchesDir, options, category, name, config) {
     // ForWrite: placement planning feeds a manifest rewrite; a corrupt
     // manifest read as empty would allocate colliding orders.
     const manifest = await loadPatchesManifestForWrite(patchesDir);
@@ -147,7 +151,9 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         }
         targetOrder = anchor.order + 1;
     }
-    return computePlacementPlan(existingPatches, category, name, targetOrder);
+    const plan = computePlacementPlan(existingPatches, category, name, targetOrder);
+    assertPlacementAvoidsReservedRanges(plan, existingPatches, config);
+    return plan;
 }
 /**
  * Extracts the newly-created files a diff would produce and builds the
@@ -225,7 +231,7 @@ export function placementSummary(plan) {
  */
 export async function commitPlacementExport(input) {
     return withPatchDirectoryLock(input.patchesDir, async () => {
-        const currentPlan = await resolvePlacementPlan(input.patchesDir, input.options, input.category, input.name);
+        const currentPlan = await resolvePlacementPlan(input.patchesDir, input.options, input.category, input.name, input.config);
         if (!placementPlansEqual(currentPlan, input.expectedPlan)) {
             throw new InvalidArgumentError('Patch queue changed while waiting for export confirmation. Re-run the command to recompute placement.', 'export placement');
         }
@@ -237,9 +243,6 @@ export async function commitPlacementExport(input) {
                 'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');
         }
         const originalManifest = await loadPatchesManifestForWrite(input.patchesDir);
-        if (originalManifest !== null) {
-            assertPlacementPreservesReservedRanges(currentPlan, originalManifest.patches, input.config, input.category);
-        }
         if (input.config !== undefined) {
             const renamed = originalManifest !== null
                 ? applyRenameMapToManifest(originalManifest, currentPlan.renameMap)

package/dist/src/commands/export-placement-gate.js

@@ -12,7 +12,6 @@ import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { outro } from '../utils/logger.js';
 import { placementSummary, projectPlacementForLint, resolvePlacementPlan, } from './export-flow.js';
-import { assertPlacementPreservesReservedRanges } from './export-placement-policy.js';
 /**
  * Spreadable optional metadata (`tier`, `lintIgnore`) derived from the
  * export flags. Every manifest-row construction site in this command
@@ -41,11 +40,10 @@ export async function gatePlacementPlan(args) {
     if (options.supersede) {
         throw new InvalidArgumentError('Placement flags (--order/--before/--after) cannot be combined with --supersede.', 'export placement');
     }
-    const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName);
+    // resolvePlacementPlan runs the reserved-range gate itself when config
+    // is passed — one up-front error per run instead of per-patch findings.
+    const placementPlan = await resolvePlacementPlan(patchesDir, options, selectedCategory, patchName, config);
     const currentManifest = await loadPatchesManifest(patchesDir);
-    if (currentManifest !== null) {
-        assertPlacementPreservesReservedRanges(placementPlan, currentManifest.patches, config, selectedCategory);
-    }
     const conflicts = await projectPlacementForLint(patchesDir, placementPlan, diff);
     const renamed = currentManifest !== null
         ? applyRenameMapToManifest(currentManifest, placementPlan.renameMap)

package/dist/src/commands/export-placement-policy.d.ts

@@ -1,7 +1,7 @@
 /**
  * Policy-aware checks for export placement plans.
  */
-import type { PatchCategory, PatchMetadata } from '../types/commands/index.js';
+import type { PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 export interface PlacementPolicyPlan {
     insertionOrder: number;
@@ -10,5 +10,13 @@ export interface PlacementPolicyPlan {
         newOrder: number;
     }>;
 }
-/** Refuses positional export plans that would renumber exact reserved patches. */
-export declare function assertPlacementPreservesReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined, category: PatchCategory): void;
+/**
+ * Refuses positional placement plans whose renumber would touch a
+ * `patchPolicy.reservedRanges` block — either by moving a patch INTO a
+ * reserved range or by moving a patch that currently sits inside one.
+ * Throws a single up-front error for the first reserved range hit (the
+ * per-patch alternative surfaced one confusing finding per shifted
+ * patch), suggesting the first free `--order` below the block when one
+ * exists. Exact `--order` plans have an empty rename map and pass.
+ */
+export declare function assertPlacementAvoidsReservedRanges(plan: PlacementPolicyPlan, manifestPatches: readonly PatchMetadata[], config: FireForgeConfig | undefined): void;

package/dist/src/commands/export-placement-policy.js

@@ -10,44 +10,47 @@ function findReservedRange(config, order) {
     return (config.patchPolicy?.reservedRanges?.find((range) => order >= range.from && order <= range.to) ??
         null);
 }
-function suggestSparseOrder(config, patches, category, insertionOrder) {
-    const ranges = (config.patchPolicy?.ranges ?? [])
-        .filter((range) => range.category === category)
-        .sort((a, b) => a.from - b.from || a.to - b.to);
+/**
+ * Scans downward from just below the reserved block for the first order
+ * not occupied by an existing patch. Returns null when every positive
+ * order below the block is taken.
+ */
+function firstFreeOrderBelowReservedRange(patches, range) {
     const occupied = new Set(patches.map((patch) => patch.order));
-    for (const range of ranges) {
-        for (let order = Math.max(insertionOrder, range.from); order <= range.to; order++) {
-            if (!occupied.has(order) && findReservedRange(config, order) === null)
-                return order;
-        }
-    }
-    for (const range of ranges) {
-        for (let order = range.from; order <= range.to; order++) {
-            if (!occupied.has(order) && findReservedRange(config, order) === null)
-                return order;
-        }
+    for (let order = range.from - 1; order >= 1; order--) {
+        if (!occupied.has(order))
+            return order;
     }
     return null;
 }
-/** Refuses positional export plans that would renumber exact reserved patches. */
-export function assertPlacementPreservesReservedRanges(plan, manifestPatches, config, category) {
+/**
+ * Refuses positional placement plans whose renumber would touch a
+ * `patchPolicy.reservedRanges` block — either by moving a patch INTO a
+ * reserved range or by moving a patch that currently sits inside one.
+ * Throws a single up-front error for the first reserved range hit (the
+ * per-patch alternative surfaced one confusing finding per shifted
+ * patch), suggesting the first free `--order` below the block when one
+ * exists. Exact `--order` plans have an empty rename map and pass.
+ */
+export function assertPlacementAvoidsReservedRanges(plan, manifestPatches, config) {
     if (config?.patchPolicy === undefined || plan.renameMap.size === 0)
         return;
     const byFilename = new Map(manifestPatches.map((patch) => [patch.filename, patch]));
     for (const [filename, rename] of plan.renameMap) {
-        const patch = byFilename.get(filename);
-        if (!patch)
-            continue;
-        const reserved = findReservedRange(config, patch.order);
+        const oldOrder = byFilename.get(filename)?.order;
+        const reserved = findReservedRange(config, rename.newOrder) ??
+            (oldOrder !== undefined ? findReservedRange(config, oldOrder) : null);
         if (reserved === null)
             continue;
-        const suggestion = suggestSparseOrder(config, manifestPatches, category, plan.insertionOrder);
-        const suggestionText = suggestion !== null
-            ? ` Use --order ${String(suggestion).padStart(3, '0')} to create the new patch in an unused ${category} slot without renumbering reserved patches.`
-            : ` Choose an unused order in the ${category} policy range or adjust patchPolicy.`;
-        throw new InvalidArgumentError(`Positional export would renumber reserved patch ${patch.filename} ` +
-            `from ${String(patch.order).padStart(3, '0')} to ${rename.newFilename} ` +
-            `(reserved range ${reservedRangeLabel(reserved)}).` +
-            suggestionText, 'export placement');
+        const label = reservedRangeLabel(reserved);
+        const freeOrder = firstFreeOrderBelowReservedRange(manifestPatches, reserved);
+        if (freeOrder !== null) {
+            throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +
+                `pass --order ${String(freeOrder).padStart(3, '0')} (first free order below the ` +
+                'reserved block) to place the new patch without renumbering reserved patches.', 'export placement');
+        }
+        throw new InvalidArgumentError(`Positional insert would renumber the reserved range ${label}; ` +
+            'no free order exists below the reserved block. Choose an unused --order outside ' +
+            'the reserved range or adjust patchPolicy.reservedRanges.', 'export placement');
     }
 }

package/dist/src/commands/export.js

@@ -6,6 +6,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { appendHistory } from '../core/destructive.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
+import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { getStatusWithCodes, isGitRepository } from '../core/git.js';
 import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff.js';
 import { isBinaryFile } from '../core/git-file-ops.js';
@@ -19,7 +20,7 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
 import { info, intro, outro, spinner, verbose, warn } from '../utils/logger.js';
-import { commanderArgParser, pickDefined } from '../utils/options.js';
+import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag } from '../utils/validation.js';
 import { commitPlacementExport, renderDryRunPreview } from './export-flow.js';
@@ -201,6 +202,11 @@ async function prepareExport(projectRoot, files, options) {
         throw new GeneralError(`Paths "${pathList}" have no changes to export.\n\n` +
             'Run "fireforge status" to see modified files.');
     }
+    // Stale-furnace-source gate (0.37.0 item 4): the export captures deployed
+    // engine copies; refuse (or warn under --allow-stale-furnace) when a
+    // covered component's source changed since the last furnace apply. Runs
+    // after --exclude-furnace so excluded furnace files never trigger it.
+    await enforceFreshFurnaceSources(projectRoot, allFiles, options.allowStaleFurnace === true, 'export');
     let diff = await generatePatchDiff(paths.engine, allFiles);
     if (!diff.trim()) {
         if (options.skipLint) {
@@ -394,7 +400,7 @@ export async function exportCommand(projectRoot, files, options) {
 }
 /** Registers the export command on the CLI program. */
 export function registerExport(program, { getProjectRoot, withErrorHandling }) {
-    program
+    const exportCmd = program
         .command('export <paths...>')
         .description('Export new changes as a patch (use re-export to update existing patches)')
         .option('-n, --name <name>', 'Name for the patch')
@@ -409,10 +415,11 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
+        .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
         .addOption(new Option('--tier <tier>', 'Force a tier override on the new patch (only "branding" recognised)').choices(['branding']))
-        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], [])
-        .action(withErrorHandling(async (paths, options) => {
+        .option('--lint-ignore <check-id>', 'Suppress a lint check on this patch (writes to PatchMetadata.lintIgnore; repeatable)', (value, prev) => [...prev, value], []);
+    addWaitLockOption(exportCmd).action(withErrorHandling(async (paths, options) => {
         const { category, tier, lintIgnore, ...rest } = options;
         const projectRoot = getProjectRoot();
         await withEngineSessionLock(projectRoot, 'export', () => exportCommand(projectRoot, paths, {
@@ -420,6 +427,6 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
             ...(category !== undefined ? { category } : {}),
             ...(tier !== undefined ? { tier: tier } : {}),
             ...(lintIgnore !== undefined && lintIgnore.length > 0 ? { lintIgnore } : {}),
-        }));
+        }), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
     }));
 }