@cat-factory/executor-harness 1.102.0 → 1.104.0

package/src/job.ts

@@ -22,6 +22,13 @@ import {
   type SkillSpec,
 } from './agent-capabilities.js'
 import { type TestSecretSpec, parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js'
+import {
+  parseContextFiles,
+  parseReferenceScreenshots,
+  type ContextFileSpec,
+  type ReferenceScreenshotSpec,
+  type ReferenceScreenshotsSpec,
+} from './context-manifests.js'
 
 // Re-exported so a handler describing a job keeps ONE import site (the env-pair shape is a job
 // body field like any other; only its VALIDATION moved out).
@@ -30,6 +37,10 @@ export type { TestSecretSpec }
 // Re-exported so the job body stays the one import site for a harness handler describing a job.
 export type { McpServerSpec, SkillResourceSpec, SkillSpec }
 
+// Same rule for the two staged-file manifests: their shapes and their defensive parsing moved to
+// `context-manifests.ts`, but they remain job body fields, so this stays the import site.
+export type { ContextFileSpec, ReferenceScreenshotSpec, ReferenceScreenshotsSpec }
+
 // The job the Worker's ContainerAgentExecutor POSTs to /run. Kept as plain
 // types with a hand-rolled validator so the image needs no schema dependency.
 // `ghToken`, `sessionToken` and `subscriptionToken` are secrets: they are
@@ -610,19 +621,6 @@ export interface AgentBootstrapSpec {
   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. */
@@ -712,6 +710,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
@@ -1015,41 +1020,6 @@ function parseAgentBootstrapSpec(value: unknown): AgentBootstrapSpec | undefined
   }
 }
 
