@cat-factory/executor-harness 1.50.2 → 1.50.6

package/dist/coding-agent.js

@@ -43,100 +43,9 @@ export async function runCodingAgent(spec, opts = {}) {
     // (which differs from the cloned branch the registry bound).
     const logger = (opts.log ?? log).child({ kind: spec.kind, branch: spec.pushBranch });
     return acquireRepoCheckout({ persistent: spec.persistentCheckout === true, prefix: spec.kind, repo: spec.repo }, async (dir) => {
-        // Resume an evicted earlier run when its work branch already exists on the
-        // remote: clone THAT branch and continue on its commits, rather than branching
-        // off base and redoing everything. Only the impl path (which creates a fresh
-        // `newBranch`) can resume; the ci-fix/conflict paths already clone the PR branch.
-        //
-        // Resume safety relies on two invariants the dispatcher (worker) upholds, since
-        // the harness can't see run/PR state from inside the container:
-        //  - At most ONE active run per block at a time. The work branch is deterministic
-        //    per block (`cat-factory/<blockId>`), so two concurrent runs would target the
-        //    same branch; their pushes race. A plain (non-forced) push fails safely on a
-        //    non-fast-forward rather than clobbering the other run's commits, so the worst
-        //    case is one run failing — never lost work — but the dispatcher should not
-        //    knowingly run two at once.
-        //  - Re-dispatch only NON-terminal runs (failed / evicted / stale-running), whose
-        //    branch is by definition unmerged. Resuming a branch whose PR already merged
-        //    could re-introduce merged work; that is avoided two ways: the platform deletes
-        //    the work branch when its PR merges (GitHubPullRequestMerger), so a re-run finds
-        //    no branch and starts fresh, and a `done` block is never re-dispatched anyway.
-        const resumed = spec.newBranch != null &&
-            (await remoteBranchExists(spec.repo.cloneUrl, spec.newBranch, spec.ghToken, signal));
-        opts.onPhase?.('clone');
-        if (spec.persistentCheckout) {
-            // Reused checkout: clean-sweep + fetch + switch branch in place. A resumed branch
-            // (or a run without `newBranch`, working directly on `cloneBranch`) already exists
-            // on the remote, so check it out directly; otherwise (re)create `newBranch` off the
-            // base tip — the same resume-vs-fresh decision the clone paths below make.
-            const targetBranch = spec.newBranch ?? spec.cloneBranch;
-            logger.info('coding-agent: preparing reused checkout', { branch: targetBranch, resumed });
-            await prepareExistingCheckout({
-                dir,
-                repo: spec.repo,
-                ghToken: spec.ghToken,
-                branch: targetBranch,
-                baseBranch: spec.cloneBranch,
-                existing: resumed || spec.newBranch == null,
-                signal,
-            });
-        }
-        else if (resumed) {
-            logger.info('coding-agent: resuming existing branch', { branch: spec.newBranch });
-            await cloneExistingBranch({
-                cloneUrl: spec.repo.cloneUrl,
-                branch: spec.newBranch,
-                ghToken: spec.ghToken,
-                dir,
-                signal,
-            });
-        }
-        else {
-            logger.info('coding-agent: cloning', { cloneBranch: spec.cloneBranch });
-            await cloneRepo({
-                repo: { ...spec.repo, baseBranch: spec.cloneBranch },
-                ghToken: spec.ghToken,
-                dir,
-                signal,
-            });
-            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
-        // refresh below so that refresh's merge commit counts as advancement and is pushed.
-        const baseSha = await headCommit(dir, signal);
-        // A resumed branch was cut from an OLDER base; merge the latest base in when the
-        // two merge cleanly, so the agent works against current base and the PR stays
-        // current. On a conflict this is a no-op (the run continues on the stale base — the
-        // merge gate handles a conflicting PR downstream, as before), so it never blocks a
-        // resume. Best-effort: any error is treated as "continue without refreshing".
-        if (resumed) {
-            const refreshed = await refreshFromBaseIfClean(dir, spec.cloneBranch, spec.ghToken, signal).catch(() => false);
-            if (!refreshed) {
-                logger.info('coding-agent: resume base refresh skipped (conflict or error)', {
-                    base: spec.cloneBranch,
-                });
-            }
-        }
+        // Clone (or resume) the checkout, fetch any read-only reference branches, and capture the
+        // pre-run branch tip. See {@link prepareCodingCheckout} for the resume-safety invariants.
+        const { resumed, baseSha } = await prepareCodingCheckout(dir, spec, logger, opts);
         // Serialize all pushes to the work branch through a single in-flight promise.
         // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
         // run `git push` to the same branch concurrently: overlapping pushes race on the
@@ -215,7 +124,7 @@ export async function runCodingAgent(spec, opts = {}) {
         try {
             opts.onPhase?.('agent');
             logger.info('coding-agent: running agent', { serviceDirectory });
-            const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace({
+            const agentRun = await runAgentInWorkspace({
                 dir: workDir,
                 systemPrompt: spec.systemPrompt,
                 userPrompt: spec.userPrompt,
@@ -232,84 +141,21 @@ export async function runCodingAgent(spec, opts = {}) {
                 guardLimits: spec.guardLimits,
                 ...(spec.skill ? { skill: spec.skill } : {}),
             }, opts);
-            // Stop tailing the follow-up sentinel and flush any items written after the last
-            // tick, so a fast final burst still reaches the job view before the run is recorded.
-            if (followUpTick)
-                clearInterval(followUpTick);
-            if (followUpTailer)
-                await followUpTailer.poll().catch(() => { });
-            // Safety net for forgotten edits: commit changes to TRACKED files only (never
-            // untracked scratch files/artifacts — the agent owns committing new files).
-            await commitTrackedEdits(dir, spec.commitMessage, signal);
-            // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
-            // push, so the two never run a concurrent `git push` to the same branch (the
-            // final push below is then a fresh attempt whose failure is the real signal).
-            clearInterval(checkpoint);
-            const inflight = inFlightPush();
-            if (inflight)
-                await inflight.catch(() => { });
-            // Surface (don't fail on) untracked, non-ignored files the agent left behind:
-            // `commitTrackedEdits` only captures edits to ALREADY tracked files, so a NEW
-            // file the agent created but forgot to commit is silently dropped. Logging it
-            // makes that loss observable when a PR turns out to be missing a file.
-            const leftover = await listUntrackedFiles(dir, signal);
-            if (leftover.length > 0) {
-                logger.warn('coding-agent: uncommitted new files left behind (not pushed)', {
-                    count: leftover.length,
-                    files: leftover.slice(0, 20),
-                });
-            }
-            // A fresh run produced work iff the branch advanced past its pre-run tip. A RESUMED
-            // run already carries prior work — UNLESS that branch turns out to have nothing ahead
-            // of the PR base (e.g. its earlier PR was merged with a merge commit, leaving the
-            // branch reachable from base and its best-effort delete skipped). Opening a PR for such
-            // a branch fails with GitHub's opaque 422 "No commits between ...", so a CONFIRMED-empty
-            // resumed branch is a no-op, not work. `undefined` (couldn't determine) keeps the prior
-            // resume-is-work behaviour; the PR-open path then no-ops on the 422 as a backstop.
-            const advancedThisPass = await branchHasCommitsSince(dir, baseSha, signal);
-            let hasWork = advancedThisPass || resumed;
-            if (resumed && !advancedThisPass) {
-                const ahead = await branchAheadOfBase(dir, spec.repo.baseBranch, spec.ghToken, signal);
-                if (ahead === false) {
-                    logger.info('coding-agent: resumed branch has no commits ahead of base — no-op', {
-                        base: spec.repo.baseBranch,
-                    });
-                    hasWork = false;
-                }
-            }
-            if (!hasWork) {
-                logger.info('coding-agent: no changes produced', { ...stats });
-                outcome = {
-                    pushed: false,
-                    resumed,
-                    summary,
-                    stats,
-                    ...(stderrTail ? { stderrTail } : {}),
-                    ...(usage ? { usage } : {}),
-                    ...(callMetrics ? { callMetrics } : {}),
-                };
-            }
-            else {
-                opts.onPhase?.('push');
-                logger.info('coding-agent: pushing', { resumed, ...stats });
-                await pushWorkOnce();
-                outcome = {
-                    pushed: true,
-                    resumed,
-                    summary,
-                    stats,
-                    ...(stderrTail ? { stderrTail } : {}),
-                    ...(usage ? { usage } : {}),
-                    ...(callMetrics ? { callMetrics } : {}),
-                };
-            }
-            // Ralph loop: run the programmatic completion command against the pushed/committed
-            // state and attach its verdict (exit code = the loop's authoritative done signal).
-            // Runs regardless of whether this pass pushed — a no-op iteration must still be able
-            // to report that the criterion is (already) met. The harness runs it, never the model.
-            if (spec.validation) {
-                outcome.validation = await runRalphValidation(workDir, spec.validation, logger, opts);
-            }
+            outcome = await finalizeCodingRun({
+                dir,
+                spec,
+                logger,
+                opts,
+                baseSha,
+                resumed,
+                workDir,
+                checkpoint,
+                followUpTick,
+                followUpTailer,
+                pushWorkOnce,
+                inFlightPush,
+                agentRun,
+            });
         }
         finally {
             // Safety net for the throw path (the happy path already cleared these above).
@@ -320,6 +166,200 @@ export async function runCodingAgent(spec, opts = {}) {
         return outcome;
     });
 }
+/**
+ * Clone (or RESUME an existing branch) into `dir`, fetch any read-only reference branches, and
+ * capture the pre-run branch tip. Extracted from {@link runCodingAgent} so its body stays small;
+ * returns `{ resumed, baseSha }` for the run to judge no-op vs work against.
+ *
+ * Resume an evicted earlier run when its work branch already exists on the remote: clone THAT
+ * branch and continue on its commits, rather than branching off base and redoing everything. Only
+ * the impl path (which creates a fresh `newBranch`) can resume; the ci-fix/conflict paths already
+ * clone the PR branch.
+ *
+ * Resume safety relies on two invariants the dispatcher (worker) upholds, since the harness can't
+ * see run/PR state from inside the container:
+ *  - At most ONE active run per block at a time. The work branch is deterministic per block
+ *    (`cat-factory/<blockId>`), so two concurrent runs would target the same branch; their pushes
+ *    race. A plain (non-forced) push fails safely on a non-fast-forward rather than clobbering the
+ *    other run's commits, so the worst case is one run failing — never lost work — but the
+ *    dispatcher should not knowingly run two at once.
+ *  - Re-dispatch only NON-terminal runs (failed / evicted / stale-running), whose branch is by
+ *    definition unmerged. Resuming a branch whose PR already merged could re-introduce merged work;
+ *    that is avoided two ways: the platform deletes the work branch when its PR merges
+ *    (GitHubPullRequestMerger), so a re-run finds no branch and starts fresh, and a `done` block is
+ *    never re-dispatched anyway.
+ */
+async function prepareCodingCheckout(dir, spec, logger, opts) {
+    const { signal } = opts;
+    const resumed = spec.newBranch != null &&
+        (await remoteBranchExists(spec.repo.cloneUrl, spec.newBranch, spec.ghToken, signal));
+    opts.onPhase?.('clone');
+    if (spec.persistentCheckout) {
+        // Reused checkout: clean-sweep + fetch + switch branch in place. A resumed branch
+        // (or a run without `newBranch`, working directly on `cloneBranch`) already exists
+        // on the remote, so check it out directly; otherwise (re)create `newBranch` off the
+        // base tip — the same resume-vs-fresh decision the clone paths below make.
+        const targetBranch = spec.newBranch ?? spec.cloneBranch;
+        logger.info('coding-agent: preparing reused checkout', { branch: targetBranch, resumed });
+        await prepareExistingCheckout({
+            dir,
+            repo: spec.repo,
+            ghToken: spec.ghToken,
+            branch: targetBranch,
+            baseBranch: spec.cloneBranch,
+            existing: resumed || spec.newBranch == null,
+            signal,
+        });
+    }
+    else if (resumed) {
+        logger.info('coding-agent: resuming existing branch', { branch: spec.newBranch });
+        await cloneExistingBranch({
+            cloneUrl: spec.repo.cloneUrl,
+            branch: spec.newBranch,
+            ghToken: spec.ghToken,
+            dir,
+            signal,
+        });
+    }
+    else {
+        logger.info('coding-agent: cloning', { cloneBranch: spec.cloneBranch });
+        await cloneRepo({
+            repo: { ...spec.repo, baseBranch: spec.cloneBranch },
+            ghToken: spec.ghToken,
+            dir,
+            signal,
+        });
+        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
+    // refresh below so that refresh's merge commit counts as advancement and is pushed.
+    const baseSha = await headCommit(dir, signal);
+    // A resumed branch was cut from an OLDER base; merge the latest base in when the
+    // two merge cleanly, so the agent works against current base and the PR stays
+    // current. On a conflict this is a no-op (the run continues on the stale base — the
+    // merge gate handles a conflicting PR downstream, as before), so it never blocks a
+    // resume. Best-effort: any error is treated as "continue without refreshing".
+    if (resumed) {
+        const refreshed = await refreshFromBaseIfClean(dir, spec.cloneBranch, spec.ghToken, signal).catch(() => false);
+        if (!refreshed) {
+            logger.info('coding-agent: resume base refresh skipped (conflict or error)', {
+                base: spec.cloneBranch,
+            });
+        }
+    }
+    return { resumed, baseSha };
+}
+/**
+ * Finalize a coding run after the agent has finished: flush the follow-up tailer, safety-net commit
+ * forgotten tracked edits, settle any in-flight checkpoint push, decide whether the branch carries
+ * work, push it iff so, and (for a Ralph run) attach the validation verdict. Extracted from
+ * {@link runCodingAgent} so its body stays small; returns the built {@link CodingAgentOutcome}.
+ */
+async function finalizeCodingRun(args) {
+    const { dir, spec, logger, opts, baseSha, resumed, workDir, checkpoint, followUpTick, followUpTailer, pushWorkOnce, inFlightPush, agentRun, } = args;
+    const { signal } = opts;
+    const { summary, stats, stderrTail, usage, callMetrics } = agentRun;
+    let outcome;
+    // Stop tailing the follow-up sentinel and flush any items written after the last
+    // tick, so a fast final burst still reaches the job view before the run is recorded.
+    if (followUpTick)
+        clearInterval(followUpTick);
+    if (followUpTailer)
+        await followUpTailer.poll().catch(() => { });
+    // Safety net for forgotten edits: commit changes to TRACKED files only (never
+    // untracked scratch files/artifacts — the agent owns committing new files).
+    await commitTrackedEdits(dir, spec.commitMessage, signal);
+    // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
+    // push, so the two never run a concurrent `git push` to the same branch (the
+    // final push below is then a fresh attempt whose failure is the real signal).
+    clearInterval(checkpoint);
+    const inflight = inFlightPush();
+    if (inflight)
+        await inflight.catch(() => { });
+    // Surface (don't fail on) untracked, non-ignored files the agent left behind:
+    // `commitTrackedEdits` only captures edits to ALREADY tracked files, so a NEW
+    // file the agent created but forgot to commit is silently dropped. Logging it
+    // makes that loss observable when a PR turns out to be missing a file.
+    const leftover = await listUntrackedFiles(dir, signal);
+    if (leftover.length > 0) {
+        logger.warn('coding-agent: uncommitted new files left behind (not pushed)', {
+            count: leftover.length,
+            files: leftover.slice(0, 20),
+        });
+    }
+    // A fresh run produced work iff the branch advanced past its pre-run tip. A RESUMED
+    // run already carries prior work — UNLESS that branch turns out to have nothing ahead
+    // of the PR base (e.g. its earlier PR was merged with a merge commit, leaving the
+    // branch reachable from base and its best-effort delete skipped). Opening a PR for such
+    // a branch fails with GitHub's opaque 422 "No commits between ...", so a CONFIRMED-empty
+    // resumed branch is a no-op, not work. `undefined` (couldn't determine) keeps the prior
+    // resume-is-work behaviour; the PR-open path then no-ops on the 422 as a backstop.
+    const advancedThisPass = await branchHasCommitsSince(dir, baseSha, signal);
+    let hasWork = advancedThisPass || resumed;
+    if (resumed && !advancedThisPass) {
+        const ahead = await branchAheadOfBase(dir, spec.repo.baseBranch, spec.ghToken, signal);
+        if (ahead === false) {
+            logger.info('coding-agent: resumed branch has no commits ahead of base — no-op', {
+                base: spec.repo.baseBranch,
+            });
+            hasWork = false;
+        }
+    }
+    if (!hasWork) {
+        logger.info('coding-agent: no changes produced', { ...stats });
+        outcome = {
+            pushed: false,
+            resumed,
+            summary,
+            stats,
+            ...(stderrTail ? { stderrTail } : {}),
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+        };
+    }
+    else {
+        opts.onPhase?.('push');
+        logger.info('coding-agent: pushing', { resumed, ...stats });
+        await pushWorkOnce();
+        outcome = {
+            pushed: true,
+            resumed,
+            summary,
+            stats,
+            ...(stderrTail ? { stderrTail } : {}),
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+        };
+    }
+    // Ralph loop: run the programmatic completion command against the pushed/committed
+    // state and attach its verdict (exit code = the loop's authoritative done signal).
+    // Runs regardless of whether this pass pushed — a no-op iteration must still be able
+    // to report that the criterion is (already) met. The harness runs it, never the model.
+    if (spec.validation) {
+        outcome.validation = await runRalphValidation(workDir, spec.validation, logger, opts);
+    }
+    return outcome;
+}
 /**
  * The Ralph-loop validation watchdog: the longest a completion command may run before it is
  * killed and treated as a failure (a hung `pnpm test` must never block the loop forever).
@@ -428,7 +468,6 @@ export function makeDirClaimer() {
  * git helpers, so the per-repo clone/commit/push/PR mechanics match the single-repo path exactly.
  */
 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 ?? [];
@@ -481,92 +520,9 @@ export async function runMultiRepoCoding(job, opts = {}) {
         })),
     ];
     return withWorkspace('multi', async (root) => {
-        // Clone phase: every repo into its sibling dir under the workspace root. Resume an
-        // existing remote work branch (an evicted retry) rather than branching off base again.
-        opts.onPhase?.('clone');
-        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', {
-                    repo: leg.dirName,
-                    branch: leg.workBranch,
-                });
-                await cloneExistingBranch({
-                    cloneUrl: leg.repo.cloneUrl,
-                    branch: leg.workBranch,
-                    ghToken: leg.ghToken,
-                    dir,
-                    signal,
-                });
-            }
-            else {
-                logger.info('multi-repo: cloning', { repo: leg.dirName, cloneBranch: leg.cloneBranch });
-                await cloneRepo({
-                    repo: { ...leg.repo, baseBranch: leg.cloneBranch },
-                    ghToken: leg.ghToken,
-                    dir,
-                    signal,
-                });
-                await createBranch(dir, leg.workBranch, signal);
-            }
-            leg.dir = dir;
-            // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
-            // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
-            // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
-            // carries prior work.
-            leg.baseSha = await headCommit(dir, signal);
-            // A resumed branch was cut from an OLDER base; merge the latest base in when the two merge
-            // cleanly so the agent works against current base and the peer/own PRs stay current. On a
-            // conflict this is a best-effort no-op (the merge gate handles a conflicting PR downstream),
-            // mirroring the single-repo {@link runCodingAgent} resume refresh.
-            if (leg.resumed) {
-                const refreshed = await refreshFromBaseIfClean(dir, leg.cloneBranch, leg.ghToken, signal).catch(() => false);
-                if (!refreshed) {
-                    logger.info('multi-repo: resume base refresh skipped (conflict or error)', {
-                        repo: leg.dirName,
-                        base: leg.cloneBranch,
-                    });
-                }
-            }
-        }
-        // 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,
-                });
-            }
-        }
+        // Clone (or resume) every sibling checkout under the workspace root and fetch the primary's
+        // reference branches. Mutates each leg's `dir`/`resumed`/`baseSha` in place.
+        await prepareMultiRepoCheckouts(root, legs, job, logger, opts);
         // 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.
