@cat-factory/executor-harness 1.100.0 → 1.104.0

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) {

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.100.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.272.0",
-    "@cat-factory/server": "0.252.0",
-    "@cat-factory/spend": "0.15.40"
+    "@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/agent.ts

@@ -29,12 +29,8 @@ import {
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
 import type { PiRunStats, RunDiagnostics } from './pi-reduction.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/src/checkout-dir.ts

@@ -0,0 +1,62 @@
+import type { RepoSpec } from './job.js'
+
+// ---------------------------------------------------------------------------
+// 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: string): string {
+  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: string, name: string): string {
+  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(): (repo: Pick<RepoSpec, 'name' | 'owner'>) => string {
+  return (repo) =>
+    `${safeDirSegment(repo.owner)}__${safeDirSegment(repo.name)}__${checkoutDirDigest(repo.owner, repo.name)}`
+}