@hominis/fireforge 0.52.0 → 0.54.0

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

@@ -1,12 +1,11 @@
 /**
  * The single awaitable delay used across FireForge.
  *
- * Five modules had grown a private copy of this (`sleep`, `delay`,
- * `sweepDelay`) and four more sites inlined
- * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
- * the one property that actually matters (whether the pending timer holds
- * the event loop open) and the disagreement was invisible at each call site.
- * Both behaviours now live here, and callers state which one they need.
+ * Callers use this rather than a private `sleep`/`delay` or an inline
+ * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
+ * disagree on the one property that actually matters (whether the pending
+ * timer holds the event loop open) and the disagreement is invisible at each
+ * call site. Both behaviours live here, and callers state which one they need.
  *
  * The default is a ref'd timer, because the dangerous mistake is the other
  * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node

package/dist/src/utils/sleep.js

@@ -2,12 +2,11 @@
 /**
  * The single awaitable delay used across FireForge.
  *
- * Five modules had grown a private copy of this (`sleep`, `delay`,
- * `sweepDelay`) and four more sites inlined
- * `new Promise((resolve) => setTimeout(resolve, ms))`. The copies disagreed on
- * the one property that actually matters (whether the pending timer holds
- * the event loop open) and the disagreement was invisible at each call site.
- * Both behaviours now live here, and callers state which one they need.
+ * Callers use this rather than a private `sleep`/`delay` or an inline
+ * `new Promise((resolve) => setTimeout(resolve, ms))`, because such copies
+ * disagree on the one property that actually matters (whether the pending
+ * timer holds the event loop open) and the disagreement is invisible at each
+ * call site. Both behaviours live here, and callers state which one they need.
  *
  * The default is a ref'd timer, because the dangerous mistake is the other
  * one: an unref'd delay awaited between a SIGTERM and its escalation lets Node

package/dist/src/utils/validation.js

@@ -20,8 +20,8 @@ export function isString(value) {
  */
 export function isNumber(value) {
     // Number.isFinite matches the documented contract: NaN and ±Infinity are
-    // excluded (a JSON config field of 1e999 parses to Infinity and used to
-    // validate as a legal number).
+    // excluded (a JSON config field of 1e999 parses to Infinity, which must
+    // not validate as a legal number).
     return typeof value === 'number' && Number.isFinite(value);
 }
 /**

package/docs/configuration.md

@@ -21,11 +21,10 @@ uncommitted pin, and the tree is then building a different version than the
 config claims.
 
 `fireforge source set`, `fireforge config <key> <value>` and `furnace init`
-edit `fireforge.json` in place (since 0.50.0). Only the values that change
+edit `fireforge.json` in place. Only the values that change
 are rewritten. Indentation, key order, and objects or arrays kept on one
 line stay as they are, so a pin move is a diff of the `firefox` block alone.
-New keys follow the layout of the object they land in. Before 0.50.0 every
-write re-serialized the whole file and expanded every compact section.
+New keys follow the layout of the object they land in.
 
 `fireforge doctor`'s "Source pin matches engine" check compares the pin with
 the engine's committed `browser/config/version.txt`. That file never carries
@@ -93,7 +92,7 @@ Most globals in it are `any`. `Cu` is typed as `CuShim`, the members of
 `nsIXPCComponents_Utils` (`js/xpconnect/idl/xpccomponents.idl`) with loose
 parameter and result types, so a call to a member `Cu` does not have (such
 as `Cu.now()`, which is `ChromeUtils.now()`) fails `typecheck` and per-patch
-lint instead of throwing at runtime (since 0.50.0). The same shim backs
+lint instead of throwing at runtime. The same shim backs
 `fireforge typecheck`.
 
 - `patchLint.checkJsExtraShim` adds members to the structured shim globals
@@ -137,7 +136,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   structured `stagedDeclarations`, so a `lint --per-patch --report` file
   can be applied with one `patch staged-dependency <patch> --add --from
 <report>` per patch instead of one call per edge. The setting is opt-in because a queue
-  that predates it can carry many such edges, and a new error would red a
+  that was never checked for these carriers can carry many such edges, and a new error would red a
   `--max-warnings 0` gate on install. The same census is on the public API as
   `findForwardRegistrations(patchesDir, { scope })`, which defaults to
   `'extended'`, for a consumer that keeps its own ratchet over these edges.
@@ -168,7 +167,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   what `file-too-large` counts. `'raw'` counts every line, the way `wc -l`
   does. `'code'` blanks comments with acorn's tokenizer (module first, then
   script, since chrome subscripts are scripts) and counts the lines left
-  non-blank, so JSDoc and blank lines stop counting. A file acorn cannot
+  non-blank, so JSDoc and blank lines do not count. A file acorn cannot
   tokenize is counted in raw lines, the upper bound, and a
   `file-size-unparsed` notice names it. Every message says which unit it
   counted ("lines" or "code lines"). The counter is on the public API as
@@ -260,7 +259,7 @@ lint instead of throwing at runtime (since 0.50.0). The same shim backs
   `@font-feature-values`, `@font-palette-values`, `@page` and its margin
   boxes) are descriptors, not properties, and are not judged.
 
-  Since 0.51.0 a scale also takes:
+  A scale also takes:
 
   - `prefix` as a list (`["--mybrowser-space-", "--mybrowser-gap-"]`) for a
     scale whose steps are spelled more than one way.
@@ -297,9 +296,9 @@ FireForge version. Diagnostics always use a fresh project
 program: prior incremental diagnostic state is never restored. Cached and
 `--no-cache` runs therefore check the same complete file set. `--no-cache`
 also disables build-info writes. A jsconfig's own `incremental` and
-`tsBuildInfoFile` remain ignored.
+`tsBuildInfoFile` are ignored.
 
-`typecheck.litTypes: true` (since 0.51.0, default off) types Lit in the
+`typecheck.litTypes: true` (default off) types Lit in the
 shim: `LitElement` and the helpers of
 `chrome://global/content/vendor/lit.all.mjs`, and `MozLitElement` of
 `chrome://global/content/lit-utils.mjs`. The element classes carry closed
@@ -307,7 +306,7 @@ member lists, as `Cu` does, so a misspelt member of a widget host is an
 error rather than `any`. Template helpers and directives stay loose. It is
 off by default because a reactive property declared only in
 `static properties` or `static queries` then needs a declaration to be
-known. Since 0.52.0 the shim declares the global type
+known. The shim declares the global type
 `MozLitElementWith<Extra>`: a widget casts its base to it, and its
 instances carry `Extra` beside MozLitElement's members. A query getter
 cannot be declared any other way: a class field redefines the getter
@@ -327,7 +326,7 @@ checks in both. A project shim can add members by merging
 `interface LitElementShimMembers`; a jsconfig `paths` entry that maps these
 URLs to real sources takes precedence.
 
-Per-patch checkJs gives each test script its own program. Since 0.51.0 a
+Per-patch checkJs gives each test script its own program. A
 test's `resource:///` and `chrome://` imports (including a
 `typeof import("…")` cast) resolve to the modules the queue creates up to
 the test's own patch, so a test of an earlier patch's module is checked
@@ -441,11 +440,11 @@ carries `invocationId` (shared by every record one command writes), `pid`,
 `ppid`, and `sessionId` when the environment sets `FIREFORGE_SESSION_ID`, so
 a session sharing the checkout can select its own lines.
 
-Before 0.50.0 the log was `patches/.fireforge-history.jsonl`, inside the
-tracked queue. The first append after upgrading moves it to `history.path`;
-when both files exist, the old records are appended to the new file rather
-than either being overwritten. Setting `history.path` to
-`patches/.fireforge-history.jsonl` keeps the old location.
+If a log exists at `patches/.fireforge-history.jsonl`, inside the tracked
+queue, the next append moves it to `history.path`; when both files exist, its
+records are appended to the `history.path` file rather than either being
+overwritten. Setting `history.path` to `patches/.fireforge-history.jsonl`
+keeps the log at that location.
 
 ## `buildAudit`
 
@@ -611,7 +610,7 @@ The dark and variant blocks mirror it and appear in `token show`.
 - `token-undeclared`: a `var(--<prefix>…)` in the tokens CSS, or in any CSS
   file a patch in the queue touches, names a token no block of the tokens
   CSS declares. A property declared in the same file, and the `furnace.json`
-  `tokenAllowlist` and `runtimeVariables` names, are exempt. Since 0.51.0 a
+  `tokenAllowlist` and `runtimeVariables` names, are exempt. A
   reference with a fallback (`var(--x, 0)`) is optional and not reported,
   and a token a sibling sheet declares counts as declared. Sheets are
   siblings when one queue document links both (`<link rel="stylesheet">`,
@@ -633,7 +632,7 @@ 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).
 
-A smoke run starts on a fresh temporary profile by default (since 0.48.0).
+A smoke run starts on a fresh temporary profile by default.
 The step exists to prove what the build does on a clean start. The
 developer's `obj-*/tmp/profile-default` carries whatever the last session
 left (a pre-reset database, a restored hand-made applet), and those reds
@@ -649,7 +648,7 @@ owning process is gone.
 
 - `--profile <path>` launches with a named profile directory and leaves it
   in place. Under `--smoke-exit` it replaces the fresh default. Firefox also
-  gets `-purgecaches` (since 0.50.0), which discards the profile's startup
+  gets `-purgecaches`, which discards the profile's startup
   cache of compiled chrome scripts. That cache is keyed on the build id, and
   a `build --ui` does not change it, so without the purge a kept profile runs
   the chrome scripts an earlier build cached. `--no-purge-caches` keeps the
@@ -657,14 +656,20 @@ owning process is gone.
   every run, and a temporary profile starts without one.
 - `--temp-profile` gives a plain `run` the same fresh, removed-afterwards
   profile.
+- Arguments after `--` go to the browser, after the profile ones. A headed
+  session on a kept profile that a chrome-context Marionette client drives
+  is `fireforge run --profile <dir> -- -marionette -remote-allow-system-access`,
+  with `marionette.port` set in the profile's `user.js` so peers' harnesses
+  keep 2828. The objdir app launched directly gets neither `-purgecaches`
+  nor the startup-cache cleanup, so it can serve a widget script an earlier
+  launch cached.
 
 A smoke run whose browser exits with a clean status before the window
-elapses, without printing any console output, fails with exit 13 (since
-0.50.0). Lines from mach's own log (the timestamped command echo) do not
+elapses, without printing any console output, fails with exit 13.
+Lines from mach's own log (the timestamped command echo) do not
 count as output. A launch that exits silently never reached a window: a
 stale `.parentlock`, or a profile whose run of SIGTERM-ended smoke runs
-counts as a startup-crash streak (`toolkit.startup.recent_crashes`). Before
-0.50.0 such a run passed as a clean exit.
+counts as a startup-crash streak (`toolkit.startup.recent_crashes`).
 
 A plain `run` without either flag keeps mach's `profile-default`. `mach run`'s
 desktop parser has no `--profile` option (its `--profile/-P` belongs to the

package/docs/exit-codes.md

@@ -29,8 +29,7 @@ which error class produces each one.
 
 Usage errors that commander detects itself (an unknown command, an unknown
 or malformed option, a missing required argument) never reach a command
-action. Before 0.46.0 commander terminated the process with its own exit 1
-and printed no refusal envelope under `--json`. `createProgram` now installs
+action. `createProgram` installs
 commander's `exitOverride()`, and the entry point maps the resulting
 `CommanderError` to `INVALID_ARGUMENT` (8) with the standard envelope on
 stdout. `--help` and `--version` take the same path and still exit 0, and so
@@ -46,10 +45,10 @@ action.
 change something, and a retry may then help. `INTERNAL_ERROR` means nothing
 they could change would have helped. Escalate it, do not retry.
 
-**Red, never ran, or thrown away.** These are three different facts, and
-before 0.44.0 two of them shared exit 1.
+**Red, never ran, or thrown away.** These are three different facts, each
+with its own code.
 
-- `BUILD_ERROR` (5) is a suite that failed. Since 0.45.0 it is thrown as
+- `BUILD_ERROR` (5) is a suite that failed. It is thrown as
   `TestFailureError`, which keeps the code but carries test remedies rather
   than build ones (`--json` reports it as `test-failure`).
 - `LOCK_TIMEOUT` (15) is a run that never started, because another FireForge
@@ -59,18 +58,16 @@ before 0.44.0 two of them shared exit 1.
   `engine/` moved underneath it. The code may be perfectly green, so
   reporting it as red is wrong.
 
-A summary line reading `FAIL - exit 1` beside `FAIL - exit 5` invited
-treating opposite facts as the same kind of thing. The codes now separate
-them. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
+Separate codes keep a summary line from showing opposite facts as the same
+kind of failure, such as `FAIL - exit 1` beside `FAIL - exit 5`. The `FIREFORGE-VERDICT:` line's `reason=` key carries the same
 distinction for humans.
 
 `LockContentionError` backs every lock in FireForge (engine session, patch
 directory, build, furnace), so all four exit 15. That is intentional: the
 fact is the same whichever lock was contended.
 
-**Interrupted or declined.** Before 0.44.0 a Ctrl+C and a deliberate "no" at
-a confirmation both returned the same value and exited 0, so a script could
-not tell them apart. They are now distinct: an interrupt raises
+**Interrupted or declined.** A Ctrl+C and a deliberate "no" at a
+confirmation are distinct, so a script can tell them apart: an interrupt raises
 `CancellationError` and exits 130, and a declined confirmation returns
 normally and exits 0, because the run did what it was asked and the answer
 was no.

package/docs/furnace.md

@@ -115,7 +115,7 @@ warning asking for the entry to be deleted. A run over one component judges
 only that component's entries. `deploy` honours the same entries when it
 validates, but leaves the staleness report to `validate`.
 
-An entry never suppresses an error (since 0.51.0): an error blocks apply,
+An entry never suppresses an error: an error blocks apply,
 and a review record cannot make a broken component deployable. The error
 stays counted, and the entry is reported as a
 `validation-exception-on-error` error until the finding is fixed and the
@@ -136,7 +136,7 @@ entries cover all of them:
 }
 ```
 
