@sayknow-cli/utils 0.7.11 → 0.7.13

package/src/crash-fingerprint.ts

@@ -0,0 +1,294 @@
+/**
+ * Crash fingerprinting, algorithm v1.
+ *
+ * A fingerprint is a stable, versioned identity for a crash *class*, computed
+ * at `recordFatalCrash` time from the already-captured diagnostic text (error
+ * name, message, stack) and nothing else. It exists so that N crash-loop
+ * records collapse into one countable signature.
+ *
+ * ## Privacy posture
+ *
+ * The fingerprint is a **public, pseudonymous correlation token**. It is
+ * deterministic over low-entropy inputs, therefore dictionary-testable, and it
+ * links the same crash class across installs and accounts. It is NOT a
+ * confidentiality control. Only *normalized* text is hashed — absolute paths,
+ * home directories, uuids/hex/long digit runs and everything
+ * `redactCrashSecrets` rewrites are replaced with placeholders before hashing —
+ * so a fingerprint never encodes a secret or a raw filesystem path.
+ *
+ * ## Canonical serialization (v1)
+ *
+ * Fields are length-prefixed UTF-8 (`<byteLength>:<bytes>`) so no delimiter
+ * ambiguity exists between an empty field and a missing one:
+ *
+ *     "skc-crash-fp.v1" | errorName | messageClass | frame0 | frame1 | frame2
+ *
+ * Up to three normalized in-app frames participate; absent frames are omitted
+ * (the length prefix of the preceding fields keeps the encoding unambiguous).
+ * The digest is sha256 truncated to its first 16 bytes, published as 32
+ * lowercase hex characters (128 bits).
+ */
+import { createHash } from "node:crypto";
+import * as os from "node:os";
+import * as path from "node:path";
+import { redactCrashSecrets } from "./crash-redaction";
+
+/** Algorithm version recorded beside every emitted fingerprint. */
+export const CRASH_FINGERPRINT_VERSION = 1;
+/** Hex length of a published fingerprint (128 bits). */
+export const CRASH_FINGERPRINT_HEX_LENGTH = 32;
+/** Matches exactly a published fingerprint. */
+export const CRASH_FINGERPRINT_PATTERN = /^[0-9a-f]{32}$/;
+/** Marker used for the machine-readable identity line of each crash record. */
+export const CRASH_RECORD_MARKER = "skc-crash-record.v1";
+/** Marker embedded in an external issue body, outside crash-derived blocks. */
+export const CRASH_ISSUE_MARKER_PREFIX = "skc-crash-fp.v1:";
+/** Literal frame used when a stack carries no in-app frame at all. */
+export const NO_APP_FRAME = "<no-app-frame>";
+
+/** Byte caps applied before hashing, so a huge throwable cannot dominate cost. */
+const MESSAGE_CLASS_MAX_BYTES = 512;
+const FRAME_MAX_BYTES = 256;
+const MAX_FRAMES = 3;
+
+export interface CrashFingerprintInput {
+	readonly name: string;
+	readonly message: string;
+	readonly stack: string;
+}
+
+export interface CrashFingerprint {
+	/** 32 lowercase hex characters. */
+	readonly fingerprint: string;
+	/** Algorithm version (`fpv`). */
+	readonly version: number;
+	readonly errorName: string;
+	/** Normalized, placeholder-substituted message class (safe to display). */
+	readonly messageClass: string;
+	/** Normalized in-app frames that participated in the digest. */
+	readonly frames: readonly string[];
+}
+
+export interface CrashFingerprintOptions {
+	/** Install root used to relativize in-app frames. Defaults to the SKC install root. */
+	readonly installRoot?: string;
+	/** Home directory used for `<home>` substitution. Defaults to `os.homedir()`. */
+	readonly homeDir?: string;
+}
+
+/**
+ * Root of this installation, used to relativize frames.
+ *
+ * Source checkouts resolve to the workspace root (this file lives at
+ * `packages/utils/src/`); an npm install resolves to the `node_modules` root.
+ * Both are stable per install *shape*, which is what frame identity needs;
+ * compiled binaries never reach here because their frames are BunFS paths.
+ */
+function defaultInstallRoot(): string {
+	return path.resolve(import.meta.dir, "..", "..", "..");
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+	const bytes = Buffer.from(text, "utf8");
+	let end = maxBytes;
+	while (end > 0 && (bytes[end - 1] & 0xc0) === 0x80) end--;
+	if (end > 0 && bytes[end - 1] >= 0xc0) end--;
+	return bytes.subarray(0, end).toString("utf8");
+}
+
+const UUID_PATTERN = /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g;
+const HEX_RUN_PATTERN = /\b[0-9a-fA-F]{8,}\b/g;
+const DIGIT_RUN_PATTERN = /\d{4,}/g;
+// UNC, Windows drive-letter, BunFS (posix + windows compiled forms), POSIX.
+const PATH_PATTERN =
+	/\\\\[^\s"'`,;)\]]+|\b[A-Za-z]:\\[^\s"'`,;)\]]*|\/\$bunfs\/[^\s"'`,;)\]]*|(?<![\w.~])\/[^\s"'`,;)\]]*/g;
+
+function normalizeSeparators(value: string): string {
+	return value.replace(/\\/g, "/");
+}
+
+/**
+ * Replace absolute path-like tokens with `<home>` / `<path>`.
+ *
+ * Semantically meaningful codes are untouched: this rule only fires on tokens
+ * that are recognizably absolute filesystem paths.
+ */
+export function replaceAbsolutePaths(text: string, homeDir: string = os.homedir()): string {
+	const normalizedHome = normalizeSeparators(homeDir).replace(/\/+$/, "");
+	return text.replace(PATH_PATTERN, match => {
+		if (match === "/") return match;
+		const normalized = normalizeSeparators(match);
+		if (normalizedHome.length > 0 && (normalized === normalizedHome || normalized.startsWith(`${normalizedHome}/`)))
+			return "<home>";
+		return "<path>";
+	});
+}
+
+/**
+ * Typed message normalization.
+ *
+ * Deliberately *not* "strip all digits": HTTP statuses, exit codes and errno
+ * names are the difference between distinct crash classes, so runs of three or
+ * fewer digits and alphabetic error codes survive verbatim (`404` stays
+ * distinct from `500`). Only high-entropy identifiers are collapsed.
+ */
+export function normalizeCrashMessage(message: string, options: CrashFingerprintOptions = {}): string {
+	const homeDir = options.homeDir ?? os.homedir();
+	let normalized = redactCrashSecrets(message);
+	normalized = replaceAbsolutePaths(normalized, homeDir);
+	normalized = normalized.replace(UUID_PATTERN, "<uuid>");
+	normalized = normalized.replace(HEX_RUN_PATTERN, match => (/[a-fA-F]/.test(match) ? "<hex>" : "<num>"));
+	normalized = normalized.replace(DIGIT_RUN_PATTERN, "<num>");
+	normalized = normalized.replace(/\s+/g, " ").trim();
+	return truncateUtf8(normalized, MESSAGE_CLASS_MAX_BYTES);
+}
+
+interface ParsedFrame {
+	readonly functionName: string;
+	readonly location: string;
+}
+
+function parseStackFrame(line: string): ParsedFrame | undefined {
+	const trimmed = line.trim();
+	const atMatch = /^at\s+(.*)$/.exec(trimmed);
+	if (!atMatch) return undefined;
+	const rest = atMatch[1] ?? "";
+	const parenIndex = rest.lastIndexOf(" (");
+	let functionName = "<anonymous>";
+	let location = rest;
+	if (parenIndex >= 0 && rest.endsWith(")")) {
+		functionName = rest.slice(0, parenIndex).trim();
+		location = rest.slice(parenIndex + 2, -1).trim();
+	}
+	if (!location) return undefined;
+	return { functionName, location };
+}
+
+function stripLocation(location: string): string {
+	let value = location;
+	if (value.startsWith("file://")) value = Bun.fileURLToPath(value);
+	// Drop `:line:col` / `:line` suffixes: they churn on every release.
+	value = value.replace(/:\d+(?::\d+)?$/, "");
+	return value;
+}
+
+function normalizeFunctionName(name: string): string {
+	let value = name.replace(/^(?:async|new)\s+/, "").trim();
+	value = value.replace(/\s+\[as\s+[^\]]+\]$/, "");
+	if (!value || value === "<anonymous>") return "<anonymous>";
+	return value;
+}
+
+function relativizeInApp(location: string, installRoot: string): string | undefined {
+	const normalized = normalizeSeparators(location);
+	if (!normalized || normalized === "native" || normalized === "<anonymous>") return undefined;
+	if (/^(?:node|bun):/.test(normalized)) return undefined;
+	if (/(?:^|\/)node_modules\//.test(normalized)) return undefined;
+	// Compiled-binary frames: posix `/$bunfs/root/...` and windows `B:\~BUN\root\...`.
+	const bunfs = /^(?:[A-Za-z]:\/~BUN|\/\$bunfs)\/root\/(.*)$/.exec(normalized);
+	if (bunfs) return bunfs[1] ?? undefined;
+	const root = normalizeSeparators(installRoot).replace(/\/+$/, "");
+	if (root.length > 0 && normalized.startsWith(`${root}/`)) return normalized.slice(root.length + 1);
+	return undefined;
+}
+
+/**
+ * Normalized in-app frames, newest first, capped at three.
+ *
+ * A frame is `<install-root-relative path>#<function>` with no line or column
+ * numbers. Stacks with no in-app frame yield the single literal
+ * `<no-app-frame>`; distinct roots can merge under that literal, which is an
+ * accepted and documented v1 property.
+ */
+export function normalizeCrashFrames(stack: string, options: CrashFingerprintOptions = {}): string[] {
+	const installRoot = options.installRoot ?? defaultInstallRoot();
+	const frames: string[] = [];
+	for (const line of stack.split("\n")) {
+		if (frames.length >= MAX_FRAMES) break;
+		const parsed = parseStackFrame(line);
+		if (!parsed) continue;
+		const relative = relativizeInApp(stripLocation(parsed.location), installRoot);
+		if (relative === undefined) continue;
+		frames.push(truncateUtf8(`${relative}#${normalizeFunctionName(parsed.functionName)}`, FRAME_MAX_BYTES));
+	}
+	return frames.length > 0 ? frames : [NO_APP_FRAME];
+}
+
+function canonicalSerialization(fields: readonly string[]): Buffer {
+	const parts: Buffer[] = [];
+	for (const field of fields) {
+		const bytes = Buffer.from(field, "utf8");
+		parts.push(Buffer.from(`${bytes.byteLength}:`, "utf8"), bytes);
+	}
+	return Buffer.concat(parts);
+}
+
+function computeFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions,
+	includeMessage: boolean,
+): CrashFingerprint {
+	const errorName = truncateUtf8(normalizeCrashMessage(input.name, options) || "Error", 128);
+	const messageClass = normalizeCrashMessage(input.message, options);
+	const frames = normalizeCrashFrames(input.stack, options);
+	const identity = includeMessage
+		? ["skc-crash-fp.v1", errorName, messageClass, ...frames]
+		: ["skc-crash-fp.v1", "handled", errorName, frames[0] ?? NO_APP_FRAME];
+	const digest = createHash("sha256").update(canonicalSerialization(identity)).digest();
+	return {
+		fingerprint: digest.subarray(0, CRASH_FINGERPRINT_HEX_LENGTH / 2).toString("hex"),
+		version: CRASH_FINGERPRINT_VERSION,
+		errorName,
+		messageClass,
+		frames,
+	};
+}
+
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export function computeCrashFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, true);
+}
+
+/**
+ * Compute the stable identity used for a handled tool error.
+ *
+ * Tool failures often carry command output or other per-occurrence detail in
+ * their message. That text is useful in the record body but is not the failure
+ * identity: handled errors group by error class and the first in-app frame
+ * where the failure originated, rather than the full wrapper stack.
+ */
+export function computeHandledErrorFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	return computeFingerprint(input, options, false);
+}
+
+/** The machine-readable identity line appended to every new crash record. */
+export function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string {
+	return `${CRASH_RECORD_MARKER} fp:${fingerprint} fpv:${version} id:${recordId}`;
+}
+
+export interface CrashRecordMarker {
+	readonly fingerprint: string;
+	readonly version: number;
+	readonly recordId: string;
+}
+
+/**
+ * Parse an identity line. Records written before this feature carry no marker
+ * and are therefore `unmatchable`: this parser never guesses at them.
+ */
+export function parseCrashRecordMarker(line: string): CrashRecordMarker | undefined {
+	const match = new RegExp(`^${CRASH_RECORD_MARKER} fp:([0-9a-f]{32}) fpv:(\\d{1,3}) id:([0-9a-f]{8,32})$`).exec(
+		line.trim(),
+	);
+	if (!match) return undefined;
+	const version = Number(match[2]);
+	if (!Number.isSafeInteger(version) || version < 1) return undefined;
+	return { fingerprint: match[1] as string, version, recordId: match[3] as string };
+}

