@iceinvein/agent-skills 0.1.39 → 0.2.0

package/skills/magpie/scripts/__tests__/skill-lint.test.ts

@@ -24,7 +24,7 @@ test('references/ ships in the install bundle', async () => {
   }
   const covers = (p: string) =>
     manifest.bundle.include.some((inc) => inc === p || p.startsWith(`${inc}/`))
-  for (const name of ['specialists.md', 'critic.md', 'peer-review.md']) {
+  for (const name of ['specialists.md', 'critic.md', 'peer-review.md', 'scout.md']) {
     expect(covers(`references/${name}`)).toBe(true)
   }
 })
@@ -81,6 +81,22 @@ test('references/peer-review.md holds the prompt and the Claude preamble', async
   }
 })
 
+test('references/scout.md holds the scout prompt and the brief contract', async () => {
+  const text = await readFile(ref('scout.md'), 'utf8')
+  expect(text).toContain('```magpie-scout')
+  expect(text).toContain('brief.json')
+  for (const key of ['purpose', 'changes', 'subsystems', 'watchItems', 'unclear']) {
+    expect(text).toContain(key)
+  }
+  for (const ph of ['<<RUN_DIR>>', '<<PR_NUMBER>>']) {
+    expect(text).toContain(ph)
+  }
+  // The scout must never trigger a full index; that is a consent-gated GPU pass.
+  expect(text).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+  // watchItems are context for specialists, not findings in their own right.
+  expect(text).toMatch(/not a finding/i)
+})
+
 test('SKILL.md sends each stage to the reference file it needs', async () => {
   const text = await readFile(SKILL, 'utf8')
   const section = (heading: string) => {
@@ -89,18 +105,73 @@ test('SKILL.md sends each stage to the reference file it needs', async () => {
     const next = text.indexOf('\n### ', start + heading.length)
     return text.slice(start, next === -1 ? undefined : next)
   }
-  expect(section('### 3. Specialists')).toContain('references/specialists.md')
-  expect(section('### 5. Critic')).toContain('references/critic.md')
-  expect(section('### 6. Peer review')).toContain('references/peer-review.md')
+  expect(section('### 3. Context')).toContain('references/scout.md')
+  expect(section('### 4. Specialists')).toContain('references/specialists.md')
+  expect(section('### 6. Critic')).toContain('references/critic.md')
+  expect(section('### 7. Peer review')).toContain('references/peer-review.md')
 })
 
 test('SKILL.md no longer inlines the prompt bodies it moved out', async () => {
   const text = await readFile(SKILL, 'utf8')
-  for (const tag of ['magpie-specialist-', 'magpie-critic', 'magpie-peer-review']) {
+  for (const tag of ['magpie-specialist-', 'magpie-critic', 'magpie-peer-review', 'magpie-scout']) {
     expect(text).not.toContain(`\`\`\`${tag}`)
   }
   // The walkthrough is the always-read part; keep it small enough to be cheap.
-  expect(text.split(/\s+/).length).toBeLessThan(2600)
+  // Raised from 2600 when the sharded-dispatch and fallback-diff prose was added:
+  // that's real, load-bearing procedure, not bloat.
+  expect(text.split(/\s+/).length).toBeLessThan(3000)
+})
+
+test('SKILL.md never instructs the agent to approve indexing', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  // A full index is a consent-gated GPU pass. The context stage degrades instead.
+  expect(text).toContain('approve_indexing')
+  expect(text).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+})
+
+test('SKILL.md logs codeIntelligence on both the done and skipped context outcomes', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 3. Context')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n### 4.', start))
+  // The bind probe's result is known by the time either log line is written,
+  // regardless of whether the scout produced a brief; specialists read this key
+  // to decide whether to include the codebase-intelligence block.
+  const doneEntry = section.match(/\{stage: context, status: done[^}]*\}/)
+  const skippedEntry = section.match(/\{stage: context, status: skipped[^}]*\}/)
+  expect(doneEntry?.[0]).toContain('codeIntelligence')
+  expect(skippedEntry?.[0]).toContain('codeIntelligence')
+})
+
+test('SKILL.md rebinds the code-intelligence session at cleanup', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 10. Cleanup')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n## ', start))
+  // Binding is per session with no per-call override, so a run that ends without
+  // rebinding leaves the session pointed at a worktree that no longer exists.
+  expect(section).toContain('bind_workspace')
+})
+
+test('SKILL.md rebinds before cleanup on the abort path too', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('## Aborting')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start)
+  // Stage 3 bound the session to the worktree; `abort` deletes that worktree via
+  // `magpie cleanup`, so it must rebind first or leave the session dangling.
+  expect(section).toMatch(/rebind.*(\$REPO|stage 10)/i)
+  expect(section).toContain('magpie cleanup')
+})
+
+test('SKILL.md rebinds before the stage-4 all-specialists-failed hard stop', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 4. Specialists')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n### 5.', start))
+  // This path stops the run without calling cleanup, but a later resume or
+  // abort must not find the session still pointed at the worktree.
+  expect(section).toMatch(/rebind.*(\$REPO|stage 10)/i)
 })
 
 test('styles.css declares a prefers-color-scheme:dark block that overrides core tokens', async () => {
@@ -195,7 +266,8 @@ test('SKILL.md does not gate resume on state/server-info', async () => {
   expect(section).not.toMatch(/if .*server-info.* exists/i)
   // Resuming must restart the server; the old one is gone.
   expect(section).toContain('magpie serve')
-  // `context` is a no-op stage: say so, or the agent stalls on it.
+  // `context` re-runs on resume too (bind probe plus a conditional scout
+  // dispatch); the resume section must still call it out explicitly.
   expect(section).toContain('context')
 })
 
@@ -222,3 +294,131 @@ test('SKILL.md has the stage walkthrough', async () => {
   expect(text).toMatch(/magpie render/)
   expect(text).toMatch(/magpie cleanup/)
 })
+
+test('references/specialists.md carries the codebase-intelligence block', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  expect(text).toContain('```magpie-codebase-intelligence')
+  const start = text.indexOf('```magpie-codebase-intelligence')
+  const block = text.slice(start, text.indexOf('```', start + 32))
+  expect(block).toContain('bind_workspace')
+  expect(block).toContain('indexing_in_progress')
+  // The one operation a specialist must never perform.
+  expect(block).toMatch(/never call `approve_indexing`|do not call `approve_indexing`/i)
+})
+
+test('every focus block names the code-intelligence tool for its focus', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  const tools: Record<(typeof FOCUSES)[number], string> = {
+    security: 'trace_data_flow',
+    bugs: 'get_call_hierarchy',
+    performance: 'find_affected_code',
+    'code-smells': 'search_code',
+    architecture: 'explore_dependency_graph',
+  }
+  for (const focus of FOCUSES) {
+    const fence = `\`\`\`magpie-specialist-${focus}`
+    const start = text.indexOf(fence)
+    const block = text.slice(start, text.indexOf('```', start + fence.length))
+    expect(block).toContain(tools[focus])
+  }
+})
+
+test('the output contract tells specialists to look before they hedge', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  const contract = text.slice(0, text.indexOf('```magpie-specialist-'))
+  expect(contract).toContain('Needs verification:')
+  expect(contract).toMatch(/look before .*hedg/i)
+})
+
+test('the output contract documents both findings filenames', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  const contract = text.slice(0, text.indexOf('```magpie-specialist-'))
+  // The pre-existing assertion must keep holding.
+  expect(contract).toMatch(/findings\/<focus>\.json/)
+  expect(contract).toMatch(/findings\/<focus>\.shard-<n>\.json/)
+})
+
+test('the run header documents the shard lines', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  expect(text).toContain('Shard: <n> of <N>')
+  expect(text).toContain('shards/shard-<n>.patch')
+})
+
+test('specialists are told excluded files are still reachable', async () => {
+  const text = await readFile(ref('specialists.md'), 'utf8')
+  expect(text).toContain('diff.full.patch')
+  expect(text).toContain('excluded-files.json')
+})
+
+test('stage 4 pins the shard field on the specialist log entry', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 4. Specialists')
+  expect(start).toBeGreaterThan(-1)
+  const section = text.slice(start, text.indexOf('\n### 5.', start))
+  // render-cmd sums per-focus findings counts keyed on this field. Drop it from a
+  // sharded run and every shard of a focus lands in one 'all' bucket,
+  // last-write-wins, so the progress page under-reports by up to the shard count
+  // with no error anywhere. This prose is the only thing that produces the field.
+  expect(section).toMatch(/\{stage: specialist,[^}]*\bshard: <n>/)
+  // ... and the unsharded path must still omit it, or 'all' would never be used.
+  expect(section).toMatch(/omit `shard`/i)
+})
+
+test('stage 4 reconciles the expected findings files before dedupe', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('### 4. Specialists')
+  const section = text.slice(start, text.indexOf('\n### 5.', start))
+  // Stage 4 fails only when every specialist fails, so losing 1 of 30 agents
+  // otherwise renders a report indistinguishable from a complete one.
+  expect(section).toMatch(/findings\/<focus>\.shard-<n>\.json/)
+  expect(section).toMatch(/5 × <shard count>/)
+})
+
+test('the stage-4 gate offers only options the pipeline can carry out', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  const start = text.indexOf('**More than four shards')
+  expect(start).toBeGreaterThan(-1)
+  const gate = text.slice(start, text.indexOf('\n\n', start))
+  // Option 2: --max-files is what binds on a PR of many small files, so naming
+  // only --budget sends the user back to an unchanged shard count.
+  expect(gate).toContain('--budget')
+  expect(gate).toContain('--max-files')
+  // Option 3 must name a mechanism that exists. There is no unreviewed marker in
+  // the report, so the record is a diagnostic log entry, on a stage outside
+  // status-cmd's ORDER ladder and never `status: error`.
+  const { ORDER } = await import('../status-cmd.ts')
+  const stage = gate.match(/\{stage: ([a-z-]+), status: ([a-z-]+)/)
+  expect(stage?.[1]).toBeDefined()
+  expect(ORDER as readonly string[]).not.toContain(stage?.[1])
+  expect(stage?.[2]).not.toBe('error')
+  expect(gate).toMatch(/skipped/)
+})
+
+test('the excluded-files note is part of the specialist prompt, not commentary', async () => {
+  const spec = await readFile(ref('specialists.md'), 'utf8')
+  // Every other specialist-directed line lives in a fenced block; this one used to
+  // sit unfenced between two numbered assembly parts, where an assembling agent
+  // reads it as a note to itself and the specialist never sees it.
+  const fences = [...spec.matchAll(/^```[a-z-]*\n([\s\S]*?)^```/gm)].map((m) => m[1] ?? '')
+  const inFence = fences.some((body) => body.includes('diff.full.patch'))
+  expect(inFence).toBe(true)
+  // And it must be a numbered part of the assembly list, not floating text.
+  expect(spec).toMatch(/^\d+\. The excluded-files block below/m)
+})
+
+test('the specialist assembly list is numbered contiguously from 1', async () => {
+  const spec = await readFile(ref('specialists.md'), 'utf8')
+  // Anchor on the heading, not on item 3's inline `## Output Contract` reference.
+  const preamble = spec.slice(0, spec.indexOf('\n## Output Contract'))
+  const numbers = [...preamble.matchAll(/^(\d+)\. /gm)].map((m) => Number(m[1]))
+  expect(numbers.length).toBeGreaterThan(4)
+  expect(numbers).toEqual(numbers.map((_, i) => i + 1))
+})
+
+test('SKILL.md documents the shard manifest and the fan-out gate', async () => {
+  const text = await readFile(SKILL, 'utf8')
+  expect(text).toContain('shards/manifest.json')
+  expect(text).toContain('diff.patch')
+  // The confirmation gate above four shards is the design's only interactive stop.
+  expect(text).toMatch(/more than four shards/i)
+})

