@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/core/wire-init.js

@@ -8,7 +8,7 @@ import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
@@ -18,6 +18,30 @@ const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
  * fallback code paths agree on the shape.
  */
 const DEFAULT_MARKER = 'FIREFORGE:';
+/**
+ * Default insertion point: after the last consecutive fireforge block, or at
+ * the top of the method body when there is none.
+ *
+ * Both callers below — the `--after`-target-not-found fallthrough and the
+ * no-`--after` default — ran a character-for-character copy of this ladder,
+ * including both throw guards. `browser-init.js` is written through those two
+ * independent paths and they MUST emit identical blocks, so having one
+ * implementation enforces the invariant rather than merely tidying.
+ */
+function resolveDefaultInsertion(content, body, fireforgeBlocks) {
+    if (fireforgeBlocks.length > 0) {
+        const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
+        if (!lastBlock)
+            throw new GeneralError('Unexpected empty fireforgeBlocks array');
+        return { insertPos: lastBlock.end, indent: detectIndent(content, lastBlock.start) };
+    }
+    const firstStmt = body.body[0];
+    if (firstStmt) {
+        const insertPos = asEstree(firstStmt).start;
+        return { insertPos, indent: detectIndent(content, insertPos) };
+    }
+    return { insertPos: body.start + 1, indent: '    ' };
+}
 /**
  * AST-based implementation: finds onLoad() method body, locates existing
  * fireforge init blocks (TryStatements containing typeof guards), and inserts
@@ -47,7 +71,7 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
     const fireforgeBlocks = [];
     for (const stmt of body.body) {
         if (stmt.type === 'TryStatement') {
-            const tryNode = stmt;
+            const tryNode = asEstree(stmt);
             const src = getNodeSource(content, tryNode);
             if (/typeof\s+\w+\s*!==\s*"undefined"/.test(src)) {
                 fireforgeBlocks.push(tryNode);
@@ -68,47 +92,12 @@ export function addInitAST(content, expression, after, marker = DEFAULT_MARKER)
         }
         else {
             // --after target not found: fall through to default (after last fireforge block)
-            if (fireforgeBlocks.length > 0) {
-                const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
-                if (!lastBlock)
-                    throw new GeneralError('Unexpected empty fireforgeBlocks array');
-                insertPos = lastBlock.end;
-                indent = detectIndent(content, lastBlock.start);
-            }
-            else {
-                // No fireforge blocks, insert at top of method body
-                const firstStmt = body.body[0];
-                if (firstStmt) {
-                    insertPos = firstStmt.start;
-                    indent = detectIndent(content, insertPos);
-                }
-                else {
-                    insertPos = body.start + 1;
-                    indent = '    ';
-                }
-            }
+            ({ insertPos, indent } = resolveDefaultInsertion(content, body, fireforgeBlocks));
         }
     }
     else {
         // Default: insert after the last consecutive fireforge block at the start
-        if (fireforgeBlocks.length > 0) {
-            const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
-            if (!lastBlock)
-                throw new GeneralError('Unexpected empty fireforgeBlocks array');
-            insertPos = lastBlock.end;
-            indent = detectIndent(content, lastBlock.start);
-        }
-        else {
-            const firstStmt = body.body[0];
-            if (firstStmt) {
-                insertPos = firstStmt.start;
-                indent = detectIndent(content, insertPos);
-            }
-            else {
-                insertPos = body.start + 1;
-                indent = '    ';
-            }
-        }
+        ({ insertPos, indent } = resolveDefaultInsertion(content, body, fireforgeBlocks));
     }
     const block = [
         `${indent}// ${marker} wire-init ${name} — must be first, before Firefox subsystem`,
@@ -224,7 +213,15 @@ export async function addInitToBrowserInit(engineDir, expression, after, marker
     if (initPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addInitAST(content, expression, after, marker), () => legacyAddInit(content, expression, after, marker), BROWSER_INIT_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

package/dist/src/core/wire-subscript.js

@@ -7,7 +7,7 @@ import MagicString from 'magic-string';
 import { GeneralError } from '../errors/base.js';
 import { BuildError } from '../errors/build.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, findNearestTryLine, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
 const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
@@ -28,7 +28,7 @@ export function addSubscriptAST(content, name, marker = DEFAULT_MARKER) {
     walkAST(ast, {
         enter(node) {
             if (node.type === 'TryStatement') {
-                const n = node;
+                const n = asEstree(node);
                 const src = getNodeSource(content, n);
                 if (src.includes('loadSubScript')) {
                     tryNodes.push(n);
@@ -137,7 +137,15 @@ export async function addSubscriptToBrowserMain(engineDir, name, marker = DEFAUL
     if (content.includes(`content/${name}.js"`)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS);
+    const { value, usedFallback } = withParserFallback(() => addSubscriptAST(content, name, marker), () => legacyAddSubscript(content, name, marker), BROWSER_MAIN_JS, 
+    // Rethrow only the internal-invariant GeneralErrors ("Unexpected empty
+    // …array"): those are programming bugs, and retrying the legacy scanner
+    // cannot fix a broken invariant — it just buries the stack. Everything
+    // else still falls back, which is load-bearing: the AST path raises a raw
+    // acorn SyntaxError on chrome sources acorn cannot parse (preprocessor
+    // directives), and BuildError when the file's shape is unexpected. Both
+    // are exactly what the legacy scanner is here to handle.
+    (error) => error instanceof GeneralError);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_MAIN_JS);
     }

package/dist/src/core/wire-utils.js

@@ -1,5 +1,5 @@
 import { GeneralError, ParserFallbackError } from '../errors/base.js';
-import { walkAST } from './ast-utils.js';
+import { asEstree, walkAST } from './ast-utils.js';
 /**
  * Validates a name for safe interpolation into generated JavaScript string literals.
  * Rejects strings containing characters that could break out of JS strings or inject code.
@@ -336,13 +336,13 @@ export function findMethodBody(ast, methodName) {
             if (found)
                 return;
             if (node.type === 'Property') {
-                const prop = node;
+                const prop = asEstree(node);
                 if (prop.key.type === 'Identifier' &&
                     names.includes(prop.key.name) &&
                     (prop.value.type === 'FunctionExpression' ||
                         prop.value.type === 'ArrowFunctionExpression')) {
-                    const fn = prop.value;
-                    found = fn.body;
+                    const fn = asEstree(prop.value);
+                    found = asEstree(fn.body);
                 }
             }
         },

package/dist/src/core/xpcshell-appdir.js

@@ -203,6 +203,7 @@ export async function resolveAbsoluteAppPath(objDirAbs, relativeAppdir) {
             entries = await readdir(distDir);
         }
         catch {
+            // No readable dist directory means no appdir candidate can be resolved.
             return null;
         }
         for (const entry of entries) {
@@ -254,6 +255,8 @@ export async function resolveXpcshellAppdirArg(engineDir, testPaths, objDirName)
             body = await readText(manifestPath);
         }
         catch {
+            // An unreadable manifest cannot declare an appdir; skip it and keep
+            // walking the remaining candidates.
             continue;
         }
         // Operator already migrated — harness will read the appname-keyed

package/dist/src/core/xpcshell-profile-dir.d.ts

@@ -0,0 +1,12 @@
+export declare const XPCSHELL_PROFILE_ENV_VAR = "XPCSHELL_TEST_PROFILE_DIR";
+/**
+ * Runs `fn` with a fresh per-invocation xpcshell profile directory
+ * injected into the environment, removing the directory afterwards
+ * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper; the harness may still hold files briefly).
+ *
+ * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
+ * process environment) is respected verbatim: no directory is minted and
+ * NOTHING is deleted — we never remove a directory we did not create.
+ */
+export declare function withXpcshellProfileDir<T>(baseEnv: Record<string, string> | undefined, fn: (env: Record<string, string>) => Promise<T>): Promise<T>;

