@cat-factory/executor-harness 1.102.0 → 1.104.0

package/dist/reference-screenshots.d.ts

@@ -0,0 +1,71 @@
+import type { ReferenceScreenshotsSpec } from './job.js';
+import type { Logger } from './logger.js';
+/** Subdirectory of {@link CONTEXT_DIR} the reference designs are written to. */
+export declare const REFERENCE_SCREENSHOT_SUBDIR = "reference-screenshots";
+/** What the pass has on disk, and what it does not. */
+export interface ReferenceScreenshotOutcome {
+    written: {
+        fileName: string;
+        view: string;
+    }[];
+    /**
+     * One entry per reference that is NOT on disk, with the cause stated in `reason`. Covers both
+     * halves of that absence, because the agent's job is the same either way (capture the view under
+     * its own name, with nothing to compare against): a transfer that failed, and a view the cap
+     * dropped before this container was ever asked to fetch it.
+     */
+    missing: {
+        view: string;
+        reason: string;
+    }[];
+    /** Where the written files live, relative to the checkout root. */
+    dir: string;
+}
+/** The relative directory the references are written to (what the prompt points the agent at). */
+export declare const REFERENCE_SCREENSHOT_DIR = ".cat-context/reference-screenshots";
+/**
+ * Download the manifest's images into the checkout and report what landed.
+ *
+ * IDEMPOTENT, and that is load-bearing rather than an optimisation: an agent flow re-enters its
+ * workspace once per repair round, so this pass runs several times over one checkout. A file
+ * already on disk is counted and never re-fetched, which keeps a later round from spending the
+ * budget again AND from reporting a view as absent that pass 1 successfully delivered. A view that
+ * MISSED is retried, since the next round is a fresh chance at whatever was transiently down.
+ *
+ * Never throws: references are an aid to a comparison, not a precondition for running, so a
+ * backend outage degrades a UI run to "name your own views" (the documented fallback) rather than
+ * failing it. Every miss is carried out on {@link ReferenceScreenshotOutcome.missing} so the caller
+ * can say so in the prompt, which is the difference between a design the platform failed to hand
+ * over and one that has no such screen.
+ */
+export declare function materializeReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec, options?: {
+    signal?: AbortSignal;
+    fetchImpl?: typeof fetch;
+}): Promise<ReferenceScreenshotOutcome>;
+/**
+ * The whole delivery in one call: download the manifest (when there is one) and answer the prompt
+ * block naming what landed, reporting any miss to the operator on the way.
+ *
+ * One entry point so an agent-running flow cannot end up doing half of it. A miss is stated to the
+ * AGENT in its prompt (it still has to capture that view) AND logged here, because a reference that
+ * never arrives is otherwise invisible in the run's output: the gallery simply pairs against
+ * nothing, months later, with no line anywhere saying why.
+ */
+export declare function deliverReferenceScreenshots(cwd: string, spec: ReferenceScreenshotsSpec | undefined, options: {
+    signal?: AbortSignal;
+    log: Logger;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
+/**
+ * The prompt block naming what the agent was handed, or '' when the pass produced nothing at all.
+ *
+ * States the MISSES beside the files, because the whole point of writing this directory is that
+ * the tester captures the same views the gate will pair against: a reference that did not arrive
+ * is a view the agent should still capture (under that name) rather than one that does not exist.
+ *
+ * The "on disk" sentence is bound to the files that ARE on disk, and appears only with them. A
+ * block that asserts a populated directory when the pass wrote nothing (every transfer failed, or
+ * the directory could not be created at all) sends the agent looking for a path that may not even
+ * exist, and reads as a platform bug at exactly the moment the platform is already degraded.
+ */
+export declare function referenceScreenshotGuidance(outcome: ReferenceScreenshotOutcome): string;

package/dist/reference-screenshots.js

@@ -0,0 +1,261 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONTEXT_DIR, excludeContextDir } from './pi.js';
+// ---------------------------------------------------------------------------
+// REFERENCE DESIGNS on disk: download the images the backend resolved for this task into
+// `.cat-context/reference-screenshots/`, the directory the UI-tester prompt has always named and
+// nothing wrote.
+//
+// The harness MATERIALISES and never decides: which artifact is the reference for which view, and
+// what each file is called, are backend answers that ride the job body. What lives here is the
+// transfer and its failure reporting: a reference the container could not fetch is NAMED to the
+// agent rather than silently missing, because an absent file and a design that has no such screen
+// look identical on disk.
+// ---------------------------------------------------------------------------
+/** Subdirectory of {@link CONTEXT_DIR} the reference designs are written to. */
+export const REFERENCE_SCREENSHOT_SUBDIR = 'reference-screenshots';
+/** Per-image ceiling, matching the platform's own upload ceiling (16 MiB). */
+const MAX_REFERENCE_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 references (stated to the agent) instead of costing it the run.
+ */
+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;
+/** 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 (reference limit)';
+/** The relative directory the references are written to (what the prompt points the agent at). */
+export const REFERENCE_SCREENSHOT_DIR = `${CONTEXT_DIR}/${REFERENCE_SCREENSHOT_SUBDIR}`;
+/**
+ * Download the manifest's images into the checkout and report what landed.
+ *
+ * IDEMPOTENT, and that is load-bearing rather than an optimisation: an agent flow re-enters its
+ * workspace once per repair round, so this pass runs several times over one checkout. A file
+ * already on disk is counted and never re-fetched, which keeps a later round from spending the
+ * budget again AND from reporting a view as absent that pass 1 successfully delivered. A view that
+ * MISSED is retried, since the next round is a fresh chance at whatever was transiently down.
+ *
+ * Never throws: references are an aid to a comparison, not a precondition for running, so a
+ * backend outage degrades a UI run to "name your own views" (the documented fallback) rather than
+ * failing it. Every miss is carried out on {@link ReferenceScreenshotOutcome.missing} so the caller
+ * can say so in the prompt, which is the difference between a design the platform failed to hand
+ * over and one that has no such screen.
+ */
+export async function materializeReferenceScreenshots(cwd, spec, options = {}) {
+    const dir = join(cwd, CONTEXT_DIR, REFERENCE_SCREENSHOT_SUBDIR);
+    const outcome = {
+        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: REFERENCE_SCREENSHOT_DIR,
+    };
+    try {
+        await mkdir(dir, { recursive: true });
+    }
+    catch (error) {
+        // Nowhere to write: report every reference 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: 'reference 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, spec) {
+    const rank = new Map(spec.files.map((file, index) => [file.view, index]));
+    const at = (view) => 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 reference.
+ *
+ * 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, fileName) {
+    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;
+    }
+}
+/**
+ * The whole delivery in one call: download the manifest (when there is one) and answer the prompt
+ * block naming what landed, reporting any miss to the operator on the way.
+ *
+ * One entry point so an agent-running flow cannot end up doing half of it. A miss is stated to the
+ * AGENT in its prompt (it still has to capture that view) AND logged here, because a reference that
+ * never arrives is otherwise invisible in the run's output: the gallery simply pairs against
+ * nothing, months later, with no line anywhere saying why.
+ */
+export async function deliverReferenceScreenshots(cwd, spec, options) {
+    if (!spec)
+        return '';
+    const outcome = await materializeReferenceScreenshots(cwd, spec, options);
+    if (outcome.missing.length) {
+        options.log.warn('agent: some reference designs are not on disk', {
+            written: outcome.written.length,
+            missing: outcome.missing.length,
+            reasons: outcome.missing.map((file) => file.reason).slice(0, 5),
+        });
+    }
+    return referenceScreenshotGuidance(outcome);
+}
+/** Fetch and write one reference, answering a failure reason or undefined on success. */
+async function downloadOne(dir, spec, file, options) {
+    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_REFERENCE_BYTES);
+        if (bytes === 'too-large')
+            return 'reference 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, limit) {
+    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 = [];
+    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) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The prompt block naming what the agent was handed, or '' when the pass produced nothing at all.
+ *
+ * States the MISSES beside the files, because the whole point of writing this directory is that
+ * the tester captures the same views the gate will pair against: a reference that did not arrive
+ * is a view the agent should still capture (under that name) rather than one that does not exist.
+ *
+ * The "on disk" sentence is bound to the files that ARE on disk, and appears only with them. A
+ * block that asserts a populated directory when the pass wrote nothing (every transfer failed, or
+ * the directory could not be created at all) sends the agent looking for a path that may not even
+ * exist, and reads as a platform bug at exactly the moment the platform is already degraded.
+ */
+export function referenceScreenshotGuidance(outcome) {
+    if (!outcome.written.length && !outcome.missing.length)
+        return '';
+    const onDisk = outcome.written.length
+        ? `\n\nThese are on disk, one file per view:\n${outcome.written
+            .map((file) => `- \`${outcome.dir}/${file.fileName}\`: ${file.view}`)
+            .join('\n')}`
+        : '';
+    const absent = outcome.missing.length
+        ? `\n\nThese views have NO reference image in this container, for the reason given. Capture them
+anyway, under exactly these names. There is simply nothing here to compare against:\n${outcome.missing
+            .map((file) => `- ${file.view}: NOT on disk (${file.reason})`)
+            .join('\n')}`
+        : '';
+    return `
+
+## Reference designs (capture these views)
+Capture the views named below and name each screenshot's \`view\` EXACTLY as given, so the platform
+can pair your capture with its reference. Capture any other view the task needs under a name of
+your own.${onDisk}${absent}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.102.0",
+  "version": "1.104.0",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -30,9 +30,9 @@
     "hono": "^4.13.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.273.0",
