From 351736baa119e8a9e71f1811edf37ef0615a0541 Mon Sep 17 00:00:00 2001
From: Julius Marminge <julius0216@outlook.com>
Date: Tue, 17 Feb 2026 10:39:23 -0800
Subject: [PATCH] Add provider checkpoints and thread rollback support

- add provider/WS contracts and server RPC handlers for listing/reverting checkpoints
- read and rollback Codex thread turns in the app server manager
- add ChatView checkpoint menu + store reducer support to revert local thread state
- expand backend, websocket, store, and contract tests for checkpoint flows
---
 apps/server/src/codexAppServerManager.test.ts |  89 +++++++++
 apps/server/src/codexAppServerManager.ts      |  80 ++++++++
 apps/server/src/providerManager.test.ts       | 132 +++++++++++++
 apps/server/src/providerManager.ts            | 182 ++++++++++++++++++
 apps/server/src/wsServer.test.ts              |  24 +++
 apps/server/src/wsServer.ts                   |   6 +
 apps/web/src/components/ChatView.tsx          | 150 ++++++++++++++-
 apps/web/src/store.test.ts                    |  62 ++++++
 apps/web/src/store.ts                         |  39 ++++
 apps/web/src/wsNativeApi.ts                   |   3 +
 packages/contracts/src/ipc.ts                 |   8 +
 packages/contracts/src/provider.test.ts       |  73 +++++++
 packages/contracts/src/provider.ts            |  38 ++++
 packages/contracts/src/ws.ts                  |   2 +
 14 files changed, 887 insertions(+), 1 deletion(-)

diff --git a/apps/server/src/codexAppServerManager.test.ts b/apps/server/src/codexAppServerManager.test.ts
index 4a97814a73080a72532e2204dfc5c306a2be8ee5..e1ce2fcd1244c97a607e7c4873d1bee54bf3fc64 100644
--- a/apps/server/src/codexAppServerManager.test.ts
+++ b/apps/server/src/codexAppServerManager.test.ts
@@ -43,6 +43,36 @@ function createSendTurnHarness() {
   return { manager, context, requireSession, sendRequest, updateSession };
 }
 
+function createThreadControlHarness() {
+  const manager = new CodexAppServerManager();
+  const context = {
+    session: {
+      sessionId: "sess_1",
+      provider: "codex",
+      status: "ready",
+      threadId: "thread_1",
+      createdAt: "2026-02-10T00:00:00.000Z",
+      updatedAt: "2026-02-10T00:00:00.000Z",
+    },
+  };
+
+  const requireSession = vi
+    .spyOn(
+      manager as unknown as { requireSession: (sessionId: string) => unknown },
+      "requireSession",
+    )
+    .mockReturnValue(context);
+  const sendRequest = vi.spyOn(
+    manager as unknown as { sendRequest: (...args: unknown[]) => Promise<unknown> },
+    "sendRequest",
+  );
+  const updateSession = vi
+    .spyOn(manager as unknown as { updateSession: (...args: unknown[]) => void }, "updateSession")
+    .mockImplementation(() => {});
+
+  return { manager, context, requireSession, sendRequest, updateSession };
+}
+
 describe("classifyCodexStderrLine", () => {
   it("ignores empty lines", () => {
     expect(classifyCodexStderrLine("   ")).toBeNull();
@@ -198,3 +228,62 @@ describe("sendTurn", () => {
     ).rejects.toThrow("Turn input must include text or attachments.");
   });
 });
+
+describe("thread checkpoint control", () => {
+  it("reads thread turns from thread/read", async () => {
+    const { manager, context, requireSession, sendRequest } = createThreadControlHarness();
+    sendRequest.mockResolvedValue({
+      thread: {
+        id: "thread_1",
+        turns: [
+          {
+            id: "turn_1",
+            items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
+          },
+        ],
+      },
+    });
+
+    const result = await manager.readThread("sess_1");
+
+    expect(requireSession).toHaveBeenCalledWith("sess_1");
+    expect(sendRequest).toHaveBeenCalledWith(context, "thread/read", {
+      threadId: "thread_1",
+      includeTurns: true,
+    });
+    expect(result).toEqual({
+      threadId: "thread_1",
+      turns: [
+        {
+          id: "turn_1",
+          items: [{ type: "userMessage", content: [{ type: "text", text: "hello" }] }],
+        },
+      ],
+    });
+  });
+
+  it("rolls back turns via thread/rollback and resets session running state", async () => {
+    const { manager, context, sendRequest, updateSession } = createThreadControlHarness();
+    sendRequest.mockResolvedValue({
+      thread: {
+        id: "thread_1",
+        turns: [],
+      },
+    });
+
+    const result = await manager.rollbackThread("sess_1", 2);
+
+    expect(sendRequest).toHaveBeenCalledWith(context, "thread/rollback", {
+      threadId: "thread_1",
+      numTurns: 2,
+    });
+    expect(updateSession).toHaveBeenCalledWith(context, {
+      status: "ready",
+      activeTurnId: undefined,
+    });
+    expect(result).toEqual({
+      threadId: "thread_1",
+      turns: [],
+    });
+  });
+});
diff --git a/apps/server/src/codexAppServerManager.ts b/apps/server/src/codexAppServerManager.ts
index 27da26fb0bfdf8a522ab138746a2513d54a9eab4..01722a69667c6df8e684ddfbd72a39b59557597a 100644
--- a/apps/server/src/codexAppServerManager.ts
+++ b/apps/server/src/codexAppServerManager.ts
@@ -65,6 +65,16 @@ interface JsonRpcNotification {
   params?: unknown;
 }
 
+export interface CodexThreadTurnSnapshot {
+  id: string;
+  items: unknown[];
+}
+
+export interface CodexThreadSnapshot {
+  threadId: string;
+  turns: CodexThreadTurnSnapshot[];
+}
+
 const ANSI_ESCAPE_CHAR = String.fromCharCode(27);
 const ANSI_ESCAPE_REGEX = new RegExp(`${ANSI_ESCAPE_CHAR}\\[[0-9;]*m`, "g");
 const CODEX_STDERR_LOG_REGEX =
@@ -331,6 +341,41 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
     });
   }
 