package/dist/src/core/xpcshell-profile-dir.js

@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-invocation xpcshell profile directory (FORGE G15b).
+ *
+ * Firefox's xpcshell harness defaults `XPCSHELL_TEST_PROFILE_DIR` to a
+ * FIXED path (`$TMPDIR/firefox/xpcshellprofile`), so two overlapping
+ * harness invocations — concurrent `fireforge test` processes, or future
+ * verification-tree shards — corrupt each other's profiles. FireForge
+ * never set the variable; this helper mints a fresh `mkdtemp` directory
+ * per harness invocation and exports it through the mach env channel.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+export const XPCSHELL_PROFILE_ENV_VAR = 'XPCSHELL_TEST_PROFILE_DIR';
+/**
+ * Runs `fn` with a fresh per-invocation xpcshell profile directory
+ * injected into the environment, removing the directory afterwards
+ * (best-effort — a failure to clean up warns and leaves the mkdtemp dir
+ * for the OS tmp reaper; the harness may still hold files briefly).
+ *
+ * An operator-provided `XPCSHELL_TEST_PROFILE_DIR` (in `baseEnv` or the
+ * process environment) is respected verbatim: no directory is minted and
+ * NOTHING is deleted — we never remove a directory we did not create.
+ */
+export async function withXpcshellProfileDir(baseEnv, fn) {
+    const operatorProvided = baseEnv?.[XPCSHELL_PROFILE_ENV_VAR] ?? process.env[XPCSHELL_PROFILE_ENV_VAR];
+    if (operatorProvided !== undefined && operatorProvided !== '') {
+        return fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: operatorProvided });
+    }
+    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-xpcshell-profile-'));
+    try {
+        return await fn({ ...baseEnv, [XPCSHELL_PROFILE_ENV_VAR]: profileDir });
+    }
+    finally {
+        try {
+            await rm(profileDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            warn(`Could not clean up xpcshell profile dir ${profileDir}: ${toError(error).message}`);
+        }
+    }
+}

