@markjaquith/agency 3.2.11 → 3.2.13

package/package.json

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

package/src/commands/context.test.ts

@@ -1,12 +1,17 @@
 import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test"
 import { mkdir, readFile as nodeReadFile, rename, rm } from "node:fs/promises"
 import { dirname, join } from "node:path"
+import { Effect } from "effect"
 import {
 	captureLogs,
 	cleanupTempDir,
 	createTempDir,
 	runTestEffect,
+	trackDocumentReadConcurrency,
 } from "../test-utils"
+import { documentLoadConcurrency } from "../workbase/document-loading"
+import { ContextService } from "../services/ContextService"
+import { FileSystemService } from "../services/FileSystemService"
 import { context } from "./context"
 
 const write = async (root: string, path: string, content: string) => {
@@ -157,6 +162,33 @@ Phase prose.
 		])
 	})
 
+	test("bounds document reads across nested task and phase traversal", async () => {
+		await Promise.all(
+			Array.from({ length: documentLoadConcurrency + 8 }, (_, index) =>
+				write(
+					root,
+					`tasks/agent-contract/phases/extra-${index}/PHASE.md`,
+					`---\nrepo: agency\nbranch: extra-${index}\nbase: main\npr: null\nstatus: open\n---\n`,
+				),
+			),
+		)
+		const fs = await Effect.runPromise(
+			FileSystemService.pipe(Effect.provide(FileSystemService.Default)),
+		)
+		const tracked = trackDocumentReadConcurrency(fs)
+
+		await runTestEffect(
+			ContextService.pipe(
+				Effect.flatMap((service) =>
+					service.get({ cwd: root, target: "foundations" }),
+				),
+				Effect.provideService(FileSystemService, tracked.fs),
+			),
+		)
+
+		expect(tracked.maximum()).toBe(documentLoadConcurrency)
+	})
+
 	afterEach(async () => {
 		await cleanupTempDir(root)
 	})

package/src/services/GraphService.test.ts

@@ -4,7 +4,14 @@ import { Effect } from "effect"
 import { mkdir } from "node:fs/promises"
 import { dirname, join } from "node:path"
 import { AgencyGraph } from "../graph-schema"
