@markjaquith/agency 2.49.0 → 2.50.0

package/src/graph-schema.ts

@@ -3,6 +3,8 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	PullRequestRecord,
+	ClaimRecord,
+	ReviewRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -69,13 +71,24 @@ const DocumentHash = Schema.Struct({ sha256: Schema.String })
 export const GraphEpicData = Schema.extend(EpicFrontmatter, DocumentHash)
 export const GraphTaskData = Schema.extend(TaskFrontmatter, DocumentHash)
 export const GraphPhaseData = Schema.extend(PhaseFrontmatter, DocumentHash)
-export const GraphExecutionData = Schema.extend(
-	PhaseFrontmatter,
+export const GraphExecutionData = Schema.Union(
+	Schema.extend(
+		PhaseFrontmatter,
+		Schema.Struct({
+			taskId: Schema.String,
+			phaseId: Schema.optional(Schema.String),
+			ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
+			epic: Schema.optional(Schema.String),
+		}),
+	),
 	Schema.Struct({
 		taskId: Schema.String,
-		phaseId: Schema.optional(Schema.String),
-		ticketUrl: Schema.optional(Schema.NullOr(Schema.String)),
+		ticketUrl: Schema.NullOr(Schema.String),
+		description: Schema.optional(Schema.String),
 		epic: Schema.optional(Schema.String),
+		review: ReviewRecord,
+		status: WorkStatus,
+		claim: Schema.optional(ClaimRecord),
 	}),
 )
 
@@ -98,15 +111,24 @@ export const GraphRepositoryGit = Schema.Struct({
 	head: Schema.NullOr(Schema.String),
 	branch: Schema.NullOr(Schema.String),
 })
-export const GraphExecutionGit = Schema.Struct({
-	branch: Schema.String,
-	base: Schema.String,
-	branchCommit: Schema.NullOr(Schema.String),
-	baseCommit: Schema.NullOr(Schema.String),
-	checkoutCommit: Schema.NullOr(Schema.String),
-	checkoutBranch: Schema.NullOr(Schema.String),
-	dirty: Schema.NullOr(Schema.Boolean),
-})
+export const GraphExecutionGit = Schema.Union(
+	Schema.Struct({
+		branch: Schema.String,
+		base: Schema.String,
+		branchCommit: Schema.NullOr(Schema.String),
+		baseCommit: Schema.NullOr(Schema.String),
+		checkoutCommit: Schema.NullOr(Schema.String),
+		checkoutBranch: Schema.NullOr(Schema.String),
+		dirty: Schema.NullOr(Schema.Boolean),
+	}),
+	Schema.Struct({
+		pinnedCommit: Schema.String,
+		sourceCommit: Schema.NullOr(Schema.String),
+		checkoutCommit: Schema.NullOr(Schema.String),
+		checkoutBranch: Schema.NullOr(Schema.String),
+		dirty: Schema.NullOr(Schema.Boolean),
+	}),
+)
 export const GraphPr = Schema.Union(
 	Schema.Struct({ url: Schema.Null, state: Schema.Literal("none") }),
 	Schema.Struct({ url: Schema.String, state: Schema.Literal("unavailable") }),

package/src/protocol.ts

@@ -100,6 +100,7 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },
+	ReviewError: { code: "REVIEW_ERROR", retryable: false },
 	ContextError: {
 		code: "CONTEXT_ERROR",
 		retryable: false,

package/src/services/ArchiveService.test.ts

@@ -315,7 +315,7 @@ describe("ArchiveService", () => {
 				),
 			),
 		)
-		await Bun.write(join(workspace.writablePath, "dirty.txt"), "keep me\n")
+		await Bun.write(join(workspace.writablePath!, "dirty.txt"), "keep me\n")
 
 		await expect(
 			runTestEffect(
@@ -747,7 +747,7 @@ describe("ArchiveService", () => {
 			),
 		).rejects.toThrow("Another archive or restore operation")
 		expect(
-			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
 		).toBe(true)
 		expect(await Bun.file(join(root, "tasks/locked/TASK.md")).exists()).toBe(
 			true,

package/src/services/ArchiveService.ts

@@ -367,6 +367,7 @@ const repositoriesFor = (record: ArchivedRecord) => {
 			...(record.data.repos ?? []).map((reference) => reference.repo),
 		]
 	}
+	if ("review" in record.data) return [record.data.review.repo]
 	return []
 }
 

package/src/services/ClaimService.ts

@@ -108,7 +108,8 @@ interface ReconcileInput {
 const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
 
 type SingleTaskData = Extract<TaskData, { readonly repo: string }>
-type ExecutionData = SingleTaskData | PhaseData
+type ReviewTaskData = Extract<TaskData, { readonly review: unknown }>
+type ExecutionData = SingleTaskData | ReviewTaskData | PhaseData
 
 const isTaggedClaimError = (
 	error: unknown,
@@ -541,7 +542,7 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 										message: `Session '${input.sessionId}' does not own ${inspected.target.label}`,
 									})
 								}
-								if (input.nonPrCompletion && data.pr !== null) {
+								if (input.nonPrCompletion && "pr" in data && data.pr !== null) {
 									throw new ClaimError({
 										target: inspected.target.label,
 										message:

package/src/services/ContextService.ts

@@ -54,6 +54,7 @@ interface CheckoutInspection {
 	readonly checkoutCommit: string | null
 	readonly checkoutBranch: string | null
 	readonly detached: boolean | null
+	readonly dirty: boolean | null
 }
 
 type ExecutionData = PhaseData & Partial<Pick<TaskData, "ticketUrl" | "epic">>
@@ -92,6 +93,18 @@ const runGit = (fs: FileSystemService, cwd: string, args: readonly string[]) =>
 		Effect.catchAll(() => Effect.succeed(null)),
 	)
 
+const runGitText = (
+	fs: FileSystemService,
+	cwd: string,
+	args: readonly string[],
+) =>
+	fs.runCommand(["git", "-C", cwd, ...args], { captureOutput: true }).pipe(
+		Effect.map((result) =>
+			result.exitCode === 0 ? result.stdout.trim() : null,
+		),
+		Effect.catchAll(() => Effect.succeed(null)),
+	)
+
 const worktreePaths = (output: string | null) =>
 	new Set(
 		(output ?? "")
@@ -765,9 +778,13 @@ export class ContextService extends Effect.Service<ContextService>()(
 						: task?.data && "repo" in task.data
 							? (task.data as ExecutionData)
 							: null
-					const references: readonly RepositoryReference[] = executionData
-						? (executionData.repos ?? [])
-						: (epic?.data.repos ?? [])
+					const reviewData =
+						task?.data && "review" in task.data ? task.data.review : null
+					const references: readonly RepositoryReference[] = reviewData
+						? [{ repo: reviewData.repo, ref: reviewData.commit }]
+						: executionData
+							? (executionData.repos ?? [])
+							: (epic?.data.repos ?? [])
 					const entityDirectory = target.path.replace(
 						/\/(?:EPIC|TASK|PHASE)\.md$/,
 						"",
@@ -812,6 +829,7 @@ export class ContextService extends Effect.Service<ContextService>()(
 									checkoutCommit: null,
 									checkoutBranch: null,
 									detached: null,
+									dirty: null,
 								}
 							}
 							const checkoutCommit = yield* runGit(fs, checkoutPath, [
@@ -824,6 +842,10 @@ export class ContextService extends Effect.Service<ContextService>()(
 								"--short",
 								"HEAD",
 							])
+							const checkoutStatus = yield* runGitText(fs, checkoutPath, [
+								"status",
+								"--porcelain",
+							])
 							const resolvedCheckoutPath = yield* fs.realPath(checkoutPath)
 							registered = registered || listedPaths.has(resolvedCheckoutPath)
 							if (checkoutCommit === null) {
@@ -837,6 +859,8 @@ export class ContextService extends Effect.Service<ContextService>()(
 								checkoutCommit,
 								checkoutBranch,
 								detached: checkoutBranch === null,
+								dirty:
+									checkoutStatus === null ? null : checkoutStatus.length > 0,
 							}
 						})
 
@@ -901,6 +925,17 @@ export class ContextService extends Effect.Service<ContextService>()(
 							...(yield* inspectCheckout(repositoryPath, checkoutPath)),
 						})
 					}
+					const reviewSourceCommit = reviewData
+						? yield* runGit(fs, join(root, "repos", reviewData.repo), [
+								"ls-remote",
+								"origin",
+								reviewData.source.kind === "pull-request"
+									? reviewData.source.fetchRef
+									: reviewData.source.ref
+											.replace(/^refs\/remotes\/origin\//, "")
+											.replace(/^origin\//, ""),
+							])
+						: null
 
 					const checkoutStates = [writable, ...referenceCheckouts].filter(
 						(value): value is NonNullable<typeof value> => value !== null,
@@ -956,7 +991,11 @@ export class ContextService extends Effect.Service<ContextService>()(
 							aggregate: aggregateProgress(aggregateStatuses),
 						},
 						authority: {
-							mode: executionData ? "execution" : "orchestration",
+							mode: reviewData
+								? "review"
+								: executionData
+									? "execution"
+									: "orchestration",
 							writable: writable
 								? {
 										repo: writable.repo,
@@ -972,6 +1011,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 								repositoryPath: reference.repositoryPath,
 								checkoutPath: reference.checkoutPath,
 							})),
+							documents: {
+								writable: reviewData && task ? [task.path] : [],
+							},
 						},
 						workspace: options.compact
 							? {
@@ -997,6 +1039,16 @@ export class ContextService extends Effect.Service<ContextService>()(
 									references: referenceCheckouts,
 									warnings: inspectionWarnings,
 								},
+						review: reviewData
+							? {
+									...reviewData,
+									sourceObservation: {
+										available: reviewSourceCommit !== null,
+										commit: reviewSourceCommit?.split(/\s+/)[0] ?? null,
+									},
+									checkout: referenceCheckouts[0] ?? null,
+								}
+							: null,
 						pr: executionData?.pr
 							? normalizePullRequestRecord(executionData.pr)
 							: { url: null, state: "none" },

package/src/services/DoctorService.ts

@@ -282,6 +282,8 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 					}
 
 					const refs = new Map<string, Set<string>>()
+					const reviewSources: { repo: string; task: string; ref: string }[] =
+						[]
 					const declareRef = (repo: string, ref: string) => {
 						const values = refs.get(repo) ?? new Set<string>()
 						values.add(ref)
@@ -293,7 +295,19 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 								declareRef(reference.repo, reference.ref)
 						}
 						for (const task of yield* tasks.list(root)) {
-							if ("repo" in task.data) {
+							if ("review" in task.data) {
+								declareRef(task.data.review.repo, task.data.review.commit)
+								reviewSources.push({
+									repo: task.data.review.repo,
+									task: task.id,
+									ref:
+										task.data.review.source.kind === "pull-request"
+											? task.data.review.source.fetchRef
+											: task.data.review.source.ref
+													.replace(/^refs\/remotes\/origin\//, "")
+													.replace(/^origin\//, ""),
+								})
+							} else if ("repo" in task.data) {
 								declareRef(task.data.repo, task.data.base)
 								for (const reference of task.data.repos ?? [])
 									declareRef(reference.repo, reference.ref)
@@ -357,6 +371,36 @@ export class DoctorService extends Effect.Service<DoctorService>()(
 						})
 						if (!repositoryValid) continue
 
+						for (const source of reviewSources.filter(
+							(item) => item.repo === repository.alias,
+						)) {
+							const observed = yield* fs.runCommand(
+								[
+									"git",
+									"-C",
+									repository.path,
+									"ls-remote",
+									"origin",
+									source.ref,
+								],
+								{ captureOutput: true },
+							)
+							const available =
+								observed.exitCode === 0 && Boolean(observed.stdout.trim())
+							add({
+								id: `review.${source.task}.source`,
+								category: "repository",
+								level: "warning",
+								status: available ? "pass" : "fail",
+								message: available
+									? `Review source '${source.ref}' is available for task '${source.task}'`
+									: `Review source '${source.ref}' is unavailable for task '${source.task}'; its pin remains usable`,
+								remediation: available
+									? undefined
+									: "Use the pinned checkout or refresh after restoring the source.",
+							})
+						}
+
 						for (const ref of [...(refs.get(repository.alias) ?? [])].sort()) {
 							const local = yield* fs.runCommand(
 								[

package/src/services/GraphMutationService.ts

@@ -360,6 +360,11 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						"base",
 						"pr",
 					].some((key) => updates[key as keyof TaskUpdates] !== undefined)
+					if ("review" in record.data && executionChange) {
+						return yield* new GraphMutationError({
+							message: `Review task '${id}' does not have writable execution metadata`,
+						})
+					}
 					if ("phases" in record.data && executionChange) {
 						return yield* new GraphMutationError({
 							message: `Task '${id}' has multiple phases; update execution metadata on a phase instead`,

package/src/services/GraphService.ts

@@ -54,7 +54,10 @@ interface RepositoryRecord {
 	readonly target: string | null
 }
 
-type ExecutionData = PhaseData | Extract<TaskData, { readonly repo: string }>
+type ExecutionData =
+	| PhaseData
+	| Extract<TaskData, { readonly repo: string }>
+	| Extract<TaskData, { readonly review: unknown }>
 
 export interface GraphOptions {
 	readonly cwd?: string
@@ -548,10 +551,18 @@ export class GraphService extends Effect.Service<GraphService>()(
 					const executionRepositories = (
 						data: TaskData | PhaseData,
 					): readonly string[] =>
-						"repo" in data
-							? [data.repo, ...(data.repos ?? []).map((item) => item.repo)]
-							: []
+						"review" in data
+							? [data.review.repo]
+							: "repo" in data
+								? [data.repo, ...(data.repos ?? []).map((item) => item.repo)]
+								: []
 					const executionEdges = (id: string, data: TaskData | PhaseData) => {
+						if ("review" in data) {
+							edges.push(
+								edge("references", id, repositoryNodeId(data.review.repo)),
+							)
+							return
+						}
 						if (!("repo" in data)) return
 						edges.push(edge("writes", id, repositoryNodeId(data.repo)))
 						for (const reference of data.repos ?? []) {
@@ -650,8 +661,9 @@ export class GraphService extends Effect.Service<GraphService>()(
 					const executionDetails = (entityPath: string, data: ExecutionData) =>
 						Effect.gen(function* () {
 							const directory = entityPath.replace(/\/(?:TASK|PHASE)\.md$/, "")
-							const checkoutPath = join(directory, "code", data.repo)
-							const repositoryPath = join(root, "repos", data.repo)
+							const repo = "review" in data ? data.review.repo : data.repo
+							const checkoutPath = join(directory, "code", repo)
+							const repositoryPath = join(root, "repos", repo)
 							const materialized = yield* fs.isDirectory(checkoutPath)
 							const result: {
 								workspace?: GraphExecutionWorkspace
@@ -666,58 +678,110 @@ export class GraphService extends Effect.Service<GraphService>()(
 								}
 							}
 							if (include.has("git")) {
-								result.git = {
-									branch: data.branch,
-									base: data.base,
-									branchCommit: yield* run(fs, [
-										"git",
-										"-C",
-										repositoryPath,
-										"rev-parse",
-										`${data.branch}^{commit}`,
-									]),
-									baseCommit: yield* run(fs, [
-										"git",
-										"-C",
-										repositoryPath,
-										"rev-parse",
-										`${data.base}^{commit}`,
-									]),
-									checkoutCommit: materialized
-										? yield* run(fs, [
-												"git",
-												"-C",
-												checkoutPath,
-												"rev-parse",
-												"HEAD",
-											])
-										: null,
-									checkoutBranch: materialized
-										? yield* run(fs, [
-												"git",
-												"-C",
-												checkoutPath,
-												"symbolic-ref",
-												"--quiet",
-												"--short",
-												"HEAD",
-											])
-										: null,
-									dirty: materialized
-										? ((status) =>
-												status === null ? null : status.length > 0)(
-												yield* runText(fs, [
+								result.git =
+									"review" in data
+										? {
+												pinnedCommit: data.review.commit,
+												sourceCommit: ((value) =>
+													value?.split(/\s+/)[0] ?? null)(
+													yield* run(fs, [
+														"git",
+														"-C",
+														repositoryPath,
+														"ls-remote",
+														"origin",
+														data.review.source.kind === "pull-request"
+															? data.review.source.fetchRef
+															: data.review.source.ref
+																	.replace(/^refs\/remotes\/origin\//, "")
+																	.replace(/^origin\//, ""),
+													]),
+												),
+												checkoutCommit: materialized
+													? yield* run(fs, [
+															"git",
+															"-C",
+															checkoutPath,
+															"rev-parse",
+															"HEAD",
+														])
+													: null,
+												checkoutBranch: materialized
+													? yield* run(fs, [
+															"git",
+															"-C",
+															checkoutPath,
+															"symbolic-ref",
+															"--quiet",
+															"--short",
+															"HEAD",
+														])
+													: null,
+												dirty: materialized
+													? ((status) =>
+															status === null ? null : status.length > 0)(
+															yield* runText(fs, [
+																"git",
+																"-C",
+																checkoutPath,
+																"status",
+																"--porcelain",
+															]),
+														)
+													: null,
+											}
+										: {
+												branch: data.branch,
+												base: data.base,
+												branchCommit: yield* run(fs, [
 													"git",
 													"-C",
-													checkoutPath,
-													"status",
-													"--porcelain",
+													repositoryPath,
+													"rev-parse",
+													`${data.branch}^{commit}`,
 												]),
-											)
-										: null,
-								}
+												baseCommit: yield* run(fs, [
+													"git",
+													"-C",
+													repositoryPath,
+													"rev-parse",
+													`${data.base}^{commit}`,
+												]),
+												checkoutCommit: materialized
+													? yield* run(fs, [
+															"git",
+															"-C",
+															checkoutPath,
+															"rev-parse",
+															"HEAD",
+														])
+													: null,
+												checkoutBranch: materialized
+													? yield* run(fs, [
+															"git",
+															"-C",
+															checkoutPath,
+															"symbolic-ref",
+															"--quiet",
+															"--short",
+															"HEAD",
+														])
+													: null,
+												dirty: materialized
+													? ((status) =>
+															status === null ? null : status.length > 0)(
+															yield* runText(fs, [
+																"git",
+																"-C",
+																checkoutPath,
+																"status",
+																"--porcelain",
+															]),
+														)
+													: null,
+											}
 							}
-							if (include.has("pr")) {
+							if (include.has("pr") && !("review" in data)) {
 								if (!data.pr) {
 									result.pr = { url: null, state: "none" }
 								} else {

package/src/services/PhaseService.ts

@@ -97,6 +97,11 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 					const taskId = yield* decodeId(input.taskId, "task")
 					const id = yield* decodeId(input.id, "phase")
 					const task = yield* tasks.show(taskId, root)
+					if ("review" in task.data) {
+						return yield* new PhaseError({
+							message: `Review task '${taskId}' cannot be converted to phases`,
+						})
+					}
 					const isMultiPhase = "phases" in task.data
 					let firstPhaseId: string | undefined
 					if (!isMultiPhase) {

package/src/services/PullRequestService.test.ts

@@ -353,7 +353,7 @@ process.exit(${exitCode})
 	test("blocks a dirty checkout before push or gh", async () => {
 		await createTask()
 		const workspace = await materialize()
-		await Bun.write(join(workspace.writablePath, "dirty.txt"), "dirty\n")
+		await Bun.write(join(workspace.writablePath!, "dirty.txt"), "dirty\n")
 		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/45" })
 
 		await expect(createPullRequest()).rejects.toThrow(
@@ -518,7 +518,7 @@ process.stdout.write(${JSON.stringify(JSON.stringify(providerRecord))})
 	test("reports git status failure before push or gh", async () => {
 		await createTask()
 		const workspace = await materialize()
-		await rm(join(workspace.writablePath, ".git"))
+		await rm(join(workspace.writablePath!, ".git"))
 		await writeFakeGh({ stdout: "https://github.com/example/agency/pull/48" })
 
 		await expect(createPullRequest()).rejects.toThrow(

package/src/services/PullRequestService.ts

@@ -50,6 +50,11 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const phases = yield* PhaseService
 					const root = yield* workbase.discover(startPath)
 					const task = yield* tasks.show(taskId, root)
+					if ("review" in task.data) {
+						return yield* new PullRequestError({
+							message: `Review task '${taskId}' cannot record a delivery pull request`,
+						})
+					}
 					const target =
 						"phases" in task.data
 							? phaseId
@@ -105,15 +110,20 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const worktrees = yield* WorktreeService
 					const readiness = yield* ReadinessService
 					const workbase = yield* WorkbaseService
-					const task = yield* tasks.show(taskId, startPath)
+					const requestedTask = yield* tasks.show(taskId, startPath)
+					if ("review" in requestedTask.data) {
+						return yield* new PullRequestError({
+							message: `Review task '${taskId}' cannot create a delivery pull request`,
+						})
+					}
 					const target =
-						"phases" in task.data
+						"phases" in requestedTask.data
 							? phaseId
 								? yield* phases.show(taskId, phaseId, startPath)
 								: yield* new PullRequestError({
 										message: `Task '${taskId}' requires a phase ID`,
 									})
-							: task
+							: requestedTask
 					if ("completion" in target.data && target.data.completion) {
 						return yield* new PullRequestError({
 							message:
@@ -134,11 +144,21 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						options,
 					)
 					const workspaceTask = yield* tasks.show(taskId, workspace.root)
+					if ("review" in workspaceTask.data) {
+						return yield* new PullRequestError({
+							message: `Review task '${taskId}' cannot create a delivery pull request`,
+						})
+					}
 					const execution =
 						"phases" in workspaceTask.data
 							? (yield* phases.show(taskId, phaseId!, workspace.root)).data
 							: workspaceTask.data
 					const { config } = yield* workbase.loadConfig(workspace.root)
+					if (!workspace.writablePath) {
+						return yield* new PullRequestError({
+							message: `Task '${taskId}' has no writable checkout`,
+						})
+					}
 					const remote = config.delivery?.remote ?? "origin"
 
 					const status = yield* fs.runCommand(

package/src/services/ReadinessService.ts

@@ -77,7 +77,7 @@ const itemFor = (
 			? task.data.epic
 			: undefined
 	const dependentIds = new Set(node.dependents)
-	if (node.data.phaseId) {
+	if ("phaseId" in node.data && node.data.phaseId) {
 		const siblings = graph.nodes.filter(
 			(candidate): candidate is ExecutionNode =>
 				candidate.kind === "execution-unit" &&
@@ -93,10 +93,14 @@ const itemFor = (
 		rank,
 		key: node.key,
 		taskId: node.data.taskId,
-		...(node.data.phaseId ? { phaseId: node.data.phaseId } : {}),
+		...("phaseId" in node.data && node.data.phaseId
+			? { phaseId: node.data.phaseId }
+			: {}),
 		...(node.data.description ? { description: node.data.description } : {}),
 		parent: {
-			...(node.data.phaseId ? { taskId: node.data.taskId } : {}),
+			...("phaseId" in node.data && node.data.phaseId
+				? { taskId: node.data.taskId }
+				: {}),
 			...(epicId ? { epicId } : {}),
 		},
 		status: node.status,