@markjaquith/agency 2.49.0 → 2.50.0

package/src/services/TaskService.ts

@@ -8,6 +8,7 @@ import {
 	EntityId,
 	TaskFrontmatter,
 	type RepositoryReference,
+	type ReviewRecord,
 	type TaskFrontmatter as TaskData,
 	WorkStatus,
 } from "../workbase/schemas"
@@ -26,6 +27,7 @@ import {
 import {
 	documentWriteStep,
 	runLifecycleTransaction,
+	type TransactionStep,
 } from "./LifecycleTransaction"
 
 class TaskError extends Data.TaggedError("TaskError")<{
@@ -50,6 +52,7 @@ export interface CreateTaskInput {
 	readonly repos?: readonly RepositoryReference[]
 	readonly branch?: string
 	readonly base?: string
+	readonly review?: ReviewRecord
 }
 
 const decodeTask = (input: unknown) => {
@@ -78,6 +81,50 @@ const decodeStatus = (status: string) => {
 		: Effect.succeed(result.right)
 }
 
+const reviewPinRef = (taskId: string) =>
+	`refs/agency/reviews/${Buffer.from(taskId).toString("hex")}`
+
+const reviewPinStep = (
+	root: string,
+	taskId: string,
+	review: ReviewRecord,
+): TransactionStep => {
+	const repositoryPath = join(root, "repos", review.repo)
+	const ref = reviewPinRef(taskId)
+	const run = async (args: readonly string[]) => {
+		const child = Bun.spawn([...args], { stdout: "pipe", stderr: "pipe" })
+		const [exitCode, stderr] = await Promise.all([
+			child.exited,
+			new Response(child.stderr).text(),
+		])
+		if (exitCode !== 0) throw new Error(stderr.trim() || args.join(" "))
+	}
+	return {
+		label: `retain review pin for ${taskId}`,
+		apply: () =>
+			run([
+				"git",
+				"-C",
+				repositoryPath,
+				"update-ref",
+				ref,
+				review.commit,
+				"0".repeat(40),
+			]),
+		rollback: () =>
+			run([
+				"git",
+				"-C",
+				repositoryPath,
+				"update-ref",
+				"-d",
+				ref,
+				review.commit,
+			]),
+		manualRecovery: `Delete ${ref} from repository '${review.repo}'`,
+	}
+}
+
 export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 	sync: () => ({
 		create: (input: CreateTaskInput, startPath: string = process.cwd()) =>
@@ -102,7 +149,28 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 
 				let data: TaskData
-				if (input.multiPhase) {
+				if (input.review) {
+					if (
+						input.multiPhase ||
+						input.repo !== undefined ||
+						input.repos !== undefined ||
+						input.branch !== undefined ||
+						input.base !== undefined
+					) {
+						return yield* new TaskError({
+							message:
+								"Review tasks cannot include writable or multi-phase fields",
+						})
+					}
+					data = yield* decodeTask({
+						ticketUrl: input.ticketUrl,
+						...(input.description !== undefined
+							? { description: input.description }
+							: {}),
+						...(input.epic ? { epic: input.epic } : {}),
+						review: input.review,
+					})
+				} else if (input.multiPhase) {
 					data = yield* decodeTask({
 						ticketUrl: input.ticketUrl,
 						...(input.description !== undefined
@@ -132,12 +200,14 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				}
 
 				const referencedRepos =
-					"repo" in data
-						? [
-								data.repo,
-								...(data.repos ?? []).map((reference) => reference.repo),
-							]
-						: []
+					"review" in data
+						? [data.review.repo]
+						: "repo" in data
+							? [
+									data.repo,
+									...(data.repos ?? []).map((reference) => reference.repo),
+								]
+							: []
 				if (new Set(referencedRepos).size !== referencedRepos.length) {
 					return yield* new TaskError({
 						message:
@@ -192,7 +262,10 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					preconditions: parentEpic
 						? [{ path: parentEpic.path, revision: parentEpic.revision }]
 						: [],
-					steps: [documentWriteStep(root, writes)],
+					steps: [
+						...(input.review ? [reviewPinStep(root, id, input.review)] : []),
+						documentWriteStep(root, writes),
+					],
 				})
 
 				return {
@@ -279,7 +352,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 						message: "Non-PR completion is valid only with a done status",
 					})
 				}
-				if (nonPrCompletion && record.data.pr !== null) {
+				if (nonPrCompletion && "pr" in record.data && record.data.pr !== null) {
 					return yield* new TaskError({
 						message:
 							"Cannot complete without a pull request while an authoritative pull request is recorded",

package/src/services/WorkbaseService.ts

@@ -712,7 +712,8 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 							)
 						}
 
-						const all = [writable, ...referenceAliases].filter(
+						const reviewAlias = "review" in data ? data.review.repo : undefined
+						const all = [writable, reviewAlias, ...referenceAliases].filter(
 							(alias): alias is string => alias !== undefined,
 						)
 						for (const alias of new Set(all)) {

package/src/services/WorktreeService.test.ts

@@ -81,13 +81,13 @@ describe("WorktreeService", () => {
 		)
 
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 		expect(
 			await Bun.file(join(workspace.codePath, "effect/README.md")).text(),
 		).toBe("example\n")
 		const branch = Bun.spawnSync(
-			["git", "-C", workspace.writablePath, "branch", "--show-current"],
+			["git", "-C", workspace.writablePath!, "branch", "--show-current"],
 			{ stdout: "pipe" },
 		)
 		expect(new TextDecoder().decode(branch.stdout).trim()).toBe("task/example")
@@ -272,7 +272,7 @@ describe("WorktreeService", () => {
 			),
 		)
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 	})
 
@@ -599,7 +599,7 @@ pr: null
 
 		expect(
 			await Bun.file(
-				join(originalWorkspace.writablePath, "README.md"),
+				join(originalWorkspace.writablePath!, "README.md"),
 			).exists(),
 		).toBe(false)
 		const movedWorkspace = await runTestEffect(
@@ -613,10 +613,10 @@ pr: null
 			join(root, "tasks/promoted/phases/implementation/code/agency"),
 		)
 		expect(
-			await Bun.file(join(movedWorkspace.writablePath, "README.md")).text(),
+			await Bun.file(join(movedWorkspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 		const status = Bun.spawnSync(
-			["git", "-C", movedWorkspace.writablePath, "status", "--porcelain"],
+			["git", "-C", movedWorkspace.writablePath!, "status", "--porcelain"],
 			{ stdout: "pipe", stderr: "pipe" },
 		)
 		expect(status.exitCode).toBe(0)
@@ -1072,7 +1072,7 @@ pr: null
 			),
 		)
 		await Bun.write(
-			join(workspace.writablePath, "uncommitted.txt"),
+			join(workspace.writablePath!, "uncommitted.txt"),
 			"keep me\n",
 		)
 
@@ -1084,7 +1084,7 @@ pr: null
 			),
 		).rejects.toThrow("Failed to remove worktree for 'agency'")
 		expect(
-			await Bun.file(join(workspace.writablePath, "uncommitted.txt")).text(),
+			await Bun.file(join(workspace.writablePath!, "uncommitted.txt")).text(),
 		).toBe("keep me\n")
 	})
 
@@ -1131,7 +1131,7 @@ pr: null
 			"--porcelain",
 		])
 		expect(new TextDecoder().decode(worktrees.stdout)).not.toContain(
-			workspace.writablePath,
+			workspace.writablePath!,
 		)
 		expect(
 			Bun.spawnSync([
@@ -1325,7 +1325,7 @@ pr: null
 			),
 		).rejects.toThrow("multiple Agency owners")
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1371,7 +1371,7 @@ pr: null
 			]),
 		)
 		expect(
-			await Bun.file(join(original.writablePath, "README.md")).exists(),
+			await Bun.file(join(original.writablePath!, "README.md")).exists(),
 		).toBe(true)
 
 		const rebuilt = await runTestEffect(
@@ -1383,7 +1383,7 @@ pr: null
 		)
 		expect(rebuilt.inspection.conflicts).toEqual([])
 		expect(
-			await Bun.file(join(original.writablePath, "README.md")).exists(),
+			await Bun.file(join(original.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1435,7 +1435,7 @@ pr: null
 			),
 		).rejects.toThrow("original worktrees were restored")
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 	})
 
@@ -1473,7 +1473,7 @@ pr: null
 			),
 		)
 		expect(plan.actions.join("\n")).toContain("worktree prune --expire now")
-		expect(plan.actions).toContain(`prepare ${workspace.writablePath}`)
+		expect(plan.actions).toContain(`prepare ${workspace.writablePath!}`)
 
 		const repaired = await runTestEffect(
 			WorktreeService.pipe(
@@ -1484,7 +1484,7 @@ pr: null
 		)
 		expect(repaired.inspection.conflicts).toEqual([])
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 		expect(
 			Bun.spawnSync([
@@ -1648,7 +1648,7 @@ pr: null
 			),
 		)
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).text(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).text(),
 		).toBe("example\n")
 	})
 })

