@cat-factory/executor-harness 1.108.0 → 1.110.0

package/dist/agent.js

@@ -10,7 +10,8 @@ import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenc
 import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
 import { makeDirClaimer } from './checkout-dir.js';
-import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js';
+import { noChangesReason, runCodingAgent } from './coding-agent.js';
+import { runMultiRepoCoding } from './multi-repo-coding.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';

package/dist/coding-agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJob, AgentResult, HarnessAuthFields, ImageManifestSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { HarnessAuthFields, ImageManifestSpec, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
 import type { HarnessCallMetric } from './pi.js';
 import type { PiRunStats } from './pi-reduction.js';
 import { type EffortReport } from './effort.js';
@@ -148,7 +148,7 @@ export interface CodingAgentOutcome {
     effortReport?: EffortReport;
     /**
      * The agent-authored PR description, lifted from its sentinel file (absent when it wrote none).
-     * The PR-opening caller folds it over the dispatch-time title/body via {@link applyPrDescription};
+     * The PR-opening caller folds it over the dispatch-time title/body via `applyPrDescription`;
      * absent means the fallback text, unchanged.
      */
     prDescription?: AgentPrDescription;
@@ -234,20 +234,6 @@ export declare function runRalphValidation(repoDir: string, cwd: string, validat
     iteration?: number;
     headSha?: string;
 }>;
-/**
- * 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 declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;
 /**
  * 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.

package/dist/coding-agent.js

@@ -1,13 +1,11 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runCapturedCommand } from './captured-command.js';
-import { makeDirClaimer } from './checkout-dir.js';
 import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
-import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
 import { EFFORT_REPORT_FILE } from './effort.js';
-import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.js';
-import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, withWorkspace, } from './pi-workspace.js';
+import { PR_DESCRIPTION_FILE, readPrDescription, } from './pr-description.js';
+import { acquireRepoCheckout, agentNeverActed, agentOutputTail, runAgentInWorkspace, } from './pi-workspace.js';
 import { log } from './logger.js';
 import { runValidationLoop, } from './validation-checks.js';
 import { runReproductionLoop, } from './reproduction-proof.js';
@@ -681,374 +679,6 @@ export async function runRalphValidation(repoDir, cwd, validation, logger, opts)
         ...(headSha ? { headSha } : {}),
     };
 }
-/**
- * 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 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__digest`, 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,
-        })),
-        // 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 (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);
-        // DEPENDENCY PREPOPULATION for the PRIMARY leg, exactly as the read-only multi-repo fan-out
-        // does it. The install is declared on ONE service frame (the primary repo's), so it runs in
-        // that leg's checkout and is never fanned out across peers, whose own frames declare configs
-        // this dispatch never resolved — running a `pnpm install` inside a Go checkout is not a
-        // degraded outcome, it is a wrong one. A cross-repo implementer needs its dependencies for
-        // the same reason a cross-repo investigator does; the note names the sibling directory
-        // because the agent itself stands at the workspace root.
-        //
-        // At the leg's checkout ROOT, not a `serviceDirectory` subtree: this layout applies no
-        // service-directory scoping anywhere (the agent runs at the root and the prompt explains the
-        // sibling checkouts), and a root install is the one that resolves a monorepo workspace whole.
-        const primaryLeg = legs.find((leg) => leg.primary);
-        const dependencyNote = primaryLeg
-            ? await prepopulateDependencies({
-                spec: job.dependencyInstall,
-                installDir: primaryLeg.dir,
-                repoDir: primaryLeg.dir,
-                agentDir: root,
-                logger,
-                opts,
-            })
-            : undefined;
-        // THE REPOS' OWN PR TEMPLATES: one per leg that will actually open a pull request, each named
-        // by its sibling directory so the agent knows which checkout's briefing takes which shape —
-        // the repos in a workspace need not share a template, or ship one at all. A read-only
-        // reference leg is excluded by construction: it carries no `pr`, so nothing publishes for it.
-        const prTemplate = await resolvePrTemplateNote({
-            targets: legs
-                .filter((leg) => leg.pr)
-                .map((leg) => ({
-                repoDir: leg.dir,
-                repoLabel: leg.dirName,
-                ...(leg.repo.provider ? { provider: leg.repo.provider } : {}),
-            })),
-            logger,
-        });
-        // 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, effortReport } = await runAgentInWorkspace({
-            dir: root,
-            systemPrompt: job.systemPrompt,
-            userPrompt: withDependencyNote(withPrTemplateNote(job.userPrompt, prTemplate.note), dependencyNote),
-            model: job.model,
-            harness: job.harness,
-            subscriptionToken: job.subscriptionToken,
-            subscriptionBaseUrl: job.subscriptionBaseUrl,
-            ambientAuth: job.ambientAuth,
-            proxyBaseUrl: job.proxyBaseUrl,
-            proxyPhasePath: job.proxyPhasePath,
-            sessionToken: job.sessionToken,
-            webToolsGuidance: job.webToolsGuidance,
-            webSearchProxy: job.webSearch,
-            guardLimits: job.guardLimits,
-            ...(job.contextFiles ? { contextFiles: job.contextFiles } : {}),
-            // Skills + tool servers apply to a multi-repo run exactly as to a single-repo one: they
-            // are properties of the AGENT KIND, not of the checkout layout.
-            ...(job.skills?.length ? { skills: job.skills } : {}),
-            ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
-            ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
-            ...(job.designImages ? { designImages: job.designImages } : {}),
-            multiRepo: true,
-        }, opts);
-        // 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, root, prTemplate);
-        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 } : {}),
-                    ...(effortReport ? { effortReport } : {}),
-                };
-            }
-            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 } : {}),
-                ...(effortReport ? { effortReport } : {}),
-            };
-        }
-        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 } : {}),
-            ...(effortReport ? { effortReport } : {}),
-        };
-    });
-}
-/**
- * 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;
-        // Exclude the agent-authored PR-description sentinel locally (as the single-repo path does)
-        // so the agent's own `git add` can never stage the briefing into the PR it describes.
-        await excludeFromGit(dir, PR_DESCRIPTION_FILE, signal);
-        // 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, 
-/** The workspace root the agent ran in — the fallback probe for the primary's briefing. */
-root, 
-/** Which legs' briefings are filled templates — see the `titleFromHeading` read below. */
-prTemplate) {
-    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;
-        // Lift (and remove) the agent-authored PR description for THIS repo's PR before anything
-        // else touches the checkout — each sibling checkout carries its own briefing for its own PR.
-        // The agent's cwd here is the WORKSPACE ROOT rather than any one checkout, so an agent that
-        // read the prompt loosely may well have written a single briefing there instead. Fall back
-        // to it for the PRIMARY leg only: at the root there is nothing to say which repo it
-        // describes, and the primary is the one the run is actually about.
-        //
-        // Per-leg `titleFromHeading`: only a leg whose OWN repo ships a template has repo-authored
-        // headings in its sentinel, and the legs of a workspace need not agree about that — so this
-        // is keyed on the leg, never on whether the run found any template at all.
-        const readOptions = { titleFromHeading: !prTemplate.templated.has(leg.dir) };
-        const agentPrDescription = (await readPrDescription(leg.dir, readOptions)) ??
-            (leg.primary ? await readPrDescription(root, readOptions) : undefined);
-        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: applyPrDescription(leg.pr, agentPrDescription),
-                // See the single-repo call site: refresh a resumed leg's already-open PR, but only
-                // when the text is the agent's own briefing rather than the dispatch-time fallback.
-                ...(agentPrDescription ? { refreshExisting: true } : {}),
-                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.

package/dist/job.d.ts

@@ -86,8 +86,13 @@ export interface PrSpec {
  */
 export interface PeerRepoSpec {
     repo: RepoSpec;
-    /** The involved service frame this repo resolved from, echoed back on the peer PR. */
-    frameId?: string;
+    /**
+     * The involved service frames this repo resolved from, echoed back on the peer PR verbatim.
+     * More than one when the peer is a monorepo hosting several of the run's involved services:
+     * they share this ONE checkout, its work branch and its pull request. Opaque to the harness,
+     * which decides no frame attribution of its own.
+     */
+    frameIds?: string[];
     /**
      * The work branch to create off the peer's base and push (the shared `cat-factory/<block>`).
      * Present for a COING fan-out (coder / ci-fixer). Absent for a READ-ONLY explore fan-out
@@ -593,10 +598,14 @@ export interface AgentResult {
      * repo the run actually changed (service-connections phase 3). Beside the own-service
      * `prUrl`/`branch`; the backend lifts these onto the block's `peerPullRequests`. Absent for
      * a single-repo run.
+     *
+     * `frameIds` is the dispatch's own attribution echoed back untouched (see
+     * {@link PeerRepoSpec.frameIds}): one entry per repo, carrying every involved frame that
+     * repo hosts.
      */
     peerPullRequests?: {
         repo: string;
-        frameId?: string;
+        frameIds?: string[];
         prUrl: string;
         branch: string;
     }[];

package/dist/job.js

@@ -169,8 +169,11 @@ function parsePeerRepos(value) {
         if (e.cloneBranch !== undefined) {
             spec.cloneBranch = str(e.cloneBranch, `peerRepos[${i}].cloneBranch`);
         }
-        if (typeof e.frameId === 'string' && e.frameId)
-            spec.frameId = e.frameId;
+        if (Array.isArray(e.frameIds)) {
+            const frameIds = e.frameIds.filter((f) => typeof f === 'string' && !!f);
+            if (frameIds.length)
+                spec.frameIds = frameIds;
+        }
         if (typeof e.ghToken === 'string' && e.ghToken)
             spec.ghToken = e.ghToken;
         if (typeof e.pr === 'object' && e.pr !== null) {

package/dist/multi-repo-coding.d.ts

@@ -0,0 +1,16 @@
+import type { AgentJob, AgentResult } from './job.js';
+import type { RunOptions } from './runner.js';
+/**
+ * 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 declare function runMultiRepoCoding(job: AgentJob, opts?: RunOptions): Promise<AgentResult>;