@markjaquith/agency 2.58.1 → 2.59.0

package/README.md

@@ -925,6 +925,15 @@ conflicting worktrees. Repair is deliberately conservative: it repairs safe Git
 registration issues and materializes missing checkouts, but never switches a
 branch, resets a commit, or discards uncommitted work.
 
+For jj, explicit removal is a suspend operation. Agency records each workspace's
+exact `@` commit and stable change ID in `.agency-jj-resume.json`, roots that
+commit with an internal local bookmark, and only then forgets the workspace.
+The next `work prepare` validates all three identities, restores the workspace by
+editing the recorded commit, and consumes the resume metadata and bookmarks.
+Missing, ambiguous, or conflicting resume state stops instead of falling back to
+the declared delivery bookmark, `@-`, or the base. Unknown checkout cleanliness
+also stops removal. Git worktree removal and preparation are unchanged.
+
 Agency launches every agent beside its epic or task document. Single-phase tasks
 and phases first fetch repositories and create or reuse worktrees under `code/`,
 then launch the execution agent from the task directory with absolute context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.58.1",
+  "version": "2.59.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/services/ArchiveService.ts

@@ -413,6 +413,7 @@ const restoreWorktreeSnapshots = async (
 				snapshot.head,
 				snapshot.path,
 			])
+			await runGit(["jj", "-R", snapshot.path, "edit", snapshot.head])
 			continue
 		}
 		await runGit(
@@ -723,6 +724,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 						removedWorktrees.push(
 							...(yield* worktrees.remove(unit.taskId, unit.phaseId, root, {
 								dryRun: true,
+								persistResume: false,
 							})),
 						)
 					}
@@ -781,6 +783,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 												worktrees.remove(unit.taskId, unit.phaseId, root, {
 													snapshots,
 													lockHeld: true,
+													persistResume: false,
 												}),
 											)
 									} catch (cause) {
@@ -891,6 +894,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 							const result = yield* worktrees
 								.remove(unit.taskId, executionPhaseId(unit), root, {
 									dryRun: true,
+									persistResume: false,
 								})
 								.pipe(Effect.either)
 							if (Either.isLeft(result)) {
@@ -1064,6 +1068,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 												worktrees.remove(unit.taskId, unit.phaseId, root, {
 													snapshots,
 													lockHeld: true,
+													persistResume: false,
 												}),
 											)
 										}
@@ -1212,6 +1217,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 								root,
 								{
 									dryRun: true,
+									persistResume: false,
 								},
 							)),
 						)
@@ -1267,6 +1273,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 													{
 														snapshots,
 														lockHeld: true,
+														persistResume: false,
 													},
 												),
 											)
@@ -1359,6 +1366,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 					yield* rejectExistingDestination(destination, "Archive")
 					const removedWorktrees = yield* worktrees.remove(taskId, id, root, {
 						dryRun: true,
+						persistResume: false,
 					})
 					const at = new Date().toISOString()
 					const content = yield* declarationContent(task, {
@@ -1407,6 +1415,7 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 													worktrees.remove(taskId, id, root, {
 														snapshots,
 														lockHeld: true,
+														persistResume: false,
 													}),
 												)
 											},

package/src/services/ReviewService.ts

@@ -101,6 +101,7 @@ const restoreSnapshots = async (
 				snapshot.head,
 				snapshot.path,
 			])
