@hominis/fireforge 0.47.1 → 0.49.0

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/rebase-dry-run.d.ts

@@ -0,0 +1,48 @@
+/** A patch to replay, in queue order. */
+export interface DryRunPatch {
+    filename: string;
+    path: string;
+}
+/** What the real rebase loop would do with one patch. */
+export type DryRunVerdict = {
+    filename: string;
+    outcome: 'clean';
+} | {
+    filename: string;
+    outcome: 'reduced-context';
+    step: number;
+    contextArg: string;
+} | {
+    filename: string;
+    outcome: 'reject';
+    /** Files git named as not applying. Empty when stderr named none. */
+    files: string[];
+    /** git's own explanation, from the exact-context `--check`. */
+    detail: string;
+};
+/** Result of a full queue replay. */
+export interface DryRunReplay {
+    verdicts: DryRunVerdict[];
+    /**
+     * Index of the first reject, or `undefined`. Verdicts after it were
+     * computed without that patch applied, so a reject there may cascade from
+     * the earlier one rather than be a conflict of its own.
+     */
+    firstRejectIndex: number | undefined;
+}
+/**
+ * Parses the file names out of `git apply --check` failure output. Git
+ * reports a context mismatch as `error: patch failed: <file>:<line>` and
+ * `error: <file>: patch does not apply`, and a missing or pre-existing
+ * target as `error: <file>: does not exist in index` /
+ * `error: <file>: already exists in index`.
+ */
+export declare function parseApplyCheckFailures(stderr: string): string[];
+/**
+ * Replays `patches` onto the engine's HEAD tree in a private index.
+ * @param engineDir - Engine repository root
+ * @param patches - Patches in queue order
+ * @param maxFuzz - Maximum context-reduction steps, as for the real rebase
+ * @returns One verdict per patch
+ */
+export declare function replayQueueIndexOnly(engineDir: string, patches: readonly DryRunPatch[], maxFuzz: number): Promise<DryRunReplay>;

