@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/utils/process.js

@@ -4,8 +4,9 @@ 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 { dispatchCompleteLines } from './line-dispatch.js';
 import { killProcessTree, sweepProcessGroup } from './process-group.js';
-// 50 MB cap per stream to prevent OOM — large toolchain builds (e.g. Firefox, Chromium)
+// 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.
 // Callers for whom truncation is unacceptable (e.g. the archive-safety preflight
 // scanning a full `tar -tvf` listing) must check `wasTruncated` and fail hard.
@@ -57,12 +58,25 @@ function buildSignalFromTimeout(timeout) {
  * {@link ExecTimeoutError} naming the command and budget instead of Node's
  * opaque `AbortError: The operation was aborted`.
  */
-function toExecRejection(error, command, args, timeout) {
+function toExecRejection(error, command, args, timeout, output) {
     if (timeout !== undefined && error.name === 'AbortError') {
-        return new ExecTimeoutError(command, args, timeout, error);
+        return new ExecTimeoutError(command, args, timeout, error, output);
     }
     return error;
 }
+/**
+ * Snapshot of what two collectors hold, for carrying onto a timeout
+ * rejection. Without it a `git add -A` killed at its budget rejected with
+ * nothing but the budget: the partial stdout/stderr that said what git was
+ * doing when it died was already collected and simply dropped.
+ */
+function collectedOutput(out, err) {
+    return {
+        stdout: out.getText(),
+        stderr: err.getText(),
+        truncated: out.wasTruncated() || err.wasTruncated(),
+    };
+}
 function exitCodeFromClose(code, signal) {
     if (code !== null) {
         return code;
@@ -95,7 +109,7 @@ export async function exec(command, args, options = {}) {
         child.stdout.on('data', out.onData);
         child.stderr.on('data', err.onData);
         child.on('error', (error) => {
-            reject(toExecRejection(error, command, args, options.timeout));
+            reject(toExecRejection(error, command, args, options.timeout, collectedOutput(out, err)));
         });
         child.on('close', (code, signal) => {
             resolve({
@@ -109,48 +123,48 @@ export async function exec(command, args, options = {}) {
     });
 }
 /**
- * Executes a command and streams its output.
- * @param command - Command to execute
- * @param args - Command arguments
- * @param options - Execution options
- * @returns Exit code of the process
+ * The shared body of every spawn wrapper that outlives its call: detach
+ * decision, shutdown forwarding, closure tracking, process-group sweep and
+ * typed timeout rejection.
+ *
+ * `execStream`, `execInherit` and `execInheritCapture` each hand-rolled this
+ * sequence, and the copies drifted: `execStream` was the one that omitted
+ * {@link trackChildClosure}, so the bin signal handler did not wait for
+ * `runMachStream`'s children on Ctrl+C and the forwarder's SIGTERM → grace →
+ * SIGKILL escalation could not finish before the parent exited. That was the
+ * exact failure the tracking set was introduced to fix, left unwired in one
+ * copy. Keeping the sequence in one place is what stops that recurring.
+ *
+ * `exec` deliberately stays outside: it neither forwards signals nor tracks
+ * closure, because it is for short-lived helpers that no one Ctrl+Cs through.
+ * `execSmokeRun` also stays outside: its deadline owns the SIGTERM → grace →
+ * SIGKILL escalation directly, so it shares no forwarder with the others.
+ *
+ * @param spec - The variant's stdio, stream wiring, grace budget and result shape
+ * @returns Whatever `spec.result` builds from the child's `close` event
  */
-export async function execStream(command, args, options = {}) {
+async function spawnTracked(spec) {
+    const { command, args, options } = spec;
     return new Promise((resolve, reject) => {
         const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
+        const child = spec.spawnChild({
             cwd: options.cwd,
             env: buildChildEnv(options),
-            stdio: ['ignore', 'pipe', 'pipe'],
             signal: buildSignalFromTimeout(options.timeout),
             detached: usesProcessGroup,
         });
         const groupPid = usesProcessGroup ? child.pid : undefined;
-        const stdoutDecoder = new StringDecoder('utf8');
-        const stderrDecoder = new StringDecoder('utf8');
-        child.stdout.on('data', (data) => {
-            const chunk = stdoutDecoder.write(data);
-            if (chunk.length > 0)
-                options.onStdout?.(chunk);
-        });
-        child.stderr.on('data', (data) => {
-            const chunk = stderrDecoder.write(data);
-            if (chunk.length > 0)
-                options.onStderr?.(chunk);
-        });
-        // A detached group leader no longer receives the terminal's Ctrl+C, so
-        // the forwarder is mandatory (not just graceful-UX) when processGroup
-        // is set. Group-aware: kills route to the whole tree.
-        const forwarder = options.processGroup === true
-            ? installGracefulShutdownForwarder(child, 1500, (signal) => {
+        spec.attach?.(child);
+        // Group-aware kills route to the whole tree. A non-group child is killed
+        // directly by the forwarder's own `child.kill`.
+        const killTarget = options.processGroup === true
+            ? (signal) => {
                 killProcessTree(child, signal, usesProcessGroup);
-            })
+            }
+            : undefined;
+        const forwarder = spec.forwardWithoutProcessGroup || options.processGroup === true
+            ? installGracefulShutdownForwarder(child, spec.graceMs, killTarget)
             : undefined;
-        // Closure tracking: this was the one wrapper that omitted it, so the bin
-        // signal handler did not wait for `runMachStream`'s children on Ctrl+C
-        // and the forwarder's SIGTERM → grace → SIGKILL escalation above could
-        // not finish before the parent exited — the exact failure the tracking
-        // set was introduced to fix, left unwired here.
         const closure = trackChildClosure();
         child.on('error', (error) => {
             // Abort/startup failure: make sure a partially-started tree does not
@@ -161,13 +175,13 @@ export async function execStream(command, args, options = {}) {
             }
             forwarder?.dispose();
             closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
+            reject(toExecRejection(error, command, args, options.timeout, spec.rejectionOutput?.()));
         });
         child.on('close', (code, signal) => {
             forwarder?.dispose();
             const finish = () => {
                 closure.settle();
-                resolve(exitCodeFromClose(code, signal));
+                resolve(spec.result(code, signal));
             };
             if (groupPid !== undefined) {
                 sweepProcessGroup(groupPid).then(finish, finish);
@@ -178,6 +192,41 @@ export async function execStream(command, args, options = {}) {
         });
     });
 }
+/**
+ * Executes a command and streams its output.
+ * @param command - Command to execute
+ * @param args - Command arguments
+ * @param options - Execution options
+ * @returns Exit code of the process
+ */
+export async function execStream(command, args, options = {}) {
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: 1500,
+        // A detached group leader no longer receives the terminal's Ctrl+C, so
+        // the forwarder is mandatory (not just graceful-UX) when processGroup
+        // is set. A plain streamed child does not get one.
+        forwardWithoutProcessGroup: false,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: ['ignore', 'pipe', 'pipe'] }),
+        attach: (child) => {
+            const stdoutDecoder = new StringDecoder('utf8');
+            const stderrDecoder = new StringDecoder('utf8');
+            child.stdout.on('data', (data) => {
+                const chunk = stdoutDecoder.write(data);
+                if (chunk.length > 0)
+                    options.onStdout?.(chunk);
+            });
+            child.stderr.on('data', (data) => {
+                const chunk = stderrDecoder.write(data);
+                if (chunk.length > 0)
+                    options.onStderr?.(chunk);
+            });
+        },
+        result: exitCodeFromClose,
+    });
+}
 /**
  * Close-promises of children whose shutdown the CLI must wait for when a
  * termination signal arrives. A bin signal handler that calls `process.exit`
@@ -194,7 +243,7 @@ const activeChildClosures = new Set();
  * Exported for the one legitimate spawn outside this module:
  * `core/marionette-preflight.ts` keeps its own `spawn` because it needs the
  * live `ChildProcess` mid-run, returns while the child is still running, and
- * aborts on a TCP byte rather than a deadline — none of which any wrapper
+ * aborts on a TCP byte rather than a deadline, none of which any wrapper
  * here can express. It still needs the shutdown contract, and a second
  * hand-rolled copy is what lets a Ctrl+C orphan the whole mach → Firefox
  * tree.
@@ -203,7 +252,7 @@ const activeChildClosures = new Set();
  * Registers a child whose shutdown {@link waitForActiveChildShutdown} must
  * wait for, and returns the handle that deregisters it.
  *
- * @returns `settle()` — call from both the child's `close` and `error`
+ * @returns `settle()`. Call from both the child's `close` and `error`
  *   handlers so a dead child never holds the shutdown wait open
  */
 export function trackChildClosure() {
@@ -242,7 +291,7 @@ export async function waitForActiveChildShutdown(timeoutMs) {
  * Graceful shutdown: when the FireForge process receives SIGINT/SIGTERM, the
  * signal is forwarded to the child as SIGTERM and a short grace timer (default
  * 1500ms) runs before escalating to SIGKILL. A second matching signal during
- * the grace period triggers an immediate SIGKILL — matching the usual
+ * the grace period triggers an immediate SIGKILL, matching the usual
  * "hit Ctrl-C again to force-quit" UX. Without this, Firefox's AsyncShutdown
  * / profileBeforeChange blockers (which flush in-memory state to disk) can be
  * racing the OS child-exit path, losing the last few seconds of edits.
@@ -253,51 +302,21 @@ export async function waitForActiveChildShutdown(timeoutMs) {
  * @returns Exit code of the process
  */
 export async function execInherit(command, args, options = {}) {
-    return new Promise((resolve, reject) => {
-        const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            env: buildChildEnv(options),
-            stdio: 'inherit',
-            signal: buildSignalFromTimeout(options.timeout),
-            detached: usesProcessGroup,
-        });
-        const groupPid = usesProcessGroup ? child.pid : undefined;
-        const graceMs = options.shutdownGraceMs ?? 1500;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs, options.processGroup === true
-            ? (signal) => {
-                killProcessTree(child, signal, usesProcessGroup);
-            }
-            : undefined);
-        const closure = trackChildClosure();
-        child.on('error', (error) => {
-            if (options.processGroup === true) {
-                killProcessTree(child, 'SIGKILL', usesProcessGroup);
-            }
-            dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
-        });
-        child.on('close', (code, signal) => {
-            dispose();
-            const finish = () => {
-                closure.settle();
-                resolve(exitCodeFromClose(code, signal));
-            };
-            if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
-            }
-            else {
-                finish();
-            }
-        });
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: options.shutdownGraceMs ?? 1500,
+        forwardWithoutProcessGroup: true,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: 'inherit' }),
+        result: exitCodeFromClose,
     });
 }
 /**
  * Wires parent-process SIGINT/SIGTERM to a child: first signal → child.kill
- * (SIGTERM) + grace timer; second matching signal → immediate SIGKILL; grace
- * timer expiry → SIGKILL. Returns a `dispose()` that clears the listeners and
- * any outstanding timer. Callers must invoke `dispose()` from both the child's
+ * (SIGTERM) + grace timer. A second matching signal → immediate SIGKILL.
+ * Grace timer expiry → SIGKILL. Returns a `dispose()` that clears the
+ * listeners and any outstanding timer. Callers must invoke `dispose()` from both the child's
  * `close` and `error` handlers so the process does not accumulate signal
  * listeners across repeated spawns.
  */
@@ -318,7 +337,7 @@ export function installGracefulShutdownForwarder(child, graceMs, killTarget) {
             sendKill('SIGKILL');
         }
         catch {
-            // Child is already gone — nothing to do.
+            // Child is already gone, nothing to do.
         }
     };
     const handleSignal = (signal) => {
@@ -365,54 +384,27 @@ export function installGracefulShutdownForwarder(child, graceMs, killTarget) {
  * @returns Execution result with stdout, stderr, and exit code
  */
 export async function execInheritCapture(command, args, options = {}) {
-    return new Promise((resolve, reject) => {
-        const usesProcessGroup = options.processGroup === true && process.platform !== 'win32';
-        const child = spawn(command, args, {
-            cwd: options.cwd,
-            env: buildChildEnv(options),
-            stdio: ['inherit', 'pipe', 'pipe'],
-            signal: buildSignalFromTimeout(options.timeout),
-            detached: usesProcessGroup,
-        });
-        const groupPid = usesProcessGroup ? child.pid : undefined;
-        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;
-        const { dispose } = installGracefulShutdownForwarder(child, graceMs, options.processGroup === true
-            ? (signal) => {
-                killProcessTree(child, signal, usesProcessGroup);
-            }
-            : undefined);
-        const closure = trackChildClosure();
-        child.on('error', (error) => {
-            if (options.processGroup === true) {
-                killProcessTree(child, 'SIGKILL', usesProcessGroup);
-            }
-            dispose();
-            closure.settle();
-            reject(toExecRejection(error, command, args, options.timeout));
-        });
-        child.on('close', (code, signal) => {
-            dispose();
-            const finish = () => {
-                closure.settle();
-                resolve({
-                    stdout: out.getText(),
-                    stderr: err.getText(),
-                    exitCode: exitCodeFromClose(code, signal),
-                    stdoutTruncated: out.wasTruncated(),
-                    stderrTruncated: err.wasTruncated(),
-                });
-            };
-            if (groupPid !== undefined) {
-                sweepProcessGroup(groupPid).then(finish, finish);
-            }
-            else {
-                finish();
-            }
-        });
+    const out = createStreamCollector(options.mirror?.stdout ?? process.stdout);
+    const err = createStreamCollector(options.mirror?.stderr ?? process.stderr);
+    return spawnTracked({
+        command,
+        args,
+        options,
+        graceMs: options.shutdownGraceMs ?? 1500,
+        forwardWithoutProcessGroup: true,
+        spawnChild: (base) => spawn(command, args, { ...base, stdio: ['inherit', 'pipe', 'pipe'] }),
+        attach: (child) => {
+            child.stdout.on('data', out.onData);
+            child.stderr.on('data', err.onData);
+        },
+        result: (code, signal) => ({
+            stdout: out.getText(),
+            stderr: err.getText(),
+            exitCode: exitCodeFromClose(code, signal),
+            stdoutTruncated: out.wasTruncated(),
+            stderrTruncated: err.wasTruncated(),
+        }),
+        rejectionOutput: () => collectedOutput(out, err),
     });
 }
 /**
@@ -430,9 +422,10 @@ export async function execInheritCapture(command, args, options = {}) {
  *
  * Windows fallback: `detached: true` does not create an equivalent group
  * there, so we kill the descendant tree with `taskkill /pid <pid> /T /F`
- * instead. taskkill has no graceful-signal equivalent — both the deadline
- * and the grace re-invocation are forced kills, so Windows children get
- * no shutdown window (best-effort; Windows is untested, see README).
+ * instead. taskkill has no graceful-signal equivalent, so both the deadline
+ * and the grace re-invocation are forced kills and Windows children get
+ * no shutdown window. This is best-effort and Windows is untested, see
+ * README.
  * `child.kill()` is still sent as a direct-child fallback in case
  * taskkill itself is unavailable.
  */
@@ -481,8 +474,8 @@ export async function execSmokeRun(command, args, options) {
         }, options.smokeTimeoutMs);
         deadlineTimer.unref();
         // Forward parent SIGINT/SIGTERM to the whole child process group. The
-        // smoke child is a group leader (detached), so it does NOT receive the
-        // terminal's Ctrl+C SIGINT — without this forwarder, the parent exits
+        // smoke child is a group leader (detached), so it does not receive the
+        // terminal's Ctrl+C SIGINT. Without this forwarder, the parent exits
         // and the entire mach → firefox tree is orphaned. Second signal (or
         // grace expiry) escalates to a group SIGKILL.
         const forwardedSignals = new Set();
@@ -542,48 +535,6 @@ export async function execSmokeRun(command, args, options) {
         });
     });
 }
-/**
- * Cap on the partial-line tail kept between chunks. A child emitting one
- * enormous line with no terminator (minified JS dumped to stderr, a raw
- * binary blob) would otherwise grow the buffer without bound — the 50 MB cap
- * guards the collector, not these line buffers. When the tail exceeds the
- * cap it is dispatched as a synthetic (oversized) line so the matchers still
- * see its content, then the buffer resets.
- */
-const MAX_PARTIAL_LINE_SIZE = 1024 * 1024;
-/**
- * Drains complete lines from `buffer`, dispatching each to `cb`. Treats
- * `\n`, `\r\n`, and lone `\r` as line terminators — the lone-`\r` case
- * matters for progress-bar style output (mach, cargo) that repaints a line
- * with carriage returns and never sends a newline, which otherwise
- * accumulates indefinitely. A single trailing `\r` is held back since it may
- * be the first half of a `\r\n` pair split across chunks. Returns the
- * remaining partial line — callers keep accumulating into it.
- */
-function dispatchCompleteLines(buffer, cb) {
-    let searchFrom = 0;
-    for (;;) {
-        const nl = buffer.indexOf('\n', searchFrom);
-        const cr = buffer.indexOf('\r', searchFrom);
-        const idx = nl === -1 ? cr : cr === -1 ? nl : Math.min(nl, cr);
-        if (idx === -1)
-            break;
-        if (buffer[idx] === '\r' && idx === buffer.length - 1) {
-            // Possible first half of a chunk-split \r\n — wait for the next chunk.
-            break;
-        }
-        const line = buffer.slice(0, idx);
-        const terminatorLength = buffer[idx] === '\r' && buffer[idx + 1] === '\n' ? 2 : 1;
-        buffer = buffer.slice(idx + terminatorLength);
-        searchFrom = 0;
-        cb?.(line);
-    }
-    if (buffer.length > MAX_PARTIAL_LINE_SIZE) {
-        cb?.(buffer);
-        return '';
-    }
-    return buffer;
-}
 /**
  * Finds an executable in the system PATH.
  * @param name - Name of the executable
@@ -602,8 +553,7 @@ export async function findExecutable(name) {
         }
         return undefined;
     }
-    catch (error) {
-        void error;
+    catch {
         return undefined;
     }
 }

package/dist/src/utils/ps-duration.d.ts

@@ -3,9 +3,9 @@
  *
  * Two different columns share one grammar, which is why this lives apart
  * from either consumer: `time=` (accumulated CPU) and `etime=` (elapsed
- * wall clock). Reading them with one parser is deliberate — a second
- * hand-rolled copy is how the two would drift, and the darwin dialect is
- * the half that is easy to get wrong.
+ * wall clock). One parser handles both: a second hand-rolled copy is how
+ * the two would drift, and the darwin dialect is the half that is easy to
+ * get wrong.
  *
  * Dialects:
  *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
@@ -13,7 +13,7 @@
  *     wrapping (e.g. `38412:07.55`)
  *
  * Returns `NaN` for anything else, so callers must treat an unrecognized
- * shape as "unknown" rather than as zero — a browser reported as 0 seconds
+ * shape as "unknown" rather than as zero. A browser reported as 0 seconds
  * old would be exactly the wrong attribution.
  */
 /**

package/dist/src/utils/ps-duration.js

@@ -4,9 +4,9 @@
  *
  * Two different columns share one grammar, which is why this lives apart
  * from either consumer: `time=` (accumulated CPU) and `etime=` (elapsed
- * wall clock). Reading them with one parser is deliberate — a second
- * hand-rolled copy is how the two would drift, and the darwin dialect is
- * the half that is easy to get wrong.
+ * wall clock). One parser handles both: a second hand-rolled copy is how
+ * the two would drift, and the darwin dialect is the half that is easy to
+ * get wrong.
  *
  * Dialects:
  *   - linux `[dd-]hh:mm:ss` (e.g. `26-03:14:12`, `03:14:12`)
@@ -14,7 +14,7 @@
  *     wrapping (e.g. `38412:07.55`)
  *
  * Returns `NaN` for anything else, so callers must treat an unrecognized
- * shape as "unknown" rather than as zero — a browser reported as 0 seconds
+ * shape as "unknown" rather than as zero. A browser reported as 0 seconds
  * old would be exactly the wrong attribution.
  */
 /**
@@ -34,14 +34,14 @@ export function parsePsDuration(value) {
     }
     const parts = rest.split(':');
     if (parts.length === 3) {
-        // hh:mm:ss (linux; seconds may not carry fractions but tolerate them)
+        // hh:mm:ss on linux. Seconds may not carry fractions but tolerate them.
         const [h, m, s] = parts.map(Number);
         if ([h, m, s].some((n) => Number.isNaN(n)))
             return NaN;
         return days * 86400 + (h ?? 0) * 3600 + (m ?? 0) * 60 + (s ?? 0);
     }
     if (parts.length === 2) {
-        // mm:ss.cc (darwin — the minutes field accumulates without wrapping)
+        // mm:ss.cc on darwin. The minutes field accumulates without wrapping.
         const [m, s] = parts.map(Number);
         if ([m, s].some((n) => Number.isNaN(n)))
             return NaN;
@@ -58,13 +58,13 @@ export function formatPsDuration(seconds) {
     if (Number.isNaN(seconds) || seconds < 0)
         return undefined;
     if (seconds < 60)
-        return `${String(Math.floor(seconds))}s`;
+        return `${Math.floor(seconds)}s`;
     if (seconds < 3600) {
         const m = Math.floor(seconds / 60);
         const s = Math.floor(seconds % 60);
-        return `${String(m)}m${String(s).padStart(2, '0')}s`;
+        return `${m}m${String(s).padStart(2, '0')}s`;
     }
     const h = Math.floor(seconds / 3600);
     const m = Math.floor((seconds % 3600) / 60);
-    return `${String(h)}h${String(m).padStart(2, '0')}m`;
+    return `${h}h${String(m).padStart(2, '0')}m`;
 }

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

@@ -9,16 +9,16 @@ export declare function hasRawCssColors(content: string): boolean;
 /**
  * Strips JS single-line and multi-line comments from source code, replacing
  * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets AND line numbers are preserved. String literals are
+ * both character offsets and line numbers are preserved. String literals are
  * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — a pure-regex
+ * Uses acorn's tokenizer, which understands regex literals. A pure-regex
  * implementation does not model them, so two adjacent slashes inside a regex
  * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. Firefox chrome sources contain preprocessor directives (`#ifdef`)
- * and other constructs acorn cannot tokenize; those fall back to the legacy
- * regex strip, which handles strings but NOT regex literals.
+ * and other constructs acorn cannot tokenize. Those fall back to the legacy
+ * regex strip, which handles strings but not regex literals.
  */
 export declare function stripJsComments(source: string): string;
 /**

package/dist/src/utils/regex.js

@@ -25,16 +25,16 @@ export function hasRawCssColors(content) {
 /**
  * Strips JS single-line and multi-line comments from source code, replacing
  * comment bytes with spaces (newlines inside block comments are kept) so
- * both character offsets AND line numbers are preserved. String literals are
+ * both character offsets and line numbers are preserved. String literals are
  * preserved intact.
  *
- * Uses acorn's tokenizer, which understands regex literals — a pure-regex
+ * Uses acorn's tokenizer, which understands regex literals. A pure-regex
  * implementation does not model them, so two adjacent slashes inside a regex
  * (the tail of `/https?:\/\//`) read as a `//` line comment and the rest of
  * the line is blanked, corrupting whatever lint pass consumes the stripped
  * text. Firefox chrome sources contain preprocessor directives (`#ifdef`)
- * and other constructs acorn cannot tokenize; those fall back to the legacy
- * regex strip, which handles strings but NOT regex literals.
+ * and other constructs acorn cannot tokenize. Those fall back to the legacy
+ * regex strip, which handles strings but not regex literals.
  */
 export function stripJsComments(source) {
     const comments = [];
@@ -47,7 +47,7 @@ export function stripJsComments(source) {
                 comments.push({ start, end });
             },
         });
