@cat-factory/executor-harness 1.34.10 → 1.35.0

package/dist/agent.js

@@ -603,11 +603,11 @@ async function runCodingMode(job, opts) {
     // commit + push (no PR). Keyed off job DATA (`mergeBase`), not the agent kind.
     if (job.mergeBase)
         return runConflictResolution(job, opts);
-    // Multi-repo coding (service-connections phase 3): clone every connected peer repo as a
-    // sibling, run the agent once across all of them, and open one PR per changed repo. Keyed
-    // off job DATA (`peerRepos`), not the agent kind — the implementer sets it when the task
-    // has involved services in distinct repos.
-    const result = job.peerRepos?.length
+    // Multi-repo coding: clone every additional repo as a sibling and run the agent once across
+    // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
+    // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
+    // reference repos (`referenceRepos`, cloned but never pushed).
+    const result = job.peerRepos?.length || job.referenceRepos?.length
         ? await runMultiRepoCoding(job, opts)
         : await runSingleRepoCoding(job, opts);
     // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the

package/dist/coding-agent.js

@@ -326,6 +326,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
     const { signal } = opts;
     const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId });
     const peers = job.peerRepos ?? [];
+    const references = job.referenceRepos ?? [];
     const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch;
     // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
     // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
@@ -358,6 +359,21 @@ export async function runMultiRepoCoding(job, opts = {}) {
             baseSha: '',
             resumed: false,
         })),
