@cat-factory/executor-harness 1.104.0 → 1.108.0

package/src/context-images.ts

@@ -0,0 +1,235 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ImageFileSpec, ImageManifestSpec } from './job.js'
+import { CONTEXT_DIR, excludeContextDir } from './pi.js'
+
+// ---------------------------------------------------------------------------
+// The TRANSFER half of every image manifest: download the images the backend resolved for this job
+// into a subdirectory of `.cat-context/`, and report what did not land.
+//
+// Shared by both manifests (the capture references and the design pictures) because the transfer is
+// the same in every respect that matters here: the same download seam, the same per-image and
+// whole-pass budgets, the same idempotence over a checkout an agent flow re-enters once per repair
+// round, and the same rule that a miss is NAMED rather than silently absent. What differs is what
+// the files mean, which is why each caller owns its own directory and its own prompt block.
+//
+// The harness MATERIALISES and never decides: which artifact belongs to which view, and what each
+// file is called, are backend answers that ride the job body.
+// ---------------------------------------------------------------------------
+
+/** Per-image ceiling, matching the platform's own upload ceiling (16 MiB). */
+const MAX_IMAGE_BYTES = 16 * 1024 * 1024
+
+/** Per-image request timeout. */
+const REQUEST_TIMEOUT_MS = 20_000
+
+/**
+ * Wall-clock ceiling on the WHOLE pass.
+ *
+ * Downloading is activity-silent from the watchdog's point of view (no agent stream, no output),
+ * and `JOB_INACTIVITY_MS` (10 min) is what kills a job that stops producing. Rather than heartbeat
+ * a transfer that should take seconds, the pass is bounded far below that: a slow or wedged blob
+ * backend costs the run its images (stated to the agent) instead of costing it the run.
+ *
+ * Bounds ONE pass, and a job with both manifests runs two. That is deliberate: the alternative is a
+ * shared budget in which whichever manifest is delivered first can starve the other, which would
+ * make a capture's references depend on how many design pictures the same task happens to hold.
+ */
+const TOTAL_BUDGET_MS = 90_000
+
+/** How many images are fetched at once. Small on purpose: this is a shared blob backend. */
+const CONCURRENCY = 4
+
+/** 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
+}
+
+/** The cause reported for a view the backend resolved but never sent this job a file for. */
+const OMITTED_REASON = 'not sent to this container (image limit)'
+
+/**
+ * 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 async function materializeContextImages(
+  cwd: string,
+  subdir: string,
+  spec: ImageManifestSpec,
+  options: { signal?: AbortSignal; fetchImpl?: typeof fetch } = {},
+): Promise<ContextImageOutcome> {
+  const dir = join(cwd, CONTEXT_DIR, subdir)
+  const outcome: ContextImageOutcome = {
+    written: [],
+    // The backend's own dropped views are missing before a single byte is fetched, and for a cause
+    // no transfer could have changed.
+    missing: spec.omitted.map((view) => ({ view, reason: OMITTED_REASON })),
+    dir: `${CONTEXT_DIR}/${subdir}`,
+  }
+  try {
+    await mkdir(dir, { recursive: true })
+  } catch (error) {
+    // Nowhere to write: report every image as missed rather than half of them, since none of them
+    // can land and the cause is the same for all.
+    for (const file of spec.files)
+      outcome.missing.push({ view: file.view, reason: describe(error) })
+    return sortByManifest(outcome, spec)
+  }
+  const deadline = Date.now() + TOTAL_BUDGET_MS
+  const queue = [...spec.files]
+  const workers = Array.from({ length: Math.min(CONCURRENCY, queue.length) }, async () => {
+    for (;;) {
+      const file = queue.shift()
+      if (!file) return
+      // An earlier pass over this same checkout already delivered it. Checked before the budget so
+      // a fully-delivered set costs one stat per file and no network at all, however long an
+      // earlier round took.
+      if (await alreadyOnDisk(dir, file.fileName)) {
+        outcome.written.push({ fileName: file.fileName, view: file.view })
+        continue
+      }
+      if (Date.now() >= deadline) {
+        outcome.missing.push({ view: file.view, reason: 'image download budget exhausted' })
+        continue
+      }
+      const failure = await downloadOne(dir, spec, file, options)
+      if (failure) outcome.missing.push({ view: file.view, reason: failure })
+      else outcome.written.push({ fileName: file.fileName, view: file.view })
+    }
+  })
+  await Promise.all(workers)
+  // Even a partial set must not reach the agent's PR (same rule as every other context file).
+  await excludeContextDir(cwd)
+  return sortByManifest(outcome, spec)
+}
+
+/**
+ * Order both lists the way the BACKEND composed the set (its own gallery order) rather than the
+ * order the transfers happened to finish in, so the list the agent reads is stable across rounds.
+ * The dropped views trail the sent ones, having no position in the manifest to sort by.
+ */
+function sortByManifest(
+  outcome: ContextImageOutcome,
+  spec: ImageManifestSpec,
+): ContextImageOutcome {
+  const rank = new Map(spec.files.map((file, index) => [file.view, index] as const))
+  const at = (view: string) => rank.get(view) ?? Number.MAX_SAFE_INTEGER
+  outcome.written.sort((a, b) => at(a.view) - at(b.view))
+  outcome.missing.sort((a, b) => at(a.view) - at(b.view))
+  return outcome
+}
+
+/**
+ * Whether a previous pass over this checkout already wrote this image.
+ *
+ * Non-empty is the test, not mere existence: a zero-length file is what a half-written transfer
+ * leaves behind, and treating it as delivered would hand the agent a blank image it reads as a
+ * design with nothing on the screen (the same case {@link downloadOne} refuses to write).
+ */
+async function alreadyOnDisk(dir: string, fileName: string): Promise<boolean> {
+  try {
+    return (await stat(join(dir, fileName))).size > 0
+  } catch {
+    // silent-catch-ok: absence is the ordinary answer here (first pass over the checkout), and any
+    // other stat failure is answered the same way — by attempting the download.
+    return false
+  }
+}
+
+/** Fetch and write one image, answering a failure reason or undefined on success. */
+async function downloadOne(
+  dir: string,
+  spec: ImageManifestSpec,
+  file: ImageFileSpec,
+  options: { signal?: AbortSignal; fetchImpl?: typeof fetch },
+): Promise<string | undefined> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout
+  try {
+    const response = await fetchImpl(`${spec.url}/${encodeURIComponent(file.artifactId)}`, {
+      headers: { authorization: `Bearer ${spec.token}` },
+      signal,
+    })
+    if (!response.ok) return `HTTP ${response.status}`
+    const bytes = await readBounded(response, MAX_IMAGE_BYTES)
+    if (bytes === 'too-large') return 'image exceeds size limit'
+    // A zero-length body is a miss, not a file: written out it would be an image the agent opens,
+    // finds empty, and reads as a design with nothing on the screen.
+    if (!bytes.byteLength) return 'empty response'
+    await writeFile(join(dir, file.fileName), bytes)
+    return undefined
+  } catch (error) {
+    return describe(error)
+  }
+}
+
+/**
+ * Read a response body, refusing one that goes past `limit` WITHOUT buffering all of it first.
+ *
+ * The ceiling has to bound the transfer and not just the write. Buffering the whole body and then
+ * measuring it means an oversized (or endless) response is already resident, times the pass's
+ * concurrency, by the time it is rejected — which is the container's memory, in a run whose whole
+ * point is that it has not started working yet. So the declared length is refused up front where
+ * it is honest, and the stream is counted as it arrives and cancelled the moment it crosses the
+ * line, which is what makes a chunked or lying body cost no more than a truthful one.
+ */
+async function readBounded(response: Response, limit: number): Promise<Uint8Array | 'too-large'> {
+  const declared = Number(response.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > limit) return 'too-large'
+  const body = response.body
+  if (!body) {
+    // No stream to count (a mocked or already-buffered response): fall back to measuring after the
+    // fact, which is sound because there is nothing left to stop arriving.
+    const bytes = new Uint8Array(await response.arrayBuffer())
+    return bytes.byteLength > limit ? 'too-large' : bytes
+  }
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > limit) {
+        await reader.cancel()
+        return 'too-large'
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+/** A one-line cause for a failed transfer (never the token, which only rides a header). */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}