package/dist/src/core/rebase-dry-run.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `rebase --dry-run`: replays the patch queue against the engine's base
+ * commit without touching `engine/`.
+ *
+ * The replay runs on a private index seeded from HEAD (`GIT_INDEX_FILE`
+ * plus `git read-tree HEAD`) and applies each patch there with
+ * `git apply --cached`, in queue order, so a later patch sees what the
+ * earlier ones did, exactly as the real loop's worktree does. Each patch
+ * walks the same context-reduction ladder as {@link applyPatchWithFuzz}.
+ * The worktree and the real index are never written. The private index is
+ * deleted when the replay ends.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { GitError } from '../errors/git.js';
+import { exec } from '../utils/process.js';
+import { ensureGit } from './git-base.js';
+import { assertValidMaxFuzz, contextReductionSteps } from './patch-apply-fuzz.js';
+/**
+ * Parses the file names out of `git apply --check` failure output. Git
+ * reports a context mismatch as `error: patch failed: <file>:<line>` and
+ * `error: <file>: patch does not apply`, and a missing or pre-existing
+ * target as `error: <file>: does not exist in index` /
+ * `error: <file>: already exists in index`.
+ */
+export function parseApplyCheckFailures(stderr) {
+    const files = new Set();
+    for (const line of stderr.split('\n')) {
+        const failed = /^error: patch failed: (.+):\d+$/.exec(line);
+        if (failed?.[1]) {
+            files.add(failed[1]);
+            continue;
+        }
+        const named = /^error: (.+?): (?:patch does not apply|does not exist in index|already exists in index)$/.exec(line);
+        if (named?.[1])
+            files.add(named[1]);
+    }
+    return [...files];
+}
+/**
+ * Replays `patches` onto the engine's HEAD tree in a private index.
+ * @param engineDir - Engine repository root
+ * @param patches - Patches in queue order
+ * @param maxFuzz - Maximum context-reduction steps, as for the real rebase
+ * @returns One verdict per patch
+ */
+export async function replayQueueIndexOnly(engineDir, patches, maxFuzz) {
+    assertValidMaxFuzz(maxFuzz);
+    await ensureGit();
+    const scratch = await mkdtemp(join(tmpdir(), 'fireforge-rebase-dry-run-'));
+    const env = { GIT_INDEX_FILE: join(scratch, 'index') };
+    try {
+        const seeded = await exec('git', ['read-tree', 'HEAD'], { cwd: engineDir, env });
+        if (seeded.exitCode !== 0) {
+            throw new GitError(seeded.stderr.trim() || 'Could not seed a private index from HEAD', 'read-tree HEAD');
+        }
+        const ladder = contextReductionSteps(maxFuzz);
+        const verdicts = [];
+        let firstRejectIndex;
+        for (const patch of patches) {
+            let verdict;
+            let exactFailure = '';
+            for (const [step, contextArgs] of ladder.entries()) {
+                const check = await exec('git', ['apply', '--cached', '--check', ...contextArgs, '--', patch.path], { cwd: engineDir, env });
+                if (check.exitCode !== 0) {
+                    if (step === 0)
+                        exactFailure = check.stderr;
+                    continue;
+                }
+                const apply = await exec('git', ['apply', '--cached', ...contextArgs, '--', patch.path], {
+                    cwd: engineDir,
+                    env,
+                });
+                if (apply.exitCode !== 0)
+                    continue;
+                verdict =
+                    step === 0
+                        ? { filename: patch.filename, outcome: 'clean' }
+                        : {
+                            filename: patch.filename,
+                            outcome: 'reduced-context',
+                            step,
+                            contextArg: contextArgs[0] ?? '',
+                        };
+                break;
+            }
+            if (verdict === undefined) {
+                verdict = {
+                    filename: patch.filename,
+                    outcome: 'reject',
+                    files: parseApplyCheckFailures(exactFailure),
+                    detail: exactFailure.trim(),
+                };
+                firstRejectIndex ??= verdicts.length;
+            }
+            verdicts.push(verdict);
+        }
+        return { verdicts, firstRejectIndex };
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}

package/dist/src/core/run-profile.d.ts

@@ -0,0 +1,50 @@
+/** Directory-name prefix of every FireForge-owned temporary run profile. */
+export declare const RUN_PROFILE_PREFIX = "fireforge-run-profile-";
+/** The profile a run launches with, and how to release it afterwards. */
+export interface RunProfile {
+    /** Program parameters to append to `mach run` (empty for mach's default). */
+    args: string[];
+    /** Absolute profile directory, when one was chosen. */
+    dir?: string;
+    /** Whether FireForge created the directory and will delete it. */
+    temporary: boolean;
+    /** Removes a temporary profile. A no-op otherwise. Never throws. */
+    dispose: () => Promise<void>;
+}
+/** Inputs to {@link resolveRunProfile}. */
+export interface RunProfileRequest {
+    /** `--profile <path>`: launch with this directory, left in place. */
+    profile?: string | undefined;
+    /** `--temp-profile`: launch with a fresh directory removed afterwards. */
+    tempProfile?: boolean | undefined;
+    /**
+     * Whether this is a `--smoke-exit` run. A smoke run with neither flag gets
+     * a temporary profile: the step exists to prove what the build does on a
+     * clean start, and the developer's profile-default carries whatever state
+     * the last session left.
+     */
+    smoke: boolean;
+    /** Base directory for temporary profiles (defaults to the OS tmpdir). */
+    tempRoot?: string | undefined;
+}
+/**
+ * Removes every temporary run profile this process still holds. Called by
+ * the CLI entry point's signal handler after child shutdown. Never throws.
+ */
+export declare function removeActiveRunProfiles(): Promise<void>;
+/**
+ * Chooses the profile for a run.
+ * @param request - The run's profile flags
+ * @returns The profile arguments and their release handle
+ */
+export declare function resolveRunProfile(request: RunProfileRequest): Promise<RunProfile>;
+/**
+ * Removes temporary run profiles whose owning FireForge process is gone.
+ * The `finally` that releases a profile covers a clean exit, a failed run
+ * and a forwarded SIGINT/SIGTERM, but not a SIGKILL of FireForge itself;
+ * this sweep is the backstop for that case. A directory whose marker is
+ * missing or unreadable is left alone: nothing proves it is abandoned.
+ * @param tempRoot - Base directory to sweep (defaults to the OS tmpdir)
+ * @returns The number of directories removed
+ */
+export declare function sweepAbandonedRunProfiles(tempRoot?: string): Promise<number>;

package/dist/src/core/run-profile.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Profile selection for `fireforge run`.
+ *
+ * `mach run` on desktop has no `--profile` option of its own: its parser's
+ * `--profile/-P` belongs to the Android run parser. On desktop a profile
+ * reaches Firefox as a program parameter (`-profile <dir>`), and mach skips
+ * creating the objdir's `tmp/profile-default` when it sees one among the
+ * params.
+ * Mach's `--temp-profile` does mint a fresh directory, but inside the objdir
+ * and never removes it, so FireForge owns the temporary profile instead:
+ * it creates the directory, seeds the two prefs mach would have written,
+ * passes it as `-profile`, and deletes it when the run ends.
+ */
+import { mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { InvalidArgumentError } from '../errors/base.js';
+import { isProcessAlive, toError } from '../utils/errors.js';
+import { verbose, warn } from '../utils/logger.js';
+/** Directory-name prefix of every FireForge-owned temporary run profile. */
+export const RUN_PROFILE_PREFIX = 'fireforge-run-profile-';
+/** Marker file naming the pid of the FireForge process that owns the profile. */
+const OWNER_MARKER = '.fireforge-run-owner';
+/**
+ * The prefs `mach run` writes into the profiles it creates itself. A profile
+ * passed with `-profile` gets none of them, and a first-run default-browser
+ * prompt would sit in a headed smoke window.
+ */
+const SEEDED_USER_JS = 'user_pref("browser.shell.checkDefaultBrowser", false);\n' +
+    'user_pref("browser.aboutConfig.showWarning", false);\n';
+/**
+ * Temporary profiles this process created and has not yet removed. The
+ * command's own `finally` loses the race to the entry point's signal
+ * handler, whose `process.exit` never lets it run, so the handler removes
+ * these itself once the browser tree has shut down.
+ */
+const activeTemporaryProfiles = new Set();
+async function removeTemporaryProfile(dir) {
+    try {
+        await rm(dir, { recursive: true, force: true });
+        activeTemporaryProfiles.delete(dir);
+    }
+    catch (error) {
+        warn(`Could not remove temporary run profile ${dir}: ${toError(error).message}`);
+    }
+}
+/**
+ * Removes every temporary run profile this process still holds. Called by
+ * the CLI entry point's signal handler after child shutdown. Never throws.
+ */
+export async function removeActiveRunProfiles() {
+    await Promise.all([...activeTemporaryProfiles].map((dir) => removeTemporaryProfile(dir)));
+}
+const NO_PROFILE = {
+    args: [],
+    temporary: false,
+    dispose: () => Promise.resolve(),
+};
+/**
+ * Chooses the profile for a run.
+ * @param request - The run's profile flags
+ * @returns The profile arguments and their release handle
+ */
+export async function resolveRunProfile(request) {
+    if (request.profile !== undefined && request.tempProfile === true) {
+        throw new InvalidArgumentError('--profile and --temp-profile are mutually exclusive: name a profile or ask for a fresh one.', 'profile');
+    }
+    if (request.profile !== undefined) {
+        const dir = resolve(request.profile);
+        return { args: ['-profile', dir], dir, temporary: false, dispose: NO_PROFILE.dispose };
+    }
+    if (request.tempProfile !== true && !request.smoke) {
+        return NO_PROFILE;
+    }
+    const dir = await mkdtemp(join(request.tempRoot ?? tmpdir(), RUN_PROFILE_PREFIX));
+    activeTemporaryProfiles.add(dir);
+    // The owner marker goes in first, so a FireForge killed past this point
+    // leaves a directory the next run can prove abandoned.
+    await writeFile(join(dir, OWNER_MARKER), `${process.pid}\n`);
+    await writeFile(join(dir, 'user.js'), SEEDED_USER_JS);
+    verbose(`Temporary run profile: ${dir}`);
+    return {
+        args: ['-profile', dir],
+        dir,
+        temporary: true,
+        dispose: () => removeTemporaryProfile(dir),
+    };
+}
+/**
+ * Removes temporary run profiles whose owning FireForge process is gone.
+ * The `finally` that releases a profile covers a clean exit, a failed run
+ * and a forwarded SIGINT/SIGTERM, but not a SIGKILL of FireForge itself;
+ * this sweep is the backstop for that case. A directory whose marker is
+ * missing or unreadable is left alone: nothing proves it is abandoned.
+ * @param tempRoot - Base directory to sweep (defaults to the OS tmpdir)
+ * @returns The number of directories removed
+ */
+export async function sweepAbandonedRunProfiles(tempRoot = tmpdir()) {
+    let entries;
+    try {
+        entries = await readdir(tempRoot);
+    }
+    catch {
+        return 0;
+    }
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.startsWith(RUN_PROFILE_PREFIX))
+            continue;
+        const dir = join(tempRoot, entry);
+        let pid;
+        try {
+            pid = Number.parseInt((await readFile(join(dir, OWNER_MARKER), 'utf8')).trim(), 10);
+        }
+        catch {
+            continue;
+        }
+        if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid || isProcessAlive(pid)) {
+            continue;
+        }
+        try {
+            await rm(dir, { recursive: true, force: true });
+            removed += 1;
+        }
+        catch (error) {
+            verbose(`Could not remove abandoned run profile ${dir}: ${toError(error).message}`);
+        }
+    }
+    return removed;
+}