@@ -589,67 +545,8 @@ export async function runMultiRepoCoding(job, opts = {}) {
             ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
             multiRepo: true,
         }, opts);
-        // Push phase: commit forgotten tracked edits, then push + open a PR for each repo the run
-        // actually changed. A repo the agent left untouched is skipped (no branch, no PR).
-        opts.onPhase?.('push');
-        let primaryPushed = false;
-        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;
-            if (leg.resumed && !advanced) {
-                const ahead = await branchAheadOfBase(leg.dir, leg.repo.baseBranch, leg.ghToken, signal);
-                if (ahead === false)
-                    hasWork = false;
-            }
-            const leftover = await listUntrackedFiles(leg.dir, signal);
-            if (leftover.length > 0) {
-                logger.warn('multi-repo: uncommitted new files left behind (not pushed)', {
-                    repo: leg.dirName,
-                    count: leftover.length,
-                    files: leftover.slice(0, 20),
-                });
-            }
-            if (!hasWork) {
-                logger.info('multi-repo: no changes for repo', { repo: leg.dirName });
-                continue;
-            }
-            await pushBranch(leg.dir, leg.workBranch, leg.ghToken, signal);
-            let prUrl = null;
-            if (leg.pr) {
-                prUrl = await openPullRequest({
-                    owner: leg.repo.owner,
-                    name: leg.repo.name,
-                    ghToken: leg.ghToken,
-                    head: leg.workBranch,
-                    base: leg.repo.baseBranch,
-                    pr: leg.pr,
-                    apiBase: job.githubApiBase,
-                    cloneUrl: leg.repo.cloneUrl,
-                    ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
-                    signal,
-                });
-            }
-            if (leg.primary) {
-                primaryPushed = true;
-                if (prUrl)
-                    primaryPrUrl = prUrl;
-            }
-            else if (prUrl) {
-                peerPullRequests.push({
-                    repo: `${leg.repo.owner}/${leg.repo.name}`,
-                    ...(leg.frameId ? { frameId: leg.frameId } : {}),
-                    prUrl,
-                    branch: leg.workBranch,
-                });
-            }
-        }
+        // Commit forgotten tracked edits, then push + open a PR for each repo the run actually changed.
+        const { primaryPushed, primaryPrUrl, peerPullRequests } = await pushMultiRepoLegs(legs, job, logger, opts);
         const anyWork = primaryPushed || peerPullRequests.length > 0;
         if (!anyWork) {
             // Nothing changed in ANY repo. For the implementer this is a failure (as in the
@@ -693,6 +590,168 @@ export async function runMultiRepoCoding(job, opts = {}) {
         };
     });
 }
