@markjaquith/agency 2.12.0 → 2.14.0

package/src/cli.test.ts

@@ -81,6 +81,91 @@ describe("CLI", () => {
 		expect(taggedError.stderr).not.toContain("An error has occurred")
 	})
 
+	test("coordinates claims through revision-guarded machine commands", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos", "agency"), { recursive: true })
+		parseJson(
+			await runCli(
+				["task", "create", "claimed", "--repo", "agency", "--json"],
+				root,
+			),
+		)
+		const context = parseJson(
+			await runCli(["context", "tasks/claimed", "--json"], root),
+		)
+		const revision = context.documents.task.sha256
+		const claimed = parseJson(
+			await runCli(
+				[
+					"claim",
+					"claimed",
+					"--claimant",
+					"orchestrator",
+					"--runner",
+					"agent",
+					"--session-id",
+					"job-1",
+					"--revision",
+					revision,
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(claimed.claim).toMatchObject({
+			claimant: "orchestrator",
+			runner: "agent",
+			sessionId: "job-1",
+			state: "active",
+		})
+
+		const conflict = await runCli(
+			[
+				"claim",
+				"claimed",
+				"--claimant",
+				"other",
+				"--runner",
+				"other-agent",
+				"--session-id",
+				"job-2",
+				"--revision",
+				claimed.revision,
+				"--json",
+			],
+			root,
+		)
+		expect(conflict.exitCode).toBe(1)
+		expect(JSON.parse(conflict.stdout)).toMatchObject({
+			ok: false,
+			error: {
+				code: "CLAIM_CONFLICT",
+				retryable: true,
+				fields: { claim: { runner: "agent", sessionId: "job-1" } },
+			},
+		})
+
+		const finished = parseJson(
+			await runCli(
+				[
+					"finish",
+					"claimed",
+					"--session-id",
+					"job-1",
+					"--revision",
+					claimed.revision,
+					"--outcome",
+					"done",
+					"--json",
+				],
+				root,
+			),
+		)
+		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
+	})
+
 	test("emits one versioned error envelope for usage and command failures", async () => {
 		const usage = await runCli(["unknown", "--json"])
 		expect(usage.exitCode).toBe(1)
@@ -301,6 +386,76 @@ status: open
 		})
 	})
 