-An optional `file` (since 0.52.0) narrows an entry the same way to findings
+An optional `file` narrows an entry the same way to findings
 in one module of the component, by file name. `hardcoded-text` names the
 modules it found text in, so a vendored bundle whose bytes are pinned (and
 so cannot carry a `furnace-ignore` comment) can be accepted while the
@@ -155,7 +155,7 @@ authored modules beside it keep the check. An entry names a `tag` or a
 Accessibility checks judge the composed component: the host
 `<tag>.mjs` and its companion modules (`<tag>-*.mjs`, tests and stories
 left out) read as one source. Moving a template between the component's
-modules therefore no longer changes its findings: a keyboard handler in a
+modules therefore does not change its findings: a keyboard handler in a
 companion covers an `@click` in the host, and an `@click` in a companion
 is judged too. `hardcoded-text` judges each module on its own, so a
 `// furnace-ignore: hardcoded-text` comment covers the file it is in, not

package/docs/lifecycle-invariants.md

@@ -25,7 +25,7 @@ command, read the decision table at the bottom first.
    exception: it writes nothing, runs its git plumbing on a private index
    (so even the `--intent-to-add` staging an untracked binary needs never
    reaches the shared `.git/index`), and serializes only against other dry
-   runs, so a preview no longer queues behind a peer's build or test run.
+   runs, so a preview does not queue behind a peer's build or test run.
 
 3. **A furnace mutation that does not finish restores the engine or says
    so.** Both a signal (SIGINT or SIGTERM) and a thrown error trigger a
