@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/{error-recovery-handlers.test.ts → worker-message-pump-handlers.test.ts}

@@ -1,7 +1,7 @@
 /**
- * error-recovery handlers — handleWorkerExit/Error/ScriptError + postBudgetUpdate 测试。
+ * worker-message-pump handlers — handleWorkerExit/Error/ScriptError + postBudgetUpdate 测试。
  *
- * 参考 error-recovery-workflow-call.test.ts 的 mock 构建。通过 vi.useFakeTimers() 跳过
+ * 参考 worker-message-pump-workflow-call.test.ts 的 mock 构建。通过 vi.useFakeTimers() 跳过
  * scheduleRebuild 的指数退避（1s/2s/4s）。
  *
  * 覆盖：
@@ -23,14 +23,15 @@ import {
   handleWorkerMessage,
   postBudgetUpdate,
   rebuildRuntime,
-} from "../error-recovery.ts";
+} from "../worker-message-pump.ts";
 import { Budget } from "../models/budget.ts";
 import { RunRuntime } from "../models/run-runtime.ts";
 import { Trace } from "../models/trace.ts";
-import type { AgentResult } from "../models/types.ts";
+import type { AgentResult, DoneReason, RunStatus } from "../models/types.ts";
 import { WorkflowRun } from "../models/workflow-run.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkerHandle } from "../worker-handle.ts";
+import { flushMicrotasks } from "./helpers/flush-microtasks.ts";
 
 // ── helpers ──────────────────────────────────────────────────
 
@@ -70,26 +71,34 @@ function makeRunningRun(opts: {
       receivedTerminalMessage: opts.receivedTerminalMessage,
     },
     // transition 副作用——run.state.status 由调用方通过 mock 控制后再次断言
-    transition(target: string, reason?: string): void {
+    transition(this: WorkflowRun, target: RunStatus, reason?: DoneReason): void {
       this.state.status = target;
       if (target === "done") this.state.reason = reason;
     },
-    replaceRuntime(rt: unknown): void {
+    replaceRuntime(this: WorkflowRun, rt: NonNullable<WorkflowRun["runtime"]>): void {
       this.runtime = rt;
     },
   } as unknown as WorkflowRun;
 }
 
-/** LifecycleDeps mock：store/workerHost/runner/eventBus/scheduleTimeBudget 可观察。 */
+/** LifecycleDeps mock：store/workerHost/runner/eventBus/scheduleTimeBudget 可观察。
+ *  mock 成员 = 真实签名 & vi.fn 能力（交叉纯 Mock 会丢真实签名，传回被测函数即报错）。 */
+type MockLifecycleDeps = Omit<
+  LifecycleDeps,
+  "store" | "workerHost" | "runner" | "eventBus" | "onRunDone" | "log"
+> & {
+  // 真实类型整体保留（RunStore/WorkerHost 等接口成员完整），仅 mock 方法交叉 vi.fn 能力
+  store: LifecycleDeps["store"] & { save: LifecycleDeps["store"]["save"] & ReturnType<typeof vi.fn> };
+  workerHost: LifecycleDeps["workerHost"] & { start: LifecycleDeps["workerHost"]["start"] & ReturnType<typeof vi.fn> };
+  runner: LifecycleDeps["runner"] & { run: LifecycleDeps["runner"]["run"] & ReturnType<typeof vi.fn> };
+  eventBus: NonNullable<LifecycleDeps["eventBus"]> & { emit: NonNullable<LifecycleDeps["eventBus"]>["emit"] & ReturnType<typeof vi.fn> };
+  onRunDone: LifecycleDeps["onRunDone"] & ReturnType<typeof vi.fn>;
+  log: LifecycleDeps["log"] & ReturnType<typeof vi.fn>;
+};
+
 function makeDeps(opts: {
   scheduleTimeBudget?: LifecycleDeps["scheduleTimeBudget"];
-} = {}): LifecycleDeps & {
-  store: { save: ReturnType<typeof vi.fn> };
-  workerHost: { start: ReturnType<typeof vi.fn> };
-  eventBus: { emit: ReturnType<typeof vi.fn> };
-  onRunDone: ReturnType<typeof vi.fn>;
-  log: ReturnType<typeof vi.fn>;
-} {
+} = {}): MockLifecycleDeps {
   return {
     store: { save: vi.fn(async () => {}) },
     workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
@@ -343,7 +352,7 @@ describe("rebuildRuntime", () => {
 
   it("带 budgetTimeMs 时重排 scheduleTimeBudget 计时器", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());
@@ -412,7 +421,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
     // 已耗 70%（3500ms）→ 剩余 1500ms；fake Date 冻结，elapsed 精确
     run.meta.startedAt = new Date(Date.now() - 3500).toISOString();
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());
@@ -428,7 +437,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
     // 已耗 6000ms > 预算 5000ms（退避 advance 1000ms 后已耗 7000ms，仍耗尽）
     run.meta.startedAt = new Date(Date.now() - 6000).toISOString();
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     const p = handleScriptError(run, "boom", [], deps, makeHandlers());
@@ -451,7 +460,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
 
   it("预算未耗尽（fresh run）→ 照常 rebuild，不误转 time_limited（防误伤回归）", async () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 }); // startedAt ≈ now，remaining 满
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     const p = handleScriptError(run, "boom", [], deps, makeHandlers());
@@ -481,14 +490,6 @@ function createDeferred<T>(): Deferred<T> {
   return { promise, resolve, reject };
 }
 
-/** flush 微任务队列（dispatch 的 fire-and-forget promise 链推进到稳定态）。 */
-async function flushMicrotasks(ticks = 10): Promise<void> {
-  for (let i = 0; i < ticks; i++) {
-    // eslint-disable-next-line no-await-in-loop -- 排空微任务队列的固定 tick 循环（fire-and-forget promise 链推进到稳定态），非逐项等待
-    await Promise.resolve();
-  }
-}
-
 /** 构造真实 WorkflowRun（真实状态机/replaceRuntime/Trace/Budget）+ 初始 RunRuntime。 */
 function makeRealRun(runId: string, opts: { budgetTimeMs?: number } = {}): WorkflowRun {
   const run = new WorkflowRun(
@@ -752,7 +753,7 @@ describe("rebuildRuntime 可观察性（OB3 日志点）", () => {
 
   it("U7: 带 budgetTimeMs + scheduleTimeBudget 注入时含 L2（在 L1 之后、L3 之前，payload 含 budgetTimeMs）", () => {
     const run = makeRealRun("wf-rebuild-log-2", { budgetTimeMs: 5000 });
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());

package/src/orchestration/__tests__/{error-recovery-postmessage-defense.test.ts → worker-message-pump-postmessage-defense.test.ts}

@@ -1,4 +1,4 @@
-// src/orchestration/__tests__/error-recovery-postmessage-defense.test.ts
+// src/orchestration/__tests__/worker-message-pump-postmessage-defense.test.ts
 //
 // W2: 主线程层 postMessage 防御测试。
 //
@@ -35,13 +35,13 @@ vi.mock("../../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { handleWorkerMessage, postBudgetUpdate } from "../error-recovery.ts";
+import { handleWorkerMessage, postBudgetUpdate } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ERROR_RECOVERY_SRC = readFileSync(
-  join(__dirname, "../error-recovery.ts"),
+const WORKER_MESSAGE_PUMP_SRC = readFileSync(
+  join(__dirname, "../worker-message-pump.ts"),
   "utf-8",
 );
 
@@ -273,7 +273,7 @@ describe("W2b: dispatchWorkflowCall postResult 防御 DataCloneError", () => {
 // 子进程）。利用这一点构造行为测试——往 cached.result 里塞不可克隆值（function），
 // mock postMessage 在首次发送 agent-result 时抛 DataCloneError，验证 fallback 路径。
 //
-// 另外补充：验证 error-recovery.ts 源码中三处 postMessage 调用点都有 try/catch 包裹，
+// 另外补充：验证 worker-message-pump.ts 源码中三处 postMessage 调用点都有 try/catch 包裹，
 // 防止未来重构误删防御（类似 worker-script-builder.test.ts 的源码字符串断言模式）。
 
 /** 构造 status="running" 且 calls 已含一个 done 结果（含不可克隆成员）的 mock run。
@@ -376,7 +376,7 @@ describe("W2c: postAgentResult 防御（源码结构断言）", () => {
   }
 
   it("postAgentResult 包含 try/catch + fallback result", () => {
-    const match = ERROR_RECOVERY_SRC.match(/function postAgentResult\([\s\S]*?\n\}/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/function postAgentResult\([\s\S]*?\n\}/);
     expect(match, "postAgentResult 函数定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
     // fallback 通过共享工厂 makeSerializeFailedResult 构造纯字符串 result（必可克隆）
@@ -387,14 +387,14 @@ describe("W2c: postAgentResult 防御（源码结构断言）", () => {
   });
 
   it("postBudgetUpdate 包含 try/catch", () => {
-    const match = ERROR_RECOVERY_SRC.match(/export function postBudgetUpdate\([\s\S]*?\n\}/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/export function postBudgetUpdate\([\s\S]*?\n\}/);
     expect(match, "postBudgetUpdate 函数定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
   });
 
   it("dispatchWorkflowCall postResult 闭包包含 try/catch + fallback", () => {
     // postResult 是 const 闭包，匹配到下一个 }; 结尾
-    const match = ERROR_RECOVERY_SRC.match(/const postResult = \(result[\s\S]*?\n  \};/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/const postResult = \(result[\s\S]*?\n  \};/);
     expect(match, "postResult 闭包定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
     expect(match![0]).toContain("Workflow result serialization failed");

package/src/orchestration/__tests__/{error-recovery-serialize-failed-result.test.ts → worker-message-pump-serialize-failed-result.test.ts}

@@ -1,4 +1,4 @@
-// src/orchestration/__tests__/error-recovery-serialize-failed-result.test.ts
+// src/orchestration/__tests__/worker-message-pump-serialize-failed-result.test.ts
 //
 // makeSerializeFailedResult 独立单测（W2 防御关键纯函数）。
 //
@@ -15,7 +15,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { makeSerializeFailedResult } from "../error-recovery.ts";
+import { makeSerializeFailedResult } from "../worker-message-pump.ts";
 
 describe("makeSerializeFailedResult", () => {
   it("返回 {content:'', error:'<prefix>: <errMsg>'} 形状（必可克隆 fallback）", () => {

package/src/orchestration/__tests__/{error-recovery-workflow-call.test.ts → worker-message-pump-workflow-call.test.ts}

@@ -10,7 +10,7 @@
  */
 import { describe, expect, it, vi } from "vitest";
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 

package/src/orchestration/__tests__/worker-pending-timeout-abort.test.ts

@@ -0,0 +1,275 @@
+/**
+ * [OR-3] worker 侧 pending per-call timeoutMs + abort 广播 测试（真实 Worker 线程，P-T3）。
+ *
+ * 覆盖（unbounded-wait-audit §4.1 OR-3 / §7.2 T3③ / §7.3 P-T3）：
+ * - agent() 传 timeoutMs：主线程不回话 → pending 以错误 resolve（不 reject、不放大成
+ *   脚本 error）+ 超时 warn 记入 _workerLogs——消息层自己的超时，旧实现零超时永挂
+ * - returnMeta 模式超时 resolve {value:"", error}
+ * - 主线程不传 timeoutMs（缺省不限）：pending 不挂 timer（行为不变）
+ * - abort 广播：await 中的 agent() 以 WorkflowAbortedError reject（脚本 catch 可感知
+ *   取消）→ 脚本自然收尾 → worker 自然退出（exit 0）
+ * - P-T3：abort 广播与 worker 自然退出交错不产 unhandledRejection——广播后立即
+ *   terminate 的竞态、fire-and-forget 后 return 的自然退出，均不产生主线程
+ *   unhandledRejection 与 worker 'error' 事件
+ */
+import { Worker } from "node:worker_threads";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+// ── 判别联合（对齐 worker-script-builder-runtime.test.ts 的守卫形态） ──
+
+interface ReturnMsg {
+  type: "return";
+  result: unknown;
+  workerLogs?: Array<{ level: string; message: string }>;
+}
+interface ErrorMsg {
+  type: "error";
+  error: string;
+  workerLogs?: Array<{ level: string; message: string }>;
+}
+
+function isReturn(m: unknown): m is ReturnMsg {
+  return typeof m === "object" && m !== null && (m as { type?: unknown }).type === "return";
+}
+function isError(m: unknown): m is ErrorMsg {
+  return typeof m === "object" && m !== null && (m as { type?: unknown }).type === "error";
+}
+function isAgentCall(m: unknown): m is { type: "agent-call"; callId: number } {
+  return typeof m === "object" && m !== null && (m as { type?: unknown }).type === "agent-call";
+}
+
+// ── harness：主线程「不回话」的可控 Worker 运行器 ──────────────
+
+interface RunResult {
+  returnValue?: unknown;
+  errorMessage?: string;
+  /** return/error 消息带回的 workerLogs（超时 warn 通路）。 */
+  workerLogs: Array<{ level: string; message: string }>;
+  exitCode?: number;
+  workerError?: string;
+  /** 收到的 agent-call 消息数（确认脚本确实发起了调用）。 */
+  agentCallCount: number;
+}
+
+interface RunOptions {
+  /** 收到 agent-call 后的主线程动作（默认：不回话——pending 留在 worker 侧）。 */
+  onAgentCall?: (msg: { callId: number; opts: Record<string, unknown> }, worker: Worker) => void;
+  /** 显式 finish（供 abort 竞态场景手工收尾）。 */
+  timeoutMs?: number;
+}
+
+const createdWorkers: Worker[] = [];
+
+afterEach(() => {
+  for (const w of createdWorkers.splice(0)) {
+    w.terminate().catch(() => {});
+  }
+});
+
+function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult> {
+  const timeoutMs = opts.timeoutMs ?? (process.env.CI ? 5000 : 2000);
+  return new Promise((resolve) => {
+    const worker = new Worker(buildWorkerScript(userScript), {
+      eval: true,
+      workerData: {
+        scriptPath: "test.js",
+        args: {},
+        workspace: process.cwd(),
+        budget: { maxTokens: 0, usedTokens: 0, usedCost: 0 },
+      },
+    });
+    createdWorkers.push(worker);
+
+    const result: RunResult = { workerLogs: [], agentCallCount: 0 };
+    let settled = false;
+    const finish = (): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      clearTimeout(graceTimer);
+      resolve(result);
+    };
+    // 兜底：永不 settle 时 terminate + 以当前观察收尾
+    const timer = setTimeout(() => {
+      worker.terminate().catch(() => {});
+      finish();
+    }, timeoutMs);
+    // 收到终态消息后的宽限窗：给潜在 worker 'error' 事件一个到达机会，
+    // 然后收尾（parentPort 挂着 message listener 时 worker 线程不自然退出，
+    // 与生产一致由 terminate 回收——故不依赖 exit 事件断言）。
+    let graceTimer: ReturnType<typeof setTimeout>;
+
+    worker.on("message", (raw: unknown) => {
+      if (isAgentCall(raw)) {
+        result.agentCallCount += 1;
+        opts.onAgentCall?.(raw as unknown as { callId: number; opts: Record<string, unknown> }, worker);
+        return;
+      }
+      if (isReturn(raw)) {
+        result.returnValue = raw.result;
+        result.workerLogs = raw.workerLogs ?? [];
+        graceTimer = setTimeout(finish, 150);
+        return;
+      }
+      if (isError(raw)) {
+        result.errorMessage = raw.error;
+        result.workerLogs = raw.workerLogs ?? [];
+        graceTimer = setTimeout(finish, 150);
+      }
+    });
+    worker.on("error", (err: Error) => {
+      result.workerError = err.message;
+    });
+    worker.on("exit", (code: number) => {
+      result.exitCode = code;
+      finish();
+    });
+  });
+}
+
+/** 收集本测试进程的 unhandledRejection（P-T3 断言）。 */
+function trackUnhandledRejections(): { reasons: unknown[]; dispose: () => void } {
+  const reasons: unknown[] = [];
+  const handler = (reason: unknown): void => {
+    reasons.push(reason);
+  };
+  process.on("unhandledRejection", handler);
+  return { reasons, dispose: () => process.off("unhandledRejection", handler) };
+}
+
+// ── [OR-3] per-call timeoutMs（消息层自己的超时） ─────────────
+
+describe("[OR-3] agent() pending per-call timeoutMs", () => {
+  it("主线程不回话 + timeoutMs=50 → pending 以错误 resolve（[B-5] 单值错误消息字符串）", async () => {
+    const script = `
+      const r = await agent("never answered", { timeoutMs: 50 });
+      return { got: r };
+    `;
+    const res = await runWorker(script);
+
+    // 脚本正常 return（超时未放大成脚本 error → 不触发 rebuild 矩阵）
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.workerError).toBeUndefined();
+    expect(res.agentCallCount).toBe(1);
+    // [B-5] 非 returnMeta 超时 resolve 单值字符串（对齐 agent-result 失败路径
+    // resolve _value = parsedOutput ?? content 的形态）——字符串消费型脚本
+    // （r.trim() 类）不再 TypeError
+    const got = (res.returnValue as { got: string }).got;
+    expect(typeof got).toBe("string");
+    expect(got).toContain("timed out after 50ms");
+    expect(got).toContain("no agent-result received");
+    // 超时 warn 记入 _workerLogs（诊断可见）
+    expect(res.workerLogs.some((l) => l.level === "warn" && l.message.includes("timed out after 50ms"))).toBe(true);
+  });
+
+  it("returnMeta 模式超时（对象分支透传 returnMeta）→ resolve {value:\"\", error}", async () => {
+    const script = `
+      const r = await agent({ prompt: "never answered", timeoutMs: 50, returnMeta: true });
+      return r;
+    `;
+    const res = await runWorker(script);
+
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.returnValue).toEqual({ value: "", error: expect.stringContaining("timed out after 50ms") });
+  });
+
+  it("[B-5] 字符串消费型脚本（r.trim()）在超时路径不 TypeError（resolve 单值字符串）", async () => {
+    // 旧实现超时 resolve {content:"", error} 对象 → r.trim() 抛 TypeError →
+    // 脚本 error → 放大成 rebuild；修复后 resolve 字符串，脚本按普通失败文本消费
+    const script = `
+      const r = await agent("never answered", { timeoutMs: 40 });
+      return { trimmed: r.trim().length > 0 };
+    `;
+    const res = await runWorker(script);
+
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.workerError).toBeUndefined();
+    expect(res.returnValue).toEqual({ trimmed: true });
+  });
+
+  it("string+secondArg 分支：timeoutMs 透传到 agent-call 消息 opts（此前该分支丢弃该字段）", async () => {
+    let seenOpts: Record<string, unknown> | undefined;
+    const script = `await agent("with timeout", { timeoutMs: 1234, label: "probe" }); return "unreachable";`;
+    await runWorker(script, {
+      onAgentCall: (msg, worker) => {
+        seenOpts = msg.opts;
+        // 回发结果让脚本收尾（透传断言与挂起行为解耦）
+        worker.postMessage({ type: "agent-result", callId: msg.callId, result: { content: "ok" }, cached: false });
+      },
+    });
+
+    expect(seenOpts?.timeoutMs).toBe(1234);
+    expect(seenOpts?.prompt).toBe("with timeout");
+  });
+});
+
+// ── [OR-3] abort 广播（worker 侧接收） ───────────────────────
+
+describe("[OR-3] abort 广播接收（P-T3：交错不产 unhandledRejection）", () => {
+  it("await 中的 agent() 收到 abort → WorkflowAbortedError → 脚本 catch 后自然 return → exit 0", async () => {
+    const script = `
+      try {
+        await agent("will be aborted");
+        return "should not reach";
+      } catch (e) {
+        return { caught: e.name, reason: e.reason };
+      }
+    `;
+    const res = await runWorker(script, {
+      onAgentCall: (msg, worker) => {
+        worker.postMessage({ type: "abort", reason: "run aborted by user" });
+      },
+    });
+
+    expect(res.workerError).toBeUndefined();
+    expect(res.errorMessage).toBeUndefined();
+    expect(res.returnValue).toEqual({ caught: "WorkflowAbortedError", reason: "run aborted by user" });
+  });
+
+  it("广播后立即 terminate（竞态）：无 worker error、无 unhandledRejection", async () => {
+    const tracked = trackUnhandledRejections();
+    try {
+      const script = `return await agent("race with terminate");`;
+      const res = await runWorker(script, {
+        onAgentCall: (msg, worker) => {
+          // 广播与 terminate 同 tick 发出——模拟 abortRun 的广播→transition(terminate) 竞态
+          worker.postMessage({ type: "abort", reason: "race" });
+          void worker.terminate();
+        },
+      });
+      // 无论脚本是否来得及收尾：主线程侧无 error 事件、进程无 unhandledRejection
+      expect(res.workerError).toBeUndefined();
+      // 给潜在异步 unhandledRejection 一个窗口
+      await new Promise((r) => { setTimeout(r, 20); });
+      expect(tracked.reasons).toEqual([]);
+    } finally {
+      tracked.dispose();
+    }
+  });
+
+  it("fire-and-forget agent() 后脚本 return：无 worker error（超时/abort 通路外的孤儿 pending 不产 rejection）", async () => {
+    const script = `
+      agent("fire and forget");
+      return "returned early";
+    `;
+    const res = await runWorker(script, { timeoutMs: 400 });
+
+    expect(res.returnValue).toBe("returned early");
+    expect(res.workerError).toBeUndefined();
+  });
+
+  it("fire-and-forget + timeoutMs：超时 resolve（非 reject）→ 无 worker error 事件", async () => {
+    const script = `
+      agent("orphan with timeout", { timeoutMs: 40 });
+      return "returned before timeout";
+    `;
+    const res = await runWorker(script, { timeoutMs: 600 });
+
+    // 超时以 resolve 收口（容错策略）——即使无人消费该 promise 也不产 rejection
+    expect(res.returnValue).toBe("returned before timeout");
+    expect(res.workerError).toBeUndefined();
+  });
+});

package/src/orchestration/__tests__/worker-script-builder-runtime.test.ts

@@ -53,6 +53,12 @@ interface ErrorMsg {
   error: string;
   workerLogs?: unknown[];
 }
+/** log 消息：脚本 log() 全局发出的独立诊断消息（协议见 worker-script-builder 头注释）。 */
+interface LogMsg {
+  type: "log";
+  phase?: string;
+  message?: string;
+}
 
 // ── 类型守卫：从 unknown 收窄到判别联合 ──
 // 共享 hasType 辅助：避免每个守卫重复 `(m as {type?:string})` 断言（taste/no-unsafe-catch）。
@@ -74,16 +80,23 @@ function isReturn(m: unknown): m is ReturnMsg {
 function isError(m: unknown): m is ErrorMsg {
   return hasType(m, "error");
 }
+function isLog(m: unknown): m is LogMsg {
+  return hasType(m, "log");
+}
 
 // ── 测试辅助：起一个真实 Worker 跑 buildWorkerScript 产物 ──────────────
 
 interface RunResult {
   /** 收到的 return 消息的 result 字段（脚本正常结束时）。 */
   returnValue?: unknown;
+  /** return 消息带回的 workerLogs（[B-3] 起只含 console.* 捕获条目，log() 不再走此通路）。 */
+  returnWorkerLogs?: unknown[];
   /** 收到的 error 消息的 error 字段（脚本 throw 时）。 */
   errorMessage?: string;
   /** error 消息带回的 workerLogs（验证诊断不丢）。 */
   errorWorkerLogs?: unknown[];
+  /** 收到的 {type:"log"} 独立消息列表（[B-3] 起 log() 的唯一通路）。 */
+  logMessages: LogMsg[];
   /** Worker exit code（0=正常，1=崩溃）。 */
   exitCode?: number;
   /** Worker 'error' 事件的错误消息（uncaught exception，正常应为 undefined）。 */
@@ -94,6 +107,15 @@ interface RunResult {
   workflowCalls: WorkflowCallMsg[];
 }
 
+/** workerLogs 条目守卫收窄 + message 包含判定（元素类型 unknown，断言前先收窄）。 */
+function someLogMessageContains(logs: unknown[] | undefined, text: string): boolean {
+  return (logs ?? []).some((l) => {
+    if (typeof l !== "object" || l === null) return false;
+    const message = (l as { message?: unknown }).message;
+    return typeof message === "string" && message.includes(text);
+  });
+}
+
 interface RunOptions {
   /** $ARGS。 */
   args?: Record<string, unknown>;
@@ -144,7 +166,7 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
     // S8：创建后立即登记，afterEach 兜底清理（防止 promise 泄漏导致 Worker 未终止）
     createdWorkers.push(worker);
 
-    const result: RunResult = { agentCalls: [], workflowCalls: [] };
+    const result: RunResult = { agentCalls: [], workflowCalls: [], logMessages: [] };
     let agentCallIdx = 0;
     let resolved = false;
     const timer = setTimeout(() => {
@@ -181,8 +203,13 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
         result.workflowCalls.push(raw);
         const wfResult = opts.handleWorkflowCall ? opts.handleWorkflowCall(raw) : { ok: true };
         worker.postMessage({ type: "workflow-result", callId: raw.callId, result: wfResult });
+      } else if (isLog(raw)) {
+        // [OR-6/T7④] 独立 log 消息收集（主线程真实 runtime 当前无消费 case，测试
+        // harness 收集以断言「协议消息仍发出」通路不被回退）。
+        result.logMessages.push(raw);
       } else if (isReturn(raw)) {
         result.returnValue = raw.result;
+        result.returnWorkerLogs = raw.workerLogs;
         finish(result);
       } else if (isError(raw)) {
         result.errorMessage = raw.error;
@@ -382,6 +409,56 @@ describe("buildWorkerScript runtime — 之前缺失的路径覆盖", () => {
   });
 });
 
+// ── [B-3] log() 单通路可观测性 ─────────────────────────────────────
+// 旧双通路（log() 同时 post 独立消息 + 记入 _workerLogs 随 return/error 带回）让
+// 同一日志在主线程 errorLogs 占两格、TUI 双份。修复后 log() 只发独立 {type:"log"}
+// 消息，主线程 handleWorkerLog 即时消费（error-recovery.ts）；崩溃场景丢 log 条目
+// 可接受（log 是 T7 补充可观测）。
+
+describe("buildWorkerScript runtime — [B-3] log() 单通路", () => {
+  it("log() 发出独立 {type:\"log\"} 消息且携带 phase（主线程即时消费的唯一通路）", async () => {
+    const script = `
+      phase("build");
+      log("hello from script");
+      return { ok: true };
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    expect(res.logMessages).toEqual([{ type: "log", phase: "build", message: "hello from script" }]);
+    expect(res.exitCode).not.toBe(1);
+  });
+
+  it("log() 内容不再随 return 消息的 workerLogs 带回（双份入账已退役）", async () => {
+    const script = `
+      phase("build");
+      log("hello from script");
+      return { ok: true };
+    `;
+    const res = await runWorker(script);
+    expect(res.workerError).toBeUndefined();
+    // workerLogs 中不得出现 log() 的条目（否则主线程 log case + workerLogs 双份入账）
+    expect(someLogMessageContains(res.returnWorkerLogs, "hello from script")).toBe(false);
+  });
+
+  it("log() 内容不再随 error 消息的 workerLogs 带回（console.* 捕获通路不受影响）", async () => {
+    const script = `
+      log("before-crash");
+      console.error("crash-context");
+      throw new Error("boom");
+    `;
+    const res = await runWorker(script);
+    expect(res.errorMessage).toBe("boom");
+    // log() 的条目不在 error workerLogs（单通路）
+    expect(someLogMessageContains(res.errorWorkerLogs, "before-crash")).toBe(false);
+    // console.* 捕获通路保持（workerLogs 仍带回 console.error 条目）
+    expect(res.errorWorkerLogs).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ level: "error", message: "crash-context" }),
+      ]),
+    );
+  });
+});
+
 // ── W2: agent() returnMeta 模式运行时验证 ───────────────────────────
 // 现有 worker-script-builder.test.ts 的 16 条 returnMeta 断言全是字符串 toContain，
 // 无法验证「真实 Worker 线程执行时 agent({returnMeta:true}) resolve 出对象、

package/src/orchestration/__tests__/worker-script-builder.test.ts

@@ -225,7 +225,7 @@ describe("buildWorkerScript — W2 agent() returnMeta mode", () => {
 // ── thinkingLevel 参数透传（agent() 三分支） ──
 // 验证 thinkingLevel 在 string / task-agent / object.prompt 三个分支均被透传至
 // agent-call 的 opts，且加入 _knownFields 白名单（object.prompt 分支整体透传，
-// 不被 unknown-fields warn 误报）。底层 AgentCallOpts→mapToExecuteOptions→
+// 不被 unknown-fields warn 误报）。底层 AgentCallOpts（D6 合流后 EnginePort 直传，
 // buildSpawnArgs 拼 pi CLI --model provider/modelId:thinkingLevel 已打通，
 // 此处只验入口层 wiring。