@lingjingai/scriptctl 0.76.0 → 0.78.0

package/scripts/review-view.mjs

@@ -0,0 +1,662 @@
+// `scriptctl review-view` serves this: the step-by-step path of review runs, from what
+// `scriptctl review` already left in a workspace (.review traces, failure snapshots, NDJSON logs).
+// Read-only: it never calls a model and never writes to the workspace.
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as http from "node:http";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PAGE = path.join(path.dirname(fileURLToPath(import.meta.url)), "review-view.html");
+const SKIP_DIRS = new Set(["node_modules", ".git", "worktrees", "raw", "ep", "cache", "src", "evidence", "archive"]);
+const VIDEO_TYPES = { ".mp4": "video/mp4", ".m4v": "video/mp4", ".mov": "video/quicktime", ".mkv": "video/x-matroska" };
+const MAX_CACHED_RUNS = 3;
+const SLOW_STEP_MS = 60_000;
+const EVIDENCE_CHARS = 3000;
+
+// ---- files ---------------------------------------------------------------------
+
+const list = (dir) => { try { return fs.readdirSync(dir); } catch { return []; } };
+const stat = (file) => fs.statSync(file, { throwIfNoEntry: false });
+const mtime = (file) => stat(file)?.mtimeMs ?? null;
+const isDir = (file) => stat(file)?.isDirectory() ?? false;
+
+function readJson(file) {
+  try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/** A run still in progress can leave a partial last line. */
+function readJsonl(file) {
+  const rows = [];
+  let text;
+  try { text = fs.readFileSync(file, "utf8"); } catch { return rows; }
+  for (const line of text.split("\n")) {
+    if (!line.startsWith("{")) continue;
+    try { rows.push(JSON.parse(line)); } catch { /* logs interleave diagnostics with NDJSON */ }
+  }
+  return rows;
+}
+
+// ---- workspaces ------------------------------------------------------------------
+
+function reviewName(dir) {
+  const names = list(path.join(dir, ".review")).filter((name) =>
+    fs.existsSync(path.join(dir, ".review", name, "trace")) || fs.existsSync(path.join(dir, ".review", name, "global.json")));
+  return names.includes("script") ? "script" : names[0] ?? null;
+}
+
+function findWorkspaces(root, depth = 5, found = []) {
+  if (reviewName(root)) { found.push(root); return found; }
+  if (depth > 0) {
+    for (const name of list(root)) {
+      if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
+      const child = path.join(root, name);
+      if (isDir(child)) findWorkspaces(child, depth - 1, found);
+    }
+  }
+  return found;
+}
+
+const registry = new Map();
+function register(dir) {
+  const absolute = path.resolve(dir.replace(/^~(?=\/|$)/, os.homedir()));
+  const workspace = reviewName(absolute) ? absolute : reviewName(path.join(absolute, "workspace")) ? path.join(absolute, "workspace") : null;
+  if (!workspace) return null;
+  const id = createHash("sha1").update(workspace).digest("hex").slice(0, 10);
+  registry.set(id, workspace);
+  return id;
+}
+function workspaceRows() {
+  const rows = [...registry].map(([id, dir]) => {
+    const folder = path.basename(dir) === "workspace" ? path.dirname(dir) : dir;
+    return { id, name: path.basename(folder), parent: path.basename(path.dirname(folder)), path: dir,
+      updated: mtime(path.join(dir, ".review", reviewName(dir), "global.json")) ?? mtime(path.join(dir, ".review")) };
+  }).sort((a, b) => (b.updated ?? 0) - (a.updated ?? 0));
+  // Sibling experiments often share a folder name; the parent tells them apart in the picker.
+  const uses = new Map();
+  for (const row of rows) uses.set(row.name, (uses.get(row.name) ?? 0) + 1);
+  return rows.map(({ parent, ...row }) => (uses.get(row.name) > 1 ? { ...row, name: `${parent}/${row.name}` } : row));
+}
+
+// ---- sources ---------------------------------------------------------------------
+
+function scriptIndex(dir, name) {
+  const names = new Map();
+  let title = null, episodes = 0;
+  for (const file of [`${name}.initial.json`, "script.initial.json", `${name}.json`]) {
+    const raw = readJson(path.join(dir, file));
+    if (!raw) continue;
+    title = raw.title ?? title;
+    episodes = raw.episodes?.length ?? episodes;
+    for (const asset of raw.actors ?? []) names.set(asset.actor_id, { kind: "人物", name: asset.actor_name });
+    for (const asset of raw.locations ?? []) names.set(asset.location_id, { kind: "地点", name: asset.location_name });
+    for (const asset of raw.props ?? []) names.set(asset.prop_id, { kind: "道具", name: asset.prop_name });
+  }
+  return { names, title, episodes };
+}
+
+function readVideos(dir) {
+  const videos = new Map();
+  for (const episode of readJson(path.join(dir, "manifest.json"))?.episodes ?? []) {
+    if (episode.path && VIDEO_TYPES[path.extname(episode.path).toLowerCase()]) videos.set(episode.episode, episode.path);
+  }
+  if (videos.size) return videos;
+  // Runs without a manifest took the raw folder beside the workspace, in name order.
+  const raw = path.join(dir, "..", "raw");
+  list(raw).filter((name) => VIDEO_TYPES[path.extname(name).toLowerCase()]).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+    .forEach((name, index) => videos.set(index + 1, path.join(raw, name)));
+  return videos;
+}
+
+/** One trace file is one agent execution; its name carries the unit and the start time. */
+function readAgentRuns(trace) {
+  return list(trace).flatMap((name) => {
+    const match = /^ep(\d+)(?::([^-]+))?-(\d+)\.jsonl$/.exec(name);
+    if (!match) return [];
+    const steps = readJsonl(path.join(trace, name));
+    const start = Number(match[3]);
+    const last = steps.at(-1)?.at;
+    return [{ file: name, episode: Number(match[1]), asset: match[2] ?? null, start, end: last ? Date.parse(last) : start, steps }];
+  }).sort((a, b) => a.start - b.start);
+}
+
+function readCalls(trace) {
+  return readJsonl(path.join(trace, "converge-calls.jsonl")).map((row) => {
+    const [, , type, ...target] = row.call.split(":");
+    const end = Date.parse(row.at);
+    return { ...row, type, target: target.join(":"), start: end - (row.ms ?? 0), end };
+  }).sort((a, b) => a.start - b.start);
+}
+
+function readFailures(dir) {
+  const folder = path.join(dir, "failures");
+  return list(folder).flatMap((file) => {
+    const raw = readJson(path.join(folder, file));
+    if (!raw) return [];
+    return [{ file, at: Number(file.split("-")[0]) || null, episode: raw.episode_number ?? 0, asset: raw.asset ?? null,
+      provider: raw.provider, model: raw.model, error: raw.error, chain: raw.error_chain ?? [],
+      messages: Array.isArray(raw.prompt) ? raw.prompt.length : 0, response: raw.responseBody ? String(raw.responseBody).slice(0, 2000) : null }];
+  }).sort((a, b) => (a.at ?? 0) - (b.at ?? 0));
+}
+
+const keyOf = (event) => event.episode_number ? `ep${event.episode_number}`
+  : event.asset === "asset-escalation" ? "escalation" : event.asset ? `ep0:${event.asset}` : "identity";
+
+/** Each log is one `scriptctl review` process; later processes re-emit reused units with empty usage. */
+function readLogs(workspace) {
+  const parent = path.dirname(workspace);
+  const files = [
+    ...list(parent).filter((name) => /^review.*\.ndjson$/.test(name)).map((name) => path.join(parent, name)),
+    ...list(path.join(parent, "logs")).filter((name) => /review.*\.(ndjson|stdout\.log)$/.test(name)).map((name) => path.join(parent, "logs", name)),
+    ...list(workspace).filter((name) => /^review.*\.ndjson$/.test(name)).map((name) => path.join(workspace, name)),
+  ].sort((a, b) => mtime(a) - mtime(b));
+  const logs = [], results = [], seen = new Set();
+  for (const file of files) {
+    const events = readJsonl(file).filter((event) => typeof event.type === "string");
+    if (!events.length) continue;
+    const name = path.relative(parent, file);
+    const done = events.find((event) => event.type === "done");
+    logs.push({ file: name, updated: mtime(file), wall_ms: done?.wall_ms ?? null, statistics: done?.statistics ?? null, finished: Boolean(done),
+      units: events.filter((event) => event.type === "episode" || event.type === "global").length });
+    for (const event of events) {
+      if (event.type !== "episode" && event.type !== "global") continue;
+      const signature = [keyOf(event), event.wall_ms, event.steps, event.findings?.length].join("|");
+      if (seen.has(signature)) continue;
+      seen.add(signature);
+      results.push({ ...event, key: keyOf(event), log: name });
+    }
+  }
+  return { logs, results };
+}
+
+// ---- assembly --------------------------------------------------------------------
+
+function agentWindow(usage) {
+  let first = Infinity, last = -Infinity;
+  for (const row of usage ?? []) {
+    if (!row.started_at || !row.call_key?.includes(":agent:")) continue;
+    const started = Date.parse(row.started_at);
+    first = Math.min(first, started);
+    last = Math.max(last, started + (row.ms ?? 0));
+  }
+  return first === Infinity ? null : [first, last];
+}
+
+const closest = (items, distance, limit) => {
+  let best = null, bestDistance = limit;
+  for (const item of items) {
+    const value = distance(item);
+    if (value < bestDistance) { best = item; bestDistance = value; }
+  }
+  return best;
+};
+
+/** `ep0-*.jsonl` is written by both the identity agent and the escalation batches. */
+function splitEp0(runs, calls, assetRuns, results, batches) {
+  const windows = results.filter((result) => result.key === "escalation").map((result) => agentWindow(result.usage)).filter(Boolean);
+  const identityCalls = calls.filter((call) => ["handoff", "episode", "duplicates"].includes(call.type));
+  const assetStarts = [...calls.filter((call) => call.type === "asset"), ...assetRuns].map((item) => item.start);
+  const escalation = (run) => {
+    if (batches.some((batch) => Math.abs(Date.parse(batch.started_at) - run.start) < 5_000)) return true;
+    if (windows.some(([first, last]) => run.start >= first - 120_000 && run.start <= last + 5_000)) return true;
+    const followsIdentityCalls = identityCalls.some((call) => call.end <= run.start && run.start - call.end < 600_000);
+    return !followsIdentityCalls && assetStarts.some((start) => start < run.start);
+  };
+  return { identity: runs.filter((run) => !escalation(run)), escalation: runs.filter(escalation) };
+}
+
+function assignResult(pool, result, create, logTimes) {
+  const win = agentWindow(result.usage);
+  // A process cannot report work that began after its log stopped growing.
+  const finished = logTimes.get(result.log) ?? Infinity;
+  const open = pool.filter((unit) => !unit.result && (unit.runs[0]?.start ?? unit.calls[0]?.start ?? -Infinity) <= finished + 5_000);
+  let target = win ? closest(open.filter((unit) => unit.runs.length), (unit) => Math.abs(unit.runs[0].start - win[0]), 180_000) : null;
+  if (!target && !win) {
+    target = result.steps > 0 && !result.usage?.some((row) => row.call_key?.includes(":converge:"))
+      ? open.find((unit) => unit.runs.length)
+      : open.find((unit) => unit.calls.length) ?? (result.steps > 0 ? open.find((unit) => unit.runs.length) : null);
+  }
+  if (!target) {
+    target = create(result);
+    pool.push(target);
+  }
+  target.result = result;
+  if (win) {
+    // A batched unit reports once for several trace files.
+    for (const other of open) {
+      if (other === target || !other.runs.length || other.runs[0].start < win[0] - 120_000 || other.runs[0].start > win[1] + 5_000) continue;
+      target.runs.push(...other.runs);
+      target.calls.push(...other.calls);
+      other.merged = true;
+    }
+  }
+}
+
+function assemble(src) {
+  const pools = new Map();
+  const unit = (phase, key, fields = {}) => {
+    const created = { phase, key, runs: [], calls: [], result: null, ...fields };
+    if (!pools.has(key)) pools.set(key, []);
+    pools.get(key).push(created);
+    return created;
+  };
+  const episodeRuns = src.runs.filter((run) => run.episode > 0);
+  const assetRuns = src.runs.filter((run) => run.episode === 0 && run.asset);
+  const ep0 = splitEp0(src.runs.filter((run) => run.episode === 0 && !run.asset), src.calls, assetRuns, src.results, src.batches);
+
+  for (const run of episodeRuns) unit("episode", `ep${run.episode}`, { episode: run.episode, runs: [run] });
+  for (const run of ep0.escalation) unit("escalation", "escalation", { runs: [run] });
+
+  // A round of identity checks ends with the duplicate scan; its agent takes what is left.
+  let round = null;
+  const identityEvents = [...src.calls.filter((call) => call.type !== "asset").map((call) => ({ call, start: call.start })),
+    ...ep0.identity.map((run) => ({ run, start: run.start }))].sort((a, b) => a.start - b.start);
+  for (const { call, run } of identityEvents) {
+    const finished = round && (round.runs.length || round.calls.some((item) => item.type === "duplicates"));
+    if (call) {
+      if (!round || (finished && call.type !== "duplicates")) round = unit("identity", "identity");
+      round.calls.push(call);
+    } else {
+      if (!round || round.runs.length) round = unit("identity", "identity");
+      round.runs.push(run);
+    }
+  }
+
+  for (const call of src.calls.filter((item) => item.type === "asset")) {
+    unit("asset", `ep0:${call.target}`, { asset: call.target, calls: [call] });
+  }
+  for (const run of assetRuns) {
+    const key = `ep0:${run.asset}`;
+    const lead = (pools.get(key) ?? []).filter((item) => !item.runs.length && item.calls.at(-1)?.end <= run.start + 1_000
+      && run.start - item.calls.at(-1).end < 600_000).at(-1);
+    if (lead) lead.runs.push(run);
+    else unit("asset", key, { asset: run.asset, runs: [run] });
+  }
+
+  const resultOnly = (result) => ({
+    phase: result.key === "identity" ? "identity" : result.key === "escalation" ? "escalation" : result.episode_number ? "episode"
+      : result.usage?.some((row) => row.call_key?.includes(":appearance")) || isDir(path.join(src.reviewDir, "trace", "appearance", result.asset ?? "")) ? "deep" : "asset",
+    key: result.key, episode: result.episode_number || undefined, asset: result.asset, runs: [], calls: [], result: null,
+  });
+  const poolOf = (key) => { if (!pools.has(key)) pools.set(key, []); return pools.get(key); };
+  const logTimes = new Map(src.logs.map((log) => [log.file, log.updated]));
+  for (const result of src.results) assignResult(poolOf(result.key), result, resultOnly, logTimes);
+  for (const saved of src.globals) {
+    const key = keyOf(saved);
+    const pool = poolOf(key);
+    const same = pool.find((item) => item.result && item.result.wall_ms === saved.wall_ms && item.result.steps === saved.steps);
+    if (same) { same.result.review_basis ??= saved.review_basis; continue; }
+    const target = pool.filter((item) => !item.result && !item.merged).at(-1);
+    const result = { ...saved, key, log: "global.json" };
+    if (target) target.result = result;
+    else if (!pool.length) { const created = resultOnly(result); created.result = result; pool.push(created); }
+  }
+
+  const units = [...pools.values()].flat().filter((item) => !item.merged);
+  for (const item of units) place(item, src.reviewDir, logTimes);
+  units.sort((a, b) => (a.start ?? Infinity) - (b.start ?? Infinity));
+  const counts = new Map(), passes = new Map(), previous = new Map();
+  for (const item of units) {
+    const nth = (counts.get(item.key) ?? 0) + 1;
+    counts.set(item.key, nth);
+    item.nth = nth;
+    item.id = `${item.key}#${nth}`;
+    const ran = item.runs.length > 0 || item.calls.length > 0 || (item.result?.usage?.length ?? 0) > 0;
+    if (ran) passes.set(item.key, (passes.get(item.key) ?? 0) + 1);
+    item.pass = ran ? passes.get(item.key) : 0;
+    const before = previous.get(item.key);
+    // Running again after a failure is a retry; running again after success is a second review.
+    if (ran && before) item.rerun = before.result?.state !== "completed" ? "retry" : before.result?.log === item.result?.log ? "same-process" : "other-process";
+    if (ran) previous.set(item.key, item);
+    item.label ??= labelOf(item, item.pass, src.names);
+  }
+  for (const failure of src.failures) {
+    const key = failure.episode ? `ep${failure.episode}` : failure.asset ? `ep0:${failure.asset}` : null;
+    const candidates = units.filter((item) => key ? item.key === key : ["identity", "escalation"].includes(item.key));
+    const owner = closest(candidates.filter((item) => item.start != null), (item) =>
+      failure.at >= item.start - 30_000 && failure.at <= item.end + 30_000 ? 0 : Math.min(Math.abs(failure.at - item.start), Math.abs(failure.at - item.end)), 3_600_000);
+    failure.unit = owner?.id ?? null;
+    (owner?.failures ?? (owner ? (owner.failures = []) : [])).push(failure);
+  }
+  return units;
+}
+
+function place(item, reviewDir, logTimes) {
+  const times = [...item.runs, ...item.calls];
+  if (times.length) {
+    item.start = Math.min(...times.map((time) => time.start));
+    item.end = Math.max(...times.map((time) => time.end));
+  } else {
+    const win = agentWindow(item.result?.usage);
+    if (win) { item.start = win[0]; item.end = win[1]; }
+    else if (item.phase === "deep") {
+      const dir = path.join(reviewDir, "trace", "appearance", item.asset ?? "");
+      const stamps = list(dir).map((name) => mtime(path.join(dir, name))).filter(Boolean);
+      if (stamps.length) { item.end = Math.max(...stamps); item.start = item.end - (item.result?.wall_ms ?? 0); }
+    }
+    // Only the log's finish time is known; the page marks this position as an estimate.
+    if (item.start == null && logTimes.has(item.result?.log)) {
+      item.end = logTimes.get(item.result.log);
+      item.start = item.end - (item.result?.wall_ms ?? 0);
+      item.approximate = true;
+    }
+  }
+  item.start ??= null;
+  item.end ??= item.start;
+}
+
+function labelOf(item, pass, names) {
+  if (item.phase === "episode") return pass ? `第 ${item.episode} 集 · 第 ${pass} 次` : `第 ${item.episode} 集 · ${item.result?.message ?? "未执行"}`;
+  if (item.phase === "identity") return `身份核对 · 第 ${pass || 1} 轮`;
+  if (item.phase === "escalation") return `资产疑点复核 · 第 ${pass || 1} 次`;
+  const asset = names.get(item.asset);
+  return `${asset?.name ?? item.asset}${pass > 1 ? ` · 第 ${pass} 次` : ""}`;
+}
+
+function totals(item) {
+  const out = { model_calls: 0, input: 0, cached: 0, output: 0, reasoning: 0 };
+  const rows = item.result?.usage ?? [];
+  if (rows.length) {
+    out.model_calls = rows.length;
+    for (const row of rows) {
+      out.input += row.input_tokens ?? 0; out.cached += row.cached_input_tokens ?? 0;
+      out.output += row.output_tokens ?? 0; out.reasoning += row.reasoning_tokens ?? 0;
+    }
+    return out;
+  }
+  out.model_calls = item.calls.reduce((sum, call) => sum + (call.attempts ?? 1), 0);
+  for (const run of item.runs) for (const step of run.steps) {
+    out.model_calls += 1;
+    out.input += step.usage?.inputTokens ?? 0; out.cached += step.usage?.cachedInputTokens ?? 0;
+    out.output += step.usage?.outputTokens ?? 0; out.reasoning += step.usage?.reasoningTokens ?? 0;
+  }
+  return out;
+}
+
+function outcomeCounts(findings = []) {
+  const counts = { fixed: 0, unresolved: 0, unchanged: 0 };
+  for (const finding of findings) if (finding.outcome in counts) counts[finding.outcome] += 1;
+  return counts;
+}
+
+function verdictOf(call) {
+  const value = call.value;
+  if (!value) return call.error ? "error" : null;
+  return value.verdict ?? value.decision ?? (Array.isArray(value.issues) ? `${value.issues.length} 个问题` : null)
+    ?? (value.pairs || value.not_objects ? `${(value.pairs?.length ?? 0) + (value.not_objects?.length ?? 0)} 个候选` : null);
+}
+
+const assetKind = (item) => ({ act: "人物", loc: "地点", prp: "道具" })[item.asset?.slice(0, 3)] ?? null;
+
+function summarize(item) {
+  const steps = item.runs.reduce((sum, run) => sum + run.steps.length, 0) || (item.result?.steps ?? 0);
+  const media = item.result?.media_calls ?? 0;
+  const state = item.state ?? item.result?.state ?? (item.runs.length || item.calls.length ? "unreported" : "unknown");
+  return {
+    id: item.id, key: item.key, phase: item.phase, label: item.label, episode: item.episode ?? null, asset: item.asset ?? null, pass: item.pass ?? 0,
+    kind: item.asset ? assetKind(item) : null, rerun: item.rerun ?? null, approximate: Boolean(item.approximate), traced: item.runs.length > 0,
+    start: item.start, end: item.end, wall_ms: item.result?.wall_ms ?? (item.start != null ? item.end - item.start : null),
+    state, failure_kind: item.result?.failure_kind ?? null, log: item.result?.log ?? null,
+    reused: Boolean(item.result && !item.result.usage?.length && !item.runs.length && !item.calls.length && item.result.findings?.length),
+    steps, media_calls: media, ...totals(item), outcomes: outcomeCounts(item.result?.findings),
+    failures: item.failures?.length ?? 0,
+    verdict: item.calls.length === 1 ? verdictOf(item.calls[0]) : null,
+    segments: [
+      ...item.calls.map((call) => ({ kind: "call", start: call.start, end: call.end })),
+      ...item.runs.map((run) => ({ kind: "agent", start: run.start, end: run.end })),
+    ],
+  };
+}
+
+function loadRun(dir) {
+  const name = reviewName(dir);
+  const reviewDir = path.join(dir, ".review", name);
+  const trace = path.join(reviewDir, "trace");
+  const { logs, results } = readLogs(dir);
+  const { names, title, episodes } = scriptIndex(dir, name);
+  const src = {
+    reviewDir, names, logs, results, runs: readAgentRuns(trace), calls: readCalls(trace),
+    globals: readJson(path.join(reviewDir, "global.json"))?.units ?? [],
+    failures: readFailures(reviewDir), batches: readJsonl(path.join(trace, "asset-escalation-batches.jsonl")),
+  };
+  const units = assemble(src);
+  return { dir, name, reviewDir, title, episodes, logs, units, failures: src.failures, videos: readVideos(dir),
+    byId: new Map(units.map((item) => [item.id, item])) };
+}
+
+const cache = new Map();
+function signature(dir) {
+  const name = reviewName(dir);
+  const trace = path.join(dir, ".review", name, "trace");
+  const stamps = [mtime(path.join(dir, ".review", name, "global.json")), ...list(trace).map((file) => {
+    const info = stat(path.join(trace, file));
+    return `${file}:${info?.size}`;
+  })];
+  return stamps.join("|");
+}
+function runFor(id) {
+  const dir = registry.get(id);
+  if (!dir) return null;
+  const current = signature(dir);
+  const cached = cache.get(id);
+  if (cached?.signature === current) return cached.run;
+  const run = loadRun(dir);
+  cache.delete(id);
+  cache.set(id, { signature: current, run });
+  if (cache.size > MAX_CACHED_RUNS) cache.delete(cache.keys().next().value);
+  return run;
+}
+
+// ---- detail payloads --------------------------------------------------------------
+
+const quiet = new Set(["validate", "issues"]);
+
+/** Results may come back in another order when a step ran tools in parallel. */
+function pairCalls(step) {
+  const left = [...(step.results ?? [])];
+  return (step.calls ?? []).map((call) => {
+    const at = left.findIndex((result) => result.tool === call.tool);
+    const result = at >= 0 ? left.splice(at, 1)[0] : null;
+    return { tool: call.tool, args: call.args, result: result?.result, error: Boolean(result?.error) };
+  });
+}
+
+function stepPayload(run, step, seen, modelRow) {
+  const calls = pairCalls(step).map((call) => {
+    const signed = JSON.stringify([call.tool, call.args]);
+    const dup = !quiet.has(call.tool) && seen.has(signed);
+    seen.add(signed);
+    const text = typeof call.result === "string" ? call.result : JSON.stringify(call.result ?? "");
+    const failed = call.error || (call.result && typeof call.result === "object" && "error" in call.result && call.result.error) || /^(error|错误|失败)/i.test(text);
+    return { ...call, dup, failed: Boolean(failed), budget: /预算已?用完|额度已?用尽/.test(text) };
+  });
+  const end = Date.parse(step.at);
+  return {
+    step: step.step, start: end - (step.step_ms ?? 0), end, step_ms: step.step_ms, finish: step.finish,
+    model_ms: modelRow?.ms ?? null, route: modelRow ? `${modelRow.provider}/${modelRow.model}` : null,
+    input: step.usage?.inputTokens ?? 0, cached: step.usage?.cachedInputTokens ?? 0, output: step.usage?.outputTokens ?? 0, reasoning_tokens: step.usage?.reasoningTokens ?? 0,
+    text: step.text ?? null, reasoning: step.reasoning ?? null, calls, slow: (step.step_ms ?? 0) >= SLOW_STEP_MS,
+  };
+}
+
+function runPayload(run, usage) {
+  const rows = (usage ?? []).filter((row) => row.started_at && row.call_key?.includes(":agent:"))
+    .filter((row) => { const at = Date.parse(row.started_at); return at >= run.start - 5_000 && at <= run.end + 5_000; });
+  const aligned = rows.length === run.steps.length;
+  const seen = new Set();
+  return { file: run.file, start: run.start, end: run.end,
+    steps: run.steps.map((step, index) => stepPayload(run, step, seen, aligned ? rows[index] : null)) };
+}
+
+function usageStages(rows = []) {
+  const stages = new Map();
+  for (const row of rows) {
+    const key = (row.call_key ?? "").replace(/:(msuicode|nnyyai|tuzi|ark|packy|litellm|doubao)[^:]*:.*$/, "").replace(/\b(act|loc|prp)[A-Za-z0-9]{4,}\b/g, "$1").replace(/\d+/g, "#");
+    const stage = stages.get(key) ?? { key, calls: 0, input: 0, cached: 0, output: 0, reasoning: 0, ms: 0 };
+    stage.calls += 1; stage.input += row.input_tokens ?? 0; stage.cached += row.cached_input_tokens ?? 0;
+    stage.output += row.output_tokens ?? 0; stage.reasoning += row.reasoning_tokens ?? 0; stage.ms += row.ms ?? 0;
+    stages.set(key, stage);
+  }
+  return [...stages.values()].sort((a, b) => b.input + b.output - a.input - a.output);
+}
+
+/** Source audits embed whole frame-by-frame reports as evidence; the page only needs the start of each. */
+function clipFinding(finding) {
+  const clip = (text) => typeof text === "string" && text.length > EVIDENCE_CHARS ? `${text.slice(0, EVIDENCE_CHARS)}…<共 ${text.length} 字符>` : text;
+  return { ...finding, evidence: finding.evidence?.map((item) => typeof item === "string" ? clip(item) : { ...item, detail: clip(item.detail) }) };
+}
+
+function unitPayload(run, item) {
+  return {
+    ...summarize(item),
+    message: item.result?.message ?? null, error: item.result?.error ?? null, retry: item.result?.retry ?? null,
+    tool_calls: item.result?.tool_calls ?? null,
+    handoffs: (item.result?.findings ?? []).filter((finding) => finding.evidence?.some((evidence) => evidence.label === "逐集上报")).length,
+    reviewBasis: item.result?.review_basis ? { handoffs: item.result.review_basis.handoffs?.length ?? 0 } : null,
+    calls: item.calls.map((call) => ({ ...call, verdict: verdictOf(call) })),
+    runs: item.runs.map((agentRun) => runPayload(agentRun, item.result?.usage)),
+    findings: (item.result?.findings ?? []).map(clipFinding),
+    usage: usageStages(item.result?.usage),
+    failureRows: item.failures ?? [],
+    files: item.phase === "deep" ? list(path.join(run.reviewDir, "trace", "appearance", item.asset ?? "")).map((file) =>
+      path.posix.join(run.name, "trace", "appearance", item.asset, file)) : [],
+    hasVideo: item.episode ? run.videos.has(item.episode) : run.videos.size > 0,
+  };
+}
+
+function overviewPayload(id, run) {
+  const units = run.units.map(summarize);
+  return { id, path: run.dir, title: run.title, episodes: run.episodes, logs: run.logs, units,
+    videos: [...run.videos.keys()], failures: run.failures.length, unassigned: run.failures.filter((failure) => !failure.unit) };
+}
+
+function failurePrompt(run, file) {
+  if (path.basename(file) !== file) return null;
+  const raw = readJson(path.join(run.reviewDir, "failures", file));
+  if (!raw) return null;
+  const clip = (text) => text.length > 40_000 ? `${text.slice(0, 40_000)}\n…<共 ${text.length} 字符>` : text;
+  const parts = (content) => typeof content === "string" ? [{ type: "text", text: clip(content) }]
+    : (content ?? []).map((part) => {
+      if (part.type === "text" || part.type === "reasoning") return { type: part.type, text: clip(part.text ?? "") };
+      if (part.type === "tool-call") return { type: part.type, text: clip(`${part.toolName} ${JSON.stringify(part.input ?? part.args ?? {})}`) };
+      if (part.type === "tool-result") {
+        const output = JSON.stringify(part.output ?? part.result ?? "", (key, value) => key === "data" && typeof value === "string" && value.length > 200 ? `<${value.length} chars>` : value);
+        return { type: part.type, text: clip(`${part.toolName} ${output}`) };
+      }
+      return { type: part.type ?? "other", text: `[${part.type ?? "other"}${part.mediaType ? ` ${part.mediaType}` : ""}]` };
+    });
+  return { error: raw.error, chain: raw.error_chain, provider: raw.provider, model: raw.model, response: raw.responseBody ?? null,
+    messages: (Array.isArray(raw.prompt) ? raw.prompt : []).map((message) => ({ role: message.role, parts: parts(message.content) })) };
+}
+
+// ---- media -------------------------------------------------------------------------
+
+function seconds(at) {
+  if (/^\d+(\.\d+)?$/.test(at)) return Number(at);
+  const match = /^(?:(\d+):)?(\d{1,3}):(\d{2}(?:\.\d+)?)$/.exec(at);
+  return match ? Number(match[1] ?? 0) * 3600 + Number(match[2]) * 60 + Number(match[3]) : null;
+}
+
+function serveFrame(res, video, at) {
+  const ffmpeg = spawn("ffmpeg", ["-nostdin", "-loglevel", "error", "-ss", String(at), "-i", video, "-frames:v", "1",
+    "-vf", "scale=720:-2", "-q:v", "4", "-f", "image2pipe", "-vcodec", "mjpeg", "-"],
+  { env: { ...process.env, PATH: `${process.env.PATH}:/opt/homebrew/bin:/usr/local/bin` }, stdio: ["ignore", "pipe", "ignore"] });
+  const chunks = [];
+  ffmpeg.stdout.on("data", (chunk) => chunks.push(chunk));
+  ffmpeg.on("error", () => { res.writeHead(500); res.end("ffmpeg unavailable"); });
+  ffmpeg.on("close", () => {
+    if (res.writableEnded) return;
+    const image = Buffer.concat(chunks);
+    if (!image.length) { res.writeHead(404); res.end("no frame"); return; }
+    res.writeHead(200, { "content-type": "image/jpeg", "cache-control": "max-age=3600" });
+    res.end(image);
+  });
+}
+
+function serveVideo(req, res, file) {
+  const info = stat(file);
+  if (!info) { res.writeHead(404); res.end("video missing"); return; }
+  const type = VIDEO_TYPES[path.extname(file).toLowerCase()];
+  const range = /bytes=(\d*)-(\d*)/.exec(req.headers.range ?? "");
+  if (!range) {
+    res.writeHead(200, { "content-type": type, "content-length": info.size, "accept-ranges": "bytes" });
+    fs.createReadStream(file).pipe(res);
+    return;
+  }
+  const start = range[1] ? Number(range[1]) : Math.max(0, info.size - Number(range[2]));
+  const end = range[1] && range[2] ? Math.min(Number(range[2]), info.size - 1) : info.size - 1;
+  if (start > end) { res.writeHead(416, { "content-range": `bytes */${info.size}` }); res.end(); return; }
+  res.writeHead(206, { "content-type": type, "content-length": end - start + 1, "accept-ranges": "bytes", "content-range": `bytes ${start}-${end}/${info.size}` });
+  fs.createReadStream(file, { start, end }).pipe(res);
+}
+
+// ---- server ------------------------------------------------------------------------
+
+const json = (res, value, status = 200) => {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+  res.end(JSON.stringify(value));
+};
+
+function handle(req, res, options) {
+  const url = new URL(req.url, "http://localhost");
+  const query = url.searchParams;
+  if (url.pathname === "/") {
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+    res.end(fs.readFileSync(PAGE));
+    return;
+  }
+  if (url.pathname === "/api/workspaces") return json(res, workspaceRows());
+  if (url.pathname === "/api/open") {
+    if (!options.allowOpen) return json(res, { error: "只有监听本机地址时才能按路径打开" }, 403);
+    const id = register(query.get("path") ?? "");
+    return id ? json(res, { id }) : json(res, { error: "这个目录下没有 .review 审核记录" }, 404);
+  }
+  const run = runFor(query.get("w"));
+  if (!run) return json(res, { error: "workspace 不存在" }, 404);
+  if (url.pathname === "/api/run") return json(res, overviewPayload(query.get("w"), run));
+  if (url.pathname === "/api/unit") {
+    const item = run.byId.get(query.get("id"));
+    return item ? json(res, unitPayload(run, item)) : json(res, { error: "单元不存在" }, 404);
+  }
+  if (url.pathname === "/api/failure") {
+    const prompt = failurePrompt(run, query.get("f") ?? "");
+    return prompt ? json(res, prompt) : json(res, { error: "失败快照不存在" }, 404);
+  }
+  if (url.pathname === "/api/file") {
+    const root = path.join(run.dir, ".review");
+    const file = path.resolve(root, query.get("p") ?? "");
+    if (!file.startsWith(root + path.sep) || !stat(file)?.isFile()) return json(res, { error: "文件不存在" }, 404);
+    res.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+    fs.createReadStream(file).pipe(res);
+    return;
+  }
+  const video = run.videos.get(Number(query.get("ep")));
+  if (url.pathname === "/api/frame") {
+    const at = seconds(query.get("at") ?? "");
+    if (!video || at === null) return json(res, { error: "没有对应原片或时间" }, 404);
+    return serveFrame(res, video, at);
+  }
+  if (url.pathname === "/api/video") {
+    if (!video) return json(res, { error: "没有对应原片" }, 404);
+    return serveVideo(req, res, video);
+  }
+  return json(res, { error: "not found" }, 404);
+}
+
+/** Find every run under the given paths and build the server; the caller decides where it listens. */
+export function createReviewViewServer({ paths, allowOpen = true }) {
+  for (const given of paths) {
+    const root = path.resolve(given.replace(/^~(?=\/|$)/, os.homedir()));
+    for (const dir of register(root) ? [] : findWorkspaces(root)) register(dir);
+  }
+  const server = http.createServer((req, res) => {
+    try { handle(req, res, { allowOpen }); } catch (error) {
+      console.error(error);
+      if (!res.headersSent) json(res, { error: error instanceof Error ? error.message : String(error) }, 500);
+      else res.end();
+    }
+  });
+  return { server, workspaces: workspaceRows() };
+}