@markjaquith/agency 3.2.1 → 3.2.3

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",
@@ -161,4 +136,28 @@ describe("machine protocol", () => {
 			},
 		})
 	})
+
+	test("uses dynamic protocol metadata without duplicating it in fields", () => {
+		expect(
+			errorEnvelope({
+				_tag: "PushError",
+				message: "remote timed out",
+				protocolCode: "PUSH_TIMEOUT",
+				retryable: true,
+				remediation: "Retry after checking connectivity.",
+				category: "timeout",
+				stage: "fetch",
+			}),
+		).toEqual({
+			version: 1,
+			ok: false,
+			error: {
+				code: "PUSH_TIMEOUT",
+				message: "remote timed out",
+				fields: { category: "timeout", stage: "fetch" },
+				retryable: true,
+				remediation: "Retry after checking connectivity.",
+			},
+		})
+	})
 })

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 },
@@ -198,6 +187,36 @@ const errorTag = (error: unknown): string | undefined => {
 	return undefined
 }
 
+const unwrapEffectError = (error: unknown): unknown => {
+	const seen = new Set<object>()
+	const visit = (value: unknown): unknown => {
+		if (typeof value !== "object" || value === null || seen.has(value))
+			return null
+		seen.add(value)
+		if ("protocolCode" in value && typeof value.protocolCode === "string") {
+			return value
+		}
+		for (const nested of [
+			...Object.values(value),
+			...Object.getOwnPropertySymbols(value).map(
+				(symbol) => (value as Record<symbol, unknown>)[symbol],
+			),
+		]) {
+			const found = visit(nested)
+			if (found) return found
+		}
+		if (
+			"_tag" in value &&
+			typeof value._tag === "string" &&
+			value._tag.endsWith("Error")
+		) {
+			return value
+		}
+		return null
+	}
+	return visit(error) ?? error
+}
+
 const errorMessage = (error: unknown): string => {
 	if (
 		typeof error === "object" &&
@@ -219,6 +238,9 @@ const errorFields = (error: unknown): Record<string, unknown> => {
 				key !== "name" &&
 				key !== "message" &&
 				key !== "cause" &&
+				key !== "protocolCode" &&
+				key !== "retryable" &&
+				key !== "remediation" &&
 				value !== undefined,
 		),
 	)
@@ -231,17 +253,36 @@ export const successEnvelope = (result: unknown): SuccessEnvelope => ({
 })
 
 export const errorEnvelope = (error: unknown): ErrorEnvelope => {
-	const metadata = errorMetadata[errorTag(error) ?? ""] ?? {
+	const normalized = unwrapEffectError(error)
+	const defaults = errorMetadata[errorTag(normalized) ?? ""] ?? {
 		code: "COMMAND_FAILED",
 		retryable: false,
 	}
+	const dynamic =
+		typeof normalized === "object" && normalized !== null
+			? {
+					...("protocolCode" in normalized &&
+					typeof normalized.protocolCode === "string"
+						? { code: normalized.protocolCode }
+						: {}),
+					...("retryable" in normalized &&
+					typeof normalized.retryable === "boolean"
+						? { retryable: normalized.retryable }
+						: {}),
+					...("remediation" in normalized &&
+					typeof normalized.remediation === "string"
+						? { remediation: normalized.remediation }
+						: {}),
+				}
+			: {}
 	return {
 		version: PROTOCOL_VERSION,
 		ok: false,
 		error: {
-			...metadata,
-			message: errorMessage(error),
-			fields: errorFields(error),
+			...defaults,
+			...dynamic,
+			message: errorMessage(normalized),
+			fields: errorFields(normalized),
 		},
 	}
 }

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

package/src/services/ArchiveBulkService.test.ts

@@ -335,94 +335,6 @@ describe("ArchiveService bulk task archive", () => {
 		).toBe(true)
 	})
 
-	test("skips task- and phase-level active claims", async () => {
-		await createTask("claimed")
-		await dropTask("claimed")
-		const taskPath = join(root, "tasks/claimed/TASK.md")
-		await Bun.write(
-			taskPath,
-			(await Bun.file(taskPath).text()).replace(
-				"status: dropped\n",
-				`status: dropped
-claim:
-  claimant: orchestrator
-  agent: opencode
-  sessionId: task-session
-  startedAt: 2026-08-07T00:00:00.000Z
-  targetRevision: ${"a".repeat(64)}
-  state: active
-`,
-			),
-		)
-		await runTestEffect(
-			TaskService.pipe(
-				Effect.flatMap((service) =>
-					service.create(
-						{ id: "multi-claimed", ticketUrl: null, multiPhase: true },
-						root,
-					),
-				),
-			),
-		)
-		await runTestEffect(
-			PhaseService.pipe(
-				Effect.flatMap((service) =>
-					service.create(
-						{
-							taskId: "multi-claimed",
-							id: "phase",
-							repo: "agency",
-							branch: "task/multi-claimed",
-							base: "main",
-						},
-						root,
-					),
-				),
-			),
-		)
-		await runTestEffect(
-			PhaseService.pipe(
-				Effect.flatMap((service) =>
-					service.setStatus("multi-claimed", "phase", "dropped", root),
-				),
-			),
-		)
-		const phasePath = join(root, "tasks/multi-claimed/phases/phase/PHASE.md")
-		await Bun.write(
-			phasePath,
-			(await Bun.file(phasePath).text()).replace(
-				"status: dropped\n",
-				`status: dropped
-claim:
-  claimant: orchestrator
-  agent: opencode
-  sessionId: phase-session
-  startedAt: 2026-08-07T00:00:00.000Z
-  targetRevision: ${"b".repeat(64)}
-  state: active
-`,
-			),
-		)
-
-		const result = await archiveTasks(true)
-
-		expect(result.tasks).toMatchObject([
-			{
-				id: "claimed",
-				disposition: "skipped",
-				reason: { code: "active-claim", details: ["task:claimed"] },
-			},
-			{
-				id: "multi-claimed",
-				disposition: "skipped",
-				reason: {
-					code: "active-claim",
-					details: ["phase:multi-claimed/phase"],
-				},
-			},
-		])
-	})
-
 	test("rolls back the entire cohort when application fails", async () => {
 		await runTestEffect(
 			EpicService.pipe(

package/src/services/ArchiveService.ts

@@ -111,7 +111,6 @@ interface LifecycleOptions {
 
 type TaskArchiveSkipCode =
 	| "non-terminal"
-	| "active-claim"
 	| "dirty-worktree"
 	| "checkout-preflight-failed"
 	| "retained-dependent"
@@ -169,7 +168,6 @@ interface TaskArchiveContext {
 	readonly executionUnits: readonly { taskId: string; phaseId?: string }[]
 	readonly terminal: boolean
 	readonly terminalDetails: readonly string[]
-	readonly activeClaims: readonly string[]
 }
 
 const loadTaskArchiveContext = (task: TaskRecord, root: string) =>
@@ -182,8 +180,6 @@ const loadTaskArchiveContext = (task: TaskRecord, root: string) =>
 				executionUnits: [{ taskId: task.id }],
 				terminal: isTerminalStatus(task.data.status),
 				terminalDetails: [`status=${task.data.status}`],
-				activeClaims:
-					task.data.claim?.state === "active" ? [`task:${task.id}`] : [],
 			} satisfies TaskArchiveContext
 		}
 
@@ -207,9 +203,6 @@ const loadTaskArchiveContext = (task: TaskRecord, root: string) =>
 					: phaseRecords.map(
 							(phase) => `phase:${phase.id}:status=${phase.data.status}`,
 						),
-			activeClaims: phaseRecords
-				.filter((phase) => phase.data.claim?.state === "active")
-				.map((phase) => `phase:${task.id}/${phase.id}`),
 		} satisfies TaskArchiveContext
 	})
 
@@ -217,9 +210,6 @@ const archiveEligibilityError = (context: TaskArchiveContext) => {
 	if (!context.terminal) {
 		return `Task '${context.task.id}' is not terminal (${context.terminalDetails.join(", ")}); only done or dropped tasks can be archived`
 	}
-	if (context.activeClaims.length > 0) {
-		return `Task '${context.task.id}' has active claims (${context.activeClaims.join(", ")}); release or finish them before archiving`
-	}
 	return undefined
 }
 
@@ -735,11 +725,6 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 					const executionUnits: { taskId: string; phaseId?: string }[] = []
 					const phaseRecords: PhaseRecord[] = []
 					for (const task of taskRecords) {
-						if ("claim" in task.data && task.data.claim?.state === "active") {
-							return yield* new ArchiveError({
-								message: `Task '${task.id}' has an active claim; release or finish it before archiving`,
-							})
-						}
 						if ("phases" in task.data) {
 							for (const phase of task.data.phases) {
 								const record = yield* (yield* PhaseService).show(
@@ -747,11 +732,6 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 									phase.id,
 									root,
 								)
-								if (record.data.claim?.state === "active") {
-									return yield* new ArchiveError({
-										message: `Phase '${phase.id}' has an active claim; release or finish it before archiving`,
-									})
-								}
 								phaseRecords.push(record)
 								executionUnits.push({ taskId: task.id, phaseId: phase.id })
 							}
@@ -910,13 +890,6 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 							})
 							continue
 						}