@@ -33,14 +33,11 @@ command, read the decision table at the bottom first.
    `pendingRepair` marker blocks all further furnace mutations until
    `fireforge doctor --repair-furnace` reconciles.
 
-   The thrown-error half landed in 0.43.0. Before it, `runFurnaceMutation`'s
-   `finally` only deregistered the operation, and because it also set
-   `completed`, a body that threw removed itself from the signal handler's
-   view as well. A throw outside a body's own catch therefore left the
-   checkout torn with no marker. `applyAllComponents` was the live instance:
-   it rolls back on collected `result.errors` and `stepErrors`, but a throw
-   from its pre-loop or post-loop work escaped both. The wrapper now runs
-   cleanups, restores the journal, and rethrows the original error. A
+   On a thrown error `runFurnaceMutation` runs cleanups, restores the
+   journal, and rethrows the original error, so a throw outside a body's own
+   catch does not leave the checkout torn with no marker. `applyAllComponents`
+   rolls back on collected `result.errors` and `stepErrors`, but a throw from
+   its pre-loop or post-loop work escapes both and relies on the wrapper. A
    rollback failure becomes a marker plus a warning, never a replacement
    error.
 
@@ -70,17 +67,15 @@ command, read the decision table at the bottom first.
    refusal on structural conflicts (`--force-unsafe` to override), and a
    JSONL history entry appended only after the mutation succeeded. This
    covers metadata mutations too: `patch tier` and `patch lint-ignore` route
