@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/run-log-redact.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Conservative secret redaction for the run-log FILE tee.
+ *
+ * A run log is a complete copy of mach's output, and mach echoes its
+ * environment in places (configure summaries, `mach env`, harness
+ * diagnostics that print the command line). The terminal already showed
+ * every byte to the operator who ran it. The file, by contrast, is retained
+ * twenty deep and gets attached to bug reports. So the file gets a narrow
+ * masking pass and the terminal does not.
+ *
+ * Minimal and pattern-based. See {@link redactRunLogText} for the exact
+ * contract. It is a seatbelt against the common accidental leak, not a
+ * guarantee that a log is free of secrets.
+ */
+/** Env-style keys whose assigned value is masked. */
+const SECRET_KEY_PATTERN = /(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i;
+/**
+ * `KEY=value` where KEY is an identifier and the value runs to the next
+ * whitespace, or is a single/double-quoted string. The leading group keeps
+ * the assignment anchored at a token boundary so `x.y=z` is not split
+ * mid-token. A hyphen IS a boundary: mach and configure echo their argv, so
+ * `--token=…`, `--password=…` and `-DAUTH_TOKEN=…` are exactly the forms a
+ * retained log would otherwise carry verbatim (the lead keeps the dash, and
+ * the key is what follows it). Empty values are left alone (nothing to hide).
+ */
+const ENV_ASSIGNMENT_PATTERN = /(^|[\s"'([{,;-])([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*"|'[^']*'|[^\s"',;)\]}]+)/g;
+/** `Authorization: <scheme> <credential>` (scheme optional) in HTTP dumps. */
+const AUTHORIZATION_HEADER_PATTERN = /(authorization\s*:\s*)(?:(bearer|basic|token)\s+)?(\S+)/gi;
+/** Marker written in place of a masked value. */
+const REDACTED = '<redacted>';
+function redactLine(line) {
+    return line
+        .replace(ENV_ASSIGNMENT_PATTERN, (whole, lead, key) => SECRET_KEY_PATTERN.test(key) ? `${lead}${key}=${REDACTED}` : whole)
+        .replace(AUTHORIZATION_HEADER_PATTERN, (_whole, lead, scheme) => scheme === undefined ? `${lead}${REDACTED}` : `${lead}${scheme} ${REDACTED}`);
+}
+/**
+ * Masks the obvious secret shapes in run-log text, line by line.
+ *
+ * Redacted:
+ * - the value of an env-style assignment `KEY=value` whose KEY matches
+ *   `/(TOKEN|SECRET|PASSWORD|PASSWD|API_KEY|AUTH)/i`. The value up to the
+ *   next whitespace, or a whole quoted string, becomes `KEY=<redacted>`.
+ *   The `--flag=value` and `-DNAME=value` spellings of the same shape are
+ *   covered (`--password=x` → `--password=<redacted>`).
+ * - the credential of an `Authorization:` header (`Bearer`, `Basic` and
+ *   `Token` schemes keep the scheme word, and anything else masks the
+ *   whole value).
+ *
+ * Not redacted: secrets that appear without one of those key names or
+ * headers (a bare token in a URL query string, a space-separated
+ * `--password foo` CLI argument, JSON `"token": "..."` fields, cookies).
+ * Line structure and every other byte pass through unchanged. `\n`, `\r\n`
+ * and lone `\r` all delimit lines, so carriage-return-repainted progress
+ * output is masked per repaint.
+ *
+ * @param text - One or more complete lines
+ * @returns The same text with masked values
+ */
+export function redactRunLogText(text) {
+    if (text.length === 0)
+        return text;
+    // Split with a capturing group so the terminators survive the round trip.
+    // Odd indices are the terminators themselves.
+    return text
+        .split(/(\r\n|\n|\r)/)
+        .map((part, index) => (index % 2 === 0 ? redactLine(part) : part))
+        .join('');
+}

package/dist/src/core/run-log.d.ts

