@lingjingai/scriptctl 0.15.0 → 0.19.1

package/dist/usecases/direct.js

@@ -1,7 +1,7 @@
 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, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, writeJson, } from "../common.js";
-import { compactBatchResult, compactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
+import { CliError, DEFAULT_BATCH_MAX_CHARS, DEFAULT_BATCH_MIN_LINES, DEFAULT_BATCH_MODE, DEFAULT_BATCH_TARGET_LINES, DEFAULT_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, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, cleanSynopsisList, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, uniqueAdd, 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";
@@ -29,6 +29,32 @@ function parseIntList(v) {
 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
 // ---------------------------------------------------------------------------
@@ -78,6 +104,19 @@ function episodeErrorPath(dir, ep) {
 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)
@@ -205,8 +244,15 @@ export function mergeBatchResultsForEpisode(episode, batchResults) {
     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;
@@ -249,14 +295,12 @@ export function mergeBatchResultsForEpisode(episode, batchResults) {
         speakers,
         state_definitions: stateDefinitions,
     };
-    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 {};
+    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.
@@ -298,17 +342,21 @@ function writeBatchFailure(dir, batch, exc) {
     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: { title: opts.title, received: opts.received, failed_at: checkpointTimestamp() },
+        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,
@@ -396,6 +444,218 @@ async function enrichEpisodeTitlesChunked(workspace, sourceText, plan, provider,
     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));
+}
+// 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;
+        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 outcomes = await pMapWithConcurrency(plan.groups, opts.concurrency, async (group) => {
+                const groupSynopses = group.map((i) => current[i]).filter((s) => s.trim());
+                if (groupSynopses.length <= 1)
+                    return { value: groupSynopses[0] ?? "" };
+                try {
+                    return { value: await reduceSynopses(provider, groupSynopses, { title: script["title"] }) };
+                }
+                catch (err) {
+                    return { value: groupSynopses.join(" "), error: err };
+                }
+            });
+            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;
+            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
 // ---------------------------------------------------------------------------
 export async function commandInit(opts) {
@@ -414,28 +674,14 @@ export async function commandInit(opts) {
     const selBatches = new Set(parseStrList(opts["batches"]));
     const retryErrors = Boolean(opts["retry_errors"]);
     const runAll = Boolean(opts["all"]);
-    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."],
-        });
-    }
+    // 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 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_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.", {
@@ -451,29 +697,7 @@ export async function commandInit(opts) {
         ["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;
+        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"];
@@ -642,6 +866,11 @@ export async function commandInit(opts) {
             default: pending.push(batch); // never attempted (or corrupt → self-heal)
         }
     }
+    // Episodes whose batches were (re)run this round — their episode synopsis is
+    // recomputed; untouched episodes reuse their persisted `syn`. Summary failures
+    // accumulate here and are reported without ever blocking init.
+    const changedEpisodes = new Set(pending.map((b) => Number(b["episode"])));
+    const summaryDegradedEpisodes = [];
     updateRunState(workspace, {
         status: "init_running",
         init_stage: "batch_extract",
@@ -680,6 +909,7 @@ export async function commandInit(opts) {
     const results = [];
     const incompleteEpisodes = [];
     try {
+        // Assemble every complete episode (incomplete ones are reported and skipped).
         for (const episode of asList(plan["episodes"])) {
             const episodeNum = Number(episode["episode"]);
             const epBatches = batchesByEpisode.get(episodeNum) ?? [];
@@ -695,9 +925,23 @@ export async function commandInit(opts) {
             }
             const merged = mergeBatchResultsForEpisode(episode, batchResults);
             validateEpisodeExtractionQuality(sourceText, episode, merged);
-            results.push(merged);
-            writeJson(episodeResultPath(episodeResultsDir, episode), compactEpisodeResult(merged));
-            const errPath = episodeErrorPath(episodeResultsDir, episode);
+            results.push(merged); // complete episodes only; carries `episode` for the write below
+        }
+        // Episode-level synopsis (reduce-1): resolve each result's synopsis in place
+        // (passthrough / reuse / skip / concurrent LLM stitch). Reads prior `syn`
+        // BEFORE the persist loop below overwrites ep_NNN.json.
+        summaryDegradedEpisodes.push(...await resolveEpisodeSynopses(provider, results, {
+            resultsDir: episodeResultsDir,
+            resummarize,
+            skipSummary,
+            changedEpisodes,
+            concurrency,
+        }));
+        // Persist every assembled episode (synopsis now resolved for all of them).
+        // merged carries `episode`, so it doubles as the path key.
+        for (const merged of results) {
+            writeJson(episodeResultPath(episodeResultsDir, merged), compactEpisodeResult(merged));
+            const errPath = episodeErrorPath(episodeResultsDir, merged);
             if (exists(errPath))
                 deletePath(errPath);
         }
@@ -780,29 +1024,23 @@ export async function commandInit(opts) {
     }
     try {
         updateRunState(workspace, { status: "init_running", init_stage: "asset_curation" });
-        const rawCuration = await providerExtractAssetCurationLocal(provider, sourceText, script);
-        const curation = curateScriptAssets(script, rawCuration);
+        // Location merge is deterministic-only: actor/prop pruning runs from scene
+        // counts and every location is kept. The previous provider location-merge
+        // call was removed (single large streaming request kept dropping the gateway
+        // connection); duplicate locations can be merged later if needed.
+        const curation = curateScriptAssets(script);
         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: { episode_completed: results.length },
-            });
-        }
+        // curateScriptAssets is deterministic (no provider call) — a failure here is
+        // a malformed assembled script, not a gateway/provider problem.
         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"],
+            required: ["a well-formed assembled script for deterministic asset curation"],
             received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
-            nextSteps: ["Rerun init; extraction checkpoints will be reused and asset curation will retry."],
+            nextSteps: ["Rerun init; completed extraction checkpoints will be reused."],
             updates: { episode_completed: results.length },
         });
     }
@@ -820,6 +1058,7 @@ export async function commandInit(opts) {
                 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."],
@@ -836,6 +1075,30 @@ export async function commandInit(opts) {
             updates: { episode_completed: results.length },
         });
     }
+    // Whole-script overview (reduce-2). Soft: a non-essential concept enhancement,
+    // the opposite of batch extraction's hard-fail policy — failures degrade the
+    // overview (recorded as summary_degraded + a sanitized reason) and NEVER block init.
+    let summaryFullDegraded = false;
+    let summaryDegradeReason = "";
+    try {
+        updateRunState(workspace, { status: "init_running", init_stage: "summary" });
+        const summary = await buildScriptSynopsis(provider, script, {
+            dd,
+            thresholdChars: summaryThresholdChars,
+            groupSize: DEFAULT_SUMMARY_GROUP_SIZE,
+            resummarize,
+            skipSummary,
+            concurrency,
+        });
+        summaryFullDegraded = summary.degraded;
+        summaryDegradeReason = summary.reason ?? "";
+    }
+    catch (exc) {
+        summaryFullDegraded = true;
+        summaryDegradeReason = providerErrorSummary(exc);
+    }
+    summaryDegradedEpisodes.sort((a, b) => a - b); // concurrent stitch pushes out of order
+    const summaryDegraded = summaryFullDegraded || summaryDegradedEpisodes.length > 0;
     const scriptPath = path.join(dd, "script.initial.json");
     writeJson(scriptPath, script);
     updateRunState(workspace, { status: "init_running", init_stage: "validate" });
@@ -877,12 +1140,18 @@ export async function commandInit(opts) {
         batch_completed: doneBatches,
         batch_reused: reusedBatchCount,
         batch_failed: erroredBatches,
+        summary_threshold_chars: summaryThresholdChars,
+        summary_skipped: skipSummary,
+        summary_degraded: summaryDegraded,
+        summary_degraded_episodes: summaryDegradedEpisodes,
+        summary_degraded_reason: summaryDegradeReason || null,
         last_error: null,
     });
     const title = passed
         ? "INIT COMPLETE: Initial script ready"
         : "INIT NEEDS AGENT: Initial script written with repair issues";
     const stats = validation["stats"] ?? {};