+	test("prepares a workspace and reports a non-mutating dry-run", async () => {
+		const parent = await createTempDir()
+		tempDirs.push(parent)
+		const root = join(parent, "workbase")
+		const source = join(parent, "source")
+		expect(
+			Bun.spawnSync(["git", "init", "--initial-branch=main", source]).exitCode,
+		).toBe(0)
+		await Bun.write(join(source, "README.md"), "example\n")
+		for (const args of [
+			["config", "user.email", "test@example.com"],
+			["config", "user.name", "Test"],
+			["add", "README.md"],
+			["-c", "commit.gpgsign=false", "commit", "-m", "initial"],
+		]) {
+			expect(Bun.spawnSync(["git", "-C", source, ...args]).exitCode).toBe(0)
+		}
+
+		parseJson(await runCli(["init", root, "--json"], parent))
+		parseJson(await runCli(["repo", "link", "agency", source, "--json"], root))
+		parseJson(
+			await runCli(
+				[
+					"task",
+					"create",
+					"example",
+					"--repo",
+					"agency",
+					"--branch",
+					"feat/example",
+					"--base",
+					"main",
+					"--json",
+				],
+				root,
+			),
+		)
+
+		const planned = parseJson(
+			await runCli(["work", "prepare", "example", "--dry-run", "--json"], root),
+		)
+		const workbaseRoot = await realpath(root)
+		expect(planned).toMatchObject({
+			dryRun: true,
+			taskPath: join(workbaseRoot, "tasks/example/TASK.md"),
+			phasePath: null,
+			checkouts: [
+				{
+					repo: "agency",
+					kind: "writable",
+					action: "created",
+					resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+				},
+			],
+		})
+		await expect(access(join(root, "tasks/example/code"))).rejects.toThrow()
+
+		const prepared = parseJson(
+			await runCli(["work", "prepare", "example", "--json"], root),
+		)
+		expect(prepared).toMatchObject({
+			dryRun: false,
+			checkouts: [{ action: "created", kind: "writable" }],
+		})
+		const task = parseJson(
+			await runCli(["task", "show", "example", "--json"], root),
+		)
+		expect(task.data.status).toBe("open")
+	})
+
 	test("envelopes help and version output in machine mode", async () => {
 		const help = await runCli(["status", "--help", "--json"])
 		expect(parseJson(help)).toContain("Usage: agency status")

package/src/commands/claim.ts

@@ -0,0 +1,97 @@
+import { Effect } from "effect"
+import { ClaimService } from "../services/ClaimService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface ClaimCommandOptions extends BaseCommandOptions {
+	readonly operation: "claim" | "release" | "finish"
+	readonly taskId?: string
+	readonly phaseId?: string
+	readonly claimant?: string
+	readonly runner?: string
+	readonly sessionId?: string
+	readonly revision?: string
+	readonly expiresAt?: string
+	readonly outcome?: string
+	readonly json?: boolean
+}
+
+export const claimCommand = (options: ClaimCommandOptions) =>
+	Effect.gen(function* () {
+		const claims = yield* ClaimService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		if (!options.taskId || !options.sessionId || !options.revision) {
+			return yield* Effect.fail(new Error("Missing required claim arguments"))
+		}
+		if (
+			options.operation === "claim" &&
+			(!options.claimant || !options.runner)
+		) {
+			return yield* Effect.fail(
+				new Error("Claimant and runner identities are required"),
+			)
+		}
+		if (
+			options.operation === "finish" &&
+			options.outcome !== "done" &&
+			options.outcome !== "dropped"
+		) {
+			return yield* Effect.fail(
+				new Error("Finish outcome must be done or dropped"),
+			)
+		}
+
+		const common = {
+			taskId: options.taskId,
+			...(options.phaseId ? { phaseId: options.phaseId } : {}),
+			sessionId: options.sessionId,
+			revision: options.revision,
+		}
+		const result =
+			options.operation === "claim"
+				? yield* claims.claim(
+						{
+							...common,
+							claimant: options.claimant!,
+							runner: options.runner!,
+							...(options.expiresAt ? { expiresAt: options.expiresAt } : {}),
+						},
+						cwd,
+					)
+				: options.operation === "release"
+					? yield* claims.release(common, cwd)
+					: yield* claims.finish(
+							{
+								...common,
+								outcome: options.outcome as "done" | "dropped",
+							},
+							cwd,
+						)
+
+		const { data: _, ...output } = result
+		log(
+			options.json
+				? JSON.stringify(output, null, 2)
+				: `${options.operation === "claim" ? "Claimed" : options.operation === "release" ? "Released" : "Finished"} ${result.target} at revision ${result.revision}`,
+		)
+	})
+
+export const claimHelp = `
+Usage: agency claim <task-id> [phase-id] --claimant <id> --runner <id> --session-id <id> --revision <sha256>
+
+Claim an execution unit. Use distinct claimant and runner identities for delegated
+work. --expires-at accepts an optional future ISO-8601 timestamp.
+`
+
+export const releaseHelp = `
+Usage: agency release <task-id> [phase-id] --session-id <id> --revision <sha256>
+
+Release an execution unit owned by the session.
+`
+
+export const finishHelp = `
+Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
+
+Finish an execution unit owned by the session.
+`

package/src/commands/phase.ts

@@ -125,7 +125,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, delegated, done, or dropped
+                        Set open, done, or dropped
 
 Create options:
   --description <text>  Short description of the phase

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

@@ -269,7 +269,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/work.test.ts

@@ -6,8 +6,9 @@ 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 } from "./work"
+import { work, workPrepare } from "./work"
 import type { PickWorkTarget } from "../workbase/work-target"
 import type { PickWorkbase } from "../workbase/workbase-choice"
 import type { Progress } from "../utils/progress"
