@cat-factory/executor-harness 1.106.0 → 1.110.0

package/README.md

@@ -128,6 +128,14 @@ from the backend over the SAME container session token the run already holds for
 this needs no extra credential. The FILE NAMES are the backend's, never derived here: the name is
 how the agent learns the view name, and the platform pairs its capture against that name later.
 
+A job for a kind that BUILDS a screen carries the same wire shape under `designImages`, downloaded
+into `.cat-context/design-renders/` instead. Same transfer, opposite instruction: those are the
+design to build, not the views to capture, which is why they get their own directory (a tester
+reading the builder's handful would take it for the complete list of views to capture). The prompt
+naming them is composed by the BACKEND, since only it knows whether this harness/model pair can be
+shown an image at all and which views the run was not sent, so the harness speaks up only to
+CORRECT that list when a picture did not land.
+
 `omitted` carries the views the backend's cap dropped. They are stated to the agent beside the
 transfers that failed, since from where it stands both are a view to capture with nothing to compare
 against. This parser keeps a higher backstop of its own against a body claiming more files than any
@@ -255,6 +263,8 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/validation-checks.ts` | Pre-PR validation: runs the job's check commands in the checkout (bounded, secret-scrubbed capture, per-command watchdog) and drives the retry-until-green loop that gates the PR. Generic: keyed off the job body, never the agent kind. |
 | `src/reproduction-proof.ts` | Bugfix reproduction proof: runs the job's declared reproduction command against two symmetric fresh worktrees (the pre-fix tree and the final tree) and computes red-then-green from the exit codes, with a repair loop that never fails the run. Generic: keyed off the job body, never the agent kind. |
 | `src/agent-capabilities.ts` | The agent CAPABILITIES a job body carries: the run's `skills` (a `SKILL.md` payload + resources) and its `mcpServers` (tool servers): with their defensive parsing and the per-CLI config writers (`--mcp-config` JSON for claude-code, `[mcp_servers.*]` TOML for Codex). Backend-authored data the harness only MATERIALISES: adding a skill or a tool server is a backend registration, never a harness change. |
+| `src/context-images.ts` | The TRANSFER half of both image manifests: downloads a manifest's images into a subdirectory of `.cat-context/` on the run's own container session token, bounded per image and per pass, and reports what did not land. Best-effort, time-bounded and IDEMPOTENT over the checkout, so a repair round re-costs a stat rather than a transfer. Shared, because the transfer is identical for both; what differs is what the files MEAN, which is each caller's own module below. |
+| `src/design-images.ts` | The task's DESIGN PICTURES: downloads the manifest a building job body carries into `.cat-context/design-renders/`, for an agent CLI that can read an image into its turn. Says NOTHING on success (the backend's prompt already names every file and its view) and speaks only to correct that list when a picture is not here, because an agent told to open a file that is absent goes looking for the design rather than for the transfer. |
 | `src/reference-screenshots.ts` | The task's REFERENCE DESIGN images: downloads the manifest a capturing job body carries into `.cat-context/reference-screenshots/` (on the run's own container session token) and composes the prompt block naming each file's view. Best-effort, time-bounded and IDEMPOTENT over the checkout, so a repair round re-costs a stat rather than a transfer. A reference that is not on disk is NAMED to the agent, whether a transfer failed or the backend's cap dropped the view, because on disk an absent file and a screen the design does not have are the same thing. Backend-authored throughout, including the file names. |
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |

package/dist/agent-capabilities.js

@@ -241,7 +241,7 @@ export function parseSkillSpecs(value) {
  * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
  * the whole value of the list is that it is the image's own honest answer.
  */
-export const HARNESS_BODY_CAPABILITIES = ['mcpServers', 'skills'];
+export const HARNESS_BODY_CAPABILITIES = ['mcpServers', 'skills', 'designImages'];
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *

package/dist/agent-shared.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJob, AgentResult, McpServerSpec, ReferenceScreenshotsSpec, SkillSpec } from './job.js';
+import type { AgentJob, AgentResult, McpServerSpec, ImageManifestSpec, SkillSpec } from './job.js';
 import type { EffortReport } from './effort.js';
 /**
  * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
@@ -16,5 +16,6 @@ export declare function mergeEffort(result: AgentResult, effortReport: EffortRep
 export declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
     mcpServers?: McpServerSpec[];
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    designImages?: ImageManifestSpec;
 };

package/dist/agent-shared.js

@@ -21,5 +21,6 @@ export function agentCapabilities(job) {
         ...(job.skills?.length ? { skills: job.skills } : {}),
         ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
         ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
+        ...(job.designImages ? { designImages: job.designImages } : {}),
     };
 }

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, ReferenceScreenshotsSpec, 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';
@@ -119,7 +119,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
      * UI-facing kind may well be a coding one, and nothing here switches on which built-in it is.
      * Absent ⇒ none (the normal case).
      */
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    /**
+     * The PICTURES of the task's designs, downloaded into `.cat-context/design-renders/` before the
+     * agent's first turn. Carried here for the same reason the capture set is: what earns a run its
+     * pictures is the KIND's declared trait plus a harness that can read an image, and a coding kind
+     * is the commonest holder of both. Absent ⇒ none (the normal case).
+     */
+    designImages?: ImageManifestSpec;
 }
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
 export interface CodingAgentOutcome {
@@ -141,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;
@@ -227,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';
@@ -212,6 +210,7 @@ export async function runCodingAgent(spec, opts = {}) {
             ...(spec.referenceScreenshots
                 ? { referenceScreenshots: spec.referenceScreenshots }
                 : {}),
+            ...(spec.designImages ? { designImages: spec.designImages } : {}),
         }, opts);
         let outcome;
         try {
@@ -680,373 +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 } : {}),
-            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/context-images.d.ts

@@ -0,0 +1,38 @@
+import type { ImageManifestSpec } from './job.js';
+/** What a transfer pass has on disk, and what it does not. */
+export interface ContextImageOutcome {
+    written: {
+        fileName: string;
+        view: string;
+    }[];
+    /**
+     * One entry per image that is NOT on disk, with the cause stated in `reason`. Covers both halves
+     * of that absence, because the agent's position is the same either way (this view exists and
+     * there is no picture of it here): a transfer that failed, and a view the backend's own cap
+     * dropped before this container was ever asked to fetch it.
+     */
+    missing: {
+        view: string;
+        reason: string;
+    }[];
+    /** Where the written files live, relative to the checkout root. */
+    dir: string;
+}
+/**
+ * Download a manifest's images into `<checkout>/.cat-context/<subdir>/` and report what landed.
+ *
+ * IDEMPOTENT, and that is load-bearing rather than an optimisation: an agent flow re-enters its
+ * workspace once per repair round, so this pass runs several times over one checkout. A file
+ * already on disk is counted and never re-fetched, which keeps a later round from spending the
+ * budget again AND from reporting an image as absent that pass 1 successfully delivered. A view
+ * that MISSED is retried, since the next round is a fresh chance at whatever was transiently down.
+ *
+ * Never throws: images are an aid, not a precondition for running, so a backend outage degrades the
+ * run to its textual context rather than failing it. Every miss is carried out on
+ * {@link ContextImageOutcome.missing} so the caller can say so in the prompt, which is the
+ * difference between an image the platform failed to hand over and a screen that does not exist.
+ */
+export declare function materializeContextImages(cwd: string, subdir: string, spec: ImageManifestSpec, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}): Promise<ContextImageOutcome>;