@hominis/fireforge 0.51.0 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.53.0
+
+### Test harness
+
+- `test --jobs` gives each harness instance its own `MOZ_UPLOAD_DIR` (`<MOZ_UPLOAD_DIR>/job-<n>`, created up front) when the caller sets one, so instances no longer overwrite each other's fixed-name artifacts such as the `modifiedPrefs.json` pref census. The verdict names the directories as `upload-dirs=`.
+- `test --jobs` holds the mochitest HTTP, ssltunnel and WebSocket ports (8888, 4443, 9988) for the whole parallel run, so each instance's harness falls back to server ports of its own instead of racing for 8888. Each `FIREFORGE-SHARD:` line names the ports its instance took as `ports=http:N,ssl:N,ws:N`.
+- A harness whose mochitest server never starts (`could not start server on port`, `Timed out while waiting for server startup`) is an infrastructure failure, not `no-tests`: it is retried within `--harness-retries` and reports `reason=server-startup` once the budget is spent. A `--results` record for a harness-level result (`automation.py`) carries `shardFiles`, plus `file` when its shard has one file.
+- `test` refuses with `note=stale-compiled` when C++, Rust, IDL, WebIDL, IPDL or YAML sources changed after the binary under test was linked (the newer of the binary and its `libxul`). `--allow-stale-build` turns the refusal into a warning, and `test --build` escalates to a full `mach build`. Every run that reaches dispatch stamps `build-id=<BuildID>` from `application.ini` on its verdict.
+- A negative control on a header (`.h`, `.hh`, `.hpp`, `.ipdlh`) counts as compiled even when an `EXPORTS` manifest installs it, so it is applied before a full pre-test build instead of reporting `control=missed`.
+- After a compiled negative control is restored, `test` rebuilds the binary under the same lock hold and adds `control-restore-build=done|failed` to the verdict. A binary that still carries a control (the run was killed, or the restore build failed) is refused with `note=control-built` until `fireforge build`, and `test --build` escalates to a full build.
+- A scoped `test --build <dir>/` no longer leaves a baseline the next plain `test` refuses: coverage paths are recorded normalized, and non-ASCII dirty paths are fingerprinted unquoted. An invalid baseline's refusal names the failing field and its value, and offers `--build` when the field belongs to the coverage claim.
+
+### Patch queue
+
+- Every `patches.json` write puts every row and the manifest's own keys in the one canonical order, not only the rows it changed. A re-export no longer leaves an older writer's rows (`sourceProduct` after `filesAffected`) in the working copy while `patch stage` stages them canonical, so commits stop flipping key order on hundreds of rows. The `re-export --dry-run` purity guard hashes rows in canonical order.
+- `patch reorder --shift <n> --from <order> [--through <order>]` renumbers a run of patches up by `n` in one transaction, to open room for inserts. Retired and reserved slots inside the run move with it, a shift onto an occupied order past the run is refused, and under `patchPolicy.allowGaps: false` the opened orders are recorded as reservations, which the inserts that follow fill. `--map-out <file>` on `reorder` and `split` writes the old-to-new filename map as JSON.
+- `patch move-files --scan-file <path>` adopts new, unowned engine files into the destination in the same transaction, and both sides are linted as the transaction leaves them. `--retire-empty` lets a move empty the source: the declarations it owns re-point to the destination and its slot is retired as by `patch retire`. Without the flag, the refusal names it.
+- The projected lint of `patch move-files`, `patch split` and a placed `export` uses the queue's whole lint configuration. With `forwardRegistration: "extended"`, a shared test manifest's suite entries (`["browser_*.js"]`) are projected and written to the `--declarations-out` report instead of surfacing only after the move.
+- A refused `move-files --create` or `split` report names the patch the rerun creates as `owner`. The declarations `move-files` and `split` write, and every report entry, carry a `reason` naming the move, so the printed `--add --from` call needs no `--reason`.
+- A per-patch size refusal from `move-files` or `split` names a tier change behind it, for example "the source becomes test tier (it was general tier): 9634 lines against 6000".
+- `patch staged-dependency --add`, single or `--from`, on a declaration already present with a different `reason` replaces the reason in place, keeping the entry's position. The summary reports updated reasons apart from additions.
+- `re-export --expect-removed` drops every staged registration and forward import, in any patch, whose `creates` path it retires, names each one (`would drop` on a dry run) and records `re-export-staged-prune`. Before, the stale declaration waited for the next `lint --per-patch`.
+- A re-export keeps a staged registration whose `creates` file exists in `engine/` or is an `--expect-new` path of the run, and says so ("kept: file exists but no patch owns it yet"), instead of pruning the declaration the next scan needs.
+- `fireforge register` inserts an xpcshell section ahead of the `#` comments that introduce the next entry, never between a comment and its entry. `--after <entry>` now works for `xpcshell.toml` and places the section after that entry's whole block.
+- `--patches` on `lint --per-patch`, `status`, `verify` and `check` splits a list on whitespace as well as commas, so a list in one zsh word works. An unmatched name is refused with its nearest matches and the queue size instead of every patch in the queue.
+
+## 0.52.0
+
+### Test harness
+
+- `test --jobs` gives each harness instance its own mochitest test list (`--testrun-manifest-file`). On the shared default `tests.json` the second instance ran the first shard's file and the verdict passed, or it found no file at all. A `--jobs` run now always reads each dispatch's mozlog raw log, and a dispatch whose raw log starts none of its requested files fails with `started=0/<m>` instead of passing on another shard's results.
+- A negative control on compiled source escalates its pre-test build to a full `mach build`, with a notice that names the control's files. `mach build faster` compiles nothing, so under `--build` such a control still tested the previous binary and reported `control=missed`.
+- A `coverage-replaced` refusal names who wrote the coverage record: its invocation, when, and the writing process's pid (marked `still running` while it is), `FIREFORGE_SESSION_ID` and invocation id. Every build baseline now records that `recorder`, and `status --test-coverage` shows it.
+
+### Furnace
+
+- A `validationExceptions` entry can name a `file` of the component, as one can name a `tag`. `hardcoded-text` judges each module on its own and lists the modules in `files`, so a vendored bundle whose bytes are pinned can be accepted while the authored modules beside it keep the check. A `furnace-ignore: hardcoded-text` comment now covers only the file it is in.
+
+### Typecheck
+
+- `typecheck.litTypes` declares the global type `MozLitElementWith<Extra>`. A widget casts its `MozLitElement` base to it to type query getters and members declared only in `static properties`. Without `litTypes`, and under per-patch checkJs, the type is `any`, so the same source checks in both.
+
+### Other
+
+- CI: `github/codeql-action` 4.39.0.
+
 ## 0.51.0
 
 ### Test harness

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.51.0",
-  "commit": "bd93338b037832fdcd69259a70a3a4b134b98906",
-  "shortCommit": "bd93338b0378",
+  "version": "0.53.0",
+  "commit": "2f2367bfe9c2b8a834cbf09f9b19b02d8dbd6b66",
+  "shortCommit": "2f2367bfe9c2",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-10-19T12:33:48.474Z"
+  "buildTime": "2026-10-22T20:59:15.472Z"
 }

