@mindscraft/branch-video-agent-cli 0.4.5 → 0.4.7

package/README.md

@@ -1,20 +1,20 @@
 # Branch Video Agent CLI
 
-`@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 发布。
+`@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 发布。
 
 ## 安装与执行
 
@@ -69,6 +69,8 @@ AI Gateway 生产媒体验收使用 `ai-gateway media-understand --raw`。P0 模
 
 搜索展开上限的数值不变；可安全去重的相同状态不重复计入，其他状态沿原搜索计数。
 
+实测范围不包含 Web 节点的 `branchConfig.defaultAction` 兜底分支，也不要求为仅落入该兜底的消息提供操作配方。业务脚本和兜底行为保持不变；显式消息分支（包括名为 `default` 的消息）、答对、答错及适用的超时仍须真实操作。仅通过豁免分支到达的节点不在本轮覆盖目标内；仍有正常路径可达的节点继续测试。JSON 报告以 `WEB_DEFAULT_NOT_TESTED` 逐边记录，JUnit 标为 `skipped`，不计作覆盖或通过；报告 `passed` 仅表示本轮要求实测的范围通过。该豁免不声称兜底不可达，也不影响其他类型的 default 校验。
+
 ```powershell
 @'
 {

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.js

@@ -98,7 +98,7 @@ 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',

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,108 @@ 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));
+}
+// Deliberately narrow: the image timer pauses at the first tick and every
+// settlement result leaves this node. Ordinary resumable interactions do not qualify.
+function settlementBlocksImageCompletion(nodeId, node, nodes) {
+    if (node.type !== 'image' || node.branchConfig || node.branches || node.events
+        || node.config?.events || node.config?.messageHandlers
+        || (node.config?.loop !== undefined && node.config.loop !== false)
+        || !Array.isArray(node.config?.slides) || node.config.slides.length !== 1
+        || !Array.isArray(node.interactions) || node.interactions.length !== 1)
+        return false;
+    const slide = node.config.slides[0];
+    if (!slide || typeof slide.id !== 'string' || !slide.id.trim()
+        || typeof slide.assetRef !== 'string' || !slide.assetRef.trim()
+        || (slide.duration !== undefined && (!Number.isFinite(slide.duration) || slide.duration < 0))
+        || (slide.duration || 3) <= 0.1)
+        return false;
+    const interaction = node.interactions[0];
+    if (!interaction || interaction.interactive?.type !== 'score_settlement'
+        || interaction.branchConfig || interaction.events
+        || (interaction.timeLimit !== undefined && (!Number.isFinite(interaction.timeLimit) || interaction.timeLimit > 0))
+        || !(interaction.trigger?.type === 'time' && interaction.trigger.value === 0
+            || interaction.trigger?.type === 'slide' && interaction.trigger.index === 0 && interaction.trigger.offsetSec === 0)
+        || !Array.isArray(interaction.branches))
+        return false;
+    const outcomes = settlementConditions(interaction.interactive);
+    if (!outcomes)
+        return false;
+    const leavesNode = (action) => action?.type === 'end'
+        || action?.type === 'goto' && typeof action.target === 'string'
+            && Boolean(nodes[action.target.trim()]) && action.target.trim() !== nodeId;
+    if (interaction.branches.some((branch) => !branch || branch.condition || !leavesNode(branch.then))
+        || [interaction.fallback?.onDefault, interaction.fallback?.onTimeout].some(action => action && !leavesNode(action)))
+        return false;
+    return [...outcomes.keys()].every(result => interaction.branches.some((branch) => (typeof branch.when === 'string' && branch.when.trim().toLowerCase() === result)));
 }
 export function extractPlaytestEdges(script) {
     const graph = script?.graph;
@@ -53,10 +141,22 @@ 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');
+        const mediaCompletion = node.type === 'video' || node.type === 'image' || node.type === 'avg';
+        if (mediaCompletion && !node.branchConfig && !avgCompletionInteraction) {
             addEdge(edges, nodeId, 'node', nodeId, { type: 'complete' }, node.config?.onComplete);
+            if (settlementBlocksImageCompletion(nodeId, node, nodes)) {
+                const completion = edges.at(-1);
+                if (completion?.from === nodeId && completion.owner === 'node' && completion.trigger.type === 'complete') {
+                    completion.unreachableReason = 'Immediate image settlement pauses completion and every result leaves the node';
+                }
+            }
         }
-        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, mediaCompletion ? '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 +171,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 +225,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 +233,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

@@ -1,5 +1,5 @@
-import { type Frame } from 'playwright';
-import type { PlaytestContract, PlaytestLimits, PlaytestScenario, PlaytestScenarioResult } from './types.js';
+import { type ElementHandle, type Frame } from 'playwright';
+import type { PlaytestContract, PlaytestEdge, PlaytestLimits, PlaytestScenario, PlaytestScenarioResult } from './types.js';
 type ScriptRecord = Record<string, any>;
 interface RunnerOptions {
     script: ScriptRecord;
@@ -15,7 +15,17 @@ interface RunnerOptions {
         height: number;
     };
 }
+interface VerifiedMedia {
+    element: ElementHandle;
+    source: string;
+    nodeId: string;
+}
 export declare function startPlayback(frame: Frame, entryNodeId: string, entryNodeType: string, timeout: number): Promise<void>;
+export declare function assertNodeMedia(frame: Frame, node: ScriptRecord, deadline: number): Promise<VerifiedMedia | undefined>;
+export declare function driveVerifiedVideo(media: VerifiedMedia | undefined, trigger: 'time' | 'complete' | 'complete-interaction', time?: number): Promise<void>;
+export declare function executeWebEdge(frame: Frame, node: ScriptRecord, edge: PlaytestEdge, contract: PlaytestContract, deadline: number): Promise<void>;
+export declare function completeAvgPlayback(frame: Frame, nodeId: string, deadline: number): Promise<void>;
+export declare function executeEdge(frame: Frame, edge: PlaytestEdge, options: RunnerOptions, 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

@@ -11,24 +11,31 @@ function locatorFor(frame, spec) {
         return frame.getByTestId(spec.testId);
     return frame.locator(spec.selector);
 }
-async function runWebStep(frame, step) {
+function remainingBudget(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new PlaytestError('SCENARIO_TIMEOUT', 'Scenario deadline elapsed');
+    return remaining;
+}
+async function runWebStep(frame, step, deadline) {
     const locator = locatorFor(frame, step.locator);
+    const timeout = remainingBudget(deadline);
     if (step.action === 'click')
-        await locator.click();
+        await locator.click({ timeout });
     else if (step.action === 'fill')
-        await locator.fill(step.value);
+        await locator.fill(step.value, { timeout });
     else if (step.action === 'selectOption')
-        await locator.selectOption(step.value);
+        await locator.selectOption(step.value, { timeout });
     else if (step.action === 'check')
-        await locator.setChecked(step.checked ?? true);
+        await locator.setChecked(step.checked ?? true, { timeout });
     else if (step.action === 'press')
-        await locator.press(step.key);
+        await locator.press(step.key, { timeout });
     else if (step.action === 'dragTo')
-        await locator.dragTo(locatorFor(frame, step.target));
+        await locator.dragTo(locatorFor(frame, step.target), { timeout });
     else if (step.action === 'setInputFiles')
-        await locator.setInputFiles(step.files);
+        await locator.setInputFiles(step.files, { timeout });
     else
-        await locator.waitFor({ state: step.state ?? 'visible', timeout: step.timeoutMs });
+        await locator.waitFor({ state: step.state ?? 'visible', timeout: step.timeoutMs && step.timeoutMs > 0 ? Math.min(step.timeoutMs, timeout) : timeout });
 }
 function appendInstrumentationQuery(rawUrl) {
     const url = new URL(rawUrl);
@@ -86,20 +93,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) {
@@ -137,42 +160,74 @@ export async function startPlayback(frame, entryNodeId, entryNodeType, timeout)
         }
     }
 }
-async function assertNodeMedia(frame, node) {
-    if (node.type === 'video') {
-        const video = frame.locator('video').first();
-        await video.waitFor({ state: 'visible' });
-        const state = await video.evaluate(async (element) => {
-            if (element.readyState < 1) {
-                await new Promise((resolve, reject) => {
-                    const timer = globalThis.setTimeout(() => reject(new Error('loadedmetadata timeout')), 10000);
-                    element.addEventListener('loadedmetadata', () => { globalThis.clearTimeout(timer); resolve(); }, { once: true });
-                    element.addEventListener('error', () => { globalThis.clearTimeout(timer); reject(new Error('video error')); }, { once: true });
-                });
-            }
-            const before = element.currentTime;
-            await element.play().catch(() => undefined);
-            await new Promise((resolve) => globalThis.setTimeout(resolve, 200));
-            return { readyState: element.readyState, duration: element.duration, progressed: element.currentTime > before };
-        });
-        if (state.readyState < 1 || !Number.isFinite(state.duration)) {
-            throw new PlaytestError('MEDIA_LOAD_FAILED', `Video media failed on node ${node.id}`, state);
-        }
-    }
-    if (node.type === 'image') {
-        const image = frame.locator('img').filter({ visible: true }).first();
-        await image.waitFor({ state: 'visible' });
-        const loaded = await image.evaluate((element) => element.complete && element.naturalWidth > 0);
-        if (!loaded)
-            throw new PlaytestError('MEDIA_LOAD_FAILED', `Image media failed on node ${node.id}`);
+function mainMedia(frame, node) {
+    return frame.locator(`[data-bv-media-role="main"][data-bv-media-node-id=${JSON.stringify(node.id)}]`);
+}
+export async function assertNodeMedia(frame, node, deadline) {
+    if (node.type === 'video' || node.type === 'image') {
+        const media = mainMedia(frame, node);
+        await media.waitFor({ state: 'visible', timeout: remainingBudget(deadline) });
+        const element = await media.elementHandle({ timeout: remainingBudget(deadline) });
+        if (!element)
+            throw new PlaytestError('NODE_MEDIA_CHANGED', `Main media disappeared on ${node.id}`);
+        const state = await element.evaluate(async (element, input) => {
+            const end = Date.now() + input.timeout;
+            const source = element.src;
+            do {
+                const current = globalThis.document.querySelector('[data-bv-node-id]')?.getAttribute('data-bv-node-id');
+                if (!element.isConnected || current !== input.nodeId || element.src !== source
+                    || element.getAttribute('data-bv-media-node-id') !== input.nodeId)
+                    return { status: 'changed', current };
+                if (input.type === 'image') {
+                    if (element.complete)
+                        return { status: element.naturalWidth > 0 ? 'loaded' : 'error', source };
+                }
+                else {
+                    if (element.error)
+                        return { status: 'error', error: element.error.code };
+                    if (element.readyState >= 2 && Number.isFinite(element.duration) && element.currentSrc === source)
+                        return { status: 'loaded', source };
+                }
+                await new Promise(resolve => globalThis.setTimeout(resolve, Math.min(50, Math.max(1, end - Date.now()))));
+            } while (Date.now() < end);
+            return { status: 'timeout', readyState: element.readyState, source };
+        }, { nodeId: node.id, type: node.type, timeout: remainingBudget(deadline) });
+        if (state.status === 'changed')
+            throw new PlaytestError('NODE_MEDIA_CHANGED', `Node or media source changed while loading ${node.id}`, state);
+        if (state.status !== 'loaded')
+            throw new PlaytestError('MEDIA_LOAD_FAILED', `Main ${node.type} media failed on node ${node.id}`, state);
+        return { element, source: state.source, nodeId: node.id };
     }
     if (node.type === 'web') {
-        await frame.locator('iframe[title="Web 页面"]').waitFor({ state: 'visible' });
+        await frame.locator('iframe[title="Web 页面"]').waitFor({ state: 'visible', timeout: remainingBudget(deadline) });
     }
 }
+export async function driveVerifiedVideo(media, trigger, time) {
+    if (!media)
+        throw new PlaytestError('NODE_MEDIA_CHANGED', 'Video was not verified before driving it');
+    const valid = await media.element.evaluate((element, input) => {
+        const current = globalThis.document.querySelector('[data-bv-node-id]')?.getAttribute('data-bv-node-id');
+        if (!element.isConnected || current !== input.nodeId || element.getAttribute('data-bv-media-node-id') !== input.nodeId
+            || element.src !== input.source || element.currentSrc !== input.source || element.readyState < 2 || element.error
+            || !Number.isFinite(element.duration))
+            return false;
+        if (input.trigger === 'time')
+            element.currentTime = Number(input.time) + 0.05;
+        else if (input.trigger === 'complete' && element.duration > 0)
+            element.currentTime = Math.max(0, element.duration - 0.01);
+        if (input.trigger !== 'complete-interaction')
+            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
+        if (input.trigger !== 'time')
+            element.dispatchEvent(new globalThis.Event('ended', { bubbles: true }));
+        return true;
+    }, { source: media.source, nodeId: media.nodeId, trigger, time });
+    if (!valid)
+        throw new PlaytestError('NODE_MEDIA_CHANGED', `Verified video changed before driving ${media.nodeId}`);
+}
 async function readObservedMessages(frame) {
     return frame.evaluate(() => globalThis.__bvPlaytestObservedMessages || []).catch(() => []);
 }
-async function executeWebEdge(frame, node, edge, contract) {
+export async function executeWebEdge(frame, node, edge, contract, deadline) {
     const explicitRoutes = new Set((node.branchConfig?.rules || [])
         .filter((rule) => rule.trigger?.type === 'message')
         .map((rule) => String(rule.trigger.value)));
@@ -181,19 +236,44 @@ async function executeWebEdge(frame, node, edge, contract) {
         : contract.webResults.find((candidate) => candidate.nodeId === edge.from && !explicitRoutes.has(candidate.routeValue));
     if (!recipe)
         throw new PlaytestError('WEB_PLAYTEST_RECIPE_MISSING', `No recipe for ${edge.from}:${String(edge.trigger.value)}`);
-    const webFrame = frame.childFrames().find((candidate) => candidate.url() !== 'about:blank');
+    const handle = await frame.locator('iframe[title="Web 页面"]').elementHandle({ timeout: remainingBudget(deadline) });
+    const webFrame = await handle?.contentFrame();
     if (!webFrame)
         throw new PlaytestError('WEB_FRAME_LOAD_FAILED', `Web iframe did not load on node ${edge.from}`);
+    const sourceId = await handle.evaluate((element) => {
+        const browserWindow = globalThis;
+        browserWindow.__bvPlaytestWebSources ||= new WeakMap();
+        const id = (browserWindow.__bvPlaytestWebSourceSequence || 0) + 1;
+        browserWindow.__bvPlaytestWebSourceSequence = id;
+        browserWindow.__bvPlaytestWebSources.set(element.contentWindow, id);
+        return id;
+    });
     const before = (await readObservedMessages(frame)).length;
-    for (const step of recipe.steps)
-        await runWebStep(webFrame, step);
+    for (let index = 0; index < recipe.steps.length; index += 1) {
+        const step = recipe.steps[index];
+        try {
+            await runWebStep(webFrame, step, deadline);
+        }
+        catch (error) {
+            // A final passive wait may lose its iframe when the real result navigates.
+            // Missing actions, wrong/stale messages and unrelated detach remain failures.
+            const message = error instanceof Error ? error.message : String(error);
+            const emitted = (await readObservedMessages(frame)).slice(before);
+            if (!(index === recipe.steps.length - 1 && step.action === 'waitFor'
+                && /frame.*detach/i.test(message) && webFrame.isDetached()
+                && emitted.some(entry => entry.sourceId === sourceId && matchesRawMessage(entry, recipe.rawMessage))))
+                throw error;
+        }
+    }
     try {
         await frame.waitForFunction((payload) => {
-            const { start, rawMessage } = payload;
+            const { start, rawMessage, sourceId } = payload;
             const messages = (globalThis.__bvPlaytestObservedMessages || []).slice(start);
             const expectedEvent = rawMessage.eventName;
             const expectedValue = rawMessage.value ?? rawMessage.data?.value ?? rawMessage.data;
             return messages.some((entry) => {
+                if (entry.sourceId !== sourceId)
+                    return false;
                 const actual = entry.data;
                 const eventName = actual?.eventName ?? actual?.type ?? actual?.event;
                 const value = actual?.value
@@ -207,14 +287,14 @@ async function executeWebEdge(frame, node, edge, contract) {
                 const comparableExpected = typeof expectedValue === 'string' || typeof expectedValue === 'number' ? String(expectedValue) : expectedValue;
                 return eventName === expectedEvent && JSON.stringify(comparableActual) === JSON.stringify(comparableExpected);
             });
-        }, { start: before, rawMessage: recipe.rawMessage }, { timeout: 10000 });
+        }, { start: before, rawMessage: recipe.rawMessage, sourceId }, { timeout: remainingBudget(deadline) });
     }
     catch {
         const observed = (await readObservedMessages(frame)).slice(before);
         throw new PlaytestError('WEB_MESSAGE_NOT_EMITTED', `Web actions did not emit the expected raw message for ${edge.from}:${recipe.routeValue}`, { observed });
     }
     const emitted = (await readObservedMessages(frame)).slice(before);
-    if (!emitted.some((message) => matchesRawMessage(message, recipe.rawMessage))) {
+    if (!emitted.some((message) => message.sourceId === sourceId && matchesRawMessage(message, recipe.rawMessage))) {
         throw new PlaytestError('WEB_MESSAGE_NOT_EMITTED', `Expected Web raw message was not recorded for ${edge.from}:${recipe.routeValue}`);
     }
 }
@@ -237,66 +317,137 @@ function chooseResultOption(interaction, result) {
     }
     return wrong.length ? [wrong[0]] : options.slice(-1).map((option) => String(option.id));
 }
-async function clickAction(frame, action) {
+async function clickAction(frame, action, deadline) {
     const control = frame.locator(`[data-bv-action="${action}"]`).first();
     const nestedButton = control.locator('button').first();
     if (await nestedButton.count())
-        await nestedButton.click();
+        await nestedButton.click({ timeout: remainingBudget(deadline) });
     else
-        await control.click();
+        await control.click({ timeout: remainingBudget(deadline) });
+}
+function normalizeSettlementResult(value) {
+    return String(value ?? '').trim().toLowerCase();
+}
+async function executeScoreSettlement(frame, interaction, edge, deadline) {
+    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', deadline);
+        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', deadline);
+}
+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;
+            try {
+                await next.click({ timeout: Math.min(5000, remaining) });
+            }
+            catch (error) {
+                throw new PlaytestError('AVG_NEXT_CONTROL_BLOCKED', `AVG next control is not clickable on ${nodeId}`, {
+                    nodeId, step: state.step, cause: error instanceof Error ? error.message : String(error),
+                });
+            }
+            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) {
+async function executeNativeInteraction(frame, node, edge, contract, deadline, media) {
     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',
             ownerId: node.id,
             trigger: { type: 'message', value: interaction.trigger.value },
-        }, contract);
+        }, contract, deadline);
     }
     else if (interaction.trigger?.type === 'time' && node.type === 'video') {
-        await frame.locator('video').first().evaluate((element, time) => {
-            element.currentTime = time + 0.05;
-            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
-        }, Number(interaction.trigger.value || 0));
+        await driveVerifiedVideo(media, 'time', Number(interaction.trigger.value || 0));
     }
     else if (interaction.trigger?.type === 'time' && Number(interaction.trigger.value || 0) > 0) {
         await frame.page().waitForTimeout(Number(interaction.trigger.value) * 1000 + 50);
     }
     else if (interaction.trigger?.type === 'complete' && node.type === 'video') {
-        await frame.locator('video').first().evaluate((element) => {
-            element.dispatchEvent(new globalThis.Event('ended', { bubbles: true }));
-        });
+        await driveVerifiedVideo(media, 'complete-interaction');
     }
-    await frame.locator(`[data-bv-interaction-id="${edge.ownerId}"]`).waitFor({ state: 'attached' });
+    await frame.locator(`[data-bv-interaction-id="${edge.ownerId}"]`).waitFor({ state: 'attached', timeout: remainingBudget(deadline) });
     if (edge.trigger.type === 'timeout') {
         await frame.page().waitForTimeout((Number(interaction.timeLimit || 0) + 2.5) * 1000);
         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, deadline);
         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();
         for (const optionId of orderedIds) {
-            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().click();
+            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().click({ timeout: remainingBudget(deadline) });
         }
-        await clickAction(frame, 'submit');
+        await clickAction(frame, 'submit', deadline);
         return;
     }
     if (interactionType === 'blank_fill') {
@@ -307,9 +458,9 @@ async function executeNativeInteraction(frame, node, edge, contract) {
             const correctId = String(blank.correctOptionId || '');
             const wrongId = String(options.find((option) => String(option.id) !== correctId)?.id || correctId);
             const optionId = resultValue === 'incorrect' || (resultValue === 'partial' && index > 0) ? wrongId : correctId;
-            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().dragTo(frame.locator(`[data-bv-blank-id="${blank.id}"]`));
+            await frame.locator(`[data-bv-option-id="${optionId}"]`).first().dragTo(frame.locator(`[data-bv-blank-id="${blank.id}"]`), { timeout: remainingBudget(deadline) });
         }
-        await clickAction(frame, 'submit');
+        await clickAction(frame, 'submit', deadline);
         return;
     }
     if (interactionType === 'input_fill') {
@@ -320,15 +471,15 @@ async function executeNativeInteraction(frame, node, edge, contract) {
             const answer = shouldBeWrong ? '__wrong__' : (blank.correctAnswers?.[0] ?? 'playtest');
             const control = frame.locator(`[data-bv-blank-id="${blank.id}"]`);
             if (blank.type === 'number') {
-                await control.click();
+                await control.click({ timeout: remainingBudget(deadline) });
                 for (const key of String(answer))
-                    await control.press(key);
+                    await control.press(key, { timeout: remainingBudget(deadline) });
             }
             else {
-                await control.fill(String(answer));
+                await control.fill(String(answer), { timeout: remainingBudget(deadline) });
             }
         }
-        await clickAction(frame, 'submit');
+        await clickAction(frame, 'submit', deadline);
         return;
     }
     let optionIds = [];
@@ -339,12 +490,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));
@@ -353,17 +502,17 @@ async function executeNativeInteraction(frame, node, edge, contract) {
         for (const optionId of optionIds) {
             const option = frame.locator(`[data-bv-option-id="${optionId}"]`);
             if (await option.count())
-                await option.first().click();
+                await option.first().click({ timeout: remainingBudget(deadline) });
             else {
                 const optionText = interaction.interactive?.options?.find((candidate) => String(candidate.id) === optionId)?.text;
                 if (!optionText)
                     throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `No real control for option ${optionId} in interaction ${edge.ownerId}`);
-                await frame.getByText(String(optionText), { exact: true }).click();
+                await frame.getByText(String(optionText), { exact: true }).click({ timeout: remainingBudget(deadline) });
             }
         }
         const submit = frame.locator('[data-bv-action="submit"]');
         if (await submit.isVisible().catch(() => false))
-            await clickAction(frame, 'submit');
+            await clickAction(frame, 'submit', deadline);
         return;
     }
     const inputs = frame.locator(`[data-bv-interaction-id="${edge.ownerId}"] input`);
@@ -371,62 +520,81 @@ async function executeNativeInteraction(frame, node, edge, contract) {
         const blanks = interaction.interactive?.blanks || [];
         for (let index = 0; index < await inputs.count(); index += 1) {
             const answer = blanks[index]?.correctAnswers?.[0] ?? blanks[index]?.answer ?? blanks[index]?.correctAnswer ?? blanks[index]?.answers?.[0] ?? 'playtest';
-            await inputs.nth(index).fill(String(edge.trigger.value === 'incorrect' ? '__wrong__' : answer));
+            await inputs.nth(index).fill(String(edge.trigger.value === 'incorrect' ? '__wrong__' : answer), { timeout: remainingBudget(deadline) });
         }
-        await clickAction(frame, 'submit');
+        await clickAction(frame, 'submit', deadline);
         return;
     }
     throw new PlaytestError('INTERACTION_DRIVER_UNSUPPORTED', `No real DOM driver is available for ${edge.ownerId}:${edge.trigger.type}`);
 }
-async function executeEdge(frame, edge, options) {
+export async function executeEdge(frame, edge, options, deadline) {
     const node = getNode(options.script, edge.from);
-    await assertNodeMedia(frame, node);
+    const media = await assertNodeMedia(frame, node, deadline);
+    const sameNode = edge.from === edge.to && edge.actionType !== 'end';
+    let beforeSequence = 0;
+    if (sameNode) {
+        if (node.type !== 'video' || !media || !['loop', 'goto'].includes(edge.actionType)
+            || await media.element.getAttribute('data-bv-video-action-protocol') !== '1') {
+            throw new PlaytestError('EDGE_EFFECT_OBSERVATION_UNSUPPORTED', `No reliable same-node effect observation for ${edge.id}`);
+        }
+        beforeSequence = Number(await media.element.getAttribute('data-bv-video-action-sequence') || 0);
+    }
     if (edge.owner === 'interaction') {
-        await executeNativeInteraction(frame, node, edge, options.contract);
+        await executeNativeInteraction(frame, node, edge, options.contract, deadline, media);
+    }
+    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);
+        await executeWebEdge(frame, node, edge, options.contract, deadline);
     }
     else if (node.type === 'video' && edge.trigger.type === 'time') {
-        await frame.locator('video').first().evaluate((element, time) => {
-            element.currentTime = time + 0.05;
-            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
-        }, Number(edge.trigger.value));
+        await driveVerifiedVideo(media, 'time', Number(edge.trigger.value));
     }
     else if (node.type === 'video' && edge.trigger.type === 'complete') {
-        await frame.locator('video').first().evaluate((element) => {
-            if (Number.isFinite(element.duration) && element.duration > 0)
-                element.currentTime = Math.max(0, element.duration - 0.01);
-            element.dispatchEvent(new globalThis.Event('timeupdate', { bubbles: true }));
-            element.dispatchEvent(new globalThis.Event('ended', { bubbles: true }));
-        });
+        await driveVerifiedVideo(media, 'complete');
     }
     else if (edge.trigger.type === 'enter') {
         // Start/enter transitions are produced by the runtime itself.
     }
     else if (node.type === 'image' && edge.trigger.type === 'complete') {
         const durationMs = (node.config?.slides || []).reduce((sum, slide) => sum + Number(slide.duration || 0) * 1000, 0);
-        await frame.page().waitForTimeout(Math.min(durationMs + 250, options.limits.scenarioTimeoutMs / 2));
+        await frame.page().waitForTimeout(Math.min(durationMs + 250, remainingBudget(deadline)));
     }
     else {
         throw new PlaytestError('EDGE_DRIVER_UNSUPPORTED', `No real runtime driver for edge ${edge.id}`);
     }
-    if (edge.actionType === 'end') {
+    if (sameNode) {
+        const segment = edge.action.segment;
+        const time = edge.actionType === 'loop' ? segment?.start ?? 0
+            : typeof edge.action.time === 'number' && edge.action.time >= 0 ? edge.action.time : 0;
+        const end = edge.actionType === 'loop' ? segment?.end ?? await media.element.evaluate((video) => video.duration) : undefined;
         try {
-            await frame.waitForFunction(() => (globalThis.document.querySelector('[data-bv-ended]')?.getAttribute('data-bv-ended') === 'true'), undefined, { timeout: Math.min(10000, options.limits.scenarioTimeoutMs) });
+            await frame.waitForFunction(({ element, sequence, nodeId, type, time, end, source }) => {
+                if (!element?.isConnected || element.src !== source || element.currentSrc !== source || element.error
+                    || element.getAttribute('data-bv-media-node-id') !== nodeId
+                    || globalThis.document.querySelector('[data-bv-node-id]')?.getAttribute('data-bv-node-id') !== nodeId
+                    || Number(element.getAttribute('data-bv-video-action-sequence') || 0) <= sequence)
+                    return false;
+                const action = JSON.parse(element.getAttribute('data-bv-video-action') || 'null');
+                return action?.nodeId === nodeId && action.type === type && action.time === time && action.end === end
+                    && Number.isFinite(action.position) && Math.abs(action.position - time) <= 0.5;
+            }, { element: media.element, sequence: beforeSequence, nodeId: edge.from, type: edge.actionType, time, end, source: media.source }, { timeout: remainingBudget(deadline) });
         }
         catch {
-            throw new PlaytestError('ROUTE_TARGET_MISMATCH', `Edge ${edge.id} did not reach the ended state`);
+            throw new PlaytestError('SAME_NODE_EFFECT_NOT_OBSERVED', `No new matching runtime action receipt for ${edge.id}`);
         }
     }
-    else if (edge.actionType === 'seek' && node.type === 'video' && Number.isFinite(Number(edge.action.time))) {
-        await frame.waitForFunction((expectedTime) => {
-            const video = globalThis.document.querySelector('video');
-            return video && Math.abs(Number(video.currentTime) - Number(expectedTime)) < 0.5;
-        }, Number(edge.action.time), { timeout: Math.min(10000, options.limits.scenarioTimeoutMs) });
+    else if (edge.actionType === 'end') {
+        try {
+            await frame.waitForFunction(() => (globalThis.document.querySelector('[data-bv-ended]')?.getAttribute('data-bv-ended') === 'true'), undefined, { timeout: remainingBudget(deadline) });
+        }
+        catch {
+            throw new PlaytestError('ROUTE_TARGET_MISMATCH', `Edge ${edge.id} did not reach the ended state`);
+        }
     }
     else {
-        await waitForNode(frame, edge.to, Math.min(10000, options.limits.scenarioTimeoutMs));
+        await waitForNode(frame, edge.to, remainingBudget(deadline));
     }
 }
 async function createContext(browser, options, scenarioDir) {
@@ -478,8 +646,23 @@ 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() });
+            browserWindow.__bvPlaytestObservedMessages.push({
+                data: event.data, origin: event.origin, at: Date.now(),
+                sourceId: event.source ? browserWindow.__bvPlaytestWebSources?.get(event.source) : undefined,
+            });
         });
     });
     await context.tracing.start({ screenshots: true, snapshots: true, sources: true });
@@ -493,25 +676,30 @@ 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)
                     throw new PlaytestError('SCENARIO_TIMEOUT', `Scenario ${scenario.id} exceeded ${options.limits.scenarioTimeoutMs}ms`);
                 await startPlayback(playerFrame, entryNodeId, String(getNode(options.script, entryNodeId).type || ''), entryTimeout);
                 playerReady = true;
-                await assertNodeMedia(playerFrame, getNode(options.script, entryNodeId));
+                await assertNodeMedia(playerFrame, getNode(options.script, entryNodeId), scenarioDeadline);
                 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,8 +707,16 @@ 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));
-        findings.push({ code: failure.code, message: failure.message, scenarioId: scenario.id, edgeId: scenario.targetEdgeId, details: failure.details });
+        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: activeEdge?.id || scenario.targetEdgeId,
+            details: activeEdge ? { ...(failure.details || {}), targetEdgeId: scenario.targetEdgeId } : failure.details });
         const screenshotPath = path.join(scenarioDir, 'failure.png');
         await page.screenshot({ path: screenshotPath, fullPage: true }).catch(() => undefined);
         artifacts.screenshot = screenshotPath;

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') {
@@ -42,6 +46,9 @@ function conditionMatches(condition, variables, inventory) {
 function applyEffects(state, edge, targetNode) {
     const variables = { ...state.variables };
     const inventory = { items: { ...state.inventory.items }, cards: { ...state.inventory.cards } };
+    // Same-node replay/media actions do not rerun entry effects; rule effects still run.
+    if (edge.from === edge.to && ['loop', 'seek', 'segment', 'goto'].includes(edge.actionType))
+        targetNode = undefined;
     const variableActions = [...(edge.variableActions || []), ...(targetNode?.variableActions || [])];
     for (const action of variableActions) {
         const current = variables[action.variable];

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.5",
+  "version": "0.4.7",
   "description": "Published CLI for branch-video and AIHub agent APIs.",
   "type": "module",
   "bin": {