plotlink-ows 1.0.32 → 1.2.94

package/README.md

@@ -256,9 +256,13 @@ PlotLink supports both human writers and AI agent writers via [ERC-8004](https:/
 
 ## Development
 
+Use Node 20 with npm 10. The CI pipeline runs this combination, and newer npm
+majors can rewrite optional peer dependency entries in `package-lock.json`.
+
 ```bash
 git clone https://github.com/realproject7/plotlink-ows.git
 cd plotlink-ows
+nvm use
 npm install
 npm run app:dev      # Start local writer app (Hono + Vite dev)
 npm run app:build    # Build frontend for production

package/app/lib/agent-command.ts

@@ -0,0 +1,85 @@
+import type { AgentProvider } from "../routes/stories";
+
+/**
+ * Pure construction of a terminal agent's CLI invocation as argv.
+ *
+ * This module performs NO fs/pty/env/network access so command building is
+ * fully unit-testable. It returns `{ command, args }` (the binary + argv).
+ *
+ * Claude (KEEP BYTE-IDENTICAL with the legacy inline behavior):
+ *   - fresh:  `claude --session-id <newSessionId>`
+ *   - resume: `claude --resume <sessionId>`
+ *   - bypass: append `--dangerously-skip-permissions`
+ *
+ * Codex (net-new). Both fresh AND resume carry the story cwd (`--cd`) and the
+ * `image_generation` capability — a resumed cartoon session needs the same
+ * working directory and image-gen feature as a fresh one (see #265):
+ *   - fresh:  `codex --enable image_generation --cd <storyDir>`
+ *   - resume: `codex resume <sessionId> --enable image_generation --cd <storyDir>`
+ *             (subcommand style) when an id is stored, otherwise
+ *             `codex resume --last --enable image_generation --cd <storyDir>`.
+ *             NEVER `--resume <id>`.
+ *   - bypass: append `--dangerously-bypass-approvals-and-sandbox`
+ *
+ * Claude-only and Codex-only flags are never mixed across providers.
+ */
+export type AgentMode = "normal" | "bypass";
+
+export interface BuildAgentCommandOptions {
+  provider: AgentProvider;
+  mode: AgentMode;
+  resume: boolean;
+  /** Stored resume id (Claude UUID / Codex session id), or null. */
+  sessionId: string | null;
+  /** Freshly generated UUID used for a brand-new Claude session. */
+  newSessionId: string;
+  /** Absolute story working directory (used by Codex `--cd`). */
+  storyDir: string;
+}
+
+export interface AgentCommand {
+  command: string;
+  args: string[];
+}
+
+export function buildAgentCommand(opts: BuildAgentCommandOptions): AgentCommand {
+  if (opts.provider === "codex") {
+    return buildCodexCommand(opts);
+  }
+  return buildClaudeArgs(opts);
+}
+
+function buildClaudeArgs(opts: BuildAgentCommandOptions): AgentCommand {
+  const args: string[] = [];
+  // Resume only when requested AND a stored id exists; else fresh session.
+  if (opts.resume && opts.sessionId) {
+    args.push("--resume", opts.sessionId);
+  } else {
+    args.push("--session-id", opts.newSessionId);
+  }
+  if (opts.mode === "bypass") {
+    args.push("--dangerously-skip-permissions");
+  }
+  return { command: "claude", args };
+}
+
+function buildCodexCommand(opts: BuildAgentCommandOptions): AgentCommand {
+  const args: string[] = [];
+  if (opts.resume) {
+    // Codex resume is a subcommand (never `--resume <id>`). The subcommand and
+    // its target come first, then the capability/cwd flags.
+    if (opts.sessionId) {
+      args.push("resume", opts.sessionId);
+    } else {
+      args.push("resume", "--last");
+    }
+  }
+  // Both fresh and resume need the image-generation capability and the story
+  // cwd so a resumed cartoon session lands in the right directory with image
+  // generation enabled (not just whatever global session `--last` would pick).
+  args.push("--enable", "image_generation", "--cd", opts.storyDir);
+  if (opts.mode === "bypass") {
+    args.push("--dangerously-bypass-approvals-and-sandbox");
+  }
+  return { command: "codex", args };
+}

package/app/lib/agent-readiness.ts

@@ -0,0 +1,133 @@
+// Agent (CLI) readiness detection.
+//
+// This module is pure: every shell interaction goes through an injected `run`
+// function so it can be unit-tested without spawning processes. The route layer
+// supplies a real `run` that shells out via the user's login shell, and stamps
+// the `checkedAt` timestamp (kept OUT of this pure function so it stays
+// deterministic/testable — no clocks here).
+//
+// Codex image-generation detection parses the structured `codex features list`
+// output rather than guessing from generic `--help` text. See
+// `probeAgentReadiness` for the exact parsing rules.
+
+export type ImageGenStatus = "enabled" | "disabled" | "unknown";
+
+// Codex auth/login hint. "ok" when `codex features list` could actually be read
+// (so we trust the imageGeneration verdict); "unknown" when Codex is installed
+// but its capabilities couldn't be read — commonly a logged-out / unclear-auth
+// state. Best-effort and conservative: default "unknown", never blocks fiction.
+export type AuthStatus = "ok" | "unknown";
+
+export interface AgentReadiness {
+  claude: { installed: boolean };
+  codex: { installed: boolean; version: string | null; imageGeneration: ImageGenStatus; auth: AuthStatus };
+  checkedAt: number; // epoch ms — added by the route, NOT by the pure probe.
+}
+
+/**
+ * Distinct "you may not be logged in to Codex" signal (#263): Codex is installed
+ * but `codex features list` couldn't be read, so the actionable next step is a
+ * Codex login (outside OWS), NOT enabling a feature. Pure + shared so the New
+ * Story flow, the terminal launch-blocked panel, and Settings stay consistent.
+ */
+export function isCodexAuthUnclear(
+  readiness: Pick<AgentReadiness, "codex"> | null | undefined,
+): boolean {
+  return !!readiness && readiness.codex.installed && readiness.codex.auth === "unknown";
+}
+
+/** Operator-facing copy for the auth-unclear case (#263). Shared across surfaces. */
+export const CODEX_AUTH_UNCLEAR_MESSAGE =
+  "Codex is installed but its capabilities couldn't be read — you may need to log in to Codex (resolve outside OWS), then re-check.";
+
+/** First non-empty, trimmed line of a command's stdout (or null). */
+function firstNonEmptyTrimmedLine(stdout: string): string | null {
+  for (const raw of stdout.split("\n")) {
+    const line = raw.trim();
+    if (line.length > 0) return line;
+  }
+  return null;
+}
+
+/**
+ * Determine the effective image_generation state from a single matched line of
+ * `codex features list` output.
+ *
+ * Rules:
+ *  - "enabled" when the line shows a truthy state: `true`, `enabled`, `on`, or
+ *    a trailing check mark (✓).
+ *  - "disabled" when the line shows a falsy state: `false`, `disabled`, `off`.
+ *  - "unknown" when image_generation is present but the state is unparseable.
+ *
+ * Truthy is checked before falsy is irrelevant because a single line never
+ * carries both; we test falsy first to avoid `disabled` matching a substring of
+ * something truthy (there is none, but order keeps intent explicit).
+ */
+function parseImageGenLine(line: string): ImageGenStatus {
+  const l = line.toLowerCase();
+  // Falsy markers.
+  if (/\b(false|disabled|off)\b/.test(l)) return "disabled";
+  // Truthy markers (word states or a trailing check mark).
+  if (/\b(true|enabled|on)\b/.test(l) || /✓/.test(line)) return "enabled";
+  return "unknown";
+}
+
+/**
+ * Probe local agent CLIs. Pure: all shelling-out is injected via `run`.
+ * Returns everything except `checkedAt` (the route stamps that with Date.now()).
+ *
+ * Checks performed:
+ *  - claude.installed: `claude --version` succeeds.
+ *  - codex.installed:  `codex --version` succeeds.
+ *  - codex.version:    first non-empty line of `codex --version` stdout (or null).
+ *  - codex.imageGeneration: parsed from `codex features list`:
+ *      * codex not installed                 -> "unknown"
+ *      * `codex features list` fails / empty  -> "unknown"
+ *      * line mentions image_generation:      -> parseImageGenLine(...)
+ *      * successful listing WITHOUT the line  -> "disabled"
+ *        (a real `features list` that omits image_generation means the feature
+ *        isn't available)
+ */
+export async function probeAgentReadiness(
+  run: (cmd: string) => Promise<{ ok: boolean; stdout: string }>,
+): Promise<Omit<AgentReadiness, "checkedAt">> {
+  const claudeInstalled = (await run("claude --version")).ok;
+
+  const codexVersionResult = await run("codex --version");
+  const codexInstalled = codexVersionResult.ok;
+  const codexVersion = codexInstalled
+    ? firstNonEmptyTrimmedLine(codexVersionResult.stdout) || null
+    : null;
+
+  let imageGeneration: ImageGenStatus = "unknown";
+  // Conservative default: until we can actually read `codex features list`, treat
+  // auth as unclear (covers not-installed and logged-out states alike).
+  let auth: AuthStatus = "unknown";
+
+  if (codexInstalled) {
+    const features = await run("codex features list");
+    if (features.ok && features.stdout.trim().length > 0) {
+      // A readable feature listing means Codex auth/login is working.
+      auth = "ok";
+      // Accept either `image_generation` or `image-generation` naming.
+      const matchLine = features.stdout
+        .split("\n")
+        .find((line) => {
+          const l = line.toLowerCase();
+          return l.includes("image_generation") || l.includes("image-generation");
+        });
+      if (matchLine) {
+        imageGeneration = parseImageGenLine(matchLine);
+      } else {
+        // Successful listing that never mentions image_generation => not available.
+        imageGeneration = "disabled";
+      }
+    }
+    // else: command failed or empty -> stays "unknown".
+  }
+
+  return {
+    claude: { installed: claudeInstalled },
+    codex: { installed: codexInstalled, version: codexVersion, imageGeneration, auth },
+  };
+}

package/app/lib/apply-schema.ts

@@ -0,0 +1,55 @@
+import fs from "fs";
+
+/**
+ * Local SQLite schema setup WITHOUT the native Prisma schema-engine (#484).
+ *
+ * The installed `plotlink-ows` package must bring its SQLite schema up at
+ * startup, but `prisma db push` spawns a platform-specific schema-engine binary
+ * that fails to start in some packed prod-only installs (an empty
+ * "Schema engine error:" on macOS arm64). The Prisma *client* the app already
+ * uses runs on the library query engine — a different, reliably-present engine —
+ * and can execute the DDL directly via `$executeRawUnsafe`.
+ *
+ * So we ship the canonical DDL as `app/prisma/schema.sql` (generated from
+ * `schema.prisma` with `npm run prisma:sql`) and apply it through the client.
+ */
+
+/**
+ * Split a committed `.sql` file into individual executable statements, dropping
+ * `-- ...` comment lines and blanks. Our DDL is a small, controlled grammar
+ * (CREATE TABLE / CREATE [UNIQUE] INDEX) with no semicolons inside values, so a
+ * `;`-split is safe here.
+ */
+export function parseSqlStatements(sql: string): string[] {
+  return sql
+    .split(";")
+    .map((chunk) =>
+      chunk
+        .split("\n")
+        .filter((line) => !line.trim().startsWith("--"))
+        .join("\n")
+        .trim(),
+    )
+    .filter((stmt) => stmt.length > 0);
+}
+
+/**
+ * Rewrite a CREATE statement to be idempotent so applying the schema on an
+ * already-initialized database is a no-op (the app applies it on every startup).
+ * Only the CREATE TABLE / CREATE [UNIQUE] INDEX forms our schema emits are
+ * rewritten; anything else is returned unchanged.
+ */
+export function makeIdempotent(statement: string): string {
+  return statement
+    .replace(/^CREATE TABLE\s+(?!IF NOT EXISTS)/i, "CREATE TABLE IF NOT EXISTS ")
+    .replace(
+      /^CREATE\s+(UNIQUE\s+)?INDEX\s+(?!IF NOT EXISTS)/i,
+      (_match, unique) => `CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS `,
+    );
+}
+
+/** Read the committed schema DDL and return idempotent, ready-to-execute statements. */
+export function loadSchemaStatements(schemaSqlPath: string): string[] {
+  const sql = fs.readFileSync(schemaSqlPath, "utf8");
+  return parseSqlStatements(sql).map(makeIdempotent);
+}

package/app/lib/bubble-text.ts

@@ -0,0 +1,160 @@
+// Shared text layout for cartoon lettering bubbles (#310).
+//
+// Both the export canvas (export-cut.ts) and the editor preview (LetteringEditor)
+// run THIS function with a canvas `measureText`-based width measurer, so dialogue
+// wraps by words and the font is sized to fit the bubble identically in the
+// preview and the exported final image (WYSIWYG). Previously each drew a single
+// maxWidth-compressed line, so long dialogue overflowed/clipped and the preview
+// did not match the export.
+
+export interface BubbleTextLayout {
+  /** Wrapped lines of body text (never empty; [""] for empty text). */
+  lines: string[];
+  /** Chosen body font size in the caller's pixel space. */
+  fontSize: number;
+  /** Line advance (fontSize * lineHeightFactor). */
+  lineHeight: number;
+  /** Speaker label font size, or 0 when there is no speaker. */
+  speakerFontSize: number;
+  /**
+   * True when the text did not fit even at the minimum font (the lines are a
+   * best-effort wrap that may clip/overflow the box). Drives the editor's
+   * text-overflow warning (#336). Export rendering ignores it (unchanged).
+   */
+  overflow: boolean;
+}
+
+export interface BubbleLayoutOptions {
+  /** Largest body font to try, in the caller's pixel space. */
+  maxFontSize: number;
+  /** Smallest body font (used even if text still overflows). */
+  minFontSize: number;
+  /** Fixed body font size; when present, skip auto-fit and use this size. */
+  fontSize?: number;
+  /** Line advance as a multiple of font size. Default 1.2. */
+  lineHeightFactor?: number;
+  /** Speaker-label size as a multiple of body font size. Default 0.8. */
+  speakerScale?: number;
+  /** Body text weight, for consistent bold/regular measurement and layout. */
+  fontWeight?: 400 | 700;
+  /** Horizontal padding inside the box (each side). Default 6% of width. */
+  paddingX?: number;
+  /** Vertical padding inside the box (each side). Default 8% of height. */
+  paddingY?: number;
+  /** Present a speaker label strip above the body. Default false. */
+  hasSpeaker?: boolean;
+}
+
+/** Measure rendered width of `text` at `fontSize` (canvas measureText-backed). */
+export type MeasureWidth = (text: string, fontSize: number, fontWeight?: 400 | 700) => number;
+
+/** Greedy word-wrap of `text` to lines no wider than `maxWidth` at `fontSize`. */
+export function wrapText(
+  measure: MeasureWidth,
+  text: string,
+  maxWidth: number,
+  fontSize: number,
+): string[] {
+  const words = text.split(/\s+/).filter(Boolean);
+  if (words.length === 0) return [""];
+  const lines: string[] = [];
+  let current = "";
+  for (const word of words) {
+    const candidate = current ? `${current} ${word}` : word;
+    // Keep a word on the current line if it fits, or if the line is empty (a
+    // single over-long word still occupies its own line — the fit loop shrinks
+    // the font until it fits the box).
+    if (!current || measure(candidate, fontSize) <= maxWidth) {
+      current = candidate;
+    } else {
+      lines.push(current);
+      current = word;
+    }
+  }
+  if (current) lines.push(current);
+  return lines;
+}
+
+/**
+ * Lay out bubble text: pick the largest font (between min and max) at which the
+ * word-wrapped lines fit the box width AND total height, reserving a strip for a
+ * speaker label when present. Deterministic given the same `measure`, so the
+ * editor preview and the export canvas produce identical wrapping/sizing.
+ */
+export function layoutBubbleText(
+  measure: MeasureWidth,
+  text: string,
+  boxWidth: number,
+  boxHeight: number,
+  opts: BubbleLayoutOptions,
+): BubbleTextLayout {
+  const lineHeightFactor = opts.lineHeightFactor ?? 1.2;
+  const speakerScale = opts.speakerScale ?? 0.8;
+  const padX = opts.paddingX ?? Math.max(2, boxWidth * 0.06);
+  const padY = opts.paddingY ?? Math.max(2, boxHeight * 0.08);
+  const availW = Math.max(1, boxWidth - 2 * padX);
+  const totalAvailH = Math.max(1, boxHeight - 2 * padY);
+
+  const maxFont = Math.max(opts.minFontSize, opts.maxFontSize);
+  const minFont = Math.max(1, Math.min(opts.minFontSize, maxFont));
+
+  const fit = (bodyFont: number): { lines: string[]; ok: boolean } => {
+    const speakerFont = opts.hasSpeaker ? bodyFont * speakerScale : 0;
+    const speakerStrip = opts.hasSpeaker ? speakerFont * lineHeightFactor : 0;
+    const bodyAvailH = Math.max(1, totalAvailH - speakerStrip);
+    const fontWeight = opts.fontWeight ?? 400;
+    const lines = wrapText((line, fontSize) => measure(line, fontSize, fontWeight), text, availW, bodyFont);
+    const bodyH = lines.length * bodyFont * lineHeightFactor;
+    const widthOk = lines.every((l) => measure(l, bodyFont, fontWeight) <= availW + 0.5);
+    return { lines, ok: bodyH <= bodyAvailH && widthOk };
+  };
+
+  if (typeof opts.fontSize === "number" && Number.isFinite(opts.fontSize) && opts.fontSize > 0) {
+    const bodyFont = Math.max(1, opts.fontSize);
+    const { lines, ok } = fit(bodyFont);
+    return {
+      lines,
+      fontSize: bodyFont,
+      lineHeight: bodyFont * lineHeightFactor,
+      speakerFontSize: opts.hasSpeaker ? bodyFont * speakerScale : 0,
+      overflow: !ok,
+    };
+  }
+
+  // Descend from max to min font (0.5px steps) and take the first that fits.
+  for (let f = maxFont; f >= minFont; f -= 0.5) {
+    const { lines, ok } = fit(f);
+    if (ok) {
+      return {
+        lines,
+        fontSize: f,
+        lineHeight: f * lineHeightFactor,
+        speakerFontSize: opts.hasSpeaker ? f * speakerScale : 0,
+        overflow: false,
+      };
+    }
+  }
+
+  // Nothing fits even at min — best effort: wrap at min font (may overflow).
+  const lines = wrapText(measure, text, availW, minFont);
+  return {
+    lines,
+    fontSize: minFont,
+    lineHeight: minFont * lineHeightFactor,
+    speakerFontSize: opts.hasSpeaker ? minFont * speakerScale : 0,
+    overflow: true,
+  };
+}
+
+/**
+ * Default body min/max font sizes for a bubble, as fractions of the rendering
+ * HEIGHT so the export (natural image size) and the editor preview (displayed
+ * size) scale together — identical wrapping at both scales. `renderHeight` is
+ * the canvas/image height in the caller's pixel space.
+ */
+export function defaultBubbleFontRange(renderHeight: number): { minFontSize: number; maxFontSize: number } {
+  return {
+    minFontSize: Math.max(1, renderHeight * 0.022),
+    maxFontSize: Math.max(1, renderHeight * 0.05),
+  };
+}

package/app/lib/cartoon-coach.ts

@@ -0,0 +1,198 @@
+// Persistent cartoon workflow coach (#429).
+//
+// The cartoon production flow is long and non-obvious — create story → bible →
+// Genesis → plan cuts → clean images → letter → export → upload → prepare →
+// publish → verify. Each individual screen was improved across #418–#427, but a
+// normal writer still needs ONE persistent, front-end guide that converts the
+// current story/episode state into a single clear next action, without reading
+// terminal logs or technical warnings.
+//
+// This derives that coach PURELY from the already-built `StoryProgress` (which
+// the route assembles from .story.json, structure.md, genesis.md, the cuts.json
+// files, local assets, exports, uploaded URLs and publish status), plus a small
+// per-episode disk hint (clean images present on disk but not yet recorded). It
+// returns one stage label + one primary action, typed as either an agent
+// copy-paste prompt or a direct in-app UI action. Fiction returns null so the
+// fiction UX is completely untouched.
+
+import type { StoryProgress, EpisodeProgress } from "./story-progress";
+
+/** A direct, app-driven next step the UI can perform/route to. */
+export type CoachUiAction =
+  | "open-cuts" // reveal the cut workspace
+  | "open-lettering" // open the cut workspace to letter / export
+  | "refresh-assets" // re-scan local clean images (#427)
+  | "upload" // upload the final images
+  | "generate-markdown" // "Prepare the episode for publish"
+  | "publish" // publish the episode to PlotLink
+  | "view-progress"; // open the story progress overview (#418)
+
+export type CoachActionKind = "agent" | "ui";
+
+export interface CartoonCoach {
+  /** Short current-stage label, e.g. "Clean images ready". */
+  stageLabel: string;
+  /** One primary next action in user-facing verbs, e.g. "Review cuts and start lettering". */
+  action: string;
+  actionKind: CoachActionKind;
+  /** Copy-paste agent prompt when `actionKind === "agent"`; null for UI actions. */
+  prompt: string | null;
+  /** The in-app action key when `actionKind === "ui"`; null for agent actions. */
+  uiAction: CoachUiAction | null;
+  /** Episode this action concerns (so the overview can deep-link), or null for setup-level steps. */
+  episodeFile: string | null;
+}
+
+export interface CoachOptions {
+  /**
+   * Currently-viewed file (e.g. "plot-02.md"). When it names an unfinished
+   * cartoon episode the coach speaks about THAT episode, so a future-episode
+   * placeholder reads as "Plan this episode first" instead of pointing at the
+   * story's active episode. Ignored for non-episode files (structure.md) and
+   * already-published episodes — those fall back to the story's active episode.
+   */
+  focusFile?: string | null;
+  /**
+   * Per-episode count of clean images present on disk but NOT yet recorded in
+   * cuts.json (acceptance #2). When > 0 at the clean-image stage the coach
+   * surfaces "Refresh assets" (re-detect) instead of "Generate clean images".
+   */
+  undetectedCleanByFile?: Record<string, number>;
+}
+
+function agent(stageLabel: string, action: string, prompt: string, episodeFile: string | null): CartoonCoach {
+  return { stageLabel, action, actionKind: "agent", prompt, uiAction: null, episodeFile };
+}
+
+function ui(stageLabel: string, action: string, uiAction: CoachUiAction, episodeFile: string | null): CartoonCoach {
+  return { stageLabel, action, actionKind: "ui", prompt: null, uiAction, episodeFile };
+}
+
+/** "genesis.cuts.json" | "plot-01.cuts.json" — the cut plan a writer points the agent at. */
+function cutsFileName(episodeFile: string): string {
+  return episodeFile === "genesis.md" ? "genesis.cuts.json" : episodeFile.replace(/\.md$/, ".cuts.json");
+}
+
+/**
+ * Convert the story/episode state into the single next action a cartoon writer
+ * should take. Returns null for fiction (so fiction UX is unchanged) and for a
+ * cartoon story that is already fully published with nothing queued.
+ */
+export function deriveCartoonCoach(progress: StoryProgress, opts: CoachOptions = {}): CartoonCoach | null {
+  if (progress.contentType !== "cartoon") return null;
+
+  // Setup gates block the whole story, so they take priority over any episode —
+  // regardless of which file is in focus. These mirror buildStoryProgress's
+  // setup ordering so the coach never disagrees with the progress overview.
+  if (!progress.setup.hasStructure) {
+    return agent(
+      "New cartoon story",
+      "Write the story bible",
+      "Let's build this cartoon. Write the story bible (structure.md) — visual style, character bible, and episode format. Don't generate images, letter, upload, or publish yet.",
+      "structure.md",
+    );
+  }
+  if (!progress.setup.hasGenesis) {
+    return agent(
+      "Story bible ready",
+      "Write the Genesis (Episode 1) opening",
+      "Write the Genesis (Episode 1) opening for this cartoon, then plan its cuts in genesis.cuts.json. Don't generate images yet.",
+      "genesis.md",
+    );
+  }
+
+  // The episode the coach speaks about: the focused file when it's an unfinished
+  // episode, otherwise the story's active (first unpublished) episode.
+  const episodes = progress.episodes;
+  const focused = opts.focusFile ? episodes.find((e) => e.file === opts.focusFile) : undefined;
+  const active = episodes.find((e) => !e.published);
+  const ep = focused && !focused.published ? focused : active;
+
+  if (!ep) {
+    // Every episode is published — nudge toward the next one rather than a wall
+    // of "all done".
+    return agent(
+      "All episodes published",
+      "Start the next episode",
+      "Plan the cuts for the next episode in a new cuts.json. Don't generate images yet.",
+      null,
+    );
+  }
+
+  return coachForEpisode(ep, opts.undetectedCleanByFile?.[ep.file] ?? 0);
+}
+
+/**
+ * The per-episode production pipeline, in the order a writer performs it
+ * (#429): plan cuts → clean images → letter → export → upload → prepare →
+ * publish. Each stage emits one stage label + one primary action; the
+ * pre-image steps are agent prompts, the rest are in-app UI actions.
+ */
+function coachForEpisode(ep: EpisodeProgress, undetectedClean: number): CartoonCoach {
+  const c = ep.cuts;
+  const label = ep.label;
+  const file = ep.file;
+  const isGenesis = ep.kind === "genesis";
+
+  // No cut plan yet — a not-started episode or a future-episode placeholder.
+  // Acceptance #3: this reads as "plan this first", never a publish warning.
+  if (!c || c.total === 0) {
+    return agent(
+      `${label} not started`,
+      isGenesis ? "Plan the Genesis cuts" : "Plan this episode first",
+      isGenesis
+        ? "Plan the cuts for the Genesis (Episode 1) in genesis.cuts.json. Don't generate images, letter, upload, or publish yet."
+        : `Plan the cuts for ${label} in ${cutsFileName(file)}. Don't generate images, letter, upload, or publish yet.`,
+      file,
+    );
+  }
+
+  // 1) Clean images — agent-generated. If images are already on disk but not yet
+  //    recorded, the next action is a read-only re-scan instead (#427), not a
+  //    redundant "generate again".
+  if (c.withClean < c.needClean) {
+    if (undetectedClean > 0) {
+      return ui(
+        "Clean images found on disk",
+        "Refresh assets to detect them",
+        "refresh-assets",
+        file,
+      );
+    }
+    return agent(
+      `${label} cuts planned`,
+      "Generate clean images",
+      `Generate clean images for every cut in ${cutsFileName(file)}. Don't letter, upload, or publish yet.`,
+      file,
+    );
+  }
+
+  // 2) Lettering — place speech bubbles & captions in the cut workspace.
+  if (c.withText < c.needClean) {
+    return ui("Clean images ready", "Review cuts and start lettering", "open-lettering", file);
+  }
+
+  // 3) Export the lettered final images.
+  if (c.exported < c.total) {
+    return ui("Lettering in progress", "Finish and export the final images", "open-lettering", file);
+  }
+
+  // 4) Upload the exported final images.
+  if (c.uploaded < c.total) {
+    return ui("Final images ready", "Upload the final images", "upload", file);
+  }
+
+  // 5) Every cut is uploaded — assemble the publish layout, then publish. Driven
+  //    by the same readiness state the per-file publish UI uses, so the coach and
+  //    the publish controls never disagree.
+  switch (ep.state) {
+    case "ready":
+      return ui("Ready to publish", `Publish ${label} to PlotLink`, "publish", file);
+    case "blocked":
+      return ui("Needs fixes before publishing", "Review and fix the publish issues", "open-cuts", file);
+    case "planning":
+    default:
+      // Images uploaded but the publish layout (cut blocks) isn't built yet.
+      return ui("Images uploaded", "Prepare the episode for publish", "generate-markdown", file);
+  }
+}