package/dist/src/commands/bootstrap.js

@@ -79,9 +79,8 @@ export async function bootstrapCommand(projectRoot) {
         if (hasErrors) {
             outro('Build dependencies installed with errors');
             // Propagate the failure (mirroring doctor's exit-code handling)
-            // instead of exiting 0. CI gating on bootstrap used to proceed to a
-            // build that could not succeed because error-severity check results
-            // were discarded here.
+            // instead of exiting 0, so CI gating on bootstrap does not proceed to
+            // a build that cannot succeed.
             return checksExitCode;
         }
         outro('Build dependencies installed with warnings');

package/dist/src/commands/build-prelock.d.ts

@@ -3,9 +3,9 @@
  * session lock, not while holding it.
  *
  * A build queued behind a running objdir browser (a demo batch, an
- * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
- * peer's build, test and re-export queued behind a run that was doing
- * nothing. The wait now happens first, and the in-lock objdir preflight
+ * end-to-end harness) that waited inside `withEngineSessionLock` would queue
+ * every peer's build, test and re-export behind a run that was doing
+ * nothing. The wait happens first, and the in-lock objdir preflight
  * re-checks once (the spent budget is stripped from the options it gets).
  */
 import type { BuildOptions } from '../types/commands/index.js';

package/dist/src/commands/build-prelock.js

@@ -4,9 +4,9 @@
  * session lock, not while holding it.
  *
  * A build queued behind a running objdir browser (a demo batch, an
- * end-to-end harness) used to wait inside `withEngineSessionLock`, so every
- * peer's build, test and re-export queued behind a run that was doing
- * nothing. The wait now happens first, and the in-lock objdir preflight
+ * end-to-end harness) that waited inside `withEngineSessionLock` would queue
+ * every peer's build, test and re-export behind a run that was doing
+ * nothing. The wait happens first, and the in-lock objdir preflight
  * re-checks once (the spent budget is stripped from the options it gets).
  */
 import { join } from 'node:path';