package/skills/magpie/scripts/__tests__/types.test.ts

@@ -6,6 +6,7 @@ import {
   FOCUS_IDS,
   isSuggestion,
   looksLikeProse,
+  parseBrief,
   parseFinding,
 } from '../types.ts'
 
@@ -316,3 +317,49 @@ describe('isSuggestion', () => {
     ).toBe(false)
   })
 })
+
+test('parseBrief accepts a well-formed brief', () => {
+  const brief = parseBrief({
+    purpose: 'Adds retry handling to the upload path.',
+    changes: ['Wraps the S3 put in a bounded retry', 'Adds a jittered backoff helper'],
+    subsystems: [{ name: 'upload', role: 'owns the client-facing put path' }],
+    watchItems: ['The PR body claims idempotency but no request key is sent'],
+    unclear: ['Whether the retry budget interacts with the outer request timeout'],
+  })
+  expect(brief).not.toBeNull()
+  expect(brief?.purpose).toBe('Adds retry handling to the upload path.')
+  expect(brief?.changes).toHaveLength(2)
+  expect(brief?.subsystems[0]).toEqual({ name: 'upload', role: 'owns the client-facing put path' })
+  expect(brief?.watchItems).toHaveLength(1)
+  expect(brief?.unclear).toHaveLength(1)
+})
+
+test('parseBrief returns null for a brief with no purpose', () => {
+  expect(parseBrief({ changes: ['a'] })).toBeNull()
+  expect(parseBrief({ purpose: '   ', changes: ['a'] })).toBeNull()
+})
+
+test('parseBrief returns null for non-objects', () => {
+  expect(parseBrief(null)).toBeNull()
+  expect(parseBrief('a brief')).toBeNull()
+  expect(parseBrief(['a brief'])).toBeNull()
+})
+
+test('parseBrief drops junk entries instead of throwing', () => {
+  const brief = parseBrief({
+    purpose: 'Does a thing.',
+    changes: ['kept', 42, null, '   ', 'also kept'],
+    subsystems: [{ name: 'kept', role: 'r' }, { role: 'no name' }, 'not an object', null],
+    watchItems: 'not an array',
+    unclear: undefined,
+  })
+  expect(brief?.changes).toEqual(['kept', 'also kept'])
+  expect(brief?.subsystems).toEqual([{ name: 'kept', role: 'r' }])
+  expect(brief?.watchItems).toEqual([])
+  expect(brief?.unclear).toEqual([])
+})
+
+test('parseBrief defaults a subsystem with no role to an empty role', () => {
+  const brief = parseBrief({ purpose: 'p', subsystems: [{ name: 'auth' }] })
+  expect(brief?.subsystems).toEqual([{ name: 'auth', role: '' }])
+})

