@cat-factory/executor-harness 1.50.8 → 1.50.10

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

@@ -684,6 +684,7 @@ export function parseAgentJob(input) {
     const testSecrets = parseTestSecrets(o.testSecrets);
     const guardLimits = parseGuardLimits(o.guardLimits);
     const validation = parseValidationSpec(o.validation);
+    const reviewPrNumber = posInt(o.reviewPrNumber);
     const job = {
         jobId: str(o.jobId, 'jobId'),
         mode,
@@ -715,6 +716,7 @@ 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 } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.50.8",
+  "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.2",
-    "@cat-factory/spend": "0.12.68"
+    "@cat-factory/server": "0.140.4",
+    "@cat-factory/spend": "0.12.69"
   },
   "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
@@ -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 } : {}),