@hominis/fireforge 0.44.1 → 0.44.3

package/dist/src/utils/child-env.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Environment construction for spawned children.
+ *
+ * Its own module rather than a helper inside `process.ts` only because that
+ * file sits on a 500-line budget; the logic belongs to the exec layer.
+ */
+/**
+ * The child's environment: `process.env`, with `env` merged over it, then
+ * every `envUnset` key removed.
+ *
+ * One helper rather than five inline spreads — the removal step is easy to
+ * add at four of the five spawn sites and forget at the fifth, which would
+ * make the option silently inert exactly where it was not tested.
+ *
+ * Removal is a real removal, not an assignment to `''`: mozbuild's
+ * `is_running_under_coding_agent()` reads `CLAUDECODE` for its PRESENCE, so
+ * an empty value would not unset it. `Reflect.deleteProperty` rather than
+ * `delete obj[key]` because the key is computed.
+ *
+ * @param options - Options carrying `env` / `envUnset`
+ * @returns The environment to hand `spawn`
+ */
+export function buildChildEnv(options) {
+    const merged = { ...process.env, ...options.env };
+    for (const key of options.envUnset ?? []) {
+        Reflect.deleteProperty(merged, key);
+    }
+    return merged;
+}

package/dist/src/utils/options.d.ts

@@ -66,6 +66,28 @@ export declare const WAIT_LOCK_ENV_VAR = "FIREFORGE_WAIT_LOCK";
  * ABSENCE, which is where it belongs.
  */
 export declare function resolveWaitLockSeconds(value: string | number | boolean | undefined): number | undefined;
+/**
+ * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
+ *
+ * Exists for the SECONDARY locks a command takes after the one its
+ * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
+ * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * budget, so a contended deploy died on the file lock's fixed 30 s while
+ * its operator believed a much larger budget was in force. Threading the
+ * flag reaches the three furnace commands that declare it — this reaches
+ * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
+ * `override`, `chrome-doc`, …), which have no flag to thread but are just
+ * as contended.
+ *
+ * Deliberately env-only: a flag belongs to one invocation and is passed
+ * explicitly where it applies, while the environment is exactly the place a
+ * session-wide default is expressed. An explicit budget at a call site
+ * always wins over this.
+ *
+ * @returns The session budget in milliseconds, or undefined
+ */
+export declare function sessionWaitLockMs(): number | undefined;
 /**
  * True when `command` already declares `--wait-lock` itself. Used by the
  * CLI wiring to add the accept-and-ignore variant only where the honoring
@@ -85,5 +107,11 @@ export declare function ensureWaitLockOptionEverywhere(command: Command): void;
  * for the bare flag or a validated integer; feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
+ *
+ * A command can take MORE than one lock — a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * has to reach all of them or the flag is a half-truth. The secondary locks
+ * read the session budget through {@link sessionWaitLockMs} rather than
+ * having it threaded to every call site.
  */
 export declare function addWaitLockOption(command: Command): Command;

package/dist/src/utils/options.js

@@ -144,6 +144,31 @@ export function resolveWaitLockSeconds(value) {
     }
     return parsed;
 }
