@cat-factory/executor-harness 1.110.2 → 1.112.0

package/src/codex-home.ts

@@ -0,0 +1,187 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import {
+  codexMcpConfigToml,
+  mcpServerSecretValues,
+  type McpServerSpec,
+} from './agent-capabilities.js'
+import {
+  GENERATED_BINARY_DIR,
+  stageCodexImages,
+  sweepCodexImages,
+  unstageCodexImages,
+} from './codex-images.js'
+import type { Logger } from './logger.js'
+import { registerKnownSecrets } from './redact.js'
+import { retainSessionTranscripts } from './transcript-retention.js'
+
+// ---------------------------------------------------------------------------
+// The PER-RUN `CODEX_HOME`: everything that is written for one codex job and torn down with it.
+//
+// Extracted from `runCodex`, which had grown past the file-size ratchet: the run loop's own job is
+// streaming and reducing the CLI's events, and this is a distinct concern — a directory with a
+// lifecycle, holding a credential, a config and (now) a redirect for the CLI's generated output.
+//
+// CRITICAL and the reason it is a temp dir rather than anything under the checkout: several
+// handlers finish with `git add -A` + push, so a decrypted `auth.json` inside `opts.cwd` would be
+// published to the PR branch.
+//
+// KNOWN LIMITATION, unchanged by the extraction: codex refreshes its OAuth access token in place by
+// rewriting `auth.json` mid-run, and this home is wiped afterwards, so the refreshed credential is
+// discarded and never written back to the pool. The stored bundle keeps working while its refresh
+// token stays valid (ChatGPT refresh tokens are long-lived and reused, not rotated per refresh
+// today); if that ever changes, a pooled codex token would need re-connecting by its owner. Claude
+// OAuth tokens (from `claude setup-token`) are long-lived and unaffected.
+// ---------------------------------------------------------------------------
+
+/** 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 async function createCodexHome(opts: CodexHomeOptions): Promise<CodexHomeSetup> {
+  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: CodexImageOutcome | undefined): string | undefined {
+  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: string,
+  opts: CodexHomeOptions,
+  images?: CodexImageOutcome,
+): Promise<void> {
+  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/src/codex-images.ts

@@ -0,0 +1,167 @@
+import { lstat, mkdir, readdir, rename, rm, symlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { CONTEXT_DIR, excludeContextDir } from './pi.js'
+import type { Logger } from './logger.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: string,
+  cwd: string,
+  log?: Logger,
+): Promise<boolean> {
+  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: string,
+  cwd: string,
+  log?: Logger,
+): Promise<string[]> {
+  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: string[]
+  try {
+    names = await readdir(source)
+  } catch {
+    return []
+  }
+  const moved: string[] = []
+  // 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: string, log?: Logger): Promise<void> {
+  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/src/job.ts

@@ -29,6 +29,7 @@ import {
   type ImageFileSpec,
   type ImageManifestSpec,
 } from './context-manifests.js'
+import { parseArtifactUpload, type ArtifactUploadSpec } from './artifact-upload.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).
@@ -41,6 +42,9 @@ export type { McpServerSpec, SkillResourceSpec, SkillSpec }
 // `context-manifests.ts`, but they remain job body fields, so this stays the import site.
 export type { ContextFileSpec, ImageFileSpec, ImageManifestSpec }
 
+// The return leg of the same seam, for the same reason (`artifact-upload.ts`).
+export type { ArtifactUploadSpec }
+
 // 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
@@ -737,6 +741,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
@@ -760,6 +775,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
@@ -1226,6 +1251,7 @@ export function parseAgentJob(input: unknown): AgentJob {
     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),
@@ -1270,6 +1296,7 @@ interface ParsedAgentJobParts {
   contextFiles: ReturnType<typeof parseContextFiles>
   referenceScreenshots: ReturnType<typeof parseImageManifest>
   designImages: ReturnType<typeof parseImageManifest>
+  artifactUpload: ReturnType<typeof parseArtifactUpload>
   packageRegistries: ReturnType<typeof parsePackageRegistries>
   skills: ReturnType<typeof parseSkillSpecs>
   mcpServers: ReturnType<typeof parseMcpServerSpecs>
@@ -1329,6 +1356,7 @@ function assembleAgentJob(
     contextFiles,
     referenceScreenshots,
     designImages,
+    artifactUpload,
     packageRegistries,
     skills,
     mcpServers,
@@ -1358,6 +1386,7 @@ function assembleAgentJob(
     ...(contextFiles.length ? { contextFiles } : {}),
     ...(referenceScreenshots ? { referenceScreenshots } : {}),
     ...(designImages ? { designImages } : {}),
+    ...(artifactUpload ? { artifactUpload } : {}),
     ...(packageRegistries.length ? { packageRegistries } : {}),
     ...(skills ? { skills } : {}),
     ...(mcpServers ? { mcpServers } : {}),
@@ -1390,6 +1419,7 @@ function collectOptionalRequestFields(o: Record<string, unknown>): Partial<Agent
     ...(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/src/pi-workspace.ts

@@ -241,6 +241,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
@@ -342,6 +351,11 @@ export async function runAgentInWorkspace(
       ...(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/src/pi.ts

@@ -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'
@@ -337,12 +337,22 @@ export async function materializeContextFiles(
  * 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: string): Promise<void> {
   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).
   }