@gajae-code/utils 0.13.3 → 0.14.0

package/dist/types/crash-fingerprint.d.ts

@@ -0,0 +1,73 @@
+/** Algorithm version recorded beside every emitted fingerprint. */
+export declare const CRASH_FINGERPRINT_VERSION = 1;
+/** Hex length of a published fingerprint (128 bits). */
+export declare const CRASH_FINGERPRINT_HEX_LENGTH = 32;
+/** Matches exactly a published fingerprint. */
+export declare const CRASH_FINGERPRINT_PATTERN: RegExp;
+/** Marker used for the machine-readable identity line of each crash record. */
+export declare const CRASH_RECORD_MARKER = "gjc-crash-record.v1";
+/** Marker embedded in an external issue body, outside crash-derived blocks. */
+export declare const CRASH_ISSUE_MARKER_PREFIX = "gjc-crash-fp.v1:";
+/** Literal frame used when a stack carries no in-app frame at all. */
+export declare const NO_APP_FRAME = "<no-app-frame>";
+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 GJC install root. */
+    readonly installRoot?: string;
+    /** Home directory used for `<home>` substitution. Defaults to `os.homedir()`. */
+    readonly homeDir?: string;
+}
+/**
+ * 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 declare function replaceAbsolutePaths(text: string, homeDir?: string): string;
+/**
+ * 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 declare function normalizeCrashMessage(message: string, options?: CrashFingerprintOptions): string;
+/**
+ * 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 declare function normalizeCrashFrames(stack: string, options?: CrashFingerprintOptions): string[];
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export declare function computeCrashFingerprint(input: CrashFingerprintInput, options?: CrashFingerprintOptions): CrashFingerprint;
+/** The machine-readable identity line appended to every new crash record. */
+export declare function formatCrashRecordMarker(fingerprint: string, version: number, recordId: string): string;
+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 declare function parseCrashRecordMarker(line: string): CrashRecordMarker | undefined;

package/dist/types/crash-journal.d.ts

@@ -0,0 +1,57 @@
+/** Hard cap for one journal line, including its newline. */
+export declare const CRASH_EVENT_MAX_BYTES = 512;
+/** Journal line format tag. */
+export declare const CRASH_EVENT_KIND = "gjc-crash-event.v1";
+/** Preview cap for the message class carried by an event. */
+export declare const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
+export type CrashEvent = CrashOccurrenceEvent | CrashReportedEvent | 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;
+}
+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 CrashAcknowledgedEvent {
+    readonly kind: "acknowledged";
+    readonly fingerprint: string;
+    readonly at: number;
+}
+export interface CrashNudgedEvent {
+    readonly kind: "nudged";
+    readonly at: number;
+}
+/**
+ * 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 declare function formatCrashEventLine(event: CrashEvent): string;
+/** Parse one journal line. Anything unexpected yields `undefined`, never a throw. */
+export declare function parseCrashEventLine(line: string): CrashEvent | 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 declare function appendCrashEvent(event: CrashEvent, journalPath: string): boolean;
+/**
+ * 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 declare function appendFatalCrashEvent(event: CrashEvent, journalPath: string): boolean;

package/dist/types/crash-redaction.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Best-effort credential scrubbing for durable crash records.
+ *
+ * This is a *persistence-time* scrub: it keeps obvious credential shapes out of
+ * a file GJC keeps indefinitely. It is explicitly NOT a privacy guarantee and
+ * must never be treated as one for data that leaves the machine — outbound
+ * text goes through `sanitizeExternalCrashV1` instead.
+ */
+/**
+ * Scrub credential material from crash text before it is persisted.
+ * Covers bearer/basic-style headers, key=value or JSON key forms of common
+ * credential names, and well-known vendor token shapes. Normal messages and
+ * stack frames are untouched; matches are replaced in place so surrounding
+ * diagnostic context survives.
+ */
+export declare function redactCrashSecrets(text: string): string;
+/** Every placeholder `redactCrashSecrets` can emit. Used by downstream normalizers. */
+export declare const CRASH_REDACTION_MARKERS: readonly string[];

package/dist/types/dirs.d.ts

@@ -35,6 +35,11 @@ export declare function formatBunRuntimeError(opts: {
     execPath?: string;
     platform?: NodeJS.Platform;
 }): string;
+/**
+ * On macOS, strip /private prefix only when both paths resolve to the same location.
+ * This preserves aliases like /private/tmp -> /tmp without rewriting unrelated paths.
+ */
+export declare function standardizeMacOSPath(p: string): string;
 export declare function resolveEquivalentPath(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string, platform?: NodeJS.Platform): string;
 /** Return whether a relative path crosses above its root or is unexpectedly absolute. */
