@cat-factory/executor-harness 1.50.8 → 1.50.12

package/dist/agent.js

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js';
-import { cloneRepo, commitAll, conflictDiff, fetchReferenceBranches, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, hasAgentChanges, headCommit, inferVcsProvider, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
 import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
@@ -405,6 +405,28 @@ async function runExploreMode(job, opts) {
                 fetched: fetched.length,
             });
         }
+        // The pr-reviewer reviews an EXISTING PR: fetch its HEAD into `origin/pr-head` so the
+        // read-only agent can inspect the PROPOSED code — files the PR adds (absent from this base
+        // checkout) and the head version of every modified file. The agent holds no git credential
+        // of its own, so this harness-side fetch (token out of band) is the only way the head is
+        // reachable; the prompt then diffs `origin/<base>...origin/pr-head`. Best-effort: on failure
+        // the review proceeds on the base checkout + the injected `.cat-context/pr-diff.md`.
+        if (job.reviewPrNumber !== undefined) {
+            const provider = job.repo.provider ?? inferVcsProvider(job.repo.cloneUrl);
+            const fetched = await fetchPullRequestHead({
+                dir,
+                number: job.reviewPrNumber,
+                provider,
+                ghToken: job.ghToken,
+                signal: opts.signal,
+                onSkip: (reason) => logger.warn('agent(explore): PR head fetch skipped', {
+                    number: job.reviewPrNumber,
+                    provider,
+                    reason,
+                }),
+            });
+            logger.info('agent(explore): PR head fetch', { number: job.reviewPrNumber, fetched });
+        }
         // Optional infra stand-up (the tester): bring the service's docker-compose
         // dependencies up at the repo root for the duration of the run, tearing them down in
         // the `finally`. A stand-up failure is non-fatal — it's surfaced to the agent as a

package/dist/git.js

@@ -691,6 +691,46 @@ export async function fetchReferenceBranches(opts) {
         await excludeFromGit(dir, `${REFERENCE_WORKTREE_DIR}/`, signal);
     return fetched;
 }