-   through `confirmDestructive`. They used to accept `--yes` without ever
-   prompting, so the flag only showed up in the history record. Enforced by
+   through `confirmDestructive`. Enforced by
    `patch-tier-and-lint-ignore.integration.test.ts`.
 
    The history log is write-only: FireForge appends to it and no command
    reads it back, so nothing depends on its contents or location. It lives
    at `.fireforge/history.jsonl` (or `fireforge.json#history.path`), outside
-   the tracked patch queue. Before 0.50.0 it was
-   `patches/.fireforge-history.jsonl`; the first append after upgrading
-   moves that file, and appends its records when both exist rather than
-   overwriting either. Each record carries `invocationId` (one per FireForge
+   the tracked patch queue. If `patches/.fireforge-history.jsonl` exists,
+   the next append moves it there, and appends its records when both exist
+   rather than overwriting either. Each record carries `invocationId` (one per FireForge
    process), `pid`, `ppid`, and `sessionId` when `FIREFORGE_SESSION_ID` is
    set, so a session sharing the checkout can select its own lines.
    Enforced by `history-log-file.test.ts`.
@@ -117,14 +112,14 @@ command, read the decision table at the bottom first.
    and `tree remove` refuses while a live PID holds a tree lock and checks
    that its `rm -rf` target is contained in the tree path.
 
-   In-tree `test` (0.41.0) is the one conditional carve-out, and it is
+   In-tree `test` is the one conditional carve-out, and it is
    marker-gated. mach objdirs embed absolute `topsrcdir` and `topobjdir`
    paths, so `tree create --with-objdir` rewrites the cloned objdir's
    `mozinfo.json` to the tree using the same safe-relocation rewriter that
    `build --rewrite-mozinfo` uses, scrubs the cloned `_virtualenvs` (they
    carry primary shebangs, and mach rebuilds them in-tree), and runs
    `mach configure` inside the tree so the configure-generated root files are
-   regenerated against the tree's paths rather than keeping the primary's. It
+   regenerated against the tree's paths rather than keeping the primary's.
    Before configure, relocation rewrites old-source symlinks, `.pp`/`.d`,
    FasterMake and Cargo fingerprint metadata, and removes copied
    `config.statusd/*/config.track` inventories. Those inventories contain
@@ -151,14 +146,14 @@ command, read the decision table at the bottom first.
    **Both halves of that enforcement fail closed on an unreadable state,
    because "we cannot tell" is not "there is nothing there."** A marker that
    exists but does not parse reports `corrupt`, not `absent`, and refuses the
-   command. Reading it as absent granted a snapshot the full mutating command
-   set on the strength of a file that failed to parse. A lock directory whose
+   command. Reading it as absent would grant a snapshot the full mutating
+   command set on the strength of a file that failed to parse. A lock directory whose
    owner cannot be identified reports `unknown`, not free, and refuses
-   removal. Since 0.45.1 `withFileLock` treats its owner-record write as
+   removal. `withFileLock` treats its owner-record write as
    fatal (`writeLockOwner` in `file-lock-owner.ts` removes the just-created
    directory and throws a `GeneralError` if the record cannot be written or
-   does not read back as written), so an owner-less lock is only ever left by
-   a pre-0.45.1 holder or by a crash inside that write. It is still refused,
+   does not read back as written), so an owner-less lock is left only by a
+   crash inside that write or by a holder that never wrote a record. It is refused,
    for the same reason. The one exception is a lock directory that vanished
    between the probe and the owner read: that is a clean release, and reads
    as free.