@@ -113,6 +118,8 @@ export declare function getGpuCachePath(): string;
  * cache file without touching the rest of the config root.
  */
 export declare function getGithubCacheDbPath(): string;
+/** Get the durable tool-choice capability cache path. */
+export declare function getToolChoiceCapabilityCachePath(): string;
 /** Get the natives directory (~/.gjc/natives). */
 export declare function getNativesDir(): string;
 /** Get the stats database path (~/.gjc/stats.db). */
@@ -155,6 +162,10 @@ export declare function getMemoriesDir(agentDir?: string): string;
 export declare function getTerminalSessionsDir(agentDir?: string): string;
 /** Get the crash log path (~/.gjc/agent/gjc-crash.log). */
 export declare function getCrashLogPath(agentDir?: string): string;
+/** Get the crash event journal path (~/.gjc/agent/gjc-crash-events.jsonl). */
+export declare function getCrashEventsPath(agentDir?: string): string;
+/** Get the compacted crash signature index path (~/.gjc/agent/gjc-crash-index.json). */
+export declare function getCrashIndexPath(agentDir?: string): string;
 /** Get the debug log path (~/.gjc/agent/gjc-debug.log). */
 export declare function getDebugLogPath(agentDir?: string): string;
 /** Get the project-level Python modules directory (.gjc/modules). */

package/dist/types/index.d.ts

@@ -2,6 +2,9 @@ export { createAbortableStream, once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./broken-pipe";
 export * from "./color";
+export * from "./crash-fingerprint";
+export * from "./crash-journal";
+export * from "./crash-redaction";
 export * from "./dirs";
 export * from "./env";
 export * from "./fetch-retry";

package/dist/types/postmortem.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Cleanup and postmortem handler utilities.
+ *
+ * This module provides a system for registering and running cleanup callbacks
+ * in response to process exit, signals, or fatal exceptions. It is intended to
+ * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
+ */
+import { redactCrashSecrets } from "./crash-redaction";
 export declare enum Reason {
     PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
     EXIT = "exit",// Normal process exit
@@ -16,6 +24,7 @@ export declare const CRASH_LOG_MAX_BYTES: number;
  * with a marker) before the append/reset decision.
  */
 export declare const CRASH_RECORD_MAX_BYTES: number;
+export { redactCrashSecrets };
 /**
  * Append a fatal-crash record to the dedicated, rotation-immune crash log
  * (`~/.gjc/agent/gjc-crash.log`).
@@ -29,10 +38,11 @@ export declare const CRASH_RECORD_MAX_BYTES: number;
  * original fatal) and uses synchronous IO so the record lands before
  * `process.exit`. Returns the path written, or `undefined` on failure.
  */
-export declare function recordFatalCrash(label: string, reason: unknown, options?: {
+export declare function recordFatalCrash(label: string, reason: unknown, options?: CrashRecordOptions): string | undefined;
+interface CrashRecordOptions {
     path?: string;
     now?: Date;
-}): string | undefined;
+}
 /**
  * Register a process cleanup callback, to be run on shutdown, signal, or fatal error.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.13.3",
+	"version": "0.14.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.13.3",
+		"@gajae-code/natives": "0.14.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/crash-fingerprint.ts

@@ -0,0 +1,270 @@
+/**
+ * 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:
+ *
+ *     "gjc-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 = "gjc-crash-record.v1";
+/** Marker embedded in an external issue body, outside crash-derived blocks. */
+export const CRASH_ISSUE_MARKER_PREFIX = "gjc-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 GJC 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);
+}
+
+/** Compute the v1 fingerprint of an already-captured fatal diagnostic. */
+export function computeCrashFingerprint(
+	input: CrashFingerprintInput,
+	options: CrashFingerprintOptions = {},
+): CrashFingerprint {
+	const errorName = truncateUtf8(normalizeCrashMessage(input.name, options) || "Error", 128);
+	const messageClass = normalizeCrashMessage(input.message, options);
+	const frames = normalizeCrashFrames(input.stack, options);
+	const digest = createHash("sha256")
+		.update(canonicalSerialization(["gjc-crash-fp.v1", errorName, messageClass, ...frames]))
+		.digest();
+	return {
+		fingerprint: digest.subarray(0, CRASH_FINGERPRINT_HEX_LENGTH / 2).toString("hex"),
+		version: CRASH_FINGERPRINT_VERSION,
+		errorName,
+		messageClass,
+		frames,
+	};
+}
+
+/** 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,203 @@
+/**
+ * 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 `gjc-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 = "gjc-crash-event.v1";
+/** Preview cap for the message class carried by an event. */
+export const CRASH_EVENT_MESSAGE_MAX_BYTES = 256;
+
+export type CrashEvent = CrashOccurrenceEvent | CrashReportedEvent | 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;
+}
+
+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 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)),
+						...(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 === "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) : "";
+			return { kind: "occurrence", fingerprint, fpv: body.fpv, recordId: body.id, at, errorName, messageClass };
+		}
+		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 "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);
+}