package/dist/src/commands/build.js

@@ -392,6 +392,10 @@ async function recordFullBuildBaseline(projectRoot, engineDir, binaryName, ui, p
             recordedBy: ui ? 'fireforge build --ui' : 'fireforge build',
             staticComponentsHandling: 'auto',
             buildKind: ui ? 'faster' : 'full',
+            // A full build recompiles a negative control's restored source, so
+            // it drops the control-built stamp; `--ui` compiles nothing and
+            // keeps it.
+            controlBuild: ui ? previousBaseline?.controlBuild : undefined,
         });
     }
     catch (baselineError) {

package/dist/src/commands/declarations-report.d.ts

@@ -10,11 +10,14 @@ export interface DeclarationsReport {
     commands: string[];
 }
 /**
- * A declaration as the report records it. `owner` is dropped when it names
- * a patch the refused change would have created, which does not exist yet.
+ * A declaration as the report records it. `owner` is optional for renamers
+ * that cannot name one; `reason` is the rationale `staged-dependency --add
+ * --from` records with the declaration (an entry's own reason wins over the
+ * call's `--reason`).
  */
 export type ReportedDeclaration = Omit<PatchLintStagedDeclaration, 'owner'> & {
     owner?: string;
+    reason?: string;
 };
 /** Rewrites a projected declaration into the names the current queue uses. */
 export type DeclarationRenamer = (declaration: PatchLintStagedDeclaration) => ReportedDeclaration;
@@ -26,8 +29,10 @@ export type DeclarationRenamer = (declaration: PatchLintStagedDeclaration) => Re
  * @param issues - The refusal's findings
  * @param out - `--declarations-out`, relative to the working directory
  * @param rename - Maps projected patch names back to current ones
+ * @param reason - Rationale stamped on every declaration that carries none
+ *   (`patch move-files` and `patch split` name the move that needs it)
  */
-export declare function writeDeclarationsReport(projectRoot: string, issues: readonly PatchLintIssue[], out?: string, rename?: DeclarationRenamer): Promise<DeclarationsReport | undefined>;
+export declare function writeDeclarationsReport(projectRoot: string, issues: readonly PatchLintIssue[], out?: string, rename?: DeclarationRenamer, reason?: string): Promise<DeclarationsReport | undefined>;
 /** The refusal lines that point at a written report. */
 export declare function formatDeclarationsReport(report: DeclarationsReport): string[];
 /**
@@ -40,4 +45,5 @@ export declare function withDeclarationsReport(conflicts: ConflictReport | null,
     regressions: readonly PatchLintIssue[];
     out?: string | undefined;
     rename?: DeclarationRenamer;
+    reason?: string;
 }): Promise<ConflictReport | null>;

package/dist/src/commands/declarations-report.js

@@ -2,12 +2,11 @@
 /**
  * One `--from`-ready declaration report for a refused queue change.
  *
- * Moving a test out of a patch that owns a shared manifest refused with one
- * `forward-registration` error per manifest line, and each line needed its
- * own `patch staged-dependency --add` call: a slice that added seven suites
- * wrote eighteen declarations by hand. `patch move-files`, `patch split`
- * and `re-export --scan` now write every declaration their refusal proposes
- * into one lint-report-shaped JSON (`queueIssues[].stagedDeclarations`) and
+ * Moving a test out of a patch that owns a shared manifest refuses with one
+ * `forward-registration` error per manifest line, and each line would need
+ * its own `patch staged-dependency --add` call. `patch move-files`,
+ * `patch split` and `re-export --scan` write every declaration their refusal
+ * proposes into one lint-report-shaped JSON (`queueIssues[].stagedDeclarations`) and
  * name the single `patch staged-dependency <holder> --add --from <file>`
  * call per holding patch that discharges them.
  */
@@ -26,15 +25,20 @@ const DECLARABLE_CHECKS = new Set(['forward-import', 'forward-registration']);
  * @param issues - The refusal's findings
  * @param out - `--declarations-out`, relative to the working directory
  * @param rename - Maps projected patch names back to current ones
+ * @param reason - Rationale stamped on every declaration that carries none
+ *   (`patch move-files` and `patch split` name the move that needs it)
  */
-export async function writeDeclarationsReport(projectRoot, issues, out, rename = (declaration) => declaration) {
+export async function writeDeclarationsReport(projectRoot, issues, out, rename = (declaration) => declaration, reason) {
+    const withReason = (declaration) => reason === undefined || declaration.reason !== undefined
+        ? declaration
+        : { ...declaration, reason };
     const queueIssues = issues
         .filter((issue) => DECLARABLE_CHECKS.has(issue.check))
         .map((issue) => ({
         check: issue.check,
         file: issue.file,
         message: issue.message,
-        stagedDeclarations: (issue.stagedDeclarations ?? []).map(rename),
+        stagedDeclarations: (issue.stagedDeclarations ?? []).map((declaration) => withReason(rename(declaration))),
     }))
         .filter((issue) => issue.stagedDeclarations.length > 0);
     const declarations = queueIssues.flatMap((issue) => issue.stagedDeclarations);
@@ -46,11 +50,14 @@ export async function writeDeclarationsReport(projectRoot, issues, out, rename =
     await ensureDir(resolve(path, '..'));
     await writeJson(path, { queueIssues });
     const holders = [...new Set(declarations.map((declaration) => declaration.patch))].sort();
+    // A report whose every entry carries its reason needs no `--reason`.
+    const reasonFlag = declarations.every((declaration) => declaration.reason !== undefined)
+        ? ''
+        : ` ${STAGED_DEPENDENCY_REASON_PLACEHOLDER}`;
     return {
         path,
         count: declarations.length,
-        commands: holders.map((holder) => `fireforge patch staged-dependency ${holder} --add --from ${path} ` +
-            STAGED_DEPENDENCY_REASON_PLACEHOLDER),
+        commands: holders.map((holder) => `fireforge patch staged-dependency ${holder} --add --from ${path}${reasonFlag}`),
     };
 }
 /** The refusal lines that point at a written report. */
@@ -69,7 +76,7 @@ export function formatDeclarationsReport(report) {
 export async function withDeclarationsReport(conflicts, args) {
     if (conflicts === null)
         return null;
-    const report = await writeDeclarationsReport(args.projectRoot, args.regressions, args.out, args.rename);
+    const report = await writeDeclarationsReport(args.projectRoot, args.regressions, args.out, args.rename, args.reason);
     if (report === undefined)
         return conflicts;
     return { ...conflicts, details: [...conflicts.details, ...formatDeclarationsReport(report)] };

package/dist/src/commands/discard.js

@@ -33,7 +33,7 @@ async function confirmDiscard(message, hint, options) {
 /**
  * Plans the restore baseline for `entries`: the patch-applied baseline for
  * patch-claimed paths, or pristine HEAD when `--to-upstream`
- * explicitly requests the legacy semantics.
+ * explicitly requests it.
  */
 async function planDiscards(patchesDir, engineDir, entries, options) {
     if (options.toUpstream)
@@ -160,8 +160,8 @@ export async function discardCommand(projectRoot, file, options = {}) {
     }
     if (options.dryRun) {
         // Show the rename pair regardless of which side the operator passed.
-        // Passing the new path of a rename used to hide that discarding also
-        // resurrects the old path, exactly when the full picture matters most.
+        // Discarding the new path of a rename also resurrects the old path, so
+        // the preview names both, exactly when the full picture matters most.
         info(`Would discard changes to: ${dryRunLabel(plan)}`);
         outro('Dry run complete — no changes made');
         return;

package/dist/src/commands/doctor-furnace-config-sync.js

@@ -138,10 +138,10 @@ function emptyOutcome() {
  *    under `custom` would leave it in both maps, a state nothing validates.
  *    Every orphan is therefore re-checked against `freshConfig` inside the
  *    lock and skipped when it is no longer orphaned.
- * 2. Delete custom directories outside the lock. `repairCustomOrphans` used to
- *    run after the lock was released, so a `furnace create` that had
- *    registered a name and not yet populated its directory had that directory
- *    deleted underneath it.
+ * 2. Delete custom directories outside the lock. `repairCustomOrphans` runs
+ *    after the lock is released, so it must not delete the directory of a
+ *    name a concurrent `furnace create` has registered but not yet
+ *    populated.
  */
 async function repairOrphans(projectRoot, orphans) {
     const outcome = emptyOutcome();

package/dist/src/commands/doctor-furnace.js

@@ -443,8 +443,8 @@ async function readFurnaceLockPid(lockPath) {
  *
  * This is the recovery path when the signal-handler sweep
  * (`forceReleaseFurnaceLocksForActiveOperations` in `bin/fireforge.ts`)
- * misses: a SIGKILL'd process that never ran the handler, or a lock created
- * by an older FireForge release without a PID file. SIGINT'ing `furnace
+ * misses: a SIGKILL'd process that never ran the handler, or a lock
+ * directory without a PID file. SIGINT'ing `furnace
  * preview` leaves the lock behind, and the next `fireforge test --build`
  * then times out waiting for it. `doctor --repair-furnace` clears it so the
  * next command runs immediately.
@@ -464,9 +464,9 @@ const furnaceStaleLockCheck = {
         const ageSuffix = ageMs !== undefined ? ` (age: ${Math.round(ageMs / 1000)}s)` : '';
         // Two signals mark a lock as stale:
         //   1. PID file says owner is dead → unambiguous, remove immediately.
-        //   2. PID file absent and lock is older than 60s → older FireForge
-        //      releases (or an externally-created lock directory) fall into this
-        //      bucket. The age gate avoids false positives on a lock just
+        //   2. PID file absent and lock is older than 60s → a lock directory
+        //      written without a PID file (for example created externally)
+        //      falls into this bucket. The age gate avoids false positives on a lock just
         //      acquired by a concurrent process that has not written its PID yet.
         //
         // `isProcessAlive` treats EPERM as alive. Returning false for EPERM

package/dist/src/commands/export-adopt-check.d.ts

@@ -4,12 +4,11 @@
  * adopt-then-split for a real moved-code block, but only after checking
  * that the adopt itself would pass.
  *
- * The advice used to be offered on the moved-code heuristic alone. On one
- * queue it told the operator to adopt six new modules into an existing
- * patch when the only error was the missing registration; the adopt then
- * refused one module for importing later patches, and without it breached
- * the source patch's hard size limit. Split out of export-flow.ts for the
- * line budget.
+ * The moved-code heuristic alone is not enough: it can advise adopting
+ * several new modules into an existing patch when the only error is the
+ * missing registration, and the adopt then refuses a module for importing
+ * later patches, or without it breaches the source patch's hard size limit.
+ * Split out of export-flow.ts for the line budget.
  */
 import { type PatchQueueContext } from '../core/patch-lint.js';
 import type { PatchLintIssue } from '../types/commands/index.js';

package/dist/src/commands/export-adopt-check.js

@@ -5,12 +5,11 @@
  * adopt-then-split for a real moved-code block, but only after checking
  * that the adopt itself would pass.
  *
- * The advice used to be offered on the moved-code heuristic alone. On one
- * queue it told the operator to adopt six new modules into an existing
- * patch when the only error was the missing registration; the adopt then
- * refused one module for importing later patches, and without it breached
- * the source patch's hard size limit. Split out of export-flow.ts for the
- * line budget.
+ * The moved-code heuristic alone is not enough: it can advise adopting
+ * several new modules into an existing patch when the only error is the
+ * missing registration, and the adopt then refuses a module for importing
+ * later patches, or without it breaches the source patch's hard size limit.
+ * Split out of export-flow.ts for the line budget.
  */
 import { detectMovedCodeOverlaps, formatMovedCodeAdvice } from '../core/export-moved-code-shape.js';
 import { countNonBinaryDiffLines, getPatchSizeThresholds, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';

package/dist/src/commands/export-flow.js

@@ -180,7 +180,10 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         ...pendingBody,
     });
     projectedEntries.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
-    const policyRest = baseCtx.patchPolicy ? { patchPolicy: baseCtx.patchPolicy } : {};
+    // The projection keeps every queue-wide lint setting of the baseline
+    // (patch policy, forward-registration scope, token scales), so a
+    // test-manifest suite entry is checked exactly as the committed gate
+    // checks it.
     // A new module whose moz.build line is declared (staged registration)
     // and present in the working tree, but not yet exported by its owner, is
     // accepted with a "re-export the owner next" note instead of refused.
@@ -189,10 +192,7 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
         baseCtx,
         newFilename: plan.newFilename,
         pendingNewFiles: new Set(pendingBody.newFiles.keys()),
-        projectedIssues: lintPatchQueue({
-            entries: projectedEntries,
-            ...policyRest,
-        }).filter((i) => i.severity === 'error'),
+        projectedIssues: lintPatchQueue({ ...baseCtx, entries: projectedEntries }).filter((i) => i.severity === 'error'),
     });
     for (const note of registration.accepted)
         warn(note);
@@ -203,10 +203,7 @@ export async function projectPlacementForLint(patchesDir, plan, diff, config) {
     // pre-existing breakage rather than a consequence of this placement, and
     // calling it one would misattribute. Entries are already in memory,
     // so this second pass costs no additional IO.
-    const baselineIssues = lintPatchQueue({
-        entries: baseCtx.entries,
-        ...policyRest,
-    }).filter((i) => i.severity === 'error');
+    const baselineIssues = lintPatchQueue(baseCtx).filter((i) => i.severity === 'error');
     // Register-first and new-file + moved-code advice: name the working
     // sequence instead of leaving the operator to derive it from two
     // individually-correct guards that together dead-end, but only offer

package/dist/src/commands/export-staged-registration.d.ts

@@ -2,10 +2,10 @@
  * Lets `export --order` land a new system module whose moz.build line is
  * still unexported working-tree drift in the patch that registers it.
  *
- * The two refusals used to deadlock: the module's export failed
- * `unregistered-system-module` because no patch body carried its moz.build
- * line yet, and the registering patch could not be re-exported first
- * because its line named a file no patch created. The way through is
+ * Without this the two refusals deadlock: the module's export fails
+ * `unregistered-system-module` because no patch body carries its moz.build
+ * line yet, and the registering patch cannot be re-exported first because
+ * its line names a file no patch creates. The way through is
  * declared intent plus evidence: when the registering patch carries a
  * staged registration for the module and the working tree's moz.build has
  * exactly that line, the export is accepted and the operator is told to

package/dist/src/commands/export-staged-registration.js

@@ -3,10 +3,10 @@
  * Lets `export --order` land a new system module whose moz.build line is
  * still unexported working-tree drift in the patch that registers it.
  *
- * The two refusals used to deadlock: the module's export failed
- * `unregistered-system-module` because no patch body carried its moz.build
- * line yet, and the registering patch could not be re-exported first
- * because its line named a file no patch created. The way through is
+ * Without this the two refusals deadlock: the module's export fails
+ * `unregistered-system-module` because no patch body carries its moz.build
+ * line yet, and the registering patch cannot be re-exported first because
+ * its line names a file no patch creates. The way through is
  * declared intent plus evidence: when the registering patch carries a
  * staged registration for the module and the working tree's moz.build has
  * exactly that line, the export is accepted and the operator is told to

package/dist/src/commands/forward-import-remedy.d.ts

@@ -4,9 +4,8 @@
  * can take as their own later patch, and the exact `patch staged-dependency
  * --add` commands that declare the edges instead.
  *
- * The refusal used to end with "export them with --order <n> or run
- * patch staged-dependency --add", which left the operator to work out both
- * the number and every flag of the declaration from the finding text.
+ * Both the order number and every flag of the declaration are spelled out,
+ * so the operator does not have to work them out from the finding text.
  */
 import type { PatchesManifest, PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';

package/dist/src/commands/forward-import-remedy.js

@@ -5,9 +5,8 @@
  * can take as their own later patch, and the exact `patch staged-dependency
  * --add` commands that declare the edges instead.
  *
- * The refusal used to end with "export them with --order <n> or run
- * patch staged-dependency --add", which left the operator to work out both
- * the number and every flag of the declaration from the finding text.
+ * Both the order number and every flag of the declaration are spelled out,
+ * so the operator does not have to work them out from the finding text.
  */
 import { STAGED_DEPENDENCY_REASON_PLACEHOLDER } from '../core/patch-lint-staged-registration.js';
 import { earliestLegalOrderAfter } from '../core/patch-order-legal.js';

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -19,8 +19,8 @@ export interface DryRunPlanInput {
      * Resolved `--test-dir` override (engine-relative, already validated by
      * `resolveValidatedTestDir`). Omit for the default `<binaryName>`-derived
      * scaffold directory. The formatters must receive the same value the
-     * scaffolders get. The plan used to recompute the default from
-     * `binaryName` and named a directory the real run never wrote to.
+     * scaffolders get; recomputing the default from `binaryName` would name a
+     * directory the real run never writes to.
      */
     testDir?: string;
 }

package/dist/src/commands/furnace/deploy-fragment-includers.d.ts

@@ -4,8 +4,8 @@
  * When `<tag>` includes a shared CSS fragment that changed, every other
  * deployed includer of that fragment still carries the old expansion after
  * the targeted deploy. Deploy-all refreshes all of them as a side effect of
- * deploying everything; the targeted form used to refresh exactly the named
- * component and say nothing about the rest. This module refreshes the other
+ * deploying everything; the targeted form refreshes only the named
+ * component. This module refreshes the other
  * stale includers through the same pipeline and reports them, so a stale
  * expansion is never left behind silently.
  */

package/dist/src/commands/furnace/deploy-fragment-includers.js

@@ -5,8 +5,8 @@
  * When `<tag>` includes a shared CSS fragment that changed, every other
  * deployed includer of that fragment still carries the old expansion after
  * the targeted deploy. Deploy-all refreshes all of them as a side effect of
- * deploying everything; the targeted form used to refresh exactly the named
- * component and say nothing about the rest. This module refreshes the other
+ * deploying everything; the targeted form refreshes only the named
+ * component. This module refreshes the other
  * stale includers through the same pipeline and reports them, so a stale
  * expansion is never left behind silently.
  */

package/dist/src/commands/furnace/index.js

@@ -24,8 +24,8 @@ import { parseMaxWarnings } from './validate-report.js';
  * Splits the raw `--wait-lock` value off a furnace leaf's parsed options and
  * resolves it into `waitLockSeconds` (flag, else `FIREFORGE_WAIT_LOCK`, else
  * undefined) for the furnace lock `runFurnaceMutation` takes. Used by the
- * leaves that take only Furnace's lock, where the flag used to be accepted
- * and ignored.
+ * leaves that take only Furnace's lock, so the flag is honoured there rather
+ * than accepted and ignored.
  */
 function withFurnaceLockBudget(options) {
     const { waitLock, ...rest } = options;

package/dist/src/commands/lint.js

@@ -377,7 +377,7 @@ async function reportLintOutcome(engineDir, issues, options) {
     // with warnings" when only notices fired contradicts the preceding
     // `0 warning(s)` summary line and reads as a regression. Errors suppressed
     // by --only-introduced still warrant the "with warnings" outro: they print
-    // as ERROR rows but no longer fail the run, which is the same contract the
+    // as ERROR rows but do not fail the run, which is the same contract the
     // operator gets from a real warning.
     const suppressedErrors = options.onlyIntroduced && errors.length > 0;
     if (warnings.length > 0 || suppressedErrors) {
@@ -480,7 +480,7 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .option('--since <git-rev>', 'Tag issues as [introduced] or [cumulative] based on whether the file changed since <git-rev> (e.g. HEAD, a branch, a SHA)')
         .option('--only-introduced', 'Fail only on issues tagged [introduced] (requires --since). Cumulative errors still print but do not set a non-zero exit.')
         .option('--per-patch', "Lint each patch in the queue as its own isolated diff. Rescopes patch-size rules so they fire against individual patches rather than the aggregate. Honours each patch's `lintIgnore` entries.")
-        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma lists, full filenames/stems, bare order numbers, manifest names, category-prefixed slugs, or bare slugs. Positional arguments after --per-patch are treated the same way.')
+        .option('--patches <names...>', 'With --per-patch, lint only the named patches. Accepts repeated flags, comma or whitespace lists, full filenames/stems, bare order numbers, manifest names, category-prefixed slugs, or bare slugs. Positional arguments after --per-patch are treated the same way.')
         .option('--max-warnings <n>', 'Fail when lint reports more than <n> warning(s); use 0 for warning-clean release gates.')
         .option('--no-cache', 'Bypass per-patch lint result cache reads and writes.')
         .option('--report <path>', 'With --per-patch, write a machine-readable JSON report (per-patch size metrics, tier, thresholds, issues, and lintIgnore-suppressed issues) to <path>.')
@@ -527,8 +527,8 @@ export function registerLint(program, { getProjectRoot, withErrorHandling }) {
         .description('Manage the per-patch lint result cache')
         // Commander routes `fireforge lint cache` here even when the operator
         // meant to lint an engine directory literally named `cache`. A bare
-        // `lint cache` (no subcommand) used to silently do nothing, so make
-        // the ambiguity explicit instead of doing the wrong operation quietly.
+        // `lint cache` (no subcommand) would otherwise silently do nothing, so
+        // make the ambiguity explicit instead of doing the wrong operation quietly.
         .action(withErrorHandling(() => {
         info('Nothing to do: "lint cache" manages the lint result cache (try "lint cache clear"). ' +
             'To lint a directory named cache/, disambiguate with a trailing slash: "fireforge lint cache/".');

package/dist/src/commands/patch/compact.js

@@ -22,7 +22,7 @@ import { addWaitLockOption, pickDefined, resolveWaitLockSeconds } from '../../ut
 import { proceedAfterDecision } from '../destructive-decision.js';
 import { renameMapsEqual } from '../patch-rename-map.js';
 import { requirePatchQueue } from './patch-context.js';
-import { rebuildFilenameForOrder } from './reorder.js';
+import { rebuildFilenameForOrder } from './reorder-projection.js';
 /** True when `order` falls inside a configured reserved range. */
 function isReservedOrder(policyCfg, order) {
     return (policyCfg.reservedRanges ?? []).some((r) => order >= r.from && order <= r.to);

package/dist/src/commands/patch/lint-ignore-from.d.ts

@@ -2,10 +2,9 @@
  * Batch and per-entry input for `patch lint-ignore --add`. Split out of
  * `lint-ignore.ts` for the per-file line budget.
  *
- * A rebaseline that sets a ceiling per rule used to take one call per rule,
- * each taking the patch lock and rewriting `patches.json` (138 calls on one
- * consumer's queue), because `--max` applied to every `--add` of a call.
- * Two forms lift that:
+ * `--max` applies to every `--add` of a call, so a rebaseline that sets a
+ * ceiling per rule would take one call per rule, each taking the patch lock
+ * and rewriting `patches.json`. Two forms avoid that:
  *
  * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
  * - `--from <json-file>` reads every entry from a file, under one lock hold

package/dist/src/commands/patch/lint-ignore-from.js

@@ -3,10 +3,9 @@
  * Batch and per-entry input for `patch lint-ignore --add`. Split out of
  * `lint-ignore.ts` for the per-file line budget.
  *
- * A rebaseline that sets a ceiling per rule used to take one call per rule,
- * each taking the patch lock and rewriting `patches.json` (138 calls on one
- * consumer's queue), because `--max` applied to every `--add` of a call.
- * Two forms lift that:
+ * `--max` applies to every `--add` of a call, so a rebaseline that sets a
+ * ceiling per rule would take one call per rule, each taking the patch lock
+ * and rewriting `patches.json`. Two forms avoid that:
  *
  * - `--add <rule>=<max>` gives each entry its own ceiling in one call.
  * - `--from <json-file>` reads every entry from a file, under one lock hold

package/dist/src/commands/patch/move-files-adopt.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `patch move-files --scan-file <path>`: adopt new engine files into the
+ * move's destination in the same transaction.
+ *
+ * Splitting a widget across patches moved existing files and adopted the
+ * seam modules that appeared beside them. Adopting first (`re-export
+ * --scan --scan-file`) grew the source past its own `large-patch-lines`
+ * ceiling, which refused although the move that followed would have
+ * shrunk it again. Adopting straight into the destination of the move
+ * means no patch ever carries the intermediate body: both sides are linted
+ * on what the transaction leaves behind.
+ */
+import type { PatchMetadata } from '../../types/commands/index.js';
+/**
+ * Validates `--scan-file` paths: each must be engine-relative, exist in
+ * `engine/`, be owned by no patch and not be one of the moved files.
+ * Returns the sorted, de-duplicated list.
+ *
+ * @param rawFiles - The `--scan-file` values
+ * @param patches - Manifest rows
+ * @param enginePath - Engine directory
+ * @param movedFiles - The `--file` paths of the same move
+ */
+export declare function resolveAdoptedFiles(rawFiles: readonly string[] | undefined, patches: readonly PatchMetadata[], enginePath: string, movedFiles: readonly string[]): Promise<string[]>;
+/**
+ * Re-checks under the patch-directory lock that no patch claimed an
+ * adopted file while the move waited for confirmation.
+ *
+ * @param patches - Manifest rows read under the lock
+ * @param adoptedFiles - Files the move adopts
+ * @param command - Command name for the error
+ */
+export declare function assertAdoptedStillUnowned(patches: readonly PatchMetadata[], adoptedFiles: readonly string[] | undefined, command: string): void;