@cat-factory/executor-harness 1.100.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/agent.js

@@ -9,7 +9,8 @@ import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './re
 import { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, unmergedPaths, } from './git.js';
 import { inferVcsProvider, openPullRequest } from './vcs-api.js';
 import { applyPrDescription } from './pr-description.js';
-import { makeDirClaimer, noChangesReason, runCodingAgent, runMultiRepoCoding, } from './coding-agent.js';
+import { makeDirClaimer } from './checkout-dir.js';
+import { noChangesReason, runCodingAgent, runMultiRepoCoding } from './coding-agent.js';
 import { validationFailureMessage } from './validation-checks.js';
 import { prepopulateDependencies, withDependencyNote } from './dependency-install.js';
 import { agentCapabilities, mergeEffort } from './agent-shared.js';

package/dist/checkout-dir.d.ts

@@ -0,0 +1,33 @@
+import type { RepoSpec } from './job.js';
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export declare function safeDirSegment(value: string): string;
+/**
+ * A short deterministic digest of the EXACT `owner` / `name` pair, before sanitisation. FNV-1a
+ * over `owner\0name`; the NUL separator makes it a digest of the PAIR rather than of a
+ * concatenation, so `('a', 'bc')` and `('ab', 'c')` cannot share one. Hand-rolled rather than
+ * taken from `node:crypto` because the backend needs the identical function and runs it in
+ * workerd as well as on Node.
+ *
+ * MUST stay byte-identical to the backend's `checkoutDirDigest`
+ * (`@cat-factory/server`, `agents/harnessContract.ts`); see {@link makeDirClaimer}.
+ */
+export declare function checkoutDirDigest(owner: string, name: string): string;
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. A pure function of the pair (`owner__name__digest`), which is
+ * what lets this and the backend compute it independently with no shared ordering or state. Kept
+ * as a factory so the coding + read-only explore fan-outs share ONE scheme, and it MUST stay
+ * byte-identical to the backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in
+ * `@cat-factory/server`, which names this exact directory in the agent's prompt: the two are
+ * computed independently, so a divergent rule would point the agent at a directory that does not
+ * exist.
+ *
+ * The readable `owner__name` prefix does not identify a repo on its own, which is why the digest
+ * is there. {@link safeDirSegment} folds a whole class of characters onto `-`, so a GitLab
+ * namespace path `grp/sub` and a group literally named `grp-sub` sanitise alike; and the `__`
+ * join is ambiguous once a segment may contain `_`, which GitHub owners cannot but GitLab
+ * namespace paths can, so `('a__b', 'c')` and `('a', 'b__c')` both read as `a__b__c`. Either
+ * collision puts two legs on one directory, and the second one's clone then fails against a
+ * directory the first already filled, killing the run in the clone phase naming neither repo.
+ */
+export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;

package/dist/checkout-dir.js

