@cat-factory/executor-harness 1.34.4 → 1.34.10

package/dist/agent.js

@@ -7,7 +7,7 @@ import { standUpFrontend, tearDownFrontend } from './frontend-infra.js';
 import { configurePackageRegistries } from './package-registries.js';
 import { captureRedactedOutput, redactSecrets } from './redact.js';
 import { cloneRepo, commitAll, conflictDiff, hasAgentChanges, headCommit, mergeBranch, openPullRequest, prepareExistingCheckout, pushBranch, reinitAndPush, unmergedPaths, } from './git.js';
-import { noChangesReason, runCodingAgent } from './coding-agent.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';
 import { log } from './logger.js';
@@ -152,6 +152,39 @@ async function tearDownInfra(dir, infra) {
         // The container is ephemeral and torn down with the run anyway — ignore.
     }
 }
+/**
+ * Parse an agent's final reply into the structured JSON `custom`, shared by the explore and
+ * coding structured-output paths. With repair enabled (default) a malformed reply gets ONE
+ * structured repair call before giving up; with `output.repair === false` it parses directly.
+ * Returns the parsed value (or null when unusable) plus the repair diagnostics. Never throws —
+ * a parse failure is a null value, and each caller decides whether that is fatal (explore: yes;
+ * coding: no, the pushed commits are the deliverable).
+ */
+async function resolveReplyCustom(job, summary, signal) {
+    if (job.output?.repair === false) {
+        try {
+            return { value: extractJsonObject(summary) };
+        }
+        catch {
+            return { value: null };
+        }
+    }
+    const resolved = await resolveStructuredOutput({
+        label: 'agent',
+        shapeHint: job.output?.shapeHint ?? 'Expected a single JSON object.',
+        parse: (text) => extractJsonObject(text),
+    }, summary, {
+        harness: job.harness,
+        subscriptionToken: job.subscriptionToken,
+        subscriptionBaseUrl: job.subscriptionBaseUrl,
+        proxyBaseUrl: job.proxyBaseUrl,
+        sessionToken: job.sessionToken,
+        model: job.model,
+        jobId: job.jobId,
+        signal,
+    });
+    return { value: resolved.value, diagnostics: resolved.diagnostics };
+}
 /** Extract the first JSON object from an agent's final message (tolerating fences/prose). */
 function extractJsonObject(text) {
     const trimmed = text.trim();
@@ -298,6 +331,15 @@ async function runPreviewMode(job, opts) {
  */
 async function runExploreMode(job, opts) {
     const logger = opts.log ?? log;
+    // Multi-repo read-only exploration (service-connections phase 3): when the job carries peer
+    // repos, clone them all as siblings and run at the workspace root. Keyed off job DATA
+    // (`peerRepos`), not the agent kind — the backend sets it for the bug-investigator when the
+    // task has involved services in distinct repos. `runMultiRepoExplore` uses its own ephemeral
+    // `withWorkspace`, so a `persistentCheckout` flag (which a warm-pool dispatch injects on EVERY
+    // job) is harmlessly ignored — it must NOT suppress the fan-out, or a pooled bug-investigator
+    // would silently drop its peer repos and only ever see the primary one.
+    if (job.peerRepos?.length)
+        return runMultiRepoExplore(job, opts);
     return acquireRepoCheckout({ persistent: job.persistentCheckout === true, prefix: 'agent-explore', repo: job.repo }, async (dir) => {
         opts.onPhase?.('clone');
         // Monorepo: run with cwd set to the service subtree (created if missing), mirroring the
@@ -367,130 +409,193 @@ async function runExploreMode(job, opts) {
                 contextFiles: job.contextFiles,
                 guardLimits: job.guardLimits,
             }, opts);
-            if (!summary.trim()) {
-                return {
-                    summary,
-                    stats,
-                    error: noOutputReason(stats, stderrTail),
-                    failureCause: 'no-usable-output',
-                    ...(usage ? { usage } : {}),
-                    ...(callMetrics ? { callMetrics } : {}),
-                    ...infraSetupFields,
-                };
-            }
-            // Opt-in (document producers): a final answer cut off at the output ceiling — or empty —
-            // must FAIL LOUDLY here, BEFORE the structured repair below could launder a truncated
-            // reply into a half-baked doc the backend then shards/commits + hands onward. Mirrors the
-            // bespoke `/spec` handler's `unusableFinalAnswerCause` gate (which drove the old loop).
-            if (job.output?.kind === 'structured' && job.output.failOnUnusableFinal) {
-                const unusable = unusableFinalAnswerCause(runDiag);
-                if (unusable) {
-                    return {
-                        summary,
-                        stats,
-                        error: `the agent did not return a usable result: ${unusable}.${agentOutputTail(stderrTail, summary)}`,
-                        failureCause: 'no-usable-output',
-                        ...(usage ? { usage } : {}),
-                        ...(callMetrics ? { callMetrics } : {}),
-                        ...infraSetupFields,
-                    };
-                }
-            }
-            // Prose: the summary IS the deliverable.
-            if (job.output?.kind !== 'structured') {
-                logger.info('agent(explore): done (prose)', { ...stats });
-                return {
-                    summary,
-                    stats,
-                    ...(usage ? { usage } : {}),
-                    ...(callMetrics ? { callMetrics } : {}),
-                    ...infraSetupFields,
-                };
-            }
-            // Structured: parse the agent's JSON. With repair enabled (default) a malformed
-            // reply gets ONE structured repair call before giving up; with `repair:false` we
-            // parse directly (no repair channel). The backend coerces/validates + renders from
-            // the returned object in a post-op.
-            let custom = null;
-            let diagnostics;
-            if (job.output.repair === false) {
-                try {
-                    custom = extractJsonObject(summary);
-                }
-                catch {
-                    custom = null;
-                }
-            }
-            else {
-                const resolved = await resolveStructuredOutput({
-                    label: 'agent',
-                    shapeHint: job.output.shapeHint ?? 'Expected a single JSON object.',
-                    parse: (text) => extractJsonObject(text),
-                }, summary, {
-                    harness: job.harness,
-                    subscriptionToken: job.subscriptionToken,
-                    subscriptionBaseUrl: job.subscriptionBaseUrl,
-                    proxyBaseUrl: job.proxyBaseUrl,
-                    sessionToken: job.sessionToken,
-                    model: job.model,
-                    jobId: job.jobId,
-                    signal: opts.signal,
-                });
-                custom = resolved.value;
-                diagnostics = resolved.diagnostics;
-            }
-            if (custom === undefined || custom === null) {
-                return {
-                    summary,
-                    stats,
-                    error: noStructuredReason(stats, stderrTail, diagnostics),
-                    failureCause: 'no-usable-output',
-                    ...(usage ? { usage } : {}),
-                    ...(callMetrics ? { callMetrics } : {}),
-                    ...infraSetupFields,
-                };
-            }
-            // Stamp the run's actual environment authoritatively onto the structured result when
-            // infra was managed (the tester): which env the suite ran in is decided by the job's
-            // infra spec, NOT the model, so the backend can echo it back to the UI deterministically
-            // even when the model omits it from its JSON (or a structured repair drops it). A
-            // frontend run tests the app against its live ephemeral backend(s), so it reports
-            // `ephemeral` (the TestReport env vocabulary has no separate frontend value).
-            const reportedEnvironment = infra
-                ? infra.kind === 'frontend'
-                    ? 'ephemeral'
-                    : infra.environment
-                : undefined;
-            if (reportedEnvironment && typeof custom === 'object') {
-                ;
-                custom.environment = reportedEnvironment;
-            }
-            logger.info('agent(explore): done (structured)', { ...stats });
+            return await finalizeExploreResult(job, { summary, stats, stderrTail, usage, callMetrics, runDiag }, { infra, infraSetupFields, logger, signal: opts.signal });
+        }
+        finally {
+            if (managed)
+                await managed.cleanup();
+        }
+    });
+}
+/**
+ * Turn an explore agent's raw run into an {@link AgentResult}: guard an empty/truncated reply,
+ * then either return the prose summary or parse (+ optionally repair) the structured JSON as
+ * `custom` — the backend renders any artifact files from it in a post-op. Extracted so the
+ * single-repo {@link runExploreMode} and the read-only {@link runMultiRepoExplore} share ONE
+ * result contract (the multi-repo path passes no infra, so the tester-only env stamping no-ops).
+ */
+async function finalizeExploreResult(job, run, ctx) {
+    const { summary, stats, stderrTail, usage, callMetrics, runDiag } = run;
+    const { infra, infraSetupFields, logger, signal } = ctx;
+    if (!summary.trim()) {
+        return {
+            summary,
+            stats,
+            error: noOutputReason(stats, stderrTail),
+            failureCause: 'no-usable-output',
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+            ...infraSetupFields,
+        };
+    }
+    // Opt-in (document producers): a final answer cut off at the output ceiling — or empty —
+    // must FAIL LOUDLY here, BEFORE the structured repair below could launder a truncated
+    // reply into a half-baked doc the backend then shards/commits + hands onward. Mirrors the
+    // bespoke `/spec` handler's `unusableFinalAnswerCause` gate (which drove the old loop).
+    if (job.output?.kind === 'structured' && job.output.failOnUnusableFinal) {
+        const unusable = unusableFinalAnswerCause(runDiag);
+        if (unusable) {
             return {
                 summary,
-                custom,
                 stats,
+                error: `the agent did not return a usable result: ${unusable}.${agentOutputTail(stderrTail, summary)}`,
+                failureCause: 'no-usable-output',
                 ...(usage ? { usage } : {}),
                 ...(callMetrics ? { callMetrics } : {}),
                 ...infraSetupFields,
             };
         }
-        finally {
-            if (managed)
-                await managed.cleanup();
-        }
+    }
+    // Prose: the summary IS the deliverable.
+    if (job.output?.kind !== 'structured') {
+        logger.info('agent(explore): done (prose)', { ...stats });
+        return {
+            summary,
+            stats,
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+            ...infraSetupFields,
+        };
+    }
+    // Structured: parse the agent's JSON via the shared resolver. With repair enabled (default)
+    // a malformed reply gets ONE structured repair call before giving up; with `repair:false` it
+    // parses directly (no repair channel). The backend coerces/validates + renders from the
+    // returned object in a post-op. Unlike the coding path, an unparseable explore reply IS a
+    // failure — the report/JSON is the whole deliverable.
+    const { value: custom, diagnostics } = await resolveReplyCustom(job, summary, signal);
+    if (custom === undefined || custom === null) {
+        return {
+            summary,
+            stats,
+            error: noStructuredReason(stats, stderrTail, diagnostics),
+            failureCause: 'no-usable-output',
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+            ...infraSetupFields,
+        };
+    }
+    // Stamp the run's actual environment authoritatively onto the structured result when
+    // infra was managed (the tester): which env the suite ran in is decided by the job's
+    // infra spec, NOT the model, so the backend can echo it back to the UI deterministically
+    // even when the model omits it from its JSON (or a structured repair drops it). A
+    // frontend run tests the app against its live ephemeral backend(s), so it reports
+    // `ephemeral` (the TestReport env vocabulary has no separate frontend value).
+    const reportedEnvironment = infra
+        ? infra.kind === 'frontend'
+            ? 'ephemeral'
+            : infra.environment
+        : undefined;
+    if (reportedEnvironment && typeof custom === 'object') {
+        ;
+        custom.environment = reportedEnvironment;
+    }
+    logger.info('agent(explore): done (structured)', { ...stats });
+    return {
+        summary,
+        custom,
+        stats,
+        ...(usage ? { usage } : {}),
+        ...(callMetrics ? { callMetrics } : {}),
+        ...infraSetupFields,
+    };
+}
+/**
+ * Read-only MULTI-REPO exploration (service-connections phase 3, read-only): clone the primary
+ * repo PLUS every connected peer repo as SIBLING checkouts under one workspace root, run the
+ * agent ONCE with its cwd at the root (so it can read across every repo the bug touches), and
+ * return its prose/structured result — making NO edits, NO commits and opening NO PR. The
+ * counterpart of {@link runMultiRepoCoding} for the `bug-investigator`, but strictly read-only:
+ * peers carry no `newBranch`/`pr`, nothing is pushed, and the peers exist only to be read. The
+ * multi-repo layout is explained to the agent by the backend-composed system-prompt section
+ * (which repo/subdir each service lives in) + the harness's own AGENTS.md multi-repo note.
+ */
+async function runMultiRepoExplore(job, opts) {
+    const logger = (opts.log ?? log).child({ kind: 'multi-repo-explore', jobId: job.jobId });
+    const peers = job.peerRepos ?? [];
+    // Unique sibling directory per repo (owner-prefixed on a name collision), so two repos
+    // named the same never clobber each other — shared claim scheme with the coding fan-out.
+    const claimDir = makeDirClaimer();
+    const legs = [
+        { repo: job.repo, cloneBranch: job.branch, ghToken: job.ghToken },
+        ...peers.map((peer) => ({
+            repo: peer.repo,
+            cloneBranch: peer.repo.baseBranch,
+            ghToken: peer.ghToken ?? job.ghToken,
+        })),
+    ].map((leg) => ({ ...leg, dirName: claimDir(leg.repo) }));
+    return withWorkspace('explore-multi', async (root) => {
+        // Clone phase: every repo (read-only) into its sibling dir under the workspace root. No
+        // work branch, no resume — the investigator only reads — so the legs are independent and
+        // clone in parallel (wall-clock is the slowest single clone, not the sum).
+        opts.onPhase?.('clone');
+        await Promise.all(legs.map(async (leg) => {
+            const dir = join(root, leg.dirName);
+            await mkdir(dir, { recursive: true });
+            logger.info('multi-repo-explore: cloning', {
+                repo: leg.dirName,
+                cloneBranch: leg.cloneBranch,
+            });
+            await cloneRepo({
+                repo: { ...leg.repo, baseBranch: leg.cloneBranch },
+                ghToken: leg.ghToken,
+                dir,
+                signal: opts.signal,
+            });
+        }));
+        opts.onPhase?.('agent');
+        logger.info('multi-repo-explore: running agent', { repos: legs.map((l) => l.dirName) });
+        const run = await runAgentInWorkspace({
+            dir: root,
+            systemPrompt: job.systemPrompt,
+            userPrompt: job.userPrompt,
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            ambientAuth: job.ambientAuth,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            // Read-only: no edits expected, so the no-progress guard's no-edit bound must not fire.
+            expectsEdits: false,
+            webToolsGuidance: job.webToolsGuidance,
+            webSearchProxy: job.webSearch,
+            ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
+            guardLimits: job.guardLimits,
+            multiRepo: true,
+        }, opts);
+        return finalizeExploreResult(job, {
+            summary: run.summary,
+            stats: run.stats,
+            stderrTail: run.stderrTail,
+            usage: run.usage,
+            callMetrics: run.callMetrics,
+            runDiag: run.diagnostics,
+        }, { infraSetupFields: {}, logger, signal: opts.signal });
     });
 }
 /**
- * Edit-and-push coding: clone `branch` (or resume `newBranch`), run the agent, commit +
- * push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
- * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal
- * no-op for the in-place fixers.
+ * Edit-and-push coding, dispatching on job DATA: repo-bootstrap (force-push a fresh history to a
+ * separate target repo), conflict-resolution (merge the base in, resolve, push back), multi-repo
+ * fan-out (sibling checkouts + one PR per changed repo), else the ordinary single-repo flow.
+ * After the flow, a STRUCTURED coding kind (e.g. `repro-test`, whose deliverable is BOTH a pushed
+ * commit AND a JSON outcome) parses its final reply into `custom` — best-effort, so an unparseable
+ * outcome degrades to no `custom` (the backend resolver then defaults) rather than failing the
+ * run, whose real deliverable is the pushed commits.
  */
 async function runCodingMode(job, opts) {
     // Repo bootstrap is a coding run that force-pushes a fresh history to a SEPARATE target
     // repo (clone + adapt a reference, or scaffold from scratch). Keyed off job DATA
-    // (`bootstrap`), not the agent kind.
+    // (`bootstrap`), not the agent kind. Bootstrap/conflict never carry a structured `output`.
     if (job.bootstrap)
         return runBootstrap(job, opts);
     // Conflict resolution is a coding run with a different pre/post around the agent:
@@ -498,6 +603,31 @@ 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
+        ? 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`
+    // is the signal) and when there is no reply to parse. Best-effort: a null parse leaves
+    // `custom` unset (the run still succeeds on its commits).
+    if (job.output?.kind === 'structured' && !result.error && result.summary) {
+        const { value } = await resolveReplyCustom(job, result.summary, opts.signal);
+        if (value !== null && value !== undefined)
+            result.custom = value;
+    }
+    return result;
+}
+/**
+ * The ordinary single-repo coding flow: clone `branch` (or resume `newBranch`), run the agent,
+ * commit + push to `pushBranch`, and open `pr` when one is set and the run produced changes. A
+ * no-op is a failure for the implementer (`noChangesIsError` default) and a non-fatal no-op for
+ * the in-place fixers (and for a seed-only kind like `repro-test`).
+ */
+async function runSingleRepoCoding(job, opts) {
     const pushBranch = job.pushBranch ?? job.newBranch ?? job.branch;
     const { summary, stats, stderrTail, pushed, usage, callMetrics } = await runCodingAgent({
         kind: 'agent',

package/dist/coding-agent.js

@@ -1,8 +1,8 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, headCommit, listUntrackedFiles, openPullRequest, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
-import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, } from './pi-workspace.js';
+import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 /**
  * How often the harness checkpoints the agent's work mid-run by pushing the branch.
@@ -292,6 +292,246 @@ export async function runCodingAgent(spec, opts = {}) {
         return outcome;
     });
 }
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export function safeDirSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
+}
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
+ * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
+ * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
+ * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
+ * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
+ * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
+ * independently, so a divergent rule would point the agent at a directory that does not exist.
+ */
+export function makeDirClaimer() {
+    return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`;
+}
+/**
+ * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
+ * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at
+ * that root (so it makes the cross-service change coherently across all of them), then commit +
+ * push each repo that actually changed and open one PR per dirty repo. The task's own-service PR
+ * is reported as `prUrl`/`branch`; the peer PRs as `peerPullRequests`.
+ *
+ * Deliberately simpler than the single-repo {@link runCodingAgent} for the first cut: NO mid-run
+ * checkpoint pushes (an evicted multi-repo run re-clones on retry — the deterministic work branch
+ * still lets it resume any commits it managed to push at the end), NO warm-pool persistent
+ * checkout (always ephemeral), and NO follow-up sentinel streaming. It reuses the SAME dir-scoped
+ * 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 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.
+    const claimDir = makeDirClaimer();
+    const legs = [
+        {
+            repo: job.repo,
+            dirName: claimDir(job.repo),
+            dir: '',
+            cloneBranch: job.branch,
+            workBranch: primaryWorkBranch,
+            ghToken: job.ghToken,
+            ...(job.pr ? { pr: job.pr } : {}),
+            primary: true,
+            baseSha: '',
+            resumed: false,
+        },
+        ...peers.map((peer) => ({
+            repo: peer.repo,
+            dirName: claimDir(peer.repo),
+            dir: '',
+            cloneBranch: peer.repo.baseBranch,
+            // Coding peers always carry `newBranch` (the backend sets the shared work branch);
+            // fall back to the primary's for the type (read-only peers never reach this path).
+            workBranch: peer.newBranch ?? primaryWorkBranch,
+            ghToken: peer.ghToken ?? job.ghToken,
+            ...(peer.pr ? { pr: peer.pr } : {}),
+            ...(peer.frameId ? { frameId: peer.frameId } : {}),
+            primary: false,
+            baseSha: '',
+            resumed: false,
+        })),
+    ];
+    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 });
+            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,
+                    });
+                }
+            }
+        }
+        // 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.
+        opts.onPhase?.('agent');
+        logger.info('multi-repo: running agent', { repos: legs.map((l) => l.dirName) });
+        const { summary, stats, stderrTail, usage, callMetrics } = await runAgentInWorkspace({
+            dir: root,
+            systemPrompt: job.systemPrompt,
+            userPrompt: job.userPrompt,
+            model: job.model,
+            harness: job.harness,
+            subscriptionToken: job.subscriptionToken,
+            subscriptionBaseUrl: job.subscriptionBaseUrl,
+            ambientAuth: job.ambientAuth,
+            proxyBaseUrl: job.proxyBaseUrl,
+            sessionToken: job.sessionToken,
+            webToolsGuidance: job.webToolsGuidance,
+            webSearchProxy: job.webSearch,
+            guardLimits: job.guardLimits,
+            ...(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) {
+            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,
+                });
+            }
+        }
+        const anyWork = primaryPushed || peerPullRequests.length > 0;
+        if (!anyWork) {
+            // Nothing changed in ANY repo. For the implementer this is a failure (as in the
+            // single-repo path); a caller that tolerates a no-op (never the implementer today)
+            // gets a clean non-event.
+            if (job.noChangesIsError === false) {
+                return {
+                    pushed: false,
+                    branch: primaryWorkBranch,
+                    summary,
+                    stats,
+                    ...(usage ? { usage } : {}),
+                    ...(callMetrics ? { callMetrics } : {}),
+                };
+            }
+            return {
+                pushed: false,
+                branch: primaryWorkBranch,
+                summary,
+                stats,
+                error: noChangesReason('the agent produced no file changes in any repository', stats, stderrTail),
+                failureCause: 'no-changes',
+                ...(usage ? { usage } : {}),
+                ...(callMetrics ? { callMetrics } : {}),
+            };
+        }
+        logger.info('multi-repo: complete', {
+            primaryPushed,
+            primaryPrUrl: primaryPrUrl ?? null,
+            peers: peerPullRequests.length,
+        });
+        return {
+            pushed: primaryPushed,
+            ...(primaryPrUrl ? { prUrl: primaryPrUrl } : {}),
+            branch: primaryWorkBranch,
+            ...(peerPullRequests.length ? { peerPullRequests } : {}),
+            summary,
+            stats,
+            ...(usage ? { usage } : {}),
+            ...(callMetrics ? { callMetrics } : {}),
+        };
+    });
+}
 /**
  * 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.