@markjaquith/agency 2.49.0 → 2.51.0

package/src/cli-parser.ts

@@ -82,6 +82,9 @@ const taskCreateOptions = {
 	branch: { type: "string" },
 	base: { type: "string" },
 	"multi-phase": { type: "boolean" },
+	review: { type: "string" },
+	"pull-request": { type: "string" },
+	ref: { type: "string" },
 } satisfies OptionConfig
 
 const phaseCreateOptions = {
@@ -393,7 +396,7 @@ const commands = {
 			},
 			create: {
 				usage:
-					"agency task create <id> (--repo <alias> | --multi-phase) [options]",
+					"agency task create <id> (--repo <alias> | --multi-phase | --review <alias> (--pull-request <value> | --ref <remote-ref>)) [options]",
 				minArgs: 1,
 				maxArgs: 1,
 				options: [
@@ -405,6 +408,9 @@ const commands = {
 					"branch",
 					"base",
 					"multi-phase",
+					"review",
+					"pull-request",
+					"ref",
 					"json",
 				],
 				repeatable: ["reference"],
@@ -760,6 +766,22 @@ const commands = {
 			},
 		},
 	},
+	review: {
+		usage: "agency review refresh <task-id> [--if-revision <hash>] [--json]",
+		options: {
+			...outputOptions,
+			"if-revision": { type: "string" },
+		},
+		subcommands: {
+			refresh: {
+				usage:
+					"agency review refresh <task-id> [--if-revision <hash>] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["if-revision", "json"],
+			},
+		},
+	},
 	worktree: {
 		usage: "agency worktree <list|inspect|prepare|remove|rebuild|repair>",
 		options: {
@@ -810,6 +832,29 @@ const commands = {
 			},
 		},
 	},
+	vcs: {
+		usage: "agency vcs <status|migrate>",
+		options: {
+			...outputOptions,
+			apply: { type: "boolean" },
+			"dry-run": { type: "boolean" },
+		},
+		subcommands: {
+			status: {
+				usage: "agency vcs status [--json]",
+				minArgs: 0,
+				maxArgs: 0,
+				options: ["json"],
+			},
+			migrate: {
+				usage: "agency vcs migrate <git|jj> [--dry-run | --apply] [--json]",
+				minArgs: 1,
+				maxArgs: 1,
+				options: ["apply", "dry-run", "json"],
+				conflicts: [["apply", "dry-run"]],
+			},
+		},
+	},
 	work: {
 		usage:
 			"agency work [<directory-or-task-id> | --epic <epic-id>] [--runner <name>] [--auto] | agency work prepare [target] [--dry-run] [--json]",
@@ -1161,6 +1206,38 @@ function validateTaskCreate(
 	spec: LeafCommand,
 	requireRepo: boolean,
 ) {
+	const review = values.review !== undefined
+	const pullRequest = values["pull-request"] !== undefined
+	const ref = values.ref !== undefined
+	if (review) {
+		if (pullRequest === ref) {
+			throw usageError(
+				"Option '--review' requires exactly one of '--pull-request' or '--ref'.",
+				spec.usage,
+			)
+		}
+		for (const option of [
+			"repo",
+			"reference",
+			"branch",
+			"base",
+			"multi-phase",
+		] as const) {
+			if (values[option] !== undefined) {
+				throw usageError(
+					`Option '--review' cannot be combined with '${optionLabel(option)}'.`,
+					spec.usage,
+				)
+			}
+		}
+		return
+	}
+	if (pullRequest || ref) {
+		throw usageError(
+			`Option '${pullRequest ? "--pull-request" : "--ref"}' requires '--review'.`,
+			spec.usage,
+		)
+	}
 	if (values["multi-phase"]) {
 		for (const option of ["repo", "reference", "branch", "base"] as const) {
 			if (values[option] !== undefined) {

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
-import { access, mkdir, realpath, symlink } from "node:fs/promises"
+import { access, mkdir, realpath, stat, symlink } from "node:fs/promises"
 import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
@@ -1762,9 +1762,9 @@ status: open
 				alias: "agency",
 				status: "applied",
 			})
-			expect(await Bun.file(join(restored, "repos/agency/HEAD")).exists()).toBe(
-				true,
-			)
+			expect(
+				(await stat(join(restored, "repos/agency/.jj"))).isDirectory(),
+			).toBe(true)
 
 			const prepared = parseJson(
 				await runCli(["work", "prepare", "portable", "--json"], restored),

package/src/commands/init.test.ts

@@ -8,6 +8,7 @@ import {
 	runTestEffect,
 } from "../test-utils"
 import { init } from "./init"
+import { preferredVersionControl } from "../workbase/version-control"
 
 describe("init command", () => {
 	let parent: string
@@ -26,6 +27,7 @@ describe("init command", () => {
 
 		expect(await Bun.file(join(root, "agency.json")).json()).toEqual({
 			version: 2,
+			vcs: preferredVersionControl(),
 		})
 		for (const directory of ["repos", "epics", "tasks"]) {
 			expect((await stat(join(root, directory))).isDirectory()).toBe(true)

package/src/commands/review.ts

@@ -0,0 +1,38 @@
+import { Effect } from "effect"
+import { ReviewService } from "../services/ReviewService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface ReviewOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly taskId?: string
+	readonly ifRevision?: string
+	readonly json?: boolean
+}
+
+export const review = (options: ReviewOptions) =>
+	Effect.gen(function* () {
+		if (options.subcommand !== "refresh" || !options.taskId) {
+			return yield* Effect.fail(
+				new Error("Usage: agency review refresh <task>"),
+			)
+		}
+		const result = yield* (yield* ReviewService).refresh(
+			options.taskId,
+			options.cwd,
+			options.ifRevision,
+		)
+		const { log } = createLoggers(options)
+		log(
+			options.json
+				? JSON.stringify(result, null, 2)
+				: `Refreshed review '${options.taskId}' at ${result.commit}`,
+		)
+	})
+
+export const help = `
+Usage: agency review refresh <task-id> [--if-revision <hash>] [--json]
+
+Fetch the review source explicitly and replace the pinned commit and any clean,
+detached review checkout. Review sources never move implicitly.
+`

package/src/commands/task.ts

@@ -11,6 +11,7 @@ import { formatTable } from "../utils/table"
 import { getWorkViews } from "../work-view"
 import { GraphMutationService } from "../services/GraphMutationService"
 import { work as startWork, type StartWork } from "./work"
+import { ReviewService } from "../services/ReviewService"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -30,6 +31,9 @@ interface TaskOptions extends BaseCommandOptions {
 	readonly ifRevision?: string
 	readonly noEpic?: boolean
 	readonly multiPhase?: boolean
+	readonly review?: string
+	readonly pullRequest?: string
+	readonly ref?: string
 	readonly json?: boolean
 	readonly statuses?: readonly string[]
 	readonly repositories?: readonly string[]
@@ -85,6 +89,7 @@ export const task = (
 		const repositories = yield* RepositoryService
 		const workbase = yield* WorkbaseService
 		const mutations = yield* GraphMutationService
+		const reviews = yield* ReviewService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 
@@ -211,11 +216,18 @@ export const task = (
 					return yield* Effect.fail(new Error("Task ID is required"))
 				}
 				const multiPhase = options.multiPhase ?? false
-				if (!multiPhase && !options.repo) {
+				if (!multiPhase && !options.repo && !options.review) {
 					return yield* Effect.fail(
 						new Error("Writable repository is required for task create"),
 					)
 				}
+				const review = options.review
+					? yield* reviews.resolve(
+							options.review,
+							{ pullRequest: options.pullRequest, ref: options.ref },
+							cwd,
+						)
+					: undefined
 				const record = yield* tasks.create(
 					{
 						id,
@@ -223,10 +235,16 @@ export const task = (
 						description: options.description?.trim() || undefined,
 						epic: options.epic,
 						multiPhase,
+						review,
 						repo: options.repo,
-						repos: parseRepositoryReferences(options.references),
-						branch: multiPhase ? undefined : (options.branch ?? `task/${id}`),
-						base: multiPhase ? undefined : (options.base ?? "main"),
+						repos: review
+							? undefined
+							: parseRepositoryReferences(options.references),
+						branch:
+							multiPhase || review
+								? undefined
+								: (options.branch ?? `task/${id}`),
+						base: multiPhase || review ? undefined : (options.base ?? "main"),
 					},
 					cwd,
 				)
@@ -462,7 +480,11 @@ Create options:
                         Read-only repository reference; repeatable
   --branch <name>       Working branch (default: task/<id>)
   --base <name>         Base branch (default: main)
-  --multi-phase         Create a task container for phases
+	--multi-phase         Create a task container for phases
+	--review <alias>      Create a pinned read-only review task
+	--pull-request <url-or-number>
+	                       Review a GitHub pull request from the alias origin
+	--ref <remote-ref>    Review a branch or other fetchable origin ref
   --work                Start work on the new task after creating it
   --auto                Pass --auto to work; requires --work
 

package/src/commands/vcs.test.ts

@@ -0,0 +1,75 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { vcs } from "./vcs"
+
+describe("vcs command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(
+			`${root}/agency.json`,
+			JSON.stringify({ version: 2, vcs: "git" }),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("reports structured backend status", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(vcs({ subcommand: "status", cwd: root, json: true })),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			root,
+			configured: "git",
+			source: "git",
+			target: "git",
+			workspaceCount: 0,
+			blockers: [],
+		})
+	})
+
+	test("persists the inferred Git backend for a legacy workbase", async () => {
+		await Bun.write(`${root}/agency.json`, JSON.stringify({ version: 2 }))
+		await captureLogs(() =>
+			runTestEffect(
+				vcs({
+					subcommand: "migrate",
+					target: "git",
+					cwd: root,
+					apply: true,
+					json: true,
+				}),
+			),
+		)
+		expect(await Bun.file(`${root}/agency.json`).json()).toEqual({
+			version: 2,
+			vcs: "git",
+		})
+	})
+
+	test("treats migration to the configured backend as a no-op", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(
+				vcs({
+					subcommand: "migrate",
+					target: "git",
+					cwd: root,
+					apply: true,
+					json: true,
+				}),
+			),
+		)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			source: "git",
+			target: "git",
+			mode: "apply",
+			actions: [],
+		})
+	})
+})

package/src/commands/vcs.ts

@@ -0,0 +1,72 @@
+import { Effect } from "effect"
+import { VcsMigrationService } from "../services/VcsMigrationService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface VcsOptions extends BaseCommandOptions {
+	readonly subcommand?: string
+	readonly target?: string
+	readonly apply?: boolean
+}
+
+export const vcs = (options: VcsOptions = {}) =>
+	Effect.gen(function* () {
+		const migrations = yield* VcsMigrationService
+		const { log } = createLoggers(options)
+		const root = options.cwd ?? process.cwd()
+		if (options.subcommand === "status") {
+			const status = yield* migrations.status(root)
+			if (options.json) return log(JSON.stringify(status, null, 2))
+			log(
+				`Version control: ${status.source}${status.configured ? "" : " (inferred for legacy workbase)"}`,
+			)
+			log(
+				`Tools: git=${status.available.git ? "available" : "missing"} jj=${status.available.jj ? "available" : "missing"}`,
+			)
+			log(
+				`Repositories: ${status.repositories.length}; managed workspaces: ${status.workspaceCount}; blockers: ${status.blockers.length}`,
+			)
+			for (const blocker of status.blockers)
+				log(`blocker ${blocker.kind} ${blocker.target}: ${blocker.message}`)
+			return
+		}
+		if (options.subcommand === "migrate") {
+			if (options.target !== "git" && options.target !== "jj") {
+				return yield* Effect.fail(
+					new Error("VCS migration target must be 'git' or 'jj'"),
+				)
+			}
+			const result = yield* migrations.migrate(options.target, root, {
+				apply: options.apply,
+			})
+			if (options.json) return log(JSON.stringify(result, null, 2))
+			log(
+				result.mode === "apply"
+					? `Migrated workbase to ${options.target}`
+					: `Migration plan: ${result.source} -> ${options.target}`,
+			)
+			for (const action of result.actions) log(`- ${action}`)
+			if (result.mode === "dry-run" && result.actions.length > 0)
+				log("Run again with --apply to perform the migration.")
+			return
+		}
+		return yield* Effect.fail(
+			new Error(`Unknown vcs subcommand '${options.subcommand ?? ""}'`),
+		)
+	})
+
+export const help = `
+Usage: agency vcs <status|migrate>
+
+Inspect or migrate the workbase-wide version-control backend.
+
+Commands:
+  status                         Show the configured backend, tools, repositories, and blockers
+  migrate <git|jj> [--dry-run | --apply]
+                                 Preview or apply a clean, transactional backend migration
+
+Options:
+  --apply              Apply the migration; omission performs a dry run
+  --dry-run            Explicitly preview the migration without applying it
+  --json               Print structured output
+`

package/src/commands/work.test.ts

@@ -24,6 +24,7 @@ const singlePhaseWorkspace: ExecutionWorkspace = {
 	phasePath: null,
 	codePath: "/workbase/tasks/example/code",
 	writablePath: "/workbase/tasks/example/code/agency",
+	reviewPath: null,
 	repo: "agency",
 	repos: [],
 	dryRun: false,
@@ -37,6 +38,7 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 	phasePath: "/workbase/tasks/example/phases/implementation/PHASE.md",
 	codePath: "/workbase/tasks/example/phases/implementation/code",
 	writablePath: "/workbase/tasks/example/phases/implementation/code/agency",
+	reviewPath: null,
 	repo: "agency",
 	repos: [],
 	dryRun: false,

package/src/commands/work.ts

@@ -262,7 +262,7 @@ export const work = (
 				? `${action} the task. Read ${workspace.taskPath} and ${workspace.phasePath}.`
 				: `${action} the task. Read ${workspace.taskPath}.`
 			launchPath = dirname(workspace.phasePath ?? workspace.taskPath)
-			writablePath = workspace.writablePath
+			writablePath = workspace.writablePath ?? undefined
 		}
 
 		const explicitlyRequested = Boolean(
@@ -468,7 +468,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 			log(JSON.stringify(workspace, null, 2))
 		} else {
 			log(
-				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath}`,
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath ?? workspace.reviewPath}`,
 			)
 		}
 	})

package/src/commands/worktree.ts

@@ -120,7 +120,7 @@ export const worktree = (options: WorktreeOptions = {}) =>
 export const help = `
 Usage: agency worktree <list|inspect|prepare|remove|rebuild|repair>
 
-Inspect and maintain Agency-managed writable and reference worktrees.
+Inspect and maintain Agency-managed writable and reference workspaces.
 
 Commands:
   list                              List every managed checkout

package/src/graph-schema.test.ts

@@ -64,7 +64,7 @@ describe("graph contract", () => {
 		]
 		const graph = {
 			version: 1,
-			workbase: { version: 2 },
+			workbase: { version: 2, vcs: "git" },
 			filters: {
 				ready: null,
 				blocked: null,

package/src/graph-schema.ts

@@ -3,6 +3,8 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	PullRequestRecord,
+	ClaimRecord,
+	ReviewRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -54,6 +56,7 @@ export const GraphReadiness = Schema.Struct({
 
 export const GraphWorkbase = Schema.Struct({
 	version: Schema.Literal(2),
+	vcs: Schema.optional(Schema.Literal("git", "jj")),
 	root: Schema.optional(Schema.String),
 })
 
@@ -69,13 +72,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 +112,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

@@ -11,6 +11,11 @@ import {
 	WorktreeService,
 	type WorktreeRemovalSnapshot,
 } from "./WorktreeService"
+import {
+	GitVersionControlService,
+	JjVersionControlService,
+	VersionControlService,
+} from "./VersionControlService"
 import {
 	formatMarkdownDocument,
 	parseFrontmatter,
@@ -268,6 +273,9 @@ const applyMutation = (moves: readonly Move[], writes: readonly Write[]) =>
 const WorktreeLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,
+	GitVersionControlService.Default,
+	JjVersionControlService.Default,
+	VersionControlService.Default,
 	TaskService.Default,
 	PhaseService.Default,
 	WorktreeService.Default,
@@ -298,6 +306,21 @@ const restoreWorktreeSnapshots = async (
 			continue
 		} catch {}
 		await mkdir(dirname(snapshot.path), { recursive: true })
+		if (snapshot.vcs === "jj") {
+			await runGit([
+				"jj",
+				"-R",
+				snapshot.repositoryPath,
+				"workspace",
+				"add",
+				"--name",
+				snapshot.workspaceName!,
+				"-r",
+				snapshot.head,
+				snapshot.path,
+			])
+			continue
+		}
 		await runGit(
 			snapshot.branch
 				? [
@@ -367,6 +390,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: