Merge pull request #1134 from corbitsdev/cl-8418-print-resume-command-on-console-exit-in-corbits-code

feat(tui): print resume command on session exit

Author: TheGreatAxios

docs/IMPLEMENTATION.md

@@ -394,7 +394,7 @@ Printed by `corbits --help` / `-h` from `CLI_HELP_TEXT` in `src/config/index.ts`
 | _(no verb)_                      | —                          | Interactive session; optional trailing task text                                                                                                                                                                                                                             |
 | `exec` / `run`                   | —                          | Run a prompt (non-interactive / one-shot)                                                                                                                                                                                                                                    |
 | `resume` / `continue`            | —                          | Open the session picker for this folder (project-keyed to this checkout's git toplevel). Lists the 10 most recently persisted sessions, completed included. Type to filter.                                                                                                  |
-| `--resume`                       | —                          | Open the interactive session picker                                                                                                                                                                                                                                          |
+| `--resume [<session-id>]`        | —                          | Open the interactive session picker, or reopen a specific session when an id is given                                                                                                                                                                                        |
 | `resume <session-id>`            | —                          | Reopen a specific session                                                                                                                                                                                                                                                    |
 | `resume --pick` / `--list`       | —                          | Interactive session picker                                                                                                                                                                                                                                                   |
 | `--cwd <dir>`                    | `process.cwd()`            | Working directory                                                                                                                                                                                                                                                            |

src/config.test.ts

@@ -779,6 +779,56 @@ describe("loadConfig", () => {
     }
   });
 
