@markjaquith/agency 3.2.2 → 3.2.3

package/src/services/WorktreeService.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test"
 import { Effect } from "effect"
-import { mkdir, realpath, rename, rm } from "node:fs/promises"
+import { mkdir, realpath, rename, rm, symlink } from "node:fs/promises"
 import { join, resolve } from "node:path"
 import {
 	captureErrors,
@@ -1526,6 +1526,107 @@ pr: null
 		).toBe("keep me\n")
 	})
 
+	test("refuses to remove worktrees for active work", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "active-removal",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/active-removal",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("active-removal", undefined, root),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("active-removal", "working", root),
+				),
+			),
+		)
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.remove("active-removal", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("active 'working' ownership")
+		expect(
+			await Bun.file(join(workspace.writablePath!, "README.md")).exists(),
+		).toBe(true)
+	})
+
+	test("restores earlier worktrees and preserves the Git failure diagnostic", async () => {
+		await ensureEffectRepository()
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "locked-removal",
+							ticketUrl: null,
+							repo: "agency",
+							repos: [{ repo: "effect", ref: "main" }],
+							branch: "task/locked-removal",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("locked-removal", undefined, root),
+				),
+			),
+		)
+		const referencePath = join(workspace.codePath, "effect")
+		await git([
+			"-C",
+			join(root, "repos/effect"),
+			"worktree",
+			"lock",
+			referencePath,
+		])
+
+		const failure = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.remove("locked-removal", undefined, root),
+				),
+				Effect.flip,
+			),
+		)
+
+		expect(failure.message).toContain("locked working tree")
+		expect(failure).toMatchObject({
+			completed: [workspace.writablePath!],
+			rolledBack: [workspace.writablePath!],
+			manualRecovery: [],
+		})
+		for (const checkout of [workspace.writablePath!, referencePath]) {
+			expect(await Bun.file(join(checkout, "README.md")).exists()).toBe(true)
+		}
+	})
+
 	test("handles a missing checkout without deleting its branch", async () => {
 		await runTestEffect(
 			TaskService.pipe(
@@ -1583,6 +1684,52 @@ pr: null
 		).toBe(0)
 	})
 
+	test("does not prune unrelated stale worktree registrations", async () => {
+		for (const id of ["stale-target", "stale-unrelated"]) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{
+								id,
+								ticketUrl: null,
+								repo: "agency",
+								branch: `task/${id}`,
+								base: "main",
+							},
+							root,
+						),
+					),
+				),
+			)
+			const workspace = await runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) => service.materialize(id, undefined, root)),
+				),
+			)
+			await rm(workspace.codePath, { recursive: true })
+		}
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.remove("stale-target", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("would also remove unrelated stale registrations")
+		const registered = await gitOutput([
+			"-C",
+			join(root, "repos/agency"),
+			"worktree",
+			"list",
+			"--porcelain",
+		])
+		expect(registered).toContain("tasks/stale-target/code/agency")
+		expect(registered).toContain("tasks/stale-unrelated/code/agency")
+	})
+
 	test("lists and inspects ownership, registration, commits, and dirtiness", async () => {
 		const repository = join(root, "repos/agency")
 		await git(["-C", repository, "branch", "task/inspected", "main"])
@@ -1712,6 +1859,50 @@ pr: null
 		expect(await Bun.file(unexpected).text()).toBe("keep me\n")
 	})
 
+	test("does not follow a symlink named for an expected checkout", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "symlink-removal",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/symlink-removal",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const repository = join(root, "repos/agency")
+		await git(["-C", repository, "branch", "task/symlink-removal", "main"])
+		const outside = join(root, "outside-symlink-removal")
+		await git([
+			"-C",
+			repository,
+			"worktree",
+			"add",
+			outside,
+			"task/symlink-removal",
+		])
+		const codePath = join(root, "tasks/symlink-removal/code")
+		await mkdir(codePath, { recursive: true })
+		await symlink(outside, join(codePath, "agency"), "dir")
+
+		await expect(
+			runTestEffect(
+				WorktreeService.pipe(
+					Effect.flatMap((service) =>
+						service.remove("symlink-removal", undefined, root),
+					),
+				),
+			),
+		).rejects.toThrow("is a symbolic link")
+		expect(await Bun.file(join(outside, "README.md")).exists()).toBe(true)
+	})
+
 	test("refuses removal when a branch has duplicate Agency owners", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/WorktreeService.ts

@@ -182,6 +182,14 @@ const formatCommand = (args: readonly string[]) =>
 		)
 		.join(" ")
 