+/**
+ * The session-wide wait budget in MILLISECONDS, or undefined when none is
+ * set. Sourced from {@link WAIT_LOCK_ENV_VAR} only.
+ *
+ * Exists for the SECONDARY locks a command takes after the one its
+ * `--wait-lock` flag was threaded to. A furnace mutation takes the engine
+ * session lock and then `.fireforge/furnace.lock`; only the first had a
+ * budget, so a contended deploy died on the file lock's fixed 30 s while
+ * its operator believed a much larger budget was in force. Threading the
+ * flag reaches the three furnace commands that declare it — this reaches
+ * the twelve that do not (`create`, `remove`, `rename`, `refresh`, `scan`,
+ * `override`, `chrome-doc`, …), which have no flag to thread but are just
+ * as contended.
+ *
+ * Deliberately env-only: a flag belongs to one invocation and is passed
+ * explicitly where it applies, while the environment is exactly the place a
+ * session-wide default is expressed. An explicit budget at a call site
+ * always wins over this.
+ *
+ * @returns The session budget in milliseconds, or undefined
+ */
+export function sessionWaitLockMs() {
+    const seconds = waitLockSecondsFromEnv();
+    return seconds === undefined ? undefined : seconds * 1000;
+}
 /**
  * Registers `--wait-lock [seconds]` on a command that takes NO lock, so a
  * scripted sequence can blanket-append the flag without hitting a usage
@@ -188,7 +213,13 @@ export function ensureWaitLockOptionEverywhere(command) {
  * for the bare flag or a validated integer; feed it through
  * {@link resolveWaitLockSeconds} at the call site to obtain the
  * `waitLockSeconds` for `withEngineSessionLock`/`withPatchDirectoryLock`.
+ *
+ * A command can take MORE than one lock — a furnace mutation takes the
+ * engine session lock and then `.fireforge/furnace.lock` — and the budget
+ * has to reach all of them or the flag is a half-truth. The secondary locks
+ * read the session budget through {@link sessionWaitLockMs} rather than
+ * having it threaded to every call site.
  */
 export function addWaitLockOption(command) {
-    return command.option('--wait-lock [seconds]', `Wait up to this many seconds (default 60) for another FireForge command to release the contended lock, instead of failing on the default budget. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
+    return command.option('--wait-lock [seconds]', `Wait up to this many seconds (default 60) for another FireForge command to release EVERY lock this command takes, instead of failing on the default budget. Set ${WAIT_LOCK_ENV_VAR} to apply a budget to every command in a session`, commanderArgParser((raw) => resolveWaitLockSeconds(raw)));
 }

package/dist/src/utils/process.d.ts

@@ -28,6 +28,28 @@ export interface ExecOptions {
     cwd?: string;
     /** Environment variables */
     env?: Record<string, string>;
+    /**
+     * Environment variables to REMOVE from the child's inherited environment,
+     * applied after {@link ExecOptions.env} is merged over `process.env`.
+     *
+     * Needed because `env` can only add or overwrite, and some variables are
+     * read for their PRESENCE — mozbuild's `is_running_under_coding_agent()`
+     * keys on `CLAUDECODE`, so setting it empty would not unset it. An
+     * explicit delete says what it means; relying on Node dropping
+     * `undefined`-valued env entries would be a semantics gamble at a layer
+     * that must not have any.
+     */
+    envUnset?: readonly string[];
+    /**
+     * Streams to mirror the child's output into, replacing the default
+     * `process.stdout` / `process.stderr` on the stdio-inheriting capture
+     * path. Lets a caller tee the live output somewhere else (a run log)
+     * without a second per-chunk hook.
+     */
+    mirror?: {
+        stdout?: NodeJS.WritableStream;
+        stderr?: NodeJS.WritableStream;
+    };
     /** Timeout in milliseconds */
     timeout?: number;
     /**

package/dist/src/utils/process.js

@@ -3,6 +3,7 @@ import { spawn } from 'node:child_process';
 import { constants as osConstants } from 'node:os';
 import { StringDecoder } from 'node:string_decoder';
 import { ExecTimeoutError } from '../errors/base.js';
+import { buildChildEnv } from './child-env.js';
 import { killProcessTree, sweepProcessGroup } from './process-group.js';
 // 50 MB cap per stream to prevent OOM — large toolchain builds (e.g. Firefox, Chromium)
 // can easily blow past this, so we truncate rather than let the buffer grow unbounded.
@@ -85,7 +86,7 @@ export async function exec(command, args, options = {}) {
     return new Promise((resolve, reject) => {
         const child = spawn(command, args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.env },
+            env: buildChildEnv(options),
             stdio: ['ignore', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
         });
@@ -119,7 +120,7 @@ export async function execStream(command, args, options = {}) {
         const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
         const child = spawn(command, args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.env },
+            env: buildChildEnv(options),
             stdio: ['ignore', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
             detached: usesProcessGroup,
@@ -256,7 +257,7 @@ export async function execInherit(command, args, options = {}) {
         const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
         const child = spawn(command, args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.env },
+            env: buildChildEnv(options),
             stdio: 'inherit',
             signal: buildSignalFromTimeout(options.timeout),
             detached: usesProcessGroup,
@@ -368,14 +369,14 @@ export async function execInheritCapture(command, args, options = {}) {
         const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
         const child = spawn(command, args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.env },
+            env: buildChildEnv(options),
             stdio: ['inherit', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
-        const out = createStreamCollector(process.stdout);
-        const err = createStreamCollector(process.stderr);
+        const out = createStreamCollector(options.mirror?.stdout ?? process.stdout);
+        const err = createStreamCollector(options.mirror?.stderr ?? process.stderr);
         child.stdout.on('data', out.onData);
         child.stderr.on('data', err.onData);
         const graceMs = options.shutdownGraceMs ?? 1500;
@@ -440,7 +441,7 @@ export async function execSmokeRun(command, args, options) {
         const usesProcessGroup = process.platform !== 'win32';
         const child = spawn(command, args, {
             cwd: options.cwd,
-            env: { ...process.env, ...options.env },
+            env: buildChildEnv(options),
             stdio: ['ignore', 'pipe', 'pipe'],
             // A new process group on POSIX lets us signal the whole descendant
             // tree at once, which is essential for mach → python → firefox →

package/docs/README.md

@@ -0,0 +1,35 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# FireForge documentation
+
+[`../README.md`](../README.md) is the getting-started page. These files are
+the reference material behind it. `fireforge --help` (and
+`fireforge <command> --help`) stays the authority on flags; the docs cover
+what a flag list cannot state.
+
+## Using FireForge
+
+| File                                           | Covers                                                                               |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------ |
+| [patch-workflow.md](patch-workflow.md)         | Export, re-export, deletions, queue maintenance, per-patch lint, CI gating, rebasing |
+| [testing.md](testing.md)                       | `fireforge test`: scope, modes, build freshness, the verdict line, verbosity         |
+| [furnace.md](furnace.md)                       | Components: overrides, shared CSS fragments, typed cross-module imports              |
+| [verification-trees.md](verification-trees.md) | CoW snapshots for concurrent read-mostly verification                                |
+| [configuration.md](configuration.md)           | `fireforge.json` settings, design tokens, lock waits, environment variables          |
+
+## Contracts for scripts and CI
+
+| File                                   | Covers                                                                      |
+| -------------------------------------- | --------------------------------------------------------------------------- |
+| [exit-codes.md](exit-codes.md)         | Every exit code, which error class produces it, and how CI should branch    |
+| [machine-output.md](machine-output.md) | The `--json` / `--raw` / verdict-line output contract and its versioning    |
+| [run-logs.md](run-logs.md)             | `.fireforge/logs/`: what `test` and `build` write, and what survives a pipe |
+
+## Internals
+
+| File                                               | Covers                                                                       |
+| -------------------------------------------------- | ---------------------------------------------------------------------------- |
+| [lifecycle-invariants.md](lifecycle-invariants.md) | Locking, rollback, signal handling, and the decision table for new mutations |
+
+Release history and the reasoning behind individual changes live in
+[`../CHANGELOG.md`](../CHANGELOG.md).

package/docs/configuration.md

@@ -0,0 +1,116 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Configuration
+
+`fireforge.json` at the project root is the project's configuration;
+`furnace.json` holds component configuration. This file covers the settings
+whose behaviour needs more than a schema line, plus the environment variables
+FireForge reads.
+
+## External toolchains
+
+Projects with generated asset prerequisites can declare opt-in
+`externalToolchains`. `fireforge doctor` reports missing **required** tools as
+errors and missing **optional** tools as warnings.
+
+Seasonal branding on macOS, for example, can declare Apple's Icon Composer
+tool at
+`/Applications/Xcode.app/Contents/Applications/Icon Composer.app/Contents/Executables/ictool`,
+plus `actool` via `xcrun`, `sips`, and `iconutil`.
+
+## `patchLint`
+
+Per-patch lint type-checks plain Firefox JS against a built-in Firefox-globals
+shim that tracks upstream WebIDL additions per release.
+
+- `patchLint.checkJsExtraShim` adds members to the structured shim globals via
+  TypeScript interface merging, e.g.
+  `interface ChromeUtilsShim { newApi(): any }`.
+- `patchLint.checkJsTestFiles: true` extends the pass to patch-owned test
+  `.js` files (`browser_*` / `test_*` / `xpcshell_*` and `/test/` paths). Each
+  is checked as its own small script-scope program against a loose built-in
+  harness shim.
+- `patchLint.checkJsTestShim` points at a project `.d.ts` whose typed
+  declarations (e.g. a real `TestUtils` interface) override the loose
+  baseline, so calls to nonexistent harness members fail at export time.
+
+## `patchPolicy`
+
+`patchPolicy.ranges` makes `patch compact` range-aware, so closing ordinal
+gaps does not move a patch out of the band its category owns.
+
+## `test`
+
+`test.canaryPath` and `test.canaryTimeoutSeconds` supply the defaults for
+`fireforge test --canary`. See [`testing.md`](testing.md).
+
+## Design tokens
+
+Tokens are managed with `fireforge token add`.
+
+- `--create-category` declares a new category banner and inserts the token in
+  one step. It is incompatible with `--variant`; author the category with the
+  base token first, then add each variant.
+- `--category` is required for a base declaration and optional under
+  `--variant`, where the declaration is routed into a `:root<selector>` block
+  and never into a category section. It is still validated when supplied.
+- `--variant` takes the same selector grammar the block matcher understands:
+  one attribute fragment (`[data-private]`, `[data-skin=precision]`), a run of
+  them (`[data-skin=precision][data-theme=dark]`), and an optional pseudo-class
+  tail (`[data-skin=precision]:not([data-private])`). Names and values must be
+  identifier-safe, and `=value` is normalized to `="value"`. A variant naming a
+  qualifier matches only a block carrying that qualifier; one without a
+  qualifier still matches a qualified block, and the write says so.
+- `--mode override` mirrors into both `:root[data-theme="dark"]` and
+  `:root[data-theme="light"]`. A qualified block such as
+  `:root[data-theme="light"]:not([data-private])` is matched and written
+  through, with a warning naming the selector — the qualifier is
+  semantically load-bearing, but silently skipping half the mirror is the
+  worse failure.
+- A token already present in the target block is reported with its location
+  (`already exists in :root[…] (line N), unchanged`) rather than a bare
+  no-op.
+
+## Smoke runs
+
+For unattended smoke checks, `fireforge run --smoke-exit <s> --headless`
+launches the browser headless. A headed smoke window on a shared desktop
+absorbs live input, which contaminates the console capture — headed non-CI
+launches print a warning saying so. Exit codes 12 and 13 separate a console
+regression from a launch failure; see [`exit-codes.md`](exit-codes.md).
+
+## Lock waits
+
+Every FireForge command that mutates the engine takes the engine-session lock,
+and some take a second subsystem lock as well. Contention fails fast after
+about a second by default.
+
+`--wait-lock [seconds]` (bare flag = 60, valid 1–3600) replaces that with a
+bounded wait, and the budget covers **every** lock the command takes — for
+`furnace apply`/`deploy`/`sync` that means the furnace lock as well as the
+engine-session lock. While waiting, a progress line roughly every 5 seconds
+identifies the holder by PID, command and start time.
+
+Commands that take no lock accept `--wait-lock` and ignore it, so a scripted
+sequence can blanket-append the flag without a usage error killing the run.
+
+`FIREFORGE_WAIT_LOCK=<seconds>` applies the same budget to every command in a
+session, using the same bounds as the flag. It is the only way to give a
+budget to the furnace mutators that declare no flag (`create`, `remove`,
+`rename`, `refresh`, `scan`, `override`, `chrome-doc`, …). An explicit
+`--wait-lock` always wins.
+
+`fireforge status --lock` reports the current holder and queue depth.
+
+## Environment variables
+
+| Variable                             | Effect                                                                                                                                  |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `FIREFORGE_WAIT_LOCK`                | Session-wide lock wait budget in seconds (1–3600). See above.                                                                           |
+| `FIREFORGE_MAX_UNTRACKED_FILES`      | Per-directory cap when expanding collapsed untracked directories in `status` (default 5000). A non-positive value warns and is ignored. |
+| `FIREFORGE_GIT_ADD_TIMEOUT_MS`       | Timeout for the monolithic `git add -A` baseline pass (default 10 min). For slow or loaded filesystems.                                 |
+| `FIREFORGE_GIT_ADD_CHUNK_TIMEOUT_MS` | Timeout for the chunked `git add -- <dir>` fallback (default 30 min). Paired with the above.                                            |
+
+`CLAUDECODE` is read by mozbuild, not by FireForge, and `fireforge test
+--full-output` unsets it for test dispatches only — see
+[`testing.md`](testing.md#output-verbosity).

package/docs/exit-codes.md

@@ -0,0 +1,63 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Exit codes (internal)
+
+The exit code is the machine-readable half of the CLI's contract: a script
+branches on it, and CI decides whether to retry or escalate. The values live
+in `src/errors/codes.ts`; this file is the operator-facing statement of what
+they mean and which class produces each.
+
+| Code | Name                   | Meaning                                                                                                                  | Produced by                                                    |
+| ---: | ---------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- |
+|    0 | `SUCCESS`              | Completed. Also a run that prompted and the operator declined — declining is a successful run that chose not to proceed. | —                                                              |
+|    1 | `GENERAL_ERROR`        | Unspecified failure the operator must act on.                                                                            | `GeneralError`, `ParserFallbackError`                          |
+|    2 | `CONFIG_ERROR`         | `fireforge.json` missing or invalid.                                                                                     | `ConfigError` and subclasses                                   |
+|    3 | `DOWNLOAD_ERROR`       | Could not download or extract Firefox source.                                                                            | `DownloadError` and subclasses                                 |
+|    4 | `GIT_ERROR`            | A git operation failed.                                                                                                  | `GitError` and subclasses                                      |
+|    5 | `BUILD_ERROR`          | `mach build` failed.                                                                                                     | `BuildError` and subclasses                                    |
+|    6 | `PATCH_ERROR`          | A patch failed to apply, or the patch queue could not be mutated.                                                        | `PatchError`                                                   |
+|    7 | `MISSING_DEPENDENCY`   | A required tool (python3, git, tar) was not found.                                                                       | `PythonNotFoundError`, `GitNotFoundError`, `MachNotFoundError` |
+|    8 | `INVALID_ARGUMENT`     | The flags were wrong. Usage problem, not an environment one.                                                             | `InvalidArgumentError`                                         |
+|    9 | `FURNACE_ERROR`        | A Furnace component operation failed.                                                                                    | `FurnaceError`                                                 |
+|   10 | `RESOLUTION_ERROR`     | Conflict resolution failed.                                                                                              | `ResolutionError`                                              |
+|   11 | `INTERNAL_ERROR`       | A FireForge invariant did not hold. **A bug in FireForge**, not something the operator can fix.                          | `InternalInvariantError`                                       |
+|   12 | `SMOKE_EXIT_FAILURE`   | `run --smoke-exit` saw unallowed console errors in the smoke window.                                                     | `SmokeRunError`                                                |
+|   13 | `SMOKE_LAUNCH_FAILURE` | `run --smoke-exit` saw a non-clean browser exit before the window elapsed.                                               | `SmokeRunError`                                                |
+|   14 | `INCONCLUSIVE`         | A test run's verdict was thrown away: `engine/` moved while the harness ran. **Not red** — re-run it.                    | `InconclusiveVerdictError`                                     |
+|   15 | `LOCK_TIMEOUT`         | A lock wait expired, so the run never started. Re-queue it, with a larger `--wait-lock`.                                 | `LockContentionError`                                          |
+|  130 | `USER_CANCELLED`       | The operator INTERRUPTED a prompt (Esc / Ctrl+C). 128 + SIGINT.                                                          | `CancellationError`                                            |
+
+## The three distinctions that matter for CI
+
+**Retry vs escalate.** `GENERAL_ERROR` usually means the operator must change
+something and a retry may help. `INTERNAL_ERROR` means nothing they could
+change would have helped — escalate it, do not retry.
+
+**Red vs never-ran vs thrown-away.** These are three different facts and,
+before 0.44.0, two of them shared exit 1. `BUILD_ERROR` (5) is a suite that
+FAILED. `LOCK_TIMEOUT` (15) is a run that never started, because another
+FireForge process held the lock for the whole budget — nothing about the
+request was wrong, so re-queue it. `INCONCLUSIVE` (14) is a suite whose
+result was DISCARDED, because `engine/` moved underneath it — the code may
+be perfectly green, and reporting it as red is wrong. A summary line reading
+`FAIL — exit 1` beside `FAIL — exit 5` invited treating opposites as the same
+kind of fact; the codes now separate them mechanically. The
+`FIREFORGE-VERDICT:` line's `reason=` key carries the same distinction for
+humans.
+
+Note that `LockContentionError` backs every lock in FireForge — engine
+session, patch directory, build, furnace — so all four now exit 15. That is
+deliberate: the fact is the same whichever lock was contended.
+
+**Interrupted vs declined.** Before 0.44.0 both a Ctrl+C and a deliberate
+"no" at a confirmation returned the same value and exited 0, so a script
+could not tell them apart. They are now distinct: an interrupt raises
+`CancellationError` and exits **130**; a declined confirmation returns
+normally and exits **0**, because the run did what it was asked and the
+answer was no.
+
+## Adding a code
+
+New codes go in `src/errors/codes.ts` with a comment saying what a consumer
+should DO differently on seeing it — if the answer is "nothing different from
+an existing code", it does not need one. Add a row here in the same change.

package/docs/furnace.md

@@ -0,0 +1,57 @@
+<!-- SPDX-License-Identifier: EUPL-1.2 -->
+
+# Furnace components
+
+Furnace is FireForge's answer to UI components. It tracks stock widgets,
+creates new fork-owned widgets, and overrides existing ones. The files still
+land inside the Firefox source directory and end up as part of the regular
+patches to export.
+
+```bash
+npx fireforge furnace scan
+npx fireforge furnace override moz-button -t css-only
+npx fireforge furnace create moz-my-widget
+npx fireforge furnace deploy
+npx fireforge furnace status
+npx fireforge furnace preview
+```
+
+`fireforge furnace --help` lists every subcommand.
+
+## Shared CSS fragments
+
+Cross-widget CSS can be single-sourced. Place the fragment in
+`components/shared/` and reference it from a widget stylesheet with a
+comment:
+
+```css
+/* @fireforge-include base-button.css */
+```
+
+`deploy` expands it into the deployed copy only, so editing the fragment
+surfaces as component drift until the next deploy.
+
+## Typed cross-module imports
+
+For multi-file components, set `furnace.json#typecheckJsconfig` to a
+consumer-owned jsconfig. `deploy` then maintains `compilerOptions.paths`
+entries mapping each deployed
+`chrome://global/content/elements/<file>.mjs` URL to its workspace source.
+
+Entries are recognized as Furnace-managed by containment in the components
+workspace, so a hand-written entry is preserved and a managed entry whose
+helper was deleted is pruned.
+
+## Safety
+
+Every furnace mutation runs through `runFurnaceMutation`: a per-root lock, a
+rollback journal restored on both a signal and a thrown error, and a
+`pendingRepair` marker that blocks further mutations when a rollback was
+incomplete — cleared with `fireforge doctor --repair-furnace`. The full
+contract, including which commands take which locks, is in
+[`lifecycle-invariants.md`](lifecycle-invariants.md).
+
+`apply`, `deploy` and `sync` accept `--wait-lock [seconds]`, whose budget
+covers **both** locks they take. The twelve mutators without the flag pick up
+a session budget from `FIREFORGE_WAIT_LOCK`; see
+[`configuration.md`](configuration.md#lock-waits).