package/src/crash-redaction.ts

@@ -0,0 +1,51 @@
+/**
+ * Best-effort credential scrubbing for durable crash records.
+ *
+ * This is a *persistence-time* scrub: it keeps obvious credential shapes out of
+ * a file GJC keeps indefinitely. It is explicitly NOT a privacy guarantee and
+ * must never be treated as one for data that leaves the machine — outbound
+ * text goes through `sanitizeExternalCrashV1` instead.
+ */
+
+/**
+ * Scrub credential material from crash text before it is persisted.
+ * Covers bearer/basic-style headers, key=value or JSON key forms of common
+ * credential names, and well-known vendor token shapes. Normal messages and
+ * stack frames are untouched; matches are replaced in place so surrounding
+ * diagnostic context survives.
+ */
+export function redactCrashSecrets(text: string): string {
+	let redacted = text;
+	redacted = redacted.replace(/\b(?:Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "«redacted-auth»");
+	redacted = redacted.replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "«redacted-jwt»");
+	redacted = redacted.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "«redacted-api-key»");
+	// `gh[opsur]_` covers the classic PAT/OAuth/server/user/refresh prefixes;
+	// fine-grained PATs use an entirely different `github_pat_` prefix and would
+	// otherwise survive into a log the module keeps indefinitely.
+	redacted = redacted.replace(/\bgh[opsur]_[A-Za-z0-9]{16,}\b/g, "«redacted-github-token»");
+	redacted = redacted.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "«redacted-github-token»");
+	redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g, "«redacted-slack-token»");
+	// AKIA is the long-term access key id; ASIA is the temporary/STS one, which is
+	// the shape that actually shows up in a crashed request. The id alone is not
+	// the credential: an STS payload carries `SecretAccessKey` and `SessionToken`
+	// alongside it, so the labeled-value rule below must name both. `secret_key`
+	// does not match `SecretAccessKey` (the canonical field has `Access` in the
+	// middle), and `access_token` does not match `SessionToken`.
+	redacted = redacted.replace(/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, "«redacted-aws-key»");
+	redacted = redacted.replace(
+		/(?<![A-Za-z0-9_])(["']?(?:api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?token|client[_-]?secret|secret[_-]?key|secret[_-]?access[_-]?key|password|passwd|authorization)["']?\s*[=:]\s*["']?)[^\s"',;}\]]{8,}/gi,
+		"$1«redacted»",
+	);
+	return redacted;
+}
+
+/** Every placeholder `redactCrashSecrets` can emit. Used by downstream normalizers. */
+export const CRASH_REDACTION_MARKERS: readonly string[] = [
+	"«redacted-auth»",
+	"«redacted-jwt»",
+	"«redacted-api-key»",
+	"«redacted-github-token»",
+	"«redacted-slack-token»",
+	"«redacted-aws-key»",
+	"«redacted»",
+];

package/src/dirs.ts

@@ -90,7 +90,7 @@ export function formatBunRuntimeError(opts: {
  * On macOS, strip /private prefix only when both paths resolve to the same location.
  * This preserves aliases like /private/tmp -> /tmp without rewriting unrelated paths.
  */
-function standardizeMacOSPath(p: string): string {
+export function standardizeMacOSPath(p: string): string {
 	if (process.platform !== "darwin" || !p.startsWith("/private/")) return p;
 	const stripped = p.slice("/private".length);
 	try {
@@ -487,6 +487,11 @@ export function getGithubCacheDbPath(): string {
 	return dirs.rootSubdir(path.join("cache", "github-cache.db"), "cache");
 }
 
+/** Get the durable tool-choice capability cache path. */
+export function getToolChoiceCapabilityCachePath(): string {
+	return dirs.rootSubdir(path.join("cache", "tool-choice-capabilities.db"), "cache");
+}
+
 /** Get the natives directory (~/.gjc/natives). */
 export function getNativesDir(): string {
 	return dirs.rootSubdir("natives", "cache");
@@ -596,6 +601,16 @@ export function getCrashLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "gjc-crash.log", "state");
 }
 
+/** Get the crash event journal path (~/.gjc/agent/gjc-crash-events.jsonl). */
+export function getCrashEventsPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "gjc-crash-events.jsonl", "state");
+}
+
+/** Get the compacted crash signature index path (~/.gjc/agent/gjc-crash-index.json). */
+export function getCrashIndexPath(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "gjc-crash-index.json", "state");
+}
+
 /** Get the debug log path (~/.gjc/agent/gjc-debug.log). */
 export function getDebugLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, `${APP_NAME}-debug.log`, "state");