@@ -24,6 +25,9 @@ const singlePhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 const multiPhaseWorkspace: ExecutionWorkspace = {
@@ -34,6 +38,9 @@ const multiPhaseWorkspace: ExecutionWorkspace = {
 	writablePath: "/workbase/tasks/example/phases/implementation/code/agency",
 	repo: "agency",
 	repos: [],
+	dryRun: false,
+	checkouts: [],
+	operations: [],
 }
 
 interface HarnessOptions {
@@ -127,6 +134,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),
@@ -165,6 +196,17 @@ 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]) =>
+		Effect.runPromise(
+			workPrepare(commandOptions).pipe(
+				Effect.provideService(WorktreeService, worktrees as never),
+				Effect.provideService(FileSystemService, fs as never),
+				Effect.provideService(WorkbaseService, workbase as never),
+				Effect.provideService(TaskService, tasks as never),
+				Effect.provideService(PhaseService, phases as never),
 			) as Effect.Effect<void, unknown, never>,
 		)
 
@@ -177,10 +219,32 @@ const createHarness = (options: HarnessOptions = {}) => {
 		shownTasks,
 		progressUpdates,
 		run,
+		runPrepare,
 	}
 }
 
 describe("work command", () => {
+	test("prepares without launching or changing lifecycle status", async () => {
+		const harness = createHarness({ existingDirectories: [] })
+
+		await captureLogs(() =>
+			harness.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				json: true,
+				dryRun: true,
+			}),
+		)
+
+		expect(harness.events).toEqual(["materialize"])
+		expect(harness.launches).toEqual([])
+		expect(harness.statusUpdates).toEqual([])
+		expect(harness.materializeOptions[0]).toMatchObject({
+			json: true,
+			dryRun: true,
+		})
+	})
+
 	test("launches an epic agent from an epic directory", async () => {
 		const harness = createHarness()
 

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
@@ -229,10 +233,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,17 +261,85 @@ 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 = {}) =>
+	Effect.gen(function* () {
+		const fs = yield* FileSystemService
+		const workbase = yield* WorkbaseService
+		const tasks = yield* TaskService
+		const phases = yield* PhaseService
+		const worktrees = yield* WorktreeService
+		const { log } = createLoggers(options)
+		const cwd = options.cwd ?? process.cwd()
+		const targetPath = options.directory ? resolve(cwd, options.directory) : cwd
+		const isDirectory = yield* fs.isDirectory(targetPath)
+		const root = yield* workbase.discover(isDirectory ? targetPath : cwd)
+
+		let taskId: string | undefined
+		let phaseId: string | undefined
+		if (options.directory && !isDirectory) {
+			const task = yield* tasks.show(options.directory, root)
+			taskId = task.id
+		} else {
+			const path = relative(root, targetPath)
+			const parts =
+				!path || isAbsolute(path) || path.startsWith(`..${sep}`)
+					? []
+					: path.split(sep)
+			if (parts[0] === "tasks" && parts[1]) {
+				const task = yield* tasks.show(parts[1], root)
+				taskId = task.id
+				if (parts[2] === "phases" && parts[3]) {
+					const phase = yield* phases.show(task.id, parts[3], root)
+					phaseId = phase.id
+				}
+			}
+		}
+
+		if (!taskId) {
+			return yield* Effect.fail(
+				new Error(
+					"Work preparation requires a task ID or a path inside an execution unit",
+				),
+			)
+		}
+
+		const workspace = yield* worktrees.materialize(taskId, phaseId, root, {
+			...options,
+			dryRun: options.dryRun,
+		})
+		if (options.json) {
+			log(JSON.stringify(workspace, null, 2))
+		} else {
+			log(
+				`${workspace.dryRun ? "Workspace plan" : "Workspace ready"}: ${workspace.writablePath}`,
+			)
+		}
 	})
 
 export const help = `
 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
 ID. Use '.' for the current directory. Outside a workbase, select a registered
 workbase first.
 
+The prepare subcommand resolves and materializes an execution workspace without
+launching an agent or changing lifecycle status. --dry-run reports planned Git
+changes without fetching, creating branches, or creating worktrees.
+
 Options:
   --epic <id>         Work on an epic
   --opencode           Require OpenCode

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 },