@lingjingai/scriptctl 0.50.0 → 0.51.0

package/dist/usecases/script/lib.js

@@ -155,12 +155,11 @@ export function parseDoLine(tokens) {
     return { verb, args, flags };
 }
 export function doErr(detail) {
-    return new CliError("DO BLOCKED: line invalid", detail, {
+    return new CliError(detail, {
         exitCode: EXIT_USAGE,
-        required: ["a valid <verb> ...args... line"],
-        received: [detail],
-        nextSteps: ["Each line is a scriptctl verb minus the leading `scriptctl`; see `scriptctl do --help`."],
         errorCode: "DO_LINE_INVALID",
+        hint: "Each line is a scriptctl verb minus the leading `scriptctl`; see `scriptctl do --help`.",
+        data: { expected: ["a valid <verb> ...args... line"], actual: [detail] },
     });
 }
 // ---- shared op-template builders ------------------------------------------
@@ -172,36 +171,46 @@ export function stateChangeTemplate(target, f) {
     const toSet = f.to !== undefined;
     const clearSet = Boolean(f.clear);
     if (toSet && clearSet) {
-        throw new CliError("VERB BLOCKED: state-change flags mutually exclusive", "state-change: --to and --clear are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["exactly one of --to <state> / --clear"], received: ["--to", "--clear"],
-            nextSteps: ["Pick one and retry."], errorCode: "STATE_CHANGE_FLAG_CONFLICT",
+        throw new CliError("state-change: --to and --clear are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "STATE_CHANGE_FLAG_CONFLICT",
+            hint: "Pick one and retry.",
+            data: { expected: ["exactly one of --to <state> / --clear"], actual: ["--to", "--clear"] },
         });
     }
     if (!toSet && !clearSet) {
-        throw new CliError("VERB BLOCKED: state-change flag missing", "state-change: must specify --to <state> or --clear.", {
-            exitCode: EXIT_USAGE, required: ["one of --to <state> / --clear"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one flag."], errorCode: "STATE_CHANGE_FLAG_MISSING",
+        throw new CliError("state-change: must specify --to <state> or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "STATE_CHANGE_FLAG_MISSING",
+            hint: "Pick exactly one flag.",
+            data: { expected: ["one of --to <state> / --clear"], actual: ["<missing>"] },
         });
     }
     // v3 has no per-action state_changes; state lives on scene.ref.* only.
-    throw new CliError("VERB BLOCKED: state-change removed", "state-change was removed in v3; set a scene ref's state instead.", {
-        exitCode: EXIT_USAGE, required: ["scene-ref state edit"], received: ["state-change"],
-        nextSteps: ["Use `scene-ref <ep/scn> <kind:id> --state <state_id>` (op scene.ref.set)."], errorCode: "STATE_CHANGE_REMOVED",
+    throw new CliError("state-change was removed in v3; set a scene ref's state instead.", {
+        exitCode: EXIT_USAGE,
+        errorCode: "STATE_CHANGE_REMOVED",
+        hint: "Use `scene-ref <ep/scn> <kind:id> --state <state_id>` (op scene.ref.set).",
+        data: { expected: ["scene-ref state edit"], actual: ["state-change"] },
     });
 }
 export function transitionTemplate(target, f) {
     const setBoth = f.process !== undefined || f.contrast !== undefined;
     const clearSet = Boolean(f.clear);
     if (setBoth && clearSet) {
-        throw new CliError("VERB BLOCKED: transition flags mutually exclusive", "transition: --clear is mutually exclusive with --process/--contrast.", {
-            exitCode: EXIT_USAGE, required: ["either --clear, or --process + --contrast"], received: ["--clear", "--process/--contrast"],
-            nextSteps: ["Pick one mode and retry."], errorCode: "TRANSITION_FLAG_CONFLICT",
+        throw new CliError("transition: --clear is mutually exclusive with --process/--contrast.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "TRANSITION_FLAG_CONFLICT",
+            hint: "Pick one mode and retry.",
+            data: { expected: ["either --clear, or --process + --contrast"], actual: ["--clear", "--process/--contrast"] },
         });
     }
     if (!setBoth && !clearSet) {
-        throw new CliError("VERB BLOCKED: transition flag missing", "transition: must specify --process/--contrast or --clear.", {
-            exitCode: EXIT_USAGE, required: ["--process + --contrast, or --clear"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one mode."], errorCode: "TRANSITION_FLAG_MISSING",
+        throw new CliError("transition: must specify --process/--contrast or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "TRANSITION_FLAG_MISSING",
+            hint: "Pick exactly one mode.",
+            data: { expected: ["--process + --contrast, or --clear"], actual: ["<missing>"] },
         });
     }
     return clearSet
@@ -212,15 +221,19 @@ export function emotionTemplate(f) {
     const emotionSet = f.emotion !== undefined;
     const clearSet = Boolean(f.clear);
     if (emotionSet && clearSet) {
-        throw new CliError("VERB BLOCKED: emotion flags mutually exclusive", "emotion: value and --clear are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["either <emotion>, or --clear"], received: ["<emotion>", "--clear"],
-            nextSteps: ["Pick one mode and retry."], errorCode: "EMOTION_FLAG_CONFLICT",
+        throw new CliError("emotion: value and --clear are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "EMOTION_FLAG_CONFLICT",
+            hint: "Pick one mode and retry.",
+            data: { expected: ["either <emotion>, or --clear"], actual: ["<emotion>", "--clear"] },
         });
     }
     if (!emotionSet && !clearSet) {
-        throw new CliError("VERB BLOCKED: emotion value missing", "emotion: must specify <emotion> or --clear.", {
-            exitCode: EXIT_USAGE, required: ["<emotion>, or --clear"], received: ["<missing>"],
-            nextSteps: ["Pass an emotion label, or use --clear."], errorCode: "EMOTION_VALUE_MISSING",
+        throw new CliError("emotion: must specify <emotion> or --clear.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "EMOTION_VALUE_MISSING",
+            hint: "Pass an emotion label, or use --clear.",
+            data: { expected: ["<emotion>, or --clear"], actual: ["<missing>"] },
         });
     }
     return clearSet
@@ -233,9 +246,11 @@ export function contextTemplate(target, f) {
     const removeSet = Boolean(f.remove);
     const n = (stateSet ? 1 : 0) + (clearSet ? 1 : 0) + (removeSet ? 1 : 0);
     if (n === 0) {
-        throw new CliError("VERB BLOCKED: context flag missing", "context: must specify --state X, --clear, or --remove.", {
-            exitCode: EXIT_USAGE, required: ["one of --state <state_id> / --clear / --remove"], received: ["<missing>"],
-            nextSteps: ["Pick exactly one flag."], errorCode: "CONTEXT_FLAG_MISSING",
+        throw new CliError("context: must specify --state X, --clear, or --remove.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "CONTEXT_FLAG_MISSING",
+            hint: "Pick exactly one flag.",
+            data: { expected: ["one of --state <state_id> / --clear / --remove"], actual: ["<missing>"] },
         });
     }
     if (n > 1) {
@@ -246,30 +261,30 @@ export function contextTemplate(target, f) {
             passed.push("--clear");
         if (removeSet)
             passed.push("--remove");
-        throw new CliError("VERB BLOCKED: context flags mutually exclusive", "context: --state / --clear / --remove are mutually exclusive.", {
-            exitCode: EXIT_USAGE, required: ["exactly one of --state / --clear / --remove"], received: passed,
-            nextSteps: ["Pick one and retry."], errorCode: "CONTEXT_FLAG_CONFLICT",
+        throw new CliError("context: --state / --clear / --remove are mutually exclusive.", {
+            exitCode: EXIT_USAGE,
+            errorCode: "CONTEXT_FLAG_CONFLICT",
+            hint: "Pick one and retry.",
+            data: { expected: ["exactly one of --state / --clear / --remove"], actual: passed },
         });
     }
     const append = Boolean(f.append);
     const occurrenceRaw = strOf(f.occurrence).trim();
     const occurrence = occurrenceRaw ? Number(occurrenceRaw) : undefined;
     if (occurrence !== undefined && (!Number.isInteger(occurrence) || occurrence < 1)) {
-        throw new CliError("VERB BLOCKED: scene-ref occurrence invalid", "scene-ref: --occurrence must be a positive integer.", {
+        throw new CliError("scene-ref: --occurrence must be a positive integer.", {
             exitCode: EXIT_USAGE,
-            required: ["--occurrence <positive integer> (1-based)"],
-            received: [occurrenceRaw],
-            nextSteps: ["Use 1 for the first matching scene ref, 2 for the second, and so on."],
             errorCode: "SCENE_REF_OCCURRENCE_INVALID",
+            hint: "Use 1 for the first matching scene ref, 2 for the second, and so on.",
+            data: { expected: ["--occurrence <positive integer> (1-based)"], actual: [occurrenceRaw] },
         });
     }
     if (append && (!stateSet || occurrence !== undefined)) {
-        throw new CliError("VERB BLOCKED: scene-ref append flags invalid", "scene-ref: --append requires --state and cannot be combined with --occurrence.", {
+        throw new CliError("scene-ref: --append requires --state and cannot be combined with --occurrence.", {
             exitCode: EXIT_USAGE,
-            required: ["--state <state_id> --append"],
-            received: [append ? "--append" : "", occurrence !== undefined ? "--occurrence" : "", clearSet ? "--clear" : "", removeSet ? "--remove" : ""].filter(Boolean),
-            nextSteps: ["Append a new actor ref with --state <state_id> --append, or target an existing ref with --occurrence <n>."],
             errorCode: "SCENE_REF_APPEND_FLAG_CONFLICT",
+            hint: "Append a new actor ref with --state <state_id> --append, or target an existing ref with --occurrence <n>.",
+            data: { expected: ["--state <state_id> --append"], actual: [append ? "--append" : "", occurrence !== undefined ? "--occurrence" : "", clearSet ? "--clear" : "", removeSet ? "--remove" : ""].filter(Boolean) },
         });
     }
     if (removeSet)
@@ -285,30 +300,30 @@ export function dialogueTemplate(f) {
     const speakerKind = strOf(f.kind).trim();
     const label = strOf(f.label).trim();
     if (actorId && speakerKind) {
-        throw new CliError("VERB BLOCKED: dialogue speaker ambiguous", "dialogue: --actor and --kind are mutually exclusive.", {
+        throw new CliError("dialogue: --actor and --kind are mutually exclusive.", {
             exitCode: EXIT_USAGE,
-            required: ["exactly one of --actor <actor_id> or --kind <non-actor kind>"],
-            received: ["--actor", "--kind"],
-            nextSteps: ["Keep --actor for a character, or --kind for a non-actor source."],
             errorCode: "SPEAKER_AMBIGUOUS",
+            hint: "Keep --actor for a character, or --kind for a non-actor source.",
+            data: { expected: ["exactly one of --actor <actor_id> or --kind <non-actor kind>"], actual: ["--actor", "--kind"] },
         });
     }
     if (actorId && label) {
-        throw new CliError("VERB BLOCKED: dialogue speaker label misplaced", "dialogue: --label is only valid with --kind.", {
+        throw new CliError("dialogue: --label is only valid with --kind.", {
             exitCode: EXIT_USAGE,
-            required: ["omit --label with --actor, or pair --label with --kind"],
-            received: ["--actor", "--label"],
-            nextSteps: ["Remove --label for an actor line, or use --kind for a labeled non-actor source."],
             errorCode: "SPEAKER_LABEL_WITHOUT_KIND",
+            hint: "Remove --label for an actor line, or use --kind for a labeled non-actor source.",
+            data: { expected: ["omit --label with --actor, or pair --label with --kind"], actual: ["--actor", "--label"] },
         });
     }
     if (actorId)
         return { op: "dialogue.speaker.set", actor_id: actorId };
     if (speakerKind)
         return { op: "dialogue.speaker.set", kind: speakerKind, label: label || undefined };
-    throw new CliError("VERB BLOCKED: dialogue speaker missing", "dialogue: pass --actor <id> or --kind <system|broadcast|offscreen|group>.", {
-        exitCode: EXIT_USAGE, required: ["--actor <actor_id> or --kind <non-actor kind>"], received: ["<missing>"],
-        nextSteps: ["Set --actor for an actor line, or --kind for a non-actor line."], errorCode: "DIALOGUE_SPEAKER_MISSING",
+    throw new CliError("dialogue: pass --actor <id> or --kind <system|broadcast|offscreen|group>.", {
+        exitCode: EXIT_USAGE,
+        errorCode: "DIALOGUE_SPEAKER_MISSING",
+        hint: "Set --actor for an actor line, or --kind for a non-actor line.",
+        data: { expected: ["--actor <actor_id> or --kind <non-actor kind>"], actual: ["<missing>"] },
     });
 }
 // Translate one parsed verb line into a patch op dict (the SAME ops `patch`
@@ -863,10 +878,10 @@ function v4OperationTargets(operation) {
 }
 export function buildV4MutationPlan(session, operations, options = {}) {
     if (session.version !== 4) {
-        throw new CliError("SCRIPT PLAN BLOCKED: wrong version", "A v4 mutation plan requires Script v4.", {
+        throw new CliError("A v4 mutation plan requires Script v4.", {
             exitCode: EXIT_USAGE,
             errorCode: "V4_PLAN_VERSION_INVALID",
-            received: [`Script v${session.version}`],
+            data: { actual: [`Script v${session.version}`] },
         });
     }
     const original = requireScriptV4(session.script);
@@ -954,12 +969,11 @@ export function assertV4PlanHasExplicitNewIds(operations) {
         if (!field || strOf(operation[field]).trim())
             continue;
         const idKind = field === "new_scene_id" ? "scene" : field.replace(/_id$/, "");
-        throw new CliError("SCRIPT V4 PLAN BLOCKED: new ID missing", "Planned creation operations require an explicit candidate ID.", {
+        throw new CliError("Planned creation operations require an explicit candidate ID.", {
             exitCode: EXIT_USAGE,
             errorCode: "V4_PLAN_ID_REQUIRED",
-            required: [`${kind}.${field}`],
-            received: [`${kind}.${field}=<missing>`],
-            nextSteps: [`Generate a candidate with \`scriptctl ids --kind ${idKind} --count 1\`, then include it in the operation.`],
+            hint: `Generate a candidate with \`scriptctl ids --kind ${idKind} --count 1\`, then include it in the operation.`,
+            data: { expected: [`${kind}.${field}`], actual: [`${kind}.${field}=<missing>`] },
         });
     }
 }
@@ -969,11 +983,11 @@ export function assertV4PlanHasExplicitNewIds(operations) {
 export async function applySingleScriptOpToSession(session, opts, op) {
     const plan = strOf(opts["plan"]).trim();
     if (plan) {
-        throw new CliError("SCRIPT OP BLOCKED: --plan is not applicable", "Single-point writes do not use plan digests.", {
+        throw new CliError("Single-point writes do not use plan digests.", {
             exitCode: EXIT_USAGE,
             errorCode: "MULTI_PLAN_USAGE_INVALID",
-            received: [plan],
-            nextSteps: ["Remove --plan from this single-point edit."],
+            hint: "Remove --plan from this single-point edit.",
+            data: { actual: [plan] },
         });
     }
     return applyScriptOpsToSession(session, opts, [op]);
@@ -989,17 +1003,18 @@ export async function applyScriptOpsToSession(session, opts, operations) {
     // One outcome line: what changed + revision (remote) + validation verdict.
     const rev = session.remote ? `; rev ${newRevision}` : "";
     const resultLine = `${applied.join(", ")} applied${rev}; validation ${passed ? "passed" : "needs repair"}`;
+    const issues = summarizeIssues(asList(validation["issues"]));
     const report = {
-        title: passed ? "SCRIPT OP APPLIED" : "SCRIPT OP APPLIED: Validation needs repair",
-        op: opName,
-        changed: applied.length > 0,
-        ...(session.remote ? { idempotent } : {}),
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        result: [resultLine],
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        // Success carries no guidance; only a failed validation needs a next step.
-        next: passed ? undefined : ["Inspect issues and apply another patch."],
+        text: [resultLine, ...issues].join("\n"),
+        data: {
+            op: opName,
+            changed: applied.length > 0,
+            revision: session.remote ? newRevision : undefined,
+            idempotent: session.remote ? idempotent : undefined,
+            validation,
+            issues,
+            script_path: session.artifactLabel,
+        },
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
@@ -1010,32 +1025,32 @@ export async function applySingleScriptOp(opts, op) {
 export function summarizeScriptOp(_script, op) {
     const kind = strOf(op["op"]);
     if (kind === "actor.add")
-        return `已新增人物 ${op["name"] || op["actor_name"]}${op["role_type"] ? `（${op["role_type"]}）` : ""}`;
+        return `Added actor ${op["name"] || op["actor_name"]}${op["role_type"] ? ` (${op["role_type"]})` : ""}`;
     if (kind === "location.add")
-        return `已新增场景地点 ${op["name"] || op["location_name"]}`;
+        return `Added location ${op["name"] || op["location_name"]}`;
     if (kind === "prop.add")
-        return `已新增道具 ${op["name"] || op["prop_name"]}`;
+        return `Added prop ${op["name"] || op["prop_name"]}`;
     if (kind === "episode.add")
-        return `已新增分集${op["episode_id"] ? ` ${op["episode_id"]}` : "（自动编号）"}${op["title"] ? `：${op["title"]}` : ""}`;
+        return `Added episode${op["episode_id"] ? ` ${op["episode_id"]}` : " (generated ID)"}${op["title"] ? `: ${op["title"]}` : ""}`;
     if (kind === "meta.synopsis.set")
-        return `已更新全剧梗概`;
+        return "Updated script synopsis";
     if (kind === "episode.synopsis.set")
-        return `已更新分集梗概 ${op["episode_id"] ?? op["target"] ?? op["at"]}`;
+        return `Updated episode synopsis ${op["episode_id"] ?? op["target"] ?? op["at"]}`;
     if (kind === "state.add")
-        return `已为 ${op["target"]} 新增状态 ${op["state_id"]}: ${op["name"] || op["state_name"]}`;
+        return `Added state ${op["state_id"]}: ${op["name"] || op["state_name"]} to ${op["target"]}`;
     if (kind === "importance.set")
-        return `已将 ${op["target"]} 重要度设为 ${op["importance"]}`;
+        return `Set ${op["target"]} importance to ${op["importance"]}`;
     if (kind === "scene.ref.set")
-        return `已在 ${op["at"]} 设置引用 ${op["target"]}${op["state"] ? `（状态 ${op["state"]}）` : ""}`;
+        return `Set reference ${op["target"]} on ${op["at"]}${op["state"] ? ` (state ${op["state"]})` : ""}`;
     if (kind === "extend.set")
-        return `已在 ${op["at"]} 设置 extend.${op["key"]}`;
+        return `Set extend.${op["key"]} on ${op["at"]}`;
     if (kind === "extend.clear")
-        return op["key"] ? `已在 ${op["at"]} 删除 extend.${op["key"]}` : `已清空 ${op["at"]} 的 extend`;
+        return op["key"] ? `Removed extend.${op["key"]} from ${op["at"]}` : `Cleared extend on ${op["at"]}`;
     if (kind.startsWith("state."))
-        return `已执行 ${kind}: ${op["target"]}`;
+        return `Applied ${kind}: ${op["target"]}`;
     if (kind.startsWith("dialogue."))
-        return `已执行 ${kind}: ${op["at"]}`;
-    return `已执行 ${kind}`;
+        return `Applied ${kind}: ${op["at"]}`;
+    return `Applied ${kind}`;
 }
 // Accept `/re/flags` as-is; wrap a bare pattern as `/pattern/` so
 // `replace --regex --from '^\s*\[[^\]]*\]'` works without the user typing slashes.
@@ -1068,29 +1083,27 @@ export async function applySelectorEditsToSession(session, opts, template, verbL
     const planDigest = planned?.digest ?? null;
     const suppliedPlan = strOf(opts["plan"]).trim();
     if (suppliedPlan && (!multiV4 || !apply)) {
-        throw new CliError("SELECTOR EDIT BLOCKED: --plan is not applicable", "A plan digest is only accepted for a v4 multi-target apply.", {
+        throw new CliError("A plan digest is only accepted for a v4 multi-target apply.", {
             exitCode: EXIT_USAGE,
             errorCode: "MULTI_PLAN_USAGE_INVALID",
-            received: [suppliedPlan],
-            nextSteps: ["Remove --plan, or apply the same v4 multi-target selection that produced the digest."],
+            hint: "Remove --plan, or apply the same v4 multi-target selection that produced the digest.",
+            data: { actual: [suppliedPlan] },
         });
     }
     if (multiV4 && apply && !suppliedPlan) {
-        throw new CliError("SELECTOR EDIT BLOCKED: plan required", "A v4 multi-target write requires its dry-run plan digest.", {
+        throw new CliError("A v4 multi-target write requires its dry-run plan digest.", {
             exitCode: EXIT_USAGE,
             errorCode: "MULTI_PLAN_REQUIRED",
-            required: [planDigest ?? ""],
-            received: ["<missing>"],
-            nextSteps: ["Run the same command without --apply, review the full plan, then retry with `--apply --plan <digest>`."],
+            hint: "Run the same command without --apply, review the full plan, then retry with `--apply --plan <digest>`.",
+            data: { expected: [planDigest ?? ""], actual: ["<missing>"] },
         });
     }
     if (multiV4 && apply && suppliedPlan !== planDigest) {
-        throw new CliError("SELECTOR EDIT BLOCKED: plan mismatch", "The supplied digest does not match the current targets and operations.", {
+        throw new CliError("The supplied digest does not match the current targets and operations.", {
             exitCode: EXIT_INPUT,
             errorCode: "MULTI_PLAN_MISMATCH",
-            required: [planDigest ?? ""],
-            received: [suppliedPlan],
-            nextSteps: ["Review the newly computed dry-run plan, then apply its exact digest."],
+            hint: "Review the newly computed dry-run plan, then apply its exact digest.",
+            data: { expected: [planDigest ?? ""], actual: [suppliedPlan] },
         });
     }
     const source = scriptSourceText(workspace);
@@ -1139,39 +1152,43 @@ export async function applySelectorEditsToSession(session, opts, template, verbL
         const legacyIssueLines = legacyValidation === null
             ? []
             : summarizeIssues(asList(legacyValidation["issues"]));
+        const issues = plannedIssueLines ?? legacyIssueLines;
+        const hint = refs.length === 0
+            ? "Widen the selection with --in, --grep, or predicates."
+            : planDigest
+                ? `Run again with --apply --plan ${planDigest} to commit this exact plan.`
+                : "Run again with --apply to commit.";
+        const lines = [...blast, `validation: ${passed ? "would pass" : "would need repair"}; no write`, ...issues, hint];
         const report = {
-            title: refs.length === 0 ? "SELECTOR EDIT DRY-RUN: no match" : "SELECTOR EDIT DRY-RUN (no write)",
-            op: `${opName}.dry-run`,
-            changed: false,
-            result: [...blast, `validation: ${passed ? "would pass" : "would need repair"}; dry-run, no write`],
-            warnings: passed
-                ? []
-                : plannedIssueLines ?? legacyIssueLines,
-            issues: plannedIssueLines ?? legacyIssueLines,
-            artifacts: [session.artifactLabel],
-            ...(planDigest ? {
-                baseline: session.baselineHash,
-                plan_digest: planDigest,
-                operations,
-                targets: refs,
-                plan: planned?.plan,
-            } : {}),
-            next: [refs.length === 0
-                    ? "Widen the selection (--in / --grep / predicates)."
-                    : planDigest
-                        ? `Re-run with --apply --plan ${planDigest} to commit this exact plan.`
-                        : "Re-run with --apply to commit."],
+            text: lines.join("\n"),
+            data: {
+                op: `${opName}.dry-run`,
+                changed: false,
+                matched: refs.length,
+                applied,
+                skipped,
+                issues,
+                script_path: session.artifactLabel,
+                ...(planDigest ? {
+                    baseline: session.baselineHash,
+                    plan_digest: planDigest,
+                    operations,
+                    targets: refs,
+                    plan: planned?.plan,
+                } : {}),
+            },
         };
         return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
     }
     if (refs.length === 0) {
         return [{
-                title: "SELECTOR EDIT: no match",
-                op: opName,
-                changed: false,
-                result: blast,
-                artifacts: [session.artifactLabel],
-                next: ["Widen the selection (--in / --grep / predicates)."],
+                text: [...blast, "Widen the selection with --in, --grep, or predicates."].join("\n"),
+                data: {
+                    op: opName,
+                    changed: false,
+                    matched: 0,
+                    script_path: session.artifactLabel,
+                },
             }, EXIT_OK];
     }
     const [newRevision, idempotent] = await saveScriptSession(session, opts, opName);
@@ -1179,23 +1196,28 @@ export async function applySelectorEditsToSession(session, opts, template, verbL
     await syncValidationResult(session, validation, newRevision);
     const passed = Boolean(validation["passed"]);
     const rev = session.remote ? `; rev ${newRevision}` : "";
+    const issues = summarizeIssues(asList(validation["issues"]));
     const report = {
-        title: passed ? "SELECTOR EDIT APPLIED" : "SELECTOR EDIT APPLIED: Validation needs repair",
-        op: opName,
-        changed: applied > 0,
-        ...(session.remote ? { idempotent } : {}),
-        result: [...blast, `validation: ${passed ? "passed" : "needs repair"}${rev}`],
-        warnings: passed ? [] : summarizeIssues(asList(validation["issues"])),
-        issues: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        ...(planDigest ? {
-            baseline: session.baselineHash,
-            plan_digest: planDigest,
-            operations,
-            targets: refs,
-            plan: planned?.plan,
-        } : {}),
-        next: passed ? undefined : ["Inspect issues and apply another edit."],
+        text: [...blast, `validation: ${passed ? "passed" : "needs repair"}${rev}`, ...issues].join("\n"),
+        data: {
+            op: opName,
+            changed: applied > 0,
+            matched: refs.length,
+            applied,
+            skipped,
+            revision: session.remote ? newRevision : undefined,
+            idempotent: session.remote ? idempotent : undefined,
+            validation,
+            issues,
+            script_path: session.artifactLabel,
+            ...(planDigest ? {
+                baseline: session.baselineHash,
+                plan_digest: planDigest,
+                operations,
+                targets: refs,
+                plan: planned?.plan,
+            } : {}),
+        },
     };
     return [report, passed ? EXIT_OK : EXIT_NEEDS_AGENT];
 }
@@ -1209,7 +1231,7 @@ export { sortDeep };
 // ===========================================================================
 //
 // Each command is a thin read-only wrapper around the underlying script
-// document. They all return a Report shaped like inspect's existing output but
+// document. They all return a CommandOutput shaped like inspect's existing output but
 // without the `--target` flag — the verb itself encodes the target. Filters
 // use `--in <addr>` (compose with the address parsers) plus per-target
 // predicates (--name / --kind / --has / --grep / --context / --type / --actor
@@ -1260,12 +1282,11 @@ export function buildGrepMatcher(raw) {
     if (m) {
         const pattern = m[1];
         if (isDangerousRegex(pattern)) {
-            throw new CliError("QUERY BLOCKED: regex unsafe", "regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
+            throw new CliError("regex pattern has nested quantifiers (ReDoS risk) or exceeds the length limit.", {
                 exitCode: EXIT_USAGE,
-                required: [`pattern length <= ${MAX_GREP_PATTERN_LEN}; no quantifier-on-group-with-internal-quantifier (e.g. (a+)+)`],
-                received: [`length=${pattern.length}, sample=${pattern.slice(0, 80)}`],
-                nextSteps: ["Rewrite the regex to avoid nested quantifiers, or use a literal substring (drop the /…/ wrapper)."],
                 errorCode: "REGEX_UNSAFE",
+                hint: "Rewrite the regex to avoid nested quantifiers, or use a literal substring (drop the /…/ wrapper).",
+                data: { expected: [`pattern length <= ${MAX_GREP_PATTERN_LEN}; no quantifier-on-group-with-internal-quantifier (e.g. (a+)+)`], actual: [`length=${pattern.length}, sample=${pattern.slice(0, 80)}`] },
             });
         }
         try {
@@ -1281,15 +1302,22 @@ export function buildGrepMatcher(raw) {
     }
     return (hay) => hay.includes(raw);
 }
-export function buildReport(op, title, lines, artifactLabel) {
+export function buildReport(op, lines) {
+    const outputLines = lines.length > 0 ? lines : ["No matches."];
     return {
-        title,
-        op,
-        changed: false,
-        result: lines.length > 0 ? lines : ["No matching items."],
-        artifacts: [artifactLabel],
+        text: outputLines.join("\n"),
+        data: {
+            op,
+            changed: false,
+        },
     };
 }
+export function buildTableReport(op, lines, rowColumns, rows) {
+    const report = buildReport(op, lines);
+    report.data["row_columns"] = rowColumns;
+    report.data["rows"] = rows;
+    return report;
+}
 // ----- summary --------------------------------------------------------------
 export function synopsisPreview(text, limit) {
     const oneLine = text.replace(/\s+/g, " ").trim();
@@ -1353,12 +1381,11 @@ export function resolveActionTargets(script, opts) {
     // "state_changes" (underscore) passed the filter-missing guard but bypassed
     // every concrete predicate, returning the whole script.
     if (hasFilter && !HAS_FILTERS.has(hasFilter)) {
-        throw new CliError("QUERY BLOCKED: --has value invalid", "--has value invalid.", {
+        throw new CliError("--has value invalid.", {
             exitCode: EXIT_USAGE,
-            required: [`--has: one of ${[...HAS_FILTERS].join(", ")}`],
-            received: [hasFilter],
-            nextSteps: ["Use a supported --has value."],
             errorCode: "HAS_FILTER_INVALID",
+            hint: "Use a supported --has value.",
+            data: { expected: [`--has: one of ${[...HAS_FILTERS].join(", ")}`], actual: [hasFilter] },
         });
     }
     const grepMatcher = buildGrepMatcher(strOf(opts["grep"]));
@@ -1451,6 +1478,7 @@ export function assetAppearanceCounts(script, kind) {
 }
 export function listAssetsByKind(script, kind, opts) {
     const lines = [];
+    const rows = [];
     const [key, idKey, nameKey] = (() => {
         switch (kind) {
             case "actor": return ["actors", "actor_id", "actor_name"];
@@ -1527,8 +1555,42 @@ export function listAssetsByKind(script, kind, opts) {
             extra.push(`scenes=${scns}`, `episodes_count=${eps}${arc}`);
         }
         lines.push(`${kind} ${id}: ${name || "-"} ${extra.join(" ")}`);
+        const seen = appearances?.get(id);
+        rows.push({
+            addr: `${kind}:${id}`,
+            kind,
+            id,
+            name,
+            aliases,
+            importance,
+            role,
+            states,
+            description_present: descPresent === "yes",
+            ...(appearances
+                ? {
+                    scenes: seen?.scenes ?? 0,
+                    episodes_count: seen?.episodes.size ?? 0,
+                    episodes: seen ? compactEpisodeRanges(seen.episodes) : "",
+                }
+                : {}),
+        });
     }
-    return lines;
+    return {
+        lines,
+        rows,
+        rowColumns: [
+            "addr",
+            "kind",
+            "id",
+            "name",
+            "aliases",
+            "importance",
+            "role",
+            "states",
+            "description_present",
+            ...(appearances ? ["scenes", "episodes_count", "episodes"] : []),
+        ],
+    };
 }
 export function splitSpeakerList(raw) {
     if (Array.isArray(raw))
@@ -1544,15 +1606,14 @@ export function blankCreateReport(session, validation, idempotent) {
             resultLines.push(`idempotent: ${String(idempotent).toLowerCase()}`);
     }
     return {
-        title: passed ? "SCRIPT CREATED: Blank scaffold" : "SCRIPT CREATED: Validation needs repair",
-        op: "script.create",
-        changed: true,
-        result: resultLines,
-        warnings: summarizeIssues(asList(validation["issues"])),
-        artifacts: [session.artifactLabel],
-        next: [
-            "用 worldview 设定世界观，用 add-actor / add-location / add-prop 注册资产，用 add-episode + insert 搭出分集与场景。",
-        ],
+        text: resultLines.join("\n"),
+        data: {
+            op: "script.create",
+            changed: true,
+            validation,
+            script_path: session.artifactLabel,
+            ...(session.remote ? { revision: session.revision, idempotent } : {}),
+        },
     };
 }
 // ----- add-* (register new entities) ----------------------------------------
@@ -1561,12 +1622,11 @@ export function blankCreateReport(session, validation, idempotent) {
 export function requireNameArg(opts, verb, example) {
     const args = asList(opts["_args"]);
     if (args.length < 1) {
-        throw new CliError(`VERB BLOCKED: ${verb} name missing`, "Name missing.", {
+        throw new CliError("Name missing.", {
             exitCode: EXIT_USAGE,
-            required: ["<name>"],
-            received: ["<empty>"],
-            nextSteps: [example],
             errorCode: "ARGS_MISSING",
+            hint: example,
+            data: { expected: ["<name>"], actual: ["<empty>"] },
         });
     }
     return args[0];