package/dist/src/errors/base.d.ts

@@ -83,6 +83,19 @@ export declare class ExecTimeoutError extends FireForgeError {
     timeoutMs: number, cause?: unknown);
     get userMessage(): string;
 }
+/**
+ * Error thrown when a file-lock wait times out because another process
+ * holds the lock (FORGE H5).
+ *
+ * Dedicated subclass so the CLI boundary renders lock contention as the
+ * one-line reason-first/remedy-second refusal it is — before this, the
+ * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
+ * as an internal failure and prints with a five-frame stack. The refusal
+ * was always correct; the presentation made it look like a crash.
+ */
+export declare class LockContentionError extends FireForgeError {
+    readonly code: 1;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/base.js

@@ -113,6 +113,19 @@ export class ExecTimeoutError extends FireForgeError {
             'If the host is just slow or loaded, re-running may succeed.');
     }
 }
+/**
+ * Error thrown when a file-lock wait times out because another process
+ * holds the lock (FORGE H5).
+ *
+ * Dedicated subclass so the CLI boundary renders lock contention as the
+ * one-line reason-first/remedy-second refusal it is — before this, the
+ * timeout surfaced as a plain `Error`, which `withErrorHandling` treats
+ * as an internal failure and prints with a five-frame stack. The refusal
+ * was always correct; the presentation made it look like a crash.
+ */
+export class LockContentionError extends FireForgeError {
+    code = ExitCode.GENERAL_ERROR;
+}
 /**
  * Error thrown when the user cancels an interactive prompt.
  */

package/dist/src/errors/git.d.ts

@@ -39,6 +39,14 @@ export declare class GitIndexLockError extends GitError {
     constructor(lockPath: string, ageMs?: number | undefined);
     get userMessage(): string;
 }
+/**
+ * Detects transient git `index.lock` contention — an external git process
+ * holding `.git/index.lock` while we stage or diff. Mirrors the message
+ * heuristics `core/git.ts` uses when wrapping stale-lock failures during
+ * download, but lives here so command modules can consult it without
+ * importing (frequently vi.mocked) core git internals.
+ */
+export declare function isGitIndexLockConflict(error: unknown): boolean;
 /**
  * Error thrown when `git add` (monolithic or chunked) exceeds the
  * configured timeout while indexing the Firefox source tree.

package/dist/src/errors/git.js

@@ -96,6 +96,23 @@ export class GitIndexLockError extends GitError {
             '  3. Re-run "fireforge download --force"');
     }
 }
+/**
+ * Detects transient git `index.lock` contention — an external git process
+ * holding `.git/index.lock` while we stage or diff. Mirrors the message
+ * heuristics `core/git.ts` uses when wrapping stale-lock failures during
+ * download, but lives here so command modules can consult it without
+ * importing (frequently vi.mocked) core git internals.
+ */
+export function isGitIndexLockConflict(error) {
+    if (error instanceof GitIndexLockError) {
+        return true;
+    }
+    if (!(error instanceof GitError)) {
+        return false;
+    }
+    return (/index\.lock/i.test(error.message) &&
+        /(unable to create|another git process seems to be running|file exists|locked)/i.test(error.message));
+}
 /**
  * Error thrown when `git add` (monolithic or chunked) exceeds the
  * configured timeout while indexing the Firefox source tree.

package/dist/src/errors/rebase.d.ts

@@ -18,3 +18,16 @@ export declare class RebaseSessionExistsError extends RebaseError {
 export declare class NoRebaseSessionError extends RebaseError {
     constructor();
 }
+/**
+ * Thrown when the session file exists but cannot be used.
+ *
+ * This case had no error of its own before 0.41.0 and was reported as
+ * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
+ * reported {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command pointed at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` now clears a corrupt session rather than
+ * refusing to run against one.
+ */
+export declare class CorruptRebaseSessionError extends RebaseError {
+    constructor(sessionPath: string, reason: string);
+}

