@kaydash9999/banker-plugins 0.15.1 → 0.16.0

package/skills/3d-intro-build/references/curate.mjs

@@ -1,301 +1,607 @@
 #!/usr/bin/env node
 /*
- * First-party still-curation server for the 3d-intro-build skill.
+ * Review page for the 3d-intro-build and motion-graphic-make skills (scripts/sync-adapter.js keeps
+ * the copies identical). Every take (a still, a clip, a snapshot, a render) is a card beside the
+ * prompt that made it, so a person judges the output and its instructions together, before any
+ * further paid step. The convention is a local page on an unused port, never a claude.ai artifact.
  *
- * Sits BETWEEN still generation (cheap paid) and video generation (the big paid step): the user
- * picks/approves one still per scene in a real browser BEFORE any Sora-2 call is spent. The project
- * convention is a self-contained local page on an unused port, never a claude.ai artifact.
- *
- * Contract (both files live in the project dir):
- *   IN   curate-input.json  {"scenes":[{"id","label","variants":[{"file","prompt?"}]}]}
- *          file = png path relative to projectDir (served with a path-traversal guard).
- *   OUT  selection.json     {"scenes":[{"id","chosen":<file>,"regenerate?":<note>}]}
- *          chosen = the file the user picked; regenerate = a tweaked-prompt note (present only when
- *          the user wants that scene re-generated). Written on POST /select.
- *
- * Routes:  GET /            -> curation page (rebuilt from curate-input.json each load, so a
- *                              regenerate-loop re-read shows fresh stills without a restart)
- *          GET /<img>       -> a still image (image/png/…; traversal-guarded; Cache-Control no-store)
- *          POST /select     -> writes selection.json, returns {ok:true}
- *
- * Runtime: Node >=18 builtins ONLY (node:http / node:fs / node:path). No external deps, no shell —
- * cross-platform (path.join / path.sep everywhere). Loopback by default; PREVIEW_HOST=0.0.0.0 for LAN.
+ * Files in the project folder:
+ *   IN   curate-input.json  { title?, stage, stageLabel?, promptLabel?, budgetUsd?, spentUsd?,
+ *                             scenes: [{ id, label?, takes: [{ file, take?, prompt?, negativePrompt?,
+ *                             model?, size?, seconds?, firstFrame?, lastFrame?, createdAt?, costUsd? }] }] }
+ *        stage: stills | clips | snapshots | render (or any name). `variants` is read as `takes`.
+ *        Every file is relative to the project folder; one outside it is refused.
+ *   OUT  decisions.json     { <stage>: { updatedAt, scenes: [{ id, verdict, chosen?, note?, rejected[],
+ *                             archived?, by: page|chat, at }] } }
+ *        verdict: approve (chosen is the take to use) | regenerate (note says what to change) | pending.
  *
  * Usage:
- *   node curate.mjs [projectDir] [--port N]
- *     projectDir   dir holding curate-input.json + the stills it references (default: cwd)
- *     --port       preferred port; falls back through a candidate list if busy/omitted
- *   On listen it writes <projectDir>/curate-port.txt and prints  CURATE http://localhost:<port>/
+ *   node curate.mjs [projectDir] [--port N]          serve the page (state: <projectDir>/curate.server.json)
+ *   node curate.mjs --stop [projectDir]              end that server
+ *   node curate.mjs --record [projectDir] --scene <id|n> --verdict approve|regenerate|reject|pending
+ *                   [--take <n|file>] [--note "..."]  record a verdict given in chat
+ *   node curate.mjs --archive [projectDir]           move rejected takes to rejected-YYYYMMDD/
+ *   PREVIEW_HOST=0.0.0.0 binds every interface and prints a warning.
+ * The server answers only the images and videos the input lists as takes and frames, inside the
+ * project by path and by link (never other files of the folder), only to a Host that is localhost
+ * or an IP address, and takes verdicts only as JSON from its own page; a page drawn before a newer
+ * verdict (one recorded in chat) gets 409 instead of overwriting it. Errors name no absolute path.
+ * A start while the recorded server runs only reports its address; with another PREVIEW_HOST or a
+ * --port other than the one it listens on or its own start asked for, it exits 1: --stop first.
+ * Each take's sha256 is read in chunks (any size) from the server start on, and again once the file
+ * changes.
+ *
+ * Runtime: Node >=18 builtins only. No shell, cross-platform.
  */
-import http from 'node:http';
+import crypto from 'node:crypto';
 import fs from 'node:fs';
+import http from 'node:http';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  LOOPBACK, READ_FLAGS, answersPid, decodePath, forgetSelf, hostAllowed, hostWarning, isRunning, listen, portMatches,
+  readState, resolveInside, send, sendFile, stopServer, urlFor, writeState,
+} from './preview-lib.mjs';
 
-// ---- args ----
-const argv = process.argv.slice(2);
-let dirArg = null;
-let portArg = null;
-for (let i = 0; i < argv.length; i++) {
-  const a = argv[i];
-  if (a === '--port') portArg = Number(argv[++i]);
-  else if (a.startsWith('--port=')) portArg = Number(a.slice('--port='.length));
-  else if (!a.startsWith('--')) dirArg = a;
-}
-
-const DIR = path.resolve(dirArg || process.cwd());
-if (!fs.existsSync(DIR) || !fs.statSync(DIR).isDirectory()) {
-  console.error(`curate: not a directory: ${DIR}`);
-  process.exit(1);
-}
-const INPUT = path.join(DIR, 'curate-input.json');
-const OUTPUT = path.join(DIR, 'selection.json');
-
-const MIME = {
-  '.html': 'text/html;charset=utf-8',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.gif': 'image/gif',
-  '.svg': 'image/svg+xml',
-};
+const INPUT = 'curate-input.json';
+const DECISIONS = 'decisions.json';
+const STATE = 'curate.server.json';
+const STAGE_LABELS = { stills: '스틸 검토', clips: '클립 검토', snapshots: '스냅숏 검토', render: '렌더 검토' };
+const INSTRUCTION_STAGES = new Set(['snapshots', 'render']);
+const VERDICTS = new Set(['approve', 'regenerate', 'reject', 'pending']);
+const VIDEO = /\.(mp4|webm|mov)$/i;
 
-// ---- html helpers ----
 const escHtml = (s) => String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
 const escAttr = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