+			await runGit(["jj", "-R", snapshot.path, "edit", snapshot.head])
 			continue
 		}
 		await runGit(
@@ -392,6 +393,7 @@ export class ReviewService extends Effect.Service<ReviewService>()(
 											worktrees.remove(taskId, undefined, root, {
 												snapshots,
 												lockHeld: true,
+												persistResume: false,
 											}),
 										).then(() => undefined),
 									rollback: () => restoreSnapshots(snapshots),

package/src/services/WorktreeService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, realpath, rename, rm, stat } from "node:fs/promises"
+import { chmod, mkdir, realpath, rename, rm, stat } from "node:fs/promises"
 import { join } from "node:path"
 import {
 	captureErrors,
@@ -34,6 +34,21 @@ const jj = async (args: string[], cwd?: string) => {
 		throw new Error(await new Response(process.stderr).text())
 }
 
+const jjOutput = async (args: string[], cwd?: string) => {
+	const process = Bun.spawn(["jj", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	const [exitCode, stdout, stderr] = await Promise.all([
+		process.exited,
+		new Response(process.stdout).text(),
+		new Response(process.stderr).text(),
+	])
+	if (exitCode !== 0) throw new Error(stderr)
+	return stdout.trim()
+}
+
 describe("WorktreeService", () => {
 	let root: string
 	let source: string
@@ -304,6 +319,269 @@ describe("WorktreeService", () => {
 		expect(await Bun.file(workspace.writablePath!).exists()).toBe(false)
 	})
 
+	test("suspends and resumes the exact jj working-copy target", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-resume",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-resume",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-resume", undefined, root),
+				),
+			),
+		)
+		await jj(["new", "-m", "local-only parent"], workspace.writablePath!)
+		await Bun.write(join(workspace.writablePath!, "local.txt"), "preserve me\n")
+		await jj(
+			["describe", "-m", "local working target"],
+			workspace.writablePath!,
+		)
+		const target = await jjOutput(
+			["log", "--no-graph", "-r", "@", "-T", 'commit_id ++ "\\t" ++ change_id'],
+			workspace.writablePath!,
+		)
+		const [commitId, changeId] = target.split("\t")
+		if (!commitId || !changeId)
+			throw new Error(`Unexpected jj identity: ${target}`)
+		await jj(["new", "-m", "temporary successor"], workspace.writablePath!)
+		await jj(["edit", commitId], workspace.writablePath!)
+
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.remove("jj-resume", undefined, root),
+				),
+			),
+		)
+		const resumePath = join(root, "tasks/jj-resume/.agency-jj-resume.json")
+		const resume = await Bun.file(resumePath).json()
+		expect(resume.checkouts[0]).toMatchObject({ commitId, changeId })
+		expect(
+			await jjOutput(
+				[
+					"log",
+					"--no-graph",
+					"-r",
+					resume.checkouts[0].bookmark,
+					"-T",
+					"commit_id",
+				],
+				repository,
+			),
+		).toBe(commitId)
+		expect(
+			await jjOutput(
+				["log", "--no-graph", "-r", "task/jj-resume", "-T", "commit_id"],
+				repository,
+			).catch(() => null),
+		).toBeNull()
+
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-resume", undefined, root),
+				),
+			),
+		)
+		expect(
+			await jjOutput(
+				["log", "--no-graph", "-r", "@", "-T", "commit_id"],
+				workspace.writablePath!,
+			),
+		).toBe(commitId)
+		expect(
+			await Bun.file(join(workspace.writablePath!, "local.txt")).text(),
+		).toBe("preserve me\n")
+		expect(await Bun.file(resumePath).exists()).toBe(false)
+		expect(
+			await jjOutput(
+				[
+					"log",
+					"--no-graph",
+					"-r",
+					resume.checkouts[0].bookmark,
+					"-T",
+					"commit_id",
+				],
+				repository,
+			).catch(() => null),
+		).toBeNull()
+	})
+
+	test("refuses stale jj resume identity and stale registrations", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		for (const id of ["stale-resume", "stale-registration"]) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id,
+								ticketUrl: null,
+								repo: "agency",
+								branch: `task/${id}`,
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			)
+		}
+		const suspended = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("stale-resume", undefined, root),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.remove("stale-resume", undefined, root),
+				),
+			),
+		)
+		const resumePath = join(root, "tasks/stale-resume/.agency-jj-resume.json")
+		const resume = await Bun.file(resumePath).json()
+		await jj([
+			"-R",
+			repository,
+			"bookmark",
+			"delete",
+			resume.checkouts[0].bookmark,
+		])
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("stale-resume", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("recorded commit, change ID, path, or internal bookmark")
+		expect(await Bun.file(resumePath).exists()).toBe(true)
+		expect(await Bun.file(suspended.writablePath!).exists()).toBe(false)
+
+		const stale = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("stale-registration", undefined, root),
+				),
+			),
+		)
+		await rm(join(stale.writablePath!, ".jj"), { recursive: true, force: true })
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.remove("stale-registration", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("checkout cleanliness could not be verified")
+	})
+
+	test("retains jj resume state when workspace deletion and rollback fail", async () => {
+		if (!Bun.which("jj")) return
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await git(["clone", source, repository])
+		await jj(["git", "init", "--colocate", repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "jj-rollback",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/jj-rollback",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-rollback", undefined, root),
+				),
+			),
+		)
+		const fakeBin = join(root, "fake-bin")
+		await mkdir(fakeBin)
+		const fakeRm = join(fakeBin, "rm")
+		await Bun.write(
+			fakeRm,
+			`#!/bin/sh\nif [ "$1" = "-rf" ] && [ "$2" = ${JSON.stringify(workspace.writablePath!)} ]; then exit 1; fi\nexec ${JSON.stringify(Bun.which("rm")!)} "$@"\n`,
+		)
+		await chmod(fakeRm, 0o755)
+		const originalPath = process.env.PATH
+		process.env.PATH = `${fakeBin}:${originalPath}`
+		try {
+			await expect(
+				runTestEffect(
+					WorktreeService.pipe(
+						Effect.flatMap((service) =>
+							service.remove("jj-rollback", undefined, root),
+						),
+					),
+				),
+			).rejects.toThrow("requires manual recovery")
+		} finally {
+			process.env.PATH = originalPath
+		}
+		const resumePath = join(root, "tasks/jj-rollback/.agency-jj-resume.json")
+		expect(await Bun.file(resumePath).exists()).toBe(true)
+
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("jj-rollback", undefined, root),
+				),
+			),
+		)
+		expect((await stat(workspace.writablePath!)).isDirectory()).toBe(true)
+		expect(await Bun.file(resumePath).exists()).toBe(false)
+	})
+
 	test("recommends a repository fetch when jj cannot resolve a base", async () => {
 		if (!Bun.which("jj")) return
 		const repository = join(root, "repos/agency")
@@ -1882,6 +2160,111 @@ pr: null
 		).toBe(true)
 	})
 
