@mindscraft/branch-video-agent-cli 0.4.4 → 0.4.6

package/README.md

@@ -2,6 +2,20 @@
 
 `@mindscraft/branch-video-agent-cli` 是一个可脱离当前代码仓库使用的发布版 CLI，用于通过 Bearer agent token 调用 branch-video、AIHub workflow 与 AI Gateway agent API。
 
+## 图片持久任务（待发布）
+
+`ai-gateway image-generate` / `image-edit` 支持 `--async` 提交、`--wait` 等待，stdin JSON 必须含稳定 `idempotencyKey`。无这两个标记时保持同步兼容。
+
+```powershell
+'{"idempotencyKey":"asset-shot09-v1","model":"gpt-image-2","prompt":"原提示词"}' | branch-video-agent ai-gateway image-generate --async --raw 2>receipt.jsonl
+'{"idempotencyKey":"asset-shot09-v1"}' | branch-video-agent ai-gateway image-get --wait --raw
+'{"taskId":"img_..."}' | branch-video-agent ai-gateway image-get --raw
+```
+
+stderr 输出提交前幂等身份、提交后 taskId 回执；stdout 为单个 JSON。提交响应丢失后按同 key 查询或原样重提，不换 key。等待超时返回任务最后状态及 `waitStopped`，Ctrl+C 不取消服务器任务；unknown 需要人工核对，不能自动重新生成。成功结果保留 `data[].url`，URL 需同项目 Bearer 下载再进入现有资产上传流程，不是公开 CDN URL。
+
+完整 API、幂等与发布边界见仓库 `docs/ai-gateway-image-tasks.md`。本地构建验收需设 `BRANCH_VIDEO_AGENT_DISABLE_AUTO_UPDATE=1`，确保运行候选 dist 而非自动切换到 registry 版本；本任务不执行 npm 发布。
+
 ## 安装与执行
 
 推荐显式指定包和可执行名：
@@ -53,7 +67,9 @@ AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模
 
 场景规划保留较长路线，删除其完整前缀场景；沿途动作、条件、状态效果和检查仍随长路线执行。`maxScenarios` 限制去重后的场景数；无法在步骤、访问次数或搜索预算内到达的边仍会使规划失败。
 
