@markjaquith/agency 2.39.2 → 2.40.1

package/README.md

@@ -427,7 +427,7 @@ materializing or pushing. Blocked, done, and dropped targets are rejected unless
 `agency sync` first compares portable repository declarations with local
 materializations, then compares every execution declaration with local branch
 and worktree registration, checkout dirtiness, resolved reference commits, claim
-expiry, and pull request and merge state. It reports
+expiry, and pull request state, merge state, and mergeability. It reports
 structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
 default and `--dry-run` modes are observational.
 
@@ -437,7 +437,7 @@ default and `--dry-run` modes are observational.
 - adopt legacy materializations only when they have an unambiguous portable origin;
 - materialize missing checkouts when no registration, branch, or path conflicts;
 - release an active claim only after its declared expiry has passed;
-- record a single PR whose head and base match the declaration; and
+- record or refresh a single PR whose head and base match the declaration; and
 - mark work done after its authoritative PR is merged and no active claim remains.
 
 Apply never overwrites linked or invalid repositories, repairs remote drift,
@@ -569,7 +569,7 @@ Targeted commands accept `--epic`, `--task`, and `--phase` where those entity
 kinds apply. A phase selector requires a task selector. Entity selectors cannot
 be mixed with positional target IDs, and an epic selector cannot be mixed with
 task or phase selectors. This makes commands such as
-`agency phase status done --task ship --phase release --workbase primary --no-input`
+`agency phase status working --task ship --phase release --workbase primary --no-input`
 fully independent of process cwd and prompts.
 
 Inspect tasks:
@@ -577,7 +577,7 @@ Inspect tasks:
 ```text
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|done|dropped> [--json]
+agency task status <id> <open|working|dropped> [--json]
 agency task update <id> [metadata options] [--json]
 agency task rename <id> <new-id> [--json]
 agency task move <id> (--epic <epic-id> | --no-epic) [--json]
@@ -616,7 +616,7 @@ agency phase create <task-id> <phase-id>
 
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
 agency phase update <task-id> <phase-id> [metadata options] [--json]
 agency phase rename <task-id> <phase-id> <new-id> [--json]
 agency phase dependency <add|remove> <task-id> <phase-id> <dependency-id>
@@ -639,6 +639,8 @@ writing anything.
 Single-phase tasks and phases store status in YAML. New execution units start
 `open`, and `agency work` marks the selected execution unit `working` immediately
 before launch. Running `agency work` again can relaunch unclaimed `working` work.
+The `done` status is reserved for an authoritative merged pull request and is
+applied by `agency sync --apply`, not by task or phase status commands.
 Use explicit claims only when an external orchestrator needs coordinated
 ownership. The interactive work selector displays status markers before
 execution units. Existing working and delegated work may be released to `open`
@@ -672,11 +674,12 @@ agency finish <task-id> [phase-id] --session-id <id>
   --revision <sha256> --outcome <done|dropped> [--json]
 ```
 
