@markjaquith/agency 2.13.0 → 2.15.0

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'")
+	})
+})

package/src/services/ClaimService.ts

@@ -0,0 +1,446 @@
+import { Schema, TreeFormatter } from "@effect/schema"
+import { Data, Effect, Either } from "effect"
+import { randomUUID } from "node:crypto"
+import {
+	open,
+	readFile,
+	rename,
+	stat,
+	unlink,
+	writeFile,
+} from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+import { PhaseService } from "./PhaseService"
+import { TaskService } from "./TaskService"
+import { WorkbaseService } from "./WorkbaseService"
+import { FileSystemService } from "./FileSystemService"
+import { documentRevision } from "../workbase/document-revision"
+import {
+	formatMarkdownDocument,
+	parseFrontmatterSync,
+} from "../workbase/frontmatter"
+import {
+	PhaseFrontmatter,
+	TaskFrontmatter,
+	type ClaimRecord,
+	type PhaseFrontmatter as PhaseData,
+	type TaskFrontmatter as TaskData,
+} from "../workbase/schemas"
+
+class ClaimError extends Data.TaggedError("ClaimError")<{
+	readonly message: string
+	readonly target?: string
+}> {}
+
+class RevisionConflictError extends Data.TaggedError("RevisionConflictError")<{
+	readonly message: string
+	readonly target: string
+	readonly expectedRevision: string
+	readonly actualRevision: string
+	readonly claim?: ClaimRecord
+}> {}
+
+class ClaimConflictError extends Data.TaggedError("ClaimConflictError")<{
+	readonly message: string
+	readonly target: string
+	readonly currentRevision: string
+	readonly claim?: ClaimRecord
+	readonly legacyStatus?: "working" | "delegated"
+}> {}
+
+class ClaimOwnershipError extends Data.TaggedError("ClaimOwnershipError")<{
+	readonly message: string
+	readonly target: string
+	readonly currentRevision: string
+	readonly sessionId: string
+	readonly claim?: ClaimRecord
+}> {}
+
+interface ClaimTarget {
+	readonly kind: "task" | "phase"
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly path: string
+	readonly label: string
+}
+
+interface ClaimInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly claimant: string
+	readonly runner: string
+	readonly sessionId: string
+	readonly revision: string
+	readonly expiresAt?: string
+	readonly now?: Date
+}
+
+interface OwnedClaimInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly sessionId: string
+	readonly revision: string
+	readonly now?: Date
+}
+
+interface FinishInput extends OwnedClaimInput {
+	readonly outcome: "done" | "dropped"
+}
+
+type SingleTaskData = Extract<TaskData, { readonly repo: string }>
+type ExecutionData = SingleTaskData | PhaseData
+
+const isTaggedClaimError = (
+	error: unknown,
+): error is
+	| ClaimError
+	| RevisionConflictError
+	| ClaimConflictError
+	| ClaimOwnershipError =>
+	typeof error === "object" &&
+	error !== null &&
+	"_tag" in error &&
+	typeof error._tag === "string" &&
+	[
+		"ClaimError",
+		"RevisionConflictError",
+		"ClaimConflictError",
+		"ClaimOwnershipError",
+	].includes(error._tag)
+
+const decodeExecution = (target: ClaimTarget, input: unknown) => {
+	const schema: Schema.Schema<any> =
+		target.kind === "task" ? TaskFrontmatter : PhaseFrontmatter
+	const result = Schema.decodeUnknownEither(schema, {
+		errors: "all",
+		onExcessProperty: "error",
+	})(input)
+	if (Either.isLeft(result)) {
+		throw new ClaimError({
+			target: target.label,
+			message: TreeFormatter.formatErrorSync(result.left),
+		})
+	}
+	if (target.kind === "task" && "phases" in result.right) {
+		throw new ClaimError({
+			target: target.label,
+			message: `Task '${target.taskId}' has multiple phases; claim a phase instead`,
+		})
+	}
+	return result.right as ExecutionData
+}
+
+const assertRevision = (revision: string) => {
+	if (!/^[a-f0-9]{64}$/.test(revision)) {
+		throw new ClaimError({
+			message: "Revision must be a 64-character SHA-256 hash",
+		})
+	}
+}
+
+const assertIdentity = (label: string, value: string) => {
+	if (!value.trim())
+		throw new ClaimError({ message: `${label} must not be empty` })
+}
+
+const isIsoTimestamp = (value: string) =>
+	/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value) &&
+	Number.isFinite(Date.parse(value))
+
+const isUnexpired = (claim: ClaimRecord, now: Date) =>
+	claim.state === "active" &&
+	(claim.expiresAt === undefined || Date.parse(claim.expiresAt) > now.getTime())
+
+const acquireLock = async (path: string) => {
+	const lockPath = `${path}.claim.lock`
+	for (let attempt = 0; attempt < 1_750; attempt += 1) {
+		try {
+			const handle = await open(lockPath, "wx")
+			return { handle, lockPath }
+		} catch (error) {
+			if (
+				!(error instanceof Error) ||
+				!("code" in error) ||
+				error.code !== "EEXIST"
+			) {
+				throw error
+			}
+			try {
+				const lock = await stat(lockPath)
+				if (Date.now() - lock.mtimeMs > 30_000) await unlink(lockPath)
+			} catch {
+				// Another process released the lock between checks.
+			}
+			await Bun.sleep(20)
+		}
+	}
+	throw new ClaimError({ message: `Timed out waiting to update ${path}` })
+}
+
+const updateAtomically = async <T>(
+	target: ClaimTarget,
+	expectedRevision: string,
+	update: (
+		data: ExecutionData,
+		now: Date,
+	) => T & {
+		readonly data: ExecutionData
+	},
+	now: Date,
+) => {
+	assertRevision(expectedRevision)
+	const { handle, lockPath } = await acquireLock(target.path)
+	let temporaryPath: string | undefined
+	try {
+		const content = await readFile(target.path, "utf8")
+		const actualRevision = documentRevision(content)
+		const parsed = parseFrontmatterSync(content, target.path)
+		const current = decodeExecution(target, parsed.data)
+		if (actualRevision !== expectedRevision) {
+			throw new RevisionConflictError({
+				target: target.label,
+				expectedRevision,
+				actualRevision,
+				claim: current.claim,
+				message: `Revision conflict for ${target.label}`,
+			})
+		}
+		const result = update(current, now)
+		const updatedContent = formatMarkdownDocument(result.data, parsed.body)
+		temporaryPath = join(
+			dirname(target.path),
+			`.${basename(target.path)}.${process.pid}.${randomUUID()}.tmp`,
+		)
+		await writeFile(temporaryPath, updatedContent, { flag: "wx" })
+		await rename(temporaryPath, target.path)
+		temporaryPath = undefined
+		return {
+			...result,
+			target: target.label,
+			previousRevision: actualRevision,
+			revision: documentRevision(updatedContent),
+		}
+	} finally {
+		if (temporaryPath) await unlink(temporaryPath).catch(() => undefined)
+		await handle.close().catch(() => undefined)
+		await unlink(lockPath).catch(() => undefined)
+	}
+}
+
+const operation = <T>(run: () => Promise<T>) =>
+	Effect.tryPromise({
+		try: run,
+		catch: (error) =>
+			isTaggedClaimError(error)
+				? error
+				: new ClaimError({
+						message: error instanceof Error ? error.message : String(error),
+					}),
+	})
+
+export class ClaimService extends Effect.Service<ClaimService>()(
+	"ClaimService",
+	{
+		sync: () => ({
+			inspect: (
+				taskId: string,
+				phaseId?: string,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const fs = yield* FileSystemService
+					const workbase = yield* WorkbaseService
+					const tasks = yield* TaskService
+					const phases = yield* PhaseService
+					const root = yield* workbase.discover(startPath)
+					const task = yield* tasks.show(taskId, root)
+					const phase = phaseId
+						? yield* phases.show(task.id, phaseId, root)
+						: undefined
+					const target: ClaimTarget = phaseId
+						? {
+								kind: "phase",
+								taskId: task.id,
+								phaseId,
+								path: phase!.path,
+								label: `phase '${task.id}/${phaseId}'`,
+							}
+						: {
+								kind: "task",
+								taskId: task.id,
+								path: task.path,
+								label: `task '${task.id}'`,
+							}
+					if (!phaseId && "phases" in task.data) {
+						return yield* new ClaimError({
+							target: target.label,
+							message: `Task '${task.id}' has multiple phases; claim a phase instead`,
+						})
+					}
+					const content = yield* fs.readFile(target.path)
+					const parsed = parseFrontmatterSync(content, target.path)
+					return {
+						target,
+						revision: documentRevision(content),
+						data: decodeExecution(target, parsed.data),
+					}
+				}),
+
+			claim: (input: ClaimInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					for (const [label, value] of [
+						["Claimant", input.claimant],
+						["Runner", input.runner],
+						["Session ID", input.sessionId],
+					] as const) {
+						assertIdentity(label, value)
+					}
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					const now = input.now ?? new Date()
+					if (
+						input.expiresAt !== undefined &&
+						(!isIsoTimestamp(input.expiresAt) ||
+							Date.parse(input.expiresAt) <= now.getTime())
+					) {
+						return yield* new ClaimError({
+							message: "Claim expiry must be a future ISO-8601 timestamp",
+						})
+					}
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, operationTime) => {
+								const replacingExpiredClaim =
+									data.claim?.state === "active" &&
+									!isUnexpired(data.claim, operationTime)
+								if (data.claim && isUnexpired(data.claim, operationTime)) {
+									throw new ClaimConflictError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										claim: data.claim,
+										message: `${inspected.target.label} is claimed by '${data.claim.runner}'`,
+									})
+								}
+								if (
+									!data.claim &&
+									(data.status === "working" || data.status === "delegated")
+								) {
+									throw new ClaimConflictError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										legacyStatus: data.status,
+										message: `${inspected.target.label} has legacy '${data.status}' ownership; reopen it before claiming`,
+									})
+								}
+								if (data.status !== "open" && !replacingExpiredClaim) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: `${inspected.target.label} cannot be claimed while ${data.status}`,
+									})
+								}
+								const claim: ClaimRecord = {
+									claimant: input.claimant.trim(),
+									runner: input.runner.trim(),
+									sessionId: input.sessionId.trim(),
+									startedAt: operationTime.toISOString(),
+									targetRevision: input.revision,
+									...(input.expiresAt ? { expiresAt: input.expiresAt } : {}),
+									state: "active",
+								}
+								return { data: { ...data, status: "working", claim }, claim }
+							},
+							now,
+						),
+					)
+				}),
+
+			release: (input: OwnedClaimInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					assertIdentity("Session ID", input.sessionId)
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, now) => {
+								if (
+									!data.claim ||
+									data.claim.state !== "active" ||
+									data.claim.sessionId !== input.sessionId
+								) {
+									throw new ClaimOwnershipError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										sessionId: input.sessionId,
+										claim: data.claim,
+										message: `Session '${input.sessionId}' does not own ${inspected.target.label}`,
+									})
+								}
+								const claim: ClaimRecord = {
+									...data.claim,
+									state: "released",
+									releasedAt: now.toISOString(),
+								}
+								return { data: { ...data, status: "open", claim }, claim }
+							},
+							input.now ?? new Date(),
+						),
+					)
+				}),
+
+			finish: (input: FinishInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					assertIdentity("Session ID", input.sessionId)
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, now) => {
+								if (
+									!data.claim ||
+									data.claim.state !== "active" ||
+									data.claim.sessionId !== input.sessionId
+								) {
+									throw new ClaimOwnershipError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										sessionId: input.sessionId,
+										claim: data.claim,
+										message: `Session '${input.sessionId}' does not own ${inspected.target.label}`,
+									})
+								}
+								const claim: ClaimRecord = {
+									...data.claim,
+									state: "finished",
+									finishedAt: now.toISOString(),
+									outcome: input.outcome,
+								}
+								return {
+									data: { ...data, status: input.outcome, claim },
+									claim,
+								}
+							},
+							input.now ?? new Date(),
+						),
+					)
+				}),
+		}),
+	},
+) {}