@markjaquith/agency 3.2.10 → 3.2.12

package/package.json

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

package/src/services/PullRequestService.ts

@@ -14,8 +14,8 @@ import {
 import type { PullRequestRecord } from "../workbase/schemas"
 import {
 	normalizePullRequestRecord,
+	parseGitHubPullRequestList,
 	parsePullRequestRecord,
-	recordFromGitHubJson,
 	recordFromGitHubUrl,
 	repositoryFromRemote,
 	resolveDeliveryCommand,
@@ -236,17 +236,7 @@ export class PullRequestService extends Effect.Service<PullRequestService>()(
 								})
 							}
 							const records = yield* Effect.try({
-								try: () => {
-									const parsed: unknown = JSON.parse(listed.stdout)
-									if (!Array.isArray(parsed)) {
-										throw new Error(
-											"GitHub CLI did not return a pull request list",
-										)
-									}
-									return parsed.map((value) =>
-										recordFromGitHubJson(value as Record<string, unknown>),
-									)
-								},
+								try: () => parseGitHubPullRequestList(listed.stdout),
 								catch: (cause) =>
 									new PullRequestError({
 										message:

package/src/services/SyncService.test.ts

@@ -613,6 +613,89 @@ process.stdout.write(${JSON.stringify(JSON.stringify(record))})
 		).toBe(false)
 	})
 
+	test("reports malformed successful GitHub responses", async () => {
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "malformed-detail",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/example",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			PullRequestService.pipe(
+				Effect.flatMap((service) =>
+					service.setUrl(
+						"malformed-detail",
+						undefined,
+						"https://github.com/example/agency/pull/42",
+						root,
+					),
+				),
+			),
+		)
+		await runTestEffect(
+			TaskService.pipe(
+				Effect.flatMap((service) =>
+					service.create(
+						{
+							id: "malformed-list",
+							ticketUrl: null,
+							repo: "agency",
+							branch: "feat/malformed-list",
+							base: "main",
+						},
+						root,
+					),
+				),
+			),
+		)
+		await Bun.write(join(root, "bin", "gh"), "#!/bin/sh\nprintf '{}\\n'\n")
+		await chmod(join(root, "bin", "gh"), 0o755)
+
+		const result = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, taskId: "malformed-detail" }),
+				),
+			),
+		)
+		expect(result.warnings).toContainEqual({
+			kind: "pr-provider-invalid-output",
+			target: "task:malformed-detail",
+			message: expect.stringContaining(
+				"GitHub CLI did not return a valid pull request",
+			),
+		})
+		expect(result.executions[0]?.pr).toMatchObject({
+			url: "https://github.com/example/agency/pull/42",
+			state: "open",
+		})
+
+		const listResult = await runTestEffect(
+			SyncService.pipe(
+				Effect.flatMap((service) =>
+					service.reconcile({ cwd: root, taskId: "malformed-list" }),
+				),
+			),
+		)
+		expect(listResult.warnings).toContainEqual({
+			kind: "pr-provider-invalid-output",
+			target: "task:malformed-list",
+			message: expect.stringContaining(
+				"GitHub CLI did not return a valid pull request list",
+			),
+		})
+	})
+
 	test("reconciles a uniquely discovered merged PR without materializing", async () => {
 		await runTestEffect(
 			TaskService.pipe(

package/src/services/SyncService.ts

@@ -14,8 +14,9 @@ import {
 } from "../workbase/frontmatter"
 import {
 	normalizePullRequestRecord,
+	parseGitHubPullRequest,
+	parseGitHubPullRequestList,
 	parseOptionalPullRequestRecord,
-	recordFromGitHubJson,
 	resolveDeliveryCommand,
 } from "../workbase/delivery-command"
 import { FileSystemService } from "./FileSystemService"
@@ -135,14 +136,6 @@ const parseWorktrees = (output: string): RegisteredWorktree[] => {
 	return worktrees
 }
 
-const parseJson = <T>(value: string, fallback: T): T => {
-	try {
-		return JSON.parse(value) as T
-	} catch {
-		return fallback
-	}
-}
-
 const isCommitId = (ref: string) => /^[0-9a-f]{40,64}$/i.test(ref)
 
 const originRef = (ref: string) =>
@@ -172,17 +165,18 @@ interface PullRequestQuery {
 const mergedPullRequestFromGitHub = (
 	data: ExecutionData,
 	query: PullRequestQuery | undefined,
+	details: readonly PullRequestRecord[] | undefined,
 ) => {
-	if (!query?.result || query.result.exitCode !== 0) return null
+	if (!query?.result || query.result.exitCode !== 0 || !details) return null
 	const existing = data.pr ? normalizePullRequestRecord(data.pr) : null
-	const details = existing
-		? [parseJson<Record<string, unknown>>(query.result.stdout, {})]
-		: parseJson<Record<string, unknown>[]>(query.result.stdout, []).filter(
+	const matches = existing
+		? details
+		: details.filter(
 				(item) =>
-					item.headRefName === data.branch && item.baseRefName === data.base,
+					item.headBranch === data.branch && item.baseBranch === data.base,
 			)
-	if (details.length !== 1) return null
-	const current = recordFromGitHubJson(details[0]!)
+	if (matches.length !== 1) return null
+	const current = matches[0]!
 	if (
 		current.merged !== true ||
 		current.headRepository?.toLowerCase() !==
@@ -493,6 +487,37 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 						{ concurrency: 8 },
 					),
 				)
+				const githubResponses = new Map<
+					string,
+					| {
+							readonly ok: true
+							readonly details: readonly PullRequestRecord[]
+					  }
+					| { readonly ok: false; readonly message: string }
+				>()
+				if (!config.delivery) {
+					for (const record of queryRecords) {
+						const query = prQueries.get(record.key)
+						if (query?.result?.exitCode !== 0) continue
+						try {
+							githubResponses.set(record.key, {
+								ok: true,
+								details: record.data.pr
+									? [parseGitHubPullRequest(query.result.stdout)]
+									: parseGitHubPullRequestList(query.result.stdout),
+							})
+						} catch (cause) {
+							const message =
+								cause instanceof Error ? cause.message : String(cause)
+							githubResponses.set(record.key, { ok: false, message })
+							warnings.push({
+								kind: "pr-provider-invalid-output",
+								target: record.key,
+								message,
+							})
+						}
+					}
+				}
 				const reviewSourceQueries = new Map(
 					yield* Effect.forEach(
 						reviewRecords,
@@ -534,11 +559,13 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 				}
 				const checkoutRecords = records.filter((record) => {
 					if (record.data.completion) return false
+					const githubResponse = githubResponses.get(record.key)
 					const merged = config.delivery
 						? null
 						: mergedPullRequestFromGitHub(
 								record.data,
 								prQueries.get(record.key),
+								githubResponse?.ok ? githubResponse.details : undefined,
 							)
 					return merged === null
 				})
@@ -590,9 +617,13 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					const codePath = join(dirname(record.path), "code")
 					const checkoutStates: CheckoutState[] = []
 					const query = prQueries.get(record.key)
+					const githubResponse = githubResponses.get(record.key)
+					const githubDetails = githubResponse?.ok
+						? githubResponse.details
+						: undefined
 					const remoteMergedPr = config.delivery
 						? null
-						: mergedPullRequestFromGitHub(data, query)
+						: mergedPullRequestFromGitHub(data, query, githubDetails)
 					const skipCheckoutReconciliation =
 						Boolean(data.completion) || remoteMergedPr !== null
 					let materialize = false
@@ -947,27 +978,25 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					} else if (existing) {
 						const viewed = query.result!
 						if (viewed.exitCode === 0) {
-							const detail = parseJson<Record<string, unknown>>(
-								viewed.stdout,
-								{},
-							)
-							current = recordFromGitHubJson(detail)
-							pr = { ...detail, ...current }
-							if (
-								current.headRepository?.toLowerCase() !==
-									remoteRepository.toLowerCase() ||
-								current.headBranch !== data.branch ||
-								current.baseRepository?.toLowerCase() !==
-									current.repository.toLowerCase() ||
-								current.baseBranch !== data.base
-							) {
-								prConflict = true
-								unresolved.push({
-									kind: "pr-repository-conflict",
-									target: record.key,
-									message: `Recorded PR head does not match '${remoteRepository}:${data.branch}' or base '${current.repository}:${data.base}'`,
-									action: "Correct the declaration or recorded PR URL",
-								})
+							if (githubDetails) {
+								current = githubDetails[0]!
+								pr = current
+								if (
+									current.headRepository?.toLowerCase() !==
+										remoteRepository.toLowerCase() ||
+									current.headBranch !== data.branch ||
+									current.baseRepository?.toLowerCase() !==
+										current.repository.toLowerCase() ||
+									current.baseBranch !== data.base
+								) {
+									prConflict = true
+									unresolved.push({
+										kind: "pr-repository-conflict",
+										target: record.key,
+										message: `Recorded PR head does not match '${remoteRepository}:${data.branch}' or base '${current.repository}:${data.base}'`,
+										action: "Correct the declaration or recorded PR URL",
+									})
+								}
 							}
 						} else {
 							pr = { url: existing.url, state: "unavailable" }
@@ -980,17 +1009,14 @@ export class SyncService extends Effect.Service<SyncService>()("SyncService", {
 					} else {
 						const listed = query.result!
 						if (listed.exitCode === 0) {
-							const matches = parseJson<Record<string, unknown>[]>(
-								listed.stdout,
-								[],
-							).filter(
+							const matches = (githubDetails ?? []).filter(
 								(item) =>
-									item.headRefName === data.branch &&
-									item.baseRefName === data.base,
+									item.headBranch === data.branch &&
+									item.baseBranch === data.base,
 							)
 							if (matches.length === 1) {
-								current = recordFromGitHubJson(matches[0]!)
-								pr = { ...matches[0], ...current }
+								current = matches[0]!
+								pr = current
 								if (
 									current.headRepository?.toLowerCase() !==
 										remoteRepository.toLowerCase() ||

package/src/utils/process.test.ts

@@ -1,7 +1,39 @@
 import { describe, expect, spyOn, test } from "bun:test"
-import { Effect } from "effect"
+import { mkdtemp, readFile, rm } from "node:fs/promises"
+import { tmpdir } from "node:os"
+import { join } from "node:path"
+import { Effect, Fiber } from "effect"
 import { spawnProcess } from "./process"
 
+const waitFor = async <A>(attempt: () => Promise<A>): Promise<A> => {
+	const deadline = Date.now() + 2_000
+	while (true) {
+		try {
+			return await attempt()
+		} catch (error) {
+			if (Date.now() >= deadline) throw error
+			await Bun.sleep(10)
+		}
+	}
+}
+
+const isProcessRunning = (pid: number): boolean => {
+	try {
+		process.kill(pid, 0)
+		return true
+	} catch (error) {
+		if (
+			typeof error === "object" &&
+			error !== null &&
+			"code" in error &&
+			error.code === "ESRCH"
+		) {
+			return false
+		}
+		throw error
+	}
+}
+
 describe("spawnProcess", () => {
 	test("forwards and captures output in tee mode", async () => {
 		const forwardedStdout: Uint8Array[] = []
@@ -74,4 +106,27 @@ describe("spawnProcess", () => {
 		).rejects.toThrow("Process timed out")
 		expect(performance.now() - startedAt).toBeLessThan(1_000)
 	})
+
+	test("terminates the subprocess when interrupted", async () => {
+		const directory = await mkdtemp(join(tmpdir(), "agency-process-"))
+		const pidPath = join(directory, "pid")
+		const script = [
+			`process.on("SIGTERM", () => {})`,
+			`await Bun.write(${JSON.stringify(pidPath)}, String(process.pid))`,
+			`setInterval(() => process.stdout.write("running\\n"), 10)`,
+		].join("\n")
+		const fiber = Effect.runFork(spawnProcess([process.execPath, "-e", script]))
+
+		try {
+			const pid = Number(await waitFor(() => readFile(pidPath, "utf8")))
+			expect(isProcessRunning(pid)).toBe(true)
+
+			await Effect.runPromise(Fiber.interrupt(fiber))
+
+			expect(isProcessRunning(pid)).toBe(false)
+		} finally {
+			await Effect.runPromise(Fiber.interrupt(fiber))
+			await rm(directory, { recursive: true, force: true })
+		}
+	})
 })

package/src/utils/process.ts

@@ -21,22 +21,38 @@ interface SpawnOptions {
 	readonly timeoutMs?: number
 }
 
-const readOutput = async (
+interface OutputReader {
+	readonly output: Promise<string>
+	readonly cancel: () => Promise<void>
+}
+
+const readOutput = (
 	stream: ReadableStream<Uint8Array> | null | undefined,
 	target?: { write(chunk: Uint8Array): unknown },
-) => {
-	if (!stream) return ""
+): OutputReader => {
+	if (!stream) {
+		return { output: Promise.resolve(""), cancel: () => Promise.resolve() }
+	}
 
 	const reader = stream.getReader()
-	const decoder = new TextDecoder()
-	let output = ""
-	while (true) {
-		const { done, value } = await reader.read()
-		if (done) break
-		target?.write(value)
-		output += decoder.decode(value, { stream: true })
+	return {
+		output: (async () => {
+			const decoder = new TextDecoder()
+			let output = ""
+			try {
+				while (true) {
+					const { done, value } = await reader.read()
+					if (done) break
+					target?.write(value)
+					output += decoder.decode(value, { stream: true })
+				}
+				return output + decoder.decode()
+			} finally {
+				reader.releaseLock()
+			}
+		})(),
+		cancel: () => reader.cancel(),
 	}
-	return output + decoder.decode()
 }
 
 /**
@@ -70,95 +86,139 @@ export const spawnProcess = (
 	args: readonly string[],
 	options?: SpawnOptions,
 ): Effect.Effect<ProcessResult, ProcessError> =>
-	Effect.tryPromise({
-		try: async () => {
-			const startedAt = performance.now()
-			const proc = Bun.spawn([...args], {
-				cwd: options?.cwd ?? process.cwd(),
-				stdin: options?.stdin ?? "pipe",
-				stdout: options?.stdout === "inherit" ? "inherit" : "pipe",
-				stderr: options?.stderr === "inherit" ? "inherit" : "pipe",
-				env: options?.env ? { ...process.env, ...options.env } : process.env,
-				detached: options?.timeoutMs !== undefined,
-			})
-			// Start draining stdout/stderr immediately so verbose subprocesses
-			// cannot block on filled pipe buffers before they exit.
-			const stdoutPromise =
-				options?.stdout === "inherit"
-					? Promise.resolve("")
-					: readOutput(
-							proc.stdout,
-							options?.stdout === "tee" ? process.stdout : undefined,
-						)
-			const stderrPromise =
-				options?.stderr === "inherit"
-					? Promise.resolve("")
-					: readOutput(
-							proc.stderr,
-							options?.stderr === "tee" ? process.stderr : undefined,
-						)
+	Effect.acquireUseRelease(
+		Effect.try({
+			try: () => {
+				const detached = options?.timeoutMs !== undefined
+				const proc = Bun.spawn([...args], {
+					cwd: options?.cwd ?? process.cwd(),
+					stdin: options?.stdin ?? "pipe",
+					stdout: options?.stdout === "inherit" ? "inherit" : "pipe",
+					stderr: options?.stderr === "inherit" ? "inherit" : "pipe",
+					env: options?.env ? { ...process.env, ...options.env } : process.env,
+					detached,
+				})
+				// Start draining stdout/stderr immediately so verbose subprocesses
+				// cannot block on filled pipe buffers before they exit.
+				const stdout =
+					options?.stdout === "inherit"
+						? readOutput(undefined)
+						: readOutput(
+								proc.stdout,
+								options?.stdout === "tee" ? process.stdout : undefined,
+							)
+				const stderr =
+					options?.stderr === "inherit"
+						? readOutput(undefined)
+						: readOutput(
+								proc.stderr,
+								options?.stderr === "tee" ? process.stderr : undefined,
+							)
 
-			let timedOut = false
-			let timer: ReturnType<typeof setTimeout> | undefined
-			const exited =
-				options?.timeoutMs === undefined
-					? proc.exited
-					: Promise.race([
-							proc.exited,
-							new Promise<number>((resolve) => {
-								timer = setTimeout(async () => {
-									timedOut = true
-									try {
-										process.kill(-proc.pid, "SIGTERM")
-									} catch {
-										proc.kill("SIGTERM")
-									}
-									const stopped = await Promise.race([
-										proc.exited.then(() => true),
-										Bun.sleep(250).then(() => false),
-									])
-									if (!stopped) {
-										try {
-											process.kill(-proc.pid, "SIGKILL")
-										} catch {
-											proc.kill("SIGKILL")
-										}
-									}
-									resolve(await proc.exited)
-								}, options.timeoutMs)
-							}),
+				let termination: Promise<void> | undefined
+				const terminate = (): Promise<void> => {
+					if (proc.exitCode !== null) return Promise.resolve()
+					return (termination ??= (async () => {
+						const signal = (name: "SIGTERM" | "SIGKILL") => {
+							if (!detached) {
+								proc.kill(name)
+								return
+							}
+							try {
+								process.kill(-proc.pid, name)
+							} catch {
+								proc.kill(name)
+							}
+						}
+						signal("SIGTERM")
+						const stopped = await Promise.race([
+							proc.exited.then(() => true),
+							Bun.sleep(250).then(() => false),
 						])
-			const [exitCode, stdout, stderr] = await Promise.all([
-				exited,
-				stdoutPromise,
-				stderrPromise,
-			])
-			if (timer) clearTimeout(timer)
-			if (timedOut) {
-				throw new ProcessError({
+						if (!stopped) signal("SIGKILL")
+						await proc.exited
+					})())
+				}
+
+				return {
+					proc,
+					stdout,
+					stderr,
+					terminate,
+					startedAt: performance.now(),
+					state: {
+						timedOut: false,
+						timer: undefined as ReturnType<typeof setTimeout> | undefined,
+					},
+				}
+			},
+			catch: (error) =>
+				new ProcessError({
 					command: args.join(" "),
-					exitCode:
-						typeof exitCode === "number" ? exitCode : (proc.exitCode ?? -1),
-					stderr: stderr.trim(),
-					timedOut: true,
-					timeoutMs: options?.timeoutMs,
-					elapsedMs: Math.round(performance.now() - startedAt),
-				})
-			}
+					exitCode: -1,
+					stderr: error instanceof Error ? error.message : String(error),
+				}),
+		}),
+		({ proc, stdout, stderr, terminate, startedAt, state }) =>
+			Effect.tryPromise({
+				try: async () => {
+					const exited =
+						options?.timeoutMs === undefined
+							? proc.exited
+							: Promise.race([
+									proc.exited,
+									new Promise<number>((resolve) => {
+										state.timer = setTimeout(async () => {
+											state.timedOut = true
+											await terminate()
+											resolve(await proc.exited)
+										}, options.timeoutMs)
+									}),
+								])
+					const [exitCode, stdoutOutput, stderrOutput] = await Promise.all([
+						exited,
+						stdout.output,
+						stderr.output,
+					])
+					if (state.timer) clearTimeout(state.timer)
+					if (state.timedOut) {
+						throw new ProcessError({
+							command: args.join(" "),
+							exitCode:
+								typeof exitCode === "number" ? exitCode : (proc.exitCode ?? -1),
+							stderr: stderrOutput.trim(),
+							timedOut: true,
+							timeoutMs: options?.timeoutMs,
+							elapsedMs: Math.round(performance.now() - startedAt),
+						})
+					}
 
-			return {
-				stdout: stdout.trim(),
-				stderr: stderr.trim(),
-				exitCode:
-					typeof exitCode === "number" ? exitCode : (proc.exitCode ?? 0),
-			}
-		},
-		catch: (error) =>
-			error instanceof ProcessError
-				? error
-				: new ProcessError({
-						command: args.join(" "),
-						exitCode: -1,
-						stderr: error instanceof Error ? error.message : String(error),
-					}),
-	})
+					return {
+						stdout: stdoutOutput.trim(),
+						stderr: stderrOutput.trim(),
+						exitCode:
+							typeof exitCode === "number" ? exitCode : (proc.exitCode ?? 0),
+					}
+				},
+				catch: (error) =>
+					error instanceof ProcessError
+						? error
+						: new ProcessError({
+								command: args.join(" "),
+								exitCode: -1,
+								stderr: error instanceof Error ? error.message : String(error),
+							}),
+			}),
+		({ proc, stdout, stderr, terminate, state }) =>
+			Effect.promise(async () => {
+				if (state.timer) clearTimeout(state.timer)
+				const terminating = terminate()
+				await Promise.allSettled([stdout.cancel(), stderr.cancel()])
+				await Promise.allSettled([
+					terminating,
+					proc.exited,
+					stdout.output,
+					stderr.output,
+				])
+			}),
+	)

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

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test"
 import {
+	parseGitHubPullRequest,
+	parseGitHubPullRequestList,
 	parsePullRequestRecord,
-	recordFromGitHubJson,
 	resolveDeliveryCommand,
 	resolveGitHubCreateCommand,
 	validateDelivery,
@@ -116,18 +117,24 @@ describe("delivery commands", () => {
 		const base = {
 			number: 17,
 			url: "https://github.com/example/agency/pull/17",
+			title: "Ship",
 			isDraft: false,
+			headRefName: "feat/example",
+			baseRefName: "main",
+			headRepository: { nameWithOwner: "fork/agency" },
+			mergedAt: null,
+			mergeCommit: null,
+			mergeable: "UNKNOWN",
 		}
 		expect(
-			recordFromGitHubJson({
-				...base,
-				state: "OPEN",
-				headRefName: "feat/example",
-				baseRefName: "main",
-				headRepository: { nameWithOwner: "fork/agency" },
-				baseRepository: { nameWithOwner: "example/agency" },
-				mergeable: "MERGEABLE",
-			}),
+			parseGitHubPullRequest(
+				JSON.stringify({
+					...base,
+					state: "OPEN",
+					baseRepository: { nameWithOwner: "example/agency" },
+					mergeable: "MERGEABLE",
+				}),
+			),
 		).toMatchObject({
 			state: "open",
 			merged: false,
@@ -138,19 +145,36 @@ describe("delivery commands", () => {
 			mergeable: true,
 		})
 		expect(
-			recordFromGitHubJson({
-				...base,
-				state: "OPEN",
-				mergeable: "CONFLICTING",
-			}),
+			parseGitHubPullRequest(
+				JSON.stringify({
+					...base,
+					state: "OPEN",
+					mergeable: "CONFLICTING",
+				}),
+			),
 		).toMatchObject({ state: "open", merged: false, mergeable: false })
 		expect(
-			recordFromGitHubJson({
-				...base,
-				state: "CLOSED",
-				mergedAt: "2026-07-21T00:00:00Z",
-				mergeable: "UNKNOWN",
-			}),
+			parseGitHubPullRequest(
+				JSON.stringify({
+					...base,
+					state: "CLOSED",
+					mergedAt: "2026-07-21T00:00:00Z",
+					mergeCommit: { oid: "abc" },
+					mergeable: "UNKNOWN",
+				}),
+			),
 		).toMatchObject({ state: "merged", merged: true, mergeable: null })
 	})
+
+	test("rejects malformed GitHub detail and list responses", () => {
+		expect(() => parseGitHubPullRequest("not-json")).toThrow(
+			"GitHub CLI did not return valid JSON for pull request",
+		)
+		expect(() => parseGitHubPullRequest("{}")).toThrow(
+			"GitHub CLI did not return a valid pull request",
+		)
+		expect(() => parseGitHubPullRequestList("{}")).toThrow(
+			"GitHub CLI did not return a valid pull request list",
+		)
+	})
 })

package/src/workbase/delivery-command.ts

@@ -1,4 +1,4 @@
-import { Schema } from "@effect/schema"
+import { Schema, TreeFormatter } from "@effect/schema"
 import type { PullRequestRecord, WorkbaseConfig } from "./schemas"
 import { PullRequestRecord as PullRequestRecordSchema } from "./schemas"
 
@@ -155,9 +155,47 @@ export const recordFromGitHubUrl = (url: string): PullRequestRecord => {
 	}
 }
 
-export const recordFromGitHubJson = (value: Record<string, unknown>) => {
-	const url = typeof value.url === "string" ? value.url : ""
-	const record = recordFromGitHubUrl(url)
+const GitHubRepository = Schema.Struct({
+	nameWithOwner: Schema.String.pipe(Schema.minLength(1)),
+})
+
+const GitHubPullRequest = Schema.Struct({
+	number: Schema.Number,
+	state: Schema.Literal("OPEN", "CLOSED", "MERGED"),
+	title: Schema.optional(Schema.String),
+	isDraft: Schema.Boolean,
+	headRefName: Schema.String,
+	baseRefName: Schema.String,
+	headRepository: Schema.NullOr(GitHubRepository),
+	baseRepository: Schema.optional(Schema.NullOr(GitHubRepository)),
+	url: Schema.String,
+	mergedAt: Schema.optional(Schema.NullOr(Schema.String)),
+	mergeCommit: Schema.optional(
+		Schema.NullOr(Schema.Struct({ oid: Schema.String })),
+	),
+	mergeable: Schema.Literal("MERGEABLE", "CONFLICTING", "UNKNOWN"),
+})
+
+const decodeGitHubPullRequest = Schema.decodeUnknownEither(GitHubPullRequest)
+const decodeGitHubPullRequests = Schema.decodeUnknownEither(
+	Schema.Array(GitHubPullRequest),
+)
+
+const invalidGitHubResponse = (
+	kind: "pull request" | "pull request list",
+	error: Parameters<typeof TreeFormatter.formatErrorSync>[0],
+) =>
+	new Error(
+		`GitHub CLI did not return a valid ${kind}: ${TreeFormatter.formatErrorSync(error)}`,
+	)
+
+const recordFromGitHubJson = (value: unknown): PullRequestRecord => {
+	const decoded = decodeGitHubPullRequest(value)
+	if (decoded._tag === "Left") {
+		throw invalidGitHubResponse("pull request", decoded.left)
+	}
+	const detail = decoded.right
+	const record = recordFromGitHubUrl(detail.url)
 	const repositoryName = (repository: unknown) => {
 		if (!repository || typeof repository !== "object") return undefined
 		const nameWithOwner = (repository as Record<string, unknown>).nameWithOwner
@@ -165,19 +203,17 @@ export const recordFromGitHubJson = (value: Record<string, unknown>) => {
 			? nameWithOwner
 			: undefined
 	}
-	const githubState = String(value.state ?? "OPEN").toLowerCase()
-	const merged = githubState === "merged" || value.mergedAt != null
-	const mergeable = String(value.mergeable ?? "UNKNOWN").toLowerCase()
+	const githubState = detail.state.toLowerCase()
+	const merged = githubState === "merged" || detail.mergedAt != null
+	const mergeable = detail.mergeable.toLowerCase()
 	return {
 		...record,
-		headRepository: repositoryName(value.headRepository),
-		headBranch:
-			typeof value.headRefName === "string" ? value.headRefName : undefined,
-		baseRepository: repositoryName(value.baseRepository) ?? record.repository,
-		baseBranch:
-			typeof value.baseRefName === "string" ? value.baseRefName : undefined,
+		headRepository: repositoryName(detail.headRepository),
+		headBranch: detail.headRefName,
+		baseRepository: repositoryName(detail.baseRepository) ?? record.repository,
+		baseBranch: detail.baseRefName,
 		state: merged ? "merged" : githubState === "closed" ? "closed" : "open",
-		draft: value.isDraft === true,
+		draft: detail.isDraft,
 		merged,
 		mergeable:
 			mergeable === "mergeable"
@@ -188,6 +224,32 @@ export const recordFromGitHubJson = (value: Record<string, unknown>) => {
 	} satisfies PullRequestRecord
 }
 
+const parseJson = (
+	value: string,
+	kind: "pull request" | "pull request list",
+) => {
+	try {
+		return JSON.parse(value) as unknown
+	} catch {
+		throw new Error(`GitHub CLI did not return valid JSON for ${kind}`)
+	}
+}
+
+export const parseGitHubPullRequest = (value: string): PullRequestRecord =>
+	recordFromGitHubJson(parseJson(value, "pull request"))
+
+export const parseGitHubPullRequestList = (
+	value: string,
+): readonly PullRequestRecord[] => {
+	const decoded = decodeGitHubPullRequests(
+		parseJson(value, "pull request list"),
+	)
+	if (decoded._tag === "Left") {
+		throw invalidGitHubResponse("pull request list", decoded.left)
+	}
+	return decoded.right.map(recordFromGitHubJson)
+}
+
 export const normalizePullRequestRecord = (
 	record: PullRequestRecord | string,
 ): PullRequestRecord =>