@markjaquith/agency 2.13.0 → 2.14.0

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"
@@ -133,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),
@@ -171,6 +196,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]) =>

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,7 +261,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 = {}) =>

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

package/src/services/ClaimService.test.ts

@@ -0,0 +1,270 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { ClaimService } from "./ClaimService"
+import { PhaseService } from "./PhaseService"
+import { TaskService } from "./TaskService"
+
+const at = (value: string) => new Date(value)
+
+describe("claim service", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "single",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/single",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	const inspect = (taskId = "single", phaseId?: string) =>
+		runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) => service.inspect(taskId, phaseId, root)),
+			),
+		)
+
+	const claim = async (
+		revision: string,
+		sessionId = "session-1",
+		now = at("2026-07-17T12:00:00.000Z"),
+		expiresAt?: string,
+	) =>
+		runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "single",
+							claimant: "orchestrator-1",
+							runner: "agent-1",
+							sessionId,
+							revision,
+							now,
+							...(expiresAt ? { expiresAt } : {}),
+						},
+						root,
+					),
+				),
+			),
+		)
+
+	test("records ownership and guarded release and finish transitions", async () => {
+		const initial = await inspect()
+		const acquired = await claim(
+			initial.revision,
+			"session-1",
+			at("2026-07-17T12:00:00.000Z"),
+			"2026-07-17T13:00:00.000Z",
+		)
+
+		expect(acquired.claim).toEqual({
+			claimant: "orchestrator-1",
+			runner: "agent-1",
+			sessionId: "session-1",
+			startedAt: "2026-07-17T12:00:00.000Z",
+			targetRevision: initial.revision,
+			expiresAt: "2026-07-17T13:00:00.000Z",
+			state: "active",
+		})
+		expect((await inspect()).data.status).toBe("working")
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("single", "done", root),
+					),
+				),
+			),
+		).rejects.toThrow("has an active claim")
+
+		const released = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.release(
+						{
+							taskId: "single",
+							sessionId: "session-1",
+							revision: acquired.revision,
+							now: at("2026-07-17T12:15:00.000Z"),
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(released.data.status).toBe("open")
+		expect(released.claim).toMatchObject({
+			state: "released",
+			releasedAt: "2026-07-17T12:15:00.000Z",
+		})
+
+		const reacquired = await claim(
+			released.revision,
+			"session-2",
+			at("2026-07-17T12:20:00.000Z"),
+		)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "single",
+							sessionId: "session-2",
+							revision: reacquired.revision,
+							outcome: "done",
+							now: at("2026-07-17T12:45:00.000Z"),
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(finished.data.status).toBe("done")
+		expect(finished.claim).toMatchObject({
+			state: "finished",
+			finishedAt: "2026-07-17T12:45:00.000Z",
+			outcome: "done",
+		})
+	})
+
+	test("returns structured ownership and revision conflicts", async () => {
+		const initial = await inspect()
+		const acquired = await claim(initial.revision)
+
+		await expect(claim(acquired.revision, "session-2")).rejects.toThrow(
+			"is claimed by 'agent-1'",
+		)
+		await expect(
+			runTestEffect(
+				ClaimService.pipe(
+					Effect.flatMap((service) =>
+						service.release(
+							{
+								taskId: "single",
+								sessionId: "session-2",
+								revision: acquired.revision,
+							},
+							root,
+						),
+					),
+				),
+			),
+		).rejects.toThrow("does not own")
+		await expect(claim(initial.revision, "session-3")).rejects.toThrow(
+			"Revision conflict",
+		)
+	})
+
+	test("serializes concurrent claims and allows expired ownership replacement", async () => {
+		const initial = await inspect()
+		const attempts = await Promise.allSettled([
+			claim(initial.revision, "session-a"),
+			claim(initial.revision, "session-b"),
+		])
+		expect(
+			attempts.filter((result) => result.status === "fulfilled"),
+		).toHaveLength(1)
+		expect(
+			attempts.filter((result) => result.status === "rejected"),
+		).toHaveLength(1)
+		const current = await inspect()
+		expect(current.data.claim?.state).toBe("active")
+
+		await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.release(
+						{
+							taskId: "single",
+							sessionId: current.data.claim!.sessionId,
+							revision: current.revision,
+						},
+						root,
+					),
+				),
+			),
+		)
+		const released = await inspect()
+		const expiring = await claim(
+			released.revision,
+			"expiring",
+			at("2026-07-17T12:00:00.000Z"),
+			"2026-07-17T12:01:00.000Z",
+		)
+		const replacement = await claim(
+			expiring.revision,
+			"replacement",
+			at("2026-07-17T12:02:00.000Z"),
+		)
+		expect(replacement.claim.sessionId).toBe("replacement")
+	})
+
+	test("claims phases and rejects multi-phase task containers", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{ id: "multi", ticketUrl: null, multiPhase: true },
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							taskId: "multi",
+							id: "implementation",
+							repo: "agency",
+							branch: "task/multi",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await expect(inspect("multi")).rejects.toThrow("claim a phase instead")
+		const phase = await inspect("multi", "implementation")
+		const acquired = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "multi",
+							phaseId: "implementation",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "phase-session",
+							revision: phase.revision,
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(acquired.target).toBe("phase 'multi/implementation'")
+	})
+})