overlay-factory-worker 0.2.0 → 0.2.2

package/README.md

@@ -1,7 +1,7 @@
 # overlay-factory-worker
 
 The Overlay Factory's worker: goosetools.com queues overlay jobs, this machine
-writes the overlays with Claude, renders them with Remotion, and burns them onto
+writes the overlays with the agent the user picked in Setup (Claude by default; episode research always uses Claude, for web search), renders them with Remotion, and burns them onto
 the uploaded clip with ffmpeg. Published to npm on its own; lives in the
 goosetools repo at `workers/overlay` (it was the standalone `reel-factory` repo
 until 2026-09-26 — the What Prints series that lived there is at the
@@ -33,7 +33,12 @@ is: **add references, it tries, you adjust in words, it learns.**
    the rewrite against the note and retries once with whatever it missed; then
    writes the result as the series. The note is appended to `notes.md`, so it
    keeps applying — to later revisions and to a full rebuild.
-4. The previous 5 versions of each series are kept in `series/.history/<slug>/`,
+4. **It checks its own render.** After a build or a revision, the series is
+   rendered and put next to the references with the shared method's compare
+   phase (`skills/reference-analysis.md`, the same method the Carousel Maker
+   uses); anything that doesn't match is fixed before you see it. Field keys
+   can't change in that step.
+5. The previous 5 versions of each series are kept in `series/.history/<slug>/`,
    so a bad revision can be put back by hand.
 
 `series/` is gitignored and per-machine (in an npm install it lives in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overlay-factory-worker",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "The Goose Tools Overlay Factory worker — your computer renders reel overlays for goosetools.com with Remotion and ffmpeg.",
   "repository": {
     "type": "git",
@@ -40,7 +40,8 @@
     "overlay:install": "node worker/cli.mjs install",
     "overlay:uninstall": "node worker/cli.mjs uninstall",
     "overlay:status": "node worker/cli.mjs status",
-    "overlay:doctor": "node worker/cli.mjs doctor"
+    "overlay:doctor": "node worker/cli.mjs doctor",
+    "prepublishOnly": "node ../sync-shared.mjs --check"
   },
   "sideEffects": [
     "*.css"
@@ -58,6 +59,7 @@
     "src",
     "remotion.config.ts",
     "tsconfig.json",
-    "README.md"
+    "README.md",
+    "skills"
   ]
 }

package/scripts/agent.ts

@@ -0,0 +1,66 @@
+/**
+ * The overlay worker's two shared dependencies with the other workers:
+ *
+ *  - Which coding-agent CLI to run. The user picks one in Setup on
+ *    goosetools.com and every claim carries it (`agentCli`); prompts go
+ *    through worker/agent-cli.mjs, the same adapter the other workers use,
+ *    synced from workers/shared/agent-cli.js.
+ *  - How to read references. skills/reference-analysis.md is the Carousel
+ *    Maker's method, shared so both tools study references, and check their
+ *    own renders against them, the same way.
+ *
+ * The worker runs one job at a time, so the agent is set per job with
+ * useAgent() rather than threaded through every generation helper.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const ROOT = join(__dirname, "..");
+
+type RunAgent = (opts: {
+  agent?: string;
+  prompt: string;
+  cwd?: string;
+  mode?: "text" | "oneshot" | "read" | "session";
+  timeoutMs?: number;
+}) => Promise<{ text: string }>;
+
+let current = "claude-code";
+
+/** Called at the start of each job with the agent that job's owner picked. */
+export const useAgent = (agentCli?: string | null) => {
+  current = agentCli || "claude-code";
+};
+
+let adapter: Promise<{ runAgent: RunAgent }> | undefined;
+
+/**
+ * Run one prompt through the current agent and return its text.
+ *
+ * "read" lets it open the reference and render images named in the prompt;
+ * "oneshot" is for judgements where everything it needs is inlined.
+ */
+export const askAgent = async (
+  prompt: string,
+  { mode = "read", timeoutMs = 15 * 60 * 1000 }: { mode?: "read" | "oneshot"; timeoutMs?: number } = {},
+): Promise<string> => {
+  // A file URL rather than a bare specifier: the adapter is an ES module in a
+  // CommonJS package, and this keeps it a real dynamic import.
+  adapter ??= import(pathToFileURL(join(ROOT, "worker", "agent-cli.mjs")).href) as Promise<{
+    runAgent: RunAgent;
+  }>;
+  const { runAgent } = await adapter;
+  const { text } = await runAgent({ agent: current, prompt, mode, cwd: ROOT, timeoutMs });
+  return text;
+};
+
+let method: string | undefined;
+
+/** One section of the shared reference method, by its SECTION marker. */
+export const skillSection = (name: string): string => {
+  method ??= readFileSync(join(ROOT, "skills", "reference-analysis.md"), "utf8");
+  const m = method.match(new RegExp(`<!-- SECTION: ${name} -->\\n([\\s\\S]*?)(?=<!-- SECTION: |$)`));
+  if (!m) throw new Error(`reference method section "${name}" not found`);
+  return m[1].trim();
+};

package/scripts/overlay-worker.ts

@@ -46,6 +46,7 @@ import {
 import { resolveCustomFonts } from "./custom-fonts";
 import { resolveFieldImages } from "./field-images";
 import { ensureStateLinks } from "./state-dir";
+import { useAgent } from "./agent";
 import { acquireWorkerLock } from "./worker-lock";
 
 // Worker-side upload, same signature as the old `upload` from
@@ -149,6 +150,8 @@ type NewSeries = {
 type Job = {
   id: string;
   kind: "overlay" | "series" | "restock" | "preview" | "single";
+  /** The coding-agent CLI this job's owner picked in Setup. */
+  agentCli?: string | null;
   /** kind='single' and one-off previews: what it should say, and what to copy. */
   single?: { say: string; refUrls: string[] } | null;
   /** The preview this job confirms, so it reuses that overlay rather than writing a new one. */
@@ -177,8 +180,17 @@ type Job = {
 const ROOT = join(__dirname, "..");
 const PUBLIC = join(ROOT, "public");
 
-/** A one-off's directory name — the same for its preview and its burn. */
-const singleSlug = (id: string) => `single-${id.slice(0, 8)}`;
+/**
+ * A one-off's directory name — the same for its preview and its burn.
+ *
+ * The id comes from the server, and the result is a folder the worker later
+ * deletes, so anything that isn't a plain job id is refused rather than
+ * trusted to stay inside series/.
+ */
+const singleSlug = (id: string) => {
+  if (!/^[0-9a-f]{8}-[0-9a-f-]{4,}$/i.test(id)) throw new Error("Bad one-off id");
+  return `single-${id.slice(0, 8).toLowerCase()}`;
+};
 
 /**
  * Run a script, and on failure raise the part a human wrote.
@@ -678,6 +690,7 @@ const watchOwnSource = () => {
   const files = [
     "scripts/overlay-worker.ts",
     "scripts/series.ts",
+    "scripts/agent.ts",
     "scripts/stock.ts",
     "scripts/render-overlay.ts",
     "scripts/custom-fonts.ts",
@@ -708,6 +721,8 @@ const main = async () => {
     try {
       const job = (await api("claim")) as Job | null;
       if (job) {
+        // One job at a time, so the owner's agent choice is set per job.
+        useAgent(job.agentCli);
         if (job.kind === "series") await runSeriesJob(job);
         else if (job.kind === "restock") await runRestockJob(job);
         else if (job.kind === "preview") await runPreviewJob(job);

package/scripts/series.ts

@@ -20,7 +20,7 @@
  * freeze on whatever the first frame painted. Each layer instead declares an
  * `enter`, which the composition drives with Remotion's own spring.
  */
-import { execFile, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
 import {
   cpSync,
   existsSync,
@@ -34,9 +34,8 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { promisify } from "node:util";
+import { askAgent, skillSection } from "./agent";
 
-const execFileAsync = promisify(execFile);
 const ROOT = join(__dirname, "..");
 const SERIES_DIR = join(ROOT, "series");
 
@@ -216,6 +215,10 @@ ${
 Read each of these image files closely (in order — the first matters most):
 ${opts.refPaths.map((p) => `- ${p}`).join("\n")}
 
+${skillSection("principles")}
+
+${skillSection("overlay-analyze")}
+
 Sample the ACTUAL colors from them. Match their typography treatment (weight,
 case, letter-spacing, serif vs sans), their shapes (radius, borders, bars),
 their spacing and their composition. A finished frame should look like it
@@ -432,11 +435,7 @@ const draftFiles = async (
   let p = initialPrompt;
   // Two attempts: the second is told exactly what was wrong with the first.
   for (let attempt = 1; attempt <= 2; attempt++) {
-    const { stdout } = await execFileAsync(
-      "claude",
-      ["-p", p, "--output-format", "text", "--allowedTools", "Read"],
-      { maxBuffer: 20 * 1024 * 1024, timeout: 15 * 60 * 1000 },
-    );
+    const stdout = await askAgent(p, { mode: "read" });
     try {
       const files = extractFiles(stdout);
       return { files, spec: validate(files) };
@@ -451,6 +450,8 @@ const draftFiles = async (
 };
 
 const NOTES_FILE = "notes.md";
+/** Marks a one-off's folder, so the sweep never touches a real series. */
+const ONE_OFF_MARKER = ".one-off";
 const HISTORY_DIR = join(SERIES_DIR, ".history");
 const KEEP_VERSIONS = 5;
 
@@ -475,7 +476,7 @@ const writeSeries = (
   const out = join(SERIES_DIR, slug);
   const notes = readNotes(slug);
 
-  if (existsSync(join(out, "series.json")) && !slug.startsWith("single-")) {
+  if (existsSync(join(out, "series.json")) && !existsSync(join(out, ONE_OFF_MARKER))) {
     const hist = join(HISTORY_DIR, slug);
     mkdirSync(hist, { recursive: true });
     cpSync(out, join(hist, new Date().toISOString().replace(/[:.]/g, "-")), {
@@ -544,12 +545,103 @@ export const generateSeries = async (input: {
       }),
       "Series generation",
     );
-    return spec.fields;
+    await selfCheck({
+      slug: input.slug,
+      refPaths,
+      brand: input.brand ?? null,
+      workDir: dir,
+    });
+    return readSeriesSpec(input.slug)?.fields ?? spec.fields;
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
 };
 
+// ── Self-check ────────────────────────────────────────────────────────────
+
+/**
+ * Look at the rendered series next to the references and fix what's off.
+ *
+ * The Carousel Maker's self-check, for overlays: judging a design by
+ * re-reading its markup misses exactly the things that make it look wrong —
+ * a label twice the size the references use, a box that reads as a slab. So
+ * this renders a frame and puts the picture beside the references, with the
+ * shared method's compare phase. One round, and it never fails the job: a
+ * check that can't run leaves the series as it was.
+ *
+ * Returns a sentence when it changed something, or null.
+ */
+const selfCheck = async (input: {
+  slug: string;
+  refPaths: string[];
+  brand: Brand | null;
+  /** When the check follows a revision, the rewrite must keep doing this. */
+  note?: string;
+  workDir: string;
+}): Promise<string | null> => {
+  if (input.refPaths.length === 0) return null;
+  const spec = readSeriesSpec(input.slug);
+  if (!spec) return null;
+  try {
+    const frame = join(input.workDir, "self-check.png");
+    renderSeriesPreview(input.slug, spec.fields, input.brand, frame);
+    const files = currentFiles(input.slug);
+
+    const out = await askAgent(
+      `You designed this overlay series for vertical video; now inspect your own output.
+
+Read the RENDERED frame (sample text in every field, over neutral grey — the real
+thing sits over footage):
+- ${frame}
+
+Then read the REFERENCES this series must look like it belongs with (in order;
+the first matters most):
+${input.refPaths.map((p) => `- ${p}`).join("\n")}
+
+${skillSection("principles")}
+
+${skillSection("overlay-compare")}
+${
+  input.note
+    ? `
+The user's latest note on this series must still be true after any fix:
+"${input.note}"
+`
+    : ""
+}
+The series files as they are now:
+${asFileBlocks(files)}
+
+If it passes every test, reply with exactly: PASS
+Otherwise reply with the corrected files — EVERY file, in full — in exactly
+this format, changing only what fails, and nothing before or after:
+=== FILE: series.json ===
+...
+=== FILE: <template>.html ===
+...`,
+      { mode: "read" },
+    );
+    if (/^\s*PASS\b/.test(out) && !out.includes("=== FILE:")) {
+      console.log("  self-check: matches the references");
+      return null;
+    }
+    const fixed = extractFiles(out);
+    const fixedSpec = validate(fixed);
+    // A fix must not change what the form asks for — episodes use those keys.
+    const keys = (f: SeriesField[]) => f.map((x) => x.key).sort().join(",");
+    if (keys(fixedSpec.fields) !== keys(spec.fields)) {
+      console.warn("  self-check: its fix changed the fields, so it was not applied");
+      return null;
+    }
+    writeSeries(input.slug, fixed, { keepEpisodes: true });
+    console.log("  self-check: adjusted to match the references");
+    return "Checked against your references and adjusted to match.";
+  } catch (e) {
+    console.error(`  self-check skipped (${(e as Error).message.split("\n")[0]})`);
+    return null;
+  }
+};
+
 // ── Revisions ─────────────────────────────────────────────────────────────
 
 /** The files that make up a series' look, as they are now. */
@@ -593,11 +685,7 @@ the AFTER files actually do it (compare against BEFORE — an unchanged value
 means it was not done). Reply with ONLY this JSON, nothing else:
 {"applied": "<one short sentence, in plain words, saying what changed>",
  "missed": ["<each request that was NOT done, in the user's words>"]}`;
-  const { stdout } = await execFileAsync(
-    "claude",
-    ["-p", p, "--output-format", "text"],
-    { maxBuffer: 5 * 1024 * 1024, timeout: 5 * 60 * 1000 },
-  );
+  const stdout = await askAgent(p, { mode: "oneshot", timeoutMs: 5 * 60 * 1000 });
   const json = stdout.slice(stdout.indexOf("{"), stdout.lastIndexOf("}") + 1);
   const parsed = JSON.parse(json) as { applied?: unknown; missed?: unknown };
   return {
@@ -697,7 +785,17 @@ ${missed.map((m) => `- ${m}`).join("\n")}
       join(SERIES_DIR, input.slug, NOTES_FILE),
       `${readNotes(input.slug)}- ${date} · ${input.feedback.replace(/\s+/g, " ").trim()}\n`,
     );
-    return { fields: draft.spec.fields, note: summary };
+    const checked = await selfCheck({
+      slug: input.slug,
+      refPaths,
+      brand,
+      note: input.feedback,
+      workDir: dir,
+    });
+    return {
+      fields: readSeriesSpec(input.slug)?.fields ?? draft.spec.fields,
+      note: checked ? `${summary} ${checked}` : summary,
+    };
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
@@ -829,6 +927,10 @@ export const sweepSingles = (maxAgeMs = 24 * 60 * 60 * 1000) => {
   for (const d of readdirSync(SERIES_DIR, { withFileTypes: true })) {
     if (!d.isDirectory() || !d.name.startsWith("single-")) continue;
     const p = join(SERIES_DIR, d.name);
+    // Only folders generateSingle marked. A real series can have a single-
+    // slug (the site now refuses new ones, but older ones may exist), and
+    // this deletes without a backup.
+    if (!existsSync(join(p, ONE_OFF_MARKER))) continue;
     try {
       if (Date.now() - statSync(p).mtimeMs > maxAgeMs) {
         rmSync(p, { recursive: true, force: true });
@@ -878,6 +980,7 @@ export const generateSingle = async (input: {
       }),
       "Overlay generation",
     );
+    writeFileSync(join(SERIES_DIR, input.slug, ONE_OFF_MARKER), "");
     return {
       layers: seriesLayers(input.slug, {}, input.durationSec, input.brand ?? null),
       cleanup,

package/scripts/stock.ts

@@ -169,6 +169,8 @@ and stops being readable. No markdown, no quotes around the whole value.
 
 Return at most ${opts.count}.`;
 
+  // Always Claude, whatever agent the user picked: research needs WebSearch
+  // and WebFetch, which the shared agent adapter doesn't offer for the others.
   const { stdout } = await execFileAsync(
     "claude",
     [

package/skills/reference-analysis.md

@@ -0,0 +1,149 @@
+# Reference Analysis Methodology
+
+How to study a set of reference images, map them onto something new, and check
+the finished render against them. Shared by the Carousel Maker (slides) and the
+Overlay Factory (overlays on reels) — the reference images are the source of
+truth for EVERY behavior described here; there are no hardcoded rules. Worker
+prompts splice individual sections by the SECTION markers below.
+
+SHARED FILE: the source of truth is workers/shared/reference-analysis.md in the
+goosetools repo, copied into each worker's skills/ by `npm run workers:sync`.
+
+<!-- SECTION: principles -->
+## Principles — both tools
+
+- **Purpose first, paint second.** Work out what each reference is FOR — the
+  recurring format a follower would recognize — before its colours and fonts.
+  A copy that nails the palette but misses the format is wrong.
+- **Variance vs constants.** Across the set, note what varies and what never
+  changes. Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+- **Same-account test.** The finished thing should read as the same account's
+  work if posted next to the references — same format, same typographic
+  voice, same palette logic. Pixel-matching any one reference is NOT the goal.
+- **Look, don't assume.** Read every image before deciding anything, and judge
+  your own output by looking at the render, not by re-reading your markup.
+
+<!-- SECTION: analyze -->
+## Phase A — understand what each reference is DOING
+
+Read every reference image first. For each one, work out:
+
+- **Role**: is this the cover (the hook slide), a middle content slide, or
+  the closer/CTA? The first reference is usually the cover; use layout and
+  copy cues (page counters, "swipe", "follow") to confirm.
+- **Content job**: what is the slide FOR? Presenting a color palette with
+  labeled swatches? Comparing a before vs an after? Listing tips? Showcasing
+  a product photo? The recurring format a follower would recognize is the
+  thing to reproduce — purpose first, paint second.
+- **Photo and subject**: where does the photo's main subject sit in the
+  frame? How tight is the crop?
+- **Overlays**: where do overlays (swatch stacks, badges, labels, text
+  blocks) sit relative to the subject? Record which behavior this set uses:
+  some styles keep overlays OFF the subject (overlays live in the empty
+  side of the frame); others deliberately lay elements OVER the photo as
+  part of the look. Both are legitimate — copy whichever these references do.
+- **Variance vs constants**: across the whole set, what varies (number of
+  swatches, which side the overlay sits on, crop tightness) and what never
+  changes (the format, the typography, the palette treatment, the border
+  style)? Freedom lives exactly where the references vary; fidelity is owed
+  everywhere they don't.
+
+<!-- SECTION: map -->
+## Phase B — map references onto the new carousel, role to role
+
+Match by ROLE and FORMAT, never image-to-image: your cover should do what
+the reference cover does, your closer what their closer does, and every
+middle slide should follow the references' middle-slide format. Your slide 3
+does not need to mirror reference slide 3.
+
+- **Colors**: if the user's photos share a coherent palette (e.g. they are
+  all sunsets, all one product line), sample the carousel's colors from THE
+  USER'S PHOTOS so the deck feels made from their images. If the photos are
+  visually unrelated, keep the references' original colors. Never mix in
+  colors from anywhere else.
+- **Variance**: whatever varied across the references may vary across your
+  slides the same way — swatch counts, overlay side, crop tightness. Do not
+  make every slide identical when the references weren't.
+- **Overlay placement**: follow the coverage behavior recorded in Phase A.
+  If the references keep overlays clear of the subject, look at each of the
+  user's photos (and what the user's prompt says the photo is about) and
+  place overlays on the empty side — use `variant: flip` on a slide to
+  mirror a template's overlay to the other side. If the references overlay
+  the photo deliberately, do the same.
+- **Photo count adaptation** — the references decide the slide mix:
+  - More photos than slides: choose the photos that best serve each slide's
+    message, but if the user's prompt asks to show something specific, the
+    photo showing it MUST be used.
+  - Fewer photos than the format wants: if the references put a photo on
+    every slide, reuse a photo with a DIFFERENT focus/zoom crop so it reads
+    as a new frame; if the references include photo-free formats (statement
+    slides, text slides), use those instead. Never pad with invented filler
+    content.
+
+<!-- SECTION: compare -->
+## Phase C — compare each rendered slide against the references
+
+For each rendered slide, find the reference(s) with the same ROLE (slide 1 =
+cover, last slide = CTA/closer, everything else = middle) and ask:
+
+- **Same-account test**: if this slide were posted next to the references,
+  would it read as the same account's work — same format, same typographic
+  voice, same palette logic? Exact alignment with any single reference is
+  NOT required; matching the format is.
+- **Overlay-behavior test**: does the slide follow the references' coverage
+  behavior? If they keep overlays off the subject, is this slide's subject
+  (or a face) hidden under a swatch stack, badge, or caption? If so it
+  fails — fix with `variant: flip` (mirror the overlay side) or a focus/zoom
+  change that moves the subject clear.
+- **Framing test**: is the thing the slide is about actually prominent and
+  centered by the crop, exactly as the reference format frames its subjects?
+
+Fix vocabulary (per slide): `focus` ("X% Y%" on the original photo),
+`zoom` (1–3), `variant: flip` (mirror the overlay side), `swatches`
+(recount/recolor a swatch list — only on slides that already have one).
+Never rewrite a slide's text or switch its template during comparison.
+
+<!-- SECTION: overlay-analyze -->
+## Overlay Phase A — understand what the references are DOING
+
+These are frames from reels (or screenshots of them) with text or graphics laid
+over footage. For the set, work out:
+
+- **Format**: what one episode of this is — a question, a hot take, a stat, a
+  quote, a before/after label? That is what the fields should capture.
+- **Hierarchy**: what the eye reads first, second, third, and how that is
+  achieved (size, weight, colour, a box, a bar, a label above the main line).
+- **Type**: weight, case, letter-spacing, serif vs sans vs mono, line length,
+  how many lines the main text runs to.
+- **Containers**: solid box, translucent scrim, outline, shadow only, or text
+  straight on footage — and corner radius, border, padding.
+- **Placement**: where on the 9:16 frame each element sits, and how much of
+  the frame the overlay takes. Note anything placed where Instagram's UI would
+  cover it — keep the format but move it into the safe band.
+- **Colour logic**: which colours are fixed accents and which come from the
+  footage; how contrast is kept over busy or bright video.
+- **Variance vs constants** across the set (see Principles).
+
+<!-- SECTION: overlay-compare -->
+## Overlay Phase C — compare the rendered frame against the references
+
+Look at the rendered frame (sample text in every field, over grey) next to the
+references and ask:
+
+- **Same-account test**: would this sit next to the references as the same
+  series? Same format, hierarchy, type treatment, container style, colour
+  logic.
+- **Hierarchy test**: does the eye land where it lands in the references, in
+  the same order?
+- **Proportion test**: is the overlay roughly the size the references use — not
+  a tiny label where they fill the band, not a slab where they are a caption?
+- **Legibility test**: would it read over ANY footage, on a phone at arm's
+  length? Thin text straight on video fails.
+- **Safe-area test**: is anything in Instagram's top bar, right action rail or
+  bottom caption zone?
+
+Fix by editing the templates (sizes, weights, spacing, colours, containers,
+widthPct, anchor). Never change field keys, the content brief, or wording that
+the user typed or asked for.
+

package/worker/agent-cli.mjs

@@ -0,0 +1,277 @@
+// Agent CLI adapter — runs a job's prompt through whichever coding-agent CLI
+// the user picked on goosetools.com (claim payloads carry `agentCli`).
+//
+// SHARED FILE: the source of truth is workers/shared/agent-cli.js in the
+// goosetools repo. Each worker ships its own copy (worker/agent-cli.js) so the
+// npm packages stay self-contained. Edit the shared one, then run
+// `npm run workers:sync` from the repo root; `npm run workers:check` fails if
+// a copy has drifted.
+//
+// Modes, chosen for speed-vs-capability (see brand-manager commit c0c1b33 —
+// tool-looping turned 36-second drafts into 10-minute ones):
+//   "text"    — plain prompt-in/text-out, no tool flags at all (captions).
+//   "oneshot" — tools explicitly OFF, all context inlined by the caller.
+//   "read"    — file-reading allowed (carousel drafts look at photos).
+//   "session" — tools ON and resumable where the CLI supports it.
+//
+// Honest capability notes per CLI:
+//   claude   — full support: fine tool control, JSON envelope, --resume.
+//   codex    — sandbox-level tool control only; resumable threads; JSONL out.
+//   gemini   — no headless resume: sessionId is always null, callers replay
+//              history (they already do this whenever sessionId is absent).
+//   opencode — plain text out; session continuation is version-dependent, so
+//              we don't claim it: sessionId is always null.
+//
+// Session ids are namespaced ("claude:<uuid>", "codex:<thread-id>") because
+// the server stores them per conversation and the user can switch agents
+// between turns — a Claude uuid means nothing to Codex. resolveSession()
+// drops a mismatched id so the caller falls back to history replay. Bare
+// un-prefixed ids predate namespacing and are treated as Claude's.
+
+import { spawn } from "node:child_process";
+import { spawnSync } from "node:child_process";
+
+export const AGENT_IDS = ["claude-code", "codex", "gemini", "opencode"];
+
+const INSTALL_HINTS = {
+  "claude-code": "npm install -g @anthropic-ai/claude-code",
+  codex: "npm install -g @openai/codex, then run: codex login",
+  gemini: "npm install -g @google/gemini-cli, then run: gemini (to sign in)",
+  opencode: "npm install -g opencode-ai, then run: opencode auth login",
+};
+
+const LABELS = {
+  "claude-code": "Claude Code",
+  codex: "Codex CLI",
+  gemini: "Gemini CLI",
+  opencode: "OpenCode",
+};
+
+// Session-id namespace per agent. claude-code writes "claude:" for continuity
+// with the bare ids already stored server-side.
+const SESSION_PREFIX = {
+  "claude-code": "claude",
+  codex: "codex",
+  gemini: "gemini",
+  opencode: "opencode",
+};
+
+function bin(agent) {
+  if (agent === "claude-code") return process.env.CLAUDE_BIN ?? "claude";
+  return agent; // codex / gemini / opencode binaries share their id
+}
+
+/** "claude" (legacy claim payloads) → "claude-code"; unknown → null. */
+export function normalizeAgent(v) {
+  if (v == null || v === "" ) return "claude-code";
+  if (v === "claude") return "claude-code";
+  return AGENT_IDS.includes(v) ? v : null;
+}
+
+/**
+ * Turn a stored (possibly namespaced, possibly another agent's) session id
+ * into one usable by `agent`, or null — null tells the caller to inline the
+ * conversation history instead of resuming.
+ */
+export function resolveSession(agent, sessionId) {
+  if (!sessionId) return null;
+  const idx = sessionId.indexOf(":");
+  if (idx === -1) {
+    // Legacy bare id — those were always Claude Code session uuids.
+    return agent === "claude-code" ? sessionId : null;
+  }
+  const prefix = sessionId.slice(0, idx);
+  return prefix === SESSION_PREFIX[agent] ? sessionId.slice(idx + 1) : null;
+}
+
+function namespaced(agent, rawId) {
+  return rawId ? `${SESSION_PREFIX[agent]}:${rawId}` : null;
+}
+
+// Strip ANSI escapes and other terminal noise some CLIs print around answers.
+export function cleanText(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/\[[0-9;]*[A-Za-z]/g, "").trim();
+}
+
+// stdio[0] MUST be "ignore". Inherited stdin makes invocations hang forever
+// under launchd — brand-manager hit this exact bug (fixed in 3b1f955) and it
+// presents as the worker silently doing nothing after a reboot.
+function run(agent, args, { timeoutMs, cwd }) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin(agent), args, {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error(`${LABELS[agent]} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      reject(
+        err.code === "ENOENT"
+          ? new Error(
+              `${LABELS[agent]} isn't installed on this computer. Install: ${INSTALL_HINTS[agent]} — or switch your agent back to Claude Code in Setup on goosetools.com.`,
+            )
+          : err,
+      );
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve(stdout);
+      else
+        reject(
+          new Error(`${LABELS[agent]} exited ${code}: ${stderr.slice(0, 600)}`),
+        );
+    });
+  });
+}
+
+/** Is the CLI on PATH? { installed, hint } — cheap, for startup diagnostics. */
+export function detect(agent) {
+  const res = spawnSync(bin(agent), ["--version"], {
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 10_000,
+  });
+  return {
+    installed: res.status === 0,
+    hint: INSTALL_HINTS[agent],
+    label: LABELS[agent],
+  };
+}
+
+// Tools Claude must NOT touch in oneshot mode — everything is inlined.
+const CLAUDE_TOOLS_OFF = "Read,Edit,Write,Bash,Glob,Grep,WebFetch,WebSearch";
+
+/**
+ * Run a prompt through the chosen agent CLI.
+ * Returns { text, sessionId } — sessionId is namespaced and null whenever
+ * the CLI can't resume (callers then replay history on the next turn).
+ */
+export async function runAgent({
+  agent = "claude-code",
+  prompt,
+  cwd,
+  mode = "text",
+  sessionId = null,
+  tools = "Read,Edit,Write,Glob,Grep",
+  timeoutMs = 5 * 60 * 1000,
+}) {
+  const normalized = normalizeAgent(agent);
+  if (!normalized) {
+    throw new Error(
+      `Unknown agent "${agent}" — update this worker: npx --yes <package>@latest install`,
+    );
+  }
+  const resume = resolveSession(normalized, sessionId);
+
+  if (normalized === "claude-code") {
+    if (mode === "session") {
+      const args = [
+        "-p",
+        prompt,
+        "--output-format",
+        "json",
+        "--permission-mode",
+        "acceptEdits",
+        "--allowedTools",
+        tools,
+      ];
+      if (resume) args.push("--resume", resume);
+      const raw = await run(normalized, args, { timeoutMs, cwd });
+      // The json envelope carries the session id. Be forgiving: a shape
+      // change shouldn't lose the user's answer.
+      try {
+        const parsed = JSON.parse(raw);
+        return {
+          text: parsed.result ?? parsed.text ?? raw,
+          sessionId: namespaced(
+            normalized,
+            parsed.session_id ?? parsed.sessionId ?? resume ?? null,
+          ),
+        };
+      } catch {
+        return { text: raw, sessionId: namespaced(normalized, resume) };
+      }
+    }
+    const args = ["-p", prompt, "--output-format", "text"];
+    if (mode === "oneshot") args.push("--disallowedTools", CLAUDE_TOOLS_OFF);
+    if (mode === "read") args.push("--allowedTools", "Read");
+    const text = await run(normalized, args, { timeoutMs, cwd });
+    return { text, sessionId: null };
+  }
+
+  if (normalized === "codex") {
+    // Sandbox is the only tool control codex offers; read-only + the prompt's
+    // own "don't use tools" language is the closest match to oneshot.
+    const sandbox = mode === "session" ? "workspace-write" : "read-only";
+    const args = ["exec"];
+    if (resume) args.push("resume", resume);
+    args.push("--skip-git-repo-check", "--sandbox", sandbox, "--json");
+    if (cwd) args.push("--cd", cwd);
+    args.push(prompt);
+    const raw = await run(normalized, args, { timeoutMs, cwd });
+    // --json emits JSONL events; harvest the thread id and the last agent
+    // message, falling back to the raw output if the shape ever changes.
+    let threadId = resume ?? null;
+    let last = null;
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith("{")) continue;
+      try {
+        const evt = JSON.parse(trimmed);
+        threadId =
+          evt.thread_id ?? evt.session_id ?? evt.thread?.id ?? threadId;
+        const item = evt.item ?? evt;
+        const type = item.item_type ?? item.type;
+        if (
+          (type === "agent_message" || type === "assistant_message") &&
+          typeof (item.text ?? item.message) === "string"
+        ) {
+          last = item.text ?? item.message;
+        }
+      } catch {
+        // not an event line — ignore
+      }
+    }
+    return {
+      text: cleanText(last ?? raw),
+      sessionId: mode === "session" ? namespaced(normalized, threadId) : null,
+    };
+  }
+
+  if (normalized === "gemini") {
+    // No reliable headless resume — never claim one. Session mode gets yolo
+    // approvals so its tools can run unattended.
+    const args = ["-p", prompt, "--output-format", "json"];
+    if (mode === "session") args.push("--yolo");
+    let raw;
+    try {
+      raw = await run(normalized, args, { timeoutMs, cwd });
+    } catch (err) {
+      // Older gemini builds lack --output-format; retry plain.
+      if (!/output-format|unknown option/i.test(String(err.message))) throw err;
+      raw = await run(normalized, ["-p", prompt], { timeoutMs, cwd });
+      return { text: cleanText(raw), sessionId: null };
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return {
+        text: cleanText(parsed.response ?? parsed.result ?? raw),
+        sessionId: null,
+      };
+    } catch {
+      return { text: cleanText(raw), sessionId: null };
+    }
+  }
+
+  // opencode — plain text out; we don't claim session continuation (it's
+  // version-dependent), so every turn replays history.
+  const raw = await run(normalized, ["run", prompt], { timeoutMs, cwd });
+  return { text: cleanText(raw), sessionId: null };
+}