@hominis/fireforge 0.49.2 → 0.50.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.50.0
+
+### Size budget
+
+- New `patchLint.fileSizeMetric` (`raw` or `code`), `patchSizeMetric` (`diff` or `addedCode`), per-tier `patchSizeThresholds` and `patchSizeRegistrationFiles`. Added code skips comments, blank lines and Furnace fragment copies. Defaults are unchanged. Size messages name their unit, and a notice no longer claims to fail `--max-warnings 0`.
+- `lintIgnore` entries can carry a size ceiling (`{ rule, max, reason }`). Size helpers are exported, and `lint --report` rows carry the metric.
+
+### Gates and policy
+
+- Added `fireforge check`, which runs status, verify, per-patch lint, typecheck, Furnace validation, token coverage and `check.extraSteps` with one verdict. `status` gains `--fail-on ownership-conflict`, `--allow`, `--fail-on-unknown` and `--patches`; `verify` gains `--patches`.
+- Opt-in `patchPolicy` rules (`upstreamAllowlist`, add-only marker mode, `scopeRules`, `verifyDocumentPaths`), `patchLint.tokenScales` and `fireforge token lint`. `furnace validate` gains `--json`, `--max-warnings` and `validationExceptions`.
+
+### Test harness
+
+- Packaging coverage is kept per staged path, so a peer's scoped build no longer replaces it. The stale-build check ignores edits the packaged runtime already serves.
+- Mixed xpcshell and browser paths, `--repeat <n>` and `--negative-control <diff>` run under one lock hold. A truncated exit-0 run is `FAIL`. The binary, checkJs and browser/port waits run before the engine lock.
+- Added `--keep-log`, `--auto-ports`, `--no-furnace-apply` and `--restart-between-tests`. A path after an optional-value flag such as `--wait-lock` is read as a test path.
+
+### Locks and history
+
+- File locks are granted in arrival order, and crashed or stopped waiters are skipped.
+- The patch history log moves to `.fireforge/history.jsonl` (configurable as `history.path`) and is migrated on first write. Records carry an invocation id, and staged-dependency records log only the delta.
+
+### Patch queue
+
+- `--refuse-foreign-drift` counts removed lines and combines with `--scan`. `--scan-file` accepts `<patch>:<path>`. `--refuse-adjacent-unmanaged` judges only files a re-export would capture, and gains `--expect-new` and `--adjacent-ignore`. Arguments are checked before the lock, and `--expect-from` is new.
+- Added `patch retire`, which keeps the retired patch's order as a slot. `staged-dependency --add --from` takes a lint report. `move-files --create` and `split` keep staged declarations in step. Refusals name the earliest legal order and the exact commands.
+
+### Furnace
+
+- `--wait-lock` works on every leaf. `deploy` takes several names, and `rename` rewrites registrations in place and gains `--dry-run`. `apply` no longer duplicates jar lines and says why it skipped. The unexported-drift belt and `furnace diff` compare against the fragment-expanded source.
+
+### Other
+
+- Config writes keep `fireforge.json`'s formatting. `rebase` labels the move from the committed pin. `doctor` tolerates the `esr` suffix and names `./mach npm ci`. `Cu` is typed in the shim. `run --profile` purges caches, and `--smoke-exit` fails a silent early exit.
+- Dev tooling: `eslint` 10.12.0 and `eslint-plugin-jsdoc` 65.0.2.
+
 ## 0.49.0
 
 ### Furnace and builds
@@ -7,6 +44,7 @@
 - Safer Furnace deployment and objdir cloning protect component sources and peer checkouts from shared files and directory aliases. Failed copies finish before rollback; cloned build metadata is relocated and verified.
 - `furnace create --localized` no longer scaffolds a `connectedCallback`/`disconnectedCallback` pair that calls `l10n.connectRoot(shadowRoot)` and `disconnectRoot`. `MozLitElement` already registers its shadow render root with `document.l10n`, so the generated pair registered the same root twice, which `DOMLocalization::ConnectRoot` asserts against in debug builds. The scaffold keeps the module-level `window.MozXULElement?.insertFTLIfNeeded(...)` call.
 - Build and test preflight detect broken partial configuration, stale artifacts and invalid build baselines. Scoped builds retain coverage only while their inputs remain unchanged, and builds remove dangling test links.