@@ -168,7 +163,7 @@ command, read the decision table at the bottom first.
    refusal spares the read-only commands that are unconditionally allowed
    (`status`, `lint`, `typecheck`, `verify`): their verdict never consults
    marker fields, so an unreadable marker cannot change their answer, and
-   blocking them left the operator unable to diagnose the very tree that
+   blocking them would leave the operator unable to diagnose the very tree that
    needs inspecting. `conditional` verdicts can write, and stay refused.
    Enforced by `tree-guard.test.ts` (verdict drift gate and corrupt-marker
    refusal), `tree-store.integration.test.ts` (marker tri-state,
@@ -208,7 +203,7 @@ command, read the decision table at the bottom first.
    `GIT_INDEX_FILE` from the repository's own index so that every refresh
    lands there and is discarded. `typecheck` additionally ignores a
    jsconfig's own `incremental` and `tsBuildInfoFile`, so no sidecar is
-   written under `engine/`. Its incremental build info (0.48.0) lives in the
+   written under `engine/`. Its incremental build info lives in the
    project's `.fireforge/typecheck/`, outside the engine. The scope fails open, meaning an unresolvable git dir
    simply does not install it, and it is not reentrant. This exists so that
    invariant 8 stays evidential: a concurrent `fireforge test` must not be
@@ -221,16 +216,14 @@ command, read the decision table at the bottom first.
     in `<lock>.waiters/` named `<startedAtMs>-<pid>-<uuid>` and deregisters in
     a `finally` that covers both outcomes: acquired the lock, or timed out.
     A newcomer that finds live tickets takes one before trying the lock at
-    all. Since 0.50.0 the tickets decide the grant: only the waiter with no
+    all. The tickets decide the grant: only the waiter with no
     live ticket ahead of it (arrival time, then ticket name) attempts the
-    lock, so "You are next" is a promise. Before, every waiter raced `mkdir`
-    and a waiter whose poll had backed off lost each free moment to later
-    arrivals. Because a ticket now blocks the queue, a dead one must not: a
+    lock, so "You are next" is a promise. Because a ticket blocks the queue, a dead one must not: a
     ticket whose PID is gone (or reused, where the start tick can tell) is
     skipped and removed, and one its owner has not refreshed for 30 s (every
     waiter rewrites its ticket every 5 s) is skipped, which covers a stopped
     waiter and PID reuse elsewhere. A registry that cannot be written falls
-    back to the old unordered contention rather than failing an acquisition.
+    back to unordered contention rather than failing an acquisition.
     This applies to every `withFileLock` lock: the engine-session, patch,
     furnace and build locks among them. `fireforge status --lock` and the
     `--wait-lock` progress lines read it, and the lines name the ordering
@@ -258,7 +251,7 @@ command, read the decision table at the bottom first.
     Enforced by `patch-manifest-repair.test.ts` (real temp queues) and the
     repair cases in `doctor.test.ts`.
 
-## Lock release (0.44.0)
+## Lock release
 
 `releaseLockIfOwned(lockPath)` in `src/core/file-lock.ts` is the
 ownership-checked removal for callers that hold no acquisition token.
@@ -266,13 +259,12 @@ Currently that is the signal-time furnace sweeper
 (`forceReleaseFurnaceLocksForActiveOperations`). It verifies the PID before
 removing, which is the half of `releaseLock`'s guard a sweeper can still
 perform: the sweeper knows which lock paths its own operations opened, but
-not the per-acquisition UUID they minted. The bare `rm` it replaced could
+not the per-acquisition UUID they minted. A bare `rm` could
 delete a lock that a different process had acquired in the window between our
 operation dying and the sweep running.
 
 `completeJournalRollback` in `src/core/furnace-operation.ts` owns the
-mutation-body rollback sequence that eight furnace commands previously
-duplicated verbatim. The ordering is the invariant: `markRolledBack()` runs
+mutation-body rollback sequence that eight furnace commands share. The ordering is the invariant: `markRolledBack()` runs
 before the restore, so a restore that itself fails does not leave the
 lifecycle wrapper replaying the same journal on the way out, and the original
 error is rethrown unless the rollback is what failed.
@@ -297,7 +289,7 @@ seconds while waiting, so a holder dying mid-wait cannot strand waiters until
 The owner-record write is fatal. A failed or unverifiable write releases the
 just-created lock and throws a `GeneralError` instead of running the
 operation. Without that, a lock with no readable owner is reaped by the age
-heuristic after 5 minutes, which for a multi-hour build meant a second holder
+heuristic after 5 minutes, which for a multi-hour build would mean a second holder
 inside the critical section. Covered by `file-lock.test.ts`, "owner record
 write at acquisition": write failure, corrupt read-back, recorded acquisition
 time.
@@ -312,8 +304,7 @@ other layer.
 Wait ergonomics are opt-in: `pollMaxMs` (the poll interval doubles from
 `pollMs` up to the cap) and `waitProgressMs` with `onWaitProgress` (a periodic
 progress callback carrying the holder's PID, liveness, and owner-metadata
-lines from the pid file). All three are inert when unset, so existing callers
-keep byte-identical behavior. Within one poll iteration a due progress probe
+lines from the pid file). All three are inert when unset. Within one poll iteration a due progress probe
 runs before the deadline check, so a wait that times out has always reported
 the holder at least once when its budget exceeds `waitProgressMs`, however
 slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
