@hominis/fireforge 0.42.0 → 0.43.1

package/dist/src/core/patch-lint-diff.js

@@ -50,7 +50,7 @@ export function extractAddedLinesPerFile(diffContent) {
  * unified diff. Walking each hunk with a new-file line counter (`+` and
  * context lines advance it, `-` lines do not) lets rules that need
  * full-file context — e.g. comment masking across the context/added
- * boundary (FORGE G4) — map the patch's additions onto the applied file.
+ * boundary — map the patch's additions onto the applied file.
  */
 export function extractAddedLineNumbersPerFile(diffContent) {
     const result = new Map();

package/dist/src/core/patch-lint-jsdoc.js

@@ -133,10 +133,12 @@ function walkForReturn(node) {
         node.type === 'ArrowFunctionExpression') {
         return false;
     }
-    for (const key of Object.keys(node)) {
+    // `entries` erases the node's static shape without asserting a new one;
+    // the `any` from `Object.entries`' fallback overload widens to `unknown`.
+    const entries = Object.entries(node);
+    for (const [key, val] of entries) {
         if (key === 'type')
             continue;
-        const val = node[key];
         if (val && typeof val === 'object') {
             if (Array.isArray(val)) {
                 for (const child of val) {

package/dist/src/core/patch-lint-module-registration.d.ts

@@ -7,6 +7,19 @@ interface ModuleRegistrationQueueEntry {
 interface ModuleRegistrationQueueContext {
     entries: readonly ModuleRegistrationQueueEntry[];
 }
+/**
+ * Maps Firefox's common system-module resource URLs to their source
+ * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so
+ * the resolution preflight resolves specifiers identically.
+ */
+export declare function moduleSourceSuffix(specifier: string): string | undefined;
+/**
+ * Resource-module strings in actual code (comments removed), de-duplicated.
+ * Exported for the engine-aware resolution preflight, which must recognise
+ * exactly the same specifier shapes this queue-level rule does — two
+ * extractors would drift.
+ */
+export declare function extractResourceModuleSpecifiers(content: string): string[];
 /**
  * Flags a new `.sys.mjs` imported through a Firefox resource URL when the
  * projected queue never adds it to a moz.build list.

package/dist/src/core/patch-lint-module-registration.js

@@ -5,8 +5,12 @@
 import { basename } from 'node:path';
 import { escapeRegex, stripJsComments } from '../utils/regex.js';
 const IMPORTABLE_EXTENSIONS = ['.mjs', '.sys.mjs', '.js', '.jsm'];
-/** Maps Firefox's common system-module resource URLs to their source suffix. */
-function moduleSourceSuffix(specifier) {
+/**
+ * Maps Firefox's common system-module resource URLs to their source
+ * suffix. Exported alongside {@link extractResourceModuleSpecifiers} so
+ * the resolution preflight resolves specifiers identically.
+ */
+export function moduleSourceSuffix(specifier) {
     const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
     for (const prefix of ['resource:///modules/', 'resource://gre/modules/']) {
         if (cleaned.startsWith(prefix))
@@ -14,8 +18,13 @@ function moduleSourceSuffix(specifier) {
     }
     return undefined;
 }
-/** Resource-module strings in actual code (comments removed), de-duplicated. */
-function extractResourceModuleSpecifiers(content) {
+/**
+ * Resource-module strings in actual code (comments removed), de-duplicated.
+ * Exported for the engine-aware resolution preflight, which must recognise
+ * exactly the same specifier shapes this queue-level rule does — two
+ * extractors would drift.
+ */
+export function extractResourceModuleSpecifiers(content) {
     const stripped = stripJsComments(content);
     const found = new Set();
     const pattern = /["'](resource:\/\/(?:\/|gre\/)modules\/[^"']+\.sys\.mjs(?:[?#][^"']*)?)["']/g;

package/dist/src/core/patch-lint-mozbuild.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-patch lint check for moz.build sorted-list violations (FORGE F2).
+ * Per-patch lint check for moz.build sorted-list violations.
  *
  * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
  * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got

package/dist/src/core/patch-lint-mozbuild.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Per-patch lint check for moz.build sorted-list violations (FORGE F2).
+ * Per-patch lint check for moz.build sorted-list violations.
  *
  * mozbuild enforces alphabetical ordering on `StrictOrderingOnAppendList`
  * variables and raises `mozbuild.util.UnsortedError: … expected "X" but got

package/dist/src/core/patch-lint-ownership.d.ts

@@ -42,7 +42,7 @@ export declare function resolvePatchOwnedSysMjs(currentNewFiles: Set<string>, pa
  */
 export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<string>, patchQueueCtx?: PatchQueueContext): Set<string>;
 /**
- * Test-script predicate for the `checkJsTestFiles` pass (FORGE G5):
+ * Test-script predicate for the `checkJsTestFiles` pass:
  * plain `.js` files (not `.sys.mjs` modules) that live under a `/test/`
  * path or carry a `browser_` / `test_` / `xpcshell_` basename. Duplicates
  * `patch-lint.ts`'s `isTestFile` shape rather than importing it —
@@ -52,7 +52,7 @@ export declare function resolvePatchOwnedChromeScripts(currentNewFiles: Set<stri
  */
 export declare function isTestScriptFile(file: string): boolean;
 /**
- * Returns the set of patch-owned test `.js` files (FORGE G5). Same
+ * Returns the set of patch-owned test `.js` files. Same
  * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
  * `patchLint.checkJsTestFiles` pass, which checks each as its own small
  * script-scope program.

package/dist/src/core/patch-lint-ownership.js

@@ -68,7 +68,7 @@ export function resolvePatchOwnedChromeScripts(currentNewFiles, patchQueueCtx) {
     return resolveOwned(currentNewFiles, patchQueueCtx, (file) => file.endsWith('.js') && !file.endsWith('.sys.mjs'));
 }
 /**
- * Test-script predicate for the `checkJsTestFiles` pass (FORGE G5):
+ * Test-script predicate for the `checkJsTestFiles` pass:
  * plain `.js` files (not `.sys.mjs` modules) that live under a `/test/`
  * path or carry a `browser_` / `test_` / `xpcshell_` basename. Duplicates
  * `patch-lint.ts`'s `isTestFile` shape rather than importing it —
@@ -85,7 +85,7 @@ export function isTestScriptFile(file) {
     return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
 }
 /**
- * Returns the set of patch-owned test `.js` files (FORGE G5). Same
+ * Returns the set of patch-owned test `.js` files. Same
  * ownership semantics as {@link resolvePatchOwnedSysMjs}; consumed by the
  * `patchLint.checkJsTestFiles` pass, which checks each as its own small
  * script-scope program.

package/dist/src/core/patch-lint.d.ts

@@ -137,7 +137,7 @@ export type PatchSizeTierDecision = {
  */
 export declare function resolvePatchSizeTier(filesAffected: ReadonlyArray<string>, patchTier?: 'branding'): PatchSizeTierDecision;
 /**
- * Read-only view of the size thresholds a tier enforces (FORGE G9).
+ * Read-only view of the size thresholds a tier enforces.
  * Public-API companion to {@link resolvePatchSizeTier} /
  * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
  * checks against the SAME numbers `large-patch-lines` /
@@ -204,7 +204,7 @@ export interface LintExportedPatchOptions {
     precomputedCheckJs?: readonly PatchLintIssue[];
     /**
      * Invoked with the issues DROPPED by the `ignoreChecks` waiver filter,
-     * when any were (FORGE G10). Suppression semantics are unchanged — the
+     * when any were. Suppression semantics are unchanged — the
      * returned issue list still excludes them — but the caller can report
      * the measurement a waived size finding carried (per-patch NOTICE lines
      * and the `--report` JSON) instead of losing it entirely.

package/dist/src/core/patch-lint.js

@@ -145,7 +145,7 @@ const PATCH_FILES_THRESHOLDS = {
     branding: 60,
 };
 /**
- * Shared remedy sentence for the over-budget findings (FORGE H4): the two
+ * Shared remedy sentence for the over-budget findings: the two
  * places an operator stands when a patch outgrows its budget must name the
  * sanctioned one-transaction way out, or they reach for the wrong tools
  * first (the field report tried two before finding it). One constant, four
@@ -560,7 +560,7 @@ export function resolvePatchSizeTier(filesAffected, patchTier) {
     return { tier: 'general' };
 }
 /**
- * Read-only view of the size thresholds a tier enforces (FORGE G9).
+ * Read-only view of the size thresholds a tier enforces.
  * Public-API companion to {@link resolvePatchSizeTier} /
  * {@link countNonBinaryDiffLines} so consumers can build waiver-freshness
  * checks against the SAME numbers `large-patch-lines` /
@@ -735,7 +735,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     else if (config.patchLint?.checkJs) {
         issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir), options?.checkJsReportScope)));
-        // Export-time twin of per-patch lint's test-file pass (FORGE G5), so
+        // Export-time twin of per-patch lint's test-file pass, so
         // export/re-export and `lint --per-patch` agree on the checked surface.
         if (config.patchLint.checkJsTestFiles === true) {
             const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir));

package/dist/src/core/patch-lock.d.ts

@@ -12,6 +12,27 @@ export interface PatchDirectoryLockOptions {
     /** Command name recorded in the lock's owner metadata for holder diagnostics. */
     command?: string | undefined;
 }
+/**
+ * Asserts that this process is inside {@link withPatchDirectoryLock} for the
+ * given patches directory.
+ *
+ * The manifest mutators document "under the caller's lock" and are reached
+ * from six different command bodies, none of which the mutator can see. This
+ * turns that comment into a check at the point it matters: filename
+ * allocation and manifest read-modify-writes are only atomic while the lock
+ * is held, so an unlocked caller silently reintroduces the interleaving the
+ * lock exists to prevent.
+ *
+ * Fail-open on an unreadable owner record, deliberately: `withFileLock`
+ * treats writing that record as non-fatal, so a live holder can legitimately
+ * have no readable PID and asserting on its presence would fire on a lock we
+ * really do hold.
+ *
+ * @param patchesDir - The patches directory whose lock must be held
+ * @param context - What is about to be done, for the failure message
+ * @throws {@link InternalInvariantError} when the lock is not held by us.
+ */
+export declare function assertPatchDirectoryLockHeld(patchesDir: string, context: string): Promise<void>;
 /**
  * Runs a patch directory mutation while holding an exclusive filesystem lock.
  * This serializes filename allocation and manifest writes across parallel exports.

package/dist/src/core/patch-lock.js

@@ -5,9 +5,10 @@
 import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { PatchError } from '../errors/patch.js';
+import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { info } from '../utils/logger.js';
-import { withFileLock } from './file-lock.js';
+import { readLockStatus, withFileLock } from './file-lock.js';
 const PATCH_DIRECTORY_LOCK = '.fireforge-patches.lock';
 /**
  * Formats the periodic operator-facing waiting line printed while
@@ -22,6 +23,32 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
     const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
     return `Waiting for the FireForge patch directory lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
 }
+/**
+ * Asserts that this process is inside {@link withPatchDirectoryLock} for the
+ * given patches directory.
+ *
+ * The manifest mutators document "under the caller's lock" and are reached
+ * from six different command bodies, none of which the mutator can see. This
+ * turns that comment into a check at the point it matters: filename
+ * allocation and manifest read-modify-writes are only atomic while the lock
+ * is held, so an unlocked caller silently reintroduces the interleaving the
+ * lock exists to prevent.
+ *
+ * Fail-open on an unreadable owner record, deliberately: `withFileLock`
+ * treats writing that record as non-fatal, so a live holder can legitimately
+ * have no readable PID and asserting on its presence would fire on a lock we
+ * really do hold.
+ *
+ * @param patchesDir - The patches directory whose lock must be held
+ * @param context - What is about to be done, for the failure message
+ * @throws {@link InternalInvariantError} when the lock is not held by us.
+ */
+export async function assertPatchDirectoryLockHeld(patchesDir, context) {
+    const status = await readLockStatus(join(patchesDir, PATCH_DIRECTORY_LOCK));
+    assert(status.held, () => `patch directory lock is held before ${context}`);
+    assert(status.holder === undefined || status.holder.pid === process.pid, () => `patch directory lock is owned by this process before ${context} ` +
+        `(held by PID ${String(status.holder?.pid)}, we are ${String(process.pid)})`);
+}
 /**
  * Runs a patch directory mutation while holding an exclusive filesystem lock.
  * This serializes filename allocation and manifest writes across parallel exports.
@@ -44,7 +71,7 @@ export async function withPatchDirectoryLock(patchesDir, operation, options = {}
         ...(command !== undefined
             ? { ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`] }
             : {}),
-        // Reason first, remedy second (FORGE H5). The remedy is waiting, not
+        // Reason first, remedy second. The remedy is waiting, not
         // deleting: bulk exports/re-exports legitimately hold this lock for
         // minutes, FireForge reaps genuinely stale locks on its own, and the
         // old advice ("rm -rf" while a holder was alive) destroyed a live

package/dist/src/core/patch-manifest-io.d.ts

@@ -8,6 +8,7 @@
  */
 import { FireForgeError } from '../errors/base.js';
 import type { PatchesManifest, PatchMetadata } from '../types/commands/index.js';
+import type { JsonObject } from '../types/json.js';
 /** Filename for the patches manifest */
 export declare const PATCHES_MANIFEST = "patches.json";
 /** Internal state returned by loadPatchesManifestState. */
@@ -69,7 +70,7 @@ export declare function savePatchesManifest(patchesDir: string, manifest: Patche
  * `sourceVersion` derived from legacy `sourceEsrVersion`, into unrelated patch
  * entries during partial metadata updates.
  */
-export declare function mutatePatchRowsInManifest(patchesDir: string, filenames: readonly string[], mutator: (existing: PatchMetadata, rawExisting: Readonly<Record<string, unknown>>) => PatchManifestRowMutation | null): Promise<PatchManifestRowMutationResult[] | null>;
+export declare function mutatePatchRowsInManifest(patchesDir: string, filenames: readonly string[], mutator: (existing: PatchMetadata, rawExisting: Readonly<JsonObject>) => PatchManifestRowMutation | null): Promise<PatchManifestRowMutationResult[] | null>;
 /**
  * Adds or updates a patch entry in the manifest.
  * @param patchesDir - Path to the patches directory

package/dist/src/core/patch-manifest-io.js

@@ -13,10 +13,12 @@ import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
 import { PatchManifestCorruptError } from '../errors/patch.js';
+import { assert } from '../utils/assert.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
+import { assertPatchDirectoryLockHeld } from './patch-lock.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
 /** Filename for the patches manifest */
 export const PATCHES_MANIFEST = 'patches.json';
@@ -117,6 +119,11 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
         const existing = beforeManifest.patches[index];
         if (!existing)
             continue;
+        // Manifest rows come out of JSON.parse and were object-checked above,
+        // so the JsonObject contract holds. The row stays a plain record
+        // internally because `mutation.set` values carry interface types
+        // (`Partial<PatchMetadata>`) that the compiler cannot relate to
+        // `JsonValue` structurally.
         const mutation = mutator(existing, rawPatch);
         if (!mutation)
             continue;
@@ -191,6 +198,36 @@ export async function removePatchFromManifest(patchesDir, filename) {
     await savePatchesManifest(patchesDir, manifest);
     return true;
 }
+/**
+ * Checks the shape a renumbered manifest is supposed to have, immediately
+ * before it becomes durable.
+ *
+ * Three properties, each of which the queue silently depends on: `order` is
+ * unique (two patches claiming one slot make apply order arbitrary),
+ * `order` matches the numeric prefix of `filename` (the prefix is what an
+ * operator reads and what `patch` commands parse back out), and the rows are
+ * sorted ascending (readers take manifest order as apply order without
+ * re-sorting).
+ *
+ * Contiguity itself is deliberately NOT checked: `patchPolicy.ranges`
+ * reserves gaps on purpose, so a hole is a legitimate queue shape.
+ *
+ * @param patches - The manifest rows about to be written
+ */
+function assertRenumberedOrderIsWellFormed(patches) {
+    const seenOrders = new Set();
+    let previousOrder = Number.NEGATIVE_INFINITY;
+    for (const patch of patches) {
+        assert(!seenOrders.has(patch.order), () => `renumbered patch orders are unique (order ${patch.order} appears twice)`);
+        seenOrders.add(patch.order);
+        assert(patch.order >= previousOrder, () => `renumbered manifest rows are sorted by order (${patch.filename} is out of place)`);
+        previousOrder = patch.order;
+        const prefixMatch = /^(\d+)-/.exec(patch.filename);
+        assert(prefixMatch !== null, () => `renumbered patch filename carries a numeric prefix (got "${patch.filename}")`);
+        assert(Number(prefixMatch[1]) === patch.order, () => `renumbered patch filename prefix matches its order ` +
+            `("${patch.filename}" carries order ${patch.order})`);
+    }
+}
 /**
  * Rewrites `stagedDependencies.forwardImports[].owner` and
  * `stagedDependencies.registrations[].owner` references on one patch
@@ -275,6 +312,7 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
 export async function renumberPatchesInManifest(patchesDir, renameMap) {
     if (renameMap.size === 0)
         return;
+    await assertPatchDirectoryLockHeld(patchesDir, 'renumbering the patch manifest');
     const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest) {
         throw new Error('Cannot renumber patches: patches.json is missing.');
@@ -389,6 +427,16 @@ export async function renumberPatchesInManifest(patchesDir, renameMap) {
     });
     updatedPatches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
     try {
+        // Phase 3 is the one write that makes the renumber visible. Every file
+        // has already moved on disk, so a manifest that disagrees with the new
+        // filenames is the worst outcome available here — the queue would apply
+        // in an order nothing on disk reflects. The callers compute the rename
+        // map (compact, reorder, export placement) and each maintains contiguity
+        // on its own; this checks the property they are all supposed to produce,
+        // at the single point where it becomes durable. Inside the try, so a
+        // violation unwinds through the Phase 3 rollback that puts the filenames
+        // back.
+        assertRenumberedOrderIsWellFormed(updatedPatches);
         await savePatchesManifest(patchesDir, {
             ...manifest,
             patches: updatedPatches,
@@ -459,6 +507,7 @@ export class PatchDeleteRollbackError extends FireForgeError {
  * @param filename - Patch filename to delete
  */
 export async function removePatchFileAndManifest(patchesDir, filename) {
+    await assertPatchDirectoryLockHeld(patchesDir, 'deleting a patch and its manifest row');
     const patchPath = join(patchesDir, filename);
     // ForWrite: deleting the patch FILE while a corrupt manifest still
     // references it would strand the queue; abort on corruption instead.

package/dist/src/core/patch-parse.d.ts

@@ -18,6 +18,24 @@
  * @returns Order number, or Infinity if no prefix
  */
 export declare function extractOrder(filename: string): number;
+/**
+ * Extracts the order number from a patch filename that is about to be
+ * written into the manifest.
+ *
+ * The write-side counterpart to {@link extractOrder}. That one answers
+ * `Infinity` for a prefix-less filename, which sorts such a patch last and
+ * is the right answer for a read: an unparseable name should not crash a
+ * status listing. Persisting `Infinity` (or the `0` some call sites used to
+ * fall back to) is a different matter — it puts an order in the manifest
+ * that no filename on disk agrees with, and the queue then applies in an
+ * order the operator cannot see. Callers here have always just built or
+ * looked up a real prefixed filename, so absence is a bug, not input.
+ *
+ * @param filename - Patch filename carrying a numeric order prefix
+ * @returns The parsed order
+ * @throws {@link InternalInvariantError} when `filename` has no numeric prefix.
+ */
+export declare function requirePatchOrder(filename: string): number;
 /**
  * A parsed `diff --git` header: both sides' paths, unquoted and with any
  * CRLF residue stripped.

package/dist/src/core/patch-parse.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { assert } from '../utils/assert.js';
 /**
  * Pure parsing functions for extracting information from patch files.
  * All functions are synchronous and operate on string content.
@@ -25,6 +26,28 @@ export function extractOrder(filename) {
     }
     return Infinity;
 }
+/**
+ * Extracts the order number from a patch filename that is about to be
+ * written into the manifest.
+ *
+ * The write-side counterpart to {@link extractOrder}. That one answers
+ * `Infinity` for a prefix-less filename, which sorts such a patch last and
+ * is the right answer for a read: an unparseable name should not crash a
+ * status listing. Persisting `Infinity` (or the `0` some call sites used to
+ * fall back to) is a different matter — it puts an order in the manifest
+ * that no filename on disk agrees with, and the queue then applies in an
+ * order the operator cannot see. Callers here have always just built or
+ * looked up a real prefixed filename, so absence is a bug, not input.
+ *
+ * @param filename - Patch filename carrying a numeric order prefix
+ * @returns The parsed order
+ * @throws {@link InternalInvariantError} when `filename` has no numeric prefix.
+ */
+export function requirePatchOrder(filename) {
+    const match = /^(\d+)-/.exec(filename);
+    assert(match?.[1] !== undefined, () => `patch filename carries a numeric order prefix (got "${filename}")`);
+    return parseInt(match[1], 10);
+}
 /**
  * Un-escapes a path from git's C-style quoted form (`"a/pfad m\303\244..."`).
  * Handles the escapes git emits: `\\`, `\"`, `\t`, `\n`, `\r` and three-digit
@@ -172,7 +195,7 @@ export function parseDiffSections(diffContent) {
             // `git diff --binary` always records full blob hashes here (git
             // apply requires them); text sections carry abbreviated ones. The
             // hashes let binary sections be compared by identity when their
-            // payload cannot be applied as text (FORGE J3).
+            // payload cannot be applied as text.
             const indexMatch = /^index ([0-9a-f]{7,64})\.\.([0-9a-f]{7,64})(?: \d{6})?$/.exec(line);
             if (indexMatch?.[1] !== undefined && indexMatch[2] !== undefined) {
                 current.indexOldHash = indexMatch[1];

package/dist/src/core/patch-policy.d.ts

@@ -37,14 +37,14 @@ export declare function getPatchPolicyCategories(config: FireForgeConfig): strin
 export declare function isCategoryAllowedByConfig(config: FireForgeConfig, category: string): boolean;
 /**
  * Human-readable label for a category's configured ranges, e.g. `300-399`.
- * Exported for the forward-import hint (FORGE F14), which must render the
+ * Exported for the forward-import hint, which must render the
  * range it found no legal ordinal in.
  */
 export declare function categoryRangeLabel(ranges: readonly PatchPolicyRange[], category: string): string;
 /**
  * Returns the configured range that contains `order` for `category`, or
  * null when no such range exists. Exported for the forward-import hint
- * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ *, which suppresses ordinal suggestions the reorder policy
  * would refuse.
  */
 export declare function categoryRangeForOrder(cfg: PatchPolicyConfig, category: string, order: number): PatchPolicyRange | null;

package/dist/src/core/patch-policy.js

@@ -47,7 +47,7 @@ function rangeLabel(range) {
 }
 /**
  * Human-readable label for a category's configured ranges, e.g. `300-399`.
- * Exported for the forward-import hint (FORGE F14), which must render the
+ * Exported for the forward-import hint, which must render the
  * range it found no legal ordinal in.
  */
 export function categoryRangeLabel(ranges, category) {
@@ -62,7 +62,7 @@ function reservedRangeForOrder(cfg, order) {
 /**
  * Returns the configured range that contains `order` for `category`, or
  * null when no such range exists. Exported for the forward-import hint
- * (FORGE F14), which suppresses ordinal suggestions the reorder policy
+ *, which suppresses ordinal suggestions the reorder policy
  * would refuse.
  */
 export function categoryRangeForOrder(cfg, category, order) {

package/dist/src/core/smoke-patterns.d.ts

@@ -20,7 +20,7 @@ export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 export declare function matchesSmokeError(line: string): boolean;
 /**
  * One compiled allowlist entry with its provenance retained so the smoke
- * summary can attribute hits per entry (FORGE G8) — an entry that silently
+ * summary can attribute hits per entry — an entry that silently
  * stops matching (its suppressed shape changed upstream) is only
  * detectable when zero-hit entries are visible.
  */

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

@@ -1,5 +1,5 @@
 /**
- * Binary-aware drift classification for patch-owned files (FORGE J3).
+ * Binary-aware drift classification for patch-owned files.
  *
  * The text classifier compares utf-8 decoded content against
  * `computePatchedContent`, which cannot apply `GIT binary patch` bodies —

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Binary-aware drift classification for patch-owned files (FORGE J3).
+ * Binary-aware drift classification for patch-owned files.
  *
  * The text classifier compares utf-8 decoded content against
  * `computePatchedContent`, which cannot apply `GIT binary patch` bodies —

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

@@ -59,7 +59,7 @@ export interface ClassifiedFile extends StatusFile {
      * (patch-backed, patch-owned-drift, and single-owner furnace entries).
      * Unset for unowned, branding-generated, unowned-furnace, and conflict
      * entries — conflicts carry `claimedBy` instead. Exposed through
-     * `status --json` as the `patch` field (FORGE G11).
+     * `status --json` as the `patch` field.
      */
     owner?: string;
 }

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

@@ -76,7 +76,7 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
     // Binary comparisons cannot go through the utf-8 content path below —
     // binary patch bodies parse to zero hunks, so the patched-content
     // computation returned HEAD content unchanged and the comparison
-    // reported `patch-owned-drift` forever (FORGE J3). Settle by blob hash,
+    // reported `patch-owned-drift` forever. Settle by blob hash,
     // or classify explicitly as `binary-unsupported` when no hash exists.
     const binaryResult = await classifyBinaryOwnedFile({
         entry,
@@ -133,7 +133,7 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
     // One manifest load + patch discovery + memoized body reads for the
     // whole batch — the previous per-file computation re-ran all three for
     // every dirty file (O(dirtyFiles × patches) redundant IO on a broad
-    // engine edit session, FORGE K1).
+    // engine edit session).
     const ctx = await createPatchedContentContext(patchesDir, engineDir);
     // Build a multimap from file path → list of claiming patch
     // filenames so we can detect cross-patch ownership conflicts. The

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

@@ -21,6 +21,7 @@
  * above so the command layer can retry them with a bounded budget instead
  * of reporting phantom test failures (or phantom passes).
  */
+import type { DisplaySleepState } from './display-state.js';
 /** How a completed harness run should be interpreted. */
 export type HarnessRunClassification = 'tests-ran-ok' | 'test-failures' | 'harness-crash' | 'no-tests';
 /** A recognized harness-crash shape with its evidence line. */
@@ -66,6 +67,13 @@ export interface HarnessRunVerdict extends HarnessSummaryCounts {
      * Callers must fail the run and surface the evidence.
      */
     greenSummaryRejected?: GreenSummaryRejection;
+    /**
+     * Short parenthetical appended to the `FIREFORGE-VERDICT:` line when the
+     * bare status would under-describe the run — currently "harness teardown
+     * noise ignored" and the headed display-asleep stall. Advisory text
+     * only; the status and reason keys are unaffected.
+     */
+    note?: string;
 }
 /** Why a green-looking embedded summary was not trusted. */
 export interface GreenSummaryRejection {
@@ -187,14 +195,72 @@ export declare function buildGreenSummaryRejectedMessage(rejection: GreenSummary
 export declare function buildHarnessCrashMessage(signature: HarnessCrashSignature, attempts: number, commandLabel?: string): string;
 /**
  * Optional hint appended to the harness-crash message when a HEADED run on
- * macOS died at the no-output timeout: the display may have slept and frozen
- * the headed browser before any test started (FORGE F17). Pure — the
- * platform is injected so unit tests need no mocking.
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it
+ * as fact rather than as one of three possibilities — that is the whole
+ * point of probing: an operator staring at a bare test failure should not
+ * have to rediscover that their machine dimmed. `caffeinate` is described
+ * accurately (it prevents sleep; it cannot wake an already-sleeping
+ * display), because the previous wording sent operators to a command that
+ * could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
  */
 export declare function headedNoOutputTimeoutHint(signature: HarnessCrashSignature, context: {
     headless: boolean;
     platform: string;
+    displayState?: DisplaySleepState;
+}): string | undefined;
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export declare function headedDisplayAsleepVerdictNote(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+    displayState: DisplaySleepState;
 }): string | undefined;
+/**
+ * True when a harness run died on SIGSEGV having produced no test evidence
+ * whatsoever.
+ *
+ * `xpcshell return code: -11` with zero output is the signature of an
+ * `.sys.mjs` that a packaged module imports but whose `EXTRA_JS_MODULES`
+ * registration never landed: the module loader faults before any logging
+ * exists, so there is no import error, no stack, no test output — just a
+ * dead process. It is indistinguishable from a genuine product crash
+ * unless someone names the cause.
+ *
+ * "Produced no evidence" is deliberately semantic rather than a byte
+ * budget: no execution signal, no real failure line, and no mozcrash
+ * marker. A run that got far enough to start a test, report a failure, or
+ * leave a crash dump has evidence of its own, and the regular diagnosis
+ * chain reads it — this branch is only for the case where there is
+ * nothing else to say.
+ *
+ * Pure; exported for direct unit testing.
+ *
+ * @param exitCode - The harness process exit code
+ * @param output - Combined stdout/stderr from the run
+ */
+export declare function isSilentSegfault(exitCode: number, output: string): boolean;
+/**
+ * Names the known cause of a silent SIGSEGV so the operator checks
+ * moz.build registration FIRST instead of paying a full rebuild cycle to
+ * rediscover it.
+ *
+ * @param exitCode - The harness process exit code
+ * @param requestedPaths - Test paths the run requested
+ */
+export declare function buildSilentSegfaultMessage(exitCode: number, requestedPaths: readonly string[]): string;
 /**
  * Builds the message for a run that produced no `TEST-START` despite
  * requesting paths — including exit-code-zero runs whose `Passed: 0`