@cat-factory/executor-harness 1.39.3 → 1.43.0

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, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
+import { cloneRepo, commitAll, conflictDiff, fetchReferenceBranches, hasAgentChanges, headCommit, 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';
@@ -389,6 +389,22 @@ async function runExploreMode(job, opts) {
             logger.info('agent(explore): cloning');
             workDir = await cloneServiceCheckout(dir, job, opts.signal);
         }
+        // Fetch any read-only reference branches into `origin/<b>` so a read-only agent (architect /
+        // analysis / spec-writer) can inspect a prior-art branch without git network credentials of
+        // its own. Best-effort per branch; the run makes no commits regardless.
+        if (job.referenceBranches?.length) {
+            const fetched = await fetchReferenceBranches({
+                dir,
+                branches: job.referenceBranches,
+                ghToken: job.ghToken,
+                signal: opts.signal,
+                onSkip: (branch, reason) => logger.warn('agent(explore): reference branch fetch skipped', { branch, reason }),
+            });
+            logger.info('agent(explore): fetched reference branches', {
+                requested: job.referenceBranches.length,
+                fetched: fetched.length,
+            });
+        }
         // 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
@@ -589,6 +605,24 @@ async function runMultiRepoExplore(job, opts) {
                 signal: opts.signal,
             });
         }));
+        // Reference branches attach to the PRIMARY repo (the first leg): fetch them into its sibling
+        // checkout's `origin/<b>` refs so the agent can read a prior-art branch. Best-effort per branch.
+        if (job.referenceBranches?.length) {
+            const primary = legs[0];
+            if (primary) {
+                const fetched = await fetchReferenceBranches({
+                    dir: join(root, primary.dirName),
+                    branches: job.referenceBranches,
+                    ghToken: primary.ghToken,
+                    signal: opts.signal,
+                    onSkip: (branch, reason) => logger.warn('multi-repo-explore: reference branch fetch skipped', { branch, reason }),
+                });
+                logger.info('multi-repo-explore: fetched reference branches', {
+                    requested: job.referenceBranches.length,
+                    fetched: fetched.length,
+                });
+            }
+        }
         opts.onPhase?.('agent');
         logger.info('multi-repo-explore: running agent', { repos: legs.map((l) => l.dirName) });
         const run = await runAgentInWorkspace({
@@ -689,6 +723,7 @@ async function runSingleRepoCoding(job, opts) {
         guardLimits: job.guardLimits,
         ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
         ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+        ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
     }, opts);
     if (!pushed) {
         // A no-op: a failure for the implementer, a clean non-event for the fixers.

package/dist/coding-agent.js

@@ -1,6 +1,6 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
@@ -99,6 +99,23 @@ export async function runCodingAgent(spec, opts = {}) {
             if (spec.newBranch)
                 await createBranch(dir, spec.newBranch, signal);
         }
+        // Fetch any read-only reference branches into their `origin/<b>` refs so the agent can
+        // inspect them (log/diff/show) without git network credentials of its own. Best-effort per
+        // branch: a vanished branch is warned + skipped, never fatal. The work branch above is the
+        // agent's HEAD; these are only readable siblings it never commits to.
+        if (spec.referenceBranches?.length) {
+            const fetched = await fetchReferenceBranches({
+                dir,
+                branches: spec.referenceBranches,
+                ghToken: spec.ghToken,
+                signal,
+                onSkip: (branch, reason) => logger.warn('coding-agent: reference branch fetch skipped', { branch, reason }),
+            });
+            logger.info('coding-agent: fetched reference branches', {
+                requested: spec.referenceBranches.length,
+                fetched: fetched.length,
+            });
+        }
         // The branch tip before the agent runs this time. A FRESH run produced work iff
         // the branch advances past it; a RESUMED run already carries prior work, so it is
         // never a no-op regardless of what this pass adds. Captured BEFORE the resume base
@@ -443,6 +460,25 @@ export async function runMultiRepoCoding(job, opts = {}) {
                 }
             }
         }
