minimal-agent 0.8.2 → 0.10.0

package/plugins/workflow-runner/src/runner.js

@@ -11,29 +11,31 @@
  *
  *  支持的 step kind（loader 已校验）：
  *    - tool / llm / assert            —— 原子动作（execXxxStep 返回 StepResult）
- *    - agent / skill                  —— 有界 TAOR：miniReAct(agent) / 外部 SKILL.md(skill)；
+ *    - agent / skill                  —— 有界 TAOR：runQuery(agent) / runQuery(skill)；
  *                                        透传子事件（stage_change/text/reasoning/tool_*）
- *    - branch / loop / pause          —— 控制流，直接在 runSteps 内处理（不走 executor）
- *    - parallel / vote                —— 并发 / 投票门，也在 runSteps 内处理
+ *    - branch / loop / pause / echo   —— 控制流，直接在 runSteps 内处理（不走 executor）
+ *    - break / continue               —— 循环信号（可带 target 穿透到指定外层循环）
  *
  *  控制流嵌套通过 runSteps 递归实现：branch.then/else / loop.do 子数组
  *  是 StepDef[]，调用方语义与顶层 def.steps 一致；变量栈用 VarStack.push/pop
  *  在 loop 迭代间隔离 `${as}` / `${as}_idx`。
  * ============================================================
  */
-import { getWorkingDir } from '../../../src/plugin-sdk.js';
-import { dlog } from '../../../src/utils/debugLog.js';
-import { evalExpr, interpolate } from './expressions.js';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { dlog, executeTool, getWorkingDir } from '../../../src/plugin-sdk.js';
+import { isMaxTurnsCutoff, truncate } from './agentCommon.js';
+import { evalExpr, interpolate, interpolateDeep, interpolateTyped } from './expressions.js';
 import { runRecovery } from './recovery.js';
+import { buildTaskArbitrator, isContinuationPhrase } from './taskIdentity.js';
 import { execAgentStep } from './stepExecutors/agent.js';
 import { execAssertStep } from './stepExecutors/assert.js';
 import { execVerifyStep } from './stepExecutors/verify.js';
 import { execLlmStep } from './stepExecutors/llm.js';
 import { execSkillStep } from './stepExecutors/skill.js';
 import { execToolStep } from './stepExecutors/tool.js';
-import { VarStack } from './types.js';
-import { runVoter } from './voteHelpers.js';
-import { WorkflowState } from './workflowState.js';
+import { normalizeCapture, VarStack } from './types.js';
+import { loopCheckpointName, WorkflowState, } from './workflowState.js';
 /**
  * 插件 ID：把私有 workflow_* 事件镜像成框架通用 plugin_progress 时挂这个 id。
  * LiveArea 状态行会渲染成 "[plugin:workflow-runner] i/total <message>"
@@ -41,7 +43,78 @@ import { WorkflowState } from './workflowState.js';
  * （-p 非交互模式另由 src/cli/print.ts 把通用 warning 事件落 stderr。）
  */
 const WF_PLUGIN_ID = 'workflow-runner';