@@ -2,19 +2,19 @@
  * Per-run output logs under `.fireforge/logs/`.
  *
  * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep` — the ergonomic default when output is long — keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * through `tail`/`grep`, the ergonomic default when output is long, keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
  * broke, and it launders the exit code besides. The operator rule ("never
  * pipe a run") was written down three times downstream and broken after each
- * writing, which is the tell that it is not an operator problem: the tool is
- * the only party that can make the log survive the mistake.
+ * writing, so this is not an operator problem: the tool is the only party
+ * that can make the log survive the mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
  * backgrounded run then still leaves a re-readable artifact.
  *
- * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
- * a run must never fail because one could not be opened, written, or pruned.
+ * Everything here is best-effort. A log is a diagnostic aid, and a run must
+ * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
  * exactly the behaviour that existed before this module.
  */
@@ -22,7 +22,11 @@
 export interface RunLog {
     /** Absolute path to the log file. */
     path: string;
-    /** Appends raw output. Silently drops on any stream error. */
+    /**
+     * Appends output. Complete lines pass through {@link redactRunLogText}
+     * before hitting disk. A trailing partial line is held until its newline
+     * arrives (or until `close`). Silently drops on any stream error.
+     */
     write: (chunk: string) => void;
     /** Flushes and closes. Resolves even when the stream already failed. */
     close: () => Promise<void>;
@@ -45,13 +49,20 @@ export declare function setActiveRunLog(log: RunLog | undefined): void;
 export declare function getActiveRunLogPath(): string | undefined;
 /** Appends to the active run log. A no-op when none is open. */
 export declare function writeToActiveRunLog(chunk: string): void;
-/** Closes and clears the active run log. Resolves even when none is open. */
+/**
+ * Closes and clears the active run log. Resolves even when none is open.
+ *
+ * Also called from the entry point's SIGINT/SIGTERM path: the held partial
+ * line and anything queued in the stream would otherwise be lost across
+ * `process.exit`, and a killed run's last line is usually the one that
+ * says what it was doing.
+ */
 export declare function closeActiveRunLog(): Promise<void>;
 /**
- * A writable that forwards to `base` AND to the active run log.
+ * A writable that forwards to `base` and to the active run log.
  *
  * Used by the stdio-inheriting capture path, whose collectors take a mirror
- * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * stream rather than per-chunk callbacks, so the tee reuses the mirror the
  * exec layer already supports instead of growing a second hook.
  *
  * @param base - The stream to forward to (normally `process.stdout`)

package/dist/src/core/run-log.js

@@ -3,19 +3,19 @@
  * Per-run output logs under `.fireforge/logs/`.
  *
  * A run's diagnosis used to exist in exactly one place: the terminal. Piping
- * through `tail`/`grep` — the ergonomic default when output is long — keeps
- * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * through `tail`/`grep`, the ergonomic default when output is long, keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say what
  * broke, and it launders the exit code besides. The operator rule ("never
  * pipe a run") was written down three times downstream and broken after each
- * writing, which is the tell that it is not an operator problem: the tool is
- * the only party that can make the log survive the mistake.
+ * writing, so this is not an operator problem: the tool is the only party
+ * that can make the log survive the mistake.
  *
  * So `test` and `build` write their own complete copy as they stream, and the
  * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
  * backgrounded run then still leaves a re-readable artifact.
  *
- * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
- * a run must never fail because one could not be opened, written, or pruned.
+ * Everything here is best-effort. A log is a diagnostic aid, and a run must
+ * never fail because one could not be opened, written, or pruned.
  * Every entry point swallows its errors and degrades to "no log", which is
  * exactly the behaviour that existed before this module.
  */
@@ -23,8 +23,11 @@ import { createWriteStream } from 'node:fs';
 import { mkdir, readdir, unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { Writable } from 'node:stream';
+import { toError } from '../utils/errors.js';
 import { verbose } from '../utils/logger.js';
 import { FIREFORGE_DIR } from './config-paths.js';
+import { redactRunLogText } from './run-log-redact.js';
+import { fileSafeTimestamp } from './state-file.js';
 /** Directory under `.fireforge/` holding run logs. */
 const LOGS_DIRNAME = 'logs';
 /**
@@ -33,24 +36,38 @@ const LOGS_DIRNAME = 'logs';
  * most often needs to read together.
  */
 const RETAINED_LOGS_PER_COMMAND = 20;
+/**
+ * Cap on the partial line held back between writes. A child emitting one
+ * enormous unterminated line (a minified dump on stderr) would otherwise
+ * grow the buffer without bound (and, because each write rebuilds
+ * `pending + chunk`, quadratically), with nothing reaching disk until
+ * close. Past the cap the tail is redacted and written as-is. A `KEY=value`
+ * split exactly at the cap boundary is the accepted cost. Same figure as
+ * `line-dispatch.ts` uses for the stream matchers.
+ */
+const MAX_PENDING_LINE_SIZE = 1024 * 1024;
+/**
+ * Index just past the last line terminator in `text`, or -1 when there is
+ * none. `\n` and lone `\r` both terminate: progress-bar output (mach,
+ * cargo) repaints a line with carriage returns and may never send a
+ * newline, which would otherwise pin the whole run in `pending`. A single
+ * trailing `\r` is not a terminator yet: it may be the first half of a
+ * `\r\n` split across chunks.
+ */
+function lastLineEnd(text) {
+    const lastNewline = text.lastIndexOf('\n');
+    const lastReturn = text.lastIndexOf('\r');
+    const cut = lastReturn > lastNewline && lastReturn < text.length - 1 ? lastReturn : lastNewline;
+    return cut === -1 ? -1 : cut + 1;
+}
 /** `.fireforge/logs` under `projectRoot`. */
 export function getRunLogDir(projectRoot) {
     return join(projectRoot, FIREFORGE_DIR, LOGS_DIRNAME);
 }
-/**
- * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
- *
- * Colons are not portable in filenames (Windows rejects them outright), so
- * the ISO form is punctuated with dashes only. Lexical order still equals
- * chronological order, which is what the pruning below relies on.
- */
-function logTimestamp(now) {
-    return now.toISOString().replace(/[:.]/g, '-');
-}
 /**
  * Makes room for one new log by deleting the oldest, so that at most
  * {@link RETAINED_LOGS_PER_COMMAND} logs for `command` exist once the new
- * one is created. Pruning runs BEFORE the file is opened — hence the
+ * one is created. Pruning runs before the file is opened, hence the
  * `- 1`, without which the directory settles at N + 1.
  *
  * Best-effort: a failure here must not stop the run that is about to be
@@ -76,7 +93,7 @@ async function pruneRunLogs(dir, command) {
         }));
     }
     catch (error) {
-        verbose(`Run-log pruning skipped: ${String(error)}`);
+        verbose(`Run-log pruning skipped: ${toError(error).message}`);
     }
 }
 /**
@@ -91,14 +108,14 @@ async function pruneRunLogs(dir, command) {
 export async function openRunLog(projectRoot, command, now = new Date()) {
     const dir = getRunLogDir(projectRoot);
     let stream;
-    const path = join(dir, `${command}-${logTimestamp(now)}.log`);
+    const path = join(dir, `${command}-${fileSafeTimestamp(now)}.log`);
     try {
         await mkdir(dir, { recursive: true });
         await pruneRunLogs(dir, command);
         stream = createWriteStream(path, { flags: 'a' });
     }
     catch (error) {
-        verbose(`Run log unavailable (${path}): ${String(error)}`);
+        verbose(`Run log unavailable (${path}): ${toError(error).message}`);
         return undefined;
     }
     // A stream error after open (disk full, a removed directory) must not
@@ -109,19 +126,44 @@ export async function openRunLog(projectRoot, command, now = new Date()) {
         broken = true;
         verbose(`Run log write failed (${path}): ${error.message}`);
     });
+    // Redaction is per LINE, and chunks arrive at arbitrary byte boundaries,
+    // so a `KEY=value` split across two chunks would slip past a per-chunk
+    // pass. Hold the trailing partial line until its terminator arrives (or
+    // it outgrows MAX_PENDING_LINE_SIZE, or the log is closed).
+    let pending = '';
+    const emit = (text) => {
+        if (broken || text.length === 0)
+            return;
+        try {
+            stream.write(redactRunLogText(text));
+        }
+        catch {
+            broken = true;
+        }
+    };
     return {
         path,
         write: (chunk) => {
             if (broken)
                 return;
-            try {
-                stream.write(chunk);
+            const buffered = pending + chunk;
+            const lineEnd = lastLineEnd(buffered);
+            if (lineEnd === -1) {
+                pending = buffered;
             }
-            catch {
-                broken = true;
+            else {
+                pending = buffered.slice(lineEnd);
+                emit(buffered.slice(0, lineEnd));
+            }
+            if (pending.length > MAX_PENDING_LINE_SIZE) {
+                emit(pending);
+                pending = '';
             }
         },
         close: async () => {
+            const tail = pending;
+            pending = '';
+            emit(tail);
             await new Promise((resolve) => {
                 stream.end(() => {
                     resolve();
@@ -155,17 +197,24 @@ export function getActiveRunLogPath() {
 export function writeToActiveRunLog(chunk) {
     activeRunLog?.write(chunk);
 }
-/** Closes and clears the active run log. Resolves even when none is open. */
+/**
+ * Closes and clears the active run log. Resolves even when none is open.
+ *
+ * Also called from the entry point's SIGINT/SIGTERM path: the held partial
+ * line and anything queued in the stream would otherwise be lost across
+ * `process.exit`, and a killed run's last line is usually the one that
+ * says what it was doing.
+ */
 export async function closeActiveRunLog() {
     const log = activeRunLog;
     activeRunLog = undefined;
     await log?.close();
 }
 /**
- * A writable that forwards to `base` AND to the active run log.
+ * A writable that forwards to `base` and to the active run log.
  *
  * Used by the stdio-inheriting capture path, whose collectors take a mirror
- * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * stream rather than per-chunk callbacks, so the tee reuses the mirror the
  * exec layer already supports instead of growing a second hook.
  *
  * @param base - The stream to forward to (normally `process.stdout`)

package/dist/src/core/shared-ftl.d.ts

@@ -2,13 +2,13 @@
  * Structural rules for the `sharedFtl` field on a custom component.
  *
  * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
- * furnace.json parser apply the same rules — extracting them here
+ * furnace.json parser apply the same rules. Extracting them here
  * avoids drift between the two entry points and lets the `.mjs`
  * template generator assume the value is safe to interpolate verbatim.
  */
 /**
  * Outcome of {@link validateSharedFtl}. `ok: true` carries the trimmed
- * (operator-safe) value; `ok: false` carries a human-readable message
+ * (operator-safe) value. `ok: false` carries a human-readable message
  * suitable for throwing as a `FurnaceError` or `InvalidArgumentError`.
  */
 export type SharedFtlValidation = {

package/dist/src/core/shared-ftl.js

@@ -3,18 +3,18 @@
  * Structural rules for the `sharedFtl` field on a custom component.
  *
  * Both the `--shared-ftl` CLI flag path (`furnace create`) and the
- * furnace.json parser apply the same rules — extracting them here
+ * furnace.json parser apply the same rules. Extracting them here
  * avoids drift between the two entry points and lets the `.mjs`
  * template generator assume the value is safe to interpolate verbatim.
  */
 /**
  * Characters that must not appear in `sharedFtl`.
  *
- * A POLICY rule about what a sensible FTL path looks like, not the safety
- * boundary for the generated `.mjs`: the scaffold escapes the value at its
- * sink with `JSON.stringify` (`commands/furnace/create-templates.ts`), which
- * is what actually makes interpolation safe and what covers the two inputs
- * this rule never catches — a `"` and a raw newline.
+ * This is a policy rule about what a sensible FTL path looks like, not the
+ * safety boundary for the generated `.mjs`. The scaffold escapes the value at
+ * its sink with `JSON.stringify` (`commands/furnace/create-templates.ts`),
+ * which is what actually makes interpolation safe, and what covers the two
+ * inputs this rule never catches: a `"` and a raw newline.
  *
  * Kept because each remains a real sign of a malformed path:
  *  - `\` is a path-escape we do not want to interpret.

package/dist/src/core/signal-critical.d.ts

@@ -13,7 +13,7 @@
  * for the slot to clear before calling `process.exit`, so a signal that
  * lands mid-body is held until the body's state write finishes.
  *
- * This module is a pure runtime registry — it installs no signal handlers
+ * This module is a pure runtime registry. It installs no signal handlers
  * itself. The bin entry point is responsible for awaiting
  * `waitForActiveCriticalSections` before terminating.
  */
@@ -23,7 +23,7 @@
  * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
  * rejects).
  *
- * `fn` should be short — anything that takes longer than the bounded wait in
+ * `fn` should be short. Anything that takes longer than the bounded wait in
  * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
  * the handler will exit anyway. The intent is "guard the apply + state
  * persist pair," not "postpone exit indefinitely."

package/dist/src/core/signal-critical.js

@@ -14,10 +14,11 @@
  * for the slot to clear before calling `process.exit`, so a signal that
  * lands mid-body is held until the body's state write finishes.
  *
- * This module is a pure runtime registry — it installs no signal handlers
+ * This module is a pure runtime registry. It installs no signal handlers
  * itself. The bin entry point is responsible for awaiting
  * `waitForActiveCriticalSections` before terminating.
  */
+import { sleep } from '../utils/sleep.js';
 const activeSections = new Set();
 /**
  * Runs `fn` inside a signal-deferred critical section. The CLI entry point's
@@ -25,7 +26,7 @@ const activeSections = new Set();
  * SIGTERM that arrives during `fn` will hold exit until `fn` returns (or
  * rejects).
  *
- * `fn` should be short — anything that takes longer than the bounded wait in
+ * `fn` should be short. Anything that takes longer than the bounded wait in
  * the bin handler (`SIGNAL_CRITICAL_SECTION_TIMEOUT_MS`) will time out and
  * the handler will exit anyway. The intent is "guard the apply + state
  * persist pair," not "postpone exit indefinitely."
@@ -57,8 +58,5 @@ export async function waitForActiveCriticalSections(timeoutMs) {
     if (activeSections.size === 0)
         return;
     const snapshot = [...activeSections].map((s) => s.promise);
-    await Promise.race([
-        Promise.allSettled(snapshot).then(() => undefined),
-        new Promise((resolve) => setTimeout(resolve, timeoutMs)),
-    ]);
+    await Promise.race([Promise.allSettled(snapshot).then(() => undefined), sleep(timeoutMs)]);
 }

package/dist/src/core/smoke-patterns.d.ts

@@ -10,17 +10,16 @@
  * warning (e.g. `"pending JavaScript error cleanup"`) do not start with
  * the prefix and should not trip the scanner.
  */
-export declare const SMOKE_ERROR_PATTERNS: readonly RegExp[];
 /**
  * Returns `true` when `line` matches any pattern in
- * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist. That step
  * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
 export declare function matchesSmokeError(line: string): boolean;
 /**
  * One compiled allowlist entry with its provenance retained so the smoke
- * summary can attribute hits per entry — an entry that silently
+ * summary can attribute hits per entry. An entry that silently
  * stops matching (its suppressed shape changed upstream) is only
  * detectable when zero-hit entries are visible.
  */
@@ -33,16 +32,16 @@ export interface CompiledAllowlistEntry {
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
- * First-match attribution is deterministic and cheap; a line matching
+ * First-match attribution is deterministic and cheap. A line matching
  * several entries credits the earliest one. Safe to call with an empty
  * allowlist (always returns -1).
  */
 export declare function matchAllowlist(line: string, allow: readonly CompiledAllowlistEntry[]): number;
 /**
- * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * Parses a newline-delimited allowlist file body. Lines are trimmed. Blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
- * pattern throws immediately — better to fail fast at CLI parse time than
+ * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
  */
 export declare function compileAllowlistFromFile(body: string, sourcePath: string): CompiledAllowlistEntry[];

package/dist/src/core/smoke-patterns.js

@@ -16,25 +16,25 @@
  * process. A hit on any of these patterns is a smoke failure unless the
  * line also matches the caller-supplied allowlist.
  *
- * Additions here should be conservative — false positives turn every
+ * Additions here should be conservative. False positives turn every
  * smoke run into noise for operators and every CI run into flake.
  */
 import { toError } from '../utils/errors.js';
-export const SMOKE_ERROR_PATTERNS = [
-    // Firefox chrome error lines — `JavaScript error: chrome://…, line N: TypeError: …`.
+const SMOKE_ERROR_PATTERNS = [
+    // Firefox chrome error lines: `JavaScript error: chrome://…, line N: TypeError: …`.
     /^\s*JavaScript error:/i,
     // Some log paths prefix browser-console `console.error(...)` with the literal label below.
     /^\s*console\.error:/i,
     // Older bracketed-prefix variant still seen in some chrome logs / test runs.
     /^\s*\[JavaScript (Error|Warning)\]/i,
-    // IPC-layer fatal assertions — Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
+    // IPC-layer fatal assertions. Firefox prints `###!!! [Parent] Error: …` on content-process crashes.
     /^\s*###!!! \[Parent\]/,
     // A chrome:// or resource:// URL that resolves to nothing. Outside
     // automation Gecko only PRINTS this (printf_stderr in
-    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp); under
+    // `CheckForBrokenChromeURL`, netwerk/base/nsNetUtil.cpp). Under
     // `xpc::IsInAutomation()` the same condition is a
     // `MOZ_CRASH_UNSAFE_PRINTF` in whichever process opened the channel. So
