@markjaquith/agency 2.15.0 → 2.16.0

package/README.md

@@ -304,6 +304,25 @@ inspection are opt-in include layers.
 `end` record with counts. Combining the metadata with the streamed node and edge
 records reconstructs the same result as `--json`.
 
+### Reconciliation
+
+`agency sync` compares every execution declaration with local branch and worktree
+registration, writable and reference checkout dirtiness, resolved reference
+commits, claim expiry, and GitHub pull request and merge state. It reports
+structured `changes`, `warnings`, `unresolved`, and per-execution evidence. The
+default and `--dry-run` modes are observational.
+
+`agency sync --apply` performs only these safe transitions:
+
+- 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
+- mark work done after its authoritative PR is merged and no active claim remains.
+
+Apply never modifies dirty checkouts, moves worktrees, switches branches, resets
+reference commits, chooses among multiple PRs, or bypasses active claims. Those
+conditions remain visible in `warnings` or `unresolved` with a suggested action.
+
 ### Workbase and Repositories
 
 ```text
@@ -324,7 +343,7 @@ repository. Alias names are then used by all documents and commands.
 
 Commands that print Agency-owned results accept `--json`, including initialization,
 integration inspection/sync, repository mutations, entity creation/list/show,
-status, validation, graph export, and PR creation.
+status, validation, graph export, reconciliation, and PR creation.
 
 ### Epics
 

package/cli.ts

@@ -10,6 +10,7 @@ import { status, help as statusHelp } from "./src/commands/status"
 import { validate, help as validateHelp } from "./src/commands/validate"
 import { context, help as contextHelp } from "./src/commands/context"
 import { graph, help as graphHelp } from "./src/commands/graph"
+import { sync, help as syncHelp } from "./src/commands/sync"
 import { repo, help as repoHelp } from "./src/commands/repo"
 import { epic, help as epicHelp } from "./src/commands/epic"
 import { phase, help as phaseHelp } from "./src/commands/phase"
@@ -33,6 +34,7 @@ import { IntegrationService } from "./src/services/IntegrationService"
 import { ContextService } from "./src/services/ContextService"
 import { GraphService } from "./src/services/GraphService"
 import { ClaimService } from "./src/services/ClaimService"
+import { SyncService } from "./src/services/SyncService"
 import {
 	claimCommand,
 	claimHelp,
@@ -61,6 +63,7 @@ const CliLayer = Layer.mergeAll(
 	ContextService.Default,
 	GraphService.Default,
 	ClaimService.Default,
+	SyncService.Default,
 )
 
 /**
@@ -424,6 +427,23 @@ const commands: Record<string, Command> = {
 			)
 		},
 	},
+	sync: {
+		run: async (_args: string[], options: Record<string, any>) => {
+			if (options.help) {
+				console.log(syncHelp)
+				return
+			}
+			await runCommand(
+				sync({
+					apply: options.apply,
+					dryRun: options["dry-run"],
+					json: options.json,
+					silent: options.silent,
+					verbose: options.verbose,
+				}),
+			)
+		},
+	},
 }
 
 function showMainHelp() {
@@ -450,6 +470,7 @@ Commands:
   validate [path]        Validate a workbase
   context [target]       Return complete target context
   graph                  Export the complete workbase graph
+  sync                   Reconcile declarations with external state
 
 Global Options:
   -h, --help             Show help for a command

package/package.json

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

package/src/cli-parser.test.ts

@@ -141,6 +141,7 @@ describe("strict CLI parsing", () => {
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
 			[["graph", "extra"], "agency graph"],
+			[["sync", "extra"], "agency sync"],
 			[
 				[
 					"claim",
@@ -191,6 +192,20 @@ describe("strict CLI parsing", () => {
 		}
 	})
 
+	test("parses reconciliation modes and rejects conflicting modes", () => {
+		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
+			commandName: "sync",
+			values: { "dry-run": true, json: true },
+		})
+		expect(parseCli(["sync", "--apply"])).toMatchObject({
+			commandName: "sync",
+			values: { apply: true },
+		})
+		expect(() => parseCli(["sync", "--dry-run", "--apply"])).toThrow(
+			"cannot be combined",
+		)
+	})
+
 	test("validates revision-guarded claim operations", () => {
 		const revision = "0".repeat(64)
 		expect(

package/src/cli-parser.ts

@@ -319,6 +319,21 @@ const commands = {
 			required: ["session-id", "revision", "outcome"],
 		},
 	},
+	sync: {
+		usage: "agency sync [--dry-run | --apply] [--json]",
+		options: {
+			...outputOptions,
+			"dry-run": { type: "boolean" },
+			apply: { type: "boolean" },
+		},
+		command: {
+			usage: "agency sync [--dry-run | --apply] [--json]",
+			minArgs: 0,
+			maxArgs: 0,
+			options: ["dry-run", "apply", "json"],
+			conflicts: [["dry-run", "apply"]],
+		},
+	},
 	archive: {
 		usage: "agency archive <epic|task|phase>",
 		options: outputOptions,

package/src/commands/sync.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect"
+import { SyncService } from "../services/SyncService"
+import type { BaseCommandOptions } from "../utils/command"
+import { createLoggers } from "../utils/effect"
+
+interface SyncCommandOptions extends BaseCommandOptions {
+	readonly apply?: boolean
+	readonly dryRun?: boolean
+}
+
+export const sync = (options: SyncCommandOptions = {}) =>
+	Effect.gen(function* () {
+		const service = yield* SyncService
+		const { log } = createLoggers(options)
+		const result = yield* service.reconcile({
+			cwd: options.cwd,
+			apply: options.apply === true,
+		})
+		log(JSON.stringify(result, null, 2))
+	})
+
+export const help = `
+Usage: agency sync [--dry-run | --apply] [--json]
+
+Compare declared execution state with Git worktrees, branches, references, claims,
+and GitHub pull requests. Dry-run is the default.
+
+Options:
+  --dry-run                 Report planned safe transitions without changing state
+  --apply                   Apply safe reconciliation transitions
+  --json                    Output one versioned machine result
+
+Apply may materialize unambiguous missing checkouts, release expired claims,
+record a uniquely matched PR, and mark merged work done. Dirty, stale, or
+conflicting checkouts are always left unresolved.
+`

package/src/protocol.ts

@@ -111,6 +111,11 @@ const errorMetadata: Readonly<Record<string, ErrorMetadata>> = {
 		retryable: false,
 		remediation: "Correct the workbase graph data or filters and retry.",
 	},
+	SyncError: {
+		code: "SYNC_ERROR",
+		retryable: false,
+		remediation: "Resolve workbase validation errors before reconciling.",
+	},
 	ProcessError: { code: "PROCESS_ERROR", retryable: true },
 	ProtocolOutputError: {
 		code: "PROTOCOL_OUTPUT_ERROR",

package/src/services/ClaimService.ts

@@ -87,6 +87,23 @@ interface FinishInput extends OwnedClaimInput {
 	readonly outcome: "done" | "dropped"
 }
 
+interface ExpireClaimInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly now?: Date
+}
+
+interface ReconcileInput {
+	readonly taskId: string
+	readonly phaseId?: string
+	readonly revision: string
+	readonly pr?: string
+	readonly status?: "done"
+}
+
+const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
+
 type SingleTaskData = Extract<TaskData, { readonly repo: string }>
 type ExecutionData = SingleTaskData | PhaseData
 
@@ -286,6 +303,83 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 					}
 				}),
 
+			expire: (input: ExpireClaimInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data, now) => {
+								if (
+									data.claim?.state !== "active" ||
+									data.claim.expiresAt === undefined ||
+									Date.parse(data.claim.expiresAt) > now.getTime() ||
+									(data.status !== "working" && data.status !== "delegated")
+								) {
+									throw new ClaimError({
+										target: inspected.target.label,
+										message: `${inspected.target.label} does not have an expired active claim`,
+									})
+								}
+								const claim: ClaimRecord = {
+									...data.claim,
+									state: "released",
+									releasedAt: now.toISOString(),
+								}
+								return { data: { ...data, status: "open", claim }, claim }
+							},
+							input.now ?? new Date(),
+						),
+					)
+				}),
+
+			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
+				Effect.gen(function* () {
+					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+						return yield* new ClaimError({
+							message: `Invalid GitHub pull request URL: ${input.pr}`,
+						})
+					}
+					const service = yield* ClaimService
+					const inspected = yield* service.inspect(
+						input.taskId,
+						input.phaseId,
+						startPath,
+					)
+					return yield* operation(() =>
+						updateAtomically(
+							inspected.target,
+							input.revision,
+							(data) => {
+								if (input.status === "done" && data.claim?.state === "active") {
+									throw new ClaimConflictError({
+										target: inspected.target.label,
+										currentRevision: input.revision,
+										claim: data.claim,
+										message: `${inspected.target.label} has an active claim`,
+									})
+								}
+								return {
+									data: {
+										...data,
+										...(input.pr !== undefined ? { pr: input.pr } : {}),
+										...(input.status !== undefined
+											? { status: input.status }
+											: {}),
+									},
+								}
+							},
+							new Date(),
+						),
+					)
+				}),
+
 			claim: (input: ClaimInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
 					for (const [label, value] of [

package/src/services/SyncService.test.ts

@@ -0,0 +1,364 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { chmod, mkdir, rm } from "node:fs/promises"
+import { join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import { ClaimService } from "./ClaimService"
+import { PullRequestService } from "./PullRequestService"
+import { SyncService } from "./SyncService"
+import { TaskService } from "./TaskService"
+import { WorktreeService } from "./WorktreeService"
+
+const git = async (args: string[], cwd?: string) => {
+	const process = Bun.spawn(["git", ...args], {
+		cwd,
+		stdout: "pipe",
+		stderr: "pipe",
+	})
+	await process.exited
+	if (process.exitCode !== 0) {
+		throw new Error(await new Response(process.stderr).text())
+	}
+}
+
+describe("SyncService", () => {
+	let root: string
+	let originalPath: string | undefined
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		const source = join(root, "source")
+		await mkdir(source, { recursive: true })
+		await git(["init", "--initial-branch=main"], source)
+		await git(["config", "user.email", "test@example.com"], source)
+		await git(["config", "user.name", "Test"], source)
+		await Bun.write(join(source, "README.md"), "example\n")
+		await git(["add", "README.md"], source)
+		await git(["-c", "commit.gpgsign=false", "commit", "-m", "initial"], source)
+		await mkdir(join(root, "repos"), { recursive: true })
+		await git(["clone", "--bare", source, join(root, "repos/agency")])
+		await git(["clone", "--bare", source, join(root, "repos/reference")])
+
+		const bin = join(root, "bin")
+		await mkdir(bin)
+		const gh = join(bin, "gh")
+		await Bun.write(
+			gh,
+			`#!/bin/sh
+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"}}
+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"}}]
+JSON
+`,
+		)
+		await chmod(gh, 0o755)
+		originalPath = process.env.PATH
+		process.env.PATH = `${bin}:${originalPath}`
+	})
+
+	afterEach(async () => {
+		if (originalPath === undefined) delete process.env.PATH
+		else process.env.PATH = originalPath
+		await cleanupTempDir(root)
+	})
+
+	test("observes drift without mutation and applies only safe transitions", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							repos: [{ repo: "reference", ref: "main" }],
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = 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"),
+		)
+		const inspected = await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.inspect("example", undefined, root),
+				),
+			),
+		)
+		await runTestEffect(
+			ClaimService.pipe(
+				Effect.flatMap((service) =>
+					service.claim(
+						{
+							taskId: "example",
+							claimant: "orchestrator",
+							runner: "agent",
+							sessionId: "session-1",
+							revision: inspected.revision,
+							expiresAt: "2099-01-01T00:00:00.000Z",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(
+			join(workspace.codePath, "reference", "LOCAL.md"),
+			"dirty\n",
+		)
+
+		const taskPath = join(root, "tasks/example/TASK.md")
+		const before = await Bun.file(taskPath).text()
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, now: new Date("2100-01-02") }),
+				),
+			),
+		)
+
+		expect(observed.mode).toBe("dry-run")
+		expect(observed.warnings).toContainEqual(
+			expect.objectContaining({
+				kind: "dirty-reference",
+				target: "task:example",
+			}),
+		)
+		expect(observed.changes.map((change) => change.kind)).toEqual([
+			"release-stale-claim",
+			"record-pr",
+			"mark-done",
+		])
+		expect(await Bun.file(taskPath).text()).toBe(before)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({
+						cwd: root,
+						apply: true,
+						now: new Date("2100-01-02"),
+					}),
+				),
+			),
+		)
+		expect(applied.changes.map((change) => change.kind)).toEqual([
+			"release-stale-claim",
+			"record-pr",
+			"mark-done",
+		])
+		expect(applied.changes.every((change) => change.status === "applied")).toBe(
+			true,
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect(task.data).toMatchObject({
+			status: "done",
+			pr: "https://github.com/example/agency/pull/42",
+			claim: { state: "released", sessionId: "session-1" },
+		})
+	})
+
+	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
+		for (const [id, branch] of [
+			["missing", "feat/missing"],
+			["conflict", "feat/conflict"],
+		] as const) {
+			await runTestEffect(
+				TaskService.pipe(
+					Effect.flatMap((service) =>
+						service.create(
+							{ id, ticketUrl: null, repo: "agency", branch, base: "main" },
+							root,
+						),
+					),
+				),
+			)
+		}
+		const repository = join(root, "repos/agency")
+		await git(["branch", "feat/conflict", "main"], repository)
+		await git(
+			["worktree", "add", join(root, "external-conflict"), "feat/conflict"],
+			repository,
+		)
+
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(observed.changes).toContainEqual(
+			expect.objectContaining({
+				kind: "materialize-workspace",
+				target: "task:missing",
+				status: "planned",
+			}),
+		)
+		expect(observed.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "branch-conflict",
+				target: "task:conflict",
+			}),
+		)
+		expect(
+			await Bun.file(
+				join(root, "tasks/missing/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.changes).toContainEqual(
+			expect.objectContaining({
+				kind: "materialize-workspace",
+				target: "task:missing",
+				status: "applied",
+			}),
+		)
+		expect(
+			applied.executions.find((item) => item.target === "task:missing")
+				?.checkouts[0],
+		).toMatchObject({ exists: true, registered: true, dirty: false })
+		expect(
+			await Bun.file(join(root, "tasks/missing/code/agency/README.md")).text(),
+		).toBe("example\n")
+		expect(
+			await Bun.file(
+				join(root, "tasks/conflict/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("leaves a missing checkout registration unresolved", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "stale",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/stale",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		const workspace = await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("stale", undefined, root),
+				),
+			),
+		)
+		await rm(workspace.writablePath, { recursive: true, force: true })
+
+		const observed = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) => service.reconcile({ cwd: root })),
+			),
+		)
+		expect(observed.changes).toEqual([])
+		expect(observed.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "stale-registration",
+				target: "task:stale",
+			}),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.changes).toEqual([])
+		expect(
+			await Bun.file(join(workspace.writablePath, "README.md")).exists(),
+		).toBe(false)
+	})
+
+	test("does not trust a recorded PR from another repository", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"example",
+						undefined,
+						"https://github.com/other/repository/pull/42",
+						root,
+					),
+				),
+			),
+		)
+
+		const applied = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(applied.unresolved).toContainEqual(
+			expect.objectContaining({
+				kind: "pr-repository-conflict",
+				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" })
+	})
+})