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

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

@@ -113,6 +113,34 @@ 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("should wait for checkpoint service initialization before saving", async () => {
 			// Set up task with uninitialized service
 			mockCheckpointService.isInitialized = false

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)
+	})
+})

src/core/checkpoints/index.ts

@@ -113,6 +113,15 @@
 		const service = RepoPerTaskCheckpointService.create(options)
 		task.checkpointServiceInitializing = true
 		await checkGitInstallation(task, service, log, provider)
+		if (!service.isInitialized) {
+			// checkGitInstallation disables checkpoints when Git is unavailable and
+			// logs initShadowGit failures without throwing: storing such a service
+			// would hand later saves (and the fast path above) an uninitialized
+			// handle whose isInitialized can never flip, so a failed
+			// initialization must resolve to no service at all.
+			task.checkpointServiceInitializing = false
+			return undefined
+		}
 		task.checkpointService = service
 		if (task.enableCheckpoints) {
 			sendCheckpointInitWarn(task)
@@ -200,6 +209,10 @@
 		} catch (err) {
 			log(`[Task#getCheckpointService] initShadowGit -> ${err.message}`)
 			task.enableCheckpoints = false
+			// The "initialize" event never fires for a failed initShadowGit, so
+			// clear the flag here or later lookups wait on an initialization
+			// that already died.
+			task.checkpointServiceInitializing = false
 		}
 	} catch (err) {
 		log(`[Task#getCheckpointService] Unexpected error during Git check: ${err.message}`)
@@ -209,6 +222,29 @@
 	}
 }
 
+// Serialize checkpoint saves per task. saveCheckpoint() runs stageAll + commit, so two
+// concurrent saves for the same task (for example the task-start baseline racing the first
+// per-write save after the baseline timeout) can stage each other's writes or interleave
+// commits. A per-task promise queue makes every save wait for the previous one, including
+// a baseline that is still running.
+const checkpointSaveQueues = new Map<string, Promise<unknown>>()
+
+function enqueueCheckpointSave<T>(taskId: string, operation: () => Promise<T>): Promise<T> {
+	const previous = checkpointSaveQueues.get(taskId) ?? Promise.resolve()
+	const next = previous.then(operation, operation)
+	const tail = next.then(
+		() => undefined,
+		() => undefined,
+	)
+	checkpointSaveQueues.set(taskId, tail)
+	void tail.finally(() => {
+		if (checkpointSaveQueues.get(taskId) === tail) {
+			checkpointSaveQueues.delete(taskId)
+		}
+	})
+	return next
+}
+
 export async function checkpointSave(task: Task, force = false, suppressMessage = false) {
 	const service = await getCheckpointService(task)
 
@@ -218,13 +254,14 @@
 
 	TelemetryService.instance.captureCheckpointCreated(task.taskId)
 
-	// Start the checkpoint process in the background.
-	return service
-		.saveCheckpoint(`Task: ${task.taskId}, Time: ${Date.now()}`, { allowEmpty: force, suppressMessage })
-		.catch((err) => {
-			console.error("[Task#checkpointSave] caught unexpected error, disabling checkpoints", err)
-			task.enableCheckpoints = false
-		})
+	// Start the checkpoint process in the background, queued behind any save already
+	// running for this task so stageAll + commit never overlap.
+	return enqueueCheckpointSave(task.taskId, () =>
+		service.saveCheckpoint(`Task: ${task.taskId}, Time: ${Date.now()}`, { allowEmpty: force, suppressMessage }),
+	).catch((err) => {
+		console.error("[Task#checkpointSave] caught unexpected error, disabling checkpoints", err)
+		task.enableCheckpoints = false
+	})
 }
 
 export type CheckpointRestoreOptions = {