@hoplogic/hopjit 0.1.0

package/dist/engine.js

@@ -0,0 +1,1792 @@
+// @module: exec-engine ^anc-struct-exec-engine
+import { randomUUID } from 'node:crypto';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseSpec } from './parser.js';
+import { validateSpec, validateOutputValues, formatSchemaMismatch } from './validator.js';
+import { VariableStore, getWriteScope, isTerminalStatus } from './ast-runtime.js';
+import { dfsNextStep, collectParallelBatch, propagateCompletion, collectDescendants, } from './engine-traverse.js';
+import { FilePersistence, MemoryPersistence, writeChildParams, readChildParams, stateExists, readState } from './persistence.js';
+import { HopLog, timestamp } from './hoplog.js';
+import { resolveDocRefs, formatDocRefContext, DocRefError } from './doc-ref.js';
+import { getParentStepId } from './ast-helpers.js';
+import { PromptAssembler, formatPromptText, formatParallelPromptText, formatHumanContext } from './prompt.js';
+import { hasChildren, getChildren, DEFLATE_THRESHOLD, isUpdateModeOutput } from './ast-helpers.js';
+import { ErrorCode } from './errors.js';
+import { bodyHasToolCall } from './act-body-parser.js';
+import { BodyInterpreter } from './act-body-interpreter.js';
+// confirm 拒绝类决策值（小写匹配）→ failStep。见 ^anc-exec-confirm-answer
+const CONFIRM_REJECT_VALUES = new Set(['reject', 'rejected', 'deny', 'denied', 'no']);
+// 哑 ToolProvider：引擎消化纯计算 body 时用——无工具 body 不会调 execute（bodyHasToolCall 已保证）；
+// 若误调说明 isCallerActionPoint 判定漏了工具，抛错暴露 bug。见 ^anc-exec-advance-to-caller
+const ENGINE_NOOP_TOOL_PROVIDER = {
+    list: () => [],
+    execute: async (name) => {
+        throw new Error(`TOOL_EXEC_ERROR: 引擎消化纯计算 body 不应调工具 "${name}"——isCallerActionPoint 判定遗漏`);
+    },
+};
+/** HopJIT 执行状态机——驱动 HopSpec 从初始化到终态，管理步骤状态机/树状变量作用域/retry-adaptive 配额/None 传播。见 [[exec-engine#^anc-struct-exec-engine]] */
+export class ExecutionEngine {
+    instanceId = '';
+    spec = null;
+    hostConfig = null;
+    stepStates = new Map();
+    variables = new VariableStore();
+    loopCounters = new Map();
+    retryCounters = new Map();
+    retryHistory = new Map();
+    replanCounters = new Map();
+    lastReplanChildren = new Map();
+    adaptiveNeededSubtask = null;
+    execEvents = [];
+    stepFailReasons = new Map();
+    stateDir = null;
+    instanceDir = null;
+    persistence = null;
+    logDir = null;
+    hoplog = null;
+    canFanout = false; // @a: anc-exec-parallel-canfanout — 顶层 true / worker 子实例 false。持久化进 StateFile
+    subtreeRoot = null; // @a: anc-exec-parallel-subinstance — worker 子实例执行 scope 收窄到的 child 子树根
+    specPath = null; // spec 文件路径（CLI 传入，parallel prompt 组装用）
+    cliAbsPath = null; // CLI 入口绝对路径
+    // fan-out CLI 调度顾问：parallel_step_id → 已派发 child_step_id 列表。CLI 派发即原子记入（防重复派发）。
+    // 见 design/parallel-execution.md ^anc-exec-parallel-fanout-advisor。// @a: anc-exec-parallel-fanout-advisor
+    dispatched = new Map();
+    joinStartedAt = null; // join 单进程内瞬态：进入 joinParallel 的时刻，join 块 started_at（不持久化）
+    // fan-out 窗口上限，跨进程持久化（host_context 不含 resource_limits，load 后 hostConfig 丢失窗口值）。
+    maxConcurrent = null;
+    forEachWorkerIdx = null; // for-each worker 在列表中的序号（itemVar 自播种用）
+    contextMode = 'full'; // @a: anc-exec-context-mode — context 精简档；run 时定、持久化，env 可覆盖
+    initExecution(specMarkdown, hostConfig, options) {
+        const { ast, errors: parseErrors } = parseSpec(specMarkdown);
+        if (parseErrors.length > 0) {
+            return { status: 'error', errors: parseErrors };
+        }
+        // P15 doc-ref 静态校验需 workspace + sandbox（hostConfig 提供）。// @a: anc-rule-p15
+        const validationErrors = validateSpec(ast, hostConfig.workspace_dir ? { workspace_dir: hostConfig.workspace_dir, sandbox: hostConfig.sandbox } : undefined);
+        const fatalErrors = validationErrors.filter((e) => e.severity === 'error');
+        if (fatalErrors.length > 0) {
+            return { status: 'error', errors: fatalErrors };
+        }
+        // warn 级不阻断，透传到 InitSuccess.warnings（警告被吞掉等于不存在）
+        const warnings = validationErrors.filter((e) => e.severity === 'warn');
+        this.spec = ast;
+        this.hostConfig = hostConfig;
+        this.canFanout = options?.canFanout ?? false;
+        this.subtreeRoot = options?.subtreeRoot ?? null;
+        this.specPath = options?.specPath ?? null;
+        this.cliAbsPath = options?.cliAbsPath ?? null;
+        this.contextMode = options?.contextMode ?? 'full';
+        // call 子实例用 callStepId 作 instanceId（落 .hopstate/<parent>/calls/<callStepId>/）；否则随机 UUID
+        this.instanceId = options?.callStepId ?? randomUUID();
+        this.setSubtreePending(ast.steps ?? []);
+        // parallel worker 子实例：scope 收窄到 child 子树（子树外预标 skipped）
+        if (this.subtreeRoot) {
+            this.executeSubtreeOnly(this.subtreeRoot, ast.steps ?? []);
+        }
+        const inputs = {};
+        if (ast.header.inputs) {
+            for (const decl of ast.header.inputs) {
+                inputs[decl.name] = decl.default ?? undefined;
+            }
+        }
+        // params 实参覆盖 Inputs 声明的 default（在此注入，确保随下方 persist 一并落盘）
+        if (options?.params) {
+            for (const [k, v] of Object.entries(options.params)) {
+                inputs[k] = v;
+            }
+        }
+        // for-each worker itemVar：引擎单一权威，fan-out 落盘 + worker init 按 cid 回填（driver 零参与）。
+        // 若 itemVar 不在 --params（显式覆盖，优先），从本 worker instance 目录 params.json 回填引擎备好的真值。
+        // 回填只读自己那份（cid 定位），不翻父/兄弟 vars。回填源缺失 → 响亮失败，而非静默错值。
+        // 见 design/parallel-execution.md §9e ^anc-exec-parallel-foreach-worker。// @a: anc-exec-parallel-foreach-worker
+        if (this.subtreeRoot) {
+            const parentId = getParentStepId(this.subtreeRoot);
+            const parentParallel = parentId ? this.findStepById(parentId, ast.steps ?? []) : null;
+            const forEach = parentParallel?.forEach;
+            if (forEach && !(forEach.itemVar in inputs)) {
+                // 按 cid 回填：worker instance 目录 = <stateDir>/<cid>（cli 已把 stateDir 解析到 <parent>/parallel）。
+                // 该目录由父引擎 fan-out 时 writeChildParams 创建并写入 params.json。
+                const childParams = options?.stateDir
+                    ? readChildParams(join(options.stateDir, this.instanceId)) : null;
+                if (childParams) {
+                    for (const [k, v] of Object.entries(childParams)) {
+                        if (!(k in inputs))
+                            inputs[k] = v; // 显式 --params 键优先，不覆盖
+                    }
+                }
+                if (!(forEach.itemVar in inputs)) {
+                    return { status: 'error', errors: [{
+                                kind: 'validate', rule: 'MISSING_INPUT', severity: 'error',
+                                message: `for-each worker '${this.subtreeRoot}' 缺 itemVar '${forEach.itemVar}'——引擎未按 cid 备料 params_for_child（fan-out 落盘缺失或 worker 被手工错启动，见 ^anc-exec-parallel-foreach-worker）`,
+                            }] };
+                }
+            }
+        }
+        inputs['instance_id'] = this.instanceId;
+        inputs['parent_instance_id'] = options?.parentInstanceId;
+        this.variables = new VariableStore(inputs);
+        if (options?.logDir) {
+            this.logDir = options.logDir;
+            this.hoplog = new HopLog({
+                specId: ast.header.id ?? 'unnamed',
+                logDir: options.logDir,
+                level: options.logLevel,
+                title: ast.header.title,
+                goal: ast.header.goal ?? '',
+                inputs: inputs,
+                traceId: options.traceId ?? this.instanceId, // 顶层用 instanceId,worker 继承父的 instanceId → 父子 trace_id 一致
+            });
+        }
+        // Persistence: explicit provider > stateDir→FilePersistence > MemoryPersistence (standalone default)
+        if (options?.persistence) {
+            this.persistence = options.persistence;
+        }
+        else if (options?.stateDir) {
+            this.stateDir = options.stateDir;
+            this.persistence = new FilePersistence(options.stateDir);
+        }
+        else {
+            this.persistence = new MemoryPersistence();
+        }
+        this.persistence.init(this.instanceId, ast);
+        if (this.persistence instanceof FilePersistence) {
+            this.instanceDir = this.persistence.getInstanceDir();
+        }
+        this.persist();
+        return {
+            status: 'ok',
+            instance_id: this.instanceId,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    getSpec() { return this.spec; }
+    getInstanceId() { return this.instanceId; }
+    getStepStates() { return this.stepStates; }
+    getVariableStore() { return this.variables; }
+    getExecEvents() { return this.execEvents; }
+    getLoopCounters() { return this.loopCounters; }
+    getHopLog() { return this.hoplog; }
+    setCanFanout(on) { this.canFanout = on; }
+    getCanFanout() { return this.canFanout; }
+    getSubtreeRoot() { return this.subtreeRoot; }
+    setContextMode(mode) { this.contextMode = mode; } // env 覆盖用
+    getContextMode() { return this.contextMode; } // @a: anc-exec-context-mode
+    // minimal 且非首步（已有 step done/failed）→ 砍 L1 静态段 + L2 spec 级。见 ^anc-exec-context-mode
+    isMinimalNonFirst() {
+        if (this.contextMode !== 'minimal')
+            return false;
+        return [...this.stepStates.values()].some(s => s === 'done' || s === 'failed');
+    }
+    getInstanceDir() { return this.instanceDir; }
+    getHopLogRunDir() { return this.hoplog?.getRunDir() ?? null; }
+    /** 顶层步骤是否全部终态（done/failed/skipped）。终态判据单点复用 isTerminalStatus。 */
+    allTopLevelTerminal(steps) {
+        return steps.every(s => isTerminalStatus(this.stepStates.get(s.step_id)));
+    }
+    nextStep() {
+        if (!this.spec) {
+            return {
+                status: 'failed',
+                instance_id: this.instanceId,
+                failed_step_id: '',
+                failure_reason: 'Engine not initialized',
+                partial_outputs: {},
+                work_zone: this.getWorkZone(),
+            };
+        }
+        const steps = this.spec.steps ?? [];
+        const allTerminal = this.allTopLevelTerminal(steps);
+        if (allTerminal) {
+            const hasFailed = this.findFirstFailedStep(steps);
+            if (hasFailed) {
+                this.hoplog?.close('failed');
+                return {
+                    status: 'failed',
+                    instance_id: this.instanceId,
+                    failed_step_id: hasFailed.step_id,
+                    failure_reason: this.getFailureReason(hasFailed.step_id),
+                    partial_outputs: this.deflateValues(this.collectOutputs()),
+                    work_zone: this.getWorkZone(),
+                };
+            }
+            this.hoplog?.close('completed');
+            return {
+                status: 'completed',
+                instance_id: this.instanceId,
+                outputs: this.deflateValues(this.collectOutputs()),
+                work_zone: this.getWorkZone(),
+            };
+        }
+        if (this.adaptiveNeededSubtask) {
+            const subtaskId = this.adaptiveNeededSubtask;
+            const subtask = this.findStepById(subtaskId);
+            const history = this.retryHistory.get(subtaskId) ?? [];
+            const retryMax = subtask.retry ?? 1;
+            const remaining = this.retryCounters.get(subtaskId) ?? 0;
+            return {
+                status: 'adaptive_needed',
+                instance_id: this.instanceId,
+                spec_id: this.spec?.header.id ?? 'unnamed',
+                subtask_id: subtaskId,
+                failure: {
+                    step_id: history.length > 0 ? history[history.length - 1].steps_tried[0]?.step_id ?? '' : '',
+                    reason: history.length > 0 ? history[history.length - 1].failure_reason : '',
+                    attempt: retryMax - remaining,
+                    max_retries: retryMax,
+                },
+                subtask_contract: {
+                    outputs: subtask.outputs ?? [],
+                    constraints: [],
+                },
+                original_children: subtask.children.map(c => this.toStepSummary(c)),
+                retry_history: history,
+            };
+        }
+        const newlyRunning = [];
+        const state = {
+            stepStates: this.stepStates,
+            variables: this.variables,
+            loopCounters: this.loopCounters,
+            newlyRunning,
+        };
+        const result = dfsNextStep(steps, state, this.spec);
+        // 容器进入 running 时记录骨架（无 context——容器不是执行步骤） // @a: anc-obs-step-start-timing
+        for (const container of newlyRunning) {
+            this.hoplog?.recordStepStart(container.step_id, container.step_type, container.summary);
+        }
+        if (result.kind === 'retry') {
+            return this.nextStep();
+        }
+        if (result.kind === 'exit') {
+            this.hoplog?.close('completed');
+            return {
+                status: 'completed',
+                instance_id: this.instanceId,
+                outputs: this.deflateValues(this.collectOutputs()),
+                work_zone: this.getWorkZone(),
+            };
+        }
+        if (result.kind === 'none') {
+            const terminalNow = this.allTopLevelTerminal(steps);
+            if (terminalNow)
+                return this.nextStep();
+            this.hoplog?.close('failed');
+            return {
+                status: 'failed',
+                instance_id: this.instanceId,
+                failed_step_id: '',
+                failure_reason: 'No executable step found',
+                partial_outputs: this.deflateValues(this.collectOutputs()),
+                work_zone: this.getWorkZone(),
+            };
+        }
+        const target = result.step;
+        this.stepStates.set(target.step_id, 'running');
+        this.recordEvent(target.step_id, 'step_start');
+        // running 状态必须落盘——复用模式下 next 与 done 是独立进程，
+        // done 进程 resume 后需读到 running 才能 completeStep（否则误判 pending）
+        this.persist();
+        let context;
+        try {
+            context = this.assembleBasicContext(target);
+        }
+        catch (err) {
+            // doc-ref 找不到文件/章节 → 硬报错（确定性引用不静默降级）。// @a: anc-exec-doc-ref-resolve
+            const reason = err instanceof DocRefError
+                ? err.message
+                : `doc-ref 解析失败: ${err instanceof Error ? err.message : String(err)}`;
+            if (target.outputs) {
+                const scopeId = getWriteScope(target.step_id, this.spec);
+                this.variables.setOutputsToNull(target.outputs, scopeId);
+            }
+            this.stepStates.set(target.step_id, 'failed');
+            this.recordStepFailure(target.step_id, reason);
+            this.handleFailStepRetry(target.step_id, reason);
+            return this.nextStep();
+        }
+        // None propagation: auto-fail if any input resolves to null (from failed step)
+        if (target.inputs && target.inputs.length > 0) {
+            const hasNullInput = target.inputs.some(b => context.inputs[b.name] === null);
+            if (hasNullInput) {
+                if (target.outputs) {
+                    const scopeId = getWriteScope(target.step_id, this.spec);
+                    this.variables.setOutputsToNull(target.outputs, scopeId);
+                }
+                this.stepStates.set(target.step_id, 'failed');
+                this.recordStepFailure(target.step_id, 'MISSING_INPUT');
+                this.handleFailStepRetry(target.step_id, 'MISSING_INPUT');
+                return this.nextStep();
+            }
+        }
+        // confirm 是 CITL 审批闸门：返回 paused（approve/reject）。// @a: anc-cli-execution-paused, anc-exec-hitl-presentation
+        if (target.step_type === 'confirm') {
+            const confirmNode = target;
+            const options = confirmNode.response_options ?? [
+                { value: 'approve', label: '批准' },
+                { value: 'reject', label: '拒绝' },
+            ];
+            const response = {
+                status: 'paused',
+                instance_id: this.instanceId,
+                step_id: target.step_id,
+                pause_reason: (confirmNode.require_human ? 'waiting_human' : 'confirm'),
+                presented_data: {
+                    summary: target.summary,
+                    question: `审批：${target.summary}。${context.instruction}`,
+                    instruction: context.instruction,
+                    // 人通道:直读原值 + formatHumanContext(>5K 走 {$file, preview}),user 看到 preview 完整可读。
+                    // 不用 context.inputs(已被 PromptAssembler 处理给 LLM 用)。见 ^anc-exec-audience-routing。
+                    context: formatHumanContext(this.resolveRawInputs(target), this.getWorkZone()),
+                },
+                response_options: options,
+                work_zone: this.getWorkZone(),
+            };
+            this.hoplog?.recordStepStart(target.step_id, target.step_type, target.summary, context.inputs, formatPromptText(context, target.step_type));
+            this.flushDocRefMeta(target.step_id);
+            return response;
+        }
+        // ask 是 CITL 数据收集：返回自包含介入请求（question + output_schema + default + options）。
+        // 见概念 ^anc-step-ask / ^anc-exec-hitl-presentation。// @a: anc-step-ask, anc-exec-hitl-presentation
+        if (target.step_type === 'ask') {
+            // default_value：取第一个声明输出在 inputs 中的同名推断值（前序产出），无则 undefined
+            const firstOut = target.outputs?.[0]?.name;
+            const defaultValue = firstOut ? context.inputs[firstOut] : undefined;
+            // present_inputs:透传 AskStep 声明,driver 据此完整 dump 这些 context 字段(禁缩略)。
+            // 见 design/step-dispatcher.md ^anc-exec-hitl-presentation。// @a: anc-rule-p14, anc-exec-hitl-presentation
+            const askNode = target;
+            // options：从 inputs 里的列表型候选构造（可选，对齐 CC AskUserQuestion）
+            const response = {
+                status: 'paused',
+                instance_id: this.instanceId,
+                step_id: target.step_id,
+                pause_reason: 'ask',
+                presented_data: {
+                    summary: target.summary,
+                    question: `请提供：${target.summary}。${context.instruction}`,
+                    instruction: context.instruction,
+                    // 人通道:直读原值 + formatHumanContext(>5K 走 {$file, preview})。
+                    // 见 ^anc-exec-audience-routing。
+                    context: formatHumanContext(this.resolveRawInputs(target), this.getWorkZone()),
+                    output_schema: target.outputs ?? [],
+                    ...(defaultValue !== undefined ? { default_value: defaultValue } : {}),
+                    ...(askNode.present_inputs && askNode.present_inputs.length > 0 ? { present_inputs: askNode.present_inputs } : {}),
+                },
+                response_options: [],
+                work_zone: this.getWorkZone(),
+            };
+            this.hoplog?.recordStepStart(target.step_id, target.step_type, target.summary, context.inputs, formatPromptText(context, target.step_type));
+            this.flushDocRefMeta(target.step_id);
+            return response;
+        }
+        const workZone = this.getWorkZone();
+        const response = {
+            status: 'step_ready',
+            instance_id: this.instanceId,
+            step_id: target.step_id,
+            step_type: target.step_type,
+            summary: target.summary,
+            // context.inputs 由 PromptAssembler 已截断到 2000 字符(LLM prompt 渲染用),
+            // 不做 deflate(deflate 用于原始数据通道:paused.context / outputs / params_for_child)。
+            context,
+            work_zone: workZone,
+            // 本步 output 文件的确切路径——driver/worker 照此写、`--output @<output_path>` 提交,零拼名自由度。
+            // 消除"parallel 内层 step_id 恒为模板 id、拼名易撞"的串台。见 design ^anc-exec-work-zone。
+            output_path: join(workZone, `out_${target.step_id}.json`),
+        };
+        // debug 级记录完整 prompt 文本（角色说明 + 6 层格式化）+ info 级记录 inputs // @a: anc-obs-debug-context
+        this.hoplog?.recordStepStart(target.step_id, target.step_type, target.summary, context.inputs, formatPromptText(context, target.step_type));
+        this.flushDocRefMeta(target.step_id);
+        return response;
+    }
+    completeStep(stepId, outputs) {
+        const state = this.stepStates.get(stepId);
+        if (state === 'done') {
+            return { status: 'ok', code: ErrorCode.ALREADY_DONE, message: 'Step already completed' }; // @a: anc-cli-idempotency
+        }
+        if (state !== 'running') {
+            return { status: 'error', code: ErrorCode.INVALID_STATE, message: `Step '${stepId}' is ${state ?? 'unknown'}, expected running` };
+        }
+        // 输出 schema 校验（值层面，写 vars 前）：不匹配 → 不写不标 done，返回 SCHEMA_MISMATCH。
+        // 触发算子级重试（独立模式引擎内重做 / 复用模式 done 打回 CC）。
+        // confirm/ask 豁免：其输出是 caller 注入的 answer（审批信号/数据值），规范化在 mapConfirm/mapAskOutputs 做。
+        // @a: anc-exec-output-schema-check
+        const declNode = this.findStepById(stepId);
+        if (declNode && declNode.step_type !== 'confirm' && declNode.step_type !== 'ask' && declNode.outputs?.length) {
+            const mismatches = validateOutputValues(declNode.outputs, outputs ?? {});
+            if (mismatches.length > 0) {
+                return { status: 'error', code: ErrorCode.SCHEMA_MISMATCH, message: formatSchemaMismatch(mismatches) };
+            }
+        }
+        // check 判定：固定双槽签名，引擎按类型定位 bool 槽判通过/失败。false → failStep
+        // 接升级阶梯（首次带反馈重跑、再 adaptive）；text 槽作失败说明。
+        // 模式无关（复用 CLI done / 独立 dispatcher 共用此处）。// @a: anc-exec-check-verdict
+        if (declNode?.step_type === 'check') {
+            const boolDecl = declNode.outputs?.find(o => o.type === 'bool');
+            const verdict = boolDecl ? outputs?.[boolDecl.name] : undefined;
+            if (verdict === false || verdict === 'false') {
+                const textDecl = declNode.outputs?.find(o => o.type === 'text');
+                const explanation = textDecl ? outputs?.[textDecl.name] : undefined;
+                // check 失败前先写它的**更新模式输出**（← X 且 → X，回填的 last_err 等）——否则显式反馈值
+                // 丢失（failStep 直接 return 不经 writeOutputs）。只写更新模式输出，保持"check 失败不落新产出"
+                // 语义（bool 判定槽/独立 text 槽仍不落盘）。与概念 ^anc-step-check「text 槽是失败说明」一致。
+                // 见 design/exec-engine.md ^anc-exec-failstep-skip-update（DEBT-13）。// @a: anc-exec-failstep-skip-update
+                if (outputs) {
+                    const updateOuts = declNode.outputs?.filter(o => isUpdateModeOutput(declNode, o.name)) ?? [];
+                    if (updateOuts.length) {
+                        const scopeId = getWriteScope(stepId, this.spec);
+                        for (const o of updateOuts) {
+                            if (o.name in outputs)
+                                this.variables.write(o.name, outputs[o.name], scopeId);
+                        }
+                    }
+                }
+                return this.failStep(stepId, `CHECK_FAILED: ${explanation ?? '(no explanation)'}`);
+            }
+        }
+        // confirm answer 规范化：caller 注入的 answer（原始 key 如 value）不直接写，
+        // 而是提取决策值 → reject 走 failStep、approve 按声明输出类型槽映射（bool→true，
+        // 非 bool→原值）落到声明的变量名。模式无关（CLI done / dispatcher.resume 共用）。
+        // 见概念 ^anc-step-confirm / 设计 step-dispatcher ^anc-exec-confirm-answer。// @a: anc-exec-confirm-answer
+        if (declNode?.step_type === 'confirm') {
+            const decision = this.extractDecision(outputs);
+            if (decision !== undefined && CONFIRM_REJECT_VALUES.has(String(decision).toLowerCase())) {
+                // reject = 授权否决 → 全局中止（非局部 None 传播）：fail 本步 + 跳过所有未终态步骤。
+                // 见概念 ^anc-step-confirm reject 全局中止 / 设计 ^anc-exec-confirm-answer。
+                this.stepStates.set(stepId, 'failed');
+                this.recordStepFailure(stepId, `confirm rejected by caller: ${decision}`);
+                this.hoplog?.recordStepFailed(stepId, `confirm rejected by caller: ${decision}`);
+                for (const [id, status] of this.stepStates) {
+                    if (id !== stepId && (status === 'pending' || status === 'running')) {
+                        this.stepStates.set(id, 'skipped');
+                    }
+                }
+                this.persist();
+                return { status: 'ok' };
+            }
+            outputs = this.mapConfirmOutputs(declNode, outputs, decision);
+        }
+        // ask answer 处理：caller 提供的数据值落到 +→ 声明的变量名。
+        // 与 confirm 正交——无 reject 中止，不做 bool 映射。answer 可能是 {声明名:值}、
+        // {value:值}（包装）、或 approve（采用 default_value 快捷）。见 ^anc-step-ask / ^anc-exec-hitl-presentation。
+        // @a: anc-step-ask, anc-exec-hitl-presentation
+        if (declNode?.step_type === 'ask') {
+            outputs = this.mapAskOutputs(declNode, outputs, stepId);
+        }
+        if (outputs) {
+            const scopeId = getWriteScope(stepId, this.spec);
+            this.variables.writeOutputs(outputs, scopeId);
+        }
+        this.stepStates.set(stepId, 'done');
+        this.recordEvent(stepId, 'step_done');
+        // confirm 决策是 CITL 审计点：决策值记成 hitl 审计字段（无视日志级别），
+        // 而非随 recordStepDone 被 info 级脱敏成 null。见概念层 ^anc-obs-hoplog 安全审计。
+        if (declNode?.step_type === 'confirm' && outputs) {
+            const vals = Object.values(outputs);
+            const decision = vals.length === 1
+                ? String(vals[0])
+                : JSON.stringify(outputs);
+            this.hoplog?.recordStepMeta(stepId, {
+                hitl: { response: decision, responder: 'caller', at: new Date().toISOString() },
+            });
+        }
+        this.hoplog?.recordStepDone(stepId, outputs);
+        // propagate + 容器 done 记录(branch/case/subtask/loop 级联标 done 时补 recordStepDone)
+        this.propagateAndRecord(stepId);
+        this.persist();
+        return { status: 'ok' };
+    }
+    // 完成并推进到 caller 介入点：driver 交活 + 领取下一指令的一次原子往返。
+    // completeStep 成功 → 推进、消化中间步（纯计算 body）→ 停在下一个 caller 介入点或终态，
+    // 返回 NextResponse。completeStep 出错（SCHEMA_MISMATCH 等）→ 原样返回错误码、不推进。
+    // 执行节奏归引擎（概念不变量6）。见设计 ^anc-exec-advance-to-caller。// @a: anc-exec-advance-to-caller
+    async completeAndAdvance(stepId, outputs) {
+        const resp = this.completeStep(stepId, outputs);
+        if (resp.status !== 'ok')
+            return resp; // 错误不推进（重做本步也是"下一步指令"）
+        return this.advanceToCaller();
+    }
+    // 从当前状态推进到下一个 caller 介入点：消化纯计算 body（BodyInterpreter + 哑 ToolProvider），
+    // 遇 caller 介入点/终态停。async 因 BodyInterpreter.run 是 async（纯计算 body 实际无 IO）。
+    // can_fanout 时每轮推进前先探最外层 parallel——命中则返回 ParallelReady 交 driver fan-out。
+    // @a: anc-exec-advance-to-caller, anc-exec-parallel-batch, anc-exec-parallel-foreach-barrier
+    async advanceToCaller() {
+        // fan-out 优先：探最外层 parallel batch 必须先于 nextStep 树遍历。
+        // 否则 dfsNextStep 越过未 join 的 forEach parallel（标 running 后 continue），落到同级
+        // 后续步并当作下一个 executable 返回 → nextStep 把它误标 running 并持久化；join 完成后
+        // 再遍历时该步既非终态也非 pending → dfsNextStep 跳过 → "No executable step found"。
+        // collectParallelBatch 能直接命中 pending 的最外层 parallel 并标 running，无需 nextStep 先行。
+        // worker（canFanout=false）不进此分支，照常 nextStep 下钻子树。
+        // 见 design/parallel-execution.md §9b' ^anc-exec-parallel-foreach-barrier。
+        if (this.canFanout) {
+            const batch = this.nextParallelBatch();
+            if (batch)
+                return batch;
+        }
+        let result = this.nextStep();
+        while (result.status === 'step_ready' && !this.isCallerActionPoint(result.step_id)) {
+            const node = this.findStepById(result.step_id);
+            if (!node?.body || bodyHasToolCall(node.body))
+                break; // 防御性二次确认
+            const interp = new BodyInterpreter({
+                inputs: result.context?.inputs ?? {},
+                toolProvider: ENGINE_NOOP_TOOL_PROVIDER,
+                allowCommit: result.step_type === 'commit',
+                toolCallLog: [],
+            });
+            const outputs = await interp.run(node.body, node.outputs ?? []);
+            const r = this.completeStep(result.step_id, outputs);
+            if (r.status !== 'ok')
+                return result; // schema 校验失败等 → 停在该步交 caller（不静默吞）
+            // 消化一步后,parallelMode 下再探 parallel（被消化步骤可能正好打开了一个 parallel 容器）
+            if (this.canFanout) {
+                const batch = this.nextParallelBatch();
+                if (batch)
+                    return batch;
+            }
+            result = this.nextStep();
+        }
+        return result;
+    }
+    // 复用模式真并行：探测最外层 running/pending parallel，命中则把其 pending children 标 running、
+    // 解析各 child 入参、构造 ParallelReady 交 driver fan-out。未命中返回 null（回退普通 advance）。
+    // @a: anc-exec-parallel-batch, anc-exec-parallel-canfanout
+    nextParallelBatch() {
+        if (!this.spec || !this.canFanout)
+            return null;
+        const state = {
+            stepStates: this.stepStates,
+            variables: this.variables,
+            loopCounters: this.loopCounters,
+        };
+        const batch = collectParallelBatch(this.spec.steps ?? [], state, this.spec);
+        if (!batch)
+            return null;
+        // 父 parallel 标 running（若尚未），开作用域 // @a: anc-obs-step-start-timing
+        if (this.stepStates.get(batch.parallelStepId) !== 'running') {
+            this.stepStates.set(batch.parallelStepId, 'running');
+            if (!this.variables.hasScope(batch.parallelStepId)) {
+                this.variables.createScope(batch.parallelStepId, getWriteScope(batch.parallelStepId, this.spec));
+            }
+        }
+        const parentScope = batch.parallelStepId; // child 入参从 parallel scope 自底向上解析
+        // for-each 动态展开：模板 child × 列表长度 → N 个 ParallelChildSpec
+        const parallelNode = this.findStepById(batch.parallelStepId);
+        const forEach = parallelNode?.forEach;
+        let expandedChildren;
+        if (forEach && batch.children.length === 1) { // @a: anc-exec-parallel-foreach
+            const listVal = this.variables.read(forEach.listVar, getWriteScope(batch.parallelStepId, this.spec));
+            const items = Array.isArray(listVal) ? listVal : [];
+            const template = batch.children[0];
+            expandedChildren = items.map((item, idx) => {
+                const childId = `${batch.parallelStepId}.${idx + 1}`;
+                this.stepStates.set(childId, 'running');
+                this.recordEvent(childId, 'step_start');
+                const baseParams = this.resolveChildParams(template, parentScope);
+                return {
+                    child_step_id: childId,
+                    summary: `${template.summary} [${idx + 1}/${items.length}]`,
+                    subinstance_dir: this.instanceDir ? `${this.instanceDir}/parallel/${childId}` : `parallel/${childId}`,
+                    params_for_child: { ...baseParams, [forEach.itemVar]: item },
+                };
+            });
+        }
+        else {
+            // 静态 parallel：原有逻辑
+            expandedChildren = batch.children.map(child => {
+                this.stepStates.set(child.step_id, 'running');
+                this.recordEvent(child.step_id, 'step_start');
+                return {
+                    child_step_id: child.step_id,
+                    summary: child.summary,
+                    subinstance_dir: this.instanceDir ? `${this.instanceDir}/parallel/${child.step_id}` : `parallel/${child.step_id}`,
+                    params_for_child: this.resolveChildParams(child, parentScope),
+                };
+            });
+        }
+        // parallel 容器 recordStepStart：debug 级记录完整自包含 fan-out 指令文本
+        const header = this.spec.header;
+        const maxConcurrent = this.hostConfig?.resource_limits?.max_concurrent_workers ?? 5;
+        const cliPath = this.cliAbsPath ?? 'PJ/AgentHOP/code/hopstep/dist/cli.js';
+        const parallelPrompt = formatParallelPromptText({
+            goal: header.goal ?? '',
+            outputs: header.outputs?.map(o => `${o.name}: ${o.type}`).join(', ') ?? '',
+            parallelStepId: batch.parallelStepId,
+            children: expandedChildren.map(c => ({ child_step_id: c.child_step_id, summary: c.summary, params_for_child: c.params_for_child })),
+            maxConcurrent,
+            instanceId: this.instanceId,
+            specPath: this.specPath ?? '<spec.md>',
+            cliPath,
+            parentLogDir: this.hoplog?.getRunDir() ?? '.hoplog',
+            stateDir: this.stateDir ?? '.hopstate',
+        });
+        this.hoplog?.recordStepStart(batch.parallelStepId, 'parallel', parallelNode?.summary ?? '', undefined, parallelPrompt);
+        // child 生命周期归子 hoplog（方案 A ^anc-obs-parallel-child-satellite）：父 hoplog 不预写 child start
+        // （child start/done 各在其子 hoplog parallel/<cid>/log/）；父只在下方 fanout 记 child_ids。
+        // 这消除"child start 在 fan-out 时写、done 在 join 时写"的撕裂——曾致流式 append 缩进交错、YAML 非法。
+        this.hoplog?.recordParallelFanout(batch.parallelStepId, expandedChildren.map(c => c.child_step_id), maxConcurrent);
+        // 落盘每个 child 的 params_for_child（内部真值，不 deflate）到其 subinstance 目录，供 worker init 按 cid 回填 itemVar。
+        // 仅复用模式（FilePersistence 有 instanceDir）；独立模式 dispatcher 不起 worker 子实例、走内存 scope。
+        // 见 design/parallel-execution.md ^anc-exec-parallel-foreach-worker。// @a: anc-exec-parallel-foreach-worker
+        if (this.instanceDir) {
+            for (const child of expandedChildren) {
+                writeChildParams(this.instanceDir, child.child_step_id, child.params_for_child);
+            }
+        }
+        this.persist();
+        return {
+            status: 'parallel_ready',
+            instance_id: this.instanceId,
+            parallel_step_id: batch.parallelStepId,
+            // params_for_child 内大值经 deflate;subinstance_dir/summary 不变。// @a: anc-exec-deflate
+            // 按 child_step_id 命名空间隔离——for-each N child 共享父 work_zone/vars 且同名(itemVar)，
+            // 不隔离会互相覆盖(实证 bug:exec-engine 批被 spec-parser 批覆盖)。见 ^anc-exec-deflate 多 child 隔离。
+            children: expandedChildren.map(c => ({
+                ...c,
+                params_for_child: this.deflateValues(c.params_for_child, c.child_step_id),
+            })),
+            max_concurrent: maxConcurrent,
+            ...(this.hoplog ? { parent_log_dir: this.hoplog.getRunDir() } : {}),
+            work_zone: this.getWorkZone(),
+        };
+    }
+    // 解析一个 parallel child 容器的入参：收集 child 子树（含自身）所有 ← 输入绑定，
+    // 从父 scope 自底向上读 source 值。driver 据此启动 worker 子实例 --params。
+    // @a: anc-exec-parallel-child-params
+    resolveChildParams(child, parentScope) {
+        const params = {};
+        const declaredInSubtree = new Set(); // 子树内部产出的名字不算外部入参
+        for (const node of [child, ...collectDescendants(child)]) {
+            for (const o of node.outputs ?? [])
+                declaredInSubtree.add(o.name);
+        }
+        for (const node of [child, ...collectDescendants(child)]) {
+            for (const b of node.inputs ?? []) {
+                if (declaredInSubtree.has(b.source))
+                    continue; // 来自子树内部步骤，非外部入参
+                const val = this.variables.read(b.source, parentScope);
+                if (val !== undefined)
+                    params[b.source] = val;
+            }
+        }
+        return params;
+    }
+    // fan-out CLI 调度顾问：无状态复原窗口，算下一步调度动作（补位 launch / join / wait）。
+    // fanout-plan（初始批）与 fanout-next（补位）共用此单一计算。派发即原子标 dispatched 落盘（防重复派发）。
+    // 见 design/parallel-execution.md ^anc-exec-parallel-fanout-advisor / ^anc-exec-parallel-fanout-concurrency。
+    // @a: anc-exec-parallel-fanout-advisor
+    fanoutSchedule(parallelStepId) {
+        const parallel = this.findStepById(parallelStepId);
+        if (!parallel || parallel.step_type !== 'parallel') {
+            return { action: 'error', message: `Step '${parallelStepId}' is not a parallel step` };
+        }
+        // 窗口上限：优先 hostConfig（顶层进程），退持久化值（load 后 hostConfig 丢 resource_limits），再缺省 5。
+        const maxConcurrent = this.hostConfig?.resource_limits?.max_concurrent_workers ?? this.maxConcurrent ?? 5;
+        // ① child 全集：fan-out 时 nextParallelBatch 已把 N 个 child 展开并标 running（for-each 合成 ID
+        //    或静态 child），故全集 = step_states 里以 parallelStepId 为直接父的所有 id。
+        const allChildren = [];
+        for (const id of this.stepStates.keys()) {
+            if (getParentStepId(id) === parallelStepId)
+                allChildren.push(id);
+        }
+        allChildren.sort((a, b) => {
+            const na = Number(a.slice(a.lastIndexOf('.') + 1));
+            const nb = Number(b.slice(b.lastIndexOf('.') + 1));
+            return na - nb;
+        });
+        // ② 已派发 / 已终态 / 在跑
+        const dispatched = new Set(this.dispatched.get(parallelStepId) ?? []);
+        const terminal = new Set();
+        for (const cid of allChildren) {
+            if (this.isChildTerminal(cid))
+                terminal.add(cid);
+        }
+        const running = [...dispatched].filter(c => !terminal.has(c));
+        const pending = allChildren.filter(c => !dispatched.has(c));
+        // ③ 全部终态 → join
+        if (terminal.size === allChildren.length && allChildren.length > 0) {
+            return {
+                action: 'join',
+                command: this.buildJoinCommand(parallelStepId),
+            };
+        }
+        // ④ 窗口有空位 + 有待起 → 补位（原子标 dispatched 落盘）
+        const slots = maxConcurrent - running.length;
+        if (slots > 0 && pending.length > 0) {
+            const toLaunch = pending.slice(0, slots);
+            const list = this.dispatched.get(parallelStepId) ?? [];
+            for (const cid of toLaunch)
+                list.push(cid);
+            this.dispatched.set(parallelStepId, list);
+            // 每派发一个 child 流式记一条 dispatch 事件到父 hoplog（dispatched_at = 此刻，引擎动作时刻）。
+            // 顾问进程 load 已 HopLog.resume 重建父句柄。log = 该 child 子日志目录（与 launch_command 里 --log-dir 同源）。
+            // 见 design ^anc-obs-parallel-dispatch。// @a: anc-obs-parallel-dispatch
+            for (const cid of toLaunch) {
+                this.hoplog?.recordParallelDispatch(parallelStepId, cid, this.childLogDir(cid));
+            }
+            this.persist(); // 派发即原子落盘，下次复原不重发
+            return {
+                action: 'launch',
+                max_concurrent: maxConcurrent,
+                workers: toLaunch.map(cid => ({ child_step_id: cid, launch_command: this.buildWorkerLaunchCommand(cid) })),
+                remaining: pending.filter(c => !toLaunch.includes(c)),
+            };
+        }
+        // ⑤ 无空位或队列已空但仍有在跑 → 等
+        return { action: 'wait', running };
+    }
+    // child 子实例是否终态：子实例存在 且 无任何 running 步骤（与 join_parallel 判据一致，cli.ts）。
+    // ⚠️ 不能用 step_states[childStepId] 判——for-each worker 经 scope 掩码把合成 ID {P}.{N} 解析回
+    // 模板 ID {P}.1 执行，子实例 state 全按模板 ID 记，合成 cid 键根本不存在（曾致 join 永不触发）。
+    // 目录名（合成 cid）才是 child 身份，目录内按"整体无 running"判终态。// @a: anc-exec-parallel-fanout-advisor
+    isChildTerminal(childStepId) {
+        if (!this.instanceDir)
+            return false;
+        const childDir = join(this.instanceDir, 'parallel', childStepId);
+        if (!stateExists(childDir))
+            return false; // 未起或刚派发未建目录 → 非终态
+        try {
+            const st = readState(childDir);
+            // 子实例无 running 步 = 该 worker 跑完（done 或 failed 都算终态，join 时再区分成败）
+            return !Object.values(st.step_states).some(s => s === 'running');
+        }
+        catch {
+            return false;
+        }
+    }
+    // 拼单个 worker 的完整启动命令（cd 锁 cwd + run --parallel-parent/child + log-dir；不含 --params，itemVar 引擎回填）。
+    // 路径全由引擎持有的 specPath/cliAbsPath/workspace_dir/stateDir 生成——消除 driver 手拼漏参。// @a: anc-exec-parallel-fanout-advisor
+    buildWorkerLaunchCommand(childStepId) {
+        const cli = this.cliAbsPath ?? 'PJ/AgentHOP/code/hopstep/dist/cli.js';
+        const spec = this.specPath ?? '<spec.md>';
+        const stateDir = this.stateDir ?? '.hopstate';
+        const vault = this.hostConfig?.workspace_dir;
+        const logDir = this.childLogDir(childStepId);
+        // 路径全双引号包裹——工作区绝对路径常含空格（iCloud "Mobile Documents"），裸插值会被 shell 拆参。
+        // 见 design/parallel-execution.md §10e 路径含空格拆裂参数。
+        const cmd = `node "${cli}" run "${spec}" --parallel-parent ${this.instanceId} --parallel-child ${childStepId} --state-dir "${stateDir}" --log-dir "${logDir}" --log-level debug`;
+        return vault ? `cd "${vault}" && ${cmd}` : cmd;
+    }
+    // 单个 child 子日志目录：与 launch_command 的 --log-dir 同源（dispatch 事件的 log 字段复用，保证一致）。
+    childLogDir(childStepId) {
+        const stateDir = this.stateDir ?? '.hopstate';
+        return `${this.hoplog?.getRunDir() ?? stateDir}/parallel/${childStepId}/log`;
+    }
+    buildJoinCommand(parallelStepId) {
+        const cli = this.cliAbsPath ?? 'PJ/AgentHOP/code/hopstep/dist/cli.js';
+        const stateDir = this.stateDir ?? '.hopstate';
+        // 路径双引号包裹（同 buildWorkerLaunchCommand，防含空格路径拆参）。
+        return `node "${cli}" join_parallel ${parallelStepId} --state-dir "${stateDir}" --instance ${this.instanceId}`;
+    }
+    // join barrier：N 个 worker 子实例终态后，单进程收集各子实例输出，按 parallel 容器声明 +→ 同名
+    // merge 回 parallel scope，标 children done/failed → propagateCompletion 标 parallel done + 提升。
+    // childResults: child_step_id → { vars, failed, log? }。log = 该 child 子实例日志路径（cli.ts 收集时带出，
+    // 供 join 块记录子日志定位线索）。见 design/exec-engine.md ^anc-exec-parallel-join-merge。
+    // @a: anc-exec-parallel-join-merge
+    joinParallel(parallelStepId, childResults) {
+        const step = this.findStepById(parallelStepId);
+        if (!step || step.step_type !== 'parallel') {
+            return { status: 'error', code: ErrorCode.INVALID_STEP_ID, message: `Step '${parallelStepId}' is not a parallel step` };
+        }
+        const parallel = step;
+        const parallelScope = parallelStepId;
+        this.joinStartedAt = timestamp(); // 进入 join 的时刻，join 块 started_at（ended_at 在 recordParallelJoin 内）
+        // for-each parallel：遍历 childResults 全部合成 ID（spec 只有模板 child），按列表输出收集。
+        // 见 design/parallel-execution.md §9c ^anc-exec-parallel-foreach-join。// @a: anc-exec-parallel-foreach-join
+        if (parallel.forEach) {
+            const template = getChildren(parallel)[0];
+            const templateOutputs = template?.outputs ?? [];
+            // 按合成 ID 序号排序，保证列表顺序与 fan-out 一致
+            const childIds = Object.keys(childResults).sort((a, b) => {
+                const na = Number(a.slice(a.lastIndexOf('.') + 1));
+                const nb = Number(b.slice(b.lastIndexOf('.') + 1));
+                return na - nb;
+            });
+            // 各 child 同名输出收集成列表（按 child 声明的 +→ 名）
+            const collected = {};
+            for (const decl of templateOutputs)
+                collected[decl.name] = [];
+            for (const childId of childIds) {
+                const res = childResults[childId];
+                for (const decl of templateOutputs) {
+                    collected[decl.name].push(res.failed ? null : (res.vars[decl.name] ?? null));
+                }
+                this.stepStates.set(childId, res.failed ? 'failed' : 'done');
+                // child 生命周期归子 hoplog（方案 A ^anc-obs-parallel-child-satellite）：父 hoplog 不写 child start/done，
+                // 只在 recordParallelJoin 记各 child 终态。父这里仅更新引擎状态 + 失败记录（供 join 聚合），不碰父 hoplog。
+                if (res.failed) {
+                    this.recordStepFailure(childId, `parallel child '${childId}' failed`, 'error');
+                }
+            }
+            // parallel 容器声明 +→ X: [T] → 写收集的列表；child 同名 X: T → 用 collected[X]
+            for (const pDecl of parallel.outputs ?? []) {
+                const list = collected[pDecl.name];
+                if (list !== undefined) {
+                    this.variables.write(pDecl.name, list, parallelScope);
+                }
+            }
+            this.stepStates.set(parallelStepId, 'done');
+            // 提升 parallel 聚合输出到父 scope
+            const parentScopeId = getWriteScope(parallelStepId, this.spec);
+            for (const pDecl of parallel.outputs ?? []) {
+                const val = this.variables.read(pDecl.name, parallelScope);
+                if (parentScopeId !== parallelScope)
+                    this.variables.write(pDecl.name, val, parentScopeId);
+            }
+            const parallelOutputs = {};
+            for (const decl of parallel.outputs ?? []) {
+                parallelOutputs[decl.name] = this.variables.read(decl.name, parentScopeId);
+            }
+            return this.finalizeParallelJoin(parallelStepId, parallelOutputs, childResults);
+        }
+        // 每个 child 容器：按其声明 +→ 输出从子实例 vars 同名取值 merge 到 parallel scope；标终态
+        for (const child of getChildren(parallel)) {
+            const res = childResults[child.step_id];
+            if (!res)
+                continue; // 未提交结果的 child（理论上 driver 应交齐）保持原状
+            if (res.failed) {
+                // child 失败：其声明输出写 None，不阻塞其余（沿用底层 fail 语义）
+                for (const decl of child.outputs ?? []) {
+                    this.variables.write(decl.name, null, parallelScope);
+                }
+                this.stepStates.set(child.step_id, 'failed');
+                this.recordStepFailure(child.step_id, `parallel child '${child.step_id}' failed`, 'error');
+                // child 生命周期归子 hoplog（方案 A）：父 hoplog 不写 child done/failed，join 记终态即可。
+            }
+            else {
+                for (const decl of child.outputs ?? []) {
+                    this.variables.write(decl.name, res.vars[decl.name] ?? null, parallelScope);
+                }
+                this.stepStates.set(child.step_id, 'done');
+            }
+        }
+        // children 全终态 → propagateCompletion 标 parallel done + 容器声明 +→ 提升到父 scope
+        propagateCompletion(getChildren(parallel)[0]?.step_id ?? parallelStepId, {
+            stepStates: this.stepStates,
+            variables: this.variables,
+            loopCounters: this.loopCounters,
+        }, this.spec);
+        // parallel 容器自身完成记录
+        const parallelOutputs = {};
+        for (const decl of parallel.outputs ?? []) {
+            parallelOutputs[decl.name] = this.variables.read(decl.name, getWriteScope(parallelStepId, this.spec));
+        }
+        return this.finalizeParallelJoin(parallelStepId, parallelOutputs, childResults);
+    }
+    /** parallel join 两分支（for-each / static）共同尾段：记 parallel 完成 + join 审计 + 落盘 + 返回 ok。 */
+    finalizeParallelJoin(parallelStepId, parallelOutputs, childResults) {
+        // 顺序：先 join 事件（4.3 的 body 字段），再 recordStepDone（4.3 收尾 status/completed_at）——
+        // 保证 status 是 parallel 步骤 mapping 的最后字段，join 作为执行事件在其前。见 ^anc-obs-parallel-child-satellite。
+        // join 块带 started_at（joinParallel 入口捕获）+ 每 child 的 log（子日志路径）+ ended_at（record 内 timestamp）。
+        this.hoplog?.recordParallelJoin(parallelStepId, Object.fromEntries(Object.entries(childResults).map(([id, r]) => [id, { failed: r.failed, log: r.log }])), this.joinStartedAt ?? undefined);
+        this.hoplog?.recordStepDone(parallelStepId, parallelOutputs);
+        this.persist();
+        return { status: 'ok' };
+    }
+    // caller 介入点判定（引擎语义，唯一权威）：reason/check 需推理、confirm 需决策、
+    // 含工具调用的 act/commit 需 caller 工具。其余（纯计算 body、容器推进）引擎自消化。
+    // 见设计 ^anc-exec-advance-to-caller。
+    isCallerActionPoint(stepId) {
+        const node = this.findStepById(stepId);
+        if (!node)
+            return true; // 未知步骤交 caller 兜底
+        if (node.step_type === 'reason' || node.step_type === 'check' || node.step_type === 'confirm' || node.step_type === 'ask') {
+            return true;
+        }
+        if (node.step_type === 'act' || node.step_type === 'commit') {
+            const body = node.body;
+            // 无 body（自然语言指令，caller 执行）或含工具调用（工具是 caller 的）→ 交 caller
+            return !body || bodyHasToolCall(body);
+        }
+        return false; // 其余（控制流/容器）非 caller 介入点
+    }
+    // call 步骤完成：读子实例输出，按 output_mapping（子output→父var）回填父 call 步骤的 +→ // @a: anc-step-call
+    completeCallStep(callStepId, childVars) {
+        const step = this.findStepById(callStepId);
+        if (!step || step.step_type !== 'call') {
+            return { status: 'error', code: ErrorCode.INVALID_STEP_ID, message: `Step '${callStepId}' is not a call step` };
+        }
+        const call = step;
+        // 按 output_mapping 把子实例输出搬到父变量；无映射则同名透传子 spec 声明的输出
+        const mapped = {};
+        if (call.output_mapping && call.output_mapping.length > 0) {
+            for (const m of call.output_mapping) {
+                mapped[m.to] = childVars[m.from]; // 父变量 m.to ← 子输出 m.from
+            }
+        }
+        else {
+            // 无显式映射：把 call 步骤声明的 +→ 输出按同名从子变量取
+            for (const decl of step.outputs ?? []) {
+                mapped[decl.name] = childVars[decl.name];
+            }
+        }
+        return this.completeStep(callStepId, mapped);
+    }
+    failStep(stepId, reason, failKind = 'error') {
+        const state = this.stepStates.get(stepId);
+        if (state === 'failed') {
+            return { status: 'ok', code: ErrorCode.ALREADY_FAILED, message: 'Step already failed' }; // @a: anc-cli-idempotency
+        }
+        if (state !== 'running') {
+            return { status: 'error', code: ErrorCode.INVALID_STATE, message: `Step '${stepId}' is ${state ?? 'unknown'}, expected running` };
+        }
+        const step = this.findStepById(stepId);
+        if (step?.outputs) {
+            const scopeId = getWriteScope(stepId, this.spec);
+            // 更新模式输出（← X 且 → X，X 是本步在更新的既有变量）不置 None——判据同 V3 更新模式豁免。
+            // 置 None 会破坏跨步/跨重试的显式反馈流（如 check finally 回填祖先 last_err 供重跑步定向修正）。
+            // 见 design/exec-engine.md ^anc-exec-failstep-skip-update（DEBT-13）。// @a: anc-exec-failstep-skip-update
+            const toNull = step.outputs.filter(o => !isUpdateModeOutput(step, o.name));
+            this.variables.setOutputsToNull(toNull, scopeId);
+        }
+        this.stepStates.set(stepId, 'failed');
+        this.recordStepFailure(stepId, reason, failKind);
+        this.hoplog?.recordStepFailed(stepId, reason, failKind);
+        this.handleFailStepRetry(stepId, reason);
+        this.persist();
+        return { status: 'ok' };
+    }
+    submitReplan(subtaskId, stepsMd) {
+        if (this.adaptiveNeededSubtask !== subtaskId) {
+            return {
+                status: 'error',
+                code: ErrorCode.INVALID_STATE,
+                errors: [{ kind: 'validate', rule: 'replan', severity: 'error', message: `Subtask '${subtaskId}' is not awaiting replan` }],
+            };
+        }
+        const subtask = this.findStepById(subtaskId);
+        if (!subtask) {
+            return {
+                status: 'error',
+                code: ErrorCode.INVALID_STEP_ID,
+                errors: [{ kind: 'validate', rule: 'replan', severity: 'error', message: `Subtask '${subtaskId}' not found` }],
+            };
+        }
+        // --- P0-2: Circuit breaker — replan attempt limit ---
+        const currentCount = this.replanCounters.get(subtaskId) ?? 0;
+        if (currentCount >= 3) {
+            return {
+                status: 'error',
+                code: ErrorCode.REPLAN_LIMIT_EXCEEDED,
+                errors: [{ kind: 'validate', rule: 'replan-limit', severity: 'error', message: `Subtask '${subtaskId}' has exceeded maximum replan attempts (3)` }],
+            };
+        }
+        const wrappedMd = `# Replan\nGoal: replan\n\n## Steps\n${stepsMd}`;
+        const { ast, errors: parseErrors } = parseSpec(wrappedMd);
+        if (parseErrors.length > 0) {
+            return { status: 'error', code: ErrorCode.PARSE_ERROR, errors: parseErrors };
+        }
+        const newSteps = ast.steps ?? [];
+        if (newSteps.length === 0) {
+            return {
+                status: 'error',
+                code: ErrorCode.VALIDATION_ERROR,
+                errors: [{ kind: 'validate', rule: 'replan', severity: 'error', message: 'Replan must have at least 1 step' }],
+            };
+        }
+        // --- P0-2: Similarity detection (duplicate replan) ---
+        const newSummaries = newSteps.map(s => this.toStepSummary(s));
+        const lastChildren = this.lastReplanChildren.get(subtaskId);
+        if (lastChildren && this.isReplanDuplicate(lastChildren, newSummaries)) {
+            this.adaptiveNeededSubtask = null;
+            this.markSubtaskFailed(subtask);
+            this.persist();
+            return {
+                status: 'error',
+                code: ErrorCode.REPLAN_DUPLICATE,
+                errors: [{ kind: 'validate', rule: 'replan-duplicate', severity: 'error', message: `Replan for '${subtaskId}' is too similar to previous attempt (duplicate detected)` }],
+            };
+        }
+        const requiredOutputs = new Set((subtask.outputs ?? []).map(o => o.name));
+        const providedOutputs = new Set();
+        const collectOutputs = (steps) => {
+            for (const s of steps) {
+                if (s.outputs)
+                    for (const o of s.outputs)
+                        providedOutputs.add(o.name);
+                if (hasChildren(s))
+                    collectOutputs(getChildren(s));
+            }
+        };
+        collectOutputs(newSteps);
+        const missing = [...requiredOutputs].filter(n => !providedOutputs.has(n));
+        if (missing.length > 0) {
+            return {
+                status: 'error',
+                code: ErrorCode.VALIDATION_ERROR,
+                errors: [{ kind: 'validate', rule: 'replan-outputs', severity: 'error', message: `Replan missing required outputs: ${missing.join(', ')}` }],
+            };
+        }
+        // --- P0-1: check-finally preservation validation ---
+        const checkValidationError = this.validateCheckPreservation(subtask.children, newSteps);
+        if (checkValidationError) {
+            return {
+                status: 'error',
+                code: ErrorCode.VALIDATION_ERROR,
+                errors: [checkValidationError],
+            };
+        }
+        // --- P0-2: Increment replan counter and store last children ---
+        this.replanCounters.set(subtaskId, currentCount + 1);
+        this.lastReplanChildren.set(subtaskId, newSummaries);
+        this.removeChildStates(subtask);
+        const reIdChildren = this.reIdSteps(newSteps, subtaskId);
+        subtask.children = reIdChildren;
+        this.setSubtreePending(reIdChildren);
+        this.stepStates.set(subtaskId, 'running');
+        const scopeId = getWriteScope(subtaskId, this.spec);
+        this.variables.clearScope(scopeId === subtaskId ? subtaskId : scopeId);
+        this.adaptiveNeededSubtask = null;
+        this.recordEvent(subtaskId, 'replan');
+        // 提报沉淀(降级阶梯运行时生成必沉淀):绑定四元组发 HopLog replan_audit 审计事件,
+        // 供运维离线提取→审核→晋升为预声明备用链路(渐进固化)。
+        // 见 ^anc-exec-retry-adaptive 提报沉淀 / spec-observability ^anc-obs-replan-audit。
+        // @a: anc-obs-replan-audit
+        const newChildrenSummary = reIdChildren.map(c => this.toStepSummary(c));
+        const lastFail = (this.retryHistory.get(subtaskId) ?? []).slice(-1)[0];
+        this.hoplog?.recordReplanAudit({
+            spec_id: this.spec?.header.id ?? 'unnamed',
+            step_id: subtaskId,
+            error_reason: lastFail?.failure_reason ?? '',
+            generated_children: newChildrenSummary,
+            base: 'scratch', // 档A:运行时从零生成(第4档)。档B 备用链路库就绪后,基于备用改的标 'fallback'
+            at: new Date().toISOString(),
+        });
+        this.persist();
+        return {
+            status: 'ok',
+            new_children: newChildrenSummary,
+        };
+    }
+    selectBranch(stepId, selectedCaseId, reason) {
+        const branch = this.findStepById(stepId);
+        if (!branch || branch.step_type !== 'branch') {
+            return { status: 'error', code: ErrorCode.INVALID_STEP_ID, message: `Step '${stepId}' is not a branch` };
+        }
+        const state = this.stepStates.get(stepId);
+        if (state !== 'pending' && state !== 'running') {
+            return { status: 'error', code: ErrorCode.INVALID_STATE, message: `Branch '${stepId}' is ${state}, expected pending or running` };
+        }
+        const caseStep = branch.children.find(c => c.step_id === selectedCaseId);
+        if (!caseStep) {
+            return { status: 'error', code: ErrorCode.INVALID_STEP_ID, message: `Case '${selectedCaseId}' not found in branch '${stepId}'` };
+        }
+        this.stepStates.set(stepId, 'running');
+        this.stepStates.set(caseStep.step_id, 'running');
+        for (const c of branch.children) {
+            if (c.step_id !== selectedCaseId) {
+                this.stepStates.set(c.step_id, 'skipped');
+                this.skipAllDescendants(c);
+            }
+        }
+        this.recordEvent(stepId, 'branch_select', reason ?? selectedCaseId);
+        this.persist();
+        return { status: 'ok' };
+    }
+    getStatus() {
+        let completed = 0, failed = 0, pending = 0;
+        let currentStep;
+        for (const [id, state] of this.stepStates) {
+            if (state === 'done')
+                completed++;
+            else if (state === 'failed')
+                failed++;
+            else if (state === 'pending')
+                pending++;
+            else if (state === 'running')
+                currentStep = id;
+        }
+        const executionStatus = this.determineExecutionStatus();
+        return {
+            status: 'ok',
+            instance_id: this.instanceId,
+            execution_status: executionStatus,
+            total_steps: this.stepStates.size,
+            completed,
+            failed,
+            pending,
+            current_step: currentStep,
+        };
+    }
+    getVars() {
+        const executionStatus = this.determineExecutionStatus();
+        const allVars = this.variables.getAllVariables();
+        const declaredOutputs = this.spec?.header.outputs ?? [];
+        const pendingOutputs = this.variables.getPendingOutputs(declaredOutputs);
+        return {
+            status: 'ok',
+            instance_id: this.instanceId,
+            execution_status: executionStatus,
+            variables: allVars,
+            pending_outputs: pendingOutputs,
+        };
+    }
+    /** 递归把子树所有步骤置 pending（init 时初始化 / retry 时重置——同一操作，单点定义）。 */
+    setSubtreePending(steps) {
+        for (const step of steps) {
+            this.stepStates.set(step.step_id, 'pending');
+            if (hasChildren(step)) {
+                this.setSubtreePending(getChildren(step));
+            }
+        }
+    }
+    // parallel worker 子实例 scope 掩码：目标 child 子树保留 pending，其余全标 skipped。
+    // 祖先链标 running（容器已进入），子树内保持 pending（等引擎正常推进）。
+    // 见 design/parallel-execution.md §2b executeSubtreeOnly + §9e for-each worker 启动。
+    // @a: anc-exec-parallel-subinstance, anc-exec-parallel-foreach-worker
+    executeSubtreeOnly(childStepId, steps) {
+        // 收集子树 step_id 集合（child 自身 + 全部后代）
+        const subtreeIds = new Set();
+        let target = this.findStepById(childStepId);
+        let effectiveRoot = childStepId;
+        // for-each 合成 ID 解析：findStepById 命中失败时，检测父 parallel 是否 forEach，
+        // 解析回模板 child {P}.1（子树结构相同，只是 step_id 前缀不同）。见 §9e
+        if (!target) {
+            const parentId = getParentStepId(childStepId);
+            const parentStep = parentId ? this.findStepById(parentId) : null;
+            if (parentStep?.step_type === 'parallel' && parentStep.forEach) {
+                const templateId = `${parentId}.1`;
+                target = this.findStepById(templateId);
+                effectiveRoot = templateId;
+                // 记录 for-each worker 序号（用于 itemVar 自播种）
+                const idxMatch = childStepId.match(/\.(\d+)$/);
+                this.forEachWorkerIdx = idxMatch ? Number(idxMatch[1]) - 1 : 0;
+            }
+        }
+        if (!target)
+            return;
+        this.subtreeRoot = effectiveRoot; // 修正为模板 ID（worker 内部执行用模板 step_id）
+        subtreeIds.add(effectiveRoot);
+        for (const d of collectDescendants(target))
+            subtreeIds.add(d.step_id);
+        // 收集祖先链 step_id（从 child 到根的容器路径）
+        const ancestorIds = new Set();
+        let pid = getParentStepId(effectiveRoot);
+        while (pid) {
+            ancestorIds.add(pid);
+            pid = getParentStepId(pid);
+        }
+        // 遍历全部步骤：子树保留 pending，祖先标 running（容器已进入态），其余标 skipped
+        for (const [stepId] of this.stepStates) {
+            if (subtreeIds.has(stepId))
+                continue; // 子树保持 pending
+            if (ancestorIds.has(stepId)) {
+                this.stepStates.set(stepId, 'running'); // 祖先容器：running 态让 dfsNextStep 递归进入
+            }
+            else {
+                this.stepStates.set(stepId, 'skipped');
+            }
+        }
+    }
+    findFirstFailedStep(steps) {
+        for (const step of steps) {
+            if (this.stepStates.get(step.step_id) === 'failed')
+                return step;
+        }
+        return null;
+    }
+    // propagateCompletion + 容器 done 记录:统一调用点,通过 newlyDone 通道捕获级联标 done 的容器,
+    // 逐个 recordStepDone(含容器声明的聚合输出,从父 scope 读)/Failed。
+    // 见 design/spec-observability.md ^anc-obs-step-done-timing。// @a: anc-obs-step-done-timing
+    propagateAndRecord(stepId) {
+        const newlyDone = [];
+        propagateCompletion(stepId, {
+            stepStates: this.stepStates,
+            variables: this.variables,
+            loopCounters: this.loopCounters,
+            newlyDone,
+        }, this.spec);
+        if (!this.hoplog)
+            return;
+        for (const { node, failed } of newlyDone) {
+            if (failed) {
+                this.hoplog.recordStepFailed(node.step_id, `container '${node.step_id}' failed`);
+            }
+            else {
+                const outputs = {};
+                if (node.outputs && node.outputs.length > 0) {
+                    const parentScope = getWriteScope(node.step_id, this.spec);
+                    for (const decl of node.outputs) {
+                        outputs[decl.name] = this.variables.read(decl.name, parentScope);
+                    }
+                }
+                this.hoplog.recordStepDone(node.step_id, Object.keys(outputs).length > 0 ? outputs : undefined);
+            }
+        }
+    }
+    // 返回 work_zone 工作区绝对路径,从 persistence 透传给 NextResponse 和 PromptAssembler。// @a: anc-exec-work-zone
+    getWorkZone() {
+        return this.persistence?.getWorkZone() ?? '';
+    }
+    // 直读 step 的 ← inputs 取原始值——绕过 PromptAssembler 截断/deflate,
+    // 用于 paused.context 等需要原始数据的人通道场景。// @a: anc-exec-audience-routing
+    resolveRawInputs(step) {
+        const result = {};
+        if (!step.inputs || !this.spec)
+            return result;
+        const scopeId = getWriteScope(step.step_id, this.spec);
+        for (const binding of step.inputs) {
+            result[binding.name] = this.variables.read(binding.source, scopeId);
+        }
+        return result;
+    }
+    // 大内容阈值传递:遍历 record,单个值 JSON.stringify().length > DEFLATE_THRESHOLD 时
+    // 写入 work_zone/vars/<key>.json,响应里替换为 {$file: abs_path} 指针。
+    // driver 遇 $file 时 Read 取真实值。见 design/shared-types.md ^anc-exec-deflate。
+    // @a: anc-exec-deflate
+    // namespace：可选子目录名，用于隔离共享 work_zone/vars 的多写者（见 ^anc-exec-deflate 多 child 命名空间隔离）。
+    // for-each 的 N 个 child 共享父 work_zone/vars 且 params_for_child 同名（itemVar），必须按 child_step_id 隔离，
+    // 否则超阈值的多个 child 写同一 vars/<name>.json 互相覆盖、$file 指针张冠李戴。
+    deflateValues(record, namespace) {
+        const workZone = this.getWorkZone();
+        if (!workZone)
+            return record; // 独立模式 work_zone 空,不做 deflate
+        const varsDir = namespace ? join(workZone, 'vars', namespace) : join(workZone, 'vars');
+        const result = {};
+        for (const [key, value] of Object.entries(record)) {
+            if (value === null || value === undefined) {
+                result[key] = value;
+                continue;
+            }
+            const serialized = JSON.stringify(value);
+            if (serialized.length > DEFLATE_THRESHOLD) {
+                const filePath = join(varsDir, `${key}.json`);
+                mkdirSync(varsDir, { recursive: true }); // namespace 子目录按需创建（vars/ 已由 initExecution 建）
+                writeFileSync(filePath, serialized, { mode: 0o600 });
+                result[key] = { $file: filePath };
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    // steps 缺省用 this.spec（运行期）；init 期 this.spec 未设，可显式传 ast.steps。
+    findStepById(stepId, steps) {
+        const search = (nodes) => {
+            for (const step of nodes) {
+                if (step.step_id === stepId)
+                    return step;
+                if (hasChildren(step)) {
+                    const found = search(getChildren(step));
+                    if (found)
+                        return found;
+                }
+            }
+            return null;
+        };
+        return search(steps ?? this.spec?.steps ?? []);
+    }
+    collectOutputs() {
+        const declared = this.spec?.header.outputs ?? [];
+        const result = {};
+        for (const decl of declared) {
+            const value = this.variables.read(decl.name, 'root');
+            result[decl.name] = value;
+            // worker 子实例(subtreeRoot)只负责子树,不检查父 spec 的顶层 Outputs(它们由父实例 join 后检查)
+            if ((value === null || value === undefined) && !this.subtreeRoot) {
+                this.recordEvent('', 'step_failed', `Output "${decl.name}" was never assigned (remains None)`);
+                this.hoplog?.recordWarn('', `Output "${decl.name}" declared in Outputs but never assigned`);
+            }
+        }
+        return result;
+    }
+    assembleBasicContext(step) {
+        const hasKnowledge = !!this.hostConfig?.knowledge_provider;
+        const assembler = new PromptAssembler(this, hasKnowledge);
+        const context = assembler.assembleReasonContext(step);
+        this.resolveStepDocRefs(step, context);
+        return context;
+    }
+    // doc-ref [[doc#章节]] 解析——两模式共享基座(assembleBasicContext)，复用模式也生效。
+    // 找不到文件/章节即抛 DocRefError（caller 在 nextStep 兜底 failStep）。// @a: anc-exec-doc-ref-resolve
+    resolveStepDocRefs(step, context) {
+        const host = this.hostConfig;
+        if (!host?.workspace_dir)
+            return; // 无 workspace（如纯 AST 测试）跳过
+        // spec 级（Constraints，对所有步骤可见）+ 步骤级，合并去重。
+        // minimal 非首步：跳过 spec 级 doc-ref（跨步不变，首步已给），仅保步骤级。见 ^anc-exec-context-mode。
+        // @a: anc-exec-context-mode
+        const lean = this.isMinimalNonFirst();
+        const specRefs = lean ? [] : (this.spec?.header.doc_refs ?? []);
+        const refs = [...specRefs, ...(step.doc_refs ?? [])];
+        if (refs.length === 0)
+            return;
+        const seen = new Set();
+        const uniq = refs.filter(r => {
+            const k = `${r.doc} ${r.section}`;
+            if (seen.has(k))
+                return false;
+            seen.add(k);
+            return true;
+        });
+        const fragments = resolveDocRefs(uniq, host.workspace_dir, host.sandbox, this.getWorkZone());
+        const text = formatDocRefContext(fragments);
+        if (text)
+            context.doc_ref_context = text;
+        // HopLog 流控字段延后记录——此刻 step 尚未 recordStepStart（在本方法之后），
+        // 立即 recordStepMeta 会被 guardOrphan 拦截。暂存，recordStepStart 后由 flushDocRefMeta 落账。
+        this.pendingDocRefSources = fragments.map(f => `${f.doc}#${f.section}`);
+    }
+    pendingDocRefSources = [];
+    // 在 recordStepStart 之后落 doc-ref 流控字段（绕开 guardOrphan 时序问题）。// @a: anc-exec-doc-ref-resolve
+    flushDocRefMeta(stepId) {
+        if (this.pendingDocRefSources.length === 0)
+            return;
+        const at = new Date().toISOString();
+        this.hoplog?.recordStepMeta(stepId, {
+            doc_refs: this.pendingDocRefSources.map(source_id => ({ source_id, at })),
+        });
+        this.pendingDocRefSources = [];
+    }
+    determineExecutionStatus() {
+        const steps = this.spec?.steps ?? [];
+        if (steps.length === 0)
+            return 'completed';
+        const allTerminal = this.allTopLevelTerminal(steps);
+        if (!allTerminal)
+            return 'running';
+        if (steps.some(s => this.stepStates.get(s.step_id) === 'failed'))
+            return 'failed';
+        return 'completed';
+    }
+    getFailureReason(stepId) {
+        return this.stepFailReasons.get(stepId)?.reason ?? 'Unknown failure';
+    }
+    handleFailStepRetry(stepId, reason) {
+        const subtask = this.findNearestSubtaskAncestor(stepId);
+        if (!subtask) {
+            this.propagateAndRecord(stepId);
+            return;
+        }
+        const retryMax = subtask.retry ?? 1;
+        if (!this.retryCounters.has(subtask.step_id)) {
+            this.retryCounters.set(subtask.step_id, retryMax);
+        }
+        const remaining = this.retryCounters.get(subtask.step_id);
+        if (remaining <= 0) {
+            this.markSubtaskFailed(subtask);
+            return;
+        }
+        this.retryCounters.set(subtask.step_id, remaining - 1);
+        // 已用失败次数（含本次）：第 1 次失败 attemptsUsed==1。升级阶梯按此判级。
+        const attemptsUsed = retryMax - remaining + 1;
+        const history = this.retryHistory.get(subtask.step_id) ?? [];
+        history.push({
+            attempt: attemptsUsed,
+            failure_reason: reason,
+            steps_tried: this.summarizeChildren(subtask),
+        });
+        this.retryHistory.set(subtask.step_id, history);
+        this.recordEvent(subtask.step_id, 'retry', `attempt ${attemptsUsed}/${retryMax}`);
+        // 升级阶梯（见概念 ^anc-exec-retry-adaptive / 设计 exec-engine fail_step 3.2/3.3）：
+        // retry=N 总失败预算。第 1 次失败 → 带反馈重跑（相同结构，失败说明经 L2c 注入，
+        // 见 prompt ^anc-exec-l2c-retry-feedback）；adaptive 且第 2 次起 → 重规划结构。
+        // 无 adaptive → 每次都机械重跑。 // @a: anc-exec-retry-adaptive
+        if (subtask.adaptive && attemptsUsed >= 2) {
+            this.adaptiveNeededSubtask = subtask.step_id;
+            return;
+        }
+        this.resetSubtaskForRetry(subtask);
+    }
+    // L2c 重试反馈源：返回 stepId 所在重试容器的最近一条失败说明（供 prompt 带反馈重跑）。
+    // 无重试容器或无重试历史 → undefined（首跑不渲染）。// @a: anc-exec-l2c-retry-feedback
+    getActiveRetryFeedback(stepId) {
+        const subtask = this.findNearestSubtaskAncestor(stepId);
+        if (!subtask)
+            return undefined;
+        const history = this.retryHistory.get(subtask.step_id);
+        if (!history || history.length === 0)
+            return undefined;
+        const last = history[history.length - 1];
+        return { attempt: last.attempt, reason: last.failure_reason };
+    }
+    // confirm answer 决策值提取：从 caller 注入的 answer 取 decision/value/answer 键或单值。
+    // 见 ^anc-exec-confirm-answer。
+    extractDecision(answer) {
+        if (!answer)
+            return undefined;
+        if ('decision' in answer)
+            return answer['decision'];
+        if ('value' in answer)
+            return answer['value'];
+        if ('answer' in answer)
+            return answer['answer'];
+        const vals = Object.values(answer);
+        return vals.length === 1 ? vals[0] : undefined;
+    }
+    // confirm approve → bool 槽写 true（纯审批闸门，+→ 仅 bool）。reject 已在调用处全局中止，到此必是 approve。
+    // 见 ^anc-exec-confirm-answer。
+    mapConfirmOutputs(node, answer, decision) {
+        const decls = node.outputs ?? [];
+        if (decls.length === 0)
+            return answer ?? {};
+        const mapped = {};
+        for (const d of decls) {
+            mapped[d.name] = true; // approve → bool true（confirm 收窄为纯审批，所有声明输出都是 bool 审批槽）
+        }
+        return mapped;
+    }
+    // ask answer → 数据值落到 +→ 声明变量名。caller answer 三种形态：
+    // ①{声明名:值} 直接采用 ②{value:值}/单值包装 → 落到首个声明名 ③approve/空 → 采用 default_value（前序推断）
+    // 见 ^anc-step-ask / ^anc-exec-hitl-presentation。// @a: anc-step-ask, anc-exec-hitl-presentation
+    mapAskOutputs(node, answer, stepId) {
+        const decls = node.outputs ?? [];
+        if (decls.length === 0)
+            return answer ?? {};
+        // ① answer 的 key 已匹配声明名 → 直接采用
+        if (answer && decls.some(d => d.name in answer))
+            return answer;
+        const raw = this.extractDecision(answer);
+        const mapped = {};
+        // ③ approve 快捷：采用 default_value（首个声明在前序产出中的同名推断值）
+        const isApproveShortcut = raw !== undefined && String(raw).toLowerCase() === 'approve';
+        for (const d of decls) {
+            if (isApproveShortcut) {
+                // 采用前序推断默认值（从当前 scope 自底向上读同名）
+                const scopeId = getWriteScope(stepId, this.spec);
+                mapped[d.name] = this.variables.read(d.name, scopeId);
+            }
+            else {
+                // ② 用 caller 提供的值
+                mapped[d.name] = raw;
+            }
+        }
+        return mapped;
+    }
+    // 重试容器祖先查找：subtask 或 case（case 就是 branch 下的 subtask，retry 语义相同）
+    findNearestSubtaskAncestor(stepId) {
+        let current = getParentStepId(stepId);
+        while (current) {
+            const step = this.findStepById(current);
+            if (step && (step.step_type === 'subtask' || step.step_type === 'case')) {
+                return step;
+            }
+            current = getParentStepId(current);
+        }
+        return null;
+    }
+    resetSubtaskForRetry(subtask) {
+        // Python 语义：仅重置 children 步骤状态为 pending；child 输出变量**不清空**（自然保留）。
+        // 重跑步骤用新产出覆盖旧值；需重跑前清空的量由作者在子步骤显式 `+ → x = Null`。
+        // 原"清 subtask scope 所有 child 输出"逻辑已删（与 loop 二分同源，属已废除的引擎隐式清空）。
+        // 见 [[exec-engine]] 变量作用域规则 6 / ^anc-exec-loop-var-scope。// @a: anc-exec-loop-var-scope
+        this.setSubtreePending(subtask.children);
+        this.stepStates.set(subtask.step_id, 'running');
+    }
+    markSubtaskFailed(subtask) {
+        if (subtask.outputs) {
+            const scopeId = getWriteScope(subtask.step_id, this.spec);
+            this.variables.setOutputsToNull(subtask.outputs, scopeId);
+        }
+        this.stepStates.set(subtask.step_id, 'failed');
+        this.recordStepFailure(subtask.step_id, 'retry exhausted');
+        this.propagateAndRecord(subtask.step_id);
+    }
+    removeChildStates(parent) {
+        if (!hasChildren(parent))
+            return;
+        for (const child of getChildren(parent)) {
+            this.stepStates.delete(child.step_id);
+            this.removeChildStates(child);
+        }
+    }
+    reIdSteps(steps, parentId) {
+        return steps.map((step, i) => {
+            const newId = `${parentId}.${i + 1}`;
+            const updated = { ...step, step_id: newId };
+            if (hasChildren(updated)) {
+                updated.children = this.reIdSteps(getChildren(updated), newId);
+            }
+            return updated;
+        });
+    }
+    skipAllDescendants(step) {
+        if (!hasChildren(step))
+            return;
+        for (const child of getChildren(step)) {
+            this.stepStates.set(child.step_id, 'skipped');
+            this.skipAllDescendants(child);
+        }
+    }
+    /** 把步骤节点投影为 StepSummary（step_id/type/summary/输出名）。单点定义——四处（adaptive
+     * original_children、replan 两处、summarizeChildren）复用，字段增减只改这里。 */
+    toStepSummary(node) {
+        return {
+            step_id: node.step_id,
+            step_type: node.step_type,
+            summary: node.summary,
+            outputs: (node.outputs ?? []).map(o => o.name),
+        };
+    }
+    summarizeChildren(subtask) {
+        return subtask.children.map(c => this.toStepSummary(c));
+    }
+    // 执行事件流——执行历史原料（L3 上下文重建用）。持久化到 state.json 的 exec_events，
+    // 跨进程续上 loop 迭代时序与子步状态。HopLog 另由 recordStepStart/Done/Failed 独立写入，不互为数据源。
+    recordEvent(stepId, event, detail) {
+        this.execEvents.push({ at: new Date().toISOString(), step_id: stepId, event, detail });
+    }
+    // 步骤失败：记事件流 + 存结构化失败原因（getFailureReason 的唯一来源，跨进程稳定）。
+    recordStepFailure(stepId, reason, failKind = 'error') {
+        this.recordEvent(stepId, 'step_failed', reason);
+        this.stepFailReasons.set(stepId, { reason, fail_kind: failKind });
+    }
+    persist() {
+        if (!this.persistence || !this.spec)
+            return;
+        this.persistence.saveSnapshot({
+            spec: this.spec,
+            state: this.buildStateFile(),
+            vars: { format_version: 2, scopes: this.variables.toJSON() },
+        });
+        this.hoplog?.flush();
+    }
+    buildStateFile() {
+        const step_states = {};
+        for (const [k, v] of this.stepStates)
+            step_states[k] = v;
+        const retry_counters = {};
+        for (const [k, v] of this.retryCounters)
+            retry_counters[k] = v;
+        const loop_counters = {};
+        for (const [k, v] of this.loopCounters)
+            loop_counters[k] = v;
+        const retry_history = {};
+        for (const [k, v] of this.retryHistory)
+            retry_history[k] = v;
+        const step_fail_reasons = {};
+        for (const [k, v] of this.stepFailReasons)
+            step_fail_reasons[k] = v;
+        return {
+            format_version: 1,
+            step_states,
+            retry_counters,
+            loop_counters,
+            ...(Object.keys(retry_history).length ? { retry_history } : {}),
+            ...(Object.keys(step_fail_reasons).length ? { step_fail_reasons } : {}),
+            ...(this.execEvents.length ? { exec_events: this.execEvents } : {}),
+            ...(this.logDir ? { log_dir: this.logDir } : {}),
+            ...(this.hoplog ? { hoplog_run_dir: this.hoplog.getRunDir() } : {}),
+            ...(this.adaptiveNeededSubtask ? { adaptive_needed_subtask: this.adaptiveNeededSubtask } : {}),
+            ...(this.canFanout ? { can_fanout: true } : {}),
+            ...(this.dispatched.size ? { dispatched: Object.fromEntries(this.dispatched) } : {}),
+            ...(this.specPath ? { spec_path: this.specPath } : {}),
+            ...(this.cliAbsPath ? { cli_abs_path: this.cliAbsPath } : {}),
+            ...(this.hostConfig?.resource_limits?.max_concurrent_workers != null
+                ? { max_concurrent: this.hostConfig.resource_limits.max_concurrent_workers }
+                : this.maxConcurrent != null ? { max_concurrent: this.maxConcurrent } : {}),
+            ...(this.contextMode === 'minimal' ? { context_mode: 'minimal' } : {}),
+            ...(this.subtreeRoot ? { subtree_root: this.subtreeRoot } : {}),
+            // doc-ref/P15 跨进程 resume 需 workspace+sandbox（不落凭证）。// @a: anc-exec-doc-ref-resolve
+            ...(this.hostConfig?.workspace_dir
+                ? { host_context: { workspace_dir: this.hostConfig.workspace_dir, sandbox: this.hostConfig.sandbox } }
+                : {}),
+        };
+    }
+    // 加载续执行：从快照重建引擎，保留 running 状态（已交付 caller、正等回写的合法持久态）。
+    // 复用模式日常命令（next/done/fail/status/vars/branch/replan）的入口。
+    // 概念见 [[HopSpec V3配套HopJIT运行时能力#^anc-exec-durable-resume]]。
+    static load(instanceDir) {
+        const persistence = new FilePersistence(instanceDir, true);
+        const snapshot = persistence.loadSnapshot();
+        const specData = snapshot.spec;
+        const varsData = snapshot.vars;
+        const stateData = snapshot.state;
+        const engine = new ExecutionEngine();
+        engine.spec = specData;
+        engine.persistence = persistence;
+        // vars.json v2：scope 树重建；v1（或无版本）：扁平变量塞 root（向后兼容）。
+        // 见 design/exec-engine.md ^anc-exec-vars-scope-persist。// @a: anc-exec-vars-scope-persist
+        engine.variables = varsData.format_version === 2 && varsData.scopes
+            ? VariableStore.fromScopes(varsData.scopes)
+            : VariableStore.fromJSON(varsData.variables ?? {});
+        // 原样重建 step_states——load 不重置 running（区别于 recover）
+        for (const [stepId, status] of Object.entries(stateData.step_states)) {
+            engine.stepStates.set(stepId, status);
+        }
+        for (const [k, v] of Object.entries(stateData.retry_counters)) {
+            engine.retryCounters.set(k, v);
+        }
+        for (const [k, v] of Object.entries(stateData.loop_counters)) {
+            engine.loopCounters.set(k, v);
+        }
+        if (stateData.retry_history) {
+            for (const [k, v] of Object.entries(stateData.retry_history)) {
+                engine.retryHistory.set(k, v);
+            }
+        }
+        if (stateData.step_fail_reasons) {
+            for (const [k, v] of Object.entries(stateData.step_fail_reasons)) {
+                // 兼容旧格式(string)和新格式(StepFailRecord)
+                engine.stepFailReasons.set(k, typeof v === 'string' ? { reason: v, fail_kind: 'error' } : v);
+            }
+        }
+        if (stateData.exec_events) {
+            engine.execEvents = [...stateData.exec_events];
+        }
+        if (stateData.adaptive_needed_subtask) {
+            engine.adaptiveNeededSubtask = stateData.adaptive_needed_subtask;
+        }
+        if (stateData.can_fanout) {
+            engine.canFanout = true;
+        }
+        if (stateData.dispatched) {
+            for (const [k, v] of Object.entries(stateData.dispatched))
+                engine.dispatched.set(k, [...v]);
+        }
+        if (stateData.spec_path)
+            engine.specPath = stateData.spec_path;
+        if (stateData.cli_abs_path)
+            engine.cliAbsPath = stateData.cli_abs_path;
+        if (stateData.max_concurrent != null)
+            engine.maxConcurrent = stateData.max_concurrent;
+        if (stateData.context_mode === 'minimal') {
+            engine.contextMode = 'minimal';
+        }
+        // env 覆盖持久值：任一 load 命令进程可临时调档（精度 env > state）。见 ^anc-exec-context-mode
+        const envMode = process.env['HOPJIT_CONTEXT_MODE']?.toLowerCase();
+        if (envMode === 'minimal' || envMode === 'full')
+            engine.contextMode = envMode;
+        if (stateData.subtree_root) {
+            engine.subtreeRoot = stateData.subtree_root;
+        }
+        // 恢复 host_context（workspace+sandbox），doc-ref/P15 跨进程必需。// @a: anc-exec-doc-ref-resolve
+        if (stateData.host_context) {
+            engine.hostConfig = {
+                workspace_dir: stateData.host_context.workspace_dir,
+                sandbox: stateData.host_context.sandbox,
+            };
+        }
+        // Rebuild HopLog if persisted // @a: anc-obs-hoplog-resume
+        if (stateData.hoplog_run_dir) {
+            engine.hoplog = HopLog.resume(stateData.hoplog_run_dir);
+            engine.logDir = stateData.log_dir ?? null;
+        }
+        const parts = instanceDir.split('/');
+        engine.instanceId = parts[parts.length - 1] || parts[parts.length - 2];
+        const parentDir = instanceDir.substring(0, instanceDir.lastIndexOf('/'));
+        engine.stateDir = parentDir;
+        engine.instanceDir = instanceDir;
+        return engine;
+    }
+    // 崩溃恢复：load + 将悬空 running 重置为 pending 幂等重跑。仅 `hopjit resume` 命令使用。
+    // 崩溃时的 running 无回写记录，是悬空的；branch 已选 case 的特例保留 running。
+    static recover(instanceDir) {
+        const engine = ExecutionEngine.load(instanceDir);
+        const snapshotStates = {};
+        for (const [k, v] of engine.stepStates)
+            snapshotStates[k] = v;
+        for (const [stepId, status] of Object.entries(snapshotStates)) {
+            if (status !== 'running')
+                continue;
+            // branch 已完成条件评估（有 skipped case）→ 保留 running，避免重新评估冲突
+            const step = engine.findStepById(stepId, engine.spec?.steps ?? []);
+            if (step && step.step_type === 'branch' && engine.hasBranchSelection(stepId, snapshotStates)) {
+                continue;
+            }
+            engine.stepStates.set(stepId, 'pending');
+        }
+        engine.persist();
+        return engine;
+    }
+    hasBranchSelection(branchId, states) {
+        // A branch has an active selection if any of its direct children are 'skipped'
+        const branch = this.findStepById(branchId, this.spec?.steps ?? []);
+        if (!branch || !hasChildren(branch))
+            return false;
+        return getChildren(branch).some(c => states[c.step_id] === 'skipped');
+    }
+    // --- P0-1: Check-finally preservation validation ---
+    validateCheckPreservation(originalChildren, newChildren) {
+        const originalHasCheck = this.hasCheckStep(originalChildren);
+        const originalFinallySteps = this.getCheckFinallySteps(originalChildren);
+        // Rule 1: If original has check steps, new must also have at least one check step
+        if (originalHasCheck && !this.hasCheckStep(newChildren)) {
+            return {
+                kind: 'validate',
+                rule: 'replan-check-required',
+                severity: 'error',
+                message: 'Replan must include at least one [check] step (original plan contained check steps)',
+            };
+        }
+        // Rule 2: If original has check-finally steps, new must preserve them at the end
+        if (originalFinallySteps.length > 0) {
+            const newTopLevel = newChildren;
+            if (newTopLevel.length === 0) {
+                return {
+                    kind: 'validate',
+                    rule: 'replan-check-finally',
+                    severity: 'error',
+                    message: 'Replan must preserve [check finally] step at the end (check finally cannot be removed)',
+                };
+            }
+            // Check that the last step(s) are check-finally
+            const lastStep = newTopLevel[newTopLevel.length - 1];
+            if (lastStep.step_type !== 'check' || !lastStep.is_finally) {
+                return {
+                    kind: 'validate',
+                    rule: 'replan-check-finally',
+                    severity: 'error',
+                    message: 'Replan must preserve [check finally] step at the end (check finally must be the last step)',
+                };
+            }
+        }
+        return null;
+    }
+    hasCheckStep(steps) {
+        for (const step of steps) {
+            if (step.step_type === 'check')
+                return true;
+            if (hasChildren(step)) {
+                if (this.hasCheckStep(getChildren(step)))
+                    return true;
+            }
+        }
+        return false;
+    }
+    getCheckFinallySteps(steps) {
+        const result = [];
+        for (const step of steps) {
+            if (step.step_type === 'check' && step.is_finally) {
+                result.push(step);
+            }
+            if (hasChildren(step)) {
+                result.push(...this.getCheckFinallySteps(getChildren(step)));
+            }
+        }
+        return result;
+    }
+    // --- P0-2: Replan similarity detection ---
+    isReplanDuplicate(previous, current) {
+        // Condition 1: Same number of steps
+        if (previous.length !== current.length)
+            return false;
+        // Condition 2: Same step type distribution
+        const prevTypes = previous.map(s => s.step_type).sort().join(',');
+        const currTypes = current.map(s => s.step_type).sort().join(',');
+        if (prevTypes !== currTypes)
+            return false;
+        // Condition 3: Summary text similarity > 80% (Jaccard on words)
+        const prevText = previous.map(s => s.summary).join(' ');
+        const currText = current.map(s => s.summary).join(' ');
+        const similarity = this.jaccardSimilarity(prevText, currText);
+        return similarity > 0.8;
+    }
+    jaccardSimilarity(a, b) {
+        const tokenize = (text) => new Set(text.toLowerCase().split(/\s+/).filter(w => w.length > 0));
+        const setA = tokenize(a);
+        const setB = tokenize(b);
+        if (setA.size === 0 && setB.size === 0)
+            return 1;
+        let intersection = 0;
+        for (const word of setA) {
+            if (setB.has(word))
+                intersection++;
+        }
+        const union = setA.size + setB.size - intersection;
+        if (union === 0)
+            return 1;
+        return intersection / union;
+    }
+}