+  async readThread(sessionId: string): Promise<CodexThreadSnapshot> {
+    const context = this.requireSession(sessionId);
+    const threadId = context.session.threadId;
+    if (!threadId) {
+      throw new Error("Session is missing a thread id.");
+    }
+
+    const response = await this.sendRequest(context, "thread/read", {
+      threadId,
+      includeTurns: true,
+    });
+    return this.parseThreadSnapshot("thread/read", response);
+  }
+
+  async rollbackThread(sessionId: string, numTurns: number): Promise<CodexThreadSnapshot> {
+    const context = this.requireSession(sessionId);
+    const threadId = context.session.threadId;
+    if (!threadId) {
+      throw new Error("Session is missing a thread id.");
+    }
+    if (!Number.isInteger(numTurns) || numTurns < 1) {
+      throw new Error("numTurns must be an integer >= 1.");
+    }
+
+    const response = await this.sendRequest(context, "thread/rollback", {
+      threadId,
+      numTurns,
+    });
+    this.updateSession(context, {
+      status: "ready",
+      activeTurnId: undefined,
+    });
+    return this.parseThreadSnapshot("thread/rollback", response);
+  }
+
   async respondToRequest(
     sessionId: string,
     requestId: string,
@@ -742,6 +787,31 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
     return undefined;
   }
 
