Distinguish missing and unreadable session state on load

loadState now returns a tagged result so callers can tell a missing run.json from a present but unreadable one without restatting the file. Unreadable resume-by-id prints one recovery line; parse diagnostics stay in the structured log.

Author: TheGreatAxios

CHANGELOG.md

@@ -13,6 +13,13 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
 
 ## [Unreleased]
 
+### Fixed
+
+- Failed sessions with an `error` string in `run.json` are valid resume
+  candidates, not corrupt files. A truly unreadable session id prints one
+  recovery line; parse diagnostics go to the structured log, not the
+  terminal.
+
 ## [0.3.10] - 2026-08-30
 
 ### Fixed

docs/PRODUCT.md

@@ -80,6 +80,11 @@ Opens a picker of saved conversations for the working directory. Plain
 `corbits` always starts a fresh conversation; `corbits resume <session-id>`
 is the direct, explicit resume path.
 
+A session that ended in `failed` (including one that recorded an `error`
+string in `run.json`) is a failed session, not a corrupt one — it still
+appears in the picker. Passing a corrupt session id prints one short
+recovery line instead of dumping the file path and parse details.
+
 ## Safety Model
 
 - **Tiered permission gate** — Read-only tools (`read_file`, `search_files`, `grep`, `list_dir`) run freely. Every consequential tool (`write_file`, `edit_file`, `run_shell`, …) is gated. The operator can Allow Once or Allow Always (scoped to a file, a directory, or a command shape); "Allow Always" choices persist per working directory so repeat actions don't interrupt flow.
