@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Cross-host shared subagent execution layer and workflow orchestration core (dual-form npm package: TS source for workspace, dist ESM+CJS for npm)",
   "type": "module",
   "license": "MIT",
@@ -72,7 +72,7 @@
       "default": "./workflows/*"
     }
   },
-  "$comment": "D5 公共 API 面定稿（docs/design/subagent-core-package-extraction.md §3.3 D5）：公共面 = 主入口 barrel + 4 条语义子入口（./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）+ ./workflows/* 资产子入口。exports 面 = semver 契约，收窄不放宽。双形态（D4）：workspace TS 消费走 import 条件 -> src（与 extension-protocol 先例同型）；npm 消费走 publishConfig 发布面（npm publish 时整体替换 exports）：import -> dist ESM、require -> dist CJS。require 条件指向 dist CJS 是本仓首例，D4 依据：zsw 宿主为纯 CJS（node>=20），而 core 依赖的 @xyz-agent/extension-protocol npm dist 仅 ESM（.mjs），node 20 下 require() 加载 ESM 不可靠——因此对 extension-protocol 设 noExternal 防御性 bundle 边界（当前 entry 闭包无其运行时引用、dist 实测零常量命中；未来 entry 一旦引入运行时引用即 bundle），绝不让外部 ESM 依赖出现在 require 链上；require 分支的 types 用 .d.cts 对应。开发态 require 条件即指向 dist：dist 是 require 语义的真实载体，未 build 时 require 失败属预期（build 前置）。语义子入口精确条目优先于 `./*` 通配（Node 规范：exact match beats pattern），`./*` -> src 通配仅为仓内壳侧深路径消费保留（壳侧 `<pkg>/<域>/<路径>.ts` 形态 import，量级百处、以 grep 实测为准，不在此固化易过期数字），发布面刻意不带该通配——npm 消费面收窄到上列受控入口。workflows/ 资产 .cjs/.js 不编译（D1：src=dist 同字节直发），require/import 条件同径。tsup 多入口保形输出见 tsup.config.ts（dist/<entry> 与 src 同构，d.ts/d.cts 全覆盖）。",
+  "$comment": "D5 公共 API 面定稿（docs/design/subagent-core-package-extraction.md §3.3 D5）：公共面 = 主入口 barrel + 4 条语义子入口（./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）+ ./workflows/* 资产子入口。exports 面 = semver 契约，收窄不放宽。双形态（D4）：workspace TS 消费走 import 条件 -> src（与 extension-protocol 先例同型）；npm 消费走 publishConfig 发布面（npm publish 时整体替换 exports）：import -> dist ESM、require -> dist CJS。require 条件指向 dist CJS 是本仓首例，D4 依据：zsw 宿主为纯 CJS（node>=20），而 core 依赖的 @xyz-agent/extension-protocol npm dist 仅 ESM（.mjs），node 20 下 require() 加载 ESM 不可靠——因此对 extension-protocol 设 noExternal 防御性 bundle 边界（当前 entry 闭包无其运行时引用、dist 实测零常量命中；未来 entry 一旦引入运行时引用即 bundle），绝不让外部 ESM 依赖出现在 require 链上；require 分支的 types 用 .d.cts 对应。开发态 require 条件即指向 dist：dist 是 require 语义的真实载体，未 build 时 require 失败属预期（build 前置）。D5 豁免终止（post-convergence 设计 §3.2 B-2 / D5-补注，2026-09）：曾为此保留的 `./*` -> src 开发态通配已删除——壳侧深路径豁免终止，生产消费收口到主入口 barrel（137 符号，逐名可审）与上列受控子入口，删通配后壳再写深路径 = tsc 编译错误（不再是风格问题）；壳测试侧带 .ts 后缀的深路径（from/vi.mock/动态 import）经壳 vitest.config.ts 正则 alias 物理解析到 core src（生产 barrel import 无路径段、子入口 specifier 无 .ts 后缀，均不命中该 alias），不经 exports——生产走 exports / 测试走 alias 的双轨解析对通配删除免疫。发布面从不带该通配，npm 消费面维持上列受控入口不变。workflows/ 资产 .cjs/.js 不编译（D1：src=dist 同字节直发），require/import 条件同径。tsup 多入口保形输出见 tsup.config.ts（dist/<entry> 与 src 同构，d.ts/d.cts 全覆盖）。",
   "files": [
     "src/",
     "workflows/",
@@ -84,7 +84,7 @@
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.8.0"
+    "@xyz-agent/extension-protocol": "0.8.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/src/__tests__/agent-opts-resolver-schema-prompt.test.ts

@@ -44,7 +44,6 @@ describe("resolveAgentOpts schema prompt wording + M2 content passthrough", () =
       prompt: "x",
       agent: "/abs/path/worker.md",
       description: "test",
-      slug: "test",
     };
     const result = resolveAgentOpts(opts);
 

package/src/__tests__/append-system-prompt-assembly.test.ts

@@ -66,7 +66,7 @@ vi.mock("../execution/alive-store.ts", () => ({
   writeAliveMarker: vi.fn(),
 }));
 
-vi.mock("../execution/temp-prompt.ts", () => ({
+vi.mock("../execution/engine/engines/pi/temp-prompt.ts", () => ({
   writePromptToTempFile: vi.fn(async (agent: string, content: string) => {
     captured.calls++;
     captured.content = content;
@@ -79,7 +79,7 @@ vi.mock("../execution/temp-prompt.ts", () => ({
 import { spawn } from "node:child_process";
 
 import { createRecord } from "../execution/execution-record.ts";
-import { runSpawn, type RunOptions, type SessionRunnerContext } from "../execution/session-runner.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../execution/engine/engines/pi/session-runner.ts";
 
 const mockSpawn = vi.mocked(spawn);
 
@@ -116,8 +116,9 @@ function makeRecord() {
   return createRecord(`append-asm-${seq}`, {
     agent: "general-purpose",
     model: "test/model",
-    mode: "sync",
+    mode: "background",
     task: "test task",
+    slug: "append-asm",
     startedAt: Date.now(),
     rootSessionId: "s1",
     parentRecordId: undefined,
@@ -127,7 +128,7 @@ function makeRecord() {
 
 function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
   return {
-    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    resolved: { model: { provider: "test", id: "model", name: "Model", reasoning: false }, thinkingLevel: undefined },
     agentConfig: undefined,
     appendSystemPrompt: undefined,
     skillPath: undefined,
@@ -178,7 +179,7 @@ describe("writeAppendSystemPromptFile 组装（经 runSpawn 驱动）", () => {
   it("全片段组装：env block → agent body → 调用方片段 → wrap-up hint，顺序稳定", async () => {
     const content = await captureAppendContent(
       makeRunOpts({
-        agentConfig: { systemPrompt: "AGENT-BODY-MARKER" },
+        agentConfig: { name: "worker", systemPrompt: "AGENT-BODY-MARKER" },
         appendSystemPrompt: ["FRAG-ONE", "FRAG-TWO"],
         maxTurns: 5,
       }),
@@ -207,7 +208,7 @@ describe("writeAppendSystemPromptFile 组装（经 runSpawn 驱动）", () => {
   });
 
   it("ask_user RPC 提示 mode 门控：rpc（gui 响应）注入，json（headless）不注入", async () => {
-    const opts = makeRunOpts({ agentConfig: { tools: ["ask_user"] } });
+    const opts = makeRunOpts({ agentConfig: { name: "worker", systemPrompt: "", tools: ["ask_user"] } });
     const rpcContent = await captureAppendContent(opts, makeCtx({ mode: "rpc" }));
     expect(rpcContent).toContain("ask_user Tool Availability");
     const jsonContent = await captureAppendContent(opts, makeCtx({ mode: "json" }));
@@ -217,7 +218,7 @@ describe("writeAppendSystemPromptFile 组装（经 runSpawn 驱动）", () => {
 
   it("mode 响应但 tools 不含 ask_user → 不注入", async () => {
     const content = await captureAppendContent(
-      makeRunOpts({ agentConfig: { tools: ["read", "bash"] } }),
+      makeRunOpts({ agentConfig: { name: "worker", systemPrompt: "", tools: ["read", "bash"] } }),
       makeCtx({ mode: "rpc" }),
     );
     expect(content).not.toContain("ask_user Tool Availability");

package/src/__tests__/fr4-get-state-handshake.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect,it } from "vitest";
 
-import { parseSpawnLine } from "../execution/spawn-event-adapter";
-import { sendGetStateCommand } from "../execution/stdin-writer";
+import { parseSpawnLine } from "../execution/engine/engines/pi/spawn-event-adapter";
+import { sendGetStateCommand } from "../execution/engine/engines/pi/stdin-writer";
 
 describe("FR-4: get_state RPC handshake", () => {
   describe("sendGetStateCommand", () => {

package/src/__tests__/m2-append-content-probe.test.ts

@@ -19,7 +19,6 @@ describe("M2 append-content probe (design.json TC1)", () => {
       schema: { type: "object", properties: { ok: { type: "boolean" } } },
       agent: "/fake/agents/worker.md",
       description: "m2-probe",
-      slug: "m2-probe",
     };
 
     const result = resolveAgentOpts(opts);

package/src/__tests__/manifest-store.test.ts

@@ -58,7 +58,7 @@ describe("ManifestStore", () => {
   });
 
   afterEach(() => {
-    fs.rmSync(tmpDir, { recursive: true, force: true });
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   describe("writeManifest", () => {
@@ -108,7 +108,7 @@ describe("ManifestStore", () => {
       };
 
       // Delete the directory to cause write failure
-      fs.rmSync(tmpDir, { recursive: true, force: true });
+      fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 
       await expect(store.writeManifest(record)).rejects.toThrow();
     });
@@ -205,7 +205,7 @@ describe("ManifestStore", () => {
   describe("listAllSync (A3)", () => {
     it("正常读：返回目录下所有合法 manifest", async () => {
       await store.writeManifest({ id: "a-1", rootSessionId: "s", agentName: "w", status: "running" as const, createdAt: 1 });
-      await store.writeManifest({ id: "a-2", rootSessionId: "s", agentName: "w", status: "completed" as const, createdAt: 2 });
+      await store.writeManifest({ id: "a-2", rootSessionId: "s", agentName: "w", status: "closed" as const, createdAt: 2 });
       const all = store.listAllSync();
       expect(all.length).toBe(2);
       expect(all.map((r) => r.id).sort()).toEqual(["a-1", "a-2"]);
@@ -240,8 +240,9 @@ describe("ManifestStore", () => {
     });
   });
 
-  // ── M3: 4 态 status 枚举（running/completed/failed/cancelled；crashed 不进 manifest）──
-  describe("4 态 status 枚举 (M3)", () => {
+  // ── M3: status 枚举（SP-1 后 running/closed/cancelled 三态；crashed 不进 manifest，
+  //    历史 completed/failed 由读侧 mapManifestStatus 映射为 closed）──
+  describe("status 枚举 (M3)", () => {
     it("cancelled 能写入 + 读回（不再归并 failed）", async () => {
       const record = {
         id: "test-cancelled-4state",
@@ -257,14 +258,14 @@ describe("ManifestStore", () => {
       expect(result?.status).toBe("cancelled");
     });
 
-    it("listAllSync 接受 4 态（含 cancelled）", async () => {
+    it("listAllSync 接受全部合法态（含 cancelled）", async () => {
       await store.writeManifest({ id: "s-running", rootSessionId: "s", agentName: "w", status: "running" as const, createdAt: 1 });
-      await store.writeManifest({ id: "s-completed", rootSessionId: "s", agentName: "w", status: "completed" as const, createdAt: 2 });
-      await store.writeManifest({ id: "s-failed", rootSessionId: "s", agentName: "w", status: "failed" as const, createdAt: 3 });
+      await store.writeManifest({ id: "s-completed", rootSessionId: "s", agentName: "w", status: "closed" as const, createdAt: 2 });
+      await store.writeManifest({ id: "s-failed", rootSessionId: "s", agentName: "w", status: "closed" as const, createdAt: 3 });
       await store.writeManifest({ id: "s-cancelled", rootSessionId: "s", agentName: "w", status: "cancelled" as const, createdAt: 4 });
       const all = store.listAllSync();
       expect(all.length).toBe(4);
-      expect(all.map((r) => r.status).sort()).toEqual(["cancelled", "completed", "failed", "running"]);
+      expect(all.map((r) => r.status).sort()).toEqual(["cancelled", "closed", "closed", "running"]);
     });
 
     it("isValidManifest 拒绝 crashed（crashed 不进 manifest）", async () => {

package/src/__tests__/record-store-cache.test.ts

@@ -66,7 +66,6 @@ describe("RecordStore per-file cache + light scan [perf]", () => {
           agent: opts.agent ?? "worker",
           mode: "background",
           task: "test task",
-          slug: "test",
           startedAt: opts.startedAt ?? 1000,
           rootSessionId: opts.rootSessionId ?? "root-1",
           depth: 0,
@@ -266,7 +265,6 @@ describe("RecordStore per-file cache + light scan [perf]", () => {
     const mem = {
       id: "sa-1",
       agent: "worker",
-      slug: "test",
       status: "running",
       mode: "background",
       startedAt: 1000,

package/src/__tests__/record-store-index.test.ts

@@ -78,11 +78,11 @@ describe("sessions-index 模块（S1TC10-12）", () => {
     return {
       mtimeMs: 111,
       size: 222,
+      slug: "t",
       id: "sa-1",
       agent: "worker",
       mode: "background",
       task: "test task",
-      slug: "test",
       startedAt: 1000,
       rootSessionId: "root-1",
       parentRecordId: undefined,
@@ -208,7 +208,6 @@ describe("RecordStore 索引接入 [perf L-1]（S1TC1-9/13）", () => {
           agent: opts.agent ?? "worker",
           mode: "background",
           task: "test task",
-          slug: "test",
           startedAt: opts.startedAt ?? 1000,
           rootSessionId: opts.rootSessionId ?? "root-1",
           depth: 0,

package/src/__tests__/review-fix-loop-script.test.ts

@@ -286,7 +286,9 @@ describe("review-fix-loop.js 模块形态约束", () => {
     // 本 import 语句同时是静态依赖边：让依赖分析把该 workflow 文件纳入测试可达域
     // （CRAP 覆盖估算）。顶层 return / require 决定了 import 必然 reject——这是
     // workflow 脚本的固有形态，抽取测试法（本文件）因此是唯一可行的直测途径。
-    await expect(import("../../workflows/review-fix-loop.js")).rejects.toThrow();
+    // `as string` 使 import() 参数脱离字面量模块解析（该文件顶层 return，非合法模块，
+// 本就无类型可锚）；esbuild 转译剥除断言后运行时与字面量形态完全一致
+    await expect(import("../../workflows/review-fix-loop.js" as string)).rejects.toThrow();
   });
 });
 
@@ -320,7 +322,7 @@ describe("review-fix-loop.js fixAgent=fallow-scan 显式拒收（RX2-F2）", ()
   });
 
   afterEach(() => {
-    rmSync(sandboxDir, { recursive: true, force: true });
+    rmSync(sandboxDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
   });
 
   /** -e 探针体：AsyncFunction 复刻 worker 模板宿主形态（workerData/$ARGS/log 注入）。 */

package/src/__tests__/review-fix-loop-utils.test.ts

@@ -450,7 +450,7 @@ describe("reconcileIssues", () => {
     const r = reconcileIssues(prev, { seenIds: new Set(), escalateIds: new Set(), round: 2, stuckThreshold: 3 });
     expect(r.issues["MF-1"].status).toBe("fixed");
     expect(r.issues["MF-2"].status).toBe("fixed");
-    expect(r.issues["MF-2"].history.at(-1).status).toBe("fixed");
+    expect(r.issues["MF-2"].history!.at(-1)!.status).toBe("fixed");
     expect(r.stuck).toBe(false);
     expect(r.knownRemaining).toEqual([]);
   });
@@ -495,7 +495,7 @@ describe("reconcileIssues", () => {
     expect(r.issues["MF-1"].status).toBe("regressed");
     expect(r.issues["MF-1"].fixAttempts).toBe(2);
     expect(r.issues["MF-1"].openStreak).toBe(1);
-    expect(r.issues["MF-1"].history.at(-1).status).toBe("regressed");
+    expect(r.issues["MF-1"].history!.at(-1)!.status).toBe("regressed");
     expect(r.stuck).toBe(false);
   });
   it("fixed 未再被报告（未 seen）→ 保持 fixed，不误转 regressed（MF-2）", () => {
@@ -616,7 +616,7 @@ describe("reconcileIssues escalate + fixAttempts 起点", () => {
       { seenIds: [], escalateIds: ["S-1"], round: 3, stuckThreshold: 3 },
     );
     expect(rec.issues["S-1"].status).toBe("open");
-    expect(rec.issues["S-1"].history.at(-1).status).toBe("escalated");
+    expect(rec.issues["S-1"].history!.at(-1)!.status).toBe("escalated");
     expect(rec.knownRemaining).toEqual([]);
   });
   it("deferred 无 escalate → 留 known-remaining", () => {
@@ -1194,8 +1194,8 @@ describe("T-2 端到端：normIssueId/findIssueKey 在 validateFixResult 的真
 
 // ── T-3：reconcile 新 ID severity:"unknown" 守卫分支 ──────────────────────
 // validateFixResult 的 tracked severity 交叉核对：trackedIssues 中某 ID 的 severity
-// 为 "unknown"（reconcileIssues 给新发现 ID 的默认值，review-fix-loop-utils.cjs:596
-// `severity: "unknown"`）时不覆盖 fix agent 自报 severity——守卫在 cjs:294-299（仅认
+// 为 "unknown"（reconcileIssues 给新发现 ID 的默认值，review-fix-loop-utils.cjs:935
+// `severity: "unknown"`）时不覆盖 fix agent 自报 severity——守卫在 cjs:347-355（仅认
 // critical/major/minor/trivial 为真实等级）。现有 MF-4 测试覆盖了 major/critical/minor
 // tracked + 无此 ID，缺 "unknown" 分支。守卫目的：新发现 ID 的 severity 尚未由 reviewer
 // 结构化确认（reconcile 默认 unknown），不应凭默认值把合法 minor deferral 误升级为违规。
@@ -1251,7 +1251,7 @@ describe("A5 resolveRunRoot: 存储根解析（git slug / 非 git cwd / home 不
       expect(root).toBe(join(home, ".review-fix-loop", "Users-x-proj-my-repo", "wf-test-1"));
       expect(made).toEqual([root]);
     } finally {
-      rmSync(home, { recursive: true, force: true });
+      rmSync(home, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -1269,7 +1269,7 @@ describe("A5 resolveRunRoot: 存储根解析（git slug / 非 git cwd / home 不
       expect(slug).toBe("tmp-plain-docs");
       expect(root).toBe(join(home, ".review-fix-loop", "tmp-plain-docs", "run-42"));
     } finally {
-      rmSync(home, { recursive: true, force: true });
+      rmSync(home, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -1294,7 +1294,7 @@ describe("A5 resolveRunRoot: 存储根解析（git slug / 非 git cwd / home 不
       expect(root).toBe(join(fallbackTmp, "review-fix-loop", "wf-test-2"));
       expect(made).toEqual([root]);
     } finally {
-      rmSync(fallbackTmp, { recursive: true, force: true });
+      rmSync(fallbackTmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 
@@ -1313,7 +1313,7 @@ describe("A5 resolveRunRoot: 存储根解析（git slug / 非 git cwd / home 不
       expect(existsSync(root)).toBe(true);
       expect(root).toContain(join(home, ".review-fix-loop", "Users-x-a b-c", "wf-real-1"));
     } finally {
-      rmSync(home, { recursive: true, force: true });
+      rmSync(home, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
   });
 });
@@ -1791,7 +1791,7 @@ describe("filterDormantFromRecon + applyCleanRoundBackfill 的 dormant 分区",
     const out = applyCleanRoundBackfill(state, { reconSeen: new Set(["MF-D1"]), reconEscalate: new Set(), round: 2, stuckThreshold: 3 });
     // 过滤生效：MF-D1 不经对账通道建 issue（复活唯一入口 = 聚合活跃重报）
     expect(out.state.issues["MF-D1"]).toBeUndefined();
-    expect(out.state.dormant[0].revived).toBe(false);
+    expect(out.state.dormant![0].revived).toBe(false);
   });
 });
 

package/src/__tests__/robustness-low-batch1.test.ts

@@ -7,14 +7,15 @@
 //（run.state.errorLogs = ...），每次重试的诊断日志都被最后一次覆盖丢失。
 // 修复：改为 push + 截断（MAX_ERROR_LOGS=500 防无界增长）。
 //
-// 测试搭建方式参照 error-recovery-handlers.test.ts（mock LifecycleDeps + WorkflowRun）。
+// 测试搭建方式参照 worker-message-pump-handlers.test.ts（mock LifecycleDeps + WorkflowRun）。
 // - handleScriptError 是 export 的 async function，直接 import 调用
 // - handleReturn 不是 export 的——通过 handleWorkerMessage 发 { type: "return", ... } 触发
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { handleScriptError, handleWorkerMessage } from "../orchestration/error-recovery.ts";
+import { handleScriptError, handleWorkerMessage } from "../orchestration/worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../orchestration/models/ports.ts";
+import type { DoneReason, RunStatus } from "../orchestration/models/types.ts";
 import type { WorkflowRun } from "../orchestration/models/workflow-run.ts";
 
 // ── helpers ──────────────────────────────────────────────────
@@ -52,15 +53,15 @@ function makeRunningRun(): WorkflowRun & { resetRunning(): void } {
     runtime: {
       worker: { postMessage: vi.fn() },
     },
-    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;
     },
     // 多次触发 handleReturn 时把状态从 done 重置回 running
-    resetRunning(): void {
+    resetRunning(this: WorkflowRun): void {
       this.state.status = "running";
       this.state.reason = undefined;
     },

package/src/__tests__/robustness-medium-batch1.test.ts

@@ -20,7 +20,7 @@ function readSrc(relPath: string): string {
 // ── M4: node.live cleared before stale guard ─────────────────
 
 describe("M4: dispatchAgentCall .then() clears node.live before stale guard", () => {
-  const src = readSrc(join("src", "orchestration", "error-recovery.ts"));
+  const src = readSrc(join("src", "orchestration", "worker-message-pump.ts"));
 
   it("node.live = undefined appears before the stale guard return", () => {
     // 找到 .then 回调中的 stale guard 和 node.live 清理的相对顺序
@@ -41,7 +41,7 @@ describe("M4: dispatchAgentCall .then() clears node.live before stale guard", ()
 // ── M7: handleWorkerMessage shape validation ─────────────────
 
 describe("M7: handleWorkerMessage validates msg before dereferencing", () => {
-  const src = readSrc(join("src", "orchestration", "error-recovery.ts"));
+  const src = readSrc(join("src", "orchestration", "worker-message-pump.ts"));
 
   it("handleWorkerMessage has shape guard for msg before dereferencing opts", () => {
     // handleWorkerMessage 中 `raw as WorkerMsg` 后应有 typeof/形状校验

package/src/__tests__/robustness-medium-batch2.test.ts

@@ -3,6 +3,8 @@
 // M6: worktree cleanup not gated by patchOk (decoupled)
 // M9: store.save not fire-and-forget (has .catch)
 // M12: budget-done transition and onRunDone in separate try blocks
+//   （D5-② coda 收敛后语义不变、落点转移：budget-done 分支改调 finalizeRun 单写点，
+//   transition / unregister+onRunDone 的错误分离在 finalizeRun 函数体内断言）
 // [u1-move] M10（notifyDone 序列化守卫，读壳侧 interface/helpers.ts 源文本）随壳件
 // 留守 pi extension 包：src/__tests__/robustness-medium-batch2-interface.test.ts。
 
@@ -37,7 +39,7 @@ describe("M6: worktree cleanup not gated by patchOk", () => {
 // ── M9: store.save has .catch (not fire-and-forget) ──────────
 
 describe("M9: store.save not fire-and-forget in dispatchAgentCall", () => {
-  const src = readSrc(join("src", "orchestration", "error-recovery.ts"));
+  const src = readSrc(join("src", "orchestration", "worker-message-pump.ts"));
 
   it("no bare `void deps.store.save` without .catch", () => {
     // 查找所有 void deps.store.save(run) 的出现
@@ -48,18 +50,27 @@ describe("M9: store.save not fire-and-forget in dispatchAgentCall", () => {
   });
 });
 
-// ── M12: budget-done has separate try blocks ─────────────────
+// ── M12: budget-done coda 经 finalizeRun 单写点（错误分离语义不变） ──
 
 describe("M12: budget-done separates transition and onRunDone error handling", () => {
-  const src = readSrc(join("src", "orchestration", "error-recovery.ts"));
+  const src = readSrc(join("src", "orchestration", "worker-message-pump.ts"));
 
-  it("budget-done block has more than one catch (transition vs onRunDone separated)", () => {
+  it("budget-done branch delegates to finalizeRun (D5-② single coda write point)", () => {
     // 找到 budget isExceeded 块
     const budgetMatch = src.match(/budget\.isExceeded\(\)[\s\S]*?\}\s*\}\s*\)/);
     expect(budgetMatch).toBeTruthy();
     const budgetBlock = budgetMatch![0];
-    // 修复后应有多个 catch（至少 2 个：一个给 transition，一个给 onRunDone/emit）
-    const catchCount = (budgetBlock.match(/\bcatch\b/g) || []).length;
+    // coda 收敛后：budget-done 分支只调 finalizeRun（transition/save/unregister/onRunDone
+    // 四步不再内联复制）
+    expect(budgetBlock).toContain("finalizeRun(run, deps, \"budget_limited\"");
+  });
+
+  it("finalizeRun body separates transition and onRunDone error handling (>= 2 catch)", () => {
+    // finalizeRun 函数体：transition 的 try/catch 与 unregister/onRunDone 的 try/catch
+    // 分离（M12 语义锚定不变，随 coda 收敛转移至单写点内）
+    const fnMatch = src.match(/export async function finalizeRun\([\s\S]*?\n\}/);
+    expect(fnMatch, "finalizeRun 函数定义应存在").toBeTruthy();
+    const catchCount = (fnMatch![0].match(/\bcatch\b/g) || []).length;
     expect(catchCount).toBeGreaterThanOrEqual(2);
   });
 });

package/src/__tests__/robustness-medium-batch4.test.ts

@@ -6,7 +6,7 @@
 //
 // 通过 handleWorkerMessage 触发 dispatchAgentCall / dispatchWorkflowCall（内部函数不 export）。
 // Mock 构造模式参考 orchestration/__tests__/agent-call-catch-fallback.test.ts 和
-// orchestration/__tests__/error-recovery-workflow-call.test.ts。
+// orchestration/__tests__/worker-message-pump-workflow-call.test.ts。
 
 import { describe, expect, it, vi } from "vitest";
 
@@ -22,7 +22,7 @@ vi.mock("../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { handleWorkerMessage } from "../orchestration/error-recovery.ts";
+import { handleWorkerMessage } from "../orchestration/worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../orchestration/models/ports.ts";
 import { Trace } from "../orchestration/models/trace.ts";
 import type { AgentResult } from "../orchestration/models/types.ts";

package/src/__tests__/session-runner.test.ts

@@ -12,7 +12,7 @@
  * 因带 delta 字段被误判为 text_delta。正向判定（只放行 text_delta）根治。
  */
 import { describe, it, expect } from "vitest";
-import { mapAssistantMessageDelta } from "../execution/session-runner.js";
+import { mapAssistantMessageDelta } from "../execution/engine/engines/pi/session-runner.js";
 
 describe("mapAssistantMessageDelta: assistantMessageEvent → streaming 事件分流", () => {
   it("text_delta → forward 为 text_delta", () => {

package/src/core/__tests__/host-services.test.ts

@@ -62,13 +62,13 @@ describe("getHostServices（未配置 → NULL_HOST）", () => {
 
     host.log("warn", "comp-a", "w-message", { k: 1 });
     expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0][0]).toBe("[comp-a] w-message");
+    expect(warnSpy.mock.calls[0]![0]).toBe("[comp-a] w-message");
     expect(warnSpy.mock.calls[0][1]).toEqual({ k: 1 });
     expect(errorSpy).not.toHaveBeenCalled();
 
     host.log("error", "comp-a", "e-message");
     expect(errorSpy).toHaveBeenCalledTimes(1);
-    expect(errorSpy.mock.calls[0][0]).toBe("[comp-a] e-message");
+    expect(errorSpy.mock.calls[0]![0]).toBe("[comp-a] e-message");
   });
 
   it("data 缺省时省略第二参数（node console 会把显式 undefined 打成尾巴）", () => {

package/src/core/__tests__/logger.test.ts

@@ -24,7 +24,7 @@ describe("facade 顶层缓存惯例 + configureCore 前后透明切换（时序
     const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
     topLevelLogger.warn("before-configure", { stage: 1 });
     expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0][0]).toBe("[top-level-comp] before-configure");
+    expect(warnSpy.mock.calls[0]![0]).toBe("[top-level-comp] before-configure");
     expect(warnSpy.mock.calls[0][1]).toEqual({ stage: 1 });
 
     // 2) configureCore：宿主 log 接线（模拟宿主壳初始化时点，晚于本模块加载）。

package/src/core/error-message.ts

@@ -0,0 +1,9 @@
+/**
+ * 从任意 thrown 值提取可读的错误信息字符串：Error → `.message`，其它 → `String(e)`。
+ *
+ * 各包独立持有本 helper（core/renderer/runtime/subagent-core/electron/ext-guards 同实现），
+ * 不引跨包依赖——收敛 `e instanceof Error ? e.message : String(e)` 样板。
+ */
+export function toErrorMessage(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

package/src/core/host-services.ts

@@ -45,16 +45,32 @@ export interface HostServices {
  *  供无自有数据根的轻宿主显式采用；core 自身不静默兜底到该值。 */
 export const DEFAULT_DATA_ROOT: string = join(homedir(), ".subagent-core");
 
-// 模块级配置态：configureCore 覆盖式写入（重复调用以后者覆盖——测试切宿主依赖此语义）。
-let configuredHost: HostServices | undefined;
+// 配置态持有：globalThis[Symbol.for] slot（post-convergence D9 根治）。模块级 `let`
+// 在 dist 双形态（主 bundle × 子入口 bundle 各持模块副本）下会被分裂——configureCore
+// 只写主 bundle 副本，子入口侧恒 undefined。slot 对象形态（非直接存值）规避
+// 「undefined 值与无 key 不可区分」；范式与 execution/subagent-service.ts 进程单例
+// slot 同型。读写语义不变：configureCore 覆盖式写入
+// （重复调用以后者覆盖——测试切宿主依赖此语义）。
+const HOST_SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.host-services");
+
+type HostSlot = { current: HostServices | undefined };
+
+function getHostSlot(): HostSlot {
+  let slot = Reflect.get(globalThis, HOST_SLOT_KEY) as HostSlot | undefined;
+  if (!slot) {
+    slot = { current: undefined };
+    Reflect.set(globalThis, HOST_SLOT_KEY, slot);
+  }
+  return slot;
+}
 
 export function configureCore(host: HostServices): void {
-  configuredHost = host;
+  getHostSlot().current = host;
 }
 
 /** 测试隔离专用：清空配置态（生产禁用——生产宿主配置一次后生命周期与进程一致）。 */
 export function resetCoreForTests(): void {
-  configuredHost = undefined;
+  getHostSlot().current = undefined;
 }
 
 const NULL_HOST: HostServices = {
@@ -93,5 +109,5 @@ const NULL_HOST: HostServices = {
 };
 
 export function getHostServices(): HostServices {
-  return configuredHost ?? NULL_HOST;
+  return getHostSlot().current ?? NULL_HOST;
 }

package/src/core/notify-ports.ts

@@ -102,16 +102,29 @@ export interface NotifyDomainPorts {
   createDelivery?(port: DeliveryPort, options?: DeliveryConfig): DeliveryHandle;
 }
 
-// 模块级配置态（与 host-services 同款覆盖式语义——重复注入以后者覆盖）。
-let configuredPorts: NotifyDomainPorts | undefined;
+// 配置态持有：globalThis[Symbol.for] slot（与 host-services 同款覆盖式语义——重复
+// 注入以后者覆盖；post-convergence D9 根治，dist 双形态下免模块副本分裂，范式与
+// execution/subagent-service.ts 进程单例 slot 同型）。
+const NOTIFY_PORTS_SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.notify-ports");
+
+type NotifyPortsSlot = { current: NotifyDomainPorts | undefined };
+
+function getNotifyPortsSlot(): NotifyPortsSlot {
+  let slot = Reflect.get(globalThis, NOTIFY_PORTS_SLOT_KEY) as NotifyPortsSlot | undefined;
+  if (!slot) {
+    slot = { current: undefined };
+    Reflect.set(globalThis, NOTIFY_PORTS_SLOT_KEY, slot);
+  }
+  return slot;
+}
 
 export function configureNotifyDomain(ports: NotifyDomainPorts): void {
-  configuredPorts = ports;
+  getNotifyPortsSlot().current = ports;
 }
 
 /** 测试隔离专用：清空注入态（生产禁用——注入点在宿主壳初始化，生命周期与进程一致）。 */
 export function resetNotifyDomainForTests(): void {
-  configuredPorts = undefined;
+  getNotifyPortsSlot().current = undefined;
 }
 
 const DEFAULT_NOTIFY_PORTS: NotifyDomainPorts = {
@@ -122,5 +135,5 @@ const DEFAULT_NOTIFY_PORTS: NotifyDomainPorts = {
 };
 
 export function getNotifyDomainPorts(): NotifyDomainPorts {
-  return configuredPorts ?? DEFAULT_NOTIFY_PORTS;
+  return getNotifyPortsSlot().current ?? DEFAULT_NOTIFY_PORTS;
 }

package/src/execution/__tests__/agent-profile.test.ts

@@ -7,7 +7,7 @@
 // （meta=null 单行兜底）与 parseResourceMeta 严格层新字段投影断言
 // （AgentMeta 扩 maxTurns/disallowedTools/skills 的 typecheckMeta 行为）。
 
-import { describe, expect, fail, it } from "vitest";
+import { describe, expect, it } from "vitest";
 
 import { parseResourceMeta } from "../../shared/meta-parser.ts";
 import { parseAgentProfile } from "../agent-registry.ts";
@@ -172,7 +172,7 @@ body`,
       "agent",
     );
     expect(meta).not.toBeNull();
-    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    if (meta?.kind !== "agent") return expect.fail("kind 应为 agent");
     expect(meta.maxTurns).toBe(2);
     expect(meta.disallowedTools).toEqual(["write"]);
     expect(meta.skills).toEqual(["code-review"]);
@@ -200,7 +200,7 @@ body`,
       "agent",
     );
     expect(meta).not.toBeNull();
-    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    if (meta?.kind !== "agent") return expect.fail("kind 应为 agent");
     expect("disallowedTools" in meta).toBe(true);
     expect(meta.disallowedTools).toEqual([]);
     expect("skills" in meta).toBe(true);
@@ -224,7 +224,7 @@ body`,
       "agent",
     );
     expect(meta).not.toBeNull();
-    if (meta?.kind !== "agent") return fail("kind 应为 agent");
+    if (meta?.kind !== "agent") return expect.fail("kind 应为 agent");
     expect("maxTurns" in meta).toBe(false);
     expect("disallowedTools" in meta).toBe(false);
     expect("skills" in meta).toBe(false);