-// posix URL for a project-relative file, each segment encoded (server decodes with decodeURIComponent)
+// A project-relative file as a URL path, each segment encoded.
 const fileUrl = (file) => '/' + String(file).replace(/^[.][/\\]/, '').split(/[\\/]/).map(encodeURIComponent).join('/');
+const money = (n) => `$${Number(Number(n).toFixed(3))}`;
+const inside = (dir, file) => typeof file === 'string' && file !== '' && resolveInside(dir, '/' + file) !== null;
+const MEDIA = /\.(png|jpe?g|webp|gif|mp4|webm|mov)$/i;
 
-function renderCard(v, sceneId, idx, selected) {
-  const cap = v.prompt ? `<span class="cap">${escHtml(v.prompt)}</span>` : '';
-  return `<button type="button" class="card${selected ? ' selected' : ''}" data-file="${escAttr(v.file)}">`
-    + `<img src="${escAttr(fileUrl(v.file))}" alt="${escAttr(sceneId)} 변형 ${idx + 1}" loading="lazy">${cap}</button>`;
+// Where a path's links lead: null when they stay in the project and end at an image or a video (a
+// file not there yet goes by its path), else why not.
+function linkRefusal(dir, fp) {
+  let real;
+  try { real = fs.realpathSync(fp); } catch { return null; }
+  if (!real.startsWith(fs.realpathSync(dir) + path.sep)) return '링크가 프로젝트 폴더 밖을 가리켜 보이지 않습니다.';
+  return MEDIA.test(real) ? null : '링크가 이미지나 영상이 아닌 파일을 가리켜 보이지 않습니다.';
 }
 
-function renderScene(s) {
-  const variants = Array.isArray(s.variants) ? s.variants : [];
-  const cards = variants.map((v, i) => renderCard(v, s.id, i, i === 0)).join('\n        ');
-  const body = cards || '<p class="empty">이 씬에 스틸 변형이 없습니다.</p>';
-  return `<section class="scene" data-scene-id="${escAttr(s.id)}">
-      <div class="scene-head">
-        <h2>${escHtml(s.label || s.id)}</h2>
-        <span class="chip keep" data-chip>이 스틸로 승인</span>
-      </div>
-      <div class="cards">
-        ${body}
-      </div>
-      <label class="regen">
-        <span>재생성 메모 (선택 · 비우면 위에서 고른 스틸로 승인)</span>
-        <textarea data-regen rows="2" placeholder="예: 배경을 더 어둡게, 캐릭터 2명 추가"></textarea>
-      </label>
-    </section>`;
-}
-
-function renderPage(manifest) {
-  const scenes = Array.isArray(manifest.scenes) ? manifest.scenes : [];
-  const rows = scenes.length ? scenes.map(renderScene).join('\n    ') : '<p class="empty">curate-input.json 에 scenes 가 없습니다.</p>';
-  return `<!doctype html>
-<html lang="ko">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>스틸 큐레이션${manifest.title ? ' — ' + escHtml(manifest.title) : ''}</title>
-<style>
-  :root {
-    --bg: #f5f3ef; --panel: #ffffff; --ink: #23202a; --muted: #6c6675;
-    --line: #e2ddd4; --accent: #7c5cbf; --accent-ink: #ffffff;
-    --keep: #2f7d4f; --keep-bg: #e6f3ea; --regen: #b26a00; --regen-bg: #fbefd8;
+// Why a listed file is neither shown nor served nor hashed, or null when it may be: it must be an
+// image or a video inside the project, by its path and by where its links lead, so a key file or
+// a record listed by mistake never leaves the folder.
+function refusal(dir, file) {
+  if (!inside(dir, file)) return '파일 경로가 프로젝트 폴더 밖이라 보이지 않습니다.';
+  if (!MEDIA.test(file)) return '이미지나 영상 파일이 아니라 보이지 않습니다.';
+  return linkRefusal(dir, path.join(dir, file));
+}
+
+// ---- input and decisions ----------------------------------------------------
+
+export function readInput(dir) {
+  const raw = JSON.parse(fs.readFileSync(path.join(dir, INPUT), 'utf8'));
+  const scenes = (Array.isArray(raw.scenes) ? raw.scenes : []).map((s, i) => ({
+    ...s, id: String(s.id ?? `scene-${i + 1}`), label: s.label || String(s.id ?? `scene-${i + 1}`),
+    takes: (Array.isArray(s.takes) ? s.takes : Array.isArray(s.variants) ? s.variants : [])
+      .map((t, j) => ({ ...t, take: t.take ?? j + 1 })),
+  }));
+  return { ...raw, stage: raw.stage || 'stills', scenes };
+}
+
+// No file yet is an empty record; a file that does not parse stops the work, so that a hand edit gone
+// wrong is not replaced with the other stages' verdicts lost.
+export function readDecisions(dir) {
+  let text;
+  try { text = fs.readFileSync(path.join(dir, DECISIONS), 'utf8'); } catch (e) {
+    if (e.code === 'ENOENT') return {};
+    throw e;
   }
-  @media (prefers-color-scheme: dark) {
-    :root {
-      --bg: #17151b; --panel: #201d26; --ink: #ece8f1; --muted: #a49db1;
-      --line: #322d3c; --accent: #a488e6; --accent-ink: #17151b;
-      --keep: #7fd3a0; --keep-bg: #1d3327; --regen: #e6b063; --regen-bg: #3a2c14;
-    }
+  try { return JSON.parse(text); } catch (e) {
+    throw new Error(`curate: ${DECISIONS} 을 읽지 못했습니다(${e.message}). 고치거나 지운 뒤 다시 하세요`);
   }
-  * { box-sizing: border-box; }
-  body { margin: 0; background: var(--bg); color: var(--ink);
-    font: 15px/1.5 system-ui, -apple-system, "Segoe UI", "Noto Sans KR", sans-serif; }
-  .bar { position: sticky; top: 0; z-index: 5; background: var(--panel);
-    border-bottom: 1px solid var(--line); }
-  .bar-in { max-width: 1100px; margin: 0 auto; padding: 12px 20px;
-    display: flex; align-items: center; gap: 16px; justify-content: space-between; }
-  .muted { color: var(--muted); font-size: 13px; }
-  .btn { border: 0; border-radius: 8px; background: var(--accent); color: var(--accent-ink);
-    font-size: 14px; font-weight: 600; padding: 10px 18px; cursor: pointer; }
-  .btn:disabled { opacity: .5; cursor: default; }
-  main { max-width: 1100px; margin: 0 auto; padding: 20px; }
-  .scene { background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
-    padding: 16px; margin-bottom: 18px; }
-  .scene-head { display: flex; align-items: center; gap: 12px; margin: 0 0 12px; }
-  .scene-head h2 { font-size: 17px; margin: 0; }
-  .chip { font-size: 12px; font-weight: 600; padding: 3px 10px; border-radius: 999px; }
-  .chip.keep { color: var(--keep); background: var(--keep-bg); }
-  .chip.regen-on { color: var(--regen); background: var(--regen-bg); }
-  .cards { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 12px; }
-  .card { padding: 0; border: 2px solid var(--line); border-radius: 10px; background: var(--panel);
-    cursor: pointer; overflow: hidden; text-align: left; display: flex; flex-direction: column; }
-  .card img { display: block; width: 100%; height: auto; aspect-ratio: 3 / 4; object-fit: cover; }
-  .card .cap { padding: 8px 10px; font-size: 12px; color: var(--muted);
-    display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; }
-  .card.selected { border-color: var(--accent); box-shadow: 0 0 0 3px color-mix(in srgb, var(--accent) 30%, transparent); }
-  .regen { display: block; margin-top: 12px; }
-  .regen span { display: block; font-size: 13px; color: var(--muted); margin-bottom: 6px; }
-  .regen textarea { width: 100%; resize: vertical; border: 1px solid var(--line); border-radius: 8px;
-    padding: 8px 10px; font: inherit; background: var(--bg); color: var(--ink); }
-  .empty { color: var(--muted); }
-  [hidden] { display: none !important; }
-  .done { position: fixed; inset: 0; display: flex; align-items: center; justify-content: center;
-    background: color-mix(in srgb, var(--bg) 82%, transparent); z-index: 10; }
-  .done-card { background: var(--panel); border: 1px solid var(--line); border-radius: 12px;
-    padding: 28px 36px; font-size: 18px; font-weight: 600; }
-</style>
-</head>
-<body>
-<header class="bar">
-  <div class="bar-in">
-    <div><strong>스틸 큐레이션</strong> <span class="muted">씬별로 스틸을 고르고, 다시 만들 씬엔 메모를 남기세요 (영상 생성은 이 확정 이후에만)</span></div>
-    <button id="confirm" class="btn">선택 확정</button>
-  </div>
-</header>
-<main id="app">
-    ${rows}
-</main>
-<div id="done" class="done" hidden><div class="done-card">선택 저장됨 — 에이전트로 돌아가세요</div></div>
-<script>
-  const app = document.getElementById('app');
-  app.addEventListener('click', (e) => {
-    const card = e.target.closest('.card');
-    if (!card) return;
-    const scene = card.closest('.scene');
-    scene.querySelectorAll('.card').forEach((c) => c.classList.remove('selected'));
-    card.classList.add('selected');
-  });
-  app.addEventListener('input', (e) => {
-    const ta = e.target.closest('[data-regen]');
-    if (!ta) return;
-    const chip = ta.closest('.scene').querySelector('[data-chip]');
-    const has = ta.value.trim() !== '';
-    chip.textContent = has ? '재생성 요청됨' : '이 스틸로 승인';
-    chip.classList.toggle('regen-on', has);
-    chip.classList.toggle('keep', !has);
+}
+
+// Written whole or not at all: a crash mid-write leaves the previous file.
+function writeJson(file, value) {
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify(value, null, 2) + '\n');
+  fs.renameSync(`${file}.tmp`, file);
+}
+
+const writeDecisions = (dir, all) => writeJson(path.join(dir, DECISIONS), all);
+
+// The verdict a scene's choice and note add up to: a note asks for a new take.
+const verdictOf = (e) => (e.note ? 'regenerate' : e.chosen ? 'approve' : 'pending');
+
+function entryFor(stageDecisions, id) {
+  let e = stageDecisions.scenes.find((x) => x.id === id);
+  if (!e) stageDecisions.scenes.push((e = { id, verdict: 'pending', rejected: [] }));
+  e.rejected = Array.isArray(e.rejected) ? e.rejected : [];
+  return e;
+}
+
+function stageOf(all, stage) {
+  all[stage] = all[stage] && Array.isArray(all[stage].scenes) ? all[stage] : { scenes: [] };
+  return all[stage];
+}
+
+function findScene(input, ref) {
+  const byId = input.scenes.find((s) => s.id === String(ref));
+  const byNumber = /^\d+$/.test(String(ref)) ? input.scenes[Number(ref) - 1] : undefined;
+  const scene = byId || byNumber;
+  if (!scene) throw new Error(`curate: 장면 ${ref} 을 찾지 못했습니다`);
+  return scene;
+}
+
+function findTake(scene, ref) {
+  const take = scene.takes.find((t) => String(t.take) === String(ref) || t.file === ref);
+  if (!take) throw new Error(`curate: ${scene.id} 에 테이크 ${ref} 가 없습니다`);
+  return take.file;
+}
+
+// How a verdict given in chat changes one scene's entry. A reject drops the take from the choice.
+const CHAT_VERDICTS = {
+  pending: (e) => Object.assign(e, { rejected: [], chosen: undefined, note: undefined }),
+  approve: (e, file, note) => Object.assign(e, { chosen: file, note: note || undefined, rejected: e.rejected.filter((f) => f !== file) }),
+  reject: (e, file) => {
+    if (!e.rejected.includes(file)) e.rejected.push(file);
+    if (e.chosen === file) e.chosen = undefined;
+  },
+  regenerate: (e, file, note) => {
+    if (note !== undefined) e.note = note || undefined;
+    if (file) e.chosen = file;
+  },
+};
+
+function applyVerdict(e, verdict, file, note) {
+  CHAT_VERDICTS[verdict](e, file, note);
+  e.verdict = verdict === 'regenerate' ? 'regenerate' : verdictOf(e);
+  return e;
+}
+
+/** Records a verdict given in chat: scene by id or 1-based number, take by number or file. */
+export function recordDecision(dir, { scene, verdict, take, note }, now = new Date()) {
+  if (!VERDICTS.has(verdict)) throw new Error(`curate: 판정은 approve, regenerate, reject, pending 중 하나입니다 (${verdict})`);
+  const input = readInput(dir);
+  const s = findScene(input, scene);
+  const needsTake = verdict === 'approve' || verdict === 'reject';
+  if (needsTake && take === undefined) throw new Error(`curate: ${verdict} 에는 테이크 번호가 필요합니다`);
+  const file = take === undefined ? undefined : findTake(s, take);
+  const all = readDecisions(dir);
+  const stage = stageOf(all, input.stage);
+  const e = applyVerdict(entryFor(stage, s.id), verdict, file, note);
+  Object.assign(e, { by: 'chat', at: now.toISOString() });
+  stage.updatedAt = now.toISOString();
+  writeDecisions(dir, all);
+  return e;
+}
+
+const stale = () => Object.assign(new Error('curate: 페이지를 연 뒤 판정이 바뀌었습니다. 새로 고친 뒤 다시 저장하세요'), { status: 409 });
+
+// One scene's verdict as the page sends it: the chosen take, a note, the rejected takes.
+function pageEntry(stage, scene, p, now) {
+  const files = new Set(scene.takes.map((t) => t.file));
+  if (p.chosen && !files.has(p.chosen)) throw new Error(`curate: ${scene.id} 의 선택이 테이크가 아닙니다`);
+  const rejected = (Array.isArray(p.rejected) ? p.rejected : []).filter((f) => files.has(f));
+  const e = entryFor(stage, scene.id);
+  Object.assign(e, { chosen: p.chosen || undefined, note: String(p.note ?? '').trim() || undefined, rejected });
+  return Object.assign(e, { verdict: verdictOf(e), by: 'page', at: now.toISOString() });
+}
+
+// Verdicts the page sends. `basedOn` is the record the page was drawn from; a verdict recorded since
+// (in chat) is not overwritten.
+function applyPageDecisions(dir, payload, now = new Date()) {
+  const input = readInput(dir);
+  const all = readDecisions(dir);
+  const stage = stageOf(all, input.stage);
+  if ((payload.basedOn || '') !== (stage.updatedAt || '')) throw stale();
+  for (const p of Array.isArray(payload.scenes) ? payload.scenes : []) pageEntry(stage, findScene(input, p.id), p, now);
+  stage.updatedAt = now.toISOString();
+  writeDecisions(dir, all);
+  return stage;
+}
+
+const dated = (now) => `rejected-${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`;
+
+// Moves a take into `folder`, keeping its place relative to the project however its path is spelled.
+function moveInto(dir, file, folder) {
+  const src = path.normalize(path.join(dir, file));
+  const rel = path.relative(dir, src);
+  const dest = path.join(dir, folder, rel);
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.renameSync(src, dest);
+  return { file, to: [folder, ...rel.split(path.sep)].join('/') };
+}
+
+/** Moves the current stage's rejected takes into rejected-YYYYMMDD/ and drops them from the input. */
+export function archiveRejected(dir, { now = new Date() } = {}) {
+  const raw = JSON.parse(fs.readFileSync(path.join(dir, INPUT), 'utf8'));
+  const input = readInput(dir);
+  const all = readDecisions(dir);
+  const stage = stageOf(all, input.stage);
+  const moves = [];
+  for (const e of stage.scenes) {
+    const moved = e.rejected.filter((f) => !refusal(dir, f) && fs.existsSync(path.join(dir, f))).map((f) => moveInto(dir, f, dated(now)));
+    e.archived = [...(e.archived || []), ...moved];
+    e.rejected = e.rejected.filter((f) => !moved.some((m) => m.file === f));
+    moves.push(...moved);
+  }
+  if (!moves.length) return moves;
+  const gone = new Set(moves.map((m) => m.file));
+  for (const s of raw.scenes || []) {
+    for (const key of ['takes', 'variants']) if (Array.isArray(s[key])) s[key] = s[key].filter((t) => !gone.has(t.file));
+  }
+  writeJson(path.join(dir, INPUT), raw);
+  writeDecisions(dir, all);
+  return moves;
+}
+
+// ---- the page -----------------------------------------------------------------
+
+// sha256 of a file, read in chunks so a render of any size never sits whole in memory (one read
+// stops at 2 GiB), and only up to the size it had when the read began, so a file that grows or
+// never ends (/proc) is still read once. Once per version of the file: the key holds its inode,
+// size, mtime and ctime, so a regenerated take is hashed anew; a view that finds the read already
+// going closes its own file and waits for that one. Rejects for a file that cannot be read, and for
+// anything but a regular file (a link to /dev/zero, a FIFO; opened without blocking in case the
+// path turns into one after the first check).
+const hashes = new Map();
+const notRegular = () => new Error('일반 파일 아님');
+export async function hashFile(fp) {
+  if (!(await fs.promises.stat(fp)).isFile()) throw notRegular();
+  const fh = await fs.promises.open(fp, READ_FLAGS);
+  let done;
+  try {
+    const st = await fh.stat();
+    if (!st.isFile()) throw notRegular();
+    const key = `${fp}:${st.ino}:${st.size}:${st.mtimeMs}:${st.ctimeMs}`;
+    done = hashes.get(key);
+    if (done) return done;
+    done = sha256Of(fh, st.size);
+    done.catch(() => hashes.delete(key));
+    hashes.set(key, done);
+    await done.catch(() => {});
+  } finally {
+    await fh.close();
+  }
+  return done;
+}
+
+// sha256 of the first `size` bytes of an open file.
+function sha256Of(fh, size) {
+  const h = crypto.createHash('sha256');
+  if (size === 0) return Promise.resolve(h.digest('hex'));
+  return new Promise((resolve, reject) => {
+    fh.createReadStream({ start: 0, end: size - 1, autoClose: false })
+      .on('error', reject).on('data', (c) => h.update(c)).on('end', () => resolve(h.digest('hex')));
   });
-  document.getElementById('confirm').addEventListener('click', async () => {
-    const scenes = [], missing = [];
-    document.querySelectorAll('.scene').forEach((scene) => {
-      const id = scene.getAttribute('data-scene-id');
-      const sel = scene.querySelector('.card.selected');
-      const regen = (scene.querySelector('[data-regen]') || {}).value?.trim() || '';
-      if (!sel) { missing.push(id); return; }
-      const s = { id, chosen: sel.getAttribute('data-file') };
-      if (regen) s.regenerate = regen;
-      scenes.push(s);
-    });
-    if (missing.length) { alert('스틸을 선택하지 않은 씬: ' + missing.join(', ')); return; }
-    const btn = document.getElementById('confirm');
-    btn.disabled = true;
-    try {
-      const r = await fetch('/select', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ scenes }) });
-      if (!r.ok) throw new Error('HTTP ' + r.status);
-      document.getElementById('done').hidden = false;
-    } catch (err) {
-      btn.disabled = false;
-      alert('저장 실패: ' + (err && err.message ? err.message : err));
+}
+
+// What a card shows for a take's file: its sha256, or why there is none.
+async function hashText(dir, file) {
+  if (refusal(dir, file)) return '보이지 않음';
+  const fp = path.join(dir, file);
+  if (!fs.existsSync(fp)) return '파일 없음';
+  try { return await hashFile(fp); } catch (e) { return `해시 실패(${e.code || e.message})`; }
+}
+
+// The hash text of every listed take by file, four files at a time per call (a long list must not
+// run out of file handles), before the page is drawn.
+async function takeHashes(input, dir) {
+  const files = [...new Set(input.scenes.flatMap((s) => s.takes.map((t) => t.file)))];
+  const out = new Map();
+  let next = 0;
+  const worker = async () => {
+    while (next < files.length) {
+      const f = files[next++];
+      out.set(f, await hashText(dir, f));
     }
-  });
-</script>
-</body>
-</html>
+  };
+  await Promise.all(Array.from({ length: Math.min(4, files.length) }, worker));
+  return out;
+}
+
+function media(t, dir) {
+  const no = refusal(dir, t.file);
+  if (no) return `<p class="refused">${no}</p>`;
+  const src = escAttr(fileUrl(t.file));
+  return VIDEO.test(t.file)
+    ? `<video src="${src}" muted loop autoplay playsinline preload="metadata"></video>`
+    : `<img src="${src}" alt="" loading="lazy">`;
+}
+
+function frameRow(label, file, dir) {
+  if (!file) return '';
+  const thumb = refusal(dir, file) ? '' : `<img class="thumb" src="${escAttr(fileUrl(file))}" alt="">`;
+  return `<dt>${label}</dt><dd>${thumb}<code>${escHtml(file)}</code></dd>`;
+}
+
+function fileFacts(t, hash) {
+  return `<dt>파일</dt><dd><code>${escHtml(t.file ?? '')}</code></dd><dt>sha256</dt><dd><code class="hash">${escHtml(hash)}</code></dd>`;
+}
+
+function facts(t, ctx) {
+  const row = (label, v) => (v === undefined || v === null || v === '' ? '' : `<dt>${label}</dt><dd>${escHtml(v)}</dd>`);
+  return '<dl>'
+    + (t.prompt ? `<dt>${ctx.promptLabel}</dt><dd class="prompt">${escHtml(t.prompt)}</dd>` : '')
+    + row('제외 프롬프트', t.negativePrompt) + row('모델', t.model) + row('크기', t.size)
+    + row('길이', t.seconds != null ? `${t.seconds}초` : null)
+    + frameRow('첫 프레임', t.firstFrame, ctx.dir) + frameRow('끝 프레임', t.lastFrame, ctx.dir)
+    + row('생성 시각', t.createdAt) + row('비용', t.costUsd != null ? money(t.costUsd) : null)
+    + fileFacts(t, ctx.hashes.get(t.file)) + '</dl>';
+}
+
+function card(t, ctx, e) {
+  const cls = ['card', e.chosen === t.file ? 'selected' : '', e.rejected.includes(t.file) ? 'rejected' : ''].filter(Boolean).join(' ');
+  return `<article class="${cls}" data-file="${escAttr(t.file ?? '')}">
+      <div class="media">${media(t, ctx.dir)}</div>
+      <div class="meta"><strong>테이크 ${escHtml(t.take)}</strong>${facts(t, ctx)}
+        <div class="actions"><button type="button" data-act="choose">이 테이크로 승인</button>
+        <button type="button" data-act="reject">탈락</button></div></div>
+    </article>`;
+}
+
+const CHIPS = { approve: '승인', regenerate: '재생성 요청', pending: '대기' };
+
+function sceneBlock(s, i, ctx) {
+  const found = ctx.entries.get(s.id) || { verdict: 'pending', rejected: [] };
+  const e = { ...found, verdict: CHIPS[found.verdict] ? found.verdict : 'pending' };
+  const cards = s.takes.map((t) => card(t, ctx, e)).join('\n      ') || '<p class="empty">테이크가 없습니다.</p>';
+  return `<section class="scene" data-scene-id="${escAttr(s.id)}">
+    <div class="scene-head"><h2>${i + 1}. ${escHtml(s.label)}</h2><span class="chip ${e.verdict}" data-chip>${CHIPS[e.verdict] || '대기'}</span></div>
+    <div class="takes">
+      ${cards}
+    </div>
+    <label class="note"><span>재생성 메모 (비우면 고른 테이크로 승인)</span>
+      <textarea data-note rows="2">${escHtml(e.note || '')}</textarea></label>
+  </section>`;
+}
+
+function summary(input, entries) {
+  const approved = input.scenes.filter((s) => entries.get(s.id)?.verdict === 'approve').length;
+  const spent = input.spentUsd ?? input.scenes.flatMap((s) => s.takes).reduce((a, t) => a + (Number(t.costUsd) || 0), 0);
+  const budget = input.budgetUsd != null ? ` / 승인 예산 ${money(input.budgetUsd)}` : '';
+  const stage = input.stageLabel || STAGE_LABELS[input.stage] || input.stage;
+  return `<strong>${escHtml(stage)}</strong> <span>승인 ${approved} / ${input.scenes.length}</span> <span>누적 비용 ${money(spent)}${budget}</span>`;
+}
+
+/** The review page for `input`. Resolves once every listed take is hashed. */
+export async function renderPage(input, decisions, { dir }) {
+  const stage = decisions[input.stage] || { scenes: [] };
+  const entries = new Map(stage.scenes.map((e) => [e.id, { ...e, rejected: e.rejected || [] }]));
+  const promptLabel = input.promptLabel || (INSTRUCTION_STAGES.has(input.stage) ? '구성 지시문' : '프롬프트');
+  const ctx = { dir, promptLabel, entries, hashes: await takeHashes(input, dir) };
+  const body = input.scenes.map((s, i) => sceneBlock(s, i, ctx)).join('\n') || '<p class="empty">curate-input.json 에 장면이 없습니다.</p>';
+  return `<!doctype html>
+<html lang="ko"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escHtml(STAGE_LABELS[input.stage] || input.stage)}${input.title ? ' - ' + escHtml(input.title) : ''}</title>
+<style>${PAGE_CSS}</style></head>
+<body><header class="bar"><div class="bar-in"><div class="sum">${summary(input, entries)}</div>
+<button id="save" class="btn">판정 저장</button></div></header>
+<main id="app" data-based-on="${escAttr(stage.updatedAt || '')}">${body}</main>
+<div id="done" class="done" hidden><div class="done-card">판정을 저장했습니다. 에이전트로 돌아가세요.</div></div>
+<script>${PAGE_JS}</script></body></html>
 `;
 }
 
-// ---- request handling ----
-function servePage(res) {
-  let manifest;
-  try { manifest = JSON.parse(fs.readFileSync(INPUT, 'utf8')); }
-  catch (e) {
-    res.writeHead(500, { 'Content-Type': 'text/plain;charset=utf-8', 'Cache-Control': 'no-store' });
-    res.end(`curate-input.json 을 읽지 못했습니다 (${INPUT}): ${e.message}`);
-    return;
+const PAGE_CSS = `
+:root{--bg:#f5f3ef;--panel:#fff;--ink:#23202a;--muted:#6c6675;--line:#e2ddd4;--accent:#7c5cbf;--ok:#2f7d4f;--warn:#b26a00;--bad:#b3261e}
+@media (prefers-color-scheme:dark){:root{--bg:#17151b;--panel:#201d26;--ink:#ece8f1;--muted:#a49db1;--line:#322d3c;--accent:#a488e6;--ok:#7fd3a0;--warn:#e6b063;--bad:#f2b8b5}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--ink);font:14px/1.5 system-ui,-apple-system,"Segoe UI","Noto Sans KR",sans-serif}
+.bar{position:sticky;top:0;z-index:5;background:var(--panel);border-bottom:1px solid var(--line)}
+.bar-in{max-width:1400px;margin:0 auto;padding:10px 20px;display:flex;gap:16px;align-items:center;justify-content:space-between}
+.sum{display:flex;gap:18px;flex-wrap:wrap;align-items:baseline}.sum span{color:var(--muted)}
+.btn{border:0;border-radius:8px;background:var(--accent);color:#fff;font-weight:600;padding:9px 18px;cursor:pointer}.btn:disabled{opacity:.5}
+main{max-width:1400px;margin:0 auto;padding:18px 20px}
+.scene{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:14px;margin-bottom:16px}
+.scene-head{display:flex;gap:12px;align-items:center}.scene-head h2{font-size:16px;margin:0}
+.chip{font-size:12px;font-weight:600;padding:2px 10px;border-radius:999px;border:1px solid currentColor}
+.chip.approve{color:var(--ok)}.chip.regenerate{color:var(--warn)}.chip.pending{color:var(--muted)}
+.takes{display:flex;gap:12px;overflow-x:auto;padding:12px 0}
+.card{flex:0 0 340px;border:2px solid var(--line);border-radius:10px;overflow:hidden;display:flex;flex-direction:column}
+.card.selected{border-color:var(--ok)}.card.rejected{border-color:var(--bad);opacity:.6}
+.media img,.media video{display:block;width:100%;height:auto;background:#000}
+.meta{padding:8px 10px}.meta dl{display:grid;grid-template-columns:max-content 1fr;gap:2px 8px;margin:6px 0}
+.meta dt{color:var(--muted)}.meta dd{margin:0;overflow-wrap:anywhere}.prompt{white-space:pre-wrap;max-height:9em;overflow:auto}
+.thumb{width:72px;height:auto;vertical-align:middle;margin-right:6px}.hash{font-size:11px}
+.actions{display:flex;gap:8px}.actions button{border:1px solid var(--line);background:var(--bg);color:var(--ink);border-radius:6px;padding:4px 10px;cursor:pointer}
+.note span{display:block;color:var(--muted);font-size:13px}.note textarea{width:100%;border:1px solid var(--line);border-radius:8px;padding:6px 8px;font:inherit;background:var(--bg);color:var(--ink)}
+.refused,.empty{color:var(--bad)}[hidden]{display:none!important}
+.done{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;background:color-mix(in srgb,var(--bg) 82%,transparent);z-index:10}
+.done-card{background:var(--panel);border:1px solid var(--line);border-radius:12px;padding:24px 32px;font-size:17px;font-weight:600}`;
+
+const PAGE_JS = `
+const chip = (scene) => {
+  const c = scene.querySelector('[data-chip]');
+  const note = scene.querySelector('[data-note]').value.trim();
+  const v = note ? 'regenerate' : scene.querySelector('.card.selected') ? 'approve' : 'pending';
+  c.className = 'chip ' + v; c.textContent = { approve: '승인', regenerate: '재생성 요청', pending: '대기' }[v];
+};
+document.getElementById('app').addEventListener('click', (e) => {
+  const btn = e.target.closest('[data-act]'); if (!btn) return;
+  const card = btn.closest('.card'); const scene = card.closest('.scene');
+  if (btn.dataset.act === 'choose') {
+    scene.querySelectorAll('.card').forEach((c) => c.classList.remove('selected'));
+    card.classList.add('selected'); card.classList.remove('rejected');
+  } else { card.classList.toggle('rejected'); if (card.classList.contains('rejected')) card.classList.remove('selected'); }
+  chip(scene);
+});
+document.getElementById('app').addEventListener('input', (e) => { const s = e.target.closest('.scene'); if (s) chip(s); });
+document.getElementById('save').addEventListener('click', async () => {
+  const basedOn = document.getElementById('app').dataset.basedOn;
+  const scenes = [...document.querySelectorAll('.scene')].map((s) => ({ id: s.dataset.sceneId,
+    chosen: s.querySelector('.card.selected')?.dataset.file || '', note: s.querySelector('[data-note]').value,
+    rejected: [...s.querySelectorAll('.card.rejected')].map((c) => c.dataset.file) }));
+  const btn = document.getElementById('save'); btn.disabled = true;
+  try {
+    const r = await fetch('/decide', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ basedOn, scenes }) });
+    if (!r.ok) throw new Error(await r.text());
+    document.getElementById('done').hidden = false;
+  } catch (err) { btn.disabled = false; alert('저장하지 못했습니다: ' + (err && err.message ? err.message : err)); }
+});`;
+
+// ---- the server ---------------------------------------------------------------
+
+function readBody(req, limit = 1_000_000) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', (c) => { body += c; if (body.length > limit) { req.destroy(); reject(new Error('too large')); } });
+    req.on('end', () => resolve(body));
+    req.on('error', reject);
+  });
+}
+
+// Verdicts come only from the page itself: JSON (a cross-site form or text/plain post is refused,
+// and JSON across sites needs a preflight this server never grants) from its own origin.
+// Text for the server's terminal: every control character escaped, C0 by JSON and the rest (DEL, C1,
+// bidirectional marks) by hand, so a request body cannot drive the terminal.
+const logSafe = (text) => JSON.stringify(String(text))
+  .replace(/[\u007f-\u009f\u061c\u200e\u200f\u202a-\u202e\u2066-\u2069]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+
+// What a failure tells the page: a curate: message as it is; anything else only by its code (a system
+// message names absolute paths), with the whole of it on the server's stderr, escaped (a request
+// body's control characters must not reach the terminal).
+function failureText(e, what) {
+  if (String(e.message).startsWith('curate:')) return e.message;
+  console.error(`curate: ${what}: ${logSafe(e.message || e)}`);
+  return `${what}(${e.code || e.name || 'error'})`;
+}
+
+async function decide(dir, req, res) {
+  if (!/^application\/json\b/i.test(req.headers['content-type'] || '')) return send(res, 415, 'JSON only');
+  const origin = req.headers.origin;
+  if (origin && origin !== `http://${req.headers.host}`) return send(res, 403, 'verdicts from another origin are refused');
+  try {
+    const stage = applyPageDecisions(dir, JSON.parse(await readBody(req)));
+    res.writeHead(200, { 'Content-Type': 'application/json;charset=utf-8', 'Cache-Control': 'no-store' });
+    res.end(JSON.stringify({ ok: true, written: DECISIONS, scenes: stage.scenes.length }));
+  } catch (e) {
+    send(res, e.status || 400, failureText(e, '판정을 저장하지 못했습니다'));
+  }
+}
+
+// The files the page may serve: the images and videos the input lists as takes and frames, inside
+// the project by their paths. Nothing else in the folder (keys in .env files, the review records) is
+// reachable; where a requested file's links lead is checked for that file alone (serveListed).
+function listedFiles(dir) {
+  let input;
+  try { input = readInput(dir); } catch { return new Set(); }
+  const files = new Set();
+  for (const t of input.scenes.flatMap((s) => s.takes)) {
+    for (const f of [t.file, t.firstFrame, t.lastFrame]) if (inside(dir, f) && MEDIA.test(f)) files.add(path.normalize(path.join(dir, f)));
+  }
+  return files;
+}
+
+async function page(dir, res) {
+  let html;
+  try { html = await renderPage(readInput(dir), readDecisions(dir), { dir }); } catch (e) {
+    return send(res, 500, failureText(e, `${INPUT} 을 읽지 못했습니다`));
   }
-  const html = renderPage(manifest);
   res.writeHead(200, { 'Content-Type': 'text/html;charset=utf-8', 'Cache-Control': 'no-store' });
   res.end(html);
 }
 
-function serveFile(urlPath, res) {
-  // Resolve inside DIR and reject any path that escapes it (traversal guard) — matches serve.mjs.
-  const fp = path.normalize(path.join(DIR, urlPath));
-  if (fp !== DIR && !fp.startsWith(DIR + path.sep)) { res.writeHead(403); res.end('403'); return; }
-  if (!fs.existsSync(fp) || fs.statSync(fp).isDirectory()) { res.writeHead(404); res.end('404'); return; }
-  const type = MIME[path.extname(fp).toLowerCase()] || 'application/octet-stream';
-  res.writeHead(200, {
-    'Content-Type': type,
-    'Content-Length': fs.statSync(fp).size,
-    'Cache-Control': 'no-store',
-  });
-  fs.createReadStream(fp).pipe(res);
+function serveListed(dir, req, res, urlPath) {
+  const fp = resolveInside(dir, urlPath);
+  if (!fp) return send(res, 403, '403');
+  if (!listedFiles(dir).has(fp) || linkRefusal(dir, fp)) return send(res, 404, '404');
+  sendFile(req, res, fp);
 }
 
-function handleSelect(req, res) {
-  let body = '';
-  let tooBig = false;
-  req.on('data', (c) => {
-    body += c;
-    if (body.length > 1_000_000) { tooBig = true; req.destroy(); }
-  });
-  req.on('end', () => {
-    if (tooBig) { res.writeHead(413); res.end('413'); return; }
-    let payload;
-    try { payload = JSON.parse(body); }
-    catch { res.writeHead(400, { 'Content-Type': 'application/json;charset=utf-8' }); res.end('{"ok":false,"error":"invalid json"}'); return; }
-    const scenes = (Array.isArray(payload.scenes) ? payload.scenes : []).map((s) => {
-      const out = { id: String(s.id), chosen: String(s.chosen) };
-      const note = s.regenerate == null ? '' : String(s.regenerate).trim();
-      if (note) out.regenerate = note;
-      return out;
-    });
-    try { fs.writeFileSync(OUTPUT, JSON.stringify({ scenes }, null, 2) + '\n'); }
-    catch (e) {
-      res.writeHead(500, { 'Content-Type': 'application/json;charset=utf-8' });
-      res.end(JSON.stringify({ ok: false, error: String(e.message || e) }));
-      return;
-    }
-    res.writeHead(200, { 'Content-Type': 'application/json;charset=utf-8', 'Cache-Control': 'no-store' });
-    res.end(JSON.stringify({ ok: true, written: 'selection.json', scenes: scenes.length }));
-    console.log(`selection.json written -> ${OUTPUT} (${scenes.length} scene(s))`);
-  });
+function route(dir, req, res, urlPath) {
+  if (req.method === 'POST' && urlPath === '/decide') return void decide(dir, req, res);
+  if (req.method !== 'GET' && req.method !== 'HEAD') return send(res, 405, '405');
+  if (answersPid(urlPath, res)) return;
+  if (urlPath === '/' || urlPath === '/index.html') return void page(dir, res);
+  serveListed(dir, req, res, urlPath);
 }
 
-const server = http.createServer((req, res) => {
-  const method = req.method || 'GET';
-  const urlPath = decodeURIComponent((req.url || '/').split('?')[0]);
-  if (method === 'POST' && urlPath === '/select') { handleSelect(req, res); return; }
-  if (method !== 'GET' && method !== 'HEAD') { res.writeHead(405); res.end('405'); return; }
-  if (urlPath === '/' || urlPath === '/index.html') { servePage(res); return; }
-  serveFile(urlPath, res);
-});
+function handler(dir, host) {
+  return (req, res) => {
+    if (!hostAllowed(req.headers.host, [host])) return send(res, 403, 'host not allowed');
+    const urlPath = decodePath(req.url);
+    if (urlPath === null) return send(res, 400, '400');
+    route(dir, req, res, urlPath);
+  };
+}
 
-// ---- pick a free port (preferred first, then a candidate list) ----
-// Distinct from serve.mjs's list so a preview server and this curation server can coexist during dev;
-// EADDRINUSE still falls through if any are taken.
-const candidates = [8941, 8942, 8943, 8850, 8860, 8870, 8223, 8421];
-const ports = portArg ? [portArg, ...candidates.filter((p) => p !== portArg)] : candidates;
-// Default to loopback (matches the printed localhost URL). Set PREVIEW_HOST=0.0.0.0 for LAN / on-device mobile preview.
-const HOST = process.env.PREVIEW_HOST || '127.0.0.1';
-
-(function tryPort(i) {
-  if (i >= ports.length) { console.error('curate: no free port available'); process.exit(1); }
-  server.once('error', (e) => {
-    if (e.code === 'EADDRINUSE') tryPort(i + 1);
-    else { console.error(e); process.exit(1); }
-  });
-  server.listen(ports[i], HOST, () => {
-    try { fs.writeFileSync(path.join(DIR, 'curate-port.txt'), String(ports[i])); } catch { /* best effort */ }
-    console.log(`CURATE http://${HOST === '127.0.0.1' ? 'localhost' : HOST}:${ports[i]}/`);
-    console.log(`curating ${DIR}  (in: curate-input.json  out: selection.json)`);
-  });
-})(0);
+/**
+ * Serves the review page for `dir` until close(). Resolves to { server, port, host, url, stateFile,
+ * close, warmed }; `warmed` resolves to the hash texts of the listed takes by file.
+ */
+export async function startCurate(dir, { port, host = process.env.PREVIEW_HOST || LOOPBACK } = {}) {
+  const root = path.resolve(dir);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`curate: not a directory: ${root}`);
+  const server = http.createServer(handler(root, host));
+  const bound = await listen(server, { host, port });
+  const url = urlFor(host, bound);
+  const stateFile = path.join(root, STATE);
+  writeState(stateFile, { pid: process.pid, port: bound, requestedPort: port || null, host, url, dir: root, startedAt: new Date().toISOString() });
+  const warmed = warmHashes(root);
+  const close = () => new Promise((resolve) => { forgetSelf(stateFile); server.close(() => resolve()); });
+  return { server, port: bound, host, url, stateFile, close, warmed };
+}
+
+// Starts hashing the listed takes, so the first view of the page does not wait for a large render.
+// An input that cannot be read hashes nothing here; the page reports it.
+function warmHashes(dir) {
+  try { return takeHashes(readInput(dir), dir).catch(() => new Map()); } catch { return Promise.resolve(new Map()); }
+}
+
+// ---- CLI ------------------------------------------------------------------------
 
-process.on('SIGINT', () => { server.close(); process.exit(0); });
-process.on('SIGTERM', () => { server.close(); process.exit(0); });
+function parseArgs(argv) {
+  const o = { dir: null, port: null };
+  const flags = new Set(['--stop', '--record', '--archive']);
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (flags.has(a)) o.mode = a.slice(2);
+    else if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      o[eq > 0 ? a.slice(2, eq) : a.slice(2)] = eq > 0 ? a.slice(eq + 1) : argv[++i];
+    } else o.dir = a;
+  }
+  return o;
+}
+
+// A review server already running for this folder answers a start with the same host and port;
+// other settings exit 1, so a page meant for one address is not reviewed on another.
+async function serveMain(dir, o) {
+  const recorded = path.join(dir, STATE);
+  if (await isRunning(recorded)) {
+    const st = readState(recorded);
+    if ((st.host || LOOPBACK) === (process.env.PREVIEW_HOST || LOOPBACK) && portMatches(st, Number(o.port))) {
+      return console.log(`CURATE ${st.url} (already running, pid ${st.pid})`);
+    }
+    console.error(`curate: a review server for this folder is running with different settings (host: ${st.host}, port: ${st.port}); `
+      + 'stop it with --stop and start again');
+    return process.exit(1);
+  }
+  const s = await startCurate(dir, { port: Number(o.port) || undefined });
+  const warn = hostWarning(s.host);
+  if (warn) console.warn(warn);
+  console.log(`CURATE ${s.url}`);
+  console.log(`reviewing ${dir}  (in: ${INPUT}  out: ${DECISIONS}  state: ${s.stateFile})`);
+  const quit = () => { forgetSelf(s.stateFile); s.server.close(); process.exit(0); };
+  process.on('SIGINT', quit);
+  process.on('SIGTERM', quit);
+}
+
+async function main() {
+  const o = parseArgs(process.argv.slice(2));
+  const dir = path.resolve(o.dir || process.cwd());
+  if (o.mode === 'stop') {
+    const r = await stopServer(path.join(dir, STATE));
+    console.log(`STOP ${r.reason}`);
+    return process.exit(['stopped', 'not-running', 'no-state'].includes(r.reason) ? 0 : 1);
+  }
+  if (o.mode === 'record') return console.log(JSON.stringify(recordDecision(dir, o)));
+  if (o.mode === 'archive') return console.log(JSON.stringify(archiveRejected(dir)));
+  return serveMain(dir, o);
+}
+
+const invokedDirectly = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invokedDirectly) {
+  main().catch((e) => { console.error(String(e?.message || e)); process.exit(1); });
+}