feat: add codex-imagegen backend for non-Codex runtimes

Implements the preferred_image_backend: codex-imagegen config key
already referenced in several SKILL.md files but with no corresponding
backend. Bridges non-Codex runtimes (Claude Code, etc.) to Codex CLI's
built-in image_gen tool via 'codex exec'. Uses the user's Codex
subscription — no OPENAI_API_KEY required.

Reliability:
- Retry with exponential backoff (default 2 retries, configurable)
- 9 classified error kinds (retryable vs non-retryable)
- Node child_process timeout with SIGTERM→SIGKILL ladder

Correctness:
- Verifies image_gen was actually invoked (not bypassed) by checking
  $CODEX_HOME/generated_images/{thread_id}/ for a PNG
- PNG magic byte validation
- Output file size sanity check

Observability:
- Structured JSONL logging with --log-file
- Verbose stderr mode with --verbose
- Returns thread_id, tool_calls, token usage in result JSON
- Raw codex event stream preserved per attempt for debugging

Efficiency:
- Idempotency cache via --cache-dir (sha256 of prompt+aspect+refs)
- Cache hit returns in <0.3s vs 50-90s cold

Features:
- --ref reference images (repeatable, passed through to codex exec --image)
- --retries, --retry-delay, --timeout all configurable
- File lock serializes concurrent invocations

Testing:
- 16 Bun unit tests across parser, cache, validator
- Path-filtered CI workflow at .github/workflows/codex-imagegen-tests.yml
- Composes with existing test.yml without conflicts

Architecture:
- scripts/codex-imagegen.sh: thin bash entrypoint (bun → npx -y bun fallback)
- scripts/codex-imagegen/: TypeScript module
  - main.ts (orchestrator), types.ts (CliOptions/GenerateResult/GenError),
    spawn.ts (child_process), parser.ts (JSONL events), validator.ts
    (image_gen check + PNG magic), cache.ts (sha256 cache + FileLock),
    logger.ts (JSONL structured logger)

Trade-offs documented in docs/codex-imagegen-backend.md:
- 5-10x slower than direct OpenAI API (or near-free on cache hit)
- ToS gray area: image_gen is documented for interactive use; non-
  interactive invocation via codex exec is not explicitly addressed.
  Suitable for personal low-volume use; users are responsible for
  ensuring their usage complies with applicable terms of service.

scripts/codex-imagegen/validator.test.ts

@@ -0,0 +1,98 @@
+import { test, expect } from "bun:test";
+import { mkdtemp, writeFile, rm, mkdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { verifyOutput, verifyImageGenWasInvoked, findCpToTarget } from "./validator.ts";
+import { GenError } from "./types.ts";
+
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+test("verifyOutput passes for valid PNG", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "good.png");
+    await writeFile(p, Buffer.concat([PNG_HEADER, Buffer.alloc(5000)]));
+    const r = await verifyOutput(p);
+    expect(r.bytes).toBeGreaterThan(1000);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects missing file", async () => {
+  await expect(verifyOutput("/no/such/file.png")).rejects.toBeInstanceOf(GenError);
+});
+
+test("verifyOutput rejects tiny file", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "tiny.png");
+    await writeFile(p, "tiny");
+    await expect(verifyOutput(p)).rejects.toThrow(/too small/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyOutput rejects non-PNG magic", async () => {
+  const dir = await mkdtemp(path.join(tmpdir(), "cig-val-"));
+  try {
+    const p = path.join(dir, "fake.png");
+    await writeFile(p, Buffer.concat([Buffer.from("GIF89a"), Buffer.alloc(5000)]));
+    await expect(verifyOutput(p)).rejects.toThrow(/not a valid PNG/);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked false when no thread directory", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const r = await verifyImageGenWasInvoked("no-such-thread");
+    expect(r.ok).toBe(false);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});
+
+test("verifyImageGenWasInvoked true when PNG exists in thread dir", async () => {
+  const orig = process.env.CODEX_HOME;
+  const tempHome = await mkdtemp(path.join(tmpdir(), "cig-home-"));
+  process.env.CODEX_HOME = tempHome;
+  try {
+    const threadDir = path.join(tempHome, "generated_images", "thread-xyz");
+    await mkdir(threadDir, { recursive: true });
+    await writeFile(path.join(threadDir, "ig_abc.png"), Buffer.alloc(100));
+    const r = await verifyImageGenWasInvoked("thread-xyz");
+    expect(r.ok).toBe(true);
+  } finally {
+    process.env.CODEX_HOME = orig;
+    await rm(tempHome, { recursive: true, force: true });
+  }
+});
+
+test("findCpToTarget detects cp from generated_images", () => {
+  expect(
+    findCpToTarget(
+      [
+        {
+          id: "1",
+          tool: "shell",
+          status: "completed",
+          command: "cp ~/.codex/generated_images/thread/ig_x.png /tmp/out.png",
+        },
+      ],
+      "/tmp/out.png",
+    ),
+  ).toBe(true);
+
+  expect(
+    findCpToTarget(
+      [{ id: "1", tool: "shell", status: "completed", command: "ls /tmp" }],
+      "/tmp/out.png",
+    ),
+  ).toBe(false);
+});