@markjaquith/agency 2.21.0 → 2.23.0

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,
@@ -23,6 +27,7 @@ import {
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	type ClaimRecord,
+	type PullRequestRecord,
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
@@ -32,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
@@ -58,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
@@ -98,7 +96,7 @@ interface ReconcileInput {
 	readonly taskId: string
 	readonly phaseId?: string
 	readonly revision: string
-	readonly pr?: string
+	readonly pr?: string | PullRequestRecord
 	readonly status?: "done"
 }
 
@@ -148,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",
 		})
@@ -168,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")
@@ -191,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>(
@@ -206,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}`,
 			})
@@ -234,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)
 	}
 }
 
@@ -277,6 +282,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 					const target: ClaimTarget = phaseId
 						? {
 								kind: "phase",
+								root,
 								taskId: task.id,
 								phaseId,
 								path: phase!.path,
@@ -284,6 +290,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 							}
 						: {
 								kind: "task",
+								root,
 								taskId: task.id,
 								path: task.path,
 								label: `task '${task.id}'`,
@@ -341,7 +348,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 
 			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
-					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+					if (
+						typeof input.pr === "string" &&
+						input.pr !== undefined &&
+						!PR_URL.test(input.pr)
+					) {
 						return yield* new ClaimError({
 							message: `Invalid GitHub pull request URL: ${input.pr}`,
 						})

package/src/services/ContextService.ts

@@ -3,9 +3,11 @@ import { Data, Effect, Either } from "effect"
 import { join, relative, resolve, sep } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
+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,
@@ -77,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 !== "..")
@@ -204,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>>
@@ -278,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,
 							})
@@ -302,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,
 								})
@@ -857,10 +856,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 									references: referenceCheckouts,
 									warnings: inspectionWarnings,
 								},
-						pr: {
-							url: executionData?.pr ?? null,
-							state: executionData?.pr ? "recorded" : "none",
-						},
+						pr: executionData?.pr
+							? normalizePullRequestRecord(executionData.pr)
+							: { url: null, state: "none" },
 						validation: {
 							valid: validation.valid,
 							warnings: validation.issues,

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",