@@ -128,7 +133,9 @@ The exact turn thresholds are model-family-dependent (tighter for models with ob
 
 **What the user sees:** `Ctrl+C` mid-run, network error, or crash. The last state is persisted.
 
-**Recovery:** `corbits resume` reloads `RunState` and continues.
+**Recovery:** `corbits resume` reloads `RunState` and continues. Failed
+sessions remain failed (still listed); a corrupt id gets a short recovery
+line instead of a path dump.
 
 ## Configuration
 

src/config.test.ts

@@ -10,6 +10,7 @@ import {
   buildProviderCatalog,
   catalogEntryAsProviderSettings,
   CliHelpError,
+  CliUserError,
   CLI_HELP_TEXT,
   KEYLESS_API_KEY,
   loadConfig,
@@ -503,6 +504,58 @@ describe("loadConfig", () => {
     }
   });
 
+  test("resume <id> --force among failed siblings stays silent and reopens the target", async () => {
+    const cwd = await emptyCwd();
+    const home = await mkdtemp(join(tmpdir(), "ic-resume-home-"));
+    try {
+      const globalPath = await writeGlobalSettings(cwd);
+      const targetId = generateSessionId();
+      for (let i = 0; i < 6; i++) {
+        const id = i === 0 ? targetId : generateSessionId();
+        await initSessionDir(cwd, id, home);
+        await saveState(
+          cwd,
+          id,
+          {
+            status: "failed",
+            turnsUsed: 2,
+            task: i === 0 ? "target failed session" : `sibling failed ${i}`,
+            startedAt: Date.now() - 1_000 - i,
+            finishedAt: Date.now() - i,
+            error: "Cycle commit failed\nhook dump: pre-commit rejected",
+          },
+          home,
+        );
+      }
+
+      const chunks: string[] = [];
+      const orig = process.stderr.write.bind(process.stderr);
+      process.stderr.write = ((chunk: string | Uint8Array, ...rest: unknown[]) => {
+        chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+        return orig(chunk, ...(rest as []));
+      }) as typeof process.stderr.write;
+      let config: Awaited<ReturnType<typeof loadConfig>>;
+      try {
+        config = await loadConfig(["resume", targetId, "--force", "--cwd", cwd], {
+          globalSettingsPath: globalPath,
+          home,
+        });
+      } finally {
+        process.stderr.write = orig;
+      }
+      assertConfigured(config);
+      expect(config.sessionId).toBe(targetId);
+      expect(config.task).toBe("target failed session");
+      const text = chunks.join("");
+      expect(text).not.toContain("ignoring unreadable");
+      expect(text).not.toContain(home);
+      expect(text).not.toContain("invalid shape");
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   test("--resume opens the picker", async () => {
     const cwd = await emptyCwd();
     const home = await mkdtemp(join(tmpdir(), "ic-resume-home-"));
@@ -621,14 +674,19 @@ describe("loadConfig", () => {
         process.stderr.write = orig;
       }
 
-      expect(thrown).toBeInstanceOf(Error);
+      expect(thrown).toBeInstanceOf(CliUserError);
       const message = thrown instanceof Error ? thrown.message : String(thrown);
-      expect(message).toMatch(new RegExp(`session ${sessionId} is unreadable`, "i"));
+      expect(message).toBe(
+        `Session ${sessionId} is unreadable. Use \`corbits resume\` to choose another.`,
+      );
       expect(message).not.toMatch(/No session/);
       expect(message).not.toContain("ignoring unreadable");
       expect(message).not.toContain("invalid shape");
       expect(message).not.toContain(home);
       expect(message.split("\n")).toHaveLength(1);
+      if (thrown instanceof CliUserError) {
+        expect(thrown.exitCode).toBe(1);
+      }
       const text = chunks.join("");
       expect(text).not.toContain("ignoring unreadable");
       expect(text).not.toContain(home);

src/config/index.ts

@@ -1,13 +1,7 @@
-import { join, resolve } from "node:path";
-import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
 
 import type { InferenceSource } from "@intx/types/runtime";
-import {
-  generateSessionId,
-  isSessionId,
-  migrateLegacySessionIfNeeded,
-  sessionDir,
-} from "../session/index.js";
+import { generateSessionId, isSessionId, migrateLegacySessionIfNeeded } from "../session/index.js";
 import { loadState } from "../session/state.js";
 import { COMMAND_NAME } from "../branding.js";
 
@@ -532,6 +526,19 @@ export class CliHelpError extends Error {
   }
 }
 
+/**
+ * Thrown for a recoverable operator mistake. Entry points must print
+ * `message` to stderr and exit 1 — not dump a stack.
+ */
+export class CliUserError extends Error {
+  readonly exitCode = 1 as const;
+
+  constructor(message: string) {
+    super(message);
+    this.name = "CliUserError";
+  }
+}
+
 export interface LoadConfigOptions {
   // Override the global settings file location (for tests / non-standard homes).
   globalSettingsPath?: string;
@@ -845,24 +852,18 @@ export async function loadConfig(
   } else if (resumeMode === "id") {
     const id = resumeSessionId!;
     await migrateLegacySessionIfNeeded(cwd, id, options.home);
-    const state = await loadState(cwd, id, options.home);
-    if (state === null) {
-      let runJsonPresent = false;
-      try {
-        await stat(join(sessionDir(cwd, id, options.home), "run.json"));
-        runJsonPresent = true;
-      } catch {
-        // Missing run.json: treat as no session for this project.
-      }
-      if (runJsonPresent) {
-        throw new Error(
-          `Session ${id} is unreadable. Use \`${COMMAND_NAME} resume\` to choose another.`,
-        );
-      }
+    const loaded = await loadState(cwd, id, options.home);
+    if (loaded.kind === "unreadable") {
+      throw new CliUserError(
+        `Session ${id} is unreadable. Use \`${COMMAND_NAME} resume\` to choose another.`,
+      );
+    }
+    if (loaded.kind === "missing") {
       throw new Error(
         `No session ${id} for this project. Sessions are stored under ~/.corbits/projects/<project-key>/ (this checkout's git toplevel). Use \`${COMMAND_NAME} resume\` to choose one.`,
       );
     }
+    const state = loaded.state;
     sessionId = id;
     skipInitialTask = true;
     if (task.length === 0) resumeTask = state.task;

src/index.ts

@@ -4,7 +4,7 @@ import { primeCrashReporting, writeCrashReport, type CrashKind } from "./crash/r
 import { getActiveRun, markCrashed } from "./session/active-run.js";
 import { getActiveDisposeHost } from "./session/active-host.js";
 import { saveCrashState } from "./session/state.js";
-import { loadConfig, CliHelpError } from "./config/index.js";
+import { loadConfig, CliHelpError, CliUserError } from "./config/index.js";
 import { ensureTelemetrySettings, globalSettingsPath } from "./config/settings.js";
 import { installFileLogSink } from "./logging/sink.js";
 import { flushPerfToOtel } from "./perf/index.js";
@@ -286,6 +286,24 @@ export function installSignalHandlers(): void {
   }
 }
 
+export function cliCaughtExit(err: unknown): {
+  stream: "stdout" | "stderr";
+  text: string;
+  code: number;
+} {
+  if (err instanceof CliHelpError) {
+    return { stream: "stdout", text: `${err.message}\n`, code: err.exitCode };
+  }
+  if (err instanceof CliUserError) {
+    return { stream: "stderr", text: `${err.message}\n`, code: err.exitCode };
+  }
+  return {
+    stream: "stderr",
+    text: `${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`,
+    code: 1,
+  };
+}
+
 if (import.meta.main) {
   installCrashHandlers();
   installSignalHandlers();
@@ -294,14 +312,10 @@ if (import.meta.main) {
   try {
     code = await main(process.argv.slice(2));
   } catch (err: unknown) {
-    // Help is an intentional early exit, not a crash — stdout + 0.
-    if (err instanceof CliHelpError) {
-      process.stdout.write(`${err.message}\n`);
-      code = err.exitCode;
-    } else {
-      process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
-      code = 1;
-    }
+    const exit = cliCaughtExit(err);
+    const dest = exit.stream === "stdout" ? process.stdout : process.stderr;
+    dest.write(exit.text);
+    code = exit.code;
   }
   process.exit(code);
 }

src/session/index.ts

@@ -240,28 +240,23 @@ export async function listSessions(
   const summaries: SessionSummary[] = [];
   for (const entry of entries) {
     await migrateLegacySessionIfNeeded(cwd, entry, home);
-    const state = await loadState(cwd, entry, home);
-    if (state !== null) {
+    const loaded = await loadState(cwd, entry, home);
+    if (loaded.kind === "ok") {
       summaries.push({
         sessionId: entry,
-        task: state.task,
-        startedAt: state.startedAt,
-        status: state.status,
+        task: loaded.state.task,
+        startedAt: loaded.state.startedAt,
+        status: loaded.state.status,
       });
       continue;
     }
-    // Present but unreadable run.json is not a picker candidate — diagnostics
-    // already went to the structured log from loadState.
-    try {
-      await stat(join(sessionDir(cwd, entry, home), "run.json"));
+    if (loaded.kind === "unreadable") {
       continue;
-    } catch {
-      // Missing run.json: fall through to the context-only crashed fallback.
     }
-    // A session directory with context/ but no readable run.json never
-    // reached its first saveState call (see src/tui/runner.ts's early
-    // "running" write) and therefore isn't actually running: report it as
-    // crashed rather than fabricating liveness.
+    // Missing run.json: a session directory with context/ never reached its
+    // first saveState call (see src/tui/runner.ts's early "running" write)
+    // and therefore isn't actually running: report it as crashed rather
+    // than fabricating liveness.
     try {
       const dirStat = await stat(sessionDir(cwd, entry, home));
       await stat(sessionContextDir(cwd, entry, home));
@@ -298,7 +293,7 @@ export async function renameSession(
   }
   await migrateLegacySessionIfNeeded(cwd, sessionId, home);
   const existing = await loadState(cwd, sessionId, home);
-  if (existing === null) {
+  if (existing.kind !== "ok") {
     let startedAt = Date.now();
     try {
       const dirStat = await stat(sessionDir(cwd, sessionId, home));
@@ -319,7 +314,7 @@ export async function renameSession(
     );
     return;
   }
-  await saveState(cwd, sessionId, { ...existing, task: trimmed }, home);
+  await saveState(cwd, sessionId, { ...existing.state, task: trimmed }, home);
 }
 
 export { projectKeyFor, projectSessionsRoot, projectsRoot, projectRootFor } from "./project-key.js";

src/session/list-sessions.test.ts

@@ -134,3 +134,83 @@ test("listSessions stays silent when many sibling run.json files are unreadable"
   expect(text).not.toContain("ignoring unreadable");
   expect(text).not.toContain(home);
 });
+
+test("listSessions includes a failed run that recorded an error", async () => {
+  const sessionId = generateSessionId();
+  await initSessionDir(cwd, sessionId, home);
+  await writeFile(
+    join(sessionDir(cwd, sessionId, home), "run.json"),
+    JSON.stringify({
+      status: "failed",
+      turnsUsed: 2,
+      task: "failed work",
+      startedAt: 1_700_000_000_000,
+      finishedAt: 1_700_000_005_000,
+      error: "Cycle commit failed\nhook dump: pre-commit rejected",
+    }),
+  );
+  const listed = await listSessions(cwd, home);
+  const row = listed.find((s) => s.sessionId === sessionId);
+  expect(row?.status).toBe("failed");
+  expect(row?.task).toBe("failed work");
+});
+
+test("listSessions includes a crashed run that recorded an error", async () => {
+  const sessionId = generateSessionId();
+  await initSessionDir(cwd, sessionId, home);
+  await writeFile(
+    join(sessionDir(cwd, sessionId, home), "run.json"),
+    JSON.stringify({
+      status: "crashed",
+      turnsUsed: 1,
+      task: "crashed work",
+      startedAt: 1_700_000_000_000,
+      finishedAt: 1_700_000_005_000,
+      error: "uncaughtException: boom",
+    }),
+  );
+  const listed = await listSessions(cwd, home);
+  const row = listed.find((s) => s.sessionId === sessionId);
+  expect(row?.status).toBe("crashed");
+  expect(row?.task).toBe("crashed work");
+});
+
+test("listSessions stays silent when many sibling runs failed with an error", async () => {
+  const ids: string[] = [];
+  for (let i = 0; i < 8; i++) {
+    const id = generateSessionId();
+    ids.push(id);
+    await initSessionDir(cwd, id, home);
+    await writeFile(
+      join(sessionDir(cwd, id, home), "run.json"),
+      JSON.stringify({
+        status: "failed",
+        turnsUsed: 1,
+        task: `failed ${i}`,
+        startedAt: 1_700_000_000_000 + i,
+        finishedAt: 1_700_000_005_000 + i,
+        error: "Cycle commit failed\nhook dump",
+      }),
+    );
+  }
+
+  const chunks: string[] = [];
+  const orig = process.stderr.write.bind(process.stderr);
+  process.stderr.write = ((chunk: string | Uint8Array, ...rest: unknown[]) => {
+    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString());
+    return orig(chunk, ...(rest as []));
+  }) as typeof process.stderr.write;
+  let listed: Awaited<ReturnType<typeof listSessions>> = [];
+  try {
+    listed = await listSessions(cwd, home);
+  } finally {
+    process.stderr.write = orig;
+  }
+
+  expect(listed.map((s) => s.sessionId).sort()).toEqual([...ids].sort());
+  expect(listed.every((s) => s.status === "failed")).toBe(true);
+  const text = chunks.join("");
+  expect(text).not.toContain("ignoring unreadable");
+  expect(text).not.toContain(home);
+  expect(text).not.toContain("invalid shape");
+});