@markjaquith/agency 2.14.0 → 2.16.0

package/README.md

@@ -11,7 +11,6 @@ or write.
 - Git
 - [GitHub CLI](https://cli.github.com/) for `agency pr create`
 - OpenCode or Claude Code for `agency work`
-- [fzf](https://github.com/junegunn/fzf) for interactive work target selection
 
 ## Installation
 
@@ -146,6 +145,29 @@ The configured command applies only to the writable checkout. Supplemental
 read-only repositories remain detached Git worktrees at their declared refs so
 they do not acquire writable branches.
 
+### Custom Chooser Command
+
+Interactive selection uses a native numbered chooser by default. To use an
+external chooser, configure an argv command in `agency.json`:
+
+```json
+{
+	"version": 2,
+	"chooserCommand": ["fzf", "--ansi", "--delimiter=\\t", "--with-nth=2.."]
+}
+```
+
+Agency writes one `key<TAB>label` record per choice to the command's stdin. The
+command must write the selected opaque key or selected record to stdout; commands
+such as `["gum", "filter"]` therefore work without wrappers. Exit codes 1 and
+130, empty stdout, native `q`, and an empty native response cancel selection.
+Other nonzero exits, unknown keys, and invalid native numbers are errors.
+
+Selectors are opened only when stdin and stderr are terminals and neither
+`--no-input` nor JSON output is active. Labels use color only when stderr is a
+terminal, `TERM` is not `dumb`, and `NO_COLOR` is unset; otherwise selectors use
+plain labels without ANSI styling or icon-font dependencies.
+
 ## Frontmatter
 
 ### Epic
@@ -282,6 +304,25 @@ inspection are opt-in include layers.
 `end` record with counts. Combining the metadata with the streamed node and edge
 records reconstructs the same result as `--json`.
 
+### Reconciliation
+
+`agency sync` compares every execution declaration with local branch and worktree
+registration, writable and reference checkout dirtiness, resolved reference
+commits, claim expiry, and GitHub pull request and merge state. It reports
+structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
+default and `--dry-run` modes are observational.
+
+`agency sync --apply` performs only these safe transitions:
+
+- materialize missing checkouts when no registration, branch, or path conflicts;
+- release an active claim only after its declared expiry has passed;
+- record a single PR whose head and base match the declaration; and
+- mark work done after its authoritative PR is merged and no active claim remains.
+
+Apply never modifies dirty checkouts, moves worktrees, switches branches, resets
+reference commits, chooses among multiple PRs, or bypasses active claims. Those
+conditions remain visible in `warnings` or `unresolved` with a suggested action.
+
 ### Workbase and Repositories
 
 ```text
@@ -302,7 +343,7 @@ repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
-status, validation, graph export, and PR creation.
+status, validation, graph export, reconciliation, and PR creation.
 
 ### Epics
 

package/cli.ts

@@ -10,6 +10,7 @@ import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
 import { graph, help as graphHelp } from "./src/commands/graph"
+import { sync, help as syncHelp } from "./src/commands/sync"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
@@ -33,6 +34,7 @@ import { IntegrationService } from "./src/services/IntegrationService"
 import { ContextService } from "./src/services/ContextService"
 import { GraphService } from "./src/services/GraphService"
 import { ClaimService } from "./src/services/ClaimService"
+import { SyncService } from "./src/services/SyncService"
 import {
 	claimCommand,
 	claimHelp,
@@ -61,6 +63,7 @@ const CliLayer = Layer.mergeAll(
 	ContextService.Default,
 	GraphService.Default,
 	ClaimService.Default,
+	SyncService.Default,
 )
 
 /**
@@ -424,6 +427,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	sync: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(syncHelp)
+				return
+			}
+			await runCommand(
+				sync({
+					apply: options.apply,
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -450,6 +470,7 @@ Commands:
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph
+  sync                   Reconcile declarations with external state
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/src/cli-parser.test.ts

@@ -141,6 +141,7 @@ describe("strict CLI parsing", () => {
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
+			[["sync", "extra"], "agency sync"],
 			[
 				[
 					"claim",
@@ -191,6 +192,20 @@ describe("strict CLI parsing", () => {
 		}
 	})
 
+	test("parses reconciliation modes and rejects conflicting modes", () => {
+		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
+			commandName: "sync",
+			values: { "dry-run": true, json: true },
+		})
+		expect(parseCli(["sync", "--apply"])).toMatchObject({
+			commandName: "sync",
+			values: { apply: true },
+		})
+		expect(() => parseCli(["sync", "--dry-run", "--apply"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("validates revision-guarded claim operations", () => {
 		const revision = "0".repeat(64)
 		expect(

package/src/cli-parser.ts

@@ -319,6 +319,21 @@ const commands = {
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
+	sync: {
+		usage: "agency sync [--dry-run | --apply] [--json]",
+		options: {
+			...outputOptions,
+			"dry-run": { type: "boolean" },
+			apply: { type: "boolean" },
+		},
+		command: {
+			usage: "agency sync [--dry-run | --apply] [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["dry-run", "apply", "json"],
+			conflicts: [["dry-run", "apply"]],
+		},
+	},
 	archive: {
 		usage: "agency archive <epic|task|phase>",
 		options: outputOptions,

package/src/commands/sync.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect"
+import { SyncService } from "../services/SyncService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface SyncCommandOptions extends BaseCommandOptions {
+	readonly apply?: boolean
+	readonly dryRun?: boolean
+}
+
+export const sync = (options: SyncCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* SyncService
+		const { log } = createLoggers(options)
+		const result = yield* service.reconcile({
+			cwd: options.cwd,
+			apply: options.apply === true,
+		})
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency sync [--dry-run | --apply] [--json]
+
+Compare declared execution state with Git worktrees, branches, references, claims,
+and GitHub pull requests. Dry-run is the default.
+
+Options:
+  --dry-run                 Report planned safe transitions without changing state
+  --apply                   Apply safe reconciliation transitions
+  --json                    Output one versioned machine result
+
+Apply may materialize unambiguous missing checkouts, release expired claims,
+record a uniquely matched PR, and mark merged work done. Dirty, stale, or
+conflicting checkouts are always left unresolved.
+`

package/src/commands/task.ts

@@ -6,6 +6,8 @@ import { EpicService } from "../services/EpicService"
 import { RepositoryService } from "../services/RepositoryService"
 import { createLoggers } from "../utils/effect"
 import { parseRepositoryReferences } from "../workbase/repository-reference"
+import { WorkbaseService } from "../services/WorkbaseService"
+import { choose } from "../utils/chooser"
 
 interface TaskOptions extends BaseCommandOptions {
 	readonly subcommand?: string
@@ -29,7 +31,9 @@ export interface TaskInteraction {
 	) => Effect.Effect<string | null, Error>
 }
 
-const defaultInteraction: TaskInteraction = {
+const defaultInteraction = (
+	chooserCommand?: readonly string[],
+): TaskInteraction => ({
 	text: (prompt) =>
 		Effect.tryPromise({
 			try: async () => {
@@ -46,37 +50,23 @@ const defaultInteraction: TaskInteraction = {
 			catch: (cause) => new Error("Failed to read task input", { cause }),
 		}),
 	select: (prompt, choices) =>
-		Effect.tryPromise({
-			try: async () => {
-				const process = Bun.spawn(
-					["fzf", `--prompt=${prompt}> `, "--height=~40%", "--reverse"],
-					{
-						stdin: new Blob([choices.join("\n")]),
-						stdout: "pipe",
-						stderr: "inherit",
-					},
-				)
-				const [exitCode, output] = await Promise.all([
-					process.exited,
-					new Response(process.stdout).text(),
-				])
-				if (exitCode === 1 || exitCode === 130) return null
-				if (exitCode !== 0) throw new Error(`fzf exited with code ${exitCode}`)
-				return output.trim() || null
-			},
-			catch: (cause) =>
-				new Error("Failed to select task input with fzf", { cause }),
-		}),
-}
+		choose(
+			prompt,
+			choices.map((choice, index) => ({
+				key: String(index),
+				label: choice,
+				value: choice,
+			})),
+			chooserCommand,
+		),
+})
 
-export const task = (
-	options: TaskOptions,
-	interaction: TaskInteraction = defaultInteraction,
-) =>
+export const task = (options: TaskOptions, interaction?: TaskInteraction) =>
 	Effect.gen(function* () {
 		const tasks = yield* TaskService
 		const epics = yield* EpicService
 		const repositories = yield* RepositoryService
+		const workbase = yield* WorkbaseService
 		const { log } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 
@@ -89,8 +79,13 @@ export const task = (
 						),
 					)
 				}
+				const activeInteraction =
+					interaction ??
+					defaultInteraction(
+						(yield* workbase.loadConfig(cwd)).config.chooserCommand,
+					)
 				const id =
-					options.args[0] ?? (yield* interaction.text("Task ID: ")).trim()
+					options.args[0] ?? (yield* activeInteraction.text("Task ID: ")).trim()
 				if (!id) {
 					return yield* Effect.fail(new Error("Task ID is required"))
 				}
@@ -103,18 +98,20 @@ export const task = (
 
 				if (options.ticketUrl === undefined) {
 					ticketUrl =
-						(yield* interaction.text("Ticket URL (optional): ")).trim() || null
+						(yield* activeInteraction.text("Ticket URL (optional): ")).trim() ||
+						null
 				}
 				if (options.description === undefined) {
 					description =
-						(yield* interaction.text("Description (optional): ")).trim() ||
-						undefined
+						(yield* activeInteraction.text(
+							"Description (optional): ",
+						)).trim() || undefined
 				}
 				if (options.epic === undefined) {
 					const epicRecords = yield* epics.list(cwd)
 					if (epicRecords.length > 0) {
 						const none = "(none)"
-						const selected = yield* interaction.select("Parent epic", [
+						const selected = yield* activeInteraction.select("Parent epic", [
 							none,
 							...epicRecords.map((record) => record.id),
 						])
@@ -125,7 +122,7 @@ export const task = (
 					}
 				}
 				if (options.multiPhase === undefined) {
-					const selected = yield* interaction.select("Task type", [
+					const selected = yield* activeInteraction.select("Task type", [
 						"single-phase",
 						"multi-phase",
 					])
@@ -144,7 +141,7 @@ export const task = (
 							),
 						)
 					}
-					const selected = yield* interaction.select(
+					const selected = yield* activeInteraction.select(
 						"Writable repository",
 						records.map((record) => record.alias),
 					)

package/src/commands/validate.ts

@@ -32,12 +32,7 @@ export const validate = (
 		const startPath = options.path ?? options.cwd ?? process.cwd()
 		const root = options.path
 			? yield* workbase.discover(startPath)
-			: yield* resolveWorkbase(
-					startPath,
-					log,
-					pick,
-					options.inputAllowed ?? true,
-				)
+			: yield* resolveWorkbase(startPath, pick, options.inputAllowed ?? true)
 		if (!root) return
 		const report = yield* workbase.validate(root)
 

package/src/commands/work.test.ts

@@ -46,7 +46,8 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 interface HarnessOptions {
 	readonly workspace?: ExecutionWorkspace
 	readonly materializeError?: Error
-	readonly available?: Partial<Record<"opencode" | "claude" | "fzf", boolean>>
+	readonly available?: Partial<Record<"opencode" | "claude", boolean>>
+	readonly chooserCommand?: readonly string[]
 	readonly multiPhaseTasks?: readonly string[]
 	readonly epicRecords?: readonly any[]
 	readonly taskRecords?: readonly any[]
@@ -93,6 +94,14 @@ const createHarness = (options: HarnessOptions = {}) => {
 					})
 				: Effect.succeed("/workbase"),
 		listRegistered: () => Effect.succeed(options.registeredWorkbases ?? []),
+		loadConfig: () =>
+			Effect.succeed({
+				root: "/workbase",
+				config: {
+					version: 2 as const,
+					chooserCommand: options.chooserCommand,
+				},
+			}),
 	}
 	const epics = {
 		show: (id: string) =>
@@ -359,7 +368,7 @@ describe("work command", () => {
 		expect(harness.launches[0]?.cwd).toBe(singlePhaseWorkspace.writablePath)
 	})
 
-	test("selects a target with fzf when no directory is provided", async () => {
+	test("selects a target when no directory is provided", async () => {
 		const phase = {
 			taskId: "delivery",
 			id: "build",
@@ -385,7 +394,6 @@ describe("work command", () => {
 		await harness.run({ cwd: "/workbase/tasks/example", opencode: true }, pick)
 
 		expect(harness.events).toEqual([
-			"probe:fzf",
 			"materialize",
 			"probe:opencode",
 			"launch:opencode",
@@ -442,7 +450,6 @@ describe("work command", () => {
 
 		expect(selections).toEqual([["/first", "/workbase"]])
 		expect(harness.events).toEqual([
-			"probe:fzf",
 			"materialize",
 			"probe:opencode",
 			"launch:opencode",
@@ -476,9 +483,9 @@ describe("work command", () => {
 		expect(harness.events).toEqual([])
 	})
 
-	test("prints the target tree when fzf is unavailable", async () => {
+	test("passes the configured chooser command to the shared picker", async () => {
 		const harness = createHarness({
-			available: { fzf: false },
+			chooserCommand: ["gum", "filter"],
 			epicRecords: [
 				{
 					id: "delivery",
@@ -487,14 +494,15 @@ describe("work command", () => {
 				},
 			],
 		})
+		let command: readonly string[] | undefined
+		const pick: PickWorkTarget = (_choices, chooserCommand) => {
+			command = chooserCommand
+			return Effect.succeed(null)
+		}
 
-		const logs = await captureLogs(async () => {
-			await expect(harness.run({ cwd: "/workbase" })).rejects.toThrow(
-				"fzf is required",
-			)
-		})
+		await harness.run({ cwd: "/workbase" }, pick)
 
-		expect(logs).toEqual(["\x1b[35m\x1b[0m delivery"])
+		expect(command).toEqual(["gum", "filter"])
 		expect(harness.launches).toEqual([])
 	})
 

package/src/commands/work.ts

@@ -89,7 +89,7 @@ export const work = (
 			: false
 		const startPath = isDirectory && directoryPath ? directoryPath : cwd
 		const inputAllowed = options.inputAllowed ?? true
-		const root = yield* resolveWorkbase(startPath, log, pickBase, inputAllowed)
+		const root = yield* resolveWorkbase(startPath, pickBase, inputAllowed)
 		if (!root) return
 
 		let target: WorkTarget | null = null
@@ -178,18 +178,8 @@ export const work = (
 					new Error("No epics, tasks, or phases found in this workbase"),
 				)
 			}
-			const fzf = yield* fs.runCommand(["which", "fzf"], {
-				captureOutput: true,
-			})
-			if (fzf.exitCode !== 0) {
-				for (const choice of choices) log(choice.label)
-				return yield* Effect.fail(
-					new Error(
-						"fzf is required to select a work target; install fzf or provide a directory explicitly",
-					),
-				)
-			}
-			target = yield* pick(choices)
+			const { config } = yield* workbase.loadConfig(root)
+			target = yield* pick(choices, config.chooserCommand)
 			if (!target) return
 		}
 
@@ -332,7 +322,7 @@ Usage: agency work [<directory-or-task-id> | --epic <epic-id>]
        agency work prepare [target] [--dry-run] [--json]
 
 Launch an agent for an epic, task, or phase. With no directory, select one
-with fzf. A positional argument resolves as a directory first, then as a task
+interactively. A positional argument resolves as a directory first, then as a task
 ID. Use '.' for the current directory. Outside a workbase, select a registered
 workbase first.
 

package/src/protocol.ts

@@ -111,6 +111,11 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		retryable: false,
 		remediation: "Correct the workbase graph data or filters and retry.",
 	},
+	SyncError: {
+		code: "SYNC_ERROR",
+		retryable: false,
+		remediation: "Resolve workbase validation errors before reconciling.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",

package/src/services/ClaimService.ts

@@ -87,6 +87,23 @@ interface FinishInput extends OwnedClaimInput {
 	readonly outcome: "done" | "dropped"
 }
 
+interface ExpireClaimInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly now?: Date
+}
+
+interface ReconcileInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly pr?: string
+	readonly status?: "done"
+}
+
+const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
+
 type SingleTaskData = Extract<TaskData, { readonly repo: string }>
 type ExecutionData = SingleTaskData | PhaseData
 
@@ -286,6 +303,83 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 					}
 				}),
 
+			expire: (input: ExpireClaimInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, now) => {
+								if (
+									data.claim?.state !== "active" ||
+									data.claim.expiresAt === undefined ||
+									Date.parse(data.claim.expiresAt) > now.getTime() ||
+									(data.status !== "working" && data.status !== "delegated")
+								) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: `${inspected.target.label} does not have an expired active claim`,
+									})
+								}
+								const claim: ClaimRecord = {
+									...data.claim,
+									state: "released",
+									releasedAt: now.toISOString(),
+								}
+								return { data: { ...data, status: "open", claim }, claim }
+							},
+							input.now ?? new Date(),
+						),
+					)
+				}),
+
+			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+						return yield* new ClaimError({
+							message: `Invalid GitHub pull request URL: ${input.pr}`,
+						})
+					}
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data) => {
+								if (input.status === "done" && data.claim?.state === "active") {
+									throw new ClaimConflictError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										claim: data.claim,
+										message: `${inspected.target.label} has an active claim`,
+									})
+								}
+								return {
+									data: {
+										...data,
+										...(input.pr !== undefined ? { pr: input.pr } : {}),
+										...(input.status !== undefined
+											? { status: input.status }
+											: {}),
+									},
+								}
+							},
+							new Date(),
+						),
+					)
+				}),
+
 			claim: (input: ClaimInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					for (const [label, value] of [