@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/commands/run.js

@@ -4,6 +4,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Command } from 'commander';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
 import { hasBuildArtifacts, hasRunnableBundle, run, runMachSmoke } from '../core/mach.js';
 import { assertBuildArtifacts } from '../core/mach-build-artifacts.js';
@@ -78,9 +79,7 @@ export async function runCommand(projectRoot, options = {}) {
     intro('FireForge Run');
     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);
     const buildCheck = await hasBuildArtifacts(paths.engine);
     assertBuildArtifacts(paths.engine, buildCheck, {
         label: 'Run',
@@ -88,16 +87,14 @@ export async function runCommand(projectRoot, options = {}) {
         remediation: "Run 'fireforge build' first, then rerun 'fireforge run'.",
         requireExisting: true,
     });
-    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a
-    // build that configured but hasn't yet produced the launchable binary
-    // (common in a long real Firefox compile that the operator stopped
-    // and restarted) passes that check, and `mach run` then fails on the
-    // missing binary path. `hasRunnableBundle` narrows the probe to the
-    // actual executable so `fireforge run` refuses with a targeted
-    // message before handing control to mach. `fireforge watch` stays
-    // permissive and instead surfaces the same information as a banner
-    // suffix; watch is supposed to drive rebuilds of partially-built
-    // trees, so blocking there would defeat the feature.
+    // `hasBuildArtifacts` only checks for an `obj-*/dist/` directory; a build
+    // that configured but has not yet produced the launchable binary passes
+    // that check, and `mach run` then fails on the missing binary path.
+    // `hasRunnableBundle` narrows the probe to the actual executable so
+    // `fireforge run` refuses with a targeted message before handing control
+    // to mach. `fireforge watch` stays permissive and surfaces the same
+    // information as a banner suffix; watch exists to drive rebuilds of
+    // partially-built trees, so blocking there would defeat it.
     if (buildCheck.objDir) {
         const config = await loadConfig(projectRoot);
         const bundleCheck = await hasRunnableBundle(paths.engine, config.binaryName, buildCheck.objDir);
@@ -142,7 +139,7 @@ async function runSmokeExit(engineDir, options) {
     // SIGTERM the whole mach → python → firefox tree. Running through anyway
     // would only kill the top-level wrapper and orphan Firefox content
     // processes, so reject the flag up front to match the documented contract
-    // in CHANGELOG.md / README.md.
+    // in the README.
     if (process.platform === 'win32') {
         throw new InvalidArgumentError('--smoke-exit is POSIX-only; process-group semantics do not map cleanly onto Windows.', 'smokeExit');
     }
@@ -187,14 +184,13 @@ async function runSmokeExit(engineDir, options) {
         const sink = stream === 'stdout' ? process.stdout : process.stderr;
         sink.write(`${line}\n`);
         // Count allowlist hits up-front, regardless of error-pattern match.
-        // Pre-0.16.0 the counter only incremented when the line ALSO matched
-        // an error pattern — so an allowlist regex that visibly matched
-        // `console.warn: RSLoader:` still reported 0 hits because
-        // `console.warn:` is not a smoke error class, confusing operators
-        // who were tuning their allowlist. We now surface two numbers: the
-        // total set of allowlisted lines (what the operator sees in the
-        // console) and the subset that were error-class (what the smoke
-        // exit contract cares about). The exit contract itself is unchanged.
+        // Incrementing only when the line ALSO matches an error pattern makes an
+        // allowlist regex that visibly matches `console.warn: RSLoader:` report 0
+        // hits, because `console.warn:` is not a smoke error class — confusing
+        // for operators tuning their allowlist. Two numbers are surfaced: the
+        // total set of allowlisted lines (what the operator sees in the console)
+        // and the subset that were error-class (what the smoke exit contract
+        // cares about). The exit contract itself is unchanged.
         const matchIndex = allowlist.length > 0 ? matchAllowlist(line, allowlist) : -1;
         const isAllowlisted = matchIndex !== -1;
         if (isAllowlisted) {
@@ -209,12 +205,12 @@ async function runSmokeExit(engineDir, options) {
         }
         findings.push({ stream, line });
     };
-    // A headed smoke window on a developer desktop absorbs live input:
-    // during the drill a human interacted with the window mid-run, the
-    // password-manager import scan probed an unreadable Chrome profile
-    // dir, and the resulting console errors failed the smoke run looking
-    // like a product regression. CI hosts (CI env var set) are assumed
-    // display-free/unattended, so the notice stays quiet there.
+    // A headed smoke window on a developer desktop absorbs live input: a human
+    // interacting with the window mid-run can trigger console errors — a
+    // password-manager import scan probing an unreadable profile dir, say —
+    // that fail the smoke run looking like a product regression. CI hosts (CI
+    // env var set) are assumed display-free and unattended, so the notice
+    // stays quiet there.
     if (!options.headless && !process.env['CI']) {
         warn('Headed smoke window: keyboard/mouse input during the window will contaminate the ' +
             'console capture and can fail the run. Pass --headless (or run on an unattended host) ' +
@@ -303,12 +299,11 @@ function reportSmokeSummary(args) {
     info('');
     info(`Smoke run complete: ${seconds}s elapsed of ${windowSeconds}s window${suffix}`);
     info(`  Unallowed errors: ${String(args.findings.length)}`);
-    // The "suppressed errors" count is what the exit contract cares about —
-    // it is the subset of allowlisted hits that would otherwise have been
-    // tallied as findings. The "all allowlisted lines" count answers the
-    // operator's mental model ("my --console-allow pattern matched N
-    // console lines"), which pre-0.16.0 was missing and led to 0-hit
-    // reports on visibly matching regexes.
+    // The "suppressed errors" count is what the exit contract cares about — the
+    // subset of allowlisted hits that would otherwise have been tallied as
+    // findings. The "all allowlisted lines" count answers the operator's mental
+    // model ("my --console-allow pattern matched N console lines"), without
+    // which a visibly matching regex reports 0 hits.
     info(`  Allowlisted error hits (suppressed): ${String(args.allowlistedErrorHits)}`);
     info(`  Allowlisted lines total: ${String(args.allowlistedTotalHits)}`);
     info(`  Child exit code:  ${String(args.exitCode)}`);
@@ -351,7 +346,10 @@ export function registerRun(program, { getProjectRoot, withErrorHandling }) {
         .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored.')
         .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
         .option('--headless', 'Launch the browser with --headless. Recommended for --smoke-exit on a shared desktop: input into a headed smoke window contaminates the console capture.')
-        .action(withErrorHandling(async (options) => {
+        .action(withErrorHandling(
+    // `args` is the variadic positional, not a Commander flag, so it
+    // never appears in this object.
+    async (options) => {
         await runCommand(getProjectRoot(), pickDefined(options));
     }));
 }

package/dist/src/commands/setup-support.js

@@ -8,7 +8,7 @@ import { CancellationError, InvalidArgumentError } from '../errors/base.js';
 import { ensureDir, pathExists, readText, writeText } from '../utils/fs.js';
 import { cancel } from '../utils/logger.js';
 import { getPackageRoot } from '../utils/package-root.js';
-import { inferProductFromVersion, isValidAppId, isValidFirefoxVersion, isValidProjectLicense, } from '../utils/validation.js';
+import { FIREFOX_PRODUCTS, inferProductFromVersion, isValidAppId, isValidFirefoxProduct, isValidFirefoxVersion, isValidProjectLicense, } from '../utils/validation.js';
 function getTemplatesDir() {
     return join(getPackageRoot(), 'templates');
 }
@@ -19,13 +19,13 @@ function renderLicenseTemplate(license, template, vendor, now = new Date()) {
     return template.replace(/\[year\]/g, String(now.getFullYear())).replace(/\[fullname\]/g, vendor);
 }
 function resolveFirefoxProduct(value, field) {
-    if (value === 'firefox' ||
-        value === 'firefox-esr' ||
-        value === 'firefox-beta' ||
-        value === 'firefox-devedition') {
+    // Matches the sibling `resolveProjectLicense`, which already delegates to
+    // its guard. The `||` chain this replaced spelled the member list twice —
+    // once as the predicate and once in the message.
+    if (typeof value === 'string' && isValidFirefoxProduct(value)) {
         return value;
     }
-    throw new InvalidArgumentError('Invalid product (use: firefox, firefox-esr, firefox-beta, firefox-devedition)', field);
+    throw new InvalidArgumentError(`Invalid product (use: ${FIREFOX_PRODUCTS.join(', ')})`, field);
 }
 function resolveProjectLicense(value, field) {
     if (typeof value === 'string' && isValidProjectLicense(value)) {
@@ -269,14 +269,11 @@ export function buildSetupConfig(inputs) {
 }
 /**
  * Creates or updates the root `package.json` so its `license` field matches
- * the project license selected during setup. When the file already exists we
- * ONLY touch the `license` field — preserving `name`, `description`,
- * `dependencies`, `scripts`, and every other author-editorial field the
- * operator may have added. Without this sync, a `fireforge setup --force`
- * that picked a new license left the old license in `package.json`, which
- * then disagreed with `fireforge.json` (the motivating eval finding:
- * setup rewrote fireforge.json but left the original package.json
- * untouched, so the two files described different projects).
+ * the project license selected during setup. When the file already exists
+ * ONLY the `license` field is touched — preserving `name`, `description`,
+ * `dependencies`, `scripts`, and every other author-editorial field. Without
+ * this sync, a `fireforge setup --force` that picks a new license leaves the
+ * old one in `package.json`, so the two files describe different projects.
  *
  * Preserves the file's trailing newline state so a hand-edited
  * `package.json` with a specific EOL convention is not silently
@@ -307,12 +304,11 @@ async function syncRootPackageJson(projectRoot, license) {
     if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
         return;
     }
-    // Treat the object as a typed shape with only the one field we modify.
+    // Treat the object as a typed shape with only the one field modified.
     // Keeping it narrowly typed rather than `Record<string, unknown>` avoids
-    // eslint's `dot-notation` / `noPropertyAccessFromIndexSignature`
-    // friction, and the rest of the package.json body is preserved via
-    // object spread at the write site so we don't lose author-editorial
-    // fields.
+    // eslint's `dot-notation` / `noPropertyAccessFromIndexSignature` friction,
+    // and the rest of the package.json body is preserved via object spread at
+    // the write site.
     const packageJson = parsed;
     if (packageJson.license === license) {
         return;

package/dist/src/commands/setup.js

@@ -3,10 +3,11 @@ import { resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { Command, Option } from 'commander';
 import { configExists } from '../core/config.js';
+import { stdioIsInteractive } from '../core/destructive.js';
 import { ConfigError } from '../errors/config.js';
 import { cancel, intro, isCancel, note, outro, spinner } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
-import { PROJECT_LICENSES } from '../utils/validation.js';
+import { FIREFOX_PRODUCTS, PROJECT_LICENSES } from '../utils/validation.js';
 import { buildSetupConfig, parseFirefoxProductOption, parseProjectLicenseOption, resolveSetupInputs, validateSetupOptions, writeSetupProjectFiles, } from './setup-support.js';
 /**
  * Runs the setup command.
@@ -17,7 +18,7 @@ export async function setupCommand(projectRoot, options = {}) {
     // Validate any CLI-provided options first
     validateSetupOptions(options);
     // Determine if we can run interactively
-    const isInteractive = process.stdin.isTTY && process.stdout.isTTY;
+    const isInteractive = stdioIsInteractive();
     intro('FireForge Setup');
     // Check if config already exists
     if (await configExists(projectRoot)) {
@@ -67,17 +68,20 @@ export function registerSetup(program, { withErrorHandling }) {
         .option('--app-id <appId>', 'Application ID (reverse-domain format)')
         .option('--binary-name <binaryName>', 'Binary name (executable name)')
         .option('--firefox-version <version>', 'Firefox version to base on')
-        .addOption(new Option('--product <product>', 'Firefox product').choices([
-        'firefox',
-        'firefox-esr',
-        'firefox-beta',
-        'firefox-devedition',
-    ]))
+        .addOption(new Option('--product <product>', 'Firefox product').choices([...FIREFOX_PRODUCTS]))
         .addOption(new Option('--license <license>', 'Project license').choices([...PROJECT_LICENSES]))
         .option('-f, --force', 'Overwrite existing configuration without prompting')
+        // `--yes` is a plain alias here: `setup`'s only bypass is the overwrite
+        // prompt, so the two flags mean exactly the same thing. Seventeen other
+        // commands spell this bypass `--yes`; accepting it means a scripted
+        // sequence can use one spelling throughout.
+        .option('-y, --yes', 'Alias for --force: skip the overwrite confirmation')
         .action(withErrorHandling(async (options) => {
-        const { product, license, ...rest } = options;
+        const { product, license, yes, ...rest } = options;
         const setupOptions = { ...pickDefined(rest) };
+        // `--yes` is an alias, so either flag sets the same bypass.
+        if (yes === true)
+            setupOptions.force = true;
         if (product !== undefined) {
             const parsedProduct = parseFirefoxProductOption(product);
             if (parsedProduct !== undefined) {

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

@@ -1,11 +1,11 @@
 /**
- * `status --check` enforcement policy. Turns the classified
- * status view into a CI-enforceable non-zero exit: the default policy
- * fails on any classification outside {patch-backed, branding, furnace},
- * and `--fail-on <class,...>` replaces that set for finer control.
+ * `status --check` enforcement policy. Turns the classified status view into
+ * a CI-enforceable non-zero exit: the default policy fails on any
+ * classification outside {patch-backed, branding, furnace}, and
+ * `--fail-on <class,...>` replaces that set for finer control.
  *
- * Helper module consumed by status.ts (which sits at the max-lines
- * budget); no top-level registrar is exported and none is wanted.
+ * Helper module consumed by status.ts (which sits at the max-lines budget);
+ * no top-level registrar is exported and none is wanted.
  */
 import type { ClassifiedFile, FileClassification } from '../core/status-classify.js';
 /** Resolved `--check`/`--fail-on` policy for one status invocation. */

package/dist/src/commands/status-json.d.ts

@@ -1,14 +1,14 @@
 /**
  * `status --json` payload rendering (schemaVersion 1). Helper module
- * consumed by status.ts (which sits at the max-lines budget); no
- * top-level registrar is exported and none is wanted.
+ * consumed by status.ts (which sits at the max-lines budget); no top-level
+ * registrar is exported and none is wanted.
  *
  * Two shapes share one counting pass:
  * - the full payload (`renderJsonStatus`) with the per-file `files[]` list;
- * - the `--summary` gate payload (`renderJsonSummaryStatus`),
- *   which omits `files[]` entirely — engine-clean gates need the verdict,
- *   per-class counts, and offender names, not a payload that grows with
- *   the queue (175 KB+ observed on a 290-patch consumer).
+ * - the `--summary` gate payload (`renderJsonSummaryStatus`), which omits
+ *   `files[]` entirely — engine-clean gates need the verdict, per-class
+ *   counts, and offender names, not a payload that grows with the queue
+ *   (175 KB+ on a large one).
  */
 import type { ClassifiedFile } from '../core/status-classify.js';
 import { type StatusCheckPolicy } from './status-check.js';

package/dist/src/commands/status-json.js

@@ -1,3 +1,4 @@
+import { setStdoutSealed } from '../utils/logger.js';
 import { collectStatusCheckOffenders, } from './status-check.js';
 function countByClassification(classified) {
     const byClassification = {
@@ -43,6 +44,8 @@ export function renderJsonStatus(classified, ownership) {
         ...(ownership !== undefined ? { ownership } : {}),
     };
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    // Payload written: stdout is now spoken for. See docs/machine-output.md.
+    setStdoutSealed(true);
 }
 /**
  * Summary-only `--json --summary` payload: counts always; when the
@@ -73,4 +76,6 @@ export function renderJsonSummaryStatus(classified, policy, ownership) {
         output.ownership = ownership;
     }
     process.stdout.write(JSON.stringify(output, null, 2) + '\n');
+    // Payload written: stdout is now spoken for. See docs/machine-output.md.
+    setStdoutSealed(true);
 }

package/dist/src/commands/status-output.d.ts

@@ -14,10 +14,10 @@ export declare function renderUnmanagedOnly(unmanagedFiles: ClassifiedFile[], to
 /** Renders the default classified status buckets. */
 export declare function renderDefaultStatus(totalModified: number, buckets: ClassifiedBuckets, projectRoot: string, binaryName: string): Promise<void>;
 /**
- * Renders `fireforge status --test-coverage`: a READ-ONLY view
- * of the last build baseline's test-packaging coverage. Before this
- * existed, the only way to learn the recorded coverage scope — which
- * concurrent sessions sharing one engine tree overwrite constantly — was
- * to trip the out-of-coverage refusal on a real test run.
+ * Renders `fireforge status --test-coverage`: a READ-ONLY view of the last
+ * build baseline's test-packaging coverage. Without it, the only way to
+ * learn the recorded coverage scope — which concurrent sessions sharing one
+ * engine tree overwrite constantly — is to trip the out-of-coverage refusal
+ * on a real test run.
  */
 export declare function renderTestCoverageStatus(baseline: BuildBaseline | undefined): void;

package/dist/src/commands/status-output.js

@@ -1,4 +1,4 @@
-import { isFileRegistered, matchesRegistrablePattern } from '../core/manifest-rules.js';
+import { isFileRegistered, matchesRegistrablePattern } from '../core/moz-manifest-rules.js';
 import { getPrimaryStatusCode } from '../core/status-classify.js';
 import { GeneralError } from '../errors/base.js';
 import { info, outro, warn } from '../utils/logger.js';
@@ -191,11 +191,11 @@ export async function renderDefaultStatus(totalModified, buckets, projectRoot, b
     outro(parts.join(', '));
 }
 /**
- * Renders `fireforge status --test-coverage`: a READ-ONLY view
- * of the last build baseline's test-packaging coverage. Before this
- * existed, the only way to learn the recorded coverage scope — which
- * concurrent sessions sharing one engine tree overwrite constantly — was
- * to trip the out-of-coverage refusal on a real test run.
+ * Renders `fireforge status --test-coverage`: a READ-ONLY view of the last
+ * build baseline's test-packaging coverage. Without it, the only way to
+ * learn the recorded coverage scope — which concurrent sessions sharing one
+ * engine tree overwrite constantly — is to trip the out-of-coverage refusal
+ * on a real test run.
  */
 export function renderTestCoverageStatus(baseline) {
     if (baseline === undefined) {

package/dist/src/commands/status-ownership.d.ts

@@ -1,13 +1,13 @@
 /**
- * Ownership-table assembly for `status`, split out of `status.ts` (FORGE
- * L3) so the human `--ownership` mode and the additive `ownership` block on
- * the `--json` payload build the SAME rows from the SAME scan.
+ * Ownership-table assembly for `status`, split out of `status.ts` so the
+ * human `--ownership` mode and the additive `ownership` block on the
+ * `--json` payload build the SAME rows from the SAME scan.
  *
- * Before L3 the `--ownership` branch re-implemented the shared scan and
- * inlined a second copy of the classification call, then discarded
- * everything but each file's classification — three back-to-back `status`
- * invocations in a gate therefore paid three full worktree scans. Both
- * callers now hand this module the already-classified files.
+ * A separate `--ownership` branch re-implements the shared scan and inlines
+ * a second copy of the classification call, then discards everything but
+ * each file's classification — so three back-to-back `status` invocations in
+ * a gate pay three full worktree scans. Both callers hand this module the
+ * already-classified files instead.
  *
  * No renderer lives here: `renderOwnershipTable` (human) and the JSON
  * serializer stay with their respective output layers.
@@ -29,13 +29,15 @@ export interface OwnershipJsonBlock {
 /**
  * Builds the flat path→owning-patch rows. Sources are the manifest's
  * `filesAffected`, worktree drift, and the cross-patch
- * duplicate-new-file-creation map produced by walking each patch body —
- * the last being the alignment fix between `status --ownership` and
- * `fireforge verify` (see `buildOwnershipTable`'s header).
- * @param patchesDir - Path to the patches directory
- * @param manifestPatches - Patch rows from patches.json (empty when absent)
- * @param files - Scanned worktree entries, temp-filtered
+ * duplicate-new-file-creation map produced by walking each patch body — the
+ * last being what keeps `status --ownership` aligned with `fireforge verify`
+ * (see `buildOwnershipTable`'s header).
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param manifestPatches - Manifest rows, each with its `filesAffected`
+ * @param files - Raw worktree status entries
  * @param classified - The same entries, already classified
+ * @returns The flat ownership rows
  */
 export declare function collectOwnershipRows(patchesDir: string, manifestPatches: readonly PatchMetadata[], files: StatusFile[], classified: readonly ClassifiedFile[]): Promise<OwnershipRow[]>;
 /**

package/dist/src/commands/status-ownership.js

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Ownership-table assembly for `status`, split out of `status.ts` (FORGE
- * L3) so the human `--ownership` mode and the additive `ownership` block on
- * the `--json` payload build the SAME rows from the SAME scan.
+ * Ownership-table assembly for `status`, split out of `status.ts` so the
+ * human `--ownership` mode and the additive `ownership` block on the
+ * `--json` payload build the SAME rows from the SAME scan.
  *
- * Before L3 the `--ownership` branch re-implemented the shared scan and
- * inlined a second copy of the classification call, then discarded
- * everything but each file's classification — three back-to-back `status`
- * invocations in a gate therefore paid three full worktree scans. Both
- * callers now hand this module the already-classified files.
+ * A separate `--ownership` branch re-implements the shared scan and inlines
+ * a second copy of the classification call, then discards everything but
+ * each file's classification — so three back-to-back `status` invocations in
+ * a gate pay three full worktree scans. Both callers hand this module the
+ * already-classified files instead.
  *
  * No renderer lives here: `renderOwnershipTable` (human) and the JSON
  * serializer stay with their respective output layers.
@@ -19,13 +19,15 @@ import { pathExists } from '../utils/fs.js';
 /**
  * Builds the flat path→owning-patch rows. Sources are the manifest's
  * `filesAffected`, worktree drift, and the cross-patch
- * duplicate-new-file-creation map produced by walking each patch body —
- * the last being the alignment fix between `status --ownership` and
- * `fireforge verify` (see `buildOwnershipTable`'s header).
- * @param patchesDir - Path to the patches directory
- * @param manifestPatches - Patch rows from patches.json (empty when absent)
- * @param files - Scanned worktree entries, temp-filtered
+ * duplicate-new-file-creation map produced by walking each patch body — the
+ * last being what keeps `status --ownership` aligned with `fireforge verify`
+ * (see `buildOwnershipTable`'s header).
+ *
+ * @param patchesDir - Absolute path to the patches directory
+ * @param manifestPatches - Manifest rows, each with its `filesAffected`
+ * @param files - Raw worktree status entries
  * @param classified - The same entries, already classified
+ * @returns The flat ownership rows
  */
 export async function collectOwnershipRows(patchesDir, manifestPatches, files, classified) {
     // Only walk patch bodies when the directory actually exists: a fresh

package/dist/src/commands/status.js

@@ -2,17 +2,19 @@
 import { Command } from 'commander';
 import { readBuildBaseline } from '../core/build-baseline.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { assertEngineExists } from '../core/engine-precondition.js';
 import { formatEngineSessionLockStatus, readEngineSessionLockStatus, } from '../core/engine-session-lock.js';
 import { collectFurnaceManagedPrefixes } from '../core/furnace-config.js';
 import { getHead, getStatusWithCodes, isGitRepository, isMissingHeadError } from '../core/git.js';
 import { getUntrackedFilesInDir, resolveMaxUntrackedFilesPerDir } from '../core/git-status.js';
 import { renderOwnershipTable } from '../core/ownership-table.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
+import { readProcessCpuSeconds } from '../core/process-cpu-time.js';
 import { classifyFiles } from '../core/status-classify.js';
-import { CommandError, GeneralError, InvalidArgumentError } from '../errors/base.js';
-import { ExitCode } from '../errors/codes.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, isMachineOutputMode, outro, setMachineOutputMode, warn, } from '../utils/logger.js';
+import { emitMachineError } from '../utils/machine-output.js';
 import { resolveStatusCheckPolicy, runStatusCheck } from './status-check.js';
 import { renderJsonStatus, renderJsonSummaryStatus } from './status-json.js';
 import { renderDefaultStatus, renderTestCoverageStatus, renderUnmanagedOnly, } from './status-output.js';
@@ -96,12 +98,13 @@ async function classifyStatusFiles(files, paths, projectRoot, binaryName) {
 /**
  * The one worktree scan every classifying mode shares: porcelain status,
  * collapsed-directory expansion, atomic-temp-file filtering, and the
- * truncation banner. `--ownership` used to carry its own copy of this
- * block; a non-git engine degrades to an empty list there,
- * which is why the git probe is a parameter rather than a hard guard.
+ * truncation banner. A non-git engine degrades to an empty list for
+ * `--ownership`, which is why the git probe is a parameter rather than a
+ * hard guard.
+ *
  * @param engineDir - Path to the engine directory
  * @param requireGitRepository - When false, a non-git engine yields `[]`
- *   instead of being probed (the historical `--ownership` behavior)
+ *   instead of being probed
  */
 async function scanEngineStatusFiles(engineDir, requireGitRepository) {
     if (!requireGitRepository && !(await isGitRepository(engineDir))) {
@@ -112,12 +115,13 @@ async function scanEngineStatusFiles(engineDir, requireGitRepository) {
     return filterFireForgeTempFiles(entries);
 }
 /**
- * Emits the `--json` payload (full or `--summary`) and applies the
- * `--check` policy, which stays the SOLE exit driver on this path.
+ * Emits the `--json` payload (full or `--summary`) and applies the `--check`
+ * policy, which stays the SOLE exit driver on this path.
+ *
+ * `--include-ownership` is a MODIFIER, not a mode: it appends an ownership
+ * block without touching exit semantics, so an ownership conflict still
+ * fails only the human `--ownership` mode.
  *
- * `--include-ownership` is a MODIFIER, not a mode: it appends an
- * ownership block without touching exit semantics, so an ownership conflict
- * still fails only the human `--ownership` mode.
  * @param classified - Classified worktree entries
  * @param files - The same entries pre-classification, for ownership rows
  * @param paths - Resolved project paths
@@ -187,8 +191,8 @@ export async function statusCommand(projectRoot, options = {}) {
     }
     // On a throw, machine mode deliberately stays ENGAGED: withErrorHandling
     // routes the styled error to stderr while the mode is on and resets it
-    // centrally (a mid-throw restore here put the refusal on stdout after the
-    // JSON payload, breaking the 0.40.0 stderr promise).
+    // centrally. A mid-throw restore here would put the refusal on stdout
+    // after the JSON payload.
     await runStatusCommandBody(projectRoot, options);
     if (isMachineOutputMode() !== previousMachineOutputMode) {
         setMachineOutputMode(previousMachineOutputMode);
@@ -229,7 +233,11 @@ async function runStatusCommandBody(projectRoot, options) {
     // concurrent command is busy with, and that answer must not depend on
     // engine/ being readable.
     if (options.lock === true) {
-        for (const line of formatEngineSessionLockStatus(await readEngineSessionLockStatus(projectRoot))) {
+        const snapshot = await readEngineSessionLockStatus(projectRoot);
+        const holderCpuSeconds = snapshot.holder?.alive === true
+            ? await readProcessCpuSeconds(snapshot.holder.pid)
+            : undefined;
+        for (const line of formatEngineSessionLockStatus(snapshot, holderCpuSeconds)) {
             info(line);
         }
         outro('Lock status');
@@ -243,24 +251,22 @@ async function runStatusCommandBody(projectRoot, options) {
     }
     const paths = getProjectPaths(projectRoot);
     const config = await loadConfig(projectRoot);
-    const emitJsonError = (code, message) => {
-        process.stdout.write(JSON.stringify({ schemaVersion: 1, error: message, code }) + '\n');
-        throw new CommandError(ExitCode.GENERAL_ERROR);
-    };
+    // Shared envelope: see src/utils/machine-output.ts and
+    // docs/machine-output.md. `status` was the only command that had one.
+    const emitJsonError = emitMachineError;
     // Ownership mode is a flat file→patch table; sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch
-    // duplicate-new-file-creation map produced by walking each patch
-    // body. The latter is the alignment fix between `status --ownership`
-    // and `fireforge verify` — see buildOwnershipTable's header comment.
-    // Runs before the default classify path so we can short-circuit
-    // without computing patch-backed state.
+    // duplicate-new-file-creation map produced by walking each patch body. The
+    // last is what keeps `status --ownership` aligned with `fireforge verify`
+    // — see buildOwnershipTable's header. Runs before the default classify
+    // path so it can short-circuit without computing patch-backed state.
     if (options.ownership) {
-        if (!(await pathExists(paths.engine))) {
-            throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-        }
+        // Rung 1 only, deliberately — see the note below on why this branch
+        // does not take the full assertEngineGitReady ladder.
+        await assertEngineExists(paths.engine);
         const manifest = await loadPatchesManifest(paths.patches);
-        // Same scan and the SAME classification pass as every other mode
-        //. This branch keeps its historical guard shape on purpose:
+        // Same scan and the SAME classification pass as every other mode.
+        // This branch keeps its historical guard shape on purpose:
         // no baseline-commit assertion, and a non-git engine degrades to an
         // empty table rather than the recovery banner.
         const rawFilesOwnership = await scanEngineStatusFiles(paths.engine, false);
@@ -280,7 +286,10 @@ async function runStatusCommandBody(projectRoot, options) {
         }
         return;
     }
-    // Check if engine exists
+    // Not routed through assertEngineExists: the --json contract requires a
+    // machine-readable payload on stdout BEFORE the throw, so scripted
+    // consumers get a parseable refusal instead of a bare non-zero exit. The
+    // message is kept identical to the helper's on purpose.
     if (!(await pathExists(paths.engine))) {
         if (options.json) {
             emitJsonError('engine-missing', 'Firefox source not found. Run "fireforge download" first.');
@@ -297,11 +306,10 @@ async function runStatusCommandBody(projectRoot, options) {
     await assertEngineHasBaselineCommit(paths.engine, options);
     const files = await scanEngineStatusFiles(paths.engine, true);
     // `--json` callers expect machine-parseable output on every invocation,
-    // including the clean-tree case. Before this ordering fix a clean tree
-    // printed "No modified files" / "Working tree clean" via the human
-    // branch below and `--json` was silently ignored, so scripts that piped
-    // the output through a JSON parser broke precisely when there was
-    // nothing to report. Emit `[]` here and return before the human fallback.
+    // including the clean-tree case. Falling through to the human branch below
+    // silently ignores `--json` and breaks scripts that pipe the output
+    // through a JSON parser precisely when there is nothing to report. Emit
+    // `[]` here and return before the human fallback.
     if (options.json) {
         const classified = await classifyStatusFiles(files, paths, projectRoot, config.binaryName);
         await renderJsonMode(classified, files, paths, options, checkPolicy);