package/dist/src/errors/rebase.js

@@ -32,3 +32,20 @@ export class NoRebaseSessionError extends RebaseError {
         super('No rebase session in progress. Start one with "fireforge rebase".');
     }
 }
+/**
+ * Thrown when the session file exists but cannot be used.
+ *
+ * This case had no error of its own before 0.41.0 and was reported as
+ * {@link NoRebaseSessionError} by `--continue`/`--abort` while `rebase`
+ * reported {@link RebaseSessionExistsError} — a closed cycle in which each
+ * command pointed at the other two. The message names the file so an operator
+ * always has a way out, and `--abort` now clears a corrupt session rather than
+ * refusing to run against one.
+ */
+export class CorruptRebaseSessionError extends RebaseError {
+    constructor(sessionPath, reason) {
+        super(`The rebase session at ${sessionPath} cannot be read (${reason}).\n` +
+            'Run "fireforge rebase --abort" to discard it and restore the engine, ' +
+            'or delete the file to start over.');
+    }
+}

package/dist/src/index.d.ts

@@ -14,6 +14,8 @@ export { loadConfig, validateConfig } from './core/config.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
+export type { PatchSizeTierDecision } from './core/patch-lint.js';
+export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export type { AddTokenOptions, AddTokenResult, TokenMode } from './core/token-manager.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';

package/dist/src/index.js

@@ -15,6 +15,7 @@ export { loadConfig, validateConfig } from './core/config.js';
 export { applyAllComponents } from './core/furnace-apply.js';
 export { ensureFurnaceConfig, loadFurnaceConfig, loadFurnaceState, saveFurnaceState, validateFurnaceConfig, } from './core/furnace-config.js';
 export { validateAllComponents, validateComponent } from './core/furnace-validate.js';
+export { countNonBinaryDiffLines, getPatchSizeThresholds, resolvePatchSizeTier, } from './core/patch-lint.js';
 export { addToken, getTokensCssPath, validateTokenAdd } from './core/token-manager.js';
 export { CancellationError, CommandError, FireForgeError, GeneralError, InvalidArgumentError, ResolutionError, } from './errors/base.js';
 export { ExitCode } from './errors/codes.js';

package/dist/src/types/commands/options.d.ts

@@ -279,6 +279,41 @@ export interface ReExportOptions {
      * the command implementation ignores it.
      */
     waitLock?: number | boolean;
+    /**
+     * Refuse (non-zero exit, patch not written) a scan-less re-export when
+     * unmanaged files exist adjacent to the patch's ownership, instead of
+     * warning. Gate-driven workflows use this so a freshly created file
+     * beside a patch's owned files cannot be silently left out of the
+     * refreshed body. Only meaningful on the plain path — mutually
+     * exclusive with `--scan` and `--files`, which set filesAffected
+     * explicitly.
+     */
+    refuseAdjacentUnmanaged?: boolean;
+    /**
+     * Bypass per-patch lint result cache reads AND writes for this
+     * invocation (`--no-cache`). The cache is what makes a repeat
+     * re-export of an unchanged patch skip the checkJs program build
+     * entirely (FORGE J1).
+     */
+    noCache?: boolean;
+    /**
+     * Refuse (non-zero exit, patch not written) a re-export whose refreshed
+     * body would absorb engine lines not present in the old patch body —
+     * the multi-session guard against silently capturing another session's
+     * uncommitted edits in files the patch already owns. The drift preview
+     * always prints; this flag turns it into a hard stop. Mutually
+     * exclusive with `--scan` and `--files`.
+     */
+    refuseForeignDrift?: boolean;
+    /**
+     * Engine-relative files whose drift is EXPECTED (`--expect`, repeatable;
+     * requires `--refuse-foreign-drift`). The content-based drift detector
+     * cannot tell the exporting session's own slice edits from another
+     * session's (FORGE L6), so a real slice export under the refusal flag
+     * names its intended files here: drift confined to expected files
+     * proceeds, drift anywhere else still refuses.
+     */
+    expect?: string[];
 }
 /**
  * Options for the `fireforge patch tier` subcommand. Sets or clears the
@@ -376,6 +411,8 @@ export interface PatchSplitOptions {
     forceUnsafe?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the `fireforge patch move-files` subcommand. Without
@@ -403,6 +440,8 @@ export interface PatchMoveFilesOptions {
     forceUnsafe?: boolean;
     /** Skip per-patch lint of the projected bodies. */
     skipLint?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the rebase command.