package/dist/src/core/status-binary.d.ts

@@ -26,7 +26,7 @@
  */
 import type { PatchedContentContext } from './patch-apply.js';
 /** Batched patch lookup, injected by callers that classify many files. */
-export type AffectingPatchLookup = Pick<PatchedContentContext, 'getAffectingPatches' | 'readPatchBody'>;
+export type AffectingPatchLookup = Pick<PatchedContentContext, 'getAffectingPatches' | 'readPatchBody'> & Partial<Pick<PatchedContentContext, 'liveBlobHash'>>;
 /**
  * Classification result for a binary comparison. Structurally assignable
  * to `ClassifiedFile` without importing it (which would create a cycle

package/dist/src/core/status-binary.js

@@ -111,7 +111,9 @@ export async function classifyBinaryOwnedFile(args) {
         }
         if (section.hasBinaryDelta && section.indexNewHash !== undefined) {
             const fullPath = join(engineDir, entry.file);
-            const live = (await hashObjectBatch(engineDir, [fullPath])).get(fullPath);
+            const live = args.lookup?.liveBlobHash !== undefined
+                ? await args.lookup.liveBlobHash(fullPath)
+                : (await hashObjectBatch(engineDir, [fullPath])).get(fullPath);
             if (live !== undefined) {
                 // Prefix-compare: recorded hashes may be abbreviated (≥7 chars).
                 const matches = live.startsWith(section.indexNewHash) || section.indexNewHash.startsWith(live);

package/dist/src/core/status-classify.js

@@ -13,6 +13,7 @@ import { readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { normalizePathSlashes } from '../utils/paths.js';
 import { isBrandingManagedPath } from './branding.js';
+import { isBinaryFile } from './git-file-ops.js';
 import { createPatchedContentContext } from './patch-apply.js';
 import { classifyBinaryOwnedFile } from './status-binary.js';
 /**
@@ -141,6 +142,7 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
     // expected-vs-actual content comparison then routes them into `unmanaged`
     // when the content matches neither owner's expectation.
     const patchClaims = buildPatchClaims(ctx.manifestPatches);
+    await prefetchSingleOwnerContent(files, engineDir, patchClaims, ctx);
     const deps = {
         engineDir,
         patchesDir,
@@ -149,12 +151,37 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
         patchClaims,
         ctx,
     };
-    // Bounded pool over per-file classification (each single-owner file
-    // spawns git). Order preserved by the mapper. Per-file failures settle
+    // Bounded pool over per-file classification. Order preserved by the mapper. Per-file failures settle
     // inside classifySingleOwnerFile's catch, so one bad file never rejects
     // the batch.
     return mapWithConcurrency(files, CLASSIFY_CONCURRENCY, (entry) => classifyEntry(entry, deps));
 }
+/**
+ * Fetches, in two git processes, what the per-file comparison would
+ * otherwise spawn git for file by file: the HEAD content of every
+ * single-owner path (one `cat-file --batch`) and the live blob hash of every
+ * one that is binary on disk (one `hash-object` per ARG_MAX chunk). On a
+ * 1,600-file Firefox scan that was ~1,550 `git show` and `hash-object`
+ * spawns. Fetching for a path the classifier ends up routing elsewhere
+ * (a branding path, say) costs a few bytes, never a wrong answer.
+ */
+async function prefetchSingleOwnerContent(files, engineDir, patchClaims, ctx) {
+    const singleOwner = files.filter((entry) => patchClaims.get(entry.file)?.length === 1);
+    if (singleOwner.length === 0)
+        return;
+    await ctx.prefetchBase(singleOwner.map((entry) => entry.file));
+    const present = singleOwner.filter((entry) => getPrimaryStatusCode(entry.status) !== 'D');
+    const binary = await mapWithConcurrency(present, CLASSIFY_CONCURRENCY, async (entry) => {
+        try {
+            return (await isBinaryFile(engineDir, entry.file)) ? join(engineDir, entry.file) : undefined;
+        }
+        catch {
+            // The per-file path probes again and settles the failure itself.
+            return undefined;
+        }
+    });
+    await ctx.prefetchLiveBlobHashes(binary.filter((path) => path !== undefined));
+}
 /** Concurrency bound for per-file classification (matches import's guard). */
 const CLASSIFY_CONCURRENCY = 8;
 /** Classifies one status entry. Extracted so the pool worker stays flat. */

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>;