@@ -321,8 +312,8 @@ slow the host (`file-lock.test.ts`, "budget shorter than one iteration").
 ### `src/core/file-lock-owner.ts`
 
 The owner record (the `pid` file) itself: its format (PID, token,
-`acquired-at-ms=` and `start-tick=` lines, plus free-form metadata, and older
-records without the mechanical lines still parse), the write-and-verify
+`acquired-at-ms=` and `start-tick=` lines, plus free-form metadata; a record
+without the mechanical lines parses too), the write-and-verify
 contract described above (a read-back that errors is retried before it counts
 as a failed write, while a missing or mismatching record fails immediately),
 and PID-reuse liveness.
@@ -333,13 +324,13 @@ re-verification, status snapshot and timeout message uses. Beyond
 tick (`/proc/self/stat` field 22), and the probe reads the candidate's tick
 from `/proc/<pid>/stat`. A different tick means a different process, so the
 lock is stale. A crashed build's PID handed to a long-lived daemon therefore
-no longer keeps the dead lock honoured until the waiter's timeout. It uses
+does not keep the dead lock honoured until the waiter's timeout. It uses
 ticks rather than wall-clock times because `btime` moves with clock steps, and
 a wall-clock comparison would reap a live holder after NTP steps the clock
 forward. macOS and Windows have no cheap start-time source (a `ps` spawn per
 poll is not worth it) and keep the PID-only answer, and so do records without
