@markjaquith/agency 2.52.2 → 2.53.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
 
@@ -803,7 +804,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 +850,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: {
@@ -736,7 +727,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@markjaquith/agency",
-  "version": "2.52.2",
+  "version": "2.53.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,15 +357,20 @@ 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("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 reconciliation modes and rejects conflicting modes", () => {
 		expect(parseCli(["sync", "--dry-run", "--json"])).toMatchObject({
 			commandName: "sync",

package/src/cli-parser.ts

@@ -897,22 +897,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 +1093,6 @@ const targetSlots = (
 	if (commandName === "worktree" && subcommand !== "list") {
 		return ["task", "phase"]
 	}
-	if (commandName === "pr" && subcommand === "create") return ["task", "phase"]
 	return []
 }
 
@@ -1324,6 +1313,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/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/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/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