+const describeError = (error: unknown) =>
+	typeof error === "object" &&
+	error !== null &&
+	"message" in error &&
+	typeof error.message === "string"
+		? error.message
+		: String(error)
+
 const runPostCheckoutHook = (options: {
 	readonly command: readonly string[] | undefined
 	readonly variables: CheckoutCommandVariables
@@ -1871,6 +1879,10 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							  }
 							| { review: { repo: string; commit: string } }
 						let codePath: string
+						let executionState: {
+							readonly status: string
+							readonly claim?: { readonly state: string }
+						}
 						if ("phases" in task.data) {
 							if (!phaseId) {
 								return yield* new WorktreeError({
@@ -1880,6 +1892,7 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							const phase =
 								options.phase ?? (yield* phases.show(taskId, phaseId, root))
 							execution = phase.data
+							executionState = phase.data
 							codePath = join(dirname(phase.path), "code")
 						} else {
 							if (phaseId) {
@@ -1888,8 +1901,25 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								})
 							}
 							execution = task.data
+							executionState = task.data
 							codePath = join(dirname(task.path), "code")
 						}
+						const ownerLabel = phaseId
+							? `Phase '${taskId}/${phaseId}'`
+							: `Task '${taskId}'`
+						if (executionState.claim?.state === "active") {
+							return yield* new WorktreeError({
+								message: `${ownerLabel} has an active claim; release or finish it before removing its worktrees`,
+							})
+						}
+						if (
+							executionState.status === "working" ||
+							executionState.status === "delegated"
+						) {
+							return yield* new WorktreeError({
+								message: `${ownerLabel} has active '${executionState.status}' ownership; reopen it before removing its worktrees`,
+							})
+						}
 
 						const codeDirectoryExists = yield* fs.isDirectory(codePath)
 						const removalPlans: {
@@ -1931,6 +1961,11 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 							const alias = checkout.repo
 							const repositoryPath = join(root, "repos", alias)
 							const checkoutPath = join(codePath, alias)
+							if ((yield* fs.readSymlinkTarget(checkoutPath)) !== null) {
+								return yield* new WorktreeError({
+									message: `Cannot remove ${codePath}; expected checkout ${checkoutPath} is a symbolic link`,
+								})
+							}
 							if (
 								(yield* fs.exists(checkoutPath)) &&
 								!(yield* fs.isDirectory(checkoutPath))
@@ -2024,7 +2059,12 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									["git", "-C", checkoutPath, "status", "--porcelain"],
 									{ captureOutput: true },
 								)
-								if (status.exitCode !== 0 || status.stdout.trim()) {
+								if (status.exitCode !== 0) {
+									return yield* new WorktreeError({
+										message: `Failed to remove worktree for '${alias}': checkout cleanliness could not be verified: ${status.stderr.trim() || `git status exited with code ${status.exitCode}`}`,
+									})
+								}
+								if (status.stdout.trim()) {
 									return yield* new WorktreeError({
 										message: `Failed to remove worktree for '${alias}': checkout has uncommitted changes`,
 									})
@@ -2039,6 +2079,25 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 								head: registered.head,
 								branch: registered.branch?.replace(/^refs\/heads\//, ""),
 							})
+							if (!checkoutExists) {
+								const unrelatedStale: string[] = []
+								for (const worktree of parseWorktreeList(listed.stdout)) {
+									const worktreePath = (yield* fs.exists(worktree.path))
+										? yield* fs.realPath(worktree.path)
+										: resolve(worktree.path)
+									if (
+										worktreePath !== registered.path &&
+										!(yield* fs.exists(worktree.path))
+									) {
+										unrelatedStale.push(worktree.path)
+									}
+								}
+								if (unrelatedStale.length > 0) {
+									return yield* new WorktreeError({
+										message: `Cannot remove stale registration ${registered.path} because pruning would also remove unrelated stale registrations: ${unrelatedStale.join(", ")}`,
+									})
+								}
+							}
 						}
 						for (const plan of removalPlans) {
 							if (!plan.checkoutExists || !plan.head) continue
@@ -2056,6 +2115,38 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 						}
 
 						const completed: typeof removalPlans = []
+						const planState = (plan: (typeof removalPlans)[number]) =>
+							Effect.gen(function* () {
+								const checkoutExists = yield* fs.isDirectory(plan.checkoutPath)
+								const listed = yield* fs.runCommand(
+									[
+										"git",
+										"-C",
+										plan.repositoryPath,
+										"worktree",
+										"list",
+										"--porcelain",
+										"-z",
+									],
+									{ captureOutput: true },
+								)
+								if (listed.exitCode !== 0) {
+									return yield* new WorktreeError({
+										message: `Failed to inspect worktrees for '${plan.alias}' during recovery: ${listed.stderr.trim() || `git worktree list exited with code ${listed.exitCode}`}`,
+									})
+								}
+								let registered = false
+								for (const worktree of parseWorktreeList(listed.stdout)) {
+									const worktreePath = (yield* fs.exists(worktree.path))
+										? yield* fs.realPath(worktree.path)
+										: resolve(worktree.path)
+									if (worktreePath === plan.registeredPath) {
+										registered = true
+										break
+									}
+								}
+								return { checkoutExists, registered }
+							})
 						const removed = yield* Effect.gen(function* () {
 							for (const plan of removalPlans) {
 								const command = plan.checkoutExists
@@ -2080,8 +2171,18 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									captureOutput: true,
 								})
 								if (result.exitCode !== 0) {
+									const state = yield* planState(plan).pipe(
+										Effect.catchAll(() => Effect.succeed(undefined)),
+									)
+									if (
+										!state ||
+										state.checkoutExists !== plan.checkoutExists ||
+										!state.registered
+									) {
+										completed.push(plan)
+									}
 									return yield* new WorktreeError({
-										message: `Failed to remove worktree for '${plan.alias}': ${result.stderr}`,
+										message: `Failed to remove worktree for '${plan.alias}': ${result.stderr.trim() || `git exited with code ${result.exitCode}`}`,
 									})
 								}
 								completed.push(plan)
@@ -2099,43 +2200,77 @@ export class WorktreeService extends Effect.Service<WorktreeService>()(
 									for (const plan of [...completed].reverse()) {
 										if (!plan.checkoutExists) {
 											manualRecovery.push(
-												`Re-run worktree repair for stale registration ${plan.registeredPath}`,
+												`Restore stale registration ${plan.registeredPath} if it is still needed`,
 											)
 											continue
 										}
-										yield* fs.createDirectory(dirname(plan.checkoutPath))
-										const command = plan.branch
-											? [
-													"git",
-													"-C",
-													plan.repositoryPath,
-													"worktree",
-													"add",
-													plan.checkoutPath,
-													plan.branch,
-												]
-											: [
-													"git",
-													"-C",
-													plan.repositoryPath,
-													"worktree",
-													"add",
-													"--detach",
-													plan.checkoutPath,
-													plan.head!,
-												]
-										const restored = yield* fs.runCommand(command, {
-											captureOutput: true,
-										})
-										if (restored.exitCode === 0)
-											rolledBack.push(plan.checkoutPath)
-										else manualRecovery.push(`Restore ${plan.checkoutPath}`)
+										const recovery = Effect.gen(function* () {
+											const state = yield* planState(plan)
+											if (state.checkoutExists && state.registered) {
+												rolledBack.push(plan.checkoutPath)
+												return
+											}
+											if (state.checkoutExists || state.registered) {
+												manualRecovery.push(
+													`Restore ${plan.checkoutPath}; checkout path ${state.checkoutExists ? "exists" : "is missing"} and registration ${state.registered ? "exists" : "is missing"}`,
+												)
+												return
+											}
+											yield* fs.createDirectory(dirname(plan.checkoutPath))
+											const command = plan.branch
+												? [
+														"git",
+														"-C",
+														plan.repositoryPath,
+														"worktree",
+														"add",
+														plan.checkoutPath,
+														plan.branch,
+													]
+												: [
+														"git",
+														"-C",
+														plan.repositoryPath,
+														"worktree",
+														"add",
+														"--detach",
+														plan.checkoutPath,
+														plan.head!,
+													]
+											const restored = yield* fs.runCommand(command, {
+												captureOutput: true,
+											})
+											if (restored.exitCode === 0) {
+												rolledBack.push(plan.checkoutPath)
+											} else {
+												manualRecovery.push(
+													`Restore ${plan.checkoutPath}: ${restored.stderr.trim() || `git exited with code ${restored.exitCode}`}`,
+												)
+											}
+										}).pipe(
+											Effect.catchAll((recoveryCause) =>
+												Effect.sync(() => {
+													manualRecovery.push(
+														`Restore ${plan.checkoutPath}: ${describeError(recoveryCause)}`,
+													)
+												}),
+											),
+										)
+										yield* recovery
 									}
+									const causeMessage = describeError(cause)
 									return yield* new WorktreeError({
-										message: manualRecovery.length
-											? "Worktree removal failed and requires manual recovery"
-											: "Worktree removal failed; removed worktrees were restored",
-										completed: completed.map((plan) => plan.checkoutPath),
+										message:
+											completed.length === 0
+												? `${causeMessage}; no worktrees were removed`
+												: manualRecovery.length
+													? `${causeMessage}. Worktree removal requires manual recovery`
+													: `${causeMessage}. Removed worktrees were restored`,
+										completed: completed.map((plan) =>
+											plan.checkoutExists
+												? plan.checkoutPath
+												: plan.registeredPath,
+										),
 										rolledBack,
 										manualRecovery,
 										cause,

package/src/test-utils.ts

@@ -16,7 +16,6 @@ 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"
 import { SyncService } from "./services/SyncService"
 import { ReadinessService } from "./services/ReadinessService"
 import { GraphMutationService } from "./services/GraphMutationService"
@@ -48,7 +47,6 @@ const TestLayer = Layer.mergeAll(
 	IntegrationService.Default,
 	ContextService.Default,
 	GraphService.Default,
-	ClaimService.Default,
 	SyncService.Default,
 	ReadinessService.Default,
 	GraphMutationService.Default,

package/src/workbase/AGENTS.md

@@ -46,9 +46,7 @@ retain `--if-revision` guards when shown, and do not add flags that are not show
     `agency push --json`. Create and record a pull request with
     `agency pr create <task> [phase] [--draft] [--title <title>] [--label <label>] --json`;
     do not run a separate push first because `pr create` owns publication.
-12. Complete genuine non-PR work. For an active claim, run
-    `agency finish <task> [phase] --session-id <id> --revision <revision> --outcome done --no-pull-request --summary <text> [--evidence-url <url>]`.
-    Without a claim, run
+12. Complete genuine non-PR work. Run
     `agency task status <task> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`
     or
     `agency phase status <task> <phase> done --if-revision <revision> --no-pull-request --summary <text> [--evidence-url <url>] --json`.
@@ -162,14 +160,14 @@ revision stale, and Agency must not silently rewrite that evidence.
 
 ## Safety
 
-- Stop on validation errors, dependency blockers, an unexpected writable
-  repository, or a conflicting active claim.
+- Stop on validation errors, dependency blockers, or an unexpected writable
+  repository.
 - 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/`.
 - Never invent entity IDs, revisions, PR state, dependency completion, or
   checkout state. Preserve parent backlinks and dependency declarations.
-- Do not bypass dirty-worktree, active-claim, revision, or readiness protections.
+- Do not bypass dirty-worktree, revision, or readiness protections.
 - Do not run `agency work` from an active agent session unless the user
   explicitly asks to launch another agent.
 - Run `agency validate` before worktree or pull-request operations.
@@ -189,10 +187,8 @@ resolve its reported commits and remediation commands before retrying.
 
 `agency work` is the human launch flow: it reconciles managed integration,
 selects work, checks readiness, prepares checkouts, marks execution work
-`working` without creating a claim, and starts the agent. Epic and multi-phase
-task launches remain orchestration-only. External orchestrators instead claim
-an execution unit, launch and monitor their agent separately, and finish or
-release the claim with the current document revision.
+`working`, and starts the agent. Epic and multi-phase task launches remain
+orchestration-only.
 
 An Agency-launched agent receives process-local worker identity through both
 the `AGENCY_SESSION_ID` and `AGENCY_TARGET` environment variables and a generated
@@ -228,13 +224,11 @@ intent, `--no-pull-request`, and a durable outcome summary.
 At each closeout trigger (creating or updating a PR, marking it ready, completing
 a refinement loop, or pausing or handing off completed implementation work):
 
-- Finish an active claim with the current revision via `agency finish`; a
-  successful claim outcome leaves unmerged work `working`. For unclaimed work,
-  keep the execution unit `working` through review and merge.
+- Keep the execution unit `working` through review and merge.
 - After merge, run `agency sync` to reconcile the execution unit to
   `done`.
-- For an approved non-PR outcome, finish an active claim or update unclaimed
-  status with `--no-pull-request --summary <text>` and optional supporting URL.
+- For an approved non-PR outcome, update status with
+  `--no-pull-request --summary <text>` and an optional supporting URL.
 - Refresh durable delivery context in `TASK.md` or `PHASE.md`, including recorded
   PR state, current head, diff summary, and verification results after later
   pushes when those details are maintained there.

package/src/workbase/agent-command.test.ts

@@ -12,9 +12,7 @@ const variables = {
 	target: "execution-unit:phase/task/build",
 	task: "task",
 	phase: "build",
-	claimant: "orchestrator",
 	sessionId: "session-1",
-	claimRevision: "revision-1",
 }
 
 describe("agent commands", () => {
@@ -116,7 +114,6 @@ describe("agent commands", () => {
 
 		expect(environment).toMatchObject({
 			AGENCY_AGENT: "custom",
-			AGENCY_CLAIMANT: "orchestrator",
 			AGENCY_SESSION_ID: "session-1",
 			AGENCY_WORKBASE: "/workbase",
 			AGENCY_TARGET: "execution-unit:phase/task/build",

package/src/workbase/agent-command.ts

@@ -6,9 +6,7 @@ export interface AgentCommandVariables {
 	readonly target: string
 	readonly task: string
 	readonly phase: string
-	readonly claimant: string
 	readonly sessionId: string
-	readonly claimRevision: string
 }
 
 interface AgentDefinition {
@@ -25,9 +23,7 @@ const PLACEHOLDERS = new Set<keyof AgentCommandVariables>([
 	"target",
 	"task",
 	"phase",
-	"claimant",
 	"sessionId",
-	"claimRevision",
 ])
 
 const BUILTIN_AGENTS: Readonly<Record<string, AgentDefinition>> = {
@@ -122,9 +118,7 @@ export const agentEnvironment = (
 	variables: AgentCommandVariables,
 ): Record<string, string> => ({
 	AGENCY_AGENT: agent,
-	AGENCY_CLAIMANT: variables.claimant,
 	AGENCY_SESSION_ID: variables.sessionId,
-	AGENCY_CLAIM_REVISION: variables.claimRevision,
 	AGENCY_WORKBASE: variables.workbase,
 	AGENCY_TARGET: variables.target,
 	AGENCY_TASK_ID: variables.task,

package/src/workbase/document-revision.ts

@@ -3,9 +3,6 @@ import { Data } from "effect"
 export const documentRevision = (content: string) =>
 	new Bun.CryptoHasher("sha256").update(content).digest("hex")
 
-export const isDocumentRevision = (revision: string) =>
-	/^[a-f0-9]{64}$/.test(revision)
-
 export class RevisionConflictError extends Data.TaggedError(
 	"RevisionConflictError",
 )<{
@@ -14,5 +11,4 @@ export class RevisionConflictError extends Data.TaggedError(
 	readonly target?: string
 	readonly expectedRevision: string
 	readonly currentRevision: string
-	readonly claim?: unknown
 }> {}

package/src/workbase/schemas.test.ts

@@ -2,7 +2,6 @@ import { describe, expect, test } from "bun:test"
 import { Schema } from "@effect/schema"
 import {
 	EntityId,
-	ClaimRecord,
 	EpicFrontmatter,
 	PhaseFrontmatter,
 	TaskFrontmatter,
@@ -401,30 +400,18 @@ describe("work status", () => {
 	})
 })
 
-describe("claim records", () => {
-	const record = {
-		claimant: "orchestrator",
-		agent: "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()
-		}
-	})
+test("rejects removed claim frontmatter", () => {
+	expect(() =>
+		Schema.decodeUnknownSync(TaskFrontmatter, { onExcessProperty: "error" })({
+			ticketUrl: null,
+			repo: "agency",
+			branch: "task/example",
+			base: "main",
+			pr: null,
+			status: "working",
+			claim: { state: "active" },
+		}),
+	).toThrow()
 })
 
 describe("workbase registry", () => {