minimal-agent 0.12.0 → 0.14.0

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

@@ -1,604 +1,560 @@
 /**
  * ============================================================
- *  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, executeTool, getWorkingDir, type LoopEvent } 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 { 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 type { ControlDeps, ControlOutcome } from './controlFlow/types.js';
-import { runStepWithRetry, type CpScope } from './stepPipeline.js';
-import type {
-  RunContext,
-  StepDef,
-  StepKind,
-  StepResult,
-  WorkflowDef,
-  WorkflowEvent,
-} from './types.js';
-import { normalizeCapture, VarStack } from './types.js';
+import type { LoopEvent } from '../../../src/plugin-sdk.js';
+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 type { RunContext, WorkflowScript } from './types.js';
 import {
-  loopCheckpointName,
-  WorkflowState,
-  type LoopResumeInfo,
-} from './workflowState.js';
+  type WorkflowBundle,
+  resolveWorkflowBundle,
+} from './workflowDependencies.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。）
- */
 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: { name: string; type: string; required?: boolean }[],
-  inputValues: Record<string, unknown>,
-): string {
-  let goalValue: string | undefined;
+/** 事件队列：生产者随时 push，消费者按序 async 迭代，close 后排空即结束。 */
+class EventQueue<T> {
+  private items: T[] = [];
+  private waiter: (() => void) | null = null;
+  private closed = false;
 
-  // 策略 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(item: T): void {
+    this.items.push(item);
+    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();
-      }
-    }
+  close(): void {
+    this.closed = true;
+    this.waiter?.();
+    this.waiter = null;
   }
 
