minimal-agent 0.12.0 → 0.14.0

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

@@ -1,514 +1,451 @@
 /**
  * ============================================================
- *  plugins/workflow-runner/src/runner.ts —— workflow 顺序执行器
+ *  plugins/workflow-runner/src/runner.ts —— 一次工作流运行的编排
  * ------------------------------------------------------------
- *  AsyncGenerator，按 yaml.steps[] 顺序执行：
- *    - when: 不满足 → yield workflow_step_skipped
- *    - 命中动作字段 → 调对应 step executor
- *    - capture: 把 result.raw 上的字段绑到 VarStack
- *    - onError: halt（默认）→ yield error 后 return；continue → 记录后跳过
- *    - 信号 abort → yield interrupted 后 return
+ *  串起：任务身份判定 → 账本装载 → 目标锚构造 → 组装 WorkflowContext → 执行 ESM → 收尾归档。
  *
- *  支持的 step kind（loader 已校验）：
- *    - tool / llm / assert            —— 原子动作（execXxxStep 返回 StepResult）
- *    - agent / skill                  —— 有界 TAOR：runQuery(agent) / runQuery(skill)；
- *                                        透传子事件（stage_change/text/reasoning/tool_*）
- *    - 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`。
+ *  ⚠️ **为什么需要事件队列**：ESM 的 run(wf) 是一个普通 async 函数，它执行期间
+ *  没有任何机制能「yield 一个事件出去」；而宿主要的是一条实时事件流（否则
+ *  整条工作流跑完之前 UI 一片死寂）。所以 `wf` 上下文把事件推进队列，本函数
+ *  作为 async generator 一边 await 脚本的 promise、一边把队列排空往外 yield。
  * ============================================================
  */