package/src/services/WorktreeService.ts

@@ -43,7 +43,8 @@ interface ExecutionWorkspace {
 	readonly taskPath: string
 	readonly phasePath: string | null
 	readonly codePath: string
-	readonly writablePath: string
+	readonly writablePath: string | null
+	readonly reviewPath: string | null
 	readonly repo: string
 	readonly repos: readonly RepositoryReference[]
 	readonly dryRun: boolean
@@ -181,12 +182,14 @@ const inspectExecution = (
 		const root = yield* workbase.discover(startPath)
 		const task = yield* tasks.show(taskId, root)
 
-		let execution: {
-			repo: string
-			repos?: readonly RepositoryReference[]
-			branch: string
-			base: string
-		}
+		let execution:
+			| {
+					repo: string
+					repos?: readonly RepositoryReference[]
+					branch: string
+					base: string
+			  }
+			| { review: { repo: string; commit: string } }
 		let owner: WorktreeOwner
 		let codePath: string
 		if ("phases" in task.data) {
@@ -230,6 +233,7 @@ const inspectExecution = (
 					ownership.set(key, owners)
 				}
 			} else {
+				if (!("repo" in taskRecord.data)) continue
 				const key = `${taskRecord.data.repo}:${taskRecord.data.branch}`
 				const owners = ownership.get(key) ?? []
 				owners.push({
@@ -244,10 +248,13 @@ const inspectExecution = (
 		const declared: readonly (
 			| { readonly repo: string; readonly branch: string }
 			| RepositoryReference
-		)[] = [
-			{ repo: execution.repo, branch: execution.branch },
-			...(execution.repos ?? []),
-		]
+		)[] =
+			"review" in execution
+				? [{ repo: execution.review.repo, ref: execution.review.commit }]
+				: [
+						{ repo: execution.repo, branch: execution.branch },
+						...(execution.repos ?? []),
+					]
 		const checkouts: WorktreeCheckoutInspection[] = []
 		for (const checkout of declared) {
 			const repositoryPath = join(root, "repos", checkout.repo)
@@ -608,12 +615,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						}
 						const task = yield* tasks.show(taskId, root)
 
-						let execution: {
-							repo: string
-							repos?: readonly RepositoryReference[]
-							branch: string
-							base: string
-						}
+						let execution:
+							| {
+									repo: string
+									repos?: readonly RepositoryReference[]
+									branch: string
+									base: string
+							  }
+							| { review: { repo: string; commit: string } }
 						let phasePath: string | null = null
 						let codePath: string
 						if ("phases" in task.data) {
@@ -639,10 +648,19 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						const requestedCheckouts: readonly (
 							| { readonly repo: string; readonly branch: string }
 							| RepositoryReference
-						)[] = [
-							{ repo: execution.repo, branch: execution.branch },
-							...(execution.repos ?? []),
-						]
+						)[] =
+							"review" in execution
+								? [
+										{
+											repo: execution.review.repo,
+											ref: execution.review.commit,
+										},
+									]
+								: [
+										{ repo: execution.repo, branch: execution.branch },
+										...(execution.repos ?? []),
+									]
+						const executionBase = "base" in execution ? execution.base : ""
 						const canonicalCodePath = (yield* fs.exists(codePath))
 							? yield* fs.realPath(codePath)
 							: resolve(codePath)
@@ -732,7 +750,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repositoryPath,
 											"rev-parse",
 											"--verify",
-											`${execution.base}^{commit}`,
+											`${executionBase}^{commit}`,
 										],
 										{ captureOutput: true },
 									)
@@ -744,7 +762,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												repositoryPath,
 												"ls-remote",
 												"origin",
-												originRef(execution.base),
+												originRef(executionBase),
 											],
 											{ captureOutput: true },
 										)
@@ -753,7 +771,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											!remoteBase.stdout.trim()
 										) {
 											return yield* new WorktreeError({
-												message: `Base '${execution.base}' for repository '${alias}' does not resolve to a commit`,
+												message: `Base '${executionBase}' for repository '${alias}' does not resolve to a commit`,
 											})
 										}
 									}