+/**
+ * 从工作流 inputs 定义 + 实际值中提取用户的原始目标，
+ * 构建紧凑的目标锚定字符串。
+ *
+ * 提取策略：
+ *   1. 优先取名为 "goal" 的输入（plan.yaml / ralph-loop.yaml 等通用约定）
+ *   2. 其次取第一个 required: true 的 string 类型输入
+ *   3. 都没有 → 返回空字符串（executor 自动跳过）
+ *
+ * 锚定字符串格式紧凑（~60-150 字符），注入每步 prompt 前置，
+ * 确保 LLM 在任何步骤都能"看到"用户原始目标，避免长上下文稀释。
+ */
+function buildGoalAnchor(inputDefs, inputValues) {
+    let goalValue;
+    // 策略 1：优先 "goal"
+    const goalInput = inputDefs.find((d) => d.name === 'goal' && d.type === 'string');
+    if (goalInput) {
+        const v = inputValues[goalInput.name];
+        if (typeof v === 'string' && v.trim()) {
+            goalValue = v.trim();
+        }
+    }
+    // 策略 2：fallback 第一个 required string
+    if (!goalValue) {
+        const firstRequired = inputDefs.find((d) => d.required && d.type === 'string');
+        if (firstRequired) {
+            const v = inputValues[firstRequired.name];
+            if (typeof v === 'string' && v.trim()) {
+                goalValue = v.trim();
+            }
+        }
+    }
+    if (!goalValue)
+        return '';
+    return `> 🎯 用户原始目标：${truncateGoal(goalValue)}\n> ⚠️ 所有操作必须直接回应此目标，不可偏离或遗忘。`;
+}
+/** 截断过长目标（>200 字符时保留首尾，中间用 … 连接）——goalAnchor 注入每步 prompt，必须紧凑。 */
+function truncateGoal(goal) {
+    return goal.length > 200 ? `${goal.slice(0, 120)}…${goal.slice(-60)}` : goal;
+}
+/** 可中断的退避等待：用户 abort 时立即返回（让后续步骤检查 signal 收口，不在这里抛）。 */
+function sleepInterruptible(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** 把一段用户输入并入贯穿目标（内存 + 状态目录持久化，resume 不丢）。 */
+async function addGoalSupplement(ctx, state, text) {
+    const t = text.trim();
+    if (!t)
+        return;
+    // 锚定必须紧凑（注入每步 prompt），逐条截断；完整原文在 capture 变量 / history 里
+    const compact = t.length > 240 ? `${t.slice(0, 240)}…` : t;
+    ctx.goalSupplements ??= [];
+    ctx.goalSupplements.push(compact);
+    await state.appendSupplement(compact);
+}
 function stepKind(step) {
+    if (step.type === 'break')
+        return 'break';
     if (step.type)
         return step.type;
     if (step.tool)
@@ -65,20 +138,41 @@ function readPath(root, path) {
     return cur;
 }
 function bindCapture(captureMap, result, vars) {
-    for (const [resultField, varName] of Object.entries(captureMap)) {
+    for (const [resultField, varName] of Object.entries(normalizeCapture(captureMap))) {
         const value = resultField.includes('.')
             ? readPath(result.raw, resultField)
             : result.raw[resultField];
         vars.set(varName, value);
     }
 }
+/** 取本步 capture 出的 { varName: value }，供 checkpoint 记录（resume 回放用）。 */
+function collectCaptured(captureMap, vars) {
+    const out = {};
+    for (const varName of Object.values(normalizeCapture(captureMap))) {
+        out[varName] = vars.get(varName);
+    }
+    return out;
+}
+function resolvePositiveIterationLimit(raw, vars, defaultValue, label) {
+    if (raw === undefined)
+        return { ok: true, value: defaultValue };
+    const interpolated = typeof raw === 'number' ? raw : interpolate(String(raw), vars);
+    const n = typeof raw === 'number' ? raw : Number(String(interpolated).trim());
+    if (!Number.isFinite(n) || n <= 0) {
+        return {
+            ok: false,
+            error: `${label} max_iterations parse failed: ${JSON.stringify(raw)} -> "${String(interpolated)}" is not a positive number`,
+        };
+    }
+    return { ok: true, value: Math.floor(n) };
+}
 /**
  * 分发"动作"型 step（tool / agent / llm / skill / assert）到对应 executor。
- * 控制流 step（branch / loop / pause / parallel / vote）由 runSteps 直接处理，不走这里。
+ * 控制流 step（branch / loop / pause 等）由 runSteps 直接处理，不走这里。
  */
 async function* dispatchActionStep(step, vars, ctx) {
     if (step.type === 'assert')
-        return execAssertStep(step, vars);
+        return execAssertStep(step, vars, ctx);
     if (step.type === 'verify')
         return await execVerifyStep(step, vars);
     if (step.tool)
@@ -92,17 +186,34 @@ async function* dispatchActionStep(step, vars, ctx) {
     throw new Error(`step ${step.id}: 无可执行字段（tool/agent/llm/skill/assert/verify）`);
 }
 /**
- * 递归执行 steps[]。返回 true 表示该 block 已 halt（上游应中止）。
+ * 递归执行 steps[]。返回 StepFlow（completed / halted / break|continue 信号，见上方定义）。
  *
  * yields 混合事件：WorkflowEvent + LoopEvent（skill 子循环转发 / error / interrupted）。
  * index/total 字段相对**当前 block**，嵌套 block 自有计数（branch.then 内 3 步就报 total=3）。
  */
-async function* runSteps(steps, vars, ctx, state) {
+async function* runSteps(steps, vars, ctx, state, 
+// checkpoint 记录范围：顶层调用（runWorkflow → def.steps）传 { name: id=>id, descendIntoLoop:true }；
+// 顶层 loop 的 do[] 由 loop 处理器派生复合名 scope；更深嵌套传 undefined（不记录）。
+cp, 
+// resume：本列表中索引 < startFrom 的步已在上次运行完成，本次跳过（变量已由 runWorkflow 回放）。
+// 顶层与「loop resume 进迭代中间」（loop 处理器对 do[] 传 innerStartFrom）都用它。
+startFrom = 0, 
+// 仅顶层传：进行中循环的恢复信息（迭代号 + 迭代内起点），由匹配 id 的 loop 消费一次。
+loopResume) {
     for (let i = 0; i < steps.length; i++) {
         const step = steps[i];
         if (ctx.signal?.aborted) {
             yield { type: 'interrupted' };
-            return true;
+            return 'halted';
+        }
+        // resume：跳过已完成的步（变量已回放，无需重跑）。
+        if (i < startFrom) {
+            yield {
+                type: 'workflow_step_skipped',
+                id: step.id,
+                reason: 'resume: 上次已完成',
+            };
+            continue;
         }
         // when 条件
         if (step.when) {
@@ -122,7 +233,7 @@ async function* runSteps(steps, vars, ctx, state) {
                     type: 'error',
                     error: `Workflow halted at step "${step.id}": ${errMsg}`,
                 };
-                return true;
+                return 'halted';
             }
             if (!pass) {
                 yield {
@@ -136,23 +247,39 @@ async function* runSteps(steps, vars, ctx, state) {
         }
         const kind = stepKind(step);
         dlog('wf', `step ${i + 1}/${steps.length} START ${step.id} (${kind})`);
+        // 已插值的人话进度名随 start 事件带给 UI：scrollback 进度行显示它而非块内相对
+        // 序号，与状态行（下方 plugin_progress）保持一致。未声明 title 的步省略此字段。
+        const interpolatedTitle = step.title
+            ? interpolate(step.title, vars)
+            : undefined;
         yield {
             type: 'workflow_step_start',
             id: step.id,
             kind,
             index: i,
             total: steps.length,
+            title: interpolatedTitle,
         };
-        // P1 TUI 可见：把私有 workflow_step_start 镜像成框架通用 plugin_progress，
-        // LiveArea 状态行渲染成 "[plugin:workflow-runner] i/total step <id> (<kind>)"。
-        // （嵌套 block 的 i/total 相对当前 block，足够给"跑到哪一步"的实时反馈。）
-        yield {
-            type: 'plugin_progress',
-            pluginId: WF_PLUGIN_ID,
-            current: i + 1,
-            max: steps.length,
-            message: `step ${step.id} (${kind})`,
-        };
+        // P1 TUI 可见：把私有 workflow_step_start 镜像成框架通用 plugin_progress。
+        // 有 title 的步显示人话阶段名（如「阶段2/6·起草实现计划」）且不带块内序号——
+        // 嵌套块的 i/total（顶层 5、循环体 12…）会被用户误读成"跳步/结构乱"；
+        // 未声明 title 的步保持 legacy 格式 "i/total step <id> (<kind>)"。
+        if (interpolatedTitle) {
+            yield {
+                type: 'plugin_progress',
+                pluginId: WF_PLUGIN_ID,
+                message: interpolatedTitle,
+            };
+        }
+        else {
+            yield {
+                type: 'plugin_progress',
+                pluginId: WF_PLUGIN_ID,
+                current: i + 1,
+                max: steps.length,
+                message: `step ${step.id} (${kind})`,
+            };
+        }
         // ---------- 控制流：branch ----------
         if (step.type === 'branch') {
             let cond = false;
@@ -164,13 +291,14 @@ async function* runSteps(steps, vars, ctx, state) {
                 await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
                 yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
                 yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return true;
+                return 'halted';
             }
             const branch = cond ? step.then : step.else;
             if (Array.isArray(branch) && branch.length > 0) {
-                const childHalted = yield* runSteps(branch, vars, ctx, state);
-                if (childHalted)
-                    return true;
+                // branch 对 break 透明：子块 break/halt 都原样上抛给最近的循环 / 顶层。
+                const r = yield* runSteps(branch, vars, ctx, state);
+                if (r !== 'completed')
+                    return r;
             }
             await state.appendProgress(`✓ ${step.id} (branch=${cond})`);
             await state.writeVars(vars.snapshot());
@@ -182,8 +310,170 @@ async function* runSteps(steps, vars, ctx, state) {
             };
             continue;
         }
-        // ---------- 控制流：loop ----------
+        // ---------- 控制流：set（确定性变量赋值） ----------
+        //
+        // 状态机类工作流（如 ralph-loop 的 phase）必须用 set——曾有 yaml 用
+        // `llm: "PLAN"` 当赋值语句：真把 "PLAN" 发给模型、capture 模型自由回复，
+        // 变量值非确定，下游 phase == 'PLAN' 比较全部不可靠。
+        if (step.type === 'set') {
+            const missing = [];
+            // 顶层值若是单一 "${EXPR}" 模板走 interpolateTyped 保留类型（布尔/数字/数组
+            // 不再字符串化成 "true"，下游条件不必写 == true || == 'true' 防御）；
+            // 多片段模板与嵌套结构行为不变（interpolateDeep）。
+            const resolved = {};
+            for (const [k, v] of Object.entries(step.set ?? {})) {
+                resolved[k] =
+                    typeof v === 'string'
+                        ? interpolateTyped(v, vars, { onMissing: (e) => missing.push(e) })
+                        : interpolateDeep(v, vars, { onMissing: (e) => missing.push(e) });
+            }
+            if (missing.length > 0) {
+                yield {
+                    type: 'warning',
+                    message: `step "${step.id}": 模板变量未定义：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}（裸名请用 inputs.<name> 或先 capture/set）`,
+                };
+            }
+            for (const [k, v] of Object.entries(resolved)) {
+                vars.setGlobal(k, v);
+            }
+            const summary = Object.entries(resolved)
+                .map(([k, v]) => `${k}=${String(v).slice(0, 40)}`)
+                .join(', ');
+            await state.appendProgress(`✓ ${step.id} (set ${summary})`);
+            await state.writeVars(vars.snapshot());
+            // set 记 checkpoint（值入 captures）：resume 跳过它时变量仍能回放
+            if (cp) {
+                await state.recordCheckpoint(cp.name(step.id), `set: ${summary}`, resolved, vars.snapshot());
+            }
+            yield {
+                type: 'workflow_step_end',
+                id: step.id,
+                ok: true,
+                output: `set: ${summary}`,
+            };
+            continue;
+        }
+        // ---------- 控制流：loop（for-each 或 while） ----------
         if (step.type === 'loop') {
+            const isWhileMode = step.over === undefined;
+            // max_iterations 支持 ${} 模板（如 "${inputs.max_iterations}"）：插值 + coerce；
+            // 失败响亮 halt——曾有模板字符串不插值直接参与 < 比较 → NaN → 静默 0 次迭代。
+            let maxIter = 200; // while 模式安全上限（缺省）
+            if (step.max_iterations !== undefined) {
+                const raw = step.max_iterations;
+                const n = typeof raw === 'number'
+                    ? raw
+                    : Number(interpolate(String(raw), vars).trim());
+                if (!Number.isFinite(n) || n <= 0) {
+                    const errMsg = `loop "${step.id}" 的 max_iterations 解析失败：${JSON.stringify(raw)} → "${typeof raw === 'string' ? interpolate(String(raw), vars) : raw}" 不是正数（检查变量是否存在，裸名请用 inputs.<name>）`;
+                    yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
+                    yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
+                    return 'halted';
+                }
+                maxIter = Math.floor(n);
+            }
+            const useFreshContext = step.fresh_context === true;
+            // fresh context：循环开始时 snapshot 当前 history
+            let baseHistorySnapshot = null;
+            if (useFreshContext) {
+                baseHistorySnapshot = ctx.history.slice();
+            }
+            // loop resume：恢复信息匹配本循环时消费一次——从中断时的迭代号起跑，
+            // 该迭代内已完成的步经 innerStartFrom 跳过（变量已由 runWorkflow 回放快照）。
+            let resumeIterStart = 0;
+            let pendingInnerStart = 0;
+            if (loopResume && loopResume.loopId === step.id) {
+                resumeIterStart = loopResume.iteration;
+                pendingInnerStart = loopResume.innerStartFrom;
+                loopResume = undefined;
+                yield {
+                    type: 'warning',
+                    message: `♻ 循环 ${step.id} 从第 ${resumeIterStart + 1} 轮迭代第 ${pendingInnerStart + 1} 步续跑。`,
+                };
+            }
+            // 顶层 loop 的 do[] 步记复合 checkpoint（loopId@@迭代号@@stepId），
+            // resume 可恢复到迭代中间；更深嵌套不再下钻（descendIntoLoop=false）。
+            const innerCpFor = (iter) => cp?.descendIntoLoop
+                ? {
+                    name: (id) => loopCheckpointName(step.id, iter, id),
+                    descendIntoLoop: false,
+                }
+                : undefined;
+            if (isWhileMode) {
+                // ===== WHILE 循环模式 =====
+                const asName = step.as ?? '_iter';
+                let iterCount = resumeIterStart;
+                let shouldBreak = false;
+                while (iterCount < maxIter) {
+                    if (ctx.signal?.aborted) {
+                        yield { type: 'interrupted' };
+                        return 'halted';
+                    }
+                    // 注入迭代变量
+                    vars.push();
+                    vars.set(asName, iterCount);
+                    vars.set(`${asName}_idx`, iterCount);
+                    // fresh context：每轮重置 history 到循环入口快照
+                    if (useFreshContext && baseHistorySnapshot) {
+                        ctx.history.length = 0;
+                        ctx.history.push(...baseHistorySnapshot);
+                    }
+                    // 迭代序号对用户有真实意义（第几轮重做），title 步也保留，只换人话名。
+                    yield {
+                        type: 'plugin_progress',
+                        pluginId: WF_PLUGIN_ID,
+                        current: iterCount + 1,
+                        max: maxIter,
+                        message: step.title
+                            ? `${interpolate(step.title, vars)}·第 ${iterCount + 1}/${maxIter} 轮`
+                            : `while-loop ${step.id} 迭代 ${iterCount + 1}/${maxIter}`,
+                    };
+                    // 第 2+ 轮额外发持久 warning：上面的状态行 progress 会被首步 title 立即
+                    // 覆盖（驻留一瞬），用户感知不到「循环重来了」——曾有 plan 工作流验收
+                    // 打回静默重启，被用户误读成死循环。while 模式的多轮 = 重做/重试，
+                    // 值得进 MessageList 留痕；for-each 的逐元素迭代是正常推进，不发。
+                    if (iterCount > 0) {
+                        yield {
+                            type: 'warning',
+                            message: `♻ 循环「${step.title ? interpolate(step.title, vars) : step.id}」进入第 ${iterCount + 1}/${maxIter} 轮`,
+                        };
+                    }
+                    const innerStart = pendingInnerStart;
+                    pendingInnerStart = 0; // 仅 resume 后的首个迭代生效
+                    const r = yield* runSteps(step.do ?? [], vars, ctx, state, innerCpFor(iterCount), innerStart);
+                    vars.pop();
+                    iterCount++;
+                    // halt（error/interrupt/onError:halt）→ 真正向上中止整个工作流。
+                    if (r === 'halted')
+                        return 'halted';
+                    if (typeof r === 'object') {
+                        // 带 target 且不是本循环 → 穿透上抛给外层循环
+                        if (r.target !== undefined && r.target !== step.id)
+                            return r;
+                        if (r.signal === 'break') {
+                            shouldBreak = true;
+                            break;
+                        }
+                        // continue → 跳到下一轮迭代（什么都不做，自然进入下一轮）
+                    }
+                }
+                const whyEnd = shouldBreak ? 'break 退出' : `达到上限 ${maxIter}`;
+                await state.appendProgress(`✓ ${step.id} (while ×${iterCount}, ${whyEnd})`);
+                await state.writeVars(vars.snapshot());
+                // 循环完成记自身 checkpoint：resume 据此判定「循环已整体完成」（否则
+                // 中断在循环之后的步骤时，resume 会误把整条循环从头重跑）。
+                if (cp) {
+                    await state.recordCheckpoint(cp.name(step.id), `while loop ${iterCount} iterations (${whyEnd})`, collectCaptured(step.capture, vars), vars.snapshot());
+                }
+                yield {
+                    type: 'workflow_step_end',
+                    id: step.id,
+                    ok: true,
+                    output: `while loop ${iterCount} iterations (${whyEnd})`,
+                };
+                continue;
+            }
+            // ===== FOR-EACH 循环模式（原有逻辑） =====
             let arr;
             try {
                 arr = evalExpr(step.over ?? '[]', vars);
@@ -193,33 +483,50 @@ async function* runSteps(steps, vars, ctx, state) {
                 await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
                 yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
                 yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return true;
+                return 'halted';
             }
             if (!Array.isArray(arr)) {
                 const errMsg = `loop over 必须求值为数组，得到 ${typeof arr}`;
                 await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
                 yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
                 yield { type: 'error', error: `Workflow halted at step "${step.id}": ${errMsg}` };
-                return true;
+                return 'halted';
             }
             const asName = step.as ?? 'item';
             let iterCount = 0;
-            for (let idx = 0; idx < arr.length; idx++) {
+            for (let idx = resumeIterStart; idx < arr.length; idx++) {
                 if (ctx.signal?.aborted) {
                     yield { type: 'interrupted' };
-                    return true;
+                    return 'halted';
                 }
                 vars.push();
                 vars.set(asName, arr[idx]);
                 vars.set(`${asName}_idx`, idx);
-                const childHalted = yield* runSteps(step.do ?? [], vars, ctx, state);
+                // fresh context 也支持 for-each 模式
+                if (useFreshContext && baseHistorySnapshot) {
+                    ctx.history.length = 0;
+                    ctx.history.push(...baseHistorySnapshot);
+                }
+                const innerStart = pendingInnerStart;
+                pendingInnerStart = 0;
+                const r = yield* runSteps(step.do ?? [], vars, ctx, state, innerCpFor(idx), innerStart);
                 vars.pop();
-                if (childHalted)
-                    return true;
                 iterCount++;
+                if (r === 'halted')
+                    return 'halted';
+                if (typeof r === 'object') {
+                    if (r.target !== undefined && r.target !== step.id)
+                        return r; // 穿透上抛
+                    if (r.signal === 'break')
+                        break; // 跳出 for-each，循环后兄弟步继续
+                    // continue → 下一个元素
+                }
             }
             await state.appendProgress(`✓ ${step.id} (loop ×${iterCount})`);
             await state.writeVars(vars.snapshot());
+            if (cp) {
+                await state.recordCheckpoint(cp.name(step.id), `loop ${iterCount} 次`, collectCaptured(step.capture, vars), vars.snapshot());
+            }
             yield {
                 type: 'workflow_step_end',
                 id: step.id,
@@ -228,258 +535,379 @@ async function* runSteps(steps, vars, ctx, state) {
             };
             continue;
         }
-        // ---------- 控制流：pause ----------
+        // ---------- 控制流：pause（真 HITL 审批闸门） ----------
         //
-        // 非交互模式（CLI -p / 测试）下无法真的暂停等待人工，直接当成 skipped。
-        // 交互模式（TUI）需要 UI 层接住 step_skipped 把 reason 渲染出来 —— P0 已
-        // 走通这条 UI 路径。step.prompt 用于把"暂停理由"传给上层呈现。
+        // 经 AskUserQuestion/askBridge 实现真停等：TUI 弹选择界面、用户拍板后继续；
+        // 非交互宿主（-p/gateway/测试）askBridge 自动选推荐项（继续执行）且 stderr
+        // 注记，绝不挂起——与 -p 单行 JSON 契约兼容。「等用户」骑在既有
+        // tool_call→tool_result 回路上（同 AskUserQuestion 工具），引擎零新通道。
         if (step.type === 'pause') {
             const msg = step.prompt
                 ? interpolate(step.prompt, vars)
-                : 'pause（非交互模式直接跳过）';
-            await state.appendProgress(`- ${step.id} pause: ${msg}`);
-            // P3：pause 在当前实现下**从不**真正等待人工（runner 是纯 AsyncGenerator，
-            // 没有把用户输入回灌进来的通道）。把"静默放行"变"响亮放行"——发通用 warning
-            // （-p 模式由 print.ts 落 stderr，权威通道）并镜像 plugin_progress（TUI 状态行可见），
-            // 避免审批闸门被悄悄跳过。真·HITL pause 属 P4，本轮不做。
-            const warnMsg = `⚠ pause "${step.id}" 在非交互模式被自动跳过，未真正等待人工确认——若这是审批闸门请勿依赖它。提示：${msg}`;
-            yield { type: 'warning', message: warnMsg };
-            yield {
-                type: 'plugin_progress',
-                pluginId: WF_PLUGIN_ID,
-                current: 0,
-                message: warnMsg,
-            };
-            yield {
-                type: 'workflow_step_skipped',
-                id: step.id,
-                reason: `pause: ${msg}`,
-            };
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: 'paused (skipped in non-interactive mode)',
-            };
-            continue;
-        }
-        // ---------- 控制流：parallel ----------
-        //
-        // 每个 fork 独立 VarStack 副本 + 独立事件缓冲；Promise.all 并发执行。
-        // 子 fork 的事件先收进 buffer，再按 fork 顺序一次性 yield，保 UI
-        // 时间轴可读（并发 yield 会导致 UI 拿到乱序事件）。
-        // 任一 fork halt → 整个 parallel halt。
-        if (step.type === 'parallel') {
-            const forks = step.fork ?? [];
-            const results = await Promise.all(forks.map(async (forkStep) => {
-                const forkVars = vars.fork();
-                const events = [];
-                let halted = false;
-                try {
-                    halted = await collectStepsToBuffer([forkStep], forkVars, ctx, state, events);
-                }
-                catch (e) {
-                    halted = true;
-                    events.push({
-                        type: 'error',
-                        error: `fork ${forkStep.id} 抛异常: ${e.message}`,
-                    });
-                }
-                return {
-                    id: forkStep.id,
-                    events,
-                    vars: forkVars.snapshot(),
-                    halted,
-                };
-            }));
-            // 顺序 yield 所有 fork 事件
-            for (const r of results) {
-                for (const ev of r.events)
-                    yield ev;
-            }
-            if (results.some((r) => r.halted)) {
-                await state.appendProgress(`✗ ${step.id}: parallel: 至少一个 fork 失败`);
+                : '工作流暂停点：请确认是否继续执行后续步骤。';
+            await state.appendProgress(`- ${step.id} pause: 等待用户确认`);
+            // pause 会驻留状态行很久（等用户），title 步同样不带块内序号防误读。
+            if (step.title) {
                 yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: false,
-                    error: 'parallel: 至少一个 fork 失败',
+                    type: 'plugin_progress',
+                    pluginId: WF_PLUGIN_ID,
+                    message: `⏸ ${interpolate(step.title, vars)}：等待用户确认…`,
                 };
+            }
+            else {
                 yield {
-                    type: 'error',
-                    error: `Workflow halted at step "${step.id}": parallel: 至少一个 fork 失败`,
+                    type: 'plugin_progress',
+                    pluginId: WF_PLUGIN_ID,
+                    current: i + 1,
+                    max: steps.length,
+                    message: `⏸ 审批闸门 ${step.id}：等待用户确认…`,
                 };
-                return true;
             }
-            // 聚合：raw.fork 是 [{ id, vars }, ...]，capture 可走 fork.0.vars.xxx 这种点路径
-            const aggResult = {
-                raw: { fork: results.map((r) => ({ id: r.id, vars: r.vars })) },
-                preview: `parallel: ${results.length} forks done`,
-            };
-            if (step.capture)
-                bindCapture(step.capture, aggResult, vars);
-            await state.appendProgress(`✓ ${step.id} (parallel ×${results.length})`);
-            await state.writeVars(vars.snapshot());
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: true,
-                output: aggResult.preview,
-            };
-            continue;
-        }
-        // ---------- 控制流：vote ----------
-        //
-        // 对每个 input 数组项跑 N 个 voter（同 prompt + refuted: boolean），
-        // refuted 票数 >= threshold 则视为驳回（item 不进 survived）。
-        // 心理学定位：voter 倾向于 refuted=true（找漏洞），所以阈值算"驳回票数"。
-        if (step.type === 'vote') {
-            const voters_count = step.voters_count ?? 3;
-            const threshold = step.threshold ?? Math.ceil(voters_count / 2);
-            let inputArr;
+            const exec = ctx.executeTool ?? executeTool;
+            // 审批语义：明确选「继续」才放行；选「停止」、取消提问（ESC）、或自由输入
+            // 其它内容（既非继续也非停止 = 用户想先改点什么）都不放行（审批门上的
+            // 含糊 = 不批准，保守处理）；桥本身异常才兜底放行（保持可用性）。
+            let approved = true;
+            let askFailed = false;
+            let freeText = '';
+            const freeTextMode = step.free_text ?? 'halt';
             try {
-                inputArr = evalExpr(step.input ?? '[]', vars);
+                const r = await exec('AskUserQuestion', JSON.stringify({
+                    questions: [
+                        {
+                            question: truncate(msg, 400),
+                            header: '审批闸门',
+                            options: [
+                                { label: '继续执行 (推荐)', description: '放行后续步骤' },
+                                {
+                                    label: '停止（保留现场）',
+                                    description: '中止本次运行；同任务重跑可从断点 resume',
+                                },
+                            ],
+                        },
+                    ],
+                }), ctx.signal);
+                // ⚠️ 只解析【答案行】（"A1: …"）——回执里 Q 行带着问题原文，
+                // 工作流的 pause 提示语若含「停止」字样（如 plan.yaml 的说明文字），
+                // 看整个 content 会把用户选的「继续」误判成停止（曾是真事故）。
+                const answerText = r.ok
+                    ? r.content
+                        .split('\n')
+                        .map((l) => l.trim())
+                        .filter((l) => /^A\d+[:：]/.test(l))
+                        .join('\n')
+                    : '';
+                if (!r.ok || answerText.includes('停止')) {
+                    approved = false;
+                }
+                else if (answerText.includes('继续')) {
+                    approved = true;
+                }
+                else {
+                    // 自由输入（「其他」逃生项）：用户想先调整 → 不放行，把原话带进 halt 文案
+                    freeText = answerText.replace(/^A\d+[:：]\s*/, '');
+                    approved = freeTextMode === 'approve';
+                }
             }
-            catch (e) {
-                const errMsg = `vote.input 求值失败: ${e.message}`;
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
-                yield {
-                    type: 'error',
-                    error: `Workflow halted at step "${step.id}": ${errMsg}`,
-                };
-                return true;
+            catch {
+                askFailed = true; // 桥不可用 → 放行 + 响亮警告（保持旧"不挂起"行为）
             }
-            if (!Array.isArray(inputArr)) {
-                const errMsg = `vote.input 必须求值为数组，得到 ${typeof inputArr}`;
-                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-                yield { type: 'workflow_step_end', id: step.id, ok: false, error: errMsg };
+            if (askFailed) {
                 yield {
-                    type: 'error',
-                    error: `Workflow halted at step "${step.id}": ${errMsg}`,
+                    type: 'warning',
+                    message: `⚠ pause "${step.id}" 审批闸门不可用（提问桥异常），已自动放行。提示：${msg}`,
                 };
-                return true;
             }
-            const survived = [];
-            for (const item of inputArr) {
-                if (ctx.signal?.aborted) {
-                    yield { type: 'interrupted' };
-                    return true;
-                }
-                const verdicts = await Promise.all(Array.from({ length: voters_count }, () => runVoter(step.rules ?? '', item, vars, ctx)));
-                const refutedCount = verdicts.filter((v) => v.refuted === true).length;
-                if (refutedCount < threshold) {
-                    survived.push(item);
-                }
+            if (!approved) {
+                const why = freeText
+                    ? `用户在审批闸门 "${step.id}" 给出指示「${truncate(freeText, 120)}」——未放行（现场已保留，按指示调整后重跑同目标可从断点续跑）`
+                    : `用户在审批闸门 "${step.id}" 选择停止（现场已保留，重跑同目标可从断点续跑）`;
+                await state.appendProgress(`■ ${step.id}: ${why}`);
+                if (cp)
+                    await state.recordFailure(step.id, why);
+                yield { type: 'workflow_step_end', id: step.id, ok: false, error: why };
+                yield { type: 'error', error: `Workflow halted at step "${step.id}": ${why}` };
+                return 'halted';
             }
-            const voteResult = {
+            // 带补充要求的放行：自由输入并入贯穿目标（后续每步都看到，不止 capture 变量）
+            if (freeText)
+                await addGoalSupplement(ctx, state, freeText);
+            const pauseResult = {
                 raw: {
-                    survived,
-                    total: inputArr.length,
-                    kept: survived.length,
+                    result: freeText,
+                    text: freeText,
+                    approved: true,
+                    free_text: freeText,
                 },
-                preview: `vote: ${survived.length}/${inputArr.length} survived (threshold=${threshold}/${voters_count})`,
+                preview: freeText
+                    ? `审批通过：继续执行；补充要求：${truncate(freeText, 120)}`
+                    : '审批通过：继续执行',
             };
             if (step.capture)
-                bindCapture(step.capture, voteResult, vars);
-            await state.appendProgress(`✓ ${step.id} (vote ${survived.length}/${inputArr.length})`);
+                bindCapture(step.capture, pauseResult, vars);
             await state.writeVars(vars.snapshot());
+            if (cp) {
+                await state.recordCheckpoint(cp.name(step.id), pauseResult.preview, collectCaptured(step.capture, vars), vars.snapshot());
+            }
+            await state.appendProgress(`✓ ${step.id} (pause: 已确认继续)`);
             yield {
                 type: 'workflow_step_end',
                 id: step.id,
                 ok: true,
-                output: voteResult.preview,
+                output: pauseResult.preview,
             };
             continue;
         }
-        // ---------- 普通动作 step：tool / llm / skill / assert ----------
-        try {
-            const result = yield* dispatchActionStep(step, vars, ctx);
-            if (step.capture)
-                bindCapture(step.capture, result, vars);
-            await state.appendProgress(`✓ ${step.id} (${kind})`);
-            await state.writeVars(vars.snapshot());
+        // ---------- 控制流：break / continue（循环信号） ----------
+        //
+        // 仅在 loop 的 do[] 内有意义。break = 跳出循环；continue = 跳到下一轮迭代。
+        // 缺省作用于最近一层循环；带 target 时穿透中间层循环直达指定 id 的 loop
+        //（如审批反馈是方向性变化时，从审批小循环 continue 到外层 plan_loop 重启规划）。
+        // 通常配合 when 条件使用；游离信号（无外层循环 / target 不存在）冒泡到顶层
+        // 按正常完成处理，绝不当 halt。
+        if (step.type === 'break' || step.type === 'continue') {
+            let shouldFire = true;
+            if (step.when) {
+                try {
+                    shouldFire = Boolean(evalExpr(step.when, vars));
+                }
+                catch (e) {
+                    // when 表达式错误 → 不触发，当 skipped 处理
+                    shouldFire = false;
+                }
+            }
+            if (shouldFire) {
+                const label = `${step.type}${step.target ? ` → ${step.target}` : ''}`;
+                await state.appendProgress(`↵ ${step.id}: ${label}`);
+                yield { type: 'workflow_step_end', id: step.id, ok: true, output: label };
+                return { signal: step.type, target: step.target };
+            }
+            // 条件不满足 → 当 skip 处理，继续下一步
             yield {
-                type: 'workflow_step_end',
+                type: 'workflow_step_skipped',
                 id: step.id,
-                ok: true,
-                output: result.preview,
+                reason: `${step.type} 条件不满足`,
             };
+            continue;
         }
-        catch (e) {
-            const errMsg = e.message ?? String(e);
-            await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
-            // onError:'recover' —— 不立刻 halt，交给有界恢复 agent 随机应变把这一步救回来。
-            // 「确定性工作流 × TAOR」的结合点：happy path 走刚性 DAG，撞上预料之外的就地
-            // 降级为 agent 自适应；救回则继续 happy path，救不回才 honest halt。
-            if (step.onError === 'recover') {
+        // ---------- 控制流：echo（确定性输出，不烧 LLM） ----------
+        //
+        // 把 message 插值后作为 text 事件输出给用户。适合工作流末尾的完成报告：
+        // 产物/裁决已在变量里时直接插值，省一次 LLM 调用且零幻觉。
+        if (step.type === 'echo') {
+            const missing = [];
+            const text = interpolate(step.message ?? '', vars, {
+                onMissing: (e) => missing.push(e),
+            });
+            if (missing.length > 0) {
                 yield {
                     type: 'warning',
-                    message: `step "${step.id}" 失败：${errMsg}；尝试自适应恢复…`,
+                    message: `step "${step.id}": 模板变量未定义，已按空串插值：${[...new Set(missing)].map((m) => `\${${m}}`).join('、')}`,
                 };
+            }
+            yield { type: 'text', delta: text.endsWith('\n') ? text : `${text}\n` };
+            await state.appendProgress(`✓ ${step.id} (echo)`);
+            if (cp) {
+                await state.recordCheckpoint(cp.name(step.id), truncate(text, 200), {}, vars.snapshot());
+            }
+            yield {
+                type: 'workflow_step_end',
+                id: step.id,
+                ok: true,
+                output: truncate(text, 200),
+            };
+            continue;
+        }
+        // ---------- 普通动作 step：tool / llm / skill / agent / assert / verify ----------
+        //
+        // in-run retry（self_heal）：失败先确定性重跑同一步，至多 maxRetries 次（retry 先于
+        // onError:recover）。maxRetries = step.max_retries ?? def.self_heal.max_retries（runWorkflow
+        // 注入到 ctx.selfHealMaxRetries）?? 0。语义：max_retries 是「额外重试次数」，总尝试 = 1 + maxRetries。
+        const maxRetries = step.max_retries ?? ctx.selfHealMaxRetries ?? 0;
+        let attempt = 0;
+        while (true) {
+            try {
+                const result = yield* dispatchActionStep(step, vars, ctx);
+                if (step.capture)
+                    bindCapture(step.capture, result, vars);
+                // goal_supplement：本步产出作为用户补充要求贯穿后续每一步（如 stage0 澄清结论）
+                if (step.goal_supplement) {
+                    const t = typeof result.raw.text === 'string' && result.raw.text.trim()
+                        ? result.raw.text
+                        : String(result.raw.result ?? result.preview ?? '');
+                    await addGoalSupplement(ctx, state, t);
+                }
+                await state.appendProgress(`✓ ${step.id} (${kind})`);
+                await state.writeVars(vars.snapshot());
+                // checkpoint：记录范围见 CpScope（顶层步 + 顶层 loop 的 do[] 一层）。
+                if (cp) {
+                    await state.recordCheckpoint(cp.name(step.id), result.preview, collectCaptured(step.capture, vars), vars.snapshot());
+                }
                 yield {
-                    type: 'plugin_progress',
-                    pluginId: WF_PLUGIN_ID,
-                    current: i + 1,
-                    max: steps.length,
-                    message: `↻ 恢复 ${step.id}…`,
+                    type: 'workflow_step_end',
+                    id: step.id,
+                    ok: true,
+                    output: result.preview,
                 };
-                const rec = yield* runRecovery(step, vars, ctx, errMsg);
-                if (ctx.signal?.aborted) {
-                    yield { type: 'interrupted' };
-                    return true;
+                break; // 成功 → 退出 retry 循环，进入下一步
+            }
+            catch (e) {
+                const errMsg = e.message ?? String(e);
+                // in-run retry：还有重试额度且未中断 → 重跑同一步（不动 onError）。
+                if (attempt < maxRetries && !ctx.signal?.aborted) {
+                    attempt++;
+                    // 退避等待（线性）：普通 LLM/网络类错误用 retry_delay_ms。
+                    // maxTurns 截断默认保持旧行为立即续跑；长文档/PPT 类工作流可显式配置
+                    // max_turns_retry_delay_ms，在模型端高峰期给下一次续作留出恢复窗口。
+                    const isMaxTurns = isMaxTurnsCutoff(errMsg);
+                    const delayBase = isMaxTurns
+                        ? (ctx.maxTurnsRetryDelayMs ?? 0)
+                        : (ctx.retryDelayMs ?? 0);
+                    const delayMs = delayBase * attempt;
+                    const retryKind = isMaxTurns ? '轮数预算用尽，可续跑截断' : '失败';
+                    const retryProgress = isMaxTurns
+                        ? `↻ ${step.id}: 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}`
+                        : `↻ ${step.id}: ${retryKind}，重试 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}（${errMsg}）`;
+                    await state.appendProgress(retryProgress);
+                    yield {
+                        type: 'warning',
+                        message: isMaxTurns
+                            ? `step "${step.id}" 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}${delayMs > 0 ? `（${delayMs}ms 后）` : ''}…`
+                            : `step "${step.id}" 失败：${errMsg}；${delayMs > 0 ? `${delayMs}ms 后` : ''}重试 ${attempt}/${maxRetries}…`,
+                    };
+                    yield {
+                        type: 'plugin_progress',
+                        pluginId: WF_PLUGIN_ID,
+                        current: i + 1,
+                        max: steps.length,
+                        message: isMaxTurns
+                            ? `↻ ${step.id} 阶段轮数预算用尽，正在续跑 ${attempt}/${maxRetries}…`
+                            : `↻ 重试 ${step.id} ${attempt}/${maxRetries}…`,
+                    };
+                    if (delayMs > 0)
+                        await sleepInterruptible(delayMs, ctx.signal);
+                    continue; // 重跑同一步
                 }
-                // 验证闸门：只有恢复 agent 真正交付（rec.ok）才绑 capture 走下去；
-                // 显式放弃 / 产出不可信（rec.ok=false）则带原因 honest halt，绝不盲绑脏值。
-                if (rec.ok) {
-                    if (step.capture)
-                        bindCapture(step.capture, rec.value, vars);
-                    await state.appendProgress(`⚠→✓ ${step.id} recovered`);
-                    await state.writeVars(vars.snapshot());
+                await state.appendProgress(`✗ ${step.id}: ${errMsg}`);
+                // onError:'recover' —— retry 用尽仍失败，交给有界恢复 agent 随机应变把这一步救回来。
+                // 「确定性工作流 × TAOR」的结合点：happy path 走刚性 DAG，撞上预料之外的就地
+                // 降级为 agent 自适应；救回则继续 happy path，救不回才 honest halt。
+                if (step.onError === 'recover') {
+                    yield {
+                        type: 'warning',
+                        message: `step "${step.id}" 失败：${errMsg}；尝试自适应恢复…`,
+                    };
+                    yield {
+                        type: 'plugin_progress',
+                        pluginId: WF_PLUGIN_ID,
+                        current: i + 1,
+                        max: steps.length,
+                        message: `↻ 恢复 ${step.id}…`,
+                    };
+                    const rec = yield* runRecovery(step, vars, ctx, errMsg);
+                    if (ctx.signal?.aborted) {
+                        yield { type: 'interrupted' };
+                        return 'halted';
+                    }
+                    // 验证闸门：只有恢复 agent 真正交付（rec.ok）才绑 capture 走下去；
+                    // 显式放弃 / 产出不可信（rec.ok=false）则带原因 honest halt，绝不盲绑脏值。
+                    if (rec.ok) {
+                        if (step.capture)
+                            bindCapture(step.capture, rec.value, vars);
+                        await state.appendProgress(`⚠→✓ ${step.id} recovered`);
+                        await state.writeVars(vars.snapshot());
+                        if (cp) {
+                            await state.recordCheckpoint(cp.name(step.id), rec.value.preview, collectCaptured(step.capture, vars), vars.snapshot());
+                        }
+                        yield {
+                            type: 'workflow_step_end',
+                            id: step.id,
+                            ok: true,
+                            output: rec.value.preview,
+                        };
+                        break; // 救回 → 进入下一步
+                    }
+                    const combined = `${errMsg}（自适应恢复未成功：${rec.reason}）`;
+                    if (cp)
+                        await state.recordFailure(step.id, combined);
                     yield {
                         type: 'workflow_step_end',
                         id: step.id,
-                        ok: true,
-                        output: rec.value.preview,
+                        ok: false,
+                        error: combined,
                     };
-                    continue;
+                    yield {
+                        type: 'error',
+                        error: `Workflow halted at step "${step.id}": ${combined}`,
+                    };
+                    return 'halted';
+                }
+                if (step.onError === 'continue') {
+                    // 降级时给 capture 变量绑【明确占位文本】而非留空：空串静默内插进下游
+                    // prompt（如「已知需求分析：\n\n」）是更大的最小惊讶违例——模型看到
+                    // 空段会困惑。占位前缀「（上游步骤 」机器可识别；continue 本就是作者
+                    // 显式选择「无此内容也继续」，需要严格闸门的步骤应配 onError:halt 或 assert。
+                    if (step.capture) {
+                        const placeholder = `（上游步骤 ${step.id} 失败已降级（onError:continue），无内容——` +
+                            `请基于用户原始目标自行推断。错误：${errMsg.length > 120 ? `${errMsg.slice(0, 120)}…` : errMsg}）`;
+                        for (const varName of Object.values(normalizeCapture(step.capture))) {
+                            vars.setGlobal(varName, placeholder);
+                        }
+                    }
+                    // 降级此前完全静默（仅 progress.md 有 ✗ 行）——补一条 warning 可见化
+                    yield {
+                        type: 'warning',
+                        message: `step "${step.id}" 失败已降级（onError:continue）：${errMsg}`,
+                    };
+                    yield {
+                        type: 'workflow_step_end',
+                        id: step.id,
+                        ok: false,
+                        error: errMsg,
+                    };
+                    break; // 跳过本步 → 进入下一步
                 }
-                const combined = `${errMsg}（自适应恢复未成功：${rec.reason}）`;
+                const finalErrMsg = isMaxTurnsCutoff(errMsg)
+                    ? `${errMsg}；重试额度已用尽，请拆分该步骤或提高 maxTurns。`
+                    : errMsg;
+                if (cp)
+                    await state.recordFailure(step.id, finalErrMsg);
                 yield {
                     type: 'workflow_step_end',
                     id: step.id,
                     ok: false,
-                    error: combined,
+                    error: finalErrMsg,
                 };
                 yield {
                     type: 'error',
-                    error: `Workflow halted at step "${step.id}": ${combined}`,
+                    error: `Workflow halted at step "${step.id}": ${finalErrMsg}`,
                 };
-                return true;
+                return 'halted';
             }
-            if (step.onError === 'continue') {
-                yield {
-                    type: 'workflow_step_end',
-                    id: step.id,
-                    ok: false,
-                    error: errMsg,
-                };
-                continue;
-            }
-            yield {
-                type: 'workflow_step_end',
-                id: step.id,
-                ok: false,
-                error: errMsg,
-            };
-            yield {
-                type: 'error',
-                error: `Workflow halted at step "${step.id}": ${errMsg}`,
-            };
-            return true;
         }
     }
-    return false;
+    return 'completed';
+}
+/**
+ * 聚合工作流【声明】的产物路径（相对 cwd）：def.artifacts + 所有 step.artifacts（含嵌套 then/else/do）。
+ * 通用：由 yaml 的 `artifacts:` 声明驱动，runner 不硬编码任何具体文件名（如 PLAN.md）。
+ * 用途：new-task 检测时清旧任务残留产物、completed 时报实际产物。
+ */
+function collectDeclaredArtifacts(def) {
+    const out = new Set();
+    for (const a of def.artifacts ?? [])
+        out.add(a);
+    const walk = (steps) => {
+        for (const s of steps ?? []) {
+            for (const a of s.artifacts ?? [])
+                out.add(a);
+            walk(s.then);
+            walk(s.else);
+            walk(s.do);
+        }
+    };
+    walk(def.steps);
+    return [...out];
 }
 /**
  * 运行一个 workflow。
@@ -499,26 +927,152 @@ export async function* runWorkflow(def, inputs, ctx) {
     // onError:'recover' 用：把工作流总目标（description）透传给恢复 agent，
     // 让它知道「这条工作流到底想干什么」。已有 goal 则不覆盖。
     const runCtx = { ...ctx, goal: ctx.goal ?? def.description };
-    const state = new WorkflowState(getWorkingDir());
-    await state.init(def.name, inputs);
+    // 通用目标锚定：从 inputs 中提取用户的原始目标，
+    // 注入 RunContext.goalAnchor，让 agent/llm/skill 步自动前置到每步 prompt。
+    // 提取策略：优先 "goal" 命名的输入 → 其次第一个 required string 输入。
+    runCtx.goalAnchor = buildGoalAnchor(def.inputs ?? [], inputs);
+    // self_heal：把全局 max_retries 默认透传给每步的 in-run retry（step.max_retries 可覆盖）。
+    runCtx.selfHealMaxRetries = def.self_heal?.max_retries;
+    runCtx.retryDelayMs = def.self_heal?.retry_delay_ms;
+    runCtx.maxTurnsRetryDelayMs = def.self_heal?.max_turns_retry_delay_ms;
+    // 声明产物清单：state.init 用于 new-task 清理/completed 报产物；
+    // 挂到 runCtx 供 tool 步覆盖判定（声明产物自动 pre-Read 解 Write 守卫）。
+    const declaredArtifacts = collectDeclaredArtifacts(def);
+    runCtx.declaredArtifacts = declaredArtifacts;
+    // 任务身份语义仲裁器（hash 不等 + 旧任务未完成时的二审，见 taskIdentity.ts）：
+    // 短语快路径 → LLM 单轮仲裁 → AskUserQuestion → 兜底 new-task。
+    // init 非 generator，仲裁过程的人话记录收进 notes，init 返回后统一 yield。
+    const arbitrationNotes = [];
+    const state = new WorkflowState(getWorkingDir(), def.name);
+    const resume = await state.init(def.name, inputs, def.steps, def.self_heal?.backoff, declaredArtifacts, buildTaskArbitrator({
+        provider: runCtx.provider,
+        chat: runCtx.chat,
+        executeTool: runCtx.executeTool,
+        signal: runCtx.signal,
+        notes: arbitrationNotes,
+    }));
     yield {
         type: 'workflow_start',
         name: def.name,
         totalSteps: def.steps.length,
     };
-    // P1 TUI 可见：开工时给 LiveArea 状态行一条 plugin_progress（0/total）。
+    // 仲裁过程可见化（命中延续短语 / LLM 判定 / 用户确认 / 兜底）
+    for (const n of arbitrationNotes) {
+        yield { type: 'warning', message: n };
+    }
+    // 同任务此前已成功完成（goal hash 匹配 + status=done）→ 不重跑，报产物后正常收尾。
+    // 成功运行会 archive() 把状态目录改名 .done，init() 回退读 .done 检测到 completed。
+    if (resume.mode === 'completed') {
+        const arts = resume.artifacts?.length ? resume.artifacts.join(', ') : '（无记录）';
+        yield {
+            type: 'text',
+            delta: `✓ 同名任务此前已完成（产物：${arts}）。如需重跑请先 /new 清理工作流状态。\n`,
+        };
+        yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
+        return;
+    }
+    // 定义结构变更可见化：同任务但 yaml 改过结构 → 旧断点作废、从头开始。
+    // 必须明示——曾有用户在 yaml 重构后同 goal 重跑，看到「从第 2 步续跑」
+    // 困惑是 bug 还是残留；作废旧断点时不说原因同样会被当成 bug。
+    if (resume.defChanged) {
+        yield {
+            type: 'warning',
+            message: '♻ 工作流定义已变更（步骤结构与旧断点不再匹配），旧执行现场已作废，本次从头开始执行。',
+        };
+    }
+    // fresh/new-task 启动清理可见化：全新任务开始前已删掉的残留产物（上次任务
+    // 的声明产物 + /new 后无主孤儿）。用户约定：全新 plan 一律从干净状态开始；
+    // 删除范围仅限本工作流声明的产物，同任务 resume 不清理。
+    if (resume.cleanedArtifacts?.length) {
+        yield {
+            type: 'warning',
+            message: `全新任务：已清理上次残留的旧产物 ${[...new Set(resume.cleanedArtifacts)].join('、')}，从干净状态开始。`,
+        };
+    }
+    // 仲裁判定的延续 resume：本次 inputs 里的 goal 是「继续」这类延续指令，
+    // 不能拿它当目标——两处都要换回旧任务的真实目标：
+    //   1. goalAnchor：锚旧目标 + 新输入作为补充指令（如「继续，但改成 12 页」不丢失）；
+    //   2. VarStack 的 inputs：yaml prompt 正文大量内插 ${inputs.goal}（业务上下文），
+    //      不替换的话重跑步骤会渲染成「用户的目标是：『继续』」——锚定与正文打架。
+    //      goal 承载键用与 buildGoalAnchor/extractGoal 同一策略（通用，零具体 yaml 耦合）；
+    //      磁盘 inputs.json 保持旧任务值不动，任务身份 hash 语义不受影响。
+    if (resume.mode === 'resume') {
+        // 贯穿补充要求：上次运行累积的（pause 反馈 / 澄清结论）从状态目录恢复，
+        // resume 后注入每步锚定不丢失。
+        runCtx.goalSupplements = await state.readSupplements();
+    }
+    if (resume.mode === 'resume' && resume.prevGoal) {
+        const goalKey = (def.inputs ?? []).find((d) => d.name === 'goal' && d.type === 'string')
+            ?.name ??
+            (def.inputs ?? []).find((d) => d.required && d.type === 'string')?.name;
+        if (goalKey && typeof inputs[goalKey] === 'string') {
+            vars.setGlobal('inputs', { ...inputs, [goalKey]: resume.prevGoal });
+        }
+        runCtx.goalAnchor = `> 🎯 用户原始目标：${truncateGoal(resume.prevGoal)}\n> ⚠️ 所有操作必须直接回应此目标，不可偏离或遗忘。`;
+        // 新输入是带信息量的补充指令（非纯「继续」延续短语）→ 并入贯穿补充要求；
+        // 经 goalSupplements 统一渲染（与 pause 反馈/澄清结论同通道），且去重防
+        // 反复 resume 时同一句话累积成噪声。
+        const supp = resume.supplementaryGoal;
+        if (supp &&
+            supp !== resume.prevGoal &&
+            !isContinuationPhrase(supp) &&
+            !(runCtx.goalSupplements ?? []).some((s) => s.startsWith(supp.slice(0, 240)))) {
+            await addGoalSupplement(runCtx, state, supp);
+        }
+    }
+    // resume：同任务中断后重跑 —— 回放已完成步的 capture 变量，从 startFrom 起跑。
+    // ⚠️ 仅回放 VarStack 变量，不恢复 TAOR history（plan.yaml 全程用 capture 变量串联故可用；
+    // 依赖隐式 history 的工作流 resume 后上下文较薄，见 types.ts 限制说明）。
+    let startFrom = 0;
+    if (resume.mode === 'resume' && ((resume.startFrom ?? 0) > 0 || resume.loopResume)) {
+        startFrom = resume.startFrom ?? 0;
+        if (resume.capturedVars && resume.completedStepIds) {
+            for (const sid of resume.completedStepIds) {
+                const caps = resume.capturedVars[sid];
+                if (caps)
+                    for (const [k, v] of Object.entries(caps))
+                        vars.setGlobal(k, v);
+            }
+        }
+        // 循环中断恢复：回放中断时刻的最近 vars 快照（含 setGlobal 的教训/裁决与
+        // 迭代内已完成步的 capture）。inputs 不回放——goal 承载键已由上方仲裁逻辑处理。
+        if (resume.loopResume?.lastVarsSnapshot) {
+            for (const [k, v] of Object.entries(resume.loopResume.lastVarsSnapshot)) {
+                if (k === 'inputs')
+                    continue;
+                vars.setGlobal(k, v);
+            }
+        }
+        const loopNote = resume.loopResume
+            ? `，循环 ${resume.loopResume.loopId} 恢复到第 ${resume.loopResume.iteration + 1} 轮迭代`
+            : '';
+        const msg = `♻ 检测到同名未完成任务，从第 ${startFrom + 1} 步续跑（已回放 ${resume.completedStepIds?.length ?? 0} 个完成步变量${loopNote}）。要全新开始请先 /new。`;
+        yield { type: 'warning', message: msg };
+    }
+    // P1 TUI 可见：开工时给 LiveArea 状态行一条 plugin_progress（startFrom/total）。
     yield {
         type: 'plugin_progress',
         pluginId: WF_PLUGIN_ID,
-        current: 0,
+        current: startFrom,
         max: def.steps.length,
         message: `▶ workflow ${def.name}`,
     };
     let succeeded = false;
     try {
-        const halted = yield* runSteps(def.steps, vars, runCtx, state);
-        if (halted)
+        const flow = yield* runSteps(def.steps, vars, runCtx, state, { name: (id) => id, descendIntoLoop: true }, startFrom, resume.mode === 'resume' ? resume.loopResume : undefined);
+        // 'halted' → 失败/中断（error/interrupted 已 yield），保留现场不归档供排查与 resume；
+        // 'completed' / 信号对象（顶层游离 break/continue）→ 正常完成。
+        if (flow === 'halted')
             return;
+        const missingArtifacts = declaredArtifacts.filter((a) => !existsSync(resolve(runCtx.cwd, a)));
+        if (missingArtifacts.length > 0) {
+            const why = `工作流声明的产物缺失：${missingArtifacts.join('、')}` +
+                `——所有步骤执行完毕但目标产物未落盘，不标记完成（保留现场供排查/续作）`;
+            await state.recordFailure('<finalize>', why);
+            yield { type: 'workflow_step_end', id: '<finalize>', ok: false, error: why };
+            yield { type: 'error', error: `Workflow halted: ${why}` };
+            return;
+        }
         // 完成态也给一条 plugin_progress（放在 workflow_done 之前，保证
         // workflow_done 仍是事件流最后一条——e2e 测试依赖 events[last]===workflow_done）。
         yield {
@@ -528,56 +1082,17 @@ export async function* runWorkflow(def, inputs, ctx) {
             max: def.steps.length,
             message: `✓ workflow ${def.name} 完成`,
         };
+        // v0.9 重构：不再需要 assistant_message 摘要注入。
+        // agent/llm/skill 步已通过 runQuery(TAOR) 直接写入共享 ctx.history，
+        // 每步的完整对话上下文（user→assistant→tool→...）都自然积累在 history 中。
+        // 后续对话和用户调整都能看到完整的工作流执行过程。
+        await state.markDone();
         yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
         succeeded = true;
-        // ---- 层1：写入摘要到对话历史（让后续对话记住这次 workflow 做了什么）----
-        const snapshot = vars.snapshot();
-        const summaryText = typeof snapshot.summary_text === 'string'
-            ? snapshot.summary_text
-            : '';
-        // 收集关键产出物（从 vars 中提取文件路径）
-        const artifacts = [];
-        if (typeof snapshot.plan_text === 'string')
-            artifacts.push('./PLAN.md');
-        // 检查是否有执行结果（execute_plan 步的产出）
-        if (typeof snapshot.execution_result === 'string') {
-            // 尝试从执行结果中提取文件路径（常见模式：产出物路径）
-            const fileMatches = snapshot.execution_result.match(/`[^`]*\.(pptx|docx|pdf|xlsx|md|ts|js|py)[^`]*`/g);
-            if (fileMatches)
-                artifacts.push(...fileMatches.map((f) => f.replace(/`/g, '')));
-        }
-        const summaryLines = [
-            `**工作流「${def.name}」执行完成**`,
-            ``,
-            `- 步骤: ${def.steps.length}/${def.steps.length} 全部完成`,
-            ...(artifacts.length > 0 ? [`- 产出物: ${artifacts.join(', ')}`] : []),
-            ...(summaryText ? [`- 摘要: ${summaryText}`] : []),
-        ];
-        yield {
-            type: 'assistant_message',
-            message: {
-                role: 'assistant',
-                content: summaryLines.join('\n'),
-            },
-        };
     }
     finally {
-        // 成功时归档（保留 vars.json/progress.md 供后续回溯）；失败/中断时保留原状供排查
+        // 成功时归档（保留 vars.json/progress.md/checkpoints 供后续回溯）；失败/中断时保留原状供排查与 resume
         if (succeeded)
             await state.archive();
     }
 }
-/**
- * parallel fork 用：把 runSteps 的 yield 流收集到 buffer 数组，
- * 让外层 Promise.all 拿到完整事件后再顺序 yield。
- *
- * 注：for-await 无法读取 generator 的 return value（JS 限制），
- * 所以"是否 halted"靠"buffer 里有 error event"近似判断 —— 这符合
- * runSteps 的语义（halt 一定会 yield error / interrupted）。
- */
-async function collectStepsToBuffer(steps, vars, ctx, state, buffer) {
-    for await (const ev of runSteps(steps, vars, ctx, state)) {
-        buffer.push(ev);
-    }
-    return buffer.some((ev) => ev.type === 'error' || ev.type === 'interrupted');
-}