+    const summaryLine = formatSummaryStatusLine(skipSummary, summaryDegraded, summaryDegradedEpisodes);
     const report = {
         title,
         result: [
@@ -894,6 +1163,7 @@ export async function commandInit(opts) {
             `episodes: ${results.length}/${totalEpisodes} complete`,
             `batches: ${doneBatches}/${totalBatches} done (reused ${reusedBatchCount})`,
             ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
+            ...(summaryLine ? [summaryLine] : []),
         ],
         artifacts: [
             path.join(workspace, "source.txt"),
@@ -904,6 +1174,7 @@ export async function commandInit(opts) {
             episodeResultsDir,
             path.join(dd, "asset_curation.json"),
             path.join(dd, "asset_metadata.json"),
+            path.join(dd, "synopsis.json"),
             scriptPath,
             path.join(dd, "validation.json"),
             path.join(dd, "run_state.json"),
@@ -1003,6 +1274,13 @@ export function commandStatus(opts) {
     if (titleDeg && Number(titleDeg["count"] ?? 0) > 0) {
         result.push(`titles degraded (deterministic): ${asList(titleDeg["episodes"]).join(", ")}`);
     }
+    // Surface synopsis state recorded by init: skipped or degraded summaries mean
+    // the overview / some episode synopses are missing or fell back to joined
+    // beats — an agent gating on status should know it isn't a complete summary.
+    // Same formatter as init's report so the two never word it differently.
+    const summaryLine = formatSummaryStatusLine(Boolean(state["summary_skipped"]), Boolean(state["summary_degraded"]), asList(state["summary_degraded_episodes"]).map((n) => Number(n)));
+    if (summaryLine)
+        result.push(summaryLine);
     result.push(...lines);
     const allDone = completeEpisodes === episodes.length;
     const report = {