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,73 @@ 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("records the baseline checkpoint when the setting is unset (default-on)", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "baseline unset task",
+				startTask: false,
+			})
+			const taskAccess = getTaskTestAccess(task)
+			const saveSpy = vi.spyOn(task, "checkpointSave").mockResolvedValue(undefined)
+			const state = await mockProvider.getState()
+			// Unset: the property is absent from the state object, so only the
+			// default-on semantics (skip only when explicitly false) apply.
+			const unsetState = { ...state }
+			Reflect.deleteProperty(unsetState, "perWriteCheckpoints")
+			vi.spyOn(mockProvider, "getState").mockResolvedValue(unsetState as typeof state)
+
+			task.abort = true
+
+			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"
@@ -102,7 +103,10 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 				return
 			}
 
-			// Process each file change
+			// Process each file change. The handlers report whether their file
+			// operation succeeded, so a rejected approval or a failed local write
+			// does not get checkpointed as if the patch had succeeded.
+			let patchSucceeded = true
 			for (const change of changes) {
 				const relPath = change.path
 				const absolutePath = path.resolve(task.cwd, relPath)
@@ -120,17 +124,39 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 
 				if (change.type === "add") {
 					// Create new file
-					await this.handleAddFile(change, absolutePath, relPath, task, callbacks, isWriteProtected)
+					patchSucceeded =
+						(await this.handleAddFile(change, absolutePath, relPath, task, callbacks, isWriteProtected)) &&
+						patchSucceeded
 				} else if (change.type === "delete") {
 					// Delete file
-					await this.handleDeleteFile(absolutePath, relPath, task, callbacks, isWriteProtected)
+					patchSucceeded =
+						(await this.handleDeleteFile(absolutePath, relPath, task, callbacks, isWriteProtected)) &&
+						patchSucceeded
 				} else if (change.type === "update") {
 					// Update file
-					await this.handleUpdateFile(change, absolutePath, relPath, task, callbacks, isWriteProtected)
+					patchSucceeded =
+						(await this.handleUpdateFile(
+							change,
+							absolutePath,
+							relPath,
+							task,
+							callbacks,
+							isWriteProtected,
+						)) && patchSucceeded
 				}
 			}
 
 			task.consecutiveMistakeCount = 0
+
+			// B1: one checkpoint for the whole patch (not per file), and only when
+			// every file operation succeeded. Live setting with default-on
+			// semantics: skip only when explicitly false.
+			if (patchSucceeded) {
+				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()
@@ -144,7 +170,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		task: Task,
 		callbacks: ToolCallbacks,
 		isWriteProtected: boolean,
-	): Promise<void> {
+	): Promise<boolean> {
 		const { askApproval, pushToolResult } = callbacks
 
 		// Check if file already exists
@@ -155,7 +181,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			const errorMessage = `File already exists: ${relPath}. Use Update File instead.`
 			await task.say("error", errorMessage)
 			pushToolResult(formatResponse.toolError(errorMessage))
-			return
+			return false
 		}
 
 		const newContent = change.newContent || ""
@@ -209,7 +235,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			}
 			pushToolResult("Changes were rejected by the user.")
 			await task.diffViewProvider.reset()
-			return
+			return false
 		}
 
 		// Save the changes
@@ -227,6 +253,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		pushToolResult(message)
 		await task.diffViewProvider.reset()
 		task.processQueuedMessages()
+		return true
 	}
 
 	private async handleDeleteFile(
@@ -235,7 +262,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		task: Task,
 		callbacks: ToolCallbacks,
 		isWriteProtected: boolean,
-	): Promise<void> {
+	): Promise<boolean> {
 		const { askApproval, pushToolResult } = callbacks
 
 		// Check if file exists
@@ -246,7 +273,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			const errorMessage = `File not found: ${relPath}. Cannot delete a non-existent file.`
 			await task.say("error", errorMessage)
 			pushToolResult(formatResponse.toolError(errorMessage))
-			return
+			return false
 		}
 
 		const isOutsideWorkspace = isPathOutsideWorkspace(absolutePath)
@@ -268,7 +295,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 
 		if (!didApprove) {
 			pushToolResult("Delete operation was rejected by the user.")
-			return
+			return false
 		}
 
 		// Delete the file
@@ -278,12 +305,13 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			const errorMessage = `Failed to delete file '${relPath}': ${error instanceof Error ? error.message : String(error)}`
 			await task.say("error", errorMessage)
 			pushToolResult(formatResponse.toolError(errorMessage))
-			return
+			return false
 		}
 
 		task.didEditFile = true
 		pushToolResult(`Successfully deleted ${relPath}`)
 		task.processQueuedMessages()
+		return true
 	}
 
 	private async handleUpdateFile(
@@ -293,7 +321,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		task: Task,
 		callbacks: ToolCallbacks,
 		isWriteProtected: boolean,
-	): Promise<void> {
+	): Promise<boolean> {
 		const { askApproval, pushToolResult } = callbacks
 
 		// Check if file exists
@@ -304,7 +332,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			const errorMessage = `File not found: ${relPath}. Cannot update a non-existent file.`
 			await task.say("error", errorMessage)
 			pushToolResult(formatResponse.toolError(errorMessage))
-			return
+			return false
 		}
 
 		const originalContent = change.originalContent || ""
@@ -318,9 +346,11 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		// Generate and validate diff
 		const diff = formatResponse.createPrettyPatch(relPath, originalContent, newContent)
 		if (!diff) {
+			// A no-op change is not a failure: the patch processed cleanly and
+			// nothing was written, so the whole-patch success state is kept.
 			pushToolResult(`No changes needed for '${relPath}'`)
 			await task.diffViewProvider.reset()
-			return
+			return true
 		}
 
 		// Check experiment settings
@@ -366,7 +396,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 			}
 			pushToolResult("Changes were rejected by the user.")
 			await task.diffViewProvider.reset()
-			return
+			return false
 		}
 
 		// Handle file move if specified
@@ -379,7 +409,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 				await task.say("rooignore_error", change.movePath)
 				pushToolResult(formatResponse.rooIgnoreError(change.movePath))
 				await task.diffViewProvider.reset()
-				return
+				return false
 			}
 
 			// Check if destination path is write-protected
@@ -391,7 +421,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 				await task.say("error", errorMessage)
 				pushToolResult(formatResponse.toolError(errorMessage))
 				await task.diffViewProvider.reset()
-				return
+				return false
 			}
 
 			// Check if destination path is outside workspace
@@ -403,7 +433,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 				await task.say("error", errorMessage)
 				pushToolResult(formatResponse.toolError(errorMessage))
 				await task.diffViewProvider.reset()
-				return
+				return false
 			}
 
 			// Save new content to the new path
@@ -447,6 +477,7 @@ export class ApplyPatchTool extends BaseTool<"apply_patch"> {
 		pushToolResult(message)
 		await task.diffViewProvider.reset()
 		task.processQueuedMessages()
+		return true
 	}
 
 	override async handlePartial(task: Task, block: ToolUse<"apply_patch">): Promise<void> {

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()