fix(supervisor): surface resume failures with provider-specific copy

- rewrite ACP `session/load` errors into user-facing "can't be resumed" messages, with a Cursor-specific override for its unsupported resume
- thread an optional `loadSessionErrorRewriter` through the structured session input so adapters can supply provider copy
- strip Electron's `Error invoking remote method '...'` framing from launch errors in ThreadView before surfacing them

Author: SDSLeon

src/renderer/components/thread/ThreadView.test.tsx

@@ -211,6 +211,65 @@ describe("ThreadView", () => {
     });
   });
 
+  it("strips Electron IPC framing from launch errors before surfacing them", async () => {
+    bridge.startThread.mockRejectedValueOnce(
+      new Error(
+        "Error invoking remote method 'lightcode:start-thread': Error: This conversation can't be resumed.",
+      ),
+    );
+    const onLaunchFailed = vi.fn<(message: string) => void>();
+
+    renderThreadView({
+      thread: {
+        id: "thread-launch-ipc-error",
+        projectId: "project-1",
+        title: "Cursor resume",
+        agentKind: "cursor",
+        config: { model: "auto" },
+        status: "launching",
+        attention: "none",
+        canResumeWithConfig: false,
+        archived: false,
+        done: false,
+        starred: false,
+        createdAt: new Date().toISOString(),
+        updatedAt: new Date().toISOString(),
+      },
+      agentStatus: {
+        kind: "cursor",
+        label: "Cursor",
+        installed: true,
+        authState: "authenticated",
+        capabilities: {
+          models: [{ id: "auto", label: "Auto" }],
+          efforts: [],
+          modelEfforts: {},
+          modes: ["agent"],
+          approvalPolicies: [{ id: "default", label: "Default" }],
+          sandboxModes: [],
+          supportsResume: true,
+          supportsDirectInput: true,
+          liveInputMode: "terminal",
+          presentationMode: "terminal",
+          settingDefs: [],
+        },
+      },
+      projectLocation: { kind: "posix", path: "/tmp" },
+      pendingLaunchPrompt: "hi",
+      onConfigChange: () => undefined,
+      onLaunchConsumed: () => undefined,
+      onLaunchFailed,
+      onResolveServerRequest: async () => undefined,
+      onSubmitInput: async () => undefined,
+    });
+
+    fireEvent.click(screen.getByText("report terminal size"));
+
+    await waitFor(() => {
+      expect(onLaunchFailed).toHaveBeenCalledWith("This conversation can't be resumed.");
+    });
+  });
+
   it("renders a server-mode composer for Codex live threads", () => {
     renderThreadView({
       thread: {

src/renderer/components/thread/ThreadView.tsx

@@ -28,12 +28,20 @@ import { ThreadHeaderStatusButton } from "./ThreadHeaderStatus";
 
 const DEFAULT_HIDDEN_TERMINAL_SIZE: TerminalSize = { cols: 120, rows: 30 };
 
+/**
+ * Strip Electron's `Error invoking remote method '<channel>': Error: ` prefix
+ * from IPC rejections so users see the supervisor's actual message verbatim.
+ */
+function stripIpcInvokeFraming(message: string): string {
+  return message.replace(/^Error invoking remote method '[^']+':\s*(?:Error:\s*)?/, "");
+}
+
 function formatLaunchError(error: unknown): string {
   if (error instanceof Error && error.message.trim().length > 0) {
-    return error.message;
+    return stripIpcInvokeFraming(error.message);
   }
   if (typeof error === "string" && error.trim().length > 0) {
-    return error;
+    return stripIpcInvokeFraming(error);
   }
   if (
     error &&
@@ -42,7 +50,7 @@ function formatLaunchError(error: unknown): string {
     typeof error.message === "string" &&
     error.message.trim().length > 0
   ) {
-    return error.message;
+    return stripIpcInvokeFraming(error.message);
   }
   return "Thread failed to start.";
 }

src/supervisor/agents/acp/session.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it, vi } from "vitest";
+import { RequestError } from "@agentclientprotocol/sdk";
 import type { CreateStructuredSessionInput } from "../base";
 import type { ThreadConfig } from "@/shared/contracts";
 import {
   AcpStructuredSession,
   resolveAcpResourcePath,
+  rewriteLoadSessionError,
   shouldSpawnAcpSession,
   toAcpResourceUri,
 } from "./session";
@@ -143,6 +145,36 @@ describe("shouldSpawnAcpSession — shared resume/presentation gate for all ACP
   });
 });
 
+describe("rewriteLoadSessionError — user-facing copy for session/load failures", () => {
+  it("rewrites a 'Session not found' invalidParams into resume-specific guidance", () => {
+    const raw = RequestError.invalidParams({ message: 'Session "abc-123" not found' });
+    const out = rewriteLoadSessionError(raw, "abc-123");
+    expect(out.message).toBe(
+      "This conversation can't be resumed — the agent no longer recognizes this session. Start a new thread to continue.",
+    );
+    expect((out as { cause?: unknown }).cause).toBe(raw);
+  });
+
+  it("includes the agent's error message verbatim for non-not-found failures", () => {
+    const raw = RequestError.invalidParams({ message: "cwd does not match" });
+    const out = rewriteLoadSessionError(raw, "ses-9");
+    expect(out.message).toContain("cwd does not match");
+    expect(out.message).toContain("Start a new thread");
+  });
+
+  it("falls back to the Error message when the error isn't a RequestError", () => {
+    const out = rewriteLoadSessionError(new Error("stream closed"), "ses-9");
+    expect(out.message).toContain("stream closed");
+    expect(out.message).toContain("Start a new thread");
+  });
+
+  it("detects 'session ... not found' phrasing inside plain Error messages", () => {
+    const out = rewriteLoadSessionError(new Error('session "ses-9" not found'), "ses-9");
+    expect(out.message).toContain("can't be resumed");
+    expect(out.message).not.toContain("ses-9");
+  });
+});
+
 describe("ACP resource path helpers", () => {
   it("resolves repo-relative paths against the project root", () => {
     expect(

src/supervisor/agents/acp/session.ts

@@ -20,6 +20,7 @@ import {
   ClientSideConnection,
   ndJsonStream,
   PROTOCOL_VERSION,
+  RequestError,
   type Client,
   type ContentBlock,
   type RequestPermissionRequest,
@@ -217,6 +218,39 @@ function createAcpPromptUsageEvent(threadId: string, usage: unknown): RuntimeEve
   );
 }
 
+/**
+ * Replace the raw JSON-RPC error from `session/load` with a message the
+ * renderer can show verbatim. Provider-agnostic on purpose: the same code
+ * path triggers whenever any ACP agent rejects a `session/load` call (lost,
+ * rotated, or never-persisted sessionId).
+ */
+export function rewriteLoadSessionError(error: unknown, _sessionId: string): Error {
+  const detail = extractLoadSessionDetail(error);
+  const message = detail.notFound
+    ? "This conversation can't be resumed — the agent no longer recognizes this session. Start a new thread to continue."
+    : `This conversation can't be resumed: ${detail.message ?? (error instanceof Error ? error.message : String(error))}. Start a new thread to continue.`;
+  return Object.assign(new Error(message), { cause: error });
+}
+
+function extractLoadSessionDetail(error: unknown): { message?: string; notFound: boolean } {
+  let message: string | undefined;
+  let notFound = false;
+  if (error instanceof RequestError) {
+    message = error.message;
+    const data = error.data as { message?: unknown } | undefined;
+    if (data && typeof data.message === "string") {
+      message = data.message;
+      if (/not\s+found/i.test(data.message)) notFound = true;
+    }
+  } else if (error instanceof Error) {
+    message = error.message;
+    if (/session.*not\s+found/i.test(error.message)) notFound = true;
+  }
+  return notFound
+    ? { ...(message ? { message } : {}), notFound: true }
+    : { ...(message ? { message } : {}), notFound: false };
+}
+
 const INTERRUPT_ACK_TEXT_TAIL_LIMIT = 512;
 const USER_INTERRUPT_ACK_RE = /\boperation cancelled by user\b/i;
 
@@ -582,9 +616,21 @@ function applyAcpModeUpdateToConfig(currentConfig: ThreadConfig, modeId: string)
 
 // ── Session ──────────────────────────────────────────────────────
 
+export interface AcpStructuredSessionOptions {
+  /**
+   * Hook the adapter passes in when it wants to control the message a failed
+   * `session/load` produces. Receives the raw transport error and the
+   * sessionId that was being loaded; must return the Error to throw.
+   */
+  loadSessionErrorRewriter?: (error: unknown, sessionId: string) => Error;
+}
+
 export class AcpStructuredSession implements StructuredSessionHandle {
   launchOptions: AgentLaunchOptions;
 
+  private loadSessionErrorRewriter: (error: unknown, sessionId: string) => Error =
+    rewriteLoadSessionError;
+
   private readonly child: ChildProcess;
   private readonly connection: ClientSideConnection;
   private readonly cwd: string;
@@ -644,13 +690,17 @@ export class AcpStructuredSession implements StructuredSessionHandle {
     projectLocation: ProjectLocation,
     cwd: string,
     threadId: string,
+    options?: AcpStructuredSessionOptions,
   ) {
     this.child = child;
     this.connection = connection;
     this.projectLocation = projectLocation;
     this.cwd = cwd;
     this.threadId = threadId;
     this.launchOptions = { suppressResumeConfigOverrides: true };
+    if (options?.loadSessionErrorRewriter) {
+      this.loadSessionErrorRewriter = options.loadSessionErrorRewriter;
+    }
   }
 
   /** Initialize the canonical mapper once we have a stable thread id. */
@@ -831,6 +881,7 @@ export class AcpStructuredSession implements StructuredSessionHandle {
     command: CommandSpec,
     projectLocation: ProjectLocation,
     threadId: string,
+    options?: AcpStructuredSessionOptions,
   ): AcpStructuredSession {
     const sessionCwd = resolveSessionCwd(projectLocation);
     const spawnCwd = command.cwd ?? resolveSpawnCwd(projectLocation);
@@ -897,7 +948,14 @@ export class AcpStructuredSession implements StructuredSessionHandle {
       stream,
     );
 
-    session = new AcpStructuredSession(child, connection, projectLocation, sessionCwd, threadId);
+    session = new AcpStructuredSession(
+      child,
+      connection,
+      projectLocation,
+      sessionCwd,
+      threadId,
+      options,
+    );
     session.spawnReady = spawnReady;
     session.stderrChunks.push(...stderrChunks);
 
@@ -1003,6 +1061,8 @@ export class AcpStructuredSession implements StructuredSessionHandle {
         this.adoptSessionRef(sessionRef);
         availableModeIds = result.modes?.availableModes?.map((m) => m.id) ?? [];
         configOptions = result.configOptions ?? [];
+      } catch (error) {
+        throw this.loadSessionErrorRewriter(error, sessionRef.providerSessionId);
       } finally {
         this.isReplayingHistory = false;
         this.replayHistoryUntil = Date.now() + 500;
@@ -1483,5 +1543,9 @@ export function createAcpStructuredSession(
   if (!shouldSpawnAcpSession(input)) {
     return undefined;
   }
-  return AcpStructuredSession.create(acpCommand, input.projectLocation, input.threadId);
+  return AcpStructuredSession.create(acpCommand, input.projectLocation, input.threadId, {
+    ...(input.loadSessionErrorRewriter
+      ? { loadSessionErrorRewriter: input.loadSessionErrorRewriter }
+      : {}),
+  });
 }

src/supervisor/agents/base.ts

@@ -122,6 +122,14 @@ export interface CreateStructuredSessionInput {
    * return `undefined` for terminal-mode threads to skip the spawn.
    */
   presentationMode?: ThreadPresentationMode;
+  /**
+   * Optional adapter-supplied rewriter for `session/load` failures. The ACP
+   * session calls this when the agent rejects a resume so the adapter can
+   * surface provider-specific copy (e.g. Cursor's ACP doesn't yet support
+   * resuming sessions). Falls back to a generic "can't resume" message when
+   * omitted.
+   */
+  loadSessionErrorRewriter?: (error: unknown, sessionId: string) => Error;
 }
 
 /**

src/supervisor/agents/cursor/cursor.test.ts

@@ -11,6 +11,7 @@ import {
   buildCursorProbeSpec,
   createCursorAdapter,
   detectCursorTerminalStatus,
+  rewriteCursorLoadSessionError,
   sortCursorModels,
 } from "./index";
 import { buildCursorArgs } from "./argv";
@@ -42,6 +43,17 @@ describe("createCursorAdapter capabilities", () => {
   });
 });
 
+describe("rewriteCursorLoadSessionError", () => {
+  it("returns the Cursor-specific 'resume not supported' copy", () => {
+    const raw = new Error("Invalid params");
+    const out = rewriteCursorLoadSessionError(raw, "ses-1");
+    expect(out.message).toBe(
+      "Cursor's ACP integration doesn't currently support resuming chat sessions. Start a new thread to continue.",
+    );
+    expect((out as { cause?: unknown }).cause).toBe(raw);
+  });
+});
+
 describe("detectCursorTerminalStatus", () => {
   it("detects working from ctrl+c to stop", () => {
     expect(

src/supervisor/agents/cursor/index.ts

@@ -48,6 +48,18 @@ function cursorHookActiveTerminalFallback(hint: TerminalStatusHint): boolean {
   return hint.status === "needs_approval";
 }
 
+/**
+ * Cursor's ACP server advertises `loadSession: true` but immediately rejects
+ * every sessionId it issues via `session/new` with `-32602 Session not found`.
+ * Acknowledged Cursor bug (forum thread #155516) with no client workaround, so
+ * we replace the raw transport error with copy that names the limitation.
+ */
+export function rewriteCursorLoadSessionError(error: unknown, _sessionId: string): Error {
+  const message =
+    "Cursor's ACP integration doesn't currently support resuming chat sessions. Start a new thread to continue.";
+  return Object.assign(new Error(message), { cause: error });
+}
+
 export function createCursorAdapter(): AgentAdapter {
   let capabilities: AgentCapability = cursorDefaultCapabilities;
 
@@ -105,7 +117,10 @@ export function createCursorAdapter(): AgentAdapter {
         ["acp"],
         resolveAgentBinaryPath(input.projectLocation, "cursor-agent"),
       );
-      return createAcpStructuredSession(command, input);
+      return createAcpStructuredSession(command, {
+        ...input,
+        loadSessionErrorRewriter: rewriteCursorLoadSessionError,
+      });
     },
     buildDirectInput(prompt, _segments, _config, projectLocation) {
       // Cursor's TUI debounces fast incoming bytes as a paste burst. With