@cat-factory/executor-harness 1.102.0 → 1.104.0

package/README.md

@@ -115,6 +115,31 @@ Bootstrap differs at the ends: it may start from an empty dir, and **resets
 history to one commit and force-pushes** the default branch instead of opening a
 PR. Blueprint **commits onto a branch** (no history reset) and returns the tree.
 
+### Reference designs
+
+A job body for a kind that CAPTURES views (the UI tester, or a deployment's own browser-driven kind)
+may carry `referenceScreenshots`: the reference images the platform holds for the task, as
+`{ url, token, files: [{ artifactId, fileName, view }], omitted: [view] }`. The harness downloads
+each into `.cat-context/reference-screenshots/` before the agent's first turn and lists them, by view
+name, at the end of the agent's context.
+
+Only identities travel in the body (a design frame is a full-page PNG), and the bytes come back
+from the backend over the SAME container session token the run already holds for the LLM proxy, so
+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.
+
+`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
+real set has, and an entry past it joins `omitted` rather than vanishing: a cap that shortened the
+list and said nothing would be indistinguishable, on disk and in the prompt, from a design that has
+no such screen.
+
+The pass is IDEMPOTENT over the checkout, which matters because a coding flow re-enters its
+workspace once per repair round: a non-empty file already on disk is counted and never re-fetched,
+and only a view that MISSED is retried. The per-image ceiling is enforced against the declared
+length and against the stream as it arrives, so an oversized body is refused rather than buffered.
+
 ### Skills and tool servers
 
 A job body may carry `skills[]` (procedural playbooks) and `mcpServers[]` (MCP tool servers): the
@@ -213,6 +238,7 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/runner.ts`    | `JobRegistry`: async job lifecycle, idempotent on `jobId`, progress tracking, and the three per-job watchdogs (max-duration, inactivity, tool-silence).                          |
 | `src/jsonl-stream.ts` | The BOUNDS on a child CLI's streams, shared by both runners: `JsonlLineReader` frames its JSONL stdout while refusing to buffer a runaway record, `BoundedTail` keeps a capped tail of raw output for failure quoting. Both watchdog timers and the poll endpoints share one event loop with this parsing, so an unbounded buffer here is how a container stops answering polls with no watchdog having fired. |
 | `src/job.ts`       | Request types + validators for the job specs.                                                           |
+| `src/context-manifests.ts` | The two manifests of FILES the backend stages into the checkout: the linked-context documents and the reference design images. Their shapes plus the defensive parse of each, sharing the basename rule that keeps a body-supplied name from escaping the directory or clobbering a repo file. Both stay job body fields, so `job.ts` remains the import site. |
 | `src/pi.ts`        | Pi provider config, non-interactive run, JSON-line event + todo-progress parsing, global `AGENTS.md` guidance. |
 | `src/pi-reduction.ts` | Reducing a Pi event stream to what the run PRODUCED (summary, stats, diagnostics, terminal failure), FOLDED as records stream rather than over a retained array — memory is O(largest record), not O(records). The array-taking entry points offline tooling uses are defined in terms of the same reducer. |
 | `src/tool-silence.ts` | The tool-silence watchdog (F13) and the `ToolProgressWindow` an agent stream opens, beats and closes. Separate from the phase marker on purpose: a window is only meaningful while something able to reset it is running. |
@@ -229,6 +255,7 @@ 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/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`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |

package/dist/agent-shared.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJob, AgentResult, McpServerSpec, SkillSpec } from './job.js';
+import type { AgentJob, AgentResult, McpServerSpec, ReferenceScreenshotsSpec, SkillSpec } from './job.js';
 import type { EffortReport } from './effort.js';
 /**
  * Fold an agent's effort self-assessment (lifted from its sentinel file by `runAgentInWorkspace`)
@@ -7,12 +7,14 @@ import type { EffortReport } from './effort.js';
  */
 export declare function mergeEffort(result: AgentResult, effortReport: EffortReport | undefined): AgentResult;
 /**
- * The agent-capability fields (skills + tool servers) every agent-running flow forwards to
- * {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow cannot silently
- * be the one that drops a kind's declared playbook or tool server — the failure mode is invisible
- * (the agent simply works without it) and would only show up as degraded output.
+ * The agent-capability fields (skills, tool servers, reference designs) every agent-running flow
+ * forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow
+ * cannot silently be the one that drops a kind's declared playbook, tool server or reference
+ * gallery: the failure mode is invisible (the agent simply works without it) and would only show
+ * up as degraded output.
  */
 export declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
     mcpServers?: McpServerSpec[];
+    referenceScreenshots?: ReferenceScreenshotsSpec;
 };

package/dist/agent-shared.js

@@ -10,14 +10,16 @@ export function mergeEffort(result, effortReport) {
     return effortReport ? { ...result, effortReport } : result;
 }
 /**
- * The agent-capability fields (skills + tool servers) every agent-running flow forwards to
- * {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow cannot silently
- * be the one that drops a kind's declared playbook or tool server — the failure mode is invisible
- * (the agent simply works without it) and would only show up as degraded output.
+ * The agent-capability fields (skills, tool servers, reference designs) every agent-running flow
+ * forwards to {@link runAgentInWorkspace}. One helper rather than a per-flow spread, so a flow
+ * cannot silently be the one that drops a kind's declared playbook, tool server or reference
+ * gallery: the failure mode is invisible (the agent simply works without it) and would only show
+ * up as degraded output.
  */
 export function agentCapabilities(job) {
     return {
         ...(job.skills?.length ? { skills: job.skills } : {}),
         ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+        ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
     };
 }

package/dist/coding-agent.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJob, AgentResult, HarnessAuthFields, RepoSpec, SkillSpec, McpServerSpec } from './job.js';
+import type { AgentJob, AgentResult, HarnessAuthFields, ReferenceScreenshotsSpec, 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';
@@ -112,6 +112,14 @@ export interface CodingAgentSpec extends HarnessAuthFields {
      * has already dropped anything this harness cannot serve. Absent ⇒ built-in tools only.
      */
     mcpServers?: McpServerSpec[];
+    /**
+     * The task's reference design images, downloaded into `.cat-context/reference-screenshots/`
+     * before the agent's first turn. Carried on the coding path as well as the explore one because
+     * what earns a run its references is the KIND's declared `ui` image, and a deployment's own
+     * 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;
 }
 /** The outcome of a coding agent run, before each caller maps it to its own result shape. */
 export interface CodingAgentOutcome {

package/dist/coding-agent.js

@@ -209,6 +209,9 @@ export async function runCodingAgent(spec, opts = {}) {
             guardLimits: spec.guardLimits,
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+            ...(spec.referenceScreenshots
+                ? { referenceScreenshots: spec.referenceScreenshots }
+                : {}),
         }, opts);
         let outcome;
         try {
@@ -808,6 +811,7 @@ export async function runMultiRepoCoding(job, opts = {}) {
             // 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.

package/dist/context-manifests.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A linked-context file the backend prepared (requirements / RFC / PRD / tracker issue)
+ * for the harness to materialise under CONTEXT_DIR in the checkout, so the agent can read
+ * it on demand. The harness can't reach Jira/GitHub itself, so all such context is fetched
+ * and shipped here up front. `path` is sanitised to a safe basename on parse.
+ */
+export interface ContextFileSpec {
+    path: string;
+    title: string;
+    url: string;
+    content: string;
+}
+/**
+ * The REFERENCE DESIGN IMAGES the backend holds for this task, for the harness to download into
+ * `.cat-context/reference-screenshots/` before the agent runs: the directory a UI tester's prompt
+ * names and, until now, nothing wrote.
+ *
+ * A manifest rather than the bytes: a design frame is a full-page PNG, and a job body is JSON
+ * that crosses every transport and is persisted with the dispatch. The bytes come back over the
+ * SAME container session token the run already holds (`GET ${url}/<artifactId>`), so this needs
+ * no extra credential and no publicly reachable URL.
+ *
+ * `view` is what the backend's gate pairs on, and `fileName` is the name the BACKEND chose for it,
+ * never derived here. The file name is how the agent learns the view name, so deriving it in the
+ * 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 {
+    /** 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[];
+    /**
+     * 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
+     * both are a view to capture with no image to compare against.
+     *
+     * Two producers, and they mean the same thing here: the BACKEND's own ceiling (the number that
+     * should ever actually bind, chosen where the precedence between an upload and a design frame
+     * is known), and this parser's backstop against a body claiming more files than any real set
+     * has. A drop with no entry here is the bug this field exists to prevent.
+     */
+    omitted: string[];
+}
+/** One reference image in a {@link ReferenceScreenshotsSpec}. `fileName` is sanitised on parse. */
+export interface ReferenceScreenshotSpec {
+    artifactId: string;
+    fileName: string;
+    view: string;
+}
+/**
+ * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
+ * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
+ * / `..` so a hostile value can't escape the directory or clobber repo files.
+ */
+export declare function sanitizeContextFileName(value: unknown): string | undefined;
+/** Parse the linked-context files, dropping any malformed/unsafe entry. */
+export declare function parseContextFiles(value: unknown): ContextFileSpec[];
+/**
+ * Parse the reference-design manifest, 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.
+ */
+export declare function parseReferenceScreenshots(value: unknown): ReferenceScreenshotsSpec | undefined;

package/dist/context-manifests.js

@@ -0,0 +1,110 @@
+// ---------------------------------------------------------------------------
+// The two manifests of FILES the backend stages into a checkout before the agent's first turn:
+// the linked-context documents it materialises under CONTEXT_DIR, and the reference design images
+// it has the harness download beside them.
+//
+// One module because they are the same kind of thing parsed the same defensive way, and because
+// they share the basename rule below: both name files the container writes into a directory it
+// then points the agent at, so both are held to a value that cannot escape it or clobber a repo
+// file. Split out of `job.ts`, which parses everything else a job body carries.
+// ---------------------------------------------------------------------------
+/**
+ * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
+ * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
+ * / `..` so a hostile value can't escape the directory or clobber repo files.
+ */
+export function sanitizeContextFileName(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
+    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
+    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
+        return undefined;
+    return cleaned;
+}
+/** Parse the linked-context files, dropping any malformed/unsafe entry. */
+export function parseContextFiles(value) {
+    if (!Array.isArray(value))
+        return [];
+    const files = [];
+    const used = new Set();
+    for (const entry of value) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const path = sanitizeContextFileName(e.path);
+        if (!path || used.has(path))
+            continue;
+        if (typeof e.content !== 'string')
+            continue;
+        used.add(path);
+        files.push({
+            path,
+            title: typeof e.title === 'string' ? e.title : path,
+            url: typeof e.url === 'string' ? e.url : '',
+            content: e.content,
+        });
+    }
+    return files;
+}
+/**
+ * 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.
+ *
+ * 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.
+ */
+const MAX_REFERENCE_SCREENSHOTS = 40;
+/**
+ * Parse the reference-design manifest, 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.
+ */
+export function parseReferenceScreenshots(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    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 = [];
+    // 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) => typeof view === 'string' && view.length > 0)
+        : [];
+    const used = new Set();
+    for (const entry of o.files) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        const fileName = sanitizeContextFileName(e.fileName);
+        const artifactId = typeof e.artifactId === 'string' ? e.artifactId.trim() : '';
+        // The id becomes a path segment on the download URL, so it is held to the shape the platform
+        // mints rather than encoded and hoped for: anything else cannot be a real artifact anyway.
+        if (!fileName || used.has(fileName) || !/^[A-Za-z0-9_-]{1,64}$/.test(artifactId))
+            continue;
+        const view = typeof e.view === 'string' ? e.view : fileName;
+        // 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) {
+            omitted.push(view);
+            continue;
+        }
+        used.add(fileName);
+        files.push({ artifactId, fileName, view });
+    }
+    if (!files.length && !omitted.length)
+        return undefined;
+    return { url: url.replace(/\/+$/, ''), token, files, omitted };
+}

package/dist/job.d.ts

@@ -8,8 +8,10 @@ import { type ReproductionReport, type ReproductionSpec } from './reproduction-p
 import { type DependencyInstallSpec } from './dependency-install.js';
 import { type McpServerSpec, type SkillResourceSpec, type SkillSpec } from './agent-capabilities.js';
 import { type TestSecretSpec } from './job-env.js';
+import { type ContextFileSpec, type ReferenceScreenshotSpec, type ReferenceScreenshotsSpec } from './context-manifests.js';
 export type { TestSecretSpec };
 export type { McpServerSpec, SkillResourceSpec, SkillSpec };
+export type { ContextFileSpec, ReferenceScreenshotSpec, ReferenceScreenshotsSpec };
 /**
  * Per-job auth fields, shared across every job shape. The Pi harness carries the
  * proxy base URL + a model-locked session token; the subscription harnesses
@@ -229,18 +231,6 @@ export interface AgentBootstrapSpec {
     /** Scaffold from an empty directory instead of cloning `job.repo` (no reference). */
     fromScratch?: boolean;
 }
-/**
- * A linked-context file the backend prepared (requirements / RFC / PRD / tracker issue)
- * for the harness to materialise under CONTEXT_DIR in the checkout, so the agent can read
- * it on demand. The harness can't reach Jira/GitHub itself, so all such context is fetched
- * and shipped here up front. `path` is sanitised to a safe basename on parse.
- */
-export interface ContextFileSpec {
-    path: string;
-    title: string;
-    url: string;
-    content: string;
-}
 /** How an explore agent's reply is consumed. */
 export interface AgentOutputSpec {
     /** `prose` keeps the reply text; `structured` parses (and optionally repairs) it to JSON. */
@@ -328,6 +318,13 @@ export interface AgentJob extends HarnessAuthFields {
      * The agent reads them on demand; they are kept out of any commit. Absent ⇒ none.
      */
     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
+     * 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;
     /**
      * 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

package/dist/job.js

@@ -3,6 +3,7 @@ import { parseReproductionSpec, } from './reproduction-proof.js';
 import { parseDependencyInstallSpec } from './dependency-install.js';
 import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 import { parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js';
+import { parseContextFiles, parseReferenceScreenshots, } from './context-manifests.js';
 /** A positive finite integer, or undefined for any other input (silently ignored). */
 function posInt(value) {
     return typeof value === 'number' && Number.isFinite(value) && value > 0
@@ -350,45 +351,6 @@ function parseAgentBootstrapSpec(value) {
         ...(o.fromScratch === true ? { fromScratch: true } : {}),
     };
 }
-/**
- * Sanitise a body-supplied context filename to a safe basename within CONTEXT_DIR:
- * strip any directory part, allow only `[A-Za-z0-9._-]`, and reject empties / dotfiles
- * / `..` so a hostile value can't escape the directory or clobber repo files.
- */
-function sanitizeContextFileName(value) {
-    if (typeof value !== 'string')
-        return undefined;
-    const base = value.replace(/\\/g, '/').split('/').pop() ?? '';
-    const cleaned = base.replace(/[^A-Za-z0-9._-]/g, '');
-    if (!cleaned || cleaned === '.' || cleaned === '..' || cleaned.startsWith('.'))
-        return undefined;
-    return cleaned;
-}
-/** Parse the linked-context files, dropping any malformed/unsafe entry. */
-function parseContextFiles(value) {
-    if (!Array.isArray(value))
-        return [];
-    const files = [];
-    const used = new Set();
-    for (const entry of value) {
-        if (typeof entry !== 'object' || entry === null)
-            continue;
-        const e = entry;
-        const path = sanitizeContextFileName(e.path);
-        if (!path || used.has(path))
-            continue;
-        if (typeof e.content !== 'string')
-            continue;
-        used.add(path);
-        files.push({
-            path,
-            title: typeof e.title === 'string' ? e.title : path,
-            url: typeof e.url === 'string' ? e.url : '',
-            content: e.content,
-        });
-    }
-    return files;
-}
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value) {
     if (typeof value !== 'object' || value === null)
@@ -516,6 +478,7 @@ export function parseAgentJob(input) {
         referenceBranches: parseReferenceBranches(o.referenceBranches),
         bootstrap: parseAgentBootstrapSpec(o.bootstrap),
         contextFiles: parseContextFiles(o.contextFiles),
+        referenceScreenshots: parseReferenceScreenshots(o.referenceScreenshots),
         packageRegistries: parsePackageRegistries(o.packageRegistries),
         skills: parseSkillSpecs(o.skills),
         mcpServers: parseMcpServerSpecs(o.mcpServers),
@@ -582,7 +545,7 @@ function parseAgentPrSpec(raw) {
  * literal doesn't blow the complexity budget; behaviour is byte-identical (spread order preserved).
  */
 function assembleAgentJob(o, mode, agentField, parts) {
-    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, referenceScreenshots, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -598,6 +561,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(bootstrap ? { bootstrap } : {}),
         ...(output ? { output } : {}),
         ...(contextFiles.length ? { contextFiles } : {}),
+        ...(referenceScreenshots ? { referenceScreenshots } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
         ...(skills ? { skills } : {}),
         ...(mcpServers ? { mcpServers } : {}),

package/dist/pi-workspace.d.ts

@@ -1,4 +1,4 @@
-import type { RepoSpec } from './job.js';
+import type { RepoSpec, ReferenceScreenshotsSpec } 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';
@@ -105,6 +105,12 @@ export interface AgentRunSpec {
      * from AGENTS.md, so the agent reads them on demand. Absent ⇒ none.
      */
     contextFiles?: ContextFileInfo[];
+    /**
+     * The task's reference design images. Downloaded into `.cat-context/reference-screenshots/`
+     * 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;
     /**
      * 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,6 +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 { readEffortReport } from './effort.js';
 import { log } from './logger.js';
 import { CONTEXT_DIR, materializeContextFiles, materializeSkillResources, phasedProxyBaseUrl, runPi, webSearchConfigFromEnv, webSearchProxyEnv, writeAgentsContext, writePiModelsConfig, writeWebToolsConfig, } from './pi.js';
@@ -142,6 +143,21 @@ export async function runAgentInWorkspace(spec, opts = {}) {
     // harness paths; kept out of the agent's commits via a local git exclude entry.
     const contextFiles = spec.contextFiles ?? [];
     await materializeContextFiles(spec.dir, contextFiles);
+    // The task's reference designs, fetched into `.cat-context/reference-screenshots/` for the kinds
+    // that capture views. Delivered here (beside the linked context, before either harness path
+    // branches) so the Pi and subscription runs are handed the SAME directory and the SAME view
+    // names; a per-path copy is how one of them would end up silently without it.
+    //
+    // This runs once per PASS, not once per job: a coding flow re-enters its workspace for every
+    // repair round. That is safe because the delivery is idempotent over the checkout (a file
+    // already on disk is counted, never re-fetched), so a later round costs a stat per reference 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.
+    const referenceGuidance = await deliverReferenceScreenshots(spec.dir, spec.referenceScreenshots, {
+        ...(opts.signal ? { signal: opts.signal } : {}),
+        log: opts.log ?? log,
+    });
     // Skills: claude-code installs them natively into its ISOLATED config dir, so it reads from
     // there. Everything else reads the checkout, so materialise each skill's resources under
     // `.cat-context/skill/<name>/` (their instructions are folded into the prompt by the backend) —
@@ -164,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),
+            systemPrompt: `${subscriptionSystemPrompt(spec.systemPrompt, contextFiles)}${referenceGuidance}`,
             userPrompt: spec.userPrompt,
             ...(spec.subscriptionToken ? { subscriptionToken: spec.subscriptionToken } : {}),
             subscriptionBaseUrl: spec.subscriptionBaseUrl,
@@ -235,6 +251,7 @@ export async function runAgentInWorkspace(spec, opts = {}) {
         serviceDirectory: spec.serviceDirectory,
         contextFiles,
         hasBlueprints,
+        ...(referenceGuidance ? { referenceGuidance } : {}),
         ...(spec.multiRepo ? { multiRepo: true } : {}),
     });
     // Pi's calls are metered server-side by the LLM proxy, which sees only an HTTP request — so

package/dist/pi.d.ts

@@ -71,6 +71,13 @@ export declare function writeAgentsContext(systemPrompt: string, opts?: {
      * every turn) pointing at files that don't exist. Absent/false ⇒ the note is omitted.
      */
     hasBlueprints?: boolean;
+    /**
+     * The reference-design block composed by `referenceScreenshotGuidance`: which files the run
+     * was handed and which it could not fetch. Composed by the caller (it is the only side that
+     * knows what actually landed on disk) and appended verbatim. Absent/'' ⇒ nothing is said,
+     * which is the normal case: only a capturing kind is sent references at all.
+     */
+    referenceGuidance?: string;
 }): Promise<void>;
 /** Directory in the checkout where linked-context files are materialised (see CONTEXT_DIR in agents). */
 export declare const CONTEXT_DIR = ".cat-context";
@@ -88,6 +95,19 @@ export interface ContextFileInfo {
  * (a scaffold-from-scratch checkout has no `.git` yet — the files just stay untracked).
  */
 export declare function materializeContextFiles(cwd: string, files: ContextFileInfo[]): Promise<void>;
+/**
+ * Add the LOCAL git exclude entry for {@link CONTEXT_DIR}, so nothing the harness materialises
+ * there can be committed into the agent's PR by a `git add -A`.
+ *
+ * The exclude pattern has no leading slash, so it matches `.cat-context/` at any depth, covering
+ * the monorepo case where cwd is a service subdirectory below the repo root. Best-effort: a
+ * scaffold-from-scratch checkout has no `.git` yet, and the files then simply stay untracked.
+ *
+ * One helper rather than a copy per materialiser: every writer into that directory owes the same
+ * exclude, and a new one that forgot it would leak the platform's own files into a customer's
+ * repository with nothing failing.
+ */
+export declare function excludeContextDir(cwd: string): Promise<void>;
 /** Subdirectory of {@link CONTEXT_DIR} where a skill's resources are materialised, per skill. */
 export declare const SKILL_CONTEXT_SUBDIR = "skill";
 /**

package/dist/pi.js

@@ -197,7 +197,11 @@ export async function writeAgentsContext(systemPrompt, opts = {}) {
     // (see the note above `writeAgentsContext`): it comes solely from the backend `spec-aware`
     // trait, so a spec-aware run no longer carries it twice.
     const blueprint = opts.hasBlueprints ? BLUEPRINT_GUIDANCE : '';
-    await writeFile(join(dir, 'AGENTS.md'), `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}`, 'utf8');
+    // The reference designs the harness downloaded for a capturing kind, listed with their view
+    // names (and the ones that could not be fetched). Last, beside the linked-context list it is the
+    // sibling of: both point the agent at files already on disk.
+    const references = opts.referenceGuidance ?? '';
+    await writeFile(join(dir, 'AGENTS.md'), `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}${references}`, 'utf8');
 }
 /** The MULTI-REPO mechanics note appended to AGENTS.md when a run spans sibling checkouts. */
 const MULTI_REPO_GUIDANCE = `
