@hominis/fireforge 0.48.0 → 0.49.1

package/dist/src/core/process-owner.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { exec } from '../utils/process.js';
+/** Parent evidence; an unreadable parent is never proof of an orphan. */
+export async function readProcessOwner(pid) {
+    if (process.platform === 'win32')
+        return undefined;
+    try {
+        const result = await exec('ps', ['-p', String(pid), '-o', 'ppid='], { timeout: 5000 });
+        const parentPid = Number(result.stdout.trim());
+        if (result.exitCode !== 0 || !Number.isSafeInteger(parentPid) || parentPid < 1)
+            return undefined;
+        if (parentPid === 1)
+            return { parentPid, owner: 'init/launchd (parent exited)' };
+        const parent = await exec('ps', ['-p', String(parentPid), '-o', 'args='], { timeout: 5000 });
+        if (parent.exitCode !== 0 || !parent.stdout.trim())
+            return undefined;
+        return { parentPid, owner: parent.stdout.trim() };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Harness arguments alone never prove abandonment: require a dead parent too. */
+export function isOrphanedHarness(commandLine, parentPid) {
+    return (parentPid === 1 &&
+        (/\s-marionette(?:\s|$)/.test(commandLine) ||
+            /\s-profile(?:\s|=)[^\n]*(?:fireforge-|mochitest|rust_mozprofile)/.test(commandLine)));
+}
+/** Refreshes the exact command and orphan evidence immediately before signaling. */
+export async function isStillOrphanedProcess(pid, commandLine) {
+    // Windows ownership has no verified implementation; never infer it from
+    // command-line appearance or enable a destructive PowerShell fallback.
+    if (process.platform === 'win32')
+        return false;
+    try {
+        const result = await exec('ps', ['-p', String(pid), '-o', 'ppid=,args='], { timeout: 5000 });
+        const match = /^\s*(\d+)\s+(.+?)\s*$/.exec(result.stdout);
+        return result.exitCode === 0 && match?.[1] === '1' && match[2] === commandLine;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/core/test-harness-crash.d.ts

@@ -25,7 +25,7 @@ export type { HarnessCrashSignature } from './test-harness-signature.js';
 import type { HarnessCrashSignature } from './test-harness-signature.js';
 export { headedDisplayAsleepVerdictNote, headedNoOutputTimeoutHint } from './test-stall-triage.js';
 /** How a completed harness run should be interpreted. */
-export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'no-tests';
+export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'harness-arguments' | 'no-tests';
 /** Numeric counts parsed from the harness's embedded result summary. */
 export interface HarnessSummaryCounts {
     /** Total checks the suite ran (`Ran N checks`), when the summary prints one. */

package/dist/src/core/test-harness-crash.js

@@ -24,6 +24,7 @@
  */
 import { hasKnownTeardownNoise } from './mach-known-noise-filter.js';
 import { truncateEvidence, unmarkedFailureEvidenceNote, } from './test-harness-verdict-notes.js';
+import { classifyProfileArgumentFailure } from './test-profile-files.js';
 // The no-output-stall triage text lives in `test-stall-triage.ts` (it is
 // operator advice, not classification) and is re-exported here so the
 // command layer keeps importing its harness diagnostics from one module.
@@ -472,6 +473,9 @@ export function detectHarnessCrashSignature(output) {
  */
 export function classifyHarnessRun(exitCode, output, requestedPaths) {
     const counts = extractSummaryCounts(output);
+    const profileFailure = classifyProfileArgumentFailure(output);
+    if (profileFailure)
+        return { ...profileFailure, ...counts };
     const realFailures = realUnexpectedFailureLines(output);
     const firstRealFailure = realFailures[0];
     const failureBlocks = collectUnexpectedFailureBlocks(output);
@@ -660,11 +664,7 @@ export function formatFireforgeVerdictLine(verdict, shards) {
     if (verdict.kind === 'tests-ran-ok') {
         return `FIREFORGE-VERDICT: PASS${counts}${shardSuffix}${note}`;
     }
-    const reason = verdict.kind === 'harness-crash'
-        ? 'crash'
-        : verdict.kind === 'no-tests'
-            ? 'no-tests'
-            : 'test-failures';
+    const reason = verdict.kind === 'harness-crash' ? 'crash' : verdict.kind;
     return `FIREFORGE-VERDICT: FAIL reason=${reason}${counts}${shardSuffix}${note}`;
 }
 /**

package/dist/src/core/test-host-state.d.ts

@@ -0,0 +1,14 @@
+export interface TestHostState {
+    load: number;
+    topProcess?: {
+        cpu: number;
+        command: string;
+    };
+    power: 'ac' | 'battery' | 'unknown';
+}
+/** Samples load/top process and the macOS power SOURCE (including charging on AC). */
+export declare function sampleTestHost(): Promise<TestHostState>;
+/** Reports host contention alongside a suite's result, without inventing a test failure. */
+export declare function reportTestHost(state: TestHostState, phase: string): boolean;
+/** Stamps each perf artifact before the verdict, preserving the producer's schema and data. */
+export declare function stampPerfHost(env: Record<string, string> | undefined, start: TestHostState, end: TestHostState): Promise<boolean>;

package/dist/src/core/test-host-state.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { loadavg } from 'node:os';
+import { toError } from '../utils/errors.js';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { notice } from '../utils/logger.js';
+import { exec } from '../utils/process.js';
+import { isObject } from '../utils/validation.js';
+/** Samples load/top process and the macOS power SOURCE (including charging on AC). */
+export async function sampleTestHost() {
+    const state = { load: loadavg()[0] ?? 0, power: 'unknown' };
+    try {
+        const result = await exec('ps', ['-axo', 'pcpu=,comm='], { timeout: 5000 });
+        const processes = result.stdout
+            .split('\n')
+            .flatMap((line) => {
+            const match = /^\s*([\d.]+)\s+(.+)$/.exec(line);
+            return match ? [{ cpu: Number(match[1]), command: match[2] ?? '' }] : [];
+        })
+            .sort((a, b) => b.cpu - a.cpu);
+        if (processes[0])
+            state.topProcess = processes[0];
+    }
+    catch {
+        /* Host diagnostics remain best effort. */
+    }
+    if (process.platform === 'darwin') {
+        try {
+            const result = await exec('pmset', ['-g', 'ps'], { timeout: 5000 });
+            state.power = /'AC Power'/.test(result.stdout)
+                ? 'ac'
+                : /'Battery Power'/.test(result.stdout)
+                    ? 'battery'
+                    : 'unknown';
+        }
+        catch {
+            /* Keep unknown when power tooling is unavailable. */
+        }
+    }
+    return state;
+}
+/** Reports host contention alongside a suite's result, without inventing a test failure. */
+export function reportTestHost(state, phase) {
+    const pegged = (state.topProcess?.cpu ?? 0) >= 90;
+    if (state.load < 4 && !pegged)
+        return false;
+    notice(`Host load at ${phase}: ${state.load.toFixed(2)}; top process ${state.topProcess?.command ?? '(unknown)'} ${state.topProcess?.cpu ?? 0}% CPU. Timing failures may reflect host contention.`);
+    return true;
+}
+/** Stamps each perf artifact before the verdict, preserving the producer's schema and data. */
+export async function stampPerfHost(env, start, end) {
+    if (!env)
+        return false;
+    const artifacts = [
+        ...new Set(Object.entries(env)
+            .filter(([key]) => key.endsWith('_PERF_SAMPLE_JSON'))
+            .map(([, path]) => path)),
+    ];
+    if (artifacts.length === 0)
+        return false;
+    const changed = start.power !== 'unknown' && end.power !== 'unknown' && start.power !== end.power;
+    if (changed)
+        notice(`Perf power source changed during the run (${start.power} → ${end.power}); this sample is inconclusive.`);
+    for (const artifact of artifacts) {
+        try {
+            if (!(await pathExists(artifact)))
+                continue;
+            const sample = await readJson(artifact);
+            if (!isObject(sample))
+                throw new Error('sample JSON is not an object');
+            await writeJson(artifact, {
+                ...sample,
+                fireforgeHost: { start, end, powerSourceChanged: changed },
+            });
+        }
+        catch (error) {
+            notice(`Could not annotate perf artifact ${artifact}: ${toError(error).message}. The harness outcome is preserved; inspect or regenerate this artifact before using it as perf evidence.`);
+        }
+    }
+    return changed;
+}

package/dist/src/core/test-profile-files.d.ts

@@ -0,0 +1,17 @@
+/** Stages explicit profile overlays with relative destinations; cleanup belongs to the caller. */
+export interface StagedProfileFiles {
+    root: string;
+    args: string[];
+    env: Record<string, string>;
+}
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export declare function stageProfileFiles(projectRoot: string, files: readonly string[]): Promise<StagedProfileFiles>;
+/** Python startup overlay: allow merging ONLY the explicitly staged profile directories. */
+export declare const PROFILE_MERGE_PYTHON = "\nimport os\nimport shutil\n_fireforge_profile_root = os.environ.get(\"FIREFORGE_PROFILE_MERGE_ROOT\")\nif _fireforge_profile_root and not getattr(shutil.copytree, \"_fireforge_profile_merge\", False):\n    _fireforge_copytree = shutil.copytree\n    def _fireforge_merge_copytree(src, dst, *args, **kwargs):\n        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):\n            # Python's recursive calls may supply dirs_exist_ok positionally.\n            if len(args) >= 5:\n                args = args[:4] + (True,) + args[5:]\n            else:\n                kwargs[\"dirs_exist_ok\"] = True\n        return _fireforge_copytree(src, dst, *args, **kwargs)\n    _fireforge_merge_copytree._fireforge_profile_merge = True\n    shutil.copytree = _fireforge_merge_copytree\n";
+/** Classifies the profile setup traceback separately from stale packaging. */
+export declare function classifyProfileArgumentFailure(output: string): {
+    kind: 'harness-arguments';
+    note: string;
+} | undefined;
+/** Cleanup is independent of the harness verdict and cannot hide its primary error. */
+export declare function cleanupProfileFiles(root: string): Promise<void>;

package/dist/src/core/test-profile-files.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { InvalidArgumentError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+/** Prepares profile overlays and browser/port ownership preconditions. */
+export async function stageProfileFiles(projectRoot, files) {
+    const root = await mkdtemp(join(tmpdir(), 'fireforge-profile-overlay-'));
+    const top = new Set();
+    try {
+        for (const file of files) {
+            const separator = file.indexOf('=');
+            const source = file.slice(0, separator);
+            const dest = file.slice(separator + 1).replaceAll('\\', '/');
+            if (separator <= 0 ||
+                !dest ||
+                dest.startsWith('/') ||
+                dest.includes(':') ||
+                dest.split('/').some((part) => !part || part === '.' || part === '..')) {
+                throw new InvalidArgumentError('--profile-file requires source=relative/destination with no traversal.', '--profile-file');
+            }
+            const target = join(root, dest);
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(resolve(projectRoot, source), target);
+            top.add(dest.split('/')[0] ?? dest);
+        }
+        return {
+            root,
+            args: [...top].map((path) => `--extra-profile-file=${join(root, path)}`),
+            env: { FIREFORGE_PROFILE_MERGE_ROOT: root },
+        };
+    }
+    catch (error) {
+        await cleanupProfileFiles(root);
+        throw error;
+    }
+}
+/** Python startup overlay: allow merging ONLY the explicitly staged profile directories. */
+export const PROFILE_MERGE_PYTHON = `
+import os
+import shutil
+_fireforge_profile_root = os.environ.get("FIREFORGE_PROFILE_MERGE_ROOT")
+if _fireforge_profile_root and not getattr(shutil.copytree, "_fireforge_profile_merge", False):
+    _fireforge_copytree = shutil.copytree
+    def _fireforge_merge_copytree(src, dst, *args, **kwargs):
+        if os.path.realpath(src).startswith(os.path.realpath(_fireforge_profile_root) + os.sep):
+            # Python's recursive calls may supply dirs_exist_ok positionally.
+            if len(args) >= 5:
+                args = args[:4] + (True,) + args[5:]
+            else:
+                kwargs["dirs_exist_ok"] = True
+        return _fireforge_copytree(src, dst, *args, **kwargs)
+    _fireforge_merge_copytree._fireforge_profile_merge = True
+    shutil.copytree = _fireforge_merge_copytree
+`;
+/** Classifies the profile setup traceback separately from stale packaging. */
+export function classifyProfileArgumentFailure(output) {
+    if (!/copyExtraFilesToProfile/.test(output) || !/FileExistsError/.test(output))
+        return undefined;
+    return {
+        kind: 'harness-arguments',
+        note: 'profile directory collision; use --profile-file source=chrome/userChrome.css to merge into the existing profile',
+    };
+}
+/** Cleanup is independent of the harness verdict and cannot hide its primary error. */
+export async function cleanupProfileFiles(root) {
+    try {
+        await rm(root, { recursive: true, force: true });
+    }
+    catch (error) {
+        warn(`Could not remove staged profile files ${root}: ${toError(error).message}`);
+    }
+}

package/dist/src/core/test-stale-check.d.ts

@@ -27,8 +27,8 @@ export interface StaleBuildResult {
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
  * as an up-front warning when `--build` was not passed. The probe never
- * throws. Git failures and a missing baseline both degrade to `stale: false`
- * so a broken probe cannot block a test run.
+ * refuses a malformed persisted baseline. Git failures and a missing baseline
+ * degrade to `stale: false` because they provide no comparison anchor.
  *
  * @param projectRoot Root directory of the project.
  * @param engineDir Path to the engine directory.
@@ -52,11 +52,10 @@ export declare const FULL_SUITE_REQUEST = "(entire suite)";
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
- * scoped list covers a request path when the request equals a covered entry,
- * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
- * packages the whole manifest directory, so a same-manifest sibling of a
- * covered file is packaged too). Both sides are normalized to forward
+ * scoped list covers a request path when the request equals a covered entry
+ * or sits beneath it. A file claim never widens to its containing directory:
+ * sibling files can belong to different manifests or harnesses, and a dot in
+ * a directory name does not make it a file. Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
  * run and is never covered by a scoped list, so the

package/dist/src/core/test-stale-check.js

@@ -35,14 +35,14 @@ const STALE_PATHS_LIMIT = 10;
  * Probes the engine tree for packageable changes since the last successful
  * `fireforge build`. Returns a summary the `fireforge test` handler renders
  * as an up-front warning when `--build` was not passed. The probe never
- * throws. Git failures and a missing baseline both degrade to `stale: false`
- * so a broken probe cannot block a test run.
+ * refuses a malformed persisted baseline. Git failures and a missing baseline
+ * degrade to `stale: false` because they provide no comparison anchor.
  *
  * @param projectRoot Root directory of the project.
  * @param engineDir Path to the engine directory.
  */
 export async function checkStaleBuildForTest(projectRoot, engineDir) {
-    const baseline = await readBuildBaseline(projectRoot);
+    const baseline = await readBuildBaseline(projectRoot, 'refuse');
     if (!baseline) {
         return { stale: false, changedPaths: [], truncated: 0, baseline: undefined };
     }
@@ -93,11 +93,10 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
  * `_tests/` support fixtures and hang rather than fail.
  *
  * Coverage semantics: an absent claim and `'full'` cover everything. A
- * scoped list covers a request path when the request equals a covered entry,
- * sits beneath a covered directory entry, or shares a manifest granule with
- * a covered entry (see {@link toManifestGranule}: a scoped `test --build`
- * packages the whole manifest directory, so a same-manifest sibling of a
- * covered file is packaged too). Both sides are normalized to forward
+ * scoped list covers a request path when the request equals a covered entry
+ * or sits beneath it. A file claim never widens to its containing directory:
+ * sibling files can belong to different manifests or harnesses, and a dot in
+ * a directory name does not make it a file. Both sides are normalized to forward
  * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
  * paths are POSIX by convention). A request with no paths is a full-suite
  * run and is never covered by a scoped list, so the
@@ -114,29 +113,9 @@ export function findUncoveredRequestPaths(coverage, requestedPaths) {
     }
     return requestedPaths.filter((requested) => {
         const path = normalizeCoveragePath(requested);
-        const granule = toManifestGranule(path);
-        return !covered.some((c) => path === c || path.startsWith(`${c}/`) || granule === toManifestGranule(c));
+        return !covered.some((c) => path === c || path.startsWith(`${c}/`));
     });
 }
-/**
- * Maps a normalized request/coverage path to the "manifest granule" the
- * packaged runtime actually staged: an extension-bearing basename (a test
- * FILE) maps to its containing directory, a directory (no dot in the
- * basename) maps to itself. Purely lexical: the directory-as-manifest
- * approximation holds because xpcshell/mochitest manifests live next to
- * their test files and a scoped `test --build` stages the whole manifest
- * directory into `obj-*`/`_tests/`, not single files. Caveat: a directory
- * whose basename contains a dot is misread as a file and mapped to its
- * parent, which widens (never narrows) the covered granule.
- */
-function toManifestGranule(path) {
-    const slash = path.lastIndexOf('/');
-    const base = slash === -1 ? path : path.slice(slash + 1);
-    if (!base.includes('.')) {
-        return path;
-    }
-    return slash === -1 ? '' : path.slice(0, slash);
-}
 /** Normalizes a path for coverage comparison: forward slashes, no trailing slash. */
 function normalizeCoveragePath(path) {
     return normalizePathSlashes(path.trim()).replace(/\/+$/, '');
@@ -196,9 +175,7 @@ export async function findChangedTestManifestsForPaths(engineDir, baseline, unco
         verbose(`Coverage refusal: manifest probe failed — ${toError(error).message}`);
         return [];
     }
-    const requestDirs = uncovered
-        .filter((p) => p !== FULL_SUITE_REQUEST)
-        .map((p) => toManifestGranule(normalizeCoveragePath(p)));
+    const requestDirs = uncovered.filter((p) => p !== FULL_SUITE_REQUEST).map(normalizeCoveragePath);
     const hits = changed.filter((path) => {
         if (!isTestManifestPath(path))
             return false;

package/dist/src/core/token-category.d.ts

@@ -5,32 +5,13 @@
  * agree on what "exists" means.
  */
 export declare function categoryHeaderExists(lines: string[], category: string): boolean;
-/**
- * Scans a tokens CSS file for category header comments and returns the
- * category names in document order. Used to enrich the "category not
- * found" error body with concrete alternatives the operator can copy.
- *
- * Mirrors the shapes `findCategorySection` recognises:
- * - Single-line: `/* = Foo = *\/`
- * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
- *   closing `*\/`.
- *
- * This helper exists as a pure inspector. It never throws on malformed
- * headers and silently skips shapes it cannot parse.
- */
-/**
- * Category name declared by the banner starting at `index`, or `undefined`
- * when that line opens no banner.
- *
- * The single reader for both banner shapes, so the inventory walk, the
- * "available categories" error body and the section finder cannot drift on
- * what counts as a header.
- *
- * @param lines - Tokens CSS split into lines
- * @param index - 0-based line index to test
- * @returns The declared category name, or undefined
- */
-export declare function categoryBannerNameAt(lines: string[], index: number): string | undefined;
+export interface TokenCategorySection {
+    name: string;
+    categoryLine: number;
+    sectionEnd: number;
+}
+/** Parses category regions owned by the base root, including nested CSS rules. */
+export declare function parseTokenCategorySections(lines: string[]): TokenCategorySection[];
 /**
  * Asserts the category banner exists (or that creation was requested).
  * Throws a GeneralError naming the available categories and the