@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/ownership-table.d.ts

@@ -21,7 +21,7 @@ interface StatusFile {
  *
  * Populated from three sources:
  *
- *   1. Every path in every patch's `filesAffected` — so managed paths show up
+ *   1. Every path in every patch's `filesAffected`, so managed paths show up
  *      even when they are not currently modified on disk.
  *   2. Any worktree status entries not claimed by any patch (flagged as
  *      `unmanaged`).
@@ -36,17 +36,17 @@ interface StatusFile {
  * `conflictReason` so the output can disambiguate.
  *
  * @param manifestPatches - Manifest rows, each with its `filesAffected`
- * @param worktreeFiles - Raw worktree status entries; untracked and modified
+ * @param worktreeFiles - Raw worktree status entries. Untracked and modified
  *   both acceptable
  * @param newFileCreatorsByPath - Map produced by
- *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath};
- *   paths with a `.length > 1` owner list become duplicate-create conflicts
+ *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath}.
+ *   Paths with a `.length > 1` owner list become duplicate-create conflicts
  */
 export declare function buildOwnershipTable(manifestPatches: PatchMetadata[], worktreeFiles: StatusFile[], newFileCreatorsByPath: Map<string, string[]>, classifications?: Map<string, FileClassification>): OwnershipRow[];
 /**
  * Renders the ownership table as a GitHub-flavored Markdown pipe table.
  * Using markdown-table's own serializer would require a seed document to
- * graft onto, which is overkill for ad-hoc status output; the rendering
+ * graft onto, which is overkill for ad-hoc status output. The rendering
  * here is trivial enough to inline.
  */
 export declare function renderOwnershipTable(rows: OwnershipRow[]): void;

package/dist/src/core/ownership-table.js

@@ -6,7 +6,7 @@ import { buildPatchClaims } from './status-classify.js';
  *
  * Populated from three sources:
  *
- *   1. Every path in every patch's `filesAffected` — so managed paths show up
+ *   1. Every path in every patch's `filesAffected`, so managed paths show up
  *      even when they are not currently modified on disk.
  *   2. Any worktree status entries not claimed by any patch (flagged as
  *      `unmanaged`).
@@ -21,11 +21,11 @@ import { buildPatchClaims } from './status-classify.js';
  * `conflictReason` so the output can disambiguate.
  *
  * @param manifestPatches - Manifest rows, each with its `filesAffected`
- * @param worktreeFiles - Raw worktree status entries; untracked and modified
+ * @param worktreeFiles - Raw worktree status entries. Untracked and modified
  *   both acceptable
  * @param newFileCreatorsByPath - Map produced by
