@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/commands/test.js

@@ -1,18 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, resolve } from 'node:path';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
 import { hasBuildArtifacts, hasRunnableBundle } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
 import { assertMarionettePortAvailable, ensureLaunchableBrowserNotRunning, ensureMarionettePortAvailable, extractForwardedMarionettePort, forwardedMachArgsIncludeMarionetteClient, shouldAutoForwardMarionettePortToMach, } from '../core/marionette-port.js';
 import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionettePreflight, } from '../core/marionette-preflight.js';
+import { ensureMochitestServerPortAvailable } from '../core/mochitest-server-port.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
 import { assertObjdirMatchesTreeMarker } from '../core/tree-store.js';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, notice, outro, success, verbose } from '../utils/logger.js';
+import { info, intro, notice, outro, verbose } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { runTestBuildPhase } from './test-build-phase.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
@@ -36,8 +38,8 @@ async function assertTestPathsExist(engineDir, testPaths) {
  * Picks the mach dispatch target for a (non-mixed) run. A single-suite run
  * auto-routes to the suite-specific command (`mach xpcshell-test` /
  * `mach mochitest`), which degrades a broken host resource monitor to a
- * warning instead of crashing generic `mach test` at startup (E1). Mixed runs
- * are rejected before this point; a path-less "run all" or an explicit
+ * warning instead of crashing generic `mach test` at startup. Mixed runs are
+ * rejected before this point; a path-less "run all" or an explicit
  * `--generic-mach-test` opt-out stays on the generic command.
  */
 function resolveTestSuite(classification, forceGeneric) {
@@ -102,27 +104,30 @@ function logTestSelection(scopes) {
  */
 async function runDoctorPreflight(args) {
     const { engineDir, effectivePort, hasTestPaths, objDir, binaryName, launchablePath } = args;
-    // Write the "Running marionette preflight..." banner via
-    // `process.stdout.write` directly before `info()` so non-TTY captures
-    // always see the banner even if clack's renderer defers output in
-    // pipe mode. `info()` is still called so TTY users keep the normal
-    // clack box-drawing framing.
-    process.stdout.write('Running marionette preflight...\n');
-    info('Running marionette preflight...');
+    // Non-TTY captures need the banner even if clack's renderer defers output
+    // in pipe mode; TTY users need the clack framing. Gated rather than
+    // written twice — the unconditional pair printed the same line twice on a
+    // terminal.
+    if (process.stdout.isTTY) {
+        info('Running marionette preflight...');
+    }
+    else {
+        process.stdout.write('Running marionette preflight...\n');
+    }
     const preflight = effectivePort !== undefined
         ? await runMarionettePreflight(engineDir, { port: effectivePort })
         : await runMarionettePreflight(engineDir);
-    // 2026-04-24 eval Finding 7: the pre-0.18.1 code used
-    // `success()` + `outro()` + a direct `process.stdout.write` as a
-    // belt-and-suspenders but still reproducibly dropped the PASS summary
-    // under non-TTY capture (observed: `tee`-wrapped eval output saw only
-    // the intro). The fix writes the authoritative PASS/FAIL line via
-    // `process.stdout.write` as the very first output after the probe
-    // returns, so the captured stream has an unambiguous summary no
-    // matter what clack does on top. The clack-rendered banner
-    // (`info`/`warn`) is retained so TTY users keep the visual framing.
+    // The authoritative PASS/FAIL line is written with `process.stdout.write`
+    // as the first output after the probe returns, because clack's renderer
+    // can drop the summary under non-TTY capture.
+    //
+    // Gated on non-TTY: unconditional, it stacks with the two clack renderings
+    // below and the same line appears THREE times on a terminal. Captured
+    // streams are exactly where this branch still fires.
     const directLine = formatMarionettePreflightLine(preflight);
-    process.stdout.write(`${directLine}\n`);
+    if (!process.stdout.isTTY) {
+        process.stdout.write(`${directLine}\n`);
+    }
     process.stdout.write(`Marionette preflight environment: objdir=${objDir ?? '(none)'}; binary=${binaryName}; app=${launchablePath ? `engine/${launchablePath}` : '(unknown)'}; port=${effectivePort ?? 2828}; elapsed=${preflight.durationMs}ms\n`);
     reportMarionettePreflight(preflight);
     if (!hasTestPaths) {
@@ -130,7 +135,6 @@ async function runDoctorPreflight(args) {
             emitFailVerdict('preflight');
             throw new GeneralError('Marionette preflight reported FAIL — see output above.');
         }
-        success(directLine);
         // Doctor-only runs end here, so they carry their own verdict line
         // (reason=preflight on failure); with test paths the verdict comes
         // from the actual harness run downstream.
@@ -152,19 +156,19 @@ async function runDoctorPreflight(args) {
  * Mutates `extraArgs` in place.
  */
 function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly = false) {
-    // Auto-forward the Marionette port to mach when `--marionette-port` is
-    // set. `--setpref=marionette.port=<n>` configures where the browser
-    // listener binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness
-    // client to connect there (default client is 127.0.0.1:2828). xpcshell
-    // ignores both for browser Marionette.
+    // Auto-forward the Marionette port to mach when `--marionette-port` is set.
+    // `--setpref=marionette.port=<n>` configures where the browser listener
+    // binds; `--marionette=127.0.0.1:<n>` tells the mochitest harness client to
+    // connect there (default client is 127.0.0.1:2828). xpcshell ignores both
+    // for browser Marionette.
     //
     // Skip setpref forwarding when the operator already supplied an equivalent
-    // arg via `--mach-arg` — duplicates would be confusing without changing
-    // semantics. Skip when mach args explicitly request `--flavor=xpcshell`
-    // (or `xpcshell-tests`): the preflight still honours `--marionette-port`,
-    // but mach does not use the marionette.port pref on that harness. Any
-    // other arg shape still forwards so toolkit widget paths and mixed suites
-    // stay aligned with the probe without duplicate `--mach-arg` flags.
+    // arg via `--mach-arg` — duplicates would confuse without changing
+    // semantics. Skip when mach args explicitly request `--flavor=xpcshell` (or
+    // `xpcshell-tests`): the preflight still honours `--marionette-port`, but
+    // mach does not use the marionette.port pref on that harness. Any other arg
+    // shape still forwards so toolkit widget paths and mixed suites stay
+    // aligned with the probe without duplicate `--mach-arg` flags.
     //
     // Skip auto `--marionette=...` when `--mach-arg` already includes a client
     // `--marionette=...` (or two-token `--marionette host:port`).
@@ -172,9 +176,8 @@ function appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcsh
         return;
     if (xpcshellOnly) {
         // Manifest classification says every requested path is xpcshell —
-        // xpcshell ignores the browser Marionette path entirely, and the
-        // mochitest client flags previously forwarded here made mach reject
-        // the dispatch.
+        // xpcshell ignores the browser Marionette path entirely, and forwarding
+        // the mochitest client flags here makes mach reject the dispatch.
         info(`--marionette-port=${options.marionettePort} applied to the preflight probe only: the requested paths are xpcshell-only, and xpcshell ignores the browser Marionette port. Not forwarding --setpref=marionette.port or --marionette to mach.`);
         return;
     }
@@ -201,8 +204,8 @@ async function ensureTestMarionettePortAvailable(port, binaryName, options, skip
     // This also recognizes a fork-branded browser via binaryName.
     if (skip.xpcshellOnly && !skip.doctor) {
         // xpcshell does not bind the browser Marionette port, so a developer's
-        // interactive browser holding 2828 must not kill an xpcshell run
-        //. --doctor keeps the preflight: its probe launches a
+        // interactive browser holding 2828 must not kill an xpcshell run.
+        // --doctor keeps the preflight: its probe launches a
         // Marionette browser regardless of the requested harness.
         const message = 'Skipping the Marionette stale-port preflight: all requested paths are xpcshell ' +
             '(xpcshell does not bind the browser Marionette port).';
@@ -229,6 +232,15 @@ async function ensureTestBrowserEnvironment(engineDir, launchablePath, xpcshellO
             killStaleBrowser: options.killStaleMarionette === true,
         });
     }
+    // A zombie mochitest httpd squatting the server port makes a fresh
+    // browser connect to a server that cannot serve this run's manifest,
+    // which surfaces as a 370s "Ran 0 checks" stall naming nothing. xpcshell
+    // does not use the httpd, so an xpcshell-only run is never blocked by it.
+    if (!xpcshellOnly) {
+        await ensureMochitestServerPortAvailable(undefined, {
+            killStaleServer: options.killStaleMarionette === true,
+        });
+    }
     const forwardedPort = options.machArg
         ? extractForwardedMarionettePort(options.machArg)
         : undefined;
@@ -292,9 +304,7 @@ async function verifyEngineGenerationOrEmitInconclusive(engineDir, before) {
 async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
+    await assertEngineExists(paths.engine);
     assertPathlessTestMode(testPaths, options);
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, TEST_BUILD_PREFLIGHT);
@@ -307,14 +317,14 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const projectConfig = await loadConfig(projectRoot);
     const canaryPath = resolveCanaryPath(options, projectConfig);
     assertTestModeCombinations(testPaths, options, canaryPath);
-    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial
-    // build (linker failed, packaging step interrupted, etc.) can satisfy
-    // that check without ever writing the launchable binary the marionette
-    // preflight needs to spawn. `fireforge run` already uses
-    // `hasRunnableBundle` to fail fast with a precise message; mirror that
-    // here so `test --doctor` against an incomplete build surfaces the
-    // missing-bundle path instead of a cryptic `Browser process exited
-    // during spawn (exit code 1, signal none). stderr tail: (empty)`.
+    // `hasBuildArtifacts` only confirms `obj-*/dist/` exists; a partial build
+    // (linker failed, packaging step interrupted) can satisfy that check
+    // without ever writing the launchable binary the marionette preflight
+    // needs to spawn. `fireforge run` already uses `hasRunnableBundle` to fail
+    // fast with a precise message; mirroring it here makes `test --doctor`
+    // against an incomplete build surface the missing-bundle path instead of a
+    // cryptic `Browser process exited during spawn (exit code 1, signal none).
+    // stderr tail: (empty)`.
     const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
     const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
     // Normalized engine-relative request paths, hoisted above the build/stale
@@ -338,9 +348,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     //   3. fall back to `DEFAULT_MARIONETTE_PORT` semantics inside the probes
     //      (passed as `undefined`).
     // Without (2), an operator working around a stale listener via the
-    // documented `--mach-arg --marionette-port=NNNN` workaround would still
-    // hit the wrapper preflight refusing on 2828 before the forwarded arg
-    // ever reached mach.
+    // documented `--mach-arg --marionette-port=NNNN` route still hits the
+    // wrapper preflight refusing on 2828 before the forwarded arg reaches
+    // mach.
     const { forwardedPort, effectivePort } = await ensureTestBrowserEnvironment(paths.engine, launchablePath, xpcshellOnly, projectConfig.binaryName, options);
     if (options.doctor) {
         const doctorOutcome = await runDoctorPreflight({
@@ -371,7 +381,7 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     }
     // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
     // flags FireForge does not model directly (see the xpcshell appdir hint
-    // above for the motivating case). Appended AFTER --headless so mach sees
+    // above for why). Appended AFTER --headless so mach sees
     // the FireForge-managed flags first and the escape-valve ones last, which
     // keeps the override precedence predictable.
     if (forwardedMachArgs.length > 0) {
@@ -380,16 +390,14 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     appendMarionetteForwardingArgs(extraArgs, options, forwardedPort, xpcshellOnly);
     // Directory arguments mean EXACTLY that directory: mozbuild's test
     // resolver matches paths by string prefix, so a bare directory arg
-    // silently swept in prefix-named siblings (152.0b7 → 153.0b8 drill:
-    // `…/test/hominis` also ran `…/test/hominis-tiles`, 1224 tests instead
-    // of ~200, with no indication the scope widened). Each directory
-    // argument dispatches as its enumerated explicit test-file list — a
-    // file list cannot prefix-match a sibling (0.35.0's trailing-`/`
-    // normalization turned out to be cosmetic on Firefox 153's mach; field
-    // verification showed the sibling still ran while the echo claimed it
-    // was excluded). Any prefix-siblings are echoed so the narrowed scope
-    // is visible. Classification above intentionally used the raw
-    // argument forms; only the mach dispatch needs the exact-match shape.
+    // silently sweeps in prefix-named siblings — `…/test/hominis` also running
+    // `…/test/hominis-tiles`, with no indication the scope widened. Each
+    // directory argument therefore dispatches as its enumerated explicit
+    // test-file list, which cannot prefix-match a sibling; a trailing-`/`
+    // normalization does not work, as mach still sweeps the sibling in. Any
+    // prefix-siblings are echoed so the narrowed scope is visible.
+    // Classification above intentionally used the raw argument forms; only the
+    // mach dispatch needs the exact-match shape.
     const scopes = await analyzeTestPathScopes(paths.engine, normalizedPaths);
     const dispatchGroups = scopes.map((scope) => ({
         label: scope.requestedPath,
@@ -419,17 +427,16 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     const postRebuildContext = options.build
         ? createPostRebuildFailureContext('fireforge test --build', normalizedPaths)
         : undefined;
-    // Multi-argument requests shard into sequential harness runs by default
-    // (field report C3): one shared mochitest profile across files bleeds
-    // pref/media-query state into later files. Sharding is per path
-    // ARGUMENT — a directory argument keeps its enumerated files together
-    // in one invocation, preserving the one-browser-instance semantics of
-    // a directory run. --no-shard restores the combined invocation. The
-    // default must not be SILENT (drill finding: a two-file cross-file
-    // pollution repro "passed" because the headed comparison run was
-    // sharded without saying so, briefly misattributing a suite-context
-    // bug to an upstream headless regression), so a one-line notice states
-    // what sharding does and does not exercise.
+    // Multi-argument requests shard into sequential harness runs by default:
+    // one shared mochitest profile across files bleeds pref/media-query state
+    // into later files. Sharding is per path ARGUMENT — a directory argument
+    // keeps its enumerated files together in one invocation, preserving the
+    // one-browser-instance semantics of a directory run. `--no-shard` restores
+    // the combined invocation. The default must not be SILENT: a cross-file
+    // pollution repro otherwise "passes" because the comparison run was
+    // sharded without saying so, misattributing a suite-context bug upstream.
+    // Hence the one-line notice stating what sharding does and does not
+    // exercise.
     if (canaryPath === undefined && dispatchGroups.length > 1 && options.shard !== false) {
         notice(`Sharding: running ${dispatchGroups.length} test path arguments in isolated browser instances ` +
             '(one mach invocation per argument; a directory argument keeps its files in one instance). ' +
@@ -468,9 +475,9 @@ async function runTestCommandBody(projectRoot, testPaths, options = {}) {
     finalizeSingleRunOutcome(outcome, normalizedPaths, projectConfig.binaryName, postRebuildContext, options.headless === true);
 }
 /**
- * Builds the perf-sample env contract for the harness run (field report
- * C4): `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON`
- * naming the artifact file a budget checker consumes after the run.
+ * Builds the perf-sample env contract for the harness run:
+ * `--perf-samples <path>` exports `<BINARYNAME>_PERF_SAMPLE_JSON` naming the
+ * artifact file a budget checker consumes after the run.
  */
 function buildPerfSampleEnv(projectRoot, binaryName, perfSamples) {
     if (!perfSamples)

package/dist/src/commands/token-coverage.js

@@ -34,10 +34,9 @@ export async function tokenCoverageCommand(projectRoot) {
         .map((f) => f.file);
     // Also scan CSS files deployed by Furnace custom components. Deployed
     // files can be committed (and therefore absent from `git status`) while
-    // still being the primary surface where token adoption matters. Before
-    // 0.16.0, coverage only looked at modified files, which silently
-    // undercounted projects where Furnace writes many component-CSS files
-    // into the engine and they are already tracked.
+    // still being the primary surface where token adoption matters; looking
+    // only at modified files silently undercounts projects where Furnace
+    // writes many component-CSS files into the engine.
     const furnaceCssFiles = await collectFurnaceCustomCssFiles(projectRoot, paths.engine, tokensCssPath);
     // De-dupe so a file that is both a custom deploy target AND modified is
     // scanned exactly once.

package/dist/src/commands/token.js

@@ -2,7 +2,7 @@
 import { Command, Option } from 'commander';
 import { loadConfig } from '../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../core/furnace-config.js';
-import { addToken, getTokensCssPath, validateTokenAdd, } from '../core/token-manager.js';
+import { addToken, getTokensCssPath, isTokenMode, TOKEN_MODES, validateTokenAdd, } from '../core/token-manager.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
@@ -45,13 +45,12 @@ async function normalizeTokenNameForProject(projectRoot, rawTokenName) {
  */
 export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     intro('Token Add');
-    // Finding #15: a fresh project without furnace.json failed deep inside
-    // the token-manager's `assertTokenCategoryExists` with "Token CSS file
-    // not found: browser/themes/shared/<binary>-tokens.css" — technically
-    // correct, but the operator's actual next step is to initialize
-    // Furnace (which scaffolds the tokens CSS file among other things).
-    // Catching the uninitialized case here gives the right guidance up-
-    // front before the generic "file not found" error fires.
+    // A fresh project without furnace.json otherwise fails deep inside the
+    // token-manager's `assertTokenCategoryExists` with "Token CSS file not
+    // found: browser/themes/shared/<binary>-tokens.css" — technically correct,
+    // but the operator's actual next step is to initialize Furnace, which
+    // scaffolds the tokens CSS file. Catching the uninitialized case here
+    // gives the right guidance before the generic "file not found" error.
     if (!(await furnaceConfigExists(projectRoot))) {
         throw new FurnaceError('Token management requires Furnace to be initialized. ' +
             'Tokens live in the Furnace-managed tokens CSS file, which `fireforge furnace init` scaffolds alongside the rest of the Furnace workspace.\n\n' +
@@ -60,10 +59,10 @@ export async function tokenAddCommand(projectRoot, tokenName, value, options) {
     // Normalize token name using the configured Furnace token prefix when the
     // user supplied a bare token name like "canvas-gap".
     tokenName = await normalizeTokenNameForProject(projectRoot, tokenName);
-    // Validate mode
-    const validModes = ['auto', 'static', 'override'];
-    if (!validModes.includes(options.mode)) {
-        throw new InvalidArgumentError(`Invalid mode "${options.mode}". Must be one of: ${validModes.join(', ')}`, 'mode');
+    // Validate mode. The guard IS the runtime proof, so the three `as
+    // TokenMode` casts this replaced are gone with it.
+    if (!isTokenMode(options.mode)) {
+        throw new InvalidArgumentError(`Invalid mode "${options.mode}". Must be one of: ${TOKEN_MODES.join(', ')}`, 'mode');
     }
     if (options.dryRun) {
         await validateTokenAdd(projectRoot, {
@@ -131,12 +130,11 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
     const token = program
         .command('token')
         .description('Design token management')
-        // Match `fireforge furnace`'s no-args contract: print the group's help and
-        // exit 0. Without this default action, commander routes `fireforge token`
-        // (no subcommand) through its own help-then-exit-1 path, so scripts that
-        // probe the CLI surface see a misleading non-zero exit for a purely
-        // informational invocation. The action prints the exact same help commander
-        // would otherwise print, but returns successfully.
+        // Match `fireforge furnace`'s no-args contract: print the group's help
+        // and exit 0. Without this default action, commander routes
+        // `fireforge token` (no subcommand) through its own help-then-exit-1
+        // path, so scripts probing the CLI surface see a misleading non-zero
+        // exit for a purely informational invocation.
         .action(() => {
         token.outputHelp();
     });

package/dist/src/commands/tree.js

@@ -2,21 +2,23 @@
 /**
  * `fireforge tree` — copy-on-write verification clones.
  *
- * Trees enable concurrent READ-MOSTLY verification (lint, typecheck,
- * status, verify, doctor, export dry-runs) beside a busy primary tree.
- * Exports and every other mutation stay strictly serial in the primary —
- * a tree's patches/components are snapshots with no merge model, and the
- * tree guard (cli.ts preAction + core/tree-guard.ts) refuses mutating
- * commands inside a tree. `create --with-objdir` additionally clones the
- * primary's built obj-* directory, rewrites its mozinfo.json to the
- * tree, and runs `mach configure` inside the tree so the remaining
- * configure output (config.status, backend.mk, Makefile,
- * config/autoconf.mk — the verified set) stops naming the primary
- * (fail-closed — mach objdirs embed absolute source paths, and an
- * unrelocated clone would silently operate against the primary), which
- * is what admits build-less `fireforge test` inside that tree.
+ * Trees enable concurrent READ-MOSTLY verification (lint, typecheck, status,
+ * verify, doctor, export dry-runs) beside a busy primary tree. Exports and
+ * every other mutation stay strictly serial in the primary — a tree's
+ * patches/components are snapshots with no merge model, and the tree guard
+ * (cli.ts preAction + core/tree-guard.ts) refuses mutating commands inside a
+ * tree.
+ *
+ * `create --with-objdir` additionally clones the primary's built obj-*
+ * directory, rewrites its mozinfo.json to the tree, and runs `mach configure`
+ * inside the tree so the remaining configure output (config.status,
+ * backend.mk, Makefile, config/autoconf.mk) stops naming the primary. That is
+ * fail-closed by design — mach objdirs embed absolute source paths, and an
+ * unrelocated clone would silently operate against the primary — and it is
+ * what admits build-less `fireforge test` inside that tree.
  */
 import { spawn } from 'node:child_process';
+import { mkdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Command } from 'commander';
 import { withEngineSessionLock } from '../core/engine-session-lock.js';
@@ -24,11 +26,13 @@ import { hasBuildArtifacts, runMach, withBuildLock } from '../core/mach.js';
 import { assertBuildArtifacts, findObjdirRelocationViolation, } from '../core/mach-build-artifacts.js';
 import { detectCowSupport } from '../core/tree-cow.js';
 import { cloneTree, listTrees, removeTree } from '../core/tree-store.js';
-import { assertValidTreeName, computePrimaryFingerprint, getTreeMarkerPath, getTreesDir, readTreeMarkerState, withTreeLifecycleLock, } from '../core/tree-store.js';
-import { GeneralError } from '../errors/base.js';
+import { assertValidTreeName, computePrimaryFingerprint, getTreeMarkerPath, getTreesDir, readTreeMarker, withTreeLifecycleLock, } from '../core/tree-store.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, outro, setMachineOutputMode, setStdoutSealed, success, warn, } from '../utils/logger.js';
+import { emitMachineError, MACHINE_OUTPUT_SCHEMA_VERSION } from '../utils/machine-output.js';
 import { addWaitLockOption, resolveWaitLockSeconds } from '../utils/options.js';
 function assertPosix() {
     if (process.platform === 'win32') {
@@ -100,7 +104,7 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
     // A marker we cannot parse still means "something claims this is a tree", so
     // it must block nesting too — otherwise a corrupt marker is a licence to
     // clone a snapshot into itself.
-    const markerState = await readTreeMarkerState(projectRoot);
+    const markerState = await readTreeMarker(projectRoot);
     if (markerState.kind !== 'absent') {
         throw new GeneralError(markerState.kind === 'valid'
             ? 'Verification trees cannot be nested: run tree create in the primary tree.'
@@ -113,7 +117,6 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
         if (await pathExists(treeRoot)) {
             throw new GeneralError(`A tree named "${name}" already exists. Remove it first (fireforge tree remove ${name}) — refresh is remove + create.`);
         }
-        const { mkdir } = await import('node:fs/promises');
         await mkdir(treesDir, { recursive: true });
         const capability = await detectCowSupport(treesDir);
         if (capability === 'none' && options.forceCopy !== true) {
@@ -162,7 +165,6 @@ export async function treeCreateCommand(projectRoot, name, options = {}) {
                     : await clone();
             }
             catch (error) {
-                const { rm } = await import('node:fs/promises');
                 await rm(treeRoot, { recursive: true, force: true });
                 throw error;
             }
@@ -184,9 +186,21 @@ export async function treeListCommand(projectRoot, options = {}) {
         // any diagnostic — including a listTrees failure rendered later by
         // withErrorHandling, which also resets the mode — routes to stderr.
         setMachineOutputMode(true);
-        const trees = await listTrees(projectRoot);
-        process.stdout.write(`${JSON.stringify({ schemaVersion: 1, trees }, null, 2)}\n`);
-        setMachineOutputMode(false);
+        try {
+            const trees = await listTrees(projectRoot);
+            process.stdout.write(`${JSON.stringify({ schemaVersion: MACHINE_OUTPUT_SCHEMA_VERSION, trees }, null, 2)}\n`);
+            // Payload written: stdout is now spoken for. See docs/machine-output.md.
+            setStdoutSealed(true);
+        }
+        catch (error) {
+            // Same failure envelope `status --json` emits. Without it a scripted
+            // consumer got a parseable refusal from one command and a bare
+            // non-zero exit from the other. See docs/machine-output.md.
+            emitMachineError('tree-list-failed', toError(error).message);
+        }
+        finally {
+            setMachineOutputMode(false);
+        }
         return;
     }
     const trees = await listTrees(projectRoot);
@@ -206,7 +220,7 @@ export async function treeRemoveCommand(projectRoot, name, options = {}) {
     assertPosix();
     intro('FireForge Tree Remove');
     if (options.all !== true && name === undefined) {
-        throw new GeneralError('Pass a tree name, or --all to remove every tree.');
+        throw new InvalidArgumentError('Pass a tree name, or --all to remove every tree.', '--all');
     }
     await withTreeLifecycleLock(projectRoot, async () => {
         const targets = options.all === true ? (await listTrees(projectRoot)).map((t) => t.name) : [name ?? ''];
@@ -226,7 +240,7 @@ async function treeExecCommand(projectRoot, name, args) {
     assertPosix();
     assertValidTreeName(name);
     const treeRoot = join(getTreesDir(projectRoot), name);
-    const state = await readTreeMarkerState(treeRoot);
+    const state = await readTreeMarker(treeRoot);
     if (state.kind === 'corrupt') {
         // Collapsing corrupt into "no such tree" misdiagnoses: the directory IS
         // there, claiming to be a tree, and "no tree named X" points the operator
@@ -237,6 +251,9 @@ async function treeExecCommand(projectRoot, name, args) {
     if (state.kind === 'absent') {
         throw new GeneralError(`No verification tree named "${name}". List trees with: fireforge tree list`);
     }
+    if (state.kind === 'unsupported') {
+        throw new GeneralError(`Cannot inspect tree "${name}": ${state.reason}`);
+    }
     const marker = state.marker;
     const current = await computePrimaryFingerprint(projectRoot);
     if (marker.engineHead !== current.engineHead) {
@@ -263,14 +280,13 @@ async function treeExecCommand(projectRoot, name, args) {
             resolvePromise(code ?? 1);
         });
     }).finally(() => {
-        // With `stdio: 'inherit'` the child owned stdout — including
-        // any FIREFORGE-VERDICT line it emitted as its LAST stdout write. From
-        // here on the parent must not write stdout again, or its own refusal
-        // text (the GeneralError below rendered by withErrorHandling) would
-        // print AFTER the child's verdict and break the "verdict is the run's
-        // last stdout line" contract at the tree-exec boundary. Sealing routes
-        // the parent's remaining output to stderr; withErrorHandling's finally
-        // clears the seal.
+        // With `stdio: 'inherit'` the child owned stdout — including any
+        // FIREFORGE-VERDICT line it emitted as its LAST stdout write. From here
+        // on the parent must not write stdout again, or its own refusal text
+        // (the GeneralError below, rendered by withErrorHandling) prints AFTER
+        // the child's verdict and breaks the "verdict is the run's last stdout
+        // line" contract at the tree-exec boundary. Sealing routes the parent's
+        // remaining output to stderr; withErrorHandling's finally clears it.
         setStdoutSealed(true);
     });
     if (exitCode !== 0) {

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

@@ -1,18 +1,16 @@
 /**
- * `fireforge typecheck` — whole-project TypeScript type checking
- * driven by user-supplied jsconfig.json paths.
+ * `fireforge typecheck` — whole-project TypeScript type checking driven by
+ * user-supplied jsconfig.json paths.
  *
- * Distinct from `patchLint.checkJs`: that pass is patch-hygiene
- * (scoped to patch-owned `.sys.mjs`, run automatically by
- * `fireforge lint`); this command is CI-grade — it runs whole
- * projects with the user's own compiler options and is intended as
- * a CI gate. The two share their Firefox-globals shim and the same
- * suppressed-diagnostic set so a file that lints clean cannot fail
- * typecheck for a reason the operator could not have inferred from
- * the docs.
+ * Distinct from `patchLint.checkJs`: that pass is patch-hygiene (scoped to
+ * patch-owned `.sys.mjs`, run automatically by `fireforge lint`); this
+ * command is CI-grade — it runs whole projects with the user's own compiler
+ * options. The two share their Firefox-globals shim and the same
+ * suppressed-diagnostic set so a file that lints clean cannot fail typecheck
+ * for a reason the operator could not have inferred from the docs.
  *
- * Exits non-zero on any error-severity diagnostic. Warnings print
- * but do not fail. Designed for CI use.
+ * Exits non-zero on any error-severity diagnostic. Warnings print but do not
+ * fail.
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';