Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

37.2 KB
Raw Blame
import { createMediaJobPreparation } from '../../lib/mediaJobPreparation.js';
import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
/**
 * Image Gen — Codex CLI provider.
 *
 * Routes image generation through the user's locally-installed `codex` CLI
 * (https://github.com/openai/codex). Codex's bundled `imagegen` skill runs
 * the built-in `image_gen` tool when the prompt starts with `$imagegen` and
 * uses the user's logged-in Codex session — no OPENAI_API_KEY required.
 *
 * Wire format: `codex exec --skip-git-repo-check --sandbox workspace-write
 * '$imagegen <prompt>'`. Codex prints a `session id: <uuid>` banner on stderr
 * and usually writes the final PNG to
 * `~/.codex/generated_images/<session-id>/*.png` (`ig_*.png` historically;
 * newer builds use `exec-*.png`). Other Codex builds can keep the image bytes
 * only in the session JSONL's `image_generation_end` event, so we parse the
 * banner and harvest both locations after the child exits.
 *
 * The user must explicitly enable this provider in Settings → Image Gen
 * because not every Codex account has access to the `image_gen` tool. When
 * disabled the dispatcher rejects up front; this module assumes it's enabled
 * by the time generateImage() is called.
 *
 * Each child runs in an owned temporary workspace. Only the Codex generated
 * image directory and image-generation session events are harvested; scratch
 * drawings are never accepted. Missing tool events do not prove an account
 * lacks image generation, so diagnostics distinguish observation from capability.
 */

import { spawn } from '../../lib/childProcess.js';
import { bufferedSpawn, prepareCliSpawn, killProcessTree } from '../../lib/bufferedSpawn.js';
import { readFile, readdir, stat, mkdtemp } from 'fs/promises';
import { existsSync } from 'fs';
import { basename, join, isAbsolute, resolve, sep } from 'path';
import { tmpdir } from 'os';
import { codexHomeDir } from '../../lib/codexUserConfig.js';
import { withSpawnCwdEnv } from '../../lib/spawnCwd.js';
import { withoutServerSecretsEnv } from '../../lib/processEnv.js';

// Codex's own ambient credentials; everything else server-held is withheld.
const CODEX_AUTH_ENV_KEYS = ['OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE'];
import { maintenance } from '../../lib/maintenanceAdmission.js';
import { noFabricationClause } from './fabricationGuard.js';
import { randomUUID } from 'crypto';
import { atomicWrite, copyFileGuarded, ensureDir, PATHS, sleep, unlinkGuarded, rmGuarded } from '../../lib/fileUtils.js';
import { ServerError } from '../../lib/errorHandler.js';
import { autoCleanGeneratedImage } from '../../lib/imageClean.js';
import { imageGenEvents } from '../imageGenEvents.js';
import { broadcastSse, attachSseClient as attachSse, closeJobAfterDelay, createJobFailureFinalizer, dispatchTerminalEvent } from '../../lib/sseUtils.js';
import { killWithEscalation } from '../../lib/killWithEscalation.js';
import { codexDriverReportedTokens, recordCodexRender } from '../imageRenderUsage.js';
import { renderTimingFields } from '../../lib/renderTiming.js';
import { buildCodexStartupArgs, buildEffortArgs, resolveCliEffort } from '../../lib/providerModels.js';
import {
  IMAGE_GEN_MODE, CODEX_IMAGEGEN_DEFAULT_MODEL, CODEX_IMAGEGEN_DEFAULT_EFFORT,
  describeFidelity, visualReferenceRole,
} from './modes.js';
import { buildNoImageReason } from './noImageReason.js';
import { rejectDegenerateFrame } from './frameGuard.js';
import { conformImageAspect } from './aspectConform.js';
import { aspectRatioPhrase } from '../../lib/aspectRatio.js';
import { resolveInputImages } from './inputImages.js';
import { cloudPromptRequired } from './cloudProviderConfig.js';
import { agentInstructionsAddition, carriedPromptAdditions, sentPromptRecord } from '../../lib/modelInput.js';

// 20 minutes — built-in `image_gen` typically returns in 30–90s, but with the
// parallel codex lane several renders share OpenAI throughput and a single
// generation can easily push past 5 minutes (xhigh reasoning, queued model,
// or an over-subscribed batch). Env-overridable for power users who want a
// tighter cap. Bigger than the SD-API timeout because there's no progress
// signal to short-circuit early on. Keep this in rough sync with
// WATCHDOG_CODEX_MS in mediaJobQueue/index.js so the queue's watchdog and
// the child's wall-clock cap fire on a similar budget.
const CODEX_TIMEOUT_MS = (() => {
  const n = Number(process.env.CODEX_TIMEOUT_MS);
  return Number.isFinite(n) && n > 0 ? n : 20 * 60 * 1000;
})();

