@cat-factory/executor-harness 1.106.0 → 1.110.0

package/dist/multi-repo-coding.js

@@ -0,0 +1,379 @@
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { makeDirClaimer } from './checkout-dir.js';
+import { branchAheadOfBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
+import { openPullRequest } from './vcs-api.js';
+import { applyPrDescription, PR_DESCRIPTION_FILE, readPrDescription } from './pr-description.js';
+import { runAgentInWorkspace, withWorkspace } from './pi-workspace.js';
+import { log } from './logger.js';
+import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
+import { resolvePrTemplateNote, withPrTemplateNote, } from './pr-template.js';
+import { noChangesReason } from './coding-agent.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 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.frameIds?.length ? { frameIds: peer.frameIds } : {}),
+            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.frameIds?.length ? { frameIds: leg.frameIds } : {}),
+                prUrl,
+                branch: leg.workBranch,
+            });
+        }
+    }
+    return { primaryPushed, primaryPrUrl, peerPullRequests };
+}

package/dist/pi-workspace.d.ts

@@ -1,4 +1,4 @@
-import type { RepoSpec, ReferenceScreenshotsSpec } from './job.js';
+import type { RepoSpec, ImageManifestSpec } from './job.js';
 import type { McpServerSpec, SkillSpec } from './agent-capabilities.js';
 import { type ContextFileInfo, type PiRunOutcome } from './pi.js';
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.js';
@@ -110,7 +110,14 @@ export interface AgentRunSpec {
      * before the run and named in the agent's prompt, so a capturing agent can compare against them
      * and use their view names. Absent ⇒ nothing is downloaded and nothing is said.
      */
-    referenceScreenshots?: ReferenceScreenshotsSpec;
+    referenceScreenshots?: ImageManifestSpec;
+    /**
+     * The PICTURES of the task's designs. Downloaded into `.cat-context/design-renders/` before the
+     * run; the agent's prompt (composed by the backend) already names each file and its view, so the
+     * only thing said here is a CORRECTION when one of them did not land. Absent ⇒ nothing is
+     * downloaded and nothing is said.
+     */
+    designImages?: ImageManifestSpec;
     /**
      * The skills to make available for this run — a `skill` step's picked skill and/or the playbooks
      * the running agent kind declares. Installed HARNESS-AWARE: the claude-code runner writes them

package/dist/pi-workspace.js

@@ -1,7 +1,7 @@
 import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { deliverReferenceScreenshots } from './reference-screenshots.js';
+import { deliverJobImages } from './job-images.js';
 import { readEffortReport } from './effort.js';
 import { log } from './logger.js';
 import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
@@ -154,7 +154,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // cannot report a view an earlier round successfully delivered as absent. A view that MISSED is
     // retried, which is the behaviour worth having: the next round is a fresh chance at a blob
     // backend that was briefly down.
-    const referenceGuidance = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, {
+    const imageGuidance = await deliverJobImages(spec, {
         ...(opts.signal ? { signal: opts.signal } : {}),
         log: opts.log ?? log,
     });
@@ -180,7 +180,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         const subOutcome = await runSubscriptionHarness(spec.harness, {
             cwd: spec.dir,
             model: spec.model,
-            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${referenceGuidance}`,
+            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${imageGuidance}`,
             userPrompt: spec.userPrompt,
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
@@ -251,7 +251,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         serviceDirectory: spec.serviceDirectory,
         contextFiles,
         hasBlueprints,
-        ...(referenceGuidance ? { referenceGuidance } : {}),
+        ...(imageGuidance ? { referenceGuidance: imageGuidance } : {}),
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
     // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so

package/dist/reference-screenshots.d.ts

@@ -1,47 +1,15 @@
-import type { ReferenceScreenshotsSpec } from './job.js';
+import type { ImageManifestSpec } from './job.js';
 import type { Logger } from './logger.js';
+import { type ContextImageOutcome } from './context-images.js';
 /** Subdirectory of {@link CONTEXT_DIR} the reference designs are written to. */
 export declare const REFERENCE_SCREENSHOT_SUBDIR = "reference-screenshots";
-/** What the pass has on disk, and what it does not. */
-export interface ReferenceScreenshotOutcome {
-    written: {
-        fileName: string;
-        view: string;
-    }[];
-    /**
-     * One entry per reference that is NOT on disk, with the cause stated in `reason`. Covers both
-     * halves of that absence, because the agent's job is the same either way (capture the view under
-     * its own name, with nothing to compare against): a transfer that failed, and a view the 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;
-}
 /** The relative directory the references are written to (what the prompt points the agent at). */
 export declare const REFERENCE_SCREENSHOT_DIR = ".cat-context/reference-screenshots";
-/**
- * Download the manifest's images into the checkout 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 a view 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: references are an aid to a comparison, not a precondition for running, so a
- * backend outage degrades a UI run to "name your own views" (the documented fallback) rather than
- * failing it. Every miss is carried out on {@link ReferenceScreenshotOutcome.missing} so the caller
- * can say so in the prompt, which is the difference between a design the platform failed to hand
- * over and one that has no such screen.
- */
-export declare function materializeReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec, options?: {
+/** Download this job's capture references. See {@link materializeContextImages}. */
+export declare function materializeReferenceScreenshots(cwd: string, spec: ImageManifestSpec, options?: {
     signal?: AbortSignal;
     fetchImpl?: typeof fetch;
-}): Promise<ReferenceScreenshotOutcome>;
+}): Promise<ContextImageOutcome>;
 /**
  * The whole delivery in one call: download the manifest (when there is one) and answer the prompt
  * block naming what landed, reporting any miss to the operator on the way.
@@ -51,7 +19,7 @@ export declare function materializeReferenceScreenshots(cwd: string, spec: Refer
  * never arrives is otherwise invisible in the run's output: the gallery simply pairs against
  * nothing, months later, with no line anywhere saying why.
  */
-export declare function deliverReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec | undefined, options: {
+export declare function deliverReferenceScreenshots(cwd: string, spec: ImageManifestSpec | undefined, options: {
     signal?: AbortSignal;
     log: Logger;
     fetchImpl?: typeof fetch;
@@ -68,4 +36,4 @@ export declare function deliverReferenceScreenshots(cwd: string, spec: Reference
  * the directory could not be created at all) sends the agent looking for a path that may not even
  * exist, and reads as a platform bug at exactly the moment the platform is already degraded.
  */
-export declare function referenceScreenshotGuidance(outcome: ReferenceScreenshotOutcome): string;
+export declare function referenceScreenshotGuidance(outcome: ContextImageOutcome): string;