+        // Reference branches attach to the PRIMARY repo, so fetch them into the primary sibling
+        // checkout's `origin/<b>` refs (best-effort per branch). The backend's reference-branches
+        // prompt section names the primary repo's directory to run the read commands in.
+        if (job.referenceBranches?.length) {
+            const primaryLeg = legs.find((l) => l.primary);
+            if (primaryLeg?.dir) {
+                const fetched = await fetchReferenceBranches({
+                    dir: primaryLeg.dir,
+                    branches: job.referenceBranches,
+                    ghToken: primaryLeg.ghToken,
+                    signal,
+                    onSkip: (branch, reason) => logger.warn('multi-repo: reference branch fetch skipped', { branch, reason }),
+                });
+                logger.info('multi-repo: fetched reference branches', {
+                    requested: job.referenceBranches.length,
+                    fetched: fetched.length,
+                });
+            }
+        }
         // Run the agent ONCE with its cwd at the workspace root, so it sees every sibling checkout
         // and can change them coherently. No monorepo/service-directory scoping — the multi-repo
         // note + the backend system-prompt section explain the layout.

package/dist/git.js

@@ -567,6 +567,50 @@ export async function refreshFromBaseIfClean(dir, baseBranch, ghToken, signal) {
         throw err;
     }
 }
