@cat-factory/executor-harness 1.110.0 → 1.112.0

package/README.md

@@ -148,6 +148,51 @@ workspace once per repair round: a non-empty file already on disk is counted and
 and only a view that MISSED is retried. The per-image ceiling is enforced against the declared
 length and against the stream as it arrives, so an oversized body is refused rather than buffered.
 
+### Uploading what a job PRODUCES
+
+The return leg of the same seam. A job body for a kind the backend gave a browser image to carries
+`artifactUpload: { url, token }`, which the harness surfaces to the agent as `ARTIFACT_UPLOAD_URL`
+/ `ARTIFACT_UPLOAD_TOKEN` — the variables the capturing prompt already names. The token is the run's
+EXISTING container session token, so this grants no reach the job did not already have, and it is
+registered for redaction before it can reach a log.
+
+Which kinds get it is the BACKEND's decision (it keys off the kind's declared `ui` image), so the
+harness passes it through for every mode rather than testing the agent kind: a container-side kind
+list would be the same decision made twice, in the half that cannot see the registry. An unusable
+spec drops the WHOLE seam — a URL with no token is an endpoint nothing can call — and the prompt
+branches on the variable being unset, which is what makes an absent capability visible as manual
+mode rather than as an upload that 401s.
+
+### Generating binaries with the CLI's own tool
+
+Codex ships an `image_gen` tool that works only on ChatGPT subscription auth (an `OPENAI_API_KEY`
+session is routed elsewhere and never offered it). A job body carrying `generateImages: true`
+enables it in the per-run `CODEX_HOME/config.toml` and redirects what it writes.
+
+The redirect is the point. Codex writes to `$CODEX_HOME/generated_images/` and tells the model no
+path for it, and `$CODEX_HOME` is where the run's decrypted subscription credential lives — so
+neither "ask the agent where it saved the file" nor "send the agent to look there" is available.
+Instead `generated_images` is created as a symlink into `.cat-context/binary-output/generated/`
+before the CLI starts, so the file is where the agent was told to look the moment the tool returns,
+with no polling and no race, and `$CODEX_HOME` stays unread. A post-run sweep moves anything a
+failed redirect left behind and NAMES it, because an image that arrived too late to be stored is a
+different fact from a run that generated none.
+
+Opt-in per job because the tool bills the leased ChatGPT plan at several times an ordinary turn.
+
+Unavailable under `ambientAuth`: there is no per-run home to configure or redirect, and
+reconfiguring the developer's own `~/.codex` is the HOME-global mutation this harness never makes.
+Unavailable is not silent — the backend has already composed a brief naming the staging directory,
+so `createCodexHome` reports the gap and one sentence is folded into the prompt saying the tool
+could not be enabled and nothing will appear there. A refused redirect gets its own wording (the
+tool IS on, its output is only unreachable until the post-run sweep), and the teardown report reads
+the same outcome, so a rescued file is never reported as a late arrival when the redirect never
+existed at all.
+
+`generateImages` is also a `/health` capability, so a runner pool on an image that predates it is
+refused rather than run blind: the brief names the staging directory whatever the image does with
+the flag.
+
 ### Skills and tool servers
 
 A job body may carry `skills[]` (procedural playbooks) and `mcpServers[]` (MCP tool servers): the
@@ -211,6 +256,7 @@ under a per-job directory:
 | Tester secrets       | child env                                    | child env (same path: the old `process.env` set/restore is gone)         |
 | Private-registry auth | `~/.npmrc`; cleared when a job has no entries | per-job `.npmrc` + `npm_config_userconfig`, seeded from the developer's; theirs is never written or removed |
 | Repo-sourced Claude Skill | installed into the isolated `CLAUDE_CONFIG_DIR` | not installed: read from the checkout's `.cat-context/skill/`, like codex |
+| Codex image output | redirected out of the per-run `CODEX_HOME` into the checkout | not redirected: no per-run home exists, so the capability is reported unavailable rather than pointed at the developer's own `~/.codex` |
 
 Two consequences worth knowing:
 