-import { cleanupTempDir, createTempDir, runTestEffect } from "../test-utils"
+import {
+	cleanupTempDir,
+	createTempDir,
+	runTestEffect,
+	trackDocumentReadConcurrency,
+} from "../test-utils"
+import { documentLoadConcurrency } from "../workbase/document-loading"
+import { FileSystemService } from "./FileSystemService"
 import { GraphService } from "./GraphService"
 import {
 	VersionControlService,
@@ -209,6 +216,33 @@ describe("GraphService", () => {
 		expect(await getGraph(root)).toEqual(graph)
 	})
 
+	test("bounds document reads across nested task and phase traversal", async () => {
+		const root = await createWorkbase()
+		roots.push(root)
+		await Promise.all(
+			Array.from({ length: documentLoadConcurrency + 8 }, (_, index) =>
+				write(
+					root,
+					`tasks/ship/phases/extra-${index}/PHASE.md`,
+					`---\nrepo: agency\nbranch: extra-${index}\nbase: main\npr: null\nstatus: open\n---\n`,
+				),
+			),
+		)
+		const fs = await Effect.runPromise(
+			FileSystemService.pipe(Effect.provide(FileSystemService.Default)),
+		)
+		const tracked = trackDocumentReadConcurrency(fs)
+
+		await runTestEffect(
+			GraphService.pipe(
+				Effect.flatMap((service) => service.get({ cwd: root })),
+				Effect.provideService(FileSystemService, tracked.fs),
+			),
+		)
+
+		expect(tracked.maximum()).toBe(documentLoadConcurrency)
+	})
+
 	test("does not resolve a VCS backend when git details are not requested", async () => {
 		const root = await createWorkbase()
 		roots.push(root)

package/src/services/GraphService.ts

@@ -22,6 +22,7 @@ import {
 import { parseFrontmatter } from "../workbase/frontmatter"
 import { normalizePullRequestRecord } from "../workbase/delivery-command"
 import { documentRevision } from "../workbase/document-revision"
+import { documentLoadConcurrency } from "../workbase/document-loading"
 import {
 	EpicFrontmatter,
 	PhaseFrontmatter,
@@ -201,7 +202,7 @@ export class GraphService extends Effect.Service<GraphService>()(
 								)
 							}),
 						),
-						{ concurrency: "unbounded" },
+						{ concurrency: documentLoadConcurrency },
 					)
 					for (const document of epicDocuments) {
 						if (document) epics.set(document.id, document)
@@ -224,40 +225,37 @@ export class GraphService extends Effect.Service<GraphService>()(
 								const phaseIds = yield* directories(
 									join(root, "tasks", id, "phases"),
 								)
-								const taskPhases = yield* Effect.all(
-									phaseIds.map((phaseId) =>
-										Effect.gen(function* () {
-											const phasePath = join(
-												root,
-												"tasks",
-												id,
-												"phases",
-												phaseId,
-												"PHASE.md",
-											)
-											return yield* readDocument(
-												phaseId,
-												phasePath,
-												PhaseFrontmatter,
-											).pipe(
-												Effect.catchTag("FileNotFoundError", () =>
-													Effect.succeed(null),
-												),
-											)
-										}),
+								return { id, task, phaseIds }
+							}),
+						),
+						{ concurrency: documentLoadConcurrency },
+					)
+					const phaseDocuments = yield* Effect.all(
+						taskDocuments.flatMap(({ id, phaseIds }) =>
+							phaseIds.map((phaseId) => {
+								const phasePath = join(
+									root,
+									"tasks",
+									id,
+									"phases",
+									phaseId,
+									"PHASE.md",
+								)
+								return readDocument(phaseId, phasePath, PhaseFrontmatter).pipe(
+									Effect.catchTag("FileNotFoundError", () =>
+										Effect.succeed(null),
 									),
-									{ concurrency: "unbounded" },
+									Effect.map((document) => ({ taskId: id, document })),
 								)
-								return { id, task, phases: taskPhases }
 							}),
 						),
-						{ concurrency: "unbounded" },
+						{ concurrency: documentLoadConcurrency },
 					)
 					for (const documents of taskDocuments) {
 						if (documents.task) tasks.set(documents.id, documents.task)
-						for (const phase of documents.phases) {
-							if (phase) phases.set(`${documents.id}/${phase.id}`, phase)
-						}
+					}
+					for (const { taskId, document } of phaseDocuments) {
+						if (document) phases.set(`${taskId}/${document.id}`, document)
 					}
 
 					const repositoryRecords = new Map<string, RepositoryRecord>()

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/services/WorkbaseService.ts

@@ -26,6 +26,7 @@ import { validateAgents } from "../workbase/agent-command"
 import { findDependencyCycles } from "../workbase/dependency-graph"
 import { validateDelivery } from "../workbase/delivery-command"
 import { documentRevision } from "../workbase/document-revision"
+import { documentLoadConcurrency } from "../workbase/document-loading"
 
 class WorkbaseNotFoundError extends Data.TaggedError("WorkbaseNotFoundError")<{
 	readonly message: string
@@ -66,8 +67,6 @@ interface DocumentRecord<T> {
 	readonly data: T
 }
 
-const validationConcurrency = 32
-
 interface ValidationDocuments {
 	readonly epics: readonly DocumentRecord<EpicData>[]
 	readonly tasks: readonly DocumentRecord<TaskData>[]
@@ -751,7 +750,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								return document ? { id, path, ...document } : null
 							}),
 						),
-						{ concurrency: validationConcurrency },
+						{ concurrency: documentLoadConcurrency },
 					)
 					for (const document of epicDocuments) {
 						if (document) epics.set(document.id, document)
@@ -793,7 +792,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 												: null
 										}),
 									),
-									{ concurrency: validationConcurrency },
+									{ concurrency: documentLoadConcurrency },
 								)
 								return {
 									id,
@@ -802,7 +801,7 @@ export class WorkbaseService extends Effect.Service<WorkbaseService>()(
 								}
 							}),
 						),
-						{ concurrency: validationConcurrency },
+						{ concurrency: documentLoadConcurrency },
 					)
 					for (const documents of taskDocuments) {
 						if (documents.task) tasks.set(documents.id, documents.task)

package/src/test-utils.ts

@@ -31,6 +31,26 @@ export const createTempDir = () => mkdtemp(join(tmpdir(), "agency-test-"))
 export const cleanupTempDir = (path: string) =>
 	rm(path, { recursive: true, force: true })
 
+export const trackDocumentReadConcurrency = (fs: FileSystemService) => {
+	let active = 0
+	let maximum = 0
+	return {
+		fs: {
+			...fs,
+			readFile: (path: string) => {
+				if (!/(?:EPIC|TASK|PHASE)\.md$/.test(path)) return fs.readFile(path)
+				return Effect.gen(function* () {
+					active += 1
+					maximum = Math.max(maximum, active)
+					yield* Effect.sleep(5)
+					return yield* fs.readFile(path)
+				}).pipe(Effect.ensuring(Effect.sync(() => (active -= 1))))
+			},
+		} satisfies FileSystemService,
+		maximum: () => maximum,
+	}
+}
+
 const TestLayer = Layer.mergeAll(
 	FileSystemService.Default,
 	WorkbaseService.Default,

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 =>

package/src/workbase/document-loading.ts

@@ -0,0 +1 @@
+export const documentLoadConcurrency = 32