-An active claim sets status to `working`. Release returns it to `open`; finish
-sets the terminal outcome. Released and finished ownership metadata remains in
-frontmatter. Conflicts return the current revision and complete ownership record
-in the machine error envelope rather than overwriting it. Expired claims may be
-replaced with a revision-guarded claim.
+An active claim sets status to `working`. Release returns it to `open`. Finish
+records the claim outcome and ownership history; a `done` claim outcome leaves
+the execution unit `working` until its pull request is merged, while `dropped`
+remains terminal. Conflicts return the current revision and complete ownership
+record in the machine error envelope rather than overwriting it. Expired claims
+may be replaced with a revision-guarded claim.
 
 `agency work` does not claim execution units. It refuses active explicit claims,
 marks open execution work `working`, and launches the runner. External

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.39.2",
+  "version": "2.40.1",
   "description": "Manage agentic work across repositories with durable workbases",
   "keywords": [
     "agents",

package/skills/agency/SKILL.md

@@ -118,11 +118,12 @@ independently meaningful tasks need coordination.
 
 1. Re-run `agency validate` and repository checks.
 2. Create a PR only when requested: `agency pr create <task> [phase]`.
-3. Record terminal state only when the requested outcome is true. A created PR
-   alone does not make work `done` if completion requires merge.
-4. If the session has a claim, use revision-guarded `agency finish`; otherwise
-   use the task or phase status command. Use `dropped` only for intentionally
-   abandoned work.
+3. Keep committed work `working` while its pull request is open. After the
+   authoritative pull request merges, use `agency sync --apply` to reconcile it
+   to `done`.
+4. If the session has a claim, use revision-guarded `agency finish`; a successful
+   claim outcome closes ownership without marking unmerged work `done`. Use
+   `dropped` only for intentionally abandoned work.
 5. Report the durable status and PR URL. Do not manually remove the worktree.
 
 ## Human Launch vs Active Agent

package/skills/agency/references/commands.md

@@ -89,7 +89,7 @@ agency task create <id> --multi-phase [--ticket-url <url>]
   [--description <text>] [--epic <id>] [--json]
 agency task list [filters] [--json]
 agency task show <id> [--json]
-agency task status <id> <open|done|dropped> [--json]
+agency task status <id> <open|working|dropped> [--json]
 agency task update <id> [metadata options] [--if-revision <hash>] [--json]
 agency task rename <id> <new-id> [--if-revision <hash>] [--json]
 agency task move <id> (--epic <epic-id> | --no-epic)
@@ -102,7 +102,7 @@ agency phase create <task-id> <phase-id> --repo <alias> --branch <name>
   [--depends-on <phase-id>...] [--first-phase <phase-id>] [--json]
 agency phase list <task-id> [filters] [--json]
 agency phase show <task-id> <phase-id> [--json]
-agency phase status <task-id> <phase-id> <open|done|dropped> [--json]
+agency phase status <task-id> <phase-id> <open|working|dropped> [--json]
 agency phase update <task-id> <phase-id> [metadata options]
   [--if-revision <hash>] [--json]
 agency phase rename <task-id> <phase-id> <new-id>

package/skills/agency/references/contracts.md

@@ -126,7 +126,9 @@ status: open
 `ticketUrl` belongs to tasks and epics, not phases. `description` is optional but
 must be non-empty when present. `pr` is `null`, a legacy GitHub PR URL, or a
 provider-neutral record containing `provider`, `repository`, `identifier`, `url`,
-`state`, `draft`, and `merged`. New PR creation writes the structured record.
+`state`, `draft`, `merged`, and optional `mergeable`. Mergeability is `true`,
+`false`, or `null` when the provider cannot determine it. New PR creation writes
+the structured record.
 Status is `open`, `working`, `delegated`, `done`, or `dropped`; `delegated` is
 readable legacy state but cannot be newly assigned.
 
@@ -135,6 +137,8 @@ readable legacy state but cannot be newly assigned.
 - An execution unit has one writable `repo`; plural `repos` are read-only
   `{ repo, ref }` entries and cannot repeat the writable alias.
 - A writable `(repo, branch)` pair belongs to exactly one active execution unit.
+- `done` represents an authoritative merged pull request and is reconciled by
+  `agency sync --apply`; committed or review-ready work remains `working`.
 - Only `done` satisfies dependencies. `dropped` is terminal but blocks dependents.
 - Epic task dependencies live in `EPIC.md`; phase dependencies live in `TASK.md`.
 - IDs remain stable; use `dependsOn`, not numeric directory prefixes, for order.

package/skills/agency/references/recipes.md

@@ -184,15 +184,17 @@ agency release checkout ui --session-id session-123 \
 
 ## Finish Verified Work
 
-Only after the assigned completion condition is true:
+After the claimed run completes successfully:
 
 ```bash
 agency finish checkout ui --session-id session-123 \
   --revision <current-sha256> --outcome done --json
 ```
 
-Do not substitute `phase status done` for `finish` when an active claim exists;
-`finish` preserves ownership history and revision safety.
+Do not substitute a phase status mutation for `finish`; `finish` preserves
+ownership history and revision safety. A `done` claim outcome leaves unmerged
+execution work `working`. After the authoritative pull request merges, use
+`agency sync --apply` to reconcile the execution unit to `done`.
 
 ## Create A Pull Request
 
@@ -239,8 +241,9 @@ agency worktree repair <task-id> [phase-id] --dry-run --json
 
 Use `agency sync --apply` only with explicit user intent. It may safely
 materialize an unconflicted missing checkout, release an expired claim, record a
-single matching PR, or mark work done after its authoritative PR merged and no
-claim remains. It never modifies dirty checkouts, switches branches, resets
+single matching PR, refresh recorded PR state and mergeability, or mark work done
+after its authoritative PR merged and no claim remains. It never modifies dirty
+checkouts, switches branches, resets
 references, chooses among PRs, or bypasses active claims.
 
 For a worktree-specific issue, use `worktree repair --dry-run` before repair.

package/src/cli.test.ts

@@ -244,6 +244,10 @@ describe("CLI", () => {
 			),
 		)
 		expect(finished.claim).toMatchObject({ state: "finished", outcome: "done" })
+		expect(
+			parseJson(await runCli(["task", "show", "claimed", "--json"], root)).data
+				.status,
+		).toBe("working")
 	})
 
 	test("routes graph mutations through structured output", async () => {
@@ -476,7 +480,7 @@ describe("CLI", () => {
 			)
 		}
 		parseJson(
-			await runCli(["task", "status", "finished", "done", "--json"], root),
+			await runCli(["task", "status", "finished", "dropped", "--json"], root),
 		)
 
 		const human = await runCli(["next"], root)
@@ -490,9 +494,9 @@ describe("CLI", () => {
 		expect(result.excluded).toMatchObject([
 			{
 				key: "task/finished",
-				status: "done",
+				status: "dropped",
 				terminal: true,
-				blockers: [{ kind: "status", reason: "Task status is done" }],
+				blockers: [{ kind: "status", reason: "Task status is dropped" }],
 			},
 		])
 
@@ -504,8 +508,8 @@ describe("CLI", () => {
 			error: {
 				code: "EXECUTION_BLOCKED",
 				fields: {
-					status: "done",
-					blockers: [{ kind: "status", reason: "Task status is done" }],
+					status: "dropped",
+					blockers: [{ kind: "status", reason: "Task status is dropped" }],
 				},
 			},
 		})
@@ -1131,18 +1135,18 @@ status: open
 			}
 
 			parseJson(
-				await runCli(["task", "status", "example", "done", "--json"], root),
+				await runCli(["task", "status", "example", "dropped", "--json"], root),
 			)
 			const blocked = await runCli(
 				["work", "--task", "example", "--runner", "noop"],
 				root,
 			)
 			expect(blocked.exitCode).toBe(1)
-			expect(blocked.stderr).toContain("Task status is done")
+			expect(blocked.stderr).toContain("Task status is dropped")
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))
 					.data.status,
-			).toBe("done")
+			).toBe("dropped")
 
 			const resumedTask = await runCli(
 				["work", "--task", "example", "--runner", "noop", "--force"],
@@ -1150,7 +1154,7 @@ status: open
 			)
 			expect(resumedTask).toMatchObject({ exitCode: 0, stderr: "" })
 			expect(resumedTask.stdout).toContain(
-				"Reopened task/example from done as working",
+				"Reopened task/example from dropped as working",
 			)
 			expect(
 				parseJson(await runCli(["task", "show", "example", "--json"], root))

package/src/commands/claim.ts

@@ -93,5 +93,6 @@ Release an execution unit owned by the session.
 export const finishHelp = `
 Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped>
 
-Finish an execution unit owned by the session.
+Finish a claim owned by the session. A done claim outcome leaves unmerged work
+working; agency sync --apply marks the execution unit done after merge.
 `

package/src/commands/phase.ts

@@ -275,7 +275,7 @@ Subcommands:
   list <task>           List task phases
   show <task> <phase>   Show a phase
   status <task> <phase> <status>
-                        Set open, working, done, or dropped
+                        Set open, working, or dropped
   update <task> <phase> Update phase metadata
   rename <task> <phase> <new-id>
                         Rename a phase and update dependencies

package/src/commands/status.test.ts

@@ -74,7 +74,7 @@ describe("status command", () => {
 		await runTestEffect(
 			task({
 				subcommand: "status",
-				args: ["finished", "done"],
+				args: ["finished", "dropped"],
 				cwd: root,
 				silent: true,
 			}),

package/src/commands/task-phase.test.ts

@@ -239,13 +239,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				phase({
 					subcommand: "status",
-					args: ["multi", "first", "done"],
+					args: ["multi", "first", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(phaseLogs[0]!).data.status).toBe("working")
 
 		await runTestEffect(
 			task({
@@ -263,13 +263,13 @@ describe("task and phase command JSON output", () => {
 			runTestEffect(
 				task({
 					subcommand: "status",
-					args: ["single-status", "done"],
+					args: ["single-status", "working"],
 					cwd: root,
 					json: true,
 				}),
 			),
 		)
-		expect(JSON.parse(taskLogs[0]!).data.status).toBe("done")
+		expect(JSON.parse(taskLogs[0]!).data.status).toBe("working")
 	})
 
 	test("converts a single-phase task with an explicit first phase ID", async () => {

package/src/commands/task.ts

@@ -423,7 +423,7 @@ Subcommands:
   create <id>           Create a task without prompting
   list                  List tasks
   show <id>             Show a task
-  status <id> <status>  Set open, working, done, or dropped
+  status <id> <status>  Set open, working, or dropped
   update <id>           Update task metadata
   rename <id> <new-id>  Rename a task and update graph references
   move <id>             Move a task with --epic or --no-epic

package/src/readiness.ts

@@ -5,9 +5,9 @@ export interface ReadinessBlocker {
 }
 
 export const WORK_STATUS_TRANSITIONS = {
-	open: ["open", "working", "delegated", "done", "dropped"],
-	working: ["open", "working", "delegated", "done", "dropped"],
-	delegated: ["open", "working", "delegated", "done", "dropped"],
+	open: ["open", "working", "delegated", "dropped"],
+	working: ["open", "working", "delegated", "dropped"],
+	delegated: ["open", "working", "delegated", "dropped"],
 	done: ["open", "done"],
 	dropped: ["open", "dropped"],
 } as const satisfies Record<WorkStatus, readonly WorkStatus[]>

package/src/services/ClaimService.test.ts

@@ -139,7 +139,7 @@ describe("claim service", () => {
 				),
 			),
 		)
-		expect(finished.data.status).toBe("done")
+		expect(finished.data.status).toBe("working")
 		expect(finished.claim).toMatchObject({
 			state: "finished",
 			finishedAt: "2026-07-17T12:45:00.000Z",

package/src/services/ClaimService.ts

@@ -538,7 +538,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 									outcome: input.outcome,
 								}
 								return {
-									data: { ...data, status: input.outcome, claim },
+									data: {
+										...data,
+										status: input.outcome === "done" ? "working" : "dropped",
+										claim,
+									},
 									claim,
 								}
 							},

package/src/services/IntegrationService.test.ts

@@ -80,14 +80,15 @@ describe("IntegrationService", () => {
 		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`")
+		expect(body).toContain("An execution unit remains `working`")
 		expect(body).toContain("It becomes `done`")
-		expect(body).toContain("solely because its PR")
+		expect(body).toContain("Do not mark committed")
 		expect(body).toContain("creating or updating a PR")
 		expect(body).toContain("marking it ready")
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
-		expect(body).toContain("`agency task status` or `agency phase status`")
+		expect(body).toContain("`agency finish`")
+		expect(body).toContain("`agency sync --apply`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		expect(body).toContain("PR state, current head, diff summary")
 		expect(body).toContain("Run `agency validate` before reporting completion")

package/src/services/PhaseService.ts

@@ -487,6 +487,12 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						})
 					}
 					if (!canTransitionStatus(record.data.status, validStatus)) {
+						if (validStatus === "done") {
+							return yield* new PhaseError({
+								message:
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+							})
+						}
 						return yield* new PhaseError({
 							message: `Cannot transition phase '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 						})

package/src/services/PullRequestService.test.ts

@@ -263,11 +263,13 @@ process.exit(${exitCode})
 		await createTask()
 		await runTestEffect(
 			TaskService.pipe(
-				Effect.flatMap((service) => service.setStatus("example", "done", root)),
+				Effect.flatMap((service) =>
+					service.setStatus("example", "dropped", root),
+				),
 			),
 		)
 
-		await expect(createPullRequest()).rejects.toThrow("Task status is done")
+		await expect(createPullRequest()).rejects.toThrow("Task status is dropped")
 		expect(
 			await Bun.file(join(root, "tasks/example/code/agency")).exists(),
 		).toBe(false)

package/src/services/SyncService.test.ts

@@ -46,14 +46,18 @@ describe("SyncService", () => {
 		await Bun.write(
 			gh,
 			`#!/bin/sh
+case "$*" in
+*mergeable*) ;;
+*) echo "mergeable field was not requested" >&2; exit 2 ;;
+esac
 if [ "$2" = "view" ]; then
 cat <<'JSON'
-{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"}}
+{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}
 JSON
 exit 0
 fi
 cat <<'JSON'
-[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"}}]
+[{"number":42,"state":"MERGED","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":"2100-01-01T00:00:00Z","mergeCommit":{"oid":"abc"},"mergeable":"MERGEABLE"}]
 JSON
 `,
 		)
@@ -220,11 +224,86 @@ pr: null
 				state: "merged",
 				draft: false,
 				merged: true,
+				mergeable: true,
 			},
 			claim: { state: "released", sessionId: "session-1" },
 		})
 	})
 
+	test("records a conflicting open PR without changing lifecycle status", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("example", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"example",
+						undefined,
+						"https://github.com/example/agency/pull/42",
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(
+			join(root, "bin", "gh"),
+			`#!/bin/sh
+cat <<'JSON'
+{"number":42,"state":"OPEN","title":"Ship","isDraft":false,"headRefName":"feat/example","baseRefName":"main","url":"https://github.com/example/agency/pull/42","mergedAt":null,"mergeCommit":null,"mergeable":"CONFLICTING"}
+JSON
+`,
+		)
+		await chmod(join(root, "bin", "gh"), 0o755)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.changes).toContainEqual(
+			expect.objectContaining({ kind: "record-pr", target: "task:example" }),
+		)
+		expect(applied.changes.some((change) => change.kind === "mark-done")).toBe(
+			false,
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect(task.data).toMatchObject({
+			status: "open",
+			pr: { state: "open", merged: false, mergeable: false },
+		})
+	})
+
 	test("queries and records a configured delivery provider", async () => {
 		await runTestEffect(
 			TaskService.pipe(
@@ -311,6 +390,99 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		expect("pr" in task.data && task.data.pr).toEqual(record)
 	})
 
+	test("marks a successfully finished claim done only after merge", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "finished-claim",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("finished-claim", undefined, root),
+				),
+			),
+		)
+		await git(
+			["remote", "set-url", "origin", "git@github.com:example/agency.git"],
+			join(root, "repos/agency"),
+		)
+		const initial = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("finished-claim", undefined, root),
+				),
+			),
+		)
+		const claimed = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "finished-claim",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "session-1",
+							revision: initial.revision,
+						},
+						root,
+					),
+				),
+			),
+		)
+		const finished = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.finish(
+						{
+							taskId: "finished-claim",
+							sessionId: "session-1",
+							revision: claimed.revision,
+							outcome: "done",
+						},
+						root,
+					),
+				),
+			),
+		)
+		expect(finished.data).toMatchObject({
+			status: "working",
+			claim: { state: "finished", outcome: "done" },
+		})
+
+		const synced = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(synced.changes.map((change) => change.kind)).toContain("mark-done")
+		expect(
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) => service.show("finished-claim", root)),
+				),
+			),
+		).toMatchObject({
+			data: {
+				status: "done",
+				claim: { state: "finished", outcome: "done" },
+			},
+		})
+	})
+
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
 		for (const [id, branch] of [
 			["missing", "feat/missing"],

package/src/services/SyncService.ts

@@ -689,7 +689,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							"view",
 							existing.url,
 							"--json",
-							"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
+							"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit,mergeable",
 						])
 						if (viewed.exitCode === 0) {
 							const detail = parseJson<Record<string, unknown>>(
@@ -729,7 +729,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								"--state",
 								"all",
 								"--json",
-								"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
+								"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit,mergeable",
 							],
 							{ cwd: repositoryPath },
 						)

