@zhushanwen/pi-subagent-workflow 7.4.0 → 8.1.0

package/src/interface/views/__tests__/WorkflowsView-signature.test.ts

@@ -0,0 +1,264 @@
+/**
+ * computeRenderSignature（IF11/TC7/DM6）— 渲染签名单测（now 参数化）。
+ *
+ * 契约：tick 条件失效的判据——签名字段集覆盖 header（renderHeader）/节点行
+ * （renderLevel1 agent list）/L2 detail（buildDetailContent）当前消费的全部动态
+ * 字段。本测试证明「已入字段变化 → 签名变」+「静态 run 不变」（完备性无法靠
+ * 测试证明，字段核对表见 WorkflowsView.ts computeRenderSignature doc）。
+ *
+ * 确定性说明：签名非完全纯——live 节点 elapsedSeconds 由 projectLiveProgress 内
+ * computeElapsedSeconds 现算（record.endedAt ?? Date.now()）。fake timers 控制
+ * Date.now() 与 now 参数同源推进，保证确定性。
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+import { computeRenderSignature } from "../WorkflowsView.ts";
+import type { ExecutionRecord } from "../../../execution/types.ts";
+import type { ExecutionTraceNode, WorkerLogEntry } from "../../../orchestration/models/types.ts";
+import type { WorkflowRun } from "../../../orchestration/models/workflow-run.ts";
+
+// ── Fixtures（duck typing，对齐 detail-content-session-file.test.ts 先例）──
+
+const T0 = 1_700_000_000_000; // 固定 epoch ms
+
+function makeLive(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return {
+    id: "run-0",
+    agent: "worker",
+    model: "default",
+    thinkingLevel: undefined,
+    mode: "sync",
+    task: "t",
+    slug: "s",
+    startedAt: T0,
+    rootSessionId: undefined,
+    parentRecordId: undefined,
+    depth: 0,
+    status: "running",
+    turns: [],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: undefined,
+    endedAt: T0 + 5000,
+    result: undefined,
+    error: undefined,
+    agentResult: undefined,
+    ...overrides,
+  } as unknown as ExecutionRecord;
+}
+
+function makeNode(overrides: Partial<ExecutionTraceNode> = {}): ExecutionTraceNode {
+  return {
+    stepIndex: 0,
+    agent: "worker",
+    task: "do",
+    model: "default",
+    status: "running",
+    ...overrides,
+  };
+}
+
+interface RunShape {
+  status?: string;
+  budget?: { usedTokens: number; maxTokens?: number; usedCost: number };
+  nodes?: ExecutionTraceNode[];
+  errorLogs?: WorkerLogEntry[];
+}
+
+function makeRun(shape: RunShape = {}): WorkflowRun {
+  return {
+    state: {
+      status: shape.status ?? "running",
+      budget: shape.budget ?? { usedTokens: 0, maxTokens: 200_000, usedCost: 0 },
+      trace: { toArray: () => shape.nodes ?? [] },
+      errorLogs: shape.errorLogs ?? [],
+    },
+  } as unknown as WorkflowRun;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  vi.setSystemTime(T0);
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+describe("computeRenderSignature — 基础确定性", () => {
+  it("同输入同签名（含 live 节点，endedAt 固定使 elapsed 确定）", () => {
+    const run = makeRun({ nodes: [makeNode({ live: makeLive() })] });
+    expect(computeRenderSignature(run, T0)).toBe(computeRenderSignature(run, T0));
+  });
+
+  it("静态 run（无 live、同秒桶）200ms 内签名不变", () => {
+    const run = makeRun({ nodes: [makeNode({ status: "completed" })] });
+    expect(computeRenderSignature(run, T0)).toBe(computeRenderSignature(run, T0 + 200));
+  });
+
+  it("秒桶跨秒（now 相差 1s 桶）→ 签名变", () => {
+    const run = makeRun();
+    expect(computeRenderSignature(run, T0)).not.toBe(computeRenderSignature(run, T0 + 1000));
+  });
+});
+
+describe("computeRenderSignature — run 级字段", () => {
+  it("run.state.status 变化 → 签名变", () => {
+    const a = makeRun({ status: "running" });
+    const b = makeRun({ status: "done" });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("completed/total 变化（节点 status 推导）→ 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({ status: "running" })] });
+    const b = makeRun({ nodes: [makeNode({ status: "completed" })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("budget tokens 量化值变化 → 签名变", () => {
+    const a = makeRun({ budget: { usedTokens: 1500, maxTokens: 200_000, usedCost: 0.01 } });
+    const b = makeRun({ budget: { usedTokens: 2500, maxTokens: 200_000, usedCost: 0.01 } });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("budget cost 第 4 位小数变化（toFixed(4) 可见精度）→ 签名变", () => {
+    // 0.0100 vs 0.0101：量化展示相同到第 3 位，第 4 位是渲染可见精度
+    const a = makeRun({ budget: { usedTokens: 0, maxTokens: 200_000, usedCost: 0.0100 } });
+    const b = makeRun({ budget: { usedTokens: 0, maxTokens: 200_000, usedCost: 0.0101 } });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("run.state.errorLogs 追加 → 签名变（末条内容入指纹）", () => {
+    const a = makeRun({ errorLogs: [{ level: "error", message: "E-0" }] });
+    const b = makeRun({ errorLogs: [{ level: "error", message: "E-0" }, { level: "warn", message: "W-1" }] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("errorLogs 封顶后 length 不变内容移（push+slice(-MAX_ERROR_LOGS)）→ 签名仍变（指纹非 length）", () => {
+    // 模拟 error-recovery 的变异路径：push 后 slice(-500) 截断。两次 state 均 500 条
+    // （length 相同），仅末条/窗口内容不同——指纹含末条内容才不漏失效。
+    const MAX_ERROR_LOGS = 500;
+    const mk = (n: number): WorkerLogEntry[] => ({ level: "error", message: `E-${n}` });
+    const before: WorkerLogEntry[] = Array.from({ length: MAX_ERROR_LOGS }, (_, i) => mk(i));
+    const after = [...before, mk(MAX_ERROR_LOGS)].slice(-MAX_ERROR_LOGS); // E-1..E-500
+    expect(after).toHaveLength(MAX_ERROR_LOGS); // 前置校验：封顶后 length 不变
+    const a = makeRun({ errorLogs: before });
+    const b = makeRun({ errorLogs: after });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+});
+
+describe("computeRenderSignature — 节点级字段（live 投影）", () => {
+  it("节点 status 变化 → 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({ status: "running" })] });
+    const b = makeRun({ nodes: [makeNode({ status: "failed" })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("live.totalTokens 变化 → 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({ live: makeLive({ totalTokens: 1000 }) })] });
+    const b = makeRun({ nodes: [makeNode({ live: makeLive({ totalTokens: 2000 }) })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("getAllToolCalls(node.live).length 变化 → 签名变（toolCalls 追加）", () => {
+    const live1 = makeLive({
+      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "read", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 }] }],
+    });
+    const live2 = makeLive({
+      turns: [{ text: "", closed: false, toolCalls: [
+        { toolName: "read", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 },
+        { toolName: "bash", args: {}, result: "", isError: false, _status: "completed", startedTs: T0 },
+      ] }],
+    });
+    const a = makeRun({ nodes: [makeNode({ live: live1 })] });
+    const b = makeRun({ nodes: [makeNode({ live: live2 })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("live.elapsedSeconds 变化 → 签名变（running 节点跨秒）", () => {
+    // endedAt undefined → computeElapsedSeconds 用真实 Date.now()；fake timers 推进 1s
+    const live = makeLive({ endedAt: undefined });
+    const run = makeRun({ nodes: [makeNode({ live })] });
+    const before = computeRenderSignature(run, T0);
+    vi.setSystemTime(T0 + 1000);
+    const after = computeRenderSignature(run, T0 + 1000);
+    expect(after).not.toBe(before);
+  });
+
+  it("live.turns 计数变化 → 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({ live: makeLive({ turnCount: 1 }) })] });
+    const b = makeRun({ nodes: [makeNode({ live: makeLive({ turnCount: 2 }) })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("live.eventLog 追加（turn 闭合产生 turn_end 条目）→ 签名变", () => {
+    const live1 = makeLive({
+      turns: [{ text: "partial", closed: false, toolCalls: [] }],
+    });
+    const live2 = makeLive({
+      turns: [{ text: "partial", closed: true, closedTs: T0, toolCalls: [] }],
+    });
+    const a = makeRun({ nodes: [makeNode({ live: live1 })] });
+    const b = makeRun({ nodes: [makeNode({ live: live2 })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("live.currentActivity 出现 / 变化（type+label）→ 签名变", () => {
+    const noActivity = makeLive({ turns: [{ text: "", closed: false, toolCalls: [] }] });
+    const toolRunning = makeLive({
+      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "write", args: {}, result: "", isError: false, _status: "running", startedTs: T0 }] }],
+    });
+    const toolRunningOtherLabel = makeLive({
+      turns: [{ text: "", closed: false, toolCalls: [{ toolName: "bash", args: {}, result: "", isError: false, _status: "running", startedTs: T0 }] }],
+    });
+    const base = makeRun({ nodes: [makeNode({ live: noActivity })] });
+    const withTool = makeRun({ nodes: [makeNode({ live: toolRunning })] });
+    const otherLabel = makeRun({ nodes: [makeNode({ live: toolRunningOtherLabel })] });
+
+    const s0 = computeRenderSignature(base, T0);
+    expect(computeRenderSignature(withTool, T0)).not.toBe(s0); // 出现
+    expect(computeRenderSignature(otherLabel, T0)).not.toBe(computeRenderSignature(withTool, T0)); // label 变
+  });
+
+  it("live.lastError 出现（内容入签名）→ 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({ live: makeLive({ lastError: undefined }) })] });
+    const b = makeRun({ nodes: [makeNode({ live: makeLive({ lastError: "EPIPE: broken pipe" }) })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("node.sessionFile 出现 → 签名变", () => {
+    const a = makeRun({ nodes: [makeNode({})] });
+    const b = makeRun({ nodes: [makeNode({ sessionFile: "/tmp/sessions/run-0.jsonl" })] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+});
+
+describe("computeRenderSignature — 多节点与无 live 终态", () => {
+  it("多节点逐一拼接（节点序参与签名）", () => {
+    const run = makeRun({
+      nodes: [
+        makeNode({ stepIndex: 0, status: "completed" }),
+        makeNode({ stepIndex: 1, status: "running", live: makeLive({ totalTokens: 500 }) }),
+      ],
+    });
+    const sig = computeRenderSignature(run, T0);
+    expect(sig).toContain("0:completed:-:-1:-1:-1:-1:-1:-:-");
+    expect(sig).toContain("1:running:-:500:0:5:0:0:-:-");
+  });
+
+  it("节点重排（trace 数组序对调，stepIndex 维度）→ 签名变", () => {
+    // 同一节点集、字段值均不变，仅 trace 数组顺序对调——nodeParts 按 trace 序拼接，
+    // 首字段 stepIndex 随之换位，签名必变（不漏失效）。
+    const first = makeNode({ stepIndex: 0, status: "completed" });
+    const second = makeNode({ stepIndex: 1, status: "running", live: makeLive() });
+    const a = makeRun({ nodes: [first, second] });
+    const b = makeRun({ nodes: [second, first] });
+    expect(computeRenderSignature(a, T0)).not.toBe(computeRenderSignature(b, T0));
+  });
+
+  it("无节点 run 签名仅含 run 级五段（status/秒桶/completed-total/budget/errorLogs）", () => {
+    const sig = computeRenderSignature(makeRun({ nodes: [] }), T0);
+    expect(sig.split("|")).toHaveLength(5);
+  });
+});

package/src/interface/views/detail-content.ts

@@ -272,7 +272,7 @@ function renderOutcomeSection(
   if (node.status === "running" && node.live) {
     // 运行中：显示实时指标（elapsed/tokens/turns）替代空荡的 "Still running..."
     const live = projectLiveProgress(node.live);
-    const tokK = live.totalTokens > 0 ? `${Math.round(live.totalTokens / 1000)}k tok` : "0 tok";
+    const tokK = live.totalTokens > 0 ? `${Math.round(live.totalTokens / BUDGET_TOKENS_DIVISOR)}k tok` : "0 tok";
     rightLines.push(theme.fg("dim", `  Running · ${formatElapsedSeconds(live.elapsedSeconds)} · ${tokK} · ${live.turns} turn${live.turns !== 1 ? "s" : ""}`));
     if (live.lastError) {
       rightLines.push(theme.fg("warning", `  ⚠ ${live.lastError.slice(0, mainWidth - BOX_BORDER_CHARS)}`));

package/src/interface/views/format.ts

@@ -10,6 +10,7 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentEventLogEntry } from "../../execution/types.ts";
 import type { ExecutionTraceNode, ToolCallEntry } from "../../orchestration/models/types.ts";
 import type { DoneReason, RunStatus } from "../../orchestration/models/types.ts";
+import { displayAgentName } from "../../shared/agent-ref.ts";
 
 // ── Constants ─────────────────────────────────────────────────
 
@@ -39,7 +40,7 @@ const SECS_PER_MIN = 60;
 /**
  * 可显示的状态文本集合。
  *
- * 包含 RunStatus（"running"|"paused"|"done" 不直接显示，转 reason）+ DoneReason
+ * 包含 RunStatus（"running"|"done" 不直接显示，转 reason）+ DoneReason
  * （completed/failed/aborted/budget_limited/time_limited）+ ExecutionTraceNode.status
  * （含 "pending"——trace 节点的初始态）。
  *
@@ -85,7 +86,6 @@ export function formatStatusBadge(
 ): string {
   switch (status) {
     case "running": return theme.fg("warning", "\u25CF running");
-    case "paused": return theme.fg("warning", "\u23F8 PAUSED");
     case "completed": return theme.fg("success", "\u2713 completed");
     case "failed": return theme.fg("error", "\u2717 failed");
     case "aborted": return theme.fg("error", "\u2717 aborted");
@@ -311,7 +311,7 @@ export function formatAgentOneLiner(node: ExecutionTraceNode, theme: ThemeLike):
     ? `${Math.round((tok.input + tok.output) / TOKEN_K)}k tok`
     : "";
   const tcCount = node.result?.toolCalls?.length ?? 0;
-  const parts = [dot, node.agent, node.model];
+  const parts = [dot, displayAgentName(node.agent), node.model];
   if (tokStr) parts.push(`${tokStr} · ${tcCount} tools`);
   parts.push(elapsed);
   return parts.join("    ");

package/src/orchestration/__tests__/__fixtures__/worker-template.snapshot.txt

@@ -0,0 +1,333 @@
+"use strict";
+// Module-scope helpers: accessible to BOTH the IIFE body AND the outer
+// .then()/.catch() handlers (which run outside the IIFE). _workerLogs/
+// _pushWorkerLog/_safePost + the parentPort/workerData handles must all live
+// here — a previous version declared _safePost inside the IIFE, so the
+// .then()/.catch() return/error handlers threw ReferenceError: _safePost is
+// not defined, crashing the Worker on EVERY script return (exit code 1) and
+// losing all diagnostics. require() is cached, so destructuring once at module
+// load and reusing everywhere avoids the redundant require calls that used to
+// appear in the IIFE and the outer .then/.catch.
+const { parentPort: _parentPort, workerData: _workerData } = require("node:worker_threads");
+const _workerLogs = [];
+// IF6(#12): known agent() fields — hoisted to module scope, built once per worker
+// (was rebuilt inside agent() on every call; field set is call-invariant).
+const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel"]);
+function _pushWorkerLog(level, args) {
+  try { _workerLogs.push({ level, message: args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ") }); } catch (e) { /* swallow */ }
+}
+// ── safePostMessage wrapper: 统一 postMessage 防御（DataCloneError 等）──
+// Module-scope so the outer .then/.catch return/error handlers can use it.
+// context 取值约定（诊断标识）：固定为消息类型字面量——
+// "agent-call" / "workflow-call" / "return" / "error"，调用方据此在日志里
+// 一眼定位是哪类 postMessage 失败。新增调用点必须传对应 context。
+function _safePost(msg, context) {
+  try { _parentPort.postMessage(msg); return true; }
+  catch (e) {
+    const errMsg = e && e.message ? e.message : String(e);
+    const stack = e && e.stack ? e.stack : "";
+    _pushWorkerLog("error", ["[postMessage failed:" + context + "]", errMsg, stack]);
+    return false;
+  }
+}
+(async () => {
+  const parentPort = _parentPort;
+  const workerData = _workerData;
+
+  if (!parentPort) {
+    throw new Error("Workflow worker: parentPort is null — not running in a Worker thread");
+  }
+
+  // ── Intercept console.* to avoid leaking worker diagnostics into the input area ──
+  console.log = function (...args) { _pushWorkerLog("log", args); };
+  console.warn = function (...args) { _pushWorkerLog("warn", args); };
+  console.error = function (...args) { _pushWorkerLog("error", args); };
+  console.info = function (...args) { _pushWorkerLog("info", args); };
+
+  // ── Internal state ──
+  let _callIdCounter = 0;
+  let _agentCallCount = 0;
+  const _pendingCalls = new Map();
+  const _callCache = workerData.callCache instanceof Map
+    ? workerData.callCache
+    : new Map(Object.entries(workerData.callCache || {}).map(([k, v]) => [Number(k), v]));
+
+  // ── Injected globals ──
+  const $ARGS = (workerData.args && typeof workerData.args === "object") ? workerData.args : {};
+  const args = $ARGS;
+  const $WORKSPACE = typeof workerData.workspace === "string" ? workerData.workspace : "";
+  const _budgetData = {
+    total: (workerData.budget && workerData.budget.maxTokens) || 0,
+    _spentTokens: (workerData.budget && workerData.budget.usedTokens) ?? 0,
+    _spentCost: (workerData.budget && workerData.budget.usedCost) ?? 0,
+  };
+  const $BUDGET = {
+    get total() { return _budgetData.total; },
+    spent() { return _budgetData._spentTokens; },
+    remaining() { return Math.max(0, _budgetData.total - _budgetData._spentTokens); },
+  };
+
+  // ── Run-level model/thinkingLevel override (Option B symmetric single-path) ──
+  // Injected from workerData (set by workerHost from RunSpec.model/thinkingLevel).
+  // agent() reads these as run-level defaults; per-call explicit opts still win.
+  const $MODEL = (workerData.model && typeof workerData.model === "string") ? workerData.model : undefined;
+  const $THINKING_LEVEL = (workerData.thinkingLevel && typeof workerData.thinkingLevel === "string") ? workerData.thinkingLevel : undefined;
+
+  // ── WorkflowAbortedError ──
+  class WorkflowAbortedError extends Error {
+    constructor(reason) {
+      super("Workflow aborted: " + (reason || "No reason"));
+      this.name = "WorkflowAbortedError";
+      this.reason = reason || "";
+    }
+  }
+
+  // ── Message handler (main thread → worker) ──
+  parentPort.on("message", (msg) => {
+    if (msg.type === "agent-result") {
+      const pending = _pendingCalls.get(msg.callId);
+      if (pending) {
+        _pendingCalls.delete(msg.callId);
+        if (typeof msg.result !== "undefined") {
+          _callCache.set(msg.callId, msg.result);
+        }
+        // 失败不传播到 agent 外部：resolve 而非 reject。
+        // 旧实现在 result.error 时 reject，单 agent 失败会冒到 worker 顶层 .catch()
+        // → 发 type:"error" → handleScriptError → rebuildRuntime → SIGKILL 同伴进程，
+        // 把单点失败放大成整批崩溃。改为始终 resolve（错误时回退到 content 文本），
+        // 让 parallel() 下的脚本容错循环（parseResult → null → skip）自然接管。
+        // 错误原因已由主线程 executeAgentCall → trace.update(result.error) 保留在 trace/TUI，
+        // 不丢失。失败 resolve 为空字符串是既定容错策略。
+        // parsedOutput: validated data object from structured-output execute().
+        // Fallback to content (raw text) when no schema was requested or on error.
+        // W2 改动 9(b)：returnMeta===true 时 resolve {value,sessionFile,worktreePath,error,usage,durationMs,sessionId}
+        // （对称缓存重放 9c）；否则单值。usage/durationMs/sessionId 为 rfl 仪表透传（tier-1 §7.1，
+        // AgentResult 已含、此处原样转发，缺省 undefined 兼容旧主线程）。
+        const _value = msg.result.parsedOutput ?? msg.result.content;
+        if (pending.returnMeta) {
+          pending.resolve({
+            value: _value,
+            sessionFile: msg.result.sessionFile,
+            worktreePath: msg.result.worktreePath,
+            error: msg.result.error,
+            usage: msg.result.usage,
+            durationMs: msg.result.durationMs,
+            sessionId: msg.result.sessionId,
+          });
+        } else {
+          pending.resolve(_value);
+        }
+      }
+    } else if (msg.type === "workflow-result") {
+      const pending = _pendingCalls.get(msg.callId);
+      if (pending) {
+        _pendingCalls.delete(msg.callId);
+        pending.resolve(msg.result);
+      }
+    } else if (msg.type === "abort") {
+      const err = new WorkflowAbortedError(msg.reason);
+      _pendingCalls.forEach((p) => { p.reject(err); });
+      _pendingCalls.clear();
+    } else if (msg.type === "budget-update" && msg.budget) {
+      _budgetData._spentTokens = msg.budget.usedTokens ?? _budgetData._spentTokens;
+      _budgetData._spentCost = msg.budget.usedCost ?? _budgetData._spentCost;
+    }
+    // "budget-warning" is informational; no required handling
+  });
+
+  let _currentPhase = "";
+  function phase(name) { _currentPhase = String(name); }
+
+  function log(msg) {
+    try { parentPort.postMessage({ type: "log", phase: _currentPhase, message: String(msg) }); } catch(e) { /* swallow */ }
+  }
+
+  async function agent(firstArg, secondArg) {
+    let opts;
+    if (typeof firstArg === "string") {
+      opts = {
+        prompt: firstArg,
+        description: (secondArg && typeof secondArg === "object" && secondArg.label) || undefined,
+        schema: (secondArg && typeof secondArg === "object" && secondArg.schema) || undefined,
+        model: (secondArg && typeof secondArg === "object" && secondArg.model) || $MODEL,
+        scene: (secondArg && typeof secondArg === "object" && secondArg.scene) || undefined,
+        phase: (secondArg && typeof secondArg === "object" && secondArg.phase) || undefined,
+        thinkingLevel: (secondArg && typeof secondArg === "object" && secondArg.thinkingLevel) || $THINKING_LEVEL,
+      };
+    } else if (typeof firstArg === "object" && firstArg !== null) {
+      if (firstArg.prompt) {
+        opts = firstArg;
+      } else if (firstArg.task || firstArg.agent) {
+        // fork/worktree/returnMeta forwarded here (parity with agent({prompt,...}) and direct-pass
+        // branches). Previously this shortcut dropped them (w1 only noted, not wired).
+        opts = {
+          prompt: firstArg.task || firstArg.prompt || "",
+          description: firstArg.label || firstArg.description,
+          agent: firstArg.agent,
+          schema: firstArg.schema,
+          model: firstArg.model || $MODEL,
+          scene: firstArg.scene,
+          skill: firstArg.skill,
+          timeoutMs: firstArg.timeoutMs,
+          cwd: firstArg.cwd,
+          fork: firstArg.fork,
+          worktree: firstArg.worktree,
+          returnMeta: firstArg.returnMeta,
+          thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL,
+        };
+      } else {
+        opts = firstArg;
+      }
+    } else {
+      throw new Error("agent() requires a prompt string or options object as first argument");
+    }
+
+    // Run-level fallback for object branches (opts = firstArg direct assign).
+    // Priority: agent() explicit > $MODEL global (set from workerData.model).
+    if (!opts.model && $MODEL) opts.model = $MODEL;
+    if (!opts.thinkingLevel && $THINKING_LEVEL) opts.thinkingLevel = $THINKING_LEVEL;
+
+    // Validate known agent() fields to catch API misuse early (_KNOWN_FIELDS at module scope)
+    const _unknownFields = Object.keys(opts).filter((k) => !_KNOWN_FIELDS.has(k));
+    if (_unknownFields.length > 0) {
+      _pushWorkerLog("warn", ["[workflow] agent() received unknown fields: " + _unknownFields.join(", ") + ". Known fields: prompt, description, schema, model, scene, label, task, agent, phase, skill, timeoutMs, cwd, fork, worktree, returnMeta, thinkingLevel"]);
+    }
+
+    const callId = _callIdCounter;
+    _callIdCounter++;
+    _agentCallCount++;
+    if (_callCache.has(callId)) {
+      const cached = _callCache.get(callId);
+      // 与 live handler 对齐：失败也 resolve（回退 content），不 throw。
+      // 见 agent-result 消息处理的注释：拒绝传播失败到 agent 外部。
+      // W2 改动 9(c)：returnMeta 分支（对称 handler 9b），opts 仍在闭包作用域。
+      if (!cached) return undefined;
+      const _cachedValue = cached.parsedOutput ?? cached.content;
+      if (opts.returnMeta === true) {
+        return {
+          value: _cachedValue,
+          sessionFile: cached.sessionFile,
+          worktreePath: cached.worktreePath,
+          error: cached.error,
+          usage: cached.usage,
+          durationMs: cached.durationMs,
+          sessionId: cached.sessionId,
+        };
+      }
+      return _cachedValue;
+    }
+
+    const _effectivePhase = opts.phase || _currentPhase;
+    delete opts.phase;
+
+    if (!_safePost({ type: "agent-call", callId, opts, phase: _effectivePhase }, "agent-call")) {
+      return Promise.reject(new Error("postMessage failed for agent-call (callId=" + callId + "): see workerLogs"));
+    }
+    return new Promise((resolve, reject) => {
+      _pendingCalls.set(callId, { resolve, reject, returnMeta: opts.returnMeta === true });
+    });
+  }
+
+  async function parallel(calls) {
+    if (typeof calls === "function") { return calls(); }
+    const settled = await Promise.allSettled(calls.map((c) => {
+      if (c && typeof c.then === "function") { return c; }
+      if (typeof c === "function") { return c(); }
+      if (typeof c === "object" && c !== null && (c.task || c.agent)) { return agent(c); }
+      return agent(c);
+    }));
+    return settled.map((r) => {
+      if (r.status === "fulfilled") {
+        const v = r.value;
+        if (v !== null && typeof v === "object" && !Array.isArray(v)) {
+          // 主线程 fallback（postAgentResult/postResult serialization failed）回发的对象含 error 字段
+          // → 归一化为 failed 形状，与脚本侧 r.status === "failed" 检查统一
+          if (typeof v.error === "string" && v.error.length > 0) return { status: "failed", error: v.error };
+          return v;
+        }
+        return { status: "failed", error: "agent returned non-object result (type=" + typeof v + ")" };
+      }
+      const reason = r.reason;
+      const errMsg = reason instanceof Error ? reason.message : String(reason);
+      return { status: "failed", error: errMsg };
+    });
+  }
+
+  async function pipeline(firstArg, ...restStages) {
+    // Single-arg mode: pipeline([stage1, stage2, ...])
+    if (Array.isArray(firstArg) && restStages.length === 0) {
+      let result;
+      for (let i = 0; i < firstArg.length; i++) {
+        try { result = await firstArg[i](result); }
+        catch (e) {
+          const msg = e && e.message ? e.message : String(e);
+          _pushWorkerLog("error", ["[pipeline stage " + i + " failed]", msg]);
+          throw e;
+        }
+      }
+      return result;
+    }
+    // Cartesian product mode: pipeline([items], stage1, stage2, ...)
+    if (Array.isArray(firstArg) && restStages.length > 0 && typeof restStages[0] === "function") {
+      const results = [];
+      for (let idx = 0; idx < firstArg.length; idx++) {
+        const item = firstArg[idx];
+        let val = item;
+        let failed = false;
+        for (const stage of restStages) {
+          if (failed) break;
+          try { val = await stage(val); }
+          catch (e) {
+          const msg = e && e.message ? e.message : String(e);
+          _pushWorkerLog("error", ["[pipeline cartesian stage failed for item " + (idx + 1) + "]", msg]);
+          val = null; failed = true;
+          }
+        }
+        results.push(val);
+      }
+      return results;
+    }
+    throw new Error("pipeline() expects pipeline([stage1, ...]) or pipeline([items], stage1, ...)");
+  }
+
+  // ── workflow global — nested workflow invocation ──
+  async function workflow(name, args) {
+    if (typeof name !== "string" || name.length === 0) {
+      throw new Error("workflow() requires a workflow name string as first argument");
+    }
+    const workflowArgs = (typeof args === "object" && args !== null) ? args : {};
+    const callId = _callIdCounter;
+    _callIdCounter++;
+    if (!_safePost({ type: "workflow-call", callId, name, args: workflowArgs }, "workflow-call")) {
+      return Promise.reject(new Error("postMessage failed for workflow-call (name=" + name + "): see workerLogs"));
+    }
+    return new Promise((resolve, reject) => {
+      _pendingCalls.set(callId, { resolve, reject });
+    });
+  }
+
+  // ── User workflow script ──
+  // sample exercising template features
+const name = $ARGS.name ?? "default";
+phase("build");
+const spec = await agent("build it", { label: "builder", schema: { type: "object" } });
+const results = await parallel([
+  agent({ task: "unit tests", agent: "./tester.md" }),
+  agent({ task: "lint", agent: "./linter.md", skill: "lint-skill" }),
+]);
+await pipeline([(x) => x, (x) => x]);
+await workflow("deploy", { env: "prod" });
+log("done " + name + " " + $WORKSPACE + " " + $BUDGET.remaining());
+module.exports = { execute: async (ctx) => ctx.agent("finalize") };
+
+  // ── Auto-invoke execute() for module.exports pattern ──
+  if (typeof module !== "undefined" && module.exports && typeof module.exports.execute === "function") {
+    return await module.exports.execute({ agent, parallel, pipeline, phase, log, workflow, $ARGS, $WORKSPACE, $BUDGET });
+  }
+})().then((result) => {
+  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";
+  _safePost({ type: "return", runId, result, workerLogs: _workerLogs }, "return");
+}).catch((err) => {
+  const runId = (_workerData.args && typeof _workerData.args === "object" && _workerData.args._runId) || "";
+  _safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");
+});

package/src/orchestration/__tests__/args-validator.test.ts

@@ -93,7 +93,7 @@ describe("validateRunArgs — 校验语义", () => {
     const args = { targetType: "git-diff", target: "main", autoCommit: "false", maxRounds: "10" };
     const spec = makeSpec(reviewFixLoopParameters(), args);
     expect(() => validateRunArgs(spec)).not.toThrow();
-    expect(spec.args).toBe(args); // 原地 mutate，引用不变（worker/resume 同一对象）
+    expect(spec.args).toBe(args); // 原地 mutate，引用不变（worker 启动/崩溃重跑同一对象）
     expect(spec.args.autoCommit).toBe(false);
     expect(spec.args.maxRounds).toBe(10);
   });