@markjaquith/agency 2.48.1 → 2.50.0

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.test.ts

@@ -147,6 +147,65 @@ describe("claim service", () => {
 		})
 	})
 
+	test("finishes claimed non-PR work with durable completion evidence", async () => {
+		const initial = await inspect()
+		const acquired = await claim(initial.revision)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "single",
+							sessionId: "session-1",
+							revision: acquired.revision,
+							outcome: "done",
+							nonPrCompletion: {
+								summary: "Review completed; no code change was needed.",
+								evidenceUrl: "https://example.com/review",
+							},
+							now: at("2026-07-17T12:45:00.000Z"),
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		expect(finished.data).toMatchObject({
+			status: "done",
+			claim: { state: "finished", outcome: "done" },
+			completion: {
+				mode: "non-pr",
+				completedAt: "2026-07-17T12:45:00.000Z",
+				summary: "Review completed; no code change was needed.",
+				evidenceUrl: "https://example.com/review",
+			},
+		})
+	})
+
+	test("rejects invalid claimed non-PR completion", async () => {
+		const initial = await inspect()
+		const acquired = await claim(initial.revision)
+		await expect(
+			runTestEffect(
+				ClaimService.pipe(
+					Effect.flatMap((service) =>
+						service.finish(
+							{
+								taskId: "single",
+								sessionId: "session-1",
+								revision: acquired.revision,
+								outcome: "done",
+								nonPrCompletion: { summary: " " },
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("summary must not be empty")
+	})
+
 	test("returns structured ownership and revision conflicts", async () => {
 		const initial = await inspect()
 		const acquired = await claim(initial.revision)

package/src/services/ClaimService.ts

@@ -31,6 +31,10 @@ import {
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
+import {
+	buildNonPrCompletion,
+	type NonPrCompletionInput,
+} from "../workbase/completion"
 
 class ClaimError extends Data.TaggedError("ClaimError")<{
 	readonly message: string
@@ -83,6 +87,7 @@ interface OwnedClaimInput {
 
 interface FinishInput extends OwnedClaimInput {
 	readonly outcome: "done" | "dropped"
+	readonly nonPrCompletion?: NonPrCompletionInput
 }
 
 interface ExpireClaimInput {
@@ -103,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,
@@ -507,6 +513,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 			finish: (input: FinishInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					assertIdentity("Session ID", input.sessionId)
+					if (input.nonPrCompletion && input.outcome !== "done") {
+						return yield* new ClaimError({
+							message: "Non-PR completion is valid only with a done outcome",
+						})
+					}
 					const service = yield* ClaimService
 					const inspected = yield* service.inspect(
 						input.taskId,
@@ -531,6 +542,22 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 										message: `Session '${input.sessionId}' does not own ${inspected.target.label}`,
 									})
 								}
+								if (input.nonPrCompletion && "pr" in data && data.pr !== null) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message:
+											"Cannot complete without a pull request while an authoritative pull request is recorded",
+									})
+								}
+								const completionResult = input.nonPrCompletion
+									? buildNonPrCompletion(input.nonPrCompletion, now)
+									: undefined
+								if (completionResult && "error" in completionResult) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: completionResult.error,
+									})
+								}
 								const claim: ClaimRecord = {
 									...data.claim,
 									state: "finished",
@@ -540,8 +567,15 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 								return {
 									data: {
 										...data,
-										status: input.outcome === "done" ? "working" : "dropped",
+										status: completionResult
+											? "done"
+											: input.outcome === "done"
+												? "working"
+												: "dropped",
 										claim,
+										...(completionResult
+											? { completion: completionResult.value }
+											: {}),
 									},
 									claim,
 								}

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`,
@@ -374,6 +379,16 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Task '${id}' has an active claim; release or finish it before changing execution metadata`,
 						})
 					}
+					if (
+						updates.pr &&
+						"completion" in record.data &&
+						record.data.completion
+					) {
+						return yield* new GraphMutationError({
+							message:
+								"Reopen non-PR completed work before recording a pull request",
+						})
+					}
 					if (
 						executionChange &&
 						(yield* fs.isDirectory(join(dirname(record.path), "code")))
@@ -504,6 +519,12 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Phase '${id}' has an active claim; release or finish it before changing execution metadata`,
 						})
 					}
+					if (updates.pr && record.data.completion) {
+						return yield* new GraphMutationError({
+							message:
+								"Reopen non-PR completed work before recording a pull request",
+						})
+					}
 					const data: PhaseData = yield* decode(
 						PhaseFrontmatter,
 						{

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/IntegrationService.test.ts

@@ -261,7 +261,9 @@ describe("IntegrationService", () => {
 		expect(body).toContain("Only `done` satisfies a dependency")
 		expect(body).toContain("Require explicit user intent")
 		expect(body).toContain("changing repository")
-		expect(body).toMatch(/archiving, restoring,\s+dropping, or/)
+		expect(body).toMatch(
+			/archiving, restoring,\s+dropping, reopening, or completing work without a pull request/,
+		)
 		expect(body).toContain("Never invent entity IDs")
 		expect(body).toContain("Preserve parent backlinks")
 		expect(body).toContain("dirty-worktree, active-claim, revision")
@@ -281,6 +283,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("pausing or handing off")
 		expect(body).toContain("`agency finish`")
 		expect(body).toContain("`agency sync --apply`")
+		expect(body).toContain("`--no-pull-request --summary <text>`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		expect(body).toContain("PR state, current head, diff summary")
 		expect(body).toContain("Run `agency validate` before reporting completion")