@@ -267,6 +313,8 @@ Kimi / DeepSeek) and meters spend. The provider key never enters the container.
 | `src/design-images.ts` | The task's DESIGN PICTURES: downloads the manifest a building job body carries into `.cat-context/design-renders/`, for an agent CLI that can read an image into its turn. Says NOTHING on success (the backend's prompt already names every file and its view) and speaks only to correct that list when a picture is not here, because an agent told to open a file that is absent goes looking for the design rather than for the transfer. |
 | `src/reference-screenshots.ts` | The task's REFERENCE DESIGN images: downloads the manifest a capturing job body carries into `.cat-context/reference-screenshots/` (on the run's own container session token) and composes the prompt block naming each file's view. Best-effort, time-bounded and IDEMPOTENT over the checkout, so a repair round re-costs a stat rather than a transfer. A reference that is not on disk is NAMED to the agent, whether a transfer failed or the backend's cap dropped the view, because on disk an absent file and a screen the design does not have are the same thing. Backend-authored throughout, including the file names. |
 | `src/bootstrap-mode.ts` | The repo-bootstrap MODE: clone-a-reference-or-scaffold → run the agent → refuse to push an empty tree → reinit + force-push to the pre-created target repo. |
+| `src/artifact-upload.ts` | The OUTBOUND half of the artifact seam: parses the body's `artifactUpload` and projects it onto the agent's env as `ARTIFACT_UPLOAD_URL` / `ARTIFACT_UPLOAD_TOKEN`, registering the token for redaction first. Passes through what the body carries and decides nothing: which kinds get the seam is the backend's call. |
+| `src/codex-images.ts` | Codex's own `image_gen` output, staged where the agent can reach it: creates `$CODEX_HOME/generated_images` as a symlink into `.cat-context/binary-output/generated/` before the CLI starts, sweeps anything a failed redirect left behind, and unlinks (never follows) the redirect at teardown — a failed unlink is REPORTED, because that unlink is what stops the recursive delete reaching the checkout. Exists because codex exposes no path for what it generated AND `$CODEX_HOME` holds the run's decrypted credential, so neither asking the agent nor sending it there is available. |
 | `src/agent-shared.ts` | The few helpers every agent MODE shares (effort-report folding, the capability fields forwarded to `runAgentInWorkspace`). |
 | `src/logger.ts`    | Structured logging.                                                                                     |
 

package/dist/agent-capabilities.js

