@lingjingai/scriptctl 0.1.0

package/dist/usecases/direct.js

@@ -0,0 +1,1679 @@
+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_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, DIRECT_CONTRACT_VERSION, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, REVIEW_TARGETS, SUPPORTED_EXTS, deletePath, deleteTree, directDir, exists, fmtId, readJson, readText, sha256Text, writeJson, } from "../common.js";
+import { compactBatchResult, compactEpisodeResult, buildBatchPlan, buildEpisodePlan, enrichEpisodePlanTitles, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, normalizeInt, recoverBatchFromSource, uniqueAdd, validateBatchExtractionQuality, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
+import { validateScript } from "../domain/script-core.js";
+import { makeProvider } from "../infra/providers.js";
+import { makeSourceManifest, prepareSource, } from "../infra/converters.js";
+function strOf(v) {
+    if (v === null || v === undefined)
+        return "";
+    return String(v);
+}
+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");
+}
+// ---------------------------------------------------------------------------
+// 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 = {};
+        }
+    }
+    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 failureSignature(items) {
+    if (!isList(items))
+        return [];
+    const out = [];
+    for (const item of items) {
+        const s = strOf(item).trim();
+        if (s)
+            out.push(s);
+    }
+    out.sort();
+    return out;
+}
+export function addInspectedTarget(workspace, target) {
+    const state = readRunState(workspace);
+    const targets = [];
+    for (const item of asList(state["inspected_targets"])) {
+        const s = strOf(item);
+        if (s)
+            targets.push(s);
+    }
+    if (!targets.includes(target))
+        targets.push(target);
+    const missing = [];
+    for (const t of REVIEW_TARGETS) {
+        if (!targets.includes(t))
+            missing.push(t);
+    }
+    const reviewStatus = missing.length === 0 ? "reviewed" : "in_progress";
+    return updateRunState(workspace, {
+        inspected_targets: targets,
+        review_status: reviewStatus,
+        review_missing: missing,
+        last_inspect_target: target,
+    });
+}
+export function markPatched(workspace, count) {
+    const state = readRunState(workspace);
+    const patchCount = Number(state["patch_count"] ?? 0) + count;
+    return updateRunState(workspace, {
+        patch_count: patchCount,
+        review_status: "patched",
+        review_missing: [],
+    });
+}
+export function markMetadataConfidenceReviewed(workspace, operations) {
+    const metadataOps = new Set(["set_worldview", "set_actor_role_type", "set_asset_description"]);
+    if (!operations.some((op) => isDict(op) && metadataOps.has(strOf(op["op"]))))
+        return;
+    const p = path.join(directDir(workspace), "asset_metadata.json");
+    if (!exists(p))
+        return;
+    let metadata;
+    try {
+        metadata = readJson(p);
+    }
+    catch {
+        return;
+    }
+    if (!isDict(metadata) || metadata["confidence"] !== "low")
+        return;
+    metadata["confidence"] = "medium";
+    metadata["confidence_reviewed_at"] = checkpointTimestamp();
+    writeJson(p, metadata);
+}
+export function reviewBlockers(state) {
+    if (Number(state["patch_count"] ?? 0) > 0)
+        return [];
+    const inspected = new Set();
+    for (const item of asList(state["inspected_targets"])) {
+        const s = strOf(item);
+        if (s)
+            inspected.add(s);
+    }
+    return REVIEW_TARGETS.filter((t) => !inspected.has(t));
+}
+// ---------------------------------------------------------------------------
+// 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"]))}`;
+}
+function episodeResultsIndexPath(dir) {
+    return path.join(dir, "index.json");
+}
+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 batchResultsIndexPath(dir) {
+    return path.join(dir, "index.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);
+    }
+}
+function readBatchResultsIndex(dir) {
+    const p = batchResultsIndexPath(dir);
+    if (!exists(p))
+        return { version: 1, batches: {} };
+    let data;
+    try {
+        data = readJson(p);
+    }
+    catch {
+        return { version: 1, batches: {} };
+    }
+    if (!isDict(data))
+        return { version: 1, batches: {} };
+    if (!isDict(data["batches"]))
+        data["batches"] = {};
+    if (!("version" in data))
+        data["version"] = 1;
+    return data;
+}
+function writeBatchResultsIndex(dir, index) {
+    writeJson(batchResultsIndexPath(dir), index);
+}
+function updateBatchResultMetadata(dir, batch, providerName, model) {
+    const index = readBatchResultsIndex(dir);
+    const batches = index["batches"] ?? {};
+    batches[batchResultKey(batch)] = {
+        episode: Number(batch["episode"]),
+        part: Number(batch["part"]),
+        provider: providerName,
+        model,
+        extracted_at: checkpointTimestamp(),
+    };
+    index["batches"] = batches;
+    writeBatchResultsIndex(dir, index);
+}
+function removeBatchResultMetadata(dir, batch) {
+    const index = readBatchResultsIndex(dir);
+    const batches = index["batches"] ?? {};
+    const key = batchResultKey(batch);
+    if (key in batches) {
+        delete batches[key];
+        index["batches"] = batches;
+        writeBatchResultsIndex(dir, index);
+    }
+}
+function readEpisodeResultsIndex(dir) {
+    const p = episodeResultsIndexPath(dir);
+    if (!exists(p))
+        return { version: 1, episodes: {} };
+    let data;
+    try {
+        data = readJson(p);
+    }
+    catch {
+        return { version: 1, episodes: {} };
+    }
+    if (!isDict(data))
+        return { version: 1, episodes: {} };
+    if (!isDict(data["episodes"]))
+        data["episodes"] = {};
+    if (!("version" in data))
+        data["version"] = 1;
+    return data;
+}
+function writeEpisodeResultsIndex(dir, index) {
+    writeJson(episodeResultsIndexPath(dir), index);
+}
+function updateEpisodeResultMetadata(dir, ep, providerName, model) {
+    const index = readEpisodeResultsIndex(dir);
+    const episodes = index["episodes"] ?? {};
+    episodes[episodeResultKey(ep)] = {
+        provider: providerName,
+        model,
+        extracted_at: checkpointTimestamp(),
+    };
+    index["episodes"] = episodes;
+    writeEpisodeResultsIndex(dir, index);
+}
+function removeEpisodeResultMetadata(dir, ep) {
+    const index = readEpisodeResultsIndex(dir);
+    const episodes = index["episodes"] ?? {};
+    const key = episodeResultKey(ep);
+    if (key in episodes) {
+        delete episodes[key];
+        index["episodes"] = episodes;
+        writeEpisodeResultsIndex(dir, index);
+    }
+}
+function compactResultHasMultiRefs(data) {
+    for (const scene of asList(data["sc"])) {
+        if (!isDict(scene))
+            continue;
+        for (const action of asList(scene["a"])) {
+            if (!isDict(action))
+                continue;
+            const refs = action["r"];
+            if (isList(refs) && refs.length > 1)
+                return true;
+        }
+    }
+    return false;
+}
+function initCheckpoint(sourceText, plan) {
+    const planText = JSON.stringify(plan, sortedReplacer(plan));
+    return {
+        contract_version: DIRECT_CONTRACT_VERSION,
+        source_sha256: sha256Text(sourceText),
+        episode_plan_sha256: sha256Text(planText),
+        total_episodes: Number(plan["total_episodes"] ?? asList(plan["episodes"]).length),
+    };
+}
+function initBatchCheckpoint(sourceText, batchPlan) {
+    const planText = JSON.stringify(batchPlan, sortedReplacer(batchPlan));
+    return {
+        contract_version: DIRECT_CONTRACT_VERSION,
+        source_sha256: sha256Text(sourceText),
+        batch_plan_sha256: sha256Text(planText),
+        total_batches: Number(batchPlan["total_batches"] ?? asList(batchPlan["batches"]).length),
+    };
+}
+function sortedReplacer(_root) {
+    // Python's json.dumps(sort_keys=True) sorts keys recursively. Replicate by walking and sorting.
+    return function (key, value) {
+        if (isDict(value)) {
+            const sorted = {};
+            for (const k of Object.keys(value).sort())
+                sorted[k] = value[k];
+            return sorted;
+        }
+        return value;
+    };
+}
+function checkpointSourceMatches(previous, current) {
+    if (!previous || Object.keys(previous).length === 0)
+        return false;
+    const keys = ["contract_version", "source_sha256", "episode_plan_sha256", "total_episodes"];
+    return keys.every((k) => previous[k] === current[k]);
+}
+function batchCheckpointMatches(previous, current) {
+    if (!previous || Object.keys(previous).length === 0)
+        return false;
+    const keys = ["contract_version", "source_sha256", "batch_plan_sha256", "total_batches"];
+    return keys.every((k) => previous[k] === current[k]);
+}
+function resetInitOutputs(dd) {
+    for (const dirname of ["episode_results", "batch_results"]) {
+        const target = path.join(dd, dirname);
+        if (exists(target))
+            deleteTree(target);
+    }
+    for (const name of ["script.initial.json", "validation.json", "batch_plan.json", "asset_curation.json", "asset_metadata.json"]) {
+        const p = path.join(dd, name);
+        if (exists(p))
+            deletePath(p);
+    }
+}
+function resetBatchOutputs(dd) {
+    const batchResultsDir = path.join(dd, "batch_results");
+    if (exists(batchResultsDir))
+        deleteTree(batchResultsDir);
+}
+function loadCheckpointedEpisode(sourceText, episodeResultsDir, ep, providerName, model, previousProvider) {
+    const p = episodeResultPath(episodeResultsDir, ep);
+    if (!exists(p))
+        return null;
+    let result;
+    try {
+        const data = readJson(p);
+        const metadata = isDict(data["_scriptctl"]) ? data["_scriptctl"] : {};
+        const index = readEpisodeResultsIndex(episodeResultsDir);
+        let indexEntry = {};
+        const eps = index["episodes"];
+        if (isDict(eps)) {
+            const entry = eps[episodeResultKey(ep)];
+            if (isDict(entry))
+                indexEntry = entry;
+        }
+        const resultProvider = strOf(metadata["provider"] || indexEntry["provider"] || previousProvider).trim();
+        if (providerName && resultProvider && resultProvider !== providerName) {
+            throw new Error(`checkpoint provider mismatch: ${resultProvider} != ${providerName}`);
+        }
+        result = normalizeEpisodeResult(data, ep);
+        validateEpisodeExtractionQuality(sourceText, ep, result);
+        if (!("sc" in data) || ["episode", "title", "source_span", "_scriptctl"].some((k) => k in data)) {
+            writeJson(p, compactEpisodeResult(result));
+            if (providerName && model)
+                updateEpisodeResultMetadata(episodeResultsDir, ep, providerName, model);
+        }
+    }
+    catch {
+        try {
+            deletePath(p);
+        }
+        catch {
+            // ignore
+        }
+        removeEpisodeResultMetadata(episodeResultsDir, ep);
+        return null;
+    }
+    if (Number(result["episode"] ?? 0) !== Number(ep["episode"]))
+        return null;
+    if (JSON.stringify(result["source_span"]) !== JSON.stringify(ep["source_span"]))
+        return null;
+    return result;
+}
+function loadCheckpointedBatch(sourceText, batchResultsDir, batch, providerName, model, previousProvider) {
+    const p = batchResultPath(batchResultsDir, batch);
+    if (!exists(p))
+        return null;
+    let result;
+    try {
+        const data = readJson(p);
+        const index = readBatchResultsIndex(batchResultsDir);
+        let indexEntry = {};
+        const batches = index["batches"];
+        if (isDict(batches)) {
+            const entry = batches[batchResultKey(batch)];
+            if (isDict(entry))
+                indexEntry = entry;
+        }
+        const resultProvider = strOf(indexEntry["provider"] || previousProvider).trim();
+        if (providerName && resultProvider && resultProvider !== providerName) {
+            throw new Error(`checkpoint provider mismatch: ${resultProvider} != ${providerName}`);
+        }
+        result = normalizeEpisodeResult(data, batch);
+        validateBatchExtractionQuality(sourceText, batch, result);
+        if (!("sc" in data) || compactResultHasMultiRefs(data) || ["episode", "title", "source_span", "_scriptctl"].some((k) => k in data)) {
+            persistBatchResult(batchResultsDir, batch, result);
+            if (providerName && model)
+                updateBatchResultMetadata(batchResultsDir, batch, providerName, model);
+        }
+    }
+    catch {
+        try {
+            deletePath(p);
+        }
+        catch {
+            // ignore
+        }
+        removeBatchResultMetadata(batchResultsDir, batch);
+        return null;
+    }
+    if (Number(result["episode"] ?? 0) !== Number(batch["episode"]))
+        return null;
+    if (JSON.stringify(result["source_span"]) !== JSON.stringify(batch["source_span"]))
+        return null;
+    return result;
+}
+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"]));
+}
+function mergeBatchResultsForEpisode(episode, batchResults) {
+    const scenes = [];
+    const actors = [];
+    const locations = [];
+    const props = [];
+    const sorted = [...batchResults].sort((a, b) => Number(a["_batch_part"] ?? 0) - Number(b["_batch_part"] ?? 0));
+    for (const item of sorted) {
+        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);
+        }
+    }
+    const result = {
+        episode: Number(episode["episode"]),
+        title: episode["title"],
+        source_span: episode["source_span"],
+        scenes,
+        actors,
+        locations,
+        props,
+    };
+    return normalizeEpisodeResult(result, episode);
+}
+async function providerExtractAssetCurationLocal(provider, sourceText, script) {
+    if (provider.extractAssetCuration) {
+        const payload = await provider.extractAssetCuration(sourceText, script);
+        return isDict(payload) ? payload : {};
+    }
+    return {};
+}
+function writeEpisodeFailure(dir, ep, exc) {
+    const err = exc;
+    const error = {
+        episode: Number(ep["episode"]),
+        title: ep["title"],
+        source_span: ep["source_span"],
+        error_type: err?.name || "Error",
+        message: (err?.message || err?.name || "Error").slice(0, 500),
+        failed_at: checkpointTimestamp(),
+    };
+    if (exc instanceof CliError) {
+        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 = episodeResultPath(dir, ep);
+    if (exists(resultPath))
+        deletePath(resultPath);
+    removeEpisodeResultMetadata(dir, ep);
+    writeJson(episodeErrorPath(dir, ep), error);
+    return error;
+}
+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.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);
+    removeBatchResultMetadata(dir, batch);
+    writeJson(batchErrorPath(dir, batch), error);
+    return error;
+}
+function initFailedReport(workspace, opts) {
+    const payload = {
+        status: "init_failed",
+        command: "direct init",
+        init_stage: opts.stage,
+        last_error: { title: opts.title, received: opts.received, failed_at: checkpointTimestamp() },
+    };
+    if (opts.updates)
+        Object.assign(payload, opts.updates);
+    updateRunState(workspace, payload);
+    return new CliError(opts.title, opts.title, {
+        exitCode: opts.exitCode ?? EXIT_RUNTIME,
+        required: opts.required,
+        received: opts.received,
+        nextSteps: opts.nextSteps,
+    });
+}
+// ---------------------------------------------------------------------------
+// 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;
+}
+// ---------------------------------------------------------------------------
+// command_init
+// ---------------------------------------------------------------------------
+export async function commandInit(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 || process.env.ANTHROPIC_MODEL || DEFAULT_MODEL);
+    let concurrency;
+    try {
+        concurrency = parseInt(strOf(opts["concurrency"] || DEFAULT_CONCURRENCY), 10);
+        if (Number.isNaN(concurrency))
+            throw new Error("nan");
+    }
+    catch {
+        throw new CliError("USAGE ERROR: Invalid concurrency", "Invalid concurrency.", {
+            exitCode: EXIT_USAGE,
+            required: ["--concurrency: positive integer"],
+            received: [`--concurrency: ${opts["concurrency"]}`],
+            nextSteps: ["Use a positive integer and rerun init."],
+        });
+    }
+    if (concurrency < 1) {
+        throw new CliError("USAGE ERROR: Invalid concurrency", "Invalid concurrency.", {
+            exitCode: EXIT_USAGE,
+            required: ["--concurrency: positive integer"],
+            received: [`--concurrency: ${concurrency}`],
+            nextSteps: ["Use a positive integer and rerun init."],
+        });
+    }
+    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],
+    ]) {
+        let value;
+        try {
+            value = parseInt(strOf(opts[optName] || defaultValue), 10);
+            if (Number.isNaN(value))
+                throw new Error("nan");
+        }
+        catch {
+            throw new CliError("USAGE ERROR: Invalid batch option", "Invalid batch option.", {
+                exitCode: EXIT_USAGE,
+                required: [`--${optName.replace(/_/g, "-")}: positive integer`],
+                received: [`--${optName.replace(/_/g, "-")}: ${opts[optName]}`],
+                nextSteps: ["Use positive integers for batch options and rerun init."],
+            });
+        }
+        if (value < 1) {
+            throw new CliError("USAGE ERROR: Invalid batch option", "Invalid batch option.", {
+                exitCode: EXIT_USAGE,
+                required: [`--${optName.replace(/_/g, "-")}: positive integer`],
+                received: [`--${optName.replace(/_/g, "-")}: ${value}`],
+                nextSteps: ["Use positive integers for batch options and rerun init."],
+            });
+        }
+        batchValues[optName] = value;
+    }
+    const batchTargetLines = batchValues["batch_target_lines"];
+    const batchMaxChars = batchValues["batch_max_chars"];
+    const batchMinLines = Math.min(batchValues["batch_min_lines"], batchTargetLines);
+    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."],
+        });
+    }
+    const dd = directDir(workspace);
+    fs.mkdirSync(dd, { recursive: true });
+    const previousStateBeforeInit = readRunState(workspace);
+    updateRunState(workspace, {
+        status: "init_running",
+        command: "direct init",
+        init_stage: "source_prepare",
+        provider: providerName,
+        model,
+        concurrency,
+        source_path: path.resolve(source),
+    });
+    let info;
+    try {
+        info = await prepareSource(source, workspace);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            updateRunState(workspace, {
+                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}` : ""}`;
+        updateRunState(workspace, {
+            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"]);
+    const sourceText = readText(sourceTextPath);
+    const manifest = makeSourceManifest(source, sourceTextPath, info);
+    updateRunState(workspace, { status: "init_running", init_stage: "episode_plan" });
+    let plan;
+    try {
+        plan = buildEpisodePlan(sourceText);
+    }
+    catch (exc) {
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Episode planning failed",
+            stage: "episode_plan",
+            required: ["source.txt that can be split into episodes"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Inspect workspace/source.txt, fix the source file, and rerun init."],
+        });
+    }
+    updateRunState(workspace, { status: "init_running", init_stage: "provider" });
+    let provider;
+    try {
+        provider = makeProvider(providerName, model);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            updateRunState(workspace, {
+                status: "init_failed",
+                init_stage: "provider",
+                last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
+            });
+        }
+        throw exc;
+    }
+    updateRunState(workspace, { status: "init_running", init_stage: "episode_titles" });
+    try {
+        plan = await enrichEpisodePlanTitles(sourceText, plan, provider);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            throw initFailedReport(workspace, {
+                title: exc.title,
+                stage: "episode_titles",
+                exitCode: exc.exitCode,
+                required: exc.required.length > 0 ? exc.required : ["episode titles generated from source text"],
+                received: exc.received.length > 0 ? exc.received : [String(exc.message).slice(0, 160)],
+                nextSteps: exc.nextSteps.length > 0 ? exc.nextSteps : ["Rerun init after checking source episode headers."],
+            });
+        }
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Episode title planning failed",
+            stage: "episode_titles",
+            required: ["episode titles generated from source text"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Inspect workspace/source.txt and episode_plan.json, then rerun init."],
+        });
+    }
+    let batchPlan;
+    try {
+        batchPlan = buildBatchPlan(sourceText, plan, {
+            targetLines: batchTargetLines,
+            maxChars: batchMaxChars,
+            minLines: batchMinLines,
+            mode: batchMode,
+        });
+    }
+    catch (exc) {
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Batch planning failed",
+            stage: "batch_plan",
+            required: ["episode_plan.json that can be split into natural paragraph batches"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Inspect workspace/source.txt and episode_plan.json, then rerun init."],
+        });
+    }
+    const checkpoint = initCheckpoint(sourceText, plan);
+    const batchCheckpoint = initBatchCheckpoint(sourceText, batchPlan);
+    const previousState = previousStateBeforeInit;
+    const previousCheckpoint = isDict(previousState["checkpoint"]) ? previousState["checkpoint"] : {};
+    const previousBatchCheckpoint = isDict(previousState["batch_checkpoint"]) ? previousState["batch_checkpoint"] : {};
+    const checkpointReused = checkpointSourceMatches(previousCheckpoint, checkpoint);
+    const batchCheckpointReused = checkpointReused && batchCheckpointMatches(previousBatchCheckpoint, batchCheckpoint);
+    if (!checkpointReused)
+        resetInitOutputs(dd);
+    else if (!batchCheckpointReused)
+        resetBatchOutputs(dd);
+    writeJson(path.join(dd, "source_manifest.json"), manifest);
+    writeJson(path.join(dd, "episode_plan.json"), plan);
+    writeJson(path.join(dd, "batch_plan.json"), batchPlan);
+    const episodeResultsDir = path.join(dd, "episode_results");
+    const batchResultsDir = path.join(dd, "batch_results");
+    fs.mkdirSync(episodeResultsDir, { recursive: true });
+    fs.mkdirSync(batchResultsDir, { recursive: true });
+    updateRunState(workspace, {
+        status: "init_running",
+        init_stage: "batch_extract",
+        checkpoint,
+        batch_checkpoint: batchCheckpoint,
+        checkpoint_reused: checkpointReused,
+        batch_checkpoint_reused: batchCheckpointReused,
+        batch_mode: batchMode,
+        batch_target_lines: batchTargetLines,
+        batch_max_chars: batchMaxChars,
+        batch_min_lines: batchMinLines,
+        episode_total: asList(plan["episodes"]).length,
+        batch_total: asList(batchPlan["batches"]).length,
+    });
+    const results = [];
+    const skipped = [];
+    let skippedEpisodeBatchCount = 0;
+    const pendingBatches = [];
+    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);
+    }
+    const previousProvider = strOf(previousState["provider"]).trim() || null;
+    for (const episode of asList(plan["episodes"])) {
+        const cached = checkpointReused
+            ? loadCheckpointedEpisode(sourceText, episodeResultsDir, episode, providerName, model, previousProvider)
+            : null;
+        if (cached !== null) {
+            results.push(cached);
+            skipped.push(Number(episode["episode"]));
+            const cachedBatches = batchesByEpisode.get(Number(episode["episode"])) ?? [];
+            skippedEpisodeBatchCount += cachedBatches.length;
+            for (const cachedBatch of cachedBatches) {
+                if (!exists(batchResultPath(batchResultsDir, cachedBatch))) {
+                    const backfilled = recoverBatchFromSource(sourceText, cachedBatch);
+                    persistBatchResult(batchResultsDir, cachedBatch, backfilled);
+                    updateBatchResultMetadata(batchResultsDir, cachedBatch, providerName, model);
+                }
+                const errorPath = batchErrorPath(batchResultsDir, cachedBatch);
+                if (exists(errorPath))
+                    deletePath(errorPath);
+            }
+        }
+        else {
+            pendingBatches.push(...(batchesByEpisode.get(Number(episode["episode"])) ?? []));
+        }
+    }
+    const batchResults = [];
+    const skippedBatches = [];
+    const pending = [];
+    for (const batch of pendingBatches) {
+        const cachedBatch = batchCheckpointReused
+            ? loadCheckpointedBatch(sourceText, batchResultsDir, batch, providerName, model, previousProvider)
+            : null;
+        if (cachedBatch !== null) {
+            cachedBatch["_batch_id"] = batchResultKey(batch);
+            cachedBatch["_batch_part"] = Number(batch["part"]);
+            cachedBatch["_starts_inside_scene"] = Boolean(batch["starts_inside_scene"]);
+            batchResults.push(cachedBatch);
+            skippedBatches.push(batchResultKey(batch));
+        }
+        else {
+            pending.push(batch);
+        }
+    }
+    const failures = [];
+    const outcomes = await pMapWithConcurrency(pending, concurrency, async (batch) => {
+        return await extractBatchWithRecovery(provider, sourceText, batch);
+    });
+    for (let i = 0; i < outcomes.length; i++) {
+        const outcome = outcomes[i];
+        const batch = pending[i];
+        const errorPath = batchErrorPath(batchResultsDir, batch);
+        if (outcome.ok) {
+            const result = outcome.value;
+            result["_batch_id"] = batchResultKey(batch);
+            result["_batch_part"] = Number(batch["part"]);
+            result["_starts_inside_scene"] = Boolean(batch["starts_inside_scene"]);
+            batchResults.push(result);
+            persistBatchResult(batchResultsDir, batch, result);
+            updateBatchResultMetadata(batchResultsDir, batch, providerName, model);
+            if (exists(errorPath))
+                deletePath(errorPath);
+        }
+        else {
+            failures.push(writeBatchFailure(batchResultsDir, batch, outcome.error));
+        }
+    }
+    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
+    batchResults.sort((a, b) => {
+        const ea = Number(a["episode"] ?? 0);
+        const eb = Number(b["episode"] ?? 0);
+        if (ea !== eb)
+            return ea - eb;
+        return Number(a["_batch_part"] ?? 0) - Number(b["_batch_part"] ?? 0);
+    });
+    failures.sort((a, b) => {
+        const ea = Number(a["episode"] ?? 0);
+        const eb = Number(b["episode"] ?? 0);
+        if (ea !== eb)
+            return ea - eb;
+        return Number(a["part"] ?? 0) - Number(b["part"] ?? 0);
+    });
+    const completedBatches = skippedEpisodeBatchCount + batchResults.length;
+    if (failures.length > 0) {
+        const failedEpisodes = [...new Set(failures.map((it) => Number(it["episode"])))].sort((a, b) => a - b);
+        const failedBatches = failures.map((it) => strOf(it["batch_id"]));
+        const currentFailureSignature = failureSignature(failedBatches);
+        const previousFailureSignature = failureSignature(previousState["failed_batches"]);
+        const sameFailuresRepeated = checkpointReused &&
+            batchCheckpointReused &&
+            currentFailureSignature.length > 0 &&
+            currentFailureSignature.length === previousFailureSignature.length &&
+            currentFailureSignature.every((v, idx) => v === previousFailureSignature[idx]) &&
+            ["init_incomplete", "init_stalled"].includes(strOf(previousState["status"]));
+        const previousFailureStreak = normalizeInt(previousState["failure_streak"], 0);
+        const failureStreak = sameFailuresRepeated ? previousFailureStreak + 1 : 1;
+        const failureTitle = sameFailuresRepeated
+            ? "INIT STALLED: Same batches keep failing"
+            : "INIT INCOMPLETE: Batch extraction failed";
+        const nextSteps = sameFailuresRepeated
+            ? [
+                "Run direct inspect --target issue to read failed batch details.",
+                "Do not rerun the same init command again until source, batch options, provider, or failed content has changed.",
+            ]
+            : [
+                "Run direct inspect --target issue to review failed batches.",
+                "Rerun the same init once if failures look transient; completed checkpoints will be reused.",
+            ];
+        const failedEpisodeSet = new Set(failedEpisodes);
+        const skippedSet = new Set(skipped);
+        const batchResultsByEpisode = new Map();
+        for (const result of batchResults) {
+            const ep = Number(result["episode"] ?? 0);
+            if (!batchResultsByEpisode.has(ep))
+                batchResultsByEpisode.set(ep, []);
+            batchResultsByEpisode.get(ep).push(result);
+        }
+        for (const episode of asList(plan["episodes"])) {
+            const episodeNum = Number(episode["episode"]);
+            if (skippedSet.has(episodeNum) || failedEpisodeSet.has(episodeNum))
+                continue;
+            const expectedBatches = (batchesByEpisode.get(episodeNum) ?? []).length;
+            if (expectedBatches && (batchResultsByEpisode.get(episodeNum) ?? []).length === expectedBatches) {
+                const result = mergeBatchResultsForEpisode(episode, batchResultsByEpisode.get(episodeNum) ?? []);
+                validateEpisodeExtractionQuality(sourceText, episode, result);
+                results.push(result);
+                writeJson(episodeResultPath(episodeResultsDir, episode), compactEpisodeResult(result));
+                updateEpisodeResultMetadata(episodeResultsDir, episode, providerName, model);
+            }
+        }
+        updateRunState(workspace, {
+            status: sameFailuresRepeated ? "init_stalled" : "init_incomplete",
+            init_stage: "batch_extract",
+            checkpoint,
+            batch_checkpoint: batchCheckpoint,
+            episode_total: asList(plan["episodes"]).length,
+            episode_completed: results.length,
+            episode_reused: skipped.length,
+            episode_failed: failedEpisodes.length,
+            failed_episodes: failedEpisodes,
+            batch_total: asList(batchPlan["batches"]).length,
+            batch_completed: completedBatches,
+            batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
+            batch_failed: failures.length,
+            failed_batches: failedBatches,
+            failure_signature: currentFailureSignature,
+            failure_streak: failureStreak,
+            last_error: { title: failureTitle, failed_at: checkpointTimestamp() },
+            exportable: false,
+        });
+        const issues = failures.slice(0, 5).map((it) => `${it["batch_id"]} episode ${it["episode"]} part ${it["part"]}: ${it["error_type"]} - ${it["message"]}`);
+        const report = {
+            title: failureTitle,
+            result: [
+                `episodes total: ${asList(plan["episodes"]).length}`,
+                `completed: ${results.length}`,
+                `reused: ${skipped.length}`,
+                `failed episodes: ${failedEpisodes.length}`,
+                `batches: ${completedBatches}/${asList(batchPlan["batches"]).length} completed, ${failures.length} failed`,
+                `provider: ${providerName}`,
+            ],
+            artifacts: [
+                path.join(workspace, "source.txt"),
+                path.join(dd, "source_manifest.json"),
+                path.join(dd, "episode_plan.json"),
+                path.join(dd, "batch_plan.json"),
+                batchResultsDir,
+                episodeResultsDir,
+                path.join(dd, "run_state.json"),
+            ],
+            issues,
+            next: nextSteps,
+        };
+        return [report, EXIT_RUNTIME];
+    }
+    updateRunState(workspace, {
+        status: "init_running",
+        init_stage: "episode_merge",
+        checkpoint,
+        batch_checkpoint: batchCheckpoint,
+        episode_total: asList(plan["episodes"]).length,
+        episode_completed: results.length,
+        episode_reused: skipped.length,
+        episode_failed: 0,
+        failed_episodes: [],
+        batch_total: asList(batchPlan["batches"]).length,
+        batch_completed: completedBatches,
+        batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
+        batch_failed: 0,
+        failed_batches: [],
+        failure_signature: [],
+        failure_streak: 0,
+        last_error: null,
+    });
+    for (const dir of [batchResultsDir, episodeResultsDir]) {
+        if (!exists(dir))
+            continue;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.endsWith(".error.json")) {
+                try {
+                    deletePath(path.join(dir, name));
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+    }
+    try {
+        const batchResultsByEpisode = new Map();
+        for (const result of batchResults) {
+            const ep = Number(result["episode"] ?? 0);
+            if (!batchResultsByEpisode.has(ep))
+                batchResultsByEpisode.set(ep, []);
+            batchResultsByEpisode.get(ep).push(result);
+        }
+        const skippedSet = new Set(skipped);
+        for (const episode of asList(plan["episodes"])) {
+            const episodeNum = Number(episode["episode"]);
+            if (skippedSet.has(episodeNum))
+                continue;
+            const result = mergeBatchResultsForEpisode(episode, batchResultsByEpisode.get(episodeNum) ?? []);
+            validateEpisodeExtractionQuality(sourceText, episode, result);
+            results.push(result);
+            writeJson(episodeResultPath(episodeResultsDir, episode), compactEpisodeResult(result));
+            updateEpisodeResultMetadata(episodeResultsDir, episode, providerName, model);
+            const errorPath = episodeErrorPath(episodeResultsDir, episode);
+            if (exists(errorPath))
+                deletePath(errorPath);
+        }
+    }
+    catch (exc) {
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Episode merge failed",
+            stage: "episode_merge",
+            required: ["complete batch_results/*.json that can merge into episode_results/*.json"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Rerun init; completed batch checkpoints will be reused and episode merge will retry."],
+            updates: { checkpoint, batch_checkpoint: batchCheckpoint, batch_completed: completedBatches },
+        });
+    }
+    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
+    let script;
+    try {
+        updateRunState(workspace, { status: "init_running", init_stage: "script_merge", checkpoint, batch_checkpoint: batchCheckpoint });
+        script = mergeEpisodeResults(results, strOf(info["projectName"]) || path.basename(source, path.extname(source)));
+    }
+    catch (exc) {
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Merge failed",
+            stage: "script_merge",
+            required: ["complete episode_results/*.json"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Rerun init; completed episode extraction checkpoints will be reused and merge will retry."],
+            updates: { checkpoint, batch_checkpoint: batchCheckpoint, episode_completed: results.length },
+        });
+    }
+    try {
+        updateRunState(workspace, { status: "init_running", init_stage: "asset_curation", checkpoint, batch_checkpoint: batchCheckpoint });
+        const rawCuration = await providerExtractAssetCurationLocal(provider, sourceText, script);
+        const curation = curateScriptAssets(script, rawCuration);
+        writeJson(path.join(dd, "asset_curation.json"), curation);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            throw initFailedReport(workspace, {
+                title: exc.title,
+                stage: "asset_curation",
+                exitCode: exc.exitCode,
+                required: exc.required.length > 0 ? exc.required : ["asset curation 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 asset curation will retry."],
+                updates: { checkpoint, batch_checkpoint: batchCheckpoint, episode_completed: results.length },
+            });
+        }
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Asset curation failed",
+            stage: "asset_curation",
+            required: ["provider location merge decisions and deterministic asset reuse curation"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Rerun init; extraction checkpoints will be reused and asset curation will retry."],
+            updates: { checkpoint, batch_checkpoint: batchCheckpoint, episode_completed: results.length },
+        });
+    }
+    try {
+        updateRunState(workspace, { status: "init_running", init_stage: "metadata_extract", checkpoint, batch_checkpoint: batchCheckpoint });
+        let metadata = provider.extractMetadata ? await provider.extractMetadata(sourceText, script) : {};
+        if (!isDict(metadata))
+            metadata = {};
+        writeJson(path.join(dd, "asset_metadata.json"), metadata);
+        applyMetadataToScript(script, metadata);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            throw initFailedReport(workspace, {
+                title: exc.title,
+                stage: "metadata_extract",
+                exitCode: exc.exitCode,
+                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: { checkpoint, batch_checkpoint: batchCheckpoint, episode_completed: results.length },
+            });
+        }
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Metadata extraction failed",
+            stage: "metadata_extract",
+            required: ["provider metadata for worldview, role_type, and asset descriptions"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
+            updates: { checkpoint, batch_checkpoint: batchCheckpoint, episode_completed: results.length },
+        });
+    }
+    const scriptPath = path.join(dd, "script.initial.json");
+    writeJson(scriptPath, script);
+    updateRunState(workspace, { status: "init_running", init_stage: "validate", checkpoint, batch_checkpoint: batchCheckpoint });
+    let validation;
+    try {
+        validation = validateScript(workspace, scriptPath);
+    }
+    catch (exc) {
+        const e = exc;
+        throw initFailedReport(workspace, {
+            title: "INIT FAILED: Validation failed",
+            stage: "validate",
+            required: ["script.initial.json that can be validated"],
+            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+            nextSteps: ["Rerun init to retry validation, or inspect script.initial.json if the failure persists."],
+            updates: { checkpoint, script_path: scriptPath },
+        });
+    }
+    const passed = Boolean(validation["passed"]);
+    const status = passed ? "ready_for_agent" : "needs_agent_repair";
+    updateRunState(workspace, {
+        status,
+        command: "direct init",
+        init_stage: "complete",
+        checkpoint,
+        batch_checkpoint: batchCheckpoint,
+        checkpoint_reused: checkpointReused,
+        batch_checkpoint_reused: batchCheckpointReused,
+        provider: providerName,
+        model,
+        concurrency,
+        batch_mode: batchMode,
+        batch_target_lines: batchTargetLines,
+        batch_max_chars: batchMaxChars,
+        batch_min_lines: batchMinLines,
+        source_path: path.resolve(source),
+        script_path: scriptPath,
+        validation_path: path.join(dd, "validation.json"),
+        episode_total: asList(plan["episodes"]).length,
+        episode_completed: results.length,
+        episode_reused: skipped.length,
+        episode_failed: 0,
+        failed_episodes: [],
+        batch_total: asList(batchPlan["batches"]).length,
+        batch_completed: completedBatches,
+        batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
+        batch_failed: 0,
+        failed_batches: [],
+        failure_signature: [],
+        failure_streak: 0,
+        last_error: null,
+        review_status: "pending",
+        review_missing: [...REVIEW_TARGETS],
+        inspected_targets: [],
+        patch_count: 0,
+        exportable: providerName !== "mock",
+    });
+    const title = passed
+        ? "INIT COMPLETE: Initial script ready"
+        : "INIT NEEDS AGENT: Initial script written with repair issues";
+    const stats = validation["stats"] ?? {};
+    const report = {
+        title,
+        result: [
+            `episodes: ${stats["episodes"] ?? 0}`,
+            `scenes: ${stats["scenes"] ?? 0}`,
+            `actions: ${stats["actions"] ?? 0}`,
+            `validation: ${passed ? "passed" : "needs repair"}`,
+            `provider: ${providerName}`,
+            `episode checkpoint reused: ${skipped.length}`,
+            `batches: ${completedBatches}/${asList(batchPlan["batches"]).length} completed`,
+            `batch checkpoint reused: ${skippedEpisodeBatchCount + skippedBatches.length}`,
+            "agent_review: pending",
+        ],
+        artifacts: [
+            path.join(workspace, "source.txt"),
+            path.join(dd, "source_manifest.json"),
+            path.join(dd, "episode_plan.json"),
+            path.join(dd, "batch_plan.json"),
+            batchResultsDir,
+            episodeResultsDir,
+            path.join(dd, "asset_curation.json"),
+            path.join(dd, "asset_metadata.json"),
+            scriptPath,
+            path.join(dd, "validation.json"),
+            path.join(dd, "run_state.json"),
+        ],
+        issues: summarizeIssues(asList(validation["issues"])),
+        next: providerName === "mock"
+            ? [
+                "Run inspect for issue, episode, and asset; apply patches if needed; then validate/export.",
+                "Do not export mock-provider results for delivery.",
+            ]
+            : ["Run inspect for issue, episode, and asset; apply patches if needed; then validate/export."],
+    };
+    return [report, passed ? 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: [
+            `episodes: ${stats["episodes"] ?? 0}`,
+            `scenes: ${stats["scenes"] ?? 0}`,
+            `actions: ${stats["actions"] ?? 0}`,
+        ],
+        artifacts: [path.join(directDir(workspace), "validation.json")],
+        issues: summarizeIssues(asList(validation["issues"])),
+        next: [passed ? "Export script.json." : "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})`,
+    ];
+    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;
+}
+export function commandInspect(opts) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const target = strOf(opts["target"]);
+    const itemId = opts["id"] ? strOf(opts["id"]) : null;
+    const dd = directDir(workspace);
+    const scriptPath = path.join(dd, "script.initial.json");
+    const validationPath = path.join(dd, "validation.json");
+    if (!exists(scriptPath) && target === "asset") {
+        throw new CliError("INSPECT BLOCKED: script.initial.json not found", "script.initial.json not found.", {
+            exitCode: EXIT_INPUT,
+            required: ["workspace/draft/scriptctl/direct/script.initial.json"],
+            received: [scriptPath],
+            nextSteps: ["Run scriptctl direct init first."],
+        });
+    }
+    const script = exists(scriptPath)
+        ? readJson(scriptPath)
+        : { episodes: [], actors: [], locations: [], props: [] };
+    let validation = exists(validationPath) ? readJson(validationPath) : { issues: [] };
+    if (target === "issue" && exists(scriptPath)) {
+        validation = validateScript(workspace, scriptPath, { requireSource: false });
+    }
+    const batchPlanPath = path.join(dd, "batch_plan.json");
+    const batchPlan = exists(batchPlanPath) ? readJson(batchPlanPath) : { batches: [] };
+    const batchCounts = new Map();
+    for (const batch of asList(batchPlan["batches"])) {
+        if (!isDict(batch))
+            continue;
+        const ep = Number(batch["episode"] ?? 0);
+        batchCounts.set(ep, (batchCounts.get(ep) ?? 0) + 1);
+    }
+    const failedByEpisode = new Map();
+    const batchResultsDir = path.join(dd, "batch_results");
+    if (exists(batchResultsDir)) {
+        const files = fs.readdirSync(batchResultsDir).filter((n) => n.endsWith(".error.json")).sort();
+        for (const name of files) {
+            const errorFile = path.join(batchResultsDir, name);
+            try {
+                const error = readJson(errorFile);
+                const episodeNum = Number(error["episode"] ?? 0);
+                if (!failedByEpisode.has(episodeNum))
+                    failedByEpisode.set(episodeNum, []);
+                failedByEpisode.get(episodeNum).push(strOf(error["batch_id"]) || name.replace(/\.error\.json$/, ""));
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    const lines = [];
+    if (target === "episode") {
+        if (exists(scriptPath)) {
+            for (const ep of asList(script["episodes"])) {
+                if (itemId && itemId !== strOf(ep["episode_id"]))
+                    continue;
+                const scenes = asList(ep["scenes"]);
+                const sceneCount = scenes.length;
+                let actionCount = 0;
+                for (const scene of scenes)
+                    actionCount += asList(scene["actions"]).length;
+                const rawNum = normalizeInt(strOf(ep["episode_id"]), lines.length + 1);
+                const failed = (failedByEpisode.get(rawNum) ?? []).join(",") || "-";
+                lines.push(`${ep["episode_id"]}: scenes=${sceneCount}, actions=${actionCount}, batches=${batchCounts.get(rawNum) ?? 0}, failed_batches=${failed}, title=${ep["title"] || "-"}`);
+            }
+        }
+        else {
+            const planPath = path.join(dd, "episode_plan.json");
+            const plan = exists(planPath) ? readJson(planPath) : { episodes: [] };
+            for (const ep of asList(plan["episodes"])) {
+                const epId = fmtId("ep", Number(ep["episode"] ?? 0));
+                if (itemId && itemId !== epId && itemId !== strOf(ep["episode"]))
+                    continue;
+                const episodeNum = Number(ep["episode"] ?? 0);
+                const failed = (failedByEpisode.get(episodeNum) ?? []).join(",") || "-";
+                lines.push(`${epId}: batches=${batchCounts.get(episodeNum) ?? 0}, failed_batches=${failed}, title=${ep["title"] || "-"}`);
+            }
+        }
+    }
+    else if (target === "asset") {
+        const curationPath = path.join(dd, "asset_curation.json");
+        if (!itemId && exists(curationPath)) {
+            const curation = readJson(curationPath);
+            if (isDict(curation))
+                lines.push(...renderAssetCurationSummary(curation));
+        }
+        for (const [key, idKey, nameKey] of [["actors", "actor_id", "actor_name"], ["locations", "location_id", "location_name"], ["props", "prop_id", "prop_name"]]) {
+            for (const asset of asList(script[key])) {
+                if (itemId && itemId !== strOf(asset[idKey]) && itemId !== strOf(asset[nameKey]))
+                    continue;
+                const aliases = asList(asset["aliases"]).length;
+                const states = asList(asset["states"]).length;
+                const role = key === "actors" ? `, role_type=${asset["role_type"]}` : "";
+                const description = strOf(asset["description"]).trim() ? "yes" : "missing";
+                const singular = key.slice(0, -1);
+                lines.push(`${singular} ${asset[idKey]}: ${asset[nameKey]} aliases=${aliases}, states=${states}${role}, description=${description}`);
+            }
+        }
+    }
+    else if (target === "issue") {
+        for (const errors of failedByEpisode.values()) {
+            for (const batchId of errors) {
+                const errorPath = path.join(batchResultsDir, `${batchId}.error.json`);
+                if (!exists(errorPath))
+                    continue;
+                let error;
+                try {
+                    error = readJson(errorPath);
+                }
+                catch {
+                    continue;
+                }
+                if (itemId && itemId !== strOf(error["batch_id"]) && itemId !== strOf(error["episode"]) && itemId !== strOf(error["error_type"]))
+                    continue;
+                lines.push(`error BATCH_FAILED: ${error["batch_id"]} episode ${error["episode"]} part ${error["part"]} - ${error["message"]}`);
+            }
+        }
+        for (const issue of asList(validation["issues"])) {
+            if (itemId && itemId !== strOf(issue["code"]) && itemId !== strOf(issue["severity"]))
+                continue;
+            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}]` : ""}`);
+        }
+    }
+    else if (target === "review") {
+        const episodeArg = strOf(opts["episode"]).trim();
+        if (!episodeArg) {
+            throw new CliError("INSPECT BLOCKED: --episode required for review", "--episode required for review.", {
+                exitCode: EXIT_USAGE,
+                required: ["--episode <n>[,<n>...]"],
+                received: ["--episode not provided"],
+                nextSteps: ["Pass --episode 1 (single) or --episode 1,15,30 (multiple)."],
+            });
+        }
+        let episodeFilters;
+        try {
+            episodeFilters = 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("INSPECT 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."],
+            });
+        }
+        const sourcePath = path.join(workspace, "source.txt");
+        if (!exists(sourcePath)) {
+            throw new CliError("INSPECT 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 sourceText = readText(sourcePath);
+        const episodePlanPath = path.join(dd, "episode_plan.json");
+        const episodePlan = exists(episodePlanPath) ? readJson(episodePlanPath) : { episodes: [] };
+        for (let idx = 0; idx < episodeFilters.length; idx++) {
+            if (idx > 0) {
+                lines.push("");
+                lines.push("");
+            }
+            lines.push(...renderReviewEpisode(sourceText, episodePlan, script, episodeFilters[idx]));
+        }
+    }
+    else {
+        throw new CliError("INSPECT BLOCKED: Invalid target", "Invalid inspect target.", {
+            exitCode: EXIT_USAGE,
+            required: ["--target: episode, asset, issue, or review"],
+            received: [`--target: ${target}`],
+            nextSteps: ["Use one of the supported inspect targets."],
+        });
+    }
+    const state = addInspectedTarget(workspace, target);
+    const missingReview = reviewBlockers(state);
+    const report = {
+        title: `INSPECT: ${target}`,
+        result: lines.length > 0 ? lines : ["No matching items."],
+        next: [
+            "Use inspect details to prepare a structured patch, or continue required review.",
+            missingReview.length === 0 ? "Review complete; run validate/export." : `Still inspect: ${missingReview.join(", ")}.`,
+        ],
+    };
+    return [report, EXIT_OK];
+}
+//# sourceMappingURL=direct.js.map