package/src/index.ts

@@ -2,6 +2,9 @@ export { createAbortableStream, once, untilAborted } from "./abortable";
 export * from "./async";
 export * from "./broken-pipe";
 export * from "./color";
+export * from "./crash-fingerprint";
+export * from "./crash-journal";
+export * from "./crash-redaction";
 export * from "./dirs";
 export * from "./env";
 export * from "./fetch-retry";

package/src/postmortem.ts

@@ -5,12 +5,17 @@
  * in response to process exit, signals, or fatal exceptions. It is intended to
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
+
+import { randomBytes } from "node:crypto";
 import * as fs from "node:fs";
 import inspector from "node:inspector";
 import * as path from "node:path";
 import { isMainThread } from "node:worker_threads";
 import { BROKEN_PIPE_EXIT_CODE, createProcessStdoutEpipeClassifier } from "./broken-pipe";
-import { getCrashLogPath } from "./dirs";
+import { computeCrashFingerprint, formatCrashRecordMarker } from "./crash-fingerprint";
+import { appendFatalCrashEvent } from "./crash-journal";
+import { redactCrashSecrets } from "./crash-redaction";
+import { getCrashEventsPath, getCrashLogPath } from "./dirs";
 import * as logger from "./logger";
 import { safeStderrWrite } from "./safe-stderr";
 
@@ -406,47 +411,17 @@ export const CRASH_LOG_MAX_BYTES = 512 * 1024;
 export const CRASH_RECORD_MAX_BYTES = 64 * 1024;
 const CRASH_RECORD_TRUNCATION_MARKER = "\n… [crash record truncated]\n\n";
 
-/**
- * Best-effort scrub of credential material from a crash record before it is
- * persisted indefinitely. Covers bearer/basic-style headers, key=value or
- * JSON key forms of common credential names, and well-known vendor token
- * shapes. Normal messages and stack frames are untouched; matches are
- * replaced in place so surrounding diagnostic context survives.
- */
-function redactCrashSecrets(text: string): string {
-	let redacted = text;
-	redacted = redacted.replace(/\b(?:Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}/gi, "«redacted-auth»");
-	redacted = redacted.replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "«redacted-jwt»");
-	redacted = redacted.replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, "«redacted-api-key»");
-	// `gh[opsur]_` covers the classic PAT/OAuth/server/user/refresh prefixes;
-	// fine-grained PATs use an entirely different `github_pat_` prefix and would
-	// otherwise survive into a log the module keeps indefinitely.
-	redacted = redacted.replace(/\bgh[opsur]_[A-Za-z0-9]{16,}\b/g, "«redacted-github-token»");
-	redacted = redacted.replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "«redacted-github-token»");
-	redacted = redacted.replace(/\bxox[baprs]-[A-Za-z0-9-]{8,}\b/g, "«redacted-slack-token»");
-	// AKIA is the long-term access key id; ASIA is the temporary/STS one, which is
-	// the shape that actually shows up in a crashed request. The id alone is not
-	// the credential: an STS payload carries `SecretAccessKey` and `SessionToken`
-	// alongside it, so the labeled-value rule below must name both. `secret_key`
-	// does not match `SecretAccessKey` (the canonical field has `Access` in the
-	// middle), and `access_token` does not match `SessionToken`.
-	redacted = redacted.replace(/\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g, "«redacted-aws-key»");
-	redacted = redacted.replace(
-		/(?<![A-Za-z0-9_])(["']?(?:api[_-]?key|apikey|access[_-]?token|refresh[_-]?token|id[_-]?token|session[_-]?token|client[_-]?secret|secret[_-]?key|secret[_-]?access[_-]?key|password|passwd|authorization)["']?\s*[=:]\s*["']?)[^\s"',;}\]]{8,}/gi,
-		"$1«redacted»",
-	);
-	return redacted;
-}
+export { redactCrashSecrets };
 
 /**
- * Bound one record to CRASH_RECORD_MAX_BYTES without splitting a UTF-8
- * sequence. Keeps the header (timestamp/label/message) at the front, where
- * the diagnostic value is highest.
+ * Bound one record to `maxBytes` without splitting a UTF-8 sequence. Keeps the
+ * header (timestamp/label/message) at the front, where the diagnostic value is
+ * highest.
  */
