@markjaquith/agency 2.13.0 → 2.15.0

package/src/commands/task-phase.test.ts

@@ -172,13 +172,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				phase({
 					subcommand: "status",
-					args: ["multi", "first", "delegated"],
+					args: ["multi", "first", "done"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("delegated")
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
 
 		await runTestEffect(
 			task({
@@ -196,13 +196,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				task({
 					subcommand: "status",
-					args: ["single-status", "delegated"],
+					args: ["single-status", "done"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(taskLogs[0]!).data.status).toBe("delegated")
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("done")
 	})
 
 	test("converts a single-phase task with an explicit first phase ID", async () => {

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),
 					)
@@ -269,7 +266,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, delegated, done, or dropped
+  status <id> <status>  Set open, done, or dropped
 
 Create options:
   --ticket-url <url>    External ticket URL (optional)

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

@@ -6,6 +6,7 @@ import { EpicService } from "../services/EpicService"
 import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
 import { WorktreeService } from "../services/WorktreeService"
+import { ClaimService } from "../services/ClaimService"
 import { captureErrors, captureLogs } from "../test-utils"
 import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
@@ -45,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[]
@@ -92,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) =>
@@ -133,6 +143,30 @@ const createHarness = (options: HarnessOptions = {}) => {
 			return Effect.void
 		},
 	}
+	const claims = {
+		inspect: (taskId: string, phaseId?: string) =>
+			Effect.succeed({
+				target: {
+					kind: phaseId ? "phase" : "task",
+					taskId,
+					phaseId,
+					path: phaseId
+						? `/workbase/tasks/${taskId}/phases/${phaseId}/PHASE.md`
+						: `/workbase/tasks/${taskId}/TASK.md`,
+					label: phaseId ? `phase '${taskId}/${phaseId}'` : `task '${taskId}'`,
+				},
+				revision: "0".repeat(64),
+				data: {},
+			}),
+		claim: (input: { taskId: string; phaseId?: string }) => {
+			statusUpdates.push(
+				input.phaseId
+					? `phase:${input.taskId}:${input.phaseId}:working`
+					: `task:${input.taskId}:working`,
+			)
+			return Effect.succeed({ revision: "1".repeat(64) })
+		},
+	}
 	const fs = {
 		isDirectory: (path: string) =>
 			Effect.succeed(options.existingDirectories?.includes(path) ?? true),
@@ -171,6 +205,7 @@ const createHarness = (options: HarnessOptions = {}) => {
 				Effect.provideService(EpicService, epics as never),
 				Effect.provideService(TaskService, tasks as never),
 				Effect.provideService(PhaseService, phases as never),
+				Effect.provideService(ClaimService, claims as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 	const runPrepare = (commandOptions: Parameters<typeof workPrepare>[0]) =>
@@ -333,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",
@@ -359,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",
@@ -416,7 +450,6 @@ describe("work command", () => {
 
 		expect(selections).toEqual([["/first", "/workbase"]])
 		expect(harness.events).toEqual([
-			"probe:fzf",
 			"materialize",
 			"probe:opencode",
 			"launch:opencode",
@@ -450,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",
@@ -461,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

@@ -7,6 +7,7 @@ import { WorkbaseService } from "../services/WorkbaseService"
 import { EpicService } from "../services/EpicService"
 import { TaskService } from "../services/TaskService"
 import { PhaseService } from "../services/PhaseService"
+import { ClaimService } from "../services/ClaimService"
 import { createLoggers } from "../utils/effect"
 import { execvp } from "../utils/exec"
 import { createProgress, type Progress } from "../utils/progress"
@@ -60,6 +61,8 @@ export const work = (
 				new Error("Cannot use both --opencode and --claude"),
 			)
 		}
+		const previousSessionId = process.env.AGENCY_SESSION_ID
+		const previousClaimRevision = process.env.AGENCY_CLAIM_REVISION
 		if (
 			options.epicId &&
 			(options.directory || options.taskId || options.phaseId)
@@ -75,6 +78,7 @@ export const work = (
 		const epics = yield* EpicService
 		const tasks = yield* TaskService
 		const phases = yield* PhaseService
+		const claims = yield* ClaimService
 		const { log, verboseLog } = createLoggers(options)
 		const cwd = options.cwd ?? process.cwd()
 		const directoryPath = options.directory
@@ -85,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
@@ -174,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
 		}
 
@@ -229,10 +223,27 @@ export const work = (
 		if (available.exitCode !== 0) {
 			return yield* Effect.fail(new Error(`${cli} CLI tool not found`))
 		}
-		if (target.kind === "phase") {
-			yield* phases.setStatus(target.taskId, target.phaseId, "working", root)
-		} else if (target.kind === "task" && !target.multiPhase) {
-			yield* tasks.setStatus(target.taskId, "working", root)
+		if (
+			target.kind === "phase" ||
+			(target.kind === "task" && !target.multiPhase)
+		) {
+			const phaseId = target.kind === "phase" ? target.phaseId : undefined
+			const current = yield* claims.inspect(target.taskId, phaseId, root)
+			const sessionId =
+				process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
+			const acquired = yield* claims.claim(
+				{
+					taskId: target.taskId,
+					...(phaseId ? { phaseId } : {}),
+					claimant: process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency",
+					runner: process.env.AGENCY_RUNNER ?? cli,
+					sessionId,
+					revision: current.revision,
+				},
+				root,
+			)
+			process.env.AGENCY_SESSION_ID = sessionId
+			process.env.AGENCY_CLAIM_REVISION = acquired.revision
 		}
 
 		const args =
@@ -240,7 +251,15 @@ export const work = (
 		verboseLog(
 			`Launching command: ${formatCommand([cli, ...args])} (cwd: ${launchPath})`,
 		)
-		launch(cli, [cli, ...args], launchPath)
+		try {
+			launch(cli, [cli, ...args], launchPath)
+		} finally {
+			if (previousSessionId === undefined) delete process.env.AGENCY_SESSION_ID
+			else process.env.AGENCY_SESSION_ID = previousSessionId
+			if (previousClaimRevision === undefined)
+				delete process.env.AGENCY_CLAIM_REVISION
+			else process.env.AGENCY_CLAIM_REVISION = previousClaimRevision
+		}
 	})
 
 export const workPrepare = (options: WorkOptions = {}) =>
@@ -303,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.test.ts

@@ -83,5 +83,30 @@ describe("machine protocol", () => {
 				},
 			},
 		})
+		expect(
+			errorEnvelope({
+				_tag: "ClaimConflictError",
+				message: "already claimed",
+				target: "task 'example'",
+				currentRevision: "a".repeat(64),
+				claim: {
+					claimant: "orchestrator",
+					runner: "agent",
+					sessionId: "job-1",
+					startedAt: "2026-07-17T12:00:00.000Z",
+					targetRevision: "0".repeat(64),
+					state: "active",
+				},
+			}),
+		).toMatchObject({
+			error: {
+				code: "CLAIM_CONFLICT",
+				retryable: true,
+				fields: {
+					target: "task 'example'",
+					claim: { runner: "agent", sessionId: "job-1" },
+				},
+			},
+		})
 	})
 })

package/src/protocol.ts

@@ -81,6 +81,22 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 	EpicError: { code: "EPIC_ERROR", retryable: false },
 	TaskError: { code: "TASK_ERROR", retryable: false },
 	PhaseError: { code: "PHASE_ERROR", retryable: false },
+	ClaimError: { code: "CLAIM_ERROR", retryable: false },
+	ClaimConflictError: {
+		code: "CLAIM_CONFLICT",
+		retryable: true,
+		remediation: "Inspect the current ownership details before retrying.",
+	},
+	RevisionConflictError: {
+		code: "REVISION_CONFLICT",
+		retryable: true,
+		remediation: "Read the current document revision and retry intentionally.",
+	},
+	ClaimOwnershipError: {
+		code: "CLAIM_OWNERSHIP",
+		retryable: false,
+		remediation: "Use the session that owns the claim.",
+	},
 	ArchiveError: { code: "ARCHIVE_ERROR", retryable: false },
 	WorktreeError: { code: "WORKTREE_ERROR", retryable: false },
 	PullRequestError: { code: "PULL_REQUEST_ERROR", retryable: false },