@markjaquith/agency 2.21.0 → 2.22.0

package/package.json

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

package/src/commands/pr.ts

@@ -33,8 +33,8 @@ export const pr = (options: PrOptions) =>
 export const help = `
 Usage: agency pr create <task-id> [phase-id]
 
-Push the execution branch, create a GitHub pull request, and update its
-task or phase document.
+Push the execution branch, create a pull request with the delivery provider,
+and update its task or phase document.
 
 Options:
   --draft             Create a draft pull request

package/src/graph-schema.ts

@@ -2,6 +2,7 @@ import { Schema } from "@effect/schema"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
+	PullRequestRecord,
 	TaskFrontmatter,
 	WorkStatus,
 } from "./workbase/schemas"
@@ -109,16 +110,7 @@ export const GraphExecutionGit = Schema.Struct({
 export const GraphPr = Schema.Union(
 	Schema.Struct({ url: Schema.Null, state: Schema.Literal("none") }),
 	Schema.Struct({ url: Schema.String, state: Schema.Literal("unavailable") }),
-	Schema.Struct({
-		recordedUrl: Schema.String,
-		number: Schema.Number,
-		state: Schema.String,
-		title: Schema.String,
-		isDraft: Schema.Boolean,
-		headRefName: Schema.String,
-		baseRefName: Schema.String,
-		url: Schema.String,
-	}),
+	PullRequestRecord,
 )
 
 const NodeIdentity = {

package/src/services/ClaimService.ts

@@ -23,6 +23,7 @@ import {
 	PhaseFrontmatter,
 	TaskFrontmatter,
 	type ClaimRecord,
+	type PullRequestRecord,
 	type PhaseFrontmatter as PhaseData,
 	type TaskFrontmatter as TaskData,
 } from "../workbase/schemas"
@@ -98,7 +99,7 @@ interface ReconcileInput {
 	readonly taskId: string
 	readonly phaseId?: string
 	readonly revision: string
-	readonly pr?: string
+	readonly pr?: string | PullRequestRecord
 	readonly status?: "done"
 }
 
@@ -341,7 +342,11 @@ export class ClaimService extends Effect.Service<ClaimService>()(
 
 			reconcile: (input: ReconcileInput, startPath: string = process.cwd()) =>
 				Effect.gen(function* () {
-					if (input.pr !== undefined && !PR_URL.test(input.pr)) {
+					if (
+						typeof input.pr === "string" &&
+						input.pr !== undefined &&
+						!PR_URL.test(input.pr)
+					) {
 						return yield* new ClaimError({
 							message: `Invalid GitHub pull request URL: ${input.pr}`,
 						})

package/src/services/ContextService.ts

@@ -3,6 +3,7 @@ import { Data, Effect, Either } from "effect"
 import { join, relative, resolve, sep } from "node:path"
 import { FileSystemService } from "./FileSystemService"
 import { WorkbaseService } from "./WorkbaseService"
+import { normalizePullRequestRecord } from "../workbase/delivery-command"
 import { RepositoryService } from "./RepositoryService"
 import { aggregateProgress, readinessState } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
@@ -857,10 +858,9 @@ export class ContextService extends Effect.Service<ContextService>()(
 									references: referenceCheckouts,
 									warnings: inspectionWarnings,
 								},
-						pr: {
-							url: executionData?.pr ?? null,
-							state: executionData?.pr ? "recorded" : "none",
-						},
+						pr: executionData?.pr
+							? normalizePullRequestRecord(executionData.pr)
+							: { url: null, state: "none" },
 						validation: {
 							valid: validation.valid,
 							warnings: validation.issues,

package/src/services/GraphService.ts

@@ -20,6 +20,7 @@ import {
 	readinessState,
 } from "../readiness"
 import { parseFrontmatter } from "../workbase/frontmatter"
+import { normalizePullRequestRecord } from "../workbase/delivery-command"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
@@ -683,17 +684,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 								if (!data.pr) {
 									result.pr = { url: null, state: "none" }
 								} else {
-									const detail = yield* run(fs, [
-										"gh",
-										"pr",
-										"view",
-										data.pr,
-										"--json",
-										"number,state,title,isDraft,headRefName,baseRefName,url",
-									])
-									result.pr = detail
-										? { ...JSON.parse(detail), recordedUrl: data.pr }
-										: { url: data.pr, state: "unavailable" }
+									result.pr = normalizePullRequestRecord(data.pr)
 								}
 							}
 							return result

package/src/services/PullRequestService.test.ts

@@ -187,7 +187,12 @@ process.exit(${exitCode})
 				Effect.flatMap((service) => service.show("example", root)),
 			),
 		)
-		expect("pr" in task.data && task.data.pr).toBe(url)
+		expect("pr" in task.data && task.data.pr).toMatchObject({
+			provider: "github",
+			repository: "markjaquith/agency",
+			identifier: "123",
+			url,
+		})
 	})
 
 	test("rejects non-GitHub PR URLs", async () => {
@@ -228,7 +233,8 @@ process.exit(${exitCode})
 			cwd: await realpath(join(root, "tasks", "example", "code", "agency")),
 		})
 		const updated = await Bun.file(taskPath).text()
-		expect(updated).toContain("pr: https://github.com/example/agency/pull/42")
+		expect(updated).toContain("pr:\n  provider: github")
+		expect(updated).toContain("url: https://github.com/example/agency/pull/42")
 		expect(updated.endsWith(`${body}\n`)).toBe(true)
 	})
 
@@ -315,7 +321,7 @@ process.exit(${exitCode})
 		await createPullRequest("multi", "implementation")
 
 		expect(await Bun.file(taskPath).text()).toBe(originalTask)
-		expect(await Bun.file(phasePath).text()).toContain(`pr: ${url}`)
+		expect(await Bun.file(phasePath).text()).toContain(`url: ${url}`)
 		await expectRemoteBranch("task/multi-implementation")
 	})
 
@@ -400,7 +406,88 @@ process.exit(${exitCode})
 				Effect.flatMap((service) => service.show("example", root)),
 			),
 		)
-		expect("pr" in task.data && task.data.pr).toBe(url)
+		expect("pr" in task.data && task.data.pr).toMatchObject({ url })
+	})
+
+	test("uses a configured remote and argv provider", async () => {
+		await createTask()
+		await requireCommand(
+			["git", "remote", "rename", "origin", "upstream"],
+			join(root, "repos", "agency"),
+		)
+		const callPath = join(root, "delivery-call.json")
+		const providerRecord = {
+			provider: "forge",
+			repository: remotePath.replace(/\.git$/, ""),
+			identifier: "17",
+			url: "https://forge.example/example/agency/pulls/17",
+			state: "open",
+			draft: false,
+			merged: false,
+		} as const
+		await Bun.write(
+			join(root, "bin", "deliver"),
+			`#!/usr/bin/env bun
+await Bun.write(${JSON.stringify(callPath)}, JSON.stringify({ args: Bun.argv.slice(2), base: process.env.DELIVERY_BASE }))
+process.stdout.write(${JSON.stringify(JSON.stringify(providerRecord))})
+`,
+		)
+		await chmod(join(root, "bin", "deliver"), 0o755)
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				delivery: {
+					provider: "forge",
+					remote: "upstream",
+					createCommand: ["deliver", "create", "{repository}", "{branch}"],
+					queryCommand: ["deliver", "query", "{identifier}"],
+					environment: { DELIVERY_BASE: "{base}" },
+				},
+			}),
+		)
+
+		expect(await createPullRequest()).toBe(providerRecord.url)
+		expect(await Bun.file(callPath).json()).toEqual({
+			args: ["create", remotePath.replace(/\.git$/, ""), "task/example"],
+			base: "main",
+		})
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toEqual(providerRecord)
+	})
+
+	test("does not persist malformed provider output", async () => {
+		await createTask()
+		await Bun.write(
+			join(root, "bin", "deliver"),
+			"#!/usr/bin/env bun\nprocess.stdout.write('{}')\n",
+		)
+		await chmod(join(root, "bin", "deliver"), 0o755)
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				delivery: {
+					provider: "forge",
+					createCommand: ["deliver", "create"],
+					queryCommand: ["deliver", "query"],
+				},
+			}),
+		)
+
+		await expect(createPullRequest()).rejects.toThrow(
+			"Delivery provider did not return a valid pull request record",
+		)
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("example", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toBeNull()
 	})
 
 	test("reports git status failure before push or gh", async () => {

package/src/services/PullRequestService.ts

@@ -10,12 +10,24 @@ import {
 	formatMarkdownDocument,
 	parseFrontmatter,
 } from "../workbase/frontmatter"
+import type { PullRequestRecord } from "../workbase/schemas"
+import {
+	normalizePullRequestRecord,
+	parsePullRequestRecord,
+	recordFromGitHubUrl,
+	resolveDeliveryCommand,
+} from "../workbase/delivery-command"
 
 class PullRequestError extends Data.TaggedError("PullRequestError")<{
 	readonly message: string
 }> {}
 
-const PR_URL = /^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/
+const repositoryFromRemote = (remote: string) =>
+	remote
+		.replace(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?[^/]+\//i, "")
+		.replace(/^[^:]+:/, "")
+		.replace(/\.git\/?$/, "")
+		.replace(/\/$/, "")
 
 interface PullRequestOptions extends BaseCommandOptions {
 	readonly force?: boolean
@@ -25,25 +37,20 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 	"PullRequestService",
 	{
 		sync: () => ({
-			setUrl: (
+			setRecord: (
 				taskId: string,
 				phaseId: string | undefined,
-				url: string,
+				record: PullRequestRecord,
 				startPath: string = process.cwd(),
 			) =>
 				Effect.gen(function* () {
-					if (!PR_URL.test(url)) {
-						return yield* new PullRequestError({
-							message: `Invalid GitHub pull request URL: ${url}`,
-						})
-					}
 					const fs = yield* FileSystemService
 					const workbase = yield* WorkbaseService
 					const tasks = yield* TaskService
 					const phases = yield* PhaseService
 					const root = yield* workbase.discover(startPath)
 					const task = yield* tasks.show(taskId, root)
-					const record =
+					const target =
 						"phases" in task.data
 							? phaseId
 								? yield* phases.show(taskId, phaseId, root)
@@ -51,13 +58,30 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 										message: `Task '${taskId}' requires a phase ID`,
 									})
 							: task
-					const parsed = yield* parseFrontmatter(record.content, record.path)
-					const data = { ...record.data, pr: url }
+					const parsed = yield* parseFrontmatter(target.content, target.path)
 					yield* fs.writeFile(
-						record.path,
-						formatMarkdownDocument(data, parsed.body),
+						target.path,
+						formatMarkdownDocument({ ...target.data, pr: record }, parsed.body),
 					)
-					return url
+					return record.url
+				}),
+
+			setUrl: (
+				taskId: string,
+				phaseId: string | undefined,
+				url: string,
+				startPath: string = process.cwd(),
+			) =>
+				Effect.gen(function* () {
+					const service = yield* PullRequestService
+					const record = yield* Effect.try({
+						try: () => recordFromGitHubUrl(url),
+						catch: (cause) =>
+							new PullRequestError({
+								message: cause instanceof Error ? cause.message : String(cause),
+							}),
+					})
+					return yield* service.setRecord(taskId, phaseId, record, startPath)
 				}),
 
 			create: (
@@ -74,6 +98,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 					const phases = yield* PhaseService
 					const worktrees = yield* WorktreeService
 					const readiness = yield* ReadinessService
+					const workbase = yield* WorkbaseService
 					yield* readiness.guard(
 						"pr",
 						taskId,
@@ -92,6 +117,8 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						"phases" in task.data
 							? (yield* phases.show(taskId, phaseId!, workspace.root)).data
 							: task.data
+					const { config } = yield* workbase.loadConfig(workspace.root)
+					const remote = config.delivery?.remote ?? "origin"
 
 					const status = yield* fs.runCommand(
 						["git", "-C", workspace.writablePath, "status", "--porcelain"],
@@ -115,7 +142,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 							workspace.writablePath,
 							"push",
 							"--set-upstream",
-							"origin",
+							remote,
 							execution.branch,
 						],
 						{ captureOutput: true },
@@ -126,33 +153,83 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 						})
 					}
 
-					const args = [
-						"gh",
-						"pr",
-						"create",
-						"--fill",
-						"--base",
-						execution.base,
-					]
-					if (draft) args.push("--draft")
-					const created = yield* fs.runCommand(args, {
+					const remoteResult = yield* fs.runCommand(
+						["git", "-C", workspace.writablePath, "remote", "get-url", remote],
+						{ captureOutput: true },
+					)
+					if (remoteResult.exitCode !== 0) {
+						return yield* new PullRequestError({
+							message: `Failed to inspect delivery remote '${remote}': ${remoteResult.stderr}`,
+						})
+					}
+					const repository = repositoryFromRemote(remoteResult.stdout.trim())
+					const resolved = config.delivery
+						? resolveDeliveryCommand(config.delivery, "create", {
+								repository,
+								branch: execution.branch,
+								base: execution.base,
+								draft: String(draft),
+								url: "",
+								identifier: "",
+							})
+						: {
+								argv: [
+									"gh",
+									"pr",
+									"create",
+									"--fill",
+									"--base",
+									execution.base,
+									...(draft ? ["--draft"] : []),
+								],
+								environment: {},
+							}
+					const created = yield* fs.runCommand(resolved.argv, {
 						cwd: workspace.writablePath,
 						captureOutput: true,
+						env: resolved.environment,
 					})
 					if (created.exitCode !== 0) {
 						return yield* new PullRequestError({
 							message: `Failed to create pull request: ${created.stderr}`,
 						})
 					}
-					const url = created.stdout
-						.split(/\s+/)
-						.find((value) => PR_URL.test(value))
-					if (!url) {
+					const record = yield* Effect.try({
+						try: () => {
+							if (config.delivery) return parsePullRequestRecord(created.stdout)
+							const url = created.stdout.split(/\s+/).find((value) => {
+								try {
+									recordFromGitHubUrl(value)
+									return true
+								} catch {
+									return false
+								}
+							})
+							if (!url)
+								throw new Error("GitHub CLI did not return a pull request URL")
+							return { ...normalizePullRequestRecord(url), draft }
+						},
+						catch: (cause) =>
+							new PullRequestError({
+								message: cause instanceof Error ? cause.message : String(cause),
+							}),
+					})
+					if (
+						config.delivery &&
+						(record.provider !== config.delivery.provider ||
+							record.repository.toLowerCase() !== repository.toLowerCase())
+					) {
 						return yield* new PullRequestError({
-							message: "GitHub CLI did not return a pull request URL",
+							message:
+								"Delivery provider returned a record for the wrong provider or repository",
 						})
 					}
-					return yield* service.setUrl(taskId, phaseId, url, workspace.root)
+					return yield* service.setRecord(
+						taskId,
+						phaseId,
+						record,
+						workspace.root,
+					)
 				}),
 		}),
 	},

package/src/services/SyncService.test.ts

@@ -176,11 +176,105 @@ JSON
 		)
 		expect(task.data).toMatchObject({
 			status: "done",
-			pr: "https://github.com/example/agency/pull/42",
+			pr: {
+				provider: "github",
+				repository: "example/agency",
+				identifier: "42",
+				url: "https://github.com/example/agency/pull/42",
+				state: "merged",
+				draft: false,
+				merged: true,
+			},
 			claim: { state: "released", sessionId: "session-1" },
 		})
 	})
 
+	test("queries and records a configured delivery provider", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "custom",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/custom",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			WorktreeService.pipe(
+				Effect.flatMap((service) =>
+					service.materialize("custom", undefined, root),
+				),
+			),
+		)
+		await git(
+			[
+				"remote",
+				"set-url",
+				"origin",
+				"https://forge.example/example/agency.git",
+			],
+			join(root, "repos/agency"),
+		)
+		const callPath = join(root, "query-call.json")
+		const record = {
+			provider: "forge",
+			repository: "example/agency",
+			identifier: "17",
+			url: "https://forge.example/example/agency/pulls/17",
+			state: "open",
+			draft: false,
+			merged: false,
+		} as const
+		await Bun.write(
+			join(root, "bin", "deliver"),
+			`#!/usr/bin/env bun
+await Bun.write(${JSON.stringify(callPath)}, JSON.stringify({ args: Bun.argv.slice(2), base: process.env.DELIVERY_BASE }))
+process.stdout.write(${JSON.stringify(JSON.stringify(record))})
+`,
+		)
+		await chmod(join(root, "bin", "deliver"), 0o755)
+		await Bun.write(
+			join(root, "agency.json"),
+			JSON.stringify({
+				version: 2,
+				delivery: {
+					provider: "forge",
+					createCommand: ["deliver", "create"],
+					queryCommand: ["deliver", "query", "{repository}", "{branch}"],
+					environment: { DELIVERY_BASE: "{base}" },
+				},
+			}),
+		)
+
+		const result = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, apply: true }),
+				),
+			),
+		)
+		expect(result.changes).toContainEqual(
+			expect.objectContaining({ kind: "record-pr", target: "task:custom" }),
+		)
+		expect(await Bun.file(callPath).json()).toEqual({
+			args: ["query", "example/agency", "feat/custom"],
+			base: "main",
+		})
+		const task = await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) => service.show("custom", root)),
+			),
+		)
+		expect("pr" in task.data && task.data.pr).toEqual(record)
+	})
+
 	test("materializes missing workspaces but leaves branch conflicts unresolved", async () => {
 		for (const [id, branch] of [
 			["missing", "feat/missing"],

package/src/services/SyncService.ts

@@ -1,4 +1,4 @@
-import { Data, Effect } from "effect"
+import { Data, Effect, Either } from "effect"
 import { dirname, join, resolve } from "node:path"
 import { documentRevision } from "../workbase/document-revision"
 import type {
@@ -7,7 +7,14 @@ import type {
 	RepositoryReference,
 	TaskFrontmatter,
 	WorkStatus,
+	PullRequestRecord,
 } from "../workbase/schemas"
+import {
+	normalizePullRequestRecord,
+	parseOptionalPullRequestRecord,
+	recordFromGitHubJson,
+	resolveDeliveryCommand,
+} from "../workbase/delivery-command"
 import { ClaimService } from "./ClaimService"
 import { FileSystemService } from "./FileSystemService"
 import { PhaseService } from "./PhaseService"
@@ -143,7 +150,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const phases = yield* PhaseService
 				const worktrees = yield* WorktreeService
 				const claims = yield* ClaimService
-				const root = yield* workbase.discover(options.cwd)
+				const { root, config } = yield* workbase.loadConfig(options.cwd)
 				const validation = yield* workbase.validate(root)
 				if (!validation.valid) {
 					return yield* new SyncError({
@@ -161,12 +168,16 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				const executions: ExecutionSyncState[] = []
 				const runExternal = (
 					args: readonly string[],
-					commandOptions?: { readonly cwd?: string },
+					commandOptions?: {
+						readonly cwd?: string
+						readonly env?: Record<string, string>
+					},
 				) =>
 					fs
 						.runCommand(args, {
 							cwd: commandOptions?.cwd,
 							captureOutput: true,
+							env: commandOptions?.env,
 						})
 						.pipe(
 							Effect.catchAll((error) =>
@@ -551,50 +562,127 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						})
 					}
 
-					let pr: Record<string, unknown> = { url: data.pr, state: "none" }
+					const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
+					let current: PullRequestRecord | null = existing
+					let pr: Record<string, unknown> = existing ?? {
+						url: null,
+						state: "none",
+					}
 					let prConflict = false
-					if (data.pr) {
-						const remote = yield* runExternal([
-							"git",
-							"-C",
-							join(root, "repos", data.repo),
-							"remote",
-							"get-url",
-							"origin",
-						])
-						const remoteRepository = remote.stdout
-							.trim()
-							.match(/(?:github\.com[/:])([^/]+\/[^/]+)$/)?.[1]
-							?.replace(/\.git$/, "")
-						const prRepository = data.pr.match(
-							/^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/\d+\/?$/,
-						)?.[1]
-						if (
-							!remoteRepository ||
-							remoteRepository.toLowerCase() !== prRepository?.toLowerCase()
-						) {
-							prConflict = true
-							unresolved.push({
-								kind: "pr-repository-conflict",
+					const repositoryPath = join(root, "repos", data.repo)
+					const remoteName = config.delivery?.remote ?? "origin"
+					const remote = yield* runExternal([
+						"git",
+						"-C",
+						repositoryPath,
+						"remote",
+						"get-url",
+						remoteName,
+					])
+					const remoteRepository = remote.stdout
+						.trim()
+						.replace(/^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]+@)?[^/]+\//i, "")
+						.replace(/^[^:]+:/, "")
+						.replace(/\.git\/?$/, "")
+						.replace(/\/$/, "")
+
+					if (
+						existing &&
+						remoteRepository.toLowerCase() !== existing.repository.toLowerCase()
+					) {
+						prConflict = true
+						unresolved.push({
+							kind: "pr-repository-conflict",
+							target: record.key,
+							message: `Recorded PR repository does not match writable repository remote '${remoteName}'`,
+							action: "Correct the configured remote or recorded PR",
+						})
+					}
+
+					if (config.delivery && remote.exitCode !== 0) {
+						warnings.push({
+							kind: "delivery-remote-unavailable",
+							target: record.key,
+							message: `Could not inspect delivery remote '${remoteName}': ${remote.stderr.trim()}`,
+						})
+					} else if (config.delivery) {
+						const resolved = resolveDeliveryCommand(config.delivery, "query", {
+							repository: remoteRepository,
+							branch: data.branch,
+							base: data.base,
+							draft: existing ? String(existing.draft) : "",
+							url: existing?.url ?? "",
+							identifier: existing?.identifier ?? "",
+						})
+						const queried = yield* runExternal(resolved.argv, {
+							cwd: repositoryPath,
+							env: resolved.environment,
+						})
+						if (queried.exitCode === 0) {
+							const parsed = yield* Effect.try({
+								try: () => parseOptionalPullRequestRecord(queried.stdout),
+								catch: (cause) =>
+									new SyncError({
+										message:
+											cause instanceof Error ? cause.message : String(cause),
+									}),
+							}).pipe(Effect.either)
+							if (Either.isLeft(parsed)) {
+								warnings.push({
+									kind: "pr-provider-invalid-output",
+									target: record.key,
+									message: parsed.left.message,
+								})
+							} else if (
+								parsed.right &&
+								(parsed.right.provider !== config.delivery.provider ||
+									parsed.right.repository.toLowerCase() !==
+										remoteRepository.toLowerCase())
+							) {
+								if (parsed.right) {
+									prConflict = true
+									unresolved.push({
+										kind: "pr-provider-conflict",
+										target: record.key,
+										message:
+											"Delivery provider returned a record for the wrong provider or repository",
+										action: "Correct the delivery provider output",
+									})
+								}
+							} else {
+								current = parsed.right
+								pr = parsed.right ?? { url: null, state: "none" }
+							}
+						} else {
+							pr = existing
+								? { url: existing.url, state: "unavailable" }
+								: { url: null, state: "none" }
+							warnings.push({
+								kind: existing ? "pr-unavailable" : "pr-discovery-unavailable",
 								target: record.key,
 								message:
-									"Recorded PR repository does not match the writable repository origin",
-								action: "Correct the repository origin or recorded PR URL",
+									queried.stderr.trim() || "Could not query delivery provider",
 							})
 						}
+					} else if (existing) {
 						const viewed = yield* runExternal([
 							"gh",
 							"pr",
 							"view",
-							data.pr,
+							existing.url,
 							"--json",
 							"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
 						])
 						if (viewed.exitCode === 0) {
-							pr = parseJson(viewed.stdout, pr)
+							const detail = parseJson<Record<string, unknown>>(
+								viewed.stdout,
+								{},
+							)
+							current = recordFromGitHubJson(detail)
+							pr = { ...detail, ...current }
 							if (
-								pr.headRefName !== data.branch ||
-								pr.baseRefName !== data.base
+								detail.headRefName !== data.branch ||
+								detail.baseRefName !== data.base
 							) {
 								prConflict = true
 								unresolved.push({
@@ -605,11 +693,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								})
 							}
 						} else {
-							pr = { url: data.pr, state: "unavailable" }
+							pr = { url: existing.url, state: "unavailable" }
 							warnings.push({
 								kind: "pr-unavailable",
 								target: record.key,
-								message: `Could not inspect ${data.pr}: ${viewed.stderr.trim()}`,
+								message: `Could not inspect ${existing.url}: ${viewed.stderr.trim()}`,
 							})
 						}
 					} else {
@@ -625,7 +713,7 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 								"--json",
 								"number,state,title,isDraft,headRefName,baseRefName,url,mergedAt,mergeCommit",
 							],
-							{ cwd: join(root, "repos", data.repo) },
+							{ cwd: repositoryPath },
 						)
 						if (listed.exitCode === 0) {
 							const matches = parseJson<Record<string, unknown>[]>(
@@ -634,31 +722,11 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 							).filter(
 								(item) =>
 									item.headRefName === data.branch &&
-									item.baseRefName === data.base &&
-									typeof item.url === "string",
+									item.baseRefName === data.base,
 							)
 							if (matches.length === 1) {
-								pr = matches[0]!
-								const url = pr.url as string
-								if (apply) {
-									const recorded = yield* claims.reconcile(
-										{
-											taskId: record.taskId,
-											phaseId: record.phaseId,
-											revision,
-											pr: url,
-										},
-										root,
-									)
-									data = recorded.data
-									revision = recorded.revision
-								}
-								changes.push({
-									kind: "record-pr",
-									target: record.key,
-									message: `Record pull request ${url}`,
-									status: apply ? "applied" : "planned",
-								})
+								current = recordFromGitHubJson(matches[0]!)
+								pr = { ...matches[0], ...current }
 							} else if (matches.length > 1) {
 								unresolved.push({
 									kind: "multiple-prs",
@@ -677,8 +745,30 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						}
 					}
 
+					if (current && JSON.stringify(current) !== JSON.stringify(existing)) {
+						if (apply) {
+							const recorded = yield* claims.reconcile(
+								{
+									taskId: record.taskId,
+									phaseId: record.phaseId,
+									revision,
+									pr: current,
+								},
+								root,
+							)
+							data = recorded.data
+							revision = recorded.revision
+						}
+						changes.push({
+							kind: "record-pr",
+							target: record.key,
+							message: `Record pull request ${current.url}`,
+							status: apply ? "applied" : "planned",
+						})
+					}
+
 					if (
-						pr.state === "MERGED" &&
+						current?.merged === true &&
 						!prConflict &&
 						data.status !== "done" &&
 						data.status !== "dropped"

package/src/services/TaskPhaseService.test.ts

@@ -211,7 +211,15 @@ describe("task and phase services", () => {
 			repos: [{ repo: "effect", ref: "main" }],
 			branch: "task/single",
 			base: "main",
-			pr: "https://github.com/example/agency/pull/42",
+			pr: {
+				provider: "github",
+				repository: "example/agency",
+				identifier: "42",
+				url: "https://github.com/example/agency/pull/42",
+				state: "open",
+				draft: false,
+				merged: false,
+			},
 			status: "open",
 		})
 	})

package/src/services/WorkbaseService.ts

@@ -22,6 +22,7 @@ import {
 import { validateWorktreeCreateCommand } from "../workbase/worktree-command"
 import { validateRunners } from "../workbase/runner-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
+import { validateDelivery } from "../workbase/delivery-command"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -246,6 +247,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								}
 								try {
 									validateRunners(decoded.value.runners)
+									validateDelivery(decoded.value.delivery)
 								} catch (cause) {
 									return yield* new WorkbaseConfigError({
 										path: configPath,

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

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test"
+import {
+	parsePullRequestRecord,
+	resolveDeliveryCommand,
+	validateDelivery,
+} from "./delivery-command"
+
+const delivery = {
+	provider: "forge",
+	remote: "upstream",
+	createCommand: ["forge", "create", "{repository}", "{branch}"],
+	queryCommand: ["forge", "query", "{identifier}"],
+	environment: { FORGE_BASE: "{base}" },
+} as const
+
+const variables = {
+	repository: "example/agency",
+	branch: "feat/example",
+	base: "main",
+	draft: "false",
+	url: "",
+	identifier: "",
+}
+
+describe("delivery commands", () => {
+	test("expands argv and environment without shell evaluation", () => {
+		expect(resolveDeliveryCommand(delivery, "create", variables)).toEqual({
+			argv: ["forge", "create", "example/agency", "feat/example"],
+			environment: { FORGE_BASE: "main" },
+		})
+	})
+
+	test("rejects unknown placeholders", () => {
+		expect(() =>
+			validateDelivery({ ...delivery, queryCommand: ["forge", "{unknown}"] }),
+		).toThrow("Unknown delivery provider 'forge' placeholder")
+	})
+
+	test("requires complete and consistent normalized records", () => {
+		const record = {
+			provider: "forge",
+			repository: "example/agency",
+			identifier: "17",
+			url: "https://forge.example/example/agency/pulls/17",
+			state: "merged",
+			draft: false,
+			merged: true,
+		} as const
+		expect(parsePullRequestRecord(JSON.stringify(record))).toEqual(record)
+		expect(() =>
+			parsePullRequestRecord(JSON.stringify({ ...record, merged: false })),
+		).toThrow("inconsistent merge state")
+	})
+})

package/src/workbase/delivery-command.ts

@@ -0,0 +1,135 @@
+import { Schema } from "@effect/schema"
+import type { PullRequestRecord, WorkbaseConfig } from "./schemas"
+import { PullRequestRecord as PullRequestRecordSchema } from "./schemas"
+
+export interface DeliveryCommandVariables {
+	readonly repository: string
+	readonly branch: string
+	readonly base: string
+	readonly draft: string
+	readonly url: string
+	readonly identifier: string
+}
+
+const PLACEHOLDERS = new Set<keyof DeliveryCommandVariables>([
+	"repository",
+	"branch",
+	"base",
+	"draft",
+	"url",
+	"identifier",
+])
+
+const validateTemplate = (provider: string, value: string) => {
+	for (const match of value.matchAll(/\{([^{}]+)\}/g)) {
+		const placeholder = match[1]!
+		if (!PLACEHOLDERS.has(placeholder as keyof DeliveryCommandVariables)) {
+			throw new Error(
+				`Unknown delivery provider '${provider}' placeholder: {${placeholder}}`,
+			)
+		}
+	}
+}
+
+export const validateDelivery = (
+	delivery: WorkbaseConfig["delivery"],
+): void => {
+	if (!delivery) return
+	for (const value of [
+		...delivery.createCommand,
+		...delivery.queryCommand,
+		...Object.values(delivery.environment ?? {}),
+	]) {
+		validateTemplate(delivery.provider, value)
+	}
+}
+
+const expand = (value: string, variables: DeliveryCommandVariables) =>
+	value.replaceAll(
+		/\{([^{}]+)\}/g,
+		(match, placeholder: string) =>
+			variables[placeholder as keyof DeliveryCommandVariables] ?? match,
+	)
+
+export const resolveDeliveryCommand = (
+	delivery: NonNullable<WorkbaseConfig["delivery"]>,
+	kind: "create" | "query",
+	variables: DeliveryCommandVariables,
+) => {
+	validateDelivery(delivery)
+	const template =
+		kind === "create" ? delivery.createCommand : delivery.queryCommand
+	return {
+		argv: template.map((argument) => expand(argument, variables)),
+		environment: Object.fromEntries(
+			Object.entries(delivery.environment ?? {}).map(([key, value]) => [
+				key,
+				expand(value, variables),
+			]),
+		),
+	}
+}
+
+const decodeRecord = Schema.decodeUnknownEither(PullRequestRecordSchema, {
+	onExcessProperty: "error",
+})
+
+export const parsePullRequestRecord = (value: string): PullRequestRecord => {
+	let input: unknown
+	try {
+		input = JSON.parse(value)
+	} catch {
+		throw new Error("Delivery provider did not return valid JSON")
+	}
+	const decoded = decodeRecord(input)
+	if (decoded._tag === "Left") {
+		throw new Error(
+			"Delivery provider did not return a valid pull request record",
+		)
+	}
+	if (decoded.right.merged !== (decoded.right.state === "merged")) {
+		throw new Error("Delivery provider returned inconsistent merge state")
+	}
+	return decoded.right
+}
+
+export const parseOptionalPullRequestRecord = (
+	value: string,
+): PullRequestRecord | null => {
+	if (value.trim() === "null") return null
+	return parsePullRequestRecord(value)
+}
+
+const GITHUB_URL = /^https:\/\/github\.com\/([^/]+\/[^/]+)\/pull\/(\d+)\/?$/
+
+export const recordFromGitHubUrl = (url: string): PullRequestRecord => {
+	const match = url.match(GITHUB_URL)
+	if (!match) throw new Error(`Invalid GitHub pull request URL: ${url}`)
+	return {
+		provider: "github",
+		repository: match[1]!,
+		identifier: match[2]!,
+		url,
+		state: "open",
+		draft: false,
+		merged: false,
+	}
+}
+
+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()
+	return {
+		...record,
+		state:
+			state === "merged" ? "merged" : state === "closed" ? "closed" : "open",
+		draft: value.isDraft === true,
+		merged: state === "merged" || value.mergedAt != null,
+	} satisfies PullRequestRecord
+}
+
+export const normalizePullRequestRecord = (
+	record: PullRequestRecord | string,
+): PullRequestRecord =>
+	typeof record === "string" ? recordFromGitHubUrl(record) : record

package/src/workbase/schemas.test.ts

@@ -104,6 +104,41 @@ describe("runner configuration", () => {
 	})
 })
 
+describe("delivery configuration", () => {
+	test("accepts an argv-based create and query provider", () => {
+		const config = Schema.decodeUnknownSync(WorkbaseConfig)({
+			version: 2,
+			delivery: {
+				provider: "forge",
+				remote: "upstream",
+				createCommand: ["forge", "create", "{branch}"],
+				queryCommand: ["forge", "query", "{identifier}"],
+			},
+		})
+		expect(config.delivery?.remote).toBe("upstream")
+	})
+
+	test("accepts normalized non-GitHub pull request records", () => {
+		const phase = Schema.decodeUnknownSync(PhaseFrontmatter)({
+			repo: "agency",
+			branch: "feat/example",
+			base: "main",
+			pr: {
+				provider: "forge",
+				repository: "example/agency",
+				identifier: "17",
+				url: "https://forge.example/example/agency/pulls/17",
+				state: "open",
+				draft: false,
+				merged: false,
+			},
+		})
+		expect(phase.pr && typeof phase.pr !== "string" && phase.pr.provider).toBe(
+			"forge",
+		)
+	})
+})
+
 describe("work status", () => {
 	const supportedStatuses: Record<WorkStatus, true> = {
 		open: true,

package/src/workbase/schemas.ts

@@ -51,6 +51,26 @@ const GitHubPullRequestUrl = NonEmptyString.pipe(
 	Schema.pattern(/^https:\/\/github\.com\/[^/]+\/[^/]+\/pull\/\d+\/?$/),
 )
 
+export const PullRequestRecord = Schema.Struct({
+	provider: EntityId,
+	repository: NonEmptyString,
+	identifier: NonEmptyString,
+	url: Url,
+	state: Schema.Literal("open", "closed", "merged"),
+	draft: Schema.Boolean,
+	merged: Schema.Boolean,
+})
+
+const DeliveryProvider = Schema.Struct({
+	provider: EntityId,
+	remote: Schema.optional(NonEmptyString),
+	createCommand: Schema.NonEmptyArray(NonEmptyString),
+	queryCommand: Schema.NonEmptyArray(NonEmptyString),
+	environment: Schema.optional(
+		Schema.Record({ key: EnvironmentName, value: Schema.String }),
+	),
+})
+
 export const WorkbaseConfig = Schema.Struct({
 	version: Schema.Literal(2),
 	chooserCommand: Schema.optional(Schema.NonEmptyArray(NonEmptyString)),
@@ -67,6 +87,7 @@ export const WorkbaseConfig = Schema.Struct({
 			}),
 		}),
 	),
+	delivery: Schema.optional(DeliveryProvider),
 })
 
 export const LegacyWorkbaseRegistry = Schema.Struct({
@@ -96,7 +117,7 @@ const ExecutionUnit = {
 	repos: Schema.optional(Schema.Array(RepositoryReference)),
 	branch: NonEmptyString,
 	base: NonEmptyString,
-	pr: Schema.NullOr(GitHubPullRequestUrl),
+	pr: Schema.NullOr(Schema.Union(GitHubPullRequestUrl, PullRequestRecord)),
 	status: Schema.optionalWith(WorkStatus, { default: () => "open" as const }),
 	claim: Schema.optional(ClaimRecord),
 }
@@ -141,6 +162,7 @@ export type Dependency = Schema.Schema.Type<typeof Dependency>
 export type RepositoryReference = Schema.Schema.Type<typeof RepositoryReference>
 export type WorkStatus = Schema.Schema.Type<typeof WorkStatus>
 export type ClaimRecord = Schema.Schema.Type<typeof ClaimRecord>
+export type PullRequestRecord = Schema.Schema.Type<typeof PullRequestRecord>
 export type EpicFrontmatter = Schema.Schema.Type<typeof EpicFrontmatter>
 export type TaskFrontmatter = Schema.Schema.Type<typeof TaskFrontmatter>
 export type PhaseFrontmatter = Schema.Schema.Type<typeof PhaseFrontmatter>