@hominis/fireforge 0.46.1 → 0.47.0

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

@@ -16,6 +16,7 @@ import { evaluateJarManifestEscalation, formatJarEscalationNotice, } from './bui
 import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
 import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
+import { logApplyWarnings } from './furnace-apply-output.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
@@ -114,15 +115,14 @@ function buildConfigureFailureError(captured) {
  *
  * @param engineDir - Absolute engine directory
  * @param changed - Build inputs changed since the last successful build
- * @param baseline - Last successful build's baseline
  */
-async function decideJarEscalation(engineDir, changed, baseline) {
+async function decideJarEscalation(engineDir, changed) {
     // Packaging manifests whose graph/destination directories may need a full
     // build. Path-shape only: `evaluateJarManifestEscalation` decides whether a
     // given changed manifest actually forces one (a new manifest, or one that
     // redirects its install base directory), so an entry added to an existing
     // `dist/bin` manifest no longer costs a ~10-minute build.
-    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath), baseline);
+    const decision = await evaluateJarManifestEscalation(engineDir, changed.filter(isJarManifestPath));
     if (decision.cleared.length > 0) {
         verbose(`jar escalation: ${decision.cleared.length} changed jar.mn add entries to an existing dist/bin manifest; not escalating for ${decision.cleared.join(', ')}.`);
     }
@@ -164,6 +164,73 @@ async function reportUnexportedDriftBeforeOverwrite(projectRoot, config, options
     }
     notice(message);
 }