@@ -0,0 +1,56 @@
+// ---------------------------------------------------------------------------
+// The HARNESS half of the sibling-checkout-directory contract.
+//
+// The harness CREATES these directories; `@cat-factory/server`'s `agents/harnessContract.ts`
+// NAMES them in the agent's prompt. The image builds from this `src/` plus typescript and may
+// depend on no workspace package, so the two halves are computed INDEPENDENTLY and pinned against
+// each other by `test/harness-contract.conformity.test.ts`. Extracted out of `coding-agent.ts` so
+// the pairing sits in one small module per side rather than buried in the agent runner: the whole
+// point of the pairing is that a reader can see both halves at once.
+// ---------------------------------------------------------------------------
+/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
+export function safeDirSegment(value) {
+    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
+}
+/**
+ * A short deterministic digest of the EXACT `owner` / `name` pair, before sanitisation. FNV-1a
+ * over `owner\0name`; the NUL separator makes it a digest of the PAIR rather than of a
+ * concatenation, so `('a', 'bc')` and `('ab', 'c')` cannot share one. Hand-rolled rather than
+ * taken from `node:crypto` because the backend needs the identical function and runs it in
+ * workerd as well as on Node.
+ *
+ * MUST stay byte-identical to the backend's `checkoutDirDigest`
+ * (`@cat-factory/server`, `agents/harnessContract.ts`); see {@link makeDirClaimer}.
+ */
+export function checkoutDirDigest(owner, name) {
+    const input = `${owner}\u0000${name}`;
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        // The FNV prime (16777619) as shifts, with `>>> 0` folding the result back to uint32 every
+        // step so the arithmetic never drifts into float range and diverges between engines.
+        hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash.toString(36).padStart(7, '0');
+}
+/**
+ * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
+ * repo under the workspace root. A pure function of the pair (`owner__name__digest`), which is
+ * what lets this and the backend compute it independently with no shared ordering or state. Kept
+ * as a factory so the coding + read-only explore fan-outs share ONE scheme, and it MUST stay
+ * byte-identical to the backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in
+ * `@cat-factory/server`, which names this exact directory in the agent's prompt: the two are
+ * computed independently, so a divergent rule would point the agent at a directory that does not
+ * exist.
+ *
+ * The readable `owner__name` prefix does not identify a repo on its own, which is why the digest
+ * is there. {@link safeDirSegment} folds a whole class of characters onto `-`, so a GitLab
+ * namespace path `grp/sub` and a group literally named `grp-sub` sanitise alike; and the `__`
+ * join is ambiguous once a segment may contain `_`, which GitHub owners cannot but GitLab
+ * namespace paths can, so `('a__b', 'c')` and `('a', 'b__c')` both read as `a__b__c`. Either
+ * collision puts two legs on one directory, and the second one's clone then fails against a
+ * directory the first already filled, killing the run in the clone phase naming neither repo.
+ */
+export function makeDirClaimer() {
+    return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}__${checkoutDirDigest(repo.owner, repo.name)}`;
+}

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 {
@@ -219,19 +227,6 @@ export declare function runRalphValidation(repoDir: string, cwd: string, validat
     iteration?: number;
     headSha?: string;
 }>;
-/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
-export declare function safeDirSegment(value: string): string;
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export declare function makeDirClaimer(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string;
 /**
  * Multi-repo coding (service-connections phase 3): clone the primary repo AND every connected
  * peer repo as SIBLING checkouts under one workspace root, run the agent ONCE with its cwd at

package/dist/coding-agent.js

@@ -1,6 +1,7 @@
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runCapturedCommand } from './captured-command.js';
+import { makeDirClaimer } from './checkout-dir.js';
 import { branchAheadOfBase, changedFilesSinceBase, branchHasCommitsSince, cloneExistingBranch, cloneRepo, commitTrackedEdits, createBranch, excludeFromGit, fetchReferenceBranches, headCommit, listUntrackedFiles, prepareExistingCheckout, pushBranch, refreshFromBaseIfClean, remoteBranchExists, } from './git.js';
 import { openPullRequest } from './vcs-api.js';
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js';
@@ -208,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 {
@@ -676,23 +680,6 @@ export async function runRalphValidation(repoDir, cwd, validation, logger, opts)
         ...(headSha ? { headSha } : {}),
     };
 }
-/** Sanitise an owner/name into a safe single path segment for a sibling checkout directory. */
-export function safeDirSegment(value) {
-    return value.replace(/[^A-Za-z0-9._-]/g, '-') || '_';
-}
-/**
- * A sibling-directory allocator for a multi-repo run: returns the checkout directory name for a
- * repo under the workspace root. Deterministic (`owner__name`) and collision-free by construction
- * — the checkout set is deduped by `owner/name` upstream and GitHub owners contain no `_`, so the
- * `owner__name` join is unique per repo without a stateful collision dance. Kept as a factory so
- * the coding + read-only explore fan-outs share ONE scheme, and it MUST stay byte-identical to the
- * backend's `siblingCheckoutDir` / `renderMultiRepoWorkspaceSection` in `@cat-factory/server`
- * (jobBody.ts), which names this exact directory in the agent's prompt — the two are computed
- * independently, so a divergent rule would point the agent at a directory that does not exist.
- */
-export function makeDirClaimer() {
-    return (repo) => `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}`;
-}
 /**
  * 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
@@ -711,8 +698,9 @@ export async function runMultiRepoCoding(job, opts = {}) {
     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`,
-    // matching the backend prompt's `siblingCheckoutDir`), shared with the read-only explore fan-out.
+    // 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 = [
         {
@@ -823,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