+  private parseThreadSnapshot(method: string, response: unknown): CodexThreadSnapshot {
+    const responseRecord = this.readObject(response);
+    const thread = this.readObject(responseRecord, "thread");
+    const threadId = this.readString(thread, "id") ?? this.readString(responseRecord, "threadId");
+    if (!threadId) {
+      throw new Error(`${method} response did not include a thread id.`);
+    }
+
+    const turnsRaw = this.readArray(thread, "turns") ?? [];
+    const turns = turnsRaw.map((turnValue, index) => {
+      const turn = this.readObject(turnValue);
+      const turnId = this.readString(turn, "id") ?? `${threadId}:turn:${index + 1}`;
+      const items = this.readArray(turn, "items") ?? [];
+      return {
+        id: turnId,
+        items,
+      };
+    });
+
+    return {
+      threadId,
+      turns,
+    };
+  }
+
   private isServerRequest(value: unknown): value is JsonRpcRequest {
     if (!value || typeof value !== "object") {
       return false;
@@ -823,6 +893,16 @@ export class CodexAppServerManager extends EventEmitter<CodexAppServerManagerEve
     return target as Record<string, unknown>;
   }
 
+  private readArray(value: unknown, key?: string): unknown[] | undefined {
+    const target =
+      key === undefined
+        ? value
+        : value && typeof value === "object"
+          ? (value as Record<string, unknown>)[key]
+          : undefined;
+    return Array.isArray(target) ? target : undefined;
+  }
+
   private readString(value: unknown, key: string): string | undefined {
     if (!value || typeof value !== "object") {
       return undefined;
diff --git a/apps/server/src/providerManager.test.ts b/apps/server/src/providerManager.test.ts
index 424cfce16c0f9ab13c038f9b3fa0f78bbc4f7dc5..7d7e7ad76fdef7321ecabfbda7a715bed79b6e1d 100644
--- a/apps/server/src/providerManager.test.ts
+++ b/apps/server/src/providerManager.test.ts
@@ -59,4 +59,136 @@ describe("ProviderManager", () => {
 
     manager.dispose();
   });
+
+  it("rejects checkpoint operations for unknown sessions", async () => {
+    const manager = new ProviderManager();
+
+    await expect(
+      manager.listCheckpoints({
+        sessionId: "missing-session",
+      }),
+    ).rejects.toThrow("Unknown provider session: missing-session");
+
+    await expect(
+      manager.revertToCheckpoint({
+        sessionId: "missing-session",
+        turnCount: 0,
+      }),
+    ).rejects.toThrow("Unknown provider session: missing-session");
+
+    manager.dispose();
+  });
+
+  it("derives checkpoints from thread turns", async () => {
+    const manager = new ProviderManager();
+    const codex = (
+      manager as unknown as {
+        codex: {
+          hasSession: (sessionId: string) => boolean;
+          readThread: (sessionId: string) => Promise<{
+            threadId: string;
+            turns: Array<{ id: string; items: unknown[] }>;
+          }>;
+        };
+      }
+    ).codex;
+
+    codex.hasSession = () => true;
+    codex.readThread = async () => ({
+      threadId: "thr_1",
+      turns: [
+        {
+          id: "turn_1",
+          items: [
+            {
+              type: "userMessage",
+              content: [{ type: "text", text: "Refactor the logger" }],
+            },
+            {
+              type: "agentMessage",
+              text: "I refactored it.",
+            },
+          ],
+        },
+      ],
+    });
+
+    const result = await manager.listCheckpoints({
+      sessionId: "sess_1",
+    });
+
+    expect(result).toEqual({
+      threadId: "thr_1",
+      checkpoints: [
+        {
+          id: "root",
+          turnCount: 0,
+          messageCount: 0,
+          label: "Start of conversation",
+          isCurrent: false,
+        },
+        {
+          id: "turn_1",
+          turnCount: 1,
+          messageCount: 2,
+          label: "Turn 1",
+          preview: "Refactor the logger",
+          isCurrent: true,
+        },
+      ],
+    });
+
+    manager.dispose();
+  });
+
+  it("rolls back from a selected checkpoint turn count", async () => {
+    const manager = new ProviderManager();
+    const codex = (
+      manager as unknown as {
+        codex: {
+          hasSession: (sessionId: string) => boolean;
+          readThread: (sessionId: string) => Promise<{
+            threadId: string;
+            turns: Array<{ id: string; items: unknown[] }>;
+          }>;
+          rollbackThread: (sessionId: string, numTurns: number) => Promise<{
+            threadId: string;
+            turns: Array<{ id: string; items: unknown[] }>;
+          }>;
+        };
+      }
+    ).codex;
+
+    const rollbackCalls: Array<{ sessionId: string; numTurns: number }> = [];
+    codex.hasSession = () => true;
+    codex.readThread = async () => ({
+      threadId: "thr_1",
+      turns: [
+        { id: "turn_1", items: [] },
+        { id: "turn_2", items: [] },
+        { id: "turn_3", items: [] },
+      ],
+    });
+    codex.rollbackThread = async (sessionId, numTurns) => {
+      rollbackCalls.push({ sessionId, numTurns });
+      return {
+        threadId: "thr_1",
+        turns: [{ id: "turn_1", items: [] }],
+      };
+    };
+
+    const result = await manager.revertToCheckpoint({
+      sessionId: "sess_1",
+      turnCount: 1,
+    });
+
+    expect(rollbackCalls).toEqual([{ sessionId: "sess_1", numTurns: 2 }]);
+    expect(result.threadId).toBe("thr_1");
+    expect(result.turnCount).toBe(1);
+    expect(result.messageCount).toBe(0);
+    expect(result.rolledBackTurns).toBe(2);
+    expect(result.checkpoints).toHaveLength(2);
+
+    manager.dispose();
+  });
 });
diff --git a/apps/server/src/providerManager.ts b/apps/server/src/providerManager.ts
index 52fb1b648475846cdc7448108419bab9a3c3418e..58977b29b9e73bbbd4fcc0ccf0e6e4b75a75b79c 100644
--- a/apps/server/src/providerManager.ts
+++ b/apps/server/src/providerManager.ts
@@ -3,8 +3,13 @@ import fs from "node:fs";
 import path from "node:path";
 
 import {
+  type ProviderCheckpoint,
   type ProviderEvent,
   type ProviderInterruptTurnInput,
+  type ProviderListCheckpointsInput,
+  type ProviderListCheckpointsResult,
+  type ProviderRevertToCheckpointInput,
+  type ProviderRevertToCheckpointResult,
   type ProviderRespondToRequestInput,
   type ProviderSendTurnInput,
   type ProviderSession,
@@ -12,17 +17,144 @@ import {
   type ProviderStopSessionInput,
   type ProviderTurnStartResult,
   providerInterruptTurnInputSchema,
+  providerListCheckpointsInputSchema,
+  providerRevertToCheckpointInputSchema,
   providerRespondToRequestInputSchema,
   providerSendTurnInputSchema,
   providerSessionStartInputSchema,
   providerStopSessionInputSchema,
 } from "@t3tools/contracts";
+import type { CodexThreadTurnSnapshot } from "./codexAppServerManager";
 import { CodexAppServerManager } from "./codexAppServerManager";
 
 export interface ProviderManagerEvents {
   event: [event: ProviderEvent];
 }
 
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function trimToPreview(value: string): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= 120) {
+    return normalized;
+  }
+  return `${normalized.slice(0, 117)}...`;
+}
+
+function summarizeUserMessageContent(content: unknown[]): string | undefined {
+  const segments: string[] = [];
+
+  for (const part of content) {
+    const record = asObject(part);
+    const type = asString(record?.type);
+    if (!type) continue;
+
+    if (type === "text") {
+      const text = asString(record?.text);
+      if (text && text.trim().length > 0) {
+        segments.push(text.trim());
+      }
+      continue;
+    }
+
+    if (type === "image") {
+      segments.push("[Image attachment]");
+      continue;
+    }
+
+    if (type === "localImage") {
+      segments.push("[Local image attachment]");
+      continue;
+    }
+  }
+
+  if (segments.length === 0) {
+    return undefined;
+  }
+  return trimToPreview(segments.join(" "));
+}
+
+function summarizeTurn(turn: CodexThreadTurnSnapshot): {
+  messageCountDelta: number;
+  preview?: string;
+} {
+  let messageCountDelta = 0;
+  let preview: string | undefined;
+
+  for (const item of turn.items) {
+    const record = asObject(item);
+    const type = asString(record?.type);
+    if (!type) continue;
+
+    if (type === "userMessage") {
+      messageCountDelta += 1;
+      if (!preview) {
+        const content = asArray(record?.content);
+        preview = summarizeUserMessageContent(content);
+      }
+      continue;
+    }
+
+    if (type === "agentMessage") {
+      messageCountDelta += 1;
+      if (!preview) {
+        const text = asString(record?.text);
+        if (text && text.trim().length > 0) {
+          preview = trimToPreview(text);
+        }
+      }
+    }
+  }
+
+  return {
+    messageCountDelta,
+    ...(preview ? { preview } : {}),
+  };
+}
+
+function buildCheckpoints(turns: CodexThreadTurnSnapshot[]): ProviderCheckpoint[] {
+  const checkpoints: ProviderCheckpoint[] = [];
+  let messageCount = 0;
+  const isEmpty = turns.length === 0;
+  checkpoints.push({
+    id: "root",
+    turnCount: 0,
+    messageCount: 0,
+    label: "Start of conversation",
+    isCurrent: isEmpty,
+  });
+
+  for (let index = 0; index < turns.length; index += 1) {
+    const turn = turns[index];
+    if (!turn) continue;
+    const turnSummary = summarizeTurn(turn);
+    messageCount += turnSummary.messageCountDelta;
+    checkpoints.push({
+      id: turn.id,
+      turnCount: index + 1,
+      messageCount,
+      label: `Turn ${index + 1}`,
+      ...(turnSummary.preview ? { preview: turnSummary.preview } : {}),
+      isCurrent: index === turns.length - 1,
+    });
+  }
+
+  return checkpoints;
+}
+
 export class ProviderManager extends EventEmitter<ProviderManagerEvents> {
   private readonly codex = new CodexAppServerManager();
   private readonly threadLogsDir: string;
@@ -101,6 +233,56 @@ export class ProviderManager extends EventEmitter<ProviderManagerEvents> {
     return this.codex.listSessions();
   }
 
+  async listCheckpoints(raw: ProviderListCheckpointsInput): Promise<ProviderListCheckpointsResult> {
+    const input = providerListCheckpointsInputSchema.parse(raw);
+    if (!this.codex.hasSession(input.sessionId)) {
+      throw new Error(`Unknown provider session: ${input.sessionId}`);
+    }
+
+    const snapshot = await this.codex.readThread(input.sessionId);
+    return {
+      threadId: snapshot.threadId,
+      checkpoints: buildCheckpoints(snapshot.turns),
+    };
+  }
+
+  async revertToCheckpoint(
+    raw: ProviderRevertToCheckpointInput,
+  ): Promise<ProviderRevertToCheckpointResult> {
+    const input = providerRevertToCheckpointInputSchema.parse(raw);
+    if (!this.codex.hasSession(input.sessionId)) {
+      throw new Error(`Unknown provider session: ${input.sessionId}`);
+    }
+
+    const beforeSnapshot = await this.codex.readThread(input.sessionId);
+    const currentTurnCount = beforeSnapshot.turns.length;
+    if (input.turnCount > currentTurnCount) {
+      throw new Error(
+        `Checkpoint turn count ${input.turnCount} exceeds current turn count ${currentTurnCount}.`,
+      );
+    }
+
+    const requestedRollbackTurns = currentTurnCount - input.turnCount;
+    const afterSnapshot =
+      requestedRollbackTurns > 0
+        ? await this.codex.rollbackThread(input.sessionId, requestedRollbackTurns)
+        : beforeSnapshot;
+    const checkpoints = buildCheckpoints(afterSnapshot.turns);
+    const currentCheckpoint =
+      checkpoints.find((checkpoint) => checkpoint.isCurrent) ??
+      checkpoints[checkpoints.length - 1] ??
+      checkpoints[0];
+    const rolledBackTurns = Math.max(0, currentTurnCount - afterSnapshot.turns.length);
+
+    return {
+      threadId: afterSnapshot.threadId,
+      turnCount: currentCheckpoint?.turnCount ?? 0,
+      messageCount: currentCheckpoint?.messageCount ?? 0,
+      rolledBackTurns,
+      checkpoints,
+    };
+  }
+
   stopAll(): void {
     this.codex.stopAll();
   }
diff --git a/apps/server/src/wsServer.test.ts b/apps/server/src/wsServer.test.ts
index 635bfbb81291c39a8240ae27b7e8277e5ee7863e..a860c5d8ae20143b1d1eeff0c36e7b60a1bf167d 100644
--- a/apps/server/src/wsServer.test.ts
+++ b/apps/server/src/wsServer.test.ts
@@ -646,6 +646,30 @@ describe("WebSocket Server", () => {
     expect(response.result).toEqual([]);
   });
 
+  it("returns unknown-session errors for checkpoint RPCs without an active provider session", async () => {
+    server = createTestServer({ cwd: "/test" });
+    await server.start();
+    const addr = server.httpServer.address();
+    const port = typeof addr === "object" && addr !== null ? addr.port : 0;
+
+    const ws = await connectWs(port);
+    connections.push(ws);
+    await waitForMessage(ws);
+
+    const listResponse = await sendRequest(ws, WS_METHODS.providersListCheckpoints, {
+      sessionId: "missing-session",
+    });
+    expect(listResponse.result).toBeUndefined();
+    expect(listResponse.error?.message).toContain("Unknown provider session");
+
+    const revertResponse = await sendRequest(ws, WS_METHODS.providersRevertToCheckpoint, {
+      sessionId: "missing-session",
+      turnCount: 0,
+    });
+    expect(revertResponse.result).toBeUndefined();
+    expect(revertResponse.error?.message).toContain("Unknown provider session");
+  });
+
   it("routes terminal RPC methods and broadcasts terminal events", async () => {
     const cwd = makeTempDir("t3code-ws-terminal-cwd-");
     const terminalManager = new MockTerminalManager();
diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.ts
index ce9878cd469bb982e0ba6a706f8a3d98b514fa73..ec0d73d59e3b7652c37020559f312a5219758aa8 100644
--- a/apps/server/src/wsServer.ts
+++ b/apps/server/src/wsServer.ts
@@ -310,6 +310,12 @@ export function createServer(options: ServerOptions) {
       case WS_METHODS.providersListSessions:
         return providerManager.listSessions();
 
+      case WS_METHODS.providersListCheckpoints:
+        return providerManager.listCheckpoints(request.params as never);
+
+      case WS_METHODS.providersRevertToCheckpoint:
+        return providerManager.revertToCheckpoint(request.params as never);
+
       case WS_METHODS.projectsList:
         return projectRegistry.list();
 
diff --git a/apps/web/src/components/ChatView.tsx b/apps/web/src/components/ChatView.tsx
index 27904e29e5ba563f60fc0295c6c2f307bf62ecb9..2fdccc071529599b4ff4795f96695f021c7cee52 100644
--- a/apps/web/src/components/ChatView.tsx
+++ b/apps/web/src/components/ChatView.tsx
@@ -8,6 +8,7 @@ import {
   PROVIDER_SEND_TURN_MAX_INPUT_CHARS,
   PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
   PROVIDER_SEND_TURN_MAX_IMAGE_BYTES,
+  type ProviderCheckpoint,
   type ResolvedKeybindingsConfig,
   type ProviderApprovalDecision,
   type ProviderSendTurnAttachmentInput,
@@ -345,6 +346,9 @@ export default function ChatView() {
   const [expandedImage, setExpandedImage] = useState<ExpandedImagePreview | null>(null);
   const [isSending, setIsSending] = useState(false);
   const [isConnecting, setIsConnecting] = useState(false);
+  const [isLoadingCheckpoints, setIsLoadingCheckpoints] = useState(false);
+  const [isRevertingCheckpoint, setIsRevertingCheckpoint] = useState(false);
+  const [checkpoints, setCheckpoints] = useState<ProviderCheckpoint[]>([]);
   const [selectedEffort, setSelectedEffort] = useState(DEFAULT_REASONING);
   const [envMode, setEnvMode] = useState<"local" | "worktree">("local");
   const [isSwitchingRuntimeMode, setIsSwitchingRuntimeMode] = useState(false);
@@ -374,7 +378,7 @@ export default function ChatView() {
     activeThread?.model ?? activeProject?.model ?? DEFAULT_MODEL,
   );
   const phase = derivePhase(activeThread?.session ?? null);
-  const isWorking = phase === "running" || isSending || isConnecting;
+  const isWorking = phase === "running" || isSending || isConnecting || isRevertingCheckpoint;
   const nowIso = new Date(nowTick).toISOString();
   const workLogEntries = useMemo(
     () => deriveWorkLogEntries(activeThread?.events ?? [], undefined),
@@ -575,6 +579,12 @@ export default function ChatView() {
   );
   const hasReachedTerminalLimit =
     (activeThread?.terminalIds.length ?? 0) >= MAX_THREAD_TERMINAL_COUNT;
+  const canCheckpoint =
+    Boolean(api && activeThread && (activeThread.codexThreadId ?? activeThread.session?.threadId)) &&
+    phase !== "running" &&
+    !isSending &&
+    !isConnecting &&
+    !isRevertingCheckpoint;
 
   const revokePreviewUrls = useCallback((images: Array<{ previewUrl?: string }>) => {
     for (const image of images) {
@@ -963,6 +973,12 @@ export default function ChatView() {
     );
   }, [composerMenuItems, composerMenuOpen]);
 
+  useEffect(() => {
+    setCheckpoints([]);
+    setIsLoadingCheckpoints(false);
+    setIsRevertingCheckpoint(false);
+  }, [activeThread?.id]);
+
   useEffect(() => {
     if (!activeThread?.id || activeThread.terminalOpen) return;
     const frame = window.requestAnimationFrame(() => {
@@ -1311,6 +1327,78 @@ export default function ChatView() {
     }
   };
 
+  const loadCheckpoints = async (): Promise<ProviderCheckpoint[] | null> => {
+    if (!api || !activeThread) return null;
+    if (phase === "running" || isSending || isConnecting || isRevertingCheckpoint) {
+      return null;
+    }
+    const hasThreadIdentity = Boolean(activeThread.codexThreadId ?? activeThread.session?.threadId);
+    if (!hasThreadIdentity) {
+      setCheckpoints([]);
+      return [];
+    }
+
+    setIsLoadingCheckpoints(true);
+    setThreadError(activeThread.id, null);
+    try {
+      const sessionInfo = await ensureSession();
+      if (!sessionInfo) {
+        return null;
+      }
+      const result = await api.providers.listCheckpoints({
+        sessionId: sessionInfo.sessionId,
+      });
+      setCheckpoints(result.checkpoints);
+      return result.checkpoints;
+    } catch (err) {
+      setThreadError(
+        activeThread.id,
+        err instanceof Error ? err.message : "Failed to load checkpoints.",
+      );
+      return null;
+    } finally {
+      setIsLoadingCheckpoints(false);
+    }
+  };
+
+  const onRevertToCheckpoint = async (checkpoint: ProviderCheckpoint) => {
+    if (!api || !activeThread || checkpoint.isCurrent || isRevertingCheckpoint) {
+      return;
+    }
+    if (phase === "running" || isSending || isConnecting) {
+      setThreadError(activeThread.id, "Interrupt the current turn before reverting checkpoints.");
+      return;
+    }
+
+    setIsRevertingCheckpoint(true);
+    setThreadError(activeThread.id, null);
+    try {
+      const sessionInfo = await ensureSession();
+      if (!sessionInfo) {
+        return;
+      }
+      const result = await api.providers.revertToCheckpoint({
+        sessionId: sessionInfo.sessionId,
+        turnCount: checkpoint.turnCount,
+      });
+      dispatch({
+        type: "REVERT_TO_CHECKPOINT",
+        threadId: activeThread.id,
+        sessionId: sessionInfo.sessionId,
+        threadRuntimeId: result.threadId,
+        messageCount: result.messageCount,
+      });
+      setCheckpoints(result.checkpoints);
+    } catch (err) {
+      setThreadError(
+        activeThread.id,
+        err instanceof Error ? err.message : "Failed to revert checkpoint.",
+      );
+    } finally {
+      setIsRevertingCheckpoint(false);
+    }
+  };
+
   const onSend = async (e: FormEvent) => {
     e.preventDefault();
     if (!api || !activeThread || isSending || isConnecting) return;
@@ -1641,6 +1729,14 @@ export default function ChatView() {
           onAddProjectScript={saveProjectScript}
           onUpdateProjectScript={updateProjectScript}
           onToggleDiff={onToggleDiff}
+          checkpoints={checkpoints}
+          canCheckpoint={canCheckpoint}
+          isLoadingCheckpoints={isLoadingCheckpoints}
+          isRevertingCheckpoint={isRevertingCheckpoint}
+          onOpenCheckpoints={() => {
+            void loadCheckpoints();
+          }}
+          onRevertToCheckpoint={onRevertToCheckpoint}
         />
       </header>
 
@@ -1974,6 +2070,12 @@ interface ChatHeaderProps {
   onAddProjectScript: (input: NewProjectScriptInput) => Promise<void>;
   onUpdateProjectScript: (scriptId: string, input: NewProjectScriptInput) => Promise<void>;
   onToggleDiff: () => void;
+  checkpoints: ProviderCheckpoint[];
+  canCheckpoint: boolean;
+  isLoadingCheckpoints: boolean;
+  isRevertingCheckpoint: boolean;
+  onOpenCheckpoints: () => void;
+  onRevertToCheckpoint: (checkpoint: ProviderCheckpoint) => void;
 }
 
 const ChatHeader = memo(function ChatHeader({
@@ -1989,6 +2091,12 @@ const ChatHeader = memo(function ChatHeader({
   onAddProjectScript,
   onUpdateProjectScript,
   onToggleDiff,
+  checkpoints,
+  canCheckpoint,
+  isLoadingCheckpoints,
+  isRevertingCheckpoint,
+  onOpenCheckpoints,
+  onRevertToCheckpoint,
 }: ChatHeaderProps) {
   return (
     <>
@@ -2011,6 +2119,46 @@ const ChatHeader = memo(function ChatHeader({
         )}
         {activeProjectName && <OpenInPicker keybindings={keybindings} />}
         {activeProjectName && <GitActionsControl api={api} gitCwd={gitCwd} />}
+        <Menu>
+          <MenuTrigger
+            render={
+              <Button
+                size="xs"
+                variant="ghost"
+                className="text-muted-foreground/70 hover:text-foreground/80"
+                disabled={!canCheckpoint || isRevertingCheckpoint}
+                onClick={onOpenCheckpoints}
+              >
+                {isRevertingCheckpoint
+                  ? "Reverting..."
+                  : isLoadingCheckpoints
+                    ? "Loading..."
+                    : "Checkpoints"}
+              </Button>
+            }
+          />
+          <MenuPopup align="end" className="w-72">
+            {!canCheckpoint ? (
+              <MenuItem disabled>Send at least one message to create checkpoints.</MenuItem>
+            ) : checkpoints.length === 0 ? (
+              <MenuItem disabled>
+                {isLoadingCheckpoints ? "Loading checkpoints..." : "No checkpoints available."}
+              </MenuItem>
+            ) : (
+              checkpoints.map((checkpoint) => (
+                <MenuItem
+                  key={checkpoint.id}
+                  disabled={checkpoint.isCurrent || isRevertingCheckpoint}
+                  onClick={() => onRevertToCheckpoint(checkpoint)}
+                >
+                  {checkpoint.label}
+                  {checkpoint.preview ? `: ${checkpoint.preview}` : ""}
+                  {checkpoint.isCurrent ? " (Current)" : ""}
+                </MenuItem>
+              ))
+            )}
+          </MenuPopup>
+        </Menu>
         <Button
           size="xs"
           variant="ghost"
diff --git a/apps/web/src/store.test.ts b/apps/web/src/store.test.ts
index 764d6ec4d479333629e9d1979b44a96c6e6330f7..4ba4b4a5022cf8588b2ebb000835c6057fd4bebf 100644
--- a/apps/web/src/store.test.ts
+++ b/apps/web/src/store.test.ts
@@ -718,4 +718,66 @@ describe("store reducer thread continuity", () => {
     expect(next.threads[0]?.latestTurnCompletedAt).toBe(completedAt);
     expect(next.threads[0]?.lastVisitedAt).toBe(completedAt);
   });
+
+  it("reverts thread state to a checkpoint snapshot", () => {
+    const state = makeState(
+      makeThread({
+        codexThreadId: "thr_before",
+        session: makeSession({
+          status: "running",
+          threadId: "thr_before",
+          activeTurnId: "turn-live",
+        }),
+        messages: [
+          {
+            id: "m-1",
+            role: "user",
+            text: "First",
+            createdAt: "2026-02-08T10:00:00.000Z",
+            streaming: false,
+          },
+          {
+            id: "m-2",
+            role: "assistant",
+            text: "First reply",
+            createdAt: "2026-02-08T10:00:01.000Z",
+            streaming: false,
+          },
+          {
+            id: "m-3",
+            role: "user",
+            text: "Second",
+            createdAt: "2026-02-08T10:00:02.000Z",
+            streaming: false,
+          },
+        ],
+        events: [
+          makeEvent({
+            method: "turn/started",
+            turnId: "turn-live",
+          }),
+        ],
+        error: "temporary failure",
+        latestTurnId: "turn-live",
+        latestTurnStartedAt: "2026-02-08T10:00:03.000Z",
+      }),
+    );
+
+    const next = reducer(state, {
+      type: "REVERT_TO_CHECKPOINT",
+      threadId: "thread-local-1",
+      sessionId: "sess-1",
+      threadRuntimeId: "thr_after",
+      messageCount: 2,
+    });
+
+    expect(next.threads[0]?.codexThreadId).toBe("thr_after");
+    expect(next.threads[0]?.messages.map((message) => message.id)).toEqual(["m-1", "m-2"]);
+    expect(next.threads[0]?.events).toEqual([]);
+    expect(next.threads[0]?.error).toBeNull();
+    expect(next.threads[0]?.session?.status).toBe("ready");
+    expect(next.threads[0]?.session?.activeTurnId).toBeUndefined();
+    expect(next.threads[0]?.session?.threadId).toBe("thr_after");
+    expect(next.threads[0]?.latestTurnId).toBeUndefined();
+  });
 });
diff --git a/apps/web/src/store.ts b/apps/web/src/store.ts
index b45e36e17e68e78f8e3090655494c3e85242d3a7..e3dc1d50dfca59c9b4e8b465007a10b86baef998 100644
--- a/apps/web/src/store.ts
+++ b/apps/web/src/store.ts
@@ -59,6 +59,13 @@ type Action =
   | { type: "SET_ERROR"; threadId: string; error: string | null }
   | { type: "SET_THREAD_TITLE"; threadId: string; title: string }
   | { type: "SET_THREAD_MODEL"; threadId: string; model: string }
+  | {
+      type: "REVERT_TO_CHECKPOINT";
+      threadId: string;
+      sessionId: string;
+      threadRuntimeId: string;
+      messageCount: number;
+    }
   | {
       type: "SET_THREAD_BRANCH";
       threadId: string;
@@ -834,6 +841,38 @@ export function reducer(state: AppState, action: Action): AppState {
         })),
       };
 
+    case "REVERT_TO_CHECKPOINT":
+      return {
+        ...state,
+        threads: updateThread(state.threads, action.threadId, (t) => {
+          const nextMessageCount = Math.max(0, Math.floor(action.messageCount));
+          const now = new Date().toISOString();
+          return {
+            ...t,
+            codexThreadId: action.threadRuntimeId,
+            session:
+              t.session?.sessionId === action.sessionId
+                ? {
+                    ...t.session,
+                    status: "ready",
+                    threadId: action.threadRuntimeId,
+                    activeTurnId: undefined,
+                    updatedAt: now,
+                    lastError: undefined,
+                  }
+                : t.session,
+            messages: t.messages.slice(0, nextMessageCount),
+            events: [],
+            error: null,
+            latestTurnId: undefined,
+            latestTurnStartedAt: undefined,
+            latestTurnCompletedAt: undefined,
+            latestTurnDurationMs: undefined,
+            lastVisitedAt: now,
+          };
+        }),
+      };
+
     case "SET_THREAD_BRANCH": {
       return {
         ...state,
diff --git a/apps/web/src/wsNativeApi.ts b/apps/web/src/wsNativeApi.ts
index bf5dc8b300f515b38e8cf46d1b460d47d1a160ca..80e1e8f72e84b2f813fa4314572942e9addb6b7e 100644
--- a/apps/web/src/wsNativeApi.ts
+++ b/apps/web/src/wsNativeApi.ts
@@ -91,6 +91,9 @@ export function createWsNativeApi(): NativeApi {
       respondToRequest: (input) => transport.request(WS_METHODS.providersRespondToRequest, input),
       stopSession: (input) => transport.request(WS_METHODS.providersStopSession, input),
       listSessions: () => transport.request(WS_METHODS.providersListSessions),
+      listCheckpoints: (input) => transport.request(WS_METHODS.providersListCheckpoints, input),
+      revertToCheckpoint: (input) =>
+        transport.request(WS_METHODS.providersRevertToCheckpoint, input),
       onEvent: (callback) =>
         transport.subscribe(WS_CHANNELS.providerEvent, callback as (data: unknown) => void),
     },
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 3153037a9e540ca6cdb68413f0c1fb512d14cec2..317bff60abbc4aad55db4510482ba07a93a54332 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -18,6 +18,10 @@ import type {
 import type {
   ProviderEvent,
   ProviderInterruptTurnInput,
+  ProviderListCheckpointsInput,
+  ProviderListCheckpointsResult,
+  ProviderRevertToCheckpointInput,
+  ProviderRevertToCheckpointResult,
   ProviderRespondToRequestInput,
   ProviderSendTurnInput,
   ProviderSession,
@@ -89,6 +93,10 @@ export interface NativeApi {
     respondToRequest: (input: ProviderRespondToRequestInput) => Promise<void>;
     stopSession: (input: ProviderStopSessionInput) => Promise<void>;
     listSessions: () => Promise<ProviderSession[]>;
+    listCheckpoints: (input: ProviderListCheckpointsInput) => Promise<ProviderListCheckpointsResult>;
+    revertToCheckpoint: (
+      input: ProviderRevertToCheckpointInput,
+    ) => Promise<ProviderRevertToCheckpointResult>;
     onEvent: (callback: (event: ProviderEvent) => void) => () => void;
   };
   projects: {
diff --git a/packages/contracts/src/provider.test.ts b/packages/contracts/src/provider.test.ts
index e2ccd990be8c53361843f1bb61a4289692527a93..bc406c37055f64f7fe7bb134f50e5059eca0b531 100644
--- a/packages/contracts/src/provider.test.ts
+++ b/packages/contracts/src/provider.test.ts
@@ -2,7 +2,12 @@ import { describe, expect, it } from "vitest";
 
 import {
   PROVIDER_SEND_TURN_MAX_ATTACHMENTS,
+  providerCheckpointSchema,
   providerEventSchema,
+  providerListCheckpointsInputSchema,
+  providerListCheckpointsResultSchema,
+  providerRevertToCheckpointInputSchema,
+  providerRevertToCheckpointResultSchema,
   providerRespondToRequestInputSchema,
   providerSendTurnInputSchema,
   providerSessionStartInputSchema,
@@ -157,3 +162,71 @@ describe("providerRespondToRequestInputSchema", () => {
     ).toThrow();
   });
 });
+
+describe("provider checkpoint schemas", () => {
+  it("accepts list checkpoint inputs", () => {
+    const parsed = providerListCheckpointsInputSchema.parse({
+      sessionId: "sess_1",
+    });
+    expect(parsed.sessionId).toBe("sess_1");
+  });
+
+  it("accepts checkpoint records and list results", () => {
+    const checkpoint = providerCheckpointSchema.parse({
+      id: "turn_1",
+      turnCount: 1,
+      messageCount: 2,
+      label: "Turn 1",
+      preview: "Summarize this file",
+      isCurrent: true,
+    });
+    expect(checkpoint.turnCount).toBe(1);
+
+    const listResult = providerListCheckpointsResultSchema.parse({
+      threadId: "thr_1",
+      checkpoints: [checkpoint],
+    });
+    expect(listResult.checkpoints).toHaveLength(1);
+  });
+
+  it("accepts revert checkpoint input/result", () => {
+    const input = providerRevertToCheckpointInputSchema.parse({
+      sessionId: "sess_1",
+      turnCount: 2,
+    });
+    expect(input.turnCount).toBe(2);
+
+    const result = providerRevertToCheckpointResultSchema.parse({
+      threadId: "thr_1",
+      turnCount: 2,
+      messageCount: 4,
+      rolledBackTurns: 1,
+      checkpoints: [
+        {
+          id: "root",
+          turnCount: 0,
+          messageCount: 0,
+          label: "Start of conversation",
+          isCurrent: false,
+        },
+        {
+          id: "turn_2",
+          turnCount: 2,
+          messageCount: 4,
+          label: "Turn 2",
+          isCurrent: true,
+        },
+      ],
+    });
+    expect(result.rolledBackTurns).toBe(1);
+  });
+
+  it("rejects negative turn counts", () => {
+    expect(() =>
+      providerRevertToCheckpointInputSchema.parse({
+        sessionId: "sess_1",
+        turnCount: -1,
+      }),
+    ).toThrow();
+  });
+});
diff --git a/packages/contracts/src/provider.ts b/packages/contracts/src/provider.ts
index 01910dd9f3fec0c0c7811416c8c23d0e1401d23d..ca599a347ae09907442ecbdae6ef0c4744c80f34 100644
--- a/packages/contracts/src/provider.ts
+++ b/packages/contracts/src/provider.ts
@@ -111,6 +111,37 @@ export const providerStopSessionInputSchema = z.object({
   sessionId: z.string().min(1),
 });
 
+export const providerListCheckpointsInputSchema = z.object({
+  sessionId: z.string().min(1),
+});
+
+export const providerCheckpointSchema = z.object({
+  id: z.string().min(1),
+  turnCount: z.number().int().min(0),
+  messageCount: z.number().int().min(0),
+  label: z.string().min(1),
+  preview: z.string().min(1).optional(),
+  isCurrent: z.boolean(),
+});
+
+export const providerListCheckpointsResultSchema = z.object({
+  threadId: z.string().min(1),
+  checkpoints: z.array(providerCheckpointSchema),
+});
+
+export const providerRevertToCheckpointInputSchema = z.object({
+  sessionId: z.string().min(1),
+  turnCount: z.number().int().min(0),
+});
+
+export const providerRevertToCheckpointResultSchema = z.object({
+  threadId: z.string().min(1),
+  turnCount: z.number().int().min(0),
+  messageCount: z.number().int().min(0),
+  rolledBackTurns: z.number().int().min(0),
+  checkpoints: z.array(providerCheckpointSchema),
+});
+
 export const providerRespondToRequestInputSchema = z.object({
   sessionId: z.string().min(1),
   requestId: z.string().min(1),
@@ -151,6 +182,13 @@ export type ProviderSendTurnInput = z.input<typeof providerSendTurnInputSchema>;
 export type ProviderTurnStartResult = z.infer<typeof providerTurnStartResultSchema>;
 export type ProviderInterruptTurnInput = z.input<typeof providerInterruptTurnInputSchema>;
 export type ProviderStopSessionInput = z.input<typeof providerStopSessionInputSchema>;
+export type ProviderListCheckpointsInput = z.input<typeof providerListCheckpointsInputSchema>;
+export type ProviderCheckpoint = z.infer<typeof providerCheckpointSchema>;
+export type ProviderListCheckpointsResult = z.infer<typeof providerListCheckpointsResultSchema>;
+export type ProviderRevertToCheckpointInput = z.input<typeof providerRevertToCheckpointInputSchema>;
+export type ProviderRevertToCheckpointResult = z.infer<
+  typeof providerRevertToCheckpointResultSchema
+>;
 export type ProviderRespondToRequestInput = z.input<typeof providerRespondToRequestInputSchema>;
 export type ProviderEventKind = z.infer<typeof providerEventKindSchema>;
 export type ProviderEvent = z.infer<typeof providerEventSchema>;
diff --git a/packages/contracts/src/ws.ts b/packages/contracts/src/ws.ts
index 7d4abb60fc710e3bc9d35472fd6440244c320497..ef395962cfcc45356efda310b4d6615ddaf52a56 100644
--- a/packages/contracts/src/ws.ts
+++ b/packages/contracts/src/ws.ts
@@ -10,6 +10,8 @@ export const WS_METHODS = {
   providersRespondToRequest: "providers.respondToRequest",
   providersStopSession: "providers.stopSession",
   providersListSessions: "providers.listSessions",
+  providersListCheckpoints: "providers.listCheckpoints",
+  providersRevertToCheckpoint: "providers.revertToCheckpoint",
 
   // Project registry methods
   projectsList: "projects.list",
-- 
2.54.0