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

packages/types/src/global-settings.ts

@@ -111,6 +111,13 @@
  */
 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
  */
@@ -220,6 +227,12 @@
 		.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

@@ -352,6 +352,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

@@ -453,6 +453,9 @@
 	public lastMessageTs?: number
 	private autoApprovalTimeoutRef?: NodeJS.Timeout
 
+	// B1: task-start baseline, recorded at most once (initiateTaskLoop also runs on resume).
+	private taskStartBaselineDone = false
+
 	// Tool Use
 	consecutiveMistakeCount: number = 0
 	consecutiveMistakeLimit: number
@@ -3705,6 +3708,24 @@
 		// arm needed.
 		void getCheckpointService(this)
 
+		// B1 task-start baseline: a suppressed pre-task root commit (default-on).
+		// History resumes skip it: the baseline belongs to the original task start
+		// (exactly once per task), and the resumed task's shadow repo already carries
+		// a baseline for the first post-resume write checkpoint to diff against.
+		// An already-aborted task skips it too: the loop will never run, so the
+		// save would only add latency to a task that is being disposed.
+		if (!this.taskStartBaselineDone && !this._isHistoryTask && !this.abort) {
+			this.taskStartBaselineDone = true
+			const baselineEnabled = (await this.providerRef.deref()?.getState())?.perWriteCheckpoints
+			// Cancellation can arrive while the state lookup is pending; recheck
+			// before the save so a canceled task performs no checkpoint work.
+			if (baselineEnabled !== false && !this.abort) {
+				// allowEmpty=true so a clean workspace still produces the baseline
+				// commit; awaited so the first per-write checkpoint cannot interleave.
+				await this.checkpointSave(true, true)
+			}
+		}
+
 		let nextUserContent = userContent
 		let includeFileDetails = true
 
@@ -3730,7 +3751,7 @@
 				// the user hits max requests and denies resetting the count.
 				break
 			} else {
 				nextUserContent = [{ type: "text", text: formatResponse.noToolsUsed() }]
 			}
 		}
 	}