+/** The local tracking ref a fetched PR/MR head lands on, so the reviewer reads `origin/pr-head`. */
+export const PR_HEAD_REF = 'refs/remotes/origin/pr-head';
+/**
+ * The `git fetch` refspec that maps a PR/MR's server-side HEAD ref onto {@link PR_HEAD_REF}. A
+ * PR head is a synthetic ref the host maintains, NOT part of a normal clone: GitHub exposes it at
+ * `refs/pull/<n>/head`, GitLab at `refs/merge-requests/<n>/head`. Pure so the provider branch is
+ * unit-tested without a network. The leading `+` forces the update (the ref is read-only here).
+ */
+export function pullHeadRefspec(number, provider) {
+    const src = provider === 'gitlab' ? `refs/merge-requests/${number}/head` : `refs/pull/${number}/head`;
+    return `+${src}:${PR_HEAD_REF}`;
+}
+/**
+ * Fetch the reviewed PR/MR's HEAD into {@link PR_HEAD_REF} so a read-only reviewer can inspect the
+ * PROPOSED code — files the PR adds (absent from the base checkout) and the head version of every
+ * modified file — with `git diff origin/<base>...origin/pr-head`, `git show origin/pr-head:<path>`.
+ * The base clone never includes the pull ref, and the container agent holds no git credential of
+ * its own (the token lives with the harness), so the agent's own `git fetch pull/<n>/head` fails
+ * on a private repo — this harness-side fetch (which carries the token out of band via GIT_ASKPASS,
+ * exactly like {@link fetchReferenceBranches}) is what actually makes the head reachable.
+ *
+ * Best-effort: a fetch failure (a closed/deleted PR, a host without the pull ref, a transient
+ * network error) is reported via `onSkip` and swallowed — the review then proceeds on the base
+ * checkout + the injected diff, never fails. Returns whether the head was fetched.
+ */
+export async function fetchPullRequestHead(opts) {
+    const { dir, number, provider, ghToken, signal, onSkip } = opts;
+    try {
+        await git(['fetch', '--no-tags', 'origin', pullHeadRefspec(number, provider)], {
+            cwd: dir,
+            signal,
+            env: await authEnv(ghToken),
+        });
+        return true;
+    }
+    catch (err) {
+        onSkip?.(err instanceof Error ? err.message : String(err));
+        return false;
+    }
+}
 /**
  * Push the work branch to origin. The remote URL carries only the username, so
  * the token is supplied here via the askpass env (never in argv).

package/dist/job.js

@@ -647,44 +647,82 @@ export function parseAgentJob(input) {
     // preview dispatch to send dummy values it has no reason to supply. Every other mode still
     // requires them (throws when missing/empty), exactly as before.
     const agentField = (value, path) => mode === 'preview' ? (typeof value === 'string' ? value : '') : str(value, path);
+    // Parse each field, then hand the pieces to `assembleAgentJob` for the (large) object literal —
+    // the parse/assemble split keeps both within the cyclomatic-complexity budget. Behaviour is
+    // byte-identical (the literal + host validation moved verbatim).
+    const job = assembleAgentJob(o, mode, agentField, {
+        output: parseAgentOutputSpec(o.output),
+        pr: parseAgentPrSpec(o.pr),
+        infra: parseAgentInfraSpec(o.infra),
+        peerRepos: parsePeerRepos(o.peerRepos),
+        referenceRepos: parseReferenceRepos(o.referenceRepos),
+        referenceBranches: parseReferenceBranches(o.referenceBranches),
+        bootstrap: parseAgentBootstrapSpec(o.bootstrap),
+        contextFiles: parseContextFiles(o.contextFiles),
+        packageRegistries: parsePackageRegistries(o.packageRegistries),
+        skill: parseSkillSpec(o.skill),
+        testSecrets: parseTestSecrets(o.testSecrets),
+        guardLimits: parseGuardLimits(o.guardLimits),
+        validation: parseValidationSpec(o.validation),
+        reviewPrNumber: posInt(o.reviewPrNumber),
+    });
+    assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
+    if (job.githubApiBase)
+        assertAllowedHost(job.githubApiBase, 'githubApiBase');
+    // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
+    // allowed GitHub host too (the installation token is sent to it on the force-push).
+    if (job.bootstrap)
+        assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl');
+    // Each peer repo's clone URL receives the installation token on clone/push, so it must be
+    // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
+    // exfiltrate the token exactly like a rogue primary clone URL.
+    for (const [i, peer] of (job.peerRepos ?? []).entries()) {
+        assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`);
+    }
+    // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+    // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+    // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+    for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+        assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`);
+    }
+    return job;
+}
+/** Parse the optional structured-output spec (`{ kind, shapeHint?, repair?, failOnUnusableFinal? }`). */
+function parseAgentOutputSpec(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const so = raw;
+    const kind = so.kind === 'structured' ? 'structured' : 'prose';
+    const spec = { kind };
+    if (typeof so.shapeHint === 'string')
+        spec.shapeHint = so.shapeHint;
+    // Carry an explicit `repair: false` through — the handler defaults to repair-on
+    // when absent, so dropping `false` would silently re-enable the repair call for a
+    // kind that opted out (it keys off `output.repair === false`).
+    if (typeof so.repair === 'boolean')
+        spec.repair = so.repair;
+    // Carry the opt-in truncation gate through (document producers set it); dropping
+    // it would silently re-enable laundering a cut-off reply into a half-baked doc.
+    if (so.failOnUnusableFinal === true)
+        spec.failOnUnusableFinal = true;
+    return spec;
+}
+/** Parse the optional PR spec (`{ title, body }`). */
+function parseAgentPrSpec(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const p = raw;
+    return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' };
+}
+/**
+ * Assemble the {@link AgentJob} object from the request `o` + the pre-parsed {@link
+ * ParsedAgentJobParts}. Extracted from {@link parseAgentJob} so the large conditional-spread
+ * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
+ */
+function assembleAgentJob(o, mode, agentField, parts) {
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skill, testSecrets, guardLimits, validation, reviewPrNumber, } = parts;
     const repo = (o.repo ?? {});