package/src/crash-journal.ts

@@ -0,0 +1,292 @@
+/**
+ * Append-only crash event journal.
+ *
+ * The fatal path is the most hostile place in the process: it runs while the
+ * program is already broken, possibly out of disk, possibly re-entered by a
+ * crash inside the crash handler. So the fatal path does exactly one thing
+ * here — append a single bounded line with `O_APPEND` — and never parses,
+ * locks, renames or reads. Aggregation into `skc-crash-index.json` happens at
+ * the next startup, under a cross-process lock, far away from the fatal path.
+ *
+ * The journal, not the index, is the source of increments: a lost index can be
+ * rebuilt from journal events, and concurrent compactors cannot drop counts.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CRASH_FINGERPRINT_PATTERN } from "./crash-fingerprint";
+
+/** Hard cap for one journal line, including its newline. */
+export const CRASH_EVENT_MAX_BYTES = 512;
+/** Journal line format tag. */
+export const CRASH_EVENT_KIND = "skc-crash-event.v1";
+/** Preview cap for the message class carried by an event. */
+export const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
+
+/** Bounded execution provenance carried only on newly written occurrences. */
+export type CrashProvenance = "product" | "eval" | "bun_test";
+
+/**
+ * Classify only process-level harness modes that are explicit and stable.
+ * Everything else is product provenance, including source checkouts, CLI
+ * invocations, SDK/ACP hosts, and native-loader failures.
+ */
+export function detectCrashProvenance(
+	argv: readonly string[] = process.argv,
+	env: NodeJS.ProcessEnv = process.env,
+	execArgv: readonly string[] = process.execArgv,
+): CrashProvenance {
+	if (env.BUN_TEST !== undefined) return "bun_test";
+	if (execArgv[0] === "-e" || execArgv[0] === "--eval" || argv[0] === "-e" || argv[0] === "--eval") return "eval";
+	return "product";
+}
+
+export type CrashEvent =
+	| CrashOccurrenceEvent
+	| CrashRefusedEvent
+	| CrashReportedEvent
+	| CrashRelayedEvent
+	| CrashAcknowledgedEvent
+	| CrashNudgedEvent;
+
+export interface CrashOccurrenceEvent {
+	readonly kind: "occurrence";
+	readonly fingerprint: string;
+	readonly fpv: number;
+	readonly recordId: string;
+	readonly at: number;
+	readonly errorName: string;
+	readonly messageClass: string;
+	/** Legacy events omit this and are treated as product crashes. */
+	readonly provenance?: CrashProvenance;
+}
+
+export interface CrashRefusedEvent {
+	readonly kind: "refused";
+	readonly fingerprint: string;
+	readonly fpv: number;
+	readonly recordId: string;
+	readonly contractVersion: string;
+	readonly at: number;
+}
+
+export interface CrashReportedEvent {
+	readonly kind: "reported";
+	readonly fingerprint: string;
+	readonly at: number;
+	readonly issueUrl: string;
+	/** Set when the submission was a "+1" comment rather than a new issue. */
+	readonly commented?: boolean;
+}
+
+export interface CrashRelayedEvent {
+	readonly kind: "relayed";
+	readonly fingerprint: string;
+	readonly at: number;
+	/** Sentry event id accepted upstream: 32 lowercase hex. */
+	readonly eventId: string;
+	/** Exact occurrence record represented by the accepted envelope. Absent on legacy pre-record-id relay lines. */
+	readonly recordId?: string;
+}
+
+export interface CrashAcknowledgedEvent {
+	readonly kind: "acknowledged";
+	readonly fingerprint: string;
+	readonly at: number;
+}
+
+export interface CrashNudgedEvent {
+	readonly kind: "nudged";
+	readonly at: number;
+}
+
+function truncateUtf8(text: string, maxBytes: number): string {
+	if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+	const bytes = Buffer.from(text, "utf8");
+	let end = maxBytes;
+	while (end > 0 && (bytes[end - 1] & 0xc0) === 0x80) end--;
+	if (end > 0 && bytes[end - 1] >= 0xc0) end--;
+	return bytes.subarray(0, end).toString("utf8");
+}
+
+/** Strip control characters so one event line can never contain a newline. */
+function sanitizeEventText(text: string): string {
+	return text.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ");
+}
+
+/**
+ * Serialize one event to a single journal line (newline included), bounded to
+ * `CRASH_EVENT_MAX_BYTES`. Oversized message previews are shortened, and if the
+ * line still does not fit the preview is dropped entirely rather than the event.
+ */
+export function formatCrashEventLine(event: CrashEvent): string {
+	const build = (messageClass?: string): string => {
+		const body: Record<string, unknown> =
+			event.kind === "occurrence"
+				? {
+						k: "occurrence",
+						fp: event.fingerprint,
+						fpv: event.fpv,
+						id: event.recordId,
+						at: event.at,
+						n: sanitizeEventText(truncateUtf8(event.errorName, 64)),
+						...(event.provenance && event.provenance !== "product" ? { p: event.provenance } : {}),
+						...(messageClass === undefined ? {} : { m: messageClass }),
+					}
+				: event.kind === "reported"
+					? {
+							k: "reported",
+							fp: event.fingerprint,
+							at: event.at,
+							u: sanitizeEventText(truncateUtf8(event.issueUrl, 256)),
+							...(event.commented ? { c: 1 } : {}),
+						}
+					: event.kind === "refused"
+						? {
+								k: "refused",
+								fp: event.fingerprint,
+								v: event.fpv,
+								r: event.recordId,
+								c: sanitizeEventText(truncateUtf8(event.contractVersion, 64)),
+								at: event.at,
+							}
+						: event.kind === "relayed"
+							? { k: "relayed", fp: event.fingerprint, at: event.at, e: event.eventId, r: event.recordId }
+							: event.kind === "acknowledged"
+								? { k: "acknowledged", fp: event.fingerprint, at: event.at }
+								: { k: "nudged", at: event.at };
+		return `${CRASH_EVENT_KIND} ${JSON.stringify(body)}\n`;
+	};
+
+	if (event.kind !== "occurrence") return truncateLine(build());
+	let preview = sanitizeEventText(truncateUtf8(event.messageClass, CRASH_EVENT_MESSAGE_MAX_BYTES));
+	let line = build(preview);
+	while (Buffer.byteLength(line, "utf8") > CRASH_EVENT_MAX_BYTES && preview.length > 0) {
+		preview = preview.slice(0, Math.floor(preview.length / 2));
+		line = build(preview);
+	}
+	if (Buffer.byteLength(line, "utf8") > CRASH_EVENT_MAX_BYTES) line = build();
+	return truncateLine(line);
+}
+
+/** Final safety net: an event line never exceeds the cap, even if malformed. */
+function truncateLine(line: string): string {
+	if (Buffer.byteLength(line, "utf8") <= CRASH_EVENT_MAX_BYTES) return line;
+	return `${truncateUtf8(line.trimEnd(), CRASH_EVENT_MAX_BYTES - 1)}\n`;
+}
+
+function isSafeTimestamp(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+/** Parse one journal line. Anything unexpected yields `undefined`, never a throw. */
+export function parseCrashEventLine(line: string): CrashEvent | undefined {
+	const trimmed = line.trim();
+	if (!trimmed.startsWith(`${CRASH_EVENT_KIND} `)) return undefined;
+	if (Buffer.byteLength(trimmed, "utf8") > CRASH_EVENT_MAX_BYTES) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(trimmed.slice(CRASH_EVENT_KIND.length + 1)) as unknown;
+	} catch {
+		return undefined;
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+	const body = parsed as Record<string, unknown>;
+	if (!isSafeTimestamp(body.at)) return undefined;
+	const at = body.at;
+	const fingerprint = typeof body.fp === "string" && CRASH_FINGERPRINT_PATTERN.test(body.fp) ? body.fp : undefined;
+
+	switch (body.k) {
+		case "occurrence": {
+			if (!fingerprint) return undefined;
+			if (typeof body.id !== "string" || !/^[0-9a-f]{8,32}$/.test(body.id)) return undefined;
+			if (typeof body.fpv !== "number" || !Number.isSafeInteger(body.fpv) || body.fpv < 1) return undefined;
+			const errorName = typeof body.n === "string" ? sanitizeEventText(body.n) : "Error";
+			const messageClass = typeof body.m === "string" ? sanitizeEventText(body.m) : "";
+			const provenance = body.p === undefined ? undefined : body.p;
+			if (provenance !== undefined && provenance !== "product" && provenance !== "eval" && provenance !== "bun_test")
+				return undefined;
+			return {
+				kind: "occurrence",
+				fingerprint,
+				fpv: body.fpv,
+				recordId: body.id,
+				at,
+				errorName,
+				messageClass,
+				...(provenance === undefined ? {} : { provenance }),
+			};
+		}
+		case "reported": {
+			if (!fingerprint) return undefined;
+			if (typeof body.u !== "string" || body.u.length === 0) return undefined;
+			return { kind: "reported", fingerprint, at, issueUrl: sanitizeEventText(body.u), commented: body.c === 1 };
+		}
+		case "refused": {
+			if (!fingerprint) return undefined;
+			if (typeof body.r !== "string" || !/^[0-9a-f]{8,32}$/.test(body.r)) return undefined;
+			if (typeof body.v !== "number" || !Number.isSafeInteger(body.v) || body.v < 1) return undefined;
+			if (typeof body.c !== "string" || body.c.length === 0 || /[\u0000-\u001f\u007f-\u009f]/.test(body.c))
+				return undefined;
+			return { kind: "refused", fingerprint, fpv: body.v, recordId: body.r, contractVersion: body.c, at };
+		}
+		case "relayed": {
+			if (!fingerprint) return undefined;
+			if (typeof body.e !== "string" || !/^[0-9a-f]{32}$/.test(body.e)) return undefined;
+			if (body.r !== undefined && (typeof body.r !== "string" || !/^[0-9a-f]{8,32}$/.test(body.r))) return undefined;
+			return {
+				kind: "relayed",
+				fingerprint,
+				at,
+				eventId: body.e,
+				...(typeof body.r === "string" ? { recordId: body.r } : {}),
+			};
+		}
+		case "acknowledged": {
+			if (!fingerprint) return undefined;
+			return { kind: "acknowledged", fingerprint, at };
+		}
+		case "nudged":
+			return { kind: "nudged", at };
+		default:
+			return undefined;
+	}
+}
+
+/**
+ * Append one event synchronously with `O_APPEND`. Never throws.
+ *
+ * No parse, no lock, no rename, no read: the only I/O is one bounded write to
+ * an append-only file, so concurrent writers interleave whole lines instead of
+ * corrupting each other's records.
+ */
+export function appendCrashEvent(event: CrashEvent, journalPath: string): boolean {
+	try {
+		const line = formatCrashEventLine(event);
+		fs.mkdirSync(path.dirname(journalPath), { recursive: true });
+		const fd = fs.openSync(journalPath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND, 0o600);
+		try {
+			fs.writeSync(fd, line);
+		} finally {
+			fs.closeSync(fd);
+		}
+		return true;
+	} catch {
+		// A failing journal write must never mask or delay the original fatal.
+		return false;
+	}
+}
+
+let fatalJournalLatched = false;
+
+/**
+ * Fatal-path entry point: at most one journal append per process lifetime.
+ *
+ * A crash raised while handling a crash must not spend the process's remaining
+ * moments on journal bookkeeping, so the latch is never cleared — the process
+ * is exiting anyway. Returns whether this call wrote a line.
+ */
+export function appendFatalCrashEvent(event: CrashEvent, journalPath: string): boolean {
+	if (fatalJournalLatched) return false;
+	fatalJournalLatched = true;
+	return appendCrashEvent(event, journalPath);
+}