+/**
+ * Clone phase for {@link runMultiRepoCoding}: every repo into its sibling dir under the workspace
+ * root. Resume an existing remote work branch (an evicted retry) rather than branching off base
+ * again, then fetch the primary repo's reference branches. Mutates each leg's `dir`/`resumed`/
+ * `baseSha` in place. Extracted so the multi-repo body stays small.
+ */
+async function prepareMultiRepoCheckouts(root, legs, job, logger, opts) {
+    const { signal } = opts;
+    opts.onPhase?.('clone');
+    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', {
+                repo: leg.dirName,
+                branch: leg.workBranch,
+            });
+            await cloneExistingBranch({
+                cloneUrl: leg.repo.cloneUrl,
+                branch: leg.workBranch,
+                ghToken: leg.ghToken,
+                dir,
+                signal,
+            });
+        }
+        else {
+            logger.info('multi-repo: cloning', { repo: leg.dirName, cloneBranch: leg.cloneBranch });
+            await cloneRepo({
+                repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+                ghToken: leg.ghToken,
+                dir,
+                signal,
+            });
+            await createBranch(dir, leg.workBranch, signal);
+        }
+        leg.dir = dir;
+        // The branch tip before the agent runs. Captured BEFORE the resume base refresh below so
+        // that refresh's merge commit counts as advancement and is pushed (as in the single-repo
+        // path). A fresh leg produced work iff its branch advances past this; a resumed leg already
+        // carries prior work.
+        leg.baseSha = await headCommit(dir, signal);
+        // A resumed branch was cut from an OLDER base; merge the latest base in when the two merge
+        // cleanly so the agent works against current base and the peer/own PRs stay current. On a
+        // conflict this is a best-effort no-op (the merge gate handles a conflicting PR downstream),
+        // mirroring the single-repo {@link runCodingAgent} resume refresh.
+        if (leg.resumed) {
+            const refreshed = await refreshFromBaseIfClean(dir, leg.cloneBranch, leg.ghToken, signal).catch(() => false);
+            if (!refreshed) {
+                logger.info('multi-repo: resume base refresh skipped (conflict or error)', {
+                    repo: leg.dirName,
+                    base: leg.cloneBranch,
+                });
+            }
+        }
+    }
+    // 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,
+            });
+        }
+    }
+}
+/**
+ * Push phase for {@link runMultiRepoCoding}: commit forgotten tracked edits, then push + open a PR
+ * for each repo the run actually changed (a repo the agent left untouched is skipped — no branch,
+ * no PR; a read-only reference leg is never committed or pushed). Extracted so the multi-repo body
+ * stays small; returns the primary's push/PR state plus the peer PRs.
+ */
+async function pushMultiRepoLegs(legs, job, logger, opts) {
+    const { signal } = opts;
+    opts.onPhase?.('push');
+    let primaryPushed = false;
+    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;
+        if (leg.resumed && !advanced) {
+            const ahead = await branchAheadOfBase(leg.dir, leg.repo.baseBranch, leg.ghToken, signal);
+            if (ahead === false)
+                hasWork = false;
+        }
+        const leftover = await listUntrackedFiles(leg.dir, signal);
+        if (leftover.length > 0) {
+            logger.warn('multi-repo: uncommitted new files left behind (not pushed)', {
+                repo: leg.dirName,
+                count: leftover.length,
+                files: leftover.slice(0, 20),
+            });
+        }
+        if (!hasWork) {
+            logger.info('multi-repo: no changes for repo', { repo: leg.dirName });
+            continue;
+        }
+        await pushBranch(leg.dir, leg.workBranch, leg.ghToken, signal);
+        let prUrl = null;
+        if (leg.pr) {
+            prUrl = await openPullRequest({
+                owner: leg.repo.owner,
+                name: leg.repo.name,
+                ghToken: leg.ghToken,
+                head: leg.workBranch,
+                base: leg.repo.baseBranch,
+                pr: leg.pr,
+                apiBase: job.githubApiBase,
+                cloneUrl: leg.repo.cloneUrl,
+                ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
+                signal,
+            });
+        }
+        if (leg.primary) {
+            primaryPushed = true;
+            if (prUrl)
+                primaryPrUrl = prUrl;
+        }
+        else if (prUrl) {
+            peerPullRequests.push({
+                repo: `${leg.repo.owner}/${leg.repo.name}`,
+                ...(leg.frameId ? { frameId: leg.frameId } : {}),
+                prUrl,
+                branch: leg.workBranch,
+            });
+        }
+    }
+    return { primaryPushed, primaryPrUrl, peerPullRequests };
+}
 /**
  * The "no changes" reason both coding agents report: a caller-supplied lead phrase
  * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.