@@ -474,6 +513,24 @@ export interface TestOptions {
     headless?: boolean;
     /** Run incremental UI build before testing */
     build?: boolean;
+    /**
+     * Run the scoped pre-test build (packaging exactly the requested paths,
+     * MIXED harnesses allowed) and exit without dispatching tests. One
+     * ~10-minute build then covers both an xpcshell and a browser-chrome
+     * half of a slice; run each harness afterwards without `--build`
+     * (FORGE J9). Emits `FIREFORGE-VERDICT: PASS` on success.
+     */
+    buildOnly?: boolean;
+    /**
+     * Union the paths this build packages onto the recorded coverage claim
+     * instead of REPLACING it (FORGE L1), so successive scoped builds
+     * accumulate and an earlier slice's build-less runs stay covered. Valid
+     * only with `--build`/`--build-only` and explicit paths. Refused
+     * fail-closed unless the build anchor is unchanged: same engine HEAD,
+     * same `engine/mozconfig`, and every previously fingerprinted packageable
+     * file byte-identical. See `src/core/coverage-extend.ts`.
+     */
+    extendCoverage?: boolean;
     /** Forward mach's pathless auto-selection mode. Valid only with no explicit paths. */
     auto?: boolean;
     /**
@@ -735,6 +792,8 @@ export interface PatchDeleteOptions {
     dryRun?: boolean;
     /** Bypass the hard refusal when later patches depend on the target. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the `fireforge patch rename` subcommand. Updates the
@@ -750,9 +809,22 @@ export interface PatchRenameOptions {
      * New human-readable name. Sanitised the same way `export --name`
      * sanitises into the filename slug (lowercase, non-alphanumerics
      * collapsed to `-`, length-capped). The patch's `name` field stores
-     * the raw value; the filename uses the sanitised slug.
+     * the raw value; the filename uses the sanitised slug. Optional when
+     * `--category`/`--order`/`--description` carry the change.
      */
     to?: string;
+    /**
+     * New category (validated against configured categories). Rewrites
+     * the filename prefix and the manifest row in one transaction —
+     * recategorising no longer requires `patch delete` + fresh export.
+     */
+    category?: string;
+    /**
+     * Move the patch to this exact UNUSED sparse order. Collisions refuse
+     * with a pointer to `patch reorder` (which renumbers siblings); an
+     * order change is projected through cross-patch lint first.
+     */
+    order?: number;
     /**
      * Replacement description. Omit to leave the description unchanged
      * (intentional — operators frequently want to relabel the slug
@@ -765,6 +837,8 @@ export interface PatchRenameOptions {
     yes?: boolean;
     /** Bypass force-mode patchPolicy refusals. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the patch reorder command.
@@ -776,6 +850,8 @@ export interface PatchReorderOptions {
     yes?: boolean;
     dryRun?: boolean;
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the patch compact command.
@@ -787,6 +863,8 @@ export interface PatchCompactOptions {
     dryRun?: boolean;
     /** Bypass force-mode patchPolicy refusals. */
     forceUnsafe?: boolean;
+    /** Wait budget for the patch directory lock (`--wait-lock [seconds]`). */
+    waitLock?: number | boolean;
 }
 /**
  * Options for the status command.
@@ -809,6 +887,36 @@ export interface StatusOptions {
     testCoverage?: boolean;
     /** Output machine-readable JSON instead of human-readable text. */
     json?: boolean;