@@ -241,7 +241,12 @@ export function parseSkillSpecs(value) {
  * 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 = ['mcpServers', 'skills', 'designImages'];
+export const HARNESS_BODY_CAPABILITIES = [
+    'mcpServers',
+    'skills',
+    'designImages',
+    'generateImages',
+];
 /**
  * A safe MCP server id: it becomes a tool-name fragment AND a TOML table key.
  *

package/dist/agent-runner.d.ts

@@ -48,6 +48,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

package/dist/agent-runner.js

@@ -8,7 +8,8 @@ import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js'
 import { log } from './logger.js';
 import { NO_TOOL_WINDOW } from './tool-silence.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
-import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { claudeAllowedToolPatterns, mcpServerSecretValues, observeClaudeMcpInit, writeClaudeMcpConfig, } from './agent-capabilities.js';
+import { codexImageGapNote, createCodexHome, disposeCodexHome } from './codex-home.js';
 import { ProgressGuard } from './progress-guard.js';
 import { BoundedTail, JsonlLineReader } from './jsonl-stream.js';
 import { killChildProcess, spawnDetached } from './process.js';
@@ -892,48 +893,19 @@ export async function runCodex(opts) {
     // weight — while the fallback call metric below needs the split, so both are derived from
     // this one value rather than one being reconstructed from the other.
     let cumulative;
-    // 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 = NO_TOOL_WINDOW;
@@ -1041,17 +1013,8 @@ export async function runCodex(opts) {
     }
     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/dist/agent-shared.d.ts

@@ -16,6 +16,7 @@ export declare function mergeEffort(result: AgentResult, effortReport: EffortRep
 export declare function agentCapabilities(job: AgentJob): {
     skills?: SkillSpec[];
     mcpServers?: McpServerSpec[];
+    generateImages?: boolean;
     referenceScreenshots?: ImageManifestSpec;
     designImages?: ImageManifestSpec;
 };

package/dist/agent-shared.js

@@ -20,6 +20,7 @@ export function agentCapabilities(job) {
     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/dist/agent.js

@@ -4,6 +4,7 @@ import { mkdir, mkdtemp, rm } from 'node:fs/promises';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 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 { cloneRepo, commitAll, conflictDiff, fetchPullRequestHead, fetchReferenceBranches, headCommit, mergeBranch, prepareExistingCheckout, pushBranch, unmergedPaths, } from './git.js';
@@ -18,6 +19,7 @@ import { agentCapabilities, mergeEffort } from './agent-shared.js';
 import { runBootstrap } from './bootstrap-mode.js';
 import { acquireRepoCheckout, agentNeverActed, agentOutputTail, NEVER_ACTED_CAUSE, runAgentInWorkspace, unusableFinalAnswerCause, withWorkspace, } from './pi-workspace.js';
 import { diagnosticsSuffix, resolveStructuredOutput, } from './structured-output.js';
+import { extractJsonObject } from './json-reply.js';
 import { log } from './logger.js';
 // The single generic agent handler — the manifest-driven replacement for the bespoke
 // per-kind handlers. It runs an LLM over an optional checkout and returns text/JSON
@@ -194,23 +196,6 @@ async function resolveReplyCustom(job, summary, signal) {
     });
     return { value: resolved.value, diagnostics: resolved.diagnostics };
 }
-/** Extract the first JSON object from an agent's final message (tolerating fences/prose). */
-function extractJsonObject(text) {
-    const trimmed = text.trim();
-    const fenced = /^```(?:json)?\s*([\s\S]*?)\s*```$/i.exec(trimmed);
-    const body = fenced ? (fenced[1] ?? '') : trimmed;
-    try {
-        return JSON.parse(body);
-    }
-    catch {
-        const start = body.indexOf('{');
-        const end = body.lastIndexOf('}');
-        if (start === -1 || end === -1 || end <= start) {
-            throw new Error('agent did not return a JSON object');
-        }
-        return JSON.parse(body.slice(start, end + 1));
-    }
-}
 /**
  * The service work directory for a checkout at `dir`: the monorepo service subtree
  * (`repo.serviceDirectory`, created if missing) when the job is service-scoped, else the clone
@@ -256,9 +241,13 @@ export async function handleAgent(job, opts = {}) {
         // 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);

package/dist/artifact-upload.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const ARTIFACT_UPLOAD_URL_ENV = "ARTIFACT_UPLOAD_URL";
+/** The env var carrying the ingest credential. */
+export declare 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 declare function parseArtifactUpload(value: unknown): ArtifactUploadSpec | undefined;
+/**
+ * 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 declare function artifactUploadEnv(spec: ArtifactUploadSpec | undefined): Record<string, string>;

package/dist/artifact-upload.js

@@ -0,0 +1,39 @@
+import { registerKnownSecrets } from './redact.js';
+/** 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) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const o = value;
+    const url = typeof o.url === 'string' ? o.url.trim() : '';
+    const token = typeof o.token === 'string' ? o.token : '';
+    if (!url || !token || !/^https?:\/\//i.test(url))
+        return undefined;
+    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) {
+    if (!spec)
+        return {};
+    registerKnownSecrets([spec.token]);
+    return { [ARTIFACT_UPLOAD_URL_ENV]: spec.url, [ARTIFACT_UPLOAD_TOKEN_ENV]: spec.token };
+}

package/dist/codex-home.d.ts

@@ -0,0 +1,79 @@
+import { type McpServerSpec } from './agent-capabilities.js';
+import type { Logger } from './logger.js';
+/** What one codex job needs written into its own home. */
+export interface CodexHomeOptions {
+    /** The decrypted `auth.json` bundle. Required unless `ambientAuth`. */
+    subscriptionToken?: string;
+    /** Run the developer's own CLI login instead: no isolated home, nothing written. */
+    ambientAuth?: boolean;
+    /** Tool servers to scope to this job's config. */
+    mcpServers?: McpServerSpec[];
+    /** Enable the CLI's built-in image tool and redirect its output into the checkout. */
+    generateImages?: boolean;
+    /** The checkout, which is where generated output is staged to. */
+    cwd: string;
+    log?: Logger;
+}
+/**
+ * What became of the image capability a job asked for, so the run can SAY so.
+ *
+ * Its own value rather than a boolean, because the two failures need different words and the
+ * teardown report needs to tell them apart: an image found in the home afterwards is a LATE
+ * arrival when the redirect was live, and a file that was never reachable at all when it was not.
+ */
+export type CodexImageOutcome = 
+/** The redirect is in place: the agent reads what the tool writes, the moment it writes it. */
+{
+    state: 'staged';
+}
+/** Enabled nowhere: an ambient run has no per-run home to configure or redirect. */
+ | {
+    state: 'unavailable';
+    reason: 'ambient-home';
+}
+/** The tool is on and its output goes somewhere the agent cannot reach during the run. */
+ | {
+    state: 'unavailable';
+    reason: 'redirect-refused';
+};
+/** This job's `CODEX_HOME` (absent for an ambient run) and what its image capability came to. */
+export interface CodexHomeSetup {
+    home?: string;
+    /** Absent when the job asked for no image generation. */
+    images?: CodexImageOutcome;
+}
+/**
+ * Create and populate this job's `CODEX_HOME`, or answer no home for an ambient run.
+ *
+ * Ambient mode writes nothing deliberately: there is no per-run home, so there is nowhere to put
+ * MCP servers (writing them into the developer's own `~/.codex/config.toml` would outlive the run
+ * and race a concurrent job) and nowhere to redirect generated images.
+ *
+ * What it does NOT do is drop the image capability quietly. The backend composed a brief naming
+ * the staging directory and told the agent to collect from it, so an ambient run with the tool
+ * silently off leaves the agent hunting for files nothing wrote and reporting a vendor problem
+ * for a configuration one. The outcome comes back so the caller can state it, which is what the
+ * brief's own "if the tool is unavailable, say so" instruction exists to be paired with.
+ */
+export declare function createCodexHome(opts: CodexHomeOptions): Promise<CodexHomeSetup>;
+/**
+ * What to TELL THE AGENT when the image capability it was briefed on is not there, or undefined
+ * when there is nothing to say.
+ *
+ * Appended to the user prompt rather than left to the backend, because only this half knows: the
+ * backend resolved a harness-served generator and composed a brief naming the staging directory,
+ * and whether that directory can be written to is decided here, one process later. Silence is the
+ * one answer that is never right — it reads to the agent exactly like a working tool that returned
+ * nothing.
+ */
+export declare function codexImageGapNote(images: CodexImageOutcome | undefined): string | undefined;
+/**
+ * Tear the home down: rescue anything generated, keep the transcripts, delete the credential.
+ *
+ * ORDER is load-bearing. The image sweep runs first because the files are about to be deleted with
+ * the home; the redirect is unlinked next so the recursive delete cannot follow it into the
+ * checkout; the transcripts are lifted before the delete (the credential lives at the home ROOT,
+ * never in `sessions/`, which is what makes that safe); and the delete is last, because nothing
+ * else may leave a decrypted credential on disk past the run.
+ */
+export declare function disposeCodexHome(codexHome: string, opts: CodexHomeOptions, images?: CodexImageOutcome): Promise<void>;

package/dist/codex-home.js

@@ -0,0 +1,109 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { codexMcpConfigToml, mcpServerSecretValues, } from './agent-capabilities.js';
+import { GENERATED_BINARY_DIR, stageCodexImages, sweepCodexImages, unstageCodexImages, } from './codex-images.js';
+import { registerKnownSecrets } from './redact.js';
+import { retainSessionTranscripts } from './transcript-retention.js';
+/**
+ * Create and populate this job's `CODEX_HOME`, or answer no home for an ambient run.
+ *
+ * Ambient mode writes nothing deliberately: there is no per-run home, so there is nowhere to put
+ * MCP servers (writing them into the developer's own `~/.codex/config.toml` would outlive the run
+ * and race a concurrent job) and nowhere to redirect generated images.
+ *
+ * What it does NOT do is drop the image capability quietly. The backend composed a brief naming
+ * the staging directory and told the agent to collect from it, so an ambient run with the tool
+ * silently off leaves the agent hunting for files nothing wrote and reporting a vendor problem
+ * for a configuration one. The outcome comes back so the caller can state it, which is what the
+ * brief's own "if the tool is unavailable, say so" instruction exists to be paired with.
+ */
+export async function createCodexHome(opts) {
+    if (!opts.ambientAuth && !opts.subscriptionToken) {
+        throw new Error('codex harness requires a subscription token (or ambientAuth)');
+    }
+    if (opts.ambientAuth) {
+        return opts.generateImages ? { images: { state: 'unavailable', reason: 'ambient-home' } } : {};
+    }
+    const codexHome = await mkdtemp(join(tmpdir(), 'cf-codex-'));
+    await writeFile(join(codexHome, 'auth.json'), opts.subscriptionToken, { mode: 0o600 });
+    // 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) : '';
+    // `image_generation` is OPT-IN per job rather than always-on: the tool bills the leased ChatGPT
+    // plan at 3-5x an ordinary turn, so every non-generating run would pay for a capability it was
+    // never asked for. Enabled only when the dispatch selected a harness-served generator, which is
+    // the one thing that knows the step exists to make pictures.
+    const imagesToml = opts.generateImages ? '\n[features]\nimage_generation = true\n' : '';
+    await writeFile(join(codexHome, 'config.toml'), `cli_auth_credentials_store = "file"\n${mcpToml ? `\n${mcpToml}` : ''}${imagesToml}`, { encoding: 'utf8', mode: 0o600 });
+    if (!opts.generateImages)
+        return { home: codexHome };
+    // Redirect the tool's output into the checkout BEFORE the CLI starts, so the agent never has to
+    // read this directory (which holds the decrypted credential) to find what it generated. The
+    // answer is KEPT rather than discarded: a refused redirect leaves the tool enabled and its
+    // output unreachable until the post-run sweep, which is a different fact from a live one and
+    // the difference the teardown report would otherwise get wrong.
+    const staged = await stageCodexImages(codexHome, opts.cwd, opts.log);
+    return {
+        home: codexHome,
+        images: staged ? { state: 'staged' } : { state: 'unavailable', reason: 'redirect-refused' },
+    };
+}
+/**
+ * What to TELL THE AGENT when the image capability it was briefed on is not there, or undefined
+ * when there is nothing to say.
+ *
+ * Appended to the user prompt rather than left to the backend, because only this half knows: the
+ * backend resolved a harness-served generator and composed a brief naming the staging directory,
+ * and whether that directory can be written to is decided here, one process later. Silence is the
+ * one answer that is never right — it reads to the agent exactly like a working tool that returned
+ * nothing.
+ */
+export function codexImageGapNote(images) {
+    if (!images || images.state === 'staged')
+        return undefined;
+    const shared = `Nothing will appear in \`${GENERATED_BINARY_DIR}/\` while you are working. Report the ` +
+        `artifacts you could not produce, exactly as your instructions for an unavailable generation ` +
+        `tool describe, and do not substitute another generator or describe an image you did not make.`;
+    return images.reason === 'ambient-home'
+        ? `NOTE: this run's built-in image generation tool could NOT be enabled. It needs an isolated ` +
+            `per-run CLI home, and this run uses the host's own CLI login, which is not reconfigured ` +
+            `for a job. ${shared}`
+        : `NOTE: this run's built-in image generation tool is enabled, but its output could NOT be ` +
+            `redirected into the checkout, so anything it writes lands somewhere you cannot read. ` +
+            `${shared}`;
+}
+/**
+ * Tear the home down: rescue anything generated, keep the transcripts, delete the credential.
+ *
+ * ORDER is load-bearing. The image sweep runs first because the files are about to be deleted with
+ * the home; the redirect is unlinked next so the recursive delete cannot follow it into the
+ * checkout; the transcripts are lifted before the delete (the credential lives at the home ROOT,
+ * never in `sessions/`, which is what makes that safe); and the delete is last, because nothing
+ * else may leave a decrypted credential on disk past the run.
+ */
+export async function disposeCodexHome(codexHome, opts, images) {
+    if (opts.generateImages) {
+        const stranded = await sweepCodexImages(codexHome, opts.cwd, opts.log);
+        if (stranded.length > 0) {
+            // REPORTED rather than quietly rescued: an image that arrived too late for the agent to
+            // store is a different fact from a run that generated none.
+            //
+            // And WHICH fact depends on what the setup came to, which is why the outcome is threaded in
+            // rather than inferred here. With a live redirect these really are late arrivals (the CLI
+            // wrote after the agent's last turn); with a refused one they were never reachable at all,
+            // and calling those "late" points the next reader at the model instead of at the filesystem.
+            opts.log?.warn(images?.state === 'unavailable'
+                ? 'generated images were rescued after the run: the output redirect was never in place'
+                : 'generated images were staged after the agent finished', { count: stranded.length, dir: GENERATED_BINARY_DIR });
+        }
+        await unstageCodexImages(codexHome, opts.log);
+    }
+    await retainSessionTranscripts(codexHome, ['sessions'], {
+        label: 'codex',
+        ...(opts.log ? { log: opts.log } : {}),
+    });
+    await rm(codexHome, { recursive: true, force: true }).catch(() => { });
+}

package/dist/codex-images.d.ts

@@ -0,0 +1,52 @@
+import type { Logger } from './logger.js';
+/**
+ * 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 declare const GENERATED_BINARY_SUBDIR = "binary-output/generated";
+/** The staging directory's repo-relative path, as the prompt names it. */
+export declare const GENERATED_BINARY_DIR = ".cat-context/binary-output/generated";
+/**
+ * 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 declare function stageCodexImages(codexHome: string, cwd: string, log?: Logger): Promise<boolean>;
+/**
+ * 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 declare function sweepCodexImages(codexHome: string, cwd: string, log?: Logger): Promise<string[]>;
+/**
+ * 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 declare function unstageCodexImages(codexHome: string, log?: Logger): Promise<void>;