@markjaquith/agency 2.13.0 → 2.15.0

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/utils/chooser.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { choose, type ChooserIO } from "./chooser"
+
+const choices = [
+	{ key: "first-key", label: "\x1b[32mFirst\x1b[0m", value: 1 },
+	{ key: "second key", label: "Second", value: 2 },
+]
+
+const createIO = (
+	overrides: Partial<ChooserIO> = {},
+): ChooserIO & { readonly writes: string[]; readonly inputs: string[] } => {
+	const writes: string[] = []
+	const inputs: string[] = []
+	return {
+		inputIsTTY: true,
+		outputIsTTY: true,
+		color: false,
+		write: (message) => writes.push(message),
+		question: async () => "1",
+		run: async (_command, input) => {
+			inputs.push(input)
+			return { exitCode: 0, stdout: "first-key\n" }
+		},
+		...overrides,
+		writes,
+		inputs,
+	}
+}
+
+describe("chooser", () => {
+	test("offers a plain-text numbered chooser on a TTY", async () => {
+		const io = createIO({ question: async () => "2" })
+
+		const result = await Effect.runPromise(
+			choose("Pick one", choices, undefined, io),
+		)
+
+		expect(result).toBe(2)
+		expect(io.writes.join("")).toBe("Pick one\n  1. First\n  2. Second\n")
+	})
+
+	test("preserves colors when enabled", async () => {
+		const io = createIO({ color: true })
+
+		await Effect.runPromise(choose("Pick one", choices, undefined, io))
+
+		expect(io.writes.join("")).toContain("\x1b[32mFirst\x1b[0m")
+	})
+
+	test("passes generic records to an external argv command", async () => {
+		const io = createIO()
+
+		const result = await Effect.runPromise(
+			choose("Pick one", choices, ["custom-chooser", "--flag"], io),
+		)
+
+		expect(result).toBe(1)
+		expect(io.inputs).toEqual(["first-key\tFirst\nsecond key\tSecond\n"])
+	})
+
+	test("accepts a selected record from fzf or gum", async () => {
+		const io = createIO({
+			run: async () => ({ exitCode: 0, stdout: "second key\tSecond\n" }),
+		})
+
+		expect(
+			await Effect.runPromise(choose("Pick", choices, ["gum", "filter"], io)),
+		).toBe(2)
+	})
+
+	test("treats native and external cancellation as no selection", async () => {
+		const native = createIO({ question: async () => "q" })
+		const external = createIO({
+			run: async () => ({ exitCode: 130, stdout: "" }),
+		})
+
+		expect(
+			await Effect.runPromise(choose("Pick", choices, undefined, native)),
+		).toBeNull()
+		expect(
+			await Effect.runPromise(choose("Pick", choices, ["chooser"], external)),
+		).toBeNull()
+	})
+
+	test("uses one typed error for unavailable input and invalid keys", async () => {
+		const nonTTY = createIO({ inputIsTTY: false })
+		const unknownKey = createIO({
+			run: async () => ({ exitCode: 0, stdout: "missing\n" }),
+		})
+
+		const unavailable = await Effect.runPromise(
+			Effect.flip(choose("Pick", choices, undefined, nonTTY)),
+		)
+		const invalid = await Effect.runPromise(
+			Effect.flip(choose("Pick", choices, ["chooser"], unknownKey)),
+		)
+
+		expect(unavailable).toMatchObject({
+			name: "ChooserError",
+			reason: "input-unavailable",
+		})
+		expect(invalid).toMatchObject({
+			name: "ChooserError",
+			reason: "invalid-selection",
+		})
+	})
+})

package/src/utils/chooser.ts

@@ -0,0 +1,222 @@
+import { Effect } from "effect"
+import { createInterface } from "node:readline/promises"
+
+export interface Choice<T> {
+	readonly key: string
+	readonly label: string
+	readonly plainLabel?: string
+	readonly value: T
+}
+
+export type ChooserErrorReason =
+	| "invalid-choices"
+	| "input-unavailable"
+	| "invalid-selection"
+	| "command-failed"
+
+export class ChooserError extends Error {
+	override readonly name = "ChooserError"
+
+	constructor(
+		readonly reason: ChooserErrorReason,
+		message: string,
+		options?: ErrorOptions,
+	) {
+		super(message, options)
+	}
+}
+
+interface ExternalResult {
+	readonly exitCode: number
+	readonly stdout: string
+}
+
+export interface ChooserIO {
+	readonly inputIsTTY: boolean
+	readonly outputIsTTY: boolean
+	readonly color: boolean
+	readonly write: (message: string) => void
+	readonly question: (prompt: string) => Promise<string>
+	readonly run: (
+		command: readonly string[],
+		input: string,
+	) => Promise<ExternalResult>
+}
+
+const stripAnsi = (value: string) =>
+	value.replace(
+		/[\u001B\u009B][[\]()#;?]*(?:(?:(?:[a-zA-Z\d]*(?:;[-a-zA-Z\d/#&.:=?%@~_]+)*)?\u0007)|(?:(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]))/g,
+		"",
+	)
+
+const defaultIO = (): ChooserIO => ({
+	inputIsTTY: Boolean(process.stdin.isTTY),
+	outputIsTTY: Boolean(process.stderr.isTTY),
+	color:
+		Boolean(process.stderr.isTTY) &&
+		process.env.NO_COLOR === undefined &&
+		process.env.TERM !== "dumb",
+	write: (message) => process.stderr.write(message),
+	question: async (prompt) => {
+		const input = createInterface({
+			input: process.stdin,
+			output: process.stderr,
+		})
+		try {
+			return await input.question(prompt)
+		} finally {
+			input.close()
+		}
+	},
+	run: async (command, input) => {
+		const child = Bun.spawn([...command], {
+			stdin: new Blob([input]),
+			stdout: "pipe",
+			stderr: "inherit",
+		})
+		const [exitCode, stdout] = await Promise.all([
+			child.exited,
+			new Response(child.stdout).text(),
+		])
+		return { exitCode, stdout }
+	},
+})
+
+const displayLabel = (choice: Choice<unknown>, color: boolean) => {
+	const normalized = (
+		color ? choice.label : (choice.plainLabel ?? choice.label)
+	).replace(/[\r\n]+/g, " ")
+	return color ? normalized : stripAnsi(normalized)
+}
+
+const validateChoices = <T>(choices: readonly Choice<T>[]) => {
+	if (choices.length === 0) {
+		throw new ChooserError(
+			"invalid-choices",
+			"Cannot choose from an empty list",
+		)
+	}
+	const keys = new Set<string>()
+	for (const choice of choices) {
+		if (!choice.key || /[\t\r\n]/.test(choice.key)) {
+			throw new ChooserError(
+				"invalid-choices",
+				"Chooser keys must be non-empty and cannot contain tabs or newlines",
+			)
+		}
+		if (keys.has(choice.key)) {
+			throw new ChooserError(
+				"invalid-choices",
+				`Duplicate chooser key: ${choice.key}`,
+			)
+		}
+		keys.add(choice.key)
+	}
+}
+
+const selectedChoice = <T>(key: string, choices: readonly Choice<T>[]) => {
+	const selected = choices.find((choice) => choice.key === key)
+	if (!selected) {
+		throw new ChooserError(
+			"invalid-selection",
+			`Chooser returned an unknown key: ${key}`,
+		)
+	}
+	return selected.value
+}
+
+const externalChoice = async <T>(
+	choices: readonly Choice<T>[],
+	command: readonly string[],
+	io: ChooserIO,
+) => {
+	let result: ExternalResult
+	try {
+		const records = `${choices
+			.map((choice) => `${choice.key}\t${displayLabel(choice, io.color)}`)
+			.join("\n")}\n`
+		result = await io.run(command, records)
+	} catch (cause) {
+		throw new ChooserError(
+			"command-failed",
+			`Failed to run chooser command: ${command.join(" ")}`,
+			{ cause },
+		)
+	}
+	if (result.exitCode === 1 || result.exitCode === 130) return null
+	if (result.exitCode !== 0) {
+		throw new ChooserError(
+			"command-failed",
+			`Chooser command exited with code ${result.exitCode}`,
+		)
+	}
+	const output = result.stdout.replace(/\r?\n$/, "")
+	if (!output) return null
+	if (/[\r\n]/.test(output)) {
+		throw new ChooserError(
+			"invalid-selection",
+			"Chooser command returned more than one key",
+		)
+	}
+	const key = output.split("\t", 1)[0] ?? ""
+	return selectedChoice(key, choices)
+}
+
+const nativeChoice = async <T>(
+	choices: readonly Choice<T>[],
+	prompt: string,
+	io: ChooserIO,
+) => {
+	if (!io.inputIsTTY || !io.outputIsTTY) {
+		throw new ChooserError(
+			"input-unavailable",
+			"Interactive selection requires a terminal; provide an explicit value or use --no-input",
+		)
+	}
+	io.write(`${prompt}\n`)
+	for (const [index, choice] of choices.entries()) {
+		io.write(`  ${index + 1}. ${displayLabel(choice, io.color)}\n`)
+	}
+	let answer: string
+	try {
+		answer = (
+			await io.question(`Select [1-${choices.length}] (q to cancel): `)
+		).trim()
+	} catch (cause) {
+		if (cause instanceof Error && cause.name === "AbortError") return null
+		throw new ChooserError("input-unavailable", "Failed to read selection", {
+			cause,
+		})
+	}
+	if (!answer || answer.toLowerCase() === "q") return null
+	if (!/^\d+$/.test(answer)) {
+		throw new ChooserError("invalid-selection", `Invalid selection: ${answer}`)
+	}
+	const selected = choices[Number.parseInt(answer, 10) - 1]
+	if (!selected) {
+		throw new ChooserError(
+			"invalid-selection",
+			`Selection must be between 1 and ${choices.length}`,
+		)
+	}
+	return selected.value
+}
+
+export const choose = <T>(
+	prompt: string,
+	choices: readonly Choice<T>[],
+	command?: readonly string[],
+	io: ChooserIO = defaultIO(),
+): Effect.Effect<T | null, ChooserError> =>
+	Effect.tryPromise({
+		try: async () => {
+			validateChoices(choices)
+			return command
+				? await externalChoice(choices, command, io)
+				: await nativeChoice(choices, prompt, io)
+		},
+		catch: (cause) =>
+			cause instanceof ChooserError
+				? cause
+				: new ChooserError("input-unavailable", "Selection failed", { cause }),
+	})

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) =>

package/src/workbase/schemas.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test"
 import { Schema } from "@effect/schema"
 import {
 	EntityId,
+	ClaimRecord,
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	TaskFrontmatter,
@@ -154,6 +155,32 @@ describe("work status", () => {
 	})
 })
 
+describe("claim records", () => {
+	const record = {
+		claimant: "orchestrator",
+		runner: "agent",
+		sessionId: "job-1",
+		startedAt: "2026-07-17T12:00:00.000Z",
+		targetRevision: "0".repeat(64),
+		expiresAt: "2026-07-17T13:00:00.000Z",
+		state: "active" as const,
+	}
+
+	test("accepts explicit ownership and revision metadata", () => {
+		expect(Schema.decodeUnknownSync(ClaimRecord)(record)).toEqual(record)
+	})
+
+	test("rejects malformed timestamps, revisions, and empty identities", () => {
+		for (const invalid of [
+			{ ...record, claimant: "" },
+			{ ...record, startedAt: "today" },
+			{ ...record, targetRevision: "abc" },
+		]) {
+			expect(() => Schema.decodeUnknownSync(ClaimRecord)(invalid)).toThrow()
+		}
+	})
+})
+
 describe("workbase registry", () => {
 	test("accepts registered paths", () => {
 		expect(
@@ -257,4 +284,16 @@ describe("schema boundaries", () => {
 			).not.toThrow()
 		}
 	})
+
+	test("accepts a configured chooser argv", () => {
+		expect(
+			Schema.decodeUnknownSync(WorkbaseConfig)({
+				version: 2,
+				chooserCommand: ["fzf", "--accept-nth=1"],
+			}),
+		).toEqual({
+			version: 2,
+			chooserCommand: ["fzf", "--accept-nth=1"],
+		})
+	})
 })

package/src/workbase/schemas.ts

@@ -23,6 +23,25 @@ export const WorkStatus = Schema.Literal(
 	"dropped",
 )
 
+const IsoTimestamp = NonEmptyString.pipe(
+	Schema.pattern(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/),
+)
+
+const DocumentRevision = Schema.String.pipe(Schema.pattern(/^[a-f0-9]{64}$/))
+
+export const ClaimRecord = Schema.Struct({
+	claimant: NonEmptyString,
+	runner: NonEmptyString,
+	sessionId: NonEmptyString,
+	startedAt: IsoTimestamp,
+	targetRevision: DocumentRevision,
+	expiresAt: Schema.optional(IsoTimestamp),
+	state: Schema.Literal("active", "released", "finished"),
+	releasedAt: Schema.optional(IsoTimestamp),
+	finishedAt: Schema.optional(IsoTimestamp),
+	outcome: Schema.optional(Schema.Literal("done", "dropped")),
+})
+
 const Url = NonEmptyString.pipe(Schema.pattern(/^[a-zA-Z][a-zA-Z0-9+.-]*:/))
 
 const GitHubPullRequestUrl = NonEmptyString.pipe(
@@ -31,6 +50,7 @@ const GitHubPullRequestUrl = NonEmptyString.pipe(
 
 export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
+	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 	worktreeCreateCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
 })
 
@@ -51,6 +71,7 @@ const ExecutionUnit = {
 	base: NonEmptyString,
 	pr: Schema.NullOr(GitHubPullRequestUrl),
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
+	claim: Schema.optional(ClaimRecord),
 }
 
 export const EpicFrontmatter = Schema.Struct({
@@ -89,6 +110,7 @@ export type WorkbaseRegistry = Schema.Schema.Type<typeof WorkbaseRegistry>
 export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
+export type ClaimRecord = Schema.Schema.Type<typeof ClaimRecord>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>

package/src/workbase/work-target.test.ts

@@ -80,5 +80,15 @@ describe("work target choices", () => {
 			"task",
 			"task",
 		])
+		expect(choices.map((choice) => choice.plainLabel)).toEqual([
+			"epic delivery - Ship the release",
+			"  task multi",
+			"    [working] phase build",
+			"    [done] phase verify",
+			"    [dropped] phase unlisted",
+			"  [done] task single",
+			"[open] task standalone - Independent work",
+			"[delegated] task delegated",
+		])
 	})
 })