@markjaquith/agency 2.52.2 → 2.54.0

package/README.md

@@ -10,7 +10,7 @@ read or write.
 - [Bun](https://bun.sh) 1.0 or newer
 - Git
 - [Jujutsu](https://jj-vcs.github.io/jj/) is preferred when available
-- [GitHub CLI](https://cli.github.com/) for `agency pr create`
+- [GitHub CLI](https://cli.github.com/) for `agency pr`
 - OpenCode, Claude Code, or a configured runner for `agency work`
 
 ## Installation
@@ -401,7 +401,8 @@ agency task new
 agency validate
 agency context tasks/refresh-copy --json
 agency work tasks/refresh-copy
-agency pr create refresh-copy
+cd tasks/refresh-copy
+agency pr create --fill
 ```
 
 After cloning an existing workbase on another machine, restore its declared
@@ -476,10 +477,10 @@ priority ready unit in human output.
 execution unit. Excluded entries retain status, terminal state, `blockedBy`, and
 detailed dependency, validation, or status blockers for orchestrators.
 
-`agency work` and `agency pr create` consult this shared readiness model before
-materializing or pushing. Blocked, done, and dropped targets are rejected unless
-`--force` is supplied explicitly. PR creation permits active `working` and
-`delegated` targets when they have no dependency or validation blocker.
+`agency work` consults this shared readiness model before materializing. Blocked,
+done, and dropped targets are rejected unless `--force` is supplied explicitly.
+`agency pr` leaves command semantics to `gh`; run `agency context . --json` first
+when readiness or validation state needs inspection.
 
 ### Reconciliation
 
@@ -488,9 +489,10 @@ materializations, then compares every execution declaration with local branch
 and worktree registration, checkout dirtiness, resolved reference commits, claim
 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.
+default mode applies safe reconciliation transitions; `--dry-run` is explicitly
+observational.
 
-`agency sync --apply` performs only these safe transitions:
+`agency sync` performs only these safe transitions:
 
 - materialize declared but missing repositories from their canonical remotes;
 - adopt legacy materializations only when they have an unambiguous portable origin;
@@ -721,7 +723,7 @@ 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.
 By default, `done` requires an authoritative merged pull request and is applied
-by `agency sync --apply`. Work whose intended outcome genuinely requires no pull
+by `agency sync`. Work whose intended outcome genuinely requires no pull
 request may instead use an explicit `--no-pull-request --summary <text>` status
 transition. Agency records the summary, completion time, and optional evidence
 URL durably; reopening removes that evidence. This exceptional path refuses work
@@ -803,7 +805,7 @@ for restoration. Archived IDs are reserved until restored.
 agency work [<directory> | --epic <epic-id>] [--runner <name>] [--auto] [--print-command]
 agency work prepare [target] [--dry-run] [--json]
 agency worktree <list|inspect|prepare|remove|rebuild|repair>
-agency pr create <task-id> [phase-id] [--draft] [--json]
+agency pr [args...]
 ```
 
 `agency work` presents the full hierarchy in the native OpenTUI selector or the
@@ -849,9 +851,9 @@ Agency resolves the ref to a commit and creates a detached worktree. Existing
 reference worktrees are reused only while their commit still matches the declared
 ref; use a commit SHA as `ref` when reproducibility matters.
 
-`agency pr create` requires a clean writable worktree. It pushes the branch,
-runs `gh pr create --fill`, and writes the returned GitHub PR URL into `pr` in
-the owning `TASK.md` or `PHASE.md`.
+`agency pr` forwards every argument to `gh pr`. From an execution task or phase
+directory, including descendants, it runs in that execution unit's authoritative
+writable checkout. Otherwise it runs in the caller's current directory.
 
 ### Status and Validation
 

package/cli-main.ts

@@ -134,6 +134,9 @@ const resolveInvocationCwd = (
 ) =>
 	runEffect(
 		Effect.gen(function* () {
+			if (commandName === "pr") {
+				return resolve(options.cwd ?? process.cwd())
+			}
 			if (
 				options.help ||
 				commandName === "init" ||
@@ -284,19 +287,7 @@ const commands: Record<string, Command> = {
 				console.log(prHelp)
 				return
 			}
-			await runCommand(
-				pr({
-					subcommand: args[0],
-					taskId: args[1],
-					phaseId: args[2],
-					draft: options.draft,
-					force: options.force,
-					json: options.json,
-					silent: options.silent,
-					verbose: options.verbose,
-					cwd: options.cwd,
-				}),
-			)
+			process.exitCode = await runEffect(pr(args, options.cwd))
 		},
 	},
 	phase: {
@@ -703,7 +694,6 @@ const commands: Record<string, Command> = {
 			}
 			await runCommand(
 				sync({
-					apply: options.apply,
 					dryRun: options["dry-run"],
 					json: options.json,
 					silent: options.silent,
@@ -736,7 +726,7 @@ Commands:
   worktree <subcommand>  Inspect and maintain managed workspaces
   vcs <subcommand>       Inspect or migrate the version-control backend
   next                   List or select ready execution units
-  pr create              Create a pull request for an execution unit
+  pr [args...]           Run gh pr with Agency repository focus
   review refresh         Explicitly refresh a pinned review task
   repo <subcommand>      Manage workbase repositories
   status                 Show status for the current workbase

package/fixtures/protocol/orchestration-recipes.json

@@ -30,7 +30,7 @@
   ["work", "prepare", "--task", "checkout", "--phase", "ui", "--json"],
   ["work", "tasks/checkout/phases/ui", "--runner", "opencode"],
   ["sync", "--dry-run", "--json"],
-  ["sync", "--apply", "--json"],
+  ["sync", "--json"],
   ["pr", "create", "checkout", "ui", "--json"],
   [
     "finish",

package/package.json

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

package/src/cli-parser.test.ts

@@ -292,7 +292,6 @@ describe("strict CLI parsing", () => {
 			[["restore", "task", "one", "two"], "agency restore task"],
 			[["restore", "phase", "one", "two", "three"], "agency restore phase"],
 			[["work", "one", "two"], "agency work"],
-			[["pr", "create", "one", "two", "three"], "agency pr create"],
 			[["status", "extra"], "agency status"],
 			[["validate", "one", "two"], "agency validate"],
 			[["context", "one", "two"], "agency context"],
@@ -358,27 +357,30 @@ describe("strict CLI parsing", () => {
 			commandName: "work",
 			values: { force: true },
 		})
-		expect(parseCli(["pr", "create", "example", "--force"])).toMatchObject({
-			commandName: "pr",
-			values: { force: true },
-		})
 		expect(() => parseCli(["work", "prepare", "example", "--force"])).toThrow(
 			"cannot be combined",
 		)
 	})
 
-	test("parses reconciliation modes and rejects conflicting modes", () => {
-		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
+	test("preserves every argument after pr without parsing it", () => {
+		const args = ["create", "--title", "two words", "--", "--literal"]
+		expect(parseCli(["--cwd", "/workbase", "pr", ...args])).toEqual({
+			commandName: "pr",
+			args,
+			values: { cwd: "/workbase" },
+		})
+	})
+
+	test("parses explicit dry-run reconciliation", () => {
+		expect(parseCli(["sync"])).toMatchObject({
 			commandName: "sync",
-			values: { "dry-run": true, json: true },
+			values: {},
 		})
-		expect(parseCli(["sync", "--apply"])).toMatchObject({
+		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
 			commandName: "sync",
-			values: { apply: true },
+			values: { "dry-run": true, json: true },
 		})
-		expect(() => parseCli(["sync", "--dry-run", "--apply"])).toThrow(
-			"cannot be combined",
-		)
+		expect(() => parseCli(["sync", "--apply"])).toThrow("Unknown option")
 	})
 
 	test("accepts archive dry-run", () => {

package/src/cli-parser.ts

@@ -678,18 +678,16 @@ const commands = {
 		},
 	},
 	sync: {
-		usage: "agency sync [--dry-run | --apply] [--json]",
+		usage: "agency sync [--dry-run] [--json]",
 		options: {
 			...outputOptions,
 			"dry-run": { type: "boolean" },
-			apply: { type: "boolean" },
 		},
 		command: {
-			usage: "agency sync [--dry-run | --apply] [--json]",
+			usage: "agency sync [--dry-run] [--json]",
 			minArgs: 0,
 			maxArgs: 0,
-			options: ["dry-run", "apply", "json"],
-			conflicts: [["dry-run", "apply"]],
+			options: ["dry-run", "json"],
 		},
 	},
 	archive: {
@@ -897,22 +895,12 @@ const commands = {
 		},
 	},
 	pr: {
-		usage: "agency pr create <task-id> [phase-id]",
-		options: {
-			...outputOptions,
-			draft: { type: "boolean" },
-			force: { type: "boolean" },
-			task: { type: "string" },
-			phase: { type: "string" },
-		},
-		subcommands: {
-			create: {
-				usage:
-					"agency pr create <task-id> [phase-id] [--draft] [--force] [--json]",
-				minArgs: 1,
-				maxArgs: 2,
-				options: ["draft", "force", "json", "task", "phase"],
-			},
+		usage: "agency pr [args...]",
+		options: commonOptions,
+		command: {
+			usage: "agency pr [args...]",
+			minArgs: 0,
+			maxArgs: Number.POSITIVE_INFINITY,
 		},
 	},
 	next: {
@@ -1103,7 +1091,6 @@ const targetSlots = (
 	if (commandName === "worktree" && subcommand !== "list") {
 		return ["task", "phase"]
 	}
-	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }
 
@@ -1324,6 +1311,35 @@ export function parseCli(args: readonly string[]): ParsedCli {
 			"agency <command> [options]",
 		)
 	}
+	if (commandName === "pr") {
+		const parsed = parse(
+			args.slice(0, commandIndex),
+			rootOptions,
+			"agency <command> [options]",
+		)
+		assertNoDuplicateOptions(
+			parsed.tokens,
+			new Set(),
+			"agency <command> [options]",
+		)
+		if (parsed.values.silent && parsed.values.verbose) {
+			throw usageError(
+				"Options '--silent' and '--verbose' cannot be combined.",
+				"agency <command> [options]",
+			)
+		}
+		if (parsed.values.workbase && parsed.values.cwd) {
+			throw usageError(
+				"Options '--workbase' and '--cwd' cannot be combined.",
+				"agency <command> [options]",
+			)
+		}
+		return {
+			commandName,
+			args: [...args.slice(commandIndex + 1)],
+			values: parsed.values,
+		}
+	}
 	const commandArgs = [
 		...args.slice(0, commandIndex),
 		...args.slice(commandIndex + 1),

package/src/cli.test.ts

@@ -1,5 +1,5 @@
 import { afterAll, afterEach, describe, expect, test } from "bun:test"
-import { access, mkdir, realpath, stat, symlink } from "node:fs/promises"
+import { access, chmod, mkdir, realpath, stat, symlink } from "node:fs/promises"
 import { join, sep } from "node:path"
 import errorFixture from "../fixtures/protocol/error.json"
 import successFixture from "../fixtures/protocol/success.json"
@@ -502,7 +502,7 @@ describe("CLI", () => {
 			["archive", "Usage: agency archive"],
 			["restore", "Usage: agency restore"],
 			["work", "Usage: agency work"],
-			["pr", "Usage: agency pr"],
+			["pr", "Work with GitHub pull requests."],
 			["status", "Usage: agency status"],
 			["validate", "Usage: agency validate"],
 			["context", "Usage: agency context"],
@@ -537,6 +537,34 @@ describe("CLI", () => {
 		expect(after).toEqual({ exitCode: 0, stdout: "", stderr: "" })
 	}, 30_000)
 
+	test("passes pr arguments and exit status through to gh", async () => {
+		const root = await createTempDir()
+		tempDirs.push(root)
+		const bin = join(root, "bin")
+		const capture = join(root, "capture")
+		await mkdir(bin)
+		await Bun.write(
+			join(bin, "gh"),
+			`#!/bin/sh
+printf '%s\n' "$PWD" "$@" > "$GH_CAPTURE"
+exit 23
+`,
+		)
+		await chmod(join(bin, "gh"), 0o755)
+		const args = ["pr", "create", "--title", "two words", "--", "literal"]
+
+		const result = await runCli(args, root, {
+			PATH: `${bin}:${process.env.PATH ?? ""}`,
+			GH_CAPTURE: capture,
+		})
+
+		expect(result).toEqual({ exitCode: 23, stdout: "", stderr: "" })
+		expect((await Bun.file(capture).text()).trim().split("\n")).toEqual([
+			await realpath(root),
+			...args,
+		])
+	})
+
 	test("lists ready work and exposes excluded blockers through one result", async () => {
 		const root = await createTempDir()
 		tempDirs.push(root)
@@ -570,20 +598,6 @@ describe("CLI", () => {
 				blockers: [{ kind: "status", reason: "Task status is dropped" }],
 			},
 		])
-
-		const blockedPr = await runCli(["pr", "create", "finished", "--json"], root)
-		expect(blockedPr.exitCode).toBe(1)
-		expect(blockedPr.stderr).toBe("")
-		expect(JSON.parse(blockedPr.stdout)).toMatchObject({
-			ok: false,
-			error: {
-				code: "EXECUTION_BLOCKED",
-				fields: {
-					status: "dropped",
-					blockers: [{ kind: "status", reason: "Task status is dropped" }],
-				},
-			},
-		})
 	})
 
 	test("reports and synchronizes managed integration files", async () => {

package/src/commands/claim.ts

@@ -117,6 +117,6 @@ export const finishHelp = `
 Usage: agency finish <task-id> [phase-id] --session-id <id> --revision <sha256> --outcome <done|dropped> [--no-pull-request --summary <text> [--evidence-url <url>]]
 
 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. Use
+working; agency sync marks the execution unit done after merge. Use
 --no-pull-request with a summary for an explicit non-PR completion.
 `

package/src/commands/pr.test.ts

@@ -1,45 +1,147 @@
-import { describe, expect, test } from "bun:test"
-import { Effect } from "effect"
-import { captureLogs } from "../test-utils"
-import { PullRequestService } from "../services/PullRequestService"
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { chmod, mkdir, realpath } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
 import { pr } from "./pr"
 
+const write = async (root: string, path: string, content: string) => {
+	const fullPath = join(root, path)
+	await mkdir(dirname(fullPath), { recursive: true })
+	await Bun.write(fullPath, content)
+}
+
 describe("pr command", () => {
-	test("outputs the created pull request URL as JSON", async () => {
-		const url = "https://github.com/markjaquith/agency/pull/123"
-		let received: unknown[] = []
-		const logs = await captureLogs(() =>
-			Effect.runPromise(
-				pr({
-					subcommand: "create",
-					taskId: "example",
-					phaseId: "implementation",
-					draft: true,
-					force: true,
-					cwd: "/workbase",
-					json: true,
-				}).pipe(
-					Effect.provideService(PullRequestService, {
-						create: (...args: unknown[]) => {
-							received = args
-							return Effect.succeed(url)
-						},
-					} as never),
-				) as Effect.Effect<void, unknown, never>,
-			),
+	let tempRoot: string
+	let capturePath: string
+	let originalPath: string | undefined
+
+	beforeEach(async () => {
+		tempRoot = await createTempDir()
+		capturePath = join(tempRoot, "capture")
+		const bin = join(tempRoot, "bin")
+		await mkdir(bin)
+		await Bun.write(
+			join(bin, "gh"),
+			`#!/bin/sh
+printf '%s\n' "$PWD" "$@" > "$GH_CAPTURE"
+exit "\${GH_EXIT:-0}"
+`,
+		)
+		await chmod(join(bin, "gh"), 0o755)
+		originalPath = process.env.PATH
+		process.env.PATH = `${bin}:${originalPath ?? ""}`
+		process.env.GH_CAPTURE = capturePath
+	})
+
+	afterEach(async () => {
+		process.env.PATH = originalPath
+		delete process.env.GH_CAPTURE
+		delete process.env.GH_EXIT
+		await cleanupTempDir(tempRoot)
+	})
+
+	const captured = async () =>
+		(await Bun.file(capturePath).text()).trim().split("\n")
+
+	const createExecutionWorkbase = async () => {
+		const root = join(tempRoot, "workbase")
+		await write(root, "agency.json", '{"version":2}\n')
+		await mkdir(join(root, "repos/agency"), { recursive: true })
+		await mkdir(join(root, "tasks/single/code/agency"), { recursive: true })
+		await write(
+			root,
+			"tasks/single/TASK.md",
+			`---
+ticketUrl: null
+repo: agency
+branch: feat/single
+base: main
+pr: null
+status: open
+---
+
+# Single
+`,
 		)
+		await mkdir(join(root, "tasks/multi/phases/build/code/agency"), {
+			recursive: true,
+		})
+		await write(
+			root,
+			"tasks/multi/TASK.md",
+			`---
+ticketUrl: null
+phases:
+  - id: build
+---
 
-		expect(JSON.parse(logs[0]!)).toEqual({ url })
-		expect(received).toEqual([
-			"example",
-			"implementation",
-			true,
-			"/workbase",
-			expect.objectContaining({
-				force: true,
-				draft: true,
-				json: true,
-			}),
+# Multi
+`,
+		)
+		await write(
+			root,
+			"tasks/multi/phases/build/PHASE.md",
+			`---
+repo: agency
+branch: feat/build
+base: main
+pr: null
+status: open
+---
+
+# Build
+`,
+		)
+		return root
+	}
+
+	test("focuses task and descendant invocations on the writable checkout", async () => {
+		const root = await createExecutionWorkbase()
+		const task = join(root, "tasks/single")
+		const descendant = join(task, "notes/deep")
+		await mkdir(descendant, { recursive: true })
+
+		for (const cwd of [task, descendant]) {
+			expect(await runTestEffect(pr(["view"], cwd))).toBe(0)
+			expect(await captured()).toEqual([
+				await realpath(join(task, "code/agency")),
+				"pr",
+				"view",
+			])
+		}
+	})
+
+	test("focuses a phase invocation on its writable checkout", async () => {
+		const root = await createExecutionWorkbase()
+		const phase = join(root, "tasks/multi/phases/build")
+
+		expect(await runTestEffect(pr(["status"], phase))).toBe(0)
+		expect(await captured()).toEqual([
+			await realpath(join(phase, "code/agency")),
+			"pr",
+			"status",
 		])
 	})
+
+	test("falls back to the invocation directory without execution authority", async () => {
+		const root = await createExecutionWorkbase()
+		const orchestration = join(root, "tasks/multi")
+		const outside = join(tempRoot, "outside")
+		await mkdir(outside)
+
+		for (const cwd of [orchestration, outside]) {
+			expect(await runTestEffect(pr(["list"], cwd))).toBe(0)
+			expect(await captured()).toEqual([await realpath(cwd), "pr", "list"])
+		}
+	})
+
+	test("forwards arguments unchanged and returns the gh exit code", async () => {
+		const outside = join(tempRoot, "outside")
+		await mkdir(outside)
+		process.env.GH_EXIT = "23"
+		const args = ["create", "--title", "two words", "--", "literal"]
+
+		expect(await runTestEffect(pr(args, outside))).toBe(23)
+		expect(await captured()).toEqual([await realpath(outside), "pr", ...args])
+	})
 })

package/src/commands/pr.ts

@@ -1,43 +1,31 @@
 import { Effect } from "effect"
-import type { BaseCommandOptions } from "../utils/command"
-import { PullRequestService } from "../services/PullRequestService"
-import { createLoggers } from "../utils/effect"
+import { resolve } from "node:path"
+import { ContextService } from "../services/ContextService"
+import { FileSystemService } from "../services/FileSystemService"
 
-interface PrOptions extends BaseCommandOptions {
-	readonly subcommand?: string
-	readonly taskId?: string
-	readonly phaseId?: string
-	readonly draft?: boolean
-	readonly force?: boolean
-}
-
-export const pr = (options: PrOptions) =>
+export const pr = (args: readonly string[], cwd: string = process.cwd()) =>
 	Effect.gen(function* () {
-		if (options.subcommand !== "create" || !options.taskId) {
-			return yield* Effect.fail(
-				new Error("Usage: agency pr create <task-id> [phase-id]"),
-			)
-		}
-		const pullRequests = yield* PullRequestService
-		const { log } = createLoggers(options)
-		const url = yield* pullRequests.create(
-			options.taskId,
-			options.phaseId,
-			options.draft,
-			options.cwd ?? process.cwd(),
-			options,
-		)
-		log(options.json ? JSON.stringify({ url }, null, 2) : url)
+		const contexts = yield* ContextService
+		const fs = yield* FileSystemService
+		const invocationCwd = resolve(cwd)
+		const context = yield* contexts
+			.get({ cwd: invocationCwd, target: ".", compact: true })
+			.pipe(Effect.catchAll(() => Effect.succeed(null)))
+		const writableCheckout =
+			context?.validation.valid && context.workspace?.writable?.materialized
+				? context.authority.writable?.checkoutPath
+				: null
+		const focusedCwd = writableCheckout ?? invocationCwd
+		const result = yield* fs.runCommand(["gh", "pr", ...args], {
+			cwd: focusedCwd,
+			passthrough: true,
+		})
+		return result.exitCode
 	})
 
 export const help = `
-Usage: agency pr create <task-id> [phase-id]
-
-Push the execution branch, create a pull request with the delivery provider,
-and update its task or phase document.
+Usage: agency pr [args...]
 
-Options:
-  --draft             Create a draft pull request
-  --force             Override readiness and terminal-state guards
-  --json              Output the pull request URL as JSON
+Run gh pr unchanged, focusing the writable repository checkout when invoked
+from an Agency execution task or phase.
 `

package/src/commands/sync.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test"
+import { Effect } from "effect"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { TaskService } from "../services/TaskService"
+import {
+	captureLogs,
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+} from "../test-utils"
+import { sync } from "./sync"
+
+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("sync command", () => {
+	let root: string
+
+	beforeEach(async () => {
+		root = await createTempDir()
+		const source = join(root, "source")
+		await mkdir(source)
+		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"))
+		await git(["clone", "--bare", source, join(root, "repos/agency")], root)
+		await Bun.write(join(root, "agency.json"), '{"version":2}\n')
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "example",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "task/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+	})
+
+	afterEach(async () => cleanupTempDir(root))
+
+	test("applies safe reconciliation by default", async () => {
+		const logs = await captureLogs(() => runTestEffect(sync({ cwd: root })))
+
+		expect(
+			await Bun.file(join(root, "tasks/example/code/agency/README.md")).text(),
+		).toBe("example\n")
+		expect(logs).toContainEqual(
+			expect.stringContaining("Applied materialize-workspace 'task:example'"),
+		)
+		expect(() => JSON.parse(logs.join("\n"))).toThrow()
+	})
+
+	test("keeps explicit dry-run observational", async () => {
+		await runTestEffect(sync({ cwd: root, dryRun: true, silent: true }))
+
+		expect(
+			await Bun.file(
+				join(root, "tasks/example/code/agency/README.md"),
+			).exists(),
+		).toBe(false)
+	})
+
+	test("preserves structured output behind --json", async () => {
+		const logs = await captureLogs(() =>
+			runTestEffect(sync({ cwd: root, dryRun: true, json: true })),
+		)
+
+		expect(logs).toHaveLength(1)
+		expect(JSON.parse(logs[0]!)).toMatchObject({
+			mode: "dry-run",
+			changes: [
+				expect.objectContaining({
+					kind: "materialize-workspace",
+					status: "planned",
+				}),
+			],
+		})
+	})
+})

package/src/commands/sync.ts

@@ -4,7 +4,6 @@ import type { BaseCommandOptions } from "../utils/command"
 import { createLoggers } from "../utils/effect"
 
 interface SyncCommandOptions extends BaseCommandOptions {
-	readonly apply?: boolean
 	readonly dryRun?: boolean
 }
 
@@ -14,24 +13,62 @@ export const sync = (options: SyncCommandOptions = {}) =>
 		const { log } = createLoggers(options)
 		const result = yield* service.reconcile({
 			cwd: options.cwd,
-			apply: options.apply === true,
+			apply: options.dryRun !== true,
 		})
-		log(JSON.stringify(result, null, 2))
+		if (options.json) return log(JSON.stringify(result, null, 2))
+
+		for (const action of result.repositories.actions) {
+			log(
+				`${action.status === "applied" ? "Applied" : "Planned"} repository ${action.kind} '${action.alias}' from ${action.remote}`,
+			)
+		}
+		for (const change of result.changes) {
+			log(
+				`${change.status === "applied" ? "Applied" : "Planned"} ${change.kind} '${change.target}': ${change.message}`,
+			)
+		}
+		for (const warning of result.warnings) {
+			log(
+				`Warning '${warning.target}': ${warning.message}${warning.action ? `. ${warning.action}` : ""}`,
+			)
+		}
+		for (const issue of result.repositories.unresolved) {
+			log(
+				`Unresolved repository '${issue.alias}': ${issue.message}. ${issue.action}`,
+			)
+		}
+		for (const issue of result.unresolved) {
+			log(
+				`Unresolved '${issue.target}': ${issue.message}${issue.action ? `. ${issue.action}` : ""}`,
+			)
+		}
+		if (
+			result.repositories.actions.length === 0 &&
+			result.changes.length === 0 &&
+			result.warnings.length === 0 &&
+			result.repositories.unresolved.length === 0 &&
+			result.unresolved.length === 0
+		) {
+			log(
+				result.mode === "apply"
+					? "Workbase sync is current"
+					: "Workbase sync plan is current",
+			)
+		}
 	})
 
 export const help = `
-Usage: agency sync [--dry-run | --apply] [--json]
+Usage: agency sync [--dry-run] [--json]
 
 Compare portable repository declarations and execution state with local Git
 repositories, worktrees, branches, references, claims, and pull requests.
-Dry-run is the default.
+Safe reconciliation transitions are applied by 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 declared repositories and unambiguous missing checkouts,
+Sync may materialize declared repositories and unambiguous missing checkouts,
 adopt legacy repositories with portable origins, release expired claims,
 record a uniquely matched PR, and mark merged work done. Dirty, stale, or
 conflicting checkouts are always left unresolved.

package/src/services/FileSystemService.ts

@@ -218,25 +218,34 @@ export class FileSystemService extends Effect.Service<FileSystemService>()(
 					readonly cwd?: string
 					readonly captureOutput?: boolean
 					readonly forwardOutput?: boolean
+					readonly passthrough?: boolean
 					readonly env?: Record<string, string>
 				},
 			) =>
 				pipe(
 					spawnProcess(args, {
 						cwd: options?.cwd,
-						stdin: "pipe",
-						stdout: options?.forwardOutput
-							? "tee"
-							: options?.captureOutput
-								? "pipe"
-								: "inherit",
-						stderr: options?.forwardOutput ? "tee" : "pipe",
+						stdin: options?.passthrough ? "inherit" : "pipe",
+						stdout: options?.passthrough
+							? "inherit"
+							: options?.forwardOutput
+								? "tee"
+								: options?.captureOutput
+									? "pipe"
+									: "inherit",
+						stderr: options?.passthrough
+							? "inherit"
+							: options?.forwardOutput
+								? "tee"
+								: "pipe",
 						env: options?.env,
 					}),
 					Effect.mapError(
 						(processError) =>
 							new FileSystemError({
-								message: `Failed to run command: ${args.join(" ")}`,
+								message: options?.passthrough
+									? processError.message
+									: `Failed to run command: ${args.join(" ")}`,
 								cause: processError,
 							}),
 					),

package/src/services/IntegrationService.test.ts

@@ -282,7 +282,7 @@ describe("IntegrationService", () => {
 		expect(body).toMatch(/completing\s+a refinement loop/)
 		expect(body).toContain("pausing or handing off")
 		expect(body).toContain("`agency finish`")
-		expect(body).toContain("`agency sync --apply`")
+		expect(body).toContain("`agency sync`")
 		expect(body).toContain("`--no-pull-request --summary <text>`")
 		expect(body).toContain("`TASK.md` or `PHASE.md`")
 		expect(body).toContain("PR state, current head, diff summary")

package/src/services/PhaseService.ts

@@ -654,7 +654,7 @@ export class PhaseService extends Effect.Service<PhaseService>()(
 						if (validStatus === "done") {
 							return yield* new PhaseError({
 								message:
-									"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
+									"Work becomes done after its authoritative pull request is merged; run 'agency sync', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 							})
 						}
 						return yield* new PhaseError({

package/src/services/TaskService.ts

@@ -381,7 +381,7 @@ export class TaskService extends Effect.Service<TaskService>()("TaskService", {
 					if (validStatus === "done") {
 						return yield* new TaskError({
 							message:
-								"Work becomes done after its authoritative pull request is merged; run 'agency sync --apply', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
+								"Work becomes done after its authoritative pull request is merged; run 'agency sync', or explicitly complete a non-PR outcome with '--no-pull-request --summary <text>'",
 						})
 					}
 					return yield* new TaskError({

package/src/workbase/AGENTS.md

@@ -59,8 +59,8 @@ to override readiness.
 - 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.
-- Create a pull request only with explicit user intent, using
-  `agency pr create <task> [phase]` so the URL is recorded durably.
+- Create a pull request only with explicit user intent. Run `agency pr create`
+  from its execution unit, then use `agency sync --apply` to reconcile PR state.
 
 ## Execution
 
@@ -91,7 +91,7 @@ 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.
-- After merge, run `agency sync --apply` to reconcile the execution unit to
+- 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.