@hominis/fireforge 0.49.2 → 0.51.0

package/dist/src/core/build-baseline.js

@@ -81,7 +81,7 @@ export async function readBuildBaseline(projectRoot, invalid = 'ignore') {
  * @param options - See {@link WriteBuildBaselineOptions}
  */
 export async function writeBuildBaseline(options) {
-    const { projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', } = options;
+    const { projectRoot, engineDir, binaryName, testPackagingCoverage, testCoverageRecords, fullCoverageAnchor, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full', } = options;
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -116,6 +116,8 @@ export async function writeBuildBaseline(options) {
         ...(testInputFingerprints !== undefined ? { testInputFingerprints } : {}),
         ...(buildInputFingerprints !== undefined ? { buildInputFingerprints } : {}),
         ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
+        ...(testCoverageRecords !== undefined ? { testCoverageRecords } : {}),
+        ...(fullCoverageAnchor !== undefined ? { fullCoverageAnchor } : {}),
         ...(mozconfigHash !== undefined ? { mozconfigHash } : {}),
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
         ...(recordedBy !== undefined ? { recordedBy } : {}),

package/dist/src/core/build-overwrite-guard.d.ts

@@ -14,8 +14,17 @@
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing
  * under an explicit flag.
+ *
+ * A deployed Furnace file is checked against its component source as well
+ * (`deployed-unexported`): when the engine copy equals the Furnace-composed
+ * current source, differs from it only inside generated fragment
+ * expansions, or is exactly Furnace's last recorded deployment, the
+ * overwrite destroys nothing that is not a component source, so it is safe
+ * even though no patch records it yet. Without this, peers' deployed but
+ * unexported widgets refused every belted build on a shared checkout.
  */
 import type { FireForgeConfig } from '../types/config.js';
+import { type DeployedSourceMatch } from './furnace-composed-source.js';
 import { type ClassifiedFile } from './status-classify.js';
 /** One file whose unexported content a build-prepare overwrite would destroy. */
 export interface UnexportedDriftAtRisk {
@@ -23,6 +32,24 @@ export interface UnexportedDriftAtRisk {
     classification: ClassifiedFile['classification'];
     owner?: string | undefined;
 }
+/**
+ * A deployed Furnace file no patch records yet whose content is its
+ * component source's (see {@link DeployedSourceMatch}), so the overwrite is
+ * safe. Its patch still owes a re-export.
+ */
+export interface DeployedUnexportedFile {
+    file: string;
+    classification: 'deployed-unexported';
+    match: DeployedSourceMatch;
+    owner?: string | undefined;
+}
+/** Outcome of {@link assessUnexportedDrift}. */
+export interface UnexportedDriftAssessment {
+    /** Files whose content the overwrite would destroy unrecorded. */
+    atRisk: UnexportedDriftAtRisk[];
+    /** Files the overwrite rewrites from their own component source. */
+    deployedUnexported: DeployedUnexportedFile[];
+}
 /**
  * Finds engine files that build-prepare is about to overwrite and whose
  * current content is recorded nowhere.
@@ -30,11 +57,34 @@ export interface UnexportedDriftAtRisk {
  * Fail-open: any probe failure is reported verbosely and yields an empty
  * list. A build must not fail because an advisory guard could not run.
  *
+ * @internal The at-risk half of {@link assessUnexportedDrift}, kept for the
+ * guard's tests; build-prepare consumes the full assessment.
+ *
  * @param projectRoot - Project root
  * @param config - Loaded FireForge config (reads `binaryName`)
  * @returns At-risk files, sorted by path
  */
 export declare function findUnexportedDriftAtRisk(projectRoot: string, config: FireForgeConfig): Promise<UnexportedDriftAtRisk[]>;
+/**
+ * Classifies the engine files build-prepare is about to overwrite into the
+ * ones whose content is recorded nowhere (`atRisk`) and the deployed
+ * Furnace files no patch records yet whose content is their component
+ * source's (`deployedUnexported`, safe to overwrite).
+ *
+ * Fail-open like {@link findUnexportedDriftAtRisk}: a probe failure yields
+ * an empty assessment.
+ *
+ * @param projectRoot - Project root
+ * @param config - Loaded FireForge config (reads `binaryName`)
+ * @returns Both lists, sorted by path
+ */
+export declare function assessUnexportedDrift(projectRoot: string, config: FireForgeConfig): Promise<UnexportedDriftAssessment>;
+/**
+ * Renders the informational note for deployed Furnace files the overwrite
+ * rewrites from their own component source: safe for this build, but their
+ * patches still owe a re-export.
+ */
+export declare function formatDeployedUnexportedNote(files: readonly DeployedUnexportedFile[]): string;
 /**
  * Renders the operator-facing warning (or refusal body) naming every file
  * whose unexported content the build is about to overwrite.

package/dist/src/core/build-overwrite-guard.js

@@ -15,10 +15,19 @@
  * whose content is explained by neither a patch body nor the pristine
  * baseline. Advisory by default (a warning naming every file), refusing
  * under an explicit flag.
+ *
+ * A deployed Furnace file is checked against its component source as well
+ * (`deployed-unexported`): when the engine copy equals the Furnace-composed
+ * current source, differs from it only inside generated fragment
+ * expansions, or is exactly Furnace's last recorded deployment, the
+ * overwrite destroys nothing that is not a component source, so it is safe
+ * even though no patch records it yet. Without this, peers' deployed but
+ * unexported widgets refused every belted build on a shared checkout.
  */
 import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { getProjectPaths } from './config.js';
+import { matchDeployedComponentFiles, } from './furnace-composed-source.js';
 import { collectFurnaceManagedPrefixes } from './furnace-config.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from './git-status.js';
 import { classifyFiles } from './status-classify.js';
@@ -98,6 +107,40 @@ async function collectOverwrittenEntries(engineDir, status, binaryName, furnaceP
     return expanded.filter((entry) => !entry.file.endsWith('/') &&
         isOverwrittenByBuildPrepare(entry.file, binaryName, furnacePrefixes));
 }
+/**
+ * Splits classified at-risk files into the ones whose engine content is a
+ * Furnace deployment of their component source and the rest.
+ *
+ * Fail-closed: when the source comparison cannot run, every file stays at
+ * risk, exactly as before the comparison existed.
+ */
+async function separateDeployedUnexported(projectRoot, engineDir, atRisk) {
+    let matches;
+    try {
+        matches = await matchDeployedComponentFiles(projectRoot, engineDir, atRisk.map((entry) => entry.file));
+    }
+    catch (error) {
+        verbose(`Unexported-drift guard could not compare component sources: ${toError(error).message}`);
+        return { atRisk, deployedUnexported: [] };
+    }
+    const deployedUnexported = [];
+    const remaining = [];
+    for (const entry of atRisk) {
+        const match = matches.get(entry.file);
+        if (match === undefined) {
+            remaining.push(entry);
+        }
+        else {
+            deployedUnexported.push({
+                file: entry.file,
+                classification: 'deployed-unexported',
+                match,
+                owner: entry.owner,
+            });
+        }
+    }
+    return { atRisk: remaining, deployedUnexported };
+}
 /**
  * Finds engine files that build-prepare is about to overwrite and whose
  * current content is recorded nowhere.
@@ -105,22 +148,42 @@ async function collectOverwrittenEntries(engineDir, status, binaryName, furnaceP
  * Fail-open: any probe failure is reported verbosely and yields an empty
  * list. A build must not fail because an advisory guard could not run.
  *
+ * @internal The at-risk half of {@link assessUnexportedDrift}, kept for the
+ * guard's tests; build-prepare consumes the full assessment.
+ *
  * @param projectRoot - Project root
  * @param config - Loaded FireForge config (reads `binaryName`)
  * @returns At-risk files, sorted by path
  */
 export async function findUnexportedDriftAtRisk(projectRoot, config) {
+    return (await assessUnexportedDrift(projectRoot, config)).atRisk;
+}
+/**
+ * Classifies the engine files build-prepare is about to overwrite into the
+ * ones whose content is recorded nowhere (`atRisk`) and the deployed
+ * Furnace files no patch records yet whose content is their component
+ * source's (`deployedUnexported`, safe to overwrite).
+ *
+ * Fail-open like {@link findUnexportedDriftAtRisk}: a probe failure yields
+ * an empty assessment.
+ *
+ * @param projectRoot - Project root
+ * @param config - Loaded FireForge config (reads `binaryName`)
+ * @returns Both lists, sorted by path
+ */
+export async function assessUnexportedDrift(projectRoot, config) {
+    const empty = { atRisk: [], deployedUnexported: [] };
     const paths = getProjectPaths(projectRoot);
     try {
         const status = await getWorkingTreeStatus(paths.engine);
         if (status.length === 0)
-            return [];
+            return empty;
         const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
         const candidates = await collectOverwrittenEntries(paths.engine, status, config.binaryName, furnacePrefixes);
         if (candidates.length === 0)
-            return [];
+            return empty;
         const classified = await classifyFiles(candidates, paths.engine, paths.patches, config.binaryName, furnacePrefixes);
-        return classified
+        const atRisk = classified
             .filter((entry) => AT_RISK_CLASSIFICATIONS.has(entry.classification))
             .map((entry) => ({
             file: entry.file,
@@ -128,12 +191,29 @@ export async function findUnexportedDriftAtRisk(projectRoot, config) {
             owner: entry.owner,
         }))
             .sort((a, b) => a.file.localeCompare(b.file));
+        if (atRisk.length === 0 || furnacePrefixes.size === 0)
+            return { ...empty, atRisk };
+        return await separateDeployedUnexported(projectRoot, paths.engine, atRisk);
     }
     catch (error) {
         verbose(`Unexported-drift guard could not run: ${toError(error).message}`);
-        return [];
+        return empty;
     }
 }
+/**
+ * Renders the informational note for deployed Furnace files the overwrite
+ * rewrites from their own component source: safe for this build, but their
+ * patches still owe a re-export.
+ */
+export function formatDeployedUnexportedNote(files) {
+    const rows = files.map((entry) => {
+        const owner = entry.owner !== undefined ? ` (owned by ${entry.owner})` : '';
+        return `  ${entry.file} [deployed-unexported: ${entry.match}]${owner}`;
+    });
+    return (`${files.length} deployed Furnace file(s) differ from their patch body but are a Furnace ` +
+        'deployment of their component source, so this overwrite loses nothing; re-export their ' +
+        `patches when the component work is done:\n${rows.join('\n')}`);
+}
 /**
  * Renders the operator-facing warning (or refusal body) naming every file
  * whose unexported content the build is about to overwrite.

package/dist/src/core/build-prepare.d.ts

@@ -10,6 +10,8 @@ import type { BuildBaseline } from './build-baseline-types.js';
 export interface BuildPreparation {
     /** Number of Furnace components applied (0 if none or no furnace.json) */
     furnaceApplied: number;
+    /** Names of the Furnace components applied, in apply order. */
+    furnaceAppliedNames?: string[];
     /** True when `mach configure` was auto-run to refresh a stale backend. */
     reconfigured: boolean;
     /** A changed packaging manifest cannot be safely handled by `mach build faster`. */
@@ -35,6 +37,17 @@ export interface PrepareBuildOptions {
      * Scripted gates want the stop. An interactive build wants the warning.
      */
     refuseUnexportedDrift?: boolean | undefined;
+    /**
+     * Skip the Furnace apply, so the build packages engine/ as it stands
+     * (`fireforge test --build --no-furnace-apply`).
+     */
+    skipFurnaceApply?: boolean | undefined;
+    /**
+     * Apply only these components (`fireforge test --build --furnace-apply
+     * reached`). Undefined applies every component with undeployed edits; an
+     * empty list applies none.
+     */
+    furnaceComponents?: readonly string[] | undefined;
 }
 /**
  * Describes an exit code in the shell's 128+N signal convention. Truncated

package/dist/src/core/build-prepare.js

@@ -13,7 +13,7 @@ import { info, notice, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { isBuildInputPath, isJarManifestPath } from './build-audit.js';
 import { evaluateJarManifestEscalation, formatJarEscalationNotice, } from './build-jar-escalation.js';
-import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
+import { assessUnexportedDrift, formatDeployedUnexportedNote, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
 import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
@@ -156,7 +156,12 @@ export function isBackendInvalidatingFile(path) {
  * @throws GeneralError under `--refuse-unexported-drift`
  */
 async function reportUnexportedDriftBeforeOverwrite(projectRoot, config, options) {
-    const atRisk = await findUnexportedDriftAtRisk(projectRoot, config);
+    const { atRisk, deployedUnexported } = await assessUnexportedDrift(projectRoot, config);
+    // Deployed Furnace files that are their component source's own
+    // deployment never block: the overwrite loses nothing. Say so, since
+    // their patches still owe a re-export.
+    if (deployedUnexported.length > 0)
+        info(formatDeployedUnexportedNote(deployedUnexported));
     if (atRisk.length === 0)
         return;
     const message = formatUnexportedDriftWarning(atRisk);
@@ -165,24 +170,48 @@ async function reportUnexportedDriftBeforeOverwrite(projectRoot, config, options
     }
     notice(message);
 }
+/**
+ * Applies the named components one at a time, each under its own Furnace
+ * mutation (one rollback journal per apply), and merges the results.
+ */
+async function applySelectedComponents(projectRoot, names) {
+    const merged = {
+        applied: [],
+        skipped: [],
+        errors: [],
+        warnings: [],
+    };
+    for (const componentName of names) {
+        const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx, componentName }));
+        merged.applied.push(...result.applied);
+        merged.skipped.push(...result.skipped);
+        merged.errors.push(...result.errors);
+        merged.warnings.push(...(result.warnings ?? []));
+    }
+    return merged;
+}
 /**
  * Applies Furnace components before the build when `furnace.json` exists.
  * Prints every warning the apply computed, then the loud sync banner.
  *
  * @param projectRoot - Project root
- * @returns Number of components written to engine/
+ * @param only - Apply just these components; every component when undefined
+ * @returns Names of the components written to engine/
  */
-async function applyFurnaceBeforeBuild(projectRoot) {
+async function applyFurnaceBeforeBuild(projectRoot, only) {
     if (!(await furnaceConfigExists(projectRoot)))
-        return 0;
+        return [];
     const furnaceConfig = await loadFurnaceConfig(projectRoot);
     const hasComponents = Object.keys(furnaceConfig.overrides).length > 0 || Object.keys(furnaceConfig.custom).length > 0;
     if (!hasComponents)
-        return 0;
+        return [];
     const furnaceSpinner = spinner('Applying Furnace components...');
     let result;
     try {
-        result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
+        result =
+            only === undefined
+                ? await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }))
+                : await applySelectedComponents(projectRoot, only);
     }
     catch (error) {
         furnaceSpinner.error('Failed to apply Furnace components');
@@ -230,7 +259,7 @@ async function applyFurnaceBeforeBuild(projectRoot) {
     else {
         furnaceSpinner.stop('Components up to date');
     }
-    return furnaceApplied;
+    return result.applied.map((entry) => entry.name);
 }
 /**
  * Runs the auto-configure step (`mach configure`) against the freshly
@@ -344,7 +373,9 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
             throw error;
         }
     }
-    const furnaceApplied = await applyFurnaceBeforeBuild(projectRoot);
+    const furnaceAppliedNames = options.skipFurnaceApply === true || options.furnaceComponents?.length === 0
+        ? []
+        : await applyFurnaceBeforeBuild(projectRoot, options.furnaceComponents);
     // Generate mozconfig
     const mozconfigSpinner = spinner('Generating mozconfig...');
     let mozconfigWritten;
@@ -374,7 +405,8 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
         reconfigured = true;
     }
     return {
-        furnaceApplied,
+        furnaceApplied: furnaceAppliedNames.length,
+        furnaceAppliedNames,
         reconfigured,
         fullBuildRequired,
         ...(fullBuildReason !== undefined ? { fullBuildReason } : {}),

package/dist/src/core/build-run-record.d.ts

@@ -0,0 +1,74 @@
+/**
+ * A record of the mach build in flight, kept in `.fireforge/build-run.json`
+ * so any session on the checkout can see why the bundle is missing.
+ *
+ * An interrupted `fireforge build` (a killed peer session, a closed
+ * terminal) can leave `dist/<App>.app/Contents/MacOS/` without its
+ * executable. Every later `fireforge test`, in every session, then failed
+ * at launch with nothing saying a build had died there, and the sessions
+ * that had not run the build had no way to find out.
+ *
+ * The record is written when a protected mach build starts and removed when
+ * it succeeds. A failed build leaves it with `status: "failed"` and the exit
+ * code. A build that never reached either end, because its process died,
+ * leaves `status: "running"` with a PID that no longer exists, which is how
+ * an interrupted run is recognized. The next build that runs to the end
+ * replaces whatever was there.
+ *
+ * Best-effort throughout: a build never fails because its record could not
+ * be written, and an unreadable record reads as "no record".
+ */
+/** The persisted record. */
+interface BuildRunRecord {
+    /** Whether the build is (or was last seen) running, or ended in failure. */
+    status: 'running' | 'failed';
+    /** PID of the FireForge process that ran the build. */
+    pid: number;
+    /** That process's boot-relative start tick, where procfs exposes one. */
+    startTick?: number;
+    /** The FireForge invocation, e.g. `fireforge build --ui`. */
+    command: string;
+    /** The mach command, e.g. `mach build faster`. */
+    machCommand: string;
+    /** ISO time the mach build started. */
+    startedAt: string;
+    /** ISO time a failed build ended. */
+    endedAt?: string;
+    /** Exit code of a failed build, when mach returned one. */
+    exitCode?: number;
+}
+/** What the record says about the last build. */
+export type BuildRunState = {
+    kind: 'none';
+} | {
+    kind: 'running' | 'interrupted' | 'failed';
+    record: BuildRunRecord;
+};
+/**
+ * Runs a mach build with its run record maintained around it. The record
+ * is removed on a zero exit and kept as `failed` on a non-zero exit or a
+ * throw, so only a build whose process died mid-run is left `running`.
+ *
+ * @param projectRoot - Project root holding `.fireforge/`
+ * @param machCommand - The mach command being run
+ * @param build - The build itself
+ * @returns Whatever the build returned
+ */
+export declare function withBuildRunRecord<T extends {
+    exitCode: number;
+}>(projectRoot: string, machCommand: string, build: () => Promise<T>): Promise<T>;
+/**
+ * Reads the last build's record and decides whether its process is still
+ * running.
+ *
+ * @param projectRoot - Project root holding `.fireforge/`
+ */
+export declare function readBuildRunState(projectRoot: string): Promise<BuildRunState>;
+/**
+ * One sentence naming why the bundle may be missing, or undefined when
+ * there is no record to go on.
+ *
+ * @param state - From {@link readBuildRunState}
+ */
+export declare function describeBuildRunState(state: BuildRunState): string | undefined;
+export {};

package/dist/src/core/build-run-record.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * A record of the mach build in flight, kept in `.fireforge/build-run.json`
+ * so any session on the checkout can see why the bundle is missing.
+ *
+ * An interrupted `fireforge build` (a killed peer session, a closed
+ * terminal) can leave `dist/<App>.app/Contents/MacOS/` without its
+ * executable. Every later `fireforge test`, in every session, then failed
+ * at launch with nothing saying a build had died there, and the sessions
+ * that had not run the build had no way to find out.
+ *
+ * The record is written when a protected mach build starts and removed when
+ * it succeeds. A failed build leaves it with `status: "failed"` and the exit
+ * code. A build that never reached either end, because its process died,
+ * leaves `status: "running"` with a PID that no longer exists, which is how
+ * an interrupted run is recognized. The next build that runs to the end
+ * replaces whatever was there.
+ *
+ * Best-effort throughout: a build never fails because its record could not
+ * be written, and an unreadable record reads as "no record".
+ */
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { writeFileAtomic } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { isLockOwnerAlive, readProcessStartTick } from './file-lock-owner.js';
+/** File name of the record under `.fireforge/`. */
+const BUILD_RUN_RECORD = 'build-run.json';
+function recordPath(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, BUILD_RUN_RECORD);
+}
+async function writeRecord(projectRoot, record) {
+    try {
+        await writeFileAtomic(recordPath(projectRoot), `${JSON.stringify(record, null, 2)}\n`);
+    }
+    catch (error) {
+        verbose(`Build run record not written: ${toError(error).message}`);
+    }
+}
+/**
+ * Runs a mach build with its run record maintained around it. The record
+ * is removed on a zero exit and kept as `failed` on a non-zero exit or a
+ * throw, so only a build whose process died mid-run is left `running`.
+ *
+ * @param projectRoot - Project root holding `.fireforge/`
+ * @param machCommand - The mach command being run
+ * @param build - The build itself
+ * @returns Whatever the build returned
+ */
+export async function withBuildRunRecord(projectRoot, machCommand, build) {
+    const startTick = readProcessStartTick(process.pid);
+    const started = {
+        status: 'running',
+        pid: process.pid,
+        ...(startTick !== undefined ? { startTick } : {}),
+        command: ['fireforge', ...process.argv.slice(2)].join(' '),
+        machCommand,
+        startedAt: new Date().toISOString(),
+    };
+    await writeRecord(projectRoot, started);
+    let result;
+    try {
+        result = await build();
+    }
+    catch (error) {
+        await writeRecord(projectRoot, {
+            ...started,
+            status: 'failed',
+            endedAt: new Date().toISOString(),
+        });
+        throw error;
+    }
+    if (result.exitCode === 0) {
+        await rm(recordPath(projectRoot), { force: true }).catch(() => undefined);
+    }
+    else {
+        await writeRecord(projectRoot, {
+            ...started,
+            status: 'failed',
+            endedAt: new Date().toISOString(),
+            exitCode: result.exitCode,
+        });
+    }
+    return result;
+}
+/**
+ * Reads the last build's record and decides whether its process is still
+ * running.
+ *
+ * @param projectRoot - Project root holding `.fireforge/`
+ */
+export async function readBuildRunState(projectRoot) {
+    let record;
+    try {
+        record = JSON.parse(await readFile(recordPath(projectRoot), 'utf8'));
+    }
+    catch {
+        return { kind: 'none' };
+    }
+    if (typeof record.pid !== 'number' || typeof record.startedAt !== 'string') {
+        return { kind: 'none' };
+    }
+    if (record.status === 'failed')
+        return { kind: 'failed', record };
+    return {
+        kind: isLockOwnerAlive({ pid: record.pid, startTick: record.startTick })
+            ? 'running'
+            : 'interrupted',
+        record,
+    };
+}
+/**
+ * One sentence naming why the bundle may be missing, or undefined when
+ * there is no record to go on.
+ *
+ * @param state - From {@link readBuildRunState}
+ */
+export function describeBuildRunState(state) {
+    if (state.kind === 'none')
+        return undefined;
+    const { record } = state;
+    const who = `"${record.command}" (${record.machCommand}, PID ${record.pid}, started ${record.startedAt})`;
+    switch (state.kind) {
+        case 'running':
+            return `A build is running right now: ${who}. The bundle is incomplete until it finishes.`;
+        case 'interrupted':
+            return (`The last build never finished: ${who} is gone without recording an end, so it was ` +
+                'interrupted (killed, or its terminal closed) part-way, which leaves the bundle without ' +
+                'its executable.');
+        case 'failed':
+            return (`The last build failed: ${who} ended ${record.endedAt ?? 'at an unrecorded time'}` +
+                `${record.exitCode !== undefined ? ` with exit code ${record.exitCode}` : ''}.`);
+    }
+}

package/dist/src/core/checkjs-support-heads.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Unowned support heads for the named-file checkJs pass of `test --build`.
+ *
+ * Each named test is checked as its own program: the test plus the
+ * patch-owned `head*.js` beside it. A suite moved onto a NEW support head
+ * (`head_world_page.js`, loaded with `loadSubScript`) cannot be proven
+ * before that head is exported, because the head is in no patch: every kit
+ * name reads as "Cannot find name" and the run is refused at preflight,
+ * with the generic hint, which offers the shim as a remedy.
+ *
+ * So an unowned same-directory `head*.js` joins the pass when a named test
+ * loads it with `loadSubScript` or a manifest beside it lists it in
+ * `support-files`, which are the two ways the harness itself would bring
+ * it into the test's scope. The operator is told it is unowned and how to
+ * adopt it, as for the `head.js` companions in
+ * `patch-lint-unmanaged-companion.ts`.
+ */
+/** A same-directory head no patch owns, and why the pass includes it. */
+export interface UnownedSupportHead {
+    /** Engine-relative path of the head. */
+    file: string;
+    /** What brings it into the test's scope. */
+    reason: string;
+}
+/**
+ * Finds the unowned same-directory `head*.js` files the named tests bring
+ * into scope.
+ *
+ * @param engineDir - Absolute engine directory
+ * @param selected - Engine-relative named test files
+ * @param owned - Every file the pass already includes
+ */
+export declare function findUnownedSupportHeads(engineDir: string, selected: Iterable<string>, owned: ReadonlySet<string>): Promise<UnownedSupportHead[]>;
+/**
+ * The notice for an included unowned head: the ownership fact, the
+ * adoption command, and an explicit "not the shim", for the same reason
+ * `formatUnmanagedCompanionHint` gives.
+ *
+ * @param head - From {@link findUnownedSupportHeads}
+ */
+export declare function formatUnownedSupportHeadNotice(head: UnownedSupportHead): string;