+/**
+ * The directory the reference-branches prompt section suggests for a `git worktree add` checkout of
+ * a reference branch alongside the agent's own work. Excluded from the checkout (below) so the
+ * embedded worktree can never be staged into the agent's PR — mirrors the `.cat-context/` treatment
+ * in {@link file://./pi.ts}. Kept in step with the same literal in the backend's
+ * `renderReferenceBranchesSection` (a separate package, so a shared constant isn't feasible).
+ */
+export const REFERENCE_WORKTREE_DIR = '.cat-reference';
+/**
+ * Fetch pre-existing REFERENCE branches into their `origin/<b>` tracking refs, so the agent can
+ * inspect them read-only (`git log origin/<b>`, two-dot `git diff origin/<b>`,
+ * `git show origin/<b>:<path>`) without any git network credentials of its own. The primary
+ * checkout is a shallow single-branch clone, so these refs aren't present until fetched — and the
+ * harness (which holds the per-job token) is the only place that can reach the remote. Uses an
+ * explicit destination refspec (`+refs/heads/<b>:refs/remotes/origin/<b>`) and `--no-tags` so a
+ * reference branch's tags don't pollute the checkout. Best-effort PER branch: a fetch failure (a
+ * branch deleted since dispatch, a transient network error) is reported via `onSkip` and skipped,
+ * never fatal — a reference branch is context, not the run's starting point (contrast the WORKING
+ * branch, whose absence fails the dispatch loudly). Returns the branch names that fetched cleanly.
+ *
+ * On any successful fetch it locally excludes {@link REFERENCE_WORKTREE_DIR} from this checkout, so
+ * if the agent follows the prompt's suggested `git worktree add .cat-reference/<b>` a broad
+ * `git add -A` can never embed that worktree as a stray gitlink in the run's PR.
+ */
+export async function fetchReferenceBranches(opts) {
+    const { dir, branches, ghToken, signal, onSkip } = opts;
+    if (branches.length === 0)
+        return [];
+    const env = await authEnv(ghToken);
+    const fetched = [];
+    for (const branch of branches) {
+        try {
+            await git(['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`], { cwd: dir, signal, env });
+            fetched.push(branch);
+        }
+        catch (err) {
+            onSkip?.(branch, err instanceof Error ? err.message : String(err));
+        }
+    }
+    // Keep the suggested reference-worktree dir out of the agent's commits (best-effort, per-clone).
+    if (fetched.length > 0)
+        await excludeFromGit(dir, `${REFERENCE_WORKTREE_DIR}/`, signal);
+    return fetched;
+}
 /**
  * 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

@@ -178,6 +178,21 @@ function parseReferenceRepos(value) {
         return spec;
     });
 }
+/**
+ * Parse the optional `referenceBranches` list: pre-existing branch NAMES of the PRIMARY repo the
+ * agent may read but never commit to (the apriori-branches reference mode). Unlike
+ * {@link parseReferenceRepos} these are not sibling repos — they are fetched into the primary
+ * checkout's `origin/<b>` refs (see {@link fetchReferenceBranches}). A non-string / empty entry is
+ * dropped; an absent list yields `[]`. Kept simple (no git-ref grammar check) because the backend
+ * validated the name at the write boundary and probed its existence at dispatch.
+ */
+function parseReferenceBranches(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'referenceBranches' must be an array");
+    return value.filter((v) => typeof v === 'string' && v.length > 0);
+}
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value) {
     if (value === undefined || value === null)
@@ -568,6 +583,7 @@ export function parseAgentJob(input) {
     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);
@@ -602,6 +618,7 @@ export function parseAgentJob(input) {
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),
         ...(referenceRepos.length ? { referenceRepos } : {}),
+        ...(referenceBranches.length ? { referenceBranches } : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),

package/dist/server.js

@@ -6,6 +6,7 @@ import { handleInline } from './inline.js';
 import { redactSecrets } from './git.js';
 import { JobRegistry, loadRunnerLimits } from './runner.js';
 import { log } from './logger.js';
+import { HARNESS_VERSION } from './version.js';
 // The container's HTTP entry point. The Worker addresses one instance per run and
 // POSTs a job to /jobs (the body's `kind` selects which agent runs); the harness
 // starts that job in the background (bounded by an inactivity + max-duration
@@ -90,7 +91,14 @@ function send(res, status, body) {
 const server = createServer((req, res) => {
     void (async () => {
         if (req.method === 'GET' && req.url === '/health') {
-            return send(res, 200, { status: 'ok' });
+            // Report the harness version so a backend can detect a stale/mismatched executor and
+            // fail loudly early (see version.ts). Unauthenticated like the rest of /health — the
+            // version is not a secret. An old image predating this field simply omits it, which the
+            // backend treats as a stale signal.
+            return send(res, 200, {
+                status: 'ok',
+                ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
+            });
         }
         // All non-health endpoints are gated by the optional shared secret.
         if (!authorized(req)) {

package/dist/version.js

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// The harness's OWN version, resolved once at module load and reported on `/health`. A
+// backend reads it back over the health handshake to detect a STALE or MISMATCHED executor
+// (an old image left behind by a mutable tag, an outdated native install) and fail loudly
+// and early — instead of the cryptic downstream symptom a version skew otherwise produces
+// (e.g. a since-removed git flag reappearing and breaking every authenticated clone/push).
+//
+// Resolution order, most authoritative first:
+//   1. `HARNESS_VERSION` env — the Docker image can bake it; an operator can override.
+//   2. the version file the image writes next to `dist/` (the image deliberately ships NO
+//      package.json, so it captures the version into `harness-version.txt` at build time).
+//   3. `package.json` — the native/npm install and a source checkout both keep it beside
+//      `dist/`, so `dist/version.js` finds it one level up.
+// Undefined only for an oddly-assembled runtime carrying none of the three; the backend then
+// treats "no reported version" as a strong stale signal in its own right.
+function readVersionFile(dir, rel) {
+    try {
+        const raw = readFileSync(join(dir, rel), 'utf8');
+        const value = rel.endsWith('.json') ? JSON.parse(raw).version : raw;
+        const trimmed = value?.trim();
+        return trimmed || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveHarnessVersion() {
+    const fromEnv = process.env.HARNESS_VERSION?.trim();
+    if (fromEnv)
+        return fromEnv;
+    let dir;
+    try {
+        // Compiled to `dist/version.js`; the baked file / package.json sit one level up from dist.
+        dir = dirname(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return undefined;
+    }
+    return readVersionFile(dir, '../harness-version.txt') ?? readVersionFile(dir, '../package.json');
+}
+/** The running harness version, or undefined when it cannot be determined. */
+export const HARNESS_VERSION = resolveHarnessVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.39.3",
+  "version": "1.43.0",
   "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.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/server": "0.106.0",
-    "@cat-factory/spend": "0.12.0"
+    "@cat-factory/server": "0.108.0",
+    "@cat-factory/spend": "0.12.10"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -18,6 +18,7 @@ import {
   cloneRepo,
   commitAll,
   conflictDiff,
+  fetchReferenceBranches,
   hasAgentChanges,
   headCommit,
   mergeBranch,
@@ -474,6 +475,24 @@ async function runExploreMode(job: AgentJob, opts: RunOptions): Promise<AgentRes
         workDir = await cloneServiceCheckout(dir, job, opts.signal)
       }
 
+      // Fetch any read-only reference branches into `origin/<b>` so a read-only agent (architect /
+      // analysis / spec-writer) can inspect a prior-art branch without git network credentials of
+      // its own. Best-effort per branch; the run makes no commits regardless.
+      if (job.referenceBranches?.length) {
+        const fetched = await fetchReferenceBranches({
+          dir,
+          branches: job.referenceBranches,
+          ghToken: job.ghToken,
+          signal: opts.signal,
+          onSkip: (branch, reason) =>
+            logger.warn('agent(explore): reference branch fetch skipped', { branch, reason }),
+        })
+        logger.info('agent(explore): fetched reference branches', {
+          requested: job.referenceBranches.length,
+          fetched: fetched.length,
+        })
+      }
+
       // 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
@@ -719,6 +738,26 @@ async function runMultiRepoExplore(job: AgentJob, opts: RunOptions): Promise<Age
       }),
     )
 
+    // Reference branches attach to the PRIMARY repo (the first leg): fetch them into its sibling
+    // checkout's `origin/<b>` refs so the agent can read a prior-art branch. Best-effort per branch.
+    if (job.referenceBranches?.length) {
+      const primary = legs[0]
+      if (primary) {
+        const fetched = await fetchReferenceBranches({
+          dir: join(root, primary.dirName),
+          branches: job.referenceBranches,
+          ghToken: primary.ghToken,
+          signal: opts.signal,
+          onSkip: (branch, reason) =>
+            logger.warn('multi-repo-explore: reference branch fetch skipped', { branch, reason }),
+        })
+        logger.info('multi-repo-explore: fetched reference branches', {
+          requested: job.referenceBranches.length,
+          fetched: fetched.length,
+        })
+      }
+    }
+
     opts.onPhase?.('agent')
     logger.info('multi-repo-explore: running agent', { repos: legs.map((l) => l.dirName) })
     const run = await runAgentInWorkspace(
@@ -828,6 +867,7 @@ async function runSingleRepoCoding(job: AgentJob, opts: RunOptions): Promise<Age
       guardLimits: job.guardLimits,
       ...(job.persistentCheckout ? { persistentCheckout: true } : {}),
       ...(job.streamFollowUps ? { streamFollowUps: true } : {}),
+      ...(job.referenceBranches?.length ? { referenceBranches: job.referenceBranches } : {}),
     },
     opts,
   )

package/src/coding-agent.ts

@@ -16,6 +16,7 @@ import {
   commitTrackedEdits,
   createBranch,
   excludeFromGit,
+  fetchReferenceBranches,
   headCommit,
   listUntrackedFiles,
   openPullRequest,
@@ -85,6 +86,12 @@ export interface CodingAgentSpec extends HarnessAuthFields {
    * only for the implementer (`coder`) dispatch; absent ⇒ no tailing (e.g. the CI-fixer).
    */
   streamFollowUps?: boolean
+  /**
+   * READ-ONLY reference branches of THIS repo (the apriori-branches reference mode): fetched
+   * into `origin/<b>` after the checkout so the agent can inspect them but never commits to
+   * them. Best-effort per branch. Absent/empty ⇒ none fetched.
+   */
+  referenceBranches?: string[]
 }
 
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
@@ -202,6 +209,26 @@ export async function runCodingAgent(
         })
         if (spec.newBranch) await createBranch(dir, spec.newBranch, signal)
       }
+
+      // Fetch any read-only reference branches into their `origin/<b>` refs so the agent can
+      // inspect them (log/diff/show) without git network credentials of its own. Best-effort per
+      // branch: a vanished branch is warned + skipped, never fatal. The work branch above is the
+      // agent's HEAD; these are only readable siblings it never commits to.
+      if (spec.referenceBranches?.length) {
+        const fetched = await fetchReferenceBranches({
+          dir,
+          branches: spec.referenceBranches,
+          ghToken: spec.ghToken,
+          signal,
+          onSkip: (branch, reason) =>
+            logger.warn('coding-agent: reference branch fetch skipped', { branch, reason }),
+        })
+        logger.info('coding-agent: fetched reference branches', {
+          requested: spec.referenceBranches.length,
+          fetched: fetched.length,
+        })
+      }
+
       // The branch tip before the agent runs this time. A FRESH run produced work iff
       // the branch advances past it; a RESUMED run already carries prior work, so it is
       // never a no-op regardless of what this pass adds. Captured BEFORE the resume base
@@ -602,6 +629,27 @@ export async function runMultiRepoCoding(
       }
     }
 
+    // Reference branches attach to the PRIMARY repo, so fetch them into the primary sibling
+    // checkout's `origin/<b>` refs (best-effort per branch). The backend's reference-branches
+    // prompt section names the primary repo's directory to run the read commands in.
+    if (job.referenceBranches?.length) {
+      const primaryLeg = legs.find((l) => l.primary)
+      if (primaryLeg?.dir) {
+        const fetched = await fetchReferenceBranches({
+          dir: primaryLeg.dir,
+          branches: job.referenceBranches,
+          ghToken: primaryLeg.ghToken,
+          signal,
+          onSkip: (branch, reason) =>
+            logger.warn('multi-repo: reference branch fetch skipped', { branch, reason }),
+        })
+        logger.info('multi-repo: fetched reference branches', {
+          requested: job.referenceBranches.length,
+          fetched: fetched.length,
+        })
+      }
+    }
+
     // Run the agent ONCE with its cwd at the workspace root, so it sees every sibling checkout
     // and can change them coherently. No monorepo/service-directory scoping — the multi-repo
     // note + the backend system-prompt section explain the layout.

package/src/git.ts

@@ -697,6 +697,59 @@ export async function refreshFromBaseIfClean(
   }
 }
 
+/**
+ * The directory the reference-branches prompt section suggests for a `git worktree add` checkout of
+ * a reference branch alongside the agent's own work. Excluded from the checkout (below) so the
+ * embedded worktree can never be staged into the agent's PR — mirrors the `.cat-context/` treatment
+ * in {@link file://./pi.ts}. Kept in step with the same literal in the backend's
+ * `renderReferenceBranchesSection` (a separate package, so a shared constant isn't feasible).
+ */
+export const REFERENCE_WORKTREE_DIR = '.cat-reference'
+
+/**
+ * Fetch pre-existing REFERENCE branches into their `origin/<b>` tracking refs, so the agent can
+ * inspect them read-only (`git log origin/<b>`, two-dot `git diff origin/<b>`,
+ * `git show origin/<b>:<path>`) without any git network credentials of its own. The primary
+ * checkout is a shallow single-branch clone, so these refs aren't present until fetched — and the
+ * harness (which holds the per-job token) is the only place that can reach the remote. Uses an
+ * explicit destination refspec (`+refs/heads/<b>:refs/remotes/origin/<b>`) and `--no-tags` so a
+ * reference branch's tags don't pollute the checkout. Best-effort PER branch: a fetch failure (a
+ * branch deleted since dispatch, a transient network error) is reported via `onSkip` and skipped,
+ * never fatal — a reference branch is context, not the run's starting point (contrast the WORKING
+ * branch, whose absence fails the dispatch loudly). Returns the branch names that fetched cleanly.
+ *
+ * On any successful fetch it locally excludes {@link REFERENCE_WORKTREE_DIR} from this checkout, so
+ * if the agent follows the prompt's suggested `git worktree add .cat-reference/<b>` a broad
+ * `git add -A` can never embed that worktree as a stray gitlink in the run's PR.
+ */
+export async function fetchReferenceBranches(opts: {
+  dir: string
+  branches: string[]
+  ghToken: string
+  signal?: AbortSignal
+  /** Called once per branch that failed to fetch, so the caller (which owns a logger) can warn. */
+  onSkip?: (branch: string, reason: string) => void
+}): Promise<string[]> {
+  const { dir, branches, ghToken, signal, onSkip } = opts
+  if (branches.length === 0) return []
+  const env = await authEnv(ghToken)
+  const fetched: string[] = []
+  for (const branch of branches) {
+    try {
+      await git(
+        ['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`],
+        { cwd: dir, signal, env },
+      )
+      fetched.push(branch)
+    } catch (err) {
+      onSkip?.(branch, err instanceof Error ? err.message : String(err))
+    }
+  }
+  // Keep the suggested reference-worktree dir out of the agent's commits (best-effort, per-clone).
+  if (fetched.length > 0) await excludeFromGit(dir, `${REFERENCE_WORKTREE_DIR}/`, signal)
+  return fetched
+}
+
 /**
  * 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

@@ -282,6 +282,20 @@ function parseReferenceRepos(value: unknown): ReferenceRepoSpec[] {
   })
 }
 
+/**
+ * Parse the optional `referenceBranches` list: pre-existing branch NAMES of the PRIMARY repo the
+ * agent may read but never commit to (the apriori-branches reference mode). Unlike
+ * {@link parseReferenceRepos} these are not sibling repos — they are fetched into the primary
+ * checkout's `origin/<b>` refs (see {@link fetchReferenceBranches}). A non-string / empty entry is
+ * dropped; an absent list yields `[]`. Kept simple (no git-ref grammar check) because the backend
+ * validated the name at the write boundary and probed its existence at dispatch.
+ */
+function parseReferenceBranches(value: unknown): string[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'referenceBranches' must be an array")
+  return value.filter((v): v is string => typeof v === 'string' && v.length > 0)
+}
+
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value: unknown): 'github' | 'gitlab' | undefined {
   if (value === undefined || value === null) return undefined
@@ -697,6 +711,16 @@ export interface AgentJob extends HarnessAuthFields {
    * pushed. Absent ⇒ single-repo run. Independent of {@link peerRepos} (those are writable).
    */
   referenceRepos?: ReferenceRepoSpec[]
+  /**
+   * Pre-existing branch names of the PRIMARY repo attached to the task as READ-ONLY reference
+   * points (the apriori-branches reference mode). After the primary checkout the harness fetches
+   * each into its `origin/<b>` tracking ref (best-effort per branch) so the agent can inspect it —
+   * `git log origin/<b>`, two-dot `git diff origin/<b>`, `git show origin/<b>:<path>` — but never
+   * commits to or pushes it (that guarantee lives in the prompt guidance, not a git constraint).
+   * Distinct from {@link referenceRepos}: those are separate sibling repos; these are branches of
+   * the same primary repo. Absent ⇒ none. Consumed by the coding + explore flows.
+   */
+  referenceBranches?: string[]
   /**
    * 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
@@ -1100,6 +1124,7 @@ export function parseAgentJob(input: unknown): AgentJob {
   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)
@@ -1134,6 +1159,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     ...(pr ? { pr } : {}),
     ...(peerRepos.length ? { peerRepos } : {}),
     ...(referenceRepos.length ? { referenceRepos } : {}),
+    ...(referenceBranches.length ? { referenceBranches } : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),

package/src/server.ts

@@ -6,6 +6,7 @@ import { handleInline } from './inline.js'
 import { redactSecrets } from './git.js'
 import { JobRegistry, loadRunnerLimits, type JobResultBase, type RunOptions } from './runner.js'
 import { log } from './logger.js'
+import { HARNESS_VERSION } from './version.js'
 
 // The container's HTTP entry point. The Worker addresses one instance per run and
 // POSTs a job to /jobs (the body's `kind` selects which agent runs); the harness
@@ -109,7 +110,14 @@ function send(res: ServerResponse, status: number, body: unknown): void {
 const server = createServer((req, res) => {
   void (async () => {
     if (req.method === 'GET' && req.url === '/health') {
-      return send(res, 200, { status: 'ok' })
+      // Report the harness version so a backend can detect a stale/mismatched executor and
+      // fail loudly early (see version.ts). Unauthenticated like the rest of /health — the
+      // version is not a secret. An old image predating this field simply omits it, which the
+      // backend treats as a stale signal.
+      return send(res, 200, {
+        status: 'ok',
+        ...(HARNESS_VERSION ? { version: HARNESS_VERSION } : {}),
+      })
     }
     // All non-health endpoints are gated by the optional shared secret.
     if (!authorized(req)) {

package/src/version.ts

@@ -0,0 +1,45 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// The harness's OWN version, resolved once at module load and reported on `/health`. A
+// backend reads it back over the health handshake to detect a STALE or MISMATCHED executor
+// (an old image left behind by a mutable tag, an outdated native install) and fail loudly
+// and early — instead of the cryptic downstream symptom a version skew otherwise produces
+// (e.g. a since-removed git flag reappearing and breaking every authenticated clone/push).
+//
+// Resolution order, most authoritative first:
+//   1. `HARNESS_VERSION` env — the Docker image can bake it; an operator can override.
+//   2. the version file the image writes next to `dist/` (the image deliberately ships NO
+//      package.json, so it captures the version into `harness-version.txt` at build time).
+//   3. `package.json` — the native/npm install and a source checkout both keep it beside
+//      `dist/`, so `dist/version.js` finds it one level up.
+// Undefined only for an oddly-assembled runtime carrying none of the three; the backend then
+// treats "no reported version" as a strong stale signal in its own right.
+
+function readVersionFile(dir: string, rel: string): string | undefined {
+  try {
+    const raw = readFileSync(join(dir, rel), 'utf8')
+    const value = rel.endsWith('.json') ? (JSON.parse(raw) as { version?: string }).version : raw
+    const trimmed = value?.trim()
+    return trimmed || undefined
+  } catch {
+    return undefined
+  }
+}
+
+function resolveHarnessVersion(): string | undefined {
+  const fromEnv = process.env.HARNESS_VERSION?.trim()
+  if (fromEnv) return fromEnv
+  let dir: string
+  try {
+    // Compiled to `dist/version.js`; the baked file / package.json sit one level up from dist.
+    dir = dirname(fileURLToPath(import.meta.url))
+  } catch {
+    return undefined
+  }
+  return readVersionFile(dir, '../harness-version.txt') ?? readVersionFile(dir, '../package.json')
+}
+
+/** The running harness version, or undefined when it cannot be determined. */
+export const HARNESS_VERSION: string | undefined = resolveHarnessVersion()