@markjaquith/agency 2.13.0 → 2.14.0

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

package/src/services/PhaseService.ts

@@ -193,6 +193,8 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 							branch: task.data.branch,
 							base: task.data.base,
 							pr: task.data.pr,
+							status: task.data.status,
+							...(task.data.claim ? { claim: task.data.claim } : {}),
 						})
 						const firstTitle = firstPhaseId!
 							.split("-")
@@ -340,7 +342,18 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 					const fs = yield* FileSystemService
 					const service = yield* PhaseService
 					const validStatus = yield* decodeStatus(status)
+					if (validStatus === "working" || validStatus === "delegated") {
+						return yield* new PhaseError({
+							message:
+								"Active work and delegation require explicit ownership; use 'agency claim'",
+						})
+					}
 					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 (!canTransitionStatus(record.data.status, validStatus)) {
 						return yield* new PhaseError({
 							message: `Cannot transition phase '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,

package/src/services/TaskPhaseService.test.ts

@@ -234,16 +234,17 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(createdTask.content).toContain("status: open")
-		const task = await runTestEffect(
-			TaskService.pipe(
-				Effect.flatMap((service) =>
-					service.setStatus("single-status", "delegated", root),
+		for (const status of ["working", "delegated"]) {
+			await expect(
+				runTestEffect(
+					TaskService.pipe(
+						Effect.flatMap((service) =>
+							service.setStatus("single-status", status, root),
+						),
+					),
 				),
-			),
-		)
-		expect(task.data.status).toBe("delegated")
-		expect(task.content).toContain("status: delegated")
-		expect(task.content).toContain("Describe the task outcome.")
+			).rejects.toThrow("require explicit ownership")
+		}
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>

package/src/services/TaskService.ts

@@ -207,12 +207,23 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 				const fs = yield* FileSystemService
 				const service = yield* TaskService
 				const validStatus = yield* decodeStatus(status)
+				if (validStatus === "working" || validStatus === "delegated") {
+					return yield* new TaskError({
+						message:
+							"Active work and delegation require explicit ownership; use 'agency claim'",
+					})
+				}
 				const record = yield* service.show(id, startPath)
 				if ("phases" in record.data) {
 					return yield* new TaskError({
 						message: `Task '${id}' has multiple phases; set status on a phase instead`,
 					})
 				}
+				if (record.data.claim?.state === "active") {
+					return yield* new TaskError({
+						message: `Task '${id}' has an active claim; use agency release or agency finish`,
+					})
+				}
 				if (!canTransitionStatus(record.data.status, validStatus)) {
 					return yield* new TaskError({
 						message: `Cannot transition task '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,

package/src/test-utils.ts

@@ -15,6 +15,7 @@ import { ArchiveService } from "./services/ArchiveService"
 import { IntegrationService } from "./services/IntegrationService"
 import { ContextService } from "./services/ContextService"
 import { GraphService } from "./services/GraphService"
+import { ClaimService } from "./services/ClaimService"
 
 export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 
@@ -34,6 +35,7 @@ const TestLayer = Layer.mergeAll(
 	IntegrationService.Default,
 	ContextService.Default,
 	GraphService.Default,
+	ClaimService.Default,
 )
 
 export async function runTestEffect<A, E>(

package/src/workbase/AGENTS.md

@@ -26,8 +26,8 @@ field. Repositories listed in plural `repos` are read-only references.
   `agency integration sync` to update managed agent files explicitly.
 - Keep task-level decisions in `TASK.md` and phase-specific delivery context in
   `PHASE.md`.
-- Keep execution-unit `status` current with `agency task status` or
-  `agency phase status`; `agency work` marks launched work as `working`.
+- Coordinate execution ownership with `agency claim`, `agency release`, and
+  `agency finish`; `agency work` claims execution units before launch.
 - Do not manually create, move, or remove worktrees under `code/`.
 - Use `agency archive`, rather than moving work item folders manually.
 - Do not edit bare repositories or repository symlinks under `repos/`.

package/src/workbase/document-revision.ts

@@ -0,0 +1,2 @@
+export const documentRevision = (content: string) =>
+	new Bun.CryptoHasher("sha256").update(content).digest("hex")

package/src/workbase/frontmatter.ts

@@ -12,65 +12,71 @@ interface ParsedFrontmatter {
 	readonly body: string
 }
 
-export const parseFrontmatter = (content: string, path: string) =>
-	Effect.try({
-		try: (): ParsedFrontmatter => {
-			const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
-			if (!match) {
-				throw new Error("Markdown file must begin with YAML frontmatter")
-			}
+export const parseFrontmatterSync = (
+	content: string,
+	path: string,
+): ParsedFrontmatter => {
+	try {
+		const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)
+		if (!match) {
+			throw new Error("Markdown file must begin with YAML frontmatter")
+		}
+
+		const document = parseDocument(match[1]!, {
+			customTags: [],
+			merge: false,
+			schema: "core",
+			strict: true,
+			uniqueKeys: true,
+			version: "1.2",
+		})
 
-			const document = parseDocument(match[1]!, {
-				customTags: [],
-				merge: false,
-				schema: "core",
-				strict: true,
-				uniqueKeys: true,
-				version: "1.2",
-			})
+		const parseMessages = [...document.errors, ...document.warnings]
+		if (parseMessages.length > 0) {
+			throw new Error(parseMessages.map((error) => error.message).join("; "))
+		}
 
-			const parseMessages = [...document.errors, ...document.warnings]
-			if (parseMessages.length > 0) {
-				throw new Error(parseMessages.map((error) => error.message).join("; "))
-			}
+		let unsupportedFeature: string | null = null
+		visit(document, {
+			Alias: () => {
+				unsupportedFeature = "YAML aliases are not supported"
+			},
+			Node: (_key, node) => {
+				if (node.anchor) {
+					unsupportedFeature = "YAML anchors are not supported"
+				} else if (node.tag && !node.tag.startsWith("tag:yaml.org,2002:")) {
+					unsupportedFeature = "Custom YAML tags are not supported"
+				}
+			},
+		})
 
-			let unsupportedFeature: string | null = null
-			visit(document, {
-				Alias: () => {
-					unsupportedFeature = "YAML aliases are not supported"
-				},
-				Node: (_key, node) => {
-					if (node.anchor) {
-						unsupportedFeature = "YAML anchors are not supported"
-					} else if (node.tag && !node.tag.startsWith("tag:yaml.org,2002:")) {
-						unsupportedFeature = "Custom YAML tags are not supported"
-					}
-				},
-			})
+		if (unsupportedFeature) {
+			throw new Error(unsupportedFeature)
+		}
 
-			if (unsupportedFeature) {
-				throw new Error(unsupportedFeature)
-			}
+		const data = document.toJS({ maxAliasCount: 0 })
+		if (data === null || typeof data !== "object" || Array.isArray(data)) {
+			throw new Error("YAML frontmatter must be a mapping")
+		}
 
-			const data = document.toJS({ maxAliasCount: 0 })
-			if (data === null || typeof data !== "object" || Array.isArray(data)) {
-				throw new Error("YAML frontmatter must be a mapping")
-			}
+		return {
+			data,
+			body: content.slice(match[0].length),
+		}
+	} catch (cause) {
+		throw new FrontmatterParseError({
+			path,
+			message:
+				cause instanceof Error ? cause.message : "Failed to parse frontmatter",
+			cause,
+		})
+	}
+}
 
-			return {
-				data,
-				body: content.slice(match[0].length),
-			}
-		},
-		catch: (cause) =>
-			new FrontmatterParseError({
-				path,
-				message:
-					cause instanceof Error
-						? cause.message
-						: "Failed to parse frontmatter",
-				cause,
-			}),
+export const parseFrontmatter = (content: string, path: string) =>
+	Effect.try({
+		try: () => parseFrontmatterSync(content, path),
+		catch: (error) => error as FrontmatterParseError,
 	})
 
 export const formatMarkdownDocument = (data: object, body: string) =>