- *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath};
- *   paths with a `.length > 1` owner list become duplicate-create conflicts
+ *   {@link import('../core/patch-lint.js').collectNewFileCreatorsByPath}.
+ *   Paths with a `.length > 1` owner list become duplicate-create conflicts
  */
 export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreatorsByPath, classifications = new Map()) {
     const ownersByPath = buildPatchClaims(manifestPatches);
@@ -57,7 +57,7 @@ export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreat
         const duplicateOwners = duplicateCreateByPath.get(path);
         const isFilesAffectedConflict = owners.length > 1;
         const isDuplicateCreateConflict = duplicateOwners !== undefined;
-        // Prefer the filesAffected reason when both apply — it's the older
+        // Prefer the filesAffected reason when both apply: it's the older
         // source of drift and the operator will usually want to fix the
         // manifest rows even when the bodies also duplicate-create.
         const conflictReason = isFilesAffectedConflict
@@ -105,7 +105,7 @@ export function buildOwnershipTable(manifestPatches, worktreeFiles, newFileCreat
  * `files-affected` drift (two manifest rows claiming the same path) from
  * `duplicate-create` drift (two patches both hitting `/dev/null → b/path`
  * in their bodies) so the operator can tell at a glance which fix
- * applies — the former wants `re-export --files`, the latter wants
+ * applies. The former wants `re-export --files`, the latter wants
  * `patch delete`.
  */
 function renderConflictCell(row) {
@@ -134,7 +134,7 @@ function renderStateCell(row) {
 /**
  * Renders the ownership table as a GitHub-flavored Markdown pipe table.
  * Using markdown-table's own serializer would require a seed document to
- * graft onto, which is overkill for ad-hoc status output; the rendering
+ * graft onto, which is overkill for ad-hoc status output. The rendering
  * here is trivial enough to inline.
  */
 export function renderOwnershipTable(rows) {

package/dist/src/core/parser-fallback.d.ts

@@ -14,8 +14,8 @@ export declare function consumeParserFallbackEvents(): ParserFallbackEvent[];
  *
  * Rethrows internal-invariant `GeneralError`s ("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
+ * broken invariant, it just buries the stack. Everything else still falls
+ * back, which matters: 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.
@@ -43,7 +43,7 @@ export interface ParserResult<T> {
  * @param primary - The modern parser implementation
  * @param fallback - The legacy fallback implementation
  * @param context - File/context name used in the warning message
- * @param rethrowIf - Optional predicate; if it returns true for the caught
+ * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for
  *   domain-specific errors that should not be swallowed).
  */

package/dist/src/core/parser-fallback.js

@@ -19,8 +19,8 @@ export function consumeParserFallbackEvents() {
  *
  * Rethrows internal-invariant `GeneralError`s ("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
+ * broken invariant, it just buries the stack. Everything else still falls
+ * back, which matters: 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.
@@ -42,7 +42,7 @@ export function isInternalInvariantFailure(error) {
  * @param primary - The modern parser implementation
  * @param fallback - The legacy fallback implementation
  * @param context - File/context name used in the warning message
- * @param rethrowIf - Optional predicate; if it returns true for the caught
+ * @param rethrowIf - Optional predicate. If it returns true for the caught
  *   error the error is re-thrown instead of falling back (useful for
  *   domain-specific errors that should not be swallowed).
  */

package/dist/src/core/patch-apply-fuzz.d.ts

@@ -3,17 +3,17 @@
  *
  * Tries an exact `git apply` first, then retries with git's real
  * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply` has
- * NO `--fuzz` option — that flag belongs to GNU `patch(1)`, and passing it
+ * no `--fuzz` option. That flag belongs to GNU `patch(1)`, and passing it
  * makes git exit 129 with a usage error that an escalation loop will happily
  * swallow, so every "fuzzy" attempt silently fails and patches that would
  * have applied with context drift are reported as hard conflicts. If all
  * context-reduction levels fail, falls through to `git apply --reject` so
  * the user gets `.rej` files for manual resolution.
  *
- * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * Semantics note: GNU fuzz *fuzzily matches* context. `-C<n>` *ignores*
  * outer context lines instead. Step k maps to `-C(3-k)` (git's default
  * context width is 3), so the final step `-C0` matches on line positions and
- * -/+ content alone — the rough analogue of GNU `--fuzz=3` on a 3-context
+ * -/+ content alone, the rough analogue of GNU `--fuzz=3` on a 3-context
  * patch.
  */
 export interface FuzzyApplyResult {
@@ -38,8 +38,8 @@ export interface FuzzyApplyResult {
  * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
  *   0 = exact only). Values above 3 are capped: git cannot reduce below
  *   `-C0`.
- * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
- *   a NaN or negative value would silently skip every apply attempt
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer.
+ *   A NaN or negative value would silently skip every apply attempt
  *   (including the exact-match one) and fall straight through to `--reject`
  */
 export declare function applyPatchWithFuzz(patchPath: string, engineDir: string, maxFuzz?: number): Promise<FuzzyApplyResult>;

package/dist/src/core/patch-apply-fuzz.js

@@ -4,24 +4,24 @@
  *
  * Tries an exact `git apply` first, then retries with git's real
  * drift-tolerance knob: `-C<n>` (reduced context matching). `git apply` has
- * NO `--fuzz` option — that flag belongs to GNU `patch(1)`, and passing it
+ * no `--fuzz` option. That flag belongs to GNU `patch(1)`, and passing it
  * makes git exit 129 with a usage error that an escalation loop will happily
  * swallow, so every "fuzzy" attempt silently fails and patches that would
  * have applied with context drift are reported as hard conflicts. If all
  * context-reduction levels fail, falls through to `git apply --reject` so
  * the user gets `.rej` files for manual resolution.
  *
- * Semantics note: GNU fuzz *fuzzily matches* context; `-C<n>` *ignores*
+ * Semantics note: GNU fuzz *fuzzily matches* context. `-C<n>` *ignores*
  * outer context lines instead. Step k maps to `-C(3-k)` (git's default
  * context width is 3), so the final step `-C0` matches on line positions and
- * -/+ content alone — the rough analogue of GNU `--fuzz=3` on a 3-context
+ * -/+ content alone, the rough analogue of GNU `--fuzz=3` on a 3-context
  * patch.
  */
 import { InvalidArgumentError } from '../errors/base.js';
 import { verbose } from '../utils/logger.js';
 import { exec } from '../utils/process.js';
 import { ensureGit } from './git-base.js';
-/** Git's default diff context width — the ceiling for reduction steps. */
+/** Git's default diff context width, the ceiling for reduction steps. */
 const GIT_DEFAULT_CONTEXT = 3;
 // ── Implementation ──
 /**
@@ -36,19 +36,19 @@ const GIT_DEFAULT_CONTEXT = 3;
  * @param maxFuzz   - Maximum context-reduction steps to try (default 3,
  *   0 = exact only). Values above 3 are capped: git cannot reduce below
  *   `-C0`.
- * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer —
- *   a NaN or negative value would silently skip every apply attempt
+ * @throws InvalidArgumentError when `maxFuzz` is not a non-negative integer.
+ *   A NaN or negative value would silently skip every apply attempt
  *   (including the exact-match one) and fall straight through to `--reject`
  */
 export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
     if (!Number.isInteger(maxFuzz) || maxFuzz < 0) {
-        throw new InvalidArgumentError(`maxFuzz must be a non-negative integer, got ${String(maxFuzz)}.`, 'maxFuzz');
+        throw new InvalidArgumentError(`maxFuzz must be a non-negative integer, got ${maxFuzz}.`, 'maxFuzz');
     }
     await ensureGit();
     // Try exact match first, then escalate context reduction.
     const maxSteps = Math.min(maxFuzz, GIT_DEFAULT_CONTEXT);
     for (let step = 0; step <= maxSteps; step++) {
-        const contextArgs = step > 0 ? [`-C${String(GIT_DEFAULT_CONTEXT - step)}`] : [];
+        const contextArgs = step > 0 ? [`-C${GIT_DEFAULT_CONTEXT - step}`] : [];
         const check = await exec('git', ['apply', '--check', ...contextArgs, '--', patchPath], {
             cwd: engineDir,
         });
@@ -59,12 +59,12 @@ export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
             });
             if (apply.exitCode === 0) {
                 if (step > 0) {
-                    verbose(`Patch applied with reduced context (-C${String(GIT_DEFAULT_CONTEXT - step)}): ${patchPath}`);
+                    verbose(`Patch applied with reduced context (-C${GIT_DEFAULT_CONTEXT - step}): ${patchPath}`);
                 }
                 return { success: true, fuzzFactor: step };
             }
-            // Unlikely: --check passed but apply failed; fall through to next step
-            verbose(`git apply -C${String(GIT_DEFAULT_CONTEXT - step)} --check passed but apply failed: ${apply.stderr.trim()}`);
+            // Unlikely: --check passed but apply failed. Fall through to next step
+            verbose(`git apply -C${GIT_DEFAULT_CONTEXT - step} --check passed but apply failed: ${apply.stderr.trim()}`);
         }
     }
     // All context-reduction levels failed → generate .rej files for manual resolution
@@ -88,8 +88,8 @@ export async function applyPatchWithFuzz(patchPath, engineDir, maxFuzz = 3) {
  *   Rejected hunk #1.
  *
  * The reject file is `<file>.rej` next to the target. Matching GNU
- * `patch(1)`'s "saving rejects to file X.rej" phrasing instead — which git
- * never prints — leaves `rejectFiles` always empty and the
+ * `patch(1)`'s "saving rejects to file X.rej" phrasing instead, which git
+ * never prints, leaves `rejectFiles` always empty and the
  * conflict-summary ".rej files created" hint never fires.
  */
 function extractRejectFiles(stderr) {

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

@@ -1,13 +1,12 @@
 /**
- * Patch orchestration — coordinates patch discovery, application, and validation.
+ * Patch orchestration. Coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
 import type { ImportSummary, PatchInfo, PatchMetadata } from '../types/commands/index.js';
 export { PatchError } from '../errors/patch.js';
-export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
+export { countPatches, discoverPatches } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
-export { extractAffectedFiles, extractOrder, isNewFileInPatch } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { extractAffectedFiles } from './patch-parse.js';
 /**
  * Options for {@link applyPatchesWithContinue}.
  */
@@ -28,14 +27,14 @@ export interface ApplyPatchesOptions {
  * The identifier is one of three shapes and the three shapes must stay
  * disjoint so the operator can reason about which patch they picked:
  *
- *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
- *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
- *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *   1. Exact filename, `005-foo.patch`. Matches only that filename.
+ *   2. Filename without extension, `005-foo`. Matches `005-foo.patch`.
+ *   3. Bare numeric ordinal, `5` or `005`. Matches the patch whose
  *      order prefix parses to the same integer (so `5` and `005` both match
  *      `005-foo.patch`, and `05` matches too because parseInt normalizes
  *      leading zeros).
  *
- * A purely-numeric identifier is treated **only** as an ordinal: it does not
+ * A purely-numeric identifier is treated only as an ordinal: it does not
  * also match a filename that happens to literally equal the digits. That
  * would require a patch literally named `5` or `005`, which would collide
  * with the filename prefix anyway.
@@ -47,10 +46,10 @@ export declare function matchesUntilFilename(patchFilename: string, needle: stri
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
+ * @param options - Application options
  * @returns Import summary with all results
  */
-export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, optionsOrContinue?: ApplyPatchesOptions | boolean): Promise<ImportSummary>;
+export declare function applyPatchesWithContinue(patchesDir: string, engineDir: string, options?: ApplyPatchesOptions): Promise<ImportSummary>;
 /**
  * Batched patched-content computation shared by status classification,
  * import's unmanaged-dirty guard, and discard baseline planning.
@@ -67,10 +66,10 @@ export interface PatchedContentContext {
 }
 /**
  * Builds a batched patched-content context that loads the manifest and
- * discovers patch files ONCE for many lookups, and memoizes each patch body
+ * discovers patch files once for many lookups, and memoizes each patch body
  * read across the batch. A per-call helper re-runs `loadPatchesManifest` +
- * `discoverPatches` and re-reads every affecting patch body for every file —
- * O(dirtyFiles × patches) redundant IO when classifying a broad engine edit
- * session during `status` or `import`.
+ * `discoverPatches` and re-reads every affecting patch body for every file,
+ * which is O(dirtyFiles × patches) redundant IO when classifying a broad
+ * engine edit session during `status` or `import`.
  */
 export declare function createPatchedContentContext(patchesDir: string, engineDir: string): Promise<PatchedContentContext>;

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Patch orchestration — coordinates patch discovery, application, and validation.
+ * Patch orchestration. Coordinates patch discovery, application, and validation.
  * Pure parsing, content transformation, and lock management are in separate modules.
  */
 import { lstat, readFile, readlink, realpath, rm } from 'node:fs/promises';
@@ -11,24 +11,23 @@ import { pathExists, readText, writeFileAtomic, writeText } from '../utils/fs.js
 import { verbose } from '../utils/logger.js';
 import { isContainedRelativePath } from '../utils/paths.js';
 import { applyPatchIdempotent, reversePatch } from './git.js';
-import { getFileContentFromHead } from './git-file-ops.js';
+import { getFileContentAtRef } from './git-file-ops.js';
 import { discoverPatches } from './patch-files.js';
 import { loadPatchesManifest } from './patch-manifest.js';
 import { extractAffectedFiles, extractConflictingFiles, isNewFileInPatch, parseDiffSections, } from './patch-parse.js';
 import { applyPatchTextToContent, extractNewFileContentFromDiff } from './patch-transform.js';
 // Re-export from split modules so existing import sites continue working
 export { PatchError } from '../errors/patch.js';
-export { countPatches, discoverPatches, getAllTargetFilesFromPatch, getTargetFileFromPatch, isNewFilePatch, } from './patch-files.js';
+export { countPatches, discoverPatches } from './patch-files.js';
 export { withPatchDirectoryLock } from './patch-lock.js';
-export { extractAffectedFiles, extractOrder, isNewFileInPatch } from './patch-parse.js';
-export { applyPatchToContent, extractNewFileContent } from './patch-transform.js';
+export { extractAffectedFiles } from './patch-parse.js';
 /**
  * Applies a single patch.
  *
  * @param patch - Patch info
  * @param engineDir - Path to the engine directory
  * @param protectedFiles - Files touched by patches already applied in the
- *   current run; the idempotent-recovery reset must not wipe them (see
+ *   current run. The idempotent-recovery reset must not wipe them (see
  *   applyPatchIdempotent). Overlapping queues (`--allow-overlap`) share files
  *   between patches, and resetting a shared file to HEAD during a later
  *   patch's recovery silently discards the earlier patch's changes.
@@ -59,7 +58,7 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
         // losslessly where a utf-8 decode of a binary file does not.
         const savedContents = new Map();
         // New-file sections keyed by target, so the binary discrimination below
-        // reads the ALREADY-parsed section instead of re-scanning the body per
+        // reads the already-parsed section instead of re-scanning the body per
         // file.
         const newFileSections = new Map(parseDiffSections(patchContent)
             .filter((section) => section.isNewFile)
@@ -74,14 +73,14 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
                 savedContents.set(file, await readFile(targetPath));
                 const section = newFileSections.get(file);
                 if (section?.isBinary === true) {
-                    // A binary new file cannot be resolved by writing extracted text —
-                    // the payload is base85, whose alphabet includes '+'. It does not
-                    // need to be: `git apply` decodes a `GIT binary patch` itself. So
-                    // the resolution is to REMOVE the blocking file and let the retry
-                    // below create it from the payload, which is exactly what the
-                    // text branch achieves by overwriting.
+                    // A binary new file cannot be resolved by writing extracted
+                    // text, because the payload is base85, whose alphabet includes
+                    // '+'. It does not need to be: `git apply` decodes a `GIT binary
+                    // patch` itself. So the resolution is to remove the blocking file
+                    // and let the retry below create it from the payload, which is
+                    // exactly what the text branch achieves by overwriting.
                     if (!section.hasBinaryDelta) {
-                        // `Binary files … differ` records THAT the bytes changed and
+                        // `Binary files … differ` records that the bytes changed and
                         // carries none of them, so nothing can recreate the file. Fail
                         // honestly rather than deleting a file we cannot put back.
                         throw new PatchError(`Cannot resolve the new-file conflict for ${file}: the patch's binary section ` +
@@ -98,8 +97,8 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
             }
         }
         catch (extractError) {
-            // Resolution threw for a LATER target after earlier targets were
-            // already overwritten or removed — restore them before reporting
+            // Resolution threw for a later target after earlier targets were
+            // already overwritten or removed. Restore them before reporting
             // failure, instead of letting the exception skip the restore loop
             // entirely and crash the whole import.
             for (const [file, originalContent] of savedContents) {
@@ -112,7 +111,7 @@ async function applySinglePatch(patch, engineDir, protectedFiles) {
                 await applyPatchIdempotent(patch.path, engineDir, {
                     ...(protectedFiles ? { protectedFiles } : {}),
                 });
-                // Keep the originals: rollbackPatches needs them if a LATER patch
+                // Keep the originals: rollbackPatches needs them if a later patch
                 // fails, since reverse-applying this new-file patch deletes the
                 // target and would otherwise permanently discard the pre-existing
                 // content (recoverable from git only if it was tracked at HEAD).
@@ -162,8 +161,8 @@ async function rollbackPatches(results, engineDir) {
         catch (rollbackError) {
             verbose(`Failed to roll back ${result.patch.filename}: ${toError(rollbackError).message}`);
         }
-        // Reversing an auto-resolved new-file patch deletes the target; put
-        // back the pre-existing content the auto-resolve overwrote.
+        // Reversing an auto-resolved new-file patch deletes the target, so
+        // put back the pre-existing content the auto-resolve overwrote.
         if (result.autoResolvedOriginals) {
             for (const [file, originalContent] of result.autoResolvedOriginals) {
                 try {
@@ -180,7 +179,7 @@ async function rollbackPatches(results, engineDir) {
 async function validatePatchTargets(patch, affectedFiles, engineDir) {
     // realpath the engine root once so containment is checked against the
     // physical tree (the root itself may sit behind a symlink, e.g. /tmp on
-    // macOS). An unresolvable engine dir skips the symlink checks — a missing
+    // macOS). An unresolvable engine dir skips the symlink checks. A missing
     // engine surfaces through `git apply --check` with a better message.
     const engineRoot = engineDir ? await realpath(engineDir).catch(() => null) : null;
     for (const file of affectedFiles) {
@@ -207,7 +206,7 @@ async function validatePatchTargets(patch, affectedFiles, engineDir) {
  * - Dangling symlink: `realpath` rejects it, but a write through the link
  *   would still be created at the link target, so the target is resolved
  *   against the link's (real) parent directory. The link target is taken
- *   textually — a loop or nested dangling link fails at apply time anyway.
+ *   textually. A loop or nested dangling link fails at apply time anyway.
  * - Not-yet-existing file: resolved against the nearest existing ancestor's
  *   real path. Components below that ancestor do not exist, so they cannot
  *   be symlinks and are appended verbatim.
@@ -241,14 +240,14 @@ async function resolvePatchWriteDestination(targetPath) {
  * The identifier is one of three shapes and the three shapes must stay
  * disjoint so the operator can reason about which patch they picked:
  *
- *   1. **Exact filename** — `005-foo.patch`. Matches only that filename.
- *   2. **Filename without extension** — `005-foo`. Matches `005-foo.patch`.
- *   3. **Bare numeric ordinal** — `5` or `005`. Matches the patch whose
+ *   1. Exact filename, `005-foo.patch`. Matches only that filename.
+ *   2. Filename without extension, `005-foo`. Matches `005-foo.patch`.
+ *   3. Bare numeric ordinal, `5` or `005`. Matches the patch whose
  *      order prefix parses to the same integer (so `5` and `005` both match
  *      `005-foo.patch`, and `05` matches too because parseInt normalizes
  *      leading zeros).
  *
- * A purely-numeric identifier is treated **only** as an ordinal: it does not
+ * A purely-numeric identifier is treated only as an ordinal: it does not
  * also match a filename that happens to literally equal the digits. That
  * would require a patch literally named `5` or `005`, which would collide
  * with the filename prefix anyway.
@@ -272,23 +271,18 @@ export function matchesUntilFilename(patchFilename, needle) {
  * on the first failure to keep the engine directory in a clean state.
  * @param patchesDir - Path to the patches directory
  * @param engineDir - Path to the engine directory
- * @param optionsOrContinue - Options object, or the legacy continueOnFailure boolean
+ * @param options - Application options
  * @returns Import summary with all results
  */
-export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrContinue = false) {
-    // Accept both the legacy boolean positional and the new options object so
-    // existing call sites (tests and rebase) keep working without a rewrite.
-    const options = typeof optionsOrContinue === 'boolean'
-        ? { continueOnFailure: optionsOrContinue }
-        : optionsOrContinue;
+export async function applyPatchesWithContinue(patchesDir, engineDir, options = {}) {
     const continueOnFailure = options.continueOnFailure ?? false;
     const untilFilename = options.untilFilename;
     const patches = await discoverPatches(patchesDir);
     // Resolve the --until stop index up front so callers get an immediate
     // error on an unknown identifier instead of a silent no-op. Detect
-    // ambiguity (two patches matching the same needle — should never happen
-    // in a well-formed manifest but surfaces queue corruption loudly
-    // instead of silently picking the first match).
+    // ambiguity (two patches matching the same needle). That should never
+    // happen in a well-formed manifest, but it surfaces queue corruption
+    // loudly instead of silently picking the first match.
     let stopIndex = patches.length - 1;
     if (untilFilename !== undefined) {
         const matchingIndexes = [];
@@ -320,8 +314,8 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrC
         if (!patch)
             continue;
         if (i > stopIndex) {
-            // Patches beyond the --until cutoff are intentionally skipped. They
-            // are not failures — record them in `skipped` so the summary still
+            // Patches beyond the --until cutoff are skipped on purpose. They
+            // are not failures. Record them in `skipped` so the summary still
             // reflects what the full queue contained.
             skipped.push(patch);
             continue;
@@ -364,11 +358,11 @@ export async function applyPatchesWithContinue(patchesDir, engineDir, optionsOrC
 }
 /**
  * Builds a batched patched-content context that loads the manifest and
- * discovers patch files ONCE for many lookups, and memoizes each patch body
+ * discovers patch files once for many lookups, and memoizes each patch body
  * read across the batch. A per-call helper re-runs `loadPatchesManifest` +
- * `discoverPatches` and re-reads every affecting patch body for every file —
- * O(dirtyFiles × patches) redundant IO when classifying a broad engine edit
- * session during `status` or `import`.
+ * `discoverPatches` and re-reads every affecting patch body for every file,
+ * which is O(dirtyFiles × patches) redundant IO when classifying a broad
+ * engine edit session during `status` or `import`.
  */
 export async function createPatchedContentContext(patchesDir, engineDir) {
     const manifest = await loadPatchesManifest(patchesDir);
@@ -406,7 +400,7 @@ export async function createPatchedContentContext(patchesDir, engineDir) {
         getAffectingPatches,
         readPatchBody,
         computePatched: async (filePath) => {
-            let content = await getFileContentFromHead(engineDir, filePath);
+            let content = await getFileContentAtRef(engineDir, filePath);
             for (const patch of getAffectingPatches(filePath)) {
                 content = applyPatchTextToContent(content, await readPatchBody(patch), filePath);
             }

package/dist/src/core/patch-export-coverage.d.ts

@@ -2,15 +2,6 @@
  * Patch coverage and supersession helpers used by export planning.
  */
 import type { PatchInfo, PatchMetadata } from '../types/commands/index.js';
-/**
- * Finds patches that are completely superseded by newer patches.
- * A patch is superseded if all its affected files are covered by newer patches.
- * @param patchesDir - Path to the patches directory
- * @param newPatchFiles - Files affected by the new patch
- * @param excludeFilename - Filename to exclude from results (the new patch itself)
- * @returns Superseded patches
- */
-export declare function findSupersededPatches(patchesDir: string, newPatchFiles: string[], excludeFilename?: string): Promise<PatchInfo[]>;
 /**
  * Report whether a patch is fully covered by a new export, and which of its
  * files caused the coverage.

package/dist/src/core/patch-export-coverage.js

@@ -2,37 +2,8 @@
 /**
  * Patch coverage and supersession helpers used by export planning.
  */
-import { discoverPatches, isNewFilePatch } from './patch-apply.js';
+import { discoverPatches } from './patch-apply.js';
 import { loadPatchesManifest } from './patch-manifest.js';
-/**
- * Finds patches that are completely superseded by newer patches.
- * A patch is superseded if all its affected files are covered by newer patches.
- * @param patchesDir - Path to the patches directory
- * @param newPatchFiles - Files affected by the new patch
- * @param excludeFilename - Filename to exclude from results (the new patch itself)
- * @returns Superseded patches
- */
-export async function findSupersededPatches(patchesDir, newPatchFiles, excludeFilename) {
-    const manifest = await loadPatchesManifest(patchesDir);
-    if (!manifest)
-        return [];
-    const patches = await discoverPatches(patchesDir);
-    const superseded = [];
-    for (const metadata of manifest.patches) {
-        if (excludeFilename && metadata.filename === excludeFilename)
-            continue;
-        if (metadata.filesAffected.length === 1) {
-            const affectedFile = metadata.filesAffected[0];
-            if (affectedFile && newPatchFiles.includes(affectedFile)) {
-                const patch = patches.find((p) => p.filename === metadata.filename);
-                if (patch && (await isNewFilePatch(patch.path))) {
-                    superseded.push(patch);
-                }
-            }
-        }
-    }
-    return superseded;
-}
 /**
  * Checks whether a patch is fully covered by a new export.
  * A patch is fully covered when every file it affects is present in the new export.

package/dist/src/core/patch-export-update.d.ts

@@ -13,6 +13,22 @@ export interface UpdatePatchPolicyGate {
     command: string;
     forceUnsafe?: boolean;
 }
+export interface UpdatePatchAndMetadataOptions {
+    /** Patch directory holding the body and `patches.json`. */
+    patchesDir: string;
+    /** Patch file to rewrite. */
+    filename: string;
+    /** New patch body. An identical body skips the write. */
+    newContent: string;
+    /** Manifest-row fields to merge into the patch's metadata. */
+    updates: Partial<PatchMetadata>;
+    /** Hook run under the lock after the mutation succeeds. */
+    onCommitted?: UpdatePatchCommittedHook | undefined;
+    /** Policy gate run against the under-lock projected manifest. */
+    policyGate?: UpdatePatchPolicyGate | undefined;
+    /** Wait budget and command name for the patch directory lock. */
+    lockOptions?: PatchDirectoryLockOptions | undefined;
+}
 /**
  * Updates a patch file body and its manifest row under the same patch
  * directory lock. Intended for commands like `re-export --files` where the
@@ -20,13 +36,14 @@ export interface UpdatePatchPolicyGate {
  *
  * The body write is skipped when the normalized new content is byte-identical
  * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched; rewriting an
+ * in the queue, including ones the working tree never touched. Rewriting an
  * unchanged body churns its mtime and reports "Re-exported" for a patch
  * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way — only
- * the redundant byte-for-byte write is elided.
+ * unexpected rewrite in `git status`. Metadata still moves either way, and
+ * only the redundant byte-for-byte write is elided.
  *
+ * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was
  *   already byte-identical to the new content.
  */
-export declare function updatePatchAndMetadata(patchesDir: string, filename: string, newContent: string, updates: Partial<PatchMetadata>, onCommitted?: UpdatePatchCommittedHook, policyGate?: UpdatePatchPolicyGate, lockOptions?: PatchDirectoryLockOptions): Promise<boolean>;
+export declare function updatePatchAndMetadata(options: UpdatePatchAndMetadataOptions): Promise<boolean>;

package/dist/src/core/patch-export-update.js

@@ -5,7 +5,6 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
 import { withPatchDirectoryLock } from './patch-apply.js';
-import { normalizePatchArtifact } from './patch-artifact-normalize.js';
 import { loadPatchesManifestForWrite, mutatePatchRowsInManifest } from './patch-manifest.js';
 import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
 /**
@@ -15,16 +14,18 @@ import { buildProjectedManifest, enforcePatchPolicy } from './patch-policy.js';
  *
  * The body write is skipped when the normalized new content is byte-identical
  * to what is already on disk. A bulk `re-export --all` refreshes every patch
- * in the queue, including ones the working tree never touched; rewriting an
+ * in the queue, including ones the working tree never touched. Rewriting an
  * unchanged body churns its mtime and reports "Re-exported" for a patch
  * nothing happened to, which is exactly the noise that hides a real
- * unexpected rewrite in `git status`. Metadata still moves either way — only
- * the redundant byte-for-byte write is elided.
+ * unexpected rewrite in `git status`. Metadata still moves either way, and
+ * only the redundant byte-for-byte write is elided.
  *
+ * @param options - See {@link UpdatePatchAndMetadataOptions}
  * @returns True when the patch body on disk changed, false when it was
  *   already byte-identical to the new content.
  */
-export async function updatePatchAndMetadata(patchesDir, filename, newContent, updates, onCommitted, policyGate, lockOptions = {}) {
+export async function updatePatchAndMetadata(options) {
+    const { patchesDir, filename, newContent, updates, onCommitted, policyGate, lockOptions = {}, } = options;
     return withPatchDirectoryLock(patchesDir, async () => {
         const manifest = await loadPatchesManifestForWrite(patchesDir);
         if (!manifest) {
@@ -49,7 +50,7 @@ export async function updatePatchAndMetadata(patchesDir, filename, newContent, u
                 forceUnsafe: policyGate.forceUnsafe === true,
             });
         }
-        const normalized = normalizePatchArtifact(newContent);
+        const normalized = newContent;
         const bodyChanged = normalized !== originalContent;
         let patchWritten = false;
         try {