const DEFAULT_BIN = 'codex';
const DEFAULT_HARVEST_TIMEOUT_MS = 5000;
let harvestTimeoutMs = DEFAULT_HARVEST_TIMEOUT_MS;

const codexImagesDir = (sessionId) =>
  join(codexHomeDir(), 'generated_images', sessionId);
const codexSessionsDir = () => join(codexHomeDir(), 'sessions');

// Cache evidence only changes PortOS's default, never an explicit selection.
async function resolveCodexDriverModel(model, modelIsShippedDefault) {
  const explicit = typeof model === 'string' && model.trim();
  if (explicit && !modelIsShippedDefault) return explicit;
  const preferred = CODEX_IMAGEGEN_DEFAULT_MODEL;
  let listed;
  try {
    const path = join(codexHomeDir(), 'models_cache.json');
    if ((await stat(path)).size > 2 * 1024 * 1024) return preferred;
    const cache = JSON.parse(await readFile(path, 'utf8'));
    if (!Array.isArray(cache.models)) return preferred;
    listed = new Set(cache.models.filter(item => item?.visibility === 'list' && typeof item.slug === 'string').map(item => item.slug));
  } catch { /* Missing or unreadable cache provides no model availability evidence. */ }
  if (!listed?.size || listed.has(preferred)) return preferred;
  const fallback = ['gpt-5.6-luna', 'gpt-5.6-terra'].find(id => listed.has(id));
  if (fallback) {
    console.log(`🔀 Codex image default ${preferred} is not listed in the local model cache; using ${fallback}`);
    return fallback;
  }
  throw new ServerError('The local Codex model cache lists no supported low-cost image-generation driver default. Select an available model explicitly in Settings → Image Gen.', { status: 400 });
}

// Per-job state — keyed by jobId so multiple codex renders can run in
// parallel under the mediaJobQueue's configurable lane limit. Same client
// shape as imageGen/local.js so attachSseClient/broadcastSse just work.
const jobs = new Map();
const activeProcs = new Map();
const activeJobs = new Map();

// Returns the most-recently-started job — used by status surfaces and the
// settings test-render; not safe for cancel routing under parallel use.
export const getActiveJob = () => {
  const entries = [...activeJobs.values()];
  return entries.length ? entries[entries.length - 1] : null;
};

export const attachSseClient = (jobId, res) => attachSse(jobs, jobId, res);

const sigtermWithEscalation = (id, proc) => {
  if (process.platform === 'win32') {
    // The cmd.exe wrapper owns a Codex descendant: terminate the whole tree.
    killProcessTree(proc);
    return;
  }
  killWithEscalation(proc, { label: 'codex child', delayMs: 5000, stillRunning: () => activeProcs.get(id) === proc });
};

// Cancel one specific codex render. jobId is required — with parallel codex
// renders an "anonymous cancel" is genuinely destructive (would nuke every
// in-flight render), so callers have to be explicit. Use `cancelAll()` for
// the legacy "stop everything" path that the imageGen.cancel() dispatcher
// wires up.
const preparations = createMediaJobPreparation();

export const cancel = (jobId) => {
  if (!jobId) {
    throw new Error("codex.cancel requires a jobId — use codex.cancelAll() to terminate every in-flight render");
  }
  const pending = preparations.cancel(jobId);
  if (pending) return pending;
  const proc = activeProcs.get(jobId);
  if (!proc) return false;
  sigtermWithEscalation(jobId, proc);
  return true;
};

// Bulk terminate every in-flight codex render. Only used by the imageGen
// dispatcher's "cancel everything" route — the per-job mediaJobQueue path
// always passes a specific jobId to `cancel()`.
export const cancelAll = () => {
  const ids = [...preparations.ids(), ...activeProcs.keys()];
  if (ids.length === 0) return false;
  for (const id of ids) cancel(id);
  return true;
};

export async function checkConnection({ codexPath } = {}) {
  // Cheap probe: spawn `codex --version`. Avoids actually invoking image_gen
  // (which would consume the user's Codex quota); the settings UI just wants
  // "yes the binary exists and is reachable".
  const bin = codexPath || DEFAULT_BIN;
  const prepared = prepareCliSpawn(bin, ['--version']);
  const result = await bufferedSpawn(prepared.command, prepared.args, {
    timeoutMs: 15_000, shell: false, env: withoutServerSecretsEnv(process.env, { keep: CODEX_AUTH_ENV_KEYS }),
  });
  if (result.error) {
    return { connected: false, mode: IMAGE_GEN_MODE.CODEX, reason: `Codex CLI not found (${result.error.message})` };
  }
  if (result.timedOut) {
    return { connected: false, mode: IMAGE_GEN_MODE.CODEX, reason: 'codex --version timed out' };
  }
  if (result.code !== 0) {
    return { connected: false, mode: IMAGE_GEN_MODE.CODEX, reason: `codex --version exited ${result.code}` };
  }
  const out = `${result.stdout}${result.stderr}`;
  const versionMatch = out.match(/codex-cli\s+([\d.]+)/i) || out.match(/(\d+\.\d+\.\d+)/);
  return { connected: true, mode: IMAGE_GEN_MODE.CODEX, model: versionMatch ? `codex-cli ${versionMatch[1]}` : 'codex-cli' };
}

