@@ -0,0 +1,198 @@
+import fs from "fs/promises"
+import os from "os"
+import path from "path"
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import type { Task } from "../../task/Task"
+import { getCheckpointService } from "../index"
+import { appendChange } from "../changeJournal"
+import { rollbackFile, rollbackStep } from "../rollback"
+
+vi.mock("../index", () => ({
+	getCheckpointService: vi.fn(),
+	checkpointSave: vi.fn(),
+	checkpointRestore: vi.fn(),
+	checkpointDiff: vi.fn(),
+}))
+
+const mockedGetCheckpointService = getCheckpointService as unknown as ReturnType<typeof vi.fn>
+
+function makeTask(): Task {
+	return {
+		taskId: "task-rollback",
+		providerRef: {
+			deref: vi.fn().mockReturnValue({ context: { globalStorageUri: { fsPath: globalStorageDir } } }),
+		},
+	} as unknown as Task
+}
+
+let globalStorageDir: string
+
+beforeEach(async () => {
+	globalStorageDir = await fs.mkdtemp(path.join(os.tmpdir(), "b3a-rollback-"))
+	mockedGetCheckpointService.mockReset()
+})
+
+afterEach(async () => {
+	await fs.rm(globalStorageDir, { recursive: true, force: true })
+})
+
+describe("rollbackFile (B3a)", () => {
+	it("restores the file through the task's checkpoint service", async () => {
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
+
+		expect(outcome).toEqual({ filePath: "src/a.ts", success: true })
+		expect(restoreFile).toHaveBeenCalledWith("sha-1", "src/a.ts")
+	})
+
+	it("fails cleanly when checkpoints are not enabled", async () => {
+		mockedGetCheckpointService.mockResolvedValue(undefined)
+
+		const outcome = await rollbackFile(makeTask(), "sha-1", "src/a.ts")
+
+		expect(outcome).toEqual({
+			filePath: "src/a.ts",
+			success: false,
+			error: "Checkpoints are not enabled for this task",
+		})
+	})
+
+	it("reports the service error without throwing", async () => {
+		mockedGetCheckpointService.mockResolvedValue({
+			restoreFile: vi.fn().mockRejectedValue(new Error("pathspec did not match")),
+		})
+
+		const outcome = await rollbackFile(makeTask(), "sha-bad", "src/a.ts")
+
+		expect(outcome.success).toBe(false)
+		expect(outcome.error).toContain("pathspec did not match")
+	})
+
+	it("stringifies non-Error rejections into the outcome", async () => {
+		mockedGetCheckpointService.mockResolvedValue({
+			restoreFile: vi.fn().mockRejectedValue("raw failure"),
+		})
+
+		const outcome = await rollbackFile(makeTask(), "sha-bad", "src/a.ts")
+
+		expect(outcome).toEqual({ filePath: "src/a.ts", success: false, error: "raw failure" })
+	})
+})
+
+describe("rollbackStep (B3a)", () => {
+	it("restores every step file from the step's checkpoint via the journal", async () => {
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/a.ts",
+			operation: "create",
+			checkpointId: "sha-step",
+		})
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/b.ts",
+			operation: "update",
+			checkpointId: "sha-step",
+		})
+
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/b.ts"], "sha-step")
+
+		expect(outcome.checkpointId).toBe("sha-step")
+		expect(outcome.files).toEqual([
+			{ filePath: "src/a.ts", success: true },
+			{ filePath: "src/b.ts", success: true },
+		])
+		expect(restoreFile).toHaveBeenCalledTimes(2)
+		expect(restoreFile).toHaveBeenNthCalledWith(1, "sha-step", "src/a.ts")
+		expect(restoreFile).toHaveBeenNthCalledWith(2, "sha-step", "src/b.ts")
+	})
+
+	it("rejects a file that is not part of the given step checkpoint", async () => {
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/a.ts",
+			operation: "create",
+			checkpointId: "sha-step",
+		})
+
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/other.ts"], "sha-step")
+
+		expect(outcome.files[0]).toEqual({ filePath: "src/a.ts", success: true })
+		expect(outcome.files[1].success).toBe(false)
+		expect(outcome.files[1].error).toBe("File is not part of this step's checkpoint")
+		expect(restoreFile).toHaveBeenCalledTimes(1)
+	})
+
+	it("falls back to the latest journal entry per file without a step checkpoint id", async () => {
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/a.ts",
+			operation: "create",
+			checkpointId: "sha-1",
+		})
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/a.ts",
+			operation: "update",
+			checkpointId: "sha-2",
+		})
+
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackStep(makeTask(), ["src/a.ts"])
+
+		expect(outcome.checkpointId).toBe("sha-2")
+		expect(restoreFile).toHaveBeenCalledWith("sha-2", "src/a.ts")
+	})
+
+	it("fails listed files without journal entries and keeps the checkpoint when resolvable", async () => {
+		await appendChange(globalStorageDir, "task-rollback", {
+			path: "src/a.ts",
+			operation: "create",
+			checkpointId: "sha-1",
+		})
+
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackStep(makeTask(), ["src/a.ts", "src/missing.ts"])
+
+		expect(outcome.checkpointId).toBe("sha-1")
+		expect(outcome.files[0]).toEqual({ filePath: "src/a.ts", success: true })
+		expect(outcome.files[1].success).toBe(false)
+		expect(outcome.files[1].error).toBe("No change journal entry for this file")
+	})
+
+	it("treats a missing global storage directory as an empty journal", async () => {
+		// No context on the provider double → no journal location to read.
+		const task = {
+			taskId: "task-rollback",
+			providerRef: { deref: vi.fn().mockReturnValue(undefined) },
+		} as unknown as Task
+
+		const restoreFile = vi.fn().mockResolvedValue(undefined)
+		mockedGetCheckpointService.mockResolvedValue({ restoreFile })
+
+		const outcome = await rollbackStep(task, ["src/a.ts"], "sha-step")
+
+		expect(outcome.checkpointId).toBe("sha-step")
+		expect(outcome.files[0].success).toBe(false)
+		expect(outcome.files[0].error).toBe("File is not part of this step's checkpoint")
+		expect(restoreFile).not.toHaveBeenCalled()
+	})
+	it("fails every file when checkpoints are not enabled", async () => {
+		mockedGetCheckpointService.mockResolvedValue(undefined)
+
+		const outcome = await rollbackStep(makeTask(), ["src/a.ts"], "sha-step")
+
+		expect(outcome.checkpointId).toBe("sha-step")
+		expect(outcome.files).toEqual([
+			{ filePath: "src/a.ts", success: false, error: "Checkpoints are not enabled for this task" },
+		])
+	})
+})
@@ -0,0 +1,119 @@
+/**
+ * Per-file / per-step checkpoint rollback (B3a).
+ *
+ * Restores reuse the existing shadow-git service (`getCheckpointService` →
+ * `RepoPerTaskCheckpointService.restoreFile`, the same instance whose
+ * `restoreCheckpoint` the checkpoints UI uses) — nothing is forked.
+ *
+ * - `rollbackFile` restores one file to the content it had at an explicit
+ *   checkpoint commit (the "restore to any checkpoint" primitive).
+ * - `rollbackStep` restores every file a step touched to that step's
+ *   checkpoint. The step's checkpoint is resolved from the B2 change
+ *   journal (`changes.jsonl`), whose entries key each written file by the
+ *   checkpoint commit it produced. When the caller already knows the step's
+ *   checkpoint id (the change-card payload carries it), pass it so the
+ *   journal is filtered to exactly that step's writes.
+ */
+import type { Task } from "../task/Task"
+
+import { getCheckpointService } from "./index"
+import { loadChanges, type ChangeJournalEntry } from "./changeJournal"
+
+export interface RollbackFileOutcome {
+	filePath: string
+	success: boolean
+	error?: string
+}
+
+export interface RollbackStepOutcome {
+	/** The step checkpoint the files were restored from, when resolvable. */
+	checkpointId?: string
+	files: RollbackFileOutcome[]
+}
+
+const NOT_ENABLED_ERROR = "Checkpoints are not enabled for this task"
+
+/**
+ * Restore a single file to its state at `checkpointId`.
+ *
+ * Only the named file's working-tree content is replaced; the shadow repo's
+ * HEAD and the checkpoint list are untouched (unlike a full
+ * `restoreCheckpoint`).
+ */
+export async function rollbackFile(task: Task, checkpointId: string, filePath: string): Promise<RollbackFileOutcome> {
+	const service = await getCheckpointService(task)
+
+	if (!service) {
+		return { filePath, success: false, error: NOT_ENABLED_ERROR }
+	}
+
+	try {
+		await service.restoreFile(checkpointId, filePath)
+		return { filePath, success: true }
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+		console.error(`[rollbackFile] failed to restore ${filePath} from checkpoint ${checkpointId}: ${message}`)
+		return { filePath, success: false, error: message }
+	}
+}
+
+/**
+ * Restore every file of a step to the step's checkpoint.
+ *
+ * `stepFiles` comes from the B2 journal entries for the step's checkpoint id
+ * (which the change-card payload also carries). Each file is resolved to its
+ * step checkpoint through the journal:
+ * - with `stepCheckpointId`, only entries for that checkpoint are considered
+ *   (exactly the step's writes), and every listed file is restored from it;
+ * - without it, the latest journal entry per file is used as a fallback.
+ */
+export async function rollbackStep(
+	task: Task,
+	stepFiles: string[],
+	stepCheckpointId?: string,
+): Promise<RollbackStepOutcome> {
+	const service = await getCheckpointService(task)
+
+	if (!service) {
+		return {
+			checkpointId: stepCheckpointId,
+			files: stepFiles.map((filePath) => ({ filePath, success: false, error: NOT_ENABLED_ERROR })),
+		}
+	}
+
+	// loadChanges never throws: an absent or torn journal resolves to its
+	// readable prefix (or []), so no error handling is needed here.
+	const globalStorageDir = task.providerRef.deref()?.context.globalStorageUri.fsPath
+	const entries = globalStorageDir ? await loadChanges(globalStorageDir, task.taskId) : []
+
+	// Latest journal entry per file (journal lines preserve write order).
+	const latestByPath = new Map<string, ChangeJournalEntry>()
+	for (const entry of entries) {
+		latestByPath.set(entry.path, entry)
+	}
+
+	const checkpointId =
+		stepCheckpointId ?? stepFiles.map((filePath) => latestByPath.get(filePath)?.checkpointId).find(Boolean)
+
+	const files: RollbackFileOutcome[] = []
+	for (const filePath of stepFiles) {
+		const entry = stepCheckpointId
+			? entries.find((e) => e.path === filePath && e.checkpointId === stepCheckpointId)
+			: latestByPath.get(filePath)
+
+		if (!entry) {
+			files.push({
+				filePath,
+				success: false,
+				error: stepCheckpointId
+					? "File is not part of this step's checkpoint"
+					: "No change journal entry for this file",
+			})
+			continue
+		}
+
+		files.push(await rollbackFile(task, entry.checkpointId, filePath))
+	}
+
+	return { checkpointId, files }
+}
@@ -407,6 +407,73 @@ export abstract class ShadowCheckpointService extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Restore a single file to its state at `commitHash` without moving the
+	 * branch or truncating the checkpoint list (unlike
+	 * {@link restoreCheckpoint}).
+	 *
+	 * If the file did not exist at `commitHash`, it is removed from the
+	 * working tree instead — rolling a file back to before it was created.
+	 */
+	public async restoreFile(commitHash: string, filePath: string): Promise<void> {
+		try {
+			this.log(`[${this.constructor.name}#restoreFile] restoring ${filePath} from ${commitHash}`)
+
+			if (!this.git) {
+				throw new Error("Shadow git repo not initialized")
+			}
+
+			// Git pathspecs are always POSIX: normalize a native (Windows
+			// backslash) path before the git calls. Without this, `cat-file -e` on
+			// a backslashed path never matches, the file is treated as absent at
+			// the checkpoint, and the delete branch below would remove a file the
+			// checkpoint actually contains. The local fs.rm join keeps the native
+			// form, since the OS treats both separators interchangeably there.
+			const gitPath = filePath.toPosix()
+
+			// Constrain the path to the workspace before either branch: `..`
+			// segments would otherwise normalize (path.join / git pathspec) to a
+			// location outside `this.workspaceDir`, and the delete branch could
+			// remove an unrelated file. `path.resolve` normalizes the segments;
+			// the trailing-separator prefix check is the containment guard.
+			const resolvedTarget = path.resolve(this.workspaceDir, filePath)
+			const workspaceRoot = this.workspaceDir.endsWith(path.sep)
+				? this.workspaceDir
+				: this.workspaceDir + path.sep
+			if (resolvedTarget !== this.workspaceDir && !resolvedTarget.startsWith(workspaceRoot)) {
+				throw new Error(`restoreFile target is outside the workspace: ${filePath}`)
+			}
+
+			const start = Date.now()
+			const existed = await this.fileExistsInCommit(commitHash, gitPath)
+
+			if (existed) {
+				await this.git.checkout([commitHash, "--", gitPath])
+			} else {
+				await fs.rm(path.join(this.workspaceDir, filePath), { force: true })
+			}
+
+			const duration = Date.now() - start
+			this.emit("restore", { type: "restore", commitHash, duration })
+			this.log(`[${this.constructor.name}#restoreFile] restored ${filePath} in ${duration}ms`)
+		} catch (e) {
+			const error = e instanceof Error ? e : new Error(String(e))
+			this.log(`[${this.constructor.name}#restoreFile] failed to restore file: ${error.message}`)
+			this.emit("error", { type: "error", error })
+			throw error
+		}
+	}
+
+	/** Whether `filePath` exists in the tree of `commitHash`. */
+	private async fileExistsInCommit(commitHash: string, filePath: string): Promise<boolean> {
+		try {
+			await this.git!.raw(["cat-file", "-e", `${commitHash}:${filePath}`])
+			return true
+		} catch {
+			return false
+		}
+	}
+
 	public async getDiff({ from, to }: { from?: string; to?: string }): Promise<CheckpointDiff[]> {
 		if (!this.git) {
 			throw new Error("Shadow git repo not initialized")