+/**
+ * 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/
+ */
+async function applyFurnaceBeforeBuild(projectRoot) {
+    if (!(await furnaceConfigExists(projectRoot)))
+        return 0;
+    const furnaceConfig = await loadFurnaceConfig(projectRoot);
+    const hasComponents = Object.keys(furnaceConfig.overrides).length > 0 || Object.keys(furnaceConfig.custom).length > 0;
+    if (!hasComponents)
+        return 0;
+    const furnaceSpinner = spinner('Applying Furnace components...');
+    let result;
+    try {
+        result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
+    }
+    catch (error) {
+        furnaceSpinner.error('Failed to apply Furnace components');
+        throw error;
+    }
+    const furnaceApplied = result.applied.length;
+    // Count entries that were "applied" but recorded step-level errors
+    // mid-apply (e.g. a post-step failure after file writes succeeded).
+    // These are distinct from `result.errors`, which captures
+    // components that failed before reaching the applied list at all.
+    // The sum of the two is the total count of failed components.
+    const appliedWithStepErrorsCount = countEntriesWithBlockingStepErrors(result.applied);
+    const totalApplyFailures = result.errors.length + appliedWithStepErrorsCount;
+    if (totalApplyFailures > 0) {
+        furnaceSpinner.error('Failed to apply Furnace components');
+        for (const err of result.errors) {
+            warn(`Furnace: ${err.name} — ${err.error}`);
+        }
+        for (const applied of result.applied) {
+            if (applied.stepErrors && applied.stepErrors.length > 0) {
+                for (const stepErr of applied.stepErrors) {
+                    warn(`Furnace: ${applied.name} [${stepErr.step}] ${stepErr.error}`);
+                }
+            }
+        }
+        throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
+    }
+    // The apply computed these (patch-owned engine files whose content
+    // differed from components/ and were replaced). `furnace apply`
+    // prints them; this path used to drop them, so a negative control
+    // that edited a deployed Furnace file ran against the shipped code
+    // with a green result and only a checksum could tell.
+    const overwriteCount = logApplyWarnings(result.warnings);
+    if (overwriteCount > 0) {
+        notice(`Furnace: ${overwriteCount} Furnace-managed engine file${overwriteCount === 1 ? '' : 's'} differed from components/ and ${overwriteCount === 1 ? 'was' : 'were'} REPLACED before this build. An engine-side edit to a Furnace-managed file (for example a negative control) did not run; edit the component source under components/ instead, or restore the edit after the build.`);
+    }
+    if (furnaceApplied > 0) {
+        const appliedNames = result.applied.map((entry) => entry.name).join(', ');
+        furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
+        // Loud banner: the build operator needs to see that engine/ was
+        // updated before this build, otherwise a silent re-apply is
+        // indistinguishable from a build that shipped stale components.
+        notice(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
+    }
+    else {
+        furnaceSpinner.stop('Components up to date');
+    }
+    return furnaceApplied;
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Warns (or refuses) about unexported engine drift the writes below
@@ -202,7 +269,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     if (options.previousBaseline) {
         const changed = await collectChangedBuildInputs(paths.engine, options.previousBaseline);
         const invalidating = changed.filter(isBackendInvalidatingFile);
-        const jarEscalation = await decideJarEscalation(paths.engine, changed, options.previousBaseline);
+        const jarEscalation = await decideJarEscalation(paths.engine, changed);
         fullBuildRequired = jarEscalation !== undefined;
         fullBuildReason = jarEscalation;
         if (invalidating.length > 0) {
@@ -263,57 +330,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
             throw error;
         }
     }
-    // Apply Furnace components if furnace.json exists
-    let furnaceApplied = 0;
-    if (await furnaceConfigExists(projectRoot)) {
-        const furnaceConfig = await loadFurnaceConfig(projectRoot);
-        const hasComponents = Object.keys(furnaceConfig.overrides).length > 0 ||
-            Object.keys(furnaceConfig.custom).length > 0;
-        if (hasComponents) {
-            const furnaceSpinner = spinner('Applying Furnace components...');
-            let result;
-            try {
-                result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
-            }
-            catch (error) {
-                furnaceSpinner.error('Failed to apply Furnace components');
-                throw error;
-            }
-            furnaceApplied = result.applied.length;
-            // Count entries that were "applied" but recorded step-level errors
-            // mid-apply (e.g. a post-step failure after file writes succeeded).
-            // These are distinct from `result.errors`, which captures
-            // components that failed before reaching the applied list at all.
-            // The sum of the two is the total count of failed components.
-            const appliedWithStepErrorsCount = countEntriesWithBlockingStepErrors(result.applied);
-            const totalApplyFailures = result.errors.length + appliedWithStepErrorsCount;
-            if (totalApplyFailures > 0) {
-                furnaceSpinner.error('Failed to apply Furnace components');
-                for (const err of result.errors) {
-                    warn(`Furnace: ${err.name} — ${err.error}`);
-                }
-                for (const applied of result.applied) {
-                    if (applied.stepErrors && applied.stepErrors.length > 0) {
-                        for (const stepErr of applied.stepErrors) {
-                            warn(`Furnace: ${applied.name} [${stepErr.step}] ${stepErr.error}`);
-                        }
-                    }
-                }
-                throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
-            }
-            if (furnaceApplied > 0) {
-                const appliedNames = result.applied.map((entry) => entry.name).join(', ');
-                furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
-                // Loud banner: the build operator needs to see that engine/ was
-                // updated before this build, otherwise a silent re-apply is
-                // indistinguishable from a build that shipped stale components.
-                notice(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
-            }
-            else {
-                furnaceSpinner.stop('Components up to date');
-            }
-        }
-    }
+    const furnaceApplied = await applyFurnaceBeforeBuild(projectRoot);
     // Generate mozconfig
     const mozconfigSpinner = spinner('Generating mozconfig...');
     try {

package/dist/src/core/firefox-cache.js

@@ -242,8 +242,7 @@ async function removeArchivePartFiles(archive, cacheDir) {
             .filter((name) => name.startsWith(partPrefix))
             .map((name) => removeFile(join(cacheDir, name))));
     }
-    catch (error) {
-        void error;
+    catch {
         // Cache dir may not exist yet. That's fine.
     }
 }

package/dist/src/core/furnace-apply-output.d.ts

@@ -13,4 +13,14 @@ type ApplyResultWithActions = ApplyResult & {
  * @param isDryRun - Whether apply was invoked with dryRun=true
  */
 export declare function logApplyResult(result: ApplyResultWithActions, isDryRun: boolean): void;
+/**
+ * Prints the operator-facing apply warnings (patch-owned overwrites) one
+ * per line and returns how many were printed. Shared by `furnace apply`
+ * and the pre-build source → engine sync, so a warning the apply computed
+ * is never dropped on one path and printed on the other.
+ *
+ * @param warnings - `result.warnings` from applyAllComponents
+ * @returns Number of warning lines printed
+ */
+export declare function logApplyWarnings(warnings: readonly string[] | undefined): number;
 export {};

package/dist/src/core/furnace-apply-output.js

@@ -55,12 +55,27 @@ export function logApplyResult(result, isDryRun) {
     // outcome, including the rolled-back branch, where the overwrite
     // happened before the rollback restored it and the operator still needs
     // to know the deployed copy was momentarily replaced.
-    if (!isDryRun && result.warnings !== undefined) {
-        for (const line of result.warnings) {
-            warn(line);
-        }
+    if (!isDryRun) {
+        logApplyWarnings(result.warnings);
     }
     for (const err of result.errors) {
         error(`${err.name} — ${err.error}`);
     }
 }
+/**
+ * Prints the operator-facing apply warnings (patch-owned overwrites) one
+ * per line and returns how many were printed. Shared by `furnace apply`
+ * and the pre-build source → engine sync, so a warning the apply computed
+ * is never dropped on one path and printed on the other.
+ *
+ * @param warnings - `result.warnings` from applyAllComponents
+ * @returns Number of warning lines printed
+ */
+export function logApplyWarnings(warnings) {
+    if (warnings === undefined)
+        return 0;
+    for (const line of warnings) {
+        warn(line);
+    }
+    return warnings.length;
+}

package/dist/src/core/furnace-css-fragments.d.ts

@@ -20,6 +20,13 @@
  */
 import type { ValidationIssue } from '../types/furnace.js';
 export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
+/**
+ * Reads a shared fragment as the exact body an expansion inlines: the
+ * trailing newline is dropped so the fenced block ends on the end marker.
+ * One definition, so every consumer (expansion, validation, the stale
+ * includer probe) compares the same bytes.
+ */
+export declare function readFragmentSource(sharedDir: string, name: string): Promise<string>;
 /** Returns the fragment names referenced by `@fireforge-include` directives. */
 export declare function listFragmentIncludes(css: string): string[];
 /**

package/dist/src/core/furnace-css-fragments.js

@@ -29,6 +29,15 @@ export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 import { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 const INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-include\s+([\w./-]+)\s*\*\/\s*$/;
 const END_INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-end-include\s+([\w./-]+)\s*\*\/\s*$/;
+/**
+ * Reads a shared fragment as the exact body an expansion inlines: the
+ * trailing newline is dropped so the fenced block ends on the end marker.
+ * One definition, so every consumer (expansion, validation, the stale
+ * includer probe) compares the same bytes.
+ */
+export async function readFragmentSource(sharedDir, name) {
+    return (await readText(join(sharedDir, name))).replace(/\n$/, '');
+}
 /** Returns the fragment names referenced by `@fireforge-include` directives. */
 export function listFragmentIncludes(css) {
     const names = [];
@@ -93,12 +102,12 @@ export async function expandCssFragments(css, sharedDir) {
             throw new FurnaceError(`CSS fragment "${name}" not found in components/${SHARED_FRAGMENTS_DIR}/. ` +
                 'Create the fragment file or remove the @fireforge-include directive.');
         }
-        const content = await readText(fragmentPath);
+        const content = await readFragmentSource(sharedDir, name);
         if (listFragmentIncludes(content).length > 0) {
             throw new FurnaceError(`CSS fragment "${name}" contains an @fireforge-include directive of its own; ` +
                 'nested fragment includes are not supported.');
         }
-        fragments.set(name, content.replace(/\n$/, ''));
+        fragments.set(name, content);
     }
     const out = [];
     for (const line of stripped.split('\n')) {
@@ -226,7 +235,7 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
             }
             if (deployedBodies === null)
                 continue;
-            const fragmentContent = (await readText(fragmentPath)).replace(/\n$/, '');
+            const fragmentContent = await readFragmentSource(sharedDir, include);
             const deployed = deployedBodies.get(include);
             if (deployed === undefined || deployed !== fragmentContent) {
                 issues.push({

package/dist/src/core/furnace-fragment-includers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Reverse index from shared CSS fragments to the custom components that
+ * include them, plus the staleness probe a targeted `furnace deploy <tag>`
+ * runs over the OTHER includers of the fragments it just refreshed.
+ *
+ * Fragment staleness was only ever a validator finding
+ * (`stale-fragment-expansion` in {@link validateCssFragments}), printed per
+ * includer by `furnace validate` and `deploy --dry-run`. A targeted deploy
+ * validates only the component it was asked for, so the one command that
+ * changes a fragment's deployed state for SOME includers is the one that
+ * never mentioned the rest: after a fragment edit, `deploy <a> <b>` left
+ * every other consumer carrying the old expansion, and nothing said so
+ * until a `grep` over the engine found it.
+ *
+ * Only custom components are indexed. Override components are copied
+ * byte-for-byte and never expand fragments.
+ */
+import type { CustomComponentConfig } from '../types/furnace.js';
+import type { FurnacePaths } from './furnace-config.js';
+/** One includer whose deployed sheets carry a stale expansion. */
+export interface StaleFragmentIncluder {
+    /** Custom component tag. */
+    tag: string;
+    /** Fragments (relative to `components/shared/`) whose expansion is stale. */
+    fragments: string[];
+}
+/**
+ * Maps every fragment name to the custom tags whose workspace sheets
+ * include it.
+ *
+ * @param customDir - `components/custom/` directory
+ * @param custom - The `custom` map from furnace.json
+ */
+export declare function collectFragmentIncluders(customDir: string, custom: Readonly<Record<string, CustomComponentConfig>>): Promise<Map<string, Set<string>>>;
+/**
+ * Finds the other DEPLOYED includers of the fragments `targetTag` includes
+ * whose engine sheets do not carry the current fragment source.
+ *
+ * Only fragments the target includes are considered: a fragment unrelated
+ * to this deploy is not its business. An includer whose engine sheet does
+ * not exist is not deployed and is skipped. A deployed sheet with no
+ * expansion at all counts as stale, the same rule `validateCssFragments`
+ * applies.
+ *
+ * @returns The fragments the target includes, and the stale includers
+ *   (sorted by tag), each naming the fragments that are stale for it
+ */
+export declare function findStaleIncludersOfTargetFragments(args: {
+    targetTag: string;
+    custom: Readonly<Record<string, CustomComponentConfig>>;
+    furnacePaths: FurnacePaths;
+    engineDir: string;
+}): Promise<{
+    fragments: string[];
+    stale: StaleFragmentIncluder[];
+}>;

package/dist/src/core/furnace-fragment-includers.js

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Reverse index from shared CSS fragments to the custom components that
+ * include them, plus the staleness probe a targeted `furnace deploy <tag>`
+ * runs over the OTHER includers of the fragments it just refreshed.
+ *
+ * Fragment staleness was only ever a validator finding
+ * (`stale-fragment-expansion` in {@link validateCssFragments}), printed per
+ * includer by `furnace validate` and `deploy --dry-run`. A targeted deploy
+ * validates only the component it was asked for, so the one command that
+ * changes a fragment's deployed state for SOME includers is the one that
+ * never mentioned the rest: after a fragment edit, `deploy <a> <b>` left
+ * every other consumer carrying the old expansion, and nothing said so
+ * until a `grep` over the engine found it.
+ *
+ * Only custom components are indexed. Override components are copied
+ * byte-for-byte and never expand fragments.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { extractExpandedFragmentBodies, listFragmentIncludes, readFragmentSource, } from './furnace-css-fragments.js';
+/** Workspace `.css` sheets of one custom component, with their includes. */
+async function listComponentSheetIncludes(componentDir) {
+    if (!(await pathExists(componentDir)))
+        return [];
+    let entries;
+    try {
+        entries = await readdir(componentDir);
+    }
+    catch {
+        // An unreadable component directory includes nothing. Same degradation
+        // as validateCssFragments: the index must never crash a deploy.
+        return [];
+    }
+    const sheets = [];
+    for (const fileName of entries.sort()) {
+        if (!fileName.endsWith('.css'))
+            continue;
+        const includes = listFragmentIncludes(await readText(join(componentDir, fileName)));
+        if (includes.length > 0)
+            sheets.push({ fileName, includes });
+    }
+    return sheets;
+}
+/**
+ * Maps every fragment name to the custom tags whose workspace sheets
+ * include it.
+ *
+ * @param customDir - `components/custom/` directory
+ * @param custom - The `custom` map from furnace.json
+ */
+export async function collectFragmentIncluders(customDir, custom) {
+    const index = new Map();
+    for (const tag of Object.keys(custom).sort()) {
+        for (const sheet of await listComponentSheetIncludes(join(customDir, tag))) {
+            for (const fragment of sheet.includes) {
+                const tags = index.get(fragment) ?? new Set();
+                tags.add(tag);
+                index.set(fragment, tags);
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Finds the other DEPLOYED includers of the fragments `targetTag` includes
+ * whose engine sheets do not carry the current fragment source.
+ *
+ * Only fragments the target includes are considered: a fragment unrelated
+ * to this deploy is not its business. An includer whose engine sheet does
+ * not exist is not deployed and is skipped. A deployed sheet with no
+ * expansion at all counts as stale, the same rule `validateCssFragments`
+ * applies.
+ *
+ * @returns The fragments the target includes, and the stale includers
+ *   (sorted by tag), each naming the fragments that are stale for it
+ */
+export async function findStaleIncludersOfTargetFragments(args) {
+    const { targetTag, custom, furnacePaths, engineDir } = args;
+    const index = await collectFragmentIncluders(furnacePaths.customDir, custom);
+    const fragments = [...index]
+        .filter(([, tags]) => tags.has(targetTag))
+        .map(([fragment]) => fragment)
+        .sort();
+    if (fragments.length === 0)
+        return { fragments, stale: [] };
+    const targetFragments = new Set(fragments);
+    const sources = new Map();
+    const stale = [];
+    for (const tag of Object.keys(custom).sort()) {
+        if (tag === targetTag)
+            continue;
+        const componentConfig = custom[tag];
+        if (!componentConfig)
+            continue;
+        const engineTargetDir = join(engineDir, componentConfig.targetPath);
+        const staleFragments = new Set();
+        for (const sheet of await listComponentSheetIncludes(join(furnacePaths.customDir, tag))) {
+            const relevant = sheet.includes.filter((f) => targetFragments.has(f));
+            if (relevant.length === 0)
+                continue;
+            const destPath = join(engineTargetDir, sheet.fileName);
+            if (!(await pathExists(destPath)))
+                continue;
+            const bodies = extractExpandedFragmentBodies(await readText(destPath));
+            for (const fragment of relevant) {
+                let source = sources.get(fragment);
+                if (source === undefined) {
+                    source = await readFragmentSource(furnacePaths.sharedDir, fragment);
+                    sources.set(fragment, source);
+                }
+                if (bodies.get(fragment) !== source)
+                    staleFragments.add(fragment);
+            }
+        }
+        if (staleFragments.size > 0) {
+            stale.push({ tag, fragments: [...staleFragments].sort() });
+        }
+    }
+    return { fragments, stale };
+}

package/dist/src/core/git-diff-new-file.js

@@ -31,8 +31,7 @@ function decodeStrictUtf8(bytes) {
     try {
         return strictUtf8.decode(bytes);
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/core/git-file-ops.js

@@ -199,8 +199,7 @@ export async function isBinaryFile(repoDir, filePath) {
             await fh.close();
         }
     }
-    catch (error) {
-        void error;
+    catch {
         return false;
     }
 }

package/dist/src/core/git.js

@@ -340,8 +340,7 @@ async function getLockAgeMs(lockPath) {
         const stats = await stat(lockPath);
         return Math.max(0, Date.now() - stats.mtimeMs);
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/core/mach-build-artifacts.js

@@ -140,8 +140,7 @@ export async function hasBuildArtifacts(engineDir) {
         }
         return { exists: true, objDir: selectedObjDir };
     }
-    catch (error) {
-        void error;
+    catch {
         return { exists: false };
     }
 }

package/dist/src/core/mochitest-server-port.d.ts

@@ -12,6 +12,36 @@ export declare const DEFAULT_MOCHITEST_SERVER_PORT = 8888;
  * harness's httpd has.
  */
 export declare function isMochitestServerHolder(holder: MarionettePortHolder): boolean;
+/**
+ * How a recognized harness httpd relates to the checkout about to run.
+ *
+ * `this-checkout` is debris from one of OUR interrupted runs and may be
+ * offered for termination. `foreign-checkout` is the same harness serving a
+ * LIVE run in a sibling worktree: `server.js` plus objdir provenance is
+ * exactly what a peer's in-flight suite looks like, and the only thing
+ * separating the two is whose objdir the command line points into.
+ * `unrecognized` is not the harness at all.
+ */
+export type MochitestServerHolderClass = 'this-checkout' | 'foreign-checkout' | 'unrecognized';
+/**
+ * Classifies the holder against this project's engine directory. Every
+ * absolute path on the command line is tested with {@link isPathInsideRoot}
+ * (a token test, not a substring test, so `/a/hominis/engine` does not claim
+ * a holder living under `/a/hominis-2/engine`). On POSIX the command line is
+ * the full `ps -o args=` output, so the objdir path is always present for a
+ * harness httpd; a holder whose paths all lie elsewhere belongs to another
+ * checkout.
+ *
+ * @param holder - The listener found on the port
+ * @param engineDir - Absolute engine directory of THIS project
+ */
+export declare function classifyMochitestServerHolder(holder: MarionettePortHolder, engineDir: string): MochitestServerHolderClass;
+/**
+ * The objdir a foreign holder is serving from, for the refusal text: the
+ * first absolute command-line token with an `obj-…` segment, cut at that
+ * segment. Falls back to the first absolute token, then to a placeholder.
+ */
+export declare function describeHolderObjdir(commandLine: string): string;
 /**
  * Refuses a mochitest dispatch when the harness's server port is held. It
  * terminates the holder first only for a recognized stale harness httpd,
@@ -26,10 +56,19 @@ export declare function isMochitestServerHolder(holder: MarionettePortHolder): b
  * Best effort: {@link probeMarionettePort} reports an
  * unprobeable port as free, so a host without `lsof` runs exactly as before.
  *
+ * A recognized httpd from ANOTHER checkout is a refusal and never a kill
+ * either, flag or no flag: it is a peer's live suite, not our debris. The
+ * browser-side probe draws the same line for a bare launch it cannot
+ * attribute; this one can attribute, because the objdir is on the command
+ * line, so it names the other checkout instead of offering `kill -9`.
+ *
  * @param port - Port to probe (default {@link DEFAULT_MOCHITEST_SERVER_PORT})
- * @param options - `killStaleServer` opts into terminating a recognized holder
+ * @param options - `engineDir` is this project's absolute engine directory,
+ *   the ownership boundary; `killStaleServer` opts into terminating a holder
+ *   recognized as THIS checkout's debris
  */
-export declare function ensureMochitestServerPortAvailable(port?: number, options?: {
+export declare function ensureMochitestServerPortAvailable(port: number | undefined, options: {
+    engineDir: string;
     killStaleServer?: boolean;
 }): Promise<void>;
 /**
@@ -37,6 +76,6 @@ export declare function ensureMochitestServerPortAvailable(port?: number, option
  *
  * @param port - The probed port
  * @param holder - The listener found on it
- * @param recognized - Whether it is the harness's own `server.js`
+ * @param holderClass - Whose harness `server.js` it is, if it is one at all
  */
-export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, recognized: boolean): string;
+export declare function describeMochitestServerRefusal(port: number, holder: MarionettePortHolder, holderClass: MochitestServerHolderClass): string;