@hominis/fireforge 0.46.0 → 0.46.1

package/dist/src/core/engine-session-lock.d.ts

@@ -9,13 +9,13 @@ export interface EngineSessionLockOptions {
     waitLockSeconds?: number | undefined;
 }
 /**
- * Formats the notice printed when the wait budget is EXTENDED because the
+ * Formats the notice printed when the wait budget is extended because the
  * queue advanced.
  *
- * Exported for direct unit testing. It names both figures — the requested
- * budget and the one now in force — because the whole point is that the two
- * have diverged, and an operator comparing the elapsed time against the
- * number they typed would otherwise conclude the timeout is broken.
+ * Exported for direct unit testing. It names both figures, the requested
+ * budget and the one now in force, because they have diverged and an
+ * operator comparing the elapsed time against the number they typed would
+ * otherwise conclude the timeout is broken.
  */
 export declare function formatWaitExtendedLine(ahead: number, budgetMs: number, requestedMs: number): string;
 /**
@@ -24,8 +24,8 @@ export declare function formatWaitExtendedLine(ahead: number, budgetMs: number,
  */
 export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
- * Inspects the project's engine-session lock without acquiring it —
- * backing `fireforge status --lock`.
+ * Inspects the project's engine-session lock without acquiring it, backing
+ * `fireforge status --lock`.
  *
  * @param projectRoot - Project root containing `.fireforge/`
  * @returns Holder identity, hold duration, and queue depth
@@ -52,7 +52,7 @@ export declare function snapshotEngineGeneration(engineDir: string): Promise<str
  */
 export declare function isIndexLockError(error: unknown): boolean;
 /**
- * True when a generation token records a failed probe — i.e. nothing was
+ * True when a generation token records a failed probe, i.e. nothing was
  * measured, so the token must never be compared (or hashed) as if it
  * described the engine's state.
  */
@@ -62,8 +62,8 @@ export declare function unavailableGenerationReason(token: string): string;
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
- * The refusal used to say only THAT the engine changed, which left the
- * operator to reconstruct the writer by hand — `find -newermt` against the
+ * The refusal used to say only that the engine changed, which left the
+ * operator to reconstruct the writer by hand: `find -newermt` against the
  * run window, minus the objdir, minus git's own bookkeeping. Everything
  * needed to answer it is already in the two tokens, so the refusal answers
  * it. Pure and total: an unparseable token yields an empty list rather than
@@ -72,7 +72,7 @@ export declare function unavailableGenerationReason(token: string): string;
  *
  * @param before - Token captured before the run
  * @param after - Token captured after the run
- * @returns Human-readable lines describing the delta; empty when nothing
+ * @returns Human-readable lines describing the delta. Empty when nothing
  *   could be attributed
  */
 export declare function describeEngineGenerationDelta(before: string, after: string): string[];