const SESSION_ID_RE = /^session id:\s*([0-9a-f-]{36})/im;


/**
 * The `$imagegen` directive describing however many images are attached.
 *
 * Codex's `image_gen` tool takes `referenced_image_paths` — an ARRAY of
 * references (probed 2026-08-09) — so an init image and the reference slots are
 * the same kind of thing to the tool; only the wording differs. The init image
 * leads and gets the fidelity phrase (`initImageStrength` mapped via
 * describeFidelity — codex CLI exposes no numeric denoise knob); the rest are
 * named as additional visual references so the model doesn't try to edit all of
 * them at once.
 */
export function buildCodexAttachmentPrefix({ initPath, referenceCount, initImageStrength }) {
  if (initPath) {
    // Single attachment keeps the wording it has always shipped with; naming a
    // position only makes sense once there is more than one to disambiguate.
    const subject = referenceCount > 0 ? 'the FIRST attached image' : 'the attached reference image';
    const refs = referenceCount > 0
      ? ` Use the other ${referenceCount === 1 ? 'attached image' : `${referenceCount} attached images`} as ${visualReferenceRole(referenceCount)}.`
      : '';
    return `Edit ${subject} — ${describeFidelity(initImageStrength)}.${refs} Render target:\n`;
  }
  if (referenceCount > 0) {
    const subject = referenceCount === 1 ? 'the attached image' : `all ${referenceCount} attached images`;
    return `Generate a new image conditioned on ${subject} — use ${referenceCount === 1 ? 'it' : 'them'} as ${visualReferenceRole(referenceCount)}. Render target:\n`;
  }
  return '';
}

/**
 * The exact message `codex exec` receives and the record of what PortOS added
 * to the user's prompt (#11317). Shared by the render and the compose preview.
 */
export function codexSentPrompt({ prompt = '', negativePrompt, width, height, inputImages, initImageStrength, promptAdditions = [] }) {
  // Width/height/negative aren't first-class args for Codex's built-in
  // image_gen tool — pass them as natural-language hints inside the prompt.
  // Codex's imagegen skill is prompt-driven; the model decides resolution.
  // gpt-image-2 supports up to 4K output; the "(high quality)" suffix
  // pushes it off its 1024 default toward whatever native size best fits
  // the requested aspect ratio.
  // The ratio is named as well as the pixels: a bare "(1672x941)" left the
  // model free to return a square close-up, so the frame is also conformed
  // after harvest (aspectConform.js) — the hint just makes that crop rarer.
  const ratioPhrase = (width && height) ? aspectRatioPhrase(Number(width), Number(height)) : '';
  const sizeHint = (width && height) ? ` (${ratioPhrase ? `${ratioPhrase} frame, ` : ''}${width}x${height})` : '';
  const qualityHint = (width >= 1536 || height >= 1536) ? ' (high quality)' : '';
  const avoidHint = negativePrompt?.trim() ? `\nAvoid: ${negativePrompt.trim()}` : '';
  const editPrefix = buildCodexAttachmentPrefix({
    initPath: inputImages.initPath,
    referenceCount: inputImages.referencePaths.length,
    initImageStrength,
  });
  const buildWith = (text) => `$imagegen ${editPrefix}${text.trim()}${sizeHint}${qualityHint}${avoidHint}`;
  const fullPrompt = buildWith(prompt) + '\n' + noFabricationClause('image_gen');
  return {
    fullPrompt,
    record: sentPromptRecord({ sentPrompt: fullPrompt, carried: carriedPromptAdditions({ promptAdditions }),
      added: [agentInstructionsAddition('Codex image tool instructions', text => buildWith(text) + '\n' + noFabricationClause('image_gen'))] }),
  };
}

// Input images are attached via codex CLI's `-i <FILE>` flag (variadic, so all
// of them ride one flag) and the prompt is reshaped so the `$imagegen` skill
// feeds the attachments to `image_gen` as references.
export const generateImage = (params) => preparations.run(params, generateImagePrepared);