package/skills/magpie/scripts/dedupe-cmd.ts

@@ -3,6 +3,7 @@ import { join } from 'node:path'
 import { annotateChangedLines } from './changed-lines.ts'
 import { deduplicateFindings } from './dedupe.ts'
 import { verifyEvidence } from './evidence-filter.ts'
+import { namespaceId, parseFindingsFilename } from './findings-files.ts'
 import { DEFAULT_THRESHOLD, scoreRisk } from './score.ts'
 import { FOCUS_IDS, parseFinding, type ReviewFinding } from './types.ts'
 
@@ -16,6 +17,49 @@ export type RunDedupeOptions = {
   threshold?: number
 }
 
+/**
+ * The five focuses a specialist subagent writes. `tests` is a `FOCUS_IDS` entry
+ * too, but setup writes `findings/tests.json` once for the whole run with no
+ * subagent, so it is never expected per shard.
+ */
+const SPECIALIST_FOCUS_IDS = FOCUS_IDS.filter((id) => id !== 'tests')
+
+type Coverage = { expected: number; missing: string[] }
+
+/**
+ * Reconcile the findings files on disk against the `(focus, shard)` pairs the
+ * shard manifest implies. Stage 4 fails the run only when *every* specialist
+ * fails, so a sharded run that lost one agent out of thirty still logs
+ * `specialists: done` and renders a report indistinguishable from a complete
+ * one. Returns null when there is nothing to reconcile against (no manifest, an
+ * unreadable one, or a manifest with no shards, which is what an empty or
+ * fully-filtered diff produces), leaving pre-sharder runs behaving exactly as
+ * they did before.
+ */
+async function reconcileCoverage(runDir: string, present: Set<string>): Promise<Coverage | null> {
+  let shards: Array<Record<string, unknown>>
+  try {
+    const manifest = (await Bun.file(join(runDir, 'shards', 'manifest.json')).json()) as {
+      shards?: unknown
+    }
+    if (!Array.isArray(manifest.shards) || manifest.shards.length === 0) return null
+    shards = manifest.shards as Array<Record<string, unknown>>
+  } catch {
+    return null
+  }
+  // A single-shard manifest means stage 4 took the unsharded path, so its
+  // specialists write `<focus>.json` with no shard suffix.
+  const sharded = shards.length > 1
+  const expected: string[] = []
+  for (const [i, shard] of shards.entries()) {
+    const id = typeof shard?.id === 'number' ? shard.id : i + 1
+    for (const focus of SPECIALIST_FOCUS_IDS) {
+      expected.push(sharded ? `${focus}.shard-${id}.json` : `${focus}.json`)
+    }
+  }
+  return { expected: expected.length, missing: expected.filter((name) => !present.has(name)) }
+}
+
 export async function runDedupe(runDir: string, options: RunDedupeOptions = {}): Promise<number> {
   const threshold = options.threshold ?? DEFAULT_THRESHOLD
   const findingsDir = join(runDir, 'findings')
@@ -29,8 +73,8 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
 
   for (const name of files) {
     if (!name.endsWith('.json')) continue
-    const focus = name.slice(0, -'.json'.length)
-    if (!FOCUS_IDS.includes(focus as (typeof FOCUS_IDS)[number])) {
+    const parsed = parseFindingsFilename(name)
+    if (!parsed || !FOCUS_IDS.includes(parsed.focus as (typeof FOCUS_IDS)[number])) {
       await logLine(runDir, {
         stage: 'dedupe',
         status: 'skip',
@@ -39,6 +83,7 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
       })
       continue
     }
+    const { focus, shard } = parsed
     const path = join(findingsDir, name)
     let raw: unknown
     try {
@@ -63,7 +108,8 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
     }
     for (const item of raw) {
       try {
-        collected.push(parseFinding(item))
+        const finding = parseFinding(item)
+        collected.push({ ...finding, id: namespaceId(finding.id, focus, shard) })
       } catch (err) {
         await logLine(runDir, {
           stage: 'dedupe',
@@ -107,6 +153,14 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
       )}\n`,
     )
   }
+  const coverage = await reconcileCoverage(runDir, new Set(files))
+  if (coverage) {
+    process.stdout.write(
+      coverage.missing.length === 0
+        ? `dedupe: all ${coverage.expected} expected findings files present\n`
+        : `dedupe: ${coverage.missing.length} of ${coverage.expected} expected findings files missing (re-dispatch those specialists): ${coverage.missing.join(', ')}\n`,
+    )
+  }
   await logLine(runDir, {
     stage: 'dedupe',
     status: 'done',
@@ -118,6 +172,7 @@ export async function runDedupe(runDir: string, options: RunDedupeOptions = {}):
       skipped: evidence.skipped,
       dropped: evidence.dropped.length,
     },
+    ...(coverage ? { coverage } : {}),
   })
   return 0
 }

package/skills/magpie/scripts/diff-chunks.ts

@@ -0,0 +1,28 @@
+export type FileChunk = { path: string; text: string; lines: number }
+
+export const FILE_HEADER = /^diff --git a\/(.+?) b\/(.+?)$/m
+
+/** Split a unified diff on file boundaries. The first element may be a preamble
+ *  that is not a file chunk; callers decide what to do with it. */
+export function splitRawChunks(diff: string): string[] {
+  return diff.split(/^(?=diff --git )/m)
+}
+
+/** The b-side path of a file chunk, falling back to the a-side for deletions. */
+export function chunkPath(chunk: string): string | null {
+  const m = chunk.match(FILE_HEADER)
+  return m?.[2] ?? m?.[1] ?? null
+}
+
+/** File chunks only, with their paths and patch-line counts resolved. */
+export function splitFileChunks(diff: string): FileChunk[] {
+  if (!diff.trim()) return []
+  const out: FileChunk[] = []
+  for (const chunk of splitRawChunks(diff)) {
+    if (!chunk.startsWith('diff --git ')) continue
+    const path = chunkPath(chunk)
+    if (!path) continue
+    out.push({ path, text: chunk, lines: chunk.split('\n').length })
+  }
+  return out
+}

package/skills/magpie/scripts/findings-files.ts

@@ -0,0 +1,32 @@
+/**
+ * A specialist writes `findings/<focus>.json`, or `findings/<focus>.shard-<n>.json`
+ * when stage 4 fanned the focus out across shards. Returns null for anything
+ * else, which the caller logs and skips.
+ */
+export function parseFindingsFilename(
+  name: string,
+): { focus: string; shard: number | null } | null {
+  if (!name.endsWith('.json')) return null
+  const stem = name.slice(0, -'.json'.length)
+  const parts = stem.split('.')
+  const focus = parts[0]
+  if (!focus) return null
+  if (parts.length === 1) return { focus, shard: null }
+  if (parts.length > 2) return null
+  const m = /^shard-(\d+)$/.exec(parts[1] ?? '')
+  if (!m) return null
+  return { focus, shard: Number(m[1]) }
+}
+
+/**
+ * Every shard's security specialist mints `security-1` for its first finding,
+ * so a five-shard run yields five findings sharing one id, and the report and
+ * post stages key on id. Rewriting deterministically here beats asking five
+ * prompts to encode the shard themselves.
+ */
+export function namespaceId(id: string, focus: string, shard: number | null): string {
+  if (shard === null) return id
+  const tag = `s${shard}`
+  const prefix = `${focus}-`
+  return id.startsWith(prefix) ? `${prefix}${tag}-${id.slice(prefix.length)}` : `${tag}-${id}`
+}

package/skills/magpie/scripts/gh.ts

@@ -1,19 +1,24 @@
 import { writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
+import { localPrDiff } from './git-diff.ts'
 
 export type FetchPrInput = {
   ghBin: string
   prNumber: number
   runDir: string
-  /** Working directory for the gh invocation. Defaults to process.cwd(). */
+  /** Working directory for the gh and git invocations. Defaults to process.cwd(). */
   cwd?: string
+  /** git binary for the local-diff fallback. Defaults to `git` on PATH. */
+  gitBin?: string
+  /** Extra environment for the gh invocation. Test seam for the fake gh fixtures. */
+  env?: Record<string, string>
 }
 
 export type FetchPrResult =
-  | { ok: true; prJsonPath: string; diffPath: string }
+  | { ok: true; prJsonPath: string; diffPath: string; source: 'gh' | 'git'; mergeBase?: string }
   | { ok: false; error: string }
 
-const PR_VIEW_FIELDS = [
+export const PR_VIEW_FIELDS = [
   'number',
   'title',
   'headRefName',
@@ -26,11 +31,28 @@ const PR_VIEW_FIELDS = [
   // depending on cwd (the worktree is gone after cleanup).
   'url',
   'files',
+  // Intent evidence for the scout's brief, and issue links for the report header.
+  'commits',
+  'closingIssuesReferences',
 ].join(',')
 
+function prFileCount(viewStdout: string): number {
+  try {
+    const parsed = JSON.parse(viewStdout) as { files?: unknown }
+    return Array.isArray(parsed.files) ? parsed.files.length : 0
+  } catch {
+    return 0
+  }
+}
+
 export async function fetchPr(input: FetchPrInput): Promise<FetchPrResult> {
   const { ghBin, prNumber, runDir, cwd } = input
-  const spawnOpts = { stdout: 'pipe' as const, stderr: 'pipe' as const, ...(cwd ? { cwd } : {}) }
+  const spawnOpts = {
+    stdout: 'pipe' as const,
+    stderr: 'pipe' as const,
+    ...(cwd ? { cwd } : {}),
+    ...(input.env ? { env: { ...process.env, ...input.env } } : {}),
+  }
   const view = Bun.spawn(
     [ghBin, 'pr', 'view', String(prNumber), '--json', PR_VIEW_FIELDS],
     spawnOpts,
@@ -45,20 +67,52 @@ export async function fetchPr(input: FetchPrInput): Promise<FetchPrResult> {
     }
   }
 
+  const prJsonPath = join(runDir, 'pr.json')
+  const diffPath = join(runDir, 'diff.patch')
+  await writeFile(prJsonPath, viewStdout)
+
   const diff = Bun.spawn([ghBin, 'pr', 'diff', String(prNumber)], spawnOpts)
   const diffStdout = await new Response(diff.stdout).text()
   const diffStderr = await new Response(diff.stderr).text()
   const diffExit = await diff.exited
-  if (diffExit !== 0) {
-    return {
-      ok: false,
-      error: `gh pr diff exit ${diffExit}: ${diffStderr.trim()}`,
-    }
+
+  // GitHub refuses the `.diff` media type above roughly 300 files (HTTP 406),
+  // and a truncating proxy can answer 200 with nothing at all. Reviewing an
+  // empty diff as though it were the PR is the worse failure of the two, so
+  // both conditions fall through to the local clone.
+  const emptyForNonEmptyPr = diffStdout.trim() === '' && prFileCount(viewStdout) > 0
+  if (diffExit === 0 && !emptyForNonEmptyPr) {
+    await writeFile(diffPath, diffStdout)
+    return { ok: true, prJsonPath, diffPath, source: 'gh' }
   }
 
-  const prJsonPath = join(runDir, 'pr.json')
-  const diffPath = join(runDir, 'diff.patch')
-  await writeFile(prJsonPath, viewStdout)
-  await writeFile(diffPath, diffStdout)
-  return { ok: true, prJsonPath, diffPath }
+  const ghError =
+    diffExit !== 0
+      ? `gh pr diff exit ${diffExit}: ${diffStderr.trim()}`
+      : 'gh pr diff returned an empty diff for a PR with changed files'
+
+  let pr: { baseRefName?: unknown; headRefOid?: unknown }
+  try {
+    pr = JSON.parse(viewStdout) as { baseRefName?: unknown; headRefOid?: unknown }
+  } catch (err) {
+    return { ok: false, error: `${ghError}; pr.json is unparseable: ${String(err)}` }
+  }
+  const baseRefName = typeof pr.baseRefName === 'string' ? pr.baseRefName : ''
+  const headRefOid = typeof pr.headRefOid === 'string' ? pr.headRefOid : ''
+  if (!baseRefName || !headRefOid) {
+    return { ok: false, error: `${ghError}; pr.json has no baseRefName/headRefOid to diff from` }
+  }
+
+  const local = await localPrDiff({
+    gitBin: input.gitBin ?? 'git',
+    repoPath: cwd ?? process.cwd(),
+    prNumber,
+    baseRefName,
+    headRefOid,
+  })
+  if (!local.ok) {
+    return { ok: false, error: `${ghError}; local fallback failed: ${local.error}` }
+  }
+  await writeFile(diffPath, local.diff)
+  return { ok: true, prJsonPath, diffPath, source: 'git', mergeBase: local.mergeBase }
 }