Install real crash handlers so a detached throw terminates the process

process.on("uncaughtException"/"unhandledRejection") now write a best-effort
crash report to ~/.corbits/projects/<slug>/errors/<timestamp>.txt and exit
non-zero, matching what docs/IMPLEMENTATION.md already documented but the
code never implemented. OpenTUI's own log-only handler for the same events
still runs, but Node invokes every registered listener, so ours still exits
the process afterward.

Author: TheGreatAxios

src/crash/report.test.ts

@@ -0,0 +1,43 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { crashReportDir, writeCrashReport } from "./report.js";
+
+let home: string | undefined;
+
+afterEach(async () => {
+  if (home !== undefined) {
+    await rm(home, { recursive: true, force: true });
+    home = undefined;
+  }
+});
+
+describe("writeCrashReport", () => {
+  test("writes a report under ~/.corbits/projects/<slug>/errors/", async () => {
+    home = await mkdtemp(join(tmpdir(), "corbits-crash-"));
+    const cwd = "/Users/dev/some project!!";
+    const file = await writeCrashReport("uncaughtException", new Error("boom"), cwd, home);
+
+    expect(file).not.toBeNull();
+    const dir = crashReportDir(cwd, home);
+    const entries = await readdir(dir);
+    expect(entries).toHaveLength(1);
+
+    const body = await readFile(join(dir, entries[0]!), "utf8");
+    expect(body).toContain("kind: uncaughtException");
+    expect(body).toContain(`cwd: ${cwd}`);
+    expect(body).toContain("boom");
+  });
+
+  test("returns null instead of throwing when the report cannot be written", async () => {
+    // A path segment that is a file, not a directory, makes mkdir fail.
+    home = await mkdtemp(join(tmpdir(), "corbits-crash-"));
+    const blockerParent = join(home, ".corbits", "projects");
+    await Bun.write(join(home, ".corbits"), "not a directory");
+    const file = await writeCrashReport("unhandledRejection", "oops", "/whatever", home);
+    expect(file).toBeNull();
+    void blockerParent;
+  });
+});

src/crash/report.ts

@@ -0,0 +1,46 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { SETTINGS_DIR_NAME } from "../branding.js";
+
+export type CrashKind = "uncaughtException" | "unhandledRejection";
+
+// Deliberately independent of session/project-key.ts: a crash can happen
+// before config or git discovery ever runs, so this slug is just the raw cwd
+// with non-alphanumeric runs collapsed, not the hashed project key.
+function slugifyCwd(cwd: string): string {
+  const slug = cwd.replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug.length > 0 ? slug : "project";
+}
+
+export function crashReportDir(cwd: string, home: string = homedir()): string {
+  return join(home, SETTINGS_DIR_NAME, "projects", slugifyCwd(cwd), "errors");
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? (error.stack ?? error.message) : String(error);
+}
+
+/**
+ * Best-effort crash report writer. Failures here must never mask the
+ * original crash, so every I/O error is swallowed and reported as null.
+ */
+export async function writeCrashReport(
+  kind: CrashKind,
+  error: unknown,
+  cwd: string = process.cwd(),
+  home: string = homedir(),
+): Promise<string | null> {
+  try {
+    const dir = crashReportDir(cwd, home);
+    await mkdir(dir, { recursive: true });
+    const now = new Date();
+    const file = join(dir, `${now.toISOString().replace(/[:.]/g, "-")}.txt`);
+    const body = `kind: ${kind}\ntime: ${now.toISOString()}\ncwd: ${cwd}\n\n${describeError(error)}\n`;
+    await writeFile(file, body, "utf8");
+    return file;
+  } catch {
+    return null;
+  }
+}

src/index.ts

@@ -1,5 +1,6 @@
 import { getLogger } from "@intx/log";
 import { LOG_NAMESPACE_ROOT } from "./branding.js";
+import { writeCrashReport, type CrashKind } from "./crash/report.js";
 import { loadConfig } from "./config/index.js";
 import { ensureTelemetrySettings, globalSettingsPath } from "./config/settings.js";
 import { flushPerfToOtel } from "./perf/index.js";
@@ -100,13 +101,31 @@ export async function main(argv: readonly string[]): Promise<number> {
   });
 }
 
+async function handleFatal(kind: CrashKind, error: unknown): Promise<void> {
+  process.stderr.write(`${kind}: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+  const file = await writeCrashReport(kind, error);
+  if (file !== null) {
+    process.stderr.write(`crash report written to ${file}\n`);
+  }
+  process.exit(1);
+}
+
 if (import.meta.main) {
-  // OpenTUI installs a process-global uncaughtException handler that only
-  // logs, which suppresses Bun's default print-and-exit. Combined with
-  // raw-mode stdin holding the event loop open, an escaped throw would
-  // otherwise hang the process forever with the terminal still in the
-  // alternate screen. Exiting explicitly here is the backstop for throws that
-  // originate outside runTUI's own crash path.
+  // OpenTUI installs a process-global uncaughtException/unhandledRejection
+  // handler that only logs (opentui/core's Renderer.handleError), which
+  // suppresses Bun's default print-and-exit. Combined with raw-mode stdin
+  // holding the event loop open, an escaped throw would otherwise hang the
+  // process forever with the terminal still in the alternate screen. Node
+  // invokes every registered listener for the event regardless of order, so
+  // these still run and terminate the process even though OpenTUI's own
+  // listener never exits or rethrows.
+  process.on("uncaughtException", (err) => {
+    void handleFatal("uncaughtException", err);
+  });
+  process.on("unhandledRejection", (reason) => {
+    void handleFatal("unhandledRejection", reason);
+  });
+
   let code: number;
   try {
     code = await main(process.argv.slice(2));