-  if (!goalValue) return '';
-
-  return `> 🎯 用户原始目标：${truncateGoal(goalValue)}\n> ⚠️ 所有操作必须直接回应此目标，不可偏离或遗忘。`;
-}
-
-/** 截断过长目标（>200 字符时保留首尾，中间用 … 连接）——goalAnchor 注入每步 prompt，必须紧凑。 */
-function truncateGoal(goal: string): string {
-  return goal.length > 200 ? `${goal.slice(0, 120)}…${goal.slice(-60)}` : goal;
-}
-
-/** 可中断的退避等待：用户 abort 时立即返回（让后续步骤检查 signal 收口，不在这里抛）。 */
-function sleepInterruptible(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise((resolve) => {
-    if (signal?.aborted) {
-      resolve();
-      return;
+  async *drain(): AsyncGenerator<T, void, void> {
+    while (true) {
+      while (this.items.length > 0) {
+        yield this.items.shift() as T;
+      }
+      if (this.closed) return;
+      await new Promise<void>((resolve) => {
+        this.waiter = resolve;
+      });
     }
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, ms);
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      resolve();
-    };
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
+  }
 }
 
-/**
- * runSteps 的返回信号——区分退出方式，根治「break 与 halt 合流」：
- *   - 'completed'  : 该 block 正常跑完
- *   - 'halted'     : error / interrupted / onError:halt / 表达式错误（上游应中止）
- *   - FlowSignal   : break / continue 循环信号（工作流不算失败）。
- *       target 缺省 = 最近一层循环消费；指定 target 时信号穿透中间层循环上抛，
- *       直到 id 匹配的 loop 消费（break=停止迭代 / continue=跳到下一轮）。
- *       目标不存在时冒泡到顶层按正常完成处理（与游离 break 同语义）。
- * 关键差异：break/continue 只影响循环迭代，循环之后的兄弟步应继续；halt 才真正向上中止。
- */
-interface FlowSignal {
-  signal: 'break' | 'continue';
-  target?: string;
+export interface RunWorkflowOptions {
+  ctx: RunContext;
+  inputs: Record<string, unknown>;
+  sessionId?: string;
 }
-type StepFlow = 'completed' | 'halted' | FlowSignal;
-
 
-/** 把一段用户输入并入贯穿目标（内存 + 状态目录持久化，resume 不丢）。 */
-async function addGoalSupplement(
-  ctx: RunContext,
-  state: WorkflowState,
-  text: string,
-): Promise<void> {
-  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);
+export interface WorkflowCallResult {
+  workflow: string;
+  runId: string;
+  result: unknown;
+  artifacts: string[];
 }
 
-function stepKind(step: StepDef): StepKind {
-  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 已校验），兜底
+interface ExecutionOptions extends RunWorkflowOptions {
+  bundle: WorkflowBundle;
+  scope: ExecutionScope;
+  parentStateDir?: string;
+  taskId?: string;
+  runId: string;
+  parentRunId?: string;
+  depth: number;
 }
 
-
-
-
-function resolvePositiveIterationLimit(
-  raw: number | string | undefined,
-  vars: VarStack,
-  defaultValue: number,
-  label: string,
-): { ok: true; value: number } | { ok: false; error: string } {
-  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: WorkflowScript,
+  opts: RunWorkflowOptions,
+): AsyncGenerator<LoopEvent, void, void> {
+  try {
+    const bundle = await resolveWorkflowBundle(
+      script,
+      effectiveWorkflowCwd(opts.ctx),
+    );
+    opts.ctx.resourceLedger ??= {
+      inputTokens: 0,
+      outputTokens: 0,
+      limit: null,
+      trustworthy: true,
     };
-  }
-  return { ok: true, value: Math.floor(n) };
-}
-
-/**
- * 分发"动作"型 step（tool / agent / llm / skill / assert）到对应 executor。
- * 控制流 step（branch / loop / pause 等）由 runSteps 直接处理，不走这里。
- */
-async function* dispatchActionStep(
-  step: StepDef,
-  vars: VarStack,
-  ctx: RunContext,
-): AsyncGenerator<LoopEvent, StepResult, void> {
-  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: StepDef[],
-  vars: VarStack,
-  ctx: RunContext,
-  state: WorkflowState,
-  // checkpoint 记录范围：顶层调用（runWorkflow → def.steps）传 { name: id=>id, descendIntoLoop:true }；
-  // 顶层 loop 的 do[] 由 loop 处理器派生复合名 scope；更深嵌套传 undefined（不记录）。
-  cp?: CpScope,
-  // resume：本列表中索引 < startFrom 的步已在上次运行完成，本次跳过（变量已由 runWorkflow 回放）。
-  // 顶层与「loop resume 进迭代中间」（loop 处理器对 do[] 传 innerStartFrom）都用它。
-  startFrom = 0,
-  // 仅顶层传：进行中循环的恢复信息（迭代号 + 迭代内起点），由匹配 id 的 loop 消费一次。
-  loopResume?: LoopResumeInfo,
-): AsyncGenerator<WorkflowEvent | LoopEvent, StepFlow, void> {
-  for (let i = 0; i < steps.length; i++) {
-    const step = steps[i];
-    if (ctx.signal?.aborted) {
-      yield { type: 'interrupted' };
-      return 'halted';
+    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();
     }
-
-    // resume：跳过已完成的步（变量已回放，无需重跑）。
-    if (i < startFrom) {
+  } catch (error) {
+    if (
+      opts.ctx.signal?.aborted ||
+      (error instanceof Error && error.name === 'AbortError')
+    )
+      yield { type: 'interrupted' };
+    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 as Error).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: 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: string) => addGoalSupplement(ctx, state, text),
-    };
-    let outcome: ControlOutcome | null = 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: string) => 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: WorkflowDef): string[] {
-  const out = new Set<string>();
-  for (const a of def.artifacts ?? []) out.add(a);
-  const walk = (steps: StepDef[] | undefined): void => {
-    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: WorkflowDef,
-  inputs: Record<string, unknown>,
-  ctx: RunContext,
-): AsyncGenerator<WorkflowEvent | LoopEvent, void, void> {
-  const vars = new VarStack();
-  vars.setGlobal('inputs', inputs);
-
-  // onError:'recover' 用：把工作流总目标（description）透传给恢复 agent，
-  // 让它知道「这条工作流到底想干什么」。已有 goal 则不覆盖。
-  const runCtx: RunContext = { ...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: WorkflowScript,
+  opts: ExecutionOptions,
+): AsyncGenerator<
+  LoopEvent,
+  (WorkflowCallResult & { reused: boolean }) | undefined,
+  void
+> {
+  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: string[] = [];
-  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,
-    }),
+    scriptHash,
+    script.meta.artifacts ?? [],
+    ctx.managedExecution || opts.parentStateDir
+      ? undefined
+      : buildTaskArbitrator({
+          provider: ctx.provider,
+          chat: ctx.chat,
+          executeTool: ctx.executeTool,
+          signal: ctx.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 };
+  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: '恢复已完成结果',
+    } as const;
+    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 语义不受影响。
-  if (resume.mode === 'resume') {
-    // 贯穿补充要求：上次运行累积的（pause 反馈 / 澄清结论）从状态目录恢复，
-    // resume 后注入每步锚定不丢失。
-    runCtx.goalSupplements = await state.readSupplements();
-  }
+  // 目标锚：仲裁判定的延续要锚**旧目标**，本次输入降级成补充要求。
+  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' && 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);
-    }
+  if (resume.mode === 'resume') {
+    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);
-      }
-    }
-    // 循环中断恢复：回放中断时刻的最近 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 queue = new EventQueue<LoopEvent>();
+  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 as Record<string, string>,
+        defs: bundle.script.meta.inputs,
+        attachments: [],
+      });
+      const childInputs = coerceInputs(
+        bound.inputs as Record<string, string>,
+        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: RunContext = {
+        ...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);
+        }
+      } 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 };
-  }
-
-  // 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}`,
-  };
+    },
+  });
 
