Treat failed run.json with error as valid session state

loadState used to treat any parsed error field as a corrupt file, so a valid failed run with an error string was unreadable. Parse is now a tagged result, resume-by-id of a truly unreadable file throws one recovery line, and diagnostics go to structured log instead of stderr.

Author: TheGreatAxios

src/config.test.ts

@@ -26,7 +26,7 @@ import {
   type Settings,
 } from "./config/settings.js";
 import { OPENCODE_GO_BASE_URL } from "../packages/opencode-go/src/index.js";
-import { generateSessionId, initSessionDir } from "./session/index.js";
+import { generateSessionId, initSessionDir, sessionDir } from "./session/index.js";
 import { saveState } from "./session/state.js";
 import { filterMcpServersForConnect } from "./trust/project-trust.js";
 import { createExaMCPServerConfig } from "./mcp/exa.js";
@@ -467,6 +467,42 @@ describe("loadConfig", () => {
     }
   });
 
+  test("resume <id> --force reopens a failed session that recorded an error", async () => {
+    const cwd = await emptyCwd();
+    const home = await mkdtemp(join(tmpdir(), "ic-resume-home-"));
+    try {
+      const globalPath = await writeGlobalSettings(cwd);
+      const sessionId = generateSessionId();
+      await initSessionDir(cwd, sessionId, home);
+      await saveState(
+        cwd,
+        sessionId,
+        {
+          status: "failed",
+          turnsUsed: 4,
+          task: "ship resume after failure",
+          startedAt: Date.now() - 1_000,
+          finishedAt: Date.now(),
+          error: "Cycle commit failed\nhook dump: pre-commit rejected",
+        },
+        home,
+      );
+      const config = await loadConfig(["resume", sessionId, "--force", "--cwd", cwd], {
+        globalSettingsPath: globalPath,
+        home,
+      });
+      assertConfigured(config);
+      expect(config.resumeMode).toBe("id");
+      expect(config.sessionId).toBe(sessionId);
+      expect(config.skipInitialTask).toBe(true);
+      expect(config.task).toBe("ship resume after failure");
+      expect(config.force).toBe(true);
+    } 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-"));
@@ -558,6 +594,50 @@ describe("loadConfig", () => {
     }
   });
 
+  test("resume <id> of an unreadable session throws a short recovery line", async () => {
+    const cwd = await emptyCwd();
+    const home = await mkdtemp(join(tmpdir(), "ic-resume-home-"));
+    try {
+      const globalPath = await writeGlobalSettings(cwd);
+      const sessionId = generateSessionId();
+      await initSessionDir(cwd, sessionId, home);
+      await writeFile(join(sessionDir(cwd, sessionId, home), "run.json"), "{ not json");
+
+      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 thrown: unknown;
+      try {
+        await loadConfig(["resume", sessionId, "--force", "--cwd", cwd], {
+          globalSettingsPath: globalPath,
+          home,
+        });
+      } catch (err) {
+        thrown = err;
+      } finally {
+        process.stderr.write = orig;
+      }
+
+      expect(thrown).toBeInstanceOf(Error);
+      const message = thrown instanceof Error ? thrown.message : String(thrown);
+      expect(message).toMatch(new RegExp(`session ${sessionId} is unreadable`, "i"));
+      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);
+      const text = chunks.join("");
+      expect(text).not.toContain("ignoring unreadable");
+      expect(text).not.toContain(home);
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
   test("resume rejects a non-id positional instead of treating it as last", async () => {
     const cwd = await emptyCwd();
     try {

src/config/index.ts

@@ -1,8 +1,15 @@
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { stat } from "node:fs/promises";
 
 import type { InferenceSource } from "@intx/types/runtime";
-import { generateSessionId, isSessionId, migrateLegacySessionIfNeeded } from "../session/index.js";
+import {
+  generateSessionId,
+  isSessionId,
+  migrateLegacySessionIfNeeded,
+  sessionDir,
+} from "../session/index.js";
 import { loadState } from "../session/state.js";
+import { COMMAND_NAME } from "../branding.js";
 
 import { isDirectorId } from "../agent/directors/registry.js";
 import { DIRECTOR_IDS, type DirectorId } from "../agent/directors/types.js";
@@ -840,8 +847,20 @@ export async function loadConfig(
     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.`,
+        );
+      }
       throw new Error(
-        `No session ${id} for this project. Sessions are stored under ~/.corbits/projects/<project-key>/ (this checkout's git toplevel). Use \`corbits resume\` to choose one.`,
+        `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.`,
       );
     }
     sessionId = id;

src/session/index.ts

@@ -250,6 +250,14 @@ export async function listSessions(
       });
       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"));
+      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

src/session/list-sessions.test.ts

@@ -89,3 +89,48 @@ test("listSessions ignores a leftover goal.json from a pre-removal session", asy
   expect(row).toBeDefined();
   expect(row?.task).toBe("pre-removal session");
 });
+
+test("listSessions skips a session whose run.json is unreadable", async () => {
+  const sessionId = generateSessionId();
+  await initSessionDir(cwd, sessionId, home);
+  await writeFile(join(sessionDir(cwd, sessionId, home), "run.json"), "{ not json");
+  const listed = await listSessions(cwd, home);
+  expect(listed.find((s) => s.sessionId === sessionId)).toBeUndefined();
+});
+
+test("listSessions stays silent when many sibling run.json files are unreadable", async () => {
+  const validId = generateSessionId();
+  await initSessionDir(cwd, validId, home);
+  await writeFile(
+    join(sessionDir(cwd, validId, home), "run.json"),
+    JSON.stringify({
+      status: "running",
+      turnsUsed: 1,
+      task: "keep me",
+      startedAt: 1_700_000_000_000,
+    }),
+  );
+  for (let i = 0; i < 8; i++) {
+    const id = generateSessionId();
+    await initSessionDir(cwd, id, home);
+    await writeFile(join(sessionDir(cwd, id, home), "run.json"), '{ "turnsUsed": ');
+  }
+
+  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)).toEqual([validId]);
+  const text = chunks.join("");
+  expect(text).not.toContain("ignoring unreadable");
+  expect(text).not.toContain(home);
+});

src/session/state.ts

@@ -2,10 +2,13 @@ import { mkdir, writeFile, readFile, rename } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 import { type } from "arktype";
+import { getLogger } from "@intx/log";
 
 import { sessionDir } from "./index.js";
 import { clearActiveRun, getTestWriteGate, isCrashed } from "./active-run.js";
-import { COMMAND_NAME } from "../branding.js";
+import { LOG_NAMESPACE_ROOT } from "../branding.js";
+
+const log = getLogger([LOG_NAMESPACE_ROOT, "session", "state"]);
 
 const ConnectedMcpServerSchema = type({
   name: "string",
@@ -50,11 +53,10 @@ export async function atomicWrite(path: string, content: string): Promise<void>
 }
 
 // A corrupt or shape-invalid state file means resume is silently starting over
-// and prior progress is being discarded. Surface it rather than swallowing it.
+// and prior progress is being discarded. Log it rather than printing a path and
+// parse dump on the terminal the TUI is about to own.
 export function warnUnreadableState(path: string, reason: string): void {
-  process.stderr.write(
-    `${COMMAND_NAME}: ignoring unreadable state at ${path} (${reason}); starting fresh\n`,
-  );
+  log.warn("unreadable session state at {path}: {reason}", { path, reason });
 }
 
 // Concurrent saveState calls for the same session (a straggler progress
@@ -159,11 +161,14 @@ export async function saveCrashState(
   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 } {
+type ParseRunStateResult = { ok: true; state: RunState } | { ok: false; reason: string };
+
+// Tagged so a valid RunState.error string cannot be mistaken for a parse failure.
+function parseRunState(data: unknown): ParseRunStateResult {
   const result = RunStateSchema(data);
-  return result instanceof type.errors ? { error: result.summary } : result;
+  return result instanceof type.errors
+    ? { ok: false, reason: result.summary }
+    : { ok: true, state: result };
 }
 
 export async function loadState(
@@ -176,11 +181,11 @@ export async function loadState(
   try {
     const raw = await readFile(path, "utf8");
     const parsed = parseRunState(JSON.parse(raw));
-    if ("error" in parsed) {
-      warnUnreadableState(path, `invalid shape: ${parsed.error}`);
+    if (!parsed.ok) {
+      warnUnreadableState(path, `invalid shape: ${parsed.reason}`);
       return null;
     }
-    return parsed;
+    return parsed.state;
   } catch (err) {
     if (err instanceof SyntaxError) {
       warnUnreadableState(path, "corrupt JSON");

src/state.test.ts

@@ -44,6 +44,30 @@ describe("state persistence", () => {
     expect(loaded).toEqual(baseRunState);
   });
 
+  test("loadState returns a failed run that recorded an error string", async () => {
+    const state: RunState = {
+      ...baseRunState,
+      status: "failed",
+      finishedAt: 1_700_000_005_000,
+      error: "Cycle commit failed\nhook dump: pre-commit rejected",
+    };
+    await saveState(cwd, SESSION_ID, state, home);
+    const loaded = await loadState(cwd, SESSION_ID, home);
+    expect(loaded).toEqual(state);
+  });
+
+  test("loadState returns a crashed run that recorded an error string", async () => {
+    const state: RunState = {
+      ...baseRunState,
+      status: "crashed",
+      finishedAt: 1_700_000_005_000,
+      error: "uncaughtException: boom",
+    };
+    await saveState(cwd, SESSION_ID, state, home);
+    const loaded = await loadState(cwd, SESSION_ID, home);
+    expect(loaded).toEqual(state);
+  });
+
   test("saveState round-trips optional fields", async () => {
     const state: RunState = {
       ...baseRunState,
@@ -78,6 +102,29 @@ describe("state persistence", () => {
     expect(result).toBeNull();
   });
 
+  test("loadState does not print unreadable-state diagnostics to stderr", async () => {
+    const stateDir = dir();
+    const { mkdir } = await import("node:fs/promises");
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(join(stateDir, "run.json"), '{ "turnsUsed": ');
+
+    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;
+    try {
+      expect(await loadState(cwd, SESSION_ID, home)).toBeNull();
+    } finally {
+      process.stderr.write = orig;
+    }
+    const text = chunks.join("");
+    expect(text).not.toContain("ignoring unreadable");
+    expect(text).not.toContain(home);
+    expect(text).not.toContain("invalid shape");
+  });
+
   // ---------------------------------------------------------------------------
   // 4. Valid JSON but wrong shape returns null via the validators
   // ---------------------------------------------------------------------------