-搜索展开上限的数值不变；可安全去重的相同状态不重复计入，其他状态沿原搜索计数。
+搜索展开上限的数值不变；可安全去重的相同状态不重复计入，其他状态沿原搜索计数。
+
+实测范围不包含 Web 节点的 `branchConfig.defaultAction` 兜底分支，也不要求为仅落入该兜底的消息提供操作配方。业务脚本和兜底行为保持不变；显式消息分支（包括名为 `default` 的消息）、答对、答错及适用的超时仍须真实操作。仅通过豁免分支到达的节点不在本轮覆盖目标内；仍有正常路径可达的节点继续测试。JSON 报告以 `WEB_DEFAULT_NOT_TESTED` 逐边记录，JUnit 标为 `skipped`，不计作覆盖或通过；报告 `passed` 仅表示本轮要求实测的范围通过。该豁免不声称兜底不可达，也不影响其他类型的 default 校验。
 
 ```powershell
 @'
@@ -94,11 +110,11 @@ sidecar 使用 `branch-video-playtest/1`，Web 结果必须提供 iframe 内的
 
 支持 `click`、`fill`、`selectOption`、`check`、`press`、`dragTo`、`setInputFiles` 和 `waitFor`。只要输入中有合法 `reportDir`，静态门禁、契约、版本漂移和浏览器启动等前置失败也会输出 `branch-video-playtest-report.json`、`junit.xml`；失败场景另存截图、trace、视频和浏览器日志。若 Chromium 缺失，执行 `npx playwright install chromium`。
 
-CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
-
-从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
-
-从 `0.4.4` 起，runner 在现有超时内等待“进入游戏”或“开始体验”入口；已开始播放时直接继续，后续节点和路由断言保持不变。
+CI 顺序为：V3 静态 self-test → 草稿 `playtest run` → 外部发布步骤 → `version get` 精确内容读回。发布内容与已测草稿一致时无需再跑发布版全量测试；内容变化后应重新测试。`playtest run` 自身始终只读，不承担发布。
+
+从 `0.4.3` 起，规划器删除被更长场景完整包含的有序前缀场景，保留条件、状态效果与全部目标边；场景数由实际图决定，不固定为 96。重复搜索状态也会合并以减少规划开销。覆盖或路径预算失败仍返回失败，不通过删边取得通过。复测时记录实际可执行文件路径；升级全局 npm 包不会更新任务内复制的旧 CLI。
+
+从 `0.4.4` 起，runner 在现有超时内等待“进入游戏”或“开始体验”入口；已开始播放时直接继续，后续节点和路由断言保持不变。
 
 AIHub 导入公共库示例：
 

package/dist/commands/aiGateway.js

@@ -127,6 +127,58 @@ function normalizeImageEditPayload(payload) {
         files,
     };
 }
+const imageTasksPath = '/api/agent/ai-gateway/images/tasks';
+function validateImageWait(context) {
+    if (context.flags.wait && [context.flags.timeoutMs, context.flags.pollIntervalMs].some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+        throw new CliCommandError('Image wait timeout and poll interval must be positive integer milliseconds', 'VALIDATION_ERROR');
+    }
+}
+async function finishImageTask(context, initial) {
+    let task = initial;
+    context.runtime.writeStderr(`${JSON.stringify({ event: 'image-task', taskId: task.taskId, idempotencyKey: task.idempotencyKey, status: task.status })}\n`);
+    if (!context.flags.wait)
+        return { data: task };
+    const deadline = context.runtime.now() + context.flags.timeoutMs;
+    while (true) {
+        if (task.status === 'succeeded') {
+            const result = task.result || {};
+            return { data: { ...result, data: (result.data || []).map((item) => ({ ...item, url: context.client.resolveUrl(item.url) })),
+                    taskId: task.taskId, idempotencyKey: task.idempotencyKey, status: task.status } };
+        }
+        if (task.status === 'failed' || task.status === 'unknown') {
+            throw new CliCommandError(task.error?.message || `Image task ${task.status}`, task.status === 'unknown' ? 'RECONCILIATION_REQUIRED' : 'RUN_FAILED', task);
+        }
+        const remaining = deadline - context.runtime.now();
+        if (remaining <= 0)
+            return { data: { ...task, waitStopped: 'timeout', message: 'Local wait stopped; query this task to continue. No new submission was made.' } };
+        await context.runtime.sleep(Math.min(context.flags.pollIntervalMs, remaining));
+        if (context.runtime.now() >= deadline)
+            return { data: { ...task, waitStopped: 'timeout', message: 'Local wait stopped; query this task to continue. No new submission was made.' } };
+        try {
+            task = (await context.client.request(`${imageTasksPath}/${encodeURIComponent(task.taskId)}`, { method: 'GET', timeoutMs: Math.max(1, Math.min(15000, deadline - context.runtime.now())) })).data;
+        }
+        catch {
+            return { data: { ...task, waitStopped: context.runtime.now() >= deadline ? 'timeout' : 'query_error', message: 'Local wait stopped; task status is last observed. Recover using taskId.' } };
+        }
+    }
+}
+async function submitImage(context, operation) {
+    validateImageWait(context);
+    const idempotencyKey = getRequiredString(context.payload, 'idempotencyKey');
+    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(idempotencyKey))
+        throw new CliCommandError('Invalid idempotencyKey', 'VALIDATION_ERROR');
+    const payload = omitKeys(context.payload, ['idempotencyKey']);
+    context.runtime.writeStderr(`${JSON.stringify({ event: 'image-submit', idempotencyKey, recovery: 'ai-gateway image-get' })}\n`);
+    let result;
+    try {
+        result = await context.client.request(imageTasksPath, { method: 'POST', timeoutMs: 15000,
+            body: { idempotencyKey, operation, body: operation === 'edits' ? normalizeImageEditPayload(payload) : payload } });
+    }
+    catch (error) {
+        throw new CliCommandError('Submission response unavailable or rejected; recover by idempotencyKey before any new generation.', 'IMAGE_SUBMIT_ERROR', { idempotencyKey, status: 'submission_unconfirmed', error: error instanceof Error ? error.message : String(error) });
+    }
+    return finishImageTask(context, result.data);
+}
 function inferMusicQueryOperation(operation) {
     switch (operation) {
         case 'vocal-removal':
@@ -197,20 +249,33 @@ export const aiGatewayCommands = {
         });
         return { data: result.data, requestId: result.requestId };
     },
-    'image-generate': async ({ client, payload }) => {
+    'image-generate': async (context) => {
+        if (context.flags.async || context.flags.wait)
+            return submitImage(context, 'generations');
+        const { client, payload } = context;
         const result = await client.request('/api/agent/ai-gateway/images/generations', {
             method: 'POST',
             body: payload,
         });
         return { data: result.data, requestId: result.requestId };
     },
-    'image-edit': async ({ client, payload }) => {
+    'image-edit': async (context) => {
+        if (context.flags.async || context.flags.wait)
+            return submitImage(context, 'edits');
+        const { client, payload } = context;
         const result = await client.request('/api/agent/ai-gateway/images/edits', {
             method: 'POST',
             body: normalizeImageEditPayload(payload),
         });
         return { data: result.data, requestId: result.requestId };
     },
+    'image-get': async (context) => {
+        validateImageWait(context);
+        const taskId = getOptionalString(context.payload, 'taskId');
+        const idempotencyKey = taskId ? '' : getRequiredString(context.payload, 'idempotencyKey');
+        const result = await context.client.request(taskId ? `${imageTasksPath}/${encodeURIComponent(taskId)}` : imageTasksPath, { method: 'GET', query: idempotencyKey ? { idempotencyKey } : undefined, timeoutMs: 15000 });
+        return finishImageTask(context, result.data);
+    },
     'video-create': async (context) => {
         const result = await context.client.request('/api/agent/ai-gateway/predictions', {
             method: 'POST',

package/dist/commands/playtest.js

@@ -59,6 +59,7 @@ async function runPlaytest({ client, payload, runtime }) {
     let reachableNodeIds = [];
     let reachableEdgeIds = [];
     let scenarioResults = [];
+    let reachabilityWarnings = [];
     let phase = 'input';
     try {
         input = parseInput(payload);
@@ -70,6 +71,13 @@ async function runPlaytest({ client, payload, runtime }) {
         fingerprint = createScriptFingerprint(script);
         phase = 'static-preflight';
         assertPlaytestStaticPreflight(script);
+        const graph = getReachablePlaytestGraph(script);
+        reachabilityWarnings = graph.excludedEdges.map(edge => ({
+            code: edge.skippedReason ? 'WEB_DEFAULT_NOT_TESTED' : 'EDGE_NOT_USER_TRIGGERABLE',
+            message: (edge.skippedReason || edge.unreachableReason),
+            phase: 'scenario-generation', nodeId: edge.from, edgeId: edge.id,
+            details: { edge, interaction: script.graph.nodes[edge.from]?.interactions?.find((item) => item.id === edge.ownerId) },
+        }));
         phase = 'contract';
         let rawContract;
         try {
@@ -94,10 +102,11 @@ async function runPlaytest({ client, payload, runtime }) {
             maxNodeVisits: normalizePositiveInt(input.limits?.maxNodeVisits, DEFAULT_LIMITS.maxNodeVisits, 'limits.maxNodeVisits'),
         };
         const concurrency = Math.min(8, normalizePositiveInt(input.concurrency, 2, 'concurrency'));
+        if (limits.scenarioTimeoutMs > 2147483647)
+            throw new PlaytestError('VALIDATION_ERROR', 'limits.scenarioTimeoutMs must not exceed 2147483647');
         const viewport = input.viewport || { width: 1280, height: 720 };
         phase = 'scenario-generation';
         const scenarios = buildPlaytestScenarios(script, limits, contract.nodeVisitLimits);
-        const graph = getReachablePlaytestGraph(script);
         reachableNodeIds = graph.reachableNodeIds;
         reachableEdgeIds = graph.reachableEdges.map((edge) => edge.id);
         const draftPlayer = input.source.kind === 'draft' ? createDraftPlayerUrl(client.resolveUrl('/')) : null;
@@ -144,7 +153,7 @@ async function runPlaytest({ client, payload, runtime }) {
             coveredEdgeIds,
             scenarios: scenarioResults,
             findings,
-            warnings,
+            warnings: [...reachabilityWarnings, ...warnings],
         };
         const reportPaths = await writePlaytestReport(input.reportDir, report);
         if (report.status === 'failed') {
@@ -178,7 +187,7 @@ async function runPlaytest({ client, payload, runtime }) {
             coveredEdgeIds: [...new Set(scenarioResults.flatMap((result) => result.coveredEdges))],
             scenarios: scenarioResults,
             findings: [finding],
-            warnings: [],
+            warnings: reachabilityWarnings,
         };
         const reportPaths = await writePlaytestReport(reportDir, report);
         throw new PlaytestError(failure.code, failure.message, { reportPaths, report });

package/dist/commands/project.js

@@ -14,6 +14,11 @@ export const projectCommands = {
         });
         return { data: result.data, requestId: result.requestId };
     },
+    'draft-get': async ({ client, payload }) => {
+        const projectId = getRequiredString(payload, 'projectId');
+        const result = await client.request(`/api/branch-video/${encodeURIComponent(projectId)}`, { method: 'GET' });
+        return { data: result.data, requestId: result.requestId };
+    },
     create: async ({ client, payload }) => {
         const result = await client.request('/api/branch-video', {
             method: 'POST',

package/dist/lib/flags.d.ts

@@ -3,6 +3,7 @@ import type { CliRuntime } from './runtime.js';
 export type CliFlags = {
     raw: boolean;
     wait: boolean;
+    async?: boolean;
     help: boolean;
     timeoutMs: number;
     pollIntervalMs: number;

package/dist/lib/flags.js

@@ -58,6 +58,9 @@ export function parseCliArgs(argv) {
             case '--wait':
                 flags.wait = true;
                 break;
+            case '--async':
+                flags.async = true;
+                break;
             case '--timeout':
                 flags.timeoutMs = Number(readValue(argv, index, arg));
                 index += 1;
@@ -95,12 +98,13 @@ export function getCliHelpText() {
         'Groups:',
         '  preset     list | upsert',
         '  workflow   run | status | outputs',
-        '  project    list | get | create | import-aihub | update | delete',
+        '  project    list | get | draft-get | create | import-aihub | update | delete',
         '  version    list | get | publish',
         '  agent-production create | status | cancel | finalize | autopilot-binding | events | metrics | multica-comment-payload | node claim|inputs|complete|submit|block|fail|retry|expire | blocker resolve | artifact submit|list | asset-job poll|retry|revise|attach-artifact|fail | gate evaluate|results',
         '  aihub-production schema | start | status | retry',
         '  character  search | create | get',
-        '  ai-gateway capabilities | request | media-understand | image-generate | image-edit | video-create | video-get | seed-audio-create | seed-audio-get | music-submit | music-get | tts-create | tts-get',
+        '  ai-gateway capabilities | request | media-understand | image-generate | image-edit | image-get | video-create | video-get | seed-audio-create | seed-audio-get | music-submit | music-get | tts-create | tts-get',
+        '  Images: --async (or --wait) requires stdin idempotencyKey; image-get accepts taskId or idempotencyKey. Recovery receipts go to stderr; stdout remains one JSON document.',
         '  playtest   run',
         '',
         'Config precedence:',

package/dist/lib/http.d.ts

@@ -2,6 +2,7 @@ type RequestOptions = {
     method: string;
     body?: unknown;
     query?: Record<string, unknown>;
+    timeoutMs?: number;
 };
 type RequestResult<T> = {
     data: T;

package/dist/lib/http.js

@@ -42,6 +42,7 @@ export class CliHttpClient {
                 method: options.method,
                 headers,
                 body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: options.timeoutMs ? AbortSignal.timeout(options.timeoutMs) : undefined,
             });
         }
         catch (error) {

package/dist/playtest/contract.js

@@ -66,13 +66,24 @@ export function validatePlaytestContract(script, rawContract) {
         result.steps.forEach((step, stepIndex) => assertStep(step, `webResults[${resultIndex}].steps[${stepIndex}]`));
     }
     const nodes = script?.graph?.nodes || {};
-    const { reachableEdges, reachableNodeIds } = getReachablePlaytestGraph(script);
+    const { reachableEdges, reachableNodeIds, excludedEdges } = getReachablePlaytestGraph(script);
     for (const nodeId of reachableNodeIds) {
         const node = nodes[nodeId];
         if (node?.type !== 'web')
             continue;
         const mapping = node.config?.messageMapping || {};
+        const skipsDefault = excludedEdges.some(edge => edge.from === nodeId && edge.skippedReason);
+        const explicitRoutes = new Set(reachableEdges
+            .filter(edge => edge.from === nodeId && edge.owner === 'node' && edge.trigger.type === 'message')
+            .map(edge => String(edge.trigger.value)));
+        // A message may open a native interaction rather than route the Web node.
+        for (const interaction of node.interactions || []) {
+            if (interaction.trigger?.type === 'message')
+                explicitRoutes.add(String(interaction.trigger.value));
+        }
         for (const routeValue of new Set(Object.values(mapping).filter((value) => typeof value === 'string'))) {
+            if (skipsDefault && !explicitRoutes.has(routeValue))
+                continue;
             const recipe = rawContract.webResults.find((candidate) => candidate.nodeId === nodeId && candidate.routeValue === routeValue);
             if (!recipe) {
                 throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `Reachable Web result ${nodeId}:${routeValue} has no real-action recipe`, {
@@ -100,14 +111,9 @@ export function validatePlaytestContract(script, rawContract) {
     for (const edge of reachableEdges) {
         if (nodes[edge.from]?.type !== 'web' || edge.owner !== 'node')
             continue;
-        const explicitRoutes = new Set(reachableEdges
-            .filter((candidate) => candidate.from === edge.from && candidate.trigger.type === 'message')
-            .map((candidate) => String(candidate.trigger.value)));
         const recipe = edge.trigger.type === 'message'
             ? rawContract.webResults.find((candidate) => candidate.nodeId === edge.from && candidate.routeValue === String(edge.trigger.value))
-            : edge.default
-                ? rawContract.webResults.find((candidate) => candidate.nodeId === edge.from && !explicitRoutes.has(candidate.routeValue))
-                : null;
+            : null;
         if (!recipe) {
             throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `Reachable Web edge ${edge.id} has no real-action recipe`, {
                 nodeId: edge.from,

package/dist/playtest/graph.d.ts

@@ -4,4 +4,5 @@ export declare function getReachablePlaytestGraph(script: unknown): {
     entryNodeId: string;
     reachableNodeIds: string[];
     reachableEdges: PlaytestEdge[];
+    excludedEdges: PlaytestEdge[];
 };

package/dist/playtest/graph.js

@@ -30,20 +30,74 @@ function addEdge(edges, from, owner, ownerId, trigger, action, isDefault = false
         default: isDefault || undefined,
     });
 }
-function addBranchConfigEdges(edges, from, owner, ownerId, config) {
+function addBranchConfigEdges(edges, from, owner, ownerId, config, defaultTrigger = 'default') {
+    const earlierConditions = new Map();
     for (const rule of config?.rules || []) {
         const rawTrigger = rule.trigger || { type: 'unknown' };
         const trigger = {
             type: rawTrigger.type,
             value: rawTrigger.value ?? rawTrigger.optionId ?? rawTrigger.optionIds,
         };
+        const matchValue = trigger.type === 'option'
+            ? String(trigger.value ?? '').trim().toLowerCase()
+            : trigger.type === 'message' ? String(trigger.value ?? '').trim() : trigger.value;
+        const key = JSON.stringify([trigger.type, matchValue]);
+        const earlier = earlierConditions.get(key) || [];
+        const conditions = [
+            ...(rule.condition ? [rule.condition] : []),
+            ...earlier.map((condition) => ({ type: 'not', condition })),
+        ];
         addEdge(edges, from, owner, ownerId, trigger, rule.action, false, {
-            condition: rule.condition,
+            condition: conditions.length > 1 ? { type: 'and', conditions } : conditions[0],
             variableActions: rule.variableActions,
             inventoryActions: rule.inventoryActions,
         });
+        earlierConditions.set(key, [...earlier, rule.condition || { type: 'and', conditions: [] }]);
     }
-    addEdge(edges, from, owner, ownerId, { type: 'default' }, config?.defaultAction, true);
+    const completeConditions = defaultTrigger === 'complete' ? earlierConditions.get(JSON.stringify(['complete', undefined])) || [] : [];
+    addEdge(edges, from, owner, ownerId, { type: defaultTrigger }, config?.defaultAction, true, {
+        condition: completeConditions.length ? { type: 'and', conditions: completeConditions.map((condition) => ({ type: 'not', condition })) } : undefined,
+    });
+}
+// Mirror ScoreSettlement's sorted ranges, extrema and lowest-level gap fallback.
+function settlementConditions(interactive) {
+    const config = interactive.settlementConfig || interactive;
+    if (!Array.isArray(config.levels) || !config.levels.length
+        || !config.levels.every((level) => level && typeof level.id === 'string' && Number.isFinite(level.minScore) && Number.isFinite(level.maxScore) && level.minScore <= level.maxScore)
+        || !Array.isArray(config.values))
+        return null;
+    const levels = [...config.levels].sort((a, b) => b.minScore - a.minScore);
+    const primary = config.values?.find((value) => value.isPrimary) || config.values?.[0];
+    const and = (...conditions) => ({ type: 'and', conditions });
+    const not = (condition) => ({ type: 'not', condition });
+    const compare = (op, value) => ({ type: 'settlement_score', variable: primary?.variableName, op, value });
+    const high = compare('gte', Math.max(...levels.map(level => level.maxScore)));
+    const low = compare('lte', Math.min(...levels.map(level => level.minScore)));
+    const ranges = levels.map(level => and(compare('gte', level.minScore), compare('lte', level.maxScore)));
+    const result = new Map();
+    for (const [index, level] of levels.entries()) {
+        const id = level.id.toLowerCase();
+        const grade = id.includes('level_s') || id.includes('score_s') ? 'score_s'
+            : id.includes('level_a') || id.includes('score_a') ? 'score_a'
+                : id.includes('level_b') || id.includes('score_b') ? 'score_b' : 'default';
+        const conditions = primary ? [
+            and(not(high), not(low), ranges[index], ...ranges.slice(0, index).map(not)),
+            ...(index === 0 ? [high] : []),
+            ...(index === levels.length - 1 ? [and(not(high), low), and(not(high), not(low), ...ranges.map(not))] : []),
+        ] : [level === config.levels[config.levels.length - 1] ? and() : not(and())];
+        const prior = result.get(grade);
+        result.set(grade, { type: 'or', conditions: [...(prior?.conditions || []), ...conditions] });
+    }
+    return result;
+}
+function closedChoiceDefault(interaction) {
+    const interactive = interaction.interactive || {};
+    return !interaction.branchConfig && interactive.type === 'story_choice'
+        && interactive.inputMode === 'button' && !interactive.collectMode
+        && !(interaction.branches || []).some((branch) => branch.when === 'all_clicked')
+        && Array.isArray(interactive.options) && interactive.options.length > 0
+        && interactive.options.every((option) => typeof option.id === 'string'
+            && (interaction.branches || []).some((branch) => branch.when === option.id && branch.then));
 }
 export function extractPlaytestEdges(script) {
     const graph = script?.graph;
@@ -53,10 +107,15 @@ export function extractPlaytestEdges(script) {
         const node = rawNode || {};
         if (node.type === 'start')
             addEdge(edges, nodeId, 'node', nodeId, { type: 'enter' }, node.config?.next);
-        if (node.type === 'video' || node.type === 'image') {
+        const avgCompletionInteraction = node.type === 'avg' && (node.interactions || []).some((interaction) => interaction.trigger?.type === 'complete');
+        if (node.type === 'video' || node.type === 'image' || (node.type === 'avg' && !node.branchConfig && !avgCompletionInteraction)) {
             addEdge(edges, nodeId, 'node', nodeId, { type: 'complete' }, node.config?.onComplete);
         }
-        addBranchConfigEdges(edges, nodeId, 'node', nodeId, node.branchConfig);
+        // Completion interactions preempt completion routing, not enter/message rules.
+        const nodeBranchConfig = avgCompletionInteraction && node.branchConfig
+            ? { ...node.branchConfig, rules: (node.branchConfig.rules || []).filter((rule) => rule.trigger?.type !== 'complete'), defaultAction: undefined }
+            : node.branchConfig;
+        addBranchConfigEdges(edges, nodeId, 'node', nodeId, nodeBranchConfig, node.type === 'avg' ? 'complete' : 'default');
         for (const handler of node.config?.messageHandlers || []) {
             addEdge(edges, nodeId, 'node', nodeId, handler.when || { type: 'message' }, handler.then, false, {
                 variableActions: handler.variableActions,
@@ -71,19 +130,45 @@ export function extractPlaytestEdges(script) {
             });
         }
         for (const interaction of node.interactions || []) {
+            const firstEdge = edges.length;
+            const settlement = interaction.interactive?.type === 'score_settlement'
+                ? settlementConditions(interaction.interactive) : null;
             addBranchConfigEdges(edges, nodeId, 'interaction', interaction.id, interaction.branchConfig);
-            for (const legacy of interaction.branches || []) {
+            for (const legacy of interaction.branchConfig ? [] : interaction.branches || []) {
                 addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'legacy', value: legacy.when }, legacy.then, false, {
-                    condition: typeof legacy.when === 'object' ? legacy.when : undefined,
+                    condition: settlement?.get(String(legacy.when).trim().toLowerCase()) || (typeof legacy.when === 'object' ? legacy.when : undefined),
                     variableActions: legacy.variableActions,
                     inventoryActions: legacy.inventoryActions,
                 });
             }
             addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'timeout' }, interaction.fallback?.onTimeout);
-            addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'default' }, interaction.fallback?.onDefault, true);
+            if (!interaction.branchConfig)
+                addEdge(edges, nodeId, 'interaction', interaction.id, { type: 'default' }, interaction.fallback?.onDefault, true);
+            for (const edge of edges.slice(firstEdge)) {
+                if (edge.default && closedChoiceDefault(interaction)) {
+                    edge.unreachableReason = 'Button story choice has no skip control and every option has an unconditional legacy branch';
+                }
+                if (edge.default && !interaction.branchConfig && settlement) {
+                    const unmatched = [...settlement].filter(([result]) => !(interaction.branches || []).some((branch) => String(branch.when).trim().toLowerCase() === result));
+                    if (!unmatched.length) {
+                        edge.unreachableReason = 'Every configured settlement level, including extrema and gap fallback, emits an explicitly handled score result';
+                    }
+                    else {
+                        edge.condition = { type: 'or', conditions: unmatched.map(([, condition]) => condition) };
+                    }
+                }
+                if (edge.trigger.type === 'timeout' && interaction.interactive?.type === 'score_settlement'
+                    && !(Number(interaction.timeLimit) > 0)) {
+                    edge.unreachableReason = 'Settlement has no active interaction timer';
+                }
+            }
         }
     }
     for (const edge of edges) {
+        // Test-scope policy, not a claim that the business fallback is unreachable.
+        if (nodes[edge.from]?.type === 'web' && edge.owner === 'node' && edge.default) {
+            edge.skippedReason = 'Web default fallback is excluded from real-action testing by approved test scope; not tested';
+        }
         if (edge.actionType !== 'restart')
             continue;
         const oldTarget = edge.to;
@@ -99,6 +184,7 @@ export function getReachablePlaytestGraph(script) {
     const allEdges = extractPlaytestEdges(script);
     const reachableNodeIds = new Set();
     const reachableEdges = [];
+    const excludedEdges = [];
     const queue = entryNodeId ? [entryNodeId] : [];
     while (queue.length) {
         const nodeId = queue.shift();
@@ -106,10 +192,14 @@ export function getReachablePlaytestGraph(script) {
             continue;
         reachableNodeIds.add(nodeId);
         for (const edge of allEdges.filter((candidate) => candidate.from === nodeId)) {
+            if (edge.unreachableReason || edge.skippedReason) {
+                excludedEdges.push(edge);
+                continue;
+            }
             reachableEdges.push(edge);
             if (nodes[edge.to] && !reachableNodeIds.has(edge.to))
                 queue.push(edge.to);
         }
     }
-    return { entryNodeId, reachableNodeIds: [...reachableNodeIds], reachableEdges };
+    return { entryNodeId, reachableNodeIds: [...reachableNodeIds], reachableEdges, excludedEdges };
 }

package/dist/playtest/report.js

@@ -21,8 +21,10 @@ export function createJUnitXml(report) {
         return `<testcase classname="branch-video-playtest" name="${escapeXml(scenario.id)}" time="${(scenario.durationMs / 1000).toFixed(3)}">${failure}</testcase>`;
     }).join('');
     const gateCases = gateFindings.map((finding, index) => (`<testcase classname="branch-video-playtest.gate" name="gate-${index + 1}-${escapeXml(finding.code)}" time="0.000"><failure type="${escapeXml(finding.code)}" message="${escapeXml(finding.message)}">${escapeXml(JSON.stringify(finding.details ?? null))}</failure></testcase>`)).join('');
-    const tests = report.scenarios.length + gateFindings.length;
-    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="branch-video-playtest" tests="${tests}" failures="${failures}" time="${duration.toFixed(3)}">${scenarioCases}${gateCases}</testsuite>\n`;
+    const skipped = report.warnings.filter(warning => warning.code === 'WEB_DEFAULT_NOT_TESTED');
+    const skippedCases = skipped.map(warning => (`<testcase classname="branch-video-playtest.excluded" name="${escapeXml(warning.edgeId)}" time="0.000"><skipped message="${escapeXml(warning.message)}"/></testcase>`)).join('');
+    const tests = report.scenarios.length + gateFindings.length + skipped.length;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="branch-video-playtest" tests="${tests}" failures="${failures}" skipped="${skipped.length}" time="${duration.toFixed(3)}">${scenarioCases}${gateCases}${skippedCases}</testsuite>\n`;
 }
 export async function writePlaytestReport(reportDir, report) {
     await mkdir(reportDir, { recursive: true });

package/dist/playtest/runner.d.ts

@@ -16,6 +16,7 @@ interface RunnerOptions {
     };
 }
 export declare function startPlayback(frame: Frame, entryNodeId: string, entryNodeType: string, timeout: number): Promise<void>;
+export declare function completeAvgPlayback(frame: Frame, nodeId: string, deadline: number): Promise<void>;
 export declare function runPlaytestScenarios(options: RunnerOptions): Promise<PlaytestScenarioResult[]>;
 export declare function createDraftPlayerUrl(baseUrl: string): {
     playerUrl: string;

package/dist/playtest/runner.js

@@ -86,20 +86,36 @@ async function waitForPlayerFrame(page, playerUrl, timeout) {
     }
     throw new PlaytestError('PLAYER_LOAD_FAILED', `Player iframe did not load ${playerUrl}`);
 }
+async function playerStartupExceptions(frame) {
+    return frame.evaluate(() => {
+        const exceptions = globalThis.__bvPlaytestStartupExceptions;
+        return Array.isArray(exceptions) ? exceptions : [];
+    }).catch(() => []);
+}
+async function throwForPlayerStartupException(frame) {
+    const exceptions = await playerStartupExceptions(frame);
+    if (exceptions.length) {
+        throw new PlaytestError('PLAYER_INIT_FAILED', 'Player raised an exception before the playtest handshake', { startupExceptions: exceptions });
+    }
+}
 async function assertPlayerProtocol(frame, timeout) {
     const root = frame.locator('[data-bv-playtest-protocol]').first();
     try {
-        await root.waitFor({ state: 'attached', timeout: Math.min(timeout, 5000) });
+        if (timeout <= 0)
+            throw new Error('Scenario deadline elapsed');
+        await root.waitFor({ state: 'attached', timeout });
     }
     catch {
-        throw new PlaytestError('PLAYER_PLAYTEST_PROTOCOL_UNSUPPORTED', 'Player does not expose the BV playtest protocol');
+        await throwForPlayerStartupException(frame);
+        throw new PlaytestError('PLAYER_HANDSHAKE_TIMEOUT', 'Player did not expose the BV playtest protocol within the scenario budget');
     }
     const protocol = await root.getAttribute('data-bv-playtest-protocol');
     if (protocol !== '1') {
         throw new PlaytestError('PLAYER_PLAYTEST_PROTOCOL_UNSUPPORTED', `Unsupported BV playtest protocol: ${protocol || 'missing'}`, { protocol });
     }
     if (await root.getAttribute('data-bv-player-state') === 'error') {
-        throw new PlaytestError('PLAYER_INIT_FAILED', 'Player entered the error state before playback started');
+        const exceptions = await playerStartupExceptions(frame);
+        throw new PlaytestError('PLAYER_INIT_FAILED', 'Player entered the error state before playback started', exceptions.length ? { startupExceptions: exceptions } : undefined);
     }
 }
 async function waitForNode(frame, nodeId, timeout) {
@@ -245,11 +261,76 @@ async function clickAction(frame, action) {
     else
         await control.click();
 }
-async function executeNativeInteraction(frame, node, edge, contract) {
+function normalizeSettlementResult(value) {
+    return String(value ?? '').trim().toLowerCase();
+}
+async function executeScoreSettlement(frame, interaction, edge) {
+    const target = (edge.trigger.type === 'legacy' || edge.trigger.type === 'result')
+        ? normalizeSettlementResult(edge.trigger.value) : '';
+    if (!edge.default && !['score_s', 'score_a', 'score_b', 'default'].includes(target)) {
+        throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `Unsupported score settlement target: ${edge.trigger.type}:${String(edge.trigger.value || '')}`);
+    }
+    const actual = normalizeSettlementResult(await frame.locator('[data-bv-settlement-result]').getAttribute('data-bv-settlement-result'));
+    if (!actual)
+        throw new PlaytestError('SETTLEMENT_RESULT_MISSING', `Score settlement did not expose a result for ${target}`);
+    if (!['score_s', 'score_a', 'score_b', 'default'].includes(actual)) {
+        throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `Unsupported score settlement result: ${actual}`);
+    }
+    if (edge.default) {
+        if (interaction.branchConfig) {
+            throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', 'Score settlement default does not support explicit branchConfig');
+        }
+        const matchedLegacy = (interaction.branches || []).some((branch) => (typeof branch?.when === 'string' && normalizeSettlementResult(branch.when) === actual));
+        if (matchedLegacy) {
+            throw new PlaytestError('SETTLEMENT_DEFAULT_NOT_REACHED', `Score settlement result ${actual} has an explicit branch`);
+        }
+        await clickAction(frame, 'confirm-settlement');
+        return;
+    }
+    if (actual !== target)
+        throw new PlaytestError('SETTLEMENT_RESULT_MISMATCH', `Score settlement result ${actual} does not match ${target}`, { actual, target });
+    await clickAction(frame, 'confirm-settlement');
+}
+export async function completeAvgPlayback(frame, nodeId, deadline) {
+    if (Date.now() >= deadline)
+        throw new PlaytestError('AVG_COMPLETION_TIMEOUT', `No scenario budget remains for AVG ${nodeId}`);
+    let clickedStep;
+    let observedAvg = false;
+    while (Date.now() < deadline) {
+        const state = await frame.evaluate((id) => {
+            const document = globalThis.document;
+            const current = document.querySelector('[data-bv-node-id]')?.getAttribute('data-bv-node-id');
+            const avg = Array.from(document.querySelectorAll('[data-bv-avg-node-id]')).find((element) => element.getAttribute('data-bv-avg-node-id') === id);
+            return { nodeId: current, step: avg?.getAttribute('data-bv-avg-step'), completed: avg?.getAttribute('data-bv-avg-completed') === 'true', ended: document.querySelector('[data-bv-ended]')?.getAttribute('data-bv-ended') === 'true' };
+        }, nodeId);
+        if (state.ended || (state.nodeId && state.nodeId !== nodeId))
+            return;
+        if (state.step != null)
+            observedAvg = true;
+        if (state.completed)
+            return;
+        const next = frame.getByRole('button', { name: '下一句', exact: true });
+        if (state.step != null && state.step !== clickedStep && await next.isVisible()) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            await next.click({ timeout: remaining });
+            clickedStep = state.step;
+        }
+        const remaining = deadline - Date.now();
+        if (remaining > 0)
+            await frame.page().waitForTimeout(Math.min(100, remaining));
+    }
+    throw new PlaytestError(observedAvg ? 'AVG_COMPLETION_TIMEOUT' : 'AVG_PLAYTEST_PROTOCOL_UNSUPPORTED', `AVG ${nodeId} did not expose completion within the remaining scenario budget`, { nodeId, clickedStep });
+}
+async function executeNativeInteraction(frame, node, edge, contract, deadline) {
     const interaction = (node.interactions || []).find((candidate) => candidate.id === edge.ownerId);
     if (!interaction)
         throw new PlaytestError('INTERACTION_NOT_RENDERED', `Interaction ${edge.ownerId} is absent from node ${edge.from}`);
-    if (node.type === 'web' && interaction.trigger?.type === 'message') {
+    if (node.type === 'avg' && interaction.trigger?.type === 'complete') {
+        await completeAvgPlayback(frame, edge.from, deadline);
+    }
+    else if (node.type === 'web' && interaction.trigger?.type === 'message') {
         await executeWebEdge(frame, node, {
             ...edge,
             owner: 'node',
@@ -277,19 +358,23 @@ async function executeNativeInteraction(frame, node, edge, contract) {
         return;
     }
     const interactionType = String(interaction.interactive?.type || '');
-    const resultValue = edge.trigger.type === 'result'
-        ? String(edge.trigger.value)
-        : edge.trigger.type === 'legacy'
-            ? String(edge.trigger.value) === 'true'
-                ? 'correct'
-                : String(edge.trigger.value) === 'partial'
-                    ? 'partial'
-                    : 'incorrect'
-            : 'incorrect';
     if (interactionType === 'score_settlement') {
-        await clickAction(frame, 'confirm-settlement');
+        await executeScoreSettlement(frame, interaction, edge);
         return;
     }
+    const legacy = edge.trigger.type === 'legacy' ? String(edge.trigger.value) : undefined;
+    const exactOption = legacy === undefined ? undefined : interaction.interactive?.options?.find((option) => String(option.id) === legacy);
+    const legacyResult = new Map([['true', 'correct'], ['correct', 'correct'], ['partial', 'partial'], ['false', 'incorrect'], ['incorrect', 'incorrect'], ['wrong', 'incorrect']]).get(legacy || '');
+    if (legacy !== undefined && !exactOption && !legacyResult
+        && !(legacy === 'all_clicked' && interaction.interactive?.collectMode?.mode === 'all')) {
+        throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `Unknown legacy interaction trigger: ${legacy}`);
+    }
+    if (exactOption && ['logic_chain', 'blank_fill', 'input_fill'].includes(interactionType)) {
+        throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `Exact option trigger is not a result for ${interactionType}`);
+    }
+    const resultValue = edge.trigger.type === 'result'
+        ? String(edge.trigger.value)
+        : legacyResult || 'incorrect';
     if (interactionType === 'logic_chain') {
         const ids = (interaction.interactive?.chainOptions || []).map((option) => String(option.id));
         const orderedIds = resultValue === 'correct' ? ids : [...ids].reverse();
@@ -339,12 +424,10 @@ async function executeNativeInteraction(frame, node, edge, contract) {
     else if (edge.trigger.type === 'result')
         optionIds = chooseResultOption(interaction, String(edge.trigger.value));
     else if (edge.trigger.type === 'legacy') {
-        const legacy = String(edge.trigger.value);
-        optionIds = legacy === 'true'
-            ? chooseResultOption(interaction, 'correct')
-            : legacy === 'partial'
-                ? chooseResultOption(interaction, 'partial')
-                : chooseResultOption(interaction, 'incorrect');
+        if (exactOption)
+            optionIds = [String(exactOption.id)];
+        else if (legacyResult)
+            optionIds = chooseResultOption(interaction, legacyResult);
     }
     if (interaction.interactive?.collectMode?.mode === 'all') {
         optionIds = (interaction.interactive?.options || []).map((option) => String(option.id));
@@ -378,11 +461,14 @@ async function executeNativeInteraction(frame, node, edge, contract) {
     }
     throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `No real DOM driver is available for ${edge.ownerId}:${edge.trigger.type}`);
 }
-async function executeEdge(frame, edge, options) {
+async function executeEdge(frame, edge, options, deadline) {
     const node = getNode(options.script, edge.from);
     await assertNodeMedia(frame, node);
     if (edge.owner === 'interaction') {
-        await executeNativeInteraction(frame, node, edge, options.contract);
+        await executeNativeInteraction(frame, node, edge, options.contract, deadline);
+    }
+    else if (node.type === 'avg' && (edge.trigger.type === 'complete' || edge.default)) {
+        await completeAvgPlayback(frame, edge.from, deadline);
     }
     else if (node.type === 'web' && (edge.trigger.type === 'message' || edge.default)) {
         await executeWebEdge(frame, node, edge, options.contract);
@@ -478,6 +564,18 @@ async function runScenario(browser, scenario, options) {
     await context.addInitScript(() => {
         const browserWindow = globalThis;
         browserWindow.__bvPlaytestObservedMessages = [];
+        browserWindow.__bvPlaytestStartupExceptions = [];
+        const recordStartupException = (reason) => {
+            const error = reason instanceof Error ? reason : undefined;
+            const message = error?.message || reason?.message || String(reason);
+            const stack = error?.stack || reason?.stack;
+            browserWindow.__bvPlaytestStartupExceptions.push(stack ? { message, stack } : { message });
+        };
+        browserWindow.addEventListener('error', (event) => {
+            if (event?.error instanceof Error || event?.message)
+                recordStartupException(event.error || event.message);
+        }, true);
+        browserWindow.addEventListener('unhandledrejection', (event) => recordStartupException(event.reason));
         browserWindow.addEventListener('message', (event) => {
             browserWindow.__bvPlaytestObservedMessages.push({ data: event.data, origin: event.origin, at: Date.now() });
         });
@@ -493,15 +591,19 @@ async function runScenario(browser, scenario, options) {
     }
     let timeoutHandle;
     const scenarioDeadline = Date.now() + options.limits.scenarioTimeoutMs;
+    let playerFrame;
+    let playerHandshakeComplete = false;
+    let activeEdge;
     const scenarioTimeout = new Promise((_, reject) => {
-        timeoutHandle = globalThis.setTimeout(() => reject(new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`)), options.limits.scenarioTimeoutMs);
+        timeoutHandle = globalThis.setTimeout(() => reject(new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`, activeEdge ? { edgeId: activeEdge.id, nodeId: activeEdge.from, nodeType: getNode(options.script, activeEdge.from).type } : undefined)), options.limits.scenarioTimeoutMs);
     });
     try {
         await Promise.race([(async () => {
                 await page.setContent('<!doctype html><html><body style="margin:0"><iframe title="BV playtest player" style="border:0;width:1280px;height:720px"></iframe></body></html>');
                 await page.locator('iframe[title="BV playtest player"]').evaluate((element, url) => { element.src = url; }, options.playerUrl);
-                const playerFrame = await waitForPlayerFrame(page, options.playerUrl, options.limits.scenarioTimeoutMs);
-                await assertPlayerProtocol(playerFrame, options.limits.scenarioTimeoutMs);
+                playerFrame = await waitForPlayerFrame(page, options.playerUrl, options.limits.scenarioTimeoutMs);
+                await assertPlayerProtocol(playerFrame, scenarioDeadline - Date.now());
+                playerHandshakeComplete = true;
                 const entryNodeId = String(options.script.graph?.entryNodeId || '');
                 const entryTimeout = scenarioDeadline - Date.now();
                 if (entryTimeout <= 0)
@@ -511,7 +613,8 @@ async function runScenario(browser, scenario, options) {
                 await assertNodeMedia(playerFrame, getNode(options.script, entryNodeId));
                 visitedNodes.push(String(options.script.graph?.entryNodeId || ''));
                 for (const edge of scenario.edges) {
-                    await executeEdge(playerFrame, edge, options);
+                    activeEdge = edge;
+                    await executeEdge(playerFrame, edge, options, scenarioDeadline);
                     coveredEdges.push(edge.id);
                     if (!edge.to.startsWith('@'))
                         visitedNodes.push(edge.to);
@@ -519,7 +622,14 @@ async function runScenario(browser, scenario, options) {
             })(), scenarioTimeout]);
     }
     catch (error) {
-        const failure = error instanceof PlaytestError ? error : new PlaytestError('SCENARIO_FAILED', error instanceof Error ? error.message : String(error));
+        let failure = error instanceof PlaytestError ? error : new PlaytestError('SCENARIO_FAILED', error instanceof Error ? error.message : String(error));
+        if (failure.code === 'SCENARIO_TIMEOUT' && playerFrame && !playerHandshakeComplete) {
+            const exceptions = await playerStartupExceptions(playerFrame);
+            if (exceptions.length)
+                failure = new PlaytestError('PLAYER_INIT_FAILED', 'Player raised an exception before the playtest handshake', { startupExceptions: exceptions });
+            else
+                failure = new PlaytestError('PLAYER_HANDSHAKE_TIMEOUT', 'Player did not expose the BV playtest protocol within the scenario budget');
+        }
         findings.push({ code: failure.code, message: failure.message, scenarioId: scenario.id, edgeId: scenario.targetEdgeId, details: failure.details });
         const screenshotPath = path.join(scenarioDir, 'failure.png');
         await page.screenshot({ path: screenshotPath, fullPage: true }).catch(() => undefined);

package/dist/playtest/scenarios.js

@@ -19,6 +19,10 @@ function compare(actual, op, expected) {
 function conditionMatches(condition, variables, inventory) {
     if (!condition)
         return true;
+    if (condition.type === 'settlement_score') {
+        const score = Number(variables[condition.variable] ?? 0);
+        return compare(Number.isFinite(score) ? score : 0, condition.op, condition.value);
+    }
     if (condition.type === 'variable' || condition.variable)
         return compare(variables[condition.variable], condition.op, condition.value);
     if (condition.type === 'inventory') {

package/dist/playtest/types.d.ts

@@ -81,6 +81,8 @@ export interface PlaytestEdge {
     actionType: string;
     action: Record<string, unknown>;
     default?: boolean;
+    unreachableReason?: string;
+    skippedReason?: string;
 }
 export interface PlaytestScenario {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindscraft/branch-video-agent-cli",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {