@markjaquith/agency 2.30.1 → 2.32.0

package/src/services/EpicService.ts

@@ -10,6 +10,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { documentRevision } from "../workbase/document-revision"
@@ -95,7 +96,7 @@ export class EpicService extends Effect.Service<EpicService>()("EpicService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the epic outcome.`,
+					formatWorkDocumentBody(title, "epic"),
 				)
 				yield* fs.writeFile(path, content)
 				return {

package/src/services/IntegrationService.test.ts

@@ -76,7 +76,8 @@ describe("IntegrationService", () => {
 
 		expect(body).toContain("agency context . --json")
 		expect(body).toContain("authority.writable.checkoutPath")
-		expect(body).toContain("Do not begin execution without a claim")
+		expect(body).toContain("`agency work` is the local launch flow")
+		expect(body).toContain("External orchestrators claim before launching")
 		expect(body).toContain("Run `agency validate`")
 		expect(body).toContain("only with explicit user intent")
 		expect(body).toContain("An execution unit is `working`")

package/src/services/PhaseService.ts

@@ -14,6 +14,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -196,7 +197,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						.join(" ")
 					const content = formatMarkdownDocument(
 						data,
-						`# ${title}\n\nDescribe the phase outcome.`,
+						formatWorkDocumentBody(title, "phase"),
 					)
 
 					if (!isMultiPhase) {
@@ -246,7 +247,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						const firstPhasePath = join(firstDirectory, "PHASE.md")
 						const firstContent = formatMarkdownDocument(
 							firstData,
-							`# ${firstTitle}\n\nDescribe the phase outcome.`,
+							formatWorkDocumentBody(firstTitle, "phase"),
 						)
 						const steps: TransactionStep[] = []
 						if (yield* fs.isDirectory(oldCodePath)) {
@@ -473,10 +474,10 @@ 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") {
+					if (validStatus === "delegated") {
 						return yield* new PhaseError({
 							message:
-								"Active work and delegation require explicit ownership; use 'agency claim'",
+								"Delegation requires explicit ownership; use 'agency claim'",
 						})
 					}
 					const record = yield* service.show(taskId, id, startPath)

package/src/services/PullRequestService.test.ts

@@ -220,7 +220,10 @@ process.exit(${exitCode})
 		const original = await Bun.file(taskPath).text()
 		await Bun.write(
 			taskPath,
-			original.replace("# Example\n\nDescribe the task outcome.", body),
+			original.replace(
+				"# Example\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+				body,
+			),
 		)
 		const url = "https://github.com/example/agency/pull/42"
 		await writeFakeGh({ stdout: `${url}\n` })

package/src/services/ReadinessService.test.ts

@@ -203,6 +203,60 @@ describe("ReadinessService", () => {
 		await service((readiness) =>
 			readiness.guardWorkTarget("phase:ship/implement", root),
 		)
+		expect(
+			[
+				...(await service((readiness) => readiness.getWorkTargetIds(root))),
+			].sort(),
+		).toEqual([...readyIds].sort())
+
+		await write(
+			root,
+			"tasks/ship/phases/implement/PHASE.md",
+			execution("working", "feat/implement"),
+		)
+		const resumableIds = await service((readiness) =>
+			readiness.getWorkTargetIds(root),
+		)
+		expect(resumableIds).toContain("epic:delivery")
+		expect(resumableIds).toContain("task:ship")
+		expect(resumableIds).toContain("execution-unit:phase/ship/implement")
+		await service((readiness) =>
+			readiness.guardWorkTarget("execution-unit:phase/ship/implement", root),
+		)
+
+		await write(
+			root,
+			"tasks/ship/phases/implement/PHASE.md",
+			`---
+repo: agency
+branch: feat/implement
+base: main
+pr: null
+status: working
+claim:
+  claimant: orchestrator
+  runner: opencode
+  sessionId: session-1
+  startedAt: 2026-07-20T00:00:00.000Z
+  targetRevision: ${"a".repeat(64)}
+  state: active
+---
+
+# Execution
+`,
+		)
+		expect(
+			await service((readiness) => readiness.getWorkTargetIds(root)),
+		).not.toContain("execution-unit:phase/ship/implement")
+		await expect(
+			service((readiness) =>
+				readiness.guardWorkTarget(
+					"execution-unit:phase/ship/implement",
+					root,
+					true,
+				),
+			),
+		).rejects.toThrow("active claim")
 
 		const blocked = await service((readiness) =>
 			Effect.either(readiness.guardWorkTarget("phase:ship/verify", root)),

package/src/services/ReadinessService.ts

@@ -46,6 +46,23 @@ const executionNodeId = (taskId: string, phaseId?: string) =>
 		? `execution-unit:phase/${taskId}/${phaseId}`
 		: `execution-unit:task/${taskId}`
 
+const hasActiveClaim = (node: GraphNode) =>
+	node.kind !== "epic" &&
+	node.kind !== "repository" &&
+	"claim" in node.data &&
+	node.data.claim?.state === "active"
+
+const isResumableWork = (node: GraphNode) =>
+	node.kind !== "repository" &&
+	node.status === "working" &&
+	!hasActiveClaim(node) &&
+	node.readiness.blockers.every((blocker) => blocker.kind !== "validation")
+
+const isWorkTarget = (node: GraphNode) =>
+	node.kind !== "repository" &&
+	!hasActiveClaim(node) &&
+	(node.readiness.ready || isResumableWork(node))
+
 const itemFor = (
 	node: ExecutionNode,
 	graph: AgencyGraph,
@@ -126,6 +143,15 @@ export class ReadinessService extends Effect.Service<ReadinessService>()(
 					)
 				}),
 
+			getWorkTargetIds: (cwd: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const graphs = yield* GraphService
+					const graph = yield* graphs.get({ cwd })
+					return new Set(
+						graph.nodes.filter(isWorkTarget).map((node) => node.id),
+					)
+				}),
+
 			getNext: (cwd: string = process.cwd(), select = false) =>
 				Effect.gen(function* () {
 					const graphs = yield* GraphService
@@ -150,11 +176,11 @@ export class ReadinessService extends Effect.Service<ReadinessService>()(
 				override = false,
 			) =>
 				Effect.gen(function* () {
-					if (override) return
 					const graphs = yield* GraphService
 					const graph = yield* graphs.get({ cwd })
 					const node = graph.nodes.find((candidate) => candidate.id === target)
 					if (!node || !node.readiness) {
+						if (override) return
 						return yield* new ExecutionGuardError({
 							message: `Work target '${target}' was not found in the work graph.`,
 							action: "work",
@@ -164,7 +190,18 @@ export class ReadinessService extends Effect.Service<ReadinessService>()(
 							blockers: [],
 						})
 					}
-					if (!node.readiness.ready) {
+					if (hasActiveClaim(node)) {
+						return yield* new ExecutionGuardError({
+							message: `Cannot work on '${node.key}': it has an active claim. Use agency release or agency finish first.`,
+							action: "work",
+							target,
+							status: node.status!,
+							blockedBy: node.readiness!.blockedBy,
+							blockers: node.readiness!.blockers,
+						})
+					}
+					if (override) return
+					if (!node.readiness.ready && !isResumableWork(node)) {
 						const item = {
 							key: node.key,
 							status: node.status!,

package/src/services/TaskPhaseService.test.ts

@@ -33,7 +33,7 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		await runTestEffect(
+		const createdTask = await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
 					service.create(
@@ -51,6 +51,9 @@ describe("task and phase services", () => {
 				),
 			),
 		)
+		expect(createdTask.content).toContain(
+			"# Task One\n\n## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 
 		const epic = await runTestEffect(
 			EpicService.pipe(
@@ -159,6 +162,14 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(phases.map((phase) => phase.id)).toEqual(["first", "second"])
+		const firstPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) => service.show("multi", "first", root)),
+			),
+		)
+		expect(firstPhase.content).toContain(
+			"# First\n\n## Outcome\n\nDescribe the phase outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions\n\nRecord consequential decisions and their rationale.",
+		)
 	})
 
 	test("converts a single-phase task when the existing phase ID is provided", async () => {
@@ -243,7 +254,9 @@ describe("task and phase services", () => {
 				{ id: "extra", dependsOn: ["implementation"] },
 			],
 		})
-		expect(task.content).toContain("Describe the task outcome.")
+		expect(task.content).toContain(
+			"## Outcome\n\nDescribe the task outcome.\n\n## Plan\n\nDescribe the current approach.\n\n## Important Decisions",
+		)
 
 		const firstPhase = await runTestEffect(
 			PhaseService.pipe(
@@ -288,17 +301,23 @@ describe("task and phase services", () => {
 			),
 		)
 		expect(createdTask.content).toContain("status: open")
-		for (const status of ["working", "delegated"]) {
-			await expect(
-				runTestEffect(
-					TaskService.pipe(
-						Effect.flatMap((service) =>
-							service.setStatus("single-status", status, root),
-						),
+		const workingTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "working", root),
+				),
+			),
+		)
+		expect(workingTask.data.status).toBe("working")
+		await expect(
+			runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("single-status", "delegated", root),
 					),
 				),
-			).rejects.toThrow("require explicit ownership")
-		}
+			),
+		).rejects.toThrow("Delegation requires explicit ownership")
 		await runTestEffect(
 			TaskService.pipe(
 				Effect.flatMap((service) =>
@@ -346,6 +365,14 @@ describe("task and phase services", () => {
 				),
 			),
 		)
+		const workingPhase = await runTestEffect(
+			PhaseService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("multi-status", "implementation", "working", root),
+				),
+			),
+		)
+		expect(workingPhase.data.status).toBe("working")
 		const phase = await runTestEffect(
 			PhaseService.pipe(
 				Effect.flatMap((service) =>

package/src/services/TaskService.ts

@@ -13,6 +13,7 @@ import {
 } from "../workbase/schemas"
 import {
 	formatMarkdownDocument,
+	formatWorkDocumentBody,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
 import { canTransitionStatus } from "../readiness"
@@ -163,7 +164,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					.join(" ")
 				const content = formatMarkdownDocument(
 					data,
-					`# ${title}\n\nDescribe the task outcome.`,
+					formatWorkDocumentBody(title, "task"),
 				)
 				const writes: {
 					path: string
@@ -251,10 +252,10 @@ 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") {
+				if (validStatus === "delegated") {
 					return yield* new TaskError({
 						message:
-							"Active work and delegation require explicit ownership; use 'agency claim'",
+							"Delegation requires explicit ownership; use 'agency claim'",
 					})
 				}
 				const record = yield* service.show(id, startPath)

package/src/utils/chooser.test.ts

@@ -9,43 +9,80 @@ const choices = [
 
 const createIO = (
 	overrides: Partial<ChooserIO> = {},
-): ChooserIO & { readonly writes: string[]; readonly inputs: string[] } => {
-	const writes: string[] = []
+): ChooserIO & {
+	readonly selections: Array<{
+		readonly prompt: string
+		readonly choices: readonly {
+			readonly key: string
+			readonly label: string
+		}[]
+	}>
+	readonly inputs: string[]
+} => {
+	const selections: Array<{
+		readonly prompt: string
+		readonly choices: readonly {
+			readonly key: string
+			readonly label: string
+		}[]
+	}> = []
 	const inputs: string[] = []
 	return {
 		inputIsTTY: true,
 		outputIsTTY: true,
 		color: false,
-		write: (message) => writes.push(message),
-		question: async () => "1",
+		select: async (prompt, choices) => {
+			selections.push({ prompt, choices })
+			return choices[0]?.key ?? null
+		},
 		run: async (_command, input) => {
 			inputs.push(input)
 			return { exitCode: 0, stdout: "first-key\n" }
 		},
 		...overrides,
-		writes,
+		selections,
 		inputs,
 	}
 }
 
 describe("chooser", () => {
-	test("offers a plain-text numbered chooser on a TTY", async () => {
-		const io = createIO({ question: async () => "2" })
+	test("offers plain choices to the native interactive renderer", async () => {
+		let offered:
+			| {
+					readonly prompt: string
+					readonly choices: readonly {
+						readonly key: string
+						readonly label: string
+					}[]
+			  }
+			| undefined
+		const io = createIO({
+			select: async (prompt, offeredChoices) => {
+				offered = { prompt, choices: offeredChoices }
+				return offeredChoices[1]!.key
+			},
+		})
 
 		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")
+		expect(offered).toEqual({
+			prompt: "Pick one",
+			choices: [
+				{ key: "first-key", label: "First" },
+				{ key: "second key", label: "Second" },
+			],
+		})
 	})
 
-	test("preserves colors when enabled", async () => {
+	test("preserves colors for configured external choosers", async () => {
 		const io = createIO({ color: true })
 
-		await Effect.runPromise(choose("Pick one", choices, undefined, io))
+		await Effect.runPromise(choose("Pick one", choices, ["chooser"], io))
 
-		expect(io.writes.join("")).toContain("\x1b[32mFirst\x1b[0m")
+		expect(io.inputs[0]).toContain("\x1b[32mFirst\x1b[0m")
 	})
 
 	test("passes generic records to an external argv command", async () => {
@@ -70,7 +107,7 @@ describe("chooser", () => {
 	})
 
 	test("treats native and external cancellation as no selection", async () => {
-		const native = createIO({ question: async () => "q" })
+		const native = createIO({ select: async () => null })
 		const external = createIO({
 			run: async () => ({ exitCode: 130, stdout: "" }),
 		})

package/src/utils/chooser.ts

@@ -1,5 +1,4 @@
 import { Effect } from "effect"
-import { createInterface } from "node:readline/promises"
 
 export interface Choice<T> {
 	readonly key: string
@@ -35,8 +34,10 @@ export interface ChooserIO {
 	readonly inputIsTTY: boolean
 	readonly outputIsTTY: boolean
 	readonly color: boolean
-	readonly write: (message: string) => void
-	readonly question: (prompt: string) => Promise<string>
+	readonly select: (
+		prompt: string,
+		choices: readonly { readonly key: string; readonly label: string }[],
+	) => Promise<string | null>
 	readonly run: (
 		command: readonly string[],
 		input: string,
@@ -51,22 +52,16 @@ const stripAnsi = (value: string) =>
 
 const defaultIO = (): ChooserIO => ({
 	inputIsTTY: Boolean(process.stdin.isTTY),
-	outputIsTTY: Boolean(process.stderr.isTTY),
+	outputIsTTY: Boolean(process.stdout.isTTY),
 	color:
-		Boolean(process.stderr.isTTY) &&
+		Boolean(process.stdout.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()
-		}
+	select: async (prompt, choices) => {
+		const { promptSelect } = await (
+			await import("./interactive-loader")
+		).loadInteractive()
+		return promptSelect(prompt, choices)
 	},
 	run: async (command, input) => {
 		const child = Bun.spawn([...command], {
@@ -173,33 +168,21 @@ const nativeChoice = async <T>(
 			"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
+	let key: string | null
 	try {
-		answer = (
-			await io.question(`Select [1-${choices.length}] (q to cancel): `)
-		).trim()
+		key = await io.select(
+			prompt,
+			choices.map((choice) => ({
+				key: choice.key,
+				label: displayLabel(choice, false),
+			})),
+		)
 	} 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
+	return key === null ? null : selectedChoice(key, choices)
 }
 
 export const choose = <T>(

package/src/utils/interactive-loader.ts

@@ -0,0 +1,6 @@
+export const loadInteractive = async () => {
+	// Resolve this at runtime so the Node-target bundle still selects Bun's preload.
+	const preload = ["@opentui", "solid", "preload"].join("/")
+	await import(preload)
+	return import("./interactive")
+}