-						if (context.activeClaims.length > 0) {
-							skipped.set(task.id, {
-								code: "active-claim",
-								details: context.activeClaims,
-							})
-							continue
-						}
 						const destination = archivedTaskDirectory(root, task.id)
 						if (yield* fs.exists(destination)) {
 							skipped.set(task.id, {
@@ -1398,11 +1371,6 @@ export class ArchiveService extends Effect.Service<ArchiveService>()(
 					const declaration = task.data.phases.find(
 						(candidate) => candidate.id === id,
 					)!
-					if (phase.data.claim?.state === "active") {
-						return yield* new ArchiveError({
-							message: `Phase '${id}' has an active claim; release or finish it before archiving`,
-						})
-					}
 					const dependent = task.data.phases.find((candidate) =>
 						candidate.dependsOn?.includes(id),
 					)

package/src/services/FileSystemService.ts

@@ -245,6 +245,7 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					readonly forwardOutput?: boolean
 					readonly passthrough?: boolean
 					readonly env?: Record<string, string>
+					readonly timeoutMs?: number
 				},
 			) =>
 				pipe(
@@ -264,6 +265,7 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 								? "tee"
 								: "pipe",
 						env: options?.env,
+						timeoutMs: options?.timeoutMs,
 					}),
 					Effect.mapError(
 						(processError) =>

package/src/services/GraphMutationService.ts

@@ -376,15 +376,6 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Task '${id}' has multiple phases; update execution metadata on a phase instead`,
 						})
 					}
-					if (
-						executionChange &&
-						"claim" in record.data &&
-						record.data.claim?.state === "active"
-					) {
-						return yield* new GraphMutationError({
-							message: `Task '${id}' has an active claim; release or finish it before changing execution metadata`,
-						})
-					}
 					if (
 						updates.pr &&
 						"completion" in record.data &&
@@ -526,11 +517,6 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 							message: `Phase '${id}' has materialized code; remove its worktree with Agency before changing execution metadata`,
 						})
 					}
-					if (executionChange && record.data.claim?.state === "active") {
-						return yield* new GraphMutationError({
-							message: `Phase '${id}' has an active claim; release or finish it before changing execution metadata`,
-						})
-					}
 					if (updates.pr && record.data.completion) {
 						return yield* new GraphMutationError({
 							message:
@@ -842,10 +828,6 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						return yield* new GraphMutationError({
 							message: `Task '${newId}' already exists`,
 						})
-					if ("claim" in task.data && task.data.claim?.state === "active")
-						return yield* new GraphMutationError({
-							message: `Task '${id}' has an active claim; release or finish it before renaming`,
-						})
 					if (yield* fs.isDirectory(join(from, "code")))
 						return yield* new GraphMutationError({
 							message: `Task '${id}' has a materialized worktree; remove it with Agency before renaming`,
@@ -859,10 +841,6 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 								root,
 							)
 							movedPhases.push(record)
-							if (record.data.claim?.state === "active")
-								return yield* new GraphMutationError({
-									message: `Phase '${phase.id}' has an active claim; release or finish it before renaming task '${id}'`,
-								})
 							if (yield* fs.isDirectory(join(dirname(record.path), "code")))
 								return yield* new GraphMutationError({
 									message: `Phase '${phase.id}' has a materialized worktree; remove it with Agency before renaming task '${id}'`,
@@ -952,10 +930,6 @@ export class GraphMutationService extends Effect.Service<GraphMutationService>()
 						})
 					}
 					const phase = yield* phases.show(taskId, id, root)
-					if (phase.data.claim?.state === "active")
-						return yield* new GraphMutationError({
-							message: `Phase '${id}' has an active claim; release or finish it before renaming`,
-						})
 					const from = dirname(phase.path)
 					const to = join(dirname(from), newId)
 					if (yield* fs.exists(to))

package/src/services/GraphService.test.ts

@@ -230,7 +230,7 @@ describe("GraphService", () => {
 		expect(calls).toBe(0)
 	})
 
-	test("never reports claimed or terminal execution units as ready", async () => {
+	test("never reports active or terminal execution units as ready", async () => {
 		const root = await createWorkbase()
 		roots.push(root)
 		const path = "tasks/ship/phases/implement/PHASE.md"

package/src/services/IntegrationService.test.ts

@@ -177,7 +177,7 @@ describe("IntegrationService", () => {
 			"agency task status <task> dropped --if-revision <revision> --json",
 			"Continue already materialized work",
 			"agency pr create <task> [phase]",
-			"agency finish <task> [phase] --session-id <id>",
+			"agency task status <task> done --if-revision <revision> --no-pull-request",
 			"agency task create <slug> --multi-phase",
 			"agency task handoff <investigation-task> <new-task>",
 			"agency review refresh <task> --if-revision <revision> --json",
@@ -626,7 +626,7 @@ describe("IntegrationService", () => {
 		)
 		expect(body).toContain("Never invent entity IDs")
 		expect(body).toContain("Preserve parent backlinks")
-		expect(body).toContain("dirty-worktree, active-claim, revision")
+		expect(body).toContain("dirty-worktree, revision")
 		expect(body).toContain("`agency work` is the human launch flow")
 		expect(body).toContain("Agency worker launch target: <target>.")
 		expect(body).toContain("environment variables and a generated")
@@ -636,7 +636,7 @@ describe("IntegrationService", () => {
 		)
 		expect(body).toMatch(/If\s+the prompt\s+and context disagree/)
 		expect(body).toContain("marks execution work")
-		expect(body).toContain("without creating a claim")
+		expect(body).toContain("marks execution work")
 		expect(body).toContain("formatting, type checks, build, dead-code checks")
 		expect(body).toContain("Review and commit the diff")
 		expect(body).toContain("Use `agency push`")
@@ -650,7 +650,7 @@ describe("IntegrationService", () => {
 		expect(body).toContain("marking it ready")
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
-		expect(body).toContain("`agency finish`")
+		expect(body).toContain("update status")
 		expect(body).toContain("`agency sync`")
 		expect(body).toContain("`--no-pull-request --summary <text>`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")

package/src/services/LifecycleTransaction.ts

@@ -262,7 +262,11 @@ export const runLifecycleTransaction = ({
 					})
 				}
 			} catch (cause) {
-				if (cause instanceof LifecycleTransactionError) throw cause
+				if (
+					cause instanceof LifecycleTransactionError ||
+					cause instanceof RevisionConflictError
+				)
+					throw cause
 				const rollbackErrors: unknown[] = []
 				for (const step of [...completed].reverse()) {
 					if (!step.rollback) continue

package/src/services/PhaseService.ts

@@ -230,7 +230,6 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							base: taskData.base,
 							pr: taskData.pr,
 							status: taskData.status,
-							...(taskData.claim ? { claim: taskData.claim } : {}),
 							...(taskData.completion
 								? { completion: taskData.completion }
 								: {}),
@@ -515,16 +514,10 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 					const validStatus = yield* decodeStatus(status)
 					if (validStatus === "delegated") {
 						return yield* new PhaseError({
-							message:
-								"Delegation requires explicit ownership; use 'agency claim'",
+							message: "Delegated status cannot be set directly",
 						})
 					}
 					const record = yield* service.show(taskId, id, startPath)
-					if (record.data.claim?.state === "active") {
-						return yield* new PhaseError({
-							message: `Phase '${id}' has an active claim; use agency release or agency finish`,
-						})
-					}
 					if (nonPrCompletion && validStatus !== "done") {
 						return yield* new PhaseError({
 							message: "Non-PR completion is valid only with a done status",