@@ -247,9 +251,21 @@ export async function materializeContextFiles(cwd, files) {
     await mkdir(dir, { recursive: true });
     for (const f of files)
         await writeFile(join(dir, f.path), f.content, 'utf8');
-    // The exclude pattern has no leading slash, so it matches `.cat-context/` at any depth
-    // — covering the monorepo case where cwd is a service subdirectory below the repo root.
-    // Walk up to find the repo's `.git` (best-effort; a from-scratch scaffold has none).
+    await excludeContextDir(cwd);
+}
+/**
+ * Add the LOCAL git exclude entry for {@link CONTEXT_DIR}, so nothing the harness materialises
+ * there can be committed into the agent's PR by a `git add -A`.
+ *
+ * The exclude pattern has no leading slash, so it matches `.cat-context/` at any depth, covering
+ * the monorepo case where cwd is a service subdirectory below the repo root. Best-effort: a
+ * scaffold-from-scratch checkout has no `.git` yet, and the files then simply stay untracked.
+ *
+ * One helper rather than a copy per materialiser: every writer into that directory owes the same
+ * exclude, and a new one that forgot it would leak the platform's own files into a customer's
+ * repository with nothing failing.
+ */
+export async function excludeContextDir(cwd) {
     const gitRoot = await findGitRoot(cwd);
     if (!gitRoot)
         return;
@@ -289,15 +305,7 @@ export async function materializeSkillResources(cwd, skills) {
             await writeFile(dest, r.content, 'utf8');
         }
     }
-    const gitRoot = await findGitRoot(cwd);
-    if (!gitRoot)
-        return;
-    try {
-        await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8');
-    }
-    catch {
-        // No writable .git/info; the files simply stay untracked.
-    }
+    await excludeContextDir(cwd);
 }
 /** Walk up from `dir` (bounded) to the directory containing a `.git` folder, or null. */
 async function findGitRoot(dir) {