Merge remote-tracking branch 'origin/main' into cl-7288-make-corbits-resume-a-named-recent-10-picker

Author: TheGreatAxios

CHANGELOG.md

@@ -20,6 +20,13 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
   `--force` is no longer required to see finished threads. The picker shows
   the 10 most recent sessions and type-to-filter narrows that list.
 
+### 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

@@ -81,6 +81,11 @@ checkout, including completed ones. Type to filter by name. 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.
@@ -129,7 +134,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/agent/environment.test.ts

@@ -6,6 +6,7 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 import { gatherEnvironment, getGitBranch } from "./environment.js";
+import { initTemporaryGitRepo } from "../../tests/helpers/temporary-git-repo.js";
 
 const run = promisify(execFile);
 
@@ -22,9 +23,7 @@ test("gatherEnvironment detects a git work tree and lists its top level", async
   // a runner may check out a detached HEAD, which has no branch name.
   const dir = await mkdtemp(join(tmpdir(), "corbits-env-repo-"));
   try {
-    await run("git", ["init"], { cwd: dir });
-    await run("git", ["config", "user.email", "t@t.test"], { cwd: dir });
-    await run("git", ["config", "user.name", "t"], { cwd: dir });
+    initTemporaryGitRepo(dir);
     await run("git", ["checkout", "-b", "trunk"], { cwd: dir });
     await mkdir(join(dir, "src"));
     await writeFile(join(dir, "src", "seed.ts"), "export const seed = 1;\n");
@@ -43,9 +42,7 @@ test("gatherEnvironment detects a git work tree and lists its top level", async
 test("gatherEnvironment gathers branch and dirty status from the same work tree", async () => {
   const dir = await mkdtemp(join(tmpdir(), "corbits-env-"));
   try {
-    await run("git", ["init"], { cwd: dir });
-    await run("git", ["config", "user.email", "t@t.test"], { cwd: dir });
-    await run("git", ["config", "user.name", "t"], { cwd: dir });
+    initTemporaryGitRepo(dir);
     await run("git", ["checkout", "-b", "trunk"], { cwd: dir });
     await writeFile(join(dir, "seed.txt"), "seed");
     await run("git", ["add", "."], { cwd: dir });

src/config.test.ts

@@ -10,6 +10,7 @@ import {
   buildProviderCatalog,
   catalogEntryAsProviderSettings,
   CliHelpError,
+  CliUserError,
   CLI_HELP_TEXT,
   KEYLESS_API_KEY,
   loadConfig,
@@ -26,7 +27,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 +468,94 @@ 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 <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-"));
@@ -558,6 +647,55 @@ 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(CliUserError);
+      const message = thrown instanceof Error ? thrown.message : String(thrown);
+      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);
+    } 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

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import type { InferenceSource } from "@intx/types/runtime";
 import { generateSessionId, isSessionId, migrateLegacySessionIfNeeded } 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";
@@ -525,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;
@@ -838,12 +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) {
+    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 \`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.`,
       );
     }
+    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/permission/gate.test.ts

@@ -8,6 +8,7 @@ import { createPermissionGate, isRequestCoveredByGrant, preGrantGuardReason } fr
 import { createPathRestriction } from "./path-restriction.js";
 import { createWorktreeRootsProvider } from "./worktree-roots.js";
 import type { Approval, PermissionRequest } from "./types.js";
+import { initTemporaryGitRepo } from "../../tests/helpers/temporary-git-repo.js";
 
 const shellCall = (command: string): ToolCall => ({
   id: "c",
@@ -112,9 +113,7 @@ describe("grant coverage rebinds relative paths to the request process cwd", ()
   const sessionCwd = join(root, "main");
   const git = (args: string[], cwd: string) => execFileSync("git", args, { cwd, stdio: "ignore" });
   mkdirSync(sessionCwd);
-  git(["init", "-q"], sessionCwd);
-  git(["config", "user.email", "t@example.com"], sessionCwd);
-  git(["config", "user.name", "t"], sessionCwd);
+  initTemporaryGitRepo(sessionCwd, { initArgs: ["-q"] });
   writeFileSync(join(sessionCwd, "seed.txt"), "seed\n");
   git(["add", "."], sessionCwd);
   git(["commit", "-qm", "seed"], sessionCwd);
@@ -171,9 +170,7 @@ describe("standing grant covers a later git worktree command (CL-5638)", () => {
   const sessionCwd = join(root, "main");
   const git = (args: string[], cwd: string) => execFileSync("git", args, { cwd, stdio: "ignore" });
   mkdirSync(sessionCwd);
-  git(["init", "-q"], sessionCwd);
-  git(["config", "user.email", "t@example.com"], sessionCwd);
-  git(["config", "user.name", "t"], sessionCwd);
+  initTemporaryGitRepo(sessionCwd, { initArgs: ["-q"] });
   writeFileSync(join(sessionCwd, "seed.txt"), "seed\n");
   git(["add", "."], sessionCwd);
   git(["commit", "-qm", "seed"], sessionCwd);