+- Objdir relocation on Windows rewrites both the backslash and the forward-slash spelling of the old root in dependency metadata (mozbuild writes both), and replaces a directory link that `rename` refuses with `EPERM` in two steps.
 
 ### Test harness
 
@@ -25,11 +63,12 @@
 ### Command reliability
 
 - Fixed leaf-command `--wait-lock` handling, JSON error reporting and watch retries. Process tracking and independent cleanup preserve the original run outcome through cancellation and cleanup failures.
+- Diff header parsing splits a rename/copy header with `indexOf` instead of a lazy regex, and token-category parsing strips CSS strings in one pass, so both run in linear time on pathological input.
 
 ### Tooling
 
 - Full-Firefox integration preserves existing workspace files and Git index state, and fails on incomplete recovery. Build identity includes untracked contents and binary changes. Release checks enforce the pinned toolchain and additional module coverage floors.
-- Dev tooling: `eslint-plugin-jsdoc` 65.0.1 and `@types/node` 26.6.4. Transitive `source-map-js` 1.2.2 (GHSA-68fv-2mgg-jv7q) and `smol-toml` 1.9.0 (GHSA-r4xh-jqrq-34v2) clear `npm audit`.
+- Dev tooling: `eslint-plugin-jsdoc` 65.0.1, `@types/node` 26.6.4, `knip` 6.39.0 and `prettier` 3.9.9. Transitive `source-map-js` 1.2.2 (GHSA-68fv-2mgg-jv7q) and `smol-toml` 1.9.0 (GHSA-r4xh-jqrq-34v2) clear `npm audit`.
 
 ## 0.48.0
 

package/README.md

@@ -15,7 +15,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 - **Firefox source and build helpers** Download, bootstrap, build, run, test, package, smoke-check, etc.
 - **Wiring and registration** Add chrome scripts, DOM fragments, modules, styles, tests and manifest entries through commands built by learning from existing Firefox conventions.
 - **Furnace components** Create or override `MozLitElement` widgets easily to add new or adapt existing UI components to your needs.
-- **Quality** `lint`, `typecheck`, `verify` and `doctor` catch common issues early.
+- **Quality** `lint`, `typecheck`, `verify` and `doctor` catch common issues early, and `check` runs the static gates together with one verdict.
 - **Tests** FireForge was built by taking apart and applying patches of all sorts to original Firefox source code across different versions and products, learning what works vs doesn't and creating some quite extensive tests based on that covering all manner of scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally on my MacBook, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Actions will be added soonishlyTM but might need a different runner...
 
 ## Requirements

package/dist/bin/fireforge.js

@@ -12,6 +12,7 @@ import { removeActivePgidFile } from '../src/commands/test-harness-teardown.js';
 import { emitKilledVerdict } from '../src/commands/test-verdict.js';
 import { forceReleaseHeldLocksForSignal } from '../src/core/file-lock.js';
 import { forceReleaseFurnaceLocksForActiveOperations, isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
+import { restoreActiveNegativeControlsForSignal } from '../src/core/negative-control.js';
 import { closeActiveRunLog } from '../src/core/run-log.js';
 import { removeActiveRunProfiles } from '../src/core/run-profile.js';
 import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
@@ -97,6 +98,11 @@ function installFurnaceSignalHandler(signal, exitCode) {
             waitForActiveCriticalSections(SIGNAL_CRITICAL_SECTION_TIMEOUT_MS),
             waitForActiveChildShutdown(CHILD_SHUTDOWN_TIMEOUT_MS),
         ])
+            // A `test --negative-control` mutation must be undone while this
+            // process still holds the engine lock, or the next lock holder builds
+            // and tests the neuter. Runs after child shutdown, so the dying
+            // harness no longer reads the files. Never throws.
+            .then(() => restoreActiveNegativeControlsForSignal())
             // `withFileLock`'s `finally { rm }` never runs across `process.exit`,
             // so both sweeps exist for the same reason. The generic one covers
             // every lock this process holds (engine session, patch directory,

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.49.2",
-  "commit": "c707978869b62aba07d1e8f0955be00c223d5ce0",
-  "shortCommit": "c707978869b6",
+  "version": "0.50.0",
+  "commit": "996c59a67aa2144ff889a8c47e9304b071afae81",
+  "shortCommit": "996c59a67aa2",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-10-06T21:50:15.508Z"
+  "buildTime": "2026-10-12T00:43:41.476Z"
 }