-    "@cat-factory/server": "0.253.0",
-    "@cat-factory/spend": "0.15.41"
+    "@cat-factory/kernel": "0.275.0",
+    "@cat-factory/server": "0.255.0",
+    "@cat-factory/spend": "0.15.43"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-shared.ts

@@ -1,4 +1,10 @@
-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'
 
 // Small helpers shared by every agent MODE (explore / coding / bootstrap / preview). They live
@@ -18,17 +24,20 @@ export function mergeEffort(
 }
 
 /**
- * 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: AgentJob): {
   skills?: SkillSpec[]
   mcpServers?: McpServerSpec[]
+  referenceScreenshots?: ReferenceScreenshotsSpec
 } {
   return {
     ...(job.skills?.length ? { skills: job.skills } : {}),
     ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+    ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
   }
 }

package/src/coding-agent.ts

@@ -8,6 +8,7 @@ import type {
   HarnessAuthFields,
   PeerRepoSpec,
   ReferenceRepoSpec,
+  ReferenceScreenshotsSpec,
   RepoSpec,
   SkillSpec,
   McpServerSpec,
@@ -180,6 +181,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. */
@@ -458,6 +467,9 @@ export async function runCodingAgent(
             guardLimits: spec.guardLimits,
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+            ...(spec.referenceScreenshots
+              ? { referenceScreenshots: spec.referenceScreenshots }
+              : {}),
           },
           opts,
         )
@@ -1190,6 +1202,7 @@ export async function runMultiRepoCoding(
           // 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,

package/src/context-manifests.ts

@@ -0,0 +1,156 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 function sanitizeContextFileName(value: unknown): string | undefined {
+  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: unknown): ContextFileSpec[] {
+  if (!Array.isArray(value)) return []
+  const files: ContextFileSpec[] = []
+  const used = new Set<string>()
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const e = entry as Record<string, unknown>
+    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: unknown): ReferenceScreenshotsSpec | 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[] = []
+  // 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)
+    : []
+  const used = new Set<string>()
+  for (const entry of o.files) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const e = entry as Record<string, unknown>
+    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 }
+}