@hominis/fireforge 0.13.2 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,59 @@
 # Changelog
 
+## 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/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

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

@@ -39,59 +39,157 @@ function checksumMapsEqual(a, b) {
     }
     return true;
 }
+/**
+ * Builds a watch-loop apply-failure message tailored to the error class so
+ * transient filesystem errors (EACCES, ENOSPC, lock timeout) look different
+ * from genuine apply-level failures; the previous generic "Apply failed: ..."
+ * collapsed all causes into one string and made diagnosis difficult.
+ */
+function classifyWatchApplyError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof FurnaceError) {
+        return `Apply failed: ${message}`;
+    }
+    const code = err instanceof Error ? err.code : undefined;
+    switch (code) {
+        case 'EACCES':
+        case 'EPERM':
+            return `Apply failed: permission denied — ${message}`;
+        case 'ENOSPC':
+            return `Apply failed: disk full — ${message}`;
+        case 'EBUSY':
+        case 'ETXTBSY':
+            return `Apply failed: file is in use — ${message}`;
+        case 'ENOENT':
+            return `Apply failed: missing file — ${message}`;
+        case 'ETIMEDOUT':
+            return `Apply failed: operation timed out — ${message}`;
+        default:
+            return `Apply failed: ${message}`;
+    }
+}
 async function runWatchLoop(projectRoot) {
     const furnacePaths = getFurnacePaths(projectRoot);
+    // Both categories are eligible targets. The set is fixed; only existence
+    // varies over time — a component dir created AFTER watch started (e.g.
+    // the user runs `furnace create` in another terminal) must be picked up
+    // without restarting watch. The prior one-shot `pathExists` check at
+    // startup captured only the dirs that existed then, leaving any later
+    // creation invisible.
+    const candidateDirs = [furnacePaths.overridesDir, furnacePaths.customDir];
     const watchDirs = [];
-    if (await pathExists(furnacePaths.overridesDir))
-        watchDirs.push(furnacePaths.overridesDir);
-    if (await pathExists(furnacePaths.customDir))
-        watchDirs.push(furnacePaths.customDir);
-    if (watchDirs.length === 0) {
-        info('No component directories to watch.');
-        return;
-    }
+    const watchers = new Map();
     if (process.platform === 'linux') {
         warn('Watch mode uses fs.watch with recursive: true, which may miss changes ' +
             'in deeply nested directories on Linux. A periodic poll runs every 30s as a fallback.');
     }
-    info(`Watching ${watchDirs.length} directory(ies) for changes... (Ctrl+C to stop)`);
     let debounceTimer = null;
     let applyInFlight = false;
-    let lastChecksums = await snapshotWatchedChecksums(watchDirs);
+    // Coalesces changes that arrive while an apply is running. Without this
+    // flag, a second edit during an in-flight apply is debounced, the timer
+    // fires while applyInFlight is true, and the change is dropped entirely
+    // because the post-apply checksum snapshot already reflects the edit so
+    // the 30s poll also sees no diff.
+    let pendingChange = false;
+    let lastChecksums = new Map();
+    let pollTimer = null;
+    const runApplyCycle = async () => {
+        applyInFlight = true;
+        try {
+            info('\nChange detected — re-applying...');
+            const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
+            logApplyResult(result, false);
+            const applied = result.applied.length;
+            const skipped = result.skipped.length;
+            info(`Re-applied: ${applied} applied, ${skipped} skipped`);
+        }
+        catch (err) {
+            warn(classifyWatchApplyError(err));
+        }
+        finally {
+            applyInFlight = false;
+            // Update checksums after apply so the next poll does not re-trigger
+            // for changes that are already reflected in the engine.
+            lastChecksums = await snapshotWatchedChecksums(watchDirs);
+        }
+        // Another change arrived while we were applying — run again so the edit
+        // is not silently absorbed into the post-apply checksum bump.
+        if (pendingChange) {
+            pendingChange = false;
+            await runApplyCycle();
+        }
+    };
     const triggerApply = () => {
+        if (applyInFlight) {
+            // An apply is already running; record the change so runApplyCycle
+            // re-runs after it completes. Do not schedule a new debounce: the
+            // in-flight apply will observe this flag when it finishes.
+            pendingChange = true;
+            return;
+        }
         if (debounceTimer)
             clearTimeout(debounceTimer);
         debounceTimer = setTimeout(() => {
-            if (applyInFlight)
+            debounceTimer = null;
+            if (applyInFlight) {
+                // Race with a change that started its own apply between the debounce
+                // scheduling and the timer firing. Record the pending change; the
+                // in-flight apply will pick it up.
+                pendingChange = true;
                 return;
-            applyInFlight = true;
-            void (async () => {
-                try {
-                    info('\nChange detected — re-applying...');
-                    const result = await runFurnaceMutation(projectRoot, 'apply-rollback', (ctx) => applyAllComponents(projectRoot, false, { operationContext: ctx }));
-                    logApplyResult(result, false);
-                    const applied = result.applied.length;
-                    const skipped = result.skipped.length;
-                    info(`Re-applied: ${applied} applied, ${skipped} skipped`);
-                }
-                catch (err) {
-                    warn(`Apply failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            void runApplyCycle();
+        }, 300);
+    };
+    const installWatcher = (dir) => {
+        if (watchers.has(dir))
+            return false;
+        try {
+            const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
+                if (!filename)
+                    return;
+                if (isComponentSourceFile(filename)) {
+                    triggerApply();
                 }
-                finally {
-                    applyInFlight = false;
-                    // Update checksums after apply so the next poll does not re-trigger.
-                    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+            });
+            watcher.on('error', (err) => {
+                warn(`Watcher error on ${dir}: ${err.message}. Periodic poll will continue as fallback.`);
+            });
+            watchers.set(dir, watcher);
+            watchDirs.push(dir);
+            return true;
+        }
+        catch (err) {
+            // Directory vanished between the pathExists check and fs.watch, or
+            // fs.watch otherwise refused. refreshWatchers will retry on the next
+            // poll tick.
+            warn(`Could not start watcher on ${dir}: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    };
+    // Scans candidate dirs for ones we are not yet watching and installs a
+    // watcher for each that now exists. Returns true when at least one new
+    // watcher was installed so the caller can trigger an apply cycle for
+    // the just-noticed content.
+    const refreshWatchers = async () => {
+        let added = false;
+        for (const dir of candidateDirs) {
+            if (watchers.has(dir))
+                continue;
+            if (await pathExists(dir)) {
+                if (installWatcher(dir)) {
+                    info(`Now watching ${dir}`);
+                    added = true;
                 }
-            })();
-        }, 300);
+            }
+        }
+        return added;
     };
     // Register signal-driven cleanup BEFORE creating watchers so there is no
     // race window where a SIGINT could arrive after watchers exist but before
     // cleanup handlers are registered.
-    const watchers = [];
-    let pollTimer = null;
     const cleanup = () => {
-        for (const w of watchers)
+        for (const w of watchers.values())
             w.close();
         if (debounceTimer)
             clearTimeout(debounceTimer);
@@ -100,26 +198,28 @@ async function runWatchLoop(projectRoot) {
     };
     process.once('SIGINT', cleanup);
     process.once('SIGTERM', cleanup);
-    for (const dir of watchDirs) {
-        const watcher = fsWatch(dir, { recursive: true }, (_event, filename) => {
-            if (!filename)
-                return;
-            if (isComponentSourceFile(filename)) {
-                triggerApply();
-            }
-        });
-        watcher.on('error', (err) => {
-            warn(`Watcher error on ${dir}: ${err.message}. Periodic poll will continue as fallback.`);
-        });
-        watchers.push(watcher);
-    }
-    // Periodic checksum-based poll to catch events missed by fs.watch (known
-    // issue on Linux with recursive: true and certain filesystems).
+    await refreshWatchers();
+    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+    if (watchDirs.length === 0) {
+        info('No component directories exist yet — will retry every 30s. Create one with "fireforge furnace override" or "fireforge furnace create" in another terminal to begin watching.');
+    }
+    else {
+        info(`Watching ${watchDirs.length} directory(ies) for changes... (Ctrl+C to stop)`);
+    }
+    // Periodic checksum-based poll that also picks up newly-created component
+    // dirs (fs.watch was not installed for them at startup because they did
+    // not yet exist).
     pollTimer = setInterval(() => {
         if (applyInFlight)
             return;
         void (async () => {
             try {
+                const added = await refreshWatchers();
+                if (added) {
+                    lastChecksums = await snapshotWatchedChecksums(watchDirs);
+                    triggerApply();
+                    return;
+                }
                 const current = await snapshotWatchedChecksums(watchDirs);
                 if (!checksumMapsEqual(current, lastChecksums)) {
                     triggerApply();

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

@@ -134,7 +134,11 @@ async function scaffoldTestFiles(componentName, license, forgeConfig, paths, jou
     // browser.toml — create if missing, append entry if existing
     const tomlPath = join(testDir, 'browser.toml');
     if (await pathExists(tomlPath)) {
-        // Append the new test entry if not already present
+        // Defensive guard: only append if the entry is not already present.
+        // With a fresh journal per create, the same test file name cannot be
+        // appended twice in a single run — but retaining the check protects
+        // against accidental re-entrance or a future refactor that reuses the
+        // helper with a stale test directory.
         const existingToml = await readText(tomlPath);
         if (!existingToml.includes(`["${testFileName}"]`)) {
             if (journal)
@@ -284,14 +288,21 @@ async function writeComponentFiles(componentDir, componentName, className, descr
  * state.
  */
 async function performCreateMutations(args) {
+    // Invariant: the journal MUST be registered with the operation context
+    // BEFORE any filesystem mutation (including recordCreatedDir, whose entries
+    // are consulted by SIGINT rollback). The try/catch below assumes signal
+    // handlers can find the journal for any partial write that follows.
     const journal = createRollbackJournal();
     if (args.operationContext) {
         args.operationContext.registerJournal(journal);
     }
-    recordCreatedDir(journal, args.componentDir);
     const testFiles = [];
     let files;
     try {
+        // Record the componentDir creation entry immediately after registration
+        // so signal-driven rollback can clean it up even if writeComponentFiles
+        // is interrupted mid-ensureDir.
+        recordCreatedDir(journal, args.componentDir);
         files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, journal);
         const customEntry = {
             description: args.description,