@@ -764,7 +782,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repo: repositoryPath,
 											worktree: checkoutPath,
 											branch: checkout.branch,
-											base: execution.base,
+											base: executionBase,
 										})
 									} catch (cause) {
 										return yield* new WorktreeError({
@@ -991,7 +1009,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 											repo: repositoryPath,
 											worktree: checkoutPath,
 											branch: checkout.branch,
-											base: execution.base,
+											base: executionBase,
 										}
 										try {
 											args = expandWorktreeCreateCommand(
@@ -1026,7 +1044,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 												repositoryPath,
 												"branch",
 												checkout.branch,
-												execution.base,
+												executionBase,
 											]
 											operations.push({
 												action: "create-branch",
@@ -1085,7 +1103,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 													repositoryPath,
 													"rev-parse",
 													"--verify",
-													`${execution.base}^{commit}`,
+													`${executionBase}^{commit}`,
 												],
 												{ captureOutput: true },
 											)
@@ -1266,9 +1284,17 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								taskPath: task.path,
 								phasePath,
 								codePath,
-								writablePath: join(codePath, execution.repo),
-								repo: execution.repo,
-								repos: execution.repos ?? [],
+								writablePath:
+									"review" in execution ? null : join(codePath, execution.repo),
+								reviewPath:
+									"review" in execution
+										? join(codePath, execution.review.repo)
+										: null,
+								repo:
+									"review" in execution
+										? execution.review.repo
+										: execution.repo,
+								repos: "review" in execution ? [] : (execution.repos ?? []),
 								dryRun: options.dryRun === true,
 								checkouts: checkoutReports,
 								operations,
@@ -1412,11 +1438,13 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						}
 						const task = yield* tasks.show(taskId, root)
 
-						let execution: {
-							repo: string
-							repos?: readonly RepositoryReference[]
-							branch: string
-						}
+						let execution:
+							| {
+									repo: string
+									repos?: readonly RepositoryReference[]
+									branch: string
+							  }
+							| { review: { repo: string; commit: string } }
 						let codePath: string
 						if ("phases" in task.data) {
 							if (!phaseId) {
@@ -1450,10 +1478,18 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						const expectedCheckouts: readonly (
 							| { readonly repo: string; readonly branch: string }
 							| RepositoryReference
-						)[] = [
-							{ repo: execution.repo, branch: execution.branch },
-							...(execution.repos ?? []),
-						]
+						)[] =
+							"review" in execution
+								? [
+										{
+											repo: execution.review.repo,
+											ref: execution.review.commit,
+										},
+									]
+								: [
+										{ repo: execution.repo, branch: execution.branch },
+										...(execution.repos ?? []),
+									]
 						const expectedAliases = expectedCheckouts.map(({ repo }) => repo)
 						if (codeDirectoryExists) {
 							const unmanaged = (yield* fs.readDirectory(codePath)).filter(

package/src/test-utils.ts

@@ -20,6 +20,7 @@ import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
 import { GraphMutationService } from "./services/GraphMutationService"
 import { DoctorService } from "./services/DoctorService"
+import { ReviewService } from "./services/ReviewService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -44,6 +45,7 @@ const TestLayer = Layer.mergeAll(
 	ReadinessService.Default,
 	GraphMutationService.Default,
 	DoctorService.Default,
+	ReviewService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/work-view.ts

@@ -79,7 +79,11 @@ const rowFor = (
 	executions: readonly ExecutionNode[],
 ): WorkViewRow => {
 	const branches = [
-		...new Set(executions.map((execution) => execution.data.branch)),
+		...new Set(
+			executions.flatMap((execution) =>
+				"branch" in execution.data ? [execution.data.branch] : [],
+			),
+		),
 	]
 	const parent =
 		node.kind === "task"
@@ -105,16 +109,19 @@ const rowFor = (
 				: branches.length === 1
 					? branches[0]!
 					: "multiple",
-		pr: aggregateLabel(executions, (execution) => Boolean(execution.data.pr), [
-			"present",
-			"absent",
-		]),
+		pr: aggregateLabel(
+			executions,
+			(execution) => "pr" in execution.data && Boolean(execution.data.pr),
+			["present", "absent"],
+		),
 		worktree: aggregateLabel(
 			executions,
 			(execution) => execution.workspace?.materialized === true,
 			["materialized", "absent"],
 		),
-		hasPr: executions.some((execution) => Boolean(execution.data.pr)),
+		hasPr: executions.some(
+			(execution) => "pr" in execution.data && Boolean(execution.data.pr),
+		),
 	}
 }
 
@@ -213,6 +220,7 @@ export const getWorkViews = (options: WorkViewOptions = {}) =>
 				return executions.filter(
 					(execution) =>
 						execution.data.taskId === taskId &&
+						"phaseId" in execution.data &&
 						execution.data.phaseId === phaseId,
 				)
 			}

package/src/workbase/schemas.test.ts

@@ -64,6 +64,63 @@ describe("portable repository declarations", () => {
 })
 
 describe("body-of-work descriptions", () => {
+	test("decodes review tasks strictly and rejects writable execution fields", () => {
+		const review = {
+			ticketUrl: null,
+			review: {
+				repo: "agency",
+				source: { kind: "branch", ref: "refs/heads/feature/review" },
+				commit: "a".repeat(40),
+				refreshedAt: "2026-07-23T12:00:00.000Z",
+			},
+		}
+		expect(
+			Schema.decodeUnknownSync(TaskFrontmatter, { onExcessProperty: "error" })(
+				review,
+			),
+		).toMatchObject({ status: "open", review: review.review })
+		for (const field of ["repo", "repos", "branch", "base", "pr"]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter, {
+					onExcessProperty: "error",
+				})({ ...review, [field]: field === "repos" ? [] : "forbidden" }),
+			).toThrow()
+		}
+	})
+
+	test("rejects inconsistent pull request source provenance", () => {
+		const source = {
+			kind: "pull-request",
+			provider: "github",
+			repository: "owner/repo",
+			identifier: "42",
+			url: "https://github.com/owner/repo/pull/42",
+			fetchRef: "refs/pull/42/head",
+		}
+		const review = {
+			ticketUrl: null,
+			review: {
+				repo: "agency",
+				source,
+				commit: "a".repeat(40),
+				refreshedAt: "2026-07-23T12:00:00.000Z",
+			},
+		}
+		expect(Schema.decodeUnknownSync(TaskFrontmatter)(review)).toBeDefined()
+		for (const inconsistent of [
+			{ ...source, url: "https://github.com/owner/repo/pull/41" },
+			{ ...source, repository: "other/repo" },
+			{ ...source, fetchRef: "refs/pull/41/head" },
+		]) {
+			expect(() =>
+				Schema.decodeUnknownSync(TaskFrontmatter)({
+					...review,
+					review: { ...review.review, source: inconsistent },
+				}),
+			).toThrow()
+		}
+	})
+
 	test("accepts descriptions on epics, tasks, and phases", () => {
 		const epic = Schema.decodeUnknownSync(EpicFrontmatter)({
 			ticketUrl: "https://example.com/epic",