@hominis/fireforge 0.13.2 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # Changelog
 
+## 0.15.0
+
+### Furnace registration
+
+- `furnace apply` idempotency check is marker-comment-tolerant. Previously the single-line substring match (`content.includes('["tag",')`) missed multi-line entries, and the standalone-line regex anchored on `\s*$`, which did not allow trailing `// <marker>:` comments an operator may have appended to a previously-written entry. A duplicate tag was then inserted on every re-apply, and the second `setElementCreationCallback` invocation threw `NotSupportedError: Operation is not supported` at every window-load. The idempotency check now matches on tag-name column 0 (both single- and multi-line array shapes) and tolerates trailing `//` comments on the line.
+- New optional fireforge.json field `markerComment` (e.g. `"HOMINIS"`) is appended as a `  // HOMINIS:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
+- `addCustomElementRegistration` and its regex fallback both accept the new marker as an optional parameter; the AST idempotency check and the regex-fallback idempotency check share a single helper (`isTagAlreadyRegistered`).
+
+### Furnace `--localized`
+
+- `furnace create --localized` now emits the Mozilla-idiomatic `MozLitElement` l10n pattern: a module-level `window.MozXULElement?.insertFTLIfNeeded("<chrome-uri>")` call and `this.ownerDocument.l10n?.connectRoot(this.shadowRoot)` / `disconnectRoot` in `connectedCallback` / `disconnectedCallback`. Previously the template called `this.insertFTLIfNeeded(...)` directly on a `MozLitElement` instance, which throws `TypeError: this.insertFTLIfNeeded is not a function` at every connect because that method lives on `MozXULElement`, not `MozLitElement`. The `--localized` path was silently non-functional.
+- `furnace apply` now registers the scaffolded `.ftl` in the locale jar.mn (default `toolkit/locales/jar.mn`) so the chrome URI `insertFTLIfNeeded` expects actually resolves at runtime. Previously only the `.ftl` file itself was copied into the FTL tree, with no chrome registration. `furnace remove` and the workspace-delete codepath (`undeployCustomFiles`) drop the jar.mn entry symmetrically.
+- The locale jar.mn write degrades gracefully — a missing target (non-standard fork tree) surfaces a structured step error rather than aborting apply, so a well-formed `.mjs`/`.css` is never blocked by a broken locale path.
+- FTL chrome URIs are now derived from `furnace.json.ftlBasePath` via a pair of helpers (`resolveFtlChromeSubPath`, `resolveFtlLocaleJarMnPath`) so forks that customise the FTL tree get matching `insertFTLIfNeeded` and jar.mn output.
+
+### Furnace validate
+
+- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `hominis.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
+- `no-keyboard-handler` no longer warns when `@click` sits on a native interactive element (`<button>`, `<a href>`, `<input>`, `<select>`, `<textarea>`, `<summary>`, `<details>`, or the Firefox `moz-button`/`moz-toggle`/`moz-checkbox`/`moz-radio`/`moz-menulist` widgets). Those elements dispatch `click` on Enter and Space via the platform, so a duplicate `@keydown`/`@keypress` handler would double-fire. The rule still fires for synthetic interactive markup (e.g. `<div @click>`) and for bare `<a>` without an `href` attribute, which are the real keyboard-a11y hazards.
+
+### Run / test
+
+- `fireforge run`, `fireforge watch`, `fireforge build`, and every other `mach` invocation launched with inherited stdio now forward parent `SIGINT`/`SIGTERM` to the child as `SIGTERM` and wait ~1.5 s before escalating to `SIGKILL`. A second Ctrl-C during the grace window escalates immediately (matches the usual "hit Ctrl-C twice to force-quit" UX). Previously the parent could exit before Gecko's `AsyncShutdown` / `profileBeforeChange` blockers finished flushing in-memory state, losing the last few seconds of edits. The grace window is configurable via a new `shutdownGraceMs` option on `execInherit` / `execInheritCapture`.
+- New `fireforge test --doctor` runs a short marionette handshake preflight before (optionally) invoking `mach test`. Spawns the built browser headless, opens a TCP socket to `127.0.0.1:2828`, waits for the handshake bytes, and reports PASS/FAIL with the tail of stderr on FAIL. When `--doctor` is supplied with no test paths, it exits after the preflight — a sub-minute way to tell "marionette wedged" apart from "test failed to discover" when `mach test` hangs for the full 360 s marionette timeout. When supplied with test paths, a FAIL preflight short-circuits before `mach test` runs.
+
+### Internal
+
+- Extracted `furnace-apply-ftl.ts`, `furnace-config-tokens.ts`, and `create-templates.ts` to keep apply / config / scaffolding files under the per-file LOC budget after the new features landed. `parseStringArray` is now exported from `furnace-config.ts` for cross-module reuse.
+- New `src/core/marionette-preflight.ts` owns the `--doctor` probe and its teardown semantics.
+- Test mocks for `furnace-registration.js` now cover the new `addLocaleFtlJarMnEntry` / `removeLocaleFtlJarMnEntry` exports; `config.js` mocks in apply-batch tests now cover `loadConfig` because the apply path reads `markerComment` from fireforge.json.
+
+## 0.14.0
+
+### Concurrency and atomicity
+
+- Patch body and manifest writes in `re-export`, `rebase --continue`, and the post-apply re-export loop in `rebase` are now atomic via `updatePatchAndMetadata`, so a concurrent `resolve` / `re-export` / `patch compact` / `patch reorder` cannot leave body and metadata disagreeing.
+- State writes in `import`, `resolve`, and `rebase` (abort, continue, patch loop) use transactional `updateState` so a concurrent command's unrelated keys are no longer clobbered.
+- `rebase` apply + session persist is guarded by a new `runInSignalCriticalSection` primitive in `src/core/signal-critical.ts`; SIGINT / SIGTERM between apply and persist (5 s ceiling) no longer leaves an applied patch marked pending, so `--continue` does not re-apply it.
+
+### Rebase
+
+- Per-patch re-export failures after apply are collected instead of silently dropped. The session stays on disk and `sourceEsrVersion` is not stamped until every re-export succeeds, so `--continue` can retry after the root cause is fixed.
+- `rebase --continue` retries the post-apply pipeline when the apply loop has already finished; the prior "session may be corrupt" rejection no longer blocks resumption.
+- `rebase --abort` splits into four sequenced steps (git reset, furnace state clear, `pendingResolution` clear, session clear) so failures get correctly-labelled errors and the session stays on disk for retry.
+
+### Download
+
+- `download` restores patch-touched files to baseline after the initial commit (or a resumed partial init), so extraction artefacts and line-ending normalisation no longer force `fireforge import --force` on a clean install. Pre-existing uncommitted edits are preserved and warned about.
+- `cleanPatchTouchedFiles` runs before stamping `state.downloadedVersion`, preserving the invariant that the stamped version matches a clean engine.
+- Resume preserves the original error cause (timeout, permission denied, corrupted git object, disk full) instead of discarding it behind a generic `PartialEngineExistsError`. Unexpected errors during the partial-engine probe are also wrapped rather than re-thrown bare.
+
+### Import
+
+- Classification no longer swallows structural errors as "unmanaged dirty file". Only pure-IO errors (`ENOENT`, `EACCES`, `EPERM`, `EISDIR`, `EBUSY`) fall through; `PatchError`, manifest corruption, and patch-parse failures re-throw with the original diagnostic.
+- Patch integrity issues prompt in interactive mode and error in non-interactive mode instead of warn-and-continue; `--force` still bypasses with an explicit warning.
+
+### Furnace
+
+- `furnace apply --watch` picks up newly-created component directories dynamically, remembers edits that arrive during an in-flight apply (a second cycle runs automatically), and classifies errors errno-aware (`EACCES`, `ENOSPC`, `EBUSY`, `ENOENT`, `ETIMEDOUT`) instead of collapsing into a generic "Apply failed".
+- `furnace override` rejects collisions with `config.stock` and `config.custom` in both single and batch paths, and wraps snapshot + copy pairs in per-file error context so a mid-copy failure names the failing file.
+- `furnace remove` requires a git engine for custom components (not just overrides) and hoists the precondition outside the lock and journal registration. A summary line surfaces when test-file cleanup fails partway.
+- `furnace rename` does prefix-only filename replacement; the prior substring replacement mangled names when `oldName` appeared more than once. Content regexes now escape every metacharacter.
+- `furnace deploy` asserts `applied[0].name` matches the requested component before persisting state; state-mismatch errors recommend `fireforge doctor --repair-furnace`.
+- `furnace validate --fix` reports the actual delta from re-validation instead of inflating the count on no-op fixes.
+- `furnace list -v` tolerates missing or unreadable component directories, rendering `unavailable` instead of terminating the listing.
+- `furnace diff` surfaces `--reset-base` recovery in the primary error rather than a secondary catch block.
+- `furnace init --ftl-base-path` traversal check uses path normalisation instead of substring match, rejecting absolute paths, null bytes, and `..` segments. Interactive detection checks both `stdin.isTTY` and `stdout.isTTY` to match every other interactive command.
+
+### Other commands
+
+- `setup` rejects project names whose sanitised slug is empty (emoji-only, pure punctuation, `---`). `validateConfig` similarly rejects empty `name`, `vendor`, `appId`, `binaryName`.
+- `config --force` no longer bypasses structural validation for known keys in `SUPPORTED_CONFIG_PATHS`; the flag is only an escape hatch for unknown keys.
+- `watch` probes `watchman --version` with a 5 s timeout before starting, and runs the furnace staleness check previously only in `run`. Both commands share a new `warnIfFurnaceStale` helper in `src/core/furnace-staleness.ts`.
+- `test` path normalisation is case-insensitive, accepts `\` as well as `/`, and trims whitespace, so `Engine/foo/bar` on macOS / Windows no longer reaches `mach` with the prefix intact.
+- `status` caps untracked-directory expansion at 5 000 files per directory (configurable via `FIREFORGE_MAX_UNTRACKED_FILES`) and renders a top-of-output banner when directories were truncated, so large outputs don't hide the warning in scrollback.
+- `export` empty-diff error distinguishes the `--skip-lint` case; `export-shared` always announces when `--skip-lint` is active.
+- `wire <name>` and `register --after <entry>` validate their inputs against strict regexes, rejecting path separators, parent-dir segments, control characters, and line terminators before any filesystem operation.
+- `token add --mode` uses Commander's `.choices()` so invalid modes fail with the built-in message and `--help` lists the valid options.
+- `run` whitelisted exit codes (0, 130 SIGINT, 143 SIGTERM) are documented inline; SIGKILL (137) and other abnormal signal codes surface as build errors.
+- `discard` wraps error causes via `toError` so thrown strings or numbers propagate as real Errors with stack traces.
+
+### Internal
+
+- New unit tests for `validateCheckDependencies` in `src/commands/doctor.ts` assert the forward-only dependency invariant so a regression cannot slip in when reordering checks.
+
 ## 0.13.0
 
 ### Setup

package/README.md

@@ -368,10 +368,29 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
   "patchLint": {
     "checkJs": true,
     "rawColorAllowlist": ["hominis-tokens.css"]
-  }
+  },
+  "markerComment": "MYBROWSER"
 }
 ```
 