-    // the smoke probe — which runs OUTSIDE automation — sees the printed
+    // the smoke probe, which runs outside automation, sees the printed
     // line for the same defect that hard-crashes every harness run, and a
     // probe that exits 0 on it reports "startup is healthy" for a build that
     // hangs at "Waiting for browser…". Both spellings are matched: the
@@ -44,7 +44,7 @@ export const SMOKE_ERROR_PATTERNS = [
 ];
 /**
  * Returns `true` when `line` matches any pattern in
- * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist — that step
+ * {@link SMOKE_ERROR_PATTERNS}. Does not consult the allowlist. That step
  * lives in {@link matchAllowlist}, so the smoke runner can count
  * allowlisted hits separately from raw error matches for its summary.
  */
@@ -58,23 +58,18 @@ export function matchesSmokeError(line) {
 }
 /**
  * Returns the index of the FIRST entry in `allow` matching `line`, or -1.
- * First-match attribution is deterministic and cheap; a line matching
+ * First-match attribution is deterministic and cheap. A line matching
  * several entries credits the earliest one. Safe to call with an empty
  * allowlist (always returns -1).
  */
 export function matchAllowlist(line, allow) {
-    for (let i = 0; i < allow.length; i++) {
-        if (allow[i]?.pattern.test(line)) {
-            return i;
-        }
-    }
-    return -1;
+    return allow.findIndex((entry) => entry.pattern.test(line));
 }
 /**
- * Parses a newline-delimited allowlist file body. Lines are trimmed; blank
+ * Parses a newline-delimited allowlist file body. Lines are trimmed. Blank
  * lines and `#`-prefixed comments are skipped. Each remaining line is
  * compiled as a RegExp with its `<file>:<line>` origin retained. A bad
- * pattern throws immediately — better to fail fast at CLI parse time than
+ * pattern throws immediately: better to fail fast at CLI parse time than
  * to silently let a typo match nothing.
  */
 export function compileAllowlistFromFile(body, sourcePath) {
@@ -88,12 +83,12 @@ export function compileAllowlistFromFile(body, sourcePath) {
             compiled.push({
                 pattern: new RegExp(line),
                 source: line,
-                origin: `${sourcePath}:${String(index + 1)}`,
+                origin: `${sourcePath}:${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid allowlist regex at ${sourcePath}:${String(index + 1)}: ${message}`, {
+            throw new Error(`Invalid allowlist regex at ${sourcePath}:${index + 1}: ${message}`, {
                 cause: error,
             });
         }
@@ -111,12 +106,12 @@ export function compileAllowlistFromStrings(sources) {
             compiled.push({
                 pattern: new RegExp(source),
                 source,
-                origin: `--console-allow #${String(index + 1)}`,
+                origin: `--console-allow #${index + 1}`,
             });
         }
         catch (error) {
             const message = toError(error).message;
-            throw new Error(`Invalid --console-allow regex at position ${String(index + 1)} ("${source}"): ${message}`, { cause: error });
+            throw new Error(`Invalid --console-allow regex at position ${index + 1} ("${source}"): ${message}`, { cause: error });
         }
     });
     return compiled;

package/dist/src/core/state-file.d.ts

@@ -1,21 +1,32 @@
 /** Runs an operation while holding the sidecar lock for a FireForge state file. */
 export declare function withStateFileLock<T>(statePath: string, operation: () => Promise<T>): Promise<T>;
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export declare function fileSafeTimestamp(now: Date): string;
 /** Renames a state file out of the way while preserving it for later inspection. */
 export declare function quarantineStateFile(statePath: string, reason?: string): Promise<string | undefined>;
 /**
  * Outcome of a version check on a persisted FireForge document.
  *
  * The distinction that matters is `newer` vs `corrupt`. A document written
- * by a NEWER FireForge is not damaged — the operator simply needs to upgrade
- * — but a check that collapses the two offers destructive remedies. The
+ * by a newer FireForge is not damaged. The operator simply needs to upgrade.
+ * A check that collapses the two offers destructive remedies. The
  * sharpest case is the tree marker, whose `schemaVersion` check inside a
  * boolean type guard makes a `schemaVersion: 2` marker read as "missing or
- * mistypes a required field"; `tree-guard.ts` is default-deny on corrupt, so
+ * mistypes a required field". `tree-guard.ts` is default-deny on corrupt, so
  * a newer FireForge would lock the operator out of every mutating command
  * inside that tree.
  *
  * `furnace.json` is the pattern the rest should follow: it refuses a newer
- * version by name and tells the operator to upgrade (`migrateFurnaceConfig`
+ * version by name and tells the operator to upgrade (`validateConfigVersion`
  * in `furnace-config.ts`).
  */
 export type DocumentVersionCheck = {

package/dist/src/core/state-file.js

@@ -12,12 +12,25 @@ export async function withStateFileLock(statePath, operation) {
             `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
     });
 }
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what run-log pruning relies on.
+ *
+ * @param now - Instant to render
+ * @returns The ISO-8601 form with `:` and `.` replaced by `-`
+ */
+export function fileSafeTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
 /** Renames a state file out of the way while preserving it for later inspection. */
 export async function quarantineStateFile(statePath, reason = 'corrupt') {
     if (!(await pathExists(statePath))) {
         return undefined;
     }
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const timestamp = fileSafeTimestamp(new Date());
     const quarantinedPath = `${statePath}.${reason}-${timestamp}`;
     await rename(statePath, quarantinedPath);
     return basename(quarantinedPath);