-/**
- * 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: 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. */
-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
-}
-
 /** Parse the explore-mode infra stand-up spec, or undefined when absent/unrecognised. */
 function parseAgentInfraSpec(value: unknown): AgentInfraSpec | undefined {
   if (typeof value !== 'object' || value === null) return undefined
@@ -1230,6 +1200,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     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),
@@ -1272,6 +1243,7 @@ interface ParsedAgentJobParts {
   referenceBranches: ReturnType<typeof parseReferenceBranches>
   bootstrap: ReturnType<typeof parseAgentBootstrapSpec>
   contextFiles: ReturnType<typeof parseContextFiles>
+  referenceScreenshots: ReturnType<typeof parseReferenceScreenshots>
   packageRegistries: ReturnType<typeof parsePackageRegistries>
   skills: ReturnType<typeof parseSkillSpecs>
   mcpServers: ReturnType<typeof parseMcpServerSpecs>
@@ -1329,6 +1301,7 @@ function assembleAgentJob(
     referenceBranches,
     bootstrap,
     contextFiles,
+    referenceScreenshots,
     packageRegistries,
     skills,
     mcpServers,
@@ -1356,6 +1329,7 @@ function assembleAgentJob(
     ...(bootstrap ? { bootstrap } : {}),
     ...(output ? { output } : {}),
     ...(contextFiles.length ? { contextFiles } : {}),
+    ...(referenceScreenshots ? { referenceScreenshots } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
     ...(skills ? { skills } : {}),
     ...(mcpServers ? { mcpServers } : {}),

package/src/pi-workspace.ts

@@ -1,7 +1,8 @@
 import { mkdir, mkdtemp, readdir, rm, stat } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import type { RepoSpec } from './job.js'
+import type { RepoSpec, ReferenceScreenshotsSpec } from './job.js'
+import { deliverReferenceScreenshots } from './reference-screenshots.js'
 import type { McpServerSpec, SkillSpec } from './agent-capabilities.js'
 import { readEffortReport } from './effort.js'
 import { log } from './logger.js'
@@ -212,6 +213,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
@@ -283,6 +290,21 @@ export async function runAgentInWorkspace(
   // 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) —
@@ -306,7 +328,7 @@ export async function runAgentInWorkspace(
     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,
@@ -376,6 +398,7 @@ export async function runAgentInWorkspace(
     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/src/pi.ts

@@ -218,6 +218,13 @@ export async function writeAgentsContext(
      * 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> {
   const dir = join(homedir(), '.pi', 'agent')
@@ -246,9 +253,13 @@ export async function writeAgentsContext(
   // (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 : ''
+  // 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}`,
+    `${systemPrompt}${blueprint}${TODO_GUIDANCE}${monorepo}${multiRepo}${webTools}${context}${references}`,
     'utf8',
   )
 }
@@ -312,9 +323,22 @@ export async function materializeContextFiles(
   const dir = join(cwd, CONTEXT_DIR)
   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: string): Promise<void> {
   const gitRoot = await findGitRoot(cwd)
   if (!gitRoot) return
   try {
@@ -356,13 +380,7 @@ export async function materializeSkillResources(
       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. */

package/src/reference-screenshots.ts

@@ -0,0 +1,295 @@
+import { mkdir, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { ReferenceScreenshotSpec, ReferenceScreenshotsSpec } from './job.js'
+import type { Logger } from './logger.js'
+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)'
+
+/** 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 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: string,
+  spec: ReferenceScreenshotsSpec,
+  options: { signal?: AbortSignal; fetchImpl?: typeof fetch } = {},
+): Promise<ReferenceScreenshotOutcome> {
+  const dir = join(cwd, CONTEXT_DIR, REFERENCE_SCREENSHOT_SUBDIR)
+  const outcome: ReferenceScreenshotOutcome = {
+    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: ReferenceScreenshotOutcome,
+  spec: ReferenceScreenshotsSpec,
+): ReferenceScreenshotOutcome {
+  const rank = new Map(spec.files.map((file, index) => [file.view, index] as const))
+  const at = (view: string) => rank.get(view) ?? Number.MAX_SAFE_INTEGER
+  outcome.written.sort((a, b) => at(a.view) - at(b.view))
+  outcome.missing.sort((a, b) => at(a.view) - at(b.view))
+  return outcome
+}
+
+/**
+ * Whether a previous pass over this checkout already wrote this 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: string, fileName: string): Promise<boolean> {
+  try {
+    return (await stat(join(dir, fileName))).size > 0
+  } catch {
+    // silent-catch-ok: absence is the ordinary answer here (first pass over the checkout), and any
+    // other stat failure is answered the same way — by attempting the download.
+    return false
+  }
+}
+
+/**
+ * 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: string,
+  spec: ReferenceScreenshotsSpec | undefined,
+  options: { signal?: AbortSignal; log: Logger; fetchImpl?: typeof fetch },
+): Promise<string> {
+  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: string,
+  spec: ReferenceScreenshotsSpec,
+  file: ReferenceScreenshotSpec,
+  options: { signal?: AbortSignal; fetchImpl?: typeof fetch },
+): Promise<string | undefined> {
+  const fetchImpl = options.fetchImpl ?? fetch
+  const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout
+  try {
+    const response = await fetchImpl(`${spec.url}/${encodeURIComponent(file.artifactId)}`, {
+      headers: { authorization: `Bearer ${spec.token}` },
+      signal,
+    })
+    if (!response.ok) return `HTTP ${response.status}`
+    const bytes = await readBounded(response, MAX_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: Response, limit: number): Promise<Uint8Array | 'too-large'> {
+  const declared = Number(response.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > limit) return 'too-large'
+  const body = response.body
+  if (!body) {
+    // No stream to count (a mocked or already-buffered response): fall back to measuring after the
+    // fact, which is sound because there is nothing left to stop arriving.
+    const bytes = new Uint8Array(await response.arrayBuffer())
+    return bytes.byteLength > limit ? 'too-large' : bytes
+  }
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > limit) {
+        await reader.cancel()
+        return 'too-large'
+      }
+      chunks.push(value)
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  return bytes
+}
+
+/** A one-line cause for a failed transfer (never the token, which only rides a header). */
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * 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: ReferenceScreenshotOutcome): string {
+  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}`
+}