@lingjingai/scriptctl 0.1.0 → 0.3.0

package/dist/usecases/episode.js

@@ -0,0 +1,1209 @@
+/**
+ * `scriptctl episode` subcommand group.
+ *
+ * Atomic per-episode production loop for the creative mainline (灵感线 / 小说线 / 原创线
+ * → 剧本). The five commands compose into three modes:
+ *
+ *   - **single**: user manually drives `draft → preview → commit` for each episode
+ *   - **batch**:  `episode batch --range a-b` internally loops draft → preview;
+ *                 user commits each episode after reviewing
+ *   - **mixed**:  first N episodes single (to lock in style), then batch
+ *
+ * The orchestrator is intentionally thin. Heavy lifting lives elsewhere:
+ *   - prompt assembly + provider call → `infra/gemini-writer.ts`
+ *   - markdown parsing → `domain/direct-core.ts::parseMarkdownBatch(.., {fragmentMode:true})`
+ *   - asset state → `domain/asset-registry.ts`
+ *   - collision detection → `domain/collision-detector.ts`
+ *   - gateway upload → existing `infra/script-output-api.ts` (commit calls it)
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, MARKDOWN_BATCH_PROMPT_SPEC, SCRIPT_SCHEMA_VERSION, exists, readJson, readText, sha256Text, writeJson, writeText, } from "../common.js";
+import { applyFragment, defaultRegistryPath, loadRegistry, rollbackEpisode, saveRegistry, } from "../domain/asset-registry.js";
+import { detectCollisions, hasHardCollision, summarizeReports, } from "../domain/collision-detector.js";
+import { isTechnicalEpisodeTitle, mergeEpisodeResults, parseMarkdownBatch } from "../domain/direct-core.js";
+import { validateScript } from "../domain/script-core.js";
+import { ScriptOutputApiError } from "../infra/script-output-api.js";
+import { summarizeIssues } from "./direct.js";
+import { apiErrorToCli, currentRevisionOrZero, scriptOutputClient, sortDeep, } from "./script.js";
+import { DEFAULT_WRITING_PROMPT, injectSpec } from "../infra/default-writing-prompt.js";
+import { dedupeRefs, draftEpisode, loadWriterContext, parseRefArg, } from "../infra/gemini-writer.js";
+import { GeminiProvider, MockProvider } from "../infra/providers.js";
+/**
+ * Concentrate the parser → registry type bridge here. `parseMarkdownBatch` returns
+ * a generic `Dict` (so it can be reused across direct init and episode fragments),
+ * but downstream registry / collision-detector accept the structurally-narrower
+ * `FragmentLike`. Casting in one place keeps the call sites clean and the unsafe
+ * boundary visible.
+ */
+function asFragment(d) {
+    return d;
+}
+/** Default episode-writer provider. Override via `--provider`. */
+const DEFAULT_EPISODE_PROVIDER = "gemini";
+function resolveContextSpec(opts) {
+    let refs = [];
+    if (Array.isArray(opts.ref) && opts.ref.length > 0) {
+        try {
+            refs = dedupeRefs(opts.ref.map((raw) => parseRefArg(raw)));
+        }
+        catch (exc) {
+            throw new CliError("DRAFT FAILED: --ref format invalid", "Invalid --ref format.", {
+                exitCode: EXIT_USAGE,
+                required: ['--ref "<title>=<path>"'],
+                received: [String(exc.message ?? exc)],
+                nextSteps: ['Example: --ref "全局设定=analysis-workspace/全局设定.md"'],
+            });
+        }
+    }
+    return { refs, outlineTemplate: opts.outline };
+}
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+function padded(n) {
+    return String(n).padStart(2, "0");
+}
+function episodeDir(workspace) {
+    return path.join(workspace, "episodes");
+}
+function epMdPath(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.md`);
+}
+function epJsonPath(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.json`);
+}
+function epLintPath(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.lint.json`);
+}
+function epCollisionPath(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.collision.json`);
+}
+function epHistoryDir(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.history`);
+}
+function epMarkerPath(workspace, n) {
+    return path.join(episodeDir(workspace), `.done-${padded(n)}`);
+}
+function metaPath(workspace) {
+    return path.join(episodeDir(workspace), "meta.json");
+}
+function outlinePath(workspace, n) {
+    return path.join(episodeDir(workspace), `ep${padded(n)}.outline.md`);
+}
+function mergedDir(workspace) {
+    return path.join(episodeDir(workspace), ".merged");
+}
+function mergedScriptPath(workspace) {
+    return path.join(mergedDir(workspace), "script.json");
+}
+function mergeReceiptPath(workspace) {
+    return path.join(mergedDir(workspace), "merge-receipt.json");
+}
+function pushReceiptPath(workspace) {
+    return path.join(mergedDir(workspace), "push-receipt.json");
+}
+// ---------------------------------------------------------------------------
+// Episode title extraction (from outline H1) — hard-failed in draft if absent
+// ---------------------------------------------------------------------------
+const EPISODE_TITLE_RE = /^#+\s*第\s*\d+\s*集\s*[:：\-—\s]+(.+?)\s*$/;
+function resolveOutlinePath(workspace, n, outlineOverride) {
+    if (!outlineOverride)
+        return outlinePath(workspace, n);
+    // Accept literal path or {NN}-template (same convention as loadWriterContext).
+    return outlineOverride.replace(/\{NN\}/g, padded(n));
+}
+function extractEpisodeTitle(workspace, n, outlineOverride) {
+    const p = resolveOutlinePath(workspace, n, outlineOverride);
+    if (!exists(p)) {
+        throw new CliError("DRAFT FAILED: outline file missing", "Outline file missing.", {
+            exitCode: EXIT_INPUT,
+            required: [p],
+            received: ["no file at that path"],
+            nextSteps: [
+                `Create ${p} with a heading like "# 第 ${n} 集：副标题" + 集纲内容.`,
+            ],
+        });
+    }
+    const text = readText(p);
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        const m = EPISODE_TITLE_RE.exec(line);
+        if (m && m[1]?.trim()) {
+            const title = m[1].trim();
+            // Defense in depth: don't pass through "技术值" titles like "第2集" / "ep_001" —
+            // those would pass our regex but fail validateScript later, defeating the whole
+            // "fix at source" guarantee. Catch them here.
+            if (isTechnicalEpisodeTitle(title)) {
+                throw new CliError("DRAFT FAILED: outline title looks technical, not a real 副标题", "Episode title looks like a placeholder.", {
+                    exitCode: EXIT_USAGE,
+                    required: [`first H1 in ${p} to contain a meaningful 副标题 (not "第N集" / "ep_001" / pure digits)`],
+                    received: [`extracted: "${title}"`],
+                    nextSteps: [
+                        `Replace the H1 with something like "# 第 ${n} 集：开场撞奥特曼" — a real one-line plot hook.`,
+                        "Generic / technical titles trip publish-time schema validation; only real 副标题 keep the chain clean.",
+                    ],
+                });
+            }
+            return title;
+        }
+        break; // First non-blank line must match; otherwise fail
+    }
+    throw new CliError("DRAFT FAILED: episode title not found in outline H1", "Episode title required.", {
+        exitCode: EXIT_USAGE,
+        required: [`first non-blank line of ${p} matching "# 第 N 集：副标题"`],
+        received: [`first line: ${text.split(/\r?\n/).find((l) => l.trim()) ?? "<empty file>"}`],
+        nextSteps: [
+            `Add a heading as the first line, e.g. "# 第 ${n} 集：开场撞奥特曼".`,
+            "Title goes into the assembled script.episodes[i].title; without it, publish would either fail validation or upload an unnamed episode.",
+        ],
+    });
+}
+function checkGatewayEnv(projectGroupOverride) {
+    const gatewayUrl = (process.env.SCRIPTCTL_GATEWAY_URL || process.env.AWB_BASE_URL || "").trim();
+    const accessKey = (process.env.SCRIPTCTL_ACCESS_KEY ||
+        process.env.AWB_ACCESS_KEY ||
+        process.env.AWB_CODE ||
+        process.env.X_ACCESS_KEY ||
+        "").trim();
+    const projectGroup = (projectGroupOverride || process.env.SANDBOX_PROJECT_GROUP_NO || "").trim();
+    const missing = [];
+    if (!gatewayUrl)
+        missing.push("SCRIPTCTL_GATEWAY_URL (or AWB_BASE_URL)");
+    if (!accessKey)
+        missing.push("SCRIPTCTL_ACCESS_KEY (or AWB_ACCESS_KEY / AWB_CODE / X_ACCESS_KEY)");
+    if (!projectGroup)
+        missing.push("SANDBOX_PROJECT_GROUP_NO (or --project-group-no on publish)");
+    const tick = (ok) => (ok ? "✓" : "✗ MISSING");
+    const table = [
+        `  Gateway URL              ${tick(Boolean(gatewayUrl))}${gatewayUrl ? ` ${gatewayUrl}` : ""}`,
+        `  Access key               ${tick(Boolean(accessKey))}`,
+        `  Project group number     ${tick(Boolean(projectGroup))}${projectGroup ? ` ${projectGroup}` : ""}`,
+    ].join("\n");
+    return { ready: missing.length === 0, table, missing };
+}
+// ---------------------------------------------------------------------------
+// Provider factory
+// ---------------------------------------------------------------------------
+function makeWriterProvider(name, model) {
+    // episode draft 仅支持 gemini（生产）+ mock（测试）。Claude 走 direct init 等结构化抽取
+    // 路径，不混进创作正文，避免 agent / 用户在写剧本时纠结模型选择。
+    if (name === "gemini")
+        return new GeminiProvider(model);
+    if (name === "mock")
+        return new MockProvider();
+    throw new CliError("DRAFT FAILED: Unsupported provider", "Unsupported provider.", {
+        exitCode: EXIT_USAGE,
+        required: ["--provider: gemini (default) | mock (tests only)"],
+        received: [`--provider: ${name}`],
+        nextSteps: ["Omit --provider to use Gemini, or pass --provider mock for tests."],
+    });
+}
+// ---------------------------------------------------------------------------
+// Option parsing
+// ---------------------------------------------------------------------------
+function requireEpisode(opts) {
+    const arg = opts._args?.[0];
+    if (!arg) {
+        throw new CliError("USAGE ERROR: Missing episode number", "Missing episode number.", {
+            exitCode: EXIT_USAGE,
+            required: ["<n>"],
+            received: ["no positional argument"],
+            nextSteps: ["Pass the episode number, e.g. `scriptctl episode draft 1`."],
+        });
+    }
+    const n = parseInt(arg, 10);
+    if (!Number.isFinite(n) || n < 1) {
+        throw new CliError("USAGE ERROR: Invalid episode number", "Invalid episode number.", {
+            exitCode: EXIT_USAGE,
+            required: ["positive integer episode number"],
+            received: [arg],
+            nextSteps: ["Pass a positive integer, e.g. `scriptctl episode draft 5`."],
+        });
+    }
+    return n;
+}
+function parseRange(raw) {
+    if (!raw) {
+        throw new CliError("USAGE ERROR: --range required", "--range required.", {
+            exitCode: EXIT_USAGE,
+            required: ["--range a-b"],
+            received: ["no --range option"],
+            nextSteps: ["Pass --range 1-10."],
+        });
+    }
+    const m = /^(\d+)-(\d+)$/.exec(raw.trim());
+    if (!m) {
+        throw new CliError("USAGE ERROR: Invalid --range format", "Invalid --range format.", {
+            exitCode: EXIT_USAGE,
+            required: ["--range a-b (e.g. 1-10)"],
+            received: [`--range ${raw}`],
+            nextSteps: ["Use --range 1-10."],
+        });
+    }
+    const a = parseInt(m[1], 10);
+    const b = parseInt(m[2], 10);
+    if (a < 1 || b < a) {
+        throw new CliError("USAGE ERROR: Invalid --range bounds", "Invalid --range bounds.", {
+            exitCode: EXIT_USAGE,
+            required: ["1 <= a <= b"],
+            received: [`a=${a}, b=${b}`],
+            nextSteps: ["Pass a range like --range 1-10 with a >= 1 and b >= a."],
+        });
+    }
+    return [a, b];
+}
+// ---------------------------------------------------------------------------
+// History archiving
+// ---------------------------------------------------------------------------
+function archivePriorVersion(workspace, n) {
+    const mdPath = epMdPath(workspace, n);
+    if (!exists(mdPath))
+        return null;
+    const dir = epHistoryDir(workspace, n);
+    fs.mkdirSync(dir, { recursive: true });
+    let version = 1;
+    while (fs.existsSync(path.join(dir, `ep${padded(n)}.v${version}.md`)))
+        version++;
+    const target = path.join(dir, `ep${padded(n)}.v${version}.md`);
+    fs.copyFileSync(mdPath, target);
+    return target;
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function loadRegistryAt(workspace) {
+    const registryPath = defaultRegistryPath(workspace);
+    return { registry: loadRegistry(registryPath), registryPath };
+}
+function ensureEpisodeDir(workspace) {
+    fs.mkdirSync(episodeDir(workspace), { recursive: true });
+}
+function writeFragment(workspace, n, fragment, raw) {
+    ensureEpisodeDir(workspace);
+    writeText(epMdPath(workspace, n), raw);
+    writeJson(epJsonPath(workspace, n), fragment);
+}
+function writeCollisionReport(workspace, n, reports) {
+    ensureEpisodeDir(workspace);
+    writeJson(epCollisionPath(workspace, n), { episode: n, generatedAt: new Date().toISOString(), collisions: reports });
+}
+function clearCollisionReport(workspace, n) {
+    const p = epCollisionPath(workspace, n);
+    if (exists(p))
+        fs.rmSync(p, { force: true });
+}
+// ---------------------------------------------------------------------------
+// `episode draft` — internal phase helpers
+// ---------------------------------------------------------------------------
+function loadPromptTemplate(promptTemplatePath) {
+    if (!promptTemplatePath)
+        return DEFAULT_WRITING_PROMPT;
+    if (!exists(promptTemplatePath)) {
+        throw new CliError("DRAFT FAILED: prompt template not found", "Prompt template not found.", {
+            exitCode: EXIT_INPUT,
+            required: [promptTemplatePath],
+            received: ["no file at that path"],
+            nextSteps: ["Verify the --prompt-template path is correct, or omit it to use scriptctl's bundled default."],
+        });
+    }
+    // Apply the same placeholder substitution the bundled prompt uses, so skill-supplied
+    // templates can `<!-- MARKDOWN_BATCH_PROMPT_SPEC -->` to inherit the parser spec
+    // and stay in sync as it evolves. Without this, custom templates that use the
+    // placeholder ship the literal comment text to the LLM, which then has no idea
+    // what spec markdown grammar to follow.
+    return injectSpec(readText(promptTemplatePath));
+}
+function applyRegenIfRequested(workspace, episode, regen) {
+    if (regen !== true)
+        return;
+    archivePriorVersion(workspace, episode);
+    // Skip rollback when the episode is already committed (marker file present) —
+    // those ids are authoritative and a re-draft will reuse them by name.
+    if (!exists(epMarkerPath(workspace, episode))) {
+        const { registry, registryPath } = loadRegistryAt(workspace);
+        rollbackEpisode(registry, episode);
+        saveRegistry(registryPath, registry);
+    }
+}
+/**
+ * Produce the raw spec markdown for this draft. Source is one of:
+ *   - --resume    : read the existing ep<n>.md (skip provider)
+ *   - --from-md   : read user-provided spec md (skip provider)
+ *   - otherwise   : invoke provider; retry once with parser-feedback on parse failure
+ */
+async function produceRawMd(opts, workspace, episode, episodeTitle) {
+    if (opts.resume === true) {
+        const mdPath = epMdPath(workspace, episode);
+        if (!exists(mdPath)) {
+            throw new CliError("DRAFT FAILED: --resume requires existing ep<n>.md", "Resume target missing.", {
+                exitCode: EXIT_INPUT,
+                required: [mdPath],
+                received: ["no file at that path"],
+                nextSteps: ["Run `scriptctl episode draft <n>` first to create the draft, or pass --from-md <path>."],
+            });
+        }
+        return { rawMd: readText(mdPath) };
+    }
+    if (opts.from_md) {
+        if (!exists(opts.from_md)) {
+            throw new CliError("DRAFT FAILED: --from-md path not found", "Spec markdown not found.", {
+                exitCode: EXIT_INPUT,
+                required: [opts.from_md],
+                received: ["no file at that path"],
+                nextSteps: ["Pass --from-md pointing at a real .md file."],
+            });
+        }
+        return { rawMd: readText(opts.from_md) };
+    }
+    // Provider path
+    const promptTemplate = loadPromptTemplate(opts.prompt_template);
+    applyRegenIfRequested(workspace, episode, opts.regen);
+    const spec = resolveContextSpec(opts);
+    let writerContext;
+    try {
+        writerContext = loadWriterContext({
+            workspace,
+            episode,
+            outlineTemplate: spec.outlineTemplate,
+            refs: spec.refs,
+        });
+    }
+    catch (exc) {
+        throw new CliError("DRAFT FAILED: cannot load writer context", "Cannot load writer context.", {
+            exitCode: EXIT_INPUT,
+            required: ["per-episode 集纲 file"],
+            received: [String(exc.message ?? exc)],
+            nextSteps: [
+                "Pass --outline <path-or-template> (e.g. --outline workspace/episodes/ep{NN}.outline.md), or",
+                `Place the outline at ${path.join(workspace, "episodes", `ep${padded(episode)}.outline.md`)}.`,
+            ],
+        });
+    }
+    const { registry } = loadRegistryAt(workspace);
+    const provider = makeWriterProvider(opts.provider ?? DEFAULT_EPISODE_PROVIDER, opts.model);
+    const maxTokens = opts.max_tokens ? parseInt(opts.max_tokens, 10) : undefined;
+    const baseReq = { episode, context: writerContext, registry, promptTemplate };
+    const first = await draftEpisode(provider, baseReq);
+    try {
+        parseMarkdownBatch(first.raw, { episode, title: episodeTitle }, { fragmentMode: true });
+        return { rawMd: first.raw, composedPrompt: first.prompt };
+    }
+    catch (parseErr) {
+        // One retry with parser feedback before giving up.
+        const detail = parseErr instanceof CliError ? parseErr.received.join("\n") : String(parseErr);
+        const retry = await draftEpisode(provider, { ...baseReq, parserErrorFeedback: detail, maxTokens });
+        try {
+            parseMarkdownBatch(retry.raw, { episode, title: episodeTitle }, { fragmentMode: true });
+            return { rawMd: retry.raw, composedPrompt: retry.prompt };
+        }
+        catch (finalErr) {
+            ensureEpisodeDir(workspace);
+            archivePriorVersion(workspace, episode);
+            writeText(epMdPath(workspace, episode), retry.raw);
+            throw new CliError("DRAFT FAILED: provider output still invalid after retry", "Provider output still invalid after retry.", {
+                exitCode: EXIT_RUNTIME,
+                required: ["spec-md markdown that parseMarkdownBatch can ingest"],
+                received: [finalErr instanceof CliError ? finalErr.received.join(" | ") : String(finalErr)],
+                nextSteps: [
+                    `Inspect ${epMdPath(workspace, episode)} and re-run with --regen, or fix the outline / prompt and re-run.`,
+                ],
+            });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// `episode draft`
+// ---------------------------------------------------------------------------
+export async function commandEpisodeDraft(opts) {
+    const workspace = opts.workspace_path ?? "workspace";
+    const episode = requireEpisode(opts);
+    // Step 1: pull episode title from outline H1. Hard fail if missing — title is
+    // mandatory for assembled publish and must come from a single canonical source
+    // (the outline file the agent already writes), not patched in after upload. Honors
+    // --outline so `--from-md` + non-default outline locations keep title and body in sync.
+    const episodeTitle = extractEpisodeTitle(workspace, episode, opts.outline);
+    // Step 2: clear leftover lint / collision reports from a previous attempt. Without
+    // this, status command + agent inspections see stale data when a prior run wrote
+    // them but the current run takes an early-exit branch that skips re-writing.
+    const lintFile = epLintPath(workspace, episode);
+    if (exists(lintFile))
+        fs.rmSync(lintFile, { force: true });
+    clearCollisionReport(workspace, episode);
+    // Step 3: produce raw spec markdown (resume / from-md / provider with retry).
+    const skipDraft = opts.resume === true || Boolean(opts.from_md);
+    const { rawMd, composedPrompt } = await produceRawMd(opts, workspace, episode, episodeTitle);
+    // Parse + collision-check (always runs, including --resume / --from-md). Title is the
+    // extracted outline H1 — flows through to the assembled script's episodes[i].title.
+    let fragment;
+    try {
+        fragment = parseMarkdownBatch(rawMd, { episode, title: episodeTitle }, { fragmentMode: true });
+    }
+    catch (exc) {
+        ensureEpisodeDir(workspace);
+        writeText(epMdPath(workspace, episode), rawMd);
+        if (exc instanceof CliError)
+            throw exc;
+        throw new CliError("DRAFT FAILED: parse error", "Parse error.", {
+            exitCode: EXIT_RUNTIME,
+            required: ["spec-md markdown"],
+            received: [String(exc)],
+            nextSteps: [`Inspect ${epMdPath(workspace, episode)} and fix the markdown manually, then re-run with --resume.`],
+        });
+    }
+    const { registry, registryPath } = loadRegistryAt(workspace);
+    const fragmentLike = asFragment(fragment);
+    // Don't mutate the registry yet — collision-check first
+    const reports = detectCollisions(fragmentLike, registry, { episode });
+    // Persist the fragment (md + json) regardless of collisions — so the agent can edit
+    writeFragment(workspace, episode, fragment, rawMd);
+    if (hasHardCollision(reports)) {
+        writeCollisionReport(workspace, episode, reports);
+        const summary = summarizeReports(reports);
+        const sourceLabel = skipDraft ? (opts.resume === true ? "--resume" : "--from-md") : "Gemini draft";
+        return [
+            {
+                title: `DRAFT BLOCKED: 资产冲突 (ep${padded(episode)})`,
+                message: "Episode drafted but blocked by asset collisions; agent must resolve.",
+                summary,
+                artifacts: [epMdPath(workspace, episode), epJsonPath(workspace, episode), epCollisionPath(workspace, episode)],
+                next: [
+                    `Read ${epCollisionPath(workspace, episode)} for structured collision details.`,
+                    `Edit ${epMdPath(workspace, episode)} per the resolution guidance, then re-run with --resume.`,
+                ],
+                episode,
+                sourceLabel,
+            },
+            EXIT_NEEDS_AGENT,
+        ];
+    }
+    // No hard collisions — register the fragment in the registry as uncommitted-pending-checks
+    clearCollisionReport(workspace, episode);
+    applyFragment(registry, fragmentLike, episode);
+    saveRegistry(registryPath, registry);
+    const softReports = reports.filter((r) => r.kind === "soft");
+    // Step 2: lint (absorbed from old `episode preview`) — single-episode quality checks
+    const lint = lintEpisodeStub(fragment);
+    writeJson(epLintPath(workspace, episode), lint);
+    if (lint.critical.length > 0) {
+        // Roll back the registration so the next attempt isn't confused by half-committed state.
+        rollbackEpisode(registry, episode);
+        saveRegistry(registryPath, registry);
+        return [
+            {
+                title: `DRAFT BLOCKED: lint critical (ep${padded(episode)})`,
+                message: `Episode ${episode} drafted but lint critical findings block commit.`,
+                issues: lint.critical.map((s) => `[critical] ${s}`),
+                warnings: [...lint.major.map((s) => `[major] ${s}`), ...lint.minor.map((s) => `[minor] ${s}`)],
+                artifacts: [epMdPath(workspace, episode), epJsonPath(workspace, episode), epLintPath(workspace, episode)],
+                next: [
+                    `Fix the critical issues in ${epMdPath(workspace, episode)}, then re-run with \`scriptctl episode draft ${episode} --resume\` (skips Gemini).`,
+                    `Or regenerate from scratch: \`scriptctl episode draft ${episode} --regen\`.`,
+                ],
+                episode,
+            },
+            EXIT_NEEDS_AGENT,
+        ];
+    }
+    // Step 3: assembled validation (absorbed from old `episode publish` end-gate, moved to source).
+    // Cross-episode issues (missing actor refs, schema drift, meta worldview validity) surface
+    // here — at the moment they were introduced, not after a long publish chain.
+    const validation = runAssembledValidation(workspace, episode, fragment);
+    if (validation.blocking) {
+        rollbackEpisode(registry, episode);
+        saveRegistry(registryPath, registry);
+        return [
+            {
+                title: `DRAFT BLOCKED: assembled validation (ep${padded(episode)})`,
+                message: `Episode ${episode} drafted but cross-episode validation has blocking issues.`,
+                issues: summarizeIssues(validation.issues),
+                artifacts: [epMdPath(workspace, episode), epJsonPath(workspace, episode)],
+                next: [
+                    `Fix the issues above. If the issue is in episodes/meta.json (e.g. worldview placeholder), edit meta then re-run \`scriptctl episode draft ${episode} --resume\`.`,
+                    `If the issue is content in ep${padded(episode)}.md, edit it then re-run with --resume.`,
+                ],
+                episode,
+            },
+            EXIT_NEEDS_AGENT,
+        ];
+    }
+    // Step 4: auto-commit (absorbed from old `episode commit`). Single command does everything;
+    // no separate preview/commit dance — agent ran draft, it's locked in. The marker file
+    // is the single source of truth for "this episode is committed"; the registry just
+    // holds durable cross-episode facts.
+    writeText(epMarkerPath(workspace, episode), JSON.stringify({
+        episode,
+        title: episodeTitle,
+        committedAt: new Date().toISOString(),
+        scenes: fragment["scenes"]?.length ?? 0,
+    }, null, 2));
+    const softWarnings = [
+        ...softReports.map((r) => `soft collision on ${r.assetType} "${r.fragmentDeclaration.name}" vs ${r.registryEntry.id}`),
+        ...lint.major.map((s) => `[lint major] ${s}`),
+        ...lint.minor.map((s) => `[lint minor] ${s}`),
+        ...(validation.passed ? [] : validation.issues.filter((it) => it && it["severity"] !== "blocking" && it["severity"] !== "error").map((it) => `[validation] ${strOfIssue(it)}`)),
+    ];
+    return [
+        {
+            title: `DRAFT OK (ep${padded(episode)}${episodeTitle ? `: ${episodeTitle}` : ""})`,
+            message: `Episode ${episode} drafted, lint clean, validation clean, committed.`,
+            summary: [
+                `title:     ${episodeTitle}`,
+                `scenes:    ${fragment["scenes"]?.length ?? 0}`,
+                `actors+:   ${fragment["actors"]?.length ?? 0} new this episode`,
+                `lint:      0 critical${lint.major.length ? `, ${lint.major.length} major` : ""}${lint.minor.length ? `, ${lint.minor.length} minor` : ""}`,
+                `collision: 0 hard${softReports.length ? `, ${softReports.length} soft` : ""}`,
+                `validation: ${validation.passed ? "passed" : `${validation.issues.length} warning(s)`}`,
+            ].join("\n"),
+            artifacts: [epMdPath(workspace, episode), epJsonPath(workspace, episode), epMarkerPath(workspace, episode)],
+            warnings: softWarnings,
+            next: [
+                `Continue: \`scriptctl episode draft ${episode + 1}\``,
+                `Or publish all drafted: \`scriptctl episode publish [--dry-run]\``,
+            ],
+            episode,
+            promptPreviewChars: composedPrompt ? composedPrompt.length : undefined,
+        },
+        EXIT_OK,
+    ];
+}
+function strOfIssue(issue) {
+    return `${issue["code"] ?? "issue"}: ${issue["summary"] ?? issue["repair_hint"] ?? ""}`;
+}
+function lintEpisodeStub(fragment) {
+    // WS6 will replace this with the full lint_scriptize implementation. For now we
+    // do a minimal structural sanity check so the preview output is non-empty and the
+    // commit gate has *something* to enforce.
+    const critical = [];
+    const major = [];
+    const minor = [];
+    const scenes = fragment["scenes"] ?? [];
+    if (scenes.length === 0)
+        critical.push("no scenes parsed");
+    let dialogueLines = 0;
+    let actionLines = 0;
+    for (const scene of scenes) {
+        const actions = scene["actions"] ?? [];
+        for (const a of actions) {
+            const kind = String(a["type"] ?? "");
+            if (kind === "dialogue")
+                dialogueLines += 1;
+            else if (kind === "action")
+                actionLines += 1;
+            // perf hard rule: 单人单次对白 ≤ 40
+            if (kind === "dialogue") {
+                const content = String(a["content"] ?? "");
+                if (content.length > 40) {
+                    major.push(`dialogue exceeds 40 chars (${content.length}): "${content.slice(0, 30)}..."`);
+                }
+            }
+        }
+    }
+    if (dialogueLines + actionLines > 0) {
+        const ratio = dialogueLines / (dialogueLines + actionLines);
+        if (ratio > 0.8)
+            major.push(`dialogue/action ratio ${(ratio * 100).toFixed(0)}% > 80% (too talky)`);
+        if (ratio < 0.3)
+            major.push(`dialogue/action ratio ${(ratio * 100).toFixed(0)}% < 30% (too silent)`);
+    }
+    return { critical, major, minor };
+}
+// ---------------------------------------------------------------------------
+// `episode batch`
+// ---------------------------------------------------------------------------
+export async function commandEpisodeBatch(opts) {
+    const [start, end] = parseRange(opts.range);
+    // After the draft+preview+commit collapse, batch just loops draft. draft auto-commits
+    // on success and self-blocks on failure — no separate preview / commit calls needed.
+    const ok = [];
+    const blocked = [];
+    for (let n = start; n <= end; n++) {
+        const draftOpts = { ...opts, _args: [String(n)] };
+        try {
+            const [, code] = await commandEpisodeDraft(draftOpts);
+            if (code === EXIT_OK)
+                ok.push(n);
+            else
+                blocked.push(n);
+        }
+        catch {
+            blocked.push(n);
+        }
+    }
+    return [
+        {
+            title: `BATCH ${start}-${end} ${blocked.length ? "PARTIAL" : "OK"}`,
+            message: `${ok.length} episode(s) drafted+committed, ${blocked.length} blocked.`,
+            summary: [
+                `committed: [${ok.join(", ")}]`,
+                `blocked:   [${blocked.join(", ")}]`,
+            ].join("\n"),
+            next: blocked.length
+                ? blocked.map((n) => `Resolve ep${padded(n)} (see workspace/episodes/ep${padded(n)}.collision.json or ep${padded(n)}.lint.json).`)
+                : [`All drafted+committed. Publish: \`scriptctl episode publish [--dry-run]\``],
+        },
+        blocked.length === 0 ? EXIT_OK : EXIT_NEEDS_AGENT,
+    ];
+}
+// ---------------------------------------------------------------------------
+// `episode spec` — expose the SPEC constant used by the bundled Gemini prompt,
+// so agents writing spec md by hand (for `draft --from-md` / `--resume`) read
+// from the same single source of truth.
+// ---------------------------------------------------------------------------
+export function commandEpisodeSpec(opts) {
+    void opts;
+    return [
+        {
+            title: "EPISODE SPEC: scriptctl spec markdown grammar",
+            body: MARKDOWN_BATCH_PROMPT_SPEC,
+        },
+        EXIT_OK,
+    ];
+}
+// ---------------------------------------------------------------------------
+// `episode workspace`
+// ---------------------------------------------------------------------------
+// Reports the state of the `episode` (from-scratch) draft workspace only. This
+// is NOT a "how many episodes are in the final script" query — for that, see
+// `script inspect --target summary` / `--target episode`.
+export function commandEpisodeWorkspace(opts) {
+    const workspace = opts.workspace_path ?? "workspace";
+    const dir = episodeDir(workspace);
+    if (!fs.existsSync(dir)) {
+        return [
+            {
+                title: "EPISODE WORKSPACE (empty)",
+                message: "No episode-path drafts in this workspace. This only reflects the `episode` (from-scratch) draft area — it does not mean there is no final script.",
+                next: [
+                    "If you want to query an EXISTING final script (episode count, per-episode size, etc.), run: scriptctl script inspect --target summary",
+                    "If you want to start a from-scratch creative pipeline here, run: scriptctl episode draft 1",
+                ],
+            },
+            EXIT_OK,
+        ];
+    }
+    const entries = fs.readdirSync(dir);
+    const rows = [];
+    for (const name of entries) {
+        const m = /^ep(\d+)\.md$/.exec(name);
+        if (!m)
+            continue;
+        const n = parseInt(m[1], 10);
+        const committed = exists(epMarkerPath(workspace, n));
+        const lintExists = exists(epLintPath(workspace, n));
+        const collisionPath = epCollisionPath(workspace, n);
+        let collisions = null;
+        if (exists(collisionPath)) {
+            try {
+                const data = readJson(collisionPath);
+                collisions = Array.isArray(data.collisions) ? data.collisions.length : null;
+            }
+            catch {
+                collisions = null;
+            }
+        }
+        // After the draft+preview+commit collapse, an episode is either: drafted (md+json
+        // written), drafted-but-blocked (collision/lint issue remains), or committed (passed
+        // all gates and marker written).
+        let state;
+        if (committed)
+            state = "committed";
+        else if (collisions && collisions > 0)
+            state = "blocked-collision";
+        else if (lintExists)
+            state = "blocked-lint";
+        else
+            state = "drafted";
+        rows.push({ episode: n, state, collisions });
+    }
+    rows.sort((a, b) => a.episode - b.episode);
+    return [
+        {
+            title: "EPISODE WORKSPACE",
+            message: `${rows.length} episode-path draft(s) tracked.`,
+            summary: rows
+                .map((r) => `ep${padded(r.episode)}  ${r.state}${r.collisions ? `  (${r.collisions} collision report(s))` : ""}`)
+                .join("\n"),
+            result: rows.map((r) => `ep${padded(r.episode)}=${r.state}`),
+        },
+        EXIT_OK,
+    ];
+}
+function readScriptMeta(metaFile) {
+    if (!exists(metaFile)) {
+        throw new CliError("PUBLISH BLOCKED: meta.json missing", "Episode meta missing.", {
+            exitCode: EXIT_INPUT,
+            required: [metaFile],
+            received: ["no file at that path"],
+            nextSteps: [
+                `Run \`scriptctl episode init\` to scaffold a meta.json template, or hand-create ${metaFile} with at least {"title": "<剧本标题>", "worldview": "现代", "style": "<风格描述>"}.`,
+                `worldview must be one of the canonical values (see scriptctl docs); worldview_raw is optional free text.`,
+            ],
+        });
+    }
+    let meta;
+    try {
+        meta = readJson(metaFile);
+    }
+    catch (exc) {
+        throw new CliError("PUBLISH BLOCKED: meta.json invalid JSON", "Episode meta invalid.", {
+            exitCode: EXIT_INPUT,
+            required: ["valid JSON"],
+            received: [String(exc.message ?? exc)],
+            nextSteps: [`Verify ${metaFile} parses as JSON.`],
+        });
+    }
+    if (!meta.title || typeof meta.title !== "string") {
+        throw new CliError("PUBLISH BLOCKED: meta.json missing title", "Missing title.", {
+            exitCode: EXIT_INPUT,
+            required: ["meta.title (string)"],
+            received: [`title: ${JSON.stringify(meta.title)}`],
+            nextSteps: [`Add a non-empty "title" to ${metaFile}.`],
+        });
+    }
+    if (!meta.worldview || typeof meta.worldview !== "string") {
+        throw new CliError("PUBLISH BLOCKED: meta.json missing worldview", "Missing worldview.", {
+            exitCode: EXIT_INPUT,
+            required: ["meta.worldview (string)"],
+            received: [`worldview: ${JSON.stringify(meta.worldview)}`],
+            nextSteps: [`Add a "worldview" value to ${metaFile} (e.g. "现代", "古风架空").`],
+        });
+    }
+    return meta;
+}
+/**
+ * Collect committed episode slots (have `.done-<NN>` marker) under `episodes/`.
+ *
+ * Episodes whose draft is on disk but blocked (collision / lint / validation) get
+ * the ep<n>.json written, but no marker — those must NOT enter an assembled
+ * script. This function gates on marker presence so `merge` only ever sees
+ * episodes the agent has actually passed through draft's auto-commit step.
+ */
+function scanCommittedEpisodes(workspace, from, to) {
+    const dir = episodeDir(workspace);
+    if (!fs.existsSync(dir)) {
+        throw new CliError("MERGE BLOCKED: no drafted episodes", "No drafted episodes.", {
+            exitCode: EXIT_INPUT,
+            required: [dir],
+            received: ["directory does not exist"],
+            nextSteps: ["Run `scriptctl episode draft <n>` for at least one episode first."],
+        });
+    }
+    const allOnDisk = fs.readdirSync(dir)
+        .filter((name) => /^ep\d+\.json$/.test(name))
+        .map((name) => {
+        const m = /^ep(\d+)\.json$/.exec(name);
+        return { name, n: parseInt(m[1], 10) };
+    })
+        .sort((a, b) => a.n - b.n);
+    const slots = [];
+    const episodes = [];
+    const paths = [];
+    const skippedNoMarker = [];
+    for (const entry of allOnDisk) {
+        if (from !== undefined && entry.n < from)
+            continue;
+        if (to !== undefined && entry.n > to)
+            continue;
+        if (!exists(epMarkerPath(workspace, entry.n))) {
+            skippedNoMarker.push(entry.n);
+            continue;
+        }
+        const slotPath = path.join(dir, entry.name);
+        slots.push(readJson(slotPath));
+        episodes.push(entry.n);
+        paths.push({ episode: entry.n, path: slotPath });
+    }
+    if (slots.length === 0) {
+        const detail = skippedNoMarker.length > 0
+            ? `found ${allOnDisk.length} drafted slot(s) but none have a .done marker; blocked ep(s): [${skippedNoMarker.join(", ")}]`
+            : `found ${allOnDisk.length} drafted slot(s), filtered to 0 by range ${from ?? "-"}..${to ?? "-"}`;
+        throw new CliError("MERGE BLOCKED: no committed episodes in range", "No committed episodes.", {
+            exitCode: EXIT_INPUT,
+            required: ["at least one episode passed through draft auto-commit (.done-<NN> marker)"],
+            received: [detail],
+            nextSteps: skippedNoMarker.length > 0
+                ? [`Resolve the blocked episodes (see ep<n>.collision.json / ep<n>.lint.json), re-run draft, then merge.`]
+                : ["Widen --from / --to, or draft more episodes first."],
+        });
+    }
+    return { slots, episodes, paths };
+}
+/**
+ * Merge episode slots with meta + schema version. Single source of truth for
+ * "what gets validated / uploaded" — both runAssembledValidation (draft-time) and
+ * commandEpisodePublish call this, so their assembled shape stays in lock-step.
+ */
+function assembleScript(slots, meta) {
+    const assembled = mergeEpisodeResults(slots, meta.title);
+    assembled["worldview"] = meta.worldview;
+    assembled["worldview_raw"] = meta.worldview_raw ?? meta.worldview;
+    if (typeof meta.style === "string")
+        assembled["style"] = meta.style;
+    assembled["version"] = SCRIPT_SCHEMA_VERSION;
+    return assembled;
+}
+/**
+ * Assemble episodes 1..n (drafted) + this fragment + meta → run validateScript.
+ * Used at draft time so cross-episode issues surface immediately, not at publish.
+ * If meta.json is missing / has placeholders, returns blocking with clear next step.
+ */
+function runAssembledValidation(workspace, currentEpisode, currentFragment) {
+    const metaFile = metaPath(workspace);
+    let meta;
+    try {
+        meta = readScriptMeta(metaFile);
+    }
+    catch (exc) {
+        if (!(exc instanceof CliError))
+            throw exc;
+        return {
+            passed: false,
+            blocking: true,
+            issues: [
+                {
+                    code: "META_MISSING_OR_INVALID",
+                    severity: "blocking",
+                    summary: exc.message,
+                    repair_hint: exc.nextSteps.join(" ") || "Run `scriptctl episode init`, then fill episodes/meta.json before drafting.",
+                },
+            ],
+        };
+    }
+    // Gather all drafted episode JSONs (excluding current — current is in-memory)
+    const dir = episodeDir(workspace);
+    const slots = [];
+    if (fs.existsSync(dir)) {
+        for (const name of fs.readdirSync(dir)) {
+            const m = /^ep(\d+)\.json$/.exec(name);
+            if (!m)
+                continue;
+            const n = parseInt(m[1], 10);
+            if (n === currentEpisode)
+                continue;
+            slots.push(readJson(path.join(dir, name)));
+        }
+    }
+    slots.push(currentFragment);
+    slots.sort((a, b) => Number(a["episode"] ?? 0) - Number(b["episode"] ?? 0));
+    const assembled = assembleScript(slots, meta);
+    const validation = validateScript(workspace, null, { requireSource: false, scriptData: assembled });
+    const issues = validation["issues"] ?? [];
+    const blocking = Boolean(validation["has_blocking"]) ||
+        issues.some((it) => it && (it["severity"] === "blocking" || it["severity"] === "error"));
+    return { passed: Boolean(validation["passed"]) && !blocking, blocking, issues };
+}
+function parseRangeNumber(raw, label) {
+    if (raw === undefined)
+        return undefined;
+    const n = parseInt(raw, 10);
+    if (Number.isNaN(n)) {
+        throw new CliError(`USAGE ERROR: ${label} must be integer`, `Invalid ${label}.`, {
+            exitCode: EXIT_USAGE, required: ["integer"], received: [raw], nextSteps: [`e.g. ${label} 1`],
+        });
+    }
+    return n;
+}
+function shaOfScript(script) {
+    return sha256Text(JSON.stringify(sortDeep(script)));
+}
+function shaOfFile(p) {
+    return sha256Text(readText(p));
+}
+export async function commandEpisodeMerge(opts) {
+    const workspace = opts.workspace_path ?? "workspace";
+    const force = opts.force === true;
+    const resolvedMetaPath = opts.meta_path ?? metaPath(workspace);
+    const from = parseRangeNumber(opts.from, "--from");
+    const to = parseRangeNumber(opts.to, "--to");
+    // Local-only — no gateway env preflight. push handles that.
+    const meta = readScriptMeta(resolvedMetaPath);
+    const { slots, episodes, paths } = scanCommittedEpisodes(workspace, from, to);
+    const script = assembleScript(slots, meta);
+    // Fresh merge dir every run — prevents stale artifact / receipt from a previous run
+    // masquerading as current state. Same pattern publish used for its staging dir.
+    const dir = mergedDir(workspace);
+    fs.rmSync(dir, { recursive: true, force: true });
+    const writeMerged = () => {
+        fs.mkdirSync(dir, { recursive: true });
+        writeJson(mergedScriptPath(workspace), script);
+    };
+    // Defensive re-validation — draft already gated each episode through the same
+    // validateScript, so this should never fail in normal flow. It catches the case
+    // where an agent hand-edited ep<n>.json after auto-commit.
+    const validation = validateScript(workspace, null, { requireSource: false, scriptData: script });
+    const issues = validation["issues"] ?? [];
+    const blockingOrError = Boolean(validation["has_blocking"]) ||
+        issues.some((it) => it && (it["severity"] === "blocking" || it["severity"] === "error"));
+    if (!validation["passed"] && (!force || blockingOrError)) {
+        // Persist the assembled script so the agent has something to inspect, but do NOT
+        // write a receipt — push would otherwise see "ok" and ship a broken script.
+        writeMerged();
+        const title = force
+            ? "MERGE BLOCKED: Validation errors require repair"
+            : "MERGE BLOCKED: Validation needs agent repair";
+        return [
+            {
+                title,
+                message: "Assembled script failed schema validation; merge artifact saved but no receipt written (push will refuse).",
+                result: [
+                    `Assembled script saved to ${mergedScriptPath(workspace)} for inspection.`,
+                    `Episodes considered: [${episodes.join(", ")}]`,
+                ],
+                issues: summarizeIssues(issues),
+                artifacts: [mergedScriptPath(workspace)],
+                next: [
+                    "Inspect the issues above; re-draft offending episode(s) via `scriptctl episode draft <n> --regen`, or hand-edit the corresponding ep<n>.md and `--resume`, then re-run `scriptctl episode merge`.",
+                ],
+            },
+            EXIT_NEEDS_AGENT,
+        ];
+    }
+    // Passed → persist artifact + receipt. Hashes lock the assembled output to the
+    // exact set of input files; push will re-verify these before uploading.
+    writeMerged();
+    const receipt = {
+        mergedAt: new Date().toISOString(),
+        scriptSha256: shaOfScript(script),
+        metaPath: path.relative(workspace, resolvedMetaPath),
+        metaSha256: shaOfFile(resolvedMetaPath),
+        episodes: paths.map((p) => ({
+            episode: p.episode,
+            path: path.relative(workspace, p.path),
+            sha256: shaOfFile(p.path),
+        })),
+        validationPassed: Boolean(validation["passed"]),
+        validationWarnings: issues.length,
+    };
+    writeJson(mergeReceiptPath(workspace), receipt);
+    return [
+        {
+            title: `MERGE OK (${episodes.length} episode${episodes.length === 1 ? "" : "s"})`,
+            message: `Assembled + validated locally. Run \`scriptctl episode push\` to upload.`,
+            summary: [
+                `episodes:   [${episodes.join(", ")}]`,
+                `script:     ${mergedScriptPath(workspace)}`,
+                `receipt:    ${mergeReceiptPath(workspace)}`,
+                `script sha: ${receipt.scriptSha256.slice(0, 16)}...`,
+                validation["passed"] ? "validation: passed" : `validation: ${issues.length} non-blocking warning(s)`,
+            ].join("\n"),
+            artifacts: [mergedScriptPath(workspace), mergeReceiptPath(workspace)],
+            warnings: validation["passed"] ? [] : summarizeIssues(issues),
+            next: [
+                "Inspect the merged script; if good, upload with `scriptctl episode push`.",
+                "If you re-draft any episode after this point, re-run `scriptctl episode merge` — push refuses stale receipts.",
+            ],
+        },
+        EXIT_OK,
+    ];
+}
+export async function commandEpisodePush(opts) {
+    const workspace = opts.workspace_path ?? "workspace";
+    // Step 1: gateway env preflight — push is the only command that talks to gateway.
+    const env = checkGatewayEnv(opts.project_group_no);
+    if (!env.ready) {
+        return [
+            {
+                title: "PUSH BLOCKED: gateway env missing",
+                message: "Cannot upload without gateway credentials.",
+                summary: env.table,
+                result: env.missing.map((v) => `missing: ${v}`),
+                next: ["Set the missing env vars and re-run."],
+            },
+            EXIT_INPUT,
+        ];
+    }
+    // Step 2: merge artifact + receipt must exist (no implicit on-the-fly merge — push
+    // is purely a uploader, all assembly decisions live in `episode merge`).
+    const scriptFile = mergedScriptPath(workspace);
+    const receiptFile = mergeReceiptPath(workspace);
+    if (!exists(scriptFile) || !exists(receiptFile)) {
+        return [
+            {
+                title: "PUSH BLOCKED: merge artifact missing",
+                message: "Push requires a fresh `episode merge` artifact + receipt.",
+                result: [
+                    `expected: ${scriptFile} (${exists(scriptFile) ? "found" : "missing"})`,
+                    `expected: ${receiptFile} (${exists(receiptFile) ? "found" : "missing"})`,
+                ],
+                next: ["Run `scriptctl episode merge` first."],
+            },
+            EXIT_INPUT,
+        ];
+    }
+    let receipt;
+    try {
+        receipt = readJson(receiptFile);
+    }
+    catch (exc) {
+        return [
+            {
+                title: "PUSH BLOCKED: receipt invalid JSON",
+                message: "merge-receipt.json could not be parsed.",
+                result: [String(exc.message ?? exc)],
+                next: ["Run `scriptctl episode merge` to regenerate the receipt."],
+            },
+            EXIT_INPUT,
+        ];
+    }
+    // Step 3: triple hash check. Catches:
+    //   (a) agent edited .merged/script.json after merge
+    //   (b) agent edited meta.json after merge
+    //   (c) agent re-drafted some ep<n>.json after merge but didn't re-merge
+    // Any drift → refuse + ask user to re-merge.
+    const driftIssues = [];
+    const scriptOnDisk = readJson(scriptFile);
+    if (shaOfScript(scriptOnDisk) !== receipt.scriptSha256) {
+        driftIssues.push("merged/script.json hash mismatch (script was edited after merge)");
+    }
+    const resolvedMetaPath = path.join(workspace, receipt.metaPath);
+    if (!exists(resolvedMetaPath)) {
+        driftIssues.push(`meta file missing: ${receipt.metaPath}`);
+    }
+    else if (shaOfFile(resolvedMetaPath) !== receipt.metaSha256) {
+        driftIssues.push(`meta.json hash mismatch (${receipt.metaPath} changed after merge)`);
+    }
+    for (const epRec of receipt.episodes) {
+        const p = path.join(workspace, epRec.path);
+        if (!exists(p)) {
+            driftIssues.push(`ep${padded(epRec.episode)} file missing: ${epRec.path}`);
+            continue;
+        }
+        if (shaOfFile(p) !== epRec.sha256) {
+            driftIssues.push(`ep${padded(epRec.episode)} hash mismatch (${epRec.path} changed after merge)`);
+        }
+    }
+    if (driftIssues.length > 0) {
+        return [
+            {
+                title: "PUSH BLOCKED: merge receipt stale",
+                message: "One or more inputs changed after merge; push refuses to upload an inconsistent snapshot.",
+                result: driftIssues,
+                next: ["Run `scriptctl episode merge` to refresh the artifact + receipt, then re-run `episode push`."],
+            },
+            EXIT_NEEDS_AGENT,
+        ];
+    }
+    // Step 4: upload the assembled script that merge produced. requestId derives from
+    // the receipt hash so a re-pushed identical snapshot is idempotent on the gateway side.
+    const client = scriptOutputClient(opts);
+    const baseRevision = await currentRevisionOrZero(client);
+    const requestId = (opts.request_id ?? "").trim() || `scriptctl-episode-push:${receipt.scriptSha256}`;
+    let replaceRes;
+    try {
+        replaceRes = await client.replaceScript({
+            requestId,
+            baseRevision,
+            script: scriptOnDisk,
+            source: "ctl",
+        });
+    }
+    catch (exc) {
+        if (exc instanceof ScriptOutputApiError) {
+            throw apiErrorToCli("PUSH BLOCKED: gateway write failed", exc);
+        }
+        throw exc;
+    }
+    const revision = Number(replaceRes["revision"] ?? 0);
+    // Persist validation outcome on gateway side too (non-fatal — the local receipt
+    // is authoritative for what was validated locally).
+    try {
+        await client.saveValidationResult({
+            revision,
+            validationStatus: receipt.validationPassed ? "passed" : "warning",
+            validationSummary: { passed: receipt.validationPassed, warnings: receipt.validationWarnings },
+            issues: [],
+        });
+    }
+    catch {
+        /* non-fatal */
+    }
+    // Push receipt lives next to merge receipt — single dir is the whole upload story.
+    writeJson(pushReceiptPath(workspace), {
+        pushedAt: new Date().toISOString(),
+        episodes: receipt.episodes.map((e) => e.episode),
+        revision,
+        requestId,
+        scriptSha256: receipt.scriptSha256,
+        validationPassed: receipt.validationPassed,
+    });
+    const eps = receipt.episodes.map((e) => e.episode);
+    return [
+        {
+            title: `PUSH OK (${eps.length} episode${eps.length === 1 ? "" : "s"})`,
+            message: `Uploaded episodes [${eps.join(", ")}] to gateway, revision ${revision}.`,
+            summary: [
+                `episodes:   [${eps.join(", ")}]`,
+                `revision:   ${revision}`,
+                `request_id: ${requestId}`,
+                receipt.validationPassed ? "validation: passed" : `validation: ${receipt.validationWarnings} non-blocking issue(s)`,
+            ].join("\n"),
+            artifacts: [pushReceiptPath(workspace), mergedScriptPath(workspace)],
+            next: ["Inspect on gateway. To push a new snapshot: re-run `episode merge` (after any upstream edit), then `episode push`."],
+        },
+        EXIT_OK,
+    ];
+}
+// ---------------------------------------------------------------------------
+// `episode init`
+// ---------------------------------------------------------------------------
+const META_TEMPLATE = {
+    title: "TODO 请填写剧本标题",
+    worldview: "TODO 请填写世界观（现代 / 古代历史 / 古风架空 / 西幻架空 / 赛博朋克 / 星际时代 / 欧洲中世纪 / 上古时代 / 近代民国 之一）",
+    worldview_raw: "",
+    style: "TODO 请填写风格 / 题材标签（例：都市复仇 / 仙侠虐恋 / ...）",
+};
+export function commandEpisodeInit(opts) {
+    const workspace = opts.workspace_path ?? "workspace";
+    const force = opts.force === true;
+    const dir = episodeDir(workspace);
+    const metaFile = metaPath(workspace);
+    fs.mkdirSync(dir, { recursive: true });
+    const existed = exists(metaFile);
+    const overwrite = existed && force;
+    if (!existed || overwrite) {
+        writeJson(metaFile, META_TEMPLATE);
+    }
+    // Gateway env preflight — informational at init time (init is fully local; we don't
+    // block on missing env vars because the agent may not need them until publish day).
+    const env = checkGatewayEnv();
+    const gatewayLines = env.ready
+        ? ["", "Gateway readiness:", env.table, "  → ready for `episode publish` whenever you are."]
+        : [
+            "",
+            "Gateway readiness:",
+            env.table,
+            "  ⚠ Set the missing vars before `episode publish` (init doesn't need them).",
+        ];
+    const next = [];
+    if (existed && !force) {
+        next.push(`${metaFile} already exists and was not modified. Pass --force to overwrite with template.`);
+    }
+    else if (overwrite) {
+        next.push(`1. Re-fill title / worldview / style in ${metaFile} (just overwritten with TODO placeholders).`);
+    }
+    else {
+        next.push(`1. Fill in title / worldview / style in ${metaFile}.`);
+    }
+    next.push(`2. Prepare per-episode outlines at ${dir}/ep<NN>.outline.md (first line must be \`# 第 N 集：副标题\`).`);
+    next.push(`3. Run \`scriptctl episode draft 1\` (default provider: gemini; output auto-committed when validation passes).`);
+    next.push(`4. When all drafted: \`scriptctl episode publish [--dry-run]\``);
+    const titleSuffix = existed && !force
+        ? "INIT SKIPPED: meta.json already exists"
+        : existed
+            ? "INIT OK: meta.json overwritten with template"
+            : "INIT OK: episode workspace ready";
+    return [
+        {
+            title: titleSuffix,
+            message: `${dir}/ and ${metaFile} are ready.${env.ready ? " Gateway env present." : " Gateway env partial (see summary)."}`,
+            summary: gatewayLines.join("\n").trim(),
+            artifacts: [metaFile],
+            next,
+        },
+        EXIT_OK,
+    ];
+}
+//# sourceMappingURL=episode.js.map