@hominis/fireforge 0.36.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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/dist/src/commands/build.js

@@ -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}`);

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/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';
@@ -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) {
@@ -409,6 +415,7 @@ 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], [])

package/dist/src/commands/patch/staged-dependency.d.ts

@@ -10,7 +10,7 @@ import type { PatchStagedDependencyOptions } from '../../types/commands/index.js
  *
  * @param projectRoot - Project root directory
  * @param identifier - Patch filename, ordinal, or manifest name
- * @param options - Mutation mode and forward-import fields
+ * @param options - Mutation mode, entry kind, and declaration fields
  */
 export declare function patchStagedDependencyCommand(projectRoot: string, identifier: string, options?: PatchStagedDependencyOptions): Promise<void>;
 /**

package/dist/src/commands/patch/staged-dependency.js

@@ -23,6 +23,19 @@ function modeFromOptions(options) {
     }
     return adding ? 'add' : removing ? 'remove' : 'clear';
 }
+function kindFromOptions(options) {
+    const kind = options.kind ?? 'import';
+    if (kind !== 'import' && kind !== 'registration') {
+        throw new InvalidArgumentError(`--kind must be "import" or "registration" (got "${kind}").`, 'patch staged-dependency');
+    }
+    if (kind === 'import' && options.line !== undefined) {
+        throw new InvalidArgumentError('--line only applies to --kind registration; import declarations use --specifier.', 'patch staged-dependency');
+    }
+    if (kind === 'registration' && options.specifier !== undefined) {
+        throw new InvalidArgumentError('--specifier only applies to --kind import; registration declarations use --line.', 'patch staged-dependency');
+    }
+    return kind;
+}
 function requireForwardImportOptions(options, mode) {
     if (!options.file || !options.specifier || !options.creates) {
         throw new InvalidArgumentError(`--${mode} requires --file, --specifier, and --creates.`, 'patch staged-dependency');
@@ -38,102 +51,149 @@ function requireForwardImportOptions(options, mode) {
         dependency.reason = options.reason;
     return dependency;
 }
-function dependencyKey(dependency) {
-    return [dependency.file, dependency.specifier, dependency.creates, dependency.owner ?? ''].join('\0');
+function requireRegistrationOptions(options, mode) {
+    if (!options.file || !options.line || !options.creates) {
+        throw new InvalidArgumentError(`--${mode} --kind registration requires --file, --line, and --creates.`, 'patch staged-dependency');
+    }
+    const dependency = {
+        file: options.file,
+        line: options.line,
+        creates: options.creates,
+    };
+    if (options.owner !== undefined)
+        dependency.owner = options.owner;
+    if (options.reason !== undefined)
+        dependency.reason = options.reason;
+    return dependency;
+}
+function importView(dependency) {
+    return { ...dependency, matcher: dependency.specifier };
 }
-function dependencyLabel(dependency) {
-    const owner = dependency.owner ? ` owner=${dependency.owner}` : '';
-    const reason = dependency.reason ? ` reason="${dependency.reason}"` : '';
-    return `${dependency.file} imports "${dependency.specifier}" from ${dependency.creates}${owner}${reason}`;
+function registrationView(dependency) {
+    return { ...dependency, matcher: dependency.line };
 }
-function removeMatching(existing, target) {
-    return existing.filter((dependency) => dependency.file !== target.file ||
-        dependency.specifier !== target.specifier ||
-        dependency.creates !== target.creates ||
-        (target.owner !== undefined && dependency.owner !== target.owner));
+function dependencyKey(view) {
+    return [view.file, view.matcher, view.creates, view.owner ?? ''].join('\0');
 }
-function applyMode(existing, mode, dependency) {
+function dependencyLabel(kind, view) {
+    const owner = view.owner ? ` owner=${view.owner}` : '';
+    const reason = view.reason ? ` reason="${view.reason}"` : '';
+    if (kind === 'import') {
+        return `${view.file} imports "${view.matcher}" from ${view.creates}${owner}${reason}`;
+    }
+    return `${view.file} registers "${view.matcher}" for ${view.creates}${owner}${reason}`;
+}
+function matchesTarget(view, target) {
+    return (view.file === target.file &&
+        view.matcher === target.matcher &&
+        view.creates === target.creates &&
+        (target.owner === undefined || view.owner === target.owner));
+}
+function applyMode(existing, mode, target, toView, addition) {
     if (mode === 'clear')
         return [];
-    if (!dependency)
+    if (!target)
         return [...existing];
     if (mode === 'remove')
-        return removeMatching(existing, dependency);
-    const seen = new Set(existing.map(dependencyKey));
-    if (seen.has(dependencyKey(dependency)))
+        return existing.filter((entry) => !matchesTarget(toView(entry), target));
+    const seen = new Set(existing.map((entry) => dependencyKey(toView(entry))));
+    if (seen.has(dependencyKey(target)) || addition === undefined)
         return [...existing];
-    return [...existing, dependency];
+    return [...existing, addition];
 }
 /**
  * Renders a one-line summary of a staged-dependency metadata change.
  */
-function describeStagedDependencyChange(before, after, mode, dependency) {
+function describeStagedDependencyChange(beforeCount, afterCount, mode, kind, target) {
+    const noun = kind === 'import' ? 'staged forward-import' : 'staged registration';
     if (mode === 'clear') {
-        return before.length === 0
+        return beforeCount === 0
             ? 'stagedDependencies was already empty — no change'
-            : `cleared ${before.length} staged forward-import declaration(s)`;
+            : `cleared ${beforeCount} staged dependency declaration(s)`;
     }
-    if (!dependency)
+    if (!target)
         return 'stagedDependencies unchanged';
     if (mode === 'add') {
-        return after.length === before.length
-            ? `staged forward-import already present: ${dependencyLabel(dependency)}`
-            : `added staged forward-import: ${dependencyLabel(dependency)}`;
+        return afterCount === beforeCount
+            ? `${noun} already present: ${dependencyLabel(kind, target)}`
+            : `added ${noun}: ${dependencyLabel(kind, target)}`;
     }
-    return after.length === before.length
-        ? `no staged forward-import matched: ${dependencyLabel(dependency)}`
-        : `removed ${before.length - after.length} staged forward-import declaration(s): ${dependencyLabel(dependency)}`;
+    return afterCount === beforeCount
+        ? `no ${noun} matched: ${dependencyLabel(kind, target)}`
+        : `removed ${beforeCount - afterCount} ${noun} declaration(s): ${dependencyLabel(kind, target)}`;
+}
+function countStagedEntries(staged) {
+    return (staged?.forwardImports?.length ?? 0) + (staged?.registrations?.length ?? 0);
 }
 /**
  * Runs the metadata-only staged-dependency mutation command.
  *
  * @param projectRoot - Project root directory
  * @param identifier - Patch filename, ordinal, or manifest name
- * @param options - Mutation mode and forward-import fields
+ * @param options - Mutation mode, entry kind, and declaration fields
  */
 export async function patchStagedDependencyCommand(projectRoot, identifier, options = {}) {
     const isDryRun = options.dryRun === true;
     intro(isDryRun ? 'FireForge patch staged-dependency (dry run)' : 'FireForge patch staged-dependency');
     const mode = modeFromOptions(options);
-    const dependency = mode === 'clear' ? undefined : requireForwardImportOptions(options, mode);
+    const kind = kindFromOptions(options);
+    const importDependency = mode === 'clear' || kind !== 'import' ? undefined : requireForwardImportOptions(options, mode);
+    const registrationDependency = mode === 'clear' || kind !== 'registration'
+        ? undefined
+        : requireRegistrationOptions(options, mode);
+    const target = importDependency !== undefined
+        ? importView(importDependency)
+        : registrationDependency !== undefined
+            ? registrationView(registrationDependency)
+            : undefined;
     const { paths, manifest } = await requirePatchQueue(projectRoot);
-    const target = requirePatchTarget(identifier, manifest.patches);
-    const existing = target.stagedDependencies?.forwardImports ?? [];
-    const projected = applyMode(existing, mode, dependency);
-    const summary = describeStagedDependencyChange(existing, projected, mode, dependency);
+    const targetPatch = requirePatchTarget(identifier, manifest.patches);
+    const applyToStaged = (staged) => {
+        if (mode === 'clear')
+            return {};
+        const forwardImports = applyMode(staged?.forwardImports ?? [], kind === 'import' ? mode : 'add', kind === 'import' ? target : undefined, importView, importDependency);
+        const registrations = applyMode(staged?.registrations ?? [], kind === 'registration' ? mode : 'add', kind === 'registration' ? target : undefined, registrationView, registrationDependency);
+        return {
+            ...(forwardImports.length > 0 ? { forwardImports } : {}),
+            ...(registrations.length > 0 ? { registrations } : {}),
+        };
+    };
+    const existing = targetPatch.stagedDependencies;
+    const projected = applyToStaged(existing);
+    const summary = describeStagedDependencyChange(countStagedEntries(existing), countStagedEntries(projected), mode, kind, target);
     if (isDryRun) {
-        info(`[dry-run] ${target.filename}: ${summary}.`);
+        info(`[dry-run] ${targetPatch.filename}: ${summary}.`);
         outro('Dry run complete — no changes made');
         return;
     }
-    const result = await mutatePatchMetadata(paths.patches, target.filename, (current) => {
-        const before = current.stagedDependencies?.forwardImports ?? [];
-        const after = applyMode(before, mode, dependency);
-        if (after.length === 0)
+    const result = await mutatePatchMetadata(paths.patches, targetPatch.filename, (current) => {
+        const after = applyToStaged(current.stagedDependencies);
+        if (countStagedEntries(after) === 0)
             return { unset: ['stagedDependencies'] };
-        return { set: { stagedDependencies: { forwardImports: after } } };
+        return { set: { stagedDependencies: after } };
     });
     if (!result) {
-        throw new GeneralError(`Patch ${target.filename} disappeared from the manifest during the update. Re-run after investigating.`);
+        throw new GeneralError(`Patch ${targetPatch.filename} disappeared from the manifest during the update. Re-run after investigating.`);
     }
-    const before = result.before.stagedDependencies?.forwardImports ?? [];
-    const after = result.after.stagedDependencies?.forwardImports ?? [];
-    info(`${target.filename}: ${describeStagedDependencyChange(before, after, mode, dependency)}.`);
+    const before = result.before.stagedDependencies;
+    const after = result.after.stagedDependencies;
+    info(`${targetPatch.filename}: ${describeStagedDependencyChange(countStagedEntries(before), countStagedEntries(after), mode, kind, target)}.`);
     try {
         await appendHistory(paths.patches, {
             operation: 'patch-staged-dependency',
             args: {
-                filename: target.filename,
+                filename: targetPatch.filename,
                 mode,
-                before,
-                after,
+                kind,
+                before: before ?? {},
+                after: after ?? {},
             },
             ...(options.yes === true ? { yes: true } : {}),
             result: 'ok',
         });
     }
     catch (historyError) {
-        warn(`History log append failed after patch staged-dependency committed (${target.filename}): ${toError(historyError).message}`);
+        warn(`History log append failed after patch staged-dependency committed (${targetPatch.filename}): ${toError(historyError).message}`);
     }
     outro('Patch staged-dependency complete');
 }
@@ -148,11 +208,13 @@ export function registerPatchStagedDependency(parent, context) {
     parent
         .command('staged-dependency <name>')
         .description('Edit PatchMetadata.stagedDependencies on a single patch (no .patch body rewrite).')
-        .option('--add', 'Add a staged forward-import declaration')
-        .option('--remove', 'Remove matching staged forward-import declaration(s)')
+        .option('--add', 'Add a staged dependency declaration')
+        .option('--remove', 'Remove matching staged dependency declaration(s)')
         .option('--clear', 'Drop the stagedDependencies field entirely')
-        .option('--file <path>', 'Importing file path relative to engine/')
-        .option('--specifier <specifier>', 'Exact import specifier as it appears in source')
+        .option('--kind <kind>', 'Declaration shape: "import" (forward import, the default) or "registration" (jar.mn packaging line, customElements or actor registration)')
+        .option('--file <path>', 'Declaring file path relative to engine/')
+        .option('--specifier <specifier>', 'Exact import specifier as it appears in source (--kind import)')
+        .option('--line <text>', 'Registration/packaging line as the patch adds it, compared whitespace-trimmed (--kind registration)')
         .option('--creates <path>', 'Later-created file path relative to engine/')
         .option('--owner <patch>', 'Exact later patch filename expected to create --creates')
         .option('--reason <text>', 'Human-readable rationale stored with the declaration')

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

@@ -2,6 +2,7 @@
 import { join } from 'node:path';
 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 { computeProjectedLintRegressions } from '../core/lint-projection.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
@@ -151,6 +152,9 @@ export async function reExportFilesInPlace(paths, selectedPatches, options, conf
         throw new InvalidArgumentError('reExportFilesInPlace called with no --files.', '--files');
     }
     const requested = [...new Set(filesOption)].sort();
+    // Stale-furnace-source gate (0.37.0 item 4): same refusal as the generic
+    // re-export path — the projected diff would capture stale deployed copies.
+    await enforceFreshFurnaceSources(paths.root, requested, options.allowStaleFurnace === true, 're-export');
     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));

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

@@ -5,6 +5,7 @@ import { multiselect } from '@clack/prompts';
 import { Command, Option } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
+import { enforceFreshFurnaceSources } from '../core/furnace-stale-export.js';
 import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
@@ -129,6 +130,12 @@ async function reExportSinglePatch(patch, paths, manifest, options, isDryRun, co
         for (const f of removed)
             info(`  - ${f}`);
     }
+    // Stale-furnace-source gate (0.37.0 item 4): re-export captures deployed
+    // engine copies, so a component source edited after the last furnace
+    // apply would land in the patch as its OLD deployed content. Refuse (or
+    // warn under --allow-stale-furnace) before diffing. Runs in dry-run too
+    // so the failure surfaces early.
+    await enforceFreshFurnaceSources(paths.root, currentFilesAffected, options.allowStaleFurnace === true, 're-export');
     const missingFiles = await findMissingFiles(paths.engine, currentFilesAffected);
     if (missingFiles.length === currentFilesAffected.length) {
         warn(`Skipped ${patch.filename}: all affected files missing`);
@@ -415,6 +422,7 @@ export function registerReExport(program, { getProjectRoot, withErrorHandling })
         .filter((v) => v.length > 0))
         .option('--dry-run', 'Show what would change without writing')
         .option('--skip-lint', 'Skip patch lint checks (downgrade errors to warnings)')
+        .option('--allow-stale-furnace', 'Export the deployed engine copy even when the components/ source changed since the last furnace apply')
         .option('--allow-shrink', 'Allow --files to remove paths currently owned by the patch. Required before --yes can bypass the shrink confirmation.')
         .option('-y, --yes', 'Skip confirmation prompts (required for non-TTY destructive writes)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal when --files shrinks a patch')

package/dist/src/commands/test-diagnose.js

@@ -209,6 +209,10 @@ export function finalizeSingleRunOutcome(outcome, normalizedPaths, binaryName, p
     }
     if (outcome.verdict.realFailureLine !== undefined) {
         info(`First real test failure: ${outcome.verdict.realFailureLine}`);
+        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
+        if (blocks !== undefined) {
+            info(blocks);
+        }
         if (outcome.verdict.secondaryHarnessSignature !== undefined) {
             info(`Secondary harness noise also present: ${outcome.verdict.secondaryHarnessSignature.reason}; ` +
                 outcome.verdict.secondaryHarnessSignature.line);
@@ -233,6 +237,21 @@ export function diagnoseShardOutcome(outcome, path, binaryName, postRebuildConte
         return undefined;
     }
     catch (error) {
-        return error instanceof Error ? error.message : String(error);
+        const diagnosis = error instanceof Error ? error.message : String(error);
+        const blocks = formatFailureBlocks(outcome.verdict.realFailureBlocks);
+        return blocks !== undefined ? `${blocks}\n${diagnosis}` : diagnosis;
     }
 }
+/**
+ * Renders the verdict's TEST-UNEXPECTED blocks (verbatim failing lines +
+ * their assertion/diff context) for the failure summary. Returns undefined
+ * when the verdict carries none, so callers can skip the section entirely.
+ */
+function formatFailureBlocks(blocks) {
+    if (blocks === undefined || blocks.length === 0)
+        return undefined;
+    // The collector appends a `…(+N more …)` note when it truncated; that
+    // note is not a failure block, so it does not count toward the header.
+    const shown = blocks.filter((block) => !block.startsWith('…(')).length;
+    return `Unexpected test failures (first ${shown}):\n${blocks.join('\n\n')}`;
+}