@@ -80,25 +80,25 @@ export declare function describeEngineGenerationDelta(before: string, after: str
  * Throws when the engine's generation token differs from `before`, i.e. the
  * engine was mutated by another writer while a test run was in flight.
  *
- * **An unmeasurable engine warns rather than throws.** `engine/` is not
- * always a git checkout — `fireforge download` extracts a source tarball —
+ * An unmeasurable engine warns rather than throws. `engine/` is not
+ * always a git checkout (`fireforge download` extracts a source tarball),
  * so a failed probe is a legitimate state and must not fail the run.
  *
- * What it must also not do is pass *silently*. A failure token compared for
+ * It must also not pass silently. A failure token compared for
  * equality like any other would let a git failure that reproduces across
  * both probes (unreadable `.git`, a permissions problem, a corrupt index)
  * take the `after === before` early return and bless a verdict the guard
- * never verified. Two *differing* failure messages are worse still: they
+ * never verified. Two differing failure messages are worse still: they
  * fall through to the mutation branch and report a spurious
  * "engine/ changed". Hence the prefix comparison rather than a token
- * comparison — the token embeds the error message, and two genuine failures
+ * comparison: the token embeds the error message, and two genuine failures
  * rarely phrase it identically.
  *
- * The tolerance is deliberately limited to a probe that failed *both* times:
+ * The tolerance is limited to a probe that failed both times:
  * that is the steady state of a non-git `engine/`, and it warns. A one-sided
  * transition is not that state. An `engine/` that was measurable and then
  * was not means the second probe measured nothing about a checkout that
- * demonstrably had something to measure; the reverse means there was never a
+ * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
 export declare function assertEngineGenerationUnchanged(engineDir: string, before: string): Promise<void>;

package/dist/src/core/engine-session-lock.js

@@ -18,7 +18,7 @@ const MAX_WAIT_LOCK_MS = 3600 * 1000;
 /**
  * Formats the periodic operator-facing waiting line printed while `--wait-lock`
  * polls a contended engine session lock. The holder identification comes from
- * the lock's owner-metadata lines (`command=…`, `started=…`); an unreadable
+ * the lock's owner-metadata lines (`command=…`, `started=…`). An unreadable
  * owner file degrades to the anonymous form.
  */
 function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
@@ -37,13 +37,13 @@ function formatWaitProgressLine(waitedMs, timeoutMs, holder, queue) {
     return `Waiting for the FireForge engine lock held by PID ${holder.pid}${details} — ${progress}.${position}`;
 }
 /**
- * Formats the notice printed when the wait budget is EXTENDED because the
+ * Formats the notice printed when the wait budget is extended because the
  * queue advanced.
  *
- * Exported for direct unit testing. It names both figures — the requested
- * budget and the one now in force — because the whole point is that the two
- * have diverged, and an operator comparing the elapsed time against the
- * number they typed would otherwise conclude the timeout is broken.
+ * Exported for direct unit testing. It names both figures, the requested
+ * budget and the one now in force, because they have diverged and an
+ * operator comparing the elapsed time against the number they typed would
+ * otherwise conclude the timeout is broken.
  */
 export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
     const position = ahead === 0 ? 'you are now next' : `${ahead} still ahead of you`;
@@ -57,11 +57,11 @@ export function formatWaitExtendedLine(ahead, budgetMs, requestedMs) {
  * one engine-mutating FireForge command touches `engine/` at a time.
  */
 export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
-    // The lock is bypassed under test by default, and that is deliberate: the
+    // The lock is bypassed under test by default, on purpose: the
     // suite runs many engine-mutating commands in-process, which would either
     // serialise on this lock or deadlock outright.
     // `FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST=1` lets the lock's own
-    // tests opt back in. Do not delete this branch — it is the reason the
+    // tests opt back in. Do not delete this branch. It is the reason the
     // suite completes.
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
@@ -78,30 +78,30 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
                 onWaitProgress: ({ waitedMs, timeoutMs, holder, queue }) => {
                     info(formatWaitProgressLine(waitedMs, timeoutMs, holder, queue));
                 },
-                // Say it out loud. An extension is the moment the budget the
+                // Announce it. An extension is the moment the budget the
                 // operator asked for stops being the budget in force, and a wait
                 // that silently outlives its own stated timeout is
-                // indistinguishable from a broken one — which is how a downstream
+                // indistinguishable from a broken one, which is how a downstream
                 // fork read it.
                 onWaitExtended: ({ ahead, budgetMs }) => {
                     info(formatWaitExtendedLine(ahead, budgetMs, waitLockSeconds * 1000));
                 },
                 // A budget that expires one position from the head pays the whole
-                // wait for nothing. While the queue is still MOVING the wait is
-                // working, so each advance renews the budget — up to a hard
-                // ceiling, so a pathological queue cannot wait forever. The
-                // no-flag fail-fast path deliberately gets none of this.
+                // wait for nothing. While the queue is still moving the wait is
+                // working, so each advance renews the budget, up to a hard
+                // ceiling so a pathological queue cannot wait forever. The
+                // no-flag fail-fast path gets none of this.
                 extendWhileAdvancing: {
                     maxWaitMs: Math.min(waitLockSeconds * 1000 * WAIT_EXTENSION_FACTOR, MAX_WAIT_LOCK_MS),
                 },
             }
             : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
-        // Reason first, remedy second — the no-flag default waits
+        // Reason first, remedy second: the no-flag default waits
         // only ~1 s, so contention is the common case and `--wait-lock` is the
         // genuine remedy. withFileLock appends the holder identification from
         // the lock's owner metadata. The leading sentence is a message contract
-        // (pinned by engine-session-lock tests); extend, don't reword.
+        // (pinned by engine-session-lock tests). Extend, don't reword.
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
             `Wait for it to finish, then retry \`${command}\` — or pass --wait-lock [seconds] ` +
             `to wait for the lock (bare --wait-lock waits up to 60 seconds). ` +
@@ -110,8 +110,8 @@ export async function withEngineSessionLock(projectRoot, command, operation, opt
     });
 }
 /**
- * Inspects the project's engine-session lock without acquiring it —
- * backing `fireforge status --lock`.
+ * Inspects the project's engine-session lock without acquiring it, backing
+ * `fireforge status --lock`.
  *
  * @param projectRoot - Project root containing `.fireforge/`
  * @returns Holder identity, hold duration, and queue depth
@@ -139,11 +139,11 @@ export function formatEngineSessionLockStatus(snapshot, holderCpuSeconds) {
         `Engine session lock: ${identity}, for ${elapsed}.`,
         `Queue depth: ${snapshot.queueDepth} waiter(s).`,
     ];
-    // Liveness answers "does the process exist"; it does not answer "is it
+    // Liveness answers "does the process exist". It does not answer "is it
     // getting anywhere". A holder alive for minutes having used a fraction of
     // a second of CPU is the shape of a wedged command, and every waiter
     // behind it inherits the stall. Stated as an observation with its own
-    // caveat — a holder blocked on I/O is also idle, and this must not be read
+    // caveat: a holder blocked on I/O is also idle, and this must not be read
     // as licence to kill anything.
     if (holder?.alive === true && holderCpuSeconds !== undefined) {
         const cpu = `${holderCpuSeconds.toFixed(1)}s`;
@@ -175,11 +175,11 @@ export async function snapshotEngineGeneration(engineDir) {
         }
         catch (error) {
             lastError = error;
-            // A contended `.git/index.lock` is TRANSIENT, not a state: some other
+            // A contended `.git/index.lock` is transient, not a state: some other
             // writer held the index for the instant we looked. Treating it as
             // "unmeasurable" turns a perfectly good suite into
             // `FAIL reason=inconclusive` on a one-sided probe failure. Anything
-            // else — an unreadable `.git`, a non-git `engine/` — is a real state
+            // else (an unreadable `.git`, a non-git `engine/`) is a real state
             // and is reported immediately.
             if (!isIndexLockError(error) || attempt === GENERATION_PROBE_ATTEMPTS - 1)
                 break;
@@ -202,7 +202,7 @@ export function isIndexLockError(error) {
     return /index\.lock/i.test(message);
 }
 /**
- * True when a generation token records a failed probe — i.e. nothing was
+ * True when a generation token records a failed probe, i.e. nothing was
  * measured, so the token must never be compared (or hashed) as if it
  * described the engine's state.
  */