-  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,
+  if (resume.supplementaryGoal) {
+    await ((workflowContext as any).state.addGoalSupplement as (t: string) => Promise<void>)(
+      resume.supplementaryGoal,
     );
-    // '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}` };
+  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}`,
+  } as const;
+  await state.appendEvent(startEvent);
+  yield startEvent;
+
+  let failure: unknown = null;
+  let scriptResult: unknown;
+  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: '用户中断，现场已保留',
+      } as const;
+      await state.appendEvent(interruptedEvent);
+      yield interruptedEvent;
+      await ctx.managedBridge?.finish({
+        status: 'stopped',
+        artifacts: [...(ctx.declaredArtifacts ?? [])],
+        blocker: '用户停止，现场已保留',
+      });
+      yield { type: 'interrupted' };
       return;
     }
+    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,
+    } as const;
+    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;
+  }
 
-    // 完成态也给一条 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} 完成`,
+  // 把运行时经 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: '执行完成',
+  } as const;
+  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 as { evidence?: unknown })
+      : 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,
+  };
+}
 
-    // 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;
-  } finally {
-    // 成功时归档（保留 vars.json/progress.md/checkpoints 供后续回溯）；失败/中断时保留原状供排查与 resume
-    if (succeeded) await state.archive();
+/**
+ * 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: unknown,
+): string | undefined {
+  let current = failure;
+  for (
+    let depth = 0;
+    depth < 8 && current && typeof current === 'object';
+    depth++
+  ) {
+    const outcome = (current as { workflowOutcome?: unknown }).workflowOutcome;
+    if (typeof outcome === 'string' && outcome.trim()) return outcome.trim();
+    current = (current as { cause?: unknown }).cause;
   }
+  return undefined;
+}
+
+/** 从 bridge.finish 的返回值里取生命周期状态；拿不到就不带这个字段。 */
+function managedStatusOf(finished: unknown): { managedStatus?: string } {
+  const status = (finished as { status?: unknown } | undefined)?.status;
+  return typeof status === 'string' ? { managedStatus: status } : {};
 }