async function generateImagePrepared({
  promptAdditions = [],
  codexPath, model, modelIsShippedDefault = false, effort, prompt = '', width, height, negativePrompt,
  initImagePath, initImageStrength, referenceImagePaths = [],
  visualConditioning = null,
  jobId: providedJobId = null,
  cleanC2PA = false,
  denoise = false,
}) {
  // The ingestion instant `renderTimingFields` measures from — the queue calls
  // generateImage the moment it picks this job up. See lib/renderTiming.js.
  const renderStartedAtMs = Date.now();
  await ensureDir(PATHS.images);

  // Ship the cheap gpt-6-luna / low-effort path by default (see modes.js).
  // A caller-supplied model/effort (an explicit Settings → Image Gen override,
  // threaded through the dispatcher) wins; `null`/`''`/absent falls back to the
  // shipped default so a bare install never runs Codex's heaviest tier.
  const effectiveModel = await resolveCodexDriverModel(model, modelIsShippedDefault);
  // Validate the effort against the known codex levels before use: an
  // unrecognized non-empty value (a hand-edited settings.json / the unvalidated
  // settings PUT) would otherwise pass through, buildEffortArgs would emit no
  // override for it, and the child would silently inherit Codex's own configured
  // effort instead of the promised cheap `low` default. Fall back to the default
  // so the low-effort guarantee holds even for garbage input.
  // `resolveCliEffort` (rather than a bare `CODEX_EFFORT_LEVELS.includes`) so a
  // legacy `ultra` value resolves to Codex's strongest supported level instead
  // of collapsing to the cheap default and silently rendering at a fraction of
  // the requested effort. `effectiveModel` is threaded through because Codex's
  // ladder is MODEL-gated in both directions: it decides whether `ultra` is a
  // real level here, and whether `minimal` is — a gpt-6 model rejects `minimal`
  // outright (HTTP 400), so an unclamped legacy value would fail the render.
  const requestedEffort = (typeof effort === 'string' && effort.trim()) ? effort.trim() : CODEX_IMAGEGEN_DEFAULT_EFFORT;
  const effectiveEffort = resolveCliEffort(requestedEffort, { command: 'codex' }, effectiveModel)
    || CODEX_IMAGEGEN_DEFAULT_EFFORT;

  // Re-anchors every path to the approved image roots and caps the list at what
  // codex's image_gen accepts — see inputImages.js.
  const inputImages = resolveInputImages({
    mode: IMAGE_GEN_MODE.CODEX, initImagePath, referenceImagePaths,
  });

  // An empty prompt is fine when an image is attached (the attachment is the
  // instruction); a pure text-to-image codex render still needs a prompt. The
  // per-provider rule lives on the provider spec — see cloudPromptRequired.
  if (cloudPromptRequired(IMAGE_GEN_MODE.CODEX, inputImages.paths.length > 0) && !prompt?.trim()) {
    throw new ServerError('Prompt is required', { status: 400, code: 'VALIDATION_ERROR' });
  }

  const jobId = providedJobId || randomUUID();
  const filename = `${jobId}.png`;
  const outputPath = join(PATHS.images, filename);

  const { fullPrompt, record: sentRecord } = codexSentPrompt({
    prompt, negativePrompt, width, height, inputImages, initImageStrength, promptAdditions,
  });

  const bin = codexPath || DEFAULT_BIN;
  // `codex exec` treats `-i, --image <FILE>...` as VARIADIC, so it greedily
  // swallows every following positional — including the prompt — when no other
  // flag interrupts it. That left codex with no positional prompt; it then read
  // stdin (ignored here) and died with "No prompt provided". A `--` terminator
  // after the options bounds the variadic so the prompt lands as the positional.
  const args = [
    'exec',
    '--skip-git-repo-check',
    '--sandbox', 'workspace-write',
    // Disable codex's startup update check (see buildCodexStartupArgs) so an
    // image-gen call never spends startup time on the update-check round-trip
    // or an unattended `brew upgrade`. Placed before the variadic `-i` so it
    // can't be swallowed as an image path.
    ...buildCodexStartupArgs(),
    // Reasoning-effort override (`-c model_reasoning_effort=<level>`), defaulting
    // to `low` — also before the variadic `-i`. A user who baked an effort pin
    // into their config is respected via hasEffortFlag inside buildEffortArgs.
    ...buildEffortArgs(effectiveEffort, { command: 'codex' }, [], effectiveModel),
    // `-i` is variadic, so every input image rides one flag.
    ...(inputImages.paths.length ? ['-i', ...inputImages.paths] : []),
    '-m', effectiveModel,
    ...(inputImages.paths.length ? ['--'] : []),
    fullPrompt,
  ];

  const meta = {
    id: jobId, prompt: prompt.trim(), negativePrompt: negativePrompt || '',
    width: width ? Number(width) : null, height: height ? Number(height) : null,
    filename, mode: IMAGE_GEN_MODE.CODEX, model: effectiveModel,
    inputProvenance: 'provider-inputs',
    initImageFilename: inputImages.initPath ? basename(inputImages.initPath) : null,
    referenceImageFilenames: inputImages.referencePaths.map(path => basename(path)),
    ...(visualConditioning ? { visualConditioning } : {}),
    ...sentRecord,
    createdAt: new Date().toISOString(),
  };
  // Per-render scratch cwd for the child (#11734). Rooted at the OS temp dir —
  // the same pattern every other ephemeral PortOS workspace uses, including the
  // sibling Codex text turn in `services/codexAppServer.js`. Deliberately NOT a
  // `PATHS` entry: `PATHS` names durable, documented directories under the
  // install root that backup and federation reason about, and this one is
  // created per render and removed when the job settles. An earlier revision
  // read `PATHS.tmp`, which has never existed on the object — `ensureDir`
  // received `undefined` and every Codex render died here before spawning.
  const scratchDir = await mkdtemp(join(tmpdir(), 'portos-codex-image-'));
  const job = { ...meta, clients: [], status: 'running', renderStartedAtMs };
  try {
    jobs.set(jobId, job);

    console.log(`🎨 Generating image [${jobId.slice(0, 8)}] codex`);
    imageGenEvents.emit('started', { generationId: jobId, totalSteps: 1 });
    activeJobs.set(jobId, { ...meta, generationId: jobId, totalSteps: 1, step: 0, progress: 0, currentImage: null });
    broadcastSse(job, { type: 'status', message: 'Spawning codex…' });
  } catch (err) {
    jobs.delete(jobId);
    activeJobs.delete(jobId);
    await removeScratchDirectory(scratchDir);
    throw err;
  }

  // generateImage returns a job descriptor synchronously; the actual codex
  // child runs out-of-band so the HTTP response can ship while the client
  // attaches to the per-job SSE stream (mirrors local.js). runCodex settles
  // every launch failure through the job's own failure finalizer.
  runCodex(job, jobId, bin, args, outputPath, filename, meta, { cleanC2PA, denoise, scratchDir });

  return {
    jobId, filename, path: `/data/images/${filename}`, generationId: jobId,
    mode: IMAGE_GEN_MODE.CODEX, model: effectiveModel,
    // Async callers gate UI state on `status`; without 'running' they flip
    // to 'done' before the PNG lands. SSE / socket 'completed' fires later.
    status: 'running',
  };
}

