@lingjingai/scriptctl 0.35.0 → 0.36.0

package/dist/usecases/direct.js

@@ -1,4172 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { CliError, DEFAULT_BATCH_MAX_CHARS, DEFAULT_BATCH_MIN_LINES, DEFAULT_BATCH_MODE, DEFAULT_BATCH_TARGET_LINES, DEFAULT_DIRECT_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_SUMMARY_GROUP_SIZE, DEFAULT_SUMMARY_REDUCE_THRESHOLD_CHARS, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, sha256Text, writeJson, } from "../common.js";
-import { compactBatchResult, compactEpisodeResult, expandCompactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, cleanSynopsisList, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResultsWithReport, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, applyAssetGroupingDuplicateMerges, applyStateCurationPlan, applyStateBindingPlan, bindDefaultStateRefsInScript, buildAssetCurationAuditContextText, buildAssetCurationContextText, buildAssetCurationRepairContextText, buildAssetGroupingContextText, buildLocationCanonicalizationAuditContextText, buildPrimaryAssetCurationChunks, buildStateCurationChunks, buildStateCurationContextText, groupedAssetCurationChunks, combineLocationCanonicalizationPlan, buildStateBindingContexts, assetCurationAuditSourceKeys, combineAssetCurationExpressionPlans, combinePrimaryAssetCurationPlans, combineAssetCurationPlans, curateScriptAssets, ensureDefaultStates, assetCurationAuditCandidateSourceKeys, locationCanonicalizationCandidateSourceKeys, missingAssetCurationRequiredSourceKeys, normalizeStateBindingPlanShape, parseStateCurationExpressions, parseAssetCurationExpressions, parseAssetCurationExpressionsTolerant, parseAssetGroupingExpressions, assertLocationCanonicalizationPlan, applyMetadataToScript, validateAssetGroupingPlan, stateCurationSourceKeysForRefs, assertStateCurationPlan, } from "../domain/direct-core.js";
-import { validateScript } from "../domain/script/validate.js";
-import { makeProvider, providerCapabilities } from "../infra/providers.js";
-import { remoteScriptOutputStoreFromEnv } from "../infra/script-output-api.js";
-import { syncEpisodeCount } from "../infra/script-output-store.js";
-import { makeSourceManifest, prepareSource, } from "../infra/converters.js";
-import { Workspace, StageIncomplete, emptyRunState, stageRunStateName, } from "../domain/direct/stage.js";
-// Circular import: runner.ts → stages/index.ts → each stage file → THIS module
-// (the stageXxx impls live here). It's safe because every reference below
-// (runStages / runOne / STAGES) is used only inside function bodies that run at
-// CALL time (commandInitImpl, commandRun), never at module-load time — so the
-// cycle is fully resolved before any of them executes.
-import { runStages, runOne } from "../domain/direct/runner.js";
-import { STAGES } from "../domain/direct/stages/index.js";
-function strOf(v) {
-    if (v === null || v === undefined)
-        return "";
-    return String(v);
-}
-function legacyDirectInitStage(stage) {
-    if (stage === "episode_synopsis")
-        return "episode_merge";
-    if (stage === "script_synopsis")
-        return "summary";
-    return stage;
-}
-function runStateDirectStage(state) {
-    const initStage = strOf(state["init_stage"]);
-    const directStage = strOf(state["direct_stage"]);
-    if (directStage && legacyDirectInitStage(directStage) === initStage)
-        return directStage;
-    return initStage;
-}
-function isDict(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
-function isList(v) {
-    return Array.isArray(v);
-}
-function asList(v) {
-    return Array.isArray(v) ? v : [];
-}
-function checkpointTimestamp() {
-    const now = new Date();
-    return now.toISOString().replace(/\.\d+Z$/, "Z");
-}
-function parseIntList(v) {
-    return strOf(v).split(",").map((s) => parseInt(s.trim(), 10)).filter((n) => !Number.isNaN(n));
-}
-function parseStrList(v) {
-    return strOf(v).split(",").map((s) => s.trim()).filter((s) => s.length > 0);
-}
-// Parse a positive-integer CLI option (default when unset) with a uniform USAGE
-// error. Shared by --concurrency / --summary-threshold-chars / the batch opts.
-function parsePositiveIntOption(raw, flag, title, fallback) {
-    const value = parseInt(strOf(raw || fallback), 10);
-    if (Number.isNaN(value) || value < 1) {
-        throw new CliError(title, `${title}.`, {
-            exitCode: EXIT_USAGE,
-            required: [`${flag}: positive integer`],
-            received: [`${flag}: ${raw}`],
-            nextSteps: ["Use a positive integer and rerun init."],
-        });
-    }
-    return value;
-}
-// Status/report line for the synopsis stage: skipped, degraded (with episode
-// list when known), or null when the overview is complete. One formatter so
-// `direct init`'s report and `direct status` never word it differently.
-function formatSummaryStatusLine(skipped, degraded, degradedEpisodes) {
-    if (skipped)
-        return "summary: skipped (--skip-summary)";
-    if (!degraded)
-        return null;
-    return degradedEpisodes.length > 0
-        ? `summary: degraded (episodes: ${degradedEpisodes.join(", ")})`
-        : "summary: degraded (overview may be partial)";
-}
-// ---------------------------------------------------------------------------
-// run_state.json
-// ---------------------------------------------------------------------------
-export function updateRunState(workspace, updates) {
-    const p = path.join(directDir(workspace), "run_state.json");
-    let state = {};
-    if (exists(p)) {
-        try {
-            state = readJson(p);
-        }
-        catch {
-            state = {};
-        }
-    }
-    const directStage = strOf(updates["direct_stage"]);
-    const initStage = strOf(updates["init_stage"]);
-    if (directStage)
-        updates["init_stage"] = legacyDirectInitStage(directStage);
-    else if (initStage) {
-        updates["direct_stage"] = initStage;
-        updates["init_stage"] = legacyDirectInitStage(initStage);
-    }
-    Object.assign(state, updates);
-    state["updated_at"] = checkpointTimestamp();
-    writeJson(p, state);
-    return state;
-}
-export function readRunState(workspace) {
-    const p = path.join(directDir(workspace), "run_state.json");
-    if (!exists(p))
-        return {};
-    try {
-        const state = readJson(p);
-        return isDict(state) ? state : {};
-    }
-    catch {
-        return {};
-    }
-}
-function isoFromMs(ms) {
-    return new Date(ms).toISOString();
-}
-function durationMs(startedAtMs, finishedAtMs) {
-    return Math.max(0, Math.round(finishedAtMs - startedAtMs));
-}
-function timingErrorSummary(error) {
-    const e = error;
-    return `${e?.name ?? "Error"}: ${e?.message ?? ""}`.slice(0, 240);
-}
-function timingSummary(events) {
-    const stages = {};
-    const branches = {};
-    const slowChunks = events
-        .filter((event) => event.category === "chunk")
-        .sort((left, right) => right.duration_ms - left.duration_ms)
-        .slice(0, 20)
-        .map((event) => ({
-        name: event.name,
-        parent: event.parent ?? "",
-        duration_ms: event.duration_ms,
-        status: event.status,
-    }));
-    for (const event of events) {
-        if (event.category === "stage")
-            stages[event.name] = event.duration_ms;
-        if (event.category === "branch")
-            branches[event.name] = event.duration_ms;
-    }
-    return { stages, branches, slow_chunks: slowChunks };
-}
-class JsonTimingRecorder {
-    ws;
-    workspace;
-    command = "";
-    events = [];
-    activeSpans = [];
-    counter = 0;
-    constructor(ws, workspace) {
-        this.ws = ws;
-        this.workspace = workspace;
-    }
-    reset(command) {
-        this.command = command;
-        this.events = [];
-        this.activeSpans = [];
-        this.counter = 0;
-        this.flush();
-        updateRunState(this.workspace, {
-            timing_current: null,
-            timing_current_stage: null,
-            timing_current_branch: null,
-            timing_summary: { stages: {}, branches: {}, slow_chunks: [] },
-        });
-    }
-    async span(options, run) {
-        const startedAtMs = Date.now();
-        const active = {
-            name: options.name,
-            category: options.category,
-            ...(options.parent ? { parent: options.parent } : {}),
-            started_at: isoFromMs(startedAtMs),
-        };
-        this.activeSpans.push(active);
-        this.updateTimingCurrent();
-        try {
-            const value = await run();
-            this.removeActiveSpan(active);
-            this.record({
-                ...options,
-                status: "success",
-                startedAtMs,
-                finishedAtMs: Date.now(),
-            });
-            return value;
-        }
-        catch (error) {
-            this.removeActiveSpan(active);
-            this.record({
-                ...options,
-                status: "error",
-                startedAtMs,
-                finishedAtMs: Date.now(),
-                error: timingErrorSummary(error),
-            });
-            throw error;
-        }
-    }
-    removeActiveSpan(active) {
-        const index = this.activeSpans.lastIndexOf(active);
-        if (index >= 0)
-            this.activeSpans.splice(index, 1);
-    }
-    activeSpanByCategory(category) {
-        for (let index = this.activeSpans.length - 1; index >= 0; index -= 1) {
-            const span = this.activeSpans[index];
-            if (span.category === category)
-                return span;
-        }
-        return null;
-    }
-    currentSpanPayload(span) {
-        if (!span)
-            return null;
-        return {
-            name: span.name,
-            category: span.category,
-            parent: span.parent ?? null,
-            started_at: span.started_at,
-        };
-    }
-    updateTimingCurrent() {
-        updateRunState(this.workspace, {
-            timing_current: this.currentSpanPayload(this.activeSpans[this.activeSpans.length - 1] ?? null),
-            timing_current_stage: this.currentSpanPayload(this.activeSpanByCategory("stage")),
-            timing_current_branch: this.currentSpanPayload(this.activeSpanByCategory("branch")),
-            timing_summary: timingSummary(this.events),
-        });
-    }
-    record(options) {
-        const event = {
-            id: `tim_${String(++this.counter).padStart(5, "0")}`,
-            name: options.name,
-            category: options.category,
-            ...(options.parent ? { parent: options.parent } : {}),
-            status: options.status,
-            started_at: isoFromMs(options.startedAtMs),
-            finished_at: isoFromMs(options.finishedAtMs),
-            duration_ms: durationMs(options.startedAtMs, options.finishedAtMs),
-            ...(options.metadata ? { metadata: options.metadata } : {}),
-            ...(options.error ? { error: options.error } : {}),
-        };
-        this.events.push(event);
-        this.flush();
-        this.updateTimingCurrent();
-    }
-    flush() {
-        this.ws.writeJson("timings.json", {
-            version: 1,
-            command: this.command,
-            updated_at: checkpointTimestamp(),
-            events: this.events,
-            summary: timingSummary(this.events),
-        });
-    }
-}
-// ---------------------------------------------------------------------------
-// Paths for episode/batch results
-// ---------------------------------------------------------------------------
-function pad3(n) {
-    return String(n).padStart(3, "0");
-}
-function pad4(n) {
-    return String(n).padStart(4, "0");
-}
-function episodeResultPath(dir, ep) {
-    return path.join(dir, `ep_${pad3(Number(ep["episode"]))}.json`);
-}
-function episodeErrorPath(dir, ep) {
-    return path.join(dir, `ep_${pad3(Number(ep["episode"]))}.error.json`);
-}
-function episodeResultKey(ep) {
-    return `ep_${pad3(Number(ep["episode"]))}`;
-}
-// Read the synopsis carried on a persisted episode result (compact key `syn`),
-// for episode-synopsis reuse. Returns "" when absent/unreadable/legacy (no syn).
-function readEpisodeSynopsis(dir, episode) {
-    const p = episodeResultPath(dir, episode);
-    if (!exists(p))
-        return "";
-    try {
-        return readCarriedSynopsis(readJson(p));
-    }
-    catch {
-        return "";
-    }
-}
-function batchResultKey(batch) {
-    const bid = strOf(batch["batch_id"]).trim();
-    if (bid)
-        return bid;
-    return `bat_${pad4(Number(batch["batch_index"] ?? 0))}`;
-}
-function batchResultPath(dir, batch) {
-    return path.join(dir, `${batchResultKey(batch)}.json`);
-}
-function batchMarkdownPath(dir, batch) {
-    return path.join(dir, `${batchResultKey(batch)}.md`);
-}
-function batchErrorPath(dir, batch) {
-    return path.join(dir, `${batchResultKey(batch)}.error.json`);
-}
-function persistBatchResult(dir, batch, result) {
-    const rawMd = result["_raw_markdown"];
-    delete result["_raw_markdown"];
-    writeJson(batchResultPath(dir, batch), compactBatchResult(result));
-    const mdPath = batchMarkdownPath(dir, batch);
-    if (typeof rawMd === "string" && rawMd) {
-        fs.mkdirSync(path.dirname(mdPath), { recursive: true });
-        fs.writeFileSync(mdPath, rawMd, "utf-8");
-    }
-    else if (exists(mdPath)) {
-        deletePath(mdPath);
-    }
-}
-// ---------------------------------------------------------------------------
-// Per-batch result files ARE the state. A batch with `<key>.json` is done; with
-// `<key>.error.json` it failed; with neither it is pending. Reuse = file
-// presence — the agent drives what to (re)run via `direct status` + --episodes/
-// --batches selection. No content hashes, no global checkpoint, no destructive
-// reset: re-running a unit only ever touches that unit's own files, so the other
-// episodes can never be lost.
-// ---------------------------------------------------------------------------
-// Read a persisted batch result (reused or freshly written) for assembly.
-// Returns null if absent or unreadable, in which case the batch counts as
-// not-done and will be (re)run.
-function readBatchResult(dir, batch) {
-    const p = batchResultPath(dir, batch);
-    if (!exists(p))
-        return null;
-    try {
-        const result = normalizeEpisodeResult(readJson(p), batch);
-        result["_batch_id"] = batchResultKey(batch);
-        result["_batch_part"] = Number(batch["part"]);
-        result["_starts_inside_scene"] = Boolean(batch["starts_inside_scene"]);
-        return result;
-    }
-    catch {
-        return null;
-    }
-}
-function isDirectStageName(value) {
-    switch (value) {
-        case "source_prepare":
-        case "episode_plan":
-        case "batch_plan":
-        case "episode_titles":
-        case "batch_extract":
-        case "episode_merge":
-        case "episode_synopsis":
-        case "script_merge":
-        case "asset_curation":
-        case "state_curation":
-        case "state_binding":
-        case "metadata_extract":
-        case "script_synopsis":
-        case "validate":
-            return true;
-        default:
-            return false;
-    }
-}
-let progressFrame = 0;
-let activeProgressFrame = null;
-let progressTimer = null;
-let progressBlockLines = 0;
-// Single source of truth for a batch's on-disk state, shared by init (what to
-// (re)run) and status (what to report) so the two can never disagree. "done"
-// requires a result that actually PARSES — a present-but-corrupt result is
-// pending, so it self-heals on the next run instead of being silently trusted.
-function classifyBatch(dir, batch) {
-    if (readBatchResult(dir, batch) !== null)
-        return "done";
-    if (exists(batchErrorPath(dir, batch)))
-        return "error";
-    return "pending";
-}
-function statusFromBatchState(state) {
-    return state === "done" ? "success" : state;
-}
-function stageSnapshot(name, status, completed, total, message) {
-    const boundedTotal = Math.max(0, total);
-    const boundedCompleted = Math.max(0, Math.min(completed, boundedTotal));
-    return {
-        name,
-        status,
-        completed: boundedCompleted,
-        total: boundedTotal,
-        pending: status === "skipped" ? 0 : Math.max(0, boundedTotal - boundedCompleted),
-        warning: status === "warning" ? 1 : 0,
-        error: status === "error" ? 1 : 0,
-        message: message ?? "",
-    };
-}
-function formatDuration(ms) {
-    const value = Math.max(0, Math.round(ms));
-    if (value < 1000)
-        return `${value}ms`;
-    const seconds = value / 1000;
-    if (seconds < 60)
-        return `${seconds.toFixed(seconds < 10 ? 1 : 0)}s`;
-    const minutes = Math.floor(seconds / 60);
-    const rest = Math.round(seconds % 60);
-    return `${minutes}m${String(rest).padStart(2, "0")}s`;
-}
-function stageTimingDurations(state) {
-    const timingSummaryRaw = state["timing_summary"];
-    const timingSummary = isDict(timingSummaryRaw) ? timingSummaryRaw : {};
-    const stagesRaw = timingSummary["stages"];
-    const stages = isDict(stagesRaw) ? stagesRaw : {};
-    const out = {};
-    for (const [key, value] of Object.entries(stages)) {
-        const n = Number(value);
-        if (!Number.isNaN(n))
-            out[key] = n;
-    }
-    return out;
-}
-function runningTimingElapsed(state, stageName) {
-    const stageRaw = state["timing_current_stage"];
-    const currentRaw = isDict(stageRaw) ? stageRaw : state["timing_current"];
-    const current = isDict(currentRaw) ? currentRaw : null;
-    if (!current || strOf(current["category"]) !== "stage" || strOf(current["name"]) !== stageName)
-        return null;
-    const startedAt = Date.parse(strOf(current["started_at"]));
-    if (Number.isNaN(startedAt))
-        return null;
-    return Date.now() - startedAt;
-}
-function applyStageTiming(stage, state, durations) {
-    const duration = durations[stage.name];
-    const elapsed = stage.status === "running" ? runningTimingElapsed(state, stage.name) : null;
-    const messageParts = [stage.message].filter((item) => item);
-    if (typeof duration === "number")
-        messageParts.push(`耗时 ${formatDuration(duration)}`);
-    else if (elapsed !== null)
-        messageParts.push(`已运行 ${formatDuration(elapsed)}`);
-    return {
-        ...stage,
-        ...(typeof duration === "number" ? { duration_ms: duration } : {}),
-        ...(elapsed !== null ? { elapsed_ms: elapsed } : {}),
-        message: messageParts.join("; "),
-    };
-}
-function fileStage(name, filePath, runningStage) {
-    if (exists(filePath))
-        return stageSnapshot(name, "success", 1, 1);
-    return stageSnapshot(name, runningStage === name ? "running" : "pending", 0, 1);
-}
-function orderedFileStage(name, filePath, runningStage, runStatus) {
-    if (!canTrustStageArtifacts(name, runningStage, runStatus)) {
-        return stageSnapshot(name, "pending", 0, 1);
-    }
-    return fileStage(name, filePath, runningStage ?? "");
-}
-function canTrustStageArtifacts(name, runningStage, runStatus) {
-    if (runStatus !== "init_running" || !runningStage)
-        return true;
-    return stageOrder(name) <= stageOrder(runningStage);
-}
-function readJsonFile(filePath, fallback) {
-    if (!exists(filePath))
-        return fallback;
-    return readJson(filePath);
-}
-function readableJsonFile(filePath) {
-    if (!exists(filePath))
-        return false;
-    try {
-        readJson(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-function stageUnit(name) {
-    if (name === "batch_extract")
-        return "progress";
-    if (name === "episode_merge" || name === "episode_synopsis" || name === "episode_titles")
-        return "items";
-    return "step";
-}
-function stageLabel(name) {
-    switch (name) {
-        case "source_prepare": return "准备素材";
-        case "episode_plan": return "阅读剧本";
-        case "batch_plan": return "理解剧情";
-        case "episode_titles": return "整理内容";
-        case "batch_extract": return "整理内容";
-        case "episode_merge": return "生成剧本";
-        case "episode_synopsis": return "补充信息";
-        case "script_merge": return "生成剧本";
-        case "asset_curation": return "补充信息";
-        case "state_curation": return "补充信息";
-        case "state_binding": return "补充信息";
-        case "metadata_extract": return "补充信息";
-        case "script_synopsis": return "补充信息";
-        case "validate": return "检查结果";
-    }
-}
-function statusText(status) {
-    switch (status) {
-        case "success": return "完成";
-        case "running": return "进行中";
-        case "pending": return "等待中";
-        case "warning": return "需留意";
-        case "error": return "出错";
-        case "skipped": return "已跳过";
-    }
-}
-function statusPriority(status) {
-    switch (status) {
-        case "error": return 5;
-        case "warning": return 4;
-        case "running": return 3;
-        case "pending": return 2;
-        case "skipped": return 1;
-        default: return 0;
-    }
-}
-function userStageRows(stages) {
-    const byLabel = new Map();
-    for (const stage of stages) {
-        const label = stageLabel(stage.name);
-        byLabel.set(label, [...(byLabel.get(label) ?? []), stage]);
-    }
-    const rows = [];
-    for (const items of byLabel.values()) {
-        const total = items.reduce((sum, item) => sum + item.total, 0);
-        const completed = items.reduce((sum, item) => sum + (item.status === "skipped" ? item.total : item.completed), 0);
-        const status = items.reduce((max, item) => statusPriority(item.status) > statusPriority(max) ? item.status : max, "success");
-        rows.push({
-            name: items[0].name,
-            status,
-            completed: Math.round(completed),
-            total,
-            pending: items.reduce((sum, item) => sum + item.pending, 0),
-            warning: items.reduce((sum, item) => sum + item.warning, 0),
-            error: items.reduce((sum, item) => sum + item.error, 0),
-            message: items.map((item) => item.message).filter(Boolean).join("; "),
-        });
-    }
-    return rows;
-}
-function stageOrder(name) {
-    switch (name) {
-        case "source_prepare": return 0;
-        case "episode_plan": return 1;
-        case "episode_titles": return 2;
-        case "batch_plan": return 3;
-        case "batch_extract": return 4;
-        case "episode_merge": return 5;
-        case "episode_synopsis": return 6;
-        case "script_merge": return 7;
-        case "asset_curation": return 8;
-        case "state_curation": return 9;
-        case "state_binding": return 10;
-        case "metadata_extract": return 11;
-        case "script_synopsis": return 12;
-        case "validate": return 13;
-    }
-}
-function stageRatio(stage) {
-    if (stage.status === "success" || stage.status === "skipped")
-        return 1;
-    if (stage.total <= 0)
-        return 0;
-    return Math.max(0, Math.min(1, stage.completed / stage.total));
-}
-function stageCountText(stage) {
-    if (stage.status === "skipped")
-        return "-";
-    return `${stage.completed}/${stage.total}`;
-}
-function useProgressColor() {
-    return Boolean(process.stderr.isTTY) && process.env.NO_COLOR === undefined;
-}
-function ansi(code, text) {
-    return useProgressColor() ? `\x1b[${code}m${text}\x1b[0m` : text;
-}
-function colorStatus(status, text) {
-    switch (status) {
-        case "success": return ansi(32, text);
-        case "error": return ansi(31, text);
-        case "warning": return ansi(33, text);
-        case "running": return ansi(36, text);
-        case "pending": return ansi(34, text);
-        case "skipped": return ansi(90, text);
-    }
-}
-function dim(text) {
-    return ansi(2, text);
-}
-function bold(text) {
-    return ansi(1, text);
-}
-function progressBar(stage) {
-    const width = 24;
-    const ratio = stageRatio(stage);
-    const filled = Math.round(ratio * width);
-    const bar = `${"█".repeat(filled)}${"░".repeat(width - filled)}`;
-    return colorStatus(stage.status, bar);
-}
-function statusMark(stage) {
-    if (stage.status === "running") {
-        const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-        const frame = frames[progressFrame % frames.length];
-        progressFrame += 1;
-        return ansi(36, frame);
-    }
-    if (stage.status === "success")
-        return ansi(32, "✓");
-    if (stage.status === "error")
-        return ansi(31, "✖");
-    if (stage.status === "warning")
-        return ansi(33, "!");
-    if (stage.status === "skipped")
-        return ansi(90, "-");
-    return ansi(34, "•");
-}
-function renderProgressLine(stage) {
-    const status = colorStatus(stage.status, stage.status.padEnd(7));
-    const bits = [
-        statusMark(stage),
-        bold(stageLabel(stage.name)),
-        status,
-        progressBar(stage),
-        `${stageCountText(stage)} ${stageUnit(stage.name)}`,
-    ];
-    if (stage.error > 0)
-        bits.push(ansi(31, `error ${stage.error}`));
-    if (stage.warning > 0)
-        bits.push(ansi(33, `warning ${stage.warning}`));
-    if (stage.status === "pending")
-        bits.push(ansi(34, statusText("pending")));
-    if (stage.message)
-        bits.push(dim(`- ${stage.message}`));
-    return bits.join(" ");
-}
-function renderStageDetail(stage) {
-    const counts = [stageCountText(stage)];
-    if (stage.error > 0)
-        counts.push(ansi(31, `error ${stage.error}`));
-    if (stage.warning > 0)
-        counts.push(ansi(33, `warning ${stage.warning}`));
-    if (stage.status === "pending")
-        counts.push(ansi(34, statusText("pending")));
-    return `  ${dim("stage")} ${stageLabel(stage.name)} ${colorStatus(stage.status, statusText(stage.status))} ${counts.join(", ")}`;
-}
-function renderEpisodeDetail(episode) {
-    const errors = episode.error_batches.length > 0 ? ansi(31, " has errors") : "";
-    return `  ${dim("episode")} ${episode.episode_id} ${colorStatus(episode.status, statusText(episode.status))} ${episode.batches_done}/${episode.batches_total}, story ${colorStatus(episode.synopsis_status, statusText(episode.synopsis_status))}${errors}`;
-}
-function renderBatchDetail(batch) {
-    const reason = batch.error_code || batch.error_type || batch.message;
-    return `  ${dim("detail")} ${batch.batch_id} ${colorStatus(batch.status, statusText(batch.status))} ep_${pad3(batch.episode)}${reason ? ` - ${reason}` : ""}`;
-}
-function capDetails(lines, total, label) {
-    if (total <= lines.length)
-        return lines;
-    return [...lines, `  ${dim(`${total - lines.length} more ${label}`)}`];
-}
-function renderProgressDetails(snapshot, stageName) {
-    if (stageName === "batch_extract") {
-        const episodes = snapshot.episodes.filter((episode) => episode.status !== "success");
-        return [
-            ...capDetails(episodes.slice(0, 4).map((episode) => renderEpisodeDetail(episode)), episodes.length, "episodes"),
-        ];
-    }
-    if (stageName === "episode_titles" || stageName === "episode_merge" || stageName === "episode_synopsis") {
-        const episodes = snapshot.episodes.filter((episode) => episode.status !== "success" || episode.synopsis_status !== "success");
-        return capDetails(episodes.slice(0, 6).map((episode) => renderEpisodeDetail(episode)), episodes.length, "episodes");
-    }
-    const stages = snapshot.stages.filter((stage) => stage.status === "running" || stage.status === "pending" || stage.status === "warning" || stage.status === "error");
-    return capDetails(stages.slice(0, 5).map((stage) => renderStageDetail(stage)), stages.length, "stages");
-}
-function renderProgressFrameText(frame) {
-    return [renderProgressLine(frame.stage), ...frame.details].join("\n");
-}
-function renderProgressFrame() {
-    if (activeProgressFrame)
-        updateProgressBlock(renderProgressFrameText(activeProgressFrame));
-}
-function progressStageWithStatus(stage, status) {
-    if (status === "success")
-        return { ...stage, status, completed: stage.total, pending: 0, warning: 0, error: 0 };
-    if (status === "warning")
-        return { ...stage, status, completed: stage.total, pending: 0, warning: Math.max(1, stage.warning), error: 0 };
-    if (status === "skipped")
-        return { ...stage, status, completed: stage.total, pending: 0, warning: 0, error: 0 };
-    if (status === "error")
-        return { ...stage, status, error: Math.max(1, stage.error) };
-    return { ...stage, status };
-}
-function stopProgressTimer() {
-    if (!progressTimer)
-        return;
-    clearInterval(progressTimer);
-    progressTimer = null;
-}
-function ensureProgressTimer() {
-    if (!process.stderr.isTTY || progressTimer !== null)
-        return;
-    progressTimer = setInterval(renderProgressFrame, 80);
-}
-function eraseProgressBlock() {
-    if (progressBlockLines === 0)
-        return;
-    process.stderr.write(`\x1b[${progressBlockLines}A`);
-    for (let i = 0; i < progressBlockLines; i++) {
-        process.stderr.write("\x1b[2K");
-        if (i < progressBlockLines - 1)
-            process.stderr.write("\x1b[1B");
-    }
-    process.stderr.write("\r");
-    if (progressBlockLines > 1)
-        process.stderr.write(`\x1b[${progressBlockLines - 1}A`);
-    progressBlockLines = 0;
-}
-function updateProgressBlock(text) {
-    eraseProgressBlock();
-    process.stderr.write(text + "\n");
-    progressBlockLines = text.split("\n").length;
-}
-function persistProgressLine(text) {
-    eraseProgressBlock();
-    process.stderr.write(text + "\n");
-}
-function emitProgressStage(stage, details = []) {
-    const line = renderProgressLine(stage);
-    if (!process.stderr.isTTY) {
-        process.stderr.write(line + "\n");
-        return;
-    }
-    activeProgressFrame = { stage, details: stage.status === "running" ? details : [] };
-    if (stage.status === "running") {
-        ensureProgressTimer();
-        updateProgressBlock(renderProgressFrameText(activeProgressFrame));
-        return;
-    }
-    stopProgressTimer();
-    persistProgressLine(line);
-    activeProgressFrame = null;
-}
-function finishInitProgress() {
-    stopProgressTimer();
-    if (process.stderr.isTTY)
-        eraseProgressBlock();
-}
-function emitInitProgress(workspace, stageName, fallbackStatus = "running") {
-    const dd = directDir(workspace);
-    const episodePlanPath = path.join(dd, "episode_plan.json");
-    const batchPlanPath = path.join(dd, "batch_plan.json");
-    if (exists(episodePlanPath) && exists(batchPlanPath)) {
-        const snapshot = buildDirectStatusSnapshot(workspace);
-        const stage = snapshot.stages.find((item) => item.name === stageName);
-        if (stage) {
-            const renderedStage = fallbackStatus === "running" ? stage : progressStageWithStatus(stage, fallbackStatus);
-            emitProgressStage(renderedStage, renderProgressDetails(snapshot, stageName));
-            return;
-        }
-    }
-    emitProgressStage({
-        name: stageName,
-        status: fallbackStatus,
-        completed: fallbackStatus === "success" ? 1 : 0,
-        total: 1,
-        pending: fallbackStatus === "running" || fallbackStatus === "pending" ? 1 : 0,
-        warning: fallbackStatus === "warning" ? 1 : 0,
-        error: fallbackStatus === "error" ? 1 : 0,
-        message: "",
-    });
-}
-function emitFailedInitProgress(workspace) {
-    const stage = runStateDirectStage(readRunState(workspace));
-    if (isDirectStageName(stage))
-        emitInitProgress(workspace, stage, "error");
-}
-function buildDirectStatusSnapshot(workspace) {
-    const dd = directDir(workspace);
-    const episodePlanPath = path.join(dd, "episode_plan.json");
-    const batchPlanPath = path.join(dd, "batch_plan.json");
-    const episodePlan = readJsonFile(episodePlanPath, {});
-    const batchPlan = readJsonFile(batchPlanPath, {});
-    const episodes = asList(episodePlan["episodes"]);
-    const batches = asList(batchPlan["batches"]);
-    const state = readRunState(workspace);
-    const rawRunningStage = runStateDirectStage(state);
-    const runningStage = rawRunningStage && rawRunningStage !== "complete" && isDirectStageName(rawRunningStage) ? rawRunningStage : null;
-    const runStatus = strOf(state["status"]);
-    const failedStage = runStatus === "init_failed" ? runningStage : null;
-    const batchResultsDir = path.join(dd, "batch_results");
-    const episodeResultsDir = path.join(dd, "episode_results");
-    const trustEpisodeMergeArtifacts = canTrustStageArtifacts("episode_merge", runningStage, runStatus);
-    const trustEpisodeSynopsisArtifacts = canTrustStageArtifacts("episode_synopsis", runningStage, runStatus);
-    const trustStateCurationArtifacts = canTrustStageArtifacts("state_curation", runningStage, runStatus);
-    const trustStateBindingArtifacts = canTrustStageArtifacts("state_binding", runningStage, runStatus);
-    const trustMetadataArtifacts = canTrustStageArtifacts("metadata_extract", runningStage, runStatus);
-    const trustScriptSynopsisArtifacts = canTrustStageArtifacts("script_synopsis", runningStage, runStatus);
-    const batchesByEpisode = new Map();
-    const batchDetails = [];
-    let doneBatches = 0;
-    let errorBatches = 0;
-    for (const batch of batches) {
-        const batchId = batchResultKey(batch);
-        const status = statusFromBatchState(classifyBatch(batchResultsDir, batch));
-        if (status === "success")
-            doneBatches++;
-        if (status === "error")
-            errorBatches++;
-        const detail = {
-            batch_id: batchId,
-            episode: Number(batch["episode"]),
-            part: Number(batch["part"] ?? 0),
-            status,
-        };
-        if (status === "error") {
-            try {
-                const err = readJson(batchErrorPath(batchResultsDir, batch));
-                const errorCode = strOf(err["error_code"]);
-                const errorType = strOf(err["error_type"]);
-                const message = strOf(err["message"]);
-                if (errorCode)
-                    detail.error_code = errorCode;
-                if (errorType)
-                    detail.error_type = errorType;
-                if (message)
-                    detail.message = message;
-            }
-            catch {
-                detail.error_type = "Error";
-            }
-        }
-        batchDetails.push(detail);
-        if (!batchesByEpisode.has(detail.episode))
-            batchesByEpisode.set(detail.episode, []);
-        batchesByEpisode.get(detail.episode).push(detail);
-    }
-    const pendingBatches = batches.length - doneBatches - errorBatches;
-    const degradedSynopsisEpisodes = trustEpisodeSynopsisArtifacts
-        ? new Set(asList(state["summary_degraded_episodes"]).map((n) => Number(n)))
-        : new Set();
-    const episodeSnapshots = [];
-    let completeEpisodes = 0;
-    let episodeResults = 0;
-    let episodeSynopses = 0;
-    for (const episode of episodes) {
-        const episodeNum = Number(episode["episode"]);
-        const epBatches = batchesByEpisode.get(episodeNum) ?? [];
-        const batchesDone = epBatches.filter((b) => b.status === "success").length;
-        const batchesError = epBatches.filter((b) => b.status === "error").length;
-        const batchesPending = epBatches.length - batchesDone - batchesError;
-        const epResultPath = episodeResultPath(episodeResultsDir, episode);
-        const hasEpisodeResult = trustEpisodeMergeArtifacts && readableJsonFile(epResultPath);
-        if (hasEpisodeResult)
-            episodeResults++;
-        const synopsis = trustEpisodeSynopsisArtifacts ? readEpisodeSynopsis(episodeResultsDir, episode) : null;
-        if (synopsis)
-            episodeSynopses++;
-        const status = batchesError > 0
-            ? "error"
-            : epBatches.length > 0 && batchesDone === epBatches.length && hasEpisodeResult
-                ? "success"
-                : runningStage === "batch_extract" || runningStage === "episode_merge"
-                    ? "running"
-                    : "pending";
-        if (status === "success")
-            completeEpisodes++;
-        const synopsisStatus = degradedSynopsisEpisodes.has(episodeNum)
-            ? "warning"
-            : synopsis
-                ? "success"
-                : Boolean(state["summary_skipped"]) && !exists(path.join(dd, "synopsis.json"))
-                    ? "skipped"
-                    : "pending";
-        episodeSnapshots.push({
-            episode: episodeNum,
-            episode_id: episodeResultKey(episode),
-            status,
-            batches_done: batchesDone,
-            batches_total: epBatches.length,
-            batches_error: batchesError,
-            batches_pending: batchesPending,
-            synopsis_status: synopsisStatus,
-            error_batches: epBatches.filter((b) => b.status === "error").map((b) => b.batch_id),
-        });
-    }
-    const sourceStage = exists(path.join(workspace, "source.txt"))
-        ? stageSnapshot("source_prepare", "success", 1, 1)
-        : stageSnapshot("source_prepare", runningStage === "source_prepare" ? "running" : "pending", 0, 1);
-    const episodePlanStage = episodes.length > 0
-        ? stageSnapshot("episode_plan", "success", episodes.length, episodes.length)
-        : stageSnapshot("episode_plan", runningStage === "episode_plan" ? "running" : "pending", 0, 1);
-    const batchPlanStage = batches.length > 0
-        ? stageSnapshot("batch_plan", "success", batches.length, batches.length)
-        : stageSnapshot("batch_plan", runningStage === "batch_plan" ? "running" : "pending", 0, 1);
-    const titleDeg = isDict(state["title_degraded"]) ? state["title_degraded"] : null;
-    const episodeTitlesStage = stageSnapshot("episode_titles", episodes.length === 0
-        ? runningStage === "episode_titles" ? "running" : "pending"
-        : titleDeg && Number(titleDeg["count"] ?? 0) > 0 ? "warning" : "success", episodes.length > 0 ? episodes.length : 0, episodes.length > 0 ? episodes.length : 1, titleDeg && Number(titleDeg["count"] ?? 0) > 0
-        ? `deterministic titles: ${asList(titleDeg["episodes"]).join(", ")}`
-        : "");
-    const batchStatus = errorBatches > 0
-        ? "error"
-        : doneBatches === batches.length && batches.length > 0
-            ? "success"
-            : runningStage === "batch_extract"
-                ? "running"
-                : "pending";
-    const batchStage = {
-        ...stageSnapshot("batch_extract", batchStatus, doneBatches, batches.length),
-        pending: pendingBatches,
-        error: errorBatches,
-    };
-    const episodeMergeStatus = errorBatches > 0
-        ? "error"
-        : episodeResults === episodes.length && episodes.length > 0
-            ? "success"
-            : runningStage === "episode_merge"
-                ? "running"
-                : "pending";
-    const episodeMergeStage = stageSnapshot("episode_merge", episodeMergeStatus, episodeResults, episodes.length);
-    const synopsisWarning = degradedSynopsisEpisodes.size;
-    const episodeSynopsisStatus = synopsisWarning > 0
-        ? "warning"
-        : episodeSynopses === episodes.length && episodes.length > 0
-            ? "success"
-            : runningStage === "episode_synopsis"
-                ? "running"
-                : "pending";
-    const episodeSynopsisStage = {
-        ...stageSnapshot("episode_synopsis", episodeSynopsisStatus, episodeSynopses, episodes.length),
-        warning: synopsisWarning,
-    };
-    const scriptStage = orderedFileStage("script_merge", path.join(dd, "script.initial.json"), runningStage, runStatus);
-    const curationStage = orderedFileStage("asset_curation", path.join(dd, "asset_curation.json"), runningStage, runStatus);
-    const stateCurationStage = trustStateCurationArtifacts
-        ? orderedFileStage("state_curation", path.join(dd, "state_curation.json"), runningStage, runStatus)
-        : stageSnapshot("state_curation", runningStage === "state_curation" ? "running" : "pending", 0, 1);
-    const stateBindingStage = trustStateBindingArtifacts
-        ? orderedFileStage("state_binding", path.join(dd, "state_binding.json"), runningStage, runStatus)
-        : stageSnapshot("state_binding", runningStage === "state_binding" ? "running" : "pending", 0, 1);
-    const metadataStage = Boolean(state["metadata_skipped"]) && trustMetadataArtifacts
-        ? stageSnapshot("metadata_extract", "skipped", 0, 1, "metadata: skipped (--skip-metadata)")
-        : orderedFileStage("metadata_extract", path.join(dd, "asset_metadata.json"), runningStage, runStatus);
-    const synopsisPath = path.join(dd, "synopsis.json");
-    const summaryLine = formatSummaryStatusLine(Boolean(state["summary_skipped"]), Boolean(state["summary_degraded"]), asList(state["summary_degraded_episodes"]).map((n) => Number(n)));
-    const hasScriptSynopsis = trustScriptSynopsisArtifacts && exists(synopsisPath);
-    const scriptSynopsisStatus = hasScriptSynopsis
-        ? Boolean(state["summary_degraded"]) ? "warning" : "success"
-        : trustScriptSynopsisArtifacts && Boolean(state["summary_skipped"])
-            ? "skipped"
-            : runningStage === "script_synopsis"
-                ? "running"
-                : "pending";
-    const scriptSynopsisStage = stageSnapshot("script_synopsis", scriptSynopsisStatus, hasScriptSynopsis ? 1 : 0, 1, summaryLine ?? "");
-    const validationPath = path.join(dd, "validation.json");
-    let validationStage = orderedFileStage("validate", validationPath, runningStage, runStatus);
-    if (exists(validationPath) && !(runStatus === "init_running" && runningStage && stageOrder("validate") > stageOrder(runningStage))) {
-        const validation = readJson(validationPath);
-        validationStage = stageSnapshot("validate", Boolean(validation["passed"]) ? "success" : "warning", 1, 1);
-    }
-    const timingDurations = stageTimingDurations(state);
-    const stages = [
-        sourceStage,
-        episodePlanStage,
-        batchPlanStage,
-        episodeTitlesStage,
-        batchStage,
-        episodeMergeStage,
-        episodeSynopsisStage,
-        scriptStage,
-        curationStage,
-        stateCurationStage,
-        stateBindingStage,
-        metadataStage,
-        scriptSynopsisStage,
-        validationStage,
-    ]
-        .map((stage) => failedStage === stage.name ? { ...stage, status: "error", error: Math.max(1, stage.error) } : stage)
-        .map((stage) => applyStageTiming(stage, state, timingDurations));
-    let overallStatus = "pending";
-    const maxStage = stages.reduce((max, stage) => statusPriority(stage.status) > statusPriority(max) ? stage.status : max, "success");
-    if (runStatus === "init_failed" || runStatus === "init_incomplete" || maxStage === "error")
-        overallStatus = "error";
-    else if (runStatus === "init_running" || maxStage === "running")
-        overallStatus = "running";
-    else if (maxStage === "warning")
-        overallStatus = "warning";
-    else if (stages.filter((s) => s.name !== "script_synopsis").every((s) => s.status === "success" || s.status === "warning" || s.status === "skipped"))
-        overallStatus = "success";
-    return {
-        overall_status: overallStatus,
-        running_stage: runningStage,
-        stages,
-        episodes: episodeSnapshots,
-        batches: batchDetails,
-    };
-}
-function renderDirectStatusResult(snapshot) {
-    const completedEpisodes = snapshot.episodes.filter((episode) => episode.status === "success").length;
-    const result = [
-        "Overall",
-        `overall: ${statusText(snapshot.overall_status)}; current: ${snapshot.running_stage && isDirectStageName(snapshot.running_stage) ? stageLabel(snapshot.running_stage) : "-"}`,
-        snapshot.episodes.length > 0 ? `episodes: ${completedEpisodes}/${snapshot.episodes.length} 完成` : "episodes: 等待中",
-        "Stages",
-    ];
-    for (const stage of userStageRows(snapshot.stages)) {
-        result.push(`${stageLabel(stage.name)}: ${statusText(stage.status)} ${stageCountText(stage)}${stage.error ? `, error ${stage.error}` : ""}${stage.warning ? `, warning ${stage.warning}` : ""}${stage.status === "pending" ? ", 等待中" : ""}${stage.message ? ` - ${stage.message}` : ""}`);
-    }
-    result.push("Episodes");
-    for (const episode of snapshot.episodes) {
-        const errors = episode.error_batches.length > 0 ? `, error ids: ${episode.error_batches.join(",")}` : "";
-        result.push(`${episode.episode_id}: ${statusText(episode.status)} ${episode.batches_done}/${episode.batches_total}, story ${statusText(episode.synopsis_status)}${errors}`);
-    }
-    result.push("Details");
-    const noisyBatches = snapshot.batches.filter((batch) => batch.status !== "success");
-    if (noisyBatches.length === 0) {
-        result.push("no error/warning/pending details");
-    }
-    else {
-        for (const batch of noisyBatches.slice(0, 50)) {
-            const reason = batch.error_code || batch.error_type || batch.message;
-            result.push(`${batch.batch_id}: ${statusText(batch.status)} ep_${pad3(batch.episode)}${reason ? ` - ${reason}` : ""}`);
-        }
-        if (noisyBatches.length > 50)
-            result.push(`${noisyBatches.length - 50} more non-success details not shown`);
-    }
-    return result;
-}
-// Delete result/meta/error/markdown files whose unit key is no longer in the
-// current plan (e.g. the source shed an episode). Pure function of the plan —
-// it never inspects hashes, content, or run_state, so it can only remove units
-// the plan no longer references. Also retires the legacy v3 `index.json`.
-function gcOrphanUnits(dir, liveKeys) {
-    if (!exists(dir))
-        return [];
-    const removed = [];
-    for (const name of fs.readdirSync(dir)) {
-        if (name === "index.json") {
-            deletePath(path.join(dir, name));
-            removed.push(name);
-            continue;
-        }
-        const key = name.replace(/\.(meta\.json|error\.json|json|md)$/, "");
-        if (key === name)
-            continue; // not a recognized unit artifact
-        if (!liveKeys.has(key)) {
-            deletePath(path.join(dir, name));
-            removed.push(name);
-        }
-    }
-    return removed;
-}
-function mergeScene(target, source) {
-    if ((target["location_name"] === "" || target["location_name"] === "未知场景" || target["location_name"] === null || target["location_name"] === undefined) &&
-        source["location_name"]) {
-        target["location_name"] = source["location_name"];
-    }
-    if (!target["location_state"] && source["location_state"]) {
-        target["location_state"] = source["location_state"];
-    }
-    for (const actor of asList(source["actor_names"])) {
-        if (!isList(target["actor_names"]))
-            target["actor_names"] = [];
-        uniqueAdd(target["actor_names"], actor);
-    }
-    const targetStates = target["actor_states"] ?? {};
-    if (!isDict(target["actor_states"]))
-        target["actor_states"] = targetStates;
-    if (isDict(source["actor_states"])) {
-        for (const [actor, state] of Object.entries(source["actor_states"])) {
-            if (state && !targetStates[actor])
-                targetStates[actor] = String(state);
-        }
-    }
-    for (const prop of asList(source["prop_names"])) {
-        if (!isList(target["prop_names"]))
-            target["prop_names"] = [];
-        uniqueAdd(target["prop_names"], prop);
-    }
-    if (!isList(target["actions"]))
-        target["actions"] = [];
-    target["actions"].push(...asList(source["actions"]));
-}
-export function mergeBatchResultsForEpisode(episode, batchResults) {
-    const scenes = [];
-    const actors = [];
-    const locations = [];
-    const props = [];
-    const speakers = [];
-    const stateDefinitions = [];
-    // Ordered, non-empty per-fragment synopses for the episode-level reduce. The
-    // reduce/passthrough decision (and LLM call) happens in the orchestrator, NOT
-    // here — this pure function only collects the beats in _batch_part order.
-    const batchSynopses = [];
-    const sorted = [...batchResults].sort((a, b) => Number(a["_batch_part"] ?? 0) - Number(b["_batch_part"] ?? 0));
-    for (const item of sorted) {
-        const synopsis = strOf(item["synopsis"]).trim();
-        if (synopsis)
-            batchSynopses.push(synopsis);
-        const itemScenes = asList(item["scenes"]);
-        if (itemScenes.length === 0)
-            continue;
-        if (item["_starts_inside_scene"] && scenes.length > 0) {
-            mergeScene(scenes[scenes.length - 1], itemScenes[0]);
-            scenes.push(...itemScenes.slice(1));
-        }
-        else {
-            scenes.push(...itemScenes);
-        }
-        for (const asset of asList(item["actors"])) {
-            if (isDict(asset))
-                _md_push_asset(actors, strOf(asset["name"]), strOf(asset["description"]).trim() || null);
-        }
-        for (const asset of asList(item["locations"])) {
-            if (isDict(asset))
-                _md_push_asset(locations, strOf(asset["name"]), strOf(asset["description"]).trim() || null);
-        }
-        for (const asset of asList(item["props"])) {
-            if (isDict(asset))
-                _md_push_asset(props, strOf(asset["name"]), strOf(asset["description"]).trim() || null);
-        }
-        for (const speaker of asList(item["speakers"])) {
-            if (isDict(speaker))
-                speakers.push(speaker);
-        }
-        for (const stateDef of asList(item["state_definitions"])) {
-            if (isDict(stateDef))
-                stateDefinitions.push(stateDef);
-        }
-    }
-    const result = {
-        episode: Number(episode["episode"]),
-        title: episode["title"],
-        source_span: episode["source_span"],
-        scenes,
-        actors,
-        locations,
-        props,
-        speakers,
-        state_definitions: stateDefinitions,
-    };
-    const normalized = normalizeEpisodeResult(result, episode);
-    // Carry the ordered fragment synopses on the merged result so the orchestrator
-    // can run the episode-level reduce (or passthrough) on them. Not part of the
-    // episode schema — stripped before the episode entry is built downstream.
-    normalized["batch_synopses"] = batchSynopses;
-    return normalized;
-}
-// Record a batch failure: write `<key>.error.json` (which marks the batch as
-// "tried and failed" → sticky on plain resume) and drop any stale result file.
-// The error_code (e.g. PROVIDER_CONTENT_FILTERED) is surfaced so the agent can
-// see WHY in `direct status` / `direct review` and decide whether to re-run.
-//
-// Deliberate content-filter policy split: batch extraction is HARD (sticky
-// error, episode blocked until an explicit re-run) because batch content is the
-// deliverable and cannot be fabricated; episode TITLES are SOFT (degrade to a
-// deterministic title, recorded as title_degraded, never blocking) because a
-// title is non-essential and always has a safe fallback. Same provider signal,
-// two intentional policies — see enrichEpisodeTitlesChunked.
-function writeBatchFailure(dir, batch, exc) {
-    const err = exc;
-    const error = {
-        batch_id: batchResultKey(batch),
-        episode: Number(batch["episode"]),
-        part: Number(batch["part"]),
-        source_span: batch["source_span"],
-        line_range: batch["line_range"],
-        error_type: err?.name || "Error",
-        message: (err?.message || err?.name || "Error").slice(0, 500),
-        failed_at: checkpointTimestamp(),
-    };
-    if (exc instanceof CliError) {
-        if (exc.errorCode)
-            error["error_code"] = exc.errorCode;
-        if (exc.required.length > 0)
-            error["required"] = exc.required;
-        if (exc.received.length > 0)
-            error["received"] = exc.received;
-        if (exc.nextSteps.length > 0)
-            error["next"] = exc.nextSteps;
-    }
-    const resultPath = batchResultPath(dir, batch);
-    if (exists(resultPath))
-        deletePath(resultPath);
-    writeJson(batchErrorPath(dir, batch), error);
-    return error;
-}
-function initFailedReport(workspace, opts) {
-    const lastError = { title: opts.title, received: opts.received, failed_at: checkpointTimestamp() };
-    if (opts.errorCode)
-        lastError["error_code"] = opts.errorCode;
-    const payload = {
-        status: "init_failed",
-        command: "direct init",
-        init_stage: opts.stage,
-        last_error: lastError,
-    };
-    if (opts.updates)
-        Object.assign(payload, opts.updates);
-    updateRunState(workspace, payload);
-    return new CliError(opts.title, opts.title, {
-        exitCode: opts.exitCode ?? EXIT_RUNTIME,
-        errorCode: opts.errorCode,
-        required: opts.required,
-        received: opts.received,
-        nextSteps: opts.nextSteps,
-    });
-}
-// Catch→initFailedReport for the deterministic stages: format the raw exception
-// into a single-line `received` and write the failure run_state, so the cast +
-// `slice(0,160)` + updates boilerplate lives here instead of being hand-copied
-// into every stage's catch block.
-function stageFailure(workspace, exc, opts) {
-    const e = exc;
-    const received = exc instanceof CliError && exc.received.length > 0
-        ? exc.received
-        : [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`];
-    throw initFailedReport(workspace, {
-        title: opts.title,
-        stage: opts.stage,
-        exitCode: exc instanceof CliError ? exc.exitCode : undefined,
-        errorCode: exc instanceof CliError ? exc.errorCode : undefined,
-        required: opts.required,
-        received,
-        nextSteps: opts.nextSteps,
-        ...(opts.updates ? { updates: opts.updates } : {}),
-    });
-}
-// ---------------------------------------------------------------------------
-// Concurrency limiter (mirrors ThreadPoolExecutor)
-// ---------------------------------------------------------------------------
-async function pMapWithConcurrency(items, concurrency, worker) {
-    const out = new Array(items.length);
-    let cursor = 0;
-    const limit = Math.max(1, Math.min(concurrency, items.length));
-    await Promise.all(Array.from({ length: limit }, async () => {
-        while (true) {
-            const idx = cursor++;
-            if (idx >= items.length)
-                break;
-            try {
-                const value = await worker(items[idx], idx);
-                out[idx] = { ok: true, value };
-            }
-            catch (error) {
-                out[idx] = { ok: false, error, item: items[idx] };
-            }
-        }
-    }));
-    return out;
-}
-function unwrapConcurrentOutcomes(outcomes) {
-    const failed = outcomes.find((outcome) => !outcome.ok);
-    if (failed)
-        throw failed.error;
-    return outcomes.map((outcome) => outcome.value);
-}
-function providerErrorSummary(error) {
-    if (error instanceof CliError && error.errorCode)
-        return error.errorCode;
-    const e = error;
-    const msg = strOf(e?.message).replace(/\s+/g, " ").trim();
-    if (/prohibited content|content filter|refused/i.test(msg))
-        return "PROVIDER_CONTENT_FILTERED";
-    return `${e?.name ?? "Error"}: ${msg}`.slice(0, 160);
-}
-function cloneDict(value) {
-    return structuredClone(value);
-}
-// Generate the plan's missing episode titles in bounded, concurrent chunks.
-// Title generation is non-essential (every episode has a deterministic
-// fallback), so a chunk that the provider filters or fails does NOT abort
-// init: its episodes are retried one-by-one to isolate the poisoned excerpt,
-// and whatever still fails degrades to a deterministic title. The plan is
-// mutated in place and persisted by the caller; degradation is recorded to
-// run_state so it's visible without being a hard failure.
-async function enrichEpisodeTitlesChunked(workspace, sourceText, plan, provider, concurrency) {
-    const chunks = chunkEpisodesNeedingTitles(plan, DEFAULT_TITLE_CHUNK_SIZE);
-    if (chunks.length === 0 || !provider.extractEpisodeTitles) {
-        // Nothing to title, or a provider with no title support: deterministic for all.
-        return applyEpisodeTitlesToPlan(sourceText, plan, new Map());
-    }
-    const extract = provider.extractEpisodeTitles.bind(provider);
-    const generated = new Map();
-    const collect = (outcomes) => {
-        for (const o of outcomes) {
-            if (o.ok)
-                for (const [num, title] of o.value)
-                    generated.set(num, title);
-        }
-    };
-    // Phase 1: chunked requests.
-    const chunkOutcomes = await pMapWithConcurrency(chunks, concurrency, async (chunk) => episodeTitleResponseMap(await extract(sourceText, { episodes: chunk })));
-    collect(chunkOutcomes);
-    // Phase 2: any episode still WITHOUT a title — whether its chunk threw or the
-    // chunk returned 200 but omitted it — gets one isolated single-episode request,
-    // so a single poisoned/omitted excerpt can't deny its chunk-mates a real title.
-    const missing = chunks.flat().filter((ep) => !generated.has(Number(ep["episode"] ?? 0)));
-    let reason;
-    if (missing.length > 0) {
-        const singleOutcomes = await pMapWithConcurrency(missing, concurrency, async (ep) => episodeTitleResponseMap(await extract(sourceText, { episodes: [ep] })));
-        collect(singleOutcomes);
-        const firstError = singleOutcomes.find((o) => !o.ok);
-        if (firstError)
-            reason = providerErrorSummary(firstError.error);
-    }
-    const degraded = applyEpisodeTitlesToPlan(sourceText, plan, generated);
-    if (degraded.length > 0) {
-        updateRunState(workspace, {
-            title_degraded: {
-                count: degraded.length,
-                episodes: degraded,
-                reason: reason ?? "provider returned no title for these episodes; used deterministic titles",
-            },
-        });
-    }
-    return degraded;
-}
-// ---------------------------------------------------------------------------
-// Synopsis reduce helpers (map-reduce overview)
-// ---------------------------------------------------------------------------
-// Stitch an ordered list of synopses into one. ≥2 beats → LLM stitch; falls
-// back to a plain join when the provider has no synopsis method or returns
-// empty. Throws if the provider call throws — callers catch for soft-degrade.
-async function reduceSynopses(provider, synopses, ctx) {
-    if (provider.extractEpisodeSynopsis) {
-        const out = await provider.extractEpisodeSynopsis(synopses, ctx);
-        const stitched = isDict(out) ? strOf(out["synopsis"]).trim() : "";
-        if (stitched)
-            return stitched;
-    }
-    return synopses.join(" ");
-}
-// Reduce-1: resolve each merged episode's `synopsis` IN PLACE. ≤1 fragment beat
-// → passthrough. ≥2 beats: if the episode is unchanged this round and has a
-// persisted `syn`, REUSE it verbatim (never overwrite a good prior synopsis —
-// including under --skip-summary); else --skip-summary → join the fresh beats
-// (no LLM); else defer the LLM stitch. The deferred stitches run concurrently;
-// a failed stitch degrades to the FRESH joined beats (never a stale prior, which
-// for a changed episode would describe old content). Returns degraded episode
-// numbers. Reads prior `syn` before the caller overwrites ep_NNN.json.
-async function resolveEpisodeSynopses(provider, results, opts) {
-    const stitchPending = [];
-    for (const merged of results) {
-        const episodeNum = Number(merged["episode"]);
-        const beats = cleanSynopsisList(merged["batch_synopses"]);
-        delete merged["batch_synopses"];
-        if (beats.length <= 1) {
-            if (beats[0])
-                merged["synopsis"] = beats[0];
-        }
-        else {
-            const unchanged = !opts.resummarize && !opts.changedEpisodes.has(episodeNum);
-            const priorSyn = unchanged ? readEpisodeSynopsis(opts.resultsDir, merged) : "";
-            if (unchanged && priorSyn)
-                merged["synopsis"] = priorSyn;
-            else if (opts.skipSummary)
-                merged["synopsis"] = beats.join(" ");
-            else
-                stitchPending.push({ merged, beats });
-        }
-    }
-    const degraded = [];
-    await pMapWithConcurrency(stitchPending, opts.concurrency, async (it) => {
-        const episodeNum = Number(it.merged["episode"]);
-        try {
-            const syn = await reduceSynopses(provider, it.beats, { episode: episodeNum, title: it.merged["title"] });
-            if (syn)
-                it.merged["synopsis"] = syn;
-        }
-        catch {
-            degraded.push(episodeNum);
-            it.merged["synopsis"] = it.beats.join(" ");
-        }
-    });
-    return degraded;
-}
-// Single source of truth for the overview field-shaping rules (trim strings,
-// keep only well-formed main_characters). Both the persisted synopsis.json and
-// the in-memory script go through this, so the two can never normalize differently.
-function normalizeOverviewFields(fields) {
-    return {
-        synopsis: strOf(fields["synopsis"]).trim(),
-        theme: strOf(fields["theme"]).trim(),
-        logline: strOf(fields["logline"]).trim(),
-        style: strOf(fields["style"]).trim(),
-        main_characters: asList(fields["main_characters"]).filter(isDict),
-    };
-}
-// Assign ALREADY-normalized overview fields onto the script. Callers with raw
-// provider/disk fields must go through applyScriptSynopsisFields instead.
-function assignOverviewFields(script, o) {
-    script["synopsis"] = o["synopsis"];
-    script["theme"] = o["theme"];
-    script["logline"] = o["logline"];
-    script["main_characters"] = o["main_characters"];
-    // style is produced by the summary layer (a whole-show judgement); only
-    // override the merge-stage placeholder when the reduce actually produced one.
-    if (o["style"])
-        script["style"] = o["style"];
-}
-// Normalize untrusted fields (provider output / a reused synopsis.json) and
-// assign them onto the script.
-function applyScriptSynopsisFields(script, fields) {
-    assignOverviewFields(script, normalizeOverviewFields(fields));
-}
-function synopsisGroupSignature(opts) {
-    return sha256Text(JSON.stringify(sortDeep({
-        title: strOf(opts.title),
-        thresholdChars: opts.thresholdChars,
-        groupSize: opts.groupSize,
-        level: opts.level,
-        groupIndex: opts.groupIndex,
-        synopses: opts.synopses,
-    })));
-}
-function synopsisGroupPartPath(dd, signature) {
-    return path.join(dd, "synopsis_parts", `${signature}.json`);
-}
-async function loadOrRunSynopsisGroup(provider, groupSynopses, opts) {
-    if (groupSynopses.length <= 1)
-        return { value: groupSynopses[0] ?? "", reused: false };
-    const signature = synopsisGroupSignature({
-        title: opts.title,
-        thresholdChars: opts.thresholdChars,
-        groupSize: opts.groupSize,
-        level: opts.level,
-        groupIndex: opts.groupIndex,
-        synopses: groupSynopses,
-    });
-    const partPath = synopsisGroupPartPath(opts.dd, signature);
-    if (!opts.resummarize && exists(partPath)) {
-        const prior = readJson(partPath);
-        if (isDict(prior) && strOf(prior["source_group_signature"]) === signature) {
-            const synopsis = strOf(prior["synopsis"]).trim();
-            if (synopsis)
-                return { value: synopsis, reused: true };
-        }
-    }
-    try {
-        const synopsis = await reduceSynopses(provider, [...groupSynopses], { title: opts.title });
-        writeJson(partPath, {
-            version: 1,
-            source_group_signature: signature,
-            level: opts.level,
-            group_index: opts.groupIndex,
-            source_count: groupSynopses.length,
-            synopsis,
-            updated_at: checkpointTimestamp(),
-        });
-        return { value: synopsis, reused: false };
-    }
-    catch (error) {
-        return { value: groupSynopses.join(" "), error, reused: false };
-    }
-}
-// Whole-script reduce-2: collapse the episode synopses down to a set that fits
-// one final reduce, then produce the top-level overview. Reuses a prior
-// synopsis.json when the episode synopses are unchanged (signature match). Soft
-// per-group: a failed intermediate stitch degrades to its joined beats (the rest
-// keep stitching) rather than wiping the whole overview; only a failed FINAL
-// synthesis falls the overview back to joined beats. Never blocks init; the
-// degrade reason is surfaced for diagnostics.
-async function buildScriptSynopsis(provider, script, opts) {
-    const synopsisPath = path.join(opts.dd, "synopsis.json");
-    const episodeSynopses = cleanSynopsisList(asList(script["episodes"]).map((ep) => ep["synopsis"]));
-    // Nothing to summarize → leave the placeholders empty (not a degrade).
-    if (episodeSynopses.length === 0)
-        return { degraded: false, reused: false };
-    // Signature gates reuse: include every input that changes the overview —
-    // the episode synopses AND the title (it is injected into the reduce prompt)
-    // AND the reduce shape (threshold/groupSize). Otherwise a rename or a
-    // different threshold would silently reuse a stale overview. sortDeep keeps
-    // the digest stable under any future key reordering (repo cache-key convention).
-    const signature = sha256Text(JSON.stringify(sortDeep({
-        title: strOf(script["title"]),
-        thresholdChars: opts.thresholdChars,
-        groupSize: opts.groupSize,
-        episodes: episodeSynopses,
-    })));
-    // Reuse: a prior synopsis.json with a matching signature and no --resummarize.
-    // This runs before the --skip-summary check ON PURPOSE: --skip-summary means
-    // "don't spend LLM on summaries", not "discard a summary we already have".
-    if (!opts.resummarize && exists(synopsisPath)) {
-        try {
-            const prior = readJson(synopsisPath);
-            if (isDict(prior) && strOf(prior["source_episode_signature"]) === signature) {
-                applyScriptSynopsisFields(script, prior);
-                return { degraded: false, reused: true };
-            }
-        }
-        catch {
-            // fall through to recompute
-        }
-    }
-    // --skip-summary: no reusable overview above → skip all reduce LLM and leave
-    // the top-level overview empty (the placeholders from the merge stage stand).
-    if (opts.skipSummary)
-        return { degraded: false, reused: false };
-    let degraded = false;
-    let reason = "";
-    const noteDegrade = (err) => {
-        degraded = true;
-        if (!reason)
-            reason = providerErrorSummary(err);
-    };
-    try {
-        // Reduce one level at a time until the surviving set fits a single final
-        // reduce. planSynopsisReduction guarantees progress (it returns fitsInOnePass
-        // whenever it can't form fewer groups than items), so `current` strictly
-        // shrinks each non-terminal pass and this terminates without a counter.
-        let current = episodeSynopses;
-        let level = 1;
-        while (true) {
-            const plan = planSynopsisReduction(current, opts.thresholdChars, opts.groupSize);
-            if (plan.fitsInOnePass)
-                break;
-            // Groups within a level are independent → stitch them concurrently. A
-            // singleton group passes through verbatim (no LLM rewrite), mirroring the
-            // reduce-1 passthrough. A group whose stitch FAILS degrades to its joined
-            // beats (soft, per-group) — one bad group never wipes the whole overview.
-            const currentLevel = level;
-            const outcomes = await pMapWithConcurrency(plan.groups, opts.concurrency, async (group, groupIndex) => {
-                const groupSynopses = group.map((i) => current[i]).filter((s) => s.trim());
-                return loadOrRunSynopsisGroup(provider, groupSynopses, { ...opts, title: script["title"], level: currentLevel, groupIndex });
-            });
-            const next = [];
-            for (const o of outcomes) {
-                if (!o.ok) {
-                    noteDegrade(o.error);
-                    continue;
-                } // unexpected worker throw (worker already soft-handles reduce)
-                if (o.value.error)
-                    noteDegrade(o.value.error);
-                if (o.value.value.trim())
-                    next.push(o.value.value);
-            }
-            current = next;
-            level += 1;
-            if (current.length === 0)
-                break;
-        }
-        // Final synthesis. On failure, fall the overview synopsis back to the joined
-        // surviving beats rather than wiping everything (theme/logline/etc. stay empty).
-        let fields = {};
-        if (provider.extractScriptSynopsis) {
-            try {
-                const out = await provider.extractScriptSynopsis(current, { title: script["title"] });
-                if (isDict(out))
-                    fields = out;
-            }
-            catch (err) {
-                noteDegrade(err);
-            }
-        }
-        const overview = {
-            ...normalizeOverviewFields(fields),
-            source_episode_signature: signature,
-        };
-        if (!strOf(overview["synopsis"]))
-            overview["synopsis"] = current.join(" "); // fall back to joined beats
-        if (!strOf(overview["synopsis"])) {
-            degraded = true;
-            if (!reason)
-                reason = "empty reduce output";
-        }
-        assignOverviewFields(script, overview); // overview is already normalized — assign directly (no re-normalize)
-        writeJson(synopsisPath, overview);
-        return { degraded, reused: false, reason: reason || undefined };
-    }
-    catch (err) {
-        // Last-resort soft-degrade (e.g. writeJson failure): never block init.
-        noteDegrade(err);
-        return { degraded: true, reused: false, reason: reason || undefined };
-    }
-}
-// ---------------------------------------------------------------------------
-// command_init
-// ---------------------------------------------------------------------------
-// 转完后把集数写回项目组（首页「我的项目」卡片读的 episode_count）。沙箱里
-// SANDBOX_PROJECT_GROUP_NO/AWB_BASE_URL/access key 齐全时才生效；本地 dev 没绑定
-// 远端项目组就静默跳过。全程 best-effort——没配置、网络或鉴权失败都不影响 init 结果。
-async function syncProjectGroupEpisodeCount(episodeCount) {
-    let client;
-    try {
-        client = remoteScriptOutputStoreFromEnv();
-    }
-    catch {
-        return; // 未绑定远端项目组（非沙箱）→ 不写
-    }
-    await syncEpisodeCount(client, episodeCount);
-}
-export async function commandInit(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    try {
-        return await commandInitImpl(opts);
-    }
-    catch (exc) {
-        emitFailedInitProgress(workspace);
-        throw exc;
-    }
-    finally {
-        finishInitProgress();
-    }
-}
-// Parse `direct init` / `direct run` options into the typed DirectRunOptions the
-// stage pipeline consumes. Single source of truth for flag parsing + validation
-// so init and run can't drift on defaults (--concurrency / batch sizing / the
-// selection flags). Throws the same USAGE/INPUT CliErrors the god-command did.
-function parseDirectRunOptions(opts) {
-    const sourcePathArg = strOf(opts["source_path"]);
-    const source = sourcePathArg.startsWith("~")
-        ? path.join(process.env.HOME ?? "", sourcePathArg.slice(1))
-        : sourcePathArg;
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const providerName = strOf(opts["provider"] || DEFAULT_PROVIDER);
-    const model = strOf(opts["model"] || process.env.SCRIPTCTL_ANTHROPIC_MODEL || DEFAULT_MODEL);
-    // Explicit selection: the agent decides what to (re)run. Default is "resume"
-    // — only batches never attempted run. --episodes / --batches force-rerun the
-    // named units, --retry-errors force-reruns everything currently errored, --all
-    // reruns everything. Forced units have their stale result/error deleted first.
-    const selEpisodes = new Set(parseIntList(opts["episodes"]));
-    const selBatches = new Set(parseStrList(opts["batches"]));
-    const retryErrors = Boolean(opts["retry_errors"]);
-    const runAll = Boolean(opts["all"]);
-    // Synopsis stage controls. --skip-summary skips all summary LLM (episode
-    // synopses degrade to joined beats, top-level overview stays empty);
-    // --resummarize forces the summary LLM to re-run even when structure is
-    // reused (e.g. after a prompt change).
-    const skipSummary = Boolean(opts["skip_summary"]);
-    const skipMetadata = Boolean(opts["skip_metadata"]);
-    const resummarize = Boolean(opts["resummarize"]);
-    const summaryThresholdChars = parsePositiveIntOption(opts["summary_threshold_chars"], "--summary-threshold-chars", "USAGE ERROR: Invalid summary threshold", DEFAULT_SUMMARY_REDUCE_THRESHOLD_CHARS);
-    const concurrency = parsePositiveIntOption(opts["concurrency"], "--concurrency", "USAGE ERROR: Invalid concurrency", DEFAULT_DIRECT_CONCURRENCY);
-    const batchMode = strOf(opts["batch_mode"] || DEFAULT_BATCH_MODE).trim();
-    if (batchMode !== "episode") {
-        throw new CliError("USAGE ERROR: Invalid batch mode", "Invalid batch mode.", {
-            exitCode: EXIT_USAGE,
-            required: ["--batch-mode: episode"],
-            received: [`--batch-mode: ${batchMode}`],
-            nextSteps: ["Use --batch-mode episode and rerun init."],
-        });
-    }
-    const batchValues = {};
-    for (const [optName, defaultValue] of [
-        ["batch_target_lines", DEFAULT_BATCH_TARGET_LINES],
-        ["batch_max_chars", DEFAULT_BATCH_MAX_CHARS],
-        ["batch_min_lines", DEFAULT_BATCH_MIN_LINES],
-    ]) {
-        batchValues[optName] = parsePositiveIntOption(opts[optName], `--${optName.replace(/_/g, "-")}`, "USAGE ERROR: Invalid batch option", defaultValue);
-    }
-    const batchTargetLines = batchValues["batch_target_lines"];
-    const batchMaxChars = batchValues["batch_max_chars"];
-    const batchMinLines = Math.min(batchValues["batch_min_lines"], batchTargetLines);
-    return {
-        source,
-        workspace,
-        providerName,
-        model,
-        concurrency,
-        batchMode,
-        batchTargetLines,
-        batchMaxChars,
-        batchMinLines,
-        selEpisodes,
-        selBatches,
-        retryErrors,
-        runAll,
-        skipSummary,
-        skipMetadata,
-        resummarize,
-        summaryThresholdChars,
-    };
-}
-// Build the per-stage progress emitter + run_state updater + lazy provider that
-// every stage shares. Extracted so commandInit and commandRun assemble an
-// identical StageContext (same progress rendering, same run_state side effects).
-function buildStageContext(options) {
-    const ws = new Workspace(options.workspace);
-    let provider = null;
-    const timing = new JsonTimingRecorder(ws, options.workspace);
-    const ctx = {
-        ws,
-        options,
-        state: emptyRunState(),
-        timing,
-        provider() {
-            if (provider)
-                return provider;
-            try {
-                provider = makeProvider(options.providerName, options.model);
-            }
-            catch (exc) {
-                if (exc instanceof CliError) {
-                    updateRunState(options.workspace, {
-                        status: "init_failed",
-                        init_stage: "episode_titles",
-                        last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
-                    });
-                }
-                throw exc;
-            }
-            return provider;
-        },
-        emitProgress(stage, status = "running") {
-            emitInitProgress(options.workspace, stageRunStateName(stage), status);
-        },
-        updateRunState(updates) {
-            updateRunState(options.workspace, updates);
-        },
-    };
-    return ctx;
-}
-// Validate --source-path (existence + supported extension) before any stage
-// runs. Kept as the init-only entry guard the god-command performed up front.
-function assertInitSource(source) {
-    if (!exists(source) || !fs.statSync(source).isFile()) {
-        throw new CliError("INIT BLOCKED: Source file not found", "Source file not found.", {
-            exitCode: EXIT_INPUT,
-            required: [`--source-path: existing ${SUPPORTED_EXTS} file`],
-            received: [`--source-path: ${source}`],
-            nextSteps: ["Use an existing file path and rerun init."],
-        });
-    }
-    const ext = path.extname(source).toLowerCase();
-    const supportedExts = new Set([".txt", ".md", ".docx", ".xlsx", ".pdf", ".json"]);
-    if (!supportedExts.has(ext)) {
-        throw new CliError("INIT BLOCKED: Unsupported source format", "Unsupported source format.", {
-            exitCode: EXIT_USAGE,
-            required: [`--source-path: ${SUPPORTED_EXTS}`],
-            received: [`--source-path: ${path.basename(source)}`],
-            nextSteps: ["Use a supported source file and rerun init."],
-        });
-    }
-}
-// Build the final INIT report from the completed run state. Reads the same
-// artifacts/state the god-command's trailing block read, so the report lines,
-// artifacts list and exit code are byte-identical.
-function buildInitReport(ctx) {
-    const { ws, options, state } = ctx;
-    const dd = ws.dir;
-    const validation = state.validation ?? {};
-    const passed = Boolean(validation["passed"]);
-    const title = passed
-        ? "INIT COMPLETE: Initial script ready"
-        : "INIT NEEDS AGENT: Initial script written with repair issues";
-    const stats = validation["stats"] ?? {};
-    const summaryDegraded = state.summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
-    const summaryLine = formatSummaryStatusLine(options.skipSummary, summaryDegraded, state.summaryDegradedEpisodes);
-    const normalization = isDict(state.assetNormalization) ? state.assetNormalization : null;
-    const normSummary = normalization && isDict(normalization["summary"]) ? normalization["summary"] : {};
-    const merges = Number(normSummary["asset_merges"] ?? 0);
-    const statesFromNames = Number(normSummary["location_states_from_names"] ?? 0);
-    const statesFromTime = Number(normSummary["location_states_from_time"] ?? 0);
-    const reviewItems = Number(normSummary["review_items"] ?? 0);
-    const norm = merges || statesFromNames || statesFromTime || reviewItems;
-    const report = {
-        title,
-        result: [
-            `${stats["episodes"] ?? 0} episodes / ${stats["scenes"] ?? 0} scenes / ${stats["actions"] ?? 0} actions; validation ${passed ? "passed" : "needs repair"}`,
-            `provider ${options.providerName}; ${state.mergedResults.length}/${state.totalEpisodes} episodes, ${state.doneBatches}/${state.totalBatches} batches`,
-            // Deviation-only lines: omit when at default/clean state.
-            ...(norm ? [`normalization: merges=${merges}, states=${statesFromNames + statesFromTime}, review=${reviewItems}`] : []),
-            ...(options.skipMetadata ? ["metadata: skipped"] : []),
-            ...(state.titleDegraded.length > 0 ? [`titles degraded (deterministic): ${state.titleDegraded.join(", ")}`] : []),
-            ...(summaryLine ? [summaryLine] : []),
-        ],
-        // The produced script is the handle for `direct review` / validate / export;
-        // validation.json only matters when there are issues to inspect.
-        artifacts: passed
-            ? [path.join(dd, "script.initial.json")]
-            : [path.join(dd, "script.initial.json"), path.join(dd, "validation.json")],
-        issues: summarizeIssues(asList(validation["issues"])),
-        // init is the entrypoint of a multi-command pipeline, so the next handoff is
-        // genuinely non-obvious — keep it concise.
-        next: options.providerName === "mock"
-            ? ["Run `direct review`, then validate/export.", "Do not export mock-provider results for delivery."]
-            : ["Run `direct review`, then validate/export."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-// Build the INIT INCOMPLETE report (some episode still has unextracted batches).
-// Mirrors the god-command's early-return block; EXIT_RUNTIME signals automation.
-function buildIncompleteReport(ctx) {
-    const { ws, options, state } = ctx;
-    const dd = ws.dir;
-    const report = {
-        title: "INIT INCOMPLETE: Some episodes have unextracted batches",
-        result: [
-            `episodes: ${state.mergedResults.length}/${state.totalEpisodes} complete`,
-            `incomplete episodes: ${state.incompleteEpisodes.join(", ")}`,
-            `content: ${state.doneBatches}/${state.totalBatches} done, ${state.erroredBatches} error`,
-            ...(state.titleDegraded.length > 0 ? [`titles degraded (deterministic): ${state.titleDegraded.join(", ")}`] : []),
-            `provider: ${options.providerName}`,
-        ],
-        artifacts: [
-            ws.rootPathOf("source.txt"),
-            path.join(dd, "episode_plan.json"),
-            path.join(dd, "batch_plan.json"),
-            path.join(dd, "batch_results"),
-            path.join(dd, "episode_results"),
-            path.join(dd, "run_state.json"),
-        ],
-        next: [
-            "Run `direct status` to see episode progress.",
-            "Re-run one episode with `direct init --episodes <n>`, or all errors with `--retry-errors`.",
-            "Errored units are left untouched on a plain rerun; select them to retry.",
-        ],
-    };
-    return [report, EXIT_RUNTIME];
-}
-function initPreFanoutStages() {
-    const end = STAGES.findIndex((stage) => stage.name === "state-curation");
-    return STAGES.slice(0, end + 1);
-}
-function validateOnlyStages() {
-    return STAGES.filter((stage) => stage.name === "validate");
-}
-function updatePostCurationBranch(ctx, name, status) {
-    const current = readRunState(ctx.options.workspace);
-    const rawBranches = current["post_curation_branches"];
-    const branches = isDict(rawBranches) ? { ...rawBranches } : {};
-    branches[name] = { status, updated_at: checkpointTimestamp() };
-    ctx.updateRunState({ post_curation_branches: branches });
-}
-async function runPostCurationBranch(ctx, name, run) {
-    updatePostCurationBranch(ctx, name, "running");
-    try {
-        const value = await ctx.timing.span({ name, category: "branch", parent: "post_curation" }, run);
-        updatePostCurationBranch(ctx, name, "success");
-        return value;
-    }
-    catch (error) {
-        updatePostCurationBranch(ctx, name, "error");
-        throw error;
-    }
-}
-async function runPostCurationFanout(ctx) {
-    const { ws, state, options } = ctx;
-    const baseScript = ensureScript(ctx);
-    ctx.updateRunState({
-        status: "init_running",
-        init_stage: "state_binding",
-        post_curation_parallel: true,
-        post_curation_branches: {
-            state_binding: { status: "running", updated_at: checkpointTimestamp() },
-            metadata_extract: { status: options.skipMetadata ? "skipped" : "running", updated_at: checkpointTimestamp() },
-            script_synopsis: { status: options.skipSummary ? "skipped" : "running", updated_at: checkpointTimestamp() },
-        },
-    });
-    ctx.emitProgress("state-binding");
-    ctx.emitProgress("metadata", options.skipMetadata ? "skipped" : "running");
-    ctx.emitProgress("script-synopsis", options.skipSummary ? "skipped" : "running");
-    const stateBindingPromise = runPostCurationBranch(ctx, "state_binding", async () => {
-        const script = cloneDict(baseScript);
-        const result = await runStateBindingForScript(ctx, script, false);
-        return { ...result, script };
-    });
-    const metadataPromise = runPostCurationBranch(ctx, "metadata_extract", async () => {
-        const script = cloneDict(baseScript);
-        return runMetadataForScript(ctx, script, false, false);
-    });
-    const synopsisPromise = runPostCurationBranch(ctx, "script_synopsis", async () => {
-        const script = cloneDict(baseScript);
-        return runScriptSynopsisForScript(ctx, script, false);
-    });
-    const settled = await Promise.allSettled([stateBindingPromise, metadataPromise, synopsisPromise]);
-    const failed = settled.find((item) => item.status === "rejected");
-    if (failed && failed.status === "rejected")
-        throw failed.reason;
-    const stateBinding = await stateBindingPromise;
-    const metadata = await metadataPromise;
-    const synopsis = await synopsisPromise;
-    await ctx.timing.span({ name: "post_curation.merge", category: "substage", parent: "post_curation" }, () => {
-        const finalScript = stateBinding.script;
-        if (!metadata.skipped)
-            applyMetadataToScript(finalScript, metadata.metadata);
-        applyScriptSynopsisFields(finalScript, synopsis.fields);
-        ws.writeJson("script.initial.json", finalScript);
-        state.script = finalScript;
-        state.summaryFullDegraded = synopsis.degraded;
-        state.summaryDegradeReason = synopsis.reason;
-    });
-    state.summaryDegradedEpisodes.sort((a, b) => a - b);
-    const summaryDegraded = state.summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
-    ctx.updateRunState({
-        post_curation_parallel: false,
-        summary_skipped: options.skipSummary,
-        summary_degraded: summaryDegraded,
-        summary_degraded_episodes: state.summaryDegradedEpisodes,
-        summary_degraded_reason: state.summaryDegradeReason || null,
-        metadata_skipped: options.skipMetadata,
-    });
-    ctx.emitProgress("state-binding", "success");
-    ctx.emitProgress("metadata", metadata.skipped ? "skipped" : "success");
-    ctx.emitProgress("script-synopsis", summaryDegraded ? "warning" : options.skipSummary ? "skipped" : "success");
-}
-async function commandInitImpl(opts) {
-    const options = parseDirectRunOptions(opts);
-    assertInitSource(options.source);
-    const ctx = buildStageContext(options);
-    ctx.ws.ensure();
-    ctx.timing.reset("direct init");
-    // Seed run_state with the init header before the first stage runs (provider /
-    // model / source_path / metadata flag) — the god-command set these up front.
-    updateRunState(options.workspace, {
-        status: "init_running",
-        command: "direct init",
-        init_stage: "source_prepare",
-        provider: options.providerName,
-        model: options.model,
-        concurrency: options.concurrency,
-        source_path: path.resolve(options.source),
-        metadata_skipped: options.skipMetadata,
-    });
-    try {
-        await runStages(ctx, initPreFanoutStages(), { force: true, persistScriptAfterStages: false });
-        await ctx.timing.span({ name: "post_curation", category: "stage" }, () => runPostCurationFanout(ctx));
-        await runStages(ctx, validateOnlyStages(), { force: true, persistScriptAfterStages: false });
-    }
-    catch (exc) {
-        // The resumable "incomplete" stop is not a failure — surface the INCOMPLETE
-        // report + EXIT_RUNTIME, exactly as the god-command's early return did.
-        if (exc instanceof StageIncomplete)
-            return buildIncompleteReport(ctx);
-        throw exc;
-    }
-    // Pipeline complete: finalize run_state (the trailing god-command block).
-    const validation = ctx.state.validation ?? {};
-    const passed = Boolean(validation["passed"]);
-    const status = passed ? "ready_for_agent" : "needs_agent_repair";
-    const summaryDegraded = ctx.state.summaryFullDegraded || ctx.state.summaryDegradedEpisodes.length > 0;
-    updateRunState(options.workspace, {
-        status,
-        command: "direct init",
-        init_stage: "complete",
-        provider: options.providerName,
-        model: options.model,
-        concurrency: options.concurrency,
-        batch_mode: options.batchMode,
-        batch_target_lines: options.batchTargetLines,
-        batch_max_chars: options.batchMaxChars,
-        batch_min_lines: options.batchMinLines,
-        source_path: path.resolve(options.source),
-        script_path: ctx.ws.pathOf("script.initial.json"),
-        validation_path: ctx.ws.pathOf("validation.json"),
-        episode_total: ctx.state.totalEpisodes,
-        episode_completed: ctx.state.mergedResults.length,
-        incomplete_episodes: [],
-        batch_total: ctx.state.totalBatches,
-        batch_completed: ctx.state.doneBatches,
-        batch_reused: ctx.state.reusedBatchCount,
-        batch_failed: ctx.state.erroredBatches,
-        summary_threshold_chars: options.summaryThresholdChars,
-        summary_skipped: options.skipSummary,
-        summary_degraded: summaryDegraded,
-        summary_degraded_episodes: ctx.state.summaryDegradedEpisodes,
-        summary_degraded_reason: ctx.state.summaryDegradeReason || null,
-        metadata_skipped: options.skipMetadata,
-        last_error: null,
-    });
-    // 转完（或重跑后集数变了）→ 回填项目组集数。只在完整完成路径写；INCOMPLETE
-    // 早返回不写。best-effort，写同样的集数也无妨（重跑覆盖即更新）。
-    await syncProjectGroupEpisodeCount(ctx.state.totalEpisodes);
-    return buildInitReport(ctx);
-}
-// ---------------------------------------------------------------------------
-// command_run — single-stage runner against an existing workspace. Lets the
-// agent re-run one step (e.g. `direct run metadata`, `direct run episode-synopsis`)
-// without re-driving the whole pipeline. The stage rehydrates the prior
-// artifacts it needs from disk, so it stands alone.
-// ---------------------------------------------------------------------------
-export async function commandRun(opts) {
-    const stageName = strOf(asList(opts["_args"])[0] || opts["stage"]).trim();
-    if (!stageName) {
-        throw new CliError("DIRECT RUN BLOCKED: missing stage", "No stage name given.", {
-            exitCode: EXIT_USAGE,
-            required: [`one of: ${STAGES.map((s) => s.name).join(", ")}`],
-            received: ["<no stage>"],
-            nextSteps: ["Pass a stage name, e.g. `direct run metadata`."],
-        });
-    }
-    // Reject an unknown stage up front (both code paths below would otherwise
-    // silently no-op the `only`-filtered runStages on a typo).
-    if (!STAGES.some((s) => s.name === stageName)) {
-        throw new CliError("DIRECT RUN BLOCKED: unknown stage", `Unknown stage "${stageName}".`, {
-            exitCode: EXIT_USAGE,
-            required: [`one of: ${STAGES.map((s) => s.name).join(", ")}`],
-            received: [stageName],
-            nextSteps: ["Pass a valid stage name to `direct run`."],
-        });
-    }
-    const options = parseDirectRunOptions(opts);
-    const ctx = buildStageContext(options);
-    ctx.ws.ensure();
-    ctx.timing.reset(`direct run ${stageName}`);
-    const force = Boolean(opts["force"]);
-    try {
-        if (force) {
-            // --force re-runs even when the output artifact is already present.
-            await runOne(ctx, stageName);
-        }
-        else {
-            // Without --force, honor skip-on-present so `direct run <stage>` is a no-op
-            // when the stage's output already exists (mirrors runStages' resume).
-            await runStages(ctx, STAGES, { only: new Set([stageName]) });
-        }
-    }
-    catch (exc) {
-        if (exc instanceof StageIncomplete) {
-            finishInitProgress();
-            return buildIncompleteReport(ctx);
-        }
-        emitFailedInitProgress(options.workspace);
-        finishInitProgress();
-        throw exc;
-    }
-    finishInitProgress();
-    const report = {
-        title: `DIRECT RUN: ${stageName}`,
-        result: [
-            `stage: ${stageName}`,
-            `workspace: ${options.workspace}`,
-            "ran one stage; run `direct status` for the full picture.",
-        ],
-        artifacts: [ctx.ws.pathOf("run_state.json")],
-        next: ["Run `direct status` to see updated progress, or `direct run <stage>` for another step."],
-    };
-    return [report, EXIT_OK];
-}
-// ===========================================================================
-// Per-stage implementations. Each function below is ONE segment of the former
-// commandInitImpl, lifted verbatim onto a StageContext so it can run either as
-// part of the full pipeline (runStages) or on its own (`direct run <stage>`).
-// They call the SAME helpers/pure functions the god-command used — no algorithm
-// is duplicated; only the cross-stage locals moved onto ctx.state. The thin
-// Stage wrappers in src/domain/direct/stages/*.ts just name + order these.
-// ===========================================================================
-// A stage that needs a prior artifact missing from ctx.state (because the run
-// started at a later stage via `direct run`) lazily rehydrates it from disk.
-function ensureEpisodePlan(ctx) {
-    if (ctx.state.episodePlan)
-        return ctx.state.episodePlan;
-    const plan = ctx.ws.readJsonSafe("episode_plan.json");
-    if (!plan) {
-        throw new CliError("DIRECT RUN BLOCKED: episode_plan.json missing", "episode_plan.json missing.", {
-            exitCode: EXIT_INPUT,
-            required: ["episode_plan.json (run the episode-plan stage first)"],
-            received: ["episode_plan.json missing"],
-            nextSteps: ["Run `direct init` or `direct run episode-plan` first."],
-        });
-    }
-    ctx.state.episodePlan = plan;
-    return plan;
-}
-function ensureBatchPlan(ctx) {
-    if (ctx.state.batchPlan)
-        return ctx.state.batchPlan;
-    const plan = ctx.ws.readJsonSafe("batch_plan.json");
-    if (!plan) {
-        throw new CliError("DIRECT RUN BLOCKED: batch_plan.json missing", "batch_plan.json missing.", {
-            exitCode: EXIT_INPUT,
-            required: ["batch_plan.json (run the batch-plan stage first)"],
-            received: ["batch_plan.json missing"],
-            nextSteps: ["Run `direct init` or `direct run batch-plan` first."],
-        });
-    }
-    ctx.state.batchPlan = plan;
-    return plan;
-}
-function ensureSourceText(ctx) {
-    if (ctx.state.sourceText)
-        return ctx.state.sourceText;
-    const p = ctx.ws.rootPathOf("source.txt");
-    if (!exists(p)) {
-        throw new CliError("DIRECT RUN BLOCKED: source.txt missing", "source.txt missing.", {
-            exitCode: EXIT_INPUT,
-            required: ["source.txt (run the source-prepare stage first)"],
-            received: ["source.txt missing"],
-            nextSteps: ["Run `direct init` or `direct run source-prepare` first."],
-        });
-    }
-    ctx.state.sourceText = readText(p);
-    return ctx.state.sourceText;
-}
-function ensureScript(ctx) {
-    if (ctx.state.script)
-        return ctx.state.script;
-    const script = ctx.ws.readJsonSafe("script.initial.json");
-    if (!script) {
-        throw new CliError("DIRECT RUN BLOCKED: script.initial.json missing", "script.initial.json missing.", {
-            exitCode: EXIT_INPUT,
-            required: ["script.initial.json (run the script-merge stage first)"],
-            received: ["script.initial.json missing"],
-            nextSteps: ["Run `direct init` or `direct run script-merge` first."],
-        });
-    }
-    ctx.state.script = script;
-    return script;
-}
-// Reassemble ctx.state.mergedResults from episode_results/ when a later stage is
-// run standalone (e.g. `direct run script-merge`). Mirrors the assembly the
-// episode-merge stage does in-memory, but reads the persisted results.
-function ensureMergedResults(ctx) {
-    if (ctx.state.mergedResults.length > 0)
-        return ctx.state.mergedResults;
-    const plan = ensureEpisodePlan(ctx);
-    const episodeResultsDir = ctx.ws.pathOf("episode_results");
-    const results = [];
-    for (const episode of asList(plan["episodes"])) {
-        const p = episodeResultPath(episodeResultsDir, episode);
-        const data = exists(p) ? readJsonFile(p, {}) : null;
-        if (data && isDict(data) && Object.keys(data).length > 0) {
-            results.push(expandCompactEpisodeResult(data, episode));
-        }
-    }
-    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
-    ctx.state.mergedResults = results;
-    return results;
-}
-// Recover the project name when a script-producing stage runs standalone (no
-// source-prepare set state.projectName, and `direct run` has no --source-path).
-// Order: in-memory → persisted manifest (source_name minus ext) → existing
-// script title → source basename. Without this, `direct run script-merge` would
-// rebuild the script with an empty title (state.projectName='' && source='').
-function ensureProjectName(ctx) {
-    if (ctx.state.projectName)
-        return ctx.state.projectName;
-    const manifest = ctx.ws.readJsonSafe("source_manifest.json");
-    const fromManifest = manifest
-        ? strOf(manifest["source_name"]).replace(/\.[^.]+$/, "")
-            || (strOf(manifest["source_path"]) ? path.basename(strOf(manifest["source_path"]), path.extname(strOf(manifest["source_path"]))) : "")
-        : "";
-    const fromScript = strOf(ctx.ws.readJsonSafe("script.initial.json")?.["title"]);
-    const fromSource = ctx.options.source ? path.basename(ctx.options.source, path.extname(ctx.options.source)) : "";
-    const name = fromManifest || fromScript || fromSource;
-    ctx.state.projectName = name;
-    return name;
-}
-// --- source-prepare -------------------------------------------------------
-export async function stageSourcePrepare(ctx) {
-    const { options, ws, state } = ctx;
-    const source = options.source;
-    ctx.updateRunState({ status: "init_running", command: "direct init", init_stage: "source_prepare" });
-    ctx.emitProgress("source-prepare");
-    let info;
-    try {
-        info = await prepareSource(source, options.workspace);
-    }
-    catch (exc) {
-        if (exc instanceof CliError) {
-            ctx.updateRunState({
-                status: "init_failed",
-                init_stage: "source_prepare",
-                last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
-            });
-            throw exc;
-        }
-        const e = exc;
-        const receivedError = `${source}: ${e?.name ?? "Error"}${e?.message ? `: ${e.message}` : ""}`;
-        ctx.updateRunState({
-            status: "init_failed",
-            init_stage: "source_prepare",
-            last_error: { title: "INIT BLOCKED: Source preparation failed", received: [receivedError], failed_at: checkpointTimestamp() },
-        });
-        throw new CliError("INIT BLOCKED: Source preparation failed", "Source preparation failed.", {
-            exitCode: EXIT_INPUT,
-            required: ["readable source file that can be converted to source.txt"],
-            received: [receivedError],
-            nextSteps: ["Fix or re-export the source file, then rerun init."],
-        });
-    }
-    const sourceTextPath = strOf(info["sourceTextPath"]);
-    state.sourceText = readText(sourceTextPath);
-    state.projectName = strOf(info["projectName"]) || path.basename(source, path.extname(source));
-    state.manifest = makeSourceManifest(source, sourceTextPath, info);
-    ws.writeJson("source_manifest.json", state.manifest);
-}
-// --- episode-plan ---------------------------------------------------------
-export async function stageEpisodePlan(ctx) {
-    const { ws, state, options } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    ctx.updateRunState({ status: "init_running", init_stage: "episode_plan" });
-    ctx.emitProgress("episode-plan");
-    let plan;
-    try {
-        plan = buildEpisodePlan(sourceText);
-    }
-    catch (exc) {
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Episode planning failed",
-            stage: "episode_plan",
-            required: ["source.txt that can be split into episodes"],
-            nextSteps: ["Inspect workspace/source.txt, fix the source file, and rerun init."],
-        });
-    }
-    state.episodePlan = plan;
-    ws.writeJson("episode_plan.json", plan);
-}
-// --- episode-titles -------------------------------------------------------
-export async function stageEpisodeTitles(ctx) {
-    const { state, options } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    const plan = ensureEpisodePlan(ctx);
-    // Provider capability gate (was inline in commandInitImpl before titles).
-    // Checked twice — declared capabilities, then the constructed provider — but
-    // both fail the same way, so share one report builder.
-    const lacksExtraction = () => initFailedReport(options.workspace, {
-        title: "INIT FAILED: provider lacks batch extraction",
-        stage: "episode_titles",
-        required: ["provider.extractBatch or provider.extractEpisode"],
-        received: [`--provider ${options.providerName}`],
-        nextSteps: ["Use --provider anthropic or --provider mock for direct init."],
-    });
-    const capabilities = providerCapabilities(options.providerName);
-    if (capabilities && !capabilities.extractBatch && !capabilities.extractEpisode) {
-        throw lacksExtraction();
-    }
-    const provider = ctx.provider();
-    if (!provider.extractBatch && !provider.extractEpisode) {
-        throw lacksExtraction();
-    }
-    ctx.updateRunState({ status: "init_running", init_stage: "episode_titles" });
-    ctx.emitProgress("episode-titles");
-    state.titleDegraded = await enrichEpisodeTitlesChunked(options.workspace, sourceText, plan, provider, options.concurrency);
-    // Titles mutate the plan in place — persist it so the artifact reflects them.
-    ctx.ws.writeJson("episode_plan.json", plan);
-}
-// --- batch-plan -----------------------------------------------------------
-export async function stageBatchPlan(ctx) {
-    const { ws, state, options } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    const plan = ensureEpisodePlan(ctx);
-    let batchPlan;
-    try {
-        batchPlan = buildBatchPlan(sourceText, plan, {
-            targetLines: options.batchTargetLines,
-            maxChars: options.batchMaxChars,
-            minLines: options.batchMinLines,
-            mode: options.batchMode,
-        });
-    }
-    catch (exc) {
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Batch planning failed",
-            stage: "batch_plan",
-            required: ["episode_plan.json that can be split into natural paragraph batches"],
-            nextSteps: ["Inspect workspace/source.txt and episode_plan.json, then rerun init."],
-        });
-    }
-    state.batchPlan = batchPlan;
-    ws.writeJson("batch_plan.json", batchPlan);
-    ctx.emitProgress("batch-plan", "success");
-}
-// --- batch-extract --------------------------------------------------------
-export async function stageBatchExtract(ctx) {
-    const { ws, state, options } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    const plan = ensureEpisodePlan(ctx);
-    const batchPlan = ensureBatchPlan(ctx);
-    const provider = ctx.provider();
-    const episodeResultsDir = ws.mkdir("episode_results");
-    const batchResultsDir = ws.mkdir("batch_results");
-    // Non-destructive GC for units the current plan no longer references.
-    gcOrphanUnits(episodeResultsDir, new Set(asList(plan["episodes"]).map((ep) => episodeResultKey(ep))));
-    gcOrphanUnits(batchResultsDir, new Set(asList(batchPlan["batches"]).map((b) => batchResultKey(b))));
-    state.totalEpisodes = asList(plan["episodes"]).length;
-    state.totalBatches = asList(batchPlan["batches"]).length;
-    // Decide which batches to run (force / reuse-done / sticky-error / pending).
-    const pending = [];
-    let reusedBatchCount = 0;
-    let stickyErrorCount = 0;
-    for (const batch of asList(batchPlan["batches"])) {
-        const epNum = Number(batch["episode"]);
-        const key = batchResultKey(batch);
-        const errorPath = batchErrorPath(batchResultsDir, batch);
-        const forced = options.runAll || options.selEpisodes.has(epNum) || options.selBatches.has(key) || (options.retryErrors && exists(errorPath));
-        if (forced) {
-            const resultPath = batchResultPath(batchResultsDir, batch);
-            if (exists(resultPath))
-                deletePath(resultPath);
-            if (exists(errorPath))
-                deletePath(errorPath);
-            pending.push(batch);
-            continue;
-        }
-        switch (classifyBatch(batchResultsDir, batch)) {
-            case "done":
-                reusedBatchCount++;
-                break;
-            case "error":
-                stickyErrorCount++;
-                break;
-            default: pending.push(batch);
-        }
-    }
-    state.pending = pending;
-    state.reusedBatchCount = reusedBatchCount;
-    state.stickyErrorCount = stickyErrorCount;
-    state.changedEpisodes = new Set(pending.map((b) => Number(b["episode"])));
-    ctx.updateRunState({
-        status: "init_running",
-        init_stage: "batch_extract",
-        batch_mode: options.batchMode,
-        batch_target_lines: options.batchTargetLines,
-        batch_max_chars: options.batchMaxChars,
-        batch_min_lines: options.batchMinLines,
-        episode_total: state.totalEpisodes,
-        batch_total: state.totalBatches,
-    });
-    ctx.emitProgress("batch-extract");
-    const outcomes = await pMapWithConcurrency(pending, options.concurrency, async (batch) => {
-        try {
-            const result = await extractBatchWithRecovery(provider, sourceText, batch);
-            persistBatchResult(batchResultsDir, batch, result);
-            const errorPath = batchErrorPath(batchResultsDir, batch);
-            if (exists(errorPath))
-                deletePath(errorPath);
-            ctx.emitProgress("batch-extract");
-            return true;
-        }
-        catch (error) {
-            writeBatchFailure(batchResultsDir, batch, error);
-            ctx.emitProgress("batch-extract");
-            return false;
-        }
-    });
-    const freshOk = outcomes.filter((o) => o.ok && o.value === true).length;
-    const freshFail = outcomes.filter((o) => o.ok && o.value === false).length;
-    state.doneBatches = reusedBatchCount + freshOk;
-    state.erroredBatches = stickyErrorCount + freshFail;
-}
-// --- episode-merge --------------------------------------------------------
-export async function stageEpisodeMerge(ctx) {
-    const { ws, state } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    const plan = ensureEpisodePlan(ctx);
-    const batchPlan = ensureBatchPlan(ctx);
-    const episodeResultsDir = ws.mkdir("episode_results");
-    const batchResultsDir = ws.mkdir("batch_results");
-    // Recompute the bookkeeping a standalone `direct run episode-merge` needs when
-    // batch-extract didn't run this invocation.
-    if (state.totalEpisodes === 0)
-        state.totalEpisodes = asList(plan["episodes"]).length;
-    if (state.totalBatches === 0)
-        state.totalBatches = asList(batchPlan["batches"]).length;
-    const batchesByEpisode = new Map();
-    for (const batch of asList(batchPlan["batches"])) {
-        const epNum = Number(batch["episode"]);
-        if (!batchesByEpisode.has(epNum))
-            batchesByEpisode.set(epNum, []);
-        batchesByEpisode.get(epNum).push(batch);
-    }
-    if (state.doneBatches === 0 && state.erroredBatches === 0) {
-        let done = 0;
-        let errored = 0;
-        for (const batch of asList(batchPlan["batches"])) {
-            const s = classifyBatch(batchResultsDir, batch);
-            if (s === "done")
-                done++;
-            else if (s === "error")
-                errored++;
-        }
-        state.doneBatches = done;
-        state.erroredBatches = errored;
-    }
-    const results = [];
-    const incompleteEpisodes = [];
-    ctx.updateRunState({
-        status: "init_running",
-        init_stage: "episode_merge",
-        episode_total: state.totalEpisodes,
-        batch_total: state.totalBatches,
-        batch_completed: state.doneBatches,
-        batch_failed: state.erroredBatches,
-    });
-    ctx.emitProgress("episode-merge");
-    try {
-        for (const episode of asList(plan["episodes"])) {
-            const episodeNum = Number(episode["episode"]);
-            const epBatches = batchesByEpisode.get(episodeNum) ?? [];
-            const batchResults = epBatches.map((b) => readBatchResult(batchResultsDir, b)).filter((r) => r !== null);
-            if (epBatches.length === 0 || batchResults.length !== epBatches.length) {
-                incompleteEpisodes.push(episodeNum);
-                const stale = episodeResultPath(episodeResultsDir, episode);
-                if (exists(stale))
-                    deletePath(stale);
-                continue;
-            }
-            const merged = mergeBatchResultsForEpisode(episode, batchResults);
-            validateEpisodeExtractionQuality(sourceText, episode, merged);
-            results.push(merged);
-        }
-    }
-    catch (exc) {
-        stageFailure(ctx.options.workspace, exc, {
-            title: "INIT FAILED: Episode merge failed",
-            stage: "episode_merge",
-            required: ["batch_results/*.json that can merge into episode_results/*.json"],
-            nextSteps: ["Rerun init; completed batches are reused and episode merge will retry."],
-        });
-    }
-    state.mergedResults = results;
-    state.incompleteEpisodes = incompleteEpisodes;
-    ctx.emitProgress("episode-merge", incompleteEpisodes.length > 0 ? "warning" : "success");
-}
-// --- episode-synopsis -----------------------------------------------------
-export async function stageEpisodeSynopsis(ctx) {
-    const { ws, state, options } = ctx;
-    const provider = ctx.provider();
-    const episodeResultsDir = ws.mkdir("episode_results");
-    const results = ensureMergedResults(ctx);
-    ctx.updateRunState({ status: "init_running", init_stage: "episode_synopsis" });
-    ctx.emitProgress("episode-synopsis");
-    state.summaryDegradedEpisodes.push(...await resolveEpisodeSynopses(provider, results, {
-        resultsDir: episodeResultsDir,
-        resummarize: options.resummarize,
-        skipSummary: options.skipSummary,
-        changedEpisodes: state.changedEpisodes,
-        concurrency: options.concurrency,
-    }));
-    for (const merged of results) {
-        writeJson(episodeResultPath(episodeResultsDir, merged), compactEpisodeResult(merged));
-        const errPath = episodeErrorPath(episodeResultsDir, merged);
-        if (exists(errPath))
-            deletePath(errPath);
-    }
-    ctx.emitProgress("episode-synopsis", state.summaryDegradedEpisodes.length > 0 ? "warning" : "success");
-    // Incomplete episodes are a resumable, non-error stop. The full-pipeline
-    // runner converts this into the INIT INCOMPLETE report + EXIT_RUNTIME; a
-    // standalone `direct run episode-synopsis` surfaces it the same way.
-    if (state.incompleteEpisodes.length > 0) {
-        state.incompleteEpisodes.sort((a, b) => a - b);
-        ctx.updateRunState({
-            status: "init_incomplete",
-            init_stage: "batch_extract",
-            episode_total: state.totalEpisodes,
-            episode_completed: state.mergedResults.length,
-            incomplete_episodes: state.incompleteEpisodes,
-            batch_total: state.totalBatches,
-            batch_completed: state.doneBatches,
-            batch_failed: state.erroredBatches,
-            last_error: { title: "INIT INCOMPLETE: Some episodes have unextracted batches", failed_at: checkpointTimestamp() },
-        });
-        ctx.emitProgress("batch-extract", "error");
-        throw new StageIncomplete();
-    }
-    state.mergedResults.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
-}
-// --- script-merge ---------------------------------------------------------
-export async function stageScriptMerge(ctx) {
-    const { ws, state, options } = ctx;
-    const results = ensureMergedResults(ctx);
-    const episodePlan = ensureEpisodePlan(ctx);
-    ctx.updateRunState({
-        status: "init_running",
-        init_stage: "script_merge",
-        episode_total: state.totalEpisodes || asList(episodePlan["episodes"]).length,
-        episode_completed: results.length,
-        incomplete_episodes: [],
-        batch_total: state.totalBatches,
-        batch_completed: state.doneBatches,
-        batch_failed: state.erroredBatches,
-        last_error: null,
-    });
-    ctx.emitProgress("script-merge");
-    try {
-        const merged = mergeEpisodeResultsWithReport(results, ensureProjectName(ctx));
-        state.script = merged.script;
-        state.assetNormalization = merged.assetNormalization;
-        ws.writeJson("asset_normalization.json", state.assetNormalization);
-    }
-    catch (exc) {
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Merge failed",
-            stage: "script_merge",
-            required: ["complete episode_results/*.json"],
-            nextSteps: ["Rerun init; completed episode extraction checkpoints will be reused and merge will retry."],
-            updates: { episode_completed: results.length },
-        });
-    }
-}
-// --- asset-curation -------------------------------------------------------
-const ASSET_GROUPING_CACHE_VERSION = 3;
-const ASSET_CURATION_CACHE_VERSION = 5;
-function assetCacheIdentity(options) {
-    return {
-        provider: options.providerName,
-        model: options.model,
-    };
-}
-function assetCacheArtifactFields(ctx, cacheVersion) {
-    return {
-        cache_version: cacheVersion,
-        ...assetCacheIdentity(ctx.options),
-    };
-}
-function assetCurationScriptFingerprint(script, options) {
-    return sha256Text(JSON.stringify(sortDeep({
-        cache_version: ASSET_CURATION_CACHE_VERSION,
-        ...assetCacheIdentity(options),
-        script: {
-            actors: script["actors"],
-            locations: script["locations"],
-            props: script["props"],
-            speakers: script["speakers"],
-            episodes: script["episodes"],
-        },
-    })));
-}
-function assetCurationPlanFingerprint(scriptFingerprint, plan) {
-    return sha256Text(JSON.stringify(sortDeep({
-        script_fingerprint: scriptFingerprint,
-        decisions: plan["decisions"],
-    })));
-}
-function chunkStrings(values, chunkSize) {
-    const chunks = [];
-    for (let index = 0; index < values.length; index += chunkSize) {
-        chunks.push(values.slice(index, index + chunkSize));
-    }
-    return chunks;
-}
-function curationSourceKey(kind, id) {
-    return `${kind}:${id}`;
-}
-function curationDecisionSourceKey(decision) {
-    return curationSourceKey(strOf(decision["kind"]), strOf(decision["source_id"]));
-}
-function curationSourceKeysForIds(kind, ids) {
-    return ids.map((id) => curationSourceKey(kind, id));
-}
-function curationPartSelection(kind, ids) {
-    if (kind === "actor")
-        return { actor: ids };
-    if (kind === "location")
-        return { location: ids };
-    return { prop: ids };
-}
-function curationIdsFromSourceKeys(kind, ids, sourceKeys) {
-    const allowed = new Set(sourceKeys);
-    return ids.filter((id) => allowed.has(curationSourceKey(kind, id)));
-}
-function invalidCurationPart(title, received) {
-    return new CliError(title, title, {
-        exitCode: EXIT_RUNTIME,
-        required: ["repairable asset curation expressions"],
-        received,
-        nextSteps: ["Rerun init; completed extraction checkpoints will be reused and only invalid curation parts will retry."],
-    });
-}
-const MAX_CURATION_PART_REPAIR_ATTEMPTS = 2;
-function assetGroupingKindListKey(kind) {
-    if (kind === "actor")
-        return "actors";
-    if (kind === "location")
-        return "locations";
-    return "props";
-}
-function assetGroupingKindIdKey(kind) {
-    if (kind === "actor")
-        return "actor_id";
-    if (kind === "location")
-        return "location_id";
-    return "prop_id";
-}
-function assetGroupingKindNameKey(kind) {
-    if (kind === "actor")
-        return "actor_name";
-    if (kind === "location")
-        return "location_name";
-    return "prop_name";
-}
-function assetGroupingScriptFingerprint(script, options) {
-    const compact = {};
-    for (const kind of ["actor", "location", "prop"]) {
-        const idKey = assetGroupingKindIdKey(kind);
-        const nameKey = assetGroupingKindNameKey(kind);
-        compact[assetGroupingKindListKey(kind)] = asList(script[assetGroupingKindListKey(kind)])
-            .filter(isDict)
-            .map((asset) => ({ id: strOf(asset[idKey]), name: strOf(asset[nameKey]) }));
-    }
-    return sha256Text(JSON.stringify(sortDeep({
-        cache_version: ASSET_GROUPING_CACHE_VERSION,
-        ...assetCacheIdentity(options),
-        assets: compact,
-    })));
-}
-function combineAssetGroupingPlans(parts) {
-    const groups = parts.flatMap((part) => asList(part["groups"]).filter(isDict));
-    const duplicateMergeDecisions = parts.flatMap((part) => asList(part["duplicate_merge_decisions"]).filter(isDict));
-    const normalizations = parts.flatMap((part) => asList(part["normalizations"]).filter(isDict));
-    const summaries = parts.map((part) => part["summary"]).filter(isDict);
-    return {
-        version: 1,
-        format: "asset-grouping-v1",
-        groups,
-        duplicate_merge_decisions: duplicateMergeDecisions,
-        normalizations,
-        parts: parts.map((part) => ({
-            kind: part["kind"],
-            expression_text: part["expression_text"],
-            summary: part["summary"],
-            normalizations: part["normalizations"],
-        })),
-        summary: {
-            group_count: groups.length,
-            duplicate_merge_count: duplicateMergeDecisions.length,
-            normalization_count: normalizations.length,
-            parts: summaries,
-        },
-    };
-}
-async function loadOrRunAssetGroupingPart(ctx, script, groupAssets, kind, fingerprint) {
-    const artifactName = `asset_grouping_parts/${kind}.json`;
-    const cached = ctx.ws.readJsonSafe(artifactName);
-    const cachedPlan = !ctx.state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === fingerprint && cached["parse_status"] === "ok" && isDict(cached["plan"]) ? cached["plan"] : null;
-    if (cachedPlan && isList(cachedPlan["groups"]))
-        return cachedPlan;
-    const startedAtMs = Date.now();
-    const idKey = assetGroupingKindIdKey(kind);
-    const assetCount = asList(script[assetGroupingKindListKey(kind)])
-        .filter(isDict)
-        .map((asset) => strOf(asset[idKey]).trim())
-        .filter((id) => id).length;
-    if (assetCount === 0) {
-        const plan = {
-            version: 1,
-            format: "asset-grouping-v1",
-            kind,
-            expression_text: "",
-            expressions: [],
-            groups: [],
-            duplicate_merge_decisions: [],
-            summary: { input_count: 0, group_count: 0, mentioned_count: 0, omitted_duplicate_count: 0 },
-        };
-        ctx.ws.writeJson(artifactName, {
-            version: 1,
-            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
-            script_fingerprint: fingerprint,
-            parse_status: "ok",
-            kind,
-            context_chars: 0,
-            expression_text: "",
-            duration_ms: durationMs(startedAtMs, Date.now()),
-            plan,
-            updated_at: checkpointTimestamp(),
-        });
-        return plan;
-    }
-    const contextText = buildAssetGroupingContextText(script, kind);
-    let rawText = "";
-    try {
-        rawText = await ctx.timing.span({ name: `asset_grouping.${kind}`, category: "chunk", parent: "asset_curation.grouping", metadata: { artifact: artifactName } }, () => groupAssets(script, contextText));
-        const parsed = parseAssetGroupingExpressions(rawText);
-        const plan = validateAssetGroupingPlan(script, kind, parsed);
-        ctx.ws.writeJson(artifactName, {
-            version: 1,
-            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
-            script_fingerprint: fingerprint,
-            parse_status: "ok",
-            kind,
-            context_chars: contextText.length,
-            expression_text: rawText,
-            duration_ms: durationMs(startedAtMs, Date.now()),
-            plan,
-            updated_at: checkpointTimestamp(),
-        });
-        return plan;
-    }
-    catch (exc) {
-        const e = exc;
-        ctx.ws.writeJson(artifactName, {
-            version: 1,
-            ...assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION),
-            script_fingerprint: fingerprint,
-            parse_status: "failed",
-            kind,
-            context_chars: contextText.length,
-            expression_text: rawText,
-            duration_ms: durationMs(startedAtMs, Date.now()),
-            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-            updated_at: checkpointTimestamp(),
-        });
-        throw exc;
-    }
-}
-async function loadOrRunAssetGrouping(ctx, script, groupAssets, fingerprint) {
-    ctx.ws.mkdir("asset_grouping_parts");
-    const outcomes = await pMapWithConcurrency(["actor", "location", "prop"], ctx.options.concurrency, async (kind) => loadOrRunAssetGroupingPart(ctx, script, groupAssets, kind, fingerprint));
-    return combineAssetGroupingPlans(unwrapConcurrentOutcomes(outcomes));
-}
-function curationDecisionSourceKeys(plan) {
-    return new Set(asList(plan["decisions"]).filter(isDict).map((decision) => curationDecisionSourceKey(decision)));
-}
-function sourceKeysFromRejectedExpressions(rejected, candidateSourceKeys) {
-    const candidateSet = new Set(candidateSourceKeys);
-    const keys = [];
-    for (const item of rejected) {
-        const key = strOf(item["source_key"]);
-        if (key && (candidateSet.size === 0 || candidateSet.has(key)))
-            uniqueAdd(keys, key);
-    }
-    return keys;
-}
-function scopedCurationPlan(plan, allowedSourceKeys) {
-    const allowed = new Set(allowedSourceKeys);
-    const decisions = asList(plan["decisions"]).filter(isDict);
-    const acceptedExpressions = asList(plan["accepted_expressions"]);
-    const scopedDecisions = [];
-    const scopedExpressions = [];
-    const ignored = [];
-    for (let index = 0; index < decisions.length; index += 1) {
-        const decision = decisions[index];
-        const sourceKey = curationDecisionSourceKey(decision);
-        const expression = acceptedExpressions[index] ?? "";
-        if (allowed.has(sourceKey)) {
-            scopedDecisions.push(decision);
-            if (expression)
-                scopedExpressions.push(expression);
-        }
-        else {
-            ignored.push({ source_key: sourceKey, expression, reason: "outside_repair_scope" });
-        }
-    }
-    return {
-        plan: {
-            ...plan,
-            expression_text: formatCurationExpressionText(scopedExpressions),
-            expressions: scopedExpressions.length > 0 ? scopedExpressions : ["NOOP # no asset curation changes"],
-            accepted_expressions: scopedExpressions,
-            decisions: scopedDecisions,
-        },
-        ignored,
-    };
-}
-function missingRequiredSourceKeysForPart(script, candidateSourceKeys, partialPlan) {
-    const candidateSet = new Set(candidateSourceKeys);
-    return missingAssetCurationRequiredSourceKeys(script, partialPlan).filter((key) => candidateSet.has(key));
-}
-function repairSourceKeysForPart(script, candidateSourceKeys, partialPlan, requireCoverage) {
-    const candidateSet = new Set(candidateSourceKeys);
-    const accepted = new Set(asList(partialPlan["decisions"]).filter(isDict).map((decision) => curationDecisionSourceKey(decision)));
-    const rejected = asList(partialPlan["rejected_expressions"]).filter(isDict);
-    const repairKeys = [];
-    let hasUnlocatedRejection = false;
-    for (const item of rejected) {
-        const key = strOf(item["source_key"]);
-        if (key && (candidateSet.size === 0 || candidateSet.has(key)))
-            uniqueAdd(repairKeys, key);
-        else
-            hasUnlocatedRejection = true;
-    }
-    if (hasUnlocatedRejection) {
-        for (const key of candidateSourceKeys) {
-            if (!accepted.has(key))
-                uniqueAdd(repairKeys, key);
-        }
-    }
-    if (requireCoverage) {
-        for (const key of missingRequiredSourceKeysForPart(script, candidateSourceKeys, partialPlan)) {
-            uniqueAdd(repairKeys, key);
-        }
-    }
-    return repairKeys;
-}
-function mergeRepairedCurationPlan(rawText, partialPlan, repairPlan, repairAttempts) {
-    const acceptedExpressions = asList(partialPlan["accepted_expressions"]);
-    const repairExpressions = asList(repairPlan["accepted_expressions"]);
-    const decisions = [
-        ...asList(partialPlan["decisions"]).filter(isDict),
-        ...asList(repairPlan["decisions"]).filter(isDict),
-    ];
-    const expressions = [...acceptedExpressions, ...repairExpressions].filter((expression) => !/^NOOP(?:\s|#|$)/i.test(expression.trim()));
-    return {
-        version: 3,
-        format: "asset-curation-exp-v1",
-        expression_text: formatCurationExpressionText(expressions),
-        raw_expression_text: rawText,
-        accepted_expressions: [...acceptedExpressions, ...repairExpressions],
-        rejected_expressions: asList(partialPlan["rejected_expressions"]).filter(isDict),
-        repair_attempts: repairAttempts,
-        expressions: expressions.length > 0 ? expressions : ["NOOP # no asset curation changes"],
-        decisions,
-        partial: false,
-    };
-}
-function formatCurationExpressionText(expressions) {
-    if (expressions.length > 0)
-        return expressions.map((expression) => `<exp>${expression}</exp>`).join("\n");
-    return "<exp>NOOP # no asset curation changes</exp>";
-}
-function writeFailedCurationPartArtifact(opts) {
-    const e = opts.error;
-    opts.ctx.ws.writeJson(opts.artifactName, {
-        version: 1,
-        ...assetCacheArtifactFields(opts.ctx, ASSET_CURATION_CACHE_VERSION),
-        script_fingerprint: opts.fingerprint,
-        ...opts.metadata,
-        parse_status: "failed",
-        candidate_source_keys: opts.candidateSourceKeys,
-        expression_text: opts.partPlan?.["expression_text"] ?? null,
-        raw_expression_text: opts.partPlan?.["raw_expression_text"] ?? opts.expressionText,
-        accepted_expressions: opts.partPlan?.["accepted_expressions"] ?? [],
-        rejected_expressions: opts.partPlan?.["rejected_expressions"] ?? [],
-        repair_attempts: opts.repairAttempts,
-        duration_ms: durationMs(opts.startedAtMs, Date.now()),
-        error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-        plan: opts.partPlan,
-        updated_at: checkpointTimestamp(),
-    });
-}
-async function loadOrRunCurationPart(ctx, script, artifactName, fingerprint, metadata, candidateSourceKeys, parentTiming, requireCoverage, contextText, run) {
-    const cached = ctx.ws.readJsonSafe(artifactName);
-    const cachedPlan = !ctx.state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === fingerprint && cached["parse_status"] === "ok" && isDict(cached["plan"]) ? cached["plan"] : null;
-    if (cachedPlan && isList(cachedPlan["decisions"]))
-        return cachedPlan;
-    const startedAtMs = Date.now();
-    const baseContextText = contextText(candidateSourceKeys);
-    const expressionText = await ctx.timing.span({ name: strOf(metadata["part_id"]) || artifactName, category: "chunk", parent: parentTiming, metadata: { artifact: artifactName } }, () => run(baseContextText));
-    let partPlan = parseAssetCurationExpressionsTolerant(expressionText);
-    if (!isDict(partPlan) || !isList(partPlan["decisions"])) {
-        throw new CliError("INIT FAILED: Provider returned invalid asset curation", "Provider returned invalid asset curation.", {
-            exitCode: EXIT_RUNTIME,
-            required: ["object with decisions[]"],
-            received: [typeof partPlan],
-            nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation will retry."],
-        });
-    }
-    const repairAttempts = [];
-    let repairSourceKeys = repairSourceKeysForPart(script, candidateSourceKeys, partPlan, requireCoverage);
-    let repairRejectedContext = asList(partPlan["rejected_expressions"]).filter(isDict);
-    try {
-        for (let attempt = 1; repairSourceKeys.length > 0 && attempt <= MAX_CURATION_PART_REPAIR_ATTEMPTS; attempt += 1) {
-            const repairContext = buildAssetCurationRepairContextText({
-                baseContextText: contextText(repairSourceKeys),
-                repairSourceKeys,
-                rejectedExpressions: repairRejectedContext,
-                acceptedDecisions: asList(partPlan["decisions"]).filter(isDict),
-            });
-            const repairText = await ctx.timing.span({ name: `${strOf(metadata["part_id"]) || artifactName}.repair.${pad3(attempt)}`, category: "repair", parent: parentTiming, metadata: { artifact: artifactName, repair_source_keys: repairSourceKeys } }, () => run(repairContext));
-            const repairPlan = parseAssetCurationExpressionsTolerant(repairText);
-            const repairRejected = asList(repairPlan["rejected_expressions"]).filter(isDict);
-            const scopedRepair = scopedCurationPlan(repairPlan, repairSourceKeys);
-            repairAttempts.push({
-                index: attempt,
-                repair_source_keys: repairSourceKeys,
-                expression_text: repairText,
-                accepted_expressions: scopedRepair.plan["accepted_expressions"],
-                ignored_expressions: scopedRepair.ignored,
-                rejected_expressions: repairRejected,
-                decisions: scopedRepair.plan["decisions"],
-            });
-            if (repairRejected.length > 0) {
-                if (asList(scopedRepair.plan["decisions"]).filter(isDict).length > 0) {
-                    partPlan = mergeRepairedCurationPlan(expressionText, partPlan, scopedRepair.plan, repairAttempts);
-                }
-                const missingKeys = requireCoverage ? missingRequiredSourceKeysForPart(script, candidateSourceKeys, partPlan) : [];
-                const rejectedKeys = sourceKeysFromRejectedExpressions(repairRejected, repairSourceKeys);
-                const nextRepairSourceKeys = [...(rejectedKeys.length > 0 ? rejectedKeys : []), ...missingKeys]
-                    .filter((key, index, all) => all.indexOf(key) === index);
-                if (nextRepairSourceKeys.length === 0) {
-                    repairSourceKeys = [];
-                    repairRejectedContext = [];
-                    continue;
-                }
-                if (attempt >= MAX_CURATION_PART_REPAIR_ATTEMPTS) {
-                    throw invalidCurationPart("INIT FAILED: Asset curation repair returned invalid expressions", repairRejected.map((item) => `${strOf(item["source_key"]) || "-"}: ${strOf(item["error"])}`).slice(0, 40));
-                }
-                repairSourceKeys = nextRepairSourceKeys;
-                repairRejectedContext = repairRejected;
-                continue;
-            }
-            const finalKeys = new Set([...curationDecisionSourceKeys(partPlan), ...curationDecisionSourceKeys(scopedRepair.plan)]);
-            const unrepaired = repairSourceKeys.filter((key) => !finalKeys.has(key));
-            if (unrepaired.length > 0 && attempt >= MAX_CURATION_PART_REPAIR_ATTEMPTS) {
-                throw invalidCurationPart("INIT FAILED: Asset curation repair omitted required source decisions", unrepaired.slice(0, 40));
-            }
-            partPlan = mergeRepairedCurationPlan(expressionText, partPlan, scopedRepair.plan, repairAttempts);
-            repairRejectedContext = [];
-            const missingKeys = requireCoverage ? missingRequiredSourceKeysForPart(script, candidateSourceKeys, partPlan) : [];
-            repairSourceKeys = [...unrepaired, ...missingKeys]
-                .filter((key, index, all) => all.indexOf(key) === index);
-        }
-        if (repairSourceKeys.length > 0) {
-            throw invalidCurationPart("INIT FAILED: Asset curation repair omitted required source decisions", repairSourceKeys.slice(0, 40));
-        }
-    }
-    catch (exc) {
-        writeFailedCurationPartArtifact({
-            ctx,
-            artifactName,
-            fingerprint,
-            metadata,
-            candidateSourceKeys,
-            expressionText,
-            partPlan,
-            repairAttempts,
-            startedAtMs,
-            error: exc,
-        });
-        throw exc;
-    }
-    for (const [key, value] of Object.entries(metadata))
-        partPlan[key] = value;
-    ctx.ws.writeJson(artifactName, {
-        version: 1,
-        ...assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION),
-        script_fingerprint: fingerprint,
-        ...metadata,
-        parse_status: "ok",
-        candidate_source_keys: candidateSourceKeys,
-        expression_text: partPlan["expression_text"],
-        raw_expression_text: partPlan["raw_expression_text"] ?? expressionText,
-        accepted_expressions: partPlan["accepted_expressions"],
-        rejected_expressions: partPlan["rejected_expressions"],
-        repair_attempts: repairAttempts,
-        duration_ms: durationMs(startedAtMs, Date.now()),
-        plan: partPlan,
-        updated_at: checkpointTimestamp(),
-    });
-    return partPlan;
-}
-async function loadOrRunPrimaryCurationPart(ctx, script, curateAssets, kind, partId, fingerprint, ids) {
-    const selection = curationPartSelection(kind, ids);
-    return loadOrRunCurationPart(ctx, script, `asset_curation_parts/primary.${partId}.json`, fingerprint, { asset_kind: kind, part_id: partId, selection }, curationSourceKeysForIds(kind, ids), "asset_curation.primary", true, (selectedSourceKeys = curationSourceKeysForIds(kind, ids)) => {
-        const selectedIds = curationIdsFromSourceKeys(kind, ids, selectedSourceKeys);
-        return buildAssetCurationContextText(script, [kind], curationPartSelection(kind, selectedIds.length > 0 ? selectedIds : ids));
-    }, (contextText) => curateAssets(script, contextText));
-}
-function primaryCurationChunks(script, groupingPlan) {
-    const chunks = [];
-    for (const kind of ["actor", "location", "prop"]) {
-        const groupingGroups = groupingPlan
-            ? asList(groupingPlan["groups"]).filter((group) => isDict(group) && group["kind"] === kind)
-            : [];
-        const kindChunks = groupingGroups.length > 0
-            ? groupedAssetCurationChunks(script, kind, groupingGroups)
-            : buildPrimaryAssetCurationChunks(script, kind);
-        for (let index = 0; index < kindChunks.length; index += 1) {
-            chunks.push({
-                kind,
-                partId: `${kind}.${String(index + 1).padStart(3, "0")}`,
-                ids: kindChunks[index],
-            });
-        }
-    }
-    return chunks;
-}
-async function loadOrRunAuditCurationParts(ctx, script, curateAssets, primaryPlan, fingerprint) {
-    const sourceChunks = chunkStrings(assetCurationAuditSourceKeys(script, primaryPlan), 24);
-    if (sourceChunks.length === 0) {
-        return parseAssetCurationExpressions("<exp>NOOP # no asset curation changes</exp>");
-    }
-    const outcomes = await pMapWithConcurrency(sourceChunks, ctx.options.concurrency, async (selectedSourceKeys, index) => {
-        const partId = `audit.${String(index + 1).padStart(3, "0")}`;
-        return loadOrRunCurationPart(ctx, script, `asset_curation_parts/${partId}.json`, fingerprint, { part_id: partId, selected_source_keys: selectedSourceKeys }, selectedSourceKeys, "asset_curation.audit", false, (repairSourceKeys = selectedSourceKeys) => buildAssetCurationAuditContextText(script, primaryPlan, repairSourceKeys), (contextText) => curateAssets(script, contextText));
-    });
-    const parts = unwrapConcurrentOutcomes(outcomes);
-    return combineAssetCurationExpressionPlans(parts);
-}
-async function loadOrRunLocationCanonicalizationParts(ctx, script, curateAssets, plan, fingerprint) {
-    const sourceChunks = chunkStrings(locationCanonicalizationCandidateSourceKeys(script, plan), 24);
-    if (sourceChunks.length === 0) {
-        return parseAssetCurationExpressions("<exp>NOOP # no location canonicalization changes</exp>");
-    }
-    const outcomes = await pMapWithConcurrency(sourceChunks, ctx.options.concurrency, async (selectedSourceKeys, index) => {
-        const partId = `location_canonical.${String(index + 1).padStart(3, "0")}`;
-        return loadOrRunCurationPart(ctx, script, `asset_curation_parts/${partId}.json`, fingerprint, { part_id: partId, selected_source_keys: selectedSourceKeys }, selectedSourceKeys, "asset_curation.location_canonical", false, (repairSourceKeys = selectedSourceKeys) => buildLocationCanonicalizationAuditContextText(script, plan, repairSourceKeys), (contextText) => curateAssets(script, contextText));
-    });
-    const parts = unwrapConcurrentOutcomes(outcomes);
-    return combineAssetCurationExpressionPlans(parts);
-}
-export async function stageAssetCuration(ctx) {
-    const { ws, state, options } = ctx;
-    const script = ensureScript(ctx);
-    let groupingPlan = null;
-    let groupingApplySummary = null;
-    let plan = null;
-    let primaryPlan = null;
-    let auditPlan = null;
-    let locationCanonicalPlan = null;
-    let primaryExpressionText = null;
-    let primaryPartExpressionTexts = [];
-    let auditExpressionText = null;
-    let locationCanonicalExpressionText = null;
-    try {
-        ctx.updateRunState({ status: "init_running", init_stage: "asset_curation" });
-        ctx.emitProgress("asset-curation");
-        const provider = ctx.provider();
-        if (!provider.curateAssets) {
-            throw new CliError("INIT FAILED: Provider does not support asset curation", "Provider does not support asset curation.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["provider.curateAssets(script, contextText)"],
-                received: [`provider: ${provider.name || options.providerName}`],
-                nextSteps: ["Use a direct provider that supports asset curation."],
-            });
-        }
-        if (!provider.groupAssets) {
-            throw new CliError("INIT FAILED: Provider does not support asset grouping", "Provider does not support asset grouping.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["provider.groupAssets(script, contextText)"],
-                received: [`provider: ${provider.name || options.providerName}`],
-                nextSteps: ["Use a direct provider that supports asset grouping."],
-            });
-        }
-        const groupAssets = provider.groupAssets.bind(provider);
-        const curateAssets = provider.curateAssets.bind(provider);
-        const groupingFingerprint = assetGroupingScriptFingerprint(script, options);
-        groupingPlan = await ctx.timing.span({ name: "asset_curation.grouping", category: "substage", parent: "asset_curation" }, () => loadOrRunAssetGrouping(ctx, script, groupAssets, groupingFingerprint));
-        groupingApplySummary = await ctx.timing.span({ name: "asset_curation.grouping.apply", category: "substage", parent: "asset_curation.grouping" }, () => applyAssetGroupingDuplicateMerges(script, { decisions: groupingPlan["duplicate_merge_decisions"] }));
-        Object.assign(groupingPlan, assetCacheArtifactFields(ctx, ASSET_GROUPING_CACHE_VERSION));
-        groupingPlan["apply_summary"] = groupingApplySummary;
-        groupingPlan["script_fingerprint"] = groupingFingerprint;
-        ws.writeJson("asset_grouping.json", groupingPlan);
-        const fingerprint = assetCurationScriptFingerprint(script, options);
-        const cachedCuration = ws.readJsonSafe("asset_curation.json");
-        if (!state.bypassInternalCaches && isDict(cachedCuration) && cachedCuration["script_fingerprint"] === fingerprint && isList(cachedCuration["decisions"])) {
-            const curation = curateScriptAssets(script, { decisions: cachedCuration["decisions"] });
-            Object.assign(curation, assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION));
-            curation["script_fingerprint"] = fingerprint;
-            curation["grouping"] = groupingPlan;
-            curation["grouping_apply_summary"] = groupingApplySummary;
-            if (typeof cachedCuration["expression_text"] === "string")
-                curation["expression_text"] = cachedCuration["expression_text"];
-            if (typeof cachedCuration["primary_expression_text"] === "string")
-                curation["primary_expression_text"] = cachedCuration["primary_expression_text"];
-            if (typeof cachedCuration["primary_part_expression_text"] === "string")
-                curation["primary_part_expression_text"] = cachedCuration["primary_part_expression_text"];
-            if (typeof cachedCuration["audit_expression_text"] === "string")
-                curation["audit_expression_text"] = cachedCuration["audit_expression_text"];
-            if (typeof cachedCuration["location_canonical_expression_text"] === "string")
-                curation["location_canonical_expression_text"] = cachedCuration["location_canonical_expression_text"];
-            if (isList(cachedCuration["expressions"]))
-                curation["expressions"] = cachedCuration["expressions"];
-            if (isList(cachedCuration["primary_expressions"]))
-                curation["primary_expressions"] = cachedCuration["primary_expressions"];
-            if (isList(cachedCuration["primary_parts"]))
-                curation["primary_parts"] = cachedCuration["primary_parts"];
-            if (isList(cachedCuration["audit_expressions"]))
-                curation["audit_expressions"] = cachedCuration["audit_expressions"];
-            if (isList(cachedCuration["location_canonical_expressions"]))
-                curation["location_canonical_expressions"] = cachedCuration["location_canonical_expressions"];
-            if (typeof cachedCuration["format"] === "string")
-                curation["format"] = cachedCuration["format"];
-            if (isDict(cachedCuration["audit_summary"]))
-                curation["audit_summary"] = cachedCuration["audit_summary"];
-            ws.writeJson("asset_curation.json", curation);
-            ws.delete("asset_curation.failed.json");
-            ctx.emitProgress("asset-curation", "success");
-            return;
-        }
-        const primaryChunkSpecs = primaryCurationChunks(script, groupingPlan);
-        const primaryOutcomes = await pMapWithConcurrency(primaryChunkSpecs, options.concurrency, async (chunk) => loadOrRunPrimaryCurationPart(ctx, script, curateAssets, chunk.kind, chunk.partId, fingerprint, chunk.ids));
-        const primaryParts = unwrapConcurrentOutcomes(primaryOutcomes);
-        primaryPartExpressionTexts = primaryParts.map((part) => ({
-            asset_kind: part["asset_kind"],
-            part_id: part["part_id"],
-            expression_text: part["expression_text"],
-        }));
-        primaryPlan = await ctx.timing.span({ name: "asset_curation.primary.combine", category: "substage", parent: "asset_curation.primary", metadata: { chunks: primaryParts.length } }, () => combinePrimaryAssetCurationPlans(primaryParts));
-        primaryExpressionText = typeof primaryPlan["expression_text"] === "string" ? primaryPlan["expression_text"] : "";
-        if (!isDict(primaryPlan) || !isList(primaryPlan["decisions"])) {
-            throw new CliError("INIT FAILED: Provider returned invalid asset curation", "Provider returned invalid asset curation.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["object with decisions[]"],
-                received: [typeof primaryPlan],
-                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation will retry."],
-            });
-        }
-        const allowedNewAuditSources = [
-            ...missingAssetCurationRequiredSourceKeys(script, primaryPlan),
-            ...assetCurationAuditCandidateSourceKeys(script, primaryPlan),
-        ];
-        auditPlan = await ctx.timing.span({ name: "asset_curation.audit", category: "substage", parent: "asset_curation" }, () => loadOrRunAuditCurationParts(ctx, script, curateAssets, primaryPlan, assetCurationPlanFingerprint(`${fingerprint}:audit-chunk-v1`, primaryPlan)));
-        auditExpressionText = typeof auditPlan["expression_text"] === "string" ? auditPlan["expression_text"] : "";
-        if (!isDict(auditPlan) || !isList(auditPlan["decisions"])) {
-            throw new CliError("INIT FAILED: Provider returned invalid asset curation audit", "Provider returned invalid asset curation audit.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["object with decisions[]"],
-                received: [typeof auditPlan],
-                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and curation audit will retry."],
-            });
-        }
-        plan = combineAssetCurationPlans(primaryPlan, auditPlan, allowedNewAuditSources, { salvageInvalidAuditSources: true });
-        const allowedNewLocationCanonicalSources = locationCanonicalizationCandidateSourceKeys(script, plan);
-        locationCanonicalPlan = await ctx.timing.span({ name: "asset_curation.location_canonical", category: "substage", parent: "asset_curation" }, () => loadOrRunLocationCanonicalizationParts(ctx, script, curateAssets, plan, assetCurationPlanFingerprint(`${fingerprint}:location-canonical-chunk-v2`, plan)));
-        locationCanonicalExpressionText = typeof locationCanonicalPlan["expression_text"] === "string" ? locationCanonicalPlan["expression_text"] : "";
-        if (!isDict(locationCanonicalPlan) || !isList(locationCanonicalPlan["decisions"])) {
-            throw new CliError("INIT FAILED: Provider returned invalid location canonicalization audit", "Provider returned invalid location canonicalization audit.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["object with decisions[]"],
-                received: [typeof locationCanonicalPlan],
-                nextSteps: ["Rerun init; completed extraction checkpoints will be reused and location canonicalization will retry."],
-            });
-        }
-        assertLocationCanonicalizationPlan(locationCanonicalPlan);
-        plan = combineLocationCanonicalizationPlan(script, plan, locationCanonicalPlan, allowedNewLocationCanonicalSources);
-        const curation = await ctx.timing.span({ name: "asset_curation.apply", category: "substage", parent: "asset_curation" }, () => curateScriptAssets(script, plan));
-        Object.assign(curation, assetCacheArtifactFields(ctx, ASSET_CURATION_CACHE_VERSION));
-        curation["script_fingerprint"] = fingerprint;
-        curation["format"] = plan["format"];
-        curation["expression_text"] = plan["expression_text"];
-        curation["primary_expression_text"] = plan["primary_expression_text"];
-        curation["audit_expression_text"] = plan["audit_expression_text"];
-        curation["location_canonical_expression_text"] = plan["location_canonical_expression_text"];
-        curation["primary_part_expression_text"] = plan["primary_part_expression_text"];
-        curation["primary_parts"] = plan["primary_parts"];
-        curation["expressions"] = plan["expressions"];
-        curation["primary_expressions"] = plan["primary_expressions"];
-        curation["audit_expressions"] = plan["audit_expressions"];
-        curation["location_canonical_expressions"] = plan["location_canonical_expressions"];
-        curation["audit_summary"] = plan["audit_summary"];
-        curation["grouping"] = groupingPlan;
-        curation["grouping_apply_summary"] = groupingApplySummary;
-        ws.writeJson("asset_curation.json", curation);
-        ws.delete("asset_curation.failed.json");
-    }
-    catch (exc) {
-        if (plan || primaryPlan || auditPlan || locationCanonicalPlan || primaryExpressionText !== null || auditExpressionText !== null || locationCanonicalExpressionText !== null) {
-            const e = exc;
-            ws.writeJson("asset_curation.failed.json", {
-                version: 3,
-                failed_at: checkpointTimestamp(),
-                error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-                expression_text: plan?.["expression_text"] ?? null,
-                primary_expression_text: primaryExpressionText,
-                primary_part_expression_texts: primaryPartExpressionTexts,
-                audit_expression_text: auditExpressionText,
-                location_canonical_expression_text: locationCanonicalExpressionText,
-                primary_plan: primaryPlan,
-                audit_plan: auditPlan,
-                location_canonical_plan: locationCanonicalPlan,
-                grouping_plan: groupingPlan,
-                grouping_apply_summary: groupingApplySummary,
-                plan,
-            });
-        }
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Asset curation failed",
-            stage: "asset_curation",
-            required: ["a well-formed assembled script for deterministic asset curation"],
-            nextSteps: ["Rerun init; completed extraction checkpoints will be reused."],
-            updates: { episode_completed: state.mergedResults.length },
-        });
-    }
-    ctx.emitProgress("asset-curation", "success");
-}
-// --- state-curation -------------------------------------------------------
-const STATE_CURATION_CACHE_VERSION = 7;
-function stateCurationScriptFingerprint(script, options) {
-    return sha256Text(JSON.stringify(sortDeep({
-        cache_version: STATE_CURATION_CACHE_VERSION,
-        ...assetCacheIdentity(options),
-        script: {
-            actors: script["actors"],
-            locations: script["locations"],
-            props: script["props"],
-            episodes: script["episodes"],
-        },
-    })));
-}
-function stateCurationContextFingerprint(scriptFingerprint, partId, refs) {
-    return sha256Text(JSON.stringify(sortDeep({
-        script_fingerprint: scriptFingerprint,
-        part_id: partId,
-        refs,
-    })));
-}
-function combineStateCurationPlans(parts) {
-    const decisions = parts.flatMap((part) => asList(part.plan["decisions"]).filter(isDict));
-    const defaultSelections = parts.flatMap((part) => asList(part.plan["default_selections"]).filter(isDict));
-    const expressions = parts.flatMap((part) => asList(part.plan["expressions"]));
-    return {
-        version: 1,
-        format: "state-curation-exp-v1",
-        expression_text: expressions.length > 0 ? expressions.map((expression) => `<exp>${expression}</exp>`).join("\n") : "<exp>NOOP # no state curation changes</exp>",
-        expressions,
-        decisions,
-        default_selections: defaultSelections,
-        parts: parts.map((part) => ({
-            part_id: part.partId,
-            refs: part.refs,
-            context_fingerprint: part.contextFingerprint,
-            context_chars: part.contextChars,
-            reused: part.reused,
-            decisions: asList(part.plan["decisions"]).length,
-            default_selections: asList(part.plan["default_selections"]).length,
-        })),
-    };
-}
-async function loadOrRunStateCurationPart(ctx, script, curateStates, scriptFingerprint, partId, refs) {
-    const artifactName = `state_curation_parts/${partId}.json`;
-    const contextFingerprint = stateCurationContextFingerprint(scriptFingerprint, partId, refs);
-    const cached = ctx.ws.readJsonSafe(artifactName);
-    const cachedPlan = !ctx.state.bypassInternalCaches
-        && isDict(cached)
-        && cached["context_fingerprint"] === contextFingerprint
-        && cached["parse_status"] === "ok"
-        && isDict(cached["plan"])
-        ? cached["plan"]
-        : null;
-    if (cachedPlan && isList(cachedPlan["decisions"])) {
-        const cachedContextChars = isDict(cached) ? Number(cached["context_chars"] ?? 0) : 0;
-        return {
-            partId,
-            refs: [...refs],
-            contextFingerprint,
-            contextChars: cachedContextChars,
-            plan: cachedPlan,
-            reused: true,
-        };
-    }
-    const startedAtMs = Date.now();
-    const contextText = buildStateCurationContextText(script, refs);
-    const requiredKeys = stateCurationSourceKeysForRefs(script, refs);
-    let expressionText = "";
-    try {
-        expressionText = await ctx.timing.span({ name: `state_curation.${partId}`, category: "chunk", parent: "state_curation.chunks", metadata: { artifact: artifactName } }, () => curateStates(script, contextText));
-        const parsed = parseStateCurationExpressions(expressionText);
-        const plan = assertStateCurationPlan(script, parsed, requiredKeys);
-        ctx.ws.writeJson(artifactName, {
-            version: 1,
-            ...assetCacheArtifactFields(ctx, STATE_CURATION_CACHE_VERSION),
-            context_fingerprint: contextFingerprint,
-            script_fingerprint: scriptFingerprint,
-            parse_status: "ok",
-            part_id: partId,
-            refs,
-            required_state_ids: requiredKeys,
-            context_chars: contextText.length,
-            expression_text: expressionText,
-            duration_ms: durationMs(startedAtMs, Date.now()),
-            plan,
-            updated_at: checkpointTimestamp(),
-        });
-        return {
-            partId,
-            refs: [...refs],
-            contextFingerprint,
-            contextChars: contextText.length,
-            plan,
-            reused: false,
-        };
-    }
-    catch (exc) {
-        const e = exc;
-        ctx.ws.writeJson(artifactName, {
-            version: 1,
-            ...assetCacheArtifactFields(ctx, STATE_CURATION_CACHE_VERSION),
-            context_fingerprint: contextFingerprint,
-            script_fingerprint: scriptFingerprint,
-            parse_status: "failed",
-            part_id: partId,
-            refs,
-            required_state_ids: requiredKeys,
-            context_chars: contextText.length,
-            expression_text: expressionText,
-            duration_ms: durationMs(startedAtMs, Date.now()),
-            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-            updated_at: checkpointTimestamp(),
-        });
-        throw exc;
-    }
-}
-export async function stageStateCuration(ctx) {
-    const { ws, state, options } = ctx;
-    const script = ensureScript(ctx);
-    let plan = null;
-    try {
-        ctx.updateRunState({ status: "init_running", init_stage: "state_curation" });
-        ctx.emitProgress("state-curation");
-        const scriptFingerprint = stateCurationScriptFingerprint(script, options);
-        const cached = ws.readJsonSafe("state_curation.json");
-        if (!state.bypassInternalCaches && isDict(cached) && cached["script_fingerprint"] === scriptFingerprint && isList(cached["decisions"])) {
-            const curation = await ctx.timing.span({ name: "state_curation.apply", category: "substage", parent: "state_curation" }, () => applyStateCurationPlan(script, { decisions: cached["decisions"], default_selections: cached["default_selections"] }));
-            curation["script_fingerprint"] = scriptFingerprint;
-            curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
-            curation["provider"] = options.providerName;
-            curation["model"] = options.model;
-            if (isList(cached["parts"]))
-                curation["parts"] = cached["parts"];
-            if (typeof cached["expression_text"] === "string")
-                curation["expression_text"] = cached["expression_text"];
-            if (isList(cached["expressions"]))
-                curation["expressions"] = cached["expressions"];
-            if (isList(cached["default_selections"]))
-                curation["default_selections"] = cached["default_selections"];
-            ws.writeJson("state_curation.json", curation);
-            ws.delete("state_curation.failed.json");
-            ctx.emitProgress("state-curation", "success");
-            return;
-        }
-        const chunks = buildStateCurationChunks(script);
-        if (chunks.length === 0) {
-            const curation = applyStateCurationPlan(script, { decisions: [] });
-            curation["script_fingerprint"] = scriptFingerprint;
-            curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
-            curation["provider"] = options.providerName;
-            curation["model"] = options.model;
-            curation["parts"] = [];
-            curation["expression_text"] = "<exp>NOOP # no state curation changes</exp>";
-            curation["expressions"] = ["NOOP # no state curation changes"];
-            ws.writeJson("state_curation.json", curation);
-            ws.delete("state_curation.failed.json");
-            ctx.emitProgress("state-curation", "success");
-            return;
-        }
-        const provider = ctx.provider();
-        if (!provider.curateStates) {
-            throw new CliError("INIT FAILED: Provider does not support state curation", "Provider does not support state curation.", {
-                exitCode: EXIT_RUNTIME,
-                required: ["provider.curateStates(script, contextText)"],
-                received: [`provider: ${provider.name || options.providerName}`],
-                nextSteps: ["Use a direct provider that supports state curation."],
-            });
-        }
-        ws.mkdir("state_curation_parts");
-        ctx.updateRunState({ state_curation_completed_chunks: 0, state_curation_total_chunks: chunks.length });
-        const curateStates = provider.curateStates.bind(provider);
-        let completedChunks = 0;
-        const outcomes = await pMapWithConcurrency(chunks, options.concurrency, async (chunk) => {
-            const part = await loadOrRunStateCurationPart(ctx, script, curateStates, scriptFingerprint, chunk.part_id, chunk.refs);
-            completedChunks += 1;
-            ctx.updateRunState({ state_curation_completed_chunks: completedChunks, state_curation_total_chunks: chunks.length });
-            return part;
-        });
-        const parts = unwrapConcurrentOutcomes(outcomes).sort((left, right) => left.partId.localeCompare(right.partId));
-        plan = combineStateCurationPlans(parts);
-        const curation = await ctx.timing.span({ name: "state_curation.apply", category: "substage", parent: "state_curation" }, () => applyStateCurationPlan(script, plan));
-        curation["script_fingerprint"] = scriptFingerprint;
-        curation["cache_version"] = STATE_CURATION_CACHE_VERSION;
-        curation["provider"] = options.providerName;
-        curation["model"] = options.model;
-        curation["expression_text"] = plan["expression_text"];
-        curation["expressions"] = plan["expressions"];
-        curation["parts"] = plan["parts"];
-        ws.writeJson("state_curation.json", curation);
-        ws.delete("state_curation.failed.json");
-    }
-    catch (exc) {
-        const e = exc;
-        ws.writeJson("state_curation.failed.json", {
-            version: 1,
-            failed_at: checkpointTimestamp(),
-            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-            plan,
-        });
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: State curation failed",
-            stage: "state_curation",
-            required: ["provider state curation decisions for the assembled script state catalog"],
-            nextSteps: ["Rerun init; completed extraction and asset curation checkpoints will be reused."],
-            updates: { episode_completed: state.mergedResults.length },
-        });
-    }
-    ctx.emitProgress("state-curation", "success");
-}
-const STATE_BINDING_CHUNK_CACHE_VERSION = 2;
-function stateBindingChunkFingerprint(options, context) {
-    return sha256Text(JSON.stringify(sortDeep({
-        cache_version: STATE_BINDING_CHUNK_CACHE_VERSION,
-        provider: options.providerName,
-        model: options.model,
-        context,
-    })));
-}
-async function runStateBindingForScript(ctx, script, progress) {
-    const { ws, options } = ctx;
-    const provider = ctx.provider();
-    if (!provider.bindStates) {
-        throw new CliError("INIT FAILED: Provider does not support state binding", "Provider does not support state binding.", {
-            exitCode: EXIT_RUNTIME,
-            required: ["provider.bindStates(script, context)"],
-            received: [`provider: ${provider.name || options.providerName}`],
-            nextSteps: ["Use a direct provider that supports state binding."],
-        });
-    }
-    const defaultSummary = await ctx.timing.span({ name: "state_binding.default_states", category: "substage", parent: "state_binding" }, () => ensureDefaultStates(script));
-    const missingDefaults = Number(defaultSummary["assets_missing_default_state"] ?? 0);
-    if (missingDefaults > 0) {
-        throw new CliError("DIRECT STATE BINDING BLOCKED: default states missing", "Some assets have states but no asset-scoped `default` state.", {
-            exitCode: EXIT_NEEDS_AGENT,
-            required: ["each stateful actor/location/prop has exactly one state_id `default`"],
-            received: [`assets_missing_default_state: ${missingDefaults}`],
-            nextSteps: ["Run `scriptctl direct run state-curation` or edit script.initial.json to select each asset's common visual state as `default`."],
-        });
-    }
-    const defaultBindingSummary = await ctx.timing.span({ name: "state_binding.default_refs", category: "substage", parent: "state_binding" }, () => bindDefaultStateRefsInScript(script));
-    const chunks = buildStateBindingContexts(script, 8);
-    ws.mkdir("state_binding_chunks");
-    if (progress) {
-        ctx.updateRunState({ state_binding_completed_chunks: 0, state_binding_total_chunks: chunks.length });
-    }
-    let chunkPlans = [];
-    const bypassChunkCache = ctx.state.bypassInternalCaches;
-    try {
-        const outcomes = await pMapWithConcurrency(chunks, options.concurrency, async (context, index) => {
-            const chunkArtifact = `state_binding_chunks/chunk_${pad3(index + 1)}.json`;
-            const contextFingerprint = stateBindingChunkFingerprint(options, context);
-            const cachedChunk = ws.readJsonSafe(chunkArtifact);
-            const cachedPlanRaw = isDict(cachedChunk) ? cachedChunk["plan"] : null;
-            const cachedPlan = !bypassChunkCache
-                && isDict(cachedChunk)
-                && cachedChunk["context_fingerprint"] === contextFingerprint
-                && isDict(cachedPlanRaw)
-                ? cachedPlanRaw
-                : null;
-            const startedAtMs = Date.now();
-            const rawPlan = normalizeStateBindingPlanShape(cachedPlan ?? await ctx.timing.span({ name: `state_binding.chunk.${pad3(index + 1)}`, category: "chunk", parent: "state_binding.chunks", metadata: { index } }, () => provider.bindStates(script, context)));
-            if (!isDict(rawPlan) || !isList(rawPlan["scenes"])) {
-                throw new CliError("INIT FAILED: Provider returned invalid state binding", "Provider returned invalid state binding.", {
-                    exitCode: EXIT_RUNTIME,
-                    required: ["object with scenes[]"],
-                    received: [typeof rawPlan],
-                    nextSteps: ["Rerun init; completed extraction checkpoints will be reused and state binding will retry."],
-                });
-            }
-            if (!cachedPlan) {
-                ws.writeJson(chunkArtifact, {
-                    version: 1,
-                    cache_version: STATE_BINDING_CHUNK_CACHE_VERSION,
-                    index,
-                    provider: options.providerName,
-                    model: options.model,
-                    context_fingerprint: contextFingerprint,
-                    scene_ids: asList(context["scenes"]).map((scene) => strOf(scene["scene_id"])),
-                    duration_ms: durationMs(startedAtMs, Date.now()),
-                    plan: rawPlan,
-                    updated_at: checkpointTimestamp(),
-                });
-            }
-            if (progress) {
-                ctx.updateRunState({ state_binding_completed_chunks: index + 1, state_binding_total_chunks: chunks.length });
-            }
-            return { index, context, plan: rawPlan, contextFingerprint, reused: Boolean(cachedPlan) };
-        });
-        chunkPlans = unwrapConcurrentOutcomes(outcomes).sort((left, right) => left.index - right.index);
-    }
-    catch (exc) {
-        const e = exc;
-        ws.writeJson("state_binding.failed.json", {
-            version: 1,
-            failed_at: checkpointTimestamp(),
-            chunks_total: chunks.length,
-            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-            completed_chunks: [],
-        });
-        throw exc;
-    }
-    const chunkReports = [];
-    let sceneRefsBound = 0;
-    let stateChangesApplied = 0;
-    let invalidSceneRefsSkipped = 0;
-    let invalidStateChangesSkipped = 0;
-    try {
-        await ctx.timing.span({ name: "state_binding.apply", category: "substage", parent: "state_binding" }, () => {
-            for (const item of chunkPlans) {
-                const applied = applyStateBindingPlan(script, item.plan, { invalidStateMode: "skip" });
-                sceneRefsBound += Number(applied["scene_refs_bound"] ?? 0);
-                stateChangesApplied += Number(applied["state_changes_applied"] ?? 0);
-                invalidSceneRefsSkipped += Number(applied["invalid_scene_refs_skipped"] ?? 0);
-                invalidStateChangesSkipped += Number(applied["invalid_state_changes_skipped"] ?? 0);
-                chunkReports.push({
-                    index: item.index,
-                    reused: item.reused,
-                    context_fingerprint: item.contextFingerprint,
-                    scene_count: asList(item.context["scenes"]).length,
-                    scene_refs_bound: applied["scene_refs_bound"],
-                    state_changes_applied: applied["state_changes_applied"],
-                    invalid_scene_refs_skipped: applied["invalid_scene_refs_skipped"],
-                    invalid_state_changes_skipped: applied["invalid_state_changes_skipped"],
-                });
-            }
-        });
-    }
-    catch (exc) {
-        const e = exc;
-        ws.writeJson("state_binding.failed.json", {
-            version: 1,
-            failed_at: checkpointTimestamp(),
-            chunks_total: chunks.length,
-            error: `${e?.name ?? "Error"}: ${e?.message ?? ""}`,
-            completed_chunks: chunkReports,
-        });
-        throw exc;
-    }
-    const summary = {
-        ...defaultSummary,
-        ...defaultBindingSummary,
-        llm_scene_refs_bound: sceneRefsBound,
-        llm_state_changes_applied: stateChangesApplied,
-        invalid_scene_refs_skipped: invalidSceneRefsSkipped,
-        invalid_state_changes_skipped: invalidStateChangesSkipped,
-        chunks: chunks.length,
-        cached_chunks: chunkPlans.filter((chunk) => chunk.reused).length,
-        llm_scene_count: chunks.reduce((n, chunk) => n + asList(chunk["scenes"]).length, 0),
-    };
-    ws.writeJson("state_binding.json", {
-        version: 1,
-        summary,
-        chunks: chunkReports,
-    });
-    ws.delete("state_binding.failed.json");
-    return { summary, chunks: chunkReports };
-}
-export async function stageStateBinding(ctx) {
-    const { state, options } = ctx;
-    const script = ensureScript(ctx);
-    try {
-        ctx.updateRunState({ status: "init_running", init_stage: "state_binding" });
-        ctx.emitProgress("state-binding");
-        await runStateBindingForScript(ctx, script, true);
-    }
-    catch (exc) {
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: State binding failed",
-            stage: "state_binding",
-            required: ["provider state binding decisions for a well-formed assembled script"],
-            nextSteps: ["Rerun init; completed extraction and curation checkpoints will be reused."],
-            updates: { episode_completed: state.mergedResults.length },
-        });
-    }
-    ctx.emitProgress("state-binding", "success");
-}
-async function runMetadataForScript(ctx, script, applyToScript, progress) {
-    const { ws, options } = ctx;
-    const sourceText = ensureSourceText(ctx);
-    const assetMetadataPath = ws.pathOf("asset_metadata.json");
-    if (options.skipMetadata) {
-        if (progress)
-            ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: true });
-        if (exists(assetMetadataPath))
-            deletePath(assetMetadataPath);
-        return { metadata: {}, skipped: true };
-    }
-    const provider = ctx.provider();
-    let metadata = provider.extractMetadata
-        ? await ctx.timing.span({ name: "metadata.extract", category: "substage", parent: "metadata_extract" }, () => provider.extractMetadata(sourceText, script))
-        : {};
-    if (!isDict(metadata))
-        metadata = {};
-    ws.writeJson("asset_metadata.json", metadata);
-    if (applyToScript) {
-        await ctx.timing.span({ name: "metadata.apply", category: "substage", parent: "metadata_extract" }, () => applyMetadataToScript(script, metadata));
-    }
-    return { metadata, skipped: false };
-}
-export async function stageMetadata(ctx) {
-    const { state, options } = ctx;
-    const script = ensureScript(ctx);
-    try {
-        ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: false });
-        ctx.emitProgress("metadata");
-        const result = await runMetadataForScript(ctx, script, true, true);
-        if (result.skipped) {
-            ctx.emitProgress("metadata", "skipped");
-            return;
-        }
-    }
-    catch (exc) {
-        if (exc instanceof CliError) {
-            throw initFailedReport(options.workspace, {
-                title: exc.title,
-                stage: "metadata_extract",
-                exitCode: exc.exitCode,
-                errorCode: exc.errorCode,
-                required: exc.required.length > 0 ? exc.required : ["metadata JSON matching final script contract"],
-                received: exc.received.length > 0 ? exc.received : [String(exc.message).slice(0, 160)],
-                nextSteps: exc.nextSteps.length > 0 ? exc.nextSteps : ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
-                updates: { episode_completed: state.mergedResults.length },
-            });
-        }
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Metadata extraction failed",
-            stage: "metadata_extract",
-            required: ["provider metadata for worldview, role_type, and asset descriptions"],
-            nextSteps: ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
-            updates: { episode_completed: state.mergedResults.length },
-        });
-    }
-    ctx.emitProgress("metadata", "success");
-}
-function overviewFieldsFromScript(script) {
-    return {
-        synopsis: script["synopsis"],
-        theme: script["theme"],
-        logline: script["logline"],
-        style: script["style"],
-        main_characters: script["main_characters"],
-    };
-}
-async function runScriptSynopsisForScript(ctx, script, persistScript) {
-    const { ws, options } = ctx;
-    const provider = ctx.provider();
-    let degraded = false;
-    let reason = "";
-    try {
-        const summary = await buildScriptSynopsis(provider, script, {
-            dd: ws.dir,
-            thresholdChars: options.summaryThresholdChars,
-            groupSize: DEFAULT_SUMMARY_GROUP_SIZE,
-            resummarize: options.resummarize,
-            skipSummary: options.skipSummary,
-            concurrency: options.concurrency,
-        });
-        degraded = summary.degraded;
-        reason = summary.reason ?? "";
-    }
-    catch (exc) {
-        degraded = true;
-        reason = providerErrorSummary(exc);
-    }
-    if (persistScript)
-        ws.writeJson("script.initial.json", script);
-    return { degraded, reason, fields: overviewFieldsFromScript(script) };
-}
-export async function stageScriptSynopsis(ctx) {
-    const { ws, state, options } = ctx;
-    const script = ensureScript(ctx);
-    ctx.updateRunState({ status: "init_running", init_stage: "script_synopsis" });
-    ctx.emitProgress("script-synopsis");
-    const summary = await runScriptSynopsisForScript(ctx, script, true);
-    state.summaryFullDegraded = summary.degraded;
-    state.summaryDegradeReason = summary.reason;
-    state.summaryDegradedEpisodes.sort((a, b) => a - b);
-    const summaryDegraded = summary.degraded || state.summaryDegradedEpisodes.length > 0;
-    ctx.updateRunState({
-        summary_skipped: options.skipSummary,
-        summary_degraded: summaryDegraded,
-        summary_degraded_episodes: state.summaryDegradedEpisodes,
-        summary_degraded_reason: summary.reason || null,
-    });
-    ctx.emitProgress("script-synopsis", summaryDegraded ? "warning" : options.skipSummary ? "skipped" : "success");
-}
-// --- validate -------------------------------------------------------------
-export async function stageValidate(ctx) {
-    const { ws, state, options } = ctx;
-    ensureScript(ctx); // ensures script.initial.json exists on disk for validateScript
-    const scriptPath = ws.pathOf("script.initial.json");
-    ctx.updateRunState({ status: "init_running", init_stage: "validate" });
-    ctx.emitProgress("validate");
-    let validation;
-    try {
-        validation = validateScript(options.workspace, scriptPath);
-    }
-    catch (exc) {
-        stageFailure(options.workspace, exc, {
-            title: "INIT FAILED: Validation failed",
-            stage: "validate",
-            required: ["script.initial.json that can be validated"],
-            nextSteps: ["Rerun init to retry validation, or inspect script.initial.json if the failure persists."],
-            updates: { script_path: scriptPath },
-        });
-    }
-    state.validation = validation;
-    const passed = Boolean(validation["passed"]);
-    ctx.emitProgress("validate", passed ? "success" : "warning");
-}
-// ---------------------------------------------------------------------------
-// command_status — the agent-facing state table, derived entirely from disk: a
-// batch with `<key>.json` is done, with `<key>.error.json` it failed, with
-// neither it is pending. run_state is just a denormalized cache of this, so the
-// agent can read state, then pick exactly which episodes/batches to (re)run.
-// ---------------------------------------------------------------------------
-export function commandStatus(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const dd = directDir(workspace);
-    const episodePlanPath = path.join(dd, "episode_plan.json");
-    const batchPlanPath = path.join(dd, "batch_plan.json");
-    const hasTrace = exists(path.join(workspace, "source.txt")) || Object.keys(readRunState(workspace)).length > 0;
-    if (!hasTrace && (!exists(episodePlanPath) || !exists(batchPlanPath))) {
-        throw new CliError("STATUS BLOCKED: Plan not found", "Plan not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["episode_plan.json and batch_plan.json"],
-            received: [exists(episodePlanPath) ? "episode_plan.json ok" : "episode_plan.json missing"],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    const snapshot = buildDirectStatusSnapshot(workspace);
-    const result = renderDirectStatusResult(snapshot);
-    const blockingStatuses = new Set(["error", "pending", "running"]);
-    const allDone = !snapshot.stages.some((stage) => blockingStatuses.has(stage.status));
-    const firstErrorEpisode = snapshot.episodes.find((episode) => episode.status === "error");
-    const report = {
-        title: "DIRECT STATUS",
-        result,
-        artifacts: [path.join(dd, "batch_results"), path.join(dd, "episode_results"), path.join(dd, "run_state.json")],
-        overall_status: snapshot.overall_status,
-        running_stage: snapshot.running_stage,
-        stages: snapshot.stages,
-        episodes: snapshot.episodes,
-        batches: snapshot.batches,
-        next: firstErrorEpisode
-            ? [`Re-run an errored episode with: direct init --episodes ${firstErrorEpisode.episode}  (or --retry-errors).`]
-            : allDone
-                ? ["All episodes complete."]
-                : ["Pending work remains — re-run: direct init (resume) or --episodes <N>."],
-    };
-    // Non-zero when the workspace is not fully extracted, so automation can gate
-    // on the exit code instead of scraping stdout.
-    return [report, allDone ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-export function summarizeIssues(issues) {
-    if (issues.length === 0)
-        return [];
-    const counts = {};
-    for (const item of issues) {
-        const sev = strOf(item["severity"]);
-        counts[sev] = (counts[sev] ?? 0) + 1;
-    }
-    const parts = Object.entries(counts).sort(([a], [b]) => a.localeCompare(b)).map(([sev, c]) => `${sev}: ${c}`);
-    const first = issues[0];
-    return [parts.join("; "), `first: ${first["code"]} - ${first["summary"]}`];
-}
-// ---------------------------------------------------------------------------
-// command_validate
-// ---------------------------------------------------------------------------
-export function commandValidate(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const scriptPath = opts["script_path"] ? strOf(opts["script_path"]) : null;
-    const validation = validateScript(workspace, scriptPath);
-    const stats = validation["stats"] ?? {};
-    const passed = Boolean(validation["passed"]);
-    const report = {
-        title: passed ? "VALIDATE PASSED: Script is ready" : "VALIDATE NEEDS AGENT: Repair issues found",
-        result: [`${stats["episodes"] ?? 0} episodes / ${stats["scenes"] ?? 0} scenes / ${stats["actions"] ?? 0} actions`],
-        artifacts: [path.join(directDir(workspace), "validation.json")],
-        issues: summarizeIssues(asList(validation["issues"])),
-        // Success needs no guidance; only repair gets a next step.
-        next: passed ? undefined : ["Inspect issues and apply structured patches."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
-}
-// ---------------------------------------------------------------------------
-// command_inspect (incl. review rendering)
-// ---------------------------------------------------------------------------
-function renderReviewEpisode(sourceText, episodePlan, script, episodeNum) {
-    const epId = fmtId("ep", episodeNum);
-    const scriptEp = asList(script["episodes"]).find((ep) => ep["episode_id"] === epId);
-    const planEp = asList(episodePlan["episodes"]).find((ep) => Number(ep["episode"] ?? 0) === episodeNum);
-    const lines = [];
-    if (!planEp && !scriptEp) {
-        lines.push(`⚠ Episode ${episodeNum} not found in episode_plan.json or script.initial.json.`);
-        const available = [...new Set(asList(episodePlan["episodes"]).map((ep) => Number(ep["episode"] ?? 0)))].sort((a, b) => a - b);
-        if (available.length > 0)
-            lines.push(`Available episodes: ${available.join(", ")}`);
-        return lines;
-    }
-    const title = (scriptEp?.["title"] ?? planEp?.["title"]) || "(无标题)";
-    lines.push("=".repeat(72));
-    lines.push(`EPISODE ${episodeNum} / ${epId} — ${title}`);
-    lines.push("=".repeat(72));
-    lines.push("");
-    lines.push("--- 原文 source.txt ---");
-    if (planEp) {
-        const span = isDict(planEp["source_span"]) ? planEp["source_span"] : {};
-        const start = Number(span["start"] ?? 0);
-        const end = Number(span["end"] ?? sourceText.length);
-        const snippet = sourceText.slice(start, end).replace(/\s+$/, "");
-        lines.push(snippet || "(empty)");
-    }
-    else {
-        lines.push("(no episode_plan entry; source span unavailable)");
-    }
-    lines.push("");
-    lines.push("--- 抽取 script.initial.json ---");
-    if (scriptEp) {
-        const actorIdToName = new Map();
-        for (const a of asList(script["actors"]))
-            actorIdToName.set(strOf(a["actor_id"]), strOf(a["actor_name"]));
-        const speakerIdToName = new Map();
-        for (const s of asList(script["speakers"]))
-            speakerIdToName.set(strOf(s["speaker_id"]), strOf(s["display_name"]));
-        const locationIdToName = new Map();
-        for (const l of asList(script["locations"]))
-            locationIdToName.set(strOf(l["location_id"]), strOf(l["location_name"]));
-        const propIdToName = new Map();
-        for (const p of asList(script["props"]))
-            propIdToName.set(strOf(p["prop_id"]), strOf(p["prop_name"]));
-        for (const scene of asList(scriptEp["scenes"])) {
-            const env = isDict(scene["environment"]) ? scene["environment"] : {};
-            const space = strOf(env["space"]) || "?";
-            const timeOfDay = strOf(env["time"]) || "?";
-            const sceneId = strOf(scene["scene_id"]) || "?";
-            let locName = "";
-            for (const ref of asList(scene["locations"])) {
-                locName = locationIdToName.get(strOf(ref["location_id"])) || locName;
-                break;
-            }
-            const actorNames = [];
-            for (const ref of asList(scene["actors"])) {
-                const n = actorIdToName.get(strOf(ref["actor_id"]));
-                if (n)
-                    actorNames.push(n);
-            }
-            const propNames = [];
-            for (const ref of asList(scene["props"])) {
-                const n = propIdToName.get(strOf(ref["prop_id"]));
-                if (n)
-                    propNames.push(n);
-            }
-            lines.push("");
-            lines.push(`Scene ${sceneId} [${space} ${timeOfDay}] ${locName || "(未知场景)"}`);
-            if (actorNames.length > 0)
-                lines.push(`  Actors: ${actorNames.join(", ")}`);
-            if (propNames.length > 0)
-                lines.push(`  Props:  ${propNames.join(", ")}`);
-            for (const action of asList(scene["actions"])) {
-                const kind = strOf(action["type"]);
-                const content = strOf(action["content"]).replace(/\n/g, "\n         ");
-                let tag;
-                if (kind === "dialogue") {
-                    const speaker = actorIdToName.get(strOf(action["actor_id"])) || speakerIdToName.get(strOf(action["speaker_id"])) || strOf(action["speaker"]) || "?";
-                    const emotion = strOf(action["emotion"]);
-                    tag = `dlg|${speaker}` + (emotion ? `|${emotion}` : "");
-                }
-                else if (kind === "inner_thought") {
-                    const speaker = actorIdToName.get(strOf(action["actor_id"])) || speakerIdToName.get(strOf(action["speaker_id"])) || strOf(action["speaker"]) || "?";
-                    const emotion = strOf(action["emotion"]);
-                    tag = `think|${speaker}` + (emotion ? `|${emotion}` : "");
-                }
-                else {
-                    tag = "act";
-                }
-                lines.push(`  [${tag}] ${content}`);
-            }
-        }
-    }
-    else {
-        lines.push("(script.initial.json contains no entry for this episode)");
-    }
-    if (scriptEp) {
-        const actorIdsInEp = new Set();
-        const locationIdsInEp = new Set();
-        const propIdsInEp = new Set();
-        for (const scene of asList(scriptEp["scenes"])) {
-            for (const ref of asList(scene["actors"])) {
-                if (ref["actor_id"])
-                    actorIdsInEp.add(strOf(ref["actor_id"]));
-            }
-            for (const ref of asList(scene["locations"])) {
-                if (ref["location_id"])
-                    locationIdsInEp.add(strOf(ref["location_id"]));
-            }
-            for (const ref of asList(scene["props"])) {
-                if (ref["prop_id"])
-                    propIdsInEp.add(strOf(ref["prop_id"]));
-            }
-            for (const action of asList(scene["actions"])) {
-                if (action["actor_id"])
-                    actorIdsInEp.add(strOf(action["actor_id"]));
-            }
-        }
-        if (actorIdsInEp.size > 0 || locationIdsInEp.size > 0 || propIdsInEp.size > 0) {
-            lines.push("");
-            lines.push(`--- Episode ${episodeNum} 资产 ---`);
-        }
-        if (actorIdsInEp.size > 0) {
-            lines.push("Actors:");
-            for (const actor of asList(script["actors"])) {
-                if (!actorIdsInEp.has(strOf(actor["actor_id"])))
-                    continue;
-                const desc = strOf(actor["description"]).trim() || "(无描述)";
-                const role = strOf(actor["role_type"]) || "?";
-                lines.push(`  - ${actor["actor_id"]} ${actor["actor_name"]} [${role}] — ${desc}`);
-            }
-        }
-        if (locationIdsInEp.size > 0) {
-            lines.push("Locations:");
-            for (const loc of asList(script["locations"])) {
-                if (!locationIdsInEp.has(strOf(loc["location_id"])))
-                    continue;
-                const desc = strOf(loc["description"]).trim() || "(无描述)";
-                lines.push(`  - ${loc["location_id"]} ${loc["location_name"]} — ${desc}`);
-            }
-        }
-        if (propIdsInEp.size > 0) {
-            lines.push("Props:");
-            for (const prop of asList(script["props"])) {
-                if (!propIdsInEp.has(strOf(prop["prop_id"])))
-                    continue;
-                const desc = strOf(prop["description"]).trim() || "(无描述)";
-                lines.push(`  - ${prop["prop_id"]} ${prop["prop_name"]} — ${desc}`);
-            }
-        }
-    }
-    return lines;
-}
-function renderAssetCurationSummary(curation) {
-    const summary = isDict(curation["summary"]) ? curation["summary"] : {};
-    const lines = [
-        `curation: ` +
-            `actors ${summary["actors_before"] ?? 0}->${summary["actors_after"] ?? 0} ` +
-            `(removed ${summary["actors_removed"] ?? 0}), ` +
-            `props ${summary["props_before"] ?? 0}->${summary["props_after"] ?? 0} ` +
-            `(removed ${summary["props_removed"] ?? 0}), ` +
-            `locations ${summary["locations_before"] ?? 0}->${summary["locations_after"] ?? 0} ` +
-            `(merged ${summary["locations_merged"] ?? 0})`,
-    ];
-    const coverage = isDict(summary["coverage"]) ? summary["coverage"] : {};
-    const required = isDict(coverage["required"]) ? coverage["required"] : {};
-    const auditSummary = isDict(curation["audit_summary"]) ? curation["audit_summary"] : {};
-    if (summary["explicit_keep_count"] !== undefined || auditSummary["audit_decisions"] !== undefined || required["prop"] !== undefined) {
-        lines.push(`curation coverage: ` +
-            `keep ${summary["explicit_keep_count"] ?? 0}, ` +
-            `implicit ${summary["implicit_keep_count"] ?? 0}, ` +
-            `audit ${auditSummary["audit_decisions"] ?? 0}, ` +
-            `required actor/location/prop ${required["actor"] ?? 0}/${required["location"] ?? 0}/${required["prop"] ?? 0}`);
-    }
-    for (const decision of asList(curation["decisions"])) {
-        if (!isDict(decision))
-            continue;
-        const action = strOf(decision["decision"]);
-        if (!action || action === "keep")
-            continue;
-        const kind = strOf(decision["kind"]);
-        const sourceId = strOf(decision["source_id"]);
-        const targetKind = strOf(decision["target_kind"]);
-        const targetId = strOf(decision["target_id"]);
-        const newName = strOf(decision["new_name"]);
-        const stateName = strOf(decision["state_name"]);
-        const speakerKind = strOf(decision["speaker_kind"]);
-        const target = targetId
-            ? ` -> ${targetKind || kind}:${targetId}`
-            : newName
-                ? ` -> ${newName}`
-                : stateName
-                    ? ` -> state:${stateName}`
-                    : speakerKind
-                        ? ` -> speaker:${speakerKind}`
-                        : "";
-        lines.push(`curation ${kind}:${sourceId} ${action}${target} — ${decision["reason"] || "-"}`);
-    }
-    for (const actor of asList(curation["actors"])) {
-        if (!isDict(actor) || actor["decision"] !== "remove")
-            continue;
-        lines.push(`curation actor ${actor["actor_id"]}: remove ${actor["name"] || "-"} (scenes=${actor["scene_count"] ?? 0}) — ${actor["reason"] || "-"}`);
-    }
-    for (const prop of asList(curation["props"])) {
-        if (!isDict(prop) || prop["decision"] !== "remove")
-            continue;
-        lines.push(`curation prop ${prop["prop_id"]}: remove ${prop["name"] || "-"} (scenes=${prop["scene_count"] ?? 0}) — ${prop["reason"] || "-"}`);
-    }
-    for (const loc of asList(curation["locations"])) {
-        if (!isDict(loc) || loc["decision"] !== "merge")
-            continue;
-        lines.push(`curation location ${loc["location_id"]}: merge ${loc["name"] || "-"} -> ${loc["target_location_id"] || "-"} — ${loc["reason"] || "-"}`);
-    }
-    return lines;
-}
-function renderStateBindingSummary(binding) {
-    const summary = isDict(binding["summary"]) ? binding["summary"] : {};
-    return [
-        `state-binding: ` +
-            `default-states synthesized ${summary["default_states_synthesized"] ?? 0}, ` +
-            `llm refs ${summary["llm_scene_refs_bound"] ?? 0}, ` +
-            `default refs ${summary["default_refs_bound"] ?? 0}, ` +
-            `unresolved ${summary["unresolved_stateful_refs"] ?? 0}, ` +
-            `state_changes ${summary["llm_state_changes_applied"] ?? 0}, ` +
-            `chunks ${summary["chunks"] ?? 0}`,
-    ];
-}
-function renderStateCurationSummary(curation) {
-    const summary = isDict(curation["summary"]) ? curation["summary"] : {};
-    const decisionSummary = isDict(summary["decisions"]) ? summary["decisions"] : {};
-    const lines = [
-        `state-curation: ` +
-            `states ${summary["states_before"] ?? 0}->${summary["states_after"] ?? 0} ` +
-            `(removed ${summary["states_removed"] ?? 0}), ` +
-            `actor/location/prop ${summary["actor_states_after"] ?? 0}/${summary["location_states_after"] ?? 0}/${summary["prop_states_after"] ?? 0}, ` +
-            `merge ${decisionSummary["merge"] ?? 0}, drop ${decisionSummary["drop"] ?? 0}, action ${decisionSummary["action_desc"] ?? 0}, rename ${decisionSummary["rename"] ?? 0}, ` +
-            `default-id ${summary["default_state_ids_rewritten"] ?? 0}, synthesized ${summary["default_states_synthesized"] ?? 0}`,
-    ];
-    for (const decision of asList(curation["decisions"])) {
-        if (!isDict(decision))
-            continue;
-        const action = strOf(decision["decision"]);
-        if (!action || action === "keep")
-            continue;
-        const kind = strOf(decision["kind"]);
-        const assetId = strOf(decision["asset_id"]);
-        const stateId = strOf(decision["state_id"]);
-        const target = action === "merge"
-            ? ` -> ${decision["target_state_id"] || "-"}`
-            : action === "rename"
-                ? ` -> ${decision["new_name"] || "-"}`
-                : "";
-        lines.push(`state-curation ${kind}:${assetId}/${stateId} ${action}${target} — ${decision["reason"] || "-"}`);
-    }
-    return lines;
-}
-function renderAssetNormalizationSummary(normalization) {
-    const summary = isDict(normalization["summary"]) ? normalization["summary"] : {};
-    const lines = [
-        `normalization: ` +
-            `merges ${summary["asset_merges"] ?? 0}, ` +
-            `location-states ${(Number(summary["location_states_from_names"] ?? 0) + Number(summary["location_states_from_time"] ?? 0))}, ` +
-            `review ${summary["review_items"] ?? 0}`,
-    ];
-    for (const decision of asList(normalization["decisions"])) {
-        if (!isDict(decision))
-            continue;
-        const action = strOf(decision["action"]);
-        if (action !== "canonical_merge" && action !== "location_state_from_name" && action !== "location_state_from_time")
-            continue;
-        lines.push(`normalization ${action}: ${decision["from"] || "-"} -> ${decision["into"] || "-"}${decision["state"] ? ` state=${decision["state"]}` : ""} — ${decision["reason"] || "-"}`);
-    }
-    return lines;
-}
-// Collect batch extraction failures (batch_results/<key>.error.json) keyed by
-// episode. Shared by both review views — these are direct-stage failures the
-// final-script `issues` query can't see.
-function collectBatchFailures(batchResultsDir) {
-    const byEpisode = new Map();
-    if (!exists(batchResultsDir))
-        return byEpisode;
-    const files = fs.readdirSync(batchResultsDir).filter((n) => n.endsWith(".error.json")).sort();
-    for (const name of files) {
-        try {
-            const error = readJson(path.join(batchResultsDir, name));
-            const episodeNum = Number(error["episode"] ?? 0);
-            if (!byEpisode.has(episodeNum))
-                byEpisode.set(episodeNum, []);
-            byEpisode.get(episodeNum).push(error);
-        }
-        catch {
-            // ignore unreadable error file
-        }
-    }
-    return byEpisode;
-}
-function parseEpisodeArg(episodeArg) {
-    try {
-        return episodeArg.split(",").map((s) => s.trim()).filter((s) => s).map((s) => {
-            const n = parseInt(s, 10);
-            if (Number.isNaN(n))
-                throw new Error("nan");
-            return n;
-        });
-    }
-    catch {
-        throw new CliError("REVIEW BLOCKED: --episode must be integers", "--episode must be integers.", {
-            exitCode: EXIT_USAGE,
-            required: ["--episode <n>[,<n>...]"],
-            received: [`--episode ${episodeArg}`],
-            nextSteps: ["Pass episode numbers like --episode 1,15,30."],
-        });
-    }
-}
-// ---------------------------------------------------------------------------
-// command_review — the direct-stage proofreading view. Read-only; no run_state
-// side effects. Two shapes:
-//   * `direct review`              workspace diagnostics: curation decisions +
-//                                  issues (validation + batch extraction errors)
-//   * `direct review --episode N`  per-episode source.txt ↔ script.initial.json
-//                                  side-by-side alignment (renderReviewEpisode)
-// Generic per-episode / per-asset listings live on the top-level `episodes` /
-// `assets` queries (use `--draft` to point them at script.initial.json).
-// ---------------------------------------------------------------------------
-export function commandReview(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const dd = directDir(workspace);
-    const scriptPath = path.join(dd, "script.initial.json");
-    const batchResultsDir = path.join(dd, "batch_results");
-    const episodeArg = strOf(opts["episode"]).trim();
-    // --episode: source ↔ extract alignment for the named episodes.
-    if (episodeArg) {
-        const episodeFilters = parseEpisodeArg(episodeArg);
-        const sourcePath = path.join(workspace, "source.txt");
-        if (!exists(sourcePath)) {
-            throw new CliError("REVIEW BLOCKED: source.txt not found", "source.txt not found.", {
-                exitCode: EXIT_INPUT,
-                required: [sourcePath],
-                received: ["source.txt missing"],
-                nextSteps: ["Run scriptctl direct init first."],
-            });
-        }
-        const script = exists(scriptPath)
-            ? readJson(scriptPath)
-            : { episodes: [], actors: [], locations: [], props: [] };
-        const sourceText = readText(sourcePath);
-        const episodePlanPath = path.join(dd, "episode_plan.json");
-        const episodePlan = exists(episodePlanPath) ? readJson(episodePlanPath) : { episodes: [] };
-        const lines = [];
-        for (let idx = 0; idx < episodeFilters.length; idx++) {
-            if (idx > 0) {
-                lines.push("");
-                lines.push("");
-            }
-            lines.push(...renderReviewEpisode(sourceText, episodePlan, script, episodeFilters[idx]));
-        }
-        const report = {
-            title: `DIRECT REVIEW: episode ${episodeFilters.join(",")}`,
-            result: lines.length > 0 ? lines : ["No matching items."],
-            artifacts: [path.join(workspace, "source.txt"), path.join(dd, "episode_plan.json"), scriptPath],
-            next: ["Edit with `--draft` (e.g. `scriptctl replace … --draft`) if the extraction is wrong, then validate/export."],
-        };
-        return [report, EXIT_OK];
-    }
-    // No --episode: workspace-level diagnostics. Curation decisions + every issue
-    // (validation issues recomputed live, plus batch extraction failures).
-    const lines = [];
-    const curationPath = path.join(dd, "asset_curation.json");
-    const stateCurationPath = path.join(dd, "state_curation.json");
-    const stateBindingPath = path.join(dd, "state_binding.json");
-    const normalizationPath = path.join(dd, "asset_normalization.json");
-    if (exists(normalizationPath)) {
-        const normalization = readJson(normalizationPath);
-        if (isDict(normalization))
-            lines.push(...renderAssetNormalizationSummary(normalization));
-    }
-    if (exists(curationPath)) {
-        const curation = readJson(curationPath);
-        if (isDict(curation))
-            lines.push(...renderAssetCurationSummary(curation));
-    }
-    if (exists(stateCurationPath)) {
-        const curation = readJson(stateCurationPath);
-        if (isDict(curation))
-            lines.push(...renderStateCurationSummary(curation));
-    }
-    if (exists(stateBindingPath)) {
-        const binding = readJson(stateBindingPath);
-        if (isDict(binding))
-            lines.push(...renderStateBindingSummary(binding));
-    }
-    const batchFailures = collectBatchFailures(batchResultsDir);
-    for (const errors of batchFailures.values()) {
-        for (const error of errors) {
-            lines.push(`error BATCH_FAILED: ${error["batch_id"]} episode ${error["episode"]} part ${error["part"]} - ${error["message"]}`);
-        }
-    }
-    // persist:false keeps review read-only — it must not overwrite validation.json
-    // (the help/comment promise "no state side effects").
-    const validation = exists(scriptPath)
-        ? validateScript(workspace, scriptPath, { requireSource: false, persist: false })
-        : { issues: [] };
-    for (const issue of asList(validation["issues"])) {
-        const whereParts = [];
-        for (const k of ["episode", "scene", "action_index"]) {
-            if (issue[k] !== null && issue[k] !== undefined)
-                whereParts.push(strOf(issue[k]));
-        }
-        const where = whereParts.join(" ");
-        lines.push(`${issue["severity"]} ${issue["code"]}: ${issue["summary"]}${where ? ` [${where}]` : ""}`);
-    }
-    const report = {
-        title: "DIRECT REVIEW",
-        result: lines.length > 0 ? lines : ["No issues, curation decisions, or batch failures to review."],
-        artifacts: [scriptPath, normalizationPath, path.join(dd, "asset_grouping.json"), path.join(dd, "asset_curation.json"), stateCurationPath, stateBindingPath, batchResultsDir],
-        next: [
-            "Run `direct review --episode <n>` for source↔extract alignment.",
-            "Edit with `--draft` (e.g. `scriptctl rename … --draft`), then validate/export.",
-        ],
-    };
-    return [report, EXIT_OK];
-}
-//# sourceMappingURL=direct.js.map