@@ -6289,6 +6310,14 @@
 	 * @param context - Context string for logging (e.g., the calling tool name)
 	 */
 	public processQueuedMessages(): void {
+		// An aborted task must not dequeue queued messages: submitUserMessage
+		// rejects once abort is set, so consuming the queue here would drop the
+		// message instead of leaving it for the resume/abort flow. Tools await
+		// checkpoint saves before handing off, so a cancellation can land between
+		// the write and this call.
+		if (this.abort) {
+			return
+		}
 		try {
 			if (!this.messageQueueService.isEmpty()) {
 				const queued = this.messageQueueService.dequeueMessage()

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

@@ -6027,6 +6027,175 @@ 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)
+
+			// End the loop after the first request; abort stays false so the
+			// baseline block (not the loop) is what the save spy observes.
+			vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
+
+			await taskAccess.initiateTaskLoop([])
+			await taskAccess.initiateTaskLoop([])
+
+			expect(saveSpy).toHaveBeenCalledOnce()
+			expect(saveSpy).toHaveBeenCalledWith(true, true)
+		})
+
+		it("does not record a baseline when the task resumes from history", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				historyItem: {
+					id: "resumed-baseline-task",
+					number: 1,
+					ts: Date.now(),
+					task: "resumed baseline task",
+					tokensIn: 10,
+					tokensOut: 5,
+					totalCost: 0.001,
+				},
+				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)
+
+			vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
+
+			await taskAccess.initiateTaskLoop([])
+
+			// A history resume must not re-record the baseline: it belongs to the
+			// original task start (exactly once per task).
+			expect(saveSpy).not.toHaveBeenCalled()
+		})
+
+		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, so default-on applies.
+			const unsetState = { ...state }
+			Reflect.deleteProperty(unsetState, "perWriteCheckpoints")
+			vi.spyOn(mockProvider, "getState").mockResolvedValue(unsetState as typeof state)
+
+			vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
+
+			await taskAccess.initiateTaskLoop([])
+
+			expect(saveSpy).toHaveBeenCalledOnce()
+			expect(saveSpy).toHaveBeenCalledWith(true, 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 })
+
+			vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
+
+			await taskAccess.initiateTaskLoop([])
+
+			expect(saveSpy).not.toHaveBeenCalled()
+		})
+
+		it("does not record a baseline when the task is already aborted", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "aborted 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)
+
+			task.abort = true
+
+			await taskAccess.initiateTaskLoop([])
+
+			// A task cancelled before the loop starts must not pay for (or await)
+			// a baseline checkpoint it will never use.
+			expect(saveSpy).not.toHaveBeenCalled()
+		})
+
+		it("does not record a baseline when cancellation arrives during the state lookup", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "racy baseline task",
+				startTask: false,
+			})
+			const taskAccess = getTaskTestAccess(task)
+			const saveSpy = vi.spyOn(task, "checkpointSave").mockResolvedValue(undefined)
+			const state = await mockProvider.getState()
+			type StateResult = Awaited<ReturnType<typeof mockProvider.getState>>
+			let resolveState: (value: StateResult | PromiseLike<StateResult>) => void = () => {}
+			const statePromise = new Promise<StateResult>((resolve) => (resolveState = resolve))
+			vi.spyOn(mockProvider, "getState").mockReturnValue(statePromise)
+
+			const loopPromise = taskAccess.initiateTaskLoop([])
+			// Cancellation lands while the state lookup is still pending.
+			task.abort = true
+			resolveState({ ...state, perWriteCheckpoints: true })
+			await loopPromise
+
+			// The post-lookup recheck must skip the save for the canceled task.
+			expect(saveSpy).not.toHaveBeenCalled()
+		})
+
+		it("awaits the baseline checkpoint before entering the request loop", async () => {
+			const task = new Task({
+				provider: mockProvider,
+				apiConfiguration: mockApiConfig,
+				task: "baseline await task",
+				startTask: false,
+			})
+			const taskAccess = getTaskTestAccess(task)
+			type SaveResult = Awaited<ReturnType<typeof task.checkpointSave>>
+			let resolveSave: (value: SaveResult | PromiseLike<SaveResult>) => void = () => {}
+			const saveSpy = vi
+				.spyOn(task, "checkpointSave")
+				.mockImplementation(() => new Promise<SaveResult>((resolve) => (resolveSave = resolve)))
+			const requestSpy = vi.spyOn(task, "recursivelyMakeClineRequests").mockResolvedValue(true)
+			vi.spyOn(mockProvider, "getState").mockResolvedValue({ ...(await mockProvider.getState()) })
+			const loopPromise = taskAccess.initiateTaskLoop([])
+
+			// The loop must not enter while the baseline checkpoint is still in flight.
+			await new Promise((resolve) => setTimeout(resolve, 0))
+			expect(saveSpy).toHaveBeenCalledOnce()
+			expect(requestSpy).not.toHaveBeenCalled()
+
+			resolveSave()
+			await loopPromise
+			expect(requestSpy).toHaveBeenCalled()
+		})
+	})
+
 	describe("start()", () => {
 		it("should be a no-op if the task was already started in the constructor", () => {
 			const task = new Task({
@@ -6950,6 +7119,34 @@ describe("Queued message processing after condense", () => {
 		expect(submitSpy).toHaveBeenCalledWith("queued text", ["img1.png"])
 		expect(task.messageQueueService.isEmpty()).toBe(true)
 	})
+	it("does not dequeue queued messages once the task is aborted", () => {
+		// Tools await the checkpoint before handing off queued work; a
+		// cancellation landing during that await must not consume the queued
+		// message: submitUserMessage rejects once abort is set, so dequeuing
+		// would drop the input instead of leaving it for the resume flow.
+		if (!TelemetryService.hasInstance()) {
+			TelemetryService.createInstance([])
+		}
+		const provider = createProvider()
+		const task = new Task({
+			provider,
+			apiConfiguration: apiConfig,
+			task: "initial task",
+			startTask: false,
+		})
+		const submitSpy = vi.spyOn(task, "submitUserMessage").mockResolvedValue(undefined)
+
+		task.messageQueueService.addMessage("queued text")
+		task.abort = true
+		try {
+			task.processQueuedMessages()
+		} finally {
+			task.abort = false
+		}
+
+		expect(submitSpy).not.toHaveBeenCalled()
+		expect(task.messageQueueService.isEmpty()).toBe(false)
+	})
 
 	it("does not cross-drain queues between separate tasks", async () => {
 		const providerA = createProvider()