@markjaquith/agency 2.22.0 → 2.23.0

package/README.md

@@ -400,6 +400,8 @@ repository. Alias names are then used by all documents and commands.
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
 status, validation, graph export, reconciliation, and PR creation.
+Entity create, list, and show results include a stable SHA-256 `revision` of the
+complete Markdown document.
 
 ### Epics
 
@@ -515,6 +517,13 @@ references as one rollback-capable mutation and refuse when a materialized
 worktree would make the directory move unsafe. Mutation JSON includes changed
 paths and the focused validation scope.
 
+Epic, task, and phase update, rename, move, and dependency mutations accept
+`--if-revision <hash>`. The option is optional for interactive human use. When
+provided, Agency fails with a structured `REVISION_CONFLICT` containing the
+expected and current revisions if the target changed. Multi-document mutations
+also recheck every affected document after taking the mutation lock and before
+writing anything.
+
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Use claims for coordinated ownership and the status subcommands

package/cli.ts

@@ -238,6 +238,7 @@ const commands: Record<string, Command> = {
 					ticketUrl: options["ticket-url"],
 					description: options.description,
 					clearDescription: options["clear-description"],
+					ifRevision: options["if-revision"],
 					repos: options.repo,
 					json: options.json,
 					statuses: options.status,
@@ -289,6 +290,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					dependsOn: options["depends-on"],
 					firstPhase: options["first-phase"],
 					json: options.json,
@@ -399,6 +401,7 @@ const commands: Record<string, Command> = {
 					clearReferences: options["clear-references"],
 					prUrl: options["pr-url"],
 					clearPr: options["clear-pr"],
+					ifRevision: options["if-revision"],
 					noEpic: options["no-epic"],
 					multiPhase: options["multi-phase"],
 					json: options.json,

package/package.json

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

package/src/cli-parser.test.ts

@@ -296,6 +296,31 @@ describe("strict CLI parsing", () => {
 		).toThrow("must be 'done' or 'dropped'")
 	})
 
+	test("accepts valid mutation revisions and rejects malformed hashes", () => {
+		const revision = "a".repeat(64)
+		expect(
+			parseCli([
+				"task",
+				"move",
+				"example",
+				"--no-epic",
+				"--if-revision",
+				revision,
+			]),
+		).toMatchObject({ values: { "if-revision": revision } })
+		expect(() =>
+			parseCli([
+				"phase",
+				"rename",
+				"task",
+				"phase",
+				"renamed",
+				"--if-revision",
+				"stale",
+			]),
+		).toThrow("64-character SHA-256 hash")
+	})
+
 	test("accepts context projections and keeps compact command-local", () => {
 		expect(parseCli(["context", ".", "--json", "--compact"])).toMatchObject({
 			commandName: "context",

package/src/cli-parser.ts

@@ -91,6 +91,7 @@ const phaseCreateOptions = {
 } satisfies OptionConfig
 
 const mutationOptions = {
+	"if-revision": { type: "string" },
 	"clear-description": { type: "boolean" },
 	"clear-ticket": { type: "boolean" },
 	"clear-references": { type: "boolean" },
@@ -249,6 +250,7 @@ const commands = {
 					"clear-description",
 					"ticket-url",
 					"repo",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["repo"],
@@ -258,7 +260,7 @@ const commands = {
 				usage: "agency epic rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -344,6 +346,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -358,13 +361,13 @@ const commands = {
 				usage: "agency task rename <id> <new-id> [--json]",
 				minArgs: 2,
 				maxArgs: 2,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			move: {
 				usage: "agency task move <id> (--epic <id> | --no-epic) [--json]",
 				minArgs: 1,
 				maxArgs: 1,
-				options: ["epic", "no-epic", "json"],
+				options: ["epic", "no-epic", "if-revision", "json"],
 				conflicts: [["epic", "no-epic"]],
 			},
 			dependency: {
@@ -372,7 +375,7 @@ const commands = {
 					"agency task dependency <add|remove> <task-id> <dependency-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -441,6 +444,7 @@ const commands = {
 					"base",
 					"pr-url",
 					"clear-pr",
+					"if-revision",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -454,14 +458,14 @@ const commands = {
 				usage: "agency phase rename <task-id> <phase-id> <new-id> [--json]",
 				minArgs: 3,
 				maxArgs: 3,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 			dependency: {
 				usage:
 					"agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id> [--json]",
 				minArgs: 4,
 				maxArgs: 4,
-				options: ["json"],
+				options: ["if-revision", "json"],
 			},
 		},
 	},
@@ -1125,11 +1129,22 @@ export function parseCli(args: readonly string[]): ParsedCli {
 		["epic", "task", "phase"].includes(commandName) &&
 		subcommand === "update"
 	) {
-		const mutationNames = (spec.options ?? []).filter((name) => name !== "json")
+		const mutationNames = (spec.options ?? []).filter(
+			(name) => name !== "json" && name !== "if-revision",
+		)
 		if (!mutationNames.some((name) => parsed.values[name] !== undefined)) {
 			throw usageError("At least one update option is required.", spec.usage)
 		}
 	}
+	if (
+		typeof parsed.values["if-revision"] === "string" &&
+		!/^[a-f0-9]{64}$/.test(parsed.values["if-revision"])
+	) {
+		throw usageError(
+			"Option '--if-revision' must be a 64-character SHA-256 hash.",
+			spec.usage,
+		)
+	}
 	if (commandName === "graph") {
 		validateGraphOptions(parsed.values, spec)
 	}

package/src/cli.test.ts

@@ -203,6 +203,41 @@ describe("CLI", () => {
 				),
 			)
 		}
+		const observed = parseJson(
+			await runCli(["task", "show", "second", "--json"], root),
+		)
+		const taskPath = join(root, "tasks/second/TASK.md")
+		await Bun.write(
+			taskPath,
+			`${await Bun.file(taskPath).text()}\nConcurrent edit.\n`,
+		)
+		const conflict = await runCli(
+			[
+				"task",
+				"update",
+				"second",
+				"--description",
+				"Stale update",
+				"--if-revision",
+				observed.revision,
+				"--json",
+			],
+			root,
+		)
+		expect(conflict.exitCode).toBe(1)
+		expect(JSON.parse(conflict.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/second/TASK.md",
+					expectedRevision: observed.revision,
+					currentRevision: expect.stringMatching(/^[a-f0-9]{64}$/),
+				},
+			},
+		})
+		expect(await Bun.file(taskPath).text()).toContain("Concurrent edit.")
 
 		const updated = parseJson(
 			await runCli(

package/src/commands/epic.test.ts

@@ -40,9 +40,12 @@ describe("epic command", () => {
 			),
 		)
 
-		expect(JSON.parse(logs[0]!)).toEqual({
+		const created = JSON.parse(logs[0]!)
+		expect(created.revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(created).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: created.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],
@@ -68,10 +71,13 @@ describe("epic command", () => {
 				epic({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "example",
 				path: join(root, "epics/example/EPIC.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/epic",
 					repos: [{ repo: "agency", ref: "main" }],
@@ -90,9 +96,12 @@ describe("epic command", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "example",
 			path: join(root, "epics/example/EPIC.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/epic",
 				repos: [{ repo: "agency", ref: "main" }],

package/src/commands/epic.ts

@@ -13,6 +13,7 @@ interface EpicOptions extends BaseCommandOptions {
 	readonly ticketUrl?: string
 	readonly description?: string
 	readonly clearDescription?: boolean
+	readonly ifRevision?: string
 	readonly repos?: readonly string[]
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
@@ -122,6 +123,7 @@ export const epic = (options: EpicOptions) =>
 								: parseRepositoryReferences(options.repos),
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -138,7 +140,12 @@ export const epic = (options: EpicOptions) =>
 						new Error("Epic ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameEpic(id, newId, cwd)
+				const output = yield* mutations.renameEpic(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -177,6 +184,9 @@ Update options:
   --clear-description   Remove the description
   --repo <alias>:<ref>  Replace repository references; repeatable
 
+Mutation options:
+  --if-revision <hash>  Require the target's current revision
+
 Options:
   --json                Output results as JSON
   --status <status>     Filter list by status; repeatable

package/src/commands/phase.ts

@@ -19,6 +19,7 @@ interface PhaseOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly dependsOn?: readonly string[]
 	readonly firstPhase?: string
 	readonly json?: boolean
@@ -181,6 +182,7 @@ export const phase = (options: PhaseOptions) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -196,7 +198,13 @@ export const phase = (options: PhaseOptions) =>
 						new Error("Task ID, phase ID, and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renamePhase(taskId, phaseId, newId, cwd)
+				const output = yield* mutations.renamePhase(
+					taskId,
+					phaseId,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -225,6 +233,7 @@ export const phase = (options: PhaseOptions) =>
 					dependencyPhaseId,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -257,6 +266,9 @@ Subcommands:
   dependency <operation> <task> <phase> <dependency>
                         Add or remove a phase dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --description <text>  Short description of the phase
   --repo <alias>        Writable repository

package/src/commands/task-phase.test.ts

@@ -48,10 +48,13 @@ describe("task and phase command JSON output", () => {
 				task({ subcommand: "list", args: [], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				id: "multi",
 				path: join(root, "tasks/multi/TASK.md"),
+				revision: listed[0].revision,
 				data: {
 					ticketUrl: "https://example.com/task",
 					phases: [{ id: "first" }],
@@ -69,9 +72,12 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			id: "multi",
 			path: join(root, "tasks/multi/TASK.md"),
+			revision: shown.revision,
 			data: {
 				ticketUrl: "https://example.com/task",
 				phases: [{ id: "first" }],
@@ -85,11 +91,14 @@ describe("task and phase command JSON output", () => {
 				phase({ subcommand: "list", args: ["multi"], cwd: root, json: true }),
 			),
 		)
-		expect(JSON.parse(listLogs[0]!)).toEqual([
+		const listed = JSON.parse(listLogs[0]!)
+		expect(listed[0].revision).toMatch(/^[a-f0-9]{64}$/)
+		expect(listed).toEqual([
 			{
 				taskId: "multi",
 				id: "first",
 				path: join(root, "tasks/multi/phases/first/PHASE.md"),
+				revision: listed[0].revision,
 				data: {
 					repo: "agency",
 					branch: "task/first",
@@ -110,10 +119,13 @@ describe("task and phase command JSON output", () => {
 				}),
 			),
 		)
-		expect(JSON.parse(showLogs[0]!)).toEqual({
+		const shown = JSON.parse(showLogs[0]!)
+		expect(shown.revision).toBe(listed[0].revision)
+		expect(shown).toEqual({
 			taskId: "multi",
 			id: "first",
 			path: join(root, "tasks/multi/phases/first/PHASE.md"),
+			revision: shown.revision,
 			data: {
 				repo: "agency",
 				branch: "task/first",

package/src/commands/task.ts

@@ -27,6 +27,7 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly clearReferences?: boolean
 	readonly prUrl?: string
 	readonly clearPr?: boolean
+	readonly ifRevision?: string
 	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
 	readonly json?: boolean
@@ -318,6 +319,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						pr: options.clearPr ? null : options.prUrl,
 					},
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -333,7 +335,12 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 						new Error("Task ID and new ID are required"),
 					)
 				}
-				const output = yield* mutations.renameTask(id, newId, cwd)
+				const output = yield* mutations.renameTask(
+					id,
+					newId,
+					cwd,
+					options.ifRevision,
+				)
 				log(
 					options.json
 						? JSON.stringify(output, null, 2)
@@ -348,6 +355,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					options.noEpic ? null : (options.epic ?? null),
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -376,6 +384,7 @@ export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 					id,
 					dependencyId,
 					cwd,
+					options.ifRevision,
 				)
 				log(
 					options.json
@@ -408,6 +417,9 @@ Subcommands:
   dependency <operation> <task> <dependency>
                         Add or remove a task dependency
 
+Mutation option:
+  --if-revision <hash>  Require the target's current revision
+
 Create options:
   --ticket-url <url>    External ticket URL (optional)
   --description <text>  Short description of the task

package/src/protocol.test.ts

@@ -108,5 +108,24 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(
+			errorEnvelope({
+				_tag: "RevisionConflictError",
+				message: "revision conflict",
+				path: "tasks/example/TASK.md",
+				expectedRevision: "a".repeat(64),
+				currentRevision: "b".repeat(64),
+			}),
+		).toMatchObject({
+			error: {
+				code: "REVISION_CONFLICT",
+				retryable: true,
+				fields: {
+					path: "tasks/example/TASK.md",
+					expectedRevision: "a".repeat(64),
+					currentRevision: "b".repeat(64),
+				},
+			},
+		})
 	})
 })

package/src/services/ClaimService.ts

@@ -9,12 +9,16 @@ import {
 	unlink,
 	writeFile,
 } from "node:fs/promises"
-import { basename, dirname, join } from "node:path"
+import { basename, dirname, join, relative } from "node:path"
 import { PhaseService } from "./PhaseService"
 import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
 import { FileSystemService } from "./FileSystemService"
-import { documentRevision } from "../workbase/document-revision"
+import {
+	documentRevision,
+	isDocumentRevision,
+	RevisionConflictError,
+} from "../workbase/document-revision"
 import {
 	formatMarkdownDocument,
 	parseFrontmatterSync,
@@ -33,14 +37,6 @@ class ClaimError extends Data.TaggedError("ClaimError")<{
 	readonly target?: string
 }> {}
 
-class RevisionConflictError extends Data.TaggedError("RevisionConflictError")<{
-	readonly message: string
-	readonly target: string
-	readonly expectedRevision: string
-	readonly actualRevision: string
-	readonly claim?: ClaimRecord
-}> {}
-
 class ClaimConflictError extends Data.TaggedError("ClaimConflictError")<{
 	readonly message: string
 	readonly target: string
@@ -59,6 +55,7 @@ class ClaimOwnershipError extends Data.TaggedError("ClaimOwnershipError")<{
 
 interface ClaimTarget {
 	readonly kind: "task" | "phase"
+	readonly root: string
 	readonly taskId: string
 	readonly phaseId?: string
 	readonly path: string
@@ -149,7 +146,7 @@ const decodeExecution = (target: ClaimTarget, input: unknown) => {
 }
 
 const assertRevision = (revision: string) => {
-	if (!/^[a-f0-9]{64}$/.test(revision)) {
+	if (!isDocumentRevision(revision)) {
 		throw new ClaimError({
 			message: "Revision must be a 64-character SHA-256 hash",
 		})
@@ -169,8 +166,7 @@ const isUnexpired = (claim: ClaimRecord, now: Date) =>
 	claim.state === "active" &&
 	(claim.expiresAt === undefined || Date.parse(claim.expiresAt) > now.getTime())
 
-const acquireLock = async (path: string) => {
-	const lockPath = `${path}.claim.lock`
+const acquireLock = async (lockPath: string, label: string) => {
 	for (let attempt = 0; attempt < 1_750; attempt += 1) {
 		try {
 			const handle = await open(lockPath, "wx")
@@ -192,7 +188,7 @@ const acquireLock = async (path: string) => {
 			await Bun.sleep(20)
 		}
 	}
-	throw new ClaimError({ message: `Timed out waiting to update ${path}` })
+	throw new ClaimError({ message: `Timed out waiting to update ${label}` })
 }
 
 const updateAtomically = async <T>(
@@ -207,18 +203,24 @@ const updateAtomically = async <T>(
 	now: Date,
 ) => {
 	assertRevision(expectedRevision)
-	const { handle, lockPath } = await acquireLock(target.path)
+	const graphLock = await acquireLock(
+		join(target.root, ".agency-graph-mutation.lock"),
+		target.root,
+	)
+	let documentLock: Awaited<ReturnType<typeof acquireLock>> | undefined
 	let temporaryPath: string | undefined
 	try {
+		documentLock = await acquireLock(`${target.path}.claim.lock`, target.path)
 		const content = await readFile(target.path, "utf8")
-		const actualRevision = documentRevision(content)
+		const currentRevision = documentRevision(content)
 		const parsed = parseFrontmatterSync(content, target.path)
 		const current = decodeExecution(target, parsed.data)
-		if (actualRevision !== expectedRevision) {
+		if (currentRevision !== expectedRevision) {
 			throw new RevisionConflictError({
+				path: relative(target.root, target.path),
 				target: target.label,
 				expectedRevision,
-				actualRevision,
+				currentRevision,
 				claim: current.claim,
 				message: `Revision conflict for ${target.label}`,
 			})
@@ -235,13 +237,15 @@ const updateAtomically = async <T>(
 		return {
 			...result,
 			target: target.label,
-			previousRevision: actualRevision,
+			previousRevision: currentRevision,
 			revision: documentRevision(updatedContent),
 		}
 	} finally {
 		if (temporaryPath) await unlink(temporaryPath).catch(() => undefined)
-		await handle.close().catch(() => undefined)
-		await unlink(lockPath).catch(() => undefined)
+		await documentLock?.handle.close().catch(() => undefined)
+		if (documentLock) await unlink(documentLock.lockPath).catch(() => undefined)
+		await graphLock.handle.close().catch(() => undefined)
+		await unlink(graphLock.lockPath).catch(() => undefined)
 	}
 }
 
@@ -278,6 +282,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 					const target: ClaimTarget = phaseId
 						? {
 								kind: "phase",
+								root,
 								taskId: task.id,
 								phaseId,
 								path: phase!.path,
@@ -285,6 +290,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 							}
 						: {
 								kind: "task",
+								root,
 								taskId: task.id,
 								path: task.path,
 								label: `task '${task.id}'`,

package/src/services/ContextService.ts

@@ -7,6 +7,7 @@ import { normalizePullRequestRecord } from "../workbase/delivery-command"
 import { RepositoryService } from "./RepositoryService"
 import { aggregateProgress, readinessState } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
+import { documentRevision } from "../workbase/document-revision"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
@@ -78,9 +79,6 @@ const decode = <S extends Schema.Schema.AnyNoContext>(
 		: { ok: true as const, value: result.right }
 }
 
-const hash = (content: string) =>
-	new Bun.CryptoHasher("sha256").update(content).digest("hex")
-
 const isWithin = (root: string, path: string) => {
 	const child = relative(root, path)
 	return child === "" || (!child.startsWith(`..${sep}`) && child !== "..")
@@ -205,7 +203,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							return {
 								id,
 								path,
-								sha256: hash(content),
+								sha256: documentRevision(content),
 								data: decoded.value,
 								body: parsed.body,
 							} satisfies Document<Schema.Schema.Type<S>>
@@ -279,7 +277,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 							taskDocuments.set(entry.name, {
 								id: entry.name,
 								path,
-								sha256: hash(content),
+								sha256: documentRevision(content),
 								data: decoded.value,
 								body: parsed.right.body,
 							})
@@ -303,7 +301,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 								phaseDocuments.set(`${entry.name}/${phaseEntry.name}`, {
 									id: phaseEntry.name,
 									path: phasePath,
-									sha256: hash(phaseContent),
+									sha256: documentRevision(phaseContent),
 									data: phaseDecoded.value,
 									body: phaseParsed.right.body,
 								})

package/src/services/EpicService.ts

@@ -12,6 +12,7 @@ import {
 	formatMarkdownDocument,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
+import { documentRevision } from "../workbase/document-revision"
 
 class EpicError extends Data.TaggedError("EpicError")<{
 	readonly message: string
@@ -21,6 +22,7 @@ export interface EpicRecord {
 	readonly id: string
 	readonly path: string
 	readonly content: string
+	readonly revision: string
 	readonly data: Schema.Schema.Type<typeof EpicFrontmatter>
 }
 
@@ -90,7 +92,13 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 					`# ${title}\n\nDescribe the epic outcome.`,
 				)
 				yield* fs.writeFile(path, content)
-				return { id: validId, path, content, data } satisfies EpicRecord
+				return {
+					id: validId,
+					path,
+					content,
+					revision: documentRevision(content),
+					data,
+				} satisfies EpicRecord
 			}),
 
 		list: (startPath: string = process.cwd()) =>
@@ -113,7 +121,13 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 					const content = yield* fs.readFile(path)
 					const parsed = yield* parseFrontmatter(content, path)
 					const data = yield* decodeEpic(parsed.data)
-					records.push({ id: entry.name, path, content, data })
+					records.push({
+						id: entry.name,
+						path,
+						content,
+						revision: documentRevision(content),
+						data,
+					})
 				}
 				return records
 			}),

package/src/services/GraphMutationService.test.ts

@@ -280,6 +280,37 @@ describe("GraphMutationService", () => {
 		)
 	})
 
+	test("rejects stale guarded moves before changing any document", async () => {
+		const paths = [
+			join(root, "tasks/alpha/TASK.md"),
+			join(root, "epics/first-epic/EPIC.md"),
+			join(root, "epics/second-epic/EPIC.md"),
+		]
+		const before = await Promise.all(paths.map((path) => Bun.file(path).text()))
+		let conflict: unknown
+		try {
+			await runTestEffect(
+				Effect.gen(function* () {
+					return yield* (yield* GraphMutationService).moveTask(
+						"alpha",
+						"second-epic",
+						root,
+						"0".repeat(64),
+					)
+				}),
+			)
+		} catch (error) {
+			conflict = error
+		}
+
+		expect(String(conflict)).toContain(
+			"Revision conflict for tasks/alpha/TASK.md",
+		)
+		expect(
+			await Promise.all(paths.map((path) => Bun.file(path).text())),
+		).toEqual(before)
+	})
+
 	test("refuses a rename that would invalidate a materialized worktree", async () => {
 		await mkdir(join(root, "tasks/alpha/code/agency"), { recursive: true })
 		await expect(

package/src/services/GraphMutationService.ts

@@ -2,9 +2,9 @@ import { Schema, TreeFormatter } from "@effect/schema"
 import { Data, Effect, Either } from "effect"
 import { open, rename, rm } from "node:fs/promises"
 import { dirname, join, relative } from "node:path"
-import { EpicService } from "./EpicService"
+import { EpicService, type EpicRecord } from "./EpicService"
 import { FileSystemService } from "./FileSystemService"
-import { PhaseService } from "./PhaseService"
+import { PhaseService, type PhaseRecord } from "./PhaseService"
 import { TaskService } from "./TaskService"
 import { WorkbaseService } from "./WorkbaseService"
 import {
@@ -23,6 +23,10 @@ import {
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { validateDependencies } from "../workbase/dependency-graph"
+import {
+	documentRevision,
+	RevisionConflictError,
+} from "../workbase/document-revision"
 
 class GraphMutationError extends Data.TaggedError("GraphMutationError")<{
 	readonly message: string
@@ -47,6 +51,10 @@ interface MutationResult {
 
 interface WritePlan {
 	readonly root: string
+	readonly preconditions: readonly {
+		readonly path: string
+		readonly revision: string
+	}[]
 	readonly writes: readonly {
 		readonly path: string
 		readonly content: string
@@ -114,7 +122,7 @@ const exists = async (path: string) => {
 	}
 }
 
-const applyWritePlan = ({ root, writes, move }: WritePlan) =>
+const applyWritePlan = ({ root, preconditions, writes, move }: WritePlan) =>
 	Effect.tryPromise({
 		try: async () => {
 			const lockPath = join(root, ".agency-graph-mutation.lock")
@@ -139,6 +147,18 @@ const applyWritePlan = ({ root, writes, move }: WritePlan) =>
 			let moved = false
 			let rollbackFailed = false
 			try {
+				for (const precondition of preconditions) {
+					const content = await Bun.file(precondition.path).text()
+					const currentRevision = documentRevision(content)
+					if (currentRevision !== precondition.revision) {
+						throw new RevisionConflictError({
+							path: relative(root, precondition.path),
+							expectedRevision: precondition.revision,
+							currentRevision,
+							message: `Revision conflict for ${relative(root, precondition.path)}`,
+						})
+					}
+				}
 				for (const write of staged) await Bun.write(write.stage, write.content)
 				if (move) {
 					await rename(move.from, move.to)
@@ -195,7 +215,8 @@ const applyWritePlan = ({ root, writes, move }: WritePlan) =>
 			}
 		},
 		catch: (cause) =>
-			cause instanceof GraphMutationError
+			cause instanceof GraphMutationError ||
+			cause instanceof RevisionConflictError
 				? cause
 				: new GraphMutationError({
 						message:
@@ -212,6 +233,19 @@ const contentWith = (
 		Effect.map((parsed) => formatMarkdownDocument(data, parsed.body)),
 	)
 
+type RevisionedRecord = {
+	readonly path: string
+	readonly revision: string
+}
+
+const precondition = (
+	record: RevisionedRecord,
+	ifRevision?: string,
+): { readonly path: string; readonly revision: string } => ({
+	path: record.path,
+	revision: ifRevision ?? record.revision,
+})
+
 const result = (
 	root: string,
 	operation: string,
@@ -250,6 +284,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				updates: EpicUpdates,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -289,10 +324,18 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						})
 					}
 					const content = yield* contentWith(record, data)
-					if (content === record.content)
+					if (content === record.content) {
+						if (ifRevision)
+							yield* applyWritePlan({
+								root,
+								preconditions: [precondition(record, ifRevision)],
+								writes: [],
+							})
 						return result(root, "epic.update", "epic", id, [])
+					}
 					yield* applyWritePlan({
 						root,
+						preconditions: [precondition(record, ifRevision)],
 						writes: [{ path: record.path, content }],
 					})
 					return result(root, "epic.update", "epic", id, [record.path])
@@ -302,6 +345,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				updates: TaskUpdates,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -410,10 +454,18 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						}
 					}
 					const content = yield* contentWith(record, data)
-					if (content === record.content)
+					if (content === record.content) {
+						if (ifRevision)
+							yield* applyWritePlan({
+								root,
+								preconditions: [precondition(record, ifRevision)],
+								writes: [],
+							})
 						return result(root, "task.update", "task", id, [])
+					}
 					yield* applyWritePlan({
 						root,
+						preconditions: [precondition(record, ifRevision)],
 						writes: [{ path: record.path, content }],
 					})
 					return result(root, "task.update", "task", id, [record.path])
@@ -424,6 +476,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				updates: PhaseUpdates,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -515,10 +568,18 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						}
 					}
 					const content = yield* contentWith(record, data)
-					if (content === record.content)
+					if (content === record.content) {
+						if (ifRevision)
+							yield* applyWritePlan({
+								root,
+								preconditions: [precondition(record, ifRevision)],
+								writes: [],
+							})
 						return result(root, "phase.update", "phase", id, [])
+					}
 					yield* applyWritePlan({
 						root,
+						preconditions: [precondition(record, ifRevision)],
 						writes: [{ path: record.path, content }],
 					})
 					return result(root, "phase.update", "phase", id, [record.path])
@@ -529,6 +590,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				dependencyId: string,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -582,6 +644,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 					const content = yield* contentWith(epic, data)
 					yield* applyWritePlan({
 						root,
+						preconditions: [precondition(task, ifRevision), precondition(epic)],
 						writes: [{ path: epic.path, content }],
 					})
 					return result(root, `task.dependency.${operation}`, "task", id, [
@@ -595,12 +658,14 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				dependencyId: string,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const root = yield* workbase.discover(startPath)
 					const task = yield* tasks.show(taskId, root)
+					const phase = yield* (yield* PhaseService).show(taskId, id, root)
 					if (!("phases" in task.data))
 						return yield* new GraphMutationError({
 							message: `Task '${taskId}' does not have phases`,
@@ -641,6 +706,10 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 					const content = yield* contentWith(task, data)
 					yield* applyWritePlan({
 						root,
+						preconditions: [
+							precondition(phase, ifRevision),
+							precondition(task),
+						],
 						writes: [{ path: task.path, content }],
 					})
 					return result(root, `phase.dependency.${operation}`, "phase", id, [
@@ -652,6 +721,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				newId: string,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -698,7 +768,17 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							content: yield* contentWith(task, data),
 						})
 					}
-					yield* applyWritePlan({ root, writes, move: { from, to } })
+					yield* applyWritePlan({
+						root,
+						preconditions: [
+							precondition(epic, ifRevision),
+							...allTasks
+								.filter((task) => task.data.epic === id)
+								.map((task) => precondition(task)),
+						],
+						writes,
+						move: { from, to },
+					})
 					return result(
 						root,
 						"epic.rename",
@@ -713,6 +793,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				newId: string,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -736,6 +817,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						return yield* new GraphMutationError({
 							message: `Task '${id}' has a materialized worktree; remove it with Agency before renaming`,
 						})
+					const movedPhases: PhaseRecord[] = []
 					if ("phases" in task.data) {
 						for (const phase of task.data.phases) {
 							const record = yield* (yield* PhaseService).show(
@@ -743,6 +825,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 								phase.id,
 								root,
 							)
+							movedPhases.push(record)
 							if (record.data.claim?.state === "active")
 								return yield* new GraphMutationError({
 									message: `Phase '${phase.id}' has an active claim; release or finish it before renaming task '${id}'`,
@@ -762,6 +845,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						}
 					}
 					const writes: { path: string; content: string }[] = []
+					const affectedEpics: EpicRecord[] = []
 					for (const epic of yield* epics.list(root)) {
 						if (
 							!epic.data.tasks.some(
@@ -769,6 +853,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							)
 						)
 							continue
+						affectedEpics.push(epic)
 						const data = {
 							...epic.data,
 							tasks: epic.data.tasks.map((item) => ({
@@ -789,7 +874,16 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							content: yield* contentWith(epic, data),
 						})
 					}
-					yield* applyWritePlan({ root, writes, move: { from, to } })
+					yield* applyWritePlan({
+						root,
+						preconditions: [
+							precondition(task, ifRevision),
+							...movedPhases.map((phase) => precondition(phase)),
+							...affectedEpics.map((epic) => precondition(epic)),
+						],
+						writes,
+						move: { from, to },
+					})
 					return result(
 						root,
 						"task.rename",
@@ -805,6 +899,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				newId: string,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -856,6 +951,10 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 					const content = yield* contentWith(task, data)
 					yield* applyWritePlan({
 						root,
+						preconditions: [
+							precondition(phase, ifRevision),
+							precondition(task),
+						],
 						writes: [{ path: task.path, content }],
 						move: { from, to },
 					})
@@ -873,6 +972,7 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 				id: string,
 				epicId: string | null,
 				startPath: string = process.cwd(),
+				ifRevision?: string,
 			) =>
 				Effect.gen(function* () {
 					const workbase = yield* WorkbaseService
@@ -881,8 +981,15 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 					const root = yield* workbase.discover(startPath)
 					const task = yield* tasks.show(id, root)
 					const sourceId = task.data.epic
-					if (sourceId === epicId)
+					if (sourceId === epicId) {
+						if (ifRevision)
+							yield* applyWritePlan({
+								root,
+								preconditions: [precondition(task, ifRevision)],
+								writes: [],
+							})
 						return result(root, "task.move", "task", id, [])
+					}
 					const source = sourceId
 						? yield* epics.show(sourceId, root)
 						: undefined
@@ -938,7 +1045,15 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						path: task.path,
 						content: yield* contentWith(task, taskData),
 					})
-					yield* applyWritePlan({ root, writes })
+					yield* applyWritePlan({
+						root,
+						preconditions: [
+							precondition(task, ifRevision),
+							...(source ? [precondition(source)] : []),
+							...(target ? [precondition(target)] : []),
+						],
+						writes,
+					})
 					return result(
 						root,
 						"task.move",

package/src/services/GraphService.ts

@@ -21,6 +21,7 @@ import {
 } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
 import { normalizePullRequestRecord } from "../workbase/delivery-command"
+import { documentRevision } from "../workbase/document-revision"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
@@ -74,9 +75,6 @@ const taskExecutionNodeId = (taskId: string) => `execution-unit:task/${taskId}`
 const phaseExecutionNodeId = (taskId: string, phaseId: string) =>
 	`execution-unit:phase/${taskId}/${phaseId}`
 
-const hash = (content: string) =>
-	new Bun.CryptoHasher("sha256").update(content).digest("hex")
-
 const decode = <S extends Schema.Schema.AnyNoContext>(
 	schema: S,
 	input: unknown,
@@ -162,7 +160,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 							return {
 								id,
 								path,
-								sha256: hash(content),
+								sha256: documentRevision(content),
 								data: decoded.value,
 								body: parsed.body,
 							} satisfies Document<Schema.Schema.Type<S>>

package/src/services/PhaseService.ts

@@ -16,16 +16,18 @@ import {
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
+import { documentRevision } from "../workbase/document-revision"
 
 class PhaseError extends Data.TaggedError("PhaseError")<{
 	readonly message: string
 }> {}
 
-interface PhaseRecord {
+export interface PhaseRecord {
 	readonly taskId: string
 	readonly id: string
 	readonly path: string
 	readonly content: string
+	readonly revision: string
 	readonly data: PhaseData
 }
 
@@ -261,7 +263,14 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							task.path,
 							formatMarkdownDocument(convertedTaskData, parsedTask.body),
 						)
-						return { taskId, id, path, content, data } satisfies PhaseRecord
+						return {
+							taskId,
+							id,
+							path,
+							content,
+							revision: documentRevision(content),
+							data,
+						} satisfies PhaseRecord
 					}
 
 					yield* fs.createDirectory(directory)
@@ -283,7 +292,14 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						formatMarkdownDocument(updatedTaskData, parsedTask.body),
 					)
 
-					return { taskId, id, path, content, data } satisfies PhaseRecord
+					return {
+						taskId,
+						id,
+						path,
+						content,
+						revision: documentRevision(content),
+						data,
+					} satisfies PhaseRecord
 				}),
 
 			list: (taskId: string, startPath: string = process.cwd()) =>
@@ -311,6 +327,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							id: entry.name,
 							path,
 							content,
+							revision: documentRevision(content),
 							data,
 						})
 					}
@@ -363,7 +380,12 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 					const data = { ...record.data, status: validStatus }
 					const content = formatMarkdownDocument(data, parsed.body)
 					yield* fs.writeFile(record.path, content)
-					return { ...record, content, data } satisfies PhaseRecord
+					return {
+						...record,
+						content,
+						revision: documentRevision(content),
+						data,
+					} satisfies PhaseRecord
 				}),
 		}),
 	},

package/src/services/TaskService.ts

@@ -16,6 +16,7 @@ import {
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
+import { documentRevision } from "../workbase/document-revision"
 
 class TaskError extends Data.TaggedError("TaskError")<{
 	readonly message: string
@@ -25,6 +26,7 @@ interface TaskRecord {
 	readonly id: string
 	readonly path: string
 	readonly content: string
+	readonly revision: string
 	readonly data: TaskData
 }
 
@@ -158,7 +160,13 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					yield* fs.writeFile(parentEpic.path, updated)
 				}
 
-				return { id, path, content, data } satisfies TaskRecord
+				return {
+					id,
+					path,
+					content,
+					revision: documentRevision(content),
+					data,
+				} satisfies TaskRecord
 			}),
 
 		list: (startPath: string = process.cwd()) =>
@@ -178,7 +186,13 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					const content = yield* fs.readFile(path)
 					const parsed = yield* parseFrontmatter(content, path)
 					const data = yield* decodeTask(parsed.data)
-					records.push({ id: entry.name, path, content, data })
+					records.push({
+						id: entry.name,
+						path,
+						content,
+						revision: documentRevision(content),
+						data,
+					})
 				}
 				return records
 			}),
@@ -233,7 +247,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				const data = { ...record.data, status: validStatus }
 				const content = formatMarkdownDocument(data, parsed.body)
 				yield* fs.writeFile(record.path, content)
-				return { ...record, content, data } satisfies TaskRecord
+				return {
+					...record,
+					content,
+					revision: documentRevision(content),
+					data,
+				} satisfies TaskRecord
 			}),
 	}),
 }) {}

package/src/work-view.ts

@@ -23,6 +23,7 @@ export interface WorkViewRow {
 	readonly kind: "epic" | "task" | "phase"
 	readonly id: string
 	readonly key: string
+	readonly revision: string
 	readonly parent: string
 	readonly status: WorkStatus
 	readonly readiness: "ready" | "blocked" | "waiting" | "terminal"
@@ -91,6 +92,7 @@ const rowFor = (
 		kind: node.kind,
 		id,
 		key: node.key,
+		revision: node.data.sha256,
 		parent,
 		status: node.status,
 		readiness: readinessLabel(node),

package/src/workbase/document-revision.ts

@@ -1,2 +1,18 @@
+import { Data } from "effect"
+
 export const documentRevision = (content: string) =>
 	new Bun.CryptoHasher("sha256").update(content).digest("hex")
+
+export const isDocumentRevision = (revision: string) =>
+	/^[a-f0-9]{64}$/.test(revision)
+
+export class RevisionConflictError extends Data.TaggedError(
+	"RevisionConflictError",
+)<{
+	readonly message: string
+	readonly path: string
+	readonly target?: string
+	readonly expectedRevision: string
+	readonly currentRevision: string
+	readonly claim?: unknown
+}> {}