package/dist/src/commands/build-prelock.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `fireforge build --wait-browser` spends its budget before the engine
+ * session lock, not while holding it.
+ *
+ * A build queued behind a running objdir browser (a demo batch, an
+ * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
+ * peer's build, test and re-export queued behind a run that was doing
+ * nothing. The wait now happens first, and the in-lock objdir preflight
+ * re-checks once (the spent budget is stripped from the options it gets).
+ */
+import type { BuildOptions } from '../types/commands/index.js';
+/**
+ * Waits for this objdir's browser before the lock when `--wait-browser`
+ * was given and there is a launchable bundle to watch.
+ *
+ * @param projectRoot - Project root
+ * @param options - Parsed build options
+ * @returns The options the in-lock run should use
+ */
+export declare function waitForBuildBrowserBeforeLock(projectRoot: string, options: BuildOptions): Promise<BuildOptions>;

package/dist/src/commands/build-prelock.js

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge build --wait-browser` spends its budget before the engine
+ * session lock, not while holding it.
+ *
+ * A build queued behind a running objdir browser (a demo batch, an
+ * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
+ * peer's build, test and re-export queued behind a run that was doing
+ * nothing. The wait now happens first, and the in-lock objdir preflight
+ * re-checks once (the spent budget is stripped from the options it gets).
+ */
+import { join } from 'node:path';
+import { getProjectPaths, loadConfig } from '../core/config.js';
+import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
+import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
+import { waitBeforeLock } from '../core/preflight-wait.js';
+import { pathExists } from '../utils/fs.js';
+import { resolveWaitLockSeconds } from '../utils/options.js';
+/**
+ * Waits for this objdir's browser before the lock when `--wait-browser`
+ * was given and there is a launchable bundle to watch.
+ *
+ * @param projectRoot - Project root
+ * @param options - Parsed build options
+ * @returns The options the in-lock run should use
+ */
+export async function waitForBuildBrowserBeforeLock(projectRoot, options) {
+    const { waitBrowser, ...rest } = options;
+    if (waitBrowser === undefined)
+        return options;
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine)))
+        return options;
+    const { objDir } = await hasBuildArtifacts(paths.engine);
+    if (objDir === undefined)
+        return options;
+    let binaryName;
+    try {
+        ({ binaryName } = await loadConfig(projectRoot));
+    }
+    catch {
+        return options;
+    }
+    const bundle = await hasRunnableBundle(paths.engine, binaryName, objDir);
+    const expectedPath = bundle.expectedPath;
+    if (!bundle.runnable || expectedPath === undefined)
+        return options;
+    await waitBeforeLock(() => ensureLaunchableBrowserNotRunning(join(paths.engine, expectedPath)), resolveWaitLockSeconds(waitBrowser));
+    return rest;
+}

package/dist/src/commands/build.d.ts

@@ -5,7 +5,9 @@ import type { BuildOptions } from '../types/commands/index.js';
  * Runs the build command.
  * @param projectRoot - Root directory of the project
  * @param options - Build options
+ * @param underLock - Runs the build under the engine session lock; a
+ *   `--wait-browser` budget is spent before it (see build-prelock.ts)
  */
-export declare function buildCommand(projectRoot: string, options: BuildOptions): Promise<void>;
+export declare function buildCommand(projectRoot: string, options: BuildOptions, underLock?: (body: () => Promise<void>) => Promise<void>): Promise<void>;
 /** Registers the build command on the CLI program. */
 export declare function registerBuild(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;

package/dist/src/commands/build.js

@@ -13,7 +13,7 @@ import { findObjdirRelocationViolation } from '../core/mach-build-artifacts.js';
 import { ensureLaunchableBrowserNotRunning } from '../core/marionette-port.js';
 import { assertHealthyPartialConfig, pruneDanglingTestLinks } from '../core/objdir-maintenance.js';
 import { waitForPreflight } from '../core/preflight-wait.js';
-import { closeActiveRunLog, getActiveRunLogPath, openRunLog, setActiveRunLog, } from '../core/run-log.js';
+import { closeActiveRunLog, getActiveRunLogPath, keepRunLogCopy, openRunLog, setActiveRunLog, } from '../core/run-log.js';
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { formatToolchainMismatchMessage, runToolchainPreflight, } from '../core/toolchain-preflight.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
@@ -24,6 +24,7 @@ import { checkDiskSpace } from '../utils/fs.js';
 import { error, info, intro, notice, outro, spinner, verbose, warn } from '../utils/logger.js';
 import { addWaitLockOption, commanderArgParser, pickDefined, resolveWaitLockSeconds, } from '../utils/options.js';
 import { isPositiveInteger } from '../utils/validation.js';
+import { waitForBuildBrowserBeforeLock } from './build-prelock.js';
 function parseJobCount(value) {
     const parsed = Number(value);
     if (!Number.isSafeInteger(parsed) || parsed < 1) {
@@ -177,17 +178,20 @@ function buildFailureDiagnostics(result, engineDir, objDir, machCommand) {
  * Runs the build command.
  * @param projectRoot - Root directory of the project
  * @param options - Build options
+ * @param underLock - Runs the build under the engine session lock; a
+ *   `--wait-browser` budget is spent before it (see build-prelock.ts)
  */
-export async function buildCommand(projectRoot, options) {
+export async function buildCommand(projectRoot, options, underLock = (body) => body()) {
     const buildType = options.ui ? 'UI-only' : 'Full';
     const brandInfo = options.brand ? ` [${options.brand}]` : '';
     intro(`FireForge Build (${buildType}${brandInfo})`);
     // A build's own complete output, kept independently of whatever the
     // operator piped the run through. `build` prints no FIREFORGE-VERDICT
     // line, so the path is announced directly at the end of the run.
-    setActiveRunLog(await openRunLog(projectRoot, 'build'));
+    setActiveRunLog(await keepRunLogCopy(await openRunLog(projectRoot, 'build'), options.keepLog, 'build'));
     try {
-        await runBuildCommandBody(projectRoot, options);
+        const lockedOptions = await waitForBuildBrowserBeforeLock(projectRoot, options);
+        await underLock(() => runBuildCommandBody(projectRoot, lockedOptions));
     }
     finally {
         const logPath = getActiveRunLogPath();
@@ -400,11 +404,12 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
         .command('build')
         .description('Build the browser (auto-applies Furnace components first)')
         .option('--wait-browser [seconds]', 'Wait for this objdir browser to exit before changing its build (default 60)', commanderArgParser((raw) => resolveWaitLockSeconds(raw)))
+        .option('--keep-log <path>', "Also write this run's log to <path> (a directory receives it under its own name), outside .fireforge/logs/ retention. FIREFORGE_LOG_KEEP sets a session default.")
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')
         .option('--rewrite-mozinfo', 'On a mozinfo path mismatch, patch mozinfo.json paths in place and run mach configure instead of aborting with a clean-rebuild instruction. Refuses anything that is not a pure prefix-move.')
-        .option('--refuse-unexported-drift', 'Refuse (instead of warning) when the build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the multi-session hazard where an unexported edit is silently reverted and a later re-export captures a hybrid')
+        .option('--refuse-unexported-drift', 'Refuse (instead of warning) when the build would overwrite engine content recorded in neither a patch body nor the pristine baseline — the multi-session hazard where an unexported edit is silently reverted and a later re-export captures a hybrid. A deployed Furnace file that is a deployment of its own component source is allowed')
         .addHelpText('after', [
         '',
         'Furnace apply runs automatically before the build step, so edits in',
@@ -425,6 +430,8 @@ export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     ].join('\n'));
     addWaitLockOption(build).action(withErrorHandling(async (options) => {
         const projectRoot = getProjectRoot();
-        await withEngineSessionLock(projectRoot, 'build', () => buildCommand(projectRoot, pickDefined(options)), { waitLockSeconds: resolveWaitLockSeconds(options.waitLock) });
+        await buildCommand(projectRoot, pickDefined(options), (body) => withEngineSessionLock(projectRoot, 'build', body, {
+            waitLockSeconds: resolveWaitLockSeconds(options.waitLock),
+        }));
     }));
 }

package/dist/src/commands/check-report.d.ts

@@ -0,0 +1,28 @@
+import type { CheckStepResult } from './check-run.js';
+/**
+ * Why a check failed. `step-failures`: at least one step went red.
+ * `lock-timeout`: every failing step exited 15, so nothing was judged red,
+ * the steps just never got their locks. Re-queue rather than fix.
+ */
+export type CheckVerdictReason = 'step-failures' | 'lock-timeout';
+/** The verdict over all steps. */
+export interface CheckVerdict {
+    passed: boolean;
+    reason?: CheckVerdictReason;
+    failed: string[];
+    skipped: string[];
+    steps: number;
+}
+/** Judges the results: any failing step fails the check. */
+export declare function judgeCheck(results: readonly CheckStepResult[]): CheckVerdict;
+/**
+ * The verdict line: `FIREFORGE-VERDICT: PASS steps=<n> skipped=<n>` or
+ * `FIREFORGE-VERDICT: FAIL reason=<reason> failed=<a,b> steps=<n> skipped=<n>`.
+ */
+export declare function formatCheckVerdictLine(verdict: CheckVerdict): string;
+/** The per-step table: one aligned row per step, with its detail. */
+export declare function formatCheckTable(results: readonly CheckStepResult[]): string;
+/** Writes the verdict line as the run's last stdout write, and seals stdout. */
+export declare function writeCheckVerdictLine(verdict: CheckVerdict): void;
+/** Writes the `--json` document (schemaVersion 1) and seals stdout. */
+export declare function writeCheckJson(results: readonly CheckStepResult[], verdict: CheckVerdict): void;

package/dist/src/commands/check-report.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge check` output: the per-step table, the single
+ * `FIREFORGE-VERDICT:` line, and the `--json` document. The verdict is
+ * computed once here and shared by all three, so the exit code, the line
+ * and the JSON can never disagree.
+ */
+import { setStdoutSealed } from '../utils/logger.js';
+/** Exit code a step reports when its lock wait expired. */
+const LOCK_TIMEOUT_EXIT = 15;
+/** Judges the results: any failing step fails the check. */
+export function judgeCheck(results) {
+    const failedResults = results.filter((result) => result.status === 'fail');
+    const verdict = {
+        passed: failedResults.length === 0,
+        failed: failedResults.map((result) => result.name),
+        skipped: results.filter((result) => result.status === 'skipped').map((result) => result.name),
+        steps: results.length,
+    };
+    if (failedResults.length > 0) {
+        verdict.reason = failedResults.every((result) => result.exitCode === LOCK_TIMEOUT_EXIT)
+            ? 'lock-timeout'
+            : 'step-failures';
+    }
+    return verdict;
+}
+/**
+ * The verdict line: `FIREFORGE-VERDICT: PASS steps=<n> skipped=<n>` or
+ * `FIREFORGE-VERDICT: FAIL reason=<reason> failed=<a,b> steps=<n> skipped=<n>`.
+ */
+export function formatCheckVerdictLine(verdict) {
+    const counts = `steps=${verdict.steps} skipped=${verdict.skipped.length}`;
+    if (verdict.passed)
+        return `FIREFORGE-VERDICT: PASS ${counts}`;
+    return `FIREFORGE-VERDICT: FAIL reason=${verdict.reason ?? 'step-failures'} failed=${verdict.failed.join(',')} ${counts}`;
+}
+function formatDuration(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/** The per-step table: one aligned row per step, with its detail. */
+export function formatCheckTable(results) {
+    const rows = results.map((result) => [
+        result.name,
+        result.status.toUpperCase(),
+        result.status === 'skipped' ? '-' : formatDuration(result.durationMs),
+        result.detail,
+    ]);
+    const header = ['STEP', 'RESULT', 'TIME', 'DETAIL'];
+    const widths = header.map((title, column) => Math.max(title.length, ...rows.map((row) => row[column]?.length ?? 0)));
+    return [header, ...rows]
+        .map((row) => row
+        .map((cell, column) => column === row.length - 1 ? cell : cell.padEnd(widths[column] ?? 0))
+        .join('  ')
+        .trimEnd())
+        .join('\n');
+}
+/** Writes the verdict line as the run's last stdout write, and seals stdout. */
+export function writeCheckVerdictLine(verdict) {
+    process.stdout.write(`${formatCheckVerdictLine(verdict)}\n`);
+    setStdoutSealed(true);
+}
+/** Writes the `--json` document (schemaVersion 1) and seals stdout. */
+export function writeCheckJson(results, verdict) {
+    const payload = {
+        schemaVersion: 1,
+        verdict: verdict.passed ? 'pass' : 'fail',
+        ...(verdict.reason !== undefined ? { reason: verdict.reason } : {}),
+        summary: {
+            steps: verdict.steps,
+            passed: results.filter((result) => result.status === 'pass').length,
+            failed: verdict.failed.length,
+            skipped: verdict.skipped.length,
+        },
+        steps: results,
+    };
+    process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+    setStdoutSealed(true);
+}

package/dist/src/commands/check-run.d.ts

@@ -0,0 +1,28 @@
+import type { CheckStepPlan } from './check-steps.js';
+/** What a step's table row and JSON entry report. */
+export interface CheckStepResult {
+    name: string;
+    kind: 'builtin' | 'extra';
+    /** The command line, as the table prints it. */
+    command: string;
+    status: 'pass' | 'fail' | 'skipped';
+    /** The child's exit code. Null when it never ran or was killed at its budget. */
+    exitCode: number | null;
+    durationMs: number;
+    /** One-line summary for the table. */
+    detail: string;
+    /** Set when the step was killed at its `timeout`. */
+    timedOut?: true;
+    /** The tail of the step's combined output, for a failed step. */
+    outputTail?: string;
+}
+/**
+ * Runs every step and returns the results in plan order. A step starts
+ * once a slot is free and every step it runs `after` has finished
+ * (whatever its outcome: the constraint is ordering, not success).
+ *
+ * @param plans - The plan from `buildCheckPlan`, already filtered
+ * @param jobs - How many steps may run at once (at least 1)
+ * @param now - Clock, injectable for tests
+ */
+export declare function runCheckSteps(plans: readonly CheckStepPlan[], jobs: number, now?: () => number): Promise<CheckStepResult[]>;

package/dist/src/commands/check-run.js

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Runs the `fireforge check` plan: up to `jobs` steps at once, each as a
+ * child process in its own process group (so a timeout or a Ctrl+C takes
+ * the step's whole tree), honouring each step's `after` ordering.
+ */
+import { ExecTimeoutError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { execStream } from '../utils/process.js';
+/** Combined output kept per step: enough for a tail, bounded for a chatty audit. */
+const COMBINED_OUTPUT_CAP = 256 * 1024;
+/** Lines of output a failed step carries in its result. */
+const OUTPUT_TAIL_LINES = 40;
+function tailLines(text) {
+    const lines = text.trimEnd().split(/\r?\n/);
+    return lines.slice(-OUTPUT_TAIL_LINES).join('\n');
+}
+/** Runs one planned step to completion. Never throws. */
+async function runStep(plan, now) {
+    const base = { name: plan.name, kind: plan.kind, command: plan.display };
+    if (plan.skipReason !== undefined) {
+        return { ...base, status: 'skipped', exitCode: null, durationMs: 0, detail: plan.skipReason };
+    }
+    let stdout = '';
+    let combined = '';
+    const append = (chunk) => {
+        combined += chunk;
+        if (combined.length > COMBINED_OUTPUT_CAP)
+            combined = combined.slice(-COMBINED_OUTPUT_CAP);
+    };
+    const started = now();
+    try {
+        const exitCode = await execStream(plan.command, plan.args, {
+            cwd: plan.cwd,
+            processGroup: true,
+            ...(plan.timeoutMs !== undefined ? { timeout: plan.timeoutMs } : {}),
+            onStdout: (chunk) => {
+                stdout += chunk;
+                append(chunk);
+            },
+            onStderr: append,
+        });
+        const status = exitCode === 0 ? 'pass' : 'fail';
+        return {
+            ...base,
+            status,
+            exitCode,
+            durationMs: now() - started,
+            detail: plan.summarize({ stdout, combined, exitCode }),
+            ...(status === 'fail' ? { outputTail: tailLines(combined) } : {}),
+        };
+    }
+    catch (error) {
+        const timedOut = error instanceof ExecTimeoutError;
+        return {
+            ...base,
+            status: 'fail',
+            exitCode: null,
+            durationMs: now() - started,
+            detail: timedOut
+                ? `timed out after ${Math.round((plan.timeoutMs ?? 0) / 1000)}s`
+                : `could not start: ${toError(error).message}`,
+            ...(timedOut ? { timedOut: true } : {}),
+            outputTail: tailLines(combined),
+        };
+    }
+}
+/**
+ * Runs every step and returns the results in plan order. A step starts
+ * once a slot is free and every step it runs `after` has finished
+ * (whatever its outcome: the constraint is ordering, not success).
+ *
+ * @param plans - The plan from `buildCheckPlan`, already filtered
+ * @param jobs - How many steps may run at once (at least 1)
+ * @param now - Clock, injectable for tests
+ */
+export async function runCheckSteps(plans, jobs, now = Date.now) {
+    const names = new Set(plans.map((plan) => plan.name));
+    const results = new Map();
+    const pending = [...plans];
+    const running = new Map();
+    const isReady = (plan) => plan.after.every((dependency) => !names.has(dependency) || results.has(dependency));
+    while (pending.length > 0 || running.size > 0) {
+        for (let index = 0; index < pending.length && running.size < Math.max(1, jobs);) {
+            const plan = pending[index];
+            if (plan === undefined || !isReady(plan)) {
+                index++;
+                continue;
+            }
+            pending.splice(index, 1);
+            running.set(plan.name, runStep(plan, now).then((result) => {
+                results.set(plan.name, result);
+                running.delete(plan.name);
+            }));
+        }
+        if (running.size === 0)
+            break;
+        await Promise.race(running.values());
+    }
+    return plans.flatMap((plan) => {
+        const result = results.get(plan.name);
+        return result === undefined ? [] : [result];
+    });
+}

package/dist/src/commands/check-steps.d.ts

@@ -0,0 +1,67 @@
+import type { CheckConfig, FireForgeConfig } from '../types/config.js';
+/** One planned step. */
+export interface CheckStepPlan {
+    name: string;
+    kind: 'builtin' | 'extra';
+    /** Executable to spawn. */
+    command: string;
+    /** Its arguments. */
+    args: string[];
+    /** The command line as the table prints it. */
+    display: string;
+    cwd: string;
+    timeoutMs?: number | undefined;
+    /** Steps that must finish before this one starts (ordering only). */
+    after: string[];
+    /** Set when the step is planned but not run, with the reason. */
+    skipReason?: string | undefined;
+    /** Condenses a finished run into the table's detail cell. */
+    summarize: (output: {
+        stdout: string;
+        combined: string;
+        exitCode: number;
+    }) => string;
+}
+/** The project facts the plan depends on. */
+export interface CheckPlanInput {
+    projectRoot: string;
+    config: FireForgeConfig;
+    furnaceConfigured: boolean;
+    /** Resolved `--patches` filenames, forwarded to status, verify and lint. */
+    patches?: string[] | undefined;
+}
+/**
+ * The generic detail: nothing on success, and on failure the last line
+ * the step printed (its refusal, usually), cut to fit a table cell.
+ */
+export declare function lastOutputLine(combined: string, exitCode: number): string;
+/** Status detail from its `--json --summary` document: the failing classes. */
+export declare function summarizeStatus(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** Furnace detail from its `--json` document: counts after exceptions. */
+export declare function summarizeFurnace(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** Token-coverage detail: the coverage percentage it reports. */
+export declare function summarizeTokenCoverage(output: {
+    stdout: string;
+    combined: string;
+    exitCode: number;
+}): string;
+/** The status step's `--check` flags from `check.status`. */
+export declare function statusPolicyArgs(policy: CheckConfig['status']): string[];
+/**
+ * Builds the full plan: the six built-in steps (with the ones this project
+ * cannot run marked skipped) followed by `check.extraSteps[]`.
+ *
+ * `furnace-validate` waits for `typecheck`, the one built-in step that
+ * writes: it regenerates a stale Furnace jsconfig, whose drift
+ * `furnace validate` reports. Run side by side, the two would race on that
+ * file and the verdict would depend on which won.
+ */
+export declare function buildCheckPlan(input: CheckPlanInput): CheckStepPlan[];