+        // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
+        // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
+        // pushes (guarded by `readOnly` in both the clone and push phases below).
+        ...references.map((reference) => ({
+            repo: reference.repo,
+            dirName: claimDir(reference.repo),
+            dir: '',
+            cloneBranch: reference.repo.baseBranch,
+            workBranch: reference.repo.baseBranch,
+            ghToken: reference.ghToken ?? job.ghToken,
+            primary: false,
+            readOnly: true,
+            baseSha: '',
+            resumed: false,
+        })),
     ];
     return withWorkspace('multi', async (root) => {
         // Clone phase: every repo into its sibling dir under the workspace root. Resume an
@@ -366,6 +382,23 @@ export async function runMultiRepoCoding(job, opts = {}) {
         for (const leg of legs) {
             const dir = join(root, leg.dirName);
             await mkdir(dir, { recursive: true });
+            // A read-only reference leg: clone its base branch for the agent to read, and stop there —
+            // no work branch, no resume, no base-refresh. It is skipped in the push phase, so it can
+            // never be written to. (Kept in the loop so it lands in the same workspace root as siblings.)
+            if (leg.readOnly) {
+                logger.info('multi-repo: cloning read-only reference', {
+                    repo: leg.dirName,
+                    cloneBranch: leg.cloneBranch,
+                });
+                await cloneRepo({
+                    repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+                    ghToken: leg.ghToken,
+                    dir,
+                    signal,
+                });
+                leg.dir = dir;
+                continue;
+            }
             leg.resumed = await remoteBranchExists(leg.repo.cloneUrl, leg.workBranch, leg.ghToken, signal);
             if (leg.resumed) {
                 logger.info('multi-repo: resuming existing branch', {
@@ -439,6 +472,10 @@ export async function runMultiRepoCoding(job, opts = {}) {
         let primaryPrUrl;
         const peerPullRequests = [];
         for (const leg of legs) {
+            // A read-only reference leg is never committed or pushed — the third layer of the read-only
+            // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
+            if (leg.readOnly)
+                continue;
             await commitTrackedEdits(leg.dir, job.commitMessage ?? leg.pr?.title ?? 'Agent changes', signal);
             const advanced = await branchHasCommitsSince(leg.dir, leg.baseSha, signal);
             let hasWork = advanced || leg.resumed;

package/dist/job.js

@@ -150,6 +150,30 @@ function parsePeerRepos(value) {
         return spec;
     });
 }
+/**
+ * Parse the optional read-only reference-repo list (document-authoring runs). Each entry carries
+ * a full {@link RepoSpec} (validated + sanitised like the primary) and an optional per-repo token.
+ * Any branch/PR fields on the wire are IGNORED — a reference repo is never pushed, so the parsed
+ * shape has none to carry. A malformed list throws; an absent one yields `[]`.
+ */
+function parseReferenceRepos(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error("Invalid job: 'referenceRepos' must be an array");
+    return value.map((entry, i) => {
+        if (typeof entry !== 'object' || entry === null) {
+            throw new Error(`Invalid job: 'referenceRepos[${i}]' must be an object`);
+        }
+        const e = entry;
+        const spec = {
+            repo: parseRepoSpec((e.repo ?? {})),
+        };
+        if (typeof e.ghToken === 'string' && e.ghToken)
+            spec.ghToken = e.ghToken;
+        return spec;
+    });
+}
 /** Parse the optional `repo.provider` discriminator (defaults to undefined ⇒ host inference). */
 function parseVcsProvider(value) {
     if (value === undefined || value === null)
@@ -479,6 +503,7 @@ export function parseAgentJob(input) {
         : undefined;
     const infra = parseAgentInfraSpec(o.infra);
     const peerRepos = parsePeerRepos(o.peerRepos);
+    const referenceRepos = parseReferenceRepos(o.referenceRepos);
     const bootstrap = parseAgentBootstrapSpec(o.bootstrap);
     const contextFiles = parseContextFiles(o.contextFiles);
     const packageRegistries = parsePackageRegistries(o.packageRegistries);
@@ -510,6 +535,7 @@ export function parseAgentJob(input) {
             : {}),
         ...(pr ? { pr } : {}),
         ...(peerRepos.length ? { peerRepos } : {}),
+        ...(referenceRepos.length ? { referenceRepos } : {}),
         ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
         ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
         ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
@@ -528,5 +554,11 @@ export function parseAgentJob(input) {
     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.34.10",
+  "version": "1.35.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",
@@ -21,13 +21,13 @@
     "access": "public"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.6",
+    "@hono/node-server": "^2.0.8",
     "@types/node": "^26.0.0",
     "hono": "^4.12.27",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
-    "@cat-factory/spend": "0.10.95",
-    "@cat-factory/server": "0.82.0"
+    "@cat-factory/spend": "0.10.104",
+    "@cat-factory/server": "0.88.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent.ts

@@ -739,13 +739,14 @@ async function runCodingMode(job: AgentJob, opts: RunOptions): Promise<AgentResu
   // clone full, merge the base in to surface the conflicts, then complete the merge
   // commit + push (no PR). Keyed off job DATA (`mergeBase`), not the agent kind.
   if (job.mergeBase) return runConflictResolution(job, opts)
-  // Multi-repo coding (service-connections phase 3): clone every connected peer repo as a
-  // sibling, run the agent once across all of them, and open one PR per changed repo. Keyed
-  // off job DATA (`peerRepos`), not the agent kind — the implementer sets it when the task
-  // has involved services in distinct repos.
-  const result = job.peerRepos?.length
-    ? await runMultiRepoCoding(job, opts)
-    : await runSingleRepoCoding(job, opts)
+  // Multi-repo coding: clone every additional repo as a sibling and run the agent once across
+  // all of them. Keyed off job DATA, not the agent kind — set for the implementer's writable
+  // peer repos (service-connections phase 3, `peerRepos`) OR the doc-writer's READ-ONLY
+  // reference repos (`referenceRepos`, cloned but never pushed).
+  const result =
+    job.peerRepos?.length || job.referenceRepos?.length
+      ? await runMultiRepoCoding(job, opts)
+      : await runSingleRepoCoding(job, opts)
 
   // Structured coding kind (repro-test): fold the final reply's JSON onto `custom` so the
   // backend post-completion resolver records the outcome. Skipped on a failed run (its `error`

package/src/coding-agent.ts

@@ -1,6 +1,13 @@
 import { mkdir } from 'node:fs/promises'
 import { join } from 'node:path'
-import type { AgentJob, AgentResult, HarnessAuthFields, PeerRepoSpec, RepoSpec } from './job.js'
+import type {
+  AgentJob,
+  AgentResult,
+  HarnessAuthFields,
+  PeerRepoSpec,
+  ReferenceRepoSpec,
+  RepoSpec,
+} from './job.js'
 import {
   branchAheadOfBase,
   branchHasCommitsSince,
@@ -435,6 +442,12 @@ interface RepoLeg {
   pr?: { title: string; body: string }
   frameId?: string
   primary: boolean
+  /**
+   * A READ-ONLY reference checkout (doc-writer's `referenceRepos`): cloned at its base branch for
+   * the agent to read, but NEVER given a work branch, committed, or pushed. Skipped entirely in the
+   * push phase, so it is structurally impossible for the run to write to it. Absent ⇒ a writable leg.
+   */
+  readOnly?: boolean
   /** The branch tip before the run — work iff the branch advances past it. */
   baseSha: string
   /** Whether an existing remote work branch was resumed (already carries prior work). */
@@ -461,6 +474,7 @@ export async function runMultiRepoCoding(
   const { signal } = opts
   const logger = (opts.log ?? log).child({ kind: 'multi-repo', jobId: job.jobId })
   const peers: PeerRepoSpec[] = job.peerRepos ?? []
+  const references: ReferenceRepoSpec[] = job.referenceRepos ?? []
   const primaryWorkBranch = job.pushBranch ?? job.newBranch ?? job.branch
 
   // Assign the sibling directory per repo via the shared deterministic allocator (`owner__name`,
@@ -496,6 +510,23 @@ export async function runMultiRepoCoding(
         resumed: false,
       }),
     ),
+    // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
+    // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
+    // pushes (guarded by `readOnly` in both the clone and push phases below).
+    ...references.map(
+      (reference): RepoLeg => ({
+        repo: reference.repo,
+        dirName: claimDir(reference.repo),
+        dir: '',
+        cloneBranch: reference.repo.baseBranch,
+        workBranch: reference.repo.baseBranch,
+        ghToken: reference.ghToken ?? job.ghToken,
+        primary: false,
+        readOnly: true,
+        baseSha: '',
+        resumed: false,
+      }),
+    ),
   ]
 
   return withWorkspace('multi', async (root) => {
@@ -505,6 +536,23 @@ export async function runMultiRepoCoding(
     for (const leg of legs) {
       const dir = join(root, leg.dirName)
       await mkdir(dir, { recursive: true })
+      // A read-only reference leg: clone its base branch for the agent to read, and stop there —
+      // no work branch, no resume, no base-refresh. It is skipped in the push phase, so it can
+      // never be written to. (Kept in the loop so it lands in the same workspace root as siblings.)
+      if (leg.readOnly) {
+        logger.info('multi-repo: cloning read-only reference', {
+          repo: leg.dirName,
+          cloneBranch: leg.cloneBranch,
+        })
+        await cloneRepo({
+          repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+          ghToken: leg.ghToken,
+          dir,
+          signal,
+        })
+        leg.dir = dir
+        continue
+      }
       leg.resumed = await remoteBranchExists(leg.repo.cloneUrl, leg.workBranch, leg.ghToken, signal)
       if (leg.resumed) {
         logger.info('multi-repo: resuming existing branch', {
@@ -587,6 +635,9 @@ export async function runMultiRepoCoding(
     let primaryPrUrl: string | undefined
     const peerPullRequests: NonNullable<AgentResult['peerPullRequests']> = []
     for (const leg of legs) {
+      // A read-only reference leg is never committed or pushed — the third layer of the read-only
+      // guarantee (the spec carries no branch/PR, and the clone phase gave it no work branch).
+      if (leg.readOnly) continue
       await commitTrackedEdits(
         leg.dir,
         job.commitMessage ?? leg.pr?.title ?? 'Agent changes',

package/src/job.ts

@@ -84,6 +84,21 @@ export interface PeerRepoSpec {
   ghToken?: string
 }
 
+/**
+ * A repository checked out READ-ONLY as a sibling alongside the primary during a
+ * document-authoring coding run — the doc-writer reads it (to reuse existing solutions as a
+ * reference) but the harness never creates a branch, commits, or opens a PR for it. Deliberately
+ * carries NO branch/PR fields (unlike {@link PeerRepoSpec}), so it is structurally impossible to
+ * push: the read-only guarantee is enforced by the shape itself, by cloning at the repo's own
+ * base branch with no work branch, and by skipping the leg in the push phase. The clone URL is
+ * host-allowlisted exactly like the primary `repo.cloneUrl`.
+ */
+export interface ReferenceRepoSpec {
+  repo: RepoSpec
+  /** Per-repo GitHub token; defaults to the job's `ghToken` (one installation per workspace today). */
+  ghToken?: string
+}
+
 function str(value: unknown, path: string): string {
   if (typeof value !== 'string' || value.length === 0) {
     throw new Error(`Invalid job: '${path}' must be a non-empty string`)
@@ -234,6 +249,28 @@ function parsePeerRepos(value: unknown): PeerRepoSpec[] {
   })
 }
 
+/**
+ * Parse the optional read-only reference-repo list (document-authoring runs). Each entry carries
+ * a full {@link RepoSpec} (validated + sanitised like the primary) and an optional per-repo token.
+ * Any branch/PR fields on the wire are IGNORED — a reference repo is never pushed, so the parsed
+ * shape has none to carry. A malformed list throws; an absent one yields `[]`.
+ */
+function parseReferenceRepos(value: unknown): ReferenceRepoSpec[] {
+  if (value === undefined || value === null) return []
+  if (!Array.isArray(value)) throw new Error("Invalid job: 'referenceRepos' must be an array")
+  return value.map((entry, i) => {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new Error(`Invalid job: 'referenceRepos[${i}]' must be an object`)
+    }
+    const e = entry as Record<string, unknown>
+    const spec: ReferenceRepoSpec = {
+      repo: parseRepoSpec((e.repo ?? {}) as Record<string, unknown>),
+    }
+    if (typeof e.ghToken === 'string' && e.ghToken) spec.ghToken = e.ghToken
+    return spec
+  })
+}
+
 /** 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
@@ -591,6 +628,14 @@ export interface AgentJob extends HarnessAuthFields {
    * peer repo it actually changed — in addition to the primary. Absent ⇒ single-repo run.
    */
   peerRepos?: PeerRepoSpec[]
+  /**
+   * Coding mode (doc-writer): repositories to clone READ-ONLY as SIBLINGS for the agent to
+   * reference while it drafts the document. When present the agent works at the workspace ROOT
+   * (all checkouts are siblings under it); the harness clones each reference at its own base
+   * branch and NEVER creates a branch, commits, or opens a PR for it. Only the primary is
+   * pushed. Absent ⇒ single-repo run. Independent of {@link peerRepos} (those are writable).
+   */
+  referenceRepos?: ReferenceRepoSpec[]
   /**
    * 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
@@ -926,6 +971,7 @@ export function parseAgentJob(input: unknown): AgentJob {
       : undefined
   const infra = parseAgentInfraSpec(o.infra)
   const peerRepos = parsePeerRepos(o.peerRepos)
+  const referenceRepos = parseReferenceRepos(o.referenceRepos)
   const bootstrap = parseAgentBootstrapSpec(o.bootstrap)
   const contextFiles = parseContextFiles(o.contextFiles)
   const packageRegistries = parsePackageRegistries(o.packageRegistries)
@@ -957,6 +1003,7 @@ export function parseAgentJob(input: unknown): AgentJob {
       : {}),
     ...(pr ? { pr } : {}),
     ...(peerRepos.length ? { peerRepos } : {}),
+    ...(referenceRepos.length ? { referenceRepos } : {}),
     ...(o.noChangesIsError === false ? { noChangesIsError: false } : {}),
     ...(o.persistentCheckout === true ? { persistentCheckout: true } : {}),
     ...(o.streamFollowUps === true ? { streamFollowUps: true } : {}),
@@ -973,5 +1020,11 @@ export function parseAgentJob(input: unknown): AgentJob {
   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
 }