@markjaquith/agency 2.12.0 → 2.14.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/services/WorktreeService.test.ts

@@ -113,15 +113,17 @@ describe("WorktreeService", () => {
 			["remote", "set-url", "origin", join(root, "missing")],
 			join(root, "repos/agency"),
 		)
-		await expect(
-			runTestEffect(
-				WorktreeService.pipe(
-					Effect.flatMap((service) =>
-						service.materialize("existing", undefined, root),
-					),
+		const reused = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("existing", undefined, root),
 				),
 			),
-		).resolves.toMatchObject({ repo: "agency" })
+		)
+		expect(reused.checkouts).toEqual([
+			expect.objectContaining({ repo: "agency", action: "reused" }),
+		])
+		expect(reused.operations).toEqual([])
 	})
 
 	test("reuses an immutable reference checkout without fetching", async () => {
@@ -771,6 +773,79 @@ pr: null
 			"refs/heads/task/removable",
 		])
 		expect(branch.exitCode).toBe(0)
+		expect(workspace.checkouts).toEqual([
+			expect.objectContaining({
+				repo: "agency",
+				kind: "writable",
+				action: "created",
+				resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+			}),
+			expect.objectContaining({
+				repo: "effect",
+				kind: "reference",
+				action: "created",
+				resolvedCommit: expect.stringMatching(/^[0-9a-f]{40}$/),
+			}),
+		])
+	})
+
+	test("reports dry-run fetch and worktree changes without mutating", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "planned",
+							ticketUrl: "https://example.com/task",
+							repo: "agency",
+							repos: [{ repo: "effect", ref: "main" }],
+							branch: "task/planned",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("planned", undefined, root, { dryRun: true }),
+				),
+			),
+		)
+
+		expect(workspace.dryRun).toBe(true)
+		expect(
+			workspace.checkouts.every(({ resolvedCommit }) => resolvedCommit),
+		).toBe(true)
+		expect(
+			workspace.checkouts.map(({ repo, action }) => ({ repo, action })),
+		).toEqual([
+			{ repo: "agency", action: "created" },
+			{ repo: "effect", action: "created" },
+		])
+		expect(workspace.operations).toEqual(
+			expect.arrayContaining([
+				expect.objectContaining({ action: "fetch", status: "planned" }),
+				expect.objectContaining({
+					action: "create-worktree",
+					status: "planned",
+				}),
+			]),
+		)
+		expect(await Bun.file(workspace.codePath).exists()).toBe(false)
+		expect(
+			Bun.spawnSync([
+				"git",
+				"-C",
+				join(root, "repos/agency"),
+				"show-ref",
+				"--verify",
+				"refs/heads/task/planned",
+			]).exitCode,
+		).not.toBe(0)
 	})
 
 	test("refuses to remove a worktree with uncommitted changes", async () => {

package/src/services/WorktreeService.ts

@@ -16,6 +16,22 @@ class WorktreeError extends Data.TaggedError("WorktreeError")<{
 	readonly message: string
 }> {}
 
+interface WorkspaceOperation {
+	readonly action: "fetch" | "create-branch" | "create-worktree"
+	readonly repo: string
+	readonly command: readonly string[]
+	readonly status: "planned" | "completed"
+}
+
+interface WorkspaceCheckout {
+	readonly repo: string
+	readonly kind: "writable" | "reference"
+	readonly path: string
+	readonly requestedRef: string
+	readonly resolvedCommit: string | null
+	readonly action: "created" | "reused"
+}
+
 interface ExecutionWorkspace {
 	readonly root: string
 	readonly taskPath: string
@@ -24,6 +40,9 @@ interface ExecutionWorkspace {
 	readonly writablePath: string
 	readonly repo: string
 	readonly repos: readonly RepositoryReference[]
+	readonly dryRun: boolean
+	readonly checkouts: readonly WorkspaceCheckout[]
+	readonly operations: readonly WorkspaceOperation[]
 }
 
 interface GitWorktree {
@@ -121,7 +140,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						codePath = join(dirname(task.path), "code")
 					}
 
-					yield* fs.createDirectory(codePath)
+					if (!options.dryRun) yield* fs.createDirectory(codePath)
+					const operations: WorkspaceOperation[] = []
+					const checkoutReports: WorkspaceCheckout[] = []
 					const checkouts: readonly (
 						| { readonly repo: string; readonly branch: string }
 						| RepositoryReference
@@ -146,23 +167,38 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									{ captureOutput: true },
 								)
 								if (remote.exitCode !== 0) return false
+								const command = [
+									"git",
+									"-C",
+									repositoryPath,
+									"fetch",
+									"origin",
+									...(ref ? [ref] : []),
+								]
+								if (options.dryRun) {
+									operations.push({
+										action: "fetch",
+										repo: alias,
+										command,
+										status: "planned",
+									})
+									return false
+								}
 
-								const fetch = yield* fs.runCommand(
-									[
-										"git",
-										"-C",
-										repositoryPath,
-										"fetch",
-										"origin",
-										...(ref ? [ref] : []),
-									],
-									{ captureOutput: true },
-								)
+								const fetch = yield* fs.runCommand(command, {
+									captureOutput: true,
+								})
 								if (fetch.exitCode !== 0) {
 									return yield* new WorktreeError({
 										message: `Failed to fetch '${alias}': ${fetch.stderr}`,
 									})
 								}
+								operations.push({
+									action: "fetch",
+									repo: alias,
+									command,
+									status: "completed",
+								})
 								return true
 							})
 
@@ -183,7 +219,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								message: `Failed to inspect worktrees for '${alias}': ${listed.stderr}`,
 							})
 						}
