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

packages/types/src/global-settings.ts

@@ -114,6 +114,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
  */
@@ -223,6 +230,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

@@ -370,6 +370,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/checkpoints/__tests__/checkpoint.test.ts

@@ -112,6 +112,179 @@ describe("Checkpoint functionality", () => {
 	})
 
 	describe("checkpointSave", () => {
+		it("serializes concurrent saves for the same task so stageAll + commit never overlap", async () => {
+			const order: string[] = []
+			let resolveFirst: (value: { commit: string }) => void = () => {}
+			mockCheckpointService.saveCheckpoint
+				.mockImplementationOnce(() => {
+					order.push("first:start")
+					return new Promise((resolve) => {
+						resolveFirst = resolve
+					})
+				})
+				.mockImplementationOnce(async () => {
+					order.push("second:start")
+					return { commit: "second-commit" }
+				})
+
+			const first = checkpointSave(mockTask, false, true)
+			const second = checkpointSave(mockTask, false, true)
+
+			// The second save must not reach the service while the first is still running:
+			// a queued save owns the stageAll + commit pair until it settles.
+			await new Promise((resolve) => setTimeout(resolve, 10))
+			expect(order).toEqual(["first:start"])
+
+			resolveFirst({ commit: "first-commit" })
+			await Promise.all([first, second])
+			expect(order).toEqual(["first:start", "second:start"])
+		})
+
+		it("drops a queued save whose checkpoint window expired behind a stalled predecessor", async () => {
+			// A stalled baseline releases the task after checkpointTimeout, but the queue used to
+			// start it anyway, however late, committing whatever the workspace had become by then.
+			// It must not: the save is dropped and the caller resolves with no commit.
+			mockTask.checkpointTimeout = 0.01
+			const order: string[] = []
+			let resolveFirst: (value: { commit: string }) => void = () => {}
+			mockCheckpointService.saveCheckpoint
+				.mockImplementationOnce(() => {
+					order.push("stalled:start")
+					return new Promise((resolve) => {
+						resolveFirst = resolve
+					})
+				})
+				.mockImplementation(async () => {
+					order.push("late:start")
+					return { commit: "late-commit" }
+				})
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+			const stalled = checkpointSave(mockTask, true, true)
+			const queued = await (async () => {
+				await new Promise((resolve) => setTimeout(resolve, 5))
+				const second = checkpointSave(mockTask, false, true)
+				// Give the expired request its turn behind the still-running baseline, then release
+				// the baseline so the queue drains.
+				await new Promise((resolve) => setTimeout(resolve, 30))
+				resolveFirst({ commit: "stalled-commit" })
+				return second
+			})()
+
+			const second = await queued
+			await stalled
+			// Only the stalled baseline ever reached the shadow git; the expired save never started,
+			// so no commit describes a workspace that has since moved on.
+			expect(order).toEqual(["stalled:start"])
+			expect(mockCheckpointService.saveCheckpoint).toHaveBeenCalledTimes(1)
+			expect(second).toBeUndefined()
+			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("skipping queued per-write checkpoint save"))
+			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("expired behind a slower checkpoint"))
+			warnSpy.mockRestore()
+		})
+
+		it("drops a queued save for a task that was canceled while it waited", async () => {
+			mockTask.checkpointTimeout = 15
+			const order: string[] = []
+			let resolveFirst: (value: { commit: string }) => void = () => {}
+			mockCheckpointService.saveCheckpoint
+				.mockImplementationOnce(() => {
+					order.push("stalled:start")
+					return new Promise((resolve) => {
+						resolveFirst = resolve
+					})
+				})
+				.mockImplementation(async () => {
+					order.push("canceled:start")
+					return { commit: "canceled-commit" }
+				})
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+			mockTask.abort = false
+
+			const stalled = checkpointSave(mockTask, true, true)
+			const queued = checkpointSave(mockTask, false, true)
+			await new Promise((resolve) => setTimeout(resolve, 5))
+			// Cancellation arrives while the save is queued, before its turn.
+			mockTask.abort = true
+			resolveFirst({ commit: "stalled-commit" })
+
+			const second = await queued
+			await stalled
+
+			expect(order).toEqual(["stalled:start"])
+			expect(mockCheckpointService.saveCheckpoint).toHaveBeenCalledTimes(1)
+			expect(second).toBeUndefined()
+			expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining("task canceled"))
+			warnSpy.mockRestore()
+			mockTask.abort = false
+		})
+
+		it("runs a save requested after a stalled predecessor settles, exactly once each", async () => {
+			// The gate must not poison the queue: the dropped request stays dropped, while a fresh
+			// request after the stall settles gets its normal turn.
+			mockTask.checkpointTimeout = 0.01
+			const order: string[] = []
+			let resolveFirst: (value: { commit: string }) => void = () => {}
+			mockCheckpointService.saveCheckpoint
+				.mockImplementationOnce(() => {
+					order.push("stalled:start")
+					return new Promise((resolve) => {
+						resolveFirst = resolve
+					})
+				})
+				.mockImplementation(async () => {
+					order.push("fresh:start")
+					return { commit: "fresh-commit" }
+				})
+			const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {})
+
+			const stalled = checkpointSave(mockTask, true, true)
+			// Requested while its window is still open, so the drop below is about the wait behind
+			// the stalled baseline rather than about an already-expired request.
+			const expired = checkpointSave(mockTask, false, true)
+			await new Promise((resolve) => setTimeout(resolve, 30))
+			resolveFirst({ commit: "stalled-commit" })
+			const expiredResult = await expired
+			const settled = await stalled
+			const fresh = await checkpointSave(mockTask, false, true)
+
+			expect(order).toEqual(["stalled:start", "fresh:start"])
+			expect(mockCheckpointService.saveCheckpoint).toHaveBeenCalledTimes(2)
+			// The dropped request resolves exactly the way a missing service does: no commit value,
+			// while the predecessor that held the queue keeps its own result.
+			expect(expiredResult).toBeUndefined()
+			expect(settled).toEqual({ commit: "stalled-commit" })
+			expect(fresh).toEqual({ commit: "fresh-commit" })
+			warnSpy.mockRestore()
+		})
+
+		it("never drops a user-initiated restore queued behind a stalled save", async () => {
+			// Restores carry no expiry: dropping one would silently discard an explicit user action.
+			mockTask.checkpointTimeout = 0.01
+			mockTask.clineMessages = [{ ts: 2, type: "say", say: "checkpoint_saved", text: RESTORE_HASH }]
+			const order: string[] = []
+			let resolveSave: (value: { commit: string }) => void = () => {}
+			mockCheckpointService.saveCheckpoint.mockImplementationOnce(() => {
+				order.push("save:start")
+				return new Promise((resolve) => {
+					resolveSave = resolve
+				})
+			})
+			mockCheckpointService.restoreCheckpoint.mockImplementationOnce(() => {
+				order.push("restore:start")
+				return Promise.resolve(undefined)
+			})
+
+			const stalled = checkpointSave(mockTask, true, true)
+			const restore = checkpointRestore(mockTask, { ts: 2, commitHash: RESTORE_HASH, mode: "preview" })
+			await new Promise((resolve) => setTimeout(resolve, 30))
+			resolveSave({ commit: "stalled-commit" })
+			await Promise.all([stalled, restore])
+
+			expect(order).toEqual(["save:start", "restore:start"])
+			expect(mockCheckpointService.restoreCheckpoint).toHaveBeenCalledWith(RESTORE_HASH)
+		})
+
 		it("should wait for checkpoint service initialization before saving", async () => {
 			// Set up task with uninitialized service
 			mockCheckpointService.isInitialized = false
@@ -129,9 +302,11 @@ describe("Checkpoint functionality", () => {
 			const result = await savePromise
 
 			// saveCheckpoint should have been called
+			// The baseline carries a content premise now: it describes the workspace before any agent
+			// write, and saveCheckpoint declines to publish if a write landed before it staged.
 			expect(mockCheckpointService.saveCheckpoint).toHaveBeenCalledWith(
 				expect.stringContaining("Task: test-task-id"),
-				{ allowEmpty: true, suppressMessage: false },
+				{ allowEmpty: true, suppressMessage: false, contentPremise: expect.any(Function) },
 			)
 
 			// Result should contain the commit hash
@@ -280,6 +455,37 @@ describe("Checkpoint functionality", () => {
 			expect(mockCheckpointService.restoreCheckpoint).not.toHaveBeenCalled()
 		})
 
+		it("serializes a restore against a queued save so no save stages over a restore", async () => {
+			const order: string[] = []
+			let resolveRestore: () => void = () => {}
+			mockCheckpointService.restoreCheckpoint.mockImplementationOnce(
+				() =>
+					new Promise((resolve) => {
+						order.push("restore:start")
+						resolveRestore = resolve as () => void
+					}),
+			)
+			mockCheckpointService.saveCheckpoint.mockImplementationOnce(async () => {
+				order.push("save:start")
+				return { commit: "queued-commit" }
+			})
+
+			const restore = checkpointRestore(mockTask, { ts: 2, commitHash: RESTORE_HASH, mode: "preview" })
+			// Let the restore reach the shadow-git reset.
+			await new Promise((resolve) => setTimeout(resolve, 10))
+
+			const save = checkpointSave(mockTask, false, true)
+			// The save must not reach stageAll + commit while the restore is resetting the
+			// workspace: that commit would record the restored bytes and drop the write's own
+			// checkpoint.
+			await new Promise((resolve) => setTimeout(resolve, 10))
+			expect(order).toEqual(["restore:start"])
+
+			resolveRestore()
+			await Promise.all([restore, save])
+			expect(order).toEqual(["restore:start", "save:start"])
+		})
+
 		it.each(["delete", "edit"] as const)(
 			"propagates restore failures for %s without rewinding",
 			async (operation) => {