+	test("rebuilds clean drifted jj references without discarding changes", async () => {
+		if (!Bun.which("jj")) return
+		const first = new TextDecoder()
+			.decode(
+				Bun.spawnSync(["git", "-C", source, "rev-parse", "HEAD"], {
+					stdout: "pipe",
+				}).stdout,
+			)
+			.trim()
+		await Bun.write(join(source, "README.md"), "updated\n")
+		await git(["add", "README.md"], source)
+		await git(["-c", "commit.gpgsign=false", "commit", "-m", "update"], source)
+		const second = new TextDecoder()
+			.decode(
+				Bun.spawnSync(["git", "-C", source, "rev-parse", "HEAD"], {
+					stdout: "pipe",
+				}).stdout,
+			)
+			.trim()
+		const repository = join(root, "repos/agency")
+		await rm(repository, { recursive: true, force: true })
+		await jj(["git", "clone", "--no-colocate", source, repository])
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({ version: 2, vcs: "jj" }),
+		)
+		const createDriftedReview = async (id: string) => {
+			const task = await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id,
+								ticketUrl: null,
+								review: {
+									repo: "agency",
+									source: {
+										kind: "branch",
+										ref: "refs/heads/main",
+									},
+									commit: first,
+									refreshedAt: "2026-08-10T00:00:00.000Z",
+								},
+							},
+							root,
+						),
+					),
+				),
+			)
+			const workspace = await runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) => service.materialize(id, undefined, root)),
+				),
+			)
+			await Bun.write(task.path, task.content.replace(first, second))
+			return workspace
+		}
+
+		const workspace = await createDriftedReview("drifted-review")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.materialize("drifted-review", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("does not match reference")
+		const inspection = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("drifted-review", undefined, root),
+				),
+			),
+		)
+		expect(inspection.conflicts).toEqual([
+			expect.objectContaining({ kind: "reference-drift" }),
+		])
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.rebuild("drifted-review", undefined, root),
+				),
+			),
+		)
+		expect(
+			await Bun.file(join(workspace.reviewPath!, "README.md")).text(),
+		).toBe("updated\n")
+
+		const dirtyWorkspace = await createDriftedReview("dirty-drifted-review")
+		const dirtyPath = join(dirtyWorkspace.reviewPath!, "dirty.txt")
+		await Bun.write(dirtyPath, "preserve me\n")
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.rebuild("dirty-drifted-review", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("checkout has uncommitted changes")
+		expect(await Bun.file(dirtyPath).text()).toBe("preserve me\n")
+	})
+
 	test("restores removed worktrees when rebuild creation fails", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/WorktreeService.ts

@@ -40,6 +40,7 @@ interface WorkspaceOperation {
 		| "create-branch"
 		| "create-worktree"
 		| "create-workspace"
+		| "restore-workspace"
 		| "post-checkout"
 	readonly repo: string
 	readonly command: readonly string[]
@@ -154,6 +155,22 @@ export interface WorktreeRemovalSnapshot {
 	readonly workspaceName?: string
 }
 
+interface JjResumeCheckout {
+	readonly repo: string
+	readonly workspacePath: string
+	readonly workspaceName: string
+	readonly commitId: string
+	readonly changeId: string
+	readonly bookmark: string
+}
+
+interface JjResumeState {
+	readonly version: 1
+	readonly taskId: string
+	readonly phaseId: string | null
+	readonly checkouts: readonly JjResumeCheckout[]
+}
+
 const parseWorktreeList = (output: string): readonly GitWorktree[] => {
 	const worktrees: GitWorktree[] = []
 	let current: { path: string; head?: string; branch?: string } | undefined
@@ -254,11 +271,14 @@ const originRef = (ref: string) =>
 interface MaterializeOptions extends BaseCommandOptions {
 	readonly force?: boolean
 	readonly lockHeld?: boolean
+	readonly allowReferenceDrift?: boolean
 }
 
 interface RemoveOptions extends BaseCommandOptions {
 	readonly snapshots?: WorktreeRemovalSnapshot[]
 	readonly lockHeld?: boolean
+	readonly allowReferenceDrift?: boolean
+	readonly persistResume?: boolean
 }
 
 interface LifecycleOptions extends BaseCommandOptions {
@@ -770,6 +790,177 @@ const jjWorkspaceName = (
 	repo: string,
 ) => `agency-${taskId}-${phaseId ?? "task"}-${repo}`
 
+const jjResumePath = (taskPath: string, phasePath: string | null) =>
+	join(dirname(phasePath ?? taskPath), ".agency-jj-resume.json")
+
+const jjResumeBookmark = (
+	taskId: string,
+	phaseId: string | undefined,
+	repo: string,
+) =>
+	`agency-resume/${Buffer.from(`${taskId}:${phaseId ?? "task"}:${repo}:${crypto.randomUUID()}`).toString("hex")}`
+
+const parseJjResumeState = (content: string, path: string): JjResumeState => {
+	let value: unknown
+	try {
+		value = JSON.parse(content)
+	} catch {
+		throw new WorktreeError({
+			message: `Invalid jj resume metadata at ${path}`,
+		})
+	}
+	if (
+		typeof value !== "object" ||
+		value === null ||
+		!("version" in value) ||
+		value.version !== 1 ||
+		!("taskId" in value) ||
+		typeof value.taskId !== "string" ||
+		!("phaseId" in value) ||
+		(value.phaseId !== null && typeof value.phaseId !== "string") ||
+		!("checkouts" in value) ||
+		!Array.isArray(value.checkouts) ||
+		value.checkouts.some(
+			(checkout) =>
+				typeof checkout !== "object" ||
+				checkout === null ||
+				![
+					"repo",
+					"workspacePath",
+					"workspaceName",
+					"commitId",
+					"changeId",
+					"bookmark",
+				].every((key) => key in checkout && typeof checkout[key] === "string"),
+		)
+	) {
+		throw new WorktreeError({
+			message: `Invalid jj resume metadata at ${path}`,
+		})
+	}
+	return value as JjResumeState
+}
+
+const readJjResumeState = (path: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		if (!(yield* fs.exists(path))) return null
+		return parseJjResumeState(yield* fs.readFile(path), path)
+	})
+
+const writeJjResumeState = (path: string, state: JjResumeState) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const temporary = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`
+		yield* Effect.gen(function* () {
+			yield* fs.writeJSON(temporary, state)
+			yield* fs.moveDirectory(temporary, path)
+		}).pipe(
+			Effect.catchAll((cause) =>
+				Effect.gen(function* () {
+					if (yield* fs.exists(temporary)) yield* fs.deleteFile(temporary)
+					return yield* Effect.fail(cause)
+				}),
+			),
+		)
+	})
+
+const jjIdentity = (repositoryPath: string, revision: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand(
+			[
+				"jj",
+				"-R",
+				repositoryPath,
+				"--no-pager",
+				"log",
+				"--ignore-working-copy",
+				"--no-graph",
+				"-r",
+				revision,
+				"-T",
+				'commit_id ++ "\\t" ++ change_id ++ "\\n"',
+			],
+			{ captureOutput: true },
+		)
+		const lines = result.stdout.trim().split("\n").filter(Boolean)
+		if (result.exitCode !== 0 || lines.length !== 1) return null
+		const [commitId, changeId] = lines[0]!.split("\t")
+		return commitId && changeId ? { commitId, changeId } : null
+	})
+
+const jjSetBookmark = (
+	repositoryPath: string,
+	bookmark: string,
+	commitId: string,
+) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand(
+			[
+				"jj",
+				"-R",
+				repositoryPath,
+				"bookmark",
+				"create",
+				bookmark,
+				"-r",
+				commitId,
+			],
+			{ captureOutput: true },
+		)
+		if (result.exitCode !== 0)
+			return yield* new WorktreeError({
+				message: `Failed to create internal jj resume bookmark '${bookmark}': ${result.stderr.trim()}`,
+			})
+	})
+
+const jjDeleteBookmark = (repositoryPath: string, bookmark: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand(
+			["jj", "-R", repositoryPath, "bookmark", "delete", bookmark],
+			{ captureOutput: true },
+		)
+		if (result.exitCode !== 0)
+			return yield* new WorktreeError({
+				message: `Failed to delete internal jj resume bookmark '${bookmark}': ${result.stderr.trim()}`,
+			})
+	})
+
+const jjEditWorkspace = (workspacePath: string, commitId: string) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const result = yield* fs.runCommand(
+			["jj", "-R", workspacePath, "edit", commitId],
+			{ captureOutput: true },
+		)
+		if (result.exitCode !== 0)
+			return yield* new WorktreeError({
+				message: `Failed to restore jj workspace ${workspacePath} at ${commitId}: ${result.stderr.trim()}`,
+			})
+	})
+
+const restoreJjWorkspace = (
+	backend: VersionControlBackend,
+	checkout: {
+		repositoryPath: string
+		workspacePath: string
+		workspaceName: string
+		commitId: string
+	},
+) =>
+	Effect.gen(function* () {
+		yield* backend.createWorkspace({
+			repositoryPath: checkout.repositoryPath,
+			workspacePath: checkout.workspacePath,
+			workspaceName: checkout.workspaceName,
+			revision: checkout.commitId,
+		})
+		yield* jjEditWorkspace(checkout.workspacePath, checkout.commitId)
+	})
+
 // A process can stop after `jj workspace forget` but before checkout deletion.
 // Only recover that residual when its repository and complete tree still match.
 const inspectJjResidual = (
@@ -967,6 +1158,8 @@ const materializeJj = (options: {
 			workspacePath: string
 			workspaceName: string
 		}[] = []
+		const resumePath = jjResumePath(options.taskPath, options.phasePath)
+		const resume = yield* readJjResumeState(resumePath)
 		const base = "base" in options.execution ? options.execution.base : null
 		const { verboseLog } = createLoggers(options.commandOptions)
 		const forwardCommandOutput =
@@ -976,6 +1169,40 @@ const materializeJj = (options: {
 
 		if (!options.commandOptions.dryRun)
 			yield* fs.createDirectory(options.codePath)
+		if (resume) {
+			const requestedRepos = [
+				...options.requestedCheckouts.map(({ repo }) => repo),
+			].sort()
+			const resumeRepos = [...resume.checkouts.map(({ repo }) => repo)].sort()
+			if (
+				resume.taskId !== options.taskId ||
+				resume.phaseId !== (options.phaseId ?? null) ||
+				requestedRepos.join("\0") !== resumeRepos.join("\0")
+			) {
+				return yield* new WorktreeError({
+					message: `Jj resume metadata at ${resumePath} does not match this execution unit; restore or remove it manually before retrying`,
+				})
+			}
+			for (const checkout of resume.checkouts) {
+				const repositoryPath = join(options.root, "repos", checkout.repo)
+				const bookmark = yield* jjIdentity(repositoryPath, checkout.bookmark)
+				const commit = yield* jjIdentity(repositoryPath, checkout.commitId)
+				if (
+					!bookmark ||
+					!commit ||
+					bookmark.commitId !== checkout.commitId ||
+					bookmark.changeId !== checkout.changeId ||
+					commit.changeId !== checkout.changeId ||
+					checkout.workspacePath !== join(options.codePath, checkout.repo) ||
+					checkout.workspaceName !==
+						jjWorkspaceName(options.taskId, options.phaseId, checkout.repo)
+				) {
+					return yield* new WorktreeError({
+						message: `Cannot resume jj workspace for '${checkout.repo}'; recorded commit, change ID, path, or internal bookmark no longer agrees`,
+					})
+				}
+			}
+		}
 
 		return yield* Effect.gen(function* () {
 			for (const checkout of options.requestedCheckouts) {
@@ -986,19 +1213,38 @@ const materializeJj = (options: {
 					options.phaseId,
 					checkout.repo,
 				)
+				const resumeCheckout = resume?.checkouts.find(
+					(entry) => entry.repo === checkout.repo,
+				)
 				if (!(yield* fs.exists(repositoryPath))) {
 					return yield* new WorktreeError({
 						message: `Repository alias '${checkout.repo}' is not materialized; run 'agency repo setup --apply'`,
 					})
 				}
 
-				const exists = yield* fs.isDirectory(workspacePath)
+				let exists = yield* fs.isDirectory(workspacePath)
 				const canonicalPath = exists
 					? yield* fs.realPath(workspacePath)
 					: resolve(workspacePath)
 				const registered = (yield* backend.listWorkspaces(repositoryPath)).find(
 					(workspace) => workspace.path === canonicalPath,
 				)
+				if (exists && !registered && resumeCheckout) {
+					const residual = yield* inspectJjResidual(
+						options.root,
+						repositoryPath,
+						workspacePath,
+						resumeCheckout.commitId,
+					)
+					if (residual !== "clean") {
+						return yield* new WorktreeError({
+							message: `Cannot resume unregistered jj checkout ${workspacePath}; ${residual === "modified" ? "its contents differ from the recorded commit" : "its repository identity cannot be verified"}`,
+						})
+					}
+					if (!options.commandOptions.dryRun)
+						yield* fs.deleteDirectory(workspacePath)
+					exists = false
+				}
 				if (exists && !registered) {
 					return yield* new WorktreeError({
 						message: `Existing checkout ${workspacePath} is not registered as a jj workspace`,
@@ -1010,12 +1256,39 @@ const materializeJj = (options: {
 					})
 				}
 				if (exists && registered) {
+					const actualCommit = resumeCheckout
+						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
+						: yield* backend.workspaceHead(workspacePath)
+					if (resumeCheckout && actualCommit !== resumeCheckout.commitId) {
+						return yield* new WorktreeError({
+							message: `Existing jj workspace ${workspacePath} is at ${actualCommit ?? "an unknown target"}, not recorded resume commit ${resumeCheckout.commitId}`,
+						})
+					}
+					if ("ref" in checkout && !resumeCheckout) {
+						const expectedCommit = yield* backend.resolveRevision(
+							repositoryPath,
+							checkout.ref,
+						)
+						if (!expectedCommit) {
+							return yield* new WorktreeError({
+								message: `Reference '${checkout.ref}' for repository '${checkout.repo}' does not resolve to a commit; run 'agency repo fetch ${checkout.repo}' and retry`,
+							})
+						}
+						if (
+							actualCommit !== expectedCommit &&
+							!options.commandOptions.allowReferenceDrift
+						) {
+							return yield* new WorktreeError({
+								message: `Existing checkout ${workspacePath} does not match reference '${checkout.ref}' (${expectedCommit})`,
+							})
+						}
+					}
 					reports.push({
 						repo: checkout.repo,
 						kind: "branch" in checkout ? "writable" : "reference",
 						path: workspacePath,
 						requestedRef: "branch" in checkout ? checkout.branch : checkout.ref,
-						resolvedCommit: yield* backend.workspaceHead(workspacePath),
+						resolvedCommit: actualCommit,
 						action: "reused",
 					})
 					continue
@@ -1023,10 +1296,9 @@ const materializeJj = (options: {
 
 				const requestedRevision =
 					"branch" in checkout ? checkout.branch : checkout.ref
-				let revision = yield* backend.resolveRevision(
-					repositoryPath,
-					requestedRevision,
-				)
+				let revision =
+					resumeCheckout?.commitId ??
+					(yield* backend.resolveRevision(repositoryPath, requestedRevision))
 				if (!revision && "branch" in checkout && base) {
 					revision = yield* backend.resolveRevision(repositoryPath, base)
 				}
@@ -1058,20 +1330,45 @@ const materializeJj = (options: {
 					command,
 					status: options.commandOptions.dryRun ? "planned" : "completed",
 				})
-				if (!options.commandOptions.dryRun) {
-					yield* backend.createWorkspace({
-						repositoryPath,
-						workspacePath,
-						workspaceName,
-						revision,
-						...("branch" in checkout ? { branch: checkout.branch } : {}),
+				if (resumeCheckout) {
+					operations.push({
+						action: "restore-workspace",
+						repo: checkout.repo,
+						command: [
+							"jj",
+							"-R",
+							workspacePath,
+							"edit",
+							resumeCheckout.commitId,
+						],
+						status: options.commandOptions.dryRun ? "planned" : "completed",
 					})
+				}
+				if (!options.commandOptions.dryRun) {
+					if (resumeCheckout) {
+						yield* restoreJjWorkspace(backend, {
+							repositoryPath,
+							workspacePath,
+							workspaceName,
+							commitId: resumeCheckout.commitId,
+						})
+					} else {
+						yield* backend.createWorkspace({
+							repositoryPath,
+							workspacePath,
+							workspaceName,
+							revision,
+							...("branch" in checkout ? { branch: checkout.branch } : {}),
+						})
+					}
 					created.push({ repositoryPath, workspacePath, workspaceName })
 					const canonicalWorkspacePath = yield* fs.realPath(workspacePath)
 					const registeredAfterCreate = (yield* backend.listWorkspaces(
 						repositoryPath,
 					)).find((workspace) => workspace.path === canonicalWorkspacePath)
-					const head = yield* backend.workspaceHead(workspacePath)
+					const head = resumeCheckout
+						? ((yield* jjIdentity(workspacePath, "@"))?.commitId ?? null)
+						: yield* backend.workspaceHead(workspacePath)
 					if (!registeredAfterCreate || head !== revision) {
 						return yield* new WorktreeError({
 							message: `Created jj workspace for '${checkout.repo}' failed validation`,
@@ -1108,6 +1405,16 @@ const materializeJj = (options: {
 				})
 			}
 
+			if (resume && !options.commandOptions.dryRun) {
+				yield* fs.deleteFile(resumePath)
+				for (const checkout of resume.checkouts) {
+					yield* jjDeleteBookmark(
+						join(options.root, "repos", checkout.repo),
+						checkout.bookmark,
+					).pipe(Effect.ignore)
+				}
+			}
+
 			return {
 				root: options.root,
 				taskPath: options.taskPath,
@@ -1187,6 +1494,16 @@ const removeJj = (
 			"phases" in task.data && phaseId
 				? (yield* phases.show(taskId, phaseId, root)).data
 				: task.data
+		const phasePath =
+			"phases" in task.data && phaseId
+				? (yield* phases.show(taskId, phaseId, root)).path
+				: null
+		const resumePath = jjResumePath(task.path, phasePath)
+		if (yield* fs.exists(resumePath)) {
+			return yield* new WorktreeError({
+				message: `Jj resume metadata already exists at ${resumePath}; run 'agency work prepare' to complete the previous resume before removing the workspace again`,
+			})
+		}
 		const recoverable = new Map<string, string>()
 		const modifiedResiduals = new Map<string, string>()
 		for (const checkout of inspection.checkouts) {
@@ -1220,7 +1537,9 @@ const removeJj = (
 			checkout.conflicts
 				.filter(
 					(conflict) =>
-						conflict.kind !== "stale-registration" &&
+						!(
+							options.allowReferenceDrift && conflict.kind === "reference-drift"
+						) &&
 						!(
 							conflict.kind === "unregistered-checkout" &&
 							recoverable.has(checkout.path)
@@ -1244,48 +1563,79 @@ const removeJj = (
 		}
 
 		const plans: {
+			repo: string
 			repositoryPath: string
 			workspacePath: string
 			workspaceName: string
 			head: string
 			branch: string | null
 			registered: boolean
+			commitId: string
+			changeId: string
+			bookmark: string
 		}[] = []
 		for (const checkout of inspection.checkouts) {
-			if (checkout.dirty) {
+			if (checkout.dirty === true && options.persistResume === false) {
 				return yield* new WorktreeError({
 					message: `Failed to remove workspace for '${checkout.repo}': checkout has uncommitted changes`,
 				})
 			}
+			if (
+				checkout.exists &&
+				checkout.dirty === null &&
+				!recoverable.has(checkout.path)
+			) {
+				return yield* new WorktreeError({
+					message: `Failed to remove workspace for '${checkout.repo}': checkout cleanliness could not be verified`,
+				})
+			}
 			const repositoryPath = join(root, "repos", checkout.repo)
 			if (!checkout.registeredPath) {
 				const recoveryRevision = recoverable.get(checkout.path)
 				if (!recoveryRevision) continue
+				const identity = yield* jjIdentity(repositoryPath, recoveryRevision)
+				if (!identity) {
+					return yield* new WorktreeError({
+						message: `Cannot prove the exact jj target for unregistered checkout ${checkout.path}`,
+					})
+				}
 				plans.push({
+					repo: checkout.repo,
 					repositoryPath,
 					workspacePath: checkout.path,
 					workspaceName: jjWorkspaceName(taskId, phaseId, checkout.repo),
 					head: recoveryRevision,
 					branch: checkout.actualBranch,
 					registered: false,
+					...identity,
+					bookmark: jjResumeBookmark(taskId, phaseId, checkout.repo),
 				})
 				continue
 			}
 			const registered = (yield* backend.listWorkspaces(repositoryPath)).find(
 				(workspace) => workspace.path === checkout.registeredPath,
 			)
-			if (!registered?.name || !checkout.actualCommit) {
+			if (!registered?.name || !checkout.actualCommit || !registered.commit) {
 				return yield* new WorktreeError({
 					message: `Cannot identify jj workspace at ${checkout.registeredPath}`,
 				})
 			}
+			const identity = yield* jjIdentity(repositoryPath, registered.commit)
+			if (!identity || identity.commitId !== registered.commit) {
+				return yield* new WorktreeError({
+					message: `Cannot prove the exact jj target for workspace at ${checkout.registeredPath}`,
+				})
+			}
 			plans.push({
+				repo: checkout.repo,
 				repositoryPath,
 				workspacePath: checkout.path,
 				workspaceName: registered.name,
-				head: checkout.actualCommit,
+				head: identity.commitId,
 				branch: checkout.actualBranch,
 				registered: true,
+				...identity,
+				bookmark: jjResumeBookmark(taskId, phaseId, checkout.repo),
 			})
 		}
 
@@ -1302,7 +1652,33 @@ const removeJj = (
 		if (options.dryRun) return plans.map((plan) => plan.workspacePath)
 
 		const completed: typeof plans = []
+		const persistent = options.persistResume !== false && plans.length > 0
+		const resume: JjResumeState = {
+			version: 1,
+			taskId,
+			phaseId: phaseId ?? null,
+			checkouts: plans.map((plan) => ({
+				repo: plan.repo,
+				workspacePath: plan.workspacePath,
+				workspaceName: plan.workspaceName,
+				commitId: plan.commitId,
+				changeId: plan.changeId,
+				bookmark: plan.bookmark,
+			})),
+		}
+		const bookmarks: typeof plans = []
 		return yield* Effect.gen(function* () {
+			if (persistent) {
+				for (const plan of plans) {
+					yield* jjSetBookmark(
+						plan.repositoryPath,
+						plan.bookmark,
+						plan.commitId,
+					)
+					bookmarks.push(plan)
+				}
+				yield* writeJjResumeState(resumePath, resume)
+			}
 			for (const plan of plans) {
 				if (plan.registered) {
 					yield* backend.removeWorkspace({
@@ -1322,19 +1698,45 @@ const removeJj = (
 				Effect.gen(function* () {
 					const rolledBack: string[] = []
 					const manualRecovery: string[] = []
-					for (const plan of [...completed].reverse()) {
+					const rollback = [...completed]
+					for (const plan of plans) {
+						if (completed.includes(plan)) continue
+						const registered = (yield* backend.listWorkspaces(
+							plan.repositoryPath,
+						)).some((workspace) => workspace.name === plan.workspaceName)
+						if (!registered) rollback.push(plan)
+					}
+					for (const plan of rollback.reverse()) {
+						if (yield* fs.exists(plan.workspacePath)) {
+							const removed = yield* fs
+								.deleteDirectory(plan.workspacePath)
+								.pipe(
+									Effect.as(true),
+									Effect.catchAll(() => Effect.succeed(false)),
+								)
+							if (!removed) {
+								manualRecovery.push(`Restore ${plan.workspacePath}`)
+								continue
+							}
+						}
 						const restored = yield* Effect.either(
-							backend.createWorkspace({
+							restoreJjWorkspace(backend, {
 								repositoryPath: plan.repositoryPath,
 								workspacePath: plan.workspacePath,
 								workspaceName: plan.workspaceName,
-								revision: plan.head,
-								...(plan.branch ? { branch: plan.branch } : {}),
+								commitId: plan.commitId,
 							}),
 						)
 						if (restored._tag === "Right") rolledBack.push(plan.workspacePath)
 						else manualRecovery.push(`Restore ${plan.workspacePath}`)
 					}
+					if (manualRecovery.length === 0 && persistent) {
+						if (yield* fs.exists(resumePath)) yield* fs.deleteFile(resumePath)
+						for (const plan of bookmarks)
+							yield* jjDeleteBookmark(plan.repositoryPath, plan.bookmark).pipe(
+								Effect.ignore,
+							)
+					}
 					return yield* new WorktreeError({
 						message: manualRecovery.length
 							? "Workspace removal failed and requires manual recovery"
@@ -2392,7 +2794,12 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										root,
 									)
 									const blockingConflicts = inspection.conflicts.filter(
-										(conflict) => conflict.kind !== "stale-registration",
+										(conflict) =>
+											conflict.kind !== "stale-registration" &&
+											!(
+												options.allowReferenceDrift &&
+												conflict.kind === "reference-drift"
+											),
 									)
 									if (blockingConflicts.length > 0) {
 										return yield* new WorktreeError({
@@ -2723,21 +3130,29 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						)
 					}
 					const inspection = yield* inspectExecution(taskId, phaseId, root)
-					const dirty = inspection.checkouts.filter(
-						(checkout) => checkout.dirty === true,
+					const notProvablyClean = inspection.checkouts.filter(
+						(checkout) => checkout.exists && checkout.dirty !== false,
 					)
-					if (dirty.length > 0) {
+					if (notProvablyClean.length > 0) {
+						const unknown = notProvablyClean.some(
+							(checkout) => checkout.dirty === null,
+						)
 						return yield* new WorktreeError({
-							message: `Cannot rebuild ${dirty.map((checkout) => checkout.path).join(", ")}; checkout has uncommitted changes`,
-							conflicts: dirty.flatMap((checkout) => checkout.conflicts),
+							message: `Cannot rebuild ${notProvablyClean.map((checkout) => checkout.path).join(", ")}; ${unknown ? "checkout cleanliness could not be verified" : "checkout has uncommitted changes"}`,
+							conflicts: notProvablyClean.flatMap(
+								(checkout) => checkout.conflicts,
+							),
 						})
 					}
-					if (inspection.conflicts.length > 0) {
+					const blockingConflicts = inspection.conflicts.filter(
+						(conflict) => conflict.kind !== "reference-drift",
+					)
+					if (blockingConflicts.length > 0) {
 						return yield* new WorktreeError({
-							message: inspection.conflicts
+							message: blockingConflicts
 								.map(({ message }) => message)
 								.join("\n"),
-							conflicts: inspection.conflicts,
+							conflicts: blockingConflicts,
 						})
 					}
 					yield* service.materialize(taskId, phaseId, inspection.root, {
@@ -2745,6 +3160,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						dryRun: true,
 						silent: true,
 						lockHeld: true,
+						allowReferenceDrift: true,
 					})
 					if (options.dryRun) {
 						return {
@@ -2768,6 +3184,8 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							...options,
 							snapshots,
 							lockHeld: true,
+							allowReferenceDrift: true,
+							persistResume: false,
 						},
 					)
 					const workspace = yield* service
@@ -2819,7 +3237,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 										const restored = yield* fs.runCommand(command, {
 											captureOutput: true,
 										})
-										if (restored.exitCode === 0) rolledBack.push(snapshot.path)
+										const edited =
+											restored.exitCode === 0 && snapshot.vcs === "jj"
+												? yield* fs.runCommand(
+														["jj", "-R", snapshot.path, "edit", snapshot.head],
+														{ captureOutput: true },
+													)
+												: restored
+										if (edited.exitCode === 0) rolledBack.push(snapshot.path)
 										else manualRecovery.push(`Restore ${snapshot.path}`)
 									}
 									return yield* new WorktreeError({