@markjaquith/agency 3.2.2 → 3.2.3

package/src/cli-parser.ts

@@ -114,21 +114,6 @@ const mutationOptions = {
 	"no-epic": { type: "boolean" },
 } satisfies OptionConfig
 
-const claimOptions = {
-	...outputOptions,
-	claimant: { type: "string" },
-	agent: { type: "string" },
-	"session-id": { type: "string" },
-	revision: { type: "string" },
-	"expires-at": { type: "string" },
-} satisfies OptionConfig
-
-const ownedClaimOptions = {
-	...outputOptions,
-	"session-id": { type: "string" },
-	revision: { type: "string" },
-} satisfies OptionConfig
-
 const nonPrCompletionOptions = {
 	"no-pull-request": { type: "boolean" },
 	summary: { type: "string" },
@@ -679,75 +664,6 @@ const commands = {
 			},
 		},
 	},
-	claim: {
-		usage: "agency claim <task-id> [phase-id] [options]",
-		options: {
-			...claimOptions,
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency claim <task-id> [phase-id] --claimant <id> --agent <id> --session-id <id> --revision <sha256> [--expires-at <timestamp>] [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: [
-				"claimant",
-				"agent",
-				"session-id",
-				"revision",
-				"expires-at",
-				"json",
-				"task",
-				"phase",
-			],
-			required: ["claimant", "agent", "session-id", "revision"],
-		},
-	},
-	release: {
-		usage: "agency release <task-id> [phase-id] [options]",
-		options: {
-			...ownedClaimOptions,
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency release <task-id> [phase-id] --session-id <id> --revision <sha256> [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: ["session-id", "revision", "json", "task", "phase"],
-			required: ["session-id", "revision"],
-		},
-	},
-	finish: {
-		usage: "agency finish <task-id> [phase-id] [options]",
-		options: {
-			...ownedClaimOptions,
-			...nonPrCompletionOptions,
-			outcome: { type: "string" },
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		command: {
-			usage:
-				"agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [options] [--json]",
-			minArgs: 1,
-			maxArgs: 2,
-			options: [
-				"session-id",
-				"revision",
-				"outcome",
-				"no-pull-request",
-				"summary",
-				"evidence-url",
-				"json",
-				"task",
-				"phase",
-			],
-			required: ["session-id", "revision", "outcome"],
-		},
-	},
 	sync: {
 		usage: "agency sync [<task-id> [phase-id]] [--dry-run] [--json]",
 		options: {
@@ -1177,8 +1093,6 @@ const targetSlots = (
 		return ["task"]
 	if (commandName === "phase")
 		return subcommand === "list" ? ["task"] : ["task", "phase"]
-	if (["claim", "release", "finish"].includes(commandName))
-		return ["task", "phase"]
 	if (["archive", "restore"].includes(commandName))
 		return subcommand === "epic"
 			? ["epic"]
@@ -1637,16 +1551,6 @@ export function parseCli(args: readonly string[]): ParsedCli {
 	) {
 		validateViewOptions(parsed.values, spec)
 	}
-	if (
-		commandName === "finish" &&
-		parsed.values.outcome !== "done" &&
-		parsed.values.outcome !== "dropped"
-	) {
-		throw usageError(
-			"Option '--outcome' must be 'done' or 'dropped'.",
-			spec.usage,
-		)
-	}
 	const nonPrCompletion = parsed.values["no-pull-request"] === true
 	const completionSummary = parsed.values.summary
 	const completionEvidenceUrl = parsed.values["evidence-url"]
@@ -1670,19 +1574,24 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			)
 		}
 		const completesDone =
-			(commandName === "finish" && parsed.values.outcome === "done") ||
-			(["task", "phase"].includes(commandName) &&
-				subcommand === "status" &&
-				commandPositionals.at(-1) === "done")
+			["task", "phase"].includes(commandName) &&
+			subcommand === "status" &&
+			commandPositionals.at(-1) === "done"
 		if (!completesDone) {
 			throw usageError(
-				"Option '--no-pull-request' is valid only with a done status or outcome.",
+				"Option '--no-pull-request' is valid only with a done status.",
 				spec.usage,
 			)
 		}
 	}
 	if (commandName === "work") {
 		const preparing = commandPositionals[0] === "prepare"
+		if (preparing && parsed.values.phase && !parsed.values.task) {
+			throw usageError(
+				"Option '--phase' requires '--task' with work preparation.",
+				spec.usage,
+			)
+		}
 		if (
 			(!preparing && commandPositionals.length > 1) ||
 			(preparing &&

package/src/cli.test.ts

@@ -210,131 +210,23 @@ describe("CLI", () => {
 		expect(exported.stdout).not.toContain("/private/value")
 	})
 
-	test("coordinates claims through revision-guarded machine commands", async () => {
+	test("records status-based non-PR completion", 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",
-					"--agent",
-					"agent",
-					"--session-id",
-					"job-1",
-					"--revision",
-					revision,
-					"--json",
-				],
-				root,
-			),
-		)
-		expect(claimed.claim).toMatchObject({
-			claimant: "orchestrator",
-			agent: "agent",
-			sessionId: "job-1",
-			state: "active",
-		})
-
-		const conflict = await runCli(
-			[
-				"claim",
-				"claimed",
-				"--claimant",
-				"other",
-				"--agent",
-				"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: { agent: "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" })
-		expect(
-			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
-				.status,
-		).toBe("working")
-
 		parseJson(
 			await runCli(
 				["task", "create", "non-pr", "--repo", "agency", "--json"],
 				root,
 			),
 		)
-		const nonPrContext = parseJson(
-			await runCli(["context", "tasks/non-pr", "--json"], root),
-		)
-		const nonPrClaim = parseJson(
-			await runCli(
-				[
-					"claim",
-					"non-pr",
-					"--claimant",
-					"orchestrator",
-					"--agent",
-					"agent",
-					"--session-id",
-					"job-2",
-					"--revision",
-					nonPrContext.documents.task.sha256,
-					"--json",
-				],
-				root,
-			),
-		)
 		parseJson(
 			await runCli(
 				[
-					"finish",
+					"task",
+					"status",
 					"non-pr",
-					"--session-id",
-					"job-2",
-					"--revision",
-					nonPrClaim.revision,
-					"--outcome",
 					"done",
 					"--no-pull-request",
 					"--summary",
@@ -1073,6 +965,15 @@ status: open
 				],
 			}),
 		])
+		const preparedAgain = parseJson(
+			await runCli(
+				["work", "prepare", join(root, "tasks/example/TASK.md"), "--json"],
+				parent,
+			),
+		)
+		expect(preparedAgain.checkouts).toEqual([
+			expect.objectContaining({ action: "reused", kind: "writable" }),
+		])
 		const rebuild = parseJson(
 			await runCli(
 				["worktree", "rebuild", "example", "--dry-run", "--json"],

package/src/commands/act.ts

@@ -106,9 +106,6 @@ const entityChoices = (
 		value: entityKey(node),
 	}))
 
-const activeClaim = (node: EntityNode) =>
-	"claim" in node.data && node.data.claim?.state === "active"
-
 const executionNode = (
 	node: EntityNode,
 	executions: ReadonlyMap<
@@ -131,7 +128,6 @@ const canWork = (
 	const execution = executionNode(node, executions)
 	return Boolean(
 		execution &&
-		!activeClaim(node) &&
 		(execution.readiness.ready ||
 			(execution.status === "working" &&
 				execution.readiness.blockers.every(
@@ -168,10 +164,10 @@ const actionChoices = (
 	if (canCreatePr(node, executions)) {
 		choices.push({ key: "pr", label: "Create pull request", value: "pr" })
 	}
-	if (execution && isTerminalStatus(node.status) && !activeClaim(node)) {
+	if (execution && isTerminalStatus(node.status)) {
 		choices.push({ key: "reopen", label: "Reopen", value: "reopen" })
 	}
-	if (execution && !isTerminalStatus(node.status) && !activeClaim(node)) {
+	if (execution && !isTerminalStatus(node.status)) {
 		choices.push({ key: "drop", label: "Drop", value: "drop" })
 	}
 	if (node.readiness.terminal) {

package/src/commands/sync.ts

@@ -125,7 +125,7 @@ export const help = `
 Usage: agency sync [<task-id> [phase-id]] [--dry-run] [--json]
 
 Compare portable repository declarations and execution state with local Git
-repositories, worktrees, branches, references, claims, and pull requests.
+repositories, worktrees, branches, references, and pull requests.
 Safe reconciliation transitions are applied by default.
 When a task or phase is provided, only that target and its repositories are
 queried or reconciled. Task scope includes all phases of a multi-phase task.
@@ -135,7 +135,7 @@ Options:
   --json                    Output one versioned machine result
 
 Sync may materialize declared repositories and unambiguous missing checkouts,
-adopt legacy repositories with portable origins, release expired claims,
-record a uniquely matched PR, and mark merged work done. Dirty, stale, or
+adopt legacy repositories with portable origins, record a uniquely matched PR,
+and mark merged work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.
 `

package/src/commands/validate.ts

@@ -13,7 +13,9 @@ interface ValidateOptions extends BaseCommandOptions {
 	readonly json?: boolean
 }
 
-class ValidationFailedError extends Data.TaggedError("ValidationFailedError")<{
+export class ValidationFailedError extends Data.TaggedError(
+	"ValidationFailedError",
+)<{
 	readonly message: string
 	readonly root: string
 	readonly issues: readonly {

package/src/commands/work.test.ts

@@ -84,6 +84,8 @@ interface HarnessOptions {
 		Record<string, "open" | "working" | "delegated" | "done" | "dropped">
 	>
 	readonly taskRepo?: string
+	readonly existingPaths?: readonly string[]
+	readonly validationIssues?: readonly { path: string; message: string }[]
 }
 
 const createHarness = (options: HarnessOptions = {}) => {
@@ -142,15 +144,17 @@ const createHarness = (options: HarnessOptions = {}) => {
 				},
 			}),
 		repositoryAliases: () => Effect.succeed(["agency"]),
-		validate: () =>
-			Effect.succeed({
+		validate: () => {
+			const issues = options.validationIssues ?? []
+			return Effect.succeed({
 				root: "/workbase",
-				issues: [],
+				issues,
 				epicCount: 0,
 				taskCount: 1,
 				phaseCount: 0,
-				valid: true,
-			}),
+				valid: issues.length === 0,
+			})
+		},
 	}
 	const epics = {
 		show: (id: string) =>
@@ -281,7 +285,8 @@ const createHarness = (options: HarnessOptions = {}) => {
 		readFile: (path: string) =>
 			Effect.succeed(path.endsWith("agency.json") ? '{"version":2}\n' : ""),
 		readDirectory: () => Effect.succeed([]),
-		exists: () => Effect.succeed(false),
+		exists: (path: string) =>
+			Effect.succeed(options.existingPaths?.includes(path) ?? false),
 		realPath: (path: string) => Effect.succeed(path),
 		runCommand: (args: readonly string[]) => {
 			const cli = args[1]!
@@ -569,6 +574,65 @@ describe("work command", () => {
 		).rejects.toThrow("Recalled repository conflicts")
 	})
 
+	test("resolves task and phase document paths", async () => {
+		const taskDocument = "/workbase/tasks/example/TASK.md"
+		const taskHarness = createHarness({
+			existingDirectories: [],
+			existingPaths: [taskDocument],
+		})
+
+		await taskHarness.runPrepare({
+			directory: taskDocument,
+			dryRun: true,
+			silent: true,
+		})
+		expect(taskHarness.guards[0]?.target).toBe("execution-unit:task/example")
+		expect(taskHarness.shownTasks).toEqual(["example", "example"])
+
+		const phaseDocument =
+			"/workbase/tasks/example/phases/implementation/PHASE.md"
+		const phaseHarness = createHarness({
+			existingDirectories: [],
+			existingPaths: [phaseDocument],
+			multiPhaseTasks: ["example"],
+			workspace: multiPhaseWorkspace,
+		})
+
+		await phaseHarness.runPrepare({
+			directory: phaseDocument,
+			dryRun: true,
+			silent: true,
+		})
+		expect(phaseHarness.guards[0]?.target).toBe(
+			"execution-unit:phase/example/implementation",
+		)
+		expect(phaseHarness.materializeOptions).toHaveLength(1)
+	})
+
+	test("returns structured validation issues before readiness or materialization", async () => {
+		const harness = createHarness({
+			existingDirectories: [],
+			validationIssues: [
+				{
+					path: "tasks/example/TASK.md",
+					message: "Repository alias 'missing' is not configured",
+				},
+			],
+		})
+
+		await expect(
+			harness.runPrepare({
+				cwd: "/workbase",
+				directory: "example",
+				dryRun: true,
+			}),
+		).rejects.toThrow(
+			"Workbase validation failed with 1 issue:\n- tasks/example/TASK.md: Repository alias 'missing' is not configured",
+		)
+		expect(harness.guards).toEqual([])
+		expect(harness.events).toEqual([])
+	})
+
 	test("force prepares a phase blocked by an active dependency without launching or changing status", async () => {
 		const blocked = createHarness({
 			workspace: multiPhaseWorkspace,
@@ -1031,12 +1095,10 @@ describe("work command", () => {
 		})
 		expect(harness.launchEnvironments[0]).toMatchObject({
 			AGENCY_AGENT: "custom",
-			AGENCY_CLAIMANT: process.env.USER ?? "agency",
 			AGENCY_WORKBASE: "/workbase",
 			AGENCY_TARGET: "execution-unit:task/example",
 			AGENCY_TASK_ID: "example",
 			AGENCY_PHASE_ID: "",
-			AGENCY_CLAIM_REVISION: "",
 			CUSTOM_TARGET: "execution-unit:task/example",
 		})
 	})

package/src/commands/work.ts

@@ -36,6 +36,7 @@ import {
 	normalizeRecalledContext,
 	readValidationEvidence,
 } from "../workbase/execution-contract"
+import { ValidationFailedError } from "./validate"
 
 export interface WorkOptions extends BaseCommandOptions {
 	readonly directory?: string
@@ -288,7 +289,6 @@ export const work = (
 		const defaultAgents = ["opencode2", "opencode", "pi", "claude"] as const
 		let defaultAgentIndex = 0
 		let agent: string = selectedAgent ?? defaultAgents[defaultAgentIndex]!
-		const claimant = process.env.AGENCY_CLAIMANT ?? process.env.USER ?? "agency"
 		const sessionId =
 			process.env.AGENCY_SESSION_ID ?? `${process.pid}-${Date.now()}`
 		const resume =
@@ -300,9 +300,7 @@ export const work = (
 			target: targetNodeId(target),
 			task: target.kind === "epic" ? "" : target.taskId,
 			phase: target.kind === "phase" ? target.phaseId : "",
-			claimant,
 			sessionId,
-			claimRevision: "",
 		}
 		let resolved = resolveAgentCommand(
 			agent,
@@ -439,7 +437,8 @@ export const workPrepare = (options: WorkOptions = {}) =>
 		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)
+		const targetExists = isDirectory || (yield* fs.exists(targetPath))
+		const root = yield* workbase.discover(targetExists ? targetPath : cwd)
 
 		let taskId = options.taskId
 		let phaseId = options.phaseId
@@ -447,7 +446,7 @@ export const workPrepare = (options: WorkOptions = {}) =>
 			const task = yield* tasks.show(taskId, root)
 			taskId = task.id
 			if (phaseId) phaseId = (yield* phases.show(task.id, phaseId, root)).id
-		} else if (options.directory && !isDirectory) {
+		} else if (options.directory && !targetExists) {
 			const task = yield* tasks.show(options.directory, root)
 			taskId = task.id
 		} else {
@@ -526,9 +525,17 @@ export const workPrepare = (options: WorkOptions = {}) =>
 		})
 		let validation: unknown = { valid: true, source: "evidence" }
 		if (assessment.disposition.status === "refreshed") {
-			validation = yield* workbase.validate(root)
-			if (!(validation as { valid: boolean }).valid && !options.force) {
-				return yield* Effect.fail(new Error("Workbase validation failed"))
+			const report = yield* workbase.validate(root)
+			validation = report
+			if (!report.valid && !options.force) {
+				const details = report.issues
+					.map((issue) => `- ${issue.path}: ${issue.message}`)
+					.join("\n")
+				return yield* new ValidationFailedError({
+					message: `Workbase validation failed with ${report.issues.length} issue${report.issues.length === 1 ? "" : "s"}:\n${details}`,
+					root: report.root,
+					issues: report.issues,
+				})
 			}
 		}
 		yield* readiness.guardWorkTarget(target, root, options.force)

package/src/graph-schema.ts

@@ -3,7 +3,6 @@ import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	PullRequestRecord,
-	ClaimRecord,
 	ReviewRecord,
 	TaskHandoff,
 	TaskFrontmatter,
@@ -96,7 +95,6 @@ export const GraphExecutionData = Schema.Union(
 		handoff: Schema.optional(TaskHandoff),
 		review: ReviewRecord,
 		status: WorkStatus,
-		claim: Schema.optional(ClaimRecord),
 	}),
 )
 

package/src/protocol.test.ts

@@ -116,31 +116,6 @@ describe("machine protocol", () => {
 			"issues",
 			"root",
 		])
-		expect(
-			errorEnvelope({
-				_tag: "ClaimConflictError",
-				message: "already claimed",
-				target: "task 'example'",
-				currentRevision: "a".repeat(64),
-				claim: {
-					claimant: "orchestrator",
-					agent: "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: { agent: "agent", sessionId: "job-1" },
-				},
-			},
-		})
 		expect(
 			errorEnvelope({
 				_tag: "RevisionConflictError",

package/src/protocol.ts

@@ -81,22 +81,11 @@ 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 },
 	PushError: { code: "PUSH_ERROR", retryable: false },

package/src/readiness.test.ts

@@ -27,10 +27,10 @@ describe("readiness model", () => {
 			blockedBy: ["task:one"],
 			terminal: true,
 		})
-		expect(readinessState("working", [{ id: "claim:self" }])).toEqual({
+		expect(readinessState("working", [{ id: "dependency:self" }])).toEqual({
 			ready: false,
 			blocked: true,
-			blockedBy: ["claim:self"],
+			blockedBy: ["dependency:self"],
 			terminal: false,
 		})
 	})