+  test("--resume <id> reopens a known session by id", 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: "done",
+          turnsUsed: 2,
+          task: "ship resume",
+          startedAt: Date.now() - 1_000,
+          finishedAt: Date.now(),
+        },
+        home,
+      );
+      // The exact argv form the exit hint prints (`corbits resume <id>`).
+      const config = await loadConfig(["--resume", sessionId, "--cwd", cwd], {
+        globalSettingsPath: globalPath,
+        home,
+      });
+      assertConfigured(config);
+      expect(config.command).toBe("tui");
+      expect(config.resumeMode).toBe("id");
+      expect(config.sessionId).toBe(sessionId);
+      expect(config.skipInitialTask).toBe(true);
+      expect(config.task).toBe("ship resume");
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+      await rm(home, { recursive: true, force: true });
+    }
+  });
+
+  test("--resume with a non-session-id token errors instead of leaking into task text", async () => {
+    const cwd = await emptyCwd();
+    try {
+      const globalPath = await writeGlobalSettings(cwd);
+      await expect(
+        loadConfig(["--resume", "not-a-session", "--cwd", cwd], {
+          globalSettingsPath: globalPath,
+        }),
+      ).rejects.toThrow("'not-a-session' is not a session id");
+    } finally {
+      await rm(cwd, { recursive: true, force: true });
+    }
+  });
+
   test("plain corbits always creates fresh state even when a previous session exists", async () => {
     const cwd = await emptyCwd();
     const home = await mkdtemp(join(tmpdir(), "ic-resume-home-"));

src/config/index.ts

@@ -681,7 +681,7 @@ Usage:
 
 Continue verbs (project-keyed to this checkout's git toplevel):
   resume / continue           interactive session picker
-  --resume                    interactive session picker
+  --resume [<session-id>]     interactive session picker, or reopen a specific session
   resume <session-id>         reopen a specific session
   resume --pick / --list      interactive session picker
 
@@ -691,7 +691,7 @@ Flags:
   --provider <name>           configured provider name
   --model <id>                model for the active provider
   --profile <name>            settings profile
-  --resume                    interactive session picker
+  --resume [<session-id>]     interactive session picker, or reopen a specific session
   --director <id>             exec-only: run as this director (default: skywalker)
   --dangerously-skip-permissions
                                skip permission prompts for this run only;
@@ -888,7 +888,24 @@ export async function loadConfig(
       if (resumeMode === "id") {
         throw new Error("cannot combine a session id with --resume");
       }
-      resumeMode = "pick";
+      // Optional session id: `corbits --resume <uuid>` reopens that session
+      // directly (an alias for the `corbits resume <uuid>` form the exit
+      // hint prints); bare `--resume` opens the
+      // picker. A non-flag token that is not a session id errors exactly like
+      // the `resume` verb path instead of leaking into task text.
+      const next = args[i + 1];
+      if (next !== undefined && !isFlagToken(next)) {
+        if (!isSessionId(next)) {
+          throw new Error(
+            `'${next}' is not a session id. Use a UUID session id or \`corbits resume\` to choose.`,
+          );
+        }
+        resumeMode = "id";
+        resumeSessionId = next;
+        i++;
+      } else {
+        resumeMode = "pick";
+      }
       continue;
     }
     if ((arg === "--pick" || arg === "--list") && resumeMode !== undefined) {

src/process-handlers.ts

@@ -4,6 +4,7 @@ import {
   type CrashKind,
 } from "./crash/report.js";
 import { getActiveRun, markCrashed } from "./session/active-run.js";
+import { printResumeHint } from "./session/resume-hint.js";
 import { getActiveDisposeHost } from "./session/active-host.js";
 import { saveCrashState } from "./session/state.js";
 import { classifyErrorClass } from "./telemetry/classify.js";
@@ -232,6 +233,14 @@ export function installSignalHandlers(options?: ProcessHandlerOptions): void {
         const teardown = awaitActiveDisposeHost(`handling ${signal}`);
         markCrashed();
         await teardown;
+        // Capture before finalizing: the terminal write clears the slot.
+        // Print before the finalize await below so the yielded disk I/O
+        // flushes this through the stderr pipe before process.exit — a write
+        // immediately preceding process.exit can otherwise be dropped.
+        // printResumeHint is exactly-once per process, so a signal racing
+        // the normal finalize tail cannot double-print the line.
+        const run = getActiveRun();
+        if (run !== null) printResumeHint(run.sessionId);
         await finalizeActiveRunOnSignal(signal);
         process.exit(128 + SIGNAL_EXIT_NUMBER[signal]);
       })();

src/session/resume-hint.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, spyOn, test } from "bun:test";
+
+import {
+  formatResumeHint,
+  printResumeHint,
+  resetResumeHintForTests,
+} from "./resume-hint.js";
+
+describe("resume hint", () => {
+  test("formats the resume command with the exited session id", () => {
+    expect(formatResumeHint("123e4567-e89b-12d3-a456-426614174000")).toBe(
+      "Run corbits resume 123e4567-e89b-12d3-a456-426614174000",
+    );
+  });
+
+  test("prints the hint line to stderr, leaving stdout clean", () => {
+    resetResumeHintForTests();
+    const outWrites: string[] = [];
+    const errWrites: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      outWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write);
+    const stderrSpy = spyOn(process.stderr, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      errWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    try {
+      printResumeHint("123e4567-e89b-12d3-a456-426614174000");
+    } finally {
+      stdoutSpy.mockRestore();
+      stderrSpy.mockRestore();
+    }
+    expect(errWrites).toEqual([
+      "Run corbits resume 123e4567-e89b-12d3-a456-426614174000\n",
+    ]);
+    expect(outWrites).toEqual([]);
+  });
+
+  test("prints at most once per process (signal racing finalize)", () => {
+    resetResumeHintForTests();
+    const errWrites: string[] = [];
+    const stderrSpy = spyOn(process.stderr, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      errWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    try {
+      // First call wins (e.g. the signal handler); the finalize tail's call
+      // for the same session is a no-op so the line emits exactly once.
+      printResumeHint("123e4567-e89b-12d3-a456-426614174000");
+      printResumeHint("123e4567-e89b-12d3-a456-426614174000");
+    } finally {
+      stderrSpy.mockRestore();
+    }
+    expect(errWrites).toEqual([
+      "Run corbits resume 123e4567-e89b-12d3-a456-426614174000\n",
+    ]);
+  });
+});

src/session/resume-hint.ts

@@ -0,0 +1,30 @@
+import { COMMAND_NAME } from "../branding.js";
+
+// Printed when an interactive session ends so the operator can get back to
+// the exact session they just left. Kept in its own module (branding only)
+// so the process-level signal handlers can use it without pulling the TUI
+// or config graph — see the import-cost comment in process-handlers.ts.
+export function formatResumeHint(sessionId: string): string {
+  return `Run ${COMMAND_NAME} resume ${sessionId}`;
+}
+
+// Exactly-once per process. The normal quit tail (finalizeTUIRun) and the
+// external-signal handler (installSignalHandlers) both funnel through
+// printResumeHint, and a signal arriving mid-finalize would otherwise print
+// the line twice: the process-level `terminating` guard covers
+// signal-vs-signal only, never signal-vs-finalize. The flag lives here —
+// the single choke point — so every current and future caller shares it.
+let printed = false;
+
+export function resetResumeHintForTests(): void {
+  printed = false;
+}
+
+export function printResumeHint(sessionId: string): void {
+  if (printed) return;
+  printed = true;
+  // stderr, not stdout: an exec run killed by a signal must not pollute piped
+  // stdout (JSON consumers). Matches the crash-report/fatal convention, which
+  // also reports on stderr; on a restored terminal both streams are visible.
+  process.stderr.write(`${formatResumeHint(sessionId)}\n`);
+}

src/tui/runner/exit.test.ts

@@ -16,6 +16,8 @@ import type {
 } from "@intx/types/runtime";
 import { LOG_NAMESPACE_ROOT } from "../../branding.js";
 import { defined } from "../../../tests/helpers/defined.js";
+import { withMockedHomedir } from "../../../tests/helpers/mock-module.js";
+import { createTempDirs } from "../../../tests/helpers/temporary-dirs.js";
 import {
   createDeliveryGeneration,
   createSessionOperationQueue,
@@ -30,6 +32,10 @@ import {
   COMPACTION_ABORTED_REASON,
   createCompactionLifecycle,
 } from "../../session/compaction-lifecycle.js";
+import {
+  printResumeHint,
+  resetResumeHintForTests,
+} from "../../session/resume-hint.js";
 import type { RunnerServices, RunnerState } from "./state.js";
 
 function stubQuit(args: {
@@ -196,6 +202,104 @@ describe("finalizeTUIRun quit order", () => {
   });
 });
 
+describe("finalizeTUIRun resume hint", () => {
+  test("prints the resume command with the exited session id", async () => {
+    resetResumeHintForTests();
+    const dirs = createTempDirs(
+      "corbits-resume-hint-cwd-",
+      "corbits-resume-hint-home-",
+    );
+    const sessionId = "123e4567-e89b-12d3-a456-426614174000";
+    const { state, services } = stubQuit({
+      awaitTail: async () => undefined,
+      shutdownRuntime: async () => undefined,
+    });
+    state.sessionId = sessionId;
+    (
+      services as unknown as { activatedToolNames: { list: () => string[] } }
+    ).activatedToolNames = { list: () => [] };
+    (state.config as { cwd: string }).cwd = dirs.cwd;
+    const outWrites: string[] = [];
+    const errWrites: string[] = [];
+    const stdoutSpy = spyOn(process.stdout, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      outWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write);
+    const stderrSpy = spyOn(process.stderr, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      errWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    try {
+      const code = await withMockedHomedir(dirs.home, () =>
+        finalizeTUIRun(state, services),
+      );
+      expect(code).toBe(0);
+    } finally {
+      stdoutSpy.mockRestore();
+      stderrSpy.mockRestore();
+      dirs.cleanup();
+    }
+    // stderr, not stdout: a piped stdout (JSON consumers) must stay clean.
+    expect(
+      errWrites.some((w) => w === `Run corbits resume ${sessionId}\n`),
+    ).toBe(true);
+    expect(outWrites.some((w) => w.includes("resume"))).toBe(false);
+  });
+
+  test("an external signal racing finalize prints the hint exactly once", async () => {
+    resetResumeHintForTests();
+    const dirs = createTempDirs(
+      "corbits-resume-hint-race-cwd-",
+      "corbits-resume-hint-race-home-",
+    );
+    const sessionId = "123e4567-e89b-12d3-a456-426614174000";
+    let releaseTail: (() => void) | undefined;
+    const gatedTail = new Promise<void>((resolve) => {
+      releaseTail = resolve;
+    });
+    const { state, services } = stubQuit({
+      awaitTail: () => gatedTail,
+      shutdownRuntime: async () => undefined,
+    });
+    state.sessionId = sessionId;
+    (
+      services as unknown as { activatedToolNames: { list: () => string[] } }
+    ).activatedToolNames = { list: () => [] };
+    (state.config as { cwd: string }).cwd = dirs.cwd;
+    const errWrites: string[] = [];
+    const stderrSpy = spyOn(process.stderr, "write").mockImplementation(((
+      chunk: unknown,
+    ) => {
+      errWrites.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write);
+    try {
+      const pending = withMockedHomedir(dirs.home, () =>
+        finalizeTUIRun(state, services),
+      );
+      // Simulate the signal handler firing mid-finalize: both paths funnel
+      // through printResumeHint, so the shared once-flag keeps exactly one
+      // line. (The process-level `terminating` guard covers signal-vs-signal
+      // only — it cannot see the finalize tail already in flight.)
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      printResumeHint(sessionId);
+      defined(releaseTail, "releaseTail")();
+      expect(await pending).toBe(0);
+    } finally {
+      stderrSpy.mockRestore();
+      dirs.cleanup();
+    }
+    const hintLines = errWrites.filter(
+      (w) => w === `Run corbits resume ${sessionId}\n`,
+    );
+    expect(hintLines).toHaveLength(1);
+  });
+});
+
 const liveSource: InferenceSource = {
   id: "codex/work",
   provider: "openai",

src/tui/runner/exit.ts

@@ -38,6 +38,7 @@ import {
   resolveSessionLabel,
   truncateSessionLabel,
 } from "../../session/session-label.js";
+import { printResumeHint } from "../../session/resume-hint.js";
 import { clearActiveDisposeHost } from "../../session/active-host.js";
 import { syncRunStateHandle } from "../../session/active-run.js";
 import { startRunHeartbeat } from "../../session/run-liveness.js";
@@ -863,6 +864,11 @@ export async function finalizeTUIRun(
     });
   }
 
+  // Last word on the restored terminal: every normal quit (exit/quit command,
+  // Ctrl+C, session end) funnels through here, so the exited session's id is
+  // always the one printed.
+  printResumeHint(state.sessionId);
+
   return resolveExitCode({
     runError: state.runError,
     sinkError,

tests/integration/signal-finalize.test.ts

@@ -41,6 +41,16 @@ describe("integration — signal finalizes run.json", () => {
 
         expect(exitCode).toBe(expectedExitCode);
 
+        // The interrupted session must name itself so the operator can
+        // resume exactly the session they just left. The hint goes to
+        // stderr — never stdout — so piped stdout (JSON consumers) stays
+        // clean. An external signal racing the finalize tail must still
+        // emit the line exactly once (shared once-flag in resume-hint).
+        const errText = await new Response(proc.stderr).text();
+        const hint = `Run corbits resume ${sessionId}`;
+        expect(errText).toContain(hint);
+        expect(errText.split(hint).length - 1).toBe(1);
+
         // The fixture parks two unawaited straggler "running" snapshot writes
         // behind setTestWriteGate and releases them only after markCrashed()
         // flips. Without that fence on the signal path, one of those renames