-import { existsSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { dlog, getWorkingDir } from '../../../src/plugin-sdk.js';
-import { evalExpr, interpolate } from './expressions.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 { execEchoStep } from './stepExecutors/echo.js';
-import { execSetStep } from './stepExecutors/set.js';
-import { execBranchStep } from './controlFlow/branch.js';
-import { execLoopStep } from './controlFlow/loop.js';
-import { execPauseStep } from './controlFlow/pause.js';
-import { execSignalStep } from './controlFlow/signal.js';
-import { runStepWithRetry } from './stepPipeline.js';
-import { VarStack } from './types.js';
-import { WorkflowState, } from './workflowState.js';
-/**
- * 插件 ID：把私有 workflow_* 事件镜像成框架通用 plugin_progress 时挂这个 id。
- * LiveArea 状态行会渲染成 "[plugin:workflow-runner] i/total <message>"
- * （src/ui/LiveArea.tsx:123），让 TUI 里跑 workflow 不再"无声"。
- * （-p 非交互模式另由 src/cli/print.ts 把通用 warning 事件落 stderr。）
- */
+import { ExecutionScope, createWorkflowContext } from './runtime/context.js';
+import { buildGoalAnchor } from './goalAnchor.js';
+import { coerceInputs } from './inputCoercion.js';
+import { Journal, fingerprint } from './journal.js';
+import { bindResourceInputs } from './resourceInputs.js';
+import { WorkflowScriptError, runScript } from './sandbox.js';
+import { DEFAULT_SESSION_ID, buildTaskArbitrator, sanitizeWorkflowDirName, } from './taskIdentity.js';
+import { effectiveWorkflowCwd } from './toolRuntime.js';
+import { resolveWorkflowBundle, } from './workflowDependencies.js';
+import { WorkflowState } from './workflowState.js';
 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();
-        }
+/** 事件队列：生产者随时 push，消费者按序 async 迭代，close 后排空即结束。 */
+class EventQueue {
+    items = [];
+    waiter = null;
+    closed = false;
+    push(item) {
+        this.items.push(item);
+        this.waiter?.();
+        this.waiter = null;
+    }
+    close() {
+        this.closed = true;
+        this.waiter?.();
+        this.waiter = null;
     }
-    // 策略 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();
+    async *drain() {
+        while (true) {
+            while (this.items.length > 0) {
+                yield this.items.shift();
             }
+            if (this.closed)
+                return;
+            await new Promise((resolve) => {
+                this.waiter = resolve;
+            });
         }
     }
-    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)
-        return 'tool';
-    if (step.skill)
-        return 'skill';
-    if (step.agent)
-        return 'agent';
-    if (step.llm)
-        return 'llm';
-    return 'assert'; // 不会到这里（loader 已校验），兜底
-}
-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`,
+/** 执行一个代码形态工作流，产出 LoopEvent 流。 */
+export async function* runWorkflowScript(script, opts) {
+    try {
+        const bundle = await resolveWorkflowBundle(script, effectiveWorkflowCwd(opts.ctx));
+        opts.ctx.resourceLedger ??= {
+            inputTokens: 0,
+            outputTokens: 0,
+            limit: null,
+            trustworthy: true,
         };
+        const scope = new ExecutionScope();
+        const lease = await scope.scheduler.acquire('root', scope.rootRunId, opts.ctx.signal);
+        try {
+            yield* executeWorkflowScript(script, {
+                ...opts,
+                bundle,
+                scope,
+                runId: scope.rootRunId,
+                depth: 0,
+            });
+        }
+        finally {
+            lease.release();
+        }
     }
-    return { ok: true, value: Math.floor(n) };
-}
-/**
- * 分发"动作"型 step（tool / agent / llm / skill / assert）到对应 executor。
- * 控制流 step（branch / loop / pause 等）由 runSteps 直接处理，不走这里。
- */
-async function* dispatchActionStep(step, vars, ctx) {
-    if (step.type === 'assert')
-        return execAssertStep(step, vars, ctx);
-    if (step.type === 'verify')
-        return await execVerifyStep(step, vars);
-    // set / echo 从 runSteps 的内联块搬进执行器体系：它们不影响迭代、只产出 StepResult。
-    // 搬过来的直接收益是 `capture:` 自然生效（此前它们从不调 bindCapture —— 静默失效）。
-    if (step.type === 'set')
-        return yield* execSetStep(step, vars);
-    if (step.type === 'echo')
-        return yield* execEchoStep(step, vars);
-    if (step.tool)
-        return yield* execToolStep(step, vars, ctx);
-    if (step.agent)
-        return yield* execAgentStep(step, vars, ctx);
-    if (step.llm)
-        return yield* execLlmStep(step, vars, ctx);
-    if (step.skill)
-        return yield* execSkillStep(step, vars, ctx);
-    throw new Error(`step ${step.id}: 无可执行字段（tool/agent/llm/skill/assert/verify）`);
-}
-/**
- * 递归执行 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, 
-// 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) {
+    catch (error) {
+        if (opts.ctx.signal?.aborted ||
+            (error instanceof Error && error.name === 'AbortError'))
             yield { type: 'interrupted' };
-            return 'halted';
-        }
-        // resume：跳过已完成的步（变量已回放，无需重跑）。
-        if (i < startFrom) {
+        else
             yield {
-                type: 'workflow_step_skipped',
-                id: step.id,
-                reason: 'resume: 上次已完成',
+                type: 'error',
+                error: error instanceof Error ? error.message : String(error),
             };
-            continue;
-        }
-        // when 条件：**所有** step 类型统一在这里判。控制流处理器里不要再判一次 ——
-        // 重构前 break/continue 块自带一份，而它恒为真（false 时这里已经 continue 掉了），
-        // 连它的 catch 分支都不可达。那是纯死代码，随本次重构删除。
-        if (step.when) {
-            let pass = false;
-            try {
-                pass = Boolean(evalExpr(step.when, vars));
-            }
-            catch (e) {
-                const errMsg = `when 表达式错误: ${e.message}`;
-                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';
-            }
-            if (!pass) {
-                yield { type: 'workflow_step_skipped', id: step.id, reason: 'when=false' };
-                await state.appendProgress(`- ${step.id} skipped (when=false)`);
-                continue;
-            }
-        }
-        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。
-        // 有 title 的步显示人话阶段名（如「阶段2/6·起草实现计划」）且不带块内序号——
-        // 嵌套块的 i/total（顶层 5、循环体 12…）会被用户误读成"跳步/结构乱"；
-        // 未声明 title 的步保持 legacy 格式 "i/total step <id> (<kind>)"。
-        yield {
-            type: 'plugin_progress',
-            pluginId: WF_PLUGIN_ID,
-            current: i + 1,
-            max: steps.length,
-            message: interpolatedTitle ?? `step ${step.id} (${kind})`,
-        };
-        // ---------- 控制流：改变的是「循环怎么走」，不是产出一个 StepResult ----------
-        //
-        // 所以它们不塞进 stepExecutors 那套 (step,vars,ctx)→StepResult 的形状里，
-        // 各自住在 controlFlow/ 并共用出口 ControlOutcome —— 这里只需一个分派。
-        const controlDeps = {
-            ctx,
-            state,
-            ...(cp ? { cp } : {}),
-            runBlock: (blockSteps, blockVars, blockCp, blockStart, blockResume) => runSteps(blockSteps, blockVars, ctx, state, blockCp, blockStart, blockResume),
-            index: i,
-            total: steps.length,
-            addGoalSupplement: (text) => addGoalSupplement(ctx, state, text),
-        };
-        let outcome = null;
-        if (step.type === 'branch') {
-            outcome = yield* execBranchStep(step, vars, controlDeps);
-        }
-        else if (step.type === 'loop') {
-            outcome = yield* execLoopStep(step, vars, controlDeps, loopResume);
-            // 恢复信息只消费一次：匹配到的那个 loop 用掉之后，后续 loop 不再套用。
-            if (loopResume && loopResume.loopId === step.id)
-                loopResume = undefined;
-        }
-        else if (step.type === 'pause') {
-            outcome = yield* execPauseStep(step, vars, controlDeps);
-        }
-        else if (step.type === 'break' || step.type === 'continue') {
-            outcome = yield* execSignalStep(step, controlDeps);
-        }
-        if (outcome) {
-            if (outcome.kind === 'halted')
-                return 'halted';
-            if (outcome.kind === 'flow')
-                return outcome.signal;
-            continue;
-        }
-        // ---------- 动作步：tool / llm / skill / agent / assert / verify / set / echo ----------
-        //
-        // 统一走 runStepWithRetry：in-run 重试 → onError 三态 → commitStep 提交。
-        // 「提交一步」只有 stepPipeline 那一份实现，这里不再自己写（见 stepPipeline 头注）。
-        const actionOutcome = yield* runStepWithRetry({
-            step,
-            kind,
-            vars,
-            ctx,
-            state,
-            ...(cp ? { cp } : {}),
-            index: i,
-            total: steps.length,
-            addGoalSupplement: (text) => addGoalSupplement(ctx, state, text),
-            execute: () => dispatchActionStep(step, vars, ctx),
-        });
-        if (actionOutcome === 'halted')
-            return 'halted';
     }
-    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。
- *
- * yields 混合事件：本地 WorkflowEvent（workflow_* 系列，UI 静默忽略不渲染）
- * + 通用 LoopEvent（error / interrupted / 子 step 透传的 text/tool/stage_change 等，
- * UI 识别并渲染）。经 plugin.ts -> pluginRunner 透传给 UI；workflow_* 由 PluginEvent
- * 开放契约承载。
- *
- * 成功跑完以 `workflow_done` 收尾（携带 vars 快照）；中途失败/中断只 yield error/interrupted。
- * **对外流式协议的通用终结事件 `turn_done` 由命令层 index.ts 在成功后补发**（见那里）——
- * 本函数自身事件序列保持不变，直测它的 runner.test.ts / 单元测试仍以 workflow_done 为最后一条。
- */
-export async function* runWorkflow(def, inputs, ctx) {
-    const vars = new VarStack();
-    vars.setGlobal('inputs', inputs);
-    // onError:'recover' 用：把工作流总目标（description）透传给恢复 agent，
-    // 让它知道「这条工作流到底想干什么」。已有 goal 则不覆盖。
-    const runCtx = { ...ctx, goal: ctx.goal ?? def.description };
-    // 通用目标锚定：从 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。
+/** Same executor for roots and children. Only roots emit terminal host events. */
+async function* executeWorkflowScript(script, opts) {
+    const { ctx, inputs } = opts;
+    ctx.signal?.throwIfAborted();
+    const sessionId = sanitizeWorkflowDirName(opts.sessionId ?? ctx.runtimeContext?.sessionId ?? DEFAULT_SESSION_ID);
+    const scriptHash = opts.bundle.hash;
+    const state = new WorkflowState(effectiveWorkflowCwd(ctx), script.name, sessionId, script.meta.inputs, opts.taskId ?? ctx.managedExecution?.runId, opts.parentStateDir);
     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,
-    };
-    // 仲裁过程可见化（命中延续短语 / LLM 判定 / 用户确认 / 兜底）
-    for (const n of arbitrationNotes) {
-        yield { type: 'warning', message: n };
+    const resume = await state.init(inputs, scriptHash, script.meta.artifacts ?? [], ctx.managedExecution || opts.parentStateDir
+        ? undefined
+        : buildTaskArbitrator({
+            provider: ctx.provider,
+            chat: ctx.chat,
+            executeTool: ctx.executeTool,
+            signal: ctx.signal,
+            notes: arbitrationNotes,
+        }));
+    for (const note of arbitrationNotes) {
+        yield { type: 'warning', message: note };
     }
-    // 同任务此前已成功完成（goal hash 匹配 + status=done）→ 不重跑，报产物后正常收尾。
-    // 成功运行会 archive() 把状态目录改名 .done，init() 回退读 .done 检测到 completed。
+    // 已完成：报实际产物，不重跑。
     if (resume.mode === 'completed') {
-        const arts = resume.artifacts?.length ? resume.artifacts.join(', ') : '（无记录）';
+        const restoredEvent = {
+            type: 'workflow_progress',
+            workflow: script.name,
+            runId: opts.runId,
+            rootRunId: opts.scope.rootRunId,
+            ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
+            depth: opts.depth,
+            phase: 'workflow',
+            status: 'complete',
+            message: '恢复已完成结果',
+        };
+        await state.appendEvent(restoredEvent);
+        yield restoredEvent;
+        const list = resume.artifacts?.length
+            ? resume.artifacts.map((a) => `  · ${a}`).join('\n')
+            : '  （本次运行没有声明产物）';
         yield {
             type: 'text',
-            delta: `✓ 同名任务此前已完成（产物：${arts}）。如需重跑请先 /new 清理工作流状态。\n`,
+            delta: `工作流「${script.name}」的这个目标此前已完成，产物：\n${list}\n换个目标即可重新执行。\n`,
+        };
+        if (!opts.parentStateDir)
+            yield { type: 'turn_done' };
+        return {
+            workflow: script.name,
+            runId: opts.runId,
+            result: await state.readResult(),
+            artifacts: (resume.artifacts ?? []).map((p) => resolve(state.workingDir, p)),
+            reused: true,
         };
-        yield { type: 'workflow_done', name: def.name, vars: vars.snapshot() };
-        return;
     }
-    // 定义结构变更可见化：同任务但 yaml 改过结构 → 旧断点作废、从头开始。
-    // 必须明示——曾有用户在 yaml 重构后同 goal 重跑，看到「从第 2 步续跑」
-    // 困惑是 bug 还是残留；作废旧断点时不说原因同样会被当成 bug。
-    if (resume.defChanged) {
+    if (resume.scriptChanged) {
         yield {
             type: 'warning',
-            message: '♻ 工作流定义已变更（步骤结构与旧断点不再匹配），旧执行现场已作废，本次从头开始执行。',
+            message: `⚠ 工作流「${script.name}」的脚本/依赖已改变或产物/返回值缺失 —— 旧断点作废，本次全新开始。`,
         };
     }
-    // fresh/new-task 启动清理可见化：全新任务开始前已删掉的残留产物（上次任务
-    // 的声明产物 + /new 后无主孤儿）。用户约定：全新 plan 一律从干净状态开始；
-    // 删除范围仅限本工作流声明的产物，同任务 resume 不清理。
-    if (resume.cleanedArtifacts?.length) {
+    if (resume.archivedTo) {
         yield {
             type: 'warning',
-            message: `全新任务：已清理上次残留的旧产物 ${[...new Set(resume.cleanedArtifacts)].join('、')}，从干净状态开始。`,
+            message: `旧产物已归档到 ${resume.archivedTo}（不是删除，需要时可取回）。`,
         };
     }
-    // 仲裁判定的延续 resume：本次 inputs 里的 goal 是「继续」这类延续指令，
-    // 不能拿它当目标——两处都要换回旧任务的真实目标：
-    //   1. goalAnchor：锚旧目标 + 新输入作为补充指令（如「继续，但改成 12 页」不丢失）；
-    //   2. VarStack 的 inputs：yaml prompt 正文大量内插 ${inputs.goal}（业务上下文），
-    //      不替换的话重跑步骤会渲染成「用户的目标是：『继续』」——锚定与正文打架。
-    //      goal 承载键用与 buildGoalAnchor/extractGoal 同一策略（通用，零具体 yaml 耦合）；
-    //      磁盘 inputs.json 保持旧任务值不动，任务身份 hash 语义不受影响。
+    // 目标锚：仲裁判定的延续要锚**旧目标**，本次输入降级成补充要求。
+    ctx.goalAnchor = ctx.managedExecution
+        ? ctx.managedExecution.anchor
+        : resume.prevGoal
+            ? buildGoalAnchor({ goal: resume.prevGoal }, script.meta.inputs)
+            : buildGoalAnchor(inputs, script.meta.inputs);
+    ctx.goalSupplements = await state.readSupplements();
+    ctx.declaredArtifacts = new Set(script.meta.artifacts ?? []);
+    const journal = new Journal(state.journalPath, {
+        bundleHash: scriptHash,
+        rootRunId: opts.scope.rootRunId,
+    });
+    await journal.load(script.meta.resumeBackoff ?? 0);
     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);
-        }
+        yield {
+            type: 'warning',
+            message: `↻ 续跑工作流「${script.name}」（上次已完成 ${journal.loadedCount} 次调用` +
+                `${resume.lastError ? `，上次失败于：${resume.lastError}` : ''}）。`,
+        };
     }
-    // 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);
+    const queue = new EventQueue();
+    const workflowContext = createWorkflowContext({
+        ctx,
+        state,
+        journal,
+        emit: (ev) => queue.push(ev),
+        args: inputs,
+        workflowName: script.name,
+        runId: opts.runId,
+        parentRunId: opts.parentRunId,
+        depth: opts.depth,
+        session: sessionId,
+        task: state.taskId,
+        workflowDir: script.dir,
+        inputResourceMap: ctx.inputResourceMap,
+        scope: opts.scope,
+        invokeWorkflow: async (name, rawInputs, site, label) => {
+            const bundle = opts.bundle.children.get(name);
+            if (!bundle)
+                throw new Error(`子工作流 ${name} 未声明在 meta.dependencies 中`);
+            const bound = await bindResourceInputs({
+                workflowName: name,
+                sessionId,
+                cwd: effectiveWorkflowCwd(ctx),
+                rawInputs: rawInputs,
+                defs: bundle.script.meta.inputs,
+                attachments: [],
+            });
+            const childInputs = coerceInputs(bound.inputs, bundle.script.meta.inputs);
+            if (bound.resourceIdentity.length)
+                childInputs.__resource_fingerprint = bound.resourceIdentity.join('|');
+            const taskId = fingerprint('child-instance-v1', {
+                parent: [script.name, state.taskId],
+                site,
+                name,
+                inputs: childInputs,
+            });
+            const childRunId = fingerprint('child-run-v2', {
+                rootRunId: opts.scope.rootRunId,
+                parentRunId: opts.runId,
+                site,
+                taskId,
+            });
+            const childCtx = {
+                ...ctx,
+                cwd: effectiveWorkflowCwd(ctx),
+                history: structuredClone(ctx.history.filter((m) => m.role === 'system')),
+                sessionState: ctx.sessionState
+                    ? structuredClone(ctx.sessionState)
+                    : undefined,
+                goal: undefined,
+                goalAnchor: undefined,
+                goalSupplements: undefined,
+                declaredArtifacts: undefined,
+                transientContext: undefined,
+                transientBundle: undefined,
+                managedExecution: undefined,
+                managedBridge: undefined,
+                usageRecorder: ctx.usageRecorder ??
+                    ctx.managedBridge?.recordUsage?.bind(ctx.managedBridge),
+                inputResources: Object.values(bound.resourceMap).flat(),
+                inputResourceMap: bound.resourceMap,
+            };
+            const prefix = `${script.name} → ${label ?? name}`;
+            await state.appendProgress(`▶ 子流程 ${prefix} (${site}, ${taskId})`);
+            const run = executeWorkflowScript(bundle.script, {
+                ctx: childCtx,
+                inputs: childInputs,
+                sessionId,
+                bundle,
+                scope: opts.scope,
+                parentStateDir: state.dir,
+                taskId,
+                runId: childRunId,
+                parentRunId: opts.runId,
+                depth: opts.depth + 1,
+            });
+            try {
+                while (true) {
+                    const next = await run.next();
+                    if (next.done) {
+                        if (!next.value)
+                            throw new Error(`子工作流 ${name} 未返回执行结果`);
+                        const { reused, ...value } = next.value;
+                        await state.appendProgress(`✓ 子流程 ${prefix} (${reused ? '复用' : '执行完成'})`);
+                        return { value, reused };
+                    }
+                    const ev = next.value;
+                    if (ev.type === 'plugin_progress' ||
+                        ev.type === 'warning' ||
+                        ev.type === 'text' ||
+                        ev.type === 'assistant_message') {
+                        const message = ev.type === 'text'
+                            ? ev.delta
+                            : ev.type === 'assistant_message'
+                                ? typeof ev.message.content === 'string'
+                                    ? ev.message.content
+                                    : JSON.stringify(ev.message.content)
+                                : ev.message;
+                        queue.push({
+                            type: 'plugin_progress',
+                            pluginId: WF_PLUGIN_ID,
+                            message: `[${prefix}] ${message}`,
+                        });
+                    }
+                    else if (ev.type !== 'turn_done' &&
+                        ev.type !== 'interrupted' &&
+                        ev.type !== 'error')
+                        queue.push(ev);
+                }
             }
-        }
-        // 循环中断恢复：回放中断时刻的最近 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);
+            catch (error) {
+                await state.appendProgress(`✗ 子流程 ${prefix}: ${String(error)}`);
+                throw error;
             }
-        }
-        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 };
+        },
+    });
+    if (resume.supplementaryGoal) {
+        await workflowContext.state.addGoalSupplement(resume.supplementaryGoal);
     }
-    // P1 TUI 可见：开工时给 LiveArea 状态行一条 plugin_progress（startFrom/total）。
-    yield {
-        type: 'plugin_progress',
-        pluginId: WF_PLUGIN_ID,
-        current: startFrom,
-        max: def.steps.length,
-        message: `▶ workflow ${def.name}`,
+    const startEvent = {
+        type: 'workflow_progress',
+        workflow: script.name,
+        runId: opts.runId,
+        rootRunId: opts.scope.rootRunId,
+        ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
+        depth: opts.depth,
+        phase: 'workflow',
+        status: 'start',
+        message: `开始 ${script.name}`,
     };
-    let succeeded = false;
-    try {
-        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}` };
+    await state.appendEvent(startEvent);
+    yield startEvent;
+    let failure = null;
+    let scriptResult;
+    const done = runScript(script, workflowContext, scriptHash)
+        .then(async (result) => {
+        ctx.signal?.throwIfAborted();
+        scriptResult = await state.writeResult(result);
+    })
+        .catch((e) => {
+        failure = e;
+    })
+        .finally(() => queue.close());
+    for await (const ev of queue.drain())
+        yield ev;
+    await done;
+    if (failure) {
+        // 中断（用户 ESC）与脚本出错语义完全不同：前者保留现场可 resume。
+        if (ctx.signal?.aborted ||
+            (failure instanceof Error && failure.name === 'AbortError')) {
+            await state.recordFailure('用户中断', [...(ctx.declaredArtifacts ?? [])]);
+            await state.appendProgress('■ 用户中断');
+            if (opts.parentStateDir)
+                throw Object.assign(new Error('用户中断'), { name: 'AbortError' });
+            const interruptedEvent = {
+                type: 'workflow_progress',
+                workflow: script.name,
+                runId: opts.runId,
+                rootRunId: opts.scope.rootRunId,
+                depth: opts.depth,
+                phase: 'workflow',
+                status: 'warning',
+                message: '用户中断，现场已保留',
+            };
+            await state.appendEvent(interruptedEvent);
+            yield interruptedEvent;
+            await ctx.managedBridge?.finish({
+                status: 'stopped',
+                artifacts: [...(ctx.declaredArtifacts ?? [])],
+                blocker: '用户停止，现场已保留',
+            });
+            yield { type: 'interrupted' };
             return;
         }
-        // 完成态也给一条 plugin_progress（放在 workflow_done 之前，保证
-        // workflow_done 仍是事件流最后一条——e2e 测试依赖 events[last]===workflow_done）。
-        yield {
-            type: 'plugin_progress',
-            pluginId: WF_PLUGIN_ID,
-            current: def.steps.length,
-            max: def.steps.length,
-            message: `✓ workflow ${def.name} 完成`,
+        const message = failure instanceof WorkflowScriptError
+            ? failure.message
+            : `工作流「${script.name}」执行失败：${failure instanceof Error ? failure.message : String(failure)}`;
+        // 工作流可以在 Error 上附带通用的 workflowOutcome。Runner 只透传这个
+        // 生命周期标签，不解释其业务含义。
+        const workflowOutcome = workflowOutcomeFromFailure(failure);
+        await state.recordFailure(message, [...(ctx.declaredArtifacts ?? [])]);
+        await state.appendProgress(`■ 失败：${message}`);
+        if (opts.parentStateDir)
+            throw failure;
+        const failureEvent = {
+            type: 'workflow_progress',
+            workflow: script.name,
+            runId: opts.runId,
+            rootRunId: opts.scope.rootRunId,
+            ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
+            depth: opts.depth,
+            phase: 'workflow',
+            status: 'warning',
+            message,
         };
-        // 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;
+        await state.appendEvent(failureEvent);
+        yield failureEvent;
+        await ctx.managedBridge?.finish({
+            status: 'failed',
+            artifacts: [...(ctx.declaredArtifacts ?? [])],
+            blocker: message,
+            ...(workflowOutcome ? { outcome: workflowOutcome } : {}),
+        });
+        yield { type: 'error', error: message };
+        return;
     }
-    finally {
-        // 成功时归档（保留 vars.json/progress.md/checkpoints 供后续回溯）；失败/中断时保留原状供排查与 resume
-        if (succeeded)
-            await state.archive();
+    // 把运行时经 declareArtifact() 登记的产物一并落盘 —— 只写 meta.artifacts
+    // 的话，循环体里的逐迭代产物会静默丢失（见 markDone 的注释）。
+    await state.markDone([...(ctx.declaredArtifacts ?? [])]);
+    await state.appendProgress(`✓ 完成（重放 ${journal.replayedCount} 次 / 上次账本 ${journal.loadedCount} 条）`);
+    const completeEvent = {
+        type: 'workflow_progress',
+        workflow: script.name,
+        runId: opts.runId,
+        rootRunId: opts.scope.rootRunId,
+        ...(opts.parentRunId ? { parentRunId: opts.parentRunId } : {}),
+        depth: opts.depth,
+        phase: 'workflow',
+        status: 'complete',
+        message: '执行完成',
+    };
+    await state.appendEvent(completeEvent);
+    yield completeEvent;
+    await state.archive();
+    const artifacts = (await state.allArtifacts()).map((p) => resolve(state.workingDir, p));
+    if (opts.parentStateDir)
+        return {
+            workflow: script.name,
+            runId: opts.runId,
+            result: scriptResult,
+            artifacts,
+            reused: false,
+        };
+    const result = scriptResult && typeof scriptResult === 'object'
+        ? scriptResult
+        : undefined;
+    const evidence = Array.isArray(result?.evidence)
+        ? result.evidence.map((item) => String(item))
+        : [];
+    const finished = await ctx.managedBridge?.finish({
+        status: 'verified',
+        artifacts,
+        evidence,
+    });
+    // ⚠️ 收尾状态必须过进程边界。传进去 'verified' 拿回来的很可能是
+    // 'ready_for_acceptance' —— 机器自检通过但还没人验收，这两者对宿主是天差地别。
+    // 就地丢弃会让 `-p --output-format json` 的宿主把「等待验收」读成「办完了」。
+    yield { type: 'turn_done', ...managedStatusOf(finished) };
+    return {
+        workflow: script.name,
+        runId: opts.runId,
+        result: scriptResult,
+        artifacts,
+        reused: false,
+    };
+}
+/**
+ * Read the structured outcome after the ESM loader has wrapped a workflow
+ * exception. The wrapper is deliberately treated as an implementation detail:
+ * both its own field and a bounded `cause` chain are accepted so the
+ * workflow → loader → runner path cannot silently downgrade budget_limited to
+ * a generic failed result.
+ */
+export function workflowOutcomeFromFailure(failure) {
+    let current = failure;
+    for (let depth = 0; depth < 8 && current && typeof current === 'object'; depth++) {
+        const outcome = current.workflowOutcome;
+        if (typeof outcome === 'string' && outcome.trim())
+            return outcome.trim();
+        current = current.cause;
     }
+    return undefined;
+}
+/** 从 bridge.finish 的返回值里取生命周期状态；拿不到就不带这个字段。 */
+function managedStatusOf(finished) {
+    const status = finished?.status;
+    return typeof status === 'string' ? { managedStatus: status } : {};
 }