+    /**
+     * With `--json`: emit only the summary counts (plus the offending
+     * files per fail-set classification when the `--check`/`--fail-on`
+     * policy is active), omitting the per-file `files[]` payload that
+     * grows with the queue (FORGE K8). Refused without `--json`.
+     */
+    summary?: boolean;
+    /**
+     * With `--json` (and composing with `--summary`), append an additive
+     * `ownership` block — the flat path→owning-patch rows plus
+     * managed/unmanaged/conflict counts — so a gate reads ownership,
+     * classification, and the check verdict from ONE scan instead of three
+     * back-to-back `status` invocations (FORGE L3). A modifier, not a mode:
+     * exit semantics are unchanged, so ownership conflicts still fail only
+     * the human `--ownership` mode. Refused without `--json`.
+     */
+    includeOwnership?: boolean;
+    /**
+     * Exit non-zero when any classification in the fail policy is
+     * non-empty (default policy: unmanaged, patch-owned-drift, conflict).
+     * Composes with the default view and `--json`; refused alongside
+     * `--raw`/`--unmanaged`/`--ownership`/`--test-coverage` (FORGE G1).
+     */
+    check?: boolean;
+    /**
+     * Comma-separated classification list replacing the default `--check`
+     * policy. Implies `--check`. Unknown values refuse, naming the valid
+     * classification set.
+     */
+    failOn?: string;
 }
 /**
  * Options for the token add command.
@@ -900,8 +1008,9 @@ export interface LintCommandOptions {
      * the cross-patch rules once over the whole queue so queue-level
      * findings (duplicate creations, forward imports) still surface.
      *
-     * Mutually exclusive with passing explicit file paths — the two
-     * scope contracts are different.
+     * Positional file arguments change meaning under this flag: they are
+     * PATCH selectors resolved like {@link patches} entries, not engine
+     * file paths (FORGE G14).
      */
     perPatch?: boolean;
     /**
@@ -923,4 +1032,11 @@ export interface LintCommandOptions {
      * for CLI consistency, but only `--per-patch` currently uses the cache.
      */
     noCache?: boolean;
+    /**
+     * With `--per-patch`, write a machine-readable JSON report (schemaVersion
+     * 1: per-patch lineCount, filesAffected, tier, thresholds, issues, and
+     * lintIgnore-suppressed issues) to this path (FORGE G9/G10). Requires
+     * {@link perPatch}.
+     */
+    report?: string;
 }

package/dist/src/types/commands/patches.d.ts

@@ -212,6 +212,14 @@ export interface PatchLintIssue {
     fingerprint?: string;
     /** Human-readable description of the issue */
     message: string;
+    /**
+     * Queue entry filenames this issue implicates (the declaring/importing
+     * patch, or every creator for a duplicate-creation clash). Used by the
+     * export placement gate to attribute projected errors to the exported
+     * patch vs pre-existing patches without parsing messages or the
+     * rename-sensitive fingerprint (FORGE K9).
+     */
+    patches?: string[];
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
     /**

package/dist/src/types/config.d.ts

@@ -253,6 +253,25 @@ export interface PatchLintConfig {
      * behaviour (built-in shim only).
      */
     checkJsExtraShim?: string;
+    /**
+     * Extend the checkJs pass to patch-owned test `.js` files
+     * (`browser_*` / `test_*` / `xpcshell_*` basenames and files under a
+     * `/test/` path), each checked as its own small script-scope program
+     * with same-directory patch-owned `head*.js` helpers included (FORGE
+     * G5 — a harness global that does not exist should fail at the patch
+     * boundary where the test was authored, not in a downstream
+     * jsconfig-project run). Opt-in: it is a new failure surface with
+     * nonzero compile cost. Requires `checkJs: true`.
+     */
+    checkJsTestFiles?: boolean;
+    /**
+     * Project-relative `.d.ts` appended to the built-in test-harness shim
+     * (loose `TestUtils`/`BrowserTestUtils`/`add_task`/… declarations) for
+     * the `checkJsTestFiles` pass — a consumer-typed `TestUtils` here is
+     * what turns a call to a nonexistent harness member into a TS2339 at
+     * export time. Requires `checkJsTestFiles: true`.
+     */
+    checkJsTestShim?: string;
     /** File paths exempt from the raw-color-value check (exact or basename match) */
     rawColorAllowlist?: string[];
     /** Enforce JSDoc on class-method exports in patch-owned .sys.mjs files. Default: 'off'. */

package/dist/src/types/furnace.d.ts

@@ -260,6 +260,13 @@ export interface ApplyResult {
      * persisted — the engine has been restored to its pre-apply state.
      */
     rolledBack?: boolean;
+    /**
+     * Operator-facing warnings, printed by `logApplyResult`. Populated when
+     * apply overwrote a deployed, patch-owned file whose engine bytes
+     * differed from the component source (FORGE J6) — the case where a
+     * shipped engine-only fix is silently reverted by the copy.
+     */
+    warnings?: string[];
 }
 /**
  * An action that would be performed during a dry-run deploy.