@lingjingai/scriptctl 0.10.3 → 0.11.0

package/dist/usecases/script.js

@@ -1,10 +1,13 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
-import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, directDir, exists, readJson, readText, sha256Text, writeJson, } from "../common.js";
+import { randomUUID } from "node:crypto";
+import { CliError, EXIT_INPUT, EXIT_NEEDS_AGENT, EXIT_OK, EXIT_RUNTIME, EXIT_USAGE, directDir, exists, readJson, readText, scriptJsonPath, sha256Text, writeJson, } from "../common.js";
 import { applyPatchOperations, collectAssetRefs, collectStateRefs, parseAnyAddress, parseStateTarget, validateScript, PATCH_OP_SCHEMA, } from "../domain/script-core.js";
 import { RemoteScriptOutputStore } from "../infra/script-output-api.js";
 import { LocalScriptOutputStore } from "../infra/local-script-output-store.js";
 import { ScriptOutputApiError, resolveOutputMode, } from "../infra/script-output-store.js";
-import { readRunState, summarizeIssues, updateRunState, } from "./direct.js";
+import { markMetadataConfidenceReviewed, readRunState, reviewBlockers, summarizeIssues, updateRunState, markPatched, } from "./direct.js";
 function strOf(v) {
     if (v === null || v === undefined)
         return "";
@@ -62,12 +65,14 @@ function episodeCharCounts(scenes) {
 export class ScriptEditSession {
     workspace;
     script;
+    scriptPath;
     client;
     projectGroupNo;
     revision;
     constructor(opts) {
         this.workspace = opts.workspace;
         this.script = opts.script;
+        this.scriptPath = opts.scriptPath ?? null;
         this.client = opts.client ?? null;
         this.projectGroupNo = opts.projectGroupNo ?? null;
         this.revision = opts.revision ?? null;
@@ -76,10 +81,16 @@ export class ScriptEditSession {
         return this.client !== null;
     }
     get artifactLabel() {
-        // Public label — keeps the project id + revision (not secret; the user
-        // supplies the project id via --project-group-no/env) so two project groups
-        // at the same revision stay distinguishable in report.artifacts.
-        return `script-output/${this.projectGroupNo}@revision/${this.revision ?? 0}`;
+        if (this.remote) {
+            // Public label — strips the internal `db:/script-output/project-groups/`
+            // storage prefix (which leaks implementation), but keeps the project id
+            // and revision so two different project groups at the same revision stay
+            // distinguishable in user-visible report.artifacts entries. The project
+            // id is not a secret: the user supplies it themselves via
+            // `--project-group-no` or env config.
+            return `script-output/${this.projectGroupNo}@revision/${this.revision ?? 0}`;
+        }
+        return this.scriptPath ?? "";
     }
 }
 export function scriptOutputClient(opts) {
@@ -201,7 +212,7 @@ export function apiErrorToCli(title, exc) {
             isConflict
                 ? "Reload the latest script revision and retry."
                 : isMissing
-                    ? "Run `scriptctl import push` to publish a script first."
+                    ? "Run `scriptctl direct export` to publish a script first."
                     : "Run `scriptctl doctor` to verify gateway configuration; retry if it was transient.",
         ],
         errorCode: isConflict
@@ -220,28 +231,12 @@ export async function currentRevisionOrZero(client) {
     }
     catch (exc) {
         if (exc instanceof ScriptOutputApiError) {
-            // WORKAROUND (see TODO.md "getRevision not-found signal"): the script-output
-            // backend returns a generic error (UNKNOWN_EXCEPTION, not a recognizable
-            // "no script yet" signal) when a project group has no published script, so
-            // a first publish can't tell first-publish from a real failure here.
-            // getRevision is only an optimistic-lock hint, not a correctness gate, so
-            // fall back to baseRevision 0 and let replaceScript decide. This is SAFE:
-            // replaceScript enforces the baseRevision lock server-side — it CREATES only
-            // when no script exists and REJECTS with a revision conflict if one already
-            // does — so base 0 never overwrites an existing script. A genuine
-            // gateway/auth failure still surfaces on the subsequent replaceScript call.
-            // Note: once a script exists, getRevision returns cleanly, so this fallback
-            // only ever engages on the no-script (first-publish) path.
-            return 0;
+            throw apiErrorToCli("SCRIPT API BLOCKED: Revision query failed", exc);
         }
         throw exc;
     }
 }
-// All reads/edits operate on the DB-backed final script. The intermediate
-// script.initial.json is a private artifact between `import init` and
-// `import push`; it is not an editable surface.
-async function loadScript(opts) {
-    const workspace = strOf(opts["workspace_path"] || "workspace");
+async function loadRemoteScript(opts, workspace) {
     const client = scriptOutputClient(opts);
     let script;
     let revision;
@@ -260,7 +255,7 @@ async function loadScript(opts) {
             exitCode: EXIT_INPUT,
             required: ["existing script-output project document"],
             received: [`projectGroupNo=${client.projectGroupNo}`],
-            nextSteps: ["Run `scriptctl import push` to publish a script first."],
+            nextSteps: ["Run `scriptctl direct export` first, or pass `--script-path` to edit a local intermediate script JSON."],
             errorCode: "SCRIPT_NOT_FOUND",
         });
     }
@@ -281,22 +276,66 @@ async function loadScript(opts) {
         revision: Number((revision ?? {})["revision"] ?? 0),
     });
 }
+async function loadScriptForEdit(opts) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    if (!opts["script_path"]) {
+        return loadRemoteScript(opts, workspace);
+    }
+    const p = scriptJsonPath(opts);
+    if (!exists(p)) {
+        throw new CliError("SCRIPT BLOCKED: Local script file not found", "Local script file not found.", {
+            exitCode: EXIT_INPUT,
+            required: ["--script-path existing local script JSON"],
+            received: [p],
+            nextSteps: ["Pass --script-path to an existing local intermediate script JSON, or omit --script-path to use DB-backed script-output."],
+            errorCode: "SCRIPT_NOT_FOUND",
+        });
+    }
+    let data;
+    try {
+        data = readJson(p);
+    }
+    catch (exc) {
+        throw new CliError("SCRIPT BLOCKED: script JSON invalid", "script JSON invalid.", {
+            exitCode: EXIT_INPUT,
+            required: ["valid JSON"],
+            received: [`${p}: ${exc.message}`],
+            nextSteps: ["Fix the local script JSON syntax before editing."],
+            errorCode: "SCRIPT_JSON_INVALID",
+        });
+    }
+    if (!isDict(data)) {
+        throw new CliError("SCRIPT BLOCKED: script root invalid", "script root invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["script root object"],
+            received: [Array.isArray(data) ? "array" : typeof data],
+            nextSteps: ["Use a valid script document object."],
+            errorCode: "SCRIPT_ROOT_INVALID",
+        });
+    }
+    return new ScriptEditSession({ workspace, scriptPath: p, script: data });
+}
 function validateSession(session, opts = {}) {
-    const persist = opts.persist ?? true;
-    // Validate the in-memory DB script directly (no tmp file). scriptData also
-    // tells validateScript not to read the local asset_metadata.json/episode_plan.json
-    // parse artifacts — those describe the local initial.json, not the DB script.
-    // requireSource:false (DB validation never needs source.txt). persist:false so
-    // validateScript doesn't write; we own the write below to set the nicer label.
-    const validation = validateScript(session.workspace, null, {
-        requireSource: false,
-        scriptData: session.script,
-        persist: false,
-    });
-    validation["script_path"] = session.artifactLabel;
-    if (persist)
+    const requireSource = opts.requireSource ?? false;
+    if (!session.remote) {
+        return validateScript(session.workspace, session.scriptPath, { requireSource });
+    }
+    const tmpPath = path.join(os.tmpdir(), `scriptctl-db-script-${randomUUID()}.json`);
+    try {
+        fs.writeFileSync(tmpPath, JSON.stringify(session.script, null, 2) + "\n", "utf-8");
+        const validation = validateScript(session.workspace, tmpPath, { requireSource });
+        validation["script_path"] = session.artifactLabel;
         writeJson(path.join(directDir(session.workspace), "validation.json"), validation);
-    return validation;
+        return validation;
+    }
+    finally {
+        try {
+            fs.unlinkSync(tmpPath);
+        }
+        catch {
+            // ignore
+        }
+    }
 }
 function validationIssuePath(issue) {
     if (issue["path"])
@@ -386,8 +425,12 @@ function requestIdForScriptWrite(opts, op, payload) {
     return `scriptctl:${op}:${sha256Text(canonical)}`;
 }
 async function saveScriptSession(session, opts, op) {
+    if (!session.remote) {
+        writeJson(session.scriptPath, session.script);
+        return [null, false];
+    }
     if (session.client === null)
-        throw new Error("script session missing client");
+        throw new Error("remote script session missing client");
     const baseRevision = Number(session.revision ?? 0);
     const requestId = requestIdForScriptWrite(opts, op, { script: session.script });
     let res;
@@ -445,11 +488,67 @@ function patchOperationsFromPayload(payload) {
     return operations;
 }
 // ---------------------------------------------------------------------------
+// command_patch (legacy: applies to script.initial.json directly with source)
+// ---------------------------------------------------------------------------
+export function commandPatch(opts) {
+    const workspace = strOf(opts["workspace_path"] || "workspace");
+    const patchPath = strOf(opts["patch"]);
+    const scriptPath = path.join(directDir(workspace), "script.initial.json");
+    const sourcePath = path.join(workspace, "source.txt");
+    if (!exists(patchPath)) {
+        throw new CliError("PATCH BLOCKED: Patch file not found", "Patch file not found.", {
+            exitCode: EXIT_INPUT,
+            required: ["--patch: existing JSON file"],
+            received: [patchPath],
+            nextSteps: ["Write a patch JSON file and rerun patch."],
+        });
+    }
+    if (!exists(scriptPath) || !exists(sourcePath)) {
+        throw new CliError("PATCH BLOCKED: Required artifact missing", "Required artifact missing.", {
+            exitCode: EXIT_INPUT,
+            required: ["source.txt and script.initial.json"],
+            received: [scriptPath, sourcePath],
+            nextSteps: ["Run scriptctl direct init first."],
+        });
+    }
+    let payload;
+    try {
+        payload = readJson(patchPath);
+    }
+    catch (exc) {
+        throw new CliError("PATCH BLOCKED: Patch JSON invalid", "Patch JSON invalid.", {
+            exitCode: EXIT_USAGE,
+            required: ["valid JSON patch file"],
+            received: [`${patchPath}: ${exc.message}`],
+            nextSteps: ["Fix patch JSON and rerun patch."],
+        });
+    }
+    const operations = patchOperationsFromPayload(payload);
+    const script = readJson(scriptPath);
+    const applied = applyPatchOperations(script, readText(sourcePath), operations);
+    writeJson(scriptPath, script);
+    markMetadataConfidenceReviewed(workspace, operations);
+    const validation = validateScript(workspace, scriptPath);
+    markPatched(workspace, applied.length);
+    const passed = Boolean(validation["passed"]);
+    const report = {
+        title: passed ? "PATCH APPLIED: Validation passed" : "PATCH APPLIED: Repair issues remain",
+        result: [
+            `operations: ${applied.length}`,
+            `validation: ${passed ? "passed" : "needs repair"}`,
+        ],
+        artifacts: [scriptPath, path.join(directDir(workspace), "validation.json")],
+        issues: summarizeIssues(asList(validation["issues"])),
+        next: [passed ? "Export the final script." : "Inspect remaining issues and apply another patch."],
+    };
+    return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
+}
+// ---------------------------------------------------------------------------
 // commandScriptValidate / commandScriptInspect
 // ---------------------------------------------------------------------------
 export async function commandScriptValidate(opts) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const validation = validateSession(session);
     await syncValidationResult(session, validation);
     const stats = validation["stats"] ?? {};
@@ -579,13 +678,13 @@ export async function commandScriptPatch(opts) {
     }
     const operations = patchOperationsFromPayload(payload);
     const dryRun = Boolean(opts["dry_run"]);
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const applied = applyPatchOperations(script, scriptSourceText(workspace), operations);
     if (dryRun) {
         // Validate the in-memory mutated script WITHOUT calling saveScriptSession.
         // Run validate but skip syncValidationResult (which writes to remote) too.
-        const validation = validateSession(session, { persist: false });
+        const validation = validateSession(session);
         const passed = Boolean(validation["passed"]);
         const report = {
             title: passed ? "SCRIPT PATCH DRY-RUN PASSED" : "SCRIPT PATCH DRY-RUN: Validation needs repair",
@@ -607,6 +706,12 @@ export async function commandScriptPatch(opts) {
     const [newRevision, idempotent] = await saveScriptSession(session, opts, applied.length === 1 ? applied[0] : "script.patch");
     const validation = validateSession(session);
     await syncValidationResult(session, validation, newRevision);
+    // Direct-stage local patches: keep run_state in sync so reviewBlockers can
+    // unblock direct export. Detect via script path under directDir.
+    if (!session.remote && session.scriptPath && session.scriptPath.startsWith(directDir(workspace))) {
+        markMetadataConfidenceReviewed(workspace, operations);
+        markPatched(workspace, applied.length);
+    }
     const passed = Boolean(validation["passed"]);
     const resultLines = [
         `operations: ${applied.length}`,
@@ -634,7 +739,7 @@ export async function commandScriptPatch(opts) {
 // ---------------------------------------------------------------------------
 async function applySingleScriptOp(opts, op) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const applied = applyPatchOperations(script, scriptSourceText(workspace), [op]);
     const opName = applied[0] ?? strOf(op["op"]);
@@ -676,7 +781,7 @@ function summarizeScriptOp(_script, op) {
     return `已执行 ${kind}`;
 }
 async function commandStateRefs(opts, plan = false) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const args = asList(opts["_args"]);
     const [targetKind, targetId, stateId] = parseStateTarget(args[0] ?? "");
@@ -715,48 +820,72 @@ async function commandStateRefs(opts, plan = false) {
     return [report, EXIT_OK];
 }
 // ---------------------------------------------------------------------------
-// command_push (import push)
+// command_export (direct export)
 // ---------------------------------------------------------------------------
-export async function commandPush(opts) {
+export async function commandExport(opts) {
     const workspace = strOf(opts["workspace_path"] || "workspace");
+    const force = Boolean(opts["force"]);
     const scriptPath = path.join(directDir(workspace), "script.initial.json");
     if (!exists(scriptPath)) {
-        throw new CliError("PUSH BLOCKED: script.initial.json not found", "script.initial.json not found.", {
+        throw new CliError("EXPORT BLOCKED: script.initial.json not found", "script.initial.json not found.", {
             exitCode: EXIT_INPUT,
             required: ["workspace/draft/scriptctl/direct/script.initial.json"],
             received: [scriptPath],
-            nextSteps: ["Run scriptctl import init first."],
+            nextSteps: ["Run scriptctl direct init first."],
         });
     }
     const state = readRunState(workspace);
     const provider = strOf(state["provider"]);
-    // SCRIPTCTL_ALLOW_MOCK_PUSH is the current name; SCRIPTCTL_ALLOW_MOCK_EXPORT is
-    // still honored for back-compat with environments configured before the rename.
-    const allowMock = process.env.SCRIPTCTL_ALLOW_MOCK_PUSH === "1" || process.env.SCRIPTCTL_ALLOW_MOCK_EXPORT === "1";
-    if (provider === "mock" && !allowMock) {
+    if (provider === "mock" && process.env.SCRIPTCTL_ALLOW_MOCK_EXPORT !== "1") {
         const report = {
-            title: "PUSH BLOCKED: Mock provider result",
-            result: ["script.initial.json was produced by --provider mock and was not pushed."],
+            title: "EXPORT BLOCKED: Mock provider result",
+            result: ["script.initial.json was produced by --provider mock and was not exported."],
             artifacts: [path.join(directDir(workspace), "run_state.json")],
             next: ["Rerun init with --provider anthropic for deliverable conversion."],
         };
         return [report, EXIT_NEEDS_AGENT];
     }
+    const missingReview = reviewBlockers(state);
+    if (missingReview.length > 0) {
+        const report = {
+            title: "EXPORT BLOCKED: Agent review incomplete",
+            result: ["script.initial.json was not exported.", `missing review: ${missingReview.join(", ")}`],
+            artifacts: [path.join(directDir(workspace), "run_state.json")],
+            next: ["Run inspect for each missing target, or apply a structured patch, then validate/export."],
+        };
+        return [report, EXIT_NEEDS_AGENT];
+    }
+    const validation = validateScript(workspace, scriptPath);
+    const blockingOrError = Boolean(validation["has_blocking"]) ||
+        asList(validation["issues"]).some((it) => isDict(it) && (it["severity"] === "blocking" || it["severity"] === "error"));
+    if (!validation["passed"] && (!force || blockingOrError)) {
+        const title = force
+            ? "EXPORT BLOCKED: Validation errors require repair"
+            : "EXPORT BLOCKED: Validation needs agent repair";
+        const report = {
+            title,
+            result: ["script.initial.json was not exported."],
+            artifacts: [path.join(directDir(workspace), "validation.json")],
+            issues: summarizeIssues(asList(validation["issues"])),
+            next: ["Inspect issues and apply structured patches, then validate/export."],
+        };
+        return [report, EXIT_NEEDS_AGENT];
+    }
     let script;
     try {
         script = readJson(scriptPath);
     }
     catch (exc) {
-        throw new CliError("PUSH BLOCKED: script.initial.json invalid", "script.initial.json invalid.", {
+        throw new CliError("EXPORT BLOCKED: script.initial.json invalid", "script.initial.json invalid.", {
             exitCode: EXIT_INPUT,
             required: ["valid script.initial.json"],
             received: [`${scriptPath}: ${exc.message}`],
-            nextSteps: ["Fix script.initial.json or rerun import init."],
+            nextSteps: ["Fix script.initial.json or rerun direct init."],
             errorCode: "SCRIPT_JSON_INVALID",
         });
     }
     if (!isDict(script)) {
-        throw new CliError("PUSH BLOCKED: script root invalid", "script root invalid.", {
+        throw new CliError("EXPORT BLOCKED: script root invalid", "script root invalid.", {
             exitCode: EXIT_USAGE,
             required: ["script root object"],
             received: [Array.isArray(script) ? "array" : typeof script],
@@ -764,14 +893,12 @@ export async function commandPush(opts) {
             errorCode: "SCRIPT_ROOT_INVALID",
         });
     }
-    // Validation is advisory, not a gate: push always publishes so the agent can
-    // self-review and repair on the DB script afterwards. requireSource:false so a
-    // missing source.txt never aborts the publish. Results are still computed and
-    // synced so the review subagent has the issue list to act on.
-    const validation = validateScript(workspace, scriptPath, { requireSource: false });
     const client = scriptOutputClient(opts);
     const baseRevision = await currentRevisionOrZero(client);
-    const requestId = requestIdForScriptWrite(opts, "import.push", { script });
+    // Sorted-keys serialization mirrors Python json.dumps(sort_keys=True, separators=(",",":"))
+    const sortedScript = sortDeep(script);
+    const scriptHash = sha256Text(JSON.stringify(sortedScript));
+    const requestId = strOf(opts["request_id"]).trim() || `scriptctl-direct-export:${scriptHash}`;
     let replaceRes;
     try {
         replaceRes = await client.replaceScript({
@@ -783,7 +910,7 @@ export async function commandPush(opts) {
     }
     catch (exc) {
         if (exc instanceof ScriptOutputApiError) {
-            throw apiErrorToCli("SCRIPT API BLOCKED: Push write failed", exc);
+            throw apiErrorToCli("SCRIPT API BLOCKED: Export write failed", exc);
         }
         throw exc;
     }
@@ -797,21 +924,17 @@ export async function commandPush(opts) {
     });
     await syncValidationResult(remoteSession, validation, revision);
     const outputLabel = remoteSession.artifactLabel;
-    updateRunState(workspace, { status: "pushed", output_path: outputLabel });
-    const passed = Boolean(validation["passed"]);
+    updateRunState(workspace, { status: "exported", output_path: outputLabel });
     const report = {
-        title: "PUSH COMPLETE: Final script stored in DB",
+        title: "EXPORT COMPLETE: Final script stored in DB",
         result: [
-            `validation: ${passed ? "passed" : "advisory (review on DB)"}`,
+            `validation: ${validation["passed"] ? "passed" : "forced"}`,
             `base_revision: ${baseRevision}`,
             `revision: ${revision}`,
             `idempotent: ${String(Boolean(replaceRes["idempotent"])).toLowerCase()}`,
         ],
-        issues: passed ? [] : summarizeIssues(asList(validation["issues"])),
         artifacts: [outputLabel, path.join(directDir(workspace), "validation.json")],
-        next: passed
-            ? ["Self-review the DB script, then proceed to downstream asset or footage stages."]
-            : ["Self-review and repair the DB script (validate / issues --severity error), then proceed downstream."],
+        next: ["Proceed to downstream asset or footage stages."],
     };
     return [report, EXIT_OK];
 }
@@ -957,8 +1080,12 @@ function buildReport(op, title, lines, artifactLabel, next) {
     };
 }
 // ----- summary --------------------------------------------------------------
+function synopsisPreview(text, limit) {
+    const oneLine = text.replace(/\s+/g, " ").trim();
+    return oneLine.length > limit ? `${oneLine.slice(0, limit)}…` : oneLine;
+}
 export async function commandSummary(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const episodes = asList(script["episodes"]);
     const scenes = [];
@@ -977,11 +1104,14 @@ export async function commandSummary(opts) {
         `props: ${asList(script["props"]).length}`,
         `speakers: ${asList(script["speakers"]).length}`,
     ];
+    const synopsis = strOf(script["synopsis"]).trim();
+    if (synopsis)
+        lines.push(`synopsis: ${synopsisPreview(synopsis, 120)}`);
     return [buildReport("query.summary", "SCRIPT SUMMARY", lines, session.artifactLabel, ["Use plural-noun queries (episodes / scenes / actions / actors / ...) or edit verbs to act on the script."]), EXIT_OK];
 }
 // ----- episodes -------------------------------------------------------------
 export async function commandEpisodes(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const itemId = strOf(opts["id"]).trim();
     const minChars = parseBound(opts["min_chars"]);
@@ -999,7 +1129,9 @@ export async function commandEpisodes(opts) {
             continue;
         if (maxChars !== null && chars.total > maxChars)
             continue;
-        lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}`);
+        const epSynopsis = strOf(ep["synopsis"]).trim();
+        const synopsisField = epSynopsis ? `, synopsis=${synopsisPreview(epSynopsis, 60)}` : "";
+        lines.push(`${ep["episode_id"]}: scenes=${scenes.length}, actions=${actionCount}, chars=${chars.total} (dialogue=${chars.dialogue}, action=${chars.action}), title=${ep["title"] || "-"}${synopsisField}`);
     }
     return [buildReport("query.episodes", "EPISODES", lines, session.artifactLabel, ["Use `scriptctl scenes --in <ep>` to drill in, or edit verbs to mutate."]), EXIT_OK];
 }
@@ -1035,7 +1167,7 @@ function formatScene(epId, scene, names) {
     return `${epId}/${scene["scene_id"]} [${space} ${time}] location=${locations.join(",") || "-"} actors=${actors.join(",") || "-"} props=${props.join(",") || "-"} actions=${actionCount}`;
 }
 export async function commandScenes(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const inFilter = parseInFilter(strOf(opts["in"]));
     const hasActor = strOf(opts["has_actor"]).trim();
@@ -1073,7 +1205,7 @@ export async function commandScenes(opts) {
 }
 // ----- actions --------------------------------------------------------------
 export async function commandActions(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const inFilter = parseInFilter(strOf(opts["in"]));
     const grep = strOf(opts["grep"]);
@@ -1258,7 +1390,7 @@ function listAssetsByKind(script, kind, opts) {
     return lines;
 }
 export async function commandActors(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const lines = listAssetsByKind(session.script, "actor", {
         id: strOf(opts["id"]).trim(),
         name: strOf(opts["name"]).trim(),
@@ -1267,7 +1399,7 @@ export async function commandActors(opts) {
     return [buildReport("query.actors", "ACTORS", lines, session.artifactLabel, ["Use `scriptctl rename actor:<id>` / `describe` / `merge` to edit."]), EXIT_OK];
 }
 export async function commandLocations(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const lines = listAssetsByKind(session.script, "location", {
         id: strOf(opts["id"]).trim(),
         name: strOf(opts["name"]).trim(),
@@ -1276,7 +1408,7 @@ export async function commandLocations(opts) {
     return [buildReport("query.locations", "LOCATIONS", lines, session.artifactLabel, ["Use `scriptctl rename location:<id>` etc. to edit."]), EXIT_OK];
 }
 export async function commandProps(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const lines = listAssetsByKind(session.script, "prop", {
         id: strOf(opts["id"]).trim(),
         name: strOf(opts["name"]).trim(),
@@ -1285,7 +1417,7 @@ export async function commandProps(opts) {
     return [buildReport("query.props", "PROPS", lines, session.artifactLabel, ["Use `scriptctl rename prop:<id>` etc. to edit."]), EXIT_OK];
 }
 export async function commandAssets(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const kindFilter = strOf(opts["kind"]).trim();
     const nameOpt = strOf(opts["name"]).trim();
     const idOpt = strOf(opts["id"]).trim();
@@ -1300,7 +1432,7 @@ export async function commandAssets(opts) {
 }
 // ----- speakers -------------------------------------------------------------
 export async function commandSpeakers(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const idOpt = strOf(opts["id"]).trim();
     const nameOpt = strOf(opts["name"]).trim();
@@ -1323,7 +1455,7 @@ export async function commandSpeakers(opts) {
 }
 // ----- issues ---------------------------------------------------------------
 export async function commandIssues(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const severityFilter = strOf(opts["severity"]).trim();
     const codeFilter = strOf(opts["code"]).trim();
     const validation = validateSession(session);
@@ -1345,7 +1477,7 @@ export async function commandIssues(opts) {
 }
 // ----- refs (unified reverse lookup) ----------------------------------------
 export async function commandRefs(opts) {
-    const session = await loadScript(opts);
+    const session = await loadScriptForEdit(opts);
     const script = session.script;
     const args = asList(opts["_args"]);
     const target = strOf(args[0]).trim();