-    const output = typeof o.output === 'object' && o.output !== null
-        ? (() => {
-            const so = o.output;
-            const kind = so.kind === 'structured' ? 'structured' : 'prose';
-            const spec = { kind };
-            if (typeof so.shapeHint === 'string')
-                spec.shapeHint = so.shapeHint;
-            // Carry an explicit `repair: false` through — the handler defaults to repair-on
-            // when absent, so dropping `false` would silently re-enable the repair call for a
-            // kind that opted out (it keys off `output.repair === false`).
-            if (typeof so.repair === 'boolean')
-                spec.repair = so.repair;
-            // Carry the opt-in truncation gate through (document producers set it); dropping
-            // it would silently re-enable laundering a cut-off reply into a half-baked doc.
-            if (so.failOnUnusableFinal === true)
-                spec.failOnUnusableFinal = true;
-            return spec;
-        })()
-        : undefined;
-    const pr = typeof o.pr === 'object' && o.pr !== null
-        ? (() => {
-            const p = o.pr;
-            return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' };
-        })()
-        : undefined;
-    const infra = parseAgentInfraSpec(o.infra);
-    const peerRepos = parsePeerRepos(o.peerRepos);
-    const referenceRepos = parseReferenceRepos(o.referenceRepos);
-    const referenceBranches = parseReferenceBranches(o.referenceBranches);
-    const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
-    const contextFiles = parseContextFiles(o.contextFiles);
-    const packageRegistries = parsePackageRegistries(o.packageRegistries);
-    const skill = parseSkillSpec(o.skill);
-    const testSecrets = parseTestSecrets(o.testSecrets);
-    const guardLimits = parseGuardLimits(o.guardLimits);
-    const validation = parseValidationSpec(o.validation);
-    const job = {
+    return {
         jobId: str(o.jobId, 'jobId'),
         mode,
         systemPrompt: agentField(o.systemPrompt, 'systemPrompt'),
@@ -715,30 +753,11 @@ export function parseAgentJob(input) {
         ...(peerRepos.length ? { peerRepos } : {}),
         ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(referenceBranches.length ? { referenceBranches } : {}),
+        ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
         ...(guardLimits ? { guardLimits } : {}),
         ...(validation ? { validation } : {}),
     };
-    assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl');
-    if (job.githubApiBase)
-        assertAllowedHost(job.githubApiBase, 'githubApiBase');
-    // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
-    // allowed GitHub host too (the installation token is sent to it on the force-push).
-    if (job.bootstrap)
-        assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl');
-    // Each peer repo's clone URL receives the installation token on clone/push, so it must be
-    // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
-    // exfiltrate the token exactly like a rogue primary clone URL.
-    for (const [i, peer] of (job.peerRepos ?? []).entries()) {
-        assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`);
-    }
-    // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
-    // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
-    // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
-    for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
-        assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`);
-    }
-    return job;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.8",
+  "version": "1.50.12",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -26,8 +26,8 @@
     "hono": "^4.12.30",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/server": "0.140.2",
-    "@cat-factory/spend": "0.12.68"
+    "@cat-factory/server": "0.141.2",
+    "@cat-factory/spend": "0.12.73"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -18,9 +18,11 @@ import {
   cloneRepo,
   commitAll,
   conflictDiff,
+  fetchPullRequestHead,
   fetchReferenceBranches,
   hasAgentChanges,
   headCommit,
+  inferVcsProvider,
   mergeBranch,
   openPullRequest,
   prepareExistingCheckout,
@@ -493,6 +495,30 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
         })
       }
 
+      // The pr-reviewer reviews an EXISTING PR: fetch its HEAD into `origin/pr-head` so the
+      // read-only agent can inspect the PROPOSED code — files the PR adds (absent from this base
+      // checkout) and the head version of every modified file. The agent holds no git credential
+      // of its own, so this harness-side fetch (token out of band) is the only way the head is
+      // reachable; the prompt then diffs `origin/<base>...origin/pr-head`. Best-effort: on failure
+      // the review proceeds on the base checkout + the injected `.cat-context/pr-diff.md`.
+      if (job.reviewPrNumber !== undefined) {
+        const provider = job.repo.provider ?? inferVcsProvider(job.repo.cloneUrl)
+        const fetched = await fetchPullRequestHead({
+          dir,
+          number: job.reviewPrNumber,
+          provider,
+          ghToken: job.ghToken,
+          signal: opts.signal,
+          onSkip: (reason) =>
+            logger.warn('agent(explore): PR head fetch skipped', {
+              number: job.reviewPrNumber,
+              provider,
+              reason,
+            }),
+        })
+        logger.info('agent(explore): PR head fetch', { number: job.reviewPrNumber, fetched })
+      }
+
       // Optional infra stand-up (the tester): bring the service's docker-compose
       // dependencies up at the repo root for the duration of the run, tearing them down in
       // the `finally`. A stand-up failure is non-fatal — it's surfaced to the agent as a

