@lingjingai/scriptctl 0.28.4 → 0.29.0

package/dist/usecases/direct.js

@@ -1,10 +1,18 @@
 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, 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, mergeEpisodeResultsWithReport, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, 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_DIRECT_CONCURRENCY, DEFAULT_MODEL, DEFAULT_PROVIDER, DEFAULT_SUMMARY_GROUP_SIZE, DEFAULT_SUMMARY_REDUCE_THRESHOLD_CHARS, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, SUPPORTED_EXTS, deletePath, directDir, exists, fmtId, readJson, readText, sha256Text, writeJson, } from "../common.js";
+import { compactBatchResult, compactEpisodeResult, expandCompactEpisodeResult, buildBatchPlan, buildEpisodePlan, DEFAULT_TITLE_CHUNK_SIZE, chunkEpisodesNeedingTitles, applyEpisodeTitlesToPlan, cleanSynopsisList, episodeTitleResponseMap, extractBatchWithRecovery, mergeEpisodeResultsWithReport, normalizeEpisodeResult, planSynopsisReduction, readCarriedSynopsis, sortDeep, uniqueAdd, validateEpisodeExtractionQuality, _md_push_asset, curateScriptAssets, applyMetadataToScript, } from "../domain/direct-core.js";
 import { validateScript } from "../domain/script/validate.js";
 import { makeProvider, providerCapabilities } from "../infra/providers.js";
 import { makeSourceManifest, prepareSource, } from "../infra/converters.js";
+import { Workspace, StageIncomplete, emptyRunState, stageRunStateName, } from "../domain/direct/stage.js";
+// Circular import: runner.ts → stages/index.ts → each stage file → THIS module
+// (the stageXxx impls live here). It's safe because every reference below
+// (runStages / runOne / STAGES) is used only inside function bodies that run at
+// CALL time (commandInitImpl, commandRun), never at module-load time — so the
+// cycle is fully resolved before any of them executes.
+import { runStages, runOne } from "../domain/direct/runner.js";
+import { STAGES } from "../domain/direct/stages/index.js";
 function strOf(v) {
     if (v === null || v === undefined)
         return "";
@@ -994,6 +1002,21 @@ function initFailedReport(workspace, opts) {
         nextSteps: opts.nextSteps,
     });
 }
+// Catch→initFailedReport for the deterministic stages: format the raw exception
+// into a single-line `received` and write the failure run_state, so the cast +
+// `slice(0,160)` + updates boilerplate lives here instead of being hand-copied
+// into every stage's catch block.
+function stageFailure(workspace, exc, opts) {
+    const e = exc;
+    throw initFailedReport(workspace, {
+        title: opts.title,
+        stage: opts.stage,
+        required: opts.required,
+        received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
+        nextSteps: opts.nextSteps,
+        ...(opts.updates ? { updates: opts.updates } : {}),
+    });
+}
 // ---------------------------------------------------------------------------
 // Concurrency limiter (mirrors ThreadPoolExecutor)
 // ---------------------------------------------------------------------------
@@ -1303,7 +1326,11 @@ export async function commandInit(opts) {
         finishInitProgress();
     }
 }
