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
@@ -280,6 +453,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) => {

src/core/checkpoints/__tests__/getCheckpointService.spec.ts

@@ -0,0 +1,126 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+import type { Task } from "../../task/Task"
+import { RepoPerTaskCheckpointService } from "../../../services/checkpoints"
+import { checkGitInstalled } from "../../../utils/git"
+import { getCheckpointService } from "../index"
+
+vi.mock("../../../services/checkpoints", () => ({
+	RepoPerTaskCheckpointService: { create: vi.fn() },
+}))
+
+vi.mock("../../../utils/git", () => ({
+	checkGitInstalled: vi.fn(),
+}))
+
+vi.mock("../../../utils/path", () => ({
+	getWorkspacePath: vi.fn(() => "/workspace"),
+}))
+
+vi.mock("../../../i18n", () => ({
+	t: (key: string) => key,
+}))
+
+/**
+ * Structural service double: getCheckpointService only registers listeners,
+ * awaits initShadowGit, and reads isInitialized. The double assertion at the
+ * create() call sites is confined to this file (AGENTS.md last-resort cast):
+ * the real class carries a Git handle and event surface the test never
+ * exercises.
+ */
+function serviceDouble(initShadowGitImpl: () => Promise<void>) {
+	const listeners = new Map<string, (...args: unknown[]) => void>()
+	let initialized = false
+	const svc = {
+		on: vi.fn((event: string, cb: (...args: unknown[]) => void) => {
+			listeners.set(event, cb)
+		}),
+		initShadowGit: vi.fn(() => initShadowGitImpl()),
+		get isInitialized() {
+			return initialized
+		},
+		completeInit: () => {
+			initialized = true
+			listeners.get("initialize")?.()
+		},
+	}
+	return svc
+}
+
+function makeTask(): Task {
+	return {
+		taskId: "task-init",
+		cwd: "/workspace",
+		enableCheckpoints: true,
+		checkpointService: undefined,
+		checkpointServiceInitializing: false,
+		checkpointTimeout: 1,
+		providerRef: {
+			deref: vi.fn().mockReturnValue({
+				context: { globalStorageUri: { fsPath: "/tmp/b3-init-storage" } },
+				postMessageToWebview: vi.fn(),
+				log: vi.fn(),
+			}),
+		},
+		say: vi.fn().mockResolvedValue(undefined),
+	} as unknown as Task
+}
+
+describe("getCheckpointService initialization failures", () => {
+	beforeEach(() => {
+		vi.mocked(checkGitInstalled).mockReset()
+		vi.mocked(RepoPerTaskCheckpointService.create).mockReset()
+	})
+
+	it("does not store a service whose shadow-git initialization failed", async () => {
+		vi.mocked(checkGitInstalled).mockResolvedValue(true)
+		const failing = serviceDouble(async () => {
+			throw new Error("shadow git init exploded")
+		})
+		vi.mocked(RepoPerTaskCheckpointService.create).mockReturnValue(
+			failing as unknown as RepoPerTaskCheckpointService,
+		)
+
+		const task = makeTask()
+		const service = await getCheckpointService(task)
+
+		// The failed service must not be stored: a stored uninitialized handle
+		// would be returned by the fast path to every later save, and the
+		// initializing flag must not strand later lookups in a wait for an
+		// initialization that already died.
+		expect(service).toBeUndefined()
+		expect(task.checkpointService).toBeUndefined()
+		expect(task.checkpointServiceInitializing).toBe(false)
+		expect(task.enableCheckpoints).toBe(false)
+	})
+
+	it("does not store a service when Git is not installed", async () => {
+		vi.mocked(checkGitInstalled).mockResolvedValue(false)
+		const svc = serviceDouble(async () => {})
+		vi.mocked(RepoPerTaskCheckpointService.create).mockReturnValue(svc as unknown as RepoPerTaskCheckpointService)
+
+		const task = makeTask()
+		const service = await getCheckpointService(task)
+
+		expect(service).toBeUndefined()
+		expect(task.checkpointService).toBeUndefined()
+		expect(task.checkpointServiceInitializing).toBe(false)
+		expect(task.enableCheckpoints).toBe(false)
+	})
+
+	it("stores an initialized service on the success path", async () => {
+		vi.mocked(checkGitInstalled).mockResolvedValue(true)
+		const svc = serviceDouble(async () => {
+			svc.completeInit()
+		})
+		vi.mocked(RepoPerTaskCheckpointService.create).mockReturnValue(svc as unknown as RepoPerTaskCheckpointService)
+
+		const task = makeTask()
+		const service = await getCheckpointService(task)
+
+		expect(service).toBe(svc)
+		expect(task.checkpointService).toBe(svc)
+		expect(task.checkpointServiceInitializing).toBe(false)
+		expect(task.enableCheckpoints).toBe(true)
+	})
+})