plotlink-ows 1.0.32 → 1.2.94

package/app/lib/public-title.ts

@@ -0,0 +1,65 @@
+/**
+ * Parse the public title PlotLink renders into a story/plot page's metadata
+ * (#379). There is no public JSON read endpoint (`/api/storyline/<id>` 404s), so
+ * the reliable source for the INDEXED public title is the rendered page's
+ * `<meta property="og:title">` (mirrored by `<title> … — PlotLink`):
+ *
+ *   /story/<id>            → og:title "<storylineTitle>"                (e.g. "genesis")
+ *   /story/<id>/<plotIdx>  → og:title "<plotTitle> — <storylineTitle>"  (e.g. "plot-01 — genesis")
+ *
+ * These helpers are pure so they can be unit-tested against the real page shape;
+ * the OWS server does the page fetch (no CORS) in the publish route.
+ */
+
+// PlotLink joins title segments with a spaced em dash, and suffixes <title> with
+// the site name.
+const TITLE_SEP = " — ";
+const SITE_SUFFIX = /\s*—\s*PlotLink\s*$/i;
+
+function decodeEntities(s: string): string {
+  return s
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&#0?39;/g, "'")
+    .replace(/&#x27;/gi, "'")
+    .replace(/&quot;/g, '"');
+}
+
+/**
+ * The page's public title text: `og:title` when present, else `<title>` with the
+ * " — PlotLink" site suffix stripped. Returns null when neither is present.
+ */
+export function extractOgTitle(html: string): string | null {
+  const og =
+    html.match(/<meta[^>]+property=["']og:title["'][^>]*\scontent=["']([^"']*)["']/i) ||
+    html.match(/<meta[^>]+\scontent=["']([^"']*)["'][^>]*property=["']og:title["']/i);
+  const ogVal = og?.[1]?.trim();
+  if (ogVal) return decodeEntities(ogVal);
+
+  const t = html.match(/<title>([^<]*)<\/title>/i);
+  const tVal = t?.[1] ? decodeEntities(t[1].trim()).replace(SITE_SUFFIX, "").trim() : "";
+  return tVal || null;
+}
+
+/**
+ * The plot-title portion of a plot page title, where og:title is
+ * "<plotTitle> — <storylineTitle>". Strip only the FINAL storyline segment,
+ * not the first separator, because a real episode title may itself contain
+ * " — " (e.g. "Episode 1 — The Couple Coupon — Coupon Crush"). Returns the
+ * whole value when there is no separator. Null for empty/missing input.
+ */
+export function leadingTitleSegment(title: string | null, storylineTitle?: string | null): string | null {
+  if (!title) return null;
+  const story = storylineTitle?.trim();
+  if (story) {
+    const suffix = `${TITLE_SEP}${story}`;
+    if (title.endsWith(suffix)) {
+      const seg = title.slice(0, -suffix.length).trim();
+      if (seg) return seg;
+    }
+  }
+  const idx = title.lastIndexOf(TITLE_SEP);
+  const seg = (idx === -1 ? title : title.slice(0, idx)).trim();
+  return seg || null;
+}

package/app/lib/publish.ts

@@ -9,6 +9,7 @@ import {
   signTransaction as owsSignTx,
   signMessage as owsSignMsg,
 } from "@open-wallet-standard/core";
+import { canonicalizeGenre } from "../../lib/genres";
 
 // Contract addresses (Base mainnet)
 const STORY_FACTORY = "0x9D2AE1E99D0A6300bfcCF41A82260374e38744Cf" as const;
@@ -295,6 +296,7 @@ export async function publishStoryline(
   onProgress: (progress: PublishProgress) => void,
   language?: string,
   isNsfw?: boolean,
+  contentType?: string,
 ): Promise<PublishResult> {
   // Normalize optional fields to backwards-compatible defaults
   const normalizedLanguage = language || "English";
@@ -340,7 +342,7 @@ export async function publishStoryline(
   // Streams "Indexing…" progress so the user does not escalate to Retry Publish.
   const indexError = await indexWithDelayAndRetry(
     "storyline",
-    { txHash, content, genre, language: normalizedLanguage, isNsfw: normalizedIsNsfw },
+    { txHash, content, genre, language: normalizedLanguage, isNsfw: normalizedIsNsfw, ...(contentType ? { contentType } : {}) },
     onProgress,
     txHash,
     contentCid,
@@ -510,6 +512,18 @@ export async function updateStoryline(
   const PLOTLINK_URL = process.env.NEXT_PUBLIC_APP_URL || "https://plotlink.xyz";
   const account = createOwsAccount(walletName, walletAddress);
 
+  // Defense-in-depth (#412): even if a caller bypassed the route's canonicalization,
+  // map the genre to a canonical PlotLink value before signing — a non-empty genre
+  // that can't be mapped is rejected here rather than leaving the story uncategorized.
+  const normalizedUpdates = { ...updates };
+  if (updates.genre !== undefined) {
+    const canonical = canonicalizeGenre(updates.genre);
+    if (updates.genre.trim() && !canonical) {
+      throw new Error(`Invalid genre "${updates.genre}". Use a canonical PlotLink genre.`);
+    }
+    normalizedUpdates.genre = canonical ?? undefined;
+  }
+
   const timestamp = Date.now();
   const message = `PlotLink: Update storyline #${storylineId}\nTimestamp: ${timestamp}`;
   const signature = await account.signMessage({ message });
@@ -521,7 +535,7 @@ export async function updateStoryline(
       storylineId,
       signature,
       message,
-      ...updates,
+      ...normalizedUpdates,
     }),
   });
 

package/app/lib/story-progress.ts

@@ -0,0 +1,243 @@
+// Story-level production progress model (#418).
+//
+// After creating a cartoon story the writer is dropped into files + terminal
+// output with no product-level view of what's done and what's next. This builds
+// a single workflow map — story metadata, setup, cover, and per-episode state —
+// from already-available data (story meta, per-episode markdown + cuts, cover
+// detection), reusing the cartoon readiness helpers so the overview agrees with
+// the per-file publish UI. Pure + framework-free so it's unit-testable; the
+// route reads the files and the panel just renders the result.
+
+import type { Cut } from "./cuts";
+import type { CartoonCoach } from "./cartoon-coach";
+import {
+  classifyCartoonReadiness,
+  summarizeCutProgress,
+  cartoonChecklist,
+  type CartoonChecklistStep,
+} from "./cartoon-readiness";
+
+export type EpisodeState =
+  | "placeholder"   // cartoon: no cuts planned yet (a future-episode stub)
+  | "planning"      // cartoon: cut plan set, publish layout not built
+  | "in-progress"   // cartoon: building images / awaiting uploads
+  | "ready"         // ready to publish
+  | "blocked"       // needs fixes
+  | "draft"         // fiction: written, not published
+  | "published";
+
+export interface EpisodeProgress {
+  /** File this episode maps to, e.g. "genesis.md" | "plot-01.md". */
+  file: string;
+  /** Reader-facing label: "Episode 1 / Genesis", "Episode 2", "Chapter 1". */
+  label: string;
+  kind: "genesis" | "plot";
+  title: string | null;
+  state: EpisodeState;
+  /** One concise line — no raw validator text. */
+  summary: string;
+  published: boolean;
+  /**
+   * Cartoon cut progress; null for fiction. `needClean`/`withText` count IMAGE
+   * cuts only (text panels are excluded), so the workflow coach (#429) can tell
+   * the clean-image stage from the lettering stage.
+   */
+  cuts: { total: number; needClean: number; withClean: number; withText: number; exported: number; uploaded: number } | null;
+  /**
+   * Per-step production checklist (plan → clean → letter → export → upload →
+   * publish) for the cartoon workflow map (#438), reusing the same `cartoonChecklist`
+   * the per-file workflow guide uses so the progress page and the file view agree.
+   * Null for fiction; an empty array for a not-started cartoon episode (no cuts
+   * planned yet), which the map renders as a "not started" stub.
+   */
+  checklist: CartoonChecklistStep[] | null;
+}
+
+export interface StoryProgress {
+  name: string;
+  contentType: "fiction" | "cartoon";
+  metadata: {
+    title: string | null;
+    language: string | null;
+    genre: string | null;
+    isNsfw: boolean | null;
+    contentType: "fiction" | "cartoon";
+  };
+  setup: { hasStructure: boolean; hasGenesis: boolean };
+  /** Cover state (meaningful for cartoon; fiction may ignore). */
+  cover: "missing" | "present" | "invalid";
+  episodes: EpisodeProgress[];
+  summary: {
+    episodes: number;
+    published: number;
+    readyToPublish: number;
+    placeholders: number;
+    blocked: number;
+  };
+  /** Single product-level next step in plain language, or null if all done. */
+  nextAction: string | null;
+  /** A copy-paste prompt the writer can hand to the agent for the next step
+   * (#423), or null when the next step is a UI action (cover/publish) not an
+   * agent task. */
+  nextPrompt: string | null;
+  /**
+   * Persistent workflow coach (#429): the single next action derived from the
+   * current state, typed as an agent prompt or an in-app UI action. Attached by
+   * the route (it needs the focused file + on-disk asset hints); null for
+   * fiction. Absent when not computed (e.g. the pure builder), so existing
+   * consumers reading only nextAction/nextPrompt are unaffected.
+   */
+  coach?: CartoonCoach | null;
+}
+
+export interface EpisodeInput {
+  /** "genesis.md" | "plot-01.md". */
+  file: string;
+  status: "published" | "published-not-indexed" | "pending" | "draft";
+  /** Publish-facing markdown content. */
+  markdown: string;
+  /** Parsed cuts (cartoon); null when there's no cuts.json (fiction or none). */
+  cuts: Cut[] | null;
+  /** Episode title from cuts.json, if any. */
+  title: string | null;
+}
+
+export interface StoryProgressInput {
+  name: string;
+  contentType: "fiction" | "cartoon";
+  title: string | null;
+  language?: string | null;
+  genre?: string | null;
+  isNsfw?: boolean | null;
+  hasStructure: boolean;
+  hasGenesis: boolean;
+  cover: "missing" | "present" | "invalid";
+  /** Ordered: genesis first, then plot-01, plot-02, … */
+  episodes: EpisodeInput[];
+}
+
+function isPublished(status: EpisodeInput["status"]): boolean {
+  return status === "published" || status === "published-not-indexed";
+}
+
+/** "Episode 2" for plot-01 (genesis is Episode 1), "Chapter 1" for fiction. */
+function episodeLabel(file: string, kind: "genesis" | "plot", contentType: "fiction" | "cartoon"): string {
+  if (kind === "genesis") return contentType === "cartoon" ? "Episode 1 / Genesis" : "Genesis";
+  const n = parseInt(file.match(/^plot-(\d+)\.md$/)?.[1] ?? "0", 10);
+  return contentType === "cartoon" ? `Episode ${n + 1}` : `Chapter ${n}`;
+}
+
+function cartoonEpisode(ep: EpisodeInput, contentType: "fiction" | "cartoon"): EpisodeProgress {
+  const kind = ep.file === "genesis.md" ? "genesis" : "plot";
+  const label = episodeLabel(ep.file, kind, contentType);
+  const cuts = ep.cuts ?? [];
+  const p = summarizeCutProgress(cuts);
+  const published = isPublished(ep.status);
+  const checklist = cartoonChecklist({ cuts, published }).steps;
+  const base = { file: ep.file, label, kind, title: ep.title, published, checklist,
+    cuts: { total: p.total, needClean: p.needClean, withClean: p.withClean, withText: p.withText, exported: p.exported, uploaded: p.uploaded } } as const;
+
+  if (published) return { ...base, state: "published", summary: "Published to PlotLink" };
+
+  const stage = classifyCartoonReadiness(ep.markdown, cuts).stage;
+  switch (stage) {
+    case "not-started":
+      return { ...base, state: "placeholder", summary: "Not started — no cuts planned yet" };
+    case "planning":
+      return { ...base, state: "planning", summary: `Cut plan set (${p.total} cut${p.total === 1 ? "" : "s"}) — prepare for publish` };
+    case "awaiting-upload":
+      return { ...base, state: "in-progress", summary: `${p.uploaded} / ${p.total} cuts have uploaded images` };
+    case "ready":
+      return { ...base, state: "ready", summary: "Ready to publish" };
+    case "error":
+    default:
+      return { ...base, state: "blocked", summary: "Needs fixes before publishing" };
+  }
+}
+
+function fictionEpisode(ep: EpisodeInput): EpisodeProgress {
+  const kind = ep.file === "genesis.md" ? "genesis" : "plot";
+  const label = episodeLabel(ep.file, kind, "fiction");
+  const published = isPublished(ep.status);
+  return {
+    file: ep.file, label, kind, title: ep.title, published, cuts: null, checklist: null,
+    state: published ? "published" : "draft",
+    summary: published ? "Published to PlotLink" : "Drafted — ready to review and publish",
+  };
+}
+
+/**
+ * Build the story-level progress map. Cartoon episodes reuse the readiness
+ * classifier so a placeholder plot reads as "placeholder", never publish-ready;
+ * fiction gets a simpler written/published view. `nextAction` is the single
+ * plain-language step the writer should take next.
+ */
+export function buildStoryProgress(input: StoryProgressInput): StoryProgress {
+  const cartoon = input.contentType === "cartoon";
+  const episodes = input.episodes.map((ep) => (cartoon ? cartoonEpisode(ep, "cartoon") : fictionEpisode(ep)));
+
+  const published = episodes.filter((e) => e.published).length;
+  const readyToPublish = episodes.filter((e) => e.state === "ready").length;
+  const placeholders = episodes.filter((e) => e.state === "placeholder").length;
+  const blocked = episodes.filter((e) => e.state === "blocked").length;
+
+  let nextAction: string | null;
+  // A paste-ready agent prompt for the agent-driven stages; null for UI-only
+  // steps (cover/publish). Worded for the writer to copy verbatim (#423).
+  let nextPrompt: string | null = null;
+  if (!input.hasStructure) {
+    nextAction = "Ask the agent to write the story bible (structure.md).";
+    nextPrompt = cartoon
+      ? "Let's start this cartoon. Write the story bible (structure.md) — visual style, character bible, and episode format — then the Genesis (Episode 1) opening. Don't generate images, letter, upload, or publish yet."
+      : "Let's start this story. Write the structure (outline, characters, arc), then the Genesis hook.";
+  } else if (!input.hasGenesis) {
+    nextAction = cartoon
+      ? "Ask the agent to write the Genesis (Episode 1) opening."
+      : "Ask the agent to write the Genesis (story hook).";
+    nextPrompt = cartoon
+      ? "Write the Genesis (Episode 1) opening for this cartoon, then plan its cuts in genesis.cuts.json. Don't generate images yet."
+      : "Write the Genesis (story hook) for this story.";
+  } else {
+    const ready = episodes.find((e) => !e.published && e.state === "ready");
+    const working = episodes.find((e) => !e.published && (e.state === "planning" || e.state === "in-progress"));
+    const draft = episodes.find((e) => !e.published && e.state === "draft");
+    const placeholder = episodes.find((e) => !e.published && e.state === "placeholder");
+    // #462: a missing cover is a publish-readiness recommendation, not the
+    // primary step. It leads only once the active episode's production is
+    // complete (the `ready` case, or nothing pending) — never while an episode is
+    // mid-production. So episode production leads over a missing cover.
+    const coverMissing = cartoon && input.cover === "missing";
+    if (ready) nextAction = coverMissing ? "Create or import a cover image for the story." : `Publish ${ready.label}.`;
+    else if (working) nextAction = cartoon
+      ? `Continue ${working.label}: ${working.summary.toLowerCase()}.`
+      : `Review and publish ${working.label}.`;
+    else if (draft) nextAction = `Review and publish ${draft.label}.`;
+    else if (placeholder) {
+      nextAction = `Plan the cuts for ${placeholder.label} to start it.`;
+      nextPrompt = `Plan the cuts for ${placeholder.label} in its cuts.json. Don't generate images, letter, upload, or publish yet.`;
+    } else if (coverMissing) nextAction = "Create or import a cover image for the story.";
+    else if (episodes.length > 0 && published === episodes.length) nextAction = null; // all published
+    else {
+      nextAction = cartoon ? "Plan the next episode's cuts." : "Write the next chapter.";
+      nextPrompt = cartoon ? "Plan the cuts for the next episode in a new cuts.json. Don't generate images yet." : "Write the next chapter.";
+    }
+  }
+
+  return {
+    name: input.name,
+    contentType: input.contentType,
+    metadata: {
+      title: input.title,
+      language: input.language ?? null,
+      genre: input.genre ?? null,
+      isNsfw: input.isNsfw ?? null,
+      contentType: input.contentType,
+    },
+    setup: { hasStructure: input.hasStructure, hasGenesis: input.hasGenesis },
+    cover: input.cover,
+    episodes,
+    summary: { episodes: episodes.length, published, readyToPublish, placeholders, blocked },
+    nextAction,
+    nextPrompt,
+  };
+}

package/app/lib/terminal-protocol.ts

@@ -0,0 +1,16 @@
+// Shared control signals for the terminal WebSocket relay (#453).
+//
+// The relay normally carries raw PTY bytes both ways. When the server has to
+// SPAWN A FRESH agent process for a story (the previous PTY exited / the server
+// restarted) and the user asked to resume, that process reprints its own startup
+// banner and conversation. The client, meanwhile, has already restored the prior
+// session's scrollback from IndexedDB — so the banner would appear twice.
+//
+// To avoid that, the server sends FRESH_SPAWN_SIGNAL as the FIRST frame on a
+// fresh spawn. The client treats only the first frame of a connection as a
+// possible control signal: on FRESH_SPAWN_SIGNAL it drops the restored scrollback
+// (so just the fresh reprint shows); a live-PTY RECONNECT sends no signal, so the
+// client keeps its scrollback (the only copy of the prior output). It is a plain
+// ASCII sentinel (no control bytes) that a real PTY never emits as a standalone
+// first frame.
+export const FRESH_SPAWN_SIGNAL = "__OWS_FRESH_SESSION__";

package/app/lib/terminal-redact.ts

@@ -0,0 +1,50 @@
+// Display/log-safety redaction for the story terminal (#454).
+//
+// The central terminal relays raw agent/PTY output. If an agent (or a command a
+// writer runs) prints auth material — an Authorization/Bearer header, a session
+// token, or an OWS passphrase / login command — it would otherwise be shown in
+// plain text and persisted to the scrollback. This masks the obvious shapes on
+// the way to the terminal so a secret isn't rendered or stored.
+//
+// It is best-effort DISPLAY hardening only: it never changes what the server
+// sends, the wallet, PlotLink auth, or any request. It replaces only the secret
+// VALUE and keeps the surrounding key/word, so the line still reads sensibly
+// (e.g. `Authorization: Bearer [REDACTED]`). A token split across two streamed
+// frames may slip through — this reduces accidental exposure, it is not a
+// guarantee, which is why the agent guidance also tells agents not to print
+// secrets into the terminal.
+
+export const REDACTION_PLACEHOLDER = "[REDACTED]";
+
+// Each rule keeps capture group 1 (the key/prefix) and masks the value after it.
+// Value classes deliberately exclude whitespace, quotes, and `&` so a redaction
+// stops at the end of the token and never eats following text or ANSI escapes.
+// The value classes exclude whitespace, quotes, `&`, AND the ESC byte (\x1b) so a
+// redaction stops at the end of the token and never swallows a trailing ANSI
+// escape sequence (which would corrupt terminal colors/cursor state).
+const RULES: ReadonlyArray<readonly [RegExp, string]> = [
+  // `Authorization: Bearer <token>` (HTTP header form).
+  [/(authorization\s*:\s*bearer\s+)[^\s'"\x1b]+/gi, `$1${REDACTION_PLACEHOLDER}`],
+  // A standalone `Bearer <token>` — min length so the word "Bearer" in prose
+  // isn't masked.
+  [/(\bbearer\s+)[A-Za-z0-9._-]{12,}/gi, `$1${REDACTION_PLACEHOLDER}`],
+  // `token=<value>` / `?token=<value>` (e.g. the WS/login token in a URL).
+  [/(\btoken=)[^\s'"&\x1b]+/gi, `$1${REDACTION_PLACEHOLDER}`],
+  // The OWS passphrase env/var: `OWS_PASSPHRASE=<value>` or `OWS_PASSPHRASE: <value>`.
+  [/(OWS_PASSPHRASE\s*[=:]\s*)[^\s'"\x1b]+/gi, `$1${REDACTION_PLACEHOLDER}`],
+  // A `--passphrase <value>` / `--passphrase=<value>` login command fragment.
+  [/(--passphrase[=\s]+)[^\s'"\x1b]+/gi, `$1${REDACTION_PLACEHOLDER}`],
+  // A generic `passphrase: "<value>"` / `"passphrase":"<value>"` (quoted or not).
+  [/(passphrase["']?\s*[:=]\s*["']?)[^\s'"\x1b]+/gi, `$1${REDACTION_PLACEHOLDER}`],
+];
+
+/**
+ * Mask obvious auth secrets in a chunk of terminal output. Pure; returns the
+ * input unchanged when nothing matches (the common case), so normal terminal
+ * rendering and ANSI control sequences are untouched.
+ */
+export function redactTerminalSecrets(text: string): string {
+  let out = text;
+  for (const [re, repl] of RULES) out = out.replace(re, repl);
+  return out;
+}

package/app/prisma/schema.sql

@@ -0,0 +1,25 @@
+-- Canonical SQLite DDL for the local writer database.
+-- GENERATED from app/prisma/schema.prisma — do not edit by hand.
+-- Regenerate after any schema change:  npm run prisma:sql
+--
+-- Applied idempotently at startup via the Prisma client's library query engine
+-- (app/lib/apply-schema.ts) so the installed package never invokes the native
+-- Prisma schema-engine (`prisma db push`), which fails to spawn in some packed
+-- prod-only environments (#484, EPIC #465).
+
+-- CreateTable
+CREATE TABLE "Session" (
+    "id" TEXT NOT NULL PRIMARY KEY,
+    "token" TEXT NOT NULL,
+    "createdAt" DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expiresAt" DATETIME NOT NULL
+);
+
+-- CreateTable
+CREATE TABLE "Setting" (
+    "key" TEXT NOT NULL PRIMARY KEY,
+    "value" TEXT NOT NULL
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "Session_token_key" ON "Session"("token");

package/app/routes/agent.ts

@@ -0,0 +1,42 @@
+import { Hono } from "hono";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { probeAgentReadiness } from "../lib/agent-readiness";
+
+const execFileP = promisify(execFile);
+
+const agent = new Hono();
+
+/** GET /api/agent/readiness — probe local agent CLIs (detection only) */
+agent.get("/readiness", async (c) => {
+  try {
+    // Probe through a login shell so PATH matches the terminal's binary
+    // resolution (terminal.ts spawns `process.env.SHELL -l -c <cmd>`).
+    const shell = process.env.SHELL || "/bin/zsh";
+    const run = async (cmd: string) => {
+      try {
+        const { stdout } = await execFileP(shell, ["-l", "-c", cmd], {
+          timeout: 5000,
+        });
+        return { ok: true, stdout: stdout ?? "" };
+      } catch (e: unknown) {
+        const stdout =
+          e && typeof e === "object" && "stdout" in e
+            ? String((e as { stdout: unknown }).stdout ?? "")
+            : "";
+        return { ok: false, stdout };
+      }
+    };
+
+    const readiness = {
+      ...(await probeAgentReadiness(run)),
+      checkedAt: Date.now(),
+    };
+    return c.json(readiness);
+  } catch (error) {
+    console.error("Agent readiness error:", error);
+    return c.json({ error: "Failed to probe agent readiness" }, 500);
+  }
+});
+
+export { agent as agentRoutes };

package/app/routes/codex-images.ts

@@ -0,0 +1,67 @@
+import { Hono } from "hono";
+import fs from "fs";
+import path from "path";
+import { CODEX_IMAGES_DIR } from "../lib/paths";
+import { sniffImageType } from "../lib/clean-image-sync";
+import {
+  listCodexImages,
+  resolveCodexImagePath,
+  CODEX_MAX_RAW_BYTES,
+} from "../lib/codex-images";
+
+/**
+ * Codex generated-image cache handoff (#403). Read-only, authenticated routes
+ * that let the OWS UI surface the Codex image cache so a writer can import a
+ * generated PNG into a cut in one click — instead of hunting through a hidden
+ * `~/.codex/generated_images/…` folder in an OS file dialog. The browser does the
+ * PNG→WebP conversion and posts to the existing per-cut upload-clean route, so
+ * the manual upload path and its validation are unchanged.
+ */
+const codexImages = new Hono();
+
+const SNIFF_MIME: Record<string, string> = {
+  png: "image/png",
+  jpeg: "image/jpeg",
+  webp: "image/webp",
+};
+
+// GET /api/codex/images — recent Codex-generated cache images, newest first.
+// A missing cache directory simply lists empty (no error).
+codexImages.get("/images", (c) => {
+  return c.json({ images: listCodexImages(CODEX_IMAGES_DIR) });
+});
+
+// GET /api/codex/images/:token — raw bytes of one cache image (for the import
+// thumbnail and the import fetch). Path-safe, image-only, size-capped.
+codexImages.get("/images/:token", (c) => {
+  const resolved = resolveCodexImagePath(CODEX_IMAGES_DIR, c.req.param("token"));
+  if (!resolved) return c.json({ error: "Invalid image reference" }, 400);
+
+  try {
+    // Defense in depth against a symlinked cache entry escaping the root:
+    // resolveCodexImagePath only does logical path math, so re-check the
+    // boundary on the realpath (which follows symlinks) before reading.
+    const rootReal = fs.realpathSync(path.resolve(CODEX_IMAGES_DIR));
+    const fileReal = fs.realpathSync(resolved.abs);
+    if (fileReal !== rootReal && !fileReal.startsWith(rootReal + path.sep)) {
+      return c.json({ error: "Invalid image reference" }, 400);
+    }
+
+    const st = fs.statSync(fileReal);
+    if (!st.isFile()) return c.json({ error: "Not found" }, 404);
+    if (st.size > CODEX_MAX_RAW_BYTES) return c.json({ error: "Image too large" }, 413);
+
+    const buf = fs.readFileSync(fileReal);
+    const kind = sniffImageType(new Uint8Array(buf));
+    if (kind === "unknown") return c.json({ error: "Not an image" }, 415);
+
+    c.header("Content-Type", SNIFF_MIME[kind]);
+    c.header("Cache-Control", "no-store");
+    return c.body(new Uint8Array(buf));
+  } catch {
+    // Missing file, broken symlink, or unreadable entry — treat as not found.
+    return c.json({ error: "Not found" }, 404);
+  }
+});
+
+export { codexImages as codexImagesRoutes };