-function boundCrashRecord(report: string): string {
-	if (Buffer.byteLength(report, "utf8") <= CRASH_RECORD_MAX_BYTES) return report;
+function boundCrashRecord(report: string, maxBytes: number = CRASH_RECORD_MAX_BYTES): string {
+	if (Buffer.byteLength(report, "utf8") <= maxBytes) return report;
 	const bytes = Buffer.from(report, "utf8");
-	const budget = CRASH_RECORD_MAX_BYTES - Buffer.byteLength(CRASH_RECORD_TRUNCATION_MARKER, "utf8");
+	const budget = maxBytes - Buffer.byteLength(CRASH_RECORD_TRUNCATION_MARKER, "utf8");
 	let end = budget;
 	// Drop trailing continuation bytes of a truncated multi-byte sequence.
 	while (end > 0 && (bytes[end - 1] & 0xc0) === 0x80) end--;
@@ -468,29 +443,35 @@ function boundCrashRecord(report: string): string {
  * original fatal) and uses synchronous IO so the record lands before
  * `process.exit`. Returns the path written, or `undefined` on failure.
  */
-export function recordFatalCrash(
-	label: string,
-	reason: unknown,
-	options: { path?: string; now?: Date } = {},
-): string | undefined {
+export function recordFatalCrash(label: string, reason: unknown, options: CrashRecordOptions = {}): string | undefined {
 	return writeCrashRecord(label, describeFatal(reason), options);
 }
 
-function writeCrashRecord(
-	label: string,
-	fatal: FatalDiagnostic,
-	options: { path?: string; now?: Date } = {},
-): string | undefined {
+interface CrashRecordOptions {
+	path?: string;
+	now?: Date;
+}
+
+function writeCrashRecord(label: string, fatal: FatalDiagnostic, options: CrashRecordOptions = {}): string | undefined {
 	try {
 		const target = options.path ?? getCrashLogPath();
 		const now = options.now ?? new Date();
 		const stack = fatal.stack ? `${redactCrashSecrets(fatal.stack)}\n` : "";
 		const payload = fatal.payload ? `${redactCrashSecrets(fatal.payload)}\n` : "";
-		const report = boundCrashRecord(
+		// Identity is computed from the already-captured diagnostic text only; the
+		// throwable is never read again here.
+		const fingerprint = computeCrashFingerprint(fatal);
+		const recordId = randomBytes(8).toString("hex");
+		const markerLine = `${formatCrashRecordMarker(fingerprint.fingerprint, fingerprint.version, recordId)}\n`;
+		// The marker is the record's identity, so it is budgeted first and appended
+		// after truncation: an oversized body can never evict it.
+		const body = boundCrashRecord(
 			`${now.toISOString()} pid=${process.pid} [${label}] ` +
 				`${redactCrashSecrets(fatal.name)}: ${redactCrashSecrets(fatal.message)}\n` +
-				`${stack}${payload}\n`,
+				`${stack}${payload}`,
+			CRASH_RECORD_MAX_BYTES - Buffer.byteLength(markerLine, "utf8") - 1,
 		);
+		const report = `${body}${markerLine}\n`;
 		fs.mkdirSync(path.dirname(target), { recursive: true });
 		let existingSize = 0;
 		try {
@@ -508,6 +489,25 @@ function writeCrashRecord(
 		try {
 			fs.chmodSync(target, 0o600);
 		} catch {}
+		// The journal always lives beside the crash log it describes, so an
+		// overridden crash-log path (tests, alternate agent dirs) keeps its events
+		// in the same scope instead of leaking into the user's agent dir.
+		const eventsPath =
+			options.path === undefined
+				? getCrashEventsPath()
+				: path.join(path.dirname(target), path.basename(getCrashEventsPath()));
+		appendFatalCrashEvent(
+			{
+				kind: "occurrence",
+				fingerprint: fingerprint.fingerprint,
+				fpv: fingerprint.version,
+				recordId,
+				at: now.getTime(),
+				errorName: fingerprint.errorName,
+				messageClass: fingerprint.messageClass,
+			},
+			eventsPath,
+		);
 		return target;
 	} catch {
 		return undefined;