-						const canonicalCodePath = yield* fs.realPath(codePath)
+						const canonicalCodePath = (yield* fs.exists(codePath))
+							? yield* fs.realPath(codePath)
+							: resolve(codePath)
 						const canonicalCheckoutPath = join(canonicalCodePath, alias)
 						const worktrees: GitWorktree[] = []
 						for (const worktree of parseWorktreeList(listed.stdout)) {
@@ -212,7 +250,17 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								})
 							}
 							if (yield* fs.isDirectory(checkoutPath)) {
-								if (registeredAtPath?.branch === branchRef) continue
+								if (registeredAtPath?.branch === branchRef) {
+									checkoutReports.push({
+										repo: alias,
+										kind: "writable",
+										path: checkoutPath,
+										requestedRef: checkout.branch,
+										resolvedCommit: registeredAtPath.head ?? null,
+										action: "reused",
+									})
+									continue
+								}
 								return yield* new WorktreeError({
 									message: `Existing checkout ${checkoutPath} is not registered to branch '${checkout.branch}'`,
 								})
@@ -260,21 +308,29 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									{ captureOutput: true },
 								)
 								if (branchExists.exitCode !== 0) {
-									const createBranch = yield* fs.runCommand(
-										[
-											"git",
-											"-C",
-											repositoryPath,
-											"branch",
-											checkout.branch,
-											execution.base,
-										],
-										{ captureOutput: true },
-									)
-									if (createBranch.exitCode !== 0) {
-										return yield* new WorktreeError({
-											message: `Failed to create branch '${checkout.branch}': ${createBranch.stderr}`,
+									const command = [
+										"git",
+										"-C",
+										repositoryPath,
+										"branch",
+										checkout.branch,
+										execution.base,
+									]
+									operations.push({
+										action: "create-branch",
+										repo: alias,
+										command,
+										status: options.dryRun ? "planned" : "completed",
+									})
+									if (!options.dryRun) {
+										const createBranch = yield* fs.runCommand(command, {
+											captureOutput: true,
 										})
+										if (createBranch.exitCode !== 0) {
+											return yield* new WorktreeError({
+												message: `Failed to create branch '${checkout.branch}': ${createBranch.stderr}`,
+											})
+										}
 									}
 								}
 								args = [
@@ -287,6 +343,48 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									checkout.branch,
 								]
 							}
+							if (options.dryRun) {
+								operations.push({
+									action: "create-worktree",
+									repo: alias,
+									command: args,
+									status: "planned",
+								})
+								let resolved = yield* fs.runCommand(
+									[
+										"git",
+										"-C",
+										repositoryPath,
+										"rev-parse",
+										"--verify",
+										`${checkout.branch}^{commit}`,
+									],
+									{ captureOutput: true },
+								)
+								if (resolved.exitCode !== 0) {
+									resolved = yield* fs.runCommand(
+										[
+											"git",
+											"-C",
+											repositoryPath,
+											"rev-parse",
+											"--verify",
+											`${execution.base}^{commit}`,
+										],
+										{ captureOutput: true },
+									)
+								}
+								checkoutReports.push({
+									repo: alias,
+									kind: "writable",
+									path: checkoutPath,
+									requestedRef: checkout.branch,
+									resolvedCommit:
+										resolved.exitCode === 0 ? resolved.stdout.trim() : null,
+									action: "created",
+								})
+								continue
+							}
 
 							if (config.worktreeCreateCommand) {
 								verboseLog(`Running worktree command: ${formatCommand(args)}`)
@@ -308,6 +406,24 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree command did not create ${checkoutPath}`,
 								})
 							}
+							operations.push({
+								action: "create-worktree",
+								repo: alias,
+								command: args,
+								status: "completed",
+							})
+							const head = yield* fs.runCommand(
+								["git", "-C", checkoutPath, "rev-parse", "HEAD"],
+								{ captureOutput: true },
+							)
+							checkoutReports.push({
+								repo: alias,
+								kind: "writable",
+								path: checkoutPath,
+								requestedRef: checkout.branch,
+								resolvedCommit: head.exitCode === 0 ? head.stdout.trim() : null,
+								action: "created",
+							})
 						} else {
 							const fetched = isCommitId(checkout.ref)
 								? false
@@ -349,6 +465,14 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									currentHead.exitCode === 0 &&
 									currentHead.stdout.trim() === commit
 								) {
+									checkoutReports.push({
+										repo: alias,
+										kind: "reference",
+										path: checkoutPath,
+										requestedRef: checkout.ref,
+										resolvedCommit: commit,
+										action: "reused",
+									})
 									continue
 								}
 								return yield* new WorktreeError({
@@ -360,24 +484,55 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									message: `Worktree registry contains a missing checkout at ${checkoutPath}`,
 								})
 							}
-							const result = yield* fs.runCommand(
-								[
-									"git",
-									"-C",
-									repositoryPath,
-									"worktree",
-									"add",
-									"--detach",
-									checkoutPath,
-									commit,
-								],
-								{ captureOutput: true },
-							)
+							const command = [
+								"git",
+								"-C",
+								repositoryPath,
+								"worktree",
+								"add",
+								"--detach",
+								checkoutPath,
+								commit,
+							]
+							if (options.dryRun) {
+								operations.push({
+									action: "create-worktree",
+									repo: alias,
+									command,
+									status: "planned",
+								})
+								checkoutReports.push({
+									repo: alias,
+									kind: "reference",
+									path: checkoutPath,
+									requestedRef: checkout.ref,
+									resolvedCommit: commit,
+									action: "created",
+								})
+								continue
+							}
+							const result = yield* fs.runCommand(command, {
+								captureOutput: true,
+							})
 							if (result.exitCode !== 0) {
 								return yield* new WorktreeError({
 									message: `Failed to create worktree for '${alias}': ${result.stderr}`,
 								})
 							}
+							operations.push({
+								action: "create-worktree",
+								repo: alias,
+								command,
+								status: "completed",
+							})
+							checkoutReports.push({
+								repo: alias,
+								kind: "reference",
+								path: checkoutPath,
+								requestedRef: checkout.ref,
+								resolvedCommit: commit,
+								action: "created",
+							})
 						}
 					}
 
@@ -389,6 +544,9 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						writablePath: join(codePath, execution.repo),
 						repo: execution.repo,
 						repos: execution.repos ?? [],
+						dryRun: options.dryRun === true,
+						checkouts: checkoutReports,
+						operations,
 					} satisfies ExecutionWorkspace
 				}),
 

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/command.ts

@@ -5,6 +5,7 @@ export interface BaseCommandOptions {
 	readonly silent?: boolean
 	readonly verbose?: boolean
 	readonly json?: boolean
+	readonly dryRun?: boolean
 	/** Whether this invocation may open prompts or selectors. */
 	readonly inputAllowed?: boolean
 	/**

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