@cat-factory/executor-harness 1.110.2 → 1.112.0

package/dist/codex-images.js

@@ -0,0 +1,157 @@
+import { lstat, mkdir, readdir, rename, rm, symlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { CONTEXT_DIR, excludeContextDir } from './pi.js';
+// ---------------------------------------------------------------------------
+// CODEX'S OWN IMAGE GENERATION, staged somewhere the agent can actually reach.
+//
+// Codex CLI carries a built-in `image_gen` tool (gpt-image-2) that is available ONLY on ChatGPT
+// subscription auth — an `OPENAI_API_KEY` session routes to the Images API instead and does not
+// get the tool at all. That makes it the one generative path the platform can offer with no
+// vendor API key anywhere, which is exactly what a `harness`-transport binary generator is.
+//
+// Two facts make this more than a feature flag.
+//
+// 1. Codex writes generated images to `$CODEX_HOME/generated_images/`, and does not reliably tell
+//    anyone where they landed: the tool result exposes no path, no URL and no artifact id
+//    (openai/codex#28887, #28898, #28873, #28849, all open), and `codex exec --json` never
+//    surfaces structured tool bodies at all. So the PLATFORM has to know where the file is; asking
+//    the model is the thing that does not work.
+//
+// 2. `$CODEX_HOME` is also where the decrypted subscription `auth.json` lives. Telling the agent to
+//    go and look there would point a prompt-injectable process at the run's own credential — the
+//    same exposure `runCodex` already keeps the home OUTSIDE the checkout to avoid.
+//
+// So the harness redirects the output instead: `generated_images` is created as a SYMLINK into the
+// checkout's context directory before the CLI starts, and codex writes through it. The agent reads
+// one stable, credential-free path, with no polling and no race between generating and uploading —
+// the file is simply there the moment the tool returns. `$CODEX_HOME` stays unreadable to it.
+//
+// A post-run sweep backs that up for the case where the symlink could not be made (a filesystem
+// that refuses one) or was replaced: anything sitting in a REAL `generated_images` directory is
+// moved into the same staging path, so a run never silently loses an image it paid to generate.
+// ---------------------------------------------------------------------------
+/** Codex's own output directory name, relative to `CODEX_HOME`. Chosen by the CLI, not by us. */
+const CODEX_OUTPUT_DIRNAME = 'generated_images';
+/**
+ * Where a harness-generated binary artifact is staged for the agent, relative to the checkout.
+ *
+ * Under {@link CONTEXT_DIR} so it inherits that directory's git exclude: an image the agent has
+ * not uploaded yet must never be swept into a commit by the `git add -A` a coding run ends with.
+ * Part of the backend↔harness path contract (`HARNESS_SENTINEL_PATHS.generatedBinaries`), because
+ * the agent's brief has to NAME this path and the two halves are written independently.
+ */
+export const GENERATED_BINARY_SUBDIR = 'binary-output/generated';
+/** The staging directory's repo-relative path, as the prompt names it. */
+export const GENERATED_BINARY_DIR = `${CONTEXT_DIR}/${GENERATED_BINARY_SUBDIR}`;
+/**
+ * Point codex's image output at the checkout, before the CLI starts.
+ *
+ * Returns whether the redirect is in place. FALSE is a real and reportable answer rather than a
+ * throw: a run whose images cannot be staged is still a run worth doing (the agent may have plenty
+ * of non-generating work), and the caller states the gap instead of failing the job. The sweep
+ * below is what keeps that case from losing files outright.
+ *
+ * Best-effort by construction, and deliberately NOT idempotent-by-overwrite: an existing
+ * `generated_images` is left exactly as it is. On the per-run home this is always a fresh
+ * directory, so anything already there on the ambient path is the DEVELOPER's own history, and
+ * replacing it with a symlink into a throwaway checkout would destroy it.
+ */
+export async function stageCodexImages(codexHome, cwd, log) {
+    const target = join(cwd, CONTEXT_DIR, GENERATED_BINARY_SUBDIR);
+    try {
+        await mkdir(target, { recursive: true });
+        // The context directory's own exclude, applied here rather than assumed: a codex run that was
+        // handed no context files never reaches the materialiser that normally writes it, and this is
+        // the one writer whose output is BINARY and would otherwise be committed as such.
+        await excludeContextDir(cwd);
+        // `junction` is ignored off Windows and is what makes the same call work on a developer's
+        // machine, where a plain directory symlink needs a privilege the shell usually lacks.
+        await symlink(target, join(codexHome, CODEX_OUTPUT_DIRNAME), 'junction');
+        return true;
+    }
+    catch (error) {
+        log?.warn('codex image staging unavailable; falling back to a post-run sweep', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return false;
+    }
+}
+/**
+ * Move anything codex wrote into a REAL `generated_images` directory across to the staging path.
+ *
+ * The backstop for a redirect that did not take. Returns the file names moved, so the caller can
+ * say what arrived after the agent had already finished — those are images the run generated and
+ * the agent never had a chance to upload, which is a different fact from generating none, and the
+ * kind of distinction this codebase refuses to let collapse into silence.
+ *
+ * A live redirect yields nothing here, detected by `lstat` on the directory itself: reading THROUGH
+ * the link would list files that are already where they belong and report every one of them as
+ * stranded.
+ */
+export async function sweepCodexImages(codexHome, cwd, log) {
+    const source = join(codexHome, CODEX_OUTPUT_DIRNAME);
+    const target = join(cwd, CONTEXT_DIR, GENERATED_BINARY_SUBDIR);
+    // A LIVE REDIRECT has nothing to sweep, and it must be detected by asking the filesystem rather
+    // than by comparing paths: `readdir` through the link yields the staging directory's own files
+    // under the SOURCE prefix, so every path pair looks distinct and every file the run generated is
+    // "moved" onto itself and then reported as stranded. That is a false alarm on every successful
+    // generating run — precisely inverting what this report is for.
+    try {
+        if ((await lstat(source)).isSymbolicLink())
+            return [];
+    }
+    catch {
+        // No directory at all is the normal case: the run generated nothing.
+        return [];
+    }
+    let names;
+    try {
+        names = await readdir(source);
+    }
+    catch {
+        return [];
+    }
+    const moved = [];
+    // Loop-invariant: made ONCE here rather than per rescued file. This is the path where
+    // `stageCodexImages` did not create it, so it cannot be assumed to exist. A failure needs no
+    // report of its own — every rename below then fails and names its own file in the warning it
+    // already emits, which is the more useful line anyway.
+    await mkdir(target, { recursive: true }).catch(() => { });
+    for (const name of names) {
+        const from = join(source, name);
+        const to = join(target, name);
+        try {
+            await rename(from, to);
+            moved.push(name);
+        }
+        catch (error) {
+            log?.warn('could not stage a generated image', {
+                name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return moved;
+}
+/**
+ * Remove the redirect before the per-run home is torn down.
+ *
+ * Only ever the LINK: `rm` on a symlink unlinks it and leaves the target alone, which is what must
+ * happen here — the target is inside the checkout and holds the run's actual output. Passed the
+ * home rather than the link path so a caller cannot accidentally hand it the staging directory.
+ *
+ * A failure is SWALLOWED (teardown must not take a completed run down with it) and REPORTED,
+ * because this unlink is the property that stops the recursive delete that follows from reaching
+ * the checkout. Dropping it silently would forfeit that with no line anywhere saying so, and the
+ * evidence would be missing artifacts nobody could trace back to this call.
+ */
+export async function unstageCodexImages(codexHome, log) {
+    try {
+        await rm(join(codexHome, CODEX_OUTPUT_DIRNAME), { recursive: false, force: true });
+    }
+    catch (error) {
+        log?.warn('could not remove the codex image redirect before tearing the home down', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

package/dist/job.d.ts

@@ -9,9 +9,11 @@ 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 ImageFileSpec, type ImageManifestSpec } from './context-manifests.js';
+import { type ArtifactUploadSpec } from './artifact-upload.js';
 export type { TestSecretSpec };
 export type { McpServerSpec, SkillResourceSpec, SkillSpec };
 export type { ContextFileSpec, ImageFileSpec, ImageManifestSpec };
+export type { ArtifactUploadSpec };
 /**
  * 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
@@ -342,6 +344,17 @@ export interface AgentJob extends HarnessAuthFields {
      * works from the textual design description (its prompt says which).
      */
     designImages?: ImageManifestSpec;
+    /**
+     * Where this job uploads the artifacts it PRODUCES (see {@link ArtifactUploadSpec}) — the
+     * outbound leg of the seam {@link AgentJob.referenceScreenshots} and {@link
+     * AgentJob.designImages} are the inbound legs of. Surfaced to the agent as
+     * `ARTIFACT_UPLOAD_URL` / `ARTIFACT_UPLOAD_TOKEN`, which the capturing prompts already name.
+     *
+     * Sent only for a kind the backend gave a browser image to, so absent is the NORMAL case and
+     * means this run produces no platform-held bytes. SECRET-BEARING (`token` is the run's container
+     * session token), so it is registered for redaction before it reaches any child.
+     */
+    artifactUpload?: ArtifactUploadSpec;
     /**
      * 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
@@ -365,6 +378,16 @@ export interface AgentJob extends HarnessAuthFields {
      * built-in tools only.
      */
     mcpServers?: McpServerSpec[];
+    /**
+     * Enable the codex CLI's own `image_gen` tool for this job, and stage what it writes into
+     * `.cat-context/binary-output/generated/` where the agent can reach it.
+     *
+     * Set when the dispatch resolved a HARNESS-transport binary generator served by codex. Opt-in
+     * per job because the tool bills the leased ChatGPT plan at several times an ordinary turn, so
+     * an always-on image capability would charge every run for one it never uses. Ignored by the
+     * Pi and claude-code runners, neither of which has such a tool. Absent ⇒ no image tool.
+     */
+    generateImages?: boolean;
     /**
      * Tester kinds only: sensitive test credentials injected into the run's ENVIRONMENT (out of
      * band) as `{ key, value }` env pairs, so the tester's shell can read `$KEY` without the value

package/dist/job.js

@@ -4,6 +4,7 @@ import { parseDependencyInstallSpec } from './dependency-install.js';
 import { parseMcpServerSpecs, parseSkillSpecs, } from './agent-capabilities.js';
 import { parseInfraEnv, parseSecretEnvPairs, str } from './job-env.js';
 import { parseContextFiles, parseImageManifest, } from './context-manifests.js';
+import { parseArtifactUpload } from './artifact-upload.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
@@ -483,6 +484,7 @@ export function parseAgentJob(input) {
         contextFiles: parseContextFiles(o.contextFiles),
         referenceScreenshots: parseImageManifest(o.referenceScreenshots),
         designImages: parseImageManifest(o.designImages),
+        artifactUpload: parseArtifactUpload(o.artifactUpload),
         packageRegistries: parsePackageRegistries(o.packageRegistries),
         skills: parseSkillSpecs(o.skills),
         mcpServers: parseMcpServerSpecs(o.mcpServers),
@@ -549,7 +551,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, referenceScreenshots, designImages, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
+    const { output, pr, infra, peerRepos, referenceRepos, referenceBranches, bootstrap, contextFiles, referenceScreenshots, designImages, artifactUpload, packageRegistries, skills, mcpServers, testSecrets, guardLimits, validation, validationChecks, reproduction, dependencyInstall, reviewPrNumber, generatorSecrets, } = parts;
     const repo = (o.repo ?? {});
     return {
         jobId: str(o.jobId, 'jobId'),
@@ -567,6 +569,7 @@ function assembleAgentJob(o, mode, agentField, parts) {
         ...(contextFiles.length ? { contextFiles } : {}),
         ...(referenceScreenshots ? { referenceScreenshots } : {}),
         ...(designImages ? { designImages } : {}),
+        ...(artifactUpload ? { artifactUpload } : {}),
         ...(packageRegistries.length ? { packageRegistries } : {}),
         ...(skills ? { skills } : {}),
         ...(mcpServers ? { mcpServers } : {}),
@@ -598,6 +601,7 @@ function collectOptionalRequestFields(o) {
         ...(typeof o.githubApiBase === 'string' ? { githubApiBase: o.githubApiBase } : {}),
         ...(typeof o.webToolsGuidance === 'string' ? { webToolsGuidance: o.webToolsGuidance } : {}),
         ...(o.webSearch === true ? { webSearch: true } : {}),
+        ...(o.generateImages === true ? { generateImages: true } : {}),
         ...(o.full === true ? { full: true } : {}),
         ...(typeof o.mergeBase === 'string' && o.mergeBase ? { mergeBase: o.mergeBase } : {}),
         ...(typeof o.newBranch === 'string' && o.newBranch ? { newBranch: o.newBranch } : {}),

package/dist/pi-workspace.d.ts

@@ -133,6 +133,15 @@ export interface AgentRunSpec {
      * re-deciding. Absent ⇒ the CLI's built-in tools only.
      */
     mcpServers?: McpServerSpec[];
+    /**
+     * Enable the codex CLI's built-in `image_gen` tool and stage its output into the checkout.
+     *
+     * Forwarded rather than decided here, exactly like {@link mcpServers}: the BACKEND is the half
+     * that resolved a harness-served binary generator for this step and knows the run is meant to
+     * generate. A run that simply asks nicely gets nothing, which is the point — the tool bills the
+     * leased plan at several times an ordinary turn.
+     */
+    generateImages?: boolean;
     /**
      * Enable proxy-backed web search: point the rpiv-web-tools SearXNG provider at the
      * backend's search proxy (`${proxyBaseUrl}/web-search`) with the session token as

package/dist/pi-workspace.js

@@ -187,6 +187,11 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             ...(spec.ambientAuth ? { ambientAuth: true } : {}),
             ...(spec.skills?.length ? { skills: spec.skills } : {}),
             ...(spec.mcpServers?.length ? { mcpServers: spec.mcpServers } : {}),
+            // Codex's own image tool. Passed for both subscription harnesses because the option lives on
+            // the shared run options; `runClaudeCode` ignores it, since claude-code has no such tool and
+            // (unlike an MCP server) there is nothing to report as unservable — the backend never
+            // resolves a codex-served generator onto a claude-code step, because admission refuses it.
+            ...(spec.generateImages ? { generateImages: true } : {}),
             ...(opts.agentEnv ? { extraEnv: opts.agentEnv } : {}),
             signal: opts.signal,
             // Run the SAME no-progress guard Pi gets (previously claude-code/codex had none): env

package/dist/pi.d.ts

@@ -106,6 +106,12 @@ export declare function materializeContextFiles(cwd: string, files: ContextFileI
  * 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.
+ *
+ * IDEMPOTENT BY CONTENT, because that is the only shape that survives its own design: several
+ * materialisers legitimately run in one job (context files, skill resources, the codex image
+ * staging), so a blind append writes the same line two or three times per run, and on a persistent
+ * checkout it accretes one copy per run forever. Re-read and skip rather than tracking who called
+ * first, which would be a second piece of state to keep right.
  */
 export declare function excludeContextDir(cwd: string): Promise<void>;
 /** Subdirectory of {@link CONTEXT_DIR} where a skill's resources are materialised, per skill. */

package/dist/pi.js

@@ -1,5 +1,5 @@
 import { spawn } from 'node:child_process';
-import { appendFile, mkdir, writeFile } from 'node:fs/promises';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
@@ -264,13 +264,24 @@ export async function materializeContextFiles(cwd, files) {
  * 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.
+ *
+ * IDEMPOTENT BY CONTENT, because that is the only shape that survives its own design: several
+ * materialisers legitimately run in one job (context files, skill resources, the codex image
+ * staging), so a blind append writes the same line two or three times per run, and on a persistent
+ * checkout it accretes one copy per run forever. Re-read and skip rather than tracking who called
+ * first, which would be a second piece of state to keep right.
  */
 export async function excludeContextDir(cwd) {
     const gitRoot = await findGitRoot(cwd);
     if (!gitRoot)
         return;
+    const excludeFile = join(gitRoot, '.git', 'info', 'exclude');
+    const entry = `${CONTEXT_DIR}/`;
     try {
-        await appendFile(join(gitRoot, '.git', 'info', 'exclude'), `\n${CONTEXT_DIR}/\n`, 'utf8');
+        const current = await readFile(excludeFile, 'utf8').catch(() => '');
+        if (current.split('\n').some((line) => line.trim() === entry))
+            return;
+        await appendFile(excludeFile, `\n${entry}\n`, 'utf8');
     }
     catch {
         // No writable .git/info; the files simply stay untracked (still not auto-added on most flows).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.110.2",
+  "version": "1.112.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.1",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.292.1",
-    "@cat-factory/server": "0.278.1",
-    "@cat-factory/spend": "0.15.80"
+    "@cat-factory/kernel": "0.296.0",
+    "@cat-factory/server": "0.283.0",
+    "@cat-factory/spend": "0.15.86"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-capabilities.ts

@@ -343,7 +343,12 @@ export function parseSkillSpecs(value: unknown): SkillSpec[] | undefined {
  * A member is added here in the SAME change that teaches the parser the field, never ahead of it:
  * the whole value of the list is that it is the image's own honest answer.
  */
-export const HARNESS_BODY_CAPABILITIES: readonly string[] = ['mcpServers', 'skills', 'designImages']
+export const HARNESS_BODY_CAPABILITIES: readonly string[] = [
+  'mcpServers',
+  'skills',
+  'designImages',
+  'generateImages',
+]
 
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.

package/src/agent-runner.ts

@@ -23,7 +23,6 @@ import {
 import type { PiRunStats } from './pi-reduction.js'
 import {
   claudeAllowedToolPatterns,
-  codexMcpConfigToml,
   mcpServerSecretValues,
   observeClaudeMcpInit,
   writeClaudeMcpConfig,
@@ -31,6 +30,7 @@ import {
   type ObservedMcpServer,
   type SkillSpec,
 } from './agent-capabilities.js'
+import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js'
 import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js'
 import { killChildProcess, spawnDetached } from './process.js'
@@ -108,6 +108,21 @@ export interface SubscriptionRunOptions {
    * carries this job's credentials. Absent ⇒ the CLI's built-in tools only.
    */
   mcpServers?: McpServerSpec[]
+  /**
+   * CODEX ONLY: enable the CLI's built-in `image_gen` tool for this job, and redirect what it
+   * writes into the checkout (see `codex-images.ts`).
+   *
+   * Opt-in per job rather than a property of the image, because the tool bills against the leased
+   * ChatGPT plan at 3-5x an ordinary turn: every non-generating run would pay for a capability it
+   * was never asked for. Set when the dispatch resolved a HARNESS-transport binary generator whose
+   * `harness` is `codex`, which is the one signal that says this step exists to make pictures.
+   *
+   * A no-op under `ambientAuth`: there is no per-run `CODEX_HOME` to write a config into or
+   * redirect, and the alternative — reconfiguring the developer's own `~/.codex` and staging into
+   * their real output directory — is the HOME-global mutation this harness never makes. The
+   * backend states the capability as unavailable there rather than half-enabling it.
+   */
+  generateImages?: boolean
   /**
    * Extra environment for the CLI child, scoped to this job (the tester's secrets, a
    * private-registry npmrc pointer). Merged over the inherited `process.env` at spawn, so the
@@ -1181,52 +1196,23 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
   // this one value rather than one being reconstructed from the other.
   let cumulative: CodexCumulativeUsage | undefined
 
-  // Codex reads its credentials from $CODEX_HOME/auth.json with file-backed
-  // storage. CRITICAL: this home must live OUTSIDE the cloned checkout (`opts.cwd`)
-  // — the blueprint/requirements/conflict-resolver handlers finish with
-  // `git add -A` + push, which would otherwise stage and publish the decrypted
-  // subscription `auth.json` (access + refresh tokens) to the PR branch. An
-  // isolated, per-run temp dir keeps the credential out of the working tree and is
-  // removed in `finally`.
-  //
-  // KNOWN LIMITATION: Codex refreshes its OAuth access token in-place by rewriting
-  // this `auth.json` mid-run. Because the home is a per-run temp dir wiped in
-  // `finally`, that refreshed credential is discarded and never written back to the
-  // pool — there is no write-back path. The stored bundle keeps working as long as
-  // its refresh token stays valid (ChatGPT refresh tokens are long-lived and reused,
-  // not rotated per refresh today), so each run re-refreshes from the same stored
-  // copy; if OpenAI ever rotates refresh tokens on use, a pooled Codex token would
-  // eventually need to be re-connected by the user. Claude OAuth tokens (from
-  // `claude setup-token`) are long-lived and unaffected.
-  // Native (ambient) mode: run the developer's installed `codex` with its OWN login —
-  // no isolated CODEX_HOME, no injected auth.json. Otherwise write the leased credential
-  // to a per-run temp home kept OUTSIDE the checkout (and removed in `finally`).
-  if (!opts.ambientAuth && !opts.subscriptionToken) {
-    throw new Error('codex harness requires a subscription token (or ambientAuth)')
-  }
-  const codexHome = opts.ambientAuth ? undefined : await mkdtemp(join(tmpdir(), 'cf-codex-'))
-  if (codexHome) {
-    await writeFile(join(codexHome, 'auth.json'), opts.subscriptionToken!, { mode: 0o600 })
-    // Tool servers (MCP) ride the SAME per-run config.toml, so they are scoped to this job and
-    // torn down with the home. Under AMBIENT auth there is no per-run home — and writing servers
-    // into the developer's own `~/.codex/config.toml` would outlive the run and race a concurrent
-    // job — so an ambient codex run gets no MCP servers; the backend states them as unavailable
-    // the same way it does for a harness with no MCP client at all.
-    // Registered before the CLI starts, for the same reason the claude path does it: a server that
-    // fails to launch puts its own command line into the stderr tail we keep.
-    if (opts.mcpServers?.length) registerKnownSecrets(mcpServerSecretValues(opts.mcpServers))
-    const mcpToml = opts.mcpServers?.length ? codexMcpConfigToml(opts.mcpServers) : ''
-    await writeFile(
-      join(codexHome, 'config.toml'),
-      `cli_auth_credentials_store = "file"\n${mcpToml ? `\n${mcpToml}` : ''}`,
-      { encoding: 'utf8', mode: 0o600 },
-    )
-  }
+  // The per-run `CODEX_HOME` — the credential, the config and the generated-output redirect — is
+  // a lifecycle of its own, in `codex-home.ts`. Ambient mode answers no home: the developer's
+  // own CLI login, with nothing written and nothing to tear down.
+  const { home: codexHome, images } = await createCodexHome(opts)
 
   // Codex has no system-prompt flag, so fold the composed role + best-practice
   // context into the prompt itself (Claude Code instead rides --append-system-prompt,
   // falling back to this same fold when the prompt overflows argv).
-  const prompt = foldSystemPrompt(opts.systemPrompt, opts.userPrompt)
+  //
+  // An image capability that could NOT be honoured is stated in the same fold, because the
+  // backend's brief has already promised it and only this half knows it is missing. Absent for
+  // every ordinary run, which is byte-for-byte the prompt it composed before.
+  const gap = codexImageGapNote(images)
+  const prompt = foldSystemPrompt(
+    opts.systemPrompt,
+    gap ? `${opts.userPrompt}\n\n${gap}` : opts.userPrompt,
+  )
   // This stream's tool-silence window (see the claude runner for the shape); opened just before
   // the CLI starts and closed in the `finally` below.
   let toolWindow: ToolProgressWindow = NO_TOOL_WINDOW
@@ -1351,17 +1337,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     throw withAgentReport(err, summary, secrets)
   } finally {
     toolWindow.close()
-    if (codexHome) {
-      // Lift the CLI session transcripts (`sessions/`) out for short-lived retention BEFORE the
-      // home is deleted — the credential (`auth.json`) lives at the home root, never in
-      // `sessions/`, so this keeps the debugging artifact without leaking it. Best-effort.
-      await retainSessionTranscripts(codexHome, ['sessions'], {
-        label: 'codex',
-        ...(opts.log ? { log: opts.log } : {}),
-      })
-      // Never leave the decrypted credential on disk past the run.
-      await rm(codexHome, { recursive: true, force: true }).catch(() => {})
-    }
+    if (codexHome) await disposeCodexHome(codexHome, opts, images)
   }
 }
 

package/src/agent-shared.ts

@@ -27,12 +27,14 @@ export function mergeEffort(
 export function agentCapabilities(job: AgentJob): {
   skills?: SkillSpec[]
   mcpServers?: McpServerSpec[]
+  generateImages?: boolean
   referenceScreenshots?: ImageManifestSpec
   designImages?: ImageManifestSpec
 } {
   return {
     ...(job.skills?.length ? { skills: job.skills } : {}),
     ...(job.mcpServers?.length ? { mcpServers: job.mcpServers } : {}),
+    ...(job.generateImages ? { generateImages: true } : {}),
     ...(job.referenceScreenshots ? { referenceScreenshots: job.referenceScreenshots } : {}),
     ...(job.designImages ? { designImages: job.designImages } : {}),
   }

package/src/agent.ts

@@ -12,6 +12,7 @@ import type {
   TestSecretSpec,
 } from './job.js'
 import { standUpFrontend, tearDownFrontend } from './frontend-infra.js'
+import { artifactUploadEnv } from './artifact-upload.js'
 import { configurePackageRegistries } from './package-registries.js'
 import { captureRedactedOutput, redactSecrets, registerKnownSecrets } from './redact.js'
 import {
@@ -317,9 +318,13 @@ export async function handleAgent(job: AgentJob, opts: RunOptions = {}): Promise
     // not the other would be an integration that works or 401s depending on how its step was
     // registered. Per-job env like everything else here — never `process.env`, which the shared
     // native host process makes a cross-job leak.
+    // The platform's own artifact ingest, layered on for EVERY mode for the same reason: which
+    // kinds get the seam is the backend's call (it keys off the kind's declared `ui` image), so a
+    // mode check here would be that decision made twice, in the half that cannot see the registry.
     const scoped = withAgentEnv(opts, {
       ...registryEnv,
       ...secretEnv(job.generatorSecrets),
+      ...artifactUploadEnv(job.artifactUpload),
     })
     if (job.mode === 'preview') return await runPreviewMode(job, scoped)
     return job.mode === 'coding'

package/src/artifact-upload.ts

@@ -0,0 +1,71 @@
+import { registerKnownSecrets } from './redact.js'
+
+// ---------------------------------------------------------------------------
+// The OUTBOUND half of the platform's own artifact seam: where a job that PRODUCES bytes sends
+// them, as the two environment variables the producing prompt already names.
+//
+// The inbound half (`context-manifests.ts`) downloads the artifacts a run was handed. This is the
+// return leg, and it stayed unwired long after its backend was done: `ContainerAgentExecutor` has
+// injected `artifactUpload` into the job body and `harnessArtifactController` has served
+// `POST <proxyBaseUrl>/artifacts/ingest` since the visual-confirmation work, while the harness
+// parsed neither — so the `tester-ui` prompt referenced `ARTIFACT_UPLOAD_URL` at a container where
+// nothing ever set it, and every screenshot a UI run captured was dropped without an error.
+//
+// Deliberately NOT a `switch (agentKind)`: which kinds get the seam is the BACKEND's decision (it
+// keys off the kind's declared `ui` image), and the container's whole job is to pass through what
+// the body carries. A harness-side kind list would be the same decision made twice, in the half
+// that cannot see the registry.
+// ---------------------------------------------------------------------------
+
+/**
+ * Where this job uploads the artifacts it produces, and the credential to do it with.
+ *
+ * The token is the run's EXISTING container session token, not a second credential: the ingest
+ * route authenticates it the same way the LLM proxy does and scopes the stored bytes to that
+ * token's workspace + execution. So a body carrying this grants no reach the job did not already
+ * have, which is why it needs no allow-list of its own beyond the transport check below.
+ */
+export interface ArtifactUploadSpec {
+  /** Absolute http(s) URL of the ingest endpoint. */
+  url: string
+  /** Bearer credential — the run's container session token. */
+  token: string
+}
+
+/** The env var naming the ingest endpoint, as the producing prompts already reference it. */
+export const ARTIFACT_UPLOAD_URL_ENV = 'ARTIFACT_UPLOAD_URL'
+/** The env var carrying the ingest credential. */
+export const ARTIFACT_UPLOAD_TOKEN_ENV = 'ARTIFACT_UPLOAD_TOKEN'
+
+/**
+ * Parse the job body's upload seam, or undefined when absent/unusable.
+ *
+ * The whole spec is dropped when either half is unusable, exactly as `parseImageManifest` drops a
+ * manifest whose transport half is: a URL with no token and a token with no URL are both
+ * an endpoint nothing can call, and the agent is told the capability is absent rather than handed
+ * half of it. Absent is the NORMAL case — only a kind the backend gave a browser image to ever
+ * receives one.
+ */
+export function parseArtifactUpload(value: unknown): ArtifactUploadSpec | 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
+  return { url, token }
+}
+
+/**
+ * Project the seam into the agent's child env, registering the credential for redaction first.
+ *
+ * Returns the env rather than writing `process.env`, for the reason every other per-job value here
+ * does: the native host transport serves every concurrent ambient job from ONE process, so a
+ * global would hand one job's ingest credential to a sibling. Absent spec ⇒ `{}`, which is what
+ * makes the capability's absence visible to the agent as an unset variable (the prompts that use
+ * it already branch on that) rather than as an endpoint that 401s.
+ */
+export function artifactUploadEnv(spec: ArtifactUploadSpec | undefined): Record<string, string> {
+  if (!spec) return {}
+  registerKnownSecrets([spec.token])
+  return { [ARTIFACT_UPLOAD_URL_ENV]: spec.url, [ARTIFACT_UPLOAD_TOKEN_ENV]: spec.token }
+}