@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.2.0",
+  "version": "0.5.1",
   "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,17 +72,19 @@
       "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/",
-    "dist/"
+    "agents/",
+    "dist/",
+    "dist.bundle/"
   ],
   "dependencies": {
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.7.0"
+    "@xyz-agent/extension-protocol": "0.8.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -93,6 +95,7 @@
   },
   "scripts": {
     "build": "tsup",
+    "build:bundle": "tsup",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }

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

@@ -12,11 +12,14 @@
 //         （旧实现不排除 error 分支，agent 失败被误诊为引擎透传未上线并烧掉 once 名额）
 //   - A11：model 缺省回退 "(default)"（请求时参数语义）
 //   - A12：promptMode=null（aggregator/fixer）必须保持 null，不被 || 误转 "full"
-import { readFileSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { copyFileSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { promisify } from "node:util";
 import vm from "node:vm";
 
-import { describe, expect, it } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 const WORKFLOW_SOURCE = readFileSync(
   join(__dirname, "..", "..", "workflows", "review-fix-loop.js"),
@@ -283,6 +286,93 @@ 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();
+  });
+});
+
+// ── RX2-F2：fixAgent=fallow-scan 显式拒收（脚本顶层参数校验，非函数段） ──
+// 拒收逻辑位于脚本顶层（FIX_AGENT_RAW 解析后、resolveAgentDefs 前），函数段抽取法
+// 覆盖不到；改用 review-fix-loop-scriptpath-failfast.test.ts 同款「AsyncFunction 包装
+// + node -e 真实子进程」探针跑整脚本顶层副本。拒收点在 RUN_ROOT 落盘 / lockReviewBase
+// 之前，探针无文件系统副作用、恒非零退出。
+describe("review-fix-loop.js fixAgent=fallow-scan 显式拒收（RX2-F2）", () => {
+  const run = promisify(execFile);
+
+  /** execFile reject 侧的最小形状（Node ExecException 子集）。 */
+  interface ExecFailure extends Error {
+    code?: number | string;
+    stderr?: string;
+  }
+
+  function isExecFailure(e: unknown): e is ExecFailure {
+    return e instanceof Error;
+  }
+
+  let sandboxDir = "";
+
+  beforeEach(() => {
+    sandboxDir = mkdtempSync(join(tmpdir(), "rfl-fixagent-guard-"));
+    const workflowsDir = join(__dirname, "..", "..", "workflows");
+    // 副本以 .cjs 落 sandbox（require 解析形态对齐 worker 宿主）；utils 锚定加载经
+    // workerData.scriptPath（副本同目录），白名单校验前即需要它
+    copyFileSync(join(workflowsDir, "review-fix-loop.js"), join(sandboxDir, "review-fix-loop.cjs"));
+    copyFileSync(join(workflowsDir, "review-fix-loop-utils.cjs"), join(sandboxDir, "review-fix-loop-utils.cjs"));
+  });
+
+  afterEach(() => {
+    rmSync(sandboxDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  /** -e 探针体：AsyncFunction 复刻 worker 模板宿主形态（workerData/$ARGS/log 注入）。 */
+  function probeCode(argsJson: string): string {
+    const copyPath = join(sandboxDir, "review-fix-loop.cjs");
+    return [
+      "const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;",
+      "const src = require('fs').readFileSync(" + JSON.stringify(copyPath) + ", 'utf8');",
+      "const runner = new AsyncFunction('workerData', '$ARGS', 'require', 'log', src + '\\n');",
+      "const workerData = { scriptPath: " + JSON.stringify(join(sandboxDir, "review-fix-loop.cjs")) + " };",
+      "const $ARGS = " + argsJson + ";",
+      // $MODEL 是 worker 模板全局（主模型注入）——对照用例会推进到 fixAgent 解析之后
+      // 的 MODEL = $MODEL 行（:204），缺席会 ReferenceError 而非到达批次校验
+      "const $MODEL = 'probe-model';",
+      "runner(workerData, $ARGS, require, function () {}).catch(function (e) {",
+      "  require('fs').writeSync(2, String((e && e.message) || e) + '\\n');",
+      "  process.exit(1);",
+      "});",
+    ].join("\n");
+  }
+
+  async function runProbeExpectFailure(argsJson: string): Promise<string> {
+    const outcome = await run(process.execPath, ["-e", probeCode(argsJson)], {
+      cwd: sandboxDir,
+      timeout: 30_000,
+    }).then(
+      (): ExecFailure | null => null,
+      (e: unknown): ExecFailure | null => (isExecFailure(e) ? e : null),
+    );
+    if (outcome === null) {
+      throw new Error("expected non-zero exit, but node exited 0 with args: " + argsJson);
+    }
+    return String(outcome.stderr ?? "");
+  }
+
+  it("fixAgent=fallow-scan → 非零退出 + 保留字错误 + fallowScan=true 恢复指引", async () => {
+    const stderr = await runProbeExpectFailure(
+      '{ targetType: "file", target: "probe", fixAgent: "fallow-scan" }',
+    );
+    expect(stderr).toContain("内部保留字");
+    expect(stderr).toContain("fallowScan=true");
+    // 旧实现静默映射 FALLOW_DEF（fix 派发退化为通用 subagent）——不会到达此处报错
+  });
+
+  it("对照：合法形态 fixAgent（.md 路径）不触发保留字拒收（后续批次校验照常 fail）", async () => {
+    const stderr = await runProbeExpectFailure(
+      '{ targetType: "file", target: "probe", fixAgent: "/tmp/rx2-f2-fake-agent.md" }',
+    );
+    // 推进到批次解析才失败（缺批次参数）——证明拒收只对字面值 fallow-scan 触发
+    expect(stderr).toContain("缺少批次参数");
+    expect(stderr).not.toContain("内部保留字");
   });
 });

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", () => {
@@ -1140,6 +1140,27 @@ describe("findIssueKey — 归一化键空间查找", () => {
     expect(findIssueKey(issues, "MF-1")).toBe("MF-1 (fixed)");
     expect(findIssueKey(issues, "mf-1 (by design)")).toBe("MF-1 (fixed)");
   });
+
+  it("原型链键（__proto__/toString/constructor）→ 不命中（Object.hasOwn 首查，zsw 侧同款修复上收）", () => {
+    // 旧 truthy 查表（issues[issueId]）会让 Object.prototype 上的成员误命中：
+    // issues["__proto__"] 取到原型对象（truthy）→ 返回 "__proto__" 当台账键 →
+    // 调用方读 issues["__proto__"].severity 得 undefined/函数污染 fix 对账。
+    // ID 来自 LLM 产出，原型链键是真实攻击面而非理论边界。
+    const issues = { "MF-1": { severity: "major" } };
+    expect(findIssueKey(issues, "__proto__")).toBeUndefined();
+    expect(findIssueKey(issues, "toString")).toBeUndefined();
+    expect(findIssueKey(issues, "constructor")).toBeUndefined();
+    expect(findIssueKey(issues, "hasOwnProperty")).toBeUndefined();
+  });
+
+  it("own 键且值 falsy（null）→ 仍命中该键（hasOwn 与 truthy 查表的等价性由归一化回退段兜底）", () => {
+    // 旧 truthy 查表在值 falsy 时不直接命中，但归一化回退段（Object.keys 只枚举
+    // own 键）会命中同一键——两形态最终返回一致，hasOwn 只是路径更短、且对原型链
+    // 键正确拒绝。断言钉住该等价性，防未来有人「顺手」改回 truthy 形态。
+    const issues = { "MF-1": null };
+    expect(findIssueKey(issues, "MF-1")).toBe("MF-1");
+    expect(findIssueKey(issues, "mf-1")).toBe("MF-1");
+  });
 });
 
 describe("T-2 端到端：normIssueId/findIssueKey 在 validateFixResult 的真实消费", () => {
@@ -1173,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 误升级为违规。
@@ -1230,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 });
     }
   });
 
@@ -1248,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 });
     }
   });
 
@@ -1273,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 });
     }
   });
 
@@ -1292,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 });
     }
   });
 });
@@ -1770,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/__tests__/smoke.test.ts

@@ -1,9 +1,16 @@
+import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
 import { CORE_PACKAGE_VERSION } from "../index";
 
+// 对 package.json version 断言（单一事实源）：本测试是 src/index.ts 字面量与
+// package.json 双源同步的执法者——任何一侧 bump 后未同步另一侧立即红，
+// 替代旧硬编码 "0.1.0" 字面量（版本 bump 时必忘改的第三处双源）。
 describe("subagent-core scaffold smoke", () => {
-  it("exposes CORE_PACKAGE_VERSION", () => {
-    expect(CORE_PACKAGE_VERSION).toBe("0.1.0");
+  it("exposes CORE_PACKAGE_VERSION synced with package.json", () => {
+    const pkgVersion = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+    ).version;
+    expect(CORE_PACKAGE_VERSION).toBe(pkgVersion);
   });
 });

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 打成尾巴）", () => {