feat(checkpoints): per-write checkpoints, task-start baseline, and perWriteCheckpoints setting (B1, #1375)

Author: easonliang28

packages/types/src/global-settings.ts

@@ -99,6 +99,13 @@ export const MAX_CHECKPOINT_TIMEOUT_SECONDS = 60
  */
 export const DEFAULT_CHECKPOINT_TIMEOUT_SECONDS = 15
 
+/**
+ * Whether per-write checkpoints and task-start baseline are enabled by default.
+ * Master switch for the B cluster of checkpoint features.
+ * @default true
+ */
+export const DEFAULT_PER_WRITE_CHECKPOINTS = true
+
 /**
  * GlobalSettings
  */
@@ -200,6 +207,12 @@ export const globalSettingsSchema = z.object({
 		.min(MIN_CHECKPOINT_TIMEOUT_SECONDS)
 		.max(MAX_CHECKPOINT_TIMEOUT_SECONDS)
 		.optional(),
+	/**
+	 * Whether to record a shadow-git checkpoint after every successful write_to_file,
+	 * edit_file, and apply_patch (per-write checkpoints), plus a task-start baseline.
+	 * @default true
+	 */
+	perWriteCheckpoints: z.boolean().optional(),
 
 	ttsEnabled: z.boolean().optional(),
 	ttsSpeed: z.number().optional(),

packages/types/src/vscode-extension-host.ts

@@ -348,6 +348,7 @@ export type ExtensionState = Pick<
 
 	enableCheckpoints: boolean
 	checkpointTimeout: number // Timeout for checkpoint initialization in seconds (default: 15)
+	perWriteCheckpoints: boolean
 	maxOpenTabsContext: number // Maximum number of VSCode open tabs to include in context (0-500)
 	maxWorkspaceFiles: number // Maximum number of files to include in current working directory details (0-500)
 	showRooIgnoredFiles: boolean // Whether to show .rooignore'd files in listings

src/core/task/Task.ts

@@ -314,6 +314,10 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 	public lastMessageTs?: number
 	private autoApprovalTimeoutRef?: NodeJS.Timeout
 
+	// B1: task-start baseline checkpoint recorded at most once per Task instance
+	// (initiateTaskLoop also runs on resume-from-history, hence the guard).
+	private taskStartBaselineDone = false
+
 	// Tool Use
 	consecutiveMistakeCount: number = 0
 	consecutiveMistakeLimit: number
@@ -2492,6 +2496,17 @@ export class Task extends EventEmitter<TaskEvents> implements TaskLike {
 		// arm needed.
 		void getCheckpointService(this)
 
+		// B1 task-start baseline: record one suppressed checkpoint per Task instance
+		// so the shadow repo has a clean pre-task root. Gated by the live
+		// perWriteCheckpoints setting (default-on: only skip when explicitly false).
+		if (!this.taskStartBaselineDone) {
+			this.taskStartBaselineDone = true
+			const baselineEnabled = (await this.providerRef.deref()?.getState())?.perWriteCheckpoints
+			if (baselineEnabled !== false) {
+				void this.checkpointSave(false, true)
+			}
+		}
+
 		let nextUserContent = userContent
 		let includeFileDetails = true
 

src/core/task/__tests__/Task.spec.ts

@@ -3289,6 +3289,49 @@ describe("Cline", () => {
 		})
 	})
 
+	describe("task-start baseline (B1 perWriteCheckpoints)", () => {
+		it("records one suppressed baseline checkpoint per Task instance at loop start", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "baseline task",
+				startTask: false,
+			})
+			const taskAccess = getTaskTestAccess(task)
+			const saveSpy = vi.spyOn(task, "checkpointSave").mockResolvedValue(undefined)
+			const state = await mockProvider.getState()
+			vi.spyOn(mockProvider, "getState").mockResolvedValue(state)
+
+			// Abort before the loop so only the pre-loop setup runs.
+			task.abort = true
+
+			await taskAccess.initiateTaskLoop([])
+			await taskAccess.initiateTaskLoop([])
+
+			expect(saveSpy).toHaveBeenCalledOnce()
+			expect(saveSpy).toHaveBeenCalledWith(false, true)
+		})
+
+		it("does not record a baseline checkpoint when perWriteCheckpoints is disabled", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "baseline disabled task",
+				startTask: false,
+			})
+			const taskAccess = getTaskTestAccess(task)
+			const saveSpy = vi.spyOn(task, "checkpointSave").mockResolvedValue(undefined)
+			const state = await mockProvider.getState()
+			vi.spyOn(mockProvider, "getState").mockResolvedValue({ ...state, perWriteCheckpoints: false })
+
+			task.abort = true
+
+			await taskAccess.initiateTaskLoop([])
+
+			expect(saveSpy).not.toHaveBeenCalled()
+		})
+	})
+
 	describe("start()", () => {
 		it("should be a no-op if the task was already started in the constructor", () => {
 			const task = new Task({

src/core/tools/ApplyPatchTool.ts

@@ -6,6 +6,7 @@ import { type ClineSayTool, DEFAULT_WRITE_DELAY_MS } from "@roo-code/types"
 import { getReadablePath } from "../../utils/path"
 import { isPathOutsideWorkspace } from "../../utils/pathUtils"
 import { Task } from "../task/Task"
+import { checkpointSave } from "../checkpoints"
 import { formatResponse } from "../prompts/responses"
 import { RecordSource } from "../context-tracking/FileContextTrackerTypes"
 import { fileExistsAtPath } from "../../utils/fs"
@@ -131,6 +132,13 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			}
 
 			task.consecutiveMistakeCount = 0
+
+			// B1: one checkpoint for the whole patch (not per file). Live setting
+			// with default-on semantics: skip only when explicitly false.
+			const perWriteCheckpoints = (await task.providerRef?.deref()?.getState())?.perWriteCheckpoints
+			if (perWriteCheckpoints !== false) {
+				void checkpointSave(task, false, true).catch(() => {})
+			}
 		} catch (error) {
 			await handleError("apply patch", error as Error)
 			await task.diffViewProvider.reset()

src/core/tools/EditFileTool.ts

@@ -11,6 +11,7 @@ import { RecordSource } from "../context-tracking/FileContextTrackerTypes"
 import { fileExistsAtPath } from "../../utils/fs"
 import { EXPERIMENT_IDS, experiments } from "../../shared/experiments"
 import { sanitizeUnifiedDiff, computeDiffStats } from "../diff/stats"
+import { checkpointSave } from "../../core/checkpoints"
 import type { ToolUse } from "../../shared/tools"
 
 import { BaseTool, ToolCallbacks } from "./BaseTool"
@@ -392,6 +393,7 @@ export class EditFileTool extends BaseTool<"edit_file"> {
 			const state = await provider?.getState()
 			const diagnosticsEnabled = state?.diagnosticsEnabled ?? true
 			const writeDelayMs = state?.writeDelayMs ?? DEFAULT_WRITE_DELAY_MS
+			const perWriteCheckpoints = state?.perWriteCheckpoints ?? true
 			const isPreventFocusDisruptionEnabled = experiments.isEnabled(
 				state?.experiments ?? {},
 				EXPERIMENT_IDS.PREVENT_FOCUS_DISRUPTION,
@@ -463,6 +465,10 @@ export class EditFileTool extends BaseTool<"edit_file"> {
 
 			pushToolResult(message + replacementInfo)
 
+			if (perWriteCheckpoints) {
+				void checkpointSave(task, false, true).catch(() => {})
+			}
+
 			await task.diffViewProvider.reset()
 			this.resetPartialState()
 

src/core/tools/WriteToFileTool.ts

@@ -14,6 +14,7 @@ import { isPathOutsideWorkspace } from "../../utils/pathUtils"
 import { unescapeHtmlEntities } from "../../utils/text-normalization"
 import { EXPERIMENT_IDS, experiments } from "../../shared/experiments"
 import { convertNewFileToUnifiedDiff, computeDiffStats, sanitizeUnifiedDiff } from "../diff/stats"
+import { checkpointSave } from "../checkpoints"
 import type { ToolUse } from "../../shared/tools"
 
 import { BaseTool, ToolCallbacks } from "./BaseTool"
@@ -103,6 +104,7 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> {
 			const state = await provider?.getState()
 			const diagnosticsEnabled = state?.diagnosticsEnabled ?? true
 			const writeDelayMs = state?.writeDelayMs ?? DEFAULT_WRITE_DELAY_MS
+			const perWriteCheckpoints = state?.perWriteCheckpoints ?? true
 			const isPreventFocusDisruptionEnabled = experiments.isEnabled(
 				state?.experiments ?? {},
 				EXPERIMENT_IDS.PREVENT_FOCUS_DISRUPTION,
@@ -179,6 +181,10 @@ export class WriteToFileTool extends BaseTool<"write_to_file"> {
 
 			pushToolResult(message)
 
+			if (perWriteCheckpoints) {
+				void checkpointSave(task, false, true).catch(() => {})
+			}
+
 			await task.diffViewProvider.reset()
 			this.resetPartialState()
 

src/core/tools/__tests__/applyPatchTool.execute.spec.ts

@@ -5,6 +5,7 @@ import type { MockedFunction } from "vitest"
 import { fileExistsAtPath } from "../../../utils/fs"
 import { isPathOutsideWorkspace } from "../../../utils/pathUtils"
 import type { Task } from "../../task/Task"
+import { checkpointSave } from "../../checkpoints"
 import { ApplyPatchTool } from "../ApplyPatchTool"
 
 vi.mock("fs/promises", () => ({
@@ -22,6 +23,10 @@ vi.mock("../../../utils/pathUtils", () => ({
 	isPathOutsideWorkspace: vi.fn().mockReturnValue(false),
 }))
 
+vi.mock("../../checkpoints", () => ({
+	checkpointSave: vi.fn().mockResolvedValue(undefined),
+}))
+
 describe("ApplyPatchTool.execute - delete file success path", () => {
 	const mockedFileExistsAtPath = fileExistsAtPath as MockedFunction<typeof fileExistsAtPath>
 	const mockedIsPathOutsideWorkspace = isPathOutsideWorkspace as MockedFunction<typeof isPathOutsideWorkspace>
@@ -38,6 +43,7 @@ describe("ApplyPatchTool.execute - delete file success path", () => {
 		| "say"
 		| "processQueuedMessages"
 		| "didEditFile"
+		| "providerRef"
 	>
 	let mockAskApproval: MockedFunction<(...args: unknown[]) => Promise<boolean>>
 	let mockHandleError: MockedFunction<(...args: unknown[]) => Promise<void>>
@@ -52,6 +58,11 @@ describe("ApplyPatchTool.execute - delete file success path", () => {
 		mockTask = {
 			cwd: "/workspace/project",
 			consecutiveMistakeCount: 0,
+			providerRef: {
+				deref: vi.fn().mockReturnValue({
+					getState: vi.fn().mockResolvedValue({}),
+				}),
+			} as unknown as Task["providerRef"],
 			recordToolUsage: vi.fn(),
 			recordToolError: vi.fn(),
 			rooIgnoreController: {
@@ -93,4 +104,57 @@ describe("ApplyPatchTool.execute - delete file success path", () => {
 		expect(mockTask.recordToolUsage).not.toHaveBeenCalled()
 		expect(mockTask.recordToolError).not.toHaveBeenCalled()
 	})
+
+	describe("per-write checkpoints (B1)", () => {
+		const deletePatch = `*** Begin Patch
+*** Delete File: src/obsolete.ts
+*** End Patch`
+		const mockedCheckpointSave = checkpointSave as MockedFunction<typeof checkpointSave>
+
+		it("records one suppressed checkpoint for the whole patch (default-on)", async () => {
+			await tool.execute({ patch: deletePatch }, mockTask as Task, {
+				askApproval: mockAskApproval,
+				handleError: mockHandleError,
+				pushToolResult: mockPushToolResult,
+			})
+
+			expect(mockPushToolResult).toHaveBeenCalledWith(expect.stringContaining("Successfully deleted"))
+			expect(mockedCheckpointSave).toHaveBeenCalledOnce()
+			expect(mockedCheckpointSave).toHaveBeenCalledWith(mockTask as Task, false, true)
+		})
+
+		it("does not record a checkpoint when perWriteCheckpoints is disabled", async () => {
+			// Structural cast for the test double (matches the mock style used for the controllers above).
+			const ref = (mockTask["providerRef"] as unknown as { deref: MockedFunction<() => unknown> }).deref
+			ref.mockReturnValue({
+				getState: vi.fn().mockResolvedValue({ perWriteCheckpoints: false }),
+			})
+
+			await tool.execute({ patch: deletePatch }, mockTask as Task, {
+				askApproval: mockAskApproval,
+				handleError: mockHandleError,
+				pushToolResult: mockPushToolResult,
+			})
+
+			expect(mockPushToolResult).toHaveBeenCalledWith(expect.stringContaining("Successfully deleted"))
+			expect(mockedCheckpointSave).not.toHaveBeenCalled()
+		})
+
+		it("does not record a checkpoint when patch processing fails", async () => {
+			// A malformed patch fails at parse time, before the change loop and
+			// the post-loop checkpoint hook.
+			const badPatch = `*** Begin Patch
+*** This is not a valid hunk
+*** End Patch`
+
+			await tool.execute({ patch: badPatch }, mockTask as Task, {
+				askApproval: mockAskApproval,
+				handleError: mockHandleError,
+				pushToolResult: mockPushToolResult,
+			})
+
+			expect(mockTask.recordToolError).toHaveBeenCalledWith("apply_patch")
+			expect(mockedCheckpointSave).not.toHaveBeenCalled()
+		})
+	})
 })

src/core/tools/__tests__/editFileTool.spec.ts

@@ -7,6 +7,7 @@ import { fileExistsAtPath } from "../../../utils/fs"
 import { isPathOutsideWorkspace } from "../../../utils/pathUtils"
 import { getReadablePath } from "../../../utils/path"
 import { ToolUse, ToolResponse, AskApproval, HandleError, PushToolResult } from "../../../shared/tools"
+import { checkpointSave } from "../../checkpoints"
 import { editFileTool } from "../EditFileTool"
 
 vi.mock("fs/promises", () => ({
@@ -59,6 +60,10 @@ vi.mock("../../diff/stats", () => ({
 	computeDiffStats: vi.fn(() => ({ additions: 1, deletions: 1 })),
 }))
 
+vi.mock("../../checkpoints", () => ({
+	checkpointSave: vi.fn().mockResolvedValue(undefined),
+}))
+
 vi.mock("vscode", () => ({
 	window: {
 		showWarningMessage: vi.fn().mockResolvedValue(undefined),
@@ -774,4 +779,41 @@ describe("editFileTool", () => {
 			expect(mockAskApproval).toHaveBeenCalled()
 		})
 	})
+
+	describe("per-write checkpoints (B1)", () => {
+		const mockedCheckpointSave = checkpointSave as MockedFunction<typeof checkpointSave>
+
+		it("records one suppressed checkpoint after a successful edit (default-on)", async () => {
+			await executeEditFileTool({})
+
+			expect(mockTask.consecutiveMistakeCount).toBe(0)
+			expect(mockedCheckpointSave).toHaveBeenCalledOnce()
+			expect(mockedCheckpointSave).toHaveBeenCalledWith(mockTask, false, true)
+		})
+
+		it("does not record a checkpoint when perWriteCheckpoints is disabled", async () => {
+			mockTask.providerRef.deref = vi.fn().mockReturnValue({
+				getState: vi.fn().mockResolvedValue({
+					diagnosticsEnabled: true,
+					writeDelayMs: 1000,
+					experiments: {},
+					perWriteCheckpoints: false,
+				}),
+			})
+
+			await executeEditFileTool({})
+
+			expect(mockTask.consecutiveMistakeCount).toBe(0)
+			expect(mockedCheckpointSave).not.toHaveBeenCalled()
+		})
+
+		it("does not record a checkpoint when the edit fails", async () => {
+			mockTask.diffViewProvider.saveChanges.mockRejectedValue(new Error("save failed"))
+
+			await executeEditFileTool({})
+
+			expect(mockHandleError).toHaveBeenCalledWith("edit_file", expect.any(Error))
+			expect(mockedCheckpointSave).not.toHaveBeenCalled()
+		})
+	})
 })