// Preserve the model's reported reason without inferring account capability
// from a missing output file or a narrated success claim.
const CODEX_NO_IMAGE_HINT =
  'Codex returned no generated image. Check the Codex session and Settings → Image Gen.';
export const noImageReason = (stdoutTail = '') => buildNoImageReason(stdoutTail, {
  hint: CODEX_NO_IMAGE_HINT,
  // Codex's own structural labels, on top of the shared dashed-rule /
  // bare-token-count filter.
  dropLine: (l) => /^(codex|user)$/i.test(l) || /^tokens used\b/i.test(l),
  describe: (said) => (
    /\b(generated|created|here(?:'|’)s|i(?:'|’)ve (?:made|generated))\b/i.test(said)
      ? `Codex reported success but no generated image file was found. Codex said: "${said}"`
      : `Codex did not produce an image. Codex said: "${said}"`
  ),
});

function removeScratchDirectory(scratchDir) {
  return maintenance.continueSettlement(
    () => rmGuarded(scratchDir, { recursive: true, force: true }),
  ).catch(err => {
    maintenance.markCurrentUnsettled();
    console.error(`❌ Codex scratch cleanup failed: ${err.message}`);
  });
}

// Launch is synchronous so every failure has one owner: a refusal before a
// child exists (Node rejects an invalid argv/bin synchronously) settles the job
// here, and a setup failure after spawn terminates the child and leaves the
// close handler to settle once it has physically exited.
function runCodex(job, jobId, bin, args, outputPath, filename, meta, { cleanC2PA = false, denoise = false, scratchDir } = {}) {
  const removeScratch = () => removeScratchDirectory(scratchDir);
  if (preparations.take(jobId)) {
    void removeScratch();
    return finalizeJobFailure.canceled(job, jobId);
  }
  let proc;
  try {
    const resolvedBin = !isAbsolute(bin) && (bin.includes('/') || bin.includes(sep)) ? resolve(bin) : bin;
    const prepared = prepareCliSpawn(resolvedBin, args);
    const baseEnv = withoutServerSecretsEnv(process.env, { keep: CODEX_AUTH_ENV_KEYS });
    const env = process.env.CODEX_HOME ? { ...baseEnv, CODEX_HOME: resolve(process.env.CODEX_HOME) } : baseEnv;
    proc = spawn(prepared.command, prepared.args, { cwd: scratchDir, env: withSpawnCwdEnv(env, scratchDir), shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
  } catch (err) {
    void removeScratch();
    return finalizeJobFailure(job, jobId, null, `Failed to spawn ${bin}: ${err?.message || err}`);
  }
  activeProcs.set(jobId, proc);

  let sessionId = null;
  let stderrTail = '';
  const STDERR_TAIL_BYTES = 32 * 1024;
  // Codex narrates its turn (incl. "I can't create that…" content declines and
  // any tool-failure notes) on STDOUT. Keep a rolling tail so a no-image finish
  // can surface the model's actual words instead of a generic "no image" guess.
  let stdoutTail = '';
  const STDOUT_TAIL_BYTES = 8 * 1024;
  let timeoutTimer = null;
  let setupError = null;

  // Banner is roughly 12 lines / ~500 bytes — keep a small rolling
  // buffer so a session-id line that gets split across chunk boundaries
  // (Node streams can land each pipe write as its own 'data' event)
  // still matches. Trim aggressively after a match to keep this tiny.
  //
  // Why: match BEFORE slicing. With long pipeline prompts (multi-KB
  // comic-script payloads), codex emits the banner + the echoed prompt
  // in a single stderr chunk that can exceed BANNER_BUF_MAX. If we
  // sliced first, the `session id:` line at the FRONT would get chopped
  // off before we ever ran the regex, producing the
  // "Codex returned no session id" false negative.
  let bannerBuf = '';
  const BANNER_BUF_MAX = 4 * 1024;
  const captureSession = (text) => {
    if (sessionId) return;
    bannerBuf += text;
    const m = bannerBuf.match(SESSION_ID_RE);
    if (m) {
      sessionId = m[1];
      bannerBuf = '';
      broadcastSse(job, { type: 'status', message: `Codex session ${sessionId.slice(0, 8)}…` });
      return;
    }
    if (bannerBuf.length > BANNER_BUF_MAX) bannerBuf = bannerBuf.slice(-BANNER_BUF_MAX);
  };

  let processError;
  proc.on('error', (err) => {
    processError = err;
    // A failed kill/send on a live child is not physical exit.
    if (proc.pid) return;
    clearTimeout(timeoutTimer);
    void removeScratch();
    finalizeJobFailure(job, jobId, proc, `Failed to spawn ${bin}: ${err.message}`);
  });

  proc.on('close', async (code, signal) => {
    await withBackupAssetPublication(async () => {
      clearTimeout(timeoutTimer);
      // Don't clear activeProcess yet — the post-exit handler still does
      // async work (harvest + copyFile + sidecar). Clearing the
      // module-scoped guard up front would let a new generation start
      // while we're still finalizing this one, then the in-flight
      // finalizer could clobber the new job's activeJob snapshot.
      // EventEmitter doesn't await async listeners — without this try/catch,
      // a throw from harvestLatestImage / copyFile would surface as an
      // unhandled rejection (process-killing on Node ≥15) and the job would
      // be stuck in 'running' forever with no SSE error to the client.
      try {
        if (setupError) {
          return finalizeJobFailure(job, jobId, proc, `Codex launch setup failed: ${setupError?.message || setupError}`);
        }
        if (code !== 0 || processError) {
          const reason = processError?.message || (signal ? `Killed by signal ${signal}` : `Exit code ${code}`);
          const tail = stderrTail.trim().split('\n').slice(-6).join('\n');
          return finalizeJobFailure(job, jobId, proc, `Codex generation failed: ${reason}\n${tail}`);
        }
        if (!sessionId) {
          return finalizeJobFailure(job, jobId, proc, 'Codex returned no session id — output format may have changed');
        }
        // Codex writes the PNG asynchronously while it's wrapping up the turn.
        // Empirically the file is on disk by the time `codex exec` exits, but
        // poll for a few seconds in case there's a flush lag on slow disks.
        const harvested = await harvestGeneratedImage(sessionId, harvestTimeoutMs);
        if (!harvested) {
          return finalizeJobFailure(job, jobId, proc, await noImageSessionReason(sessionId, stdoutTail));
        }
        if (harvested.path) {
          await copyFileGuarded(harvested.path, outputPath);
        } else {
          await atomicWrite(outputPath, harvested.buffer);
        }
        // Degenerate-frame gate (#4173) — before the sidecar, so a decodable but
        // contentless canvas never becomes a gallery record.
        const emptyFrame = await rejectDegenerateFrame(outputPath);
        if (emptyFrame) {
          return finalizeJobFailure(job, jobId, proc, emptyFrame);
        }
        // Codex picks its own output size; crop an off-aspect frame to the
        // requested ratio before anything downstream inherits its shape.
        const aspectConformed = await conformImageAspect(outputPath, meta.width, meta.height);
        if (aspectConformed) console.log(`✂️ Conformed codex frame [${jobId.slice(0, 8)}] ${aspectConformed.from} → ${aspectConformed.to}`);
        // Sidecar metadata so the gallery can recover prompt/seed/etc. The
        // codex sessionId is the closest analogue to a seed for gpt-image-2
        // (which doesn't expose one) — uniquely identifies the run and is
        // useful for traceability even though it doesn't reproduce the output.
        const sidecar = join(PATHS.images, `${jobId}.metadata.json`);
        // `job.renderStartedAtMs` is the queue-ingestion instant generateImage
        // captured, so the spread measures the render itself — not the time the
        // job spent queued behind other renders.
        const renderMeta = { ...meta, codexSessionId: sessionId, driverReportedTokens: codexDriverReportedTokens(stderrTail), ...(aspectConformed ? { aspectConformed } : {}), ...renderTimingFields(job.renderStartedAtMs) };
        await atomicWrite(sidecar, renderMeta);
        // Cleaners run BEFORE the SSE complete + completed events so subscribers
        // see the cleaned bytes. codex output is the highest-value target for
        // C2PA stripping because gpt-image is the one provider that embeds
        // provenance metadata.
        await autoCleanGeneratedImage({ cleanC2PA, denoise, pngPath: outputPath, sidecarPath: sidecar, mode: IMAGE_GEN_MODE.CODEX });
        // Accounting failure must preserve the image and its recoverable sidecar.
        await recordCodexRender(renderMeta).catch(err => {
          console.error(`❌ Failed to record Codex image usage: ${err.message}`);
        });
        job.status = 'complete';
        if (activeProcs.get(jobId) === proc) activeProcs.delete(jobId);
        activeJobs.delete(jobId);
        console.log(`✅ Image generated [${jobId.slice(0, 8)}]: ${filename} (codex)`);
        const result = { filename, path: `/data/images/${filename}` };
        dispatchTerminalEvent(
          jobId,
          () => broadcastSse(job, { type: 'complete', result }),
          () => imageGenEvents.emit('completed', { mode: IMAGE_GEN_MODE.CODEX, generationId: jobId, path: `/data/images/${filename}`, filename }),
        );
        closeJobAfterDelay(jobs, jobId);
      } catch (err) {
        await Promise.all([outputPath, join(PATHS.images, `${jobId}.metadata.json`)].map(path => unlinkGuarded(path).catch(() => {})));
        // force: true — 'complete' is already stamped above; see
        // createJobFailureFinalizer's doc comment in sseUtils.js.
        finalizeJobFailure(job, jobId, proc, `Codex post-exit handler failed: ${err?.message || err}`, { force: true });
      }
    }).catch(err => {
      // Admission can reject before the publication callback is entered.
      // EventEmitter does not await this listener, so settle the job here too.
      clearTimeout(timeoutTimer);
      finalizeJobFailure(job, jobId, proc, `Codex publication admission failed: ${err?.message || err}`);
    }).finally(removeScratch);
  });

  // Post-spawn setup. The error/close owners above are already installed, so a
  // throw here must not settle the job under a live child: record it,
  // terminate the child, and let close settle once it has physically exited.
  try {
    timeoutTimer = setTimeout(() => {
      if (activeProcs.get(jobId) === proc) {
        console.log(`⏱️ codex timed out after ${CODEX_TIMEOUT_MS}ms [${jobId.slice(0, 8)}]`);
        sigtermWithEscalation(jobId, proc);
      }
    }, CODEX_TIMEOUT_MS);

    proc.stdout.on('data', (chunk) => {
      // Codex prints the `session id:` banner on stderr only — don't feed
      // stdout into bannerBuf. A stdout chunk arriving between two stderr
      // chunks of the banner can split the session-id line with unrelated
      // text and break the regex match.
      // We DO retain stdout here (the model's turn narration) so a no-image
      // finish can report why — a content decline, or a "generated" claim with
      // no file.
      stdoutTail += chunk.toString();
      if (stdoutTail.length > STDOUT_TAIL_BYTES) stdoutTail = stdoutTail.slice(-STDOUT_TAIL_BYTES);
      broadcastSse(job, { type: 'status', message: 'Running…' });
    });

    proc.stderr.on('data', (chunk) => {
      const text = chunk.toString();
      captureSession(text);
      stderrTail += text;
      if (stderrTail.length > STDERR_TAIL_BYTES) stderrTail = stderrTail.slice(-STDERR_TAIL_BYTES);
    });
  } catch (err) {
    setupError = err;
    clearTimeout(timeoutTimer);
    sigtermWithEscalation(jobId, proc);
  }
}

const finalizeJobFailure = createJobFailureFinalizer({
  jobs,
  activeJobs,
  activeSlots: activeProcs,
  label: 'codex image generation',
  events: imageGenEvents,
  failedPayload: (jobId, reason) => ({ mode: IMAGE_GEN_MODE.CODEX, generationId: jobId, error: reason }),
});

// Returns the absolute path to the newest PNG in the session dir. Codex has
// used both `ig_*.png` and `exec-*.png`; the per-session directory is already
// the ownership boundary, so a filename-prefix allowlist only turns valid tool
// output into a false failure when the CLI changes its internal naming again.
async function latestGeneratedImageFile(sessionId) {
  const dir = codexImagesDir(sessionId);
  if (!existsSync(dir)) return null;
  const names = await readdir(dir).catch(() => []);
  const pngs = names.filter((name) => name.toLowerCase().endsWith('.png'));
  if (pngs.length) {
    const stats = await Promise.all(pngs.map(async (n) => {
      const s = await stat(join(dir, n)).catch(() => null);
      return s ? { n, mtimeMs: s.mtimeMs } : null;
    }));
    const latest = stats.filter(Boolean).sort((a, b) => b.mtimeMs - a.mtimeMs)[0];
    if (latest) return join(dir, latest.n);
  }
  return null;
}

async function harvestLatestImage(sessionId, timeoutMs) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const latest = await latestGeneratedImageFile(sessionId);
    if (latest) return latest;
    const remainingMs = Math.max(1, deadline - Date.now());
    await sleep(Math.min(250, remainingMs));
  }
  return null;
}