-        // Drive the tokenizer to EOF; we only care about onComment callbacks.
+        // Drive the tokenizer to EOF. We only care about onComment callbacks.
         for (;;) {
             const token = t.getToken();
             if (token.type === acornTokTypes.eof)
@@ -71,8 +71,8 @@ export function stripJsComments(source) {
 }
 /**
  * Legacy pure-regex comment strip, used only when acorn cannot tokenize
- * the source (preprocessor directives, syntax errors). Strings survive;
- * regex literals are NOT modeled, so `//` inside a regex blanks the rest
+ * the source (preprocessor directives, syntax errors). Strings survive.
+ * Regex literals are not modeled, so `//` inside a regex blanks the rest
  * of the line.
  */
 function stripJsCommentsLegacy(source) {

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ *
+ * 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
+ * exit mid-grace and skip the escalation entirely.
+ *
+ * Built on the global `setTimeout` rather than `node:timers/promises`: the
+ * suites that drive retry and grace-period logic use vitest fake timers,
+ * which patch the global but not the promisified module, so the tidier
+ * import would make every timing path untestable.
+ * @param ms - Milliseconds to wait.
+ * @param options - Pass `unref: true` when a pending delay must not keep the
+ *   process alive (background probes, best-effort retries during shutdown).
+ * @returns A promise that resolves once the delay has elapsed.
+ */
+export declare function sleep(ms: number, options?: {
+    unref?: boolean;
+}): Promise<void>;

package/dist/src/utils/sleep.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * 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.
+ *
+ * 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
+ * exit mid-grace and skip the escalation entirely.
+ *
+ * Built on the global `setTimeout` rather than `node:timers/promises`: the
+ * suites that drive retry and grace-period logic use vitest fake timers,
+ * which patch the global but not the promisified module, so the tidier
+ * import would make every timing path untestable.
+ * @param ms - Milliseconds to wait.
+ * @param options - Pass `unref: true` when a pending delay must not keep the
+ *   process alive (background probes, best-effort retries during shutdown).
+ * @returns A promise that resolves once the delay has elapsed.
+ */
+export function sleep(ms, options) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        if (options?.unref === true)
+            timer.unref();
+    });
+}