package/src/git.ts

@@ -862,6 +862,57 @@ export async function fetchReferenceBranches(opts: {
   return fetched
 }
 
+/** The local tracking ref a fetched PR/MR head lands on, so the reviewer reads `origin/pr-head`. */
+export const PR_HEAD_REF = 'refs/remotes/origin/pr-head'
+
+/**
+ * The `git fetch` refspec that maps a PR/MR's server-side HEAD ref onto {@link PR_HEAD_REF}. A
+ * PR head is a synthetic ref the host maintains, NOT part of a normal clone: GitHub exposes it at
+ * `refs/pull/<n>/head`, GitLab at `refs/merge-requests/<n>/head`. Pure so the provider branch is
+ * unit-tested without a network. The leading `+` forces the update (the ref is read-only here).
+ */
+export function pullHeadRefspec(number: number, provider: 'github' | 'gitlab'): string {
+  const src =
+    provider === 'gitlab' ? `refs/merge-requests/${number}/head` : `refs/pull/${number}/head`
+  return `+${src}:${PR_HEAD_REF}`
+}
+
+/**
+ * Fetch the reviewed PR/MR's HEAD into {@link PR_HEAD_REF} so a read-only reviewer can inspect the
+ * PROPOSED code — files the PR adds (absent from the base checkout) and the head version of every
+ * modified file — with `git diff origin/<base>...origin/pr-head`, `git show origin/pr-head:<path>`.
+ * The base clone never includes the pull ref, and the container agent holds no git credential of
+ * its own (the token lives with the harness), so the agent's own `git fetch pull/<n>/head` fails
+ * on a private repo — this harness-side fetch (which carries the token out of band via GIT_ASKPASS,
+ * exactly like {@link fetchReferenceBranches}) is what actually makes the head reachable.
+ *
+ * Best-effort: a fetch failure (a closed/deleted PR, a host without the pull ref, a transient
+ * network error) is reported via `onSkip` and swallowed — the review then proceeds on the base
+ * checkout + the injected diff, never fails. Returns whether the head was fetched.
+ */
+export async function fetchPullRequestHead(opts: {
+  dir: string
+  number: number
+  provider: 'github' | 'gitlab'
+  ghToken: string
+  signal?: AbortSignal
+  /** Called when the fetch failed, so the caller (which owns a logger) can warn. */
+  onSkip?: (reason: string) => void
+}): Promise<boolean> {
+  const { dir, number, provider, ghToken, signal, onSkip } = opts
+  try {
+    await git(['fetch', '--no-tags', 'origin', pullHeadRefspec(number, provider)], {
+      cwd: dir,
+      signal,
+      env: await authEnv(ghToken),
+    })
+    return true
+  } catch (err) {
+    onSkip?.(err instanceof Error ? err.message : String(err))
+    return false
+  }
+}
+
 /**
  * Push the work branch to origin. The remote URL carries only the username, so
  * the token is supplied here via the askpass env (never in argv).

package/src/job.ts

@@ -784,6 +784,15 @@ export interface AgentJob extends HarnessAuthFields {
    * the same primary repo. Absent ⇒ none. Consumed by the coding + explore flows.
    */
   referenceBranches?: string[]
+  /**
+   * Explore mode (the `pr-reviewer`): the reviewed PR/MR number. Present ⇒ after the base
+   * checkout the harness fetches that PR's HEAD into `origin/pr-head` (best-effort) so the
+   * read-only reviewer can diff/read the PROPOSED code — files the PR adds are otherwise absent
+   * from the base checkout, and the agent has no git credential to fetch the head itself. The
+   * GitHub-vs-GitLab pull ref is chosen from `repo.provider` (host-inferred when absent). Absent
+   * ⇒ no head fetch (every non-review run). See {@link file://./git.ts} `fetchPullRequestHead`.
+   */
+  reviewPrNumber?: number
   /**
    * Coding mode: whether a no-op run (nothing changed) is a failure. The implementer
    * fails on a no-op; the in-place fixers (ci-fix / fix-tests) treat it as a non-fatal
@@ -1241,43 +1250,116 @@ export function parseAgentJob(input: unknown): AgentJob {
   // requires them (throws when missing/empty), exactly as before.
   const agentField = (value: unknown, path: string): string =>
     mode === 'preview' ? (typeof value === 'string' ? value : '') : str(value, path)
+  // Parse each field, then hand the pieces to `assembleAgentJob` for the (large) object literal —
+  // the parse/assemble split keeps both within the cyclomatic-complexity budget. Behaviour is
+  // byte-identical (the literal + host validation moved verbatim).
+  const job = assembleAgentJob(o, mode, agentField, {
+    output: parseAgentOutputSpec(o.output),
+    pr: parseAgentPrSpec(o.pr),
+    infra: parseAgentInfraSpec(o.infra),
+    peerRepos: parsePeerRepos(o.peerRepos),
+    referenceRepos: parseReferenceRepos(o.referenceRepos),
+    referenceBranches: parseReferenceBranches(o.referenceBranches),
+    bootstrap: parseAgentBootstrapSpec(o.bootstrap),
+    contextFiles: parseContextFiles(o.contextFiles),
+    packageRegistries: parsePackageRegistries(o.packageRegistries),
+    skill: parseSkillSpec(o.skill),
+    testSecrets: parseTestSecrets(o.testSecrets),
+    guardLimits: parseGuardLimits(o.guardLimits),
+    validation: parseValidationSpec(o.validation),
+    reviewPrNumber: posInt(o.reviewPrNumber),
+  })
+  assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
+  if (job.githubApiBase) assertAllowedHost(job.githubApiBase, 'githubApiBase')
+  // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
+  // allowed GitHub host too (the installation token is sent to it on the force-push).
+  if (job.bootstrap) assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl')
+  // Each peer repo's clone URL receives the installation token on clone/push, so it must be
+  // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
+  // exfiltrate the token exactly like a rogue primary clone URL.
+  for (const [i, peer] of (job.peerRepos ?? []).entries()) {
+    assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
+  }
+  // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
+  // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
+  // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
+  for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
+    assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`)
+  }
+  return job
+}
+
+/** The pre-parsed field bundle {@link parseAgentJob} hands to {@link assembleAgentJob}. */
+interface ParsedAgentJobParts {
+  output: AgentOutputSpec | undefined
+  pr: { title: string; body: string } | undefined
+  infra: ReturnType<typeof parseAgentInfraSpec>
+  peerRepos: ReturnType<typeof parsePeerRepos>
+  referenceRepos: ReturnType<typeof parseReferenceRepos>
+  referenceBranches: ReturnType<typeof parseReferenceBranches>
+  bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
+  contextFiles: ReturnType<typeof parseContextFiles>
+  packageRegistries: ReturnType<typeof parsePackageRegistries>
+  skill: ReturnType<typeof parseSkillSpec>
+  testSecrets: ReturnType<typeof parseTestSecrets>
+  guardLimits: ReturnType<typeof parseGuardLimits>
+  validation: ReturnType<typeof parseValidationSpec>
+  reviewPrNumber: number | undefined
+}
+
+/** Parse the optional structured-output spec (`{ kind, shapeHint?, repair?, failOnUnusableFinal? }`). */
+function parseAgentOutputSpec(raw: unknown): AgentOutputSpec | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const so = raw as Record<string, unknown>
+  const kind = so.kind === 'structured' ? 'structured' : 'prose'
+  const spec: AgentOutputSpec = { kind }
+  if (typeof so.shapeHint === 'string') spec.shapeHint = so.shapeHint
+  // Carry an explicit `repair: false` through — the handler defaults to repair-on
+  // when absent, so dropping `false` would silently re-enable the repair call for a
+  // kind that opted out (it keys off `output.repair === false`).
+  if (typeof so.repair === 'boolean') spec.repair = so.repair
+  // Carry the opt-in truncation gate through (document producers set it); dropping
+  // it would silently re-enable laundering a cut-off reply into a half-baked doc.
+  if (so.failOnUnusableFinal === true) spec.failOnUnusableFinal = true
+  return spec
+}
+
+/** Parse the optional PR spec (`{ title, body }`). */
+function parseAgentPrSpec(raw: unknown): { title: string; body: string } | undefined {
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const p = raw as Record<string, unknown>
+  return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' }
+}
+
+/**
+ * Assemble the {@link AgentJob} object from the request `o` + the pre-parsed {@link
+ * ParsedAgentJobParts}. Extracted from {@link parseAgentJob} so the large conditional-spread
+ * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
+ */
+function assembleAgentJob(
+  o: Record<string, unknown>,
+  mode: AgentJob['mode'],
+  agentField: (value: unknown, path: string) => string,
+  parts: ParsedAgentJobParts,
+): AgentJob {
+  const {
+    output,
+    pr,
+    infra,
+    peerRepos,
+    referenceRepos,
+    referenceBranches,
+    bootstrap,
+    contextFiles,
+    packageRegistries,
+    skill,
+    testSecrets,
+    guardLimits,
+    validation,
+    reviewPrNumber,
+  } = parts
   const repo = (o.repo ?? {}) as Record<string, unknown>
-  const output =
-    typeof o.output === 'object' && o.output !== null
-      ? (() => {
-          const so = o.output as Record<string, unknown>
-          const kind = so.kind === 'structured' ? 'structured' : 'prose'
-          const spec: AgentOutputSpec = { kind }
-          if (typeof so.shapeHint === 'string') spec.shapeHint = so.shapeHint
-          // Carry an explicit `repair: false` through — the handler defaults to repair-on
-          // when absent, so dropping `false` would silently re-enable the repair call for a
-          // kind that opted out (it keys off `output.repair === false`).
-          if (typeof so.repair === 'boolean') spec.repair = so.repair
-          // Carry the opt-in truncation gate through (document producers set it); dropping
-          // it would silently re-enable laundering a cut-off reply into a half-baked doc.
-          if (so.failOnUnusableFinal === true) spec.failOnUnusableFinal = true
-          return spec
-        })()
-      : undefined
-  const pr =
-    typeof o.pr === 'object' && o.pr !== null
-      ? (() => {
-          const p = o.pr as Record<string, unknown>
-          return { title: str(p.title, 'pr.title'), body: typeof p.body === 'string' ? p.body : '' }
-        })()
-      : undefined
-  const infra = parseAgentInfraSpec(o.infra)
-  const peerRepos = parsePeerRepos(o.peerRepos)
-  const referenceRepos = parseReferenceRepos(o.referenceRepos)
-  const referenceBranches = parseReferenceBranches(o.referenceBranches)
-  const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
-  const contextFiles = parseContextFiles(o.contextFiles)
-  const packageRegistries = parsePackageRegistries(o.packageRegistries)
-  const skill = parseSkillSpec(o.skill)
-  const testSecrets = parseTestSecrets(o.testSecrets)
-  const guardLimits = parseGuardLimits(o.guardLimits)
-  const validation = parseValidationSpec(o.validation)
-  const job: AgentJob = {
+  return {
     jobId: str(o.jobId, 'jobId'),
     mode,
     systemPrompt: agentField(o.systemPrompt, 'systemPrompt'),
@@ -1308,28 +1390,11 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(peerRepos.length ? { peerRepos } : {}),
     ...(referenceRepos.length ? { referenceRepos } : {}),
     ...(referenceBranches.length ? { referenceBranches } : {}),
+    ...(reviewPrNumber !== undefined ? { reviewPrNumber } : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
     ...(guardLimits ? { guardLimits } : {}),
     ...(validation ? { validation } : {}),
   }
-  assertAllowedHost(job.repo.cloneUrl, 'repo.cloneUrl')
-  if (job.githubApiBase) assertAllowedHost(job.githubApiBase, 'githubApiBase')
-  // Bootstrap pushes the result to a SEPARATE target repo, so its clone URL must be an
-  // allowed GitHub host too (the installation token is sent to it on the force-push).
-  if (job.bootstrap) assertAllowedHost(job.bootstrap.target.cloneUrl, 'bootstrap.target.cloneUrl')
-  // Each peer repo's clone URL receives the installation token on clone/push, so it must be
-  // an allowed GitHub host too — a body-supplied peer pointing at an attacker host would
-  // exfiltrate the token exactly like a rogue primary clone URL.
-  for (const [i, peer] of (job.peerRepos ?? []).entries()) {
-    assertAllowedHost(peer.repo.cloneUrl, `peerRepos[${i}].repo.cloneUrl`)
-  }
-  // Each reference repo's clone URL receives the installation/PAT token on clone (read-only,
-  // never pushed), so it must be an allowed host too — a body-supplied reference pointing at an
-  // attacker host would exfiltrate the token exactly like a rogue peer clone URL.
-  for (const [i, ref] of (job.referenceRepos ?? []).entries()) {
-    assertAllowedHost(ref.repo.cloneUrl, `referenceRepos[${i}].repo.cloneUrl`)
-  }
-  return job
 }