-a start tick. Enforced by `file-lock-owner.test.ts`: backward-compatible
-parsing, forged mechanical lines dropped, transient read-back error retried
+a start tick. Enforced by `file-lock-owner.test.ts`: parsing of records without the
+mechanical lines, forged mechanical lines dropped, transient read-back error retried
 versus persistent error versus mismatch, fake-procfs tick parsing, reused-PID
 versus genuine-holder verdicts, stepped-clock immunity, and on Linux a
 real-procfs `withFileLock` reap of a live-PID stale record.
@@ -360,9 +351,9 @@ log or the engine-session lock shows one in the window (`re-export-purity-scope.
 
 Contention fails fast after about a second by default, with the fixed message
 "Another FireForge engine-mutating command is already running. Wait for it to
-finish, then retry `<command>`." That message contract is unchanged, and it
-also closes the bounded wait. Each of those commands accepts
-`--wait-lock [seconds]` (bare flag means 60, valid 1 to 3600) for a bounded
+finish, then retry `<command>`." The same message also closes the bounded
+wait. Each of those commands accepts
+`--wait-lock [seconds]` (bare flag means 60, valid 1 to 86400) for a bounded
 operator wait instead: polling backs off exponentially from 100 ms to 2 s, and
 roughly every 5 s a progress line identifies the holder from the lock's
 owner-metadata lines, in the form `Waiting for the FireForge engine lock held
@@ -432,7 +423,7 @@ hold it.
 The destructive-operation contract: `confirmDestructive` (summary, prompt,
 `--yes`, `--dry-run`, conflict refusal, `--force-unsafe`) and the
 append-only history log (`src/core/history-log-file.ts` resolves its path,
-migrates a legacy `patches/.fireforge-history.jsonl`, and stamps each
+moves a `patches/.fireforge-history.jsonl` it finds to that path, and stamps each
 record's invocation and session).
 
 ### `src/core/tree-store.ts`