-async function commandInitImpl(opts) {
+// Parse `direct init` / `direct run` options into the typed DirectRunOptions the
+// stage pipeline consumes. Single source of truth for flag parsing + validation
+// so init and run can't drift on defaults (--concurrency / batch sizing / the
+// selection flags). Throws the same USAGE/INPUT CliErrors the god-command did.
+function parseDirectRunOptions(opts) {
     const sourcePathArg = strOf(opts["source_path"]);
     const source = sourcePathArg.startsWith("~")
         ? path.join(process.env.HOME ?? "", sourcePathArg.slice(1))
@@ -1327,7 +1354,7 @@ async function commandInitImpl(opts) {
     const skipMetadata = Boolean(opts["skip_metadata"]);
     const resummarize = Boolean(opts["resummarize"]);
     const summaryThresholdChars = parsePositiveIntOption(opts["summary_threshold_chars"], "--summary-threshold-chars", "USAGE ERROR: Invalid summary threshold", DEFAULT_SUMMARY_REDUCE_THRESHOLD_CHARS);
-    const concurrency = parsePositiveIntOption(opts["concurrency"], "--concurrency", "USAGE ERROR: Invalid concurrency", DEFAULT_CONCURRENCY);
+    const concurrency = parsePositiveIntOption(opts["concurrency"], "--concurrency", "USAGE ERROR: Invalid concurrency", DEFAULT_DIRECT_CONCURRENCY);
     const batchMode = strOf(opts["batch_mode"] || DEFAULT_BATCH_MODE).trim();
     if (batchMode !== "episode") {
         throw new CliError("USAGE ERROR: Invalid batch mode", "Invalid batch mode.", {
@@ -1348,6 +1375,66 @@ async function commandInitImpl(opts) {
     const batchTargetLines = batchValues["batch_target_lines"];
     const batchMaxChars = batchValues["batch_max_chars"];
     const batchMinLines = Math.min(batchValues["batch_min_lines"], batchTargetLines);
+    return {
+        source,
+        workspace,
+        providerName,
+        model,
+        concurrency,
+        batchMode,
+        batchTargetLines,
+        batchMaxChars,
+        batchMinLines,
+        selEpisodes,
+        selBatches,
+        retryErrors,
+        runAll,
+        skipSummary,
+        skipMetadata,
+        resummarize,
+        summaryThresholdChars,
+    };
+}
+// Build the per-stage progress emitter + run_state updater + lazy provider that
+// every stage shares. Extracted so commandInit and commandRun assemble an
+// identical StageContext (same progress rendering, same run_state side effects).
+function buildStageContext(options) {
+    const ws = new Workspace(options.workspace);
+    let provider = null;
+    const ctx = {
+        ws,
+        options,
+        state: emptyRunState(),
+        provider() {
+            if (provider)
+                return provider;
+            try {
+                provider = makeProvider(options.providerName, options.model);
+            }
+            catch (exc) {
+                if (exc instanceof CliError) {
+                    updateRunState(options.workspace, {
+                        status: "init_failed",
+                        init_stage: "episode_titles",
+                        last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
+                    });
+                }
+                throw exc;
+            }
+            return provider;
+        },
+        emitProgress(stage, status = "running") {
+            emitInitProgress(options.workspace, stageRunStateName(stage), status);
+        },
+        updateRunState(updates) {
+            updateRunState(options.workspace, updates);
+        },
+    };
+    return ctx;
+}
+// Validate --source-path (existence + supported extension) before any stage
+// runs. Kept as the init-only entry guard the god-command performed up front.
+function assertInitSource(source) {
     if (!exists(source) || !fs.statSync(source).isFile()) {
         throw new CliError("INIT BLOCKED: Source file not found", "Source file not found.", {
             exitCode: EXIT_INPUT,
@@ -1366,26 +1453,350 @@ async function commandInitImpl(opts) {
             nextSteps: ["Use a supported source file and rerun init."],
         });
     }
-    const dd = directDir(workspace);
-    fs.mkdirSync(dd, { recursive: true });
-    updateRunState(workspace, {
+}
+// Build the final INIT report from the completed run state. Reads the same
+// artifacts/state the god-command's trailing block read, so the report lines,
+// artifacts list and exit code are byte-identical.
+function buildInitReport(ctx) {
+    const { ws, options, state } = ctx;
+    const dd = ws.dir;
+    const validation = state.validation ?? {};
+    const passed = Boolean(validation["passed"]);
+    const title = passed
+        ? "INIT COMPLETE: Initial script ready"
+        : "INIT NEEDS AGENT: Initial script written with repair issues";
+    const stats = validation["stats"] ?? {};
+    const summaryDegraded = state.summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
+    const summaryLine = formatSummaryStatusLine(options.skipSummary, summaryDegraded, state.summaryDegradedEpisodes);
+    const normalization = isDict(state.assetNormalization) ? state.assetNormalization : null;
+    const normSummary = normalization && isDict(normalization["summary"]) ? normalization["summary"] : {};
+    const merges = Number(normSummary["asset_merges"] ?? 0);
+    const statesFromNames = Number(normSummary["location_states_from_names"] ?? 0);
+    const statesFromTime = Number(normSummary["location_states_from_time"] ?? 0);
+    const reviewItems = Number(normSummary["review_items"] ?? 0);
+    const report = {
+        title,
+        result: [
+            `episodes: ${stats["episodes"] ?? 0}`,
+            `scenes: ${stats["scenes"] ?? 0}`,
+            `actions: ${stats["actions"] ?? 0}`,
+            `validation: ${passed ? "passed" : "needs repair"}`,
+            `provider: ${options.providerName}`,
+            `episodes: ${state.mergedResults.length}/${state.totalEpisodes} complete`,
+            `content: ${state.doneBatches}/${state.totalBatches} done`,
+            `normalization: merges=${merges}, states=${statesFromNames + statesFromTime}, review=${reviewItems}`,
+            ...(options.skipMetadata ? ["metadata: skipped"] : []),
+            ...(state.titleDegraded.length > 0 ? [`titles degraded (deterministic): ${state.titleDegraded.join(", ")}`] : []),
+            ...(summaryLine ? [summaryLine] : []),
+        ],
+        artifacts: [
+            ws.rootPathOf("source.txt"),
+            path.join(dd, "source_manifest.json"),
+            path.join(dd, "episode_plan.json"),
+            path.join(dd, "batch_plan.json"),
+            path.join(dd, "batch_results"),
+            path.join(dd, "episode_results"),
+            path.join(dd, "asset_normalization.json"),
+            path.join(dd, "asset_curation.json"),
+            ...(options.skipMetadata ? [] : [path.join(dd, "asset_metadata.json")]),
+            path.join(dd, "synopsis.json"),
+            path.join(dd, "script.initial.json"),
+            path.join(dd, "validation.json"),
+            path.join(dd, "run_state.json"),
+        ],
+        issues: summarizeIssues(asList(validation["issues"])),
+        next: options.providerName === "mock"
+            ? [
+                "Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export.",
+                "Do not export mock-provider results for delivery.",
+            ]
+            : ["Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export."],
+    };
+    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+}
+// Build the INIT INCOMPLETE report (some episode still has unextracted batches).
+// Mirrors the god-command's early-return block; EXIT_RUNTIME signals automation.
+function buildIncompleteReport(ctx) {
+    const { ws, options, state } = ctx;
+    const dd = ws.dir;
+    const report = {
+        title: "INIT INCOMPLETE: Some episodes have unextracted batches",
+        result: [
+            `episodes: ${state.mergedResults.length}/${state.totalEpisodes} complete`,
+            `incomplete episodes: ${state.incompleteEpisodes.join(", ")}`,
+            `content: ${state.doneBatches}/${state.totalBatches} done, ${state.erroredBatches} error`,
+            ...(state.titleDegraded.length > 0 ? [`titles degraded (deterministic): ${state.titleDegraded.join(", ")}`] : []),
+            `provider: ${options.providerName}`,
+        ],
+        artifacts: [
+            ws.rootPathOf("source.txt"),
+            path.join(dd, "episode_plan.json"),
+            path.join(dd, "batch_plan.json"),
+            path.join(dd, "batch_results"),
+            path.join(dd, "episode_results"),
+            path.join(dd, "run_state.json"),
+        ],
+        next: [
+            "Run `direct status` to see episode progress.",
+            "Re-run one episode with `direct init --episodes <n>`, or all errors with `--retry-errors`.",
+            "Errored units are left untouched on a plain rerun; select them to retry.",
+        ],
+    };
+    return [report, EXIT_RUNTIME];
+}
+async function commandInitImpl(opts) {
+    const options = parseDirectRunOptions(opts);
+    assertInitSource(options.source);
+    const ctx = buildStageContext(options);
+    ctx.ws.ensure();
+    // Seed run_state with the init header before the first stage runs (provider /
+    // model / source_path / metadata flag) — the god-command set these up front.
+    updateRunState(options.workspace, {
         status: "init_running",
         command: "direct init",
         init_stage: "source_prepare",
-        provider: providerName,
-        model,
-        concurrency,
-        source_path: path.resolve(source),
-        metadata_skipped: skipMetadata,
+        provider: options.providerName,
+        model: options.model,
+        concurrency: options.concurrency,
+        source_path: path.resolve(options.source),
+        metadata_skipped: options.skipMetadata,
     });
-    emitInitProgress(workspace, "source_prepare");
+    try {
+        // `direct init` runs EVERY stage (force) — exactly like the former god
+        // command, which had no whole-stage skip. The reuse model lives INSIDE the
+        // stages (per-batch file presence in batch-extract; per-episode `syn` reuse
+        // in the synopsis stages), so a deterministic stage must still re-derive its
+        // output from the (possibly reused/edited) upstream artifacts. Whole-stage
+        // skip-on-present is a `direct run <stage>` convenience only.
+        await runStages(ctx, STAGES, { force: true });
+    }
+    catch (exc) {
+        // The resumable "incomplete" stop is not a failure — surface the INCOMPLETE
+        // report + EXIT_RUNTIME, exactly as the god-command's early return did.
+        if (exc instanceof StageIncomplete)
+            return buildIncompleteReport(ctx);
+        throw exc;
+    }
+    // Pipeline complete: finalize run_state (the trailing god-command block).
+    const validation = ctx.state.validation ?? {};
+    const passed = Boolean(validation["passed"]);
+    const status = passed ? "ready_for_agent" : "needs_agent_repair";
+    const summaryDegraded = ctx.state.summaryFullDegraded || ctx.state.summaryDegradedEpisodes.length > 0;
+    updateRunState(options.workspace, {
+        status,
+        command: "direct init",
+        init_stage: "complete",
+        provider: options.providerName,
+        model: options.model,
+        concurrency: options.concurrency,
+        batch_mode: options.batchMode,
+        batch_target_lines: options.batchTargetLines,
+        batch_max_chars: options.batchMaxChars,
+        batch_min_lines: options.batchMinLines,
+        source_path: path.resolve(options.source),
+        script_path: ctx.ws.pathOf("script.initial.json"),
+        validation_path: ctx.ws.pathOf("validation.json"),
+        episode_total: ctx.state.totalEpisodes,
+        episode_completed: ctx.state.mergedResults.length,
+        incomplete_episodes: [],
+        batch_total: ctx.state.totalBatches,
+        batch_completed: ctx.state.doneBatches,
+        batch_reused: ctx.state.reusedBatchCount,
+        batch_failed: ctx.state.erroredBatches,
+        summary_threshold_chars: options.summaryThresholdChars,
+        summary_skipped: options.skipSummary,
+        summary_degraded: summaryDegraded,
+        summary_degraded_episodes: ctx.state.summaryDegradedEpisodes,
+        summary_degraded_reason: ctx.state.summaryDegradeReason || null,
+        metadata_skipped: options.skipMetadata,
+        last_error: null,
+    });
+    return buildInitReport(ctx);
+}
+// ---------------------------------------------------------------------------
+// command_run — single-stage runner against an existing workspace. Lets the
+// agent re-run one step (e.g. `direct run metadata`, `direct run episode-synopsis`)
+// without re-driving the whole pipeline. The stage rehydrates the prior
+// artifacts it needs from disk, so it stands alone.
+// ---------------------------------------------------------------------------
+export async function commandRun(opts) {
+    const stageName = strOf(asList(opts["_args"])[0] || opts["stage"]).trim();
+    if (!stageName) {
+        throw new CliError("DIRECT RUN BLOCKED: missing stage", "No stage name given.", {
+            exitCode: EXIT_USAGE,
+            required: [`one of: ${STAGES.map((s) => s.name).join(", ")}`],
+            received: ["<no stage>"],
+            nextSteps: ["Pass a stage name, e.g. `direct run metadata`."],
+        });
+    }
+    // Reject an unknown stage up front (both code paths below would otherwise
+    // silently no-op the `only`-filtered runStages on a typo).
+    if (!STAGES.some((s) => s.name === stageName)) {
+        throw new CliError("DIRECT RUN BLOCKED: unknown stage", `Unknown stage "${stageName}".`, {
+            exitCode: EXIT_USAGE,
+            required: [`one of: ${STAGES.map((s) => s.name).join(", ")}`],
+            received: [stageName],
+            nextSteps: ["Pass a valid stage name to `direct run`."],
+        });
+    }
+    const options = parseDirectRunOptions(opts);
+    const ctx = buildStageContext(options);
+    const force = Boolean(opts["force"]);
+    try {
+        if (force) {
+            // --force re-runs even when the output artifact is already present.
+            await runOne(ctx, stageName);
+        }
+        else {
+            // Without --force, honor skip-on-present so `direct run <stage>` is a no-op
+            // when the stage's output already exists (mirrors runStages' resume).
+            await runStages(ctx, STAGES, { only: new Set([stageName]) });
+        }
+    }
+    catch (exc) {
+        if (exc instanceof StageIncomplete) {
+            finishInitProgress();
+            return buildIncompleteReport(ctx);
+        }
+        emitFailedInitProgress(options.workspace);
+        finishInitProgress();
+        throw exc;
+    }
+    finishInitProgress();
+    const report = {
+        title: `DIRECT RUN: ${stageName}`,
+        result: [
+            `stage: ${stageName}`,
+            `workspace: ${options.workspace}`,
+            "ran one stage; run `direct status` for the full picture.",
+        ],
+        artifacts: [ctx.ws.pathOf("run_state.json")],
+        next: ["Run `direct status` to see updated progress, or `direct run <stage>` for another step."],
+    };
+    return [report, EXIT_OK];
+}
+// ===========================================================================
+// Per-stage implementations. Each function below is ONE segment of the former
+// commandInitImpl, lifted verbatim onto a StageContext so it can run either as
+// part of the full pipeline (runStages) or on its own (`direct run <stage>`).
+// They call the SAME helpers/pure functions the god-command used — no algorithm
+// is duplicated; only the cross-stage locals moved onto ctx.state. The thin
+// Stage wrappers in src/domain/direct/stages/*.ts just name + order these.
+// ===========================================================================
+// A stage that needs a prior artifact missing from ctx.state (because the run
+// started at a later stage via `direct run`) lazily rehydrates it from disk.
+function ensureEpisodePlan(ctx) {
+    if (ctx.state.episodePlan)
+        return ctx.state.episodePlan;
+    const plan = ctx.ws.readJsonSafe("episode_plan.json");
+    if (!plan) {
+        throw new CliError("DIRECT RUN BLOCKED: episode_plan.json missing", "episode_plan.json missing.", {
+            exitCode: EXIT_INPUT,
+            required: ["episode_plan.json (run the episode-plan stage first)"],
+            received: ["episode_plan.json missing"],
+            nextSteps: ["Run `direct init` or `direct run episode-plan` first."],
+        });
+    }
+    ctx.state.episodePlan = plan;
+    return plan;
+}
+function ensureBatchPlan(ctx) {
+    if (ctx.state.batchPlan)
+        return ctx.state.batchPlan;
+    const plan = ctx.ws.readJsonSafe("batch_plan.json");
+    if (!plan) {
+        throw new CliError("DIRECT RUN BLOCKED: batch_plan.json missing", "batch_plan.json missing.", {
+            exitCode: EXIT_INPUT,
+            required: ["batch_plan.json (run the batch-plan stage first)"],
+            received: ["batch_plan.json missing"],
+            nextSteps: ["Run `direct init` or `direct run batch-plan` first."],
+        });
+    }
+    ctx.state.batchPlan = plan;
+    return plan;
+}
+function ensureSourceText(ctx) {
+    if (ctx.state.sourceText)
+        return ctx.state.sourceText;
+    const p = ctx.ws.rootPathOf("source.txt");
+    if (!exists(p)) {
+        throw new CliError("DIRECT RUN BLOCKED: source.txt missing", "source.txt missing.", {
+            exitCode: EXIT_INPUT,
+            required: ["source.txt (run the source-prepare stage first)"],
+            received: ["source.txt missing"],
+            nextSteps: ["Run `direct init` or `direct run source-prepare` first."],
+        });
+    }
+    ctx.state.sourceText = readText(p);
+    return ctx.state.sourceText;
+}
+function ensureScript(ctx) {
+    if (ctx.state.script)
+        return ctx.state.script;
+    const script = ctx.ws.readJsonSafe("script.initial.json");
+    if (!script) {
+        throw new CliError("DIRECT RUN BLOCKED: script.initial.json missing", "script.initial.json missing.", {
+            exitCode: EXIT_INPUT,
+            required: ["script.initial.json (run the script-merge stage first)"],
+            received: ["script.initial.json missing"],
+            nextSteps: ["Run `direct init` or `direct run script-merge` first."],
+        });
+    }
+    ctx.state.script = script;
+    return script;
+}
+// Reassemble ctx.state.mergedResults from episode_results/ when a later stage is
+// run standalone (e.g. `direct run script-merge`). Mirrors the assembly the
+// episode-merge stage does in-memory, but reads the persisted results.
+function ensureMergedResults(ctx) {
+    if (ctx.state.mergedResults.length > 0)
+        return ctx.state.mergedResults;
+    const plan = ensureEpisodePlan(ctx);
+    const episodeResultsDir = ctx.ws.pathOf("episode_results");
+    const results = [];
+    for (const episode of asList(plan["episodes"])) {
+        const p = episodeResultPath(episodeResultsDir, episode);
+        const data = exists(p) ? readJsonFile(p, {}) : null;
+        if (data && isDict(data) && Object.keys(data).length > 0) {
+            results.push(expandCompactEpisodeResult(data, episode));
+        }
+    }
+    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
+    ctx.state.mergedResults = results;
+    return results;
+}
+// Recover the project name when a script-producing stage runs standalone (no
+// source-prepare set state.projectName, and `direct run` has no --source-path).
+// Order: in-memory → persisted manifest (source_name minus ext) → existing
+// script title → source basename. Without this, `direct run script-merge` would
+// rebuild the script with an empty title (state.projectName='' && source='').
+function ensureProjectName(ctx) {
+    if (ctx.state.projectName)
+        return ctx.state.projectName;
+    const manifest = ctx.ws.readJsonSafe("source_manifest.json");
+    const fromManifest = manifest
+        ? strOf(manifest["source_name"]).replace(/\.[^.]+$/, "")
+            || (strOf(manifest["source_path"]) ? path.basename(strOf(manifest["source_path"]), path.extname(strOf(manifest["source_path"]))) : "")
+        : "";
+    const fromScript = strOf(ctx.ws.readJsonSafe("script.initial.json")?.["title"]);
+    const fromSource = ctx.options.source ? path.basename(ctx.options.source, path.extname(ctx.options.source)) : "";
+    const name = fromManifest || fromScript || fromSource;
+    ctx.state.projectName = name;
+    return name;
+}
+// --- source-prepare -------------------------------------------------------
+export async function stageSourcePrepare(ctx) {
+    const { options, ws, state } = ctx;
+    const source = options.source;
+    ctx.updateRunState({ status: "init_running", command: "direct init", init_stage: "source_prepare" });
+    ctx.emitProgress("source-prepare");
     let info;
     try {
-        info = await prepareSource(source, workspace);
+        info = await prepareSource(source, options.workspace);
     }
     catch (exc) {
         if (exc instanceof CliError) {
-            updateRunState(workspace, {
+            ctx.updateRunState({
                 status: "init_failed",
                 init_stage: "source_prepare",
                 last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
@@ -1394,7 +1805,7 @@ async function commandInitImpl(opts) {
         }
         const e = exc;
         const receivedError = `${source}: ${e?.name ?? "Error"}${e?.message ? `: ${e.message}` : ""}`;
-        updateRunState(workspace, {
+        ctx.updateRunState({
             status: "init_failed",
             init_stage: "source_prepare",
             last_error: { title: "INIT BLOCKED: Source preparation failed", received: [receivedError], failed_at: checkpointTimestamp() },
@@ -1407,108 +1818,102 @@ async function commandInitImpl(opts) {
         });
     }
     const sourceTextPath = strOf(info["sourceTextPath"]);
-    const sourceText = readText(sourceTextPath);
-    const manifest = makeSourceManifest(source, sourceTextPath, info);
-    updateRunState(workspace, { status: "init_running", init_stage: "episode_plan" });
-    emitInitProgress(workspace, "episode_plan");
+    state.sourceText = readText(sourceTextPath);
+    state.projectName = strOf(info["projectName"]) || path.basename(source, path.extname(source));
+    state.manifest = makeSourceManifest(source, sourceTextPath, info);
+    ws.writeJson("source_manifest.json", state.manifest);
+}
+// --- episode-plan ---------------------------------------------------------
+export async function stageEpisodePlan(ctx) {
+    const { ws, state, options } = ctx;
+    const sourceText = ensureSourceText(ctx);
+    ctx.updateRunState({ status: "init_running", init_stage: "episode_plan" });
+    ctx.emitProgress("episode-plan");
     let plan;
     try {
         plan = buildEpisodePlan(sourceText);
     }
     catch (exc) {
-        const e = exc;
-        throw initFailedReport(workspace, {
+        stageFailure(options.workspace, exc, {
             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: "episode_titles" });
-    const capabilities = providerCapabilities(providerName);
+    state.episodePlan = plan;
+    ws.writeJson("episode_plan.json", plan);
+}
+// --- episode-titles -------------------------------------------------------
+export async function stageEpisodeTitles(ctx) {
+    const { state, options } = ctx;
+    const sourceText = ensureSourceText(ctx);
+    const plan = ensureEpisodePlan(ctx);
+    // Provider capability gate (was inline in commandInitImpl before titles).
+    // Checked twice — declared capabilities, then the constructed provider — but
+    // both fail the same way, so share one report builder.
+    const lacksExtraction = () => initFailedReport(options.workspace, {
+        title: "INIT FAILED: provider lacks batch extraction",
+        stage: "episode_titles",
+        required: ["provider.extractBatch or provider.extractEpisode"],
+        received: [`--provider ${options.providerName}`],
+        nextSteps: ["Use --provider anthropic or --provider mock for direct init."],
+    });
+    const capabilities = providerCapabilities(options.providerName);
     if (capabilities && !capabilities.extractBatch && !capabilities.extractEpisode) {
-        throw initFailedReport(workspace, {
-            title: "INIT FAILED: provider lacks batch extraction",
-            stage: "episode_titles",
-            required: ["provider.extractBatch or provider.extractEpisode"],
-            received: [`--provider ${providerName}`],
-            nextSteps: ["Use --provider anthropic or --provider mock for direct init."],
-        });
-    }
-    let provider;
-    try {
-        provider = makeProvider(providerName, model);
-    }
-    catch (exc) {
-        if (exc instanceof CliError) {
-            updateRunState(workspace, {
-                status: "init_failed",
-                init_stage: "episode_titles",
-                last_error: { title: exc.title, received: exc.received, failed_at: checkpointTimestamp() },
-            });
-        }
-        throw exc;
+        throw lacksExtraction();
     }
+    const provider = ctx.provider();
     if (!provider.extractBatch && !provider.extractEpisode) {
-        throw initFailedReport(workspace, {
-            title: "INIT FAILED: provider lacks batch extraction",
-            stage: "episode_titles",
-            required: ["provider.extractBatch or provider.extractEpisode"],
-            received: [`--provider ${providerName}`],
-            nextSteps: ["Use --provider anthropic or --provider mock for direct init."],
-        });
-    }
-    updateRunState(workspace, { status: "init_running", init_stage: "episode_titles" });
-    emitInitProgress(workspace, "episode_titles");
-    const titleDegraded = await enrichEpisodeTitlesChunked(workspace, sourceText, plan, provider, concurrency);
+        throw lacksExtraction();
+    }
+    ctx.updateRunState({ status: "init_running", init_stage: "episode_titles" });
+    ctx.emitProgress("episode-titles");
+    state.titleDegraded = await enrichEpisodeTitlesChunked(options.workspace, sourceText, plan, provider, options.concurrency);
+    // Titles mutate the plan in place — persist it so the artifact reflects them.
+    ctx.ws.writeJson("episode_plan.json", plan);
+}
+// --- batch-plan -----------------------------------------------------------
+export async function stageBatchPlan(ctx) {
+    const { ws, state, options } = ctx;
+    const sourceText = ensureSourceText(ctx);
+    const plan = ensureEpisodePlan(ctx);
     let batchPlan;
     try {
         batchPlan = buildBatchPlan(sourceText, plan, {
-            targetLines: batchTargetLines,
-            maxChars: batchMaxChars,
-            minLines: batchMinLines,
-            mode: batchMode,
+            targetLines: options.batchTargetLines,
+            maxChars: options.batchMaxChars,
+            minLines: options.batchMinLines,
+            mode: options.batchMode,
         });
     }
     catch (exc) {
-        const e = exc;
-        throw initFailedReport(workspace, {
+        stageFailure(options.workspace, exc, {
             title: "INIT FAILED: Batch planning failed",
             stage: "batch_plan",
             required: ["episode_plan.json that can be split into natural paragraph batches"],
-            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
             nextSteps: ["Inspect workspace/source.txt and episode_plan.json, then rerun init."],
         });
     }
-    writeJson(path.join(dd, "source_manifest.json"), manifest);
-    writeJson(path.join(dd, "episode_plan.json"), plan);
-    writeJson(path.join(dd, "batch_plan.json"), batchPlan);
-    emitInitProgress(workspace, "batch_plan", "success");
-    const episodeResultsDir = path.join(dd, "episode_results");
-    const batchResultsDir = path.join(dd, "batch_results");
-    fs.mkdirSync(episodeResultsDir, { recursive: true });
-    fs.mkdirSync(batchResultsDir, { recursive: true });
-    // Non-destructive GC: drop result/meta/error/md files for units the current
-    // plan no longer references (e.g. the source shed an episode). Pure function
-    // of the plan — it never touches a unit the plan still references, and retires
-    // the legacy v3 index.json. There is no whole-directory reset any more.
+    state.batchPlan = batchPlan;
+    ws.writeJson("batch_plan.json", batchPlan);
+    ctx.emitProgress("batch-plan", "success");
+}
+// --- batch-extract --------------------------------------------------------
+export async function stageBatchExtract(ctx) {
+    const { ws, state, options } = ctx;
+    const sourceText = ensureSourceText(ctx);
+    const plan = ensureEpisodePlan(ctx);
+    const batchPlan = ensureBatchPlan(ctx);
+    const provider = ctx.provider();
+    const episodeResultsDir = ws.mkdir("episode_results");
+    const batchResultsDir = ws.mkdir("batch_results");
+    // Non-destructive GC for units the current plan no longer references.
     gcOrphanUnits(episodeResultsDir, new Set(asList(plan["episodes"]).map((ep) => episodeResultKey(ep))));
     gcOrphanUnits(batchResultsDir, new Set(asList(batchPlan["batches"]).map((b) => batchResultKey(b))));
-    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 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.
+    state.totalEpisodes = asList(plan["episodes"]).length;
+    state.totalBatches = asList(batchPlan["batches"]).length;
+    // Decide which batches to run (force / reuse-done / sticky-error / pending).
     const pending = [];
     let reusedBatchCount = 0;
     let stickyErrorCount = 0;
@@ -1516,7 +1921,7 @@ async function commandInitImpl(opts) {
         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));
+        const forced = options.runAll || options.selEpisodes.has(epNum) || options.selBatches.has(key) || (options.retryErrors && exists(errorPath));
         if (forced) {
             const resultPath = batchResultPath(batchResultsDir, batch);
             if (exists(resultPath))
@@ -1532,74 +1937,98 @@ async function commandInitImpl(opts) {
                 break;
             case "error":
                 stickyErrorCount++;
-                break; // tried and failed; left until explicitly re-run
-            default: pending.push(batch); // never attempted (or corrupt → self-heal)
+                break;
+            default: pending.push(batch);
         }
     }
-    // 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, {
+    state.pending = pending;
+    state.reusedBatchCount = reusedBatchCount;
+    state.stickyErrorCount = stickyErrorCount;
+    state.changedEpisodes = new Set(pending.map((b) => Number(b["episode"])));
+    ctx.updateRunState({
         status: "init_running",
         init_stage: "batch_extract",
-        batch_mode: batchMode,
-        batch_target_lines: batchTargetLines,
-        batch_max_chars: batchMaxChars,
-        batch_min_lines: batchMinLines,
-        episode_total: totalEpisodes,
-        batch_total: totalBatches,
+        batch_mode: options.batchMode,
+        batch_target_lines: options.batchTargetLines,
+        batch_max_chars: options.batchMaxChars,
+        batch_min_lines: options.batchMinLines,
+        episode_total: state.totalEpisodes,
+        batch_total: state.totalBatches,
     });
-    emitInitProgress(workspace, "batch_extract");
-    // Persist each batch the moment it finishes (inside the worker), NOT after the
-    // whole pool drains. Per-unit files have no shared index, so concurrent writes
-    // are safe — and batch_results/ fills up live, so a crash/kill mid-run keeps
-    // every batch already extracted (the resume model depends on this).
-    const outcomes = await pMapWithConcurrency(pending, concurrency, async (batch) => {
+    ctx.emitProgress("batch-extract");
+    const outcomes = await pMapWithConcurrency(pending, options.concurrency, async (batch) => {
         try {
             const result = await extractBatchWithRecovery(provider, sourceText, batch);
             persistBatchResult(batchResultsDir, batch, result);
             const errorPath = batchErrorPath(batchResultsDir, batch);
             if (exists(errorPath))
                 deletePath(errorPath);
-            emitInitProgress(workspace, "batch_extract");
+            ctx.emitProgress("batch-extract");
             return true;
         }
         catch (error) {
             writeBatchFailure(batchResultsDir, batch, error);
-            emitInitProgress(workspace, "batch_extract");
+            ctx.emitProgress("batch-extract");
             return false;
         }
     });
     const freshOk = outcomes.filter((o) => o.ok && o.value === true).length;
     const freshFail = outcomes.filter((o) => o.ok && o.value === false).length;
-    const doneBatches = reusedBatchCount + freshOk;
-    const erroredBatches = stickyErrorCount + freshFail;
-    // 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.
+    state.doneBatches = reusedBatchCount + freshOk;
+    state.erroredBatches = stickyErrorCount + freshFail;
+}
+// --- episode-merge --------------------------------------------------------
+export async function stageEpisodeMerge(ctx) {
+    const { ws, state } = ctx;
+    const sourceText = ensureSourceText(ctx);
+    const plan = ensureEpisodePlan(ctx);
+    const batchPlan = ensureBatchPlan(ctx);
+    const episodeResultsDir = ws.mkdir("episode_results");
+    const batchResultsDir = ws.mkdir("batch_results");
+    // Recompute the bookkeeping a standalone `direct run episode-merge` needs when
+    // batch-extract didn't run this invocation.
+    if (state.totalEpisodes === 0)
+        state.totalEpisodes = asList(plan["episodes"]).length;
+    if (state.totalBatches === 0)
+        state.totalBatches = asList(batchPlan["batches"]).length;
+    const batchesByEpisode = new Map();
+    for (const batch of asList(batchPlan["batches"])) {
+        const epNum = Number(batch["episode"]);
+        if (!batchesByEpisode.has(epNum))
+            batchesByEpisode.set(epNum, []);
+        batchesByEpisode.get(epNum).push(batch);
+    }
+    if (state.doneBatches === 0 && state.erroredBatches === 0) {
+        let done = 0;
+        let errored = 0;
+        for (const batch of asList(batchPlan["batches"])) {
+            const s = classifyBatch(batchResultsDir, batch);
+            if (s === "done")
+                done++;
+            else if (s === "error")
+                errored++;
+        }
+        state.doneBatches = done;
+        state.erroredBatches = errored;
+    }
     const results = [];
     const incompleteEpisodes = [];
-    updateRunState(workspace, {
+    ctx.updateRunState({
         status: "init_running",
         init_stage: "episode_merge",
-        episode_total: totalEpisodes,
-        batch_total: totalBatches,
-        batch_completed: doneBatches,
-        batch_failed: erroredBatches,
+        episode_total: state.totalEpisodes,
+        batch_total: state.totalBatches,
+        batch_completed: state.doneBatches,
+        batch_failed: state.erroredBatches,
     });
-    emitInitProgress(workspace, "episode_merge");
+    ctx.emitProgress("episode-merge");
     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) ?? [];
             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);
@@ -1607,194 +2036,180 @@ async function commandInitImpl(opts) {
             }
             const merged = mergeBatchResultsForEpisode(episode, batchResults);
             validateEpisodeExtractionQuality(sourceText, episode, merged);
-            results.push(merged); // complete episodes only; carries `episode` for the write below
-        }
-        emitInitProgress(workspace, "episode_merge", incompleteEpisodes.length > 0 ? "warning" : "success");
-        // 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.
-        updateRunState(workspace, { status: "init_running", init_stage: "episode_synopsis" });
-        emitInitProgress(workspace, "episode_synopsis");
-        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);
+            results.push(merged);
         }
-        emitInitProgress(workspace, "episode_synopsis", summaryDegradedEpisodes.length > 0 ? "warning" : "success");
     }
     catch (exc) {
-        const e = exc;
-        throw initFailedReport(workspace, {
+        stageFailure(ctx.options.workspace, exc, {
             title: "INIT FAILED: Episode merge failed",
             stage: "episode_merge",
             required: ["batch_results/*.json that can merge into episode_results/*.json"],
-            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
             nextSteps: ["Rerun init; completed batches are reused and episode merge will retry."],
         });
     }
-    results.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
-    incompleteEpisodes.sort((a, b) => a - b);
-    if (incompleteEpisodes.length > 0) {
-        updateRunState(workspace, {
+    state.mergedResults = results;
+    state.incompleteEpisodes = incompleteEpisodes;
+    ctx.emitProgress("episode-merge", incompleteEpisodes.length > 0 ? "warning" : "success");
+}
+// --- episode-synopsis -----------------------------------------------------
+export async function stageEpisodeSynopsis(ctx) {
+    const { ws, state, options } = ctx;
+    const provider = ctx.provider();
+    const episodeResultsDir = ws.mkdir("episode_results");
+    const results = ensureMergedResults(ctx);
+    ctx.updateRunState({ status: "init_running", init_stage: "episode_synopsis" });
+    ctx.emitProgress("episode-synopsis");
+    state.summaryDegradedEpisodes.push(...await resolveEpisodeSynopses(provider, results, {
+        resultsDir: episodeResultsDir,
+        resummarize: options.resummarize,
+        skipSummary: options.skipSummary,
+        changedEpisodes: state.changedEpisodes,
+        concurrency: options.concurrency,
+    }));
+    for (const merged of results) {
+        writeJson(episodeResultPath(episodeResultsDir, merged), compactEpisodeResult(merged));
+        const errPath = episodeErrorPath(episodeResultsDir, merged);
+        if (exists(errPath))
+            deletePath(errPath);
+    }
+    ctx.emitProgress("episode-synopsis", state.summaryDegradedEpisodes.length > 0 ? "warning" : "success");
+    // Incomplete episodes are a resumable, non-error stop. The full-pipeline
+    // runner converts this into the INIT INCOMPLETE report + EXIT_RUNTIME; a
+    // standalone `direct run episode-synopsis` surfaces it the same way.
+    if (state.incompleteEpisodes.length > 0) {
+        state.incompleteEpisodes.sort((a, b) => a - b);
+        ctx.updateRunState({
             status: "init_incomplete",
             init_stage: "batch_extract",
-            episode_total: totalEpisodes,
-            episode_completed: results.length,
-            incomplete_episodes: incompleteEpisodes,
-            batch_total: totalBatches,
-            batch_completed: doneBatches,
-            batch_failed: erroredBatches,
+            episode_total: state.totalEpisodes,
+            episode_completed: state.mergedResults.length,
+            incomplete_episodes: state.incompleteEpisodes,
+            batch_total: state.totalBatches,
+            batch_completed: state.doneBatches,
+            batch_failed: state.erroredBatches,
             last_error: { title: "INIT INCOMPLETE: Some episodes have unextracted batches", failed_at: checkpointTimestamp() },
         });
-        emitInitProgress(workspace, "batch_extract", "error");
-        const report = {
-            title: "INIT INCOMPLETE: Some episodes have unextracted batches",
-            result: [
-                `episodes: ${results.length}/${totalEpisodes} complete`,
-                `incomplete episodes: ${incompleteEpisodes.join(", ")}`,
-                `content: ${doneBatches}/${totalBatches} done, ${erroredBatches} error`,
-                ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
-                `provider: ${providerName}`,
-            ],
-            artifacts: [
-                path.join(workspace, "source.txt"),
-                path.join(dd, "episode_plan.json"),
-                path.join(dd, "batch_plan.json"),
-                batchResultsDir,
-                episodeResultsDir,
-                path.join(dd, "run_state.json"),
-            ],
-            next: [
-                "Run `direct status` to see episode progress.",
-                "Re-run one episode with `direct init --episodes <n>`, or all errors with `--retry-errors`.",
-                "Errored units are left untouched on a plain rerun; select them to retry.",
-            ],
-        };
-        return [report, EXIT_RUNTIME];
+        ctx.emitProgress("batch-extract", "error");
+        throw new StageIncomplete();
     }
-    updateRunState(workspace, {
+    state.mergedResults.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
+}
+// --- script-merge ---------------------------------------------------------
+export async function stageScriptMerge(ctx) {
+    const { ws, state, options } = ctx;
+    const results = ensureMergedResults(ctx);
+    ctx.updateRunState({
         status: "init_running",
         init_stage: "script_merge",
-        episode_total: totalEpisodes,
+        episode_total: state.totalEpisodes || asList((ensureEpisodePlan(ctx))["episodes"]).length,
         episode_completed: results.length,
         incomplete_episodes: [],
-        batch_total: totalBatches,
-        batch_completed: doneBatches,
-        batch_failed: erroredBatches,
+        batch_total: state.totalBatches,
+        batch_completed: state.doneBatches,
+        batch_failed: state.erroredBatches,
         last_error: null,
     });
-    let script;
-    const assetNormalizationPath = path.join(dd, "asset_normalization.json");
-    const assetMetadataPath = path.join(dd, "asset_metadata.json");
-    let assetNormalization = null;
+    ctx.emitProgress("script-merge");
     try {
-        emitInitProgress(workspace, "script_merge");
-        const merged = mergeEpisodeResultsWithReport(results, strOf(info["projectName"]) || path.basename(source, path.extname(source)));
-        script = merged.script;
-        assetNormalization = merged.assetNormalization;
-        writeJson(assetNormalizationPath, assetNormalization);
+        const merged = mergeEpisodeResultsWithReport(results, ensureProjectName(ctx));
+        state.script = merged.script;
+        state.assetNormalization = merged.assetNormalization;
+        ws.writeJson("asset_normalization.json", state.assetNormalization);
     }
     catch (exc) {
-        const e = exc;
-        throw initFailedReport(workspace, {
+        stageFailure(options.workspace, exc, {
             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: { episode_completed: results.length },
         });
     }
+}
+// --- asset-curation -------------------------------------------------------
+export async function stageAssetCuration(ctx) {
+    const { ws, state, options } = ctx;
+    const script = ensureScript(ctx);
     try {
-        updateRunState(workspace, { status: "init_running", init_stage: "asset_curation" });
-        emitInitProgress(workspace, "asset_curation");
-        // 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.
+        ctx.updateRunState({ status: "init_running", init_stage: "asset_curation" });
+        ctx.emitProgress("asset-curation");
         const curation = curateScriptAssets(script);
-        writeJson(path.join(dd, "asset_curation.json"), curation);
+        ws.writeJson("asset_curation.json", curation);
     }
     catch (exc) {
-        // 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, {
+        stageFailure(options.workspace, exc, {
             title: "INIT FAILED: Asset curation failed",
             stage: "asset_curation",
             required: ["a well-formed assembled script for deterministic asset curation"],
-            received: [`${e?.name ?? "Error"}: ${(e?.message ?? "").slice(0, 160)}`],
             nextSteps: ["Rerun init; completed extraction checkpoints will be reused."],
-            updates: { episode_completed: results.length },
+            updates: { episode_completed: state.mergedResults.length },
         });
     }
-    emitInitProgress(workspace, "asset_curation", "success");
-    if (skipMetadata) {
-        updateRunState(workspace, { status: "init_running", init_stage: "metadata_extract", metadata_skipped: true });
+    ctx.emitProgress("asset-curation", "success");
+}
+// --- metadata -------------------------------------------------------------
+export async function stageMetadata(ctx) {
+    const { ws, state, options } = ctx;
+    const script = ensureScript(ctx);
+    const sourceText = ensureSourceText(ctx);
+    const assetMetadataPath = ws.pathOf("asset_metadata.json");
+    if (options.skipMetadata) {
+        ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: true });
         if (exists(assetMetadataPath))
             deletePath(assetMetadataPath);
-        emitInitProgress(workspace, "metadata_extract", "skipped");
+        ctx.emitProgress("metadata", "skipped");
+        return;
     }
-    else {
-        try {
-            updateRunState(workspace, { status: "init_running", init_stage: "metadata_extract", metadata_skipped: false });
-            emitInitProgress(workspace, "metadata_extract");
-            let metadata = provider.extractMetadata ? await provider.extractMetadata(sourceText, script) : {};
-            if (!isDict(metadata))
-                metadata = {};
-            writeJson(assetMetadataPath, metadata);
-            applyMetadataToScript(script, metadata);
-        }
-        catch (exc) {
-            if (exc instanceof CliError) {
-                throw initFailedReport(workspace, {
-                    title: exc.title,
-                    stage: "metadata_extract",
-                    exitCode: exc.exitCode,
-                    errorCode: exc.errorCode,
-                    required: exc.required.length > 0 ? exc.required : ["metadata JSON matching final script contract"],
-                    received: exc.received.length > 0 ? exc.received : [String(exc.message).slice(0, 160)],
-                    nextSteps: exc.nextSteps.length > 0 ? exc.nextSteps : ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
-                    updates: { episode_completed: results.length },
-                });
-            }
-            const e = exc;
-            throw initFailedReport(workspace, {
-                title: "INIT FAILED: Metadata extraction failed",
+    const provider = ctx.provider();
+    try {
+        ctx.updateRunState({ status: "init_running", init_stage: "metadata_extract", metadata_skipped: false });
+        ctx.emitProgress("metadata");
+        let metadata = provider.extractMetadata ? await provider.extractMetadata(sourceText, script) : {};
+        if (!isDict(metadata))
+            metadata = {};
+        ws.writeJson("asset_metadata.json", metadata);
+        applyMetadataToScript(script, metadata);
+    }
+    catch (exc) {
+        if (exc instanceof CliError) {
+            throw initFailedReport(options.workspace, {
+                title: exc.title,
                 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: { episode_completed: results.length },
+                exitCode: exc.exitCode,
+                errorCode: exc.errorCode,
+                required: exc.required.length > 0 ? exc.required : ["metadata JSON matching final script contract"],
+                received: exc.received.length > 0 ? exc.received : [String(exc.message).slice(0, 160)],
+                nextSteps: exc.nextSteps.length > 0 ? exc.nextSteps : ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
+                updates: { episode_completed: state.mergedResults.length },
             });
         }
-        emitInitProgress(workspace, "metadata_extract", "success");
+        stageFailure(options.workspace, exc, {
+            title: "INIT FAILED: Metadata extraction failed",
+            stage: "metadata_extract",
+            required: ["provider metadata for worldview, role_type, and asset descriptions"],
+            nextSteps: ["Rerun init; extraction checkpoints will be reused and metadata will retry."],
+            updates: { episode_completed: state.mergedResults.length },
+        });
     }
-    // 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.
+    ctx.emitProgress("metadata", "success");
+}
+// --- script-synopsis ------------------------------------------------------
+export async function stageScriptSynopsis(ctx) {
+    const { ws, state, options } = ctx;
+    const script = ensureScript(ctx);
+    const provider = ctx.provider();
     let summaryFullDegraded = false;
     let summaryDegradeReason = "";
     try {
-        updateRunState(workspace, { status: "init_running", init_stage: "script_synopsis" });
-        emitInitProgress(workspace, "script_synopsis");
+        ctx.updateRunState({ status: "init_running", init_stage: "script_synopsis" });
+        ctx.emitProgress("script-synopsis");
         const summary = await buildScriptSynopsis(provider, script, {
-            dd,
-            thresholdChars: summaryThresholdChars,
+            dd: ws.dir,
+            thresholdChars: options.summaryThresholdChars,
             groupSize: DEFAULT_SUMMARY_GROUP_SIZE,
-            resummarize,
-            skipSummary,
-            concurrency,
+            resummarize: options.resummarize,
+            skipSummary: options.skipSummary,
+            concurrency: options.concurrency,
         });
         summaryFullDegraded = summary.degraded;
         summaryDegradeReason = summary.reason ?? "";
@@ -1803,116 +2218,44 @@ async function commandInitImpl(opts) {
         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, {
-        summary_skipped: skipSummary,
+    state.summaryFullDegraded = summaryFullDegraded;
+    state.summaryDegradeReason = summaryDegradeReason;
+    state.summaryDegradedEpisodes.sort((a, b) => a - b);
+    const summaryDegraded = summaryFullDegraded || state.summaryDegradedEpisodes.length > 0;
+    // Persist script.initial.json now that the overview fields are assigned — the
+    // same write point as the god-command (right after the synopsis stage).
+    ws.writeJson("script.initial.json", script);
+    ctx.updateRunState({
+        summary_skipped: options.skipSummary,
         summary_degraded: summaryDegraded,
-        summary_degraded_episodes: summaryDegradedEpisodes,
+        summary_degraded_episodes: state.summaryDegradedEpisodes,
         summary_degraded_reason: summaryDegradeReason || null,
     });
-    emitInitProgress(workspace, "script_synopsis", summaryDegraded ? "warning" : skipSummary ? "skipped" : "success");
-    updateRunState(workspace, { status: "init_running", init_stage: "validate" });
-    emitInitProgress(workspace, "validate");
+    ctx.emitProgress("script-synopsis", summaryDegraded ? "warning" : options.skipSummary ? "skipped" : "success");
+}
+// --- validate -------------------------------------------------------------
+export async function stageValidate(ctx) {
+    const { ws, state, options } = ctx;
+    ensureScript(ctx); // ensures script.initial.json exists on disk for validateScript
+    const scriptPath = ws.pathOf("script.initial.json");
+    ctx.updateRunState({ status: "init_running", init_stage: "validate" });
+    ctx.emitProgress("validate");
     let validation;
     try {
-        validation = validateScript(workspace, scriptPath);
+        validation = validateScript(options.workspace, scriptPath);
     }
     catch (exc) {
-        const e = exc;
-        throw initFailedReport(workspace, {
+        stageFailure(options.workspace, exc, {
             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: { script_path: scriptPath },
         });
     }
+    state.validation = validation;
     const passed = Boolean(validation["passed"]);
-    const status = passed ? "ready_for_agent" : "needs_agent_repair";
-    updateRunState(workspace, {
-        status,
-        command: "direct init",
-        init_stage: "complete",
-        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: totalEpisodes,
-        episode_completed: results.length,
-        incomplete_episodes: [],
-        batch_total: totalBatches,
-        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,
-        metadata_skipped: skipMetadata,
-        last_error: null,
-    });
-    emitInitProgress(workspace, "validate", passed ? "success" : "warning");
-    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 normalizationSummary = assetNormalization?.summary ?? {
-        asset_merges: 0,
-        location_states_from_names: 0,
-        location_states_from_time: 0,
-        review_items: 0,
-    };
-    const report = {
-        title,
-        result: [
-            `episodes: ${stats["episodes"] ?? 0}`,
-            `scenes: ${stats["scenes"] ?? 0}`,
-            `actions: ${stats["actions"] ?? 0}`,
-            `validation: ${passed ? "passed" : "needs repair"}`,
-            `provider: ${providerName}`,
-            `episodes: ${results.length}/${totalEpisodes} complete`,
-            `content: ${doneBatches}/${totalBatches} done`,
-            `normalization: merges=${normalizationSummary.asset_merges}, states=${normalizationSummary.location_states_from_names + normalizationSummary.location_states_from_time}, review=${normalizationSummary.review_items}`,
-            ...(skipMetadata ? ["metadata: skipped"] : []),
-            ...(titleDegraded.length > 0 ? [`titles degraded (deterministic): ${titleDegraded.join(", ")}`] : []),
-            ...(summaryLine ? [summaryLine] : []),
-        ],
-        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,
-            assetNormalizationPath,
-            path.join(dd, "asset_curation.json"),
-            ...(skipMetadata ? [] : [assetMetadataPath]),
-            path.join(dd, "synopsis.json"),
-            scriptPath,
-            path.join(dd, "validation.json"),
-            path.join(dd, "run_state.json"),
-        ],
-        issues: summarizeIssues(asList(validation["issues"])),
-        next: providerName === "mock"
-            ? [
-                "Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export.",
-                "Do not export mock-provider results for delivery.",
-            ]
-            : ["Run `direct review` (add --episode <n> for source↔extract); edit with --draft if needed; then validate/export."],
-    };
-    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+    ctx.emitProgress("validate", passed ? "success" : "warning");
 }
 // ---------------------------------------------------------------------------
 // command_status — the agent-facing state table, derived entirely from disk: a