Tie active-run liveness to a single write instead of two independent ones

RunStateHandle carried its own active boolean alongside RunState.status
on disk, set at two separate call sites in src/tui/runner.ts (finalizeOnCrash
and the normal completion path). Both sites happened to null the handle
immediately after flipping the flag, so the boolean was always true whenever
the handle existed, making it a redundant copy of the same fact rather than
independent state -- deleted in favor of "the handle is null" as the sole
liveness signal (src/session/active-run.ts).

Terminal RunState writes now go through finalizeRunState (src/session/state.ts),
which persists the record and clears the active-run handle in one call instead
of leaving each terminal call site to remember both.

Author: TheGreatAxios

src/index.ts

@@ -148,7 +148,7 @@ export async function handleFatal(kind: CrashKind, error: unknown): Promise<void
 // 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;
+  if (run === null) return;
   const message = error instanceof Error ? error.message : String(error);
   try {
     await saveCrashState(run.cwd, run.sessionId, {

src/session/active-run.ts

@@ -9,10 +9,14 @@
 // crash path has the exact failure mode primeCrashReporting (src/crash/
 // report.ts) exists to avoid for git: a stalled disk or network mount would
 // block process.exit forever.
+//
+// Liveness has exactly one representation: presence of this handle in the
+// module-level slot (see getActiveRun below). There is no separate "active"
+// flag on the handle itself — a second field would just be a copy of the
+// same fact, free to drift from the slot it's meant to describe.
 export type RunStateHandle = {
   sessionId: string;
   cwd: string;
-  active: boolean;
   task: string;
   startedAt: number;
   model?: string;

src/session/state.test.ts

@@ -29,7 +29,8 @@ afterAll(() => {
   mock.module("node:fs/promises", () => realFs);
 });
 
-const { loadState, saveState } = await import("./state.js");
+const { finalizeRunState, loadState, saveState } = await import("./state.js");
+const { getActiveRun, setActiveRun } = await import("./active-run.js");
 type RunState = Awaited<ReturnType<typeof loadState>>;
 
 let cwd = "";
@@ -72,6 +73,19 @@ test("a straggler snapshot started before a terminal write does not overwrite it
   expect(final?.finishedAt).toBe(999);
 });
 
+test("a persisted terminal status agrees with the active-run handle without a second call site", async () => {
+  const sessionId = "sess-terminal";
+  setActiveRun({ sessionId, cwd, task: "task", startedAt: 1 });
+
+  await finalizeRunState(cwd, sessionId, state({ status: "done", finishedAt: 1000 }), home);
+
+  const persisted = await loadState(cwd, sessionId, home);
+  expect(persisted?.status).toBe("done");
+  // The only liveness representation left is presence in the active-run
+  // slot -- a terminal RunState.status must leave nothing there to read.
+  expect(getActiveRun()).toBeNull();
+});
+
 test("saveState calls for different sessions do not block each other", async () => {
   await Promise.all([
     saveState(cwd, "session-a", state({ task: "a" }), home),

src/session/state.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 import { type } from "arktype";
 
 import { sessionDir } from "./index.js";
-import { getTestWriteGate, isCrashed } from "./active-run.js";
+import { clearActiveRun, getTestWriteGate, isCrashed } from "./active-run.js";
 import { COMMAND_NAME } from "../branding.js";
 
 const ConnectedMcpServerSchema = type({
@@ -108,6 +108,21 @@ export async function saveState(
   return write;
 }
 
+// Single write path for a terminal RunState: pairs the on-disk status with
+// clearing the in-memory active-run handle (active-run.ts) so the two facts
+// are set together instead of at two independent call sites that could drift.
+// Callers writing a non-terminal ("running") snapshot should call saveState
+// directly — clearing the active-run handle on a running snapshot would be
+// wrong, not merely redundant.
+export async function finalizeRunState(
+  cwd: string,
+  sessionId: string,
+  state: RunState,
+  home?: string,
+): Promise<void> {
+  await saveState(cwd, sessionId, state, home);
+  clearActiveRun();
+}
 
 // Crash-time terminal write. Deliberately bypasses writeChains: a hung or
 // still-pending write for this session (possibly the very write mid-flight

src/tui/runner.ts

@@ -174,7 +174,7 @@ import {
 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 { finalizeRunState, 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";
@@ -503,7 +503,6 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   const activeRunHandle: RunStateHandle = {
     sessionId,
     cwd: config.cwd,
-    active: true,
     task: runTaskTitle.trim().length > 0 ? runTaskTitle.trim() : "(conversation)",
     startedAt,
     model: `${config.providerName}:${config.model}`,
@@ -536,7 +535,12 @@ export async function runTUI(initialConfig: Config): Promise<number> {
   const finalizeOnCrash = async (err: unknown): Promise<void> => {
     if (finalized) return;
     finalized = true;
-    activeRunHandle.active = false;
+    // Clear the active-run handle up front, before the awaits below, so a
+    // second crash mid-flush can't see this run as still live and race the
+    // finalize write issued here. finalizeRunState (state.ts) would otherwise
+    // do this itself, but only after saveState resolves — too late for that
+    // guard, so it's done here and finalizeRunState's own clear becomes a
+    // no-op repeat of the same fact rather than a second independent write.
     clearActiveRun();
     await flushPartialOnCrash().catch((flushErr: unknown) => {
       // Best-effort only — still attempt saveState below. Log so a flush
@@ -546,7 +550,7 @@ export async function runTUI(initialConfig: Config): Promise<number> {
       process.stderr.write(`${COMMAND_NAME}: crash finalize partial flush failed: ${flushMessage}\n`);
     });
     const message = err instanceof Error ? err.message : String(err);
-    await saveState(config.cwd, sessionId, {
+    await finalizeRunState(config.cwd, sessionId, {
       status: "failed",
       turnsUsed: 0,
       task: runTaskTitle.trim().length > 0 ? runTaskTitle.trim() : "(conversation)",
@@ -1445,15 +1449,24 @@ export async function runTUI(initialConfig: Config): Promise<number> {
     activeRunHandle.task = task;
     activeRunHandle.startedAt = startedAt;
     activeRunHandle.model = model;
-    await saveState(config.cwd, sessionId, {
+    const state: RunState = {
       status,
       turnsUsed: runSink.getTurnCount(),
       task,
       startedAt,
       model,
       mcpServers: connectedMcpServers,
       ...extra,
-    });
+    };
+    // "running" is the only non-terminal status writeRunSnapshot ever
+    // receives (progress snapshots); anything else closes the run out, so
+    // the active-run handle is cleared in the same call as the disk write
+    // rather than by a separate statement at each terminal call site.
+    if (status === "running") {
+      await saveState(config.cwd, sessionId, state);
+    } else {
+      await finalizeRunState(config.cwd, sessionId, state);
+    }
   };
 
   // Progress snapshots are fired unsequenced (model switch, MCP connect, turn
@@ -2375,8 +2388,9 @@ 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();
+  // writeRunSnapshot clears the active-run handle itself for a terminal
+  // status (via finalizeRunState in state.ts), pairing the on-disk write
+  // with the in-memory one instead of setting them at two call sites.
   await writeRunSnapshot(persistedStatus, {
     finishedAt,
     ...(sinkError !== undefined ? { error: sinkError } : {}),