package/src/context-manifests.ts

@@ -37,12 +37,12 @@ export interface ContextFileSpec {
  * container would let a harness image the deployment has not rolled out yet rename every view a
  * run reports, and the pairing would come apart with nothing failing.
  */
-export interface ReferenceScreenshotsSpec {
+export interface ImageManifestSpec {
   /** Base URL of the reference download route; the artifact id is appended as a path segment. */
   url: string
   /** The run's container session token (the same one the LLM proxy is called with). */
   token: string
-  files: ReferenceScreenshotSpec[]
+  files: ImageFileSpec[]
   /**
    * View names the task holds a reference for that this job was NOT sent a file for, because the
    * set was capped. Stated to the agent beside the transfers that failed: from where it stands
@@ -56,8 +56,8 @@ export interface ReferenceScreenshotsSpec {
   omitted: string[]
 }
 
-/** One reference image in a {@link ReferenceScreenshotsSpec}. `fileName` is sanitised on parse. */
-export interface ReferenceScreenshotSpec {
+/** One reference image in a {@link ImageManifestSpec}. `fileName` is sanitised on parse. */
+export interface ImageFileSpec {
   artifactId: string
   fileName: string
   view: string
@@ -99,34 +99,41 @@ export function parseContextFiles(value: unknown): ContextFileSpec[] {
 }
 
 /**
- * How many reference images one job may be handed. The backend caps the set it sends well below
- * this, so this is the harness's own backstop against a malformed or hostile body turning the
- * pre-run setup into an unbounded download, never the ceiling a real run meets.
+ * How many images one job may be handed PER MANIFEST. The backend caps each set it sends well
+ * below this, so this is the harness's own backstop against a malformed or hostile body turning
+ * the pre-run setup into an unbounded download, never the ceiling a real run meets.
+ *
+ * One number for both manifests on purpose: the two real ceilings are the BACKEND's, chosen where
+ * the reason for each is known (transfer time for a capture, input tokens for an attachment). A
+ * second backstop here would only encode those reasons a second time, in the one place that
+ * cannot see either.
  *
  * Hitting it is REPORTED rather than silently obeyed: an entry past the ceiling is dropped from
  * `files` and its view named on `omitted`, so an agent facing a truncated set is still told which
- * views to capture. A cap that shortened the list and said nothing would be indistinguishable, on
- * disk and in the prompt, from a design that simply has no such screen.
+ * views it is not being shown. A cap that shortened the list and said nothing would be
+ * indistinguishable, on disk and in the prompt, from a design that simply has no such screen.
  */
-const MAX_REFERENCE_SCREENSHOTS = 40
+const MAX_MANIFEST_IMAGES = 40
 
 /**
- * Parse the reference-design manifest, or undefined when absent/unusable.
+ * Parse one image manifest (the capture set or the design pictures), or undefined when
+ * absent/unusable.
  *
- * The whole manifest is dropped when its transport half is unusable (no absolute http(s) URL, no
- * token): every file would fail the same way, and one stated cause beats N identical ones. An
- * individual entry is dropped only when it cannot name a file safely: the same basename
- * sanitisation every context file gets, so a hostile `fileName` can neither escape the directory
- * nor clobber a repo file.
+ * ONE parser for both, because the wire shape and every rule over it are the same: only the job
+ * body FIELD and what the harness does with the files afterwards differ. The whole manifest is
+ * dropped when its transport half is unusable (no absolute http(s) URL, no token): every file
+ * would fail the same way, and one stated cause beats N identical ones. An individual entry is
+ * dropped only when it cannot name a file safely: the same basename sanitisation every context
+ * file gets, so a hostile `fileName` can neither escape the directory nor clobber a repo file.
  */
-export function parseReferenceScreenshots(value: unknown): ReferenceScreenshotsSpec | undefined {
+export function parseImageManifest(value: unknown): ImageManifestSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
   const o = value as Record<string, unknown>
   const url = typeof o.url === 'string' ? o.url.trim() : ''
   const token = typeof o.token === 'string' ? o.token : ''
   if (!url || !token || !/^https?:\/\//i.test(url)) return undefined
   if (!Array.isArray(o.files)) return undefined
-  const files: ReferenceScreenshotSpec[] = []
+  const files: ImageFileSpec[] = []
   // The backend's own dropped views come first; anything this parser drops joins them below.
   const omitted = Array.isArray(o.omitted)
     ? o.omitted.filter((view): view is string => typeof view === 'string' && view.length > 0)
@@ -144,7 +151,7 @@ export function parseReferenceScreenshots(value: unknown): ReferenceScreenshotsS
     // Past the backstop the entry is NAMED, not dropped: it stays a view the agent must capture.
     // Checked here rather than at the top of the loop so a malformed entry is refused on its own
     // terms (it names no usable view to report) instead of being counted against the ceiling.
-    if (files.length >= MAX_REFERENCE_SCREENSHOTS) {
+    if (files.length >= MAX_MANIFEST_IMAGES) {
       omitted.push(view)
       continue
     }

package/src/design-images.ts

@@ -0,0 +1,82 @@
+import type { ImageManifestSpec } from './job.js'
+import type { Logger } from './logger.js'
+import { CONTEXT_DIR } from './pi.js'
+import { type ContextImageOutcome, materializeContextImages } from './context-images.js'
+
+// ---------------------------------------------------------------------------
+// DESIGN PICTURES on disk for a BUILDING kind: what the screen is supposed to look like, in
+// `.cat-context/design-renders/`, for an agent CLI that can read an image into its turn.
+//
+// The other use of the same artifacts the capture path delivers, and the reason each has its own
+// directory: a tester reading these six would take them for the complete list of views to capture,
+// and a builder reading the tester's twenty-four would spend its context on screens it was never
+// asked to touch.
+//
+// The agent is told about these files by the BACKEND's prompt, which is the half that knows which
+// views the platform holds and whether this model can be shown them at all. What this module adds
+// is the container's own half of the truth: which of those files actually landed here.
+// ---------------------------------------------------------------------------
+
+/** Subdirectory of {@link CONTEXT_DIR} the design pictures are written to. */
+export const DESIGN_RENDER_SUBDIR = 'design-renders'
+
+/** The relative directory the design pictures are written to (what the prompt names). */
+export const DESIGN_RENDER_DIR = `${CONTEXT_DIR}/${DESIGN_RENDER_SUBDIR}`
+
+/** Download this job's design pictures. See {@link materializeContextImages}. */
+export function materializeDesignImages(
+  cwd: string,
+  spec: ImageManifestSpec,
+  options: { signal?: AbortSignal; fetchImpl?: typeof fetch } = {},
+): Promise<ContextImageOutcome> {
+  return materializeContextImages(cwd, DESIGN_RENDER_SUBDIR, spec, options)
+}
+
+/**
+ * Download the design pictures and answer the CORRECTION to the prompt's own list, or '' when
+ * everything the backend named is on disk.
+ *
+ * Silence on success is the difference from the capture delivery, and it is deliberate. The
+ * backend's prompt already names every picture and its view, because it is the side that knows
+ * which views exist and how they were delivered; repeating the list here would give the agent two
+ * lists of the same files, differing only when something went wrong, with nothing saying which one
+ * is current.
+ *
+ * So this speaks only when the container's truth DIVERGES from what the prompt promised. That
+ * divergence has to be stated: an agent told to open a file that is not there re-reads the path,
+ * lists the directory and eventually decides the design is missing something, when the honest
+ * answer is that this one picture did not transfer and the rest are exactly as described.
+ */
+export async function deliverDesignImages(
+  cwd: string,
+  spec: ImageManifestSpec | undefined,
+  options: { signal?: AbortSignal; log: Logger; fetchImpl?: typeof fetch },
+): Promise<string> {
+  if (!spec) return ''
+  const outcome = await materializeDesignImages(cwd, spec, options)
+  if (outcome.missing.length) {
+    options.log.warn('agent: some design pictures are not on disk', {
+      written: outcome.written.length,
+      missing: outcome.missing.length,
+      reasons: outcome.missing.map((file) => file.reason).slice(0, 5),
+    })
+  }
+  return designImageGuidance(outcome)
+}
+
+/**
+ * The prompt correction: the views whose picture is NOT in this container, with the cause.
+ *
+ * Empty whenever the transfer matched the prompt, including the case where the manifest was empty
+ * to begin with. The agent is told to carry on from the textual design description rather than to
+ * ask for the file, because nothing in the run can deliver it after this point.
+ */
+export function designImageGuidance(outcome: ContextImageOutcome): string {
+  if (!outcome.missing.length) return ''
+  return `
+
+## Design pictures: correction
+These views were listed above as pictures, and are NOT in this container. Work from the textual
+design description for them; there is nothing to open and nothing that can fetch them now:
+${outcome.missing.map((file) => `- ${file.view}: NOT on disk (${file.reason})`).join('\n')}`
+}

package/src/job-images.ts

@@ -0,0 +1,43 @@
+import type { ImageManifestSpec } from './job.js'
+import type { Logger } from './logger.js'
+import { deliverDesignImages } from './design-images.js'
+import { deliverReferenceScreenshots } from './reference-screenshots.js'
+
+// ---------------------------------------------------------------------------
+// Both image deliveries of one job, in one call.
+//
+// A job can legitimately carry both manifests (a capturing kind that also builds), and every
+// agent-running flow has to perform both or neither: a flow that did half would leave the agent
+// with a directory it was told about and never got, which is invisible until the output degrades.
+// One entry point makes that impossible to get half-right, the same reason `agentCapabilities`
+// exists for the fields these come from.
+// ---------------------------------------------------------------------------
+
+/** The manifests a job may carry, as they sit on any agent-running spec. */
+export interface JobImageSpecs {
+  referenceScreenshots?: ImageManifestSpec
+  designImages?: ImageManifestSpec
+}
+
+/**
+ * Deliver both manifests into the checkout and answer the prompt text they contribute.
+ *
+ * The two blocks are CONCATENATED rather than kept apart because they say the same kind of thing
+ * (what this container actually holds, against what the run was told it would), and the agent reads
+ * one context. Either half is empty when its manifest is absent or when nothing needs saying, so a
+ * job with one manifest is byte-identical to what it produced before the other existed.
+ *
+ * Runs once per PASS, not once per job: a coding flow re-enters its workspace for every repair
+ * round. That is safe because each delivery is idempotent over the checkout (a file already on disk
+ * is counted, never re-fetched), so a later round costs a stat per image and 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.
+ */
+export async function deliverJobImages(
+  spec: JobImageSpecs & { dir: string },
+  options: { signal?: AbortSignal; log: Logger; fetchImpl?: typeof fetch },
+): Promise<string> {
+  const references = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, options)
+  const designs = await deliverDesignImages(spec.dir, spec.designImages, options)
+  return `${references}${designs}`
+}

package/src/job.ts

@@ -24,10 +24,10 @@ import {
 import { type TestSecretSpec, parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js'
 import {
   parseContextFiles,
-  parseReferenceScreenshots,
+  parseImageManifest,
   type ContextFileSpec,
-  type ReferenceScreenshotSpec,
-  type ReferenceScreenshotsSpec,
+  type ImageFileSpec,
+  type ImageManifestSpec,
 } from './context-manifests.js'
 
 // Re-exported so a handler describing a job keeps ONE import site (the env-pair shape is a job
@@ -39,7 +39,7 @@ export type { McpServerSpec, SkillResourceSpec, SkillSpec }
 
 // Same rule for the two staged-file manifests: their shapes and their defensive parsing moved to
 // `context-manifests.ts`, but they remain job body fields, so this stays the import site.
-export type { ContextFileSpec, ReferenceScreenshotSpec, ReferenceScreenshotsSpec }
+export type { ContextFileSpec, ImageFileSpec, ImageManifestSpec }
 
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
@@ -712,11 +712,23 @@ export interface AgentJob extends HarnessAuthFields {
   contextFiles?: ContextFileSpec[]
   /**
    * The task's reference design images, downloaded into `.cat-context/reference-screenshots/`
-   * before the agent runs (see {@link ReferenceScreenshotsSpec}). Sent only for a kind that
+   * before the agent runs (see {@link ImageManifestSpec}). Sent only for a kind that
    * CAPTURES views and only when the task actually has references, so absent is the normal case
    * and means the agent names its own views.
    */
-  referenceScreenshots?: ReferenceScreenshotsSpec
+  referenceScreenshots?: ImageManifestSpec
+  /**
+   * The PICTURES of the task's designs, for a kind that builds or plans a screen. Downloaded into
+   * `.cat-context/design-renders/` before the run; the agent's prompt (composed by the backend)
+   * names each file and its view, and the agent opens them with its own image-reading tool.
+   *
+   * The same wire shape and the same download seam as {@link AgentJob.referenceScreenshots}, and a
+   * separate field with a separate directory because the two are opposite instructions: that one
+   * names the views to CAPTURE, this one is the design to BUILD. Sent only when the backend
+   * decided this harness can read an image at all, so absent is the normal case and means the run
+   * works from the textual design description (its prompt says which).
+   */
+  designImages?: ImageManifestSpec
   /**
    * Private package-registry auth (npm private orgs, GitHub Packages), rendered into
    * `~/.npmrc` before the run so the checkout's installs — the agent's own and the
@@ -1200,7 +1212,8 @@ export function parseAgentJob(input: unknown): AgentJob {
     referenceBranches: parseReferenceBranches(o.referenceBranches),
     bootstrap: parseAgentBootstrapSpec(o.bootstrap),
     contextFiles: parseContextFiles(o.contextFiles),
-    referenceScreenshots: parseReferenceScreenshots(o.referenceScreenshots),
+    referenceScreenshots: parseImageManifest(o.referenceScreenshots),
+    designImages: parseImageManifest(o.designImages),
     packageRegistries: parsePackageRegistries(o.packageRegistries),
     skills: parseSkillSpecs(o.skills),
     mcpServers: parseMcpServerSpecs(o.mcpServers),
@@ -1243,7 +1256,8 @@ interface ParsedAgentJobParts {
   referenceBranches: ReturnType<typeof parseReferenceBranches>
   bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
   contextFiles: ReturnType<typeof parseContextFiles>
-  referenceScreenshots: ReturnType<typeof parseReferenceScreenshots>
+  referenceScreenshots: ReturnType<typeof parseImageManifest>
+  designImages: ReturnType<typeof parseImageManifest>
   packageRegistries: ReturnType<typeof parsePackageRegistries>
   skills: ReturnType<typeof parseSkillSpecs>
   mcpServers: ReturnType<typeof parseMcpServerSpecs>
@@ -1302,6 +1316,7 @@ function assembleAgentJob(
     bootstrap,
     contextFiles,
     referenceScreenshots,
+    designImages,
     packageRegistries,
     skills,
     mcpServers,
@@ -1330,6 +1345,7 @@ function assembleAgentJob(
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(referenceScreenshots ? { referenceScreenshots } : {}),
+    ...(designImages ? { designImages } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
     ...(skills ? { skills } : {}),
     ...(mcpServers ? { mcpServers } : {}),

package/src/pi-workspace.ts

@@ -1,8 +1,8 @@
 import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { RepoSpec, ReferenceScreenshotsSpec } from './job.js'
-import { deliverReferenceScreenshots } from './reference-screenshots.js'
+import type { RepoSpec, ImageManifestSpec } from './job.js'
+import { deliverJobImages } from './job-images.js'
 import type { McpServerSpec, SkillSpec } from './agent-capabilities.js'
 import { readEffortReport } from './effort.js'
 import { log } from './logger.js'
@@ -218,7 +218,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
@@ -301,7 +308,7 @@ export async function runAgentInWorkspace(
   // 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,
   })
@@ -328,7 +335,7 @@ export async function runAgentInWorkspace(
     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,
@@ -398,7 +405,7 @@ export async function runAgentInWorkspace(
     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