const isPngBuffer = (buf) => {
  if (!Buffer.isBuffer(buf) || buf.length < 12) return false;
  return buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47
    && buf[4] === 0x0d && buf[5] === 0x0a && buf[6] === 0x1a && buf[7] === 0x0a;
};

async function findSessionLogFile(sessionId) {
  const root = codexSessionsDir();
  if (!existsSync(root)) return null;
  const stack = [root];
  while (stack.length) {
    const dir = stack.pop();
    const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
    for (const entry of entries) {
      const full = join(dir, entry.name);
      if (entry.isFile() && entry.name.endsWith('.jsonl') && entry.name.includes(sessionId)) {
        return full;
      }
      if (entry.isDirectory()) stack.push(full);
    }
  }
  return null;
}

async function noImageSessionReason(sessionId, stdoutTail) {
  const path = await findSessionLogFile(sessionId);
  if (!path) return noImageReason(stdoutTail);
  const text = await readFile(path, 'utf8').catch(() => '');
  let imageToolObserved = false;
  let shellObserved = false;
  for (const line of text.split('\n')) {
    try {
      const payload = JSON.parse(line)?.payload;
      const name = payload?.name || '';
      if (['image_gen', 'image_gen.text2im', 'image_gen.imagegen'].includes(name) || ['image_generation_call', 'image_generation_end'].includes(payload?.type)) imageToolObserved = true;
      if (['function_call', 'custom_tool_call'].includes(payload?.type) && /^(exec|exec_command|shell|shell_command)$/.test(name)) shellObserved = true;
    } catch { /* Incomplete transcript lines do not establish tool usage. */ }
  }
  if (imageToolObserved) return noImageReason(stdoutTail);
  return `No image_gen call was observed in the Codex session${shellObserved ? '; shell activity was recorded' : ''}. No generated image was found. This does not establish whether the tool is available to this account. Check Settings → Image Gen and the Codex session. ${noImageReason(stdoutTail)}`;
}

