Finalize run.json when the process crashes

Process-level uncaughtException/unhandledRejection handlers wrote a
crash report but left run.json stuck at status: running, so crashed
sessions kept reappearing in the resume picker as in-progress.

runTUI now registers a narrow handle (session id, cwd, active flag)
in a module-level slot the moment a run starts, clearing it on any
finalize path it already owns. The top-level crash handler reads that
slot and writes status: crashed plus finishedAt through a new
saveCrashState that bypasses the per-session write chain entirely, so
a write that never settles can't block process.exit.

Author: TheGreatAxios

src/index.ts

@@ -1,6 +1,8 @@
 import { getLogger } from "@intx/log";
 import { LOG_NAMESPACE_ROOT } from "./branding.js";
 import { primeCrashReporting, writeCrashReport, type CrashKind } from "./crash/report.js";
+import { getActiveRun } from "./session/active-run.js";
+import { loadState, saveCrashState } from "./session/state.js";
 import { loadConfig } from "./config/index.js";
 import { ensureTelemetrySettings, globalSettingsPath } from "./config/settings.js";
 import { flushPerfToOtel } from "./perf/index.js";
@@ -106,32 +108,69 @@ export async function main(argv: readonly string[]): Promise<number> {
   });
 }
 
-async function handleFatal(kind: CrashKind, error: unknown): Promise<void> {
+// Exported so an integration test can register these process-level handlers
+// and inject a crash without spawning the full TUI stack.
+export 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`);
   } else {
     process.stderr.write("failed to write crash report\n");
   }
+  await finalizeActiveRunOnCrash(error);
   process.exit(1);
 }
 
-if (import.meta.main) {
-  // 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.
+// A crash reaching here escaped without ever hitting runTUI's own try/catch
+// (e.g. a throw inside a fire-and-forget `void` call), so run.json was never
+// closed out. getActiveRun surfaces the in-flight session set by runTUI; the
+// write itself goes through saveCrashState, which bypasses the per-session
+// write chain in state.ts on purpose — chaining behind a write that never
+// settles (possibly the very write that triggered this crash) would block
+// process.exit indefinitely, defeating this handler's one job.
+async function finalizeActiveRunOnCrash(error: unknown): Promise<void> {
+  const run = getActiveRun();
+  if (run === null || !run.active) return;
+  const message = error instanceof Error ? error.message : String(error);
+  try {
+    const prior = await loadState(run.cwd, run.sessionId);
+    await saveCrashState(run.cwd, run.sessionId, {
+      status: "crashed",
+      turnsUsed: prior?.turnsUsed ?? 0,
+      task: prior?.task ?? "(conversation)",
+      startedAt: prior?.startedAt ?? Date.now(),
+      finishedAt: Date.now(),
+      error: message,
+      ...(prior?.model !== undefined ? { model: prior.model } : {}),
+      ...(prior?.mcpServers !== undefined ? { mcpServers: prior.mcpServers } : {}),
+    });
+  } catch (saveErr: unknown) {
+    process.stderr.write(
+      `failed to finalize run state after crash: ${saveErr instanceof Error ? saveErr.message : String(saveErr)}\n`,
+    );
+  }
+}
+
+// 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.
+export function installCrashHandlers(): void {
   process.on("uncaughtException", (err) => {
     void handleFatal("uncaughtException", err);
   });
   process.on("unhandledRejection", (reason) => {
     void handleFatal("unhandledRejection", reason);
   });
+}
+
+if (import.meta.main) {
+  installCrashHandlers();
 
   let code: number;
   try {

src/session/active-run.ts

@@ -0,0 +1,23 @@
+// A module-level slot the top-level uncaughtException/unhandledRejection
+// handler (src/index.ts) can reach even though persistRunSnapshot is a
+// closure local to runTUI. Only ever consulted from the crash path: a run
+// that never crashes never has this read.
+export type RunStateHandle = {
+  sessionId: string;
+  cwd: string;
+  active: boolean;
+};
+
+let activeRun: RunStateHandle | null = null;
+
+export function setActiveRun(handle: RunStateHandle): void {
+  activeRun = handle;
+}
+
+export function clearActiveRun(): void {
+  activeRun = null;
+}
+
+export function getActiveRun(): RunStateHandle | null {
+  return activeRun;
+}

src/session/state.ts

@@ -14,7 +14,7 @@ const ConnectedMcpServerSchema = type({
 export type ConnectedMcpServer = typeof ConnectedMcpServerSchema.infer;
 
 const RunStateSchema = type({
-  status: "'running' | 'done' | 'failed' | 'cancelled'",
+  status: "'running' | 'done' | 'failed' | 'cancelled' | 'crashed'",
   turnsUsed: "number",
   task: "string",
   startedAt: "number",
@@ -92,6 +92,22 @@ export async function saveState(
 }
 
 
+// Crash-time terminal write. Deliberately bypasses writeChains: a hung or
+// still-pending write for this session (possibly the very write mid-flight
+// when the process crashed) must never be awaited here, or a queued write
+// that never settles would block the crash handler's process.exit forever.
+// There is no later write to order against once the process is exiting, so
+// per-session ordering has nothing left to protect.
+export async function saveCrashState(
+  cwd: string,
+  sessionId: string,
+  state: RunState,
+  home?: string,
+): Promise<void> {
+  const path = statePath(cwd, sessionId, home);
+  await atomicWrite(path, JSON.stringify(state, null, 2));
+}
+
 // Returns the parsed state, or the arktype error summary when the shape is
 // invalid, so callers can surface a specific reason rather than "invalid shape".
 function parseRunState(data: unknown): RunState | { error: string } {

src/tui/runner.ts

@@ -161,6 +161,7 @@ import { createRunSink } from "../session/run-sink.js";
 import { generateSessionId, initSessionDir, renameSession, sessionContextDir, sessionDir } from "../session/index.js";
 import { resolveSessionLabel, truncateSessionLabel } from "../session/session-label.js";
 import { loadState, saveState, type ConnectedMcpServer, type RunState } from "../session/state.js";
+import { setActiveRun, clearActiveRun, type RunStateHandle } from "../session/active-run.js";
 import { openInBrowser } from "../auth/oauth/browser.js";
 import { pickSession } from "./pick-session.js";
 import { RESUME_TRANSCRIPT_BLOCK_LIMIT, turnsToContentBlocks } from "./turns-to-blocks.js";
@@ -468,6 +469,15 @@ export async function runTUI(initialConfig: Config): Promise<number> {
     mcpServers: resumeSeed.mcpServers,
   });
 
+  // Registered the moment a run starts so the top-level uncaughtException /
+  // unhandledRejection handler in index.ts (which cannot see any local state
+  // in this function) can finalize run.json for crashes that escape without
+  // ever reaching this function's own try/catch — e.g. a throw inside a
+  // fire-and-forget `void` call. Cleared wherever `finalized` below flips
+  // true, since those paths already write a terminal run.json themselves.
+  const activeRunHandle: RunStateHandle = { sessionId, cwd: config.cwd, active: true };
+  setActiveRun(activeRunHandle);
+
   // Crash guard: if anything from setup onward throws all the way out of
   // runTUI instead of reaching the normal finalize block, this still closes
   // out run.json so status and finishedAt never disagree. Declared before the
@@ -494,6 +504,8 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   const finalizeOnCrash = async (err: unknown): Promise<void> => {
     if (finalized) return;
     finalized = true;
+    activeRunHandle.active = false;
+    clearActiveRun();
     await flushPartialOnCrash().catch((flushErr: unknown) => {
       // Best-effort only — still attempt saveState below. Log so a flush
       // failure is not invisible when diagnosing a crash exit.
@@ -1630,6 +1642,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
         });
         await persistRunSnapshot("done", { finishedAt: Date.now() });
         sessionId = generateSessionId();
+        activeRunHandle.sessionId = sessionId;
         startedAt = Date.now();
         runTaskTitle = config.task;
         emitter.emit("session.title", runTaskTitle.trim().length > 0 ? truncateSessionLabel(runTaskTitle) : "Untitled session");
@@ -2244,6 +2257,8 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   // finished run (finishedAt set) can be left reading as still in progress.
   const persistedStatus: RunState["status"] = summaryStatus;
   finalized = true;
+  activeRunHandle.active = false;
+  clearActiveRun();
   await writeRunSnapshot(persistedStatus, {
     finishedAt,
     ...(sinkError !== undefined ? { error: sinkError } : {}),

tests/fixtures/crash-run/simulate-crash.ts

@@ -0,0 +1,31 @@
+// Spawned as a subprocess by tests/integration/crash-finalize.test.ts. Mimics
+// what runTUI does at startup (register the active run, write the initial
+// "running" run.json) and what index.ts does at process entry (install the
+// crash handlers), then throws asynchronously so it surfaces as a genuine
+// uncaughtException rather than a synchronous throw the caller could catch.
+import { installCrashHandlers } from "../../../src/index.js";
+import { setActiveRun } from "../../../src/session/active-run.js";
+import { sessionDir } from "../../../src/session/index.js";
+import { saveState } from "../../../src/session/state.js";
+
+const cwd = process.cwd();
+const sessionId = process.env["CRASH_TEST_SESSION_ID"];
+if (sessionId === undefined) {
+  throw new Error("CRASH_TEST_SESSION_ID must be set");
+}
+
+await saveState(cwd, sessionId, {
+  status: "running",
+  turnsUsed: 3,
+  task: "simulated crash task",
+  startedAt: Date.now(),
+});
+
+setActiveRun({ sessionId, cwd, active: true });
+installCrashHandlers();
+
+process.stdout.write(`${sessionDir(cwd, sessionId)}\n`);
+
+setImmediate(() => {
+  throw new Error("simulated crash");
+});

tests/integration/crash-finalize.test.ts

@@ -0,0 +1,48 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, test } from "bun:test";
+
+import { generateSessionId } from "../../src/session/index.js";
+import type { RunState } from "../../src/session/state.js";
+import { isResumableByDefault } from "../../src/tui/pick-session.js";
+
+const FIXTURE = join(import.meta.dirname, "../fixtures/crash-run/simulate-crash.ts");
+
+describe("integration — crash finalizes run.json", () => {
+  test("uncaughtException writes status: crashed with finishedAt", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "corbits-crash-cwd-"));
+    const home = mkdtempSync(join(tmpdir(), "corbits-crash-home-"));
+    const sessionId = generateSessionId();
+
+    try {
+      const proc = Bun.spawn(["bun", "run", FIXTURE], {
+        cwd,
+        env: { ...process.env, HOME: home, CRASH_TEST_SESSION_ID: sessionId },
+        stdout: "pipe",
+        stderr: "pipe",
+      });
+
+      const exitCode = await proc.exited;
+      const stdout = await new Response(proc.stdout).text();
+      const stderr = await new Response(proc.stderr).text();
+
+      expect(exitCode).toBe(1);
+      expect(stderr).toContain("uncaughtException: Error: simulated crash");
+
+      const runJsonPath = join(stdout.trim(), "run.json");
+      const raw = readFileSync(runJsonPath, "utf8");
+      const state = JSON.parse(raw) as RunState;
+
+      expect(state.status).toBe("crashed");
+      expect(state.finishedAt).toBeGreaterThan(0);
+      expect(state.error).toContain("simulated crash");
+      expect(state.task).toBe("simulated crash task");
+      expect(isResumableByDefault(state)).toBe(false);
+    } finally {
+      rmSync(cwd, { recursive: true, force: true });
+      rmSync(home, { recursive: true, force: true });
+    }
+  }, 15_000);
+});