@cat-factory/executor-harness 1.50.6 → 1.50.10

package/dist/subagents.js

@@ -0,0 +1,206 @@
+import { readdir, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+import { claudeAssistantContent, claudeCallUsage, isObject, redactBody } from './claude-stream.js';
+export function createSliceTracker() {
+    // Insertion-ordered so the progress `items` render in dispatch order.
+    const slices = new Map();
+    return {
+        onAssistant(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_use' || block.name !== 'Task')
+                    continue;
+                const id = typeof block.id === 'string' ? block.id : undefined;
+                if (!id || slices.has(id))
+                    continue;
+                const input = isObject(block.input) ? block.input : {};
+                const description = typeof input.description === 'string' && input.description.trim()
+                    ? input.description.trim()
+                    : `Subagent ${slices.size + 1}`;
+                slices.set(id, { toolUseId: id, description, done: false });
+            }
+        },
+        onUser(content) {
+            if (!Array.isArray(content))
+                return;
+            for (const block of content) {
+                if (!isObject(block) || block.type !== 'tool_result')
+                    continue;
+                const id = typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+                const slice = id ? slices.get(id) : undefined;
+                if (slice)
+                    slice.done = true;
+            }
+        },
+        hasSlices() {
+            return slices.size > 0;
+        },
+        progress() {
+            if (slices.size === 0)
+                return undefined;
+            const items = [...slices.values()].map((s) => ({
+                label: s.description,
+                status: (s.done ? 'completed' : 'in_progress'),
+            }));
+            const completed = items.filter((i) => i.status === 'completed').length;
+            return {
+                completed,
+                inProgress: items.length - completed,
+                total: items.length,
+                items,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Subagent transcript watcher (heartbeat + usage) (D3)
+// ---------------------------------------------------------------------------
+/** Default poll cadence for the transcript directory; well under the git timeout margin. */
+const DEFAULT_POLL_MS = 3_000;
+/**
+ * Start watching `dir` (the CLI's `<configHome>/subagents`) for `*.jsonl` transcripts,
+ * tailing each file by byte offset. New content feeds `onActivity` (heartbeat) and each
+ * assistant turn carrying usage is lifted into a {@link HarnessCallMetric} + summed into
+ * the cumulative usage. Best-effort throughout: the directory may not exist yet (created
+ * lazily by the CLI), a file may be mid-write, and the line/usage shape may change across
+ * CLI versions — every such case is swallowed so the watcher can only ever ADD signal,
+ * never break the run.
+ */
+export function startSubagentWatcher(dir, opts) {
+    const secrets = opts.secrets ?? [];
+    const offsets = new Map();
+    const calls = [];
+    const usage = { inputTokens: 0, outputTokens: 0 };
+    // Per-file partial-line remainder, carried as raw BYTES (not a decoded string). A JSONL
+    // record can straddle two polls (the file is appended between ticks), and the byte offset
+    // we stop at can fall in the middle of a multi-byte UTF-8 character; decoding a partial
+    // read to a string would replace that split character with U+FFFD and corrupt the line.
+    // Buffering bytes and decoding only whole lines keeps the captured text faithful.
+    const carry = new Map();
+    let polling = false;
+    const ingestLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('{'))
+            return;
+        let event;
+        try {
+            event = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        // Subagent transcripts mirror the session-transcript envelope: an `assistant` entry
+        // whose `message` carries the Anthropic `usage` + `content`. Read defensively.
+        if (event.type !== 'assistant' || !isObject(event.message))
+            return;
+        const message = event.message;
+        const u = claudeCallUsage(message.usage);
+        if (u.inputTokens === 0 && u.outputTokens === 0)
+            return;
+        const content = Array.isArray(message.content) ? message.content : [];
+        const { text, reasoning } = claudeAssistantContent(content);
+        calls.push({
+            ...(typeof message.model === 'string'
+                ? { model: message.model }
+                : opts.model
+                    ? { model: opts.model }
+                    : {}),
+            // The subagent's own transcript isn't a re-sendable prompt chain, so we don't
+            // reconstruct the request side (kept empty); the response + tokens are faithful.
+            promptText: '',
+            messageCount: 0,
+            responseText: redactBody(text, secrets),
+            reasoningText: redactBody(reasoning, secrets),
+            inputTokens: u.inputTokens,
+            cachedInputTokens: u.cachedInputTokens,
+            outputTokens: u.outputTokens,
+            finishReason: typeof message.stop_reason === 'string' ? message.stop_reason : null,
+        });
+        usage.inputTokens += u.inputTokens;
+        usage.outputTokens += u.outputTokens;
+    };
+    const NEWLINE = 0x0a;
+    const readNew = (path, from, to) => new Promise((resolve) => {
+        // Tail as raw bytes and split on the newline byte, decoding each COMPLETE line to
+        // UTF-8 only on that boundary (a '\n' is a single byte, never part of a multi-byte
+        // sequence), so a record — or a multi-byte character — that spans this read and the
+        // next is reassembled from the byte carry rather than corrupted at the seam.
+        let buffer = carry.get(path) ?? Buffer.alloc(0);
+        const stream = createReadStream(path, { start: from, end: to - 1 });
+        stream.on('data', (chunk) => {
+            buffer = buffer.length ? Buffer.concat([buffer, chunk]) : chunk;
+            let nl = buffer.indexOf(NEWLINE);
+            while (nl !== -1) {
+                ingestLine(buffer.subarray(0, nl).toString('utf8'));
+                buffer = buffer.subarray(nl + 1);
+                nl = buffer.indexOf(NEWLINE);
+            }
+        });
+        stream.on('error', () => resolve());
+        stream.on('close', () => {
+            // Copy the remainder out of the shared chunk backing store before caching it, so a
+            // later Buffer.concat can't be aliased by a reused stream buffer.
+            carry.set(path, Buffer.from(buffer));
+            resolve();
+        });
+    });
+    const pollOnce = async () => {
+        if (polling)
+            return;
+        polling = true;
+        try {
+            let entries;
+            try {
+                entries = (await readdir(dir)).filter((n) => n.endsWith('.jsonl'));
+            }
+            catch {
+                return; // dir not created yet (or vanished) — try again next tick
+            }
+            let grew = false;
+            for (const name of entries) {
+                const path = join(dir, name);
+                let size;
+                try {
+                    size = (await stat(path)).size;
+                }
+                catch {
+                    continue;
+                }
+                const from = offsets.get(path) ?? 0;
+                if (size <= from)
+                    continue;
+                grew = true;
+                await readNew(path, from, size);
+                offsets.set(path, size);
+            }
+            if (grew)
+                opts.onActivity?.();
+        }
+        catch (e) {
+            opts.log?.warn('subagent transcript poll failed', { error: String(e) });
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const timer = setInterval(() => void pollOnce(), opts.intervalMs ?? DEFAULT_POLL_MS);
+    // Don't let the watcher's timer keep the container process alive on its own.
+    timer.unref?.();
+    return {
+        // Always does a final drain (idempotent clear of the timer), so a late transcript
+        // write between the last tick and stop is still captured, and a second stop() picks up
+        // anything appended since — the per-file offsets make re-polling safe (no double count).
+        async stop() {
+            clearInterval(timer);
+            await pollOnce();
+        },
+        usage() {
+            return { ...usage };
+        },
+        calls() {
+            return calls;
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.6",
+  "version": "1.50.10",
   "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.0",
-    "@cat-factory/spend": "0.12.67"
+    "@cat-factory/server": "0.140.4",
+    "@cat-factory/spend": "0.12.69"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -2,10 +2,19 @@ import { spawn } from 'node:child_process'
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { homedir, tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
+import {
+  claudeAssistantContent,
+  claudeCallUsage,
+  isObject,
+  numberOf,
+  redactBody,
+} from './claude-stream.js'
 import type { Logger } from './logger.js'
 import type { HarnessCallMetric, PiRunOutcome, PiRunStats, TodoProgress } from './pi.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { redact, secretsToRedact } from './redact.js'
+import { createSliceTracker, startSubagentWatcher } from './subagents.js'
+import { assertOnboardingKeysCurrent, writeOnboardingPreseed } from './onboarding-preseed.js'
 import { retainSessionTranscripts } from './transcript-retention.js'
 
 // The alternate (subscription) harness runners. The Pi harness reaches models
@@ -79,15 +88,6 @@ export interface SubscriptionRunOptions {
   log?: Logger
 }
 
-function isObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null
-}
-
-/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
-function redactBody(text: string, secrets: string[]): string {
-  return secrets.length ? redact(text, secrets) : text
-}
-
 /**
  * Fallback token attribution: if a CLI reported a cumulative total but no per-turn
  * usage (so every captured call has zero tokens), pin the whole total onto the LAST
@@ -325,6 +325,19 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       ]
   const calls: HarnessCallMetric[] = []
 
+  // ADR 0026 D2.1: derive slice progress from the parent stream's `Task` dispatches +
+  // their terminal tool_results (both DO appear here — only a subagent's intermediate
+  // turns don't). A real parent TodoWrite plan, when the agent writes one, wins; the
+  // slice-derived progress is the fallback for the parallel-subagent shape that writes no
+  // parent plan (the pr-reviewer failure this fixes).
+  const sliceTracker = createSliceTracker()
+  let sawTodoPlan = false
+  const emitSliceProgress = (): void => {
+    if (sawTodoPlan || !opts.onProgress) return
+    const progress = sliceTracker.progress()
+    if (progress) opts.onProgress(progress)
+  }
+
   const onEvent = (event: Record<string, unknown>): void => {
     const type = event.type
     if (type === 'assistant' && isObject(event.message)) {
@@ -341,9 +354,14 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           opts.onProgress
         ) {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
-          if (progress) opts.onProgress(progress)
+          if (progress) {
+            sawTodoPlan = true
+            opts.onProgress(progress)
+          }
         }
       }
+      sliceTracker.onAssistant(content)
+      emitSliceProgress()
       // Record this call BEFORE appending its turn: the prompt is the history that
       // produced this response. The append-only array keeps each call's prompt a strict
       // prefix of the next, so the backend's telemetry chain delta-compresses cleanly.
@@ -363,7 +381,11 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     } else if (type === 'user' && isObject(event.message)) {
       // tool_result blocks the harness fed back to the model — part of the next prompt.
       const content = (event.message as Record<string, unknown>).content
-      if (Array.isArray(content)) messages.push({ role: 'tool', content })
+      if (Array.isArray(content)) {
+        sliceTracker.onUser(content)
+        emitSliceProgress()
+        messages.push({ role: 'tool', content })
+      }
     } else if (type === 'result') {
       if (typeof event.result === 'string') summary = event.result
       usage = claudeUsage(event.usage) ?? usage
@@ -389,16 +411,12 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // as already accepted so `-p` starts straight into the run. Best-effort: written
   // before the CLI starts; unknown keys are harmless if a CLI version ignores them.
   // (Ambient mode skips this — the developer's own config is already onboarded.)
+  // ADR 0026 D4: assert the pinned onboarding keys landed and log them with the CLI
+  // version, so a future first-run gate this set doesn't cover (which looks identical to
+  // a healthy-but-quiet subagent start) is diffable when the cold-start watchdog fires.
   if (configHome) {
-    await writeFile(
-      join(configHome, '.claude.json'),
-      JSON.stringify({
-        hasCompletedOnboarding: true,
-        bypassPermissionsModeAccepted: true,
-        hasTrustDialogAccepted: true,
-      }),
-      { mode: 0o600 },
-    ).catch(() => {})
+    await writeOnboardingPreseed(configHome)
+    await assertOnboardingKeysCurrent(configHome, process.env.CLAUDE_CLI_VERSION, opts.log)
   }
 
   // Repo-sourced Claude Skill (slice 2): install it as a native skill under the config dir's
@@ -428,6 +446,20 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
           : { CLAUDE_CODE_OAUTH_TOKEN: opts.subscriptionToken! }),
       }
 
+  // ADR 0026 D2.1/D3: while the run is live, tail the CLI's `subagents/*.jsonl`
+  // transcripts (under the isolated config home) so a parallel-subagent review keeps the
+  // inactivity heartbeat alive (any new bytes ⇒ `onActivity`) and its otherwise-invisible
+  // token spend is lifted into the run's telemetry. Ambient mode has no isolated home to
+  // watch. Best-effort — a missing/renamed transcript layout just yields no extra signal.
+  const subagents = configHome
+    ? startSubagentWatcher(join(configHome, 'subagents'), {
+        ...(opts.onActivity ? { onActivity: opts.onActivity } : {}),
+        secrets,
+        model: opts.model,
+        ...(opts.log ? { log: opts.log } : {}),
+      })
+    : undefined
+
   try {
     const { stderrTail } = await streamCli(
       {
@@ -455,15 +487,40 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       onEvent,
     )
 
+    // The parent's cumulative-usage fallback applies to the PARENT calls only (before the
+    // subagent calls, which carry their own per-turn tokens, are concatenated).
     attributeCumulativeUsage(calls, usage)
+    // Final drain of any subagent transcript writes that landed after the last poll, then
+    // fold the subagents' usage + per-call telemetry into the run's outcome — their tokens
+    // never appear on the parent stream, so this is the only place they are accounted.
+    await subagents?.stop()
+    const subUsage = subagents?.usage() ?? { inputTokens: 0, outputTokens: 0 }
+    const subCalls = subagents?.calls() ?? []
+    const mergedCalls = [...calls, ...subCalls]
+    // INVARIANT (do not "fix" this into a double count): the run total is the parent usage
+    // PLUS the subagent usage because the two are disjoint sources. The parent `usage` here
+    // is the terminal `result` event's cumulative, which covers ONLY the parent loop — the
+    // ADR 0026 incident is itself the proof: a heavily subagent-parallelised review reported
+    // ~0 tokens, i.e. the parent stream (and its `result` total) never included the subagent
+    // spend. The subagent tokens live exclusively in the `subagents/*.jsonl` transcripts (a
+    // directory distinct from the parent's `projects/` session transcript), which the watcher
+    // reads and nothing else does — so neither `calls` nor `usage` can already contain them.
+    const mergedUsage =
+      usage || subUsage.inputTokens || subUsage.outputTokens
+        ? {
+            inputTokens: (usage?.inputTokens ?? 0) + subUsage.inputTokens,
+            outputTokens: (usage?.outputTokens ?? 0) + subUsage.outputTokens,
+          }
+        : undefined
     return {
       summary,
       stats,
       stderrTail,
-      ...(usage ? { usage } : {}),
-      ...(calls.length ? { callMetrics: calls } : {}),
+      ...(mergedUsage ? { usage: mergedUsage } : {}),
+      ...(mergedCalls.length ? { callMetrics: mergedCalls } : {}),
     }
   } finally {
+    await subagents?.stop()
     if (configHome) {
       // Lift the CLI session transcripts (`projects/`) out for short-lived retention BEFORE the
       // home is deleted — the credential lives at the home root, never in `projects/`, so this
@@ -511,44 +568,6 @@ function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number
   return { inputTokens: input, outputTokens: output }
 }
 
-/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
-function claudeAssistantContent(content: unknown[]): {
-  text: string
-  reasoning: string
-  toolUses: number
-} {
-  let text = ''
-  let reasoning = ''
-  let toolUses = 0
-  for (const block of content) {
-    if (!isObject(block)) continue
-    if (block.type === 'text' && typeof block.text === 'string') text += block.text
-    else if (block.type === 'thinking' && typeof block.thinking === 'string')
-      reasoning += block.thinking
-    else if (block.type === 'tool_use') toolUses += 1
-  }
-  return { text, reasoning, toolUses }
-}
-
-/**
- * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
- * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
- * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
- */
-function claudeCallUsage(raw: unknown): {
-  inputTokens: number
-  cachedInputTokens: number
-  outputTokens: number
-} {
-  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
-  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
-  return {
-    inputTokens: numberOf(raw.input_tokens) + cached,
-    cachedInputTokens: cached,
-    outputTokens: numberOf(raw.output_tokens),
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Codex
 // ---------------------------------------------------------------------------
@@ -808,10 +827,6 @@ function codexLastTurnUsage(event: Record<string, unknown>):
   return { inputTokens: input, cachedInputTokens: cached, outputTokens: output }
 }
 
-function numberOf(value: unknown): number {
-  return typeof value === 'number' && Number.isFinite(value) ? value : 0
-}
-
 /** Dispatch to the configured subscription harness runner. */
 export function runSubscriptionHarness(
   harness: SubscriptionHarness,

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/claude-stream.ts

@@ -0,0 +1,58 @@
+import { redact } from './redact.js'
+
+// Shared parsing of Claude Code's stream-json / session-transcript envelope. The parent
+// runner (`agent-runner.ts`) reads these off the CLI's stdout; the subagent watcher
+// (`subagents.ts`) reads the same shapes off the `subagents/*.jsonl` transcripts. Kept in
+// one place so both read usage/content identically and the cycle between the two modules
+// is broken.
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+export function numberOf(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+/** Scrub any leased-credential occurrences from a telemetry body (no-op when none). */
+export function redactBody(text: string, secrets: string[]): string {
+  return secrets.length ? redact(text, secrets) : text
+}
+
+/** Pull the text + reasoning out of a Claude `assistant` message's content blocks. */
+export function claudeAssistantContent(content: unknown[]): {
+  text: string
+  reasoning: string
+  toolUses: number
+} {
+  let text = ''
+  let reasoning = ''
+  let toolUses = 0
+  for (const block of content) {
+    if (!isObject(block)) continue
+    if (block.type === 'text' && typeof block.text === 'string') text += block.text
+    else if (block.type === 'thinking' && typeof block.thinking === 'string')
+      reasoning += block.thinking
+    else if (block.type === 'tool_use') toolUses += 1
+  }
+  return { text, reasoning, toolUses }
+}
+
+/**
+ * Per-CALL token usage off a Claude `assistant` message's `usage` (this turn only, not
+ * the cumulative `result` total). `inputTokens` counts every billed input bucket (fresh
+ * + both cache buckets); `cachedInputTokens` is the cache share, surfaced separately.
+ */
+export function claudeCallUsage(raw: unknown): {
+  inputTokens: number
+  cachedInputTokens: number
+  outputTokens: number
+} {
+  if (!isObject(raw)) return { inputTokens: 0, cachedInputTokens: 0, outputTokens: 0 }
+  const cached = numberOf(raw.cache_read_input_tokens) + numberOf(raw.cache_creation_input_tokens)
+  return {
+    inputTokens: numberOf(raw.input_tokens) + cached,
+    cachedInputTokens: cached,
+    outputTokens: numberOf(raw.output_tokens),
+  }
+}

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
@@ -1277,6 +1286,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   const testSecrets = parseTestSecrets(o.testSecrets)
   const guardLimits = parseGuardLimits(o.guardLimits)
   const validation = parseValidationSpec(o.validation)
+  const reviewPrNumber = posInt(o.reviewPrNumber)
   const job: AgentJob = {
     jobId: str(o.jobId, 'jobId'),
     mode,
@@ -1308,6 +1318,7 @@ 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 } : {}),