async function harvestSessionLogImage(sessionId) {
  const logPath = await findSessionLogFile(sessionId);
  if (!logPath) return null;
  const text = await readFile(logPath, 'utf8').catch(() => '');
  let latest = null;
  for (const line of text.split('\n')) {
    if (!line.trim()) continue;
    try {
      const record = JSON.parse(line);
      const payload = record?.payload;
      if (payload?.type !== 'image_generation_end' || typeof payload.result !== 'string') continue;
      const raw = payload.result.replace(/^data:image\/[a-z0-9.+-]+;base64,/i, '');
      const buffer = Buffer.from(raw, 'base64');
      if (isPngBuffer(buffer)) latest = { buffer, path: logPath, callId: payload.call_id || null };
    } catch {
      // Session JSONL can contain arbitrarily large model payloads; ignore
      // malformed/truncated lines and keep scanning for a valid image event.
    }
  }
  return latest;
}

async function harvestGeneratedImage(sessionId, timeoutMs) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const path = await latestGeneratedImageFile(sessionId);
    if (path) return { path };

    // Newer Codex builds may persist image bytes only in the session JSONL as
    // image_generation_end.result (base64), without materializing a PNG in
    // ~/.codex/generated_images/<session-id>/. Decode that fallback so
    // a real generation does not get reported as "success but no file".
    const sessionImage = await harvestSessionLogImage(sessionId);
    if (sessionImage) return { buffer: sessionImage.buffer, sessionLogPath: sessionImage.path };

    await sleep(250);
  }
  return null;
}

// Tiny helper for unit tests — overrides the homedir lookup so tests can
// point at a tmpdir-rooted ~/.codex without touching the real one. Not used
// in production. The function below intentionally keeps state inside this
// module because the test path is an explicit ergonomic carve-out.
export const _internals = {
  codexImagesDir,
  codexSessionsDir,
  SESSION_ID_RE,
  harvestLatestImage,
  harvestSessionLogImage,
  harvestGeneratedImage,
  setHarvestTimeoutForTests: (timeoutMs = DEFAULT_HARVEST_TIMEOUT_MS) => {
    harvestTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
      ? timeoutMs
      : DEFAULT_HARVEST_TIMEOUT_MS;
  },
};