package/src/services/TaskPhaseService.test.ts

@@ -318,22 +318,23 @@ describe("task and phase services", () => {
 				),
 			),
 		).rejects.toThrow("Delegation requires explicit ownership")
-		await runTestEffect(
-			TaskService.pipe(
-				Effect.flatMap((service) =>
-					service.setStatus("single-status", "done", root),
-				),
-			),
-		)
 		await expect(
 			runTestEffect(
 				TaskService.pipe(
 					Effect.flatMap((service) =>
-						service.setStatus("single-status", "dropped", root),
+						service.setStatus("single-status", "done", root),
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
+		const droppedTask = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.setStatus("single-status", "dropped", root),
+				),
+			),
+		)
+		expect(droppedTask.data.status).toBe("dropped")
 
 		await runTestEffect(
 			TaskService.pipe(
@@ -389,7 +390,7 @@ describe("task and phase services", () => {
 					),
 				),
 			),
-		).rejects.toThrow("reopen it first")
+		).rejects.toThrow("authoritative pull request is merged")
 		await runTestEffect(
 			PhaseService.pipe(
 				Effect.flatMap((service) =>
@@ -397,17 +398,15 @@ describe("task and phase services", () => {
 				),
 			),
 		)
-		expect(
-			(
-				await runTestEffect(
-					PhaseService.pipe(
-						Effect.flatMap((service) =>
-							service.setStatus("multi-status", "implementation", "done", root),
-						),
+		await expect(
+			runTestEffect(
+				PhaseService.pipe(
+					Effect.flatMap((service) =>
+						service.setStatus("multi-status", "implementation", "done", root),
 					),
-				)
-			).data.status,
-		).toBe("done")
+				),
+			),
+		).rejects.toThrow("authoritative pull request is merged")
 		await expect(
 			runTestEffect(
 				TaskService.pipe(

package/src/services/TaskService.ts

@@ -270,6 +270,12 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					})
 				}
 				if (!canTransitionStatus(record.data.status, validStatus)) {
+					if (validStatus === "done") {
+						return yield* new TaskError({
+							message:
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply'",
+						})
+					}
 					return yield* new TaskError({
 						message: `Cannot transition task '${id}' from ${record.data.status} to ${validStatus}; reopen it first`,
 					})

package/src/workbase/AGENTS.md

@@ -48,17 +48,19 @@ reason to edit `agency.json` or `repos/` by hand.
 
 ## Closeout
 
-An execution unit is `working` while implementation or requested delivery work
-remains. It becomes `done` when both are complete, even if its PR remains open
-for review or merge. Do not leave a task or phase `working` solely because its PR
-is open; if merge was requested, merge remains delivery work.
+An execution unit remains `working` after implementation is committed and while
+its pull request is open. It becomes `done` only after its authoritative pull
+request is merged and Agency reconciles that state. Do not mark committed or
+review-ready work `done` manually.
 
 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`.
-  Otherwise use `agency task status` or `agency phase status` to set the
-  execution unit's current status.
+- 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.
+- After merge, run `agency sync --apply` to reconcile the execution unit to
+  `done`.
 - 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/delivery-command.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test"
 import {
 	parsePullRequestRecord,
+	recordFromGitHubJson,
 	resolveDeliveryCommand,
 	validateDelivery,
 } from "./delivery-command"
@@ -50,5 +51,37 @@ describe("delivery commands", () => {
 		expect(() =>
 			parsePullRequestRecord(JSON.stringify({ ...record, merged: false })),
 		).toThrow("inconsistent merge state")
+		expect(
+			parsePullRequestRecord(JSON.stringify({ ...record, mergeable: null })),
+		).toEqual({ ...record, mergeable: null })
+		expect(() =>
+			parsePullRequestRecord(JSON.stringify({ ...record, mergeable: "yes" })),
+		).toThrow("valid pull request record")
+	})
+
+	test("normalizes GitHub state and mergeability", () => {
+		const base = {
+			number: 17,
+			url: "https://github.com/example/agency/pull/17",
+			isDraft: false,
+		}
+		expect(
+			recordFromGitHubJson({ ...base, state: "OPEN", mergeable: "MERGEABLE" }),
+		).toMatchObject({ state: "open", merged: false, mergeable: true })
+		expect(
+			recordFromGitHubJson({
+				...base,
+				state: "OPEN",
+				mergeable: "CONFLICTING",
+			}),
+		).toMatchObject({ state: "open", merged: false, mergeable: false })
+		expect(
+			recordFromGitHubJson({
+				...base,
+				state: "CLOSED",
+				mergedAt: "2026-07-21T00:00:00Z",
+				mergeable: "UNKNOWN",
+			}),
+		).toMatchObject({ state: "merged", merged: true, mergeable: null })
 	})
 })

package/src/workbase/delivery-command.ts

@@ -119,13 +119,20 @@ export const recordFromGitHubUrl = (url: string): PullRequestRecord => {
 export const recordFromGitHubJson = (value: Record<string, unknown>) => {
 	const url = typeof value.url === "string" ? value.url : ""
 	const record = recordFromGitHubUrl(url)
-	const state = String(value.state ?? "OPEN").toLowerCase()
+	const githubState = String(value.state ?? "OPEN").toLowerCase()
+	const merged = githubState === "merged" || value.mergedAt != null
+	const mergeable = String(value.mergeable ?? "UNKNOWN").toLowerCase()
 	return {
 		...record,
-		state:
-			state === "merged" ? "merged" : state === "closed" ? "closed" : "open",
+		state: merged ? "merged" : githubState === "closed" ? "closed" : "open",
 		draft: value.isDraft === true,
-		merged: state === "merged" || value.mergedAt != null,
+		merged,
+		mergeable:
+			mergeable === "mergeable"
+				? true
+				: mergeable === "conflicting"
+					? false
+					: null,
 	} satisfies PullRequestRecord
 }
 

package/src/workbase/schemas.test.ts

@@ -185,11 +185,15 @@ describe("delivery configuration", () => {
 				state: "open",
 				draft: false,
 				merged: false,
+				mergeable: false,
 			},
 		})
 		expect(phase.pr && typeof phase.pr !== "string" && phase.pr.provider).toBe(
 			"forge",
 		)
+		expect(phase.pr && typeof phase.pr !== "string" && phase.pr.mergeable).toBe(
+			false,
+		)
 	})
 })
 

package/src/workbase/schemas.ts

@@ -72,6 +72,7 @@ export const PullRequestRecord = Schema.Struct({
 	state: Schema.Literal("open", "closed", "merged"),
 	draft: Schema.Boolean,
 	merged: Schema.Boolean,
+	mergeable: Schema.optional(Schema.NullOr(Schema.Boolean)),
 })
 
 const DeliveryProvider = Schema.Struct({