@lingjingai/scriptctl 0.11.5 → 0.12.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, DIRECT_CONTRACT_VERSION, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, REVIEW_TARGETS, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, sha256Text, writeJson, } from "../common.js";
-import { compactBatchResult, compactEpisodeResult, buildBatchPlan, buildEpisodePlan, classifyProviderError, enrichEpisodePlanTitles, extractBatchWithRecovery, mergeEpisodeResults, normalizeEpisodeResult, normalizeInt, recoverBatchFromSource, uniqueAdd, validateBatchExtractionQuality, 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, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, REVIEW_TARGETS, 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, normalizeInt, 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";
@@ -23,6 +23,12 @@ function checkpointTimestamp() {
     const now = new Date();
     return now.toISOString().replace(/\.\d+Z$/, "Z");
 }
+function parseIntList(v) {
+    return strOf(v).split(",").map((s) => parseInt(s.trim(), 10)).filter((n) => !Number.isNaN(n));
+}
+function parseStrList(v) {
+    return strOf(v).split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
 // ---------------------------------------------------------------------------
 // run_state.json
 // ---------------------------------------------------------------------------
@@ -163,53 +169,42 @@ function persistBatchResult(dir, batch, result) {
         deletePath(mdPath);
     }
 }
-function episodeMetaPath(dir, ep) {
-    return path.join(dir, `${episodeResultKey(ep)}.meta.json`);
-}
-function batchMetaPath(dir, batch) {
-    return path.join(dir, `${batchResultKey(batch)}.meta.json`);
-}
-function readUnitMeta(metaPath) {
-    if (!exists(metaPath))
+// ---------------------------------------------------------------------------
+// Per-batch result files ARE the state. A batch with `<key>.json` is done; with
+// `<key>.error.json` it failed; with neither it is pending. Reuse = file
+// presence — the agent drives what to (re)run via `direct status` + --episodes/
+// --batches selection. No content hashes, no global checkpoint, no destructive
+// reset: re-running a unit only ever touches that unit's own files, so the other
+// episodes can never be lost.
+// ---------------------------------------------------------------------------
+// Read a persisted batch result (reused or freshly written) for assembly.
+// Returns null if absent or unreadable, in which case the batch counts as
+// not-done and will be (re)run.
+function readBatchResult(dir, batch) {
+    const p = batchResultPath(dir, batch);
+    if (!exists(p))
         return null;
     try {
-        const data = readJson(metaPath);
-        return isDict(data) ? data : null;
+        const result = normalizeEpisodeResult(readJson(p), batch);
+        result["_batch_id"] = batchResultKey(batch);
+        result["_batch_part"] = Number(batch["part"]);
+        result["_starts_inside_scene"] = Boolean(batch["starts_inside_scene"]);
+        return result;
     }
     catch {
         return null;
     }
 }
-function writeUnitMeta(metaPath, meta) {
-    fs.mkdirSync(path.dirname(metaPath), { recursive: true });
-    writeJson(metaPath, meta);
-}
-function removeUnitMeta(metaPath) {
-    if (exists(metaPath))
-        deletePath(metaPath);
-}
-function stampEpisodeMeta(dir, ep, inputHash, provenance, providerName, model) {
-    writeUnitMeta(episodeMetaPath(dir, ep), {
-        schema: 1, key: episodeResultKey(ep), episode: Number(ep["episode"]),
-        input_hash: inputHash, provenance, status: "ok", provider: providerName, model, extracted_at: checkpointTimestamp(),
-    });
-}
-function stampBatchMeta(dir, batch, inputHash, provenance, providerName, model) {
-    writeUnitMeta(batchMetaPath(dir, batch), {
-        schema: 1, key: batchResultKey(batch), episode: Number(batch["episode"]), part: Number(batch["part"]),
-        input_hash: inputHash, provenance, status: "ok", provider: providerName, model, extracted_at: checkpointTimestamp(),
-    });
-}
-// Content-address a single episode/batch plan unit: the contract version, the
-// exact source span text, the title-stable plan item, and provider/model. Any
-// change to what would alter extraction rotates the hash for THAT unit only.
-export function computeUnitHash(sourceText, unit, providerName, model) {
-    const span = isDict(unit["source_span"]) ? unit["source_span"] : {};
-    const start = Number(span["start"] ?? 0);
-    const end = Number(span["end"] ?? 0);
-    const spanText = sourceText.slice(start, end);
-    const planText = JSON.stringify(unit, checkpointReplacer());
-    return sha256Text([String(DIRECT_CONTRACT_VERSION), spanText, planText, providerName ?? "", model ?? ""].join("\u0000"));
+// Single source of truth for a batch's on-disk state, shared by init (what to
+// (re)run) and status (what to report) so the two can never disagree. "done"
+// requires a result that actually PARSES — a present-but-corrupt result is
+// pending, so it self-heals on the next run instead of being silently trusted.
+function classifyBatch(dir, batch) {
+    if (readBatchResult(dir, batch) !== null)
+        return "done";
+    if (exists(batchErrorPath(dir, batch)))
+        return "error";
+    return "pending";
 }
 // Delete result/meta/error/markdown files whose unit key is no longer in the
 // current plan (e.g. the source shed an episode). Pure function of the plan —
@@ -235,69 +230,6 @@ function gcOrphanUnits(dir, liveKeys) {
     }
     return removed;
 }
-// Title fields are LLM-mutated downstream by enrichEpisodePlanTitles, so they
-// must be excluded from unit hashes — otherwise every rerun gets a fresh SHA,
-// the cached unit never matches, and that unit re-extracts from scratch.
-const CHECKPOINT_UNSTABLE_KEYS = new Set(["title", "generated_title", "title_status", "title_source"]);
-function checkpointReplacer() {
-    // Python's json.dumps(sort_keys=True) sorts keys recursively. Replicate by walking and sorting.
-    return function (key, value) {
-        if (CHECKPOINT_UNSTABLE_KEYS.has(key))
-            return undefined;
-        if (isDict(value)) {
-            const sorted = {};
-            for (const k of Object.keys(value).sort()) {
-                if (CHECKPOINT_UNSTABLE_KEYS.has(k))
-                    continue;
-                sorted[k] = value[k];
-            }
-            return sorted;
-        }
-        return value;
-    };
-}
-// Non-destructive reuse: a cached episode result is reusable iff its sidecar
-// meta records the same input_hash we compute for the current plan unit. The
-// hash subsumes the old provider / source_span / episode-number / contract
-// checks — any of those changing rotates the hash. On any mismatch or read
-// failure we return null and let the caller re-extract and overwrite; we NEVER
-// delete the cached file pre-emptively (that was the data-loss root cause).
-export function loadCachedEpisode(sourceText, episodeResultsDir, ep, expectedHash) {
-    const meta = readUnitMeta(episodeMetaPath(episodeResultsDir, ep));
-    if (!meta || meta["input_hash"] !== expectedHash)
-        return null;
-    if (meta["status"] === "terminal")
-        return null;
-    const p = episodeResultPath(episodeResultsDir, ep);
-    if (!exists(p))
-        return null;
-    try {
-        const result = normalizeEpisodeResult(readJson(p), ep);
-        validateEpisodeExtractionQuality(sourceText, ep, result);
-        return result;
-    }
-    catch {
-        return null;
-    }
-}
-export function loadCachedBatch(sourceText, batchResultsDir, batch, expectedHash) {
-    const meta = readUnitMeta(batchMetaPath(batchResultsDir, batch));
-    if (!meta || meta["input_hash"] !== expectedHash)
-        return null;
-    if (meta["status"] === "terminal")
-        return null;
-    const p = batchResultPath(batchResultsDir, batch);
-    if (!exists(p))
-        return null;
-    try {
-        const result = normalizeEpisodeResult(readJson(p), batch);
-        validateBatchExtractionQuality(sourceText, batch, result);
-        return result;
-    }
-    catch {
-        return null;
-    }
-}
 function mergeScene(target, source) {
     if ((target["location_name"] === "" || target["location_name"] === "未知场景" || target["location_name"] === null || target["location_name"] === undefined) &&
         source["location_name"]) {
@@ -389,9 +321,19 @@ async function providerExtractAssetCurationLocal(provider, sourceText, script) {
     }
     return {};
 }
-function writeBatchFailure(dir, batch, exc, inputHash, providerName, model) {
+// Record a batch failure: write `<key>.error.json` (which marks the batch as
+// "tried and failed" → sticky on plain resume) and drop any stale result file.
+// The error_code (e.g. PROVIDER_CONTENT_FILTERED) is surfaced so the agent can
+// see WHY in `direct status` / `direct inspect` and decide whether to re-run.
+//
+// Deliberate content-filter policy split: batch extraction is HARD (sticky
+// error, episode blocked until an explicit re-run) because batch content is the
+// deliverable and cannot be fabricated; episode TITLES are SOFT (degrade to a
+// deterministic title, recorded as title_degraded, never blocking) because a
+// title is non-essential and always has a safe fallback. Same provider signal,
+// two intentional policies — see enrichEpisodeTitlesChunked.
+function writeBatchFailure(dir, batch, exc) {
     const err = exc;
-    const terminal = classifyProviderError(exc) === "terminal";
     const error = {
         batch_id: batchResultKey(batch),
         episode: Number(batch["episode"]),
@@ -400,11 +342,11 @@ function writeBatchFailure(dir, batch, exc, inputHash, providerName, model) {
         line_range: batch["line_range"],
         error_type: err?.name || "Error",
         message: (err?.message || err?.name || "Error").slice(0, 500),
-        terminal,
-        input_hash: inputHash,
         failed_at: checkpointTimestamp(),
     };
     if (exc instanceof CliError) {
+        if (exc.errorCode)
+            error["error_code"] = exc.errorCode;
         if (exc.required.length > 0)
             error["required"] = exc.required;
         if (exc.received.length > 0)
@@ -415,16 +357,6 @@ function writeBatchFailure(dir, batch, exc, inputHash, providerName, model) {
     const resultPath = batchResultPath(dir, batch);
     if (exists(resultPath))
         deletePath(resultPath);
-    if (terminal) {
-        writeUnitMeta(batchMetaPath(dir, batch), {
-            schema: 1, key: batchResultKey(batch), episode: Number(batch["episode"]), part: Number(batch["part"]),
-            input_hash: inputHash, provenance: "extracted", status: "terminal",
-            provider: providerName, model, extracted_at: checkpointTimestamp(),
-        });
-    }
-    else {
-        removeUnitMeta(batchMetaPath(dir, batch));
-    }
     writeJson(batchErrorPath(dir, batch), error);
     return error;
 }
@@ -468,6 +400,64 @@ async function pMapWithConcurrency(items, concurrency, worker) {
     }));
     return out;
 }
+function providerErrorSummary(error) {
+    if (error instanceof CliError && error.errorCode)
+        return error.errorCode;
+    const e = error;
+    const msg = strOf(e?.message).replace(/\s+/g, " ").trim();
+    if (/prohibited content|content filter|refused/i.test(msg))
+        return "PROVIDER_CONTENT_FILTERED";
+    return `${e?.name ?? "Error"}: ${msg}`.slice(0, 160);
+}
+// Generate the plan's missing episode titles in bounded, concurrent chunks.
+// Title generation is non-essential (every episode has a deterministic
+// fallback), so a chunk that the provider filters or fails does NOT abort
+// init: its episodes are retried one-by-one to isolate the poisoned excerpt,
+// and whatever still fails degrades to a deterministic title. The plan is
+// mutated in place and persisted by the caller; degradation is recorded to
+// run_state so it's visible without being a hard failure.
+async function enrichEpisodeTitlesChunked(workspace, sourceText, plan, provider, concurrency) {
+    const chunks = chunkEpisodesNeedingTitles(plan, DEFAULT_TITLE_CHUNK_SIZE);
+    if (chunks.length === 0 || !provider.extractEpisodeTitles) {
+        // Nothing to title, or a provider with no title support: deterministic for all.
+        return applyEpisodeTitlesToPlan(sourceText, plan, new Map());
+    }
+    const extract = provider.extractEpisodeTitles.bind(provider);
+    const generated = new Map();
+    const collect = (outcomes) => {
+        for (const o of outcomes) {
+            if (o.ok)
+                for (const [num, title] of o.value)
+                    generated.set(num, title);
+        }
+    };
+    // Phase 1: chunked requests.
+    const chunkOutcomes = await pMapWithConcurrency(chunks, concurrency, async (chunk) => episodeTitleResponseMap(await extract(sourceText, { episodes: chunk })));
+    collect(chunkOutcomes);
+    // Phase 2: any episode still WITHOUT a title — whether its chunk threw or the
+    // chunk returned 200 but omitted it — gets one isolated single-episode request,
+    // so a single poisoned/omitted excerpt can't deny its chunk-mates a real title.
+    const missing = chunks.flat().filter((ep) => !generated.has(Number(ep["episode"] ?? 0)));
+    let reason;
+    if (missing.length > 0) {
+        const singleOutcomes = await pMapWithConcurrency(missing, concurrency, async (ep) => episodeTitleResponseMap(await extract(sourceText, { episodes: [ep] })));
+        collect(singleOutcomes);
+        const firstError = singleOutcomes.find((o) => !o.ok);
+        if (firstError)
+            reason = providerErrorSummary(firstError.error);
+    }
+    const degraded = applyEpisodeTitlesToPlan(sourceText, plan, generated);
+    if (degraded.length > 0) {
+        updateRunState(workspace, {
+            title_degraded: {
+                count: degraded.length,
+                episodes: degraded,
+                reason: reason ?? "provider returned no title for these episodes; used deterministic titles",
+            },
+        });
+    }
+    return degraded;
+}
 // ---------------------------------------------------------------------------
 // command_init
 // ---------------------------------------------------------------------------
@@ -479,9 +469,14 @@ export async function commandInit(opts) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
     const providerName = strOf(opts["provider"] || DEFAULT_PROVIDER);
     const model = strOf(opts["model"] || process.env.SCRIPTCTL_ANTHROPIC_MODEL || DEFAULT_MODEL);
-    // When set, retry batches a prior run marked terminal (content-filtered)
-    // instead of skipping them — e.g. after the provider's filter was adjusted.
-    const retryTerminal = Boolean(opts["retry_terminal"]);
+    // Explicit selection: the agent decides what to (re)run. Default is "resume"
+    // — only batches never attempted run. --episodes / --batches force-rerun the
+    // named units, --retry-errors force-reruns everything currently errored, --all
+    // reruns everything. Forced units have their stale result/error deleted first.
+    const selEpisodes = new Set(parseIntList(opts["episodes"]));
+    const selBatches = new Set(parseStrList(opts["batches"]));
+    const retryErrors = Boolean(opts["retry_errors"]);
+    const runAll = Boolean(opts["all"]);
     let concurrency;
     try {
         concurrency = parseInt(strOf(opts["concurrency"] || DEFAULT_CONCURRENCY), 10);
@@ -636,29 +631,7 @@ export async function commandInit(opts) {
         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."],
-        });
-    }
+    const titleDegraded = await enrichEpisodeTitlesChunked(workspace, sourceText, plan, provider, concurrency);
     let batchPlan;
     try {
         batchPlan = buildBatchPlan(sourceText, plan, {
@@ -691,20 +664,6 @@ export async function commandInit(opts) {
     // the legacy v3 index.json. There is no whole-directory reset any more.
     gcOrphanUnits(episodeResultsDir, new Set(asList(plan["episodes"]).map((ep) => episodeResultKey(ep))));
     gcOrphanUnits(batchResultsDir, new Set(asList(batchPlan["batches"]).map((b) => batchResultKey(b))));
-    updateRunState(workspace, {
-        status: "init_running",
-        init_stage: "batch_extract",
-        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"]);
@@ -712,126 +671,93 @@ export async function commandInit(opts) {
             batchesByEpisode.set(epNum, []);
         batchesByEpisode.get(epNum).push(batch);
     }
-    // Per-unit reuse: each episode is judged independently by its own input hash,
-    // so a source edit to one episode invalidates only that episode — not all 33.
-    for (const episode of asList(plan["episodes"])) {
-        const epHash = computeUnitHash(sourceText, episode, providerName, model);
-        const cached = loadCachedEpisode(sourceText, episodeResultsDir, episode, epHash);
-        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);
-                    stampBatchMeta(batchResultsDir, cachedBatch, computeUnitHash(sourceText, cachedBatch, providerName, model), "recovered", 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 terminalSkipped = [];
+    const totalEpisodes = asList(plan["episodes"]).length;
+    const totalBatches = asList(batchPlan["batches"]).length;
+    // Decide which batches to run. State (classifyBatch) is shared with `direct
+    // status` so the two never disagree: a "done" batch is reused, an "error"
+    // batch is sticky (skipped on a plain rerun so a content filter can't loop),
+    // a "pending" (never-run or corrupt) batch runs. The agent overrides with
+    // explicit selection.
     const pending = [];
-    for (const batch of pendingBatches) {
-        const bHash = computeUnitHash(sourceText, batch, providerName, model);
-        // A terminal failure (content filter) with the same input hash will fail the
-        // same way — skip it instead of re-calling the provider, unless --retry-terminal
-        // or the source/provider changed (which rotates the hash).
-        const meta = readUnitMeta(batchMetaPath(batchResultsDir, batch));
-        if (!retryTerminal && meta && meta["status"] === "terminal" && meta["input_hash"] === bHash) {
-            terminalSkipped.push(batchResultKey(batch));
+    let reusedBatchCount = 0;
+    let stickyErrorCount = 0;
+    for (const batch of asList(batchPlan["batches"])) {
+        const epNum = Number(batch["episode"]);
+        const key = batchResultKey(batch);
+        const errorPath = batchErrorPath(batchResultsDir, batch);
+        const forced = runAll || selEpisodes.has(epNum) || selBatches.has(key) || (retryErrors && exists(errorPath));
+        if (forced) {
+            const resultPath = batchResultPath(batchResultsDir, batch);
+            if (exists(resultPath))
+                deletePath(resultPath);
+            if (exists(errorPath))
+                deletePath(errorPath);
+            pending.push(batch);
             continue;
         }
-        const cachedBatch = loadCachedBatch(sourceText, batchResultsDir, batch, bHash);
-        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);
+        switch (classifyBatch(batchResultsDir, batch)) {
+            case "done":
+                reusedBatchCount++;
+                break;
+            case "error":
+                stickyErrorCount++;
+                break; // tried and failed; left until explicitly re-run
+            default: pending.push(batch); // never attempted (or corrupt → self-heal)
         }
     }
-    const failures = [];
-    const outcomes = await pMapWithConcurrency(pending, concurrency, async (batch) => {
-        return await extractBatchWithRecovery(provider, sourceText, batch);
+    updateRunState(workspace, {
+        status: "init_running",
+        init_stage: "batch_extract",
+        batch_mode: batchMode,
+        batch_target_lines: batchTargetLines,
+        batch_max_chars: batchMaxChars,
+        batch_min_lines: batchMinLines,
+        episode_total: totalEpisodes,
+        batch_total: totalBatches,
     });
+    const failures = [];
+    const outcomes = await pMapWithConcurrency(pending, concurrency, async (batch) => 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);
-            stampBatchMeta(batchResultsDir, batch, computeUnitHash(sourceText, batch, providerName, model), "extracted", providerName, model);
+            persistBatchResult(batchResultsDir, batch, outcome.value);
+            const errorPath = batchErrorPath(batchResultsDir, batch);
             if (exists(errorPath))
                 deletePath(errorPath);
         }
         else {
-            failures.push(writeBatchFailure(batchResultsDir, batch, outcome.error, computeUnitHash(sourceText, batch, providerName, model), providerName, model));
+            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;
-    const transientFailures = failures.filter((it) => !it["terminal"]);
-    const terminalFailures = failures.filter((it) => Boolean(it["terminal"]));
-    const skippedSet = new Set(skipped);
-    // Merge every fully-completed, non-cached episode into an episode_results
-    // checkpoint. Episodes still missing a batch (a failure this run, or a batch
-    // a prior run marked terminal and we skipped) are left unmerged so a rerun or
-    // an override can complete them.
-    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 doneBatches = reusedBatchCount + outcomes.filter((o) => o.ok).length;
+    const erroredBatches = stickyErrorCount + failures.length;
+    // Assemble every episode whose batches are all present on disk (reused +
+    // freshly extracted, read uniformly from disk). Incomplete episodes are
+    // reported; assembling them is left to an explicit re-run.
+    const results = [];
+    const incompleteEpisodes = [];
     try {
         for (const episode of asList(plan["episodes"])) {
             const episodeNum = Number(episode["episode"]);
-            if (skippedSet.has(episodeNum))
-                continue;
-            const expectedBatches = (batchesByEpisode.get(episodeNum) ?? []).length;
-            if (!expectedBatches || (batchResultsByEpisode.get(episodeNum) ?? []).length !== expectedBatches)
+            const epBatches = batchesByEpisode.get(episodeNum) ?? [];
+            const batchResults = epBatches.map((b) => readBatchResult(batchResultsDir, b)).filter((r) => r !== null);
+            if (epBatches.length === 0 || batchResults.length !== epBatches.length) {
+                incompleteEpisodes.push(episodeNum);
+                // Drop any stale episode_results/ep_NNN.json from a prior complete run so
+                // the derived artifact never claims an episode is complete when it isn't.
+                const stale = episodeResultPath(episodeResultsDir, episode);
+                if (exists(stale))
+                    deletePath(stale);
                 continue;
-            const result = mergeBatchResultsForEpisode(episode, batchResultsByEpisode.get(episodeNum) ?? []);
-            validateEpisodeExtractionQuality(sourceText, episode, result);
-            results.push(result);
-            writeJson(episodeResultPath(episodeResultsDir, episode), compactEpisodeResult(result));
-            stampEpisodeMeta(episodeResultsDir, episode, computeUnitHash(sourceText, episode, providerName, model), "extracted", providerName, model);
-            const errorPath = episodeErrorPath(episodeResultsDir, episode);
-            if (exists(errorPath))
-                deletePath(errorPath);
+            }
+            const merged = mergeBatchResultsForEpisode(episode, batchResults);
+            validateEpisodeExtractionQuality(sourceText, episode, merged);
+            results.push(merged);
+            writeJson(episodeResultPath(episodeResultsDir, episode), compactEpisodeResult(merged));
+            const errPath = episodeErrorPath(episodeResultsDir, episode);
+            if (exists(errPath))
+                deletePath(errPath);
         }
     }
     catch (exc) {
@@ -839,109 +765,61 @@ export async function commandInit(opts) {
         throw initFailedReport(workspace, {
             title: "INIT FAILED: Episode merge failed",
             stage: "episode_merge",
-            required: ["complete batch_results/*.json that can merge into episode_results/*.json"],
+            required: ["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: { batch_completed: completedBatches },
+            nextSteps: ["Rerun init; completed batches are reused and episode merge will retry."],
         });
     }
     results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
-    // Classify episodes that could not be assembled. An episode blocked by ANY
-    // transient batch (timeout/5xx) can still complete on rerun → it blocks init.
-    // An episode blocked only by terminal (content-filtered) batches is held out:
-    // the rest of the script ships, and the operator overrides the blocked unit.
-    const completedEpisodeNums = new Set(results.map((r) => Number(r["episode"])));
-    const transientEpisodeSet = new Set(transientFailures.map((it) => Number(it["episode"])));
-    const incompleteEpisodes = asList(plan["episodes"]).map((ep) => Number(ep["episode"])).filter((n) => !completedEpisodeNums.has(n));
-    const transientBlocked = incompleteEpisodes.filter((n) => transientEpisodeSet.has(n)).sort((a, b) => a - b);
-    const heldOutEpisodes = incompleteEpisodes.filter((n) => !transientEpisodeSet.has(n)).sort((a, b) => a - b);
-    if (transientBlocked.length > 0) {
+    incompleteEpisodes.sort((a, b) => a - b);
+    if (incompleteEpisodes.length > 0) {
         updateRunState(workspace, {
             status: "init_incomplete",
             init_stage: "batch_extract",
-            episode_total: asList(plan["episodes"]).length,
+            episode_total: totalEpisodes,
             episode_completed: results.length,
-            episode_reused: skipped.length,
-            episode_failed: incompleteEpisodes.length,
-            failed_episodes: transientBlocked,
-            held_out_episodes: heldOutEpisodes,
-            batch_total: asList(batchPlan["batches"]).length,
-            batch_completed: completedBatches,
-            batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
-            batch_failed: failures.length,
-            batch_terminal: terminalFailures.length,
-            transient_failed_batches: transientFailures.map((it) => strOf(it["batch_id"])),
-            terminal_failed_batches: terminalFailures.map((it) => strOf(it["batch_id"])),
-            last_error: { title: "INIT INCOMPLETE: Batch extraction failed", failed_at: checkpointTimestamp() },
+            incomplete_episodes: incompleteEpisodes,
+            batch_total: totalBatches,
+            batch_completed: doneBatches,
+            batch_failed: erroredBatches,
+            last_error: { title: "INIT INCOMPLETE: Some episodes have unextracted batches", failed_at: checkpointTimestamp() },
         });
-        const issues = failures.slice(0, 5).map((it) => `${it["batch_id"]} episode ${it["episode"]} part ${it["part"]} [${it["terminal"] ? "terminal" : "transient"}]: ${it["error_type"]} - ${it["message"]}`);
-        const next = [
-            "Run direct inspect --target issue to review failed batches.",
-            "Rerun the same init to retry transient failures; completed units are reused.",
-        ];
-        if (terminalFailures.length > 0) {
-            next.push("Terminal (content-filtered) batches will not clear on retry — use `direct override <unit> --from <file>` or soften the source.");
-        }
         const report = {
-            title: "INIT INCOMPLETE: Batch extraction failed",
+            title: "INIT INCOMPLETE: Some episodes have unextracted batches",
             result: [
-                `episodes total: ${asList(plan["episodes"]).length}`,
-                `completed: ${results.length}`,
-                `reused: ${skipped.length}`,
-                `held out (terminal): ${heldOutEpisodes.length}`,
-                `batches: ${completedBatches}/${asList(batchPlan["batches"]).length} completed, ${transientFailures.length} transient, ${terminalFailures.length} terminal`,
+                `episodes: ${results.length}/${totalEpisodes} complete`,
+                `incomplete episodes: ${incompleteEpisodes.join(", ")}`,
+                `batches: ${doneBatches}/${totalBatches} done, ${erroredBatches} error`,
+                ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
                 `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,
+            next: [
+                "Run `direct status` to see per-episode batch state.",
+                "Re-run one episode with `direct init --episodes <n>`, one batch with `--batches <key>`, or all errors with `--retry-errors`.",
+                "Errored batches are left untouched on a plain rerun; select them to retry.",
+            ],
         };
         return [report, EXIT_RUNTIME];
     }
     updateRunState(workspace, {
         status: "init_running",
         init_stage: "episode_merge",
-        episode_total: asList(plan["episodes"]).length,
+        episode_total: totalEpisodes,
         episode_completed: results.length,
-        episode_reused: skipped.length,
-        episode_failed: 0,
-        failed_episodes: [],
-        held_out_episodes: heldOutEpisodes,
-        batch_total: asList(batchPlan["batches"]).length,
-        batch_completed: completedBatches,
-        batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
-        batch_failed: terminalFailures.length,
-        batch_terminal: terminalFailures.length,
+        incomplete_episodes: [],
+        batch_total: totalBatches,
+        batch_completed: doneBatches,
+        batch_failed: erroredBatches,
         last_error: null,
     });
-    // Drop transient/cleared error markers, but KEEP terminal ones so `direct
-    // status` and export gating can see which episodes are held out.
-    for (const dir of [batchResultsDir, episodeResultsDir]) {
-        if (!exists(dir))
-            continue;
-        for (const name of fs.readdirSync(dir)) {
-            if (!name.endsWith(".error.json"))
-                continue;
-            const errPath = path.join(dir, name);
-            try {
-                const err = readJson(errPath);
-                if (!isDict(err) || !err["terminal"])
-                    deletePath(errPath);
-            }
-            catch {
-                deletePath(errPath);
-            }
-        }
-    }
-    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
     let script;
     try {
         updateRunState(workspace, { status: "init_running", init_stage: "script_merge" });
@@ -1050,17 +928,13 @@ export async function commandInit(opts) {
         source_path: path.resolve(source),
         script_path: scriptPath,
         validation_path: path.join(dd, "validation.json"),
-        episode_total: asList(plan["episodes"]).length,
+        episode_total: totalEpisodes,
         episode_completed: results.length,
-        episode_reused: skipped.length,
-        episode_failed: 0,
-        failed_episodes: [],
-        held_out_episodes: heldOutEpisodes,
-        batch_total: asList(batchPlan["batches"]).length,
-        batch_completed: completedBatches,
-        batch_reused: skippedEpisodeBatchCount + skippedBatches.length,
-        batch_failed: terminalFailures.length,
-        batch_terminal: terminalFailures.length,
+        incomplete_episodes: [],
+        batch_total: totalBatches,
+        batch_completed: doneBatches,
+        batch_reused: reusedBatchCount,
+        batch_failed: erroredBatches,
         last_error: null,
         review_status: "pending",
         review_missing: [...REVIEW_TARGETS],
@@ -1079,9 +953,9 @@ export async function commandInit(opts) {
             `actions: ${stats["actions"] ?? 0}`,
             `validation: ${passed ? "passed" : "needs repair"}`,
             `provider: ${providerName}`,
-            `episodes reused: ${skipped.length}`,
-            `batches: ${completedBatches}/${asList(batchPlan["batches"]).length} completed`,
-            `batches reused: ${skippedEpisodeBatchCount + skippedBatches.length}`,
+            `episodes: ${results.length}/${totalEpisodes} complete`,
+            `batches: ${doneBatches}/${totalBatches} done (reused ${reusedBatchCount})`,
+            ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
             "agent_review: pending",
         ],
         artifacts: [
@@ -1108,138 +982,10 @@ export async function commandInit(opts) {
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
 // ---------------------------------------------------------------------------
-// command_override — inject a human extraction for a unit the provider can't
-// produce (content-filtered). The override is content-addressed exactly like a
-// provider result, so init reuses it and never re-calls the provider, and the
-// non-destructive GC never deletes it. We compute the input_hash from the plan
-// ourselves, so the operator never hand-edits source_span.
-// ---------------------------------------------------------------------------
-export function commandOverride(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
-    const unit = strOf(asList(opts["_args"])[0]).trim();
-    const fromPath = strOf(opts["from"]).trim();
-    const dd = directDir(workspace);
-    const state = readRunState(workspace);
-    const providerName = strOf(opts["provider"] || state["provider"] || DEFAULT_PROVIDER);
-    const model = strOf(opts["model"] || state["model"] || DEFAULT_MODEL);
-    const isEpisode = /^ep_\d+$/.test(unit);
-    if (!isEpisode && !/^bat_\d+$/.test(unit)) {
-        throw new CliError("OVERRIDE BLOCKED: Invalid unit", "Invalid unit key.", {
-            exitCode: EXIT_USAGE,
-            required: ["<unit>: ep_NNN or bat_NNNN"],
-            received: [`<unit>: ${unit || "<empty>"}`],
-            nextSteps: ["Pass an episode (ep_007) or batch (bat_0012) key shown by direct status."],
-        });
-    }
-    if (!fromPath || !exists(fromPath)) {
-        throw new CliError("OVERRIDE BLOCKED: --from not found", "Override source file not found.", {
-            exitCode: EXIT_INPUT,
-            required: ["--from <path>: readable JSON extraction for the unit"],
-            received: [`--from: ${fromPath || "<missing>"}`],
-            nextSteps: ["Provide a JSON file with scenes/actions for the unit."],
-        });
-    }
-    const planPath = path.join(dd, isEpisode ? "episode_plan.json" : "batch_plan.json");
-    if (!exists(planPath)) {
-        throw new CliError("OVERRIDE BLOCKED: Plan not found", "Plan not found.", {
-            exitCode: EXIT_INPUT,
-            required: [isEpisode ? "episode_plan.json" : "batch_plan.json"],
-            received: [planPath],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    const plan = readJson(planPath);
-    const planUnits = asList(plan[isEpisode ? "episodes" : "batches"]);
-    const planItem = planUnits.find((u) => (isEpisode ? episodeResultKey(u) : batchResultKey(u)) === unit) ?? null;
-    if (!planItem) {
-        throw new CliError("OVERRIDE BLOCKED: Unit not in current plan", "Unit not in current plan.", {
-            exitCode: EXIT_INPUT,
-            required: [`${unit} present in ${isEpisode ? "episode_plan.json" : "batch_plan.json"}`],
-            received: [`${unit}: not found among ${planUnits.length} units`],
-            nextSteps: ["Use a unit key from direct status; rerun init if the plan changed."],
-        });
-    }
-    const sourceTextPath = path.join(workspace, "source.txt");
-    if (!exists(sourceTextPath)) {
-        throw new CliError("OVERRIDE BLOCKED: source.txt missing", "source.txt missing.", {
-            exitCode: EXIT_INPUT,
-            required: [sourceTextPath],
-            received: ["<missing>"],
-            nextSteps: ["Run scriptctl direct init first."],
-        });
-    }
-    const sourceText = readText(sourceTextPath);
-    let data;
-    try {
-        data = readJson(fromPath);
-    }
-    catch (exc) {
-        throw new CliError("OVERRIDE BLOCKED: --from invalid JSON", "Override JSON invalid.", {
-            exitCode: EXIT_INPUT,
-            required: ["valid extraction JSON"],
-            received: [`${fromPath}: ${exc.message}`],
-            nextSteps: ["Fix the JSON and retry."],
-        });
-    }
-    const result = normalizeEpisodeResult(data, planItem);
-    if (Number(result["episode"]) !== Number(planItem["episode"])) {
-        throw new CliError("OVERRIDE BLOCKED: Episode mismatch", "Episode mismatch.", {
-            exitCode: EXIT_USAGE,
-            required: [`episode ${Number(planItem["episode"])}`],
-            received: [`episode ${Number(result["episode"])}`],
-            nextSteps: ["Provide an extraction for the correct episode."],
-        });
-    }
-    try {
-        if (isEpisode)
-            validateEpisodeExtractionQuality(sourceText, planItem, result);
-        else
-            validateBatchExtractionQuality(sourceText, planItem, result);
-    }
-    catch (exc) {
-        if (exc instanceof CliError)
-            throw exc;
-        throw new CliError("OVERRIDE BLOCKED: Extraction invalid", "Extraction invalid.", {
-            exitCode: EXIT_USAGE,
-            required: ["valid action types (dialogue/inner_thought/action)"],
-            received: [exc.message.slice(0, 160)],
-            nextSteps: ["Fix the override extraction and retry."],
-        });
-    }
-    const dir = path.join(dd, isEpisode ? "episode_results" : "batch_results");
-    fs.mkdirSync(dir, { recursive: true });
-    const hash = computeUnitHash(sourceText, planItem, providerName, model);
-    if (isEpisode) {
-        writeJson(episodeResultPath(dir, planItem), compactEpisodeResult(result));
-        stampEpisodeMeta(dir, planItem, hash, "override", providerName, model);
-        const errPath = episodeErrorPath(dir, planItem);
-        if (exists(errPath))
-            deletePath(errPath);
-    }
-    else {
-        persistBatchResult(dir, planItem, result);
-        stampBatchMeta(dir, planItem, hash, "override", providerName, model);
-        const errPath = batchErrorPath(dir, planItem);
-        if (exists(errPath))
-            deletePath(errPath);
-    }
-    const report = {
-        title: "OVERRIDE COMPLETE: Unit extraction injected",
-        result: [
-            `unit: ${unit}`,
-            `kind: ${isEpisode ? "episode" : "batch"}`,
-            `provenance: override`,
-            `provider/model: ${providerName} / ${model}`,
-            `scenes: ${asList(result["scenes"]).length}`,
-        ],
-        artifacts: [dir, path.join(dd, "run_state.json")],
-        next: ["Rerun scriptctl direct init — the override is reused without re-calling the provider."],
-    };
-    return [report, EXIT_OK];
-}
-// ---------------------------------------------------------------------------
-// command_status — rebuild the progress view from on-disk meta/error sidecars.
-// run_state is just a cache of this; deleting it loses nothing.
+// command_status — the agent-facing state table, derived entirely from disk: a
+// batch with `<key>.json` is done, with `<key>.error.json` it failed, with
+// neither it is pending. run_state is just a denormalized cache of this, so the
+// agent can read state, then pick exactly which episodes/batches to (re)run.
 // ---------------------------------------------------------------------------
 export function commandStatus(opts) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
@@ -1256,56 +1002,85 @@ export function commandStatus(opts) {
     }
     const episodes = asList(readJson(episodePlanPath)["episodes"]);
     const batches = asList(readJson(batchPlanPath)["batches"]);
-    const episodeResultsDir = path.join(dd, "episode_results");
     const batchResultsDir = path.join(dd, "batch_results");
-    const count = { ok: 0, override: 0, recovered: 0, terminal: 0, missing: 0 };
+    const byEp = new Map();
+    let doneTotal = 0;
+    let errorTotal = 0;
     for (const batch of batches) {
-        const meta = readUnitMeta(batchMetaPath(batchResultsDir, batch));
-        if (!meta) {
-            count.missing++;
+        const epNum = Number(batch["episode"]);
+        if (!byEp.has(epNum))
+            byEp.set(epNum, { total: 0, done: 0, error: 0, pending: 0, errorKeys: [], reasons: new Set() });
+        const st = byEp.get(epNum);
+        st.total++;
+        const state = classifyBatch(batchResultsDir, batch);
+        if (state === "done") {
+            st.done++;
+            doneTotal++;
             continue;
         }
-        if (meta["status"] === "terminal") {
-            count.terminal++;
-            continue;
+        if (state === "error") {
+            st.error++;
+            errorTotal++;
+            st.errorKeys.push(batchResultKey(batch));
+            try {
+                const err = readJson(batchErrorPath(batchResultsDir, batch));
+                st.reasons.add(strOf(err["error_code"] || err["error_type"] || "Error"));
+            }
+            catch {
+                st.reasons.add("Error");
+            }
+        }
+        else {
+            st.pending++;
         }
-        count.ok++;
-        if (meta["provenance"] === "override")
-            count.override++;
-        else if (meta["provenance"] === "recovered")
-            count.recovered++;
     }
-    const completedEpisodes = [];
+    const lines = [];
+    let completeEpisodes = 0;
+    const errorEpisodes = [];
     for (const ep of episodes) {
-        const meta = readUnitMeta(episodeMetaPath(episodeResultsDir, ep));
-        if (meta && meta["status"] === "ok")
-            completedEpisodes.push(Number(ep["episode"]));
+        const epNum = Number(ep["episode"]);
+        const st = byEp.get(epNum) ?? { total: 0, done: 0, error: 0, pending: 0, errorKeys: [], reasons: new Set() };
+        let label;
+        if (st.total > 0 && st.done === st.total) {
+            label = "done";
+            completeEpisodes++;
+        }
+        else if (st.error > 0) {
+            label = `ERROR (${st.done}/${st.total} done, ${st.error} err: ${[...st.reasons].join(",")})  [${st.errorKeys.join(",")}]`;
+            errorEpisodes.push(epNum);
+        }
+        else {
+            label = `pending (${st.done}/${st.total} done)`;
+        }
+        lines.push(`${episodeResultKey(ep)}  ${label}`);
     }
-    // Held out = episodes with at least one terminal batch and no episode result.
-    const completedSet = new Set(completedEpisodes);
-    const heldOut = new Set();
-    for (const batch of batches) {
-        const meta = readUnitMeta(batchMetaPath(batchResultsDir, batch));
-        const epNum = Number(batch["episode"]);
-        if (meta && meta["status"] === "terminal" && !completedSet.has(epNum))
-            heldOut.add(epNum);
+    // Surface degraded titles (deterministic fallback) recorded by init — they are
+    // not a failure but the agent should know.
+    const state = readRunState(workspace);
+    const titleDeg = isDict(state["title_degraded"]) ? state["title_degraded"] : null;
+    const result = [
+        `episodes: ${completeEpisodes}/${episodes.length} done`,
+        `batches: ${doneTotal}/${batches.length} done, ${errorTotal} error`,
+        `error episodes: ${errorEpisodes.length === 0 ? "-" : errorEpisodes.join(", ")}`,
+    ];
+    if (titleDeg && Number(titleDeg["count"] ?? 0) > 0) {
+        result.push(`titles degraded (deterministic): ${asList(titleDeg["episodes"]).join(", ")}`);
     }
-    const heldOutEpisodes = [...heldOut].sort((a, b) => a - b);
+    result.push(...lines);
+    const allDone = completeEpisodes === episodes.length;
     const report = {
         title: "DIRECT STATUS",
-        result: [
-            `episodes: ${completedEpisodes.length}/${episodes.length} complete`,
-            `batches: ${count.ok}/${batches.length} ok (override ${count.override}, recovered ${count.recovered})`,
-            `terminal batches: ${count.terminal}`,
-            `pending batches: ${count.missing}`,
-            `held out episodes: ${heldOutEpisodes.length === 0 ? "-" : heldOutEpisodes.join(", ")}`,
-        ],
-        artifacts: [batchResultsDir, episodeResultsDir, path.join(dd, "run_state.json")],
-        next: heldOutEpisodes.length > 0
-            ? ["Override held-out episodes with direct override, or export 32/33 with direct export --allow-incomplete."]
-            : ["All units accounted for."],
+        result,
+        artifacts: [batchResultsDir, path.join(dd, "episode_results"), path.join(dd, "run_state.json")],
+        next: errorEpisodes.length > 0
+            ? [`Re-run an errored episode with: direct init --episodes ${errorEpisodes[0]}  (or --batches <key>, or --retry-errors).`]
+            : allDone
+                ? ["All episodes complete."]
+                : ["Pending batches remain — re-run: direct init (resume) or --episodes <N>."],
     };
-    return [report, EXIT_OK];
+    // Non-zero when the workspace is not fully extracted, so automation can gate
+    // on the exit code instead of scraping stdout.
+    return [report, allDone ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
 export function summarizeIssues(issues) {
     if (issues.length === 0)