+**`markerComment`** (optional). Appended as a `  // <marker>:` suffix to every line FireForge writes into upstream Firefox source files (starting with `customElements.js`). Keeps fork modifications discoverable and makes re-apply idempotent without hand-tagging entries after each `furnace apply`. Reject list: empty strings, leading/trailing whitespace, newlines, `*/` (would close an enclosing block comment), control characters.
+
+**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `hominis.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted.
+
+### `furnace create --localized` for `MozLitElement`
+
+`fireforge furnace create <tag> --localized` scaffolds a Fluent-ready component. The generated `.mjs` uses the Mozilla-idiomatic `MozLitElement` pattern: a module-level `window.MozXULElement?.insertFTLIfNeeded("<chrome-uri>")` plus `this.ownerDocument.l10n?.connectRoot(this.shadowRoot)` / `disconnectRoot` in `connectedCallback` / `disconnectedCallback`. The chrome URI derives from `furnace.json.ftlBasePath` (default `toolkit/locales/en-US/toolkit/global` → `toolkit/global/<tag>.ftl`). `furnace apply` registers the `.ftl` in the matching locale jar.mn (default `toolkit/locales/jar.mn`) so the chrome URI resolves at runtime. If the locale jar.mn is missing in your fork (non-standard tree), apply surfaces a structured step error instead of aborting — the `.mjs`/`.css` still ship.
+
+### `fireforge test --doctor`
+
+```bash
+# Sub-minute marionette handshake probe; bails out of mach test on FAIL
+fireforge test --doctor
+fireforge test --doctor browser/base/content/test/foo/browser_bar.js
+```
+
+Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
+
 ## Roadmap
 
 Planned but not yet implemented:

package/dist/bin/fireforge.js

@@ -10,7 +10,15 @@
  */
 import { installBrokenPipeHandler, main } from '../src/cli.js';
 import { isSignalRollbackInFlight, rollbackActiveOperationsForSignal, } from '../src/core/furnace-operation.js';
+import { waitForActiveCriticalSections } from '../src/core/signal-critical.js';
 import { CommandError } from '../src/errors/base.js';
+/**
+ * Upper bound (ms) the signal handler will wait for any in-flight critical
+ * section (e.g. rebase apply + session persist) to finish before calling
+ * process.exit. Keep short so a stuck I/O operation cannot indefinitely
+ * postpone the exit a user requested with Ctrl+C.
+ */
+const SIGNAL_CRITICAL_SECTION_TIMEOUT_MS = 5_000;
 installBrokenPipeHandler();
 process.on('unhandledRejection', (reason) => {
     console.error('Fatal error (unhandled rejection):', reason instanceof Error ? reason.message : reason);
@@ -33,11 +41,17 @@ function installFurnaceSignalHandler(signal, exitCode) {
             // rather than queueing another rollback that will race the first.
             process.exit(exitCode);
         }
-        rollbackActiveOperationsForSignal(signal)
-            .catch((error) => {
-            console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
-        })
-            .finally(() => {
+        // Run furnace rollback and signal-critical-section drain in parallel.
+        // Rebase-style operations register critical sections (apply + session
+        // persist) via `runInSignalCriticalSection`; awaiting them here ensures
+        // the CLI never exits with a patch applied to the engine but a stale
+        // session file that would mis-track progress on `--continue`.
+        void Promise.allSettled([
+            rollbackActiveOperationsForSignal(signal).catch((error) => {
+                console.error(`Furnace rollback after ${signal} failed:`, error instanceof Error ? error.message : error);
+            }),
+            waitForActiveCriticalSections(SIGNAL_CRITICAL_SECTION_TIMEOUT_MS),
+        ]).finally(() => {
             process.exit(exitCode);
         });
     });

package/dist/src/commands/config.js

@@ -105,8 +105,14 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             throw new InvalidArgumentError(`Unknown config key: "${key}". Known keys: ${SUPPORTED_CONFIG_PATHS.join(', ')}. Use --force to set anyway.`);
         }
         const parsedValue = parseValue(value, key);
+        const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
         try {
-            if (options.force) {
+            // `--force` is intended as an escape hatch for *unknown* keys; it
+            // should not also let the user write a structurally invalid value
+            // for a *known* key. Apply strict validation whenever the key is
+            // listed in SUPPORTED_CONFIG_PATHS, regardless of --force, and only
+            // skip validation for genuinely unknown key paths.
+            if (options.force && !keyIsKnown) {
                 const updatedConfig = mutateConfig(config, key, parsedValue, true);
                 await writeConfigDocument(projectRoot, updatedConfig);
             }

package/dist/src/commands/discard.js

@@ -7,6 +7,7 @@ import { discardStatusEntry } from '../core/git-file-ops.js';
 import { expandUntrackedDirectoryEntries, getWorkingTreeStatus } from '../core/git-status.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { GitError } from '../errors/git.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, intro, isCancel, outro, spinner, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
@@ -79,7 +80,11 @@ export async function discardCommand(projectRoot, file, options = {}) {
         }
         throw new GitError(`Failed to discard ${file}`, statusEntry.isUntracked
             ? `rm ${statusEntry.file}`
-            : `restore --source HEAD --staged --worktree -- ${statusEntry.file}`, error instanceof Error ? error : undefined);
+            : `restore --source HEAD --staged --worktree -- ${statusEntry.file}`, 
+        // Always attach the cause via toError so thrown primitives (strings,
+        // numbers) produced by poorly-behaved utilities still propagate as
+        // an Error, preserving stack traces for verbose-mode triage.
+        toError(error));
     }
 }
 /** Registers the discard command on the CLI program. */

package/dist/src/commands/doctor.d.ts

@@ -109,6 +109,18 @@ export declare function warning(name: string, message: string, fix?: string): Do
  * Exported for sibling check modules — see {@link ok}.
  */
 export declare function failure(name: string, message: string, fix?: string): DoctorCheck;
+/**
+ * Validates that every check's `dependsOn` entries appear earlier in the
+ * registry. Called once at module load time so a broken reorder surfaces
+ * immediately as a thrown error rather than producing a subtle
+ * context-population bug at runtime.
+ *
+ * Exported so tests can exercise the forward-only invariant against
+ * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * time, but a targeted unit test makes the contract explicit and
+ * prevents regressions if the validator is ever relaxed.
+ */
+export declare function validateCheckDependencies(checks: readonly DoctorCheckDefinition[]): void;
 /**
  * Ordered list of the doctor check names, exported for tests. Pinning
  * the order here is intentional: any reorder that breaks the

package/dist/src/commands/doctor.js

@@ -135,8 +135,13 @@ async function runEngineGitChecks(ctx) {
  * registry. Called once at module load time so a broken reorder surfaces
  * immediately as a thrown error rather than producing a subtle
  * context-population bug at runtime.
+ *
+ * Exported so tests can exercise the forward-only invariant against
+ * fixtures — the real DOCTOR_CHECKS list is also validated at import
+ * time, but a targeted unit test makes the contract explicit and
+ * prevents regressions if the validator is ever relaxed.
  */
-function validateCheckDependencies(checks) {
+export function validateCheckDependencies(checks) {
     const seen = new Set();
     for (const check of checks) {
         if (check.dependsOn) {

package/dist/src/commands/download.js

@@ -4,10 +4,68 @@ import { getProjectPaths, loadConfig, updateState } from '../core/config.js';
 import { downloadFirefoxSource, formatBytes } from '../core/firefox.js';
 import { getFurnacePaths, updateFurnaceState } from '../core/furnace-config.js';
 import { getHead, initRepository, isGitRepository, isMissingHeadError, resumeRepository, } from '../core/git.js';
+import { restoreTrackedPath } from '../core/git-file-ops.js';
+import { getDirtyFiles } from '../core/git-status.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { EngineExistsError, PartialEngineExistsError } from '../errors/download.js';
+import { toError } from '../utils/errors.js';
 import { checkDiskSpace, ensureDir, pathExists, removeDir } from '../utils/fs.js';
-import { info, intro, outro, spinner, step, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, step, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
+/**
+ * Collects the set of patch-touched files from the manifest.
+ * Returns an empty set when the patches directory or manifest is absent.
+ */
+async function getPatchTouchedFiles(patchesDir) {
+    if (!(await pathExists(patchesDir)))
+        return new Set();
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest || manifest.patches.length === 0)
+        return new Set();
+    const files = new Set();
+    for (const patch of manifest.patches) {
+        for (const file of patch.filesAffected) {
+            files.add(file);
+        }
+    }
+    return files;
+}
+/**
+ * Restores patch-touched files to their committed (HEAD) state so that a
+ * subsequent `fireforge import` does not see spurious uncommitted changes.
+ *
+ * Files that were already dirty *before* the download started (tracked via
+ * `preExistingDirty`) are left untouched and warned about.
+ */
+async function cleanPatchTouchedFiles(engineDir, patchesDir, preExistingDirty) {
+    const patchFiles = await getPatchTouchedFiles(patchesDir);
+    if (patchFiles.size === 0)
+        return;
+    const dirtyFiles = await getDirtyFiles(engineDir, [...patchFiles]);
+    if (dirtyFiles.length === 0)
+        return;
+    const toClean = preExistingDirty
+        ? dirtyFiles.filter((f) => !preExistingDirty.has(f))
+        : dirtyFiles;
+    const preserved = preExistingDirty ? dirtyFiles.filter((f) => preExistingDirty.has(f)) : [];
+    for (const file of toClean) {
+        try {
+            await restoreTrackedPath(engineDir, file);
+        }
+        catch {
+            warn(`Could not restore patch-touched file: ${file}`);
+        }
+    }
+    if (toClean.length > 0) {
+        info(`Restored ${toClean.length} patch-touched file(s) to baseline state.`);
+    }
+    if (preserved.length > 0) {
+        warn(`${preserved.length} patch-touched file(s) had pre-existing changes and were left as-is:`);
+        for (const file of preserved) {
+            warn(`  ${file}`);
+        }
+    }
+}
 /**
  * Runs the download command.
  * @param projectRoot - Root directory of the project
@@ -33,6 +91,12 @@ export async function downloadCommand(projectRoot, options) {
                     if (isMissingHeadError(error)) {
                         // Partial init detected — attempt to resume instead of requiring --force
                         info('Detected partially initialized engine. Attempting to resume...');
+                        // Snapshot patch-touched files that are already dirty so we
+                        // can preserve them after the resume commit.
+                        const patchFiles = await getPatchTouchedFiles(paths.patches);
+                        const preExistingDirty = patchFiles.size > 0
+                            ? new Set(await getDirtyFiles(paths.engine, [...patchFiles]))
+                            : new Set();
                         const resumeSpinner = spinner('Resuming git repository initialization...');
                         try {
                             await resumeRepository(paths.engine, {
@@ -45,6 +109,14 @@ export async function downloadCommand(projectRoot, options) {
                             });
                             const baseCommit = await getHead(paths.engine);
                             resumeSpinner.stop('Git repository resumed successfully');
+                            // Restore patch-touched files BEFORE stamping state. If this
+                            // step fails (disk full, permission denied, git object issue),
+                            // state.json keeps the previous downloadedVersion so the
+                            // invariant "state.downloadedVersion matches a clean engine"
+                            // holds. A retry of `fireforge download` then re-enters the
+                            // resume path instead of declaring success against a dirty
+                            // engine.
+                            await cleanPatchTouchedFiles(paths.engine, paths.patches, preExistingDirty);
                             await updateState(projectRoot, {
                                 downloadedVersion: version,
                                 baseCommit,
@@ -53,14 +125,31 @@ export async function downloadCommand(projectRoot, options) {
                             return;
                         }
                         catch (error) {
-                            void error;
                             resumeSpinner.error('Resume failed');
-                            throw new PartialEngineExistsError(paths.engine);
+                            // Preserve the underlying cause so the user sees *why* the
+                            // resume failed (timeout, permission denied, corrupted object,
+                            // disk full, …) instead of only the generic "partial engine
+                            // exists" story. Verbose mode prints the stack for deeper
+                            // triage.
+                            const cause = toError(error);
+                            verbose(`Resume failure detail: ${cause.message}`);
+                            if (cause.stack) {
+                                verbose(cause.stack);
+                            }
+                            throw new PartialEngineExistsError(paths.engine, cause);
                         }
                     }
-                    // Re-throw unexpected git errors (e.g. corrupted objects) rather
-                    // than masking them behind the generic EngineExistsError below.
-                    throw error;
+                    // Re-throw unexpected git errors (corrupted objects, permission
+                    // denied, …) wrapped in PartialEngineExistsError so the user sees
+                    // both narratives: "we detected a partial engine and attempted
+                    // resume" AND the underlying git failure. Without the wrap the
+                    // raw git error loses the context that resume was in flight.
+                    const cause = toError(error);
+                    verbose(`Partial-engine probe failed with unexpected error: ${cause.message}`);
+                    if (cause.stack) {
+                        verbose(cause.stack);
+                    }
+                    throw new PartialEngineExistsError(paths.engine, cause);
                 }
             }
             throw new EngineExistsError(paths.engine);
@@ -122,7 +211,17 @@ export async function downloadCommand(projectRoot, options) {
         warn('engine/ may now contain a partially initialized git repository. Re-run "fireforge download --force" to recreate the baseline cleanly.');
         throw error;
     }
-    // Update state
+    // Restore any patch-touched files that ended up dirty after the initial
+    // commit (e.g. line-ending normalisation or extraction artefacts) so that
+    // a subsequent `fireforge import` works without --force.
+    //
+    // This runs BEFORE updateState so a restore failure keeps the previous
+    // downloadedVersion in state.json. The invariant we preserve is
+    // "state.downloadedVersion matches a clean engine": stamping the new
+    // version only after the restore succeeds means a failed clean-up will
+    // re-enter the resume path on the next `fireforge download` rather than
+    // reporting success against a dirty engine.
+    await cleanPatchTouchedFiles(paths.engine, paths.patches);
     await updateState(projectRoot, {
         downloadedVersion: version,
         baseCommit,

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

@@ -47,6 +47,13 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
         }
         info(`Lint: ${errors.length} error(s) downgraded to warnings (--skip-lint)`);
     }
+    else if (skipLint) {
+        // Always announce that --skip-lint was honoured, even when there were
+        // no errors to downgrade, so the operator can confirm the flag took
+        // effect. Without this, a clean `--skip-lint` run emitted nothing
+        // about the flag and looked identical to an unflagged run.
+        info('Lint: 0 error(s); --skip-lint is active (no effect on this run).');
+    }
     const warnCount = warnings.length + (skipLint ? errors.length : 0);
     if (warnCount > 0) {
         info(`Patch lint: ${warnCount} warning(s)`);

package/dist/src/commands/export.js

@@ -139,6 +139,11 @@ export async function exportCommand(projectRoot, files, options) {
     }
     let diff = await generatePatchDiff(paths.engine, allFiles);
     if (!diff.trim()) {
+        if (options.skipLint) {
+            throw new GeneralError('The specified paths have no diff content to export. ' +
+                '(--skip-lint is set; lint checks were bypassed but there are still no content changes — ' +
+                'the paths may have only been lint-level differences that resolved, or the working tree is already clean.)');
+        }
         throw new GeneralError('The specified paths have no diff content to export.');
     }
     // Ensure patches directory exists