@@ -228,9 +228,9 @@ function splitGenerationToken(token) {
 /**
  * Parses `git status --porcelain=v1 -z` into `XY path` records.
  *
- * The rename/copy shape is the trap: `R`/`C` entries are followed by a
- * SECOND NUL-separated field carrying the original path, and consuming only
- * one desynchronises every record after it — turning a one-file rename into
+ * The rename/copy shape needs care: `R`/`C` entries are followed by a
+ * second NUL-separated field carrying the original path, and consuming only
+ * one desynchronises every record after it, turning a one-file rename into
  * a report that the whole tree moved. Both fields are consumed and the
  * record renders as `orig -> new`.
  */
@@ -239,7 +239,7 @@ function parsePorcelainRecords(body) {
     const records = [];
     for (let i = 0; i < fields.length; i++) {
         const field = fields[i] ?? '';
-        // `XY ` — two status characters and a space — then the path.
+        // `XY `, two status characters and a space, then the path.
         if (field.length < 4)
             continue;
         const status = field.slice(0, 2);
@@ -257,8 +257,8 @@ function parsePorcelainRecords(body) {
 /**
  * Describes what moved between two generation tokens, in operator terms.
  *
- * The refusal used to say only THAT the engine changed, which left the
- * operator to reconstruct the writer by hand — `find -newermt` against the
+ * The refusal used to say only that the engine changed, which left the
+ * operator to reconstruct the writer by hand: `find -newermt` against the
  * run window, minus the objdir, minus git's own bookkeeping. Everything
  * needed to answer it is already in the two tokens, so the refusal answers
  * it. Pure and total: an unparseable token yields an empty list rather than
@@ -267,7 +267,7 @@ function parsePorcelainRecords(body) {
  *
  * @param before - Token captured before the run
  * @param after - Token captured after the run
- * @returns Human-readable lines describing the delta; empty when nothing
+ * @returns Human-readable lines describing the delta. Empty when nothing
  *   could be attributed
  */
 export function describeEngineGenerationDelta(before, after) {
@@ -296,25 +296,25 @@ export function describeEngineGenerationDelta(before, after) {
  * Throws when the engine's generation token differs from `before`, i.e. the
  * engine was mutated by another writer while a test run was in flight.
  *
- * **An unmeasurable engine warns rather than throws.** `engine/` is not
- * always a git checkout — `fireforge download` extracts a source tarball —
+ * An unmeasurable engine warns rather than throws. `engine/` is not
+ * always a git checkout (`fireforge download` extracts a source tarball),
  * so a failed probe is a legitimate state and must not fail the run.
  *
- * What it must also not do is pass *silently*. A failure token compared for
+ * It must also not pass silently. A failure token compared for
  * equality like any other would let a git failure that reproduces across
  * both probes (unreadable `.git`, a permissions problem, a corrupt index)
  * take the `after === before` early return and bless a verdict the guard
- * never verified. Two *differing* failure messages are worse still: they
+ * never verified. Two differing failure messages are worse still: they
  * fall through to the mutation branch and report a spurious
  * "engine/ changed". Hence the prefix comparison rather than a token
- * comparison — the token embeds the error message, and two genuine failures
+ * comparison: the token embeds the error message, and two genuine failures
  * rarely phrase it identically.
  *
- * The tolerance is deliberately limited to a probe that failed *both* times:
+ * The tolerance is limited to a probe that failed both times:
  * that is the steady state of a non-git `engine/`, and it warns. A one-sided
  * transition is not that state. An `engine/` that was measurable and then
  * was not means the second probe measured nothing about a checkout that
- * demonstrably had something to measure; the reverse means there was never a
+ * demonstrably had something to measure. The reverse means there was never a
  * baseline to compare against. Neither verdict can be trusted, so both throw.
  */
 export async function assertEngineGenerationUnchanged(engineDir, before) {

package/dist/src/core/export-moved-code-shape.d.ts

@@ -2,23 +2,23 @@
  * Detects the new-file-plus-moved-code slice shape and names the working
  * sequence through it.
  *
- * A slice that ADDS new files and MOVES lines into them from an existing
+ * A slice that adds new files and moves lines into them from an existing
  * patch has no path through the two refusal flags:
  *
  *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files are
- *    still unmanaged; and
+ *    still unmanaged, and
  *  - exporting the new files as their own patch fails cross-patch lint,
- *    because at the projected placement the OLD patch still contains the
+ *    because at the projected placement the old patch still contains the
  *    moved code.
  *
  * Each guard is individually correct. Together they dead-end, and the way out
- * is non-obvious: adopt the new files into the OLD patch first
+ * is non-obvious: adopt the new files into the old patch first
  * (`re-export --scan --scan-file`), then split them out into a patch of their
  * own (`patch move-files --create --order N`).
  *
- * This module recognises the shape from evidence FireForge already has — the
+ * This module recognises the shape from evidence FireForge already has (the
  * pending diff's new-file content versus the added lines the existing patches
- * carry — so the refusal can name the sequence instead of leaving the
+ * carry), so the refusal can name the sequence instead of leaving the
  * operator to derive it.
  */
 /** One existing patch that already carries lines the new files would add. */
@@ -37,7 +37,7 @@ export interface MovedCodeQueueEntry {
 }
 /**
  * Finds existing patches that still carry substantive lines the pending
- * diff's NEW files would add — the fingerprint of code moved out of an
+ * diff's new files would add, the fingerprint of code moved out of an
  * existing patch into a new file.
  *
  * Pure. Overlaps are returned strongest-first so the message names the

package/dist/src/core/export-moved-code-shape.js

@@ -3,23 +3,23 @@
  * Detects the new-file-plus-moved-code slice shape and names the working
  * sequence through it.
  *
- * A slice that ADDS new files and MOVES lines into them from an existing
+ * A slice that adds new files and moves lines into them from an existing
  * patch has no path through the two refusal flags:
  *
  *  - `re-export --refuse-adjacent-unmanaged` refuses while the new files are
- *    still unmanaged; and
+ *    still unmanaged, and
  *  - exporting the new files as their own patch fails cross-patch lint,
- *    because at the projected placement the OLD patch still contains the
+ *    because at the projected placement the old patch still contains the
  *    moved code.
  *
  * Each guard is individually correct. Together they dead-end, and the way out
- * is non-obvious: adopt the new files into the OLD patch first
+ * is non-obvious: adopt the new files into the old patch first
  * (`re-export --scan --scan-file`), then split them out into a patch of their
  * own (`patch move-files --create --order N`).
  *
- * This module recognises the shape from evidence FireForge already has — the
+ * This module recognises the shape from evidence FireForge already has (the
  * pending diff's new-file content versus the added lines the existing patches
- * carry — so the refusal can name the sequence instead of leaving the
+ * carry), so the refusal can name the sequence instead of leaving the
  * operator to derive it.
  */
 import { extractAddedLinesPerFile } from './patch-lint-diff.js';
@@ -42,7 +42,7 @@ function isSubstantiveLine(line) {
 const MOVED_CODE_LINE_THRESHOLD = 3;
 /**
  * Finds existing patches that still carry substantive lines the pending
- * diff's NEW files would add — the fingerprint of code moved out of an
+ * diff's new files would add, the fingerprint of code moved out of an
  * existing patch into a new file.
  *
  * Pure. Overlaps are returned strongest-first so the message names the
@@ -108,7 +108,7 @@ export function formatAdoptThenSplitRemedy(overlaps, newPatchName, insertionOrde
         return [];
     const fileArgs = strongest.files.map((file) => `--scan-file ${file}`).join(' ');
     const moveArgs = strongest.files.map((file) => `--file ${file}`).join(' ');
-    // `patch move-files --create` takes the new patch's NAME, not a
+    // `patch move-files --create` takes the new patch's name, not a
     // filename: strip the order prefix and the `.patch` suffix so the
     // suggested command is copy-pasteable.
     const suggestedName = newPatchName.replace(/^\d+-/, '').replace(/\.patch$/, '');

package/dist/src/core/file-lock-owner.d.ts

@@ -2,7 +2,7 @@
  * Filename of a lock directory's owner record, relative to the lock dir.
  *
  * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
- * the constant instead of re-spelling `'pid'`; the file *format* is
+ * the constant instead of re-spelling `'pid'`. The file format is
  * documented on {@link readLockOwner}.
  */
 export declare const LOCK_PID_FILE = "pid";
@@ -12,8 +12,8 @@ export declare const LOCK_PID_FILE = "pid";
  * `token` is the per-acquisition UUID written on line 2 of the PID file,
  * `acquiredAtMs` the wall-clock time the record was written (diagnostic),
  * and `startTick` the writer's boot-relative start tick (liveness). Records
- * from releases before a field was introduced parse with it `undefined`;
- * readers must treat that as "unknown", never as a mismatch.
+ * from releases before a field was introduced parse with it `undefined`.
+ * Readers must treat that as "unknown", never as a mismatch.
  */
 export type LockOwner = {
     present: false;
@@ -34,7 +34,7 @@ export type LockOwner = {
  * age-only staleness heuristic).
  *
  * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file — so the token and
+ * which parses the leading digits of a multi-line file, so the token and
  * mechanical lines stay compatible.
  *
  * @param lockPath - Lock directory whose owner record to read
@@ -46,8 +46,8 @@ export declare function readLockOwner(lockPath: string): Promise<LockOwner>;
  * time, own start tick, diagnostic metadata) into a lock directory it has
  * just created, and reads the record back to prove it landed.
  *
- * The write is FATAL. It used to be best-effort, on the theory that stale
- * recovery would fall back to the age heuristic — but that heuristic reaps
+ * The write is fatal. It used to be best-effort, on the theory that stale
+ * recovery would fall back to the age heuristic, but that heuristic reaps
  * any owner-less lock after five minutes, and the build lock legitimately
  * holds for hours. A holder whose record failed to write was therefore
  * reaped mid-build and a second process entered the critical section. On
@@ -67,14 +67,14 @@ export declare function writeLockOwner(lockPath: string, token: string, ownerMet
  * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
  * Elsewhere (macOS, Windows) obtaining a start time means spawning
  * `ps`/`wmic` per probe, which is not worth paying on every poll of a
- * contended lock — those platforms return `undefined` and liveness stays
+ * contended lock. Those platforms return `undefined` and liveness stays
  * PID-only.
  *
- * Deliberately NOT converted to wall-clock time via `/proc/stat` `btime`:
+ * Not converted to wall-clock time via `/proc/stat` `btime`, on purpose:
  * on current kernels `btime` is derived from the realtime clock and moves
  * with every clock step, so a wall-clock comparison against a recorded
  * acquisition time misjudges a live holder as a reused PID after NTP steps
- * the clock forward — and reaps a lock that is in use.
+ * the clock forward, and reaps a lock that is in use.
  *
  * @param pid - Process to look up
  * @param procRoot - procfs mount, overridable for tests
@@ -82,10 +82,10 @@ export declare function writeLockOwner(lockPath: string, token: string, ownerMet
  */
 export declare function readProcessStartTick(pid: number, procRoot?: string): number | undefined;
 /**
- * Whether the process named by a lock's owner record is the SAME process
+ * Whether the process named by a lock's owner record is the same process
  * that acquired the lock, not merely a live process wearing its PID.
  *
- * `isProcessAlive` answers "does this PID exist"; after a holder crashes,
+ * `isProcessAlive` answers "does this PID exist". After a holder crashes,
  * the kernel may hand its PID to a long-lived daemon, and a PID-only check
  * then honours the dead lock until the waiter's timeout. Where the record
  * carries the writer's start tick and the candidate's own tick is cheaply

package/dist/src/core/file-lock-owner.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Owner record of a `withFileLock` directory: the file that says WHICH
+ * Owner record of a `withFileLock` directory: the file that says which
  * process holds the lock, so stale recovery can tell a dead holder from a
  * slow one and release can refuse to remove a lock it no longer owns.
  *
@@ -18,7 +18,7 @@ import { sleep } from '../utils/sleep.js';
  * Filename of a lock directory's owner record, relative to the lock dir.
  *
  * Re-exported by `file-lock.ts` so external readers (`tree-store.ts`) share
- * the constant instead of re-spelling `'pid'`; the file *format* is
+ * the constant instead of re-spelling `'pid'`. The file format is
  * documented on {@link readLockOwner}.
  */
 export const LOCK_PID_FILE = 'pid';
@@ -26,8 +26,8 @@ export const LOCK_PID_FILE = 'pid';
  * Prefix of the mechanical owner-record line that carries the acquisition
  * wall time. It lives among the metadata lines (line 3 onward) so older
  * readers, which treat everything past line 2 as free-form diagnostics,
- * still parse the record; the current reader lifts it out of `metadata`.
- * Diagnostic only — see {@link START_TICK_PREFIX} for the liveness field.
+ * still parse the record. The current reader lifts it out of `metadata`.
+ * Diagnostic only. See {@link START_TICK_PREFIX} for the liveness field.
  */
 const ACQUIRED_AT_PREFIX = 'acquired-at-ms=';
 /**
@@ -41,11 +41,11 @@ const ACQUIRED_AT_PREFIX = 'acquired-at-ms=';
  */
 const START_TICK_PREFIX = 'start-tick=';
 /**
- * How many times the post-write read-back is retried when the READ itself
+ * How many times the post-write read-back is retried when the read itself
  * errors (not when the record is absent or differs). An on-access scanner
  * on Windows briefly holding the just-written file (`EBUSY`), or a FUSE
  * mount's momentary `EIO`, must not be indistinguishable from "the record
- * never landed" — that verdict releases a lock this process has correctly
+ * never landed": that verdict releases a lock this process has correctly
  * acquired and aborts the run before it starts.
  */
 const READ_BACK_ATTEMPTS = 5;
@@ -100,7 +100,7 @@ function parseLockOwnerRecord(pidContent) {
  * age-only staleness heuristic).
  *
  * File format note: external readers do `parseInt(content.trim(), 10)`,
- * which parses the leading digits of a multi-line file — so the token and
+ * which parses the leading digits of a multi-line file, so the token and
  * mechanical lines stay compatible.
  *
  * @param lockPath - Lock directory whose owner record to read
@@ -113,14 +113,14 @@ export async function readLockOwner(lockPath) {
             return owner;
     }
     catch {
-        // PID file missing or unreadable — treat as absent.
+        // PID file missing or unreadable. Treat as absent.
     }
     return { present: false };
 }
 /**
- * Reads the just-written record back, retrying a READ ERROR a few times
+ * Reads the just-written record back, retrying a read error a few times
  * before giving up. A missing or malformed record is returned as-is (the
- * caller treats it as a failed write); only errno-level failures retry.
+ * caller treats it as a failed write). Only errno-level failures retry.
  */
 async function readBackLockOwner(lockPath) {
     let lastError;
@@ -141,8 +141,8 @@ async function readBackLockOwner(lockPath) {
  * time, own start tick, diagnostic metadata) into a lock directory it has
  * just created, and reads the record back to prove it landed.
  *
- * The write is FATAL. It used to be best-effort, on the theory that stale
- * recovery would fall back to the age heuristic — but that heuristic reaps
+ * The write is fatal. It used to be best-effort, on the theory that stale
+ * recovery would fall back to the age heuristic, but that heuristic reaps
  * any owner-less lock after five minutes, and the build lock legitimately
  * holds for hours. A holder whose record failed to write was therefore
  * reaped mid-build and a second process entered the critical section. On
@@ -196,14 +196,14 @@ export async function writeLockOwner(lockPath, token, ownerMetadata) {
  * Linux only: field 22 of `/proc/<pid>/stat`, in USER_HZ since boot.
  * Elsewhere (macOS, Windows) obtaining a start time means spawning
  * `ps`/`wmic` per probe, which is not worth paying on every poll of a
- * contended lock — those platforms return `undefined` and liveness stays
+ * contended lock. Those platforms return `undefined` and liveness stays
  * PID-only.
  *
- * Deliberately NOT converted to wall-clock time via `/proc/stat` `btime`:
+ * Not converted to wall-clock time via `/proc/stat` `btime`, on purpose:
  * on current kernels `btime` is derived from the realtime clock and moves
  * with every clock step, so a wall-clock comparison against a recorded
  * acquisition time misjudges a live holder as a reused PID after NTP steps
- * the clock forward — and reaps a lock that is in use.
+ * the clock forward, and reaps a lock that is in use.
  *
  * @param pid - Process to look up
  * @param procRoot - procfs mount, overridable for tests
@@ -213,7 +213,7 @@ export function readProcessStartTick(pid, procRoot = '/proc') {
     try {
         const stat = readFileSync(join(procRoot, String(pid), 'stat'), 'utf-8');
         // `comm` (field 2) is parenthesised and may itself contain spaces or
-        // parentheses, so split only what follows the LAST closing paren:
+        // parentheses, so split only what follows the last closing paren:
         // field 3 (state) is then index 0 and field 22 (starttime) index 19.
         const startTick = Number.parseInt(stat
             .slice(stat.lastIndexOf(')') + 1)
@@ -226,10 +226,10 @@ export function readProcessStartTick(pid, procRoot = '/proc') {
     }
 }
 /**
- * Whether the process named by a lock's owner record is the SAME process
+ * Whether the process named by a lock's owner record is the same process
  * that acquired the lock, not merely a live process wearing its PID.
  *
- * `isProcessAlive` answers "does this PID exist"; after a holder crashes,
+ * `isProcessAlive` answers "does this PID exist". After a holder crashes,
  * the kernel may hand its PID to a long-lived daemon, and a PID-only check
  * then honours the dead lock until the waiter's timeout. Where the record
  * carries the writer's start tick and the candidate's own tick is cheaply