@zhushanwen/subagent-core 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.8.0",
+  "version": "0.9.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",
@@ -74,7 +74,7 @@
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
     "@xyz-agent/extension-protocol": "0.9.0",
-    "@zhushanwen/subagent-engine-sdk": "0.2.1"
+    "@zhushanwen/subagent-engine-sdk": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -82,8 +82,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "vitest": "^4.1.8",
-    "@zhushanwen/pi-subagent-cli": "0.1.2",
-    "@zhushanwen/zcode-subagent-cli": "0.2.0"
+    "@zhushanwen/pi-subagent-cli": "0.2.0",
+    "@zhushanwen/zcode-subagent-cli": "0.2.1"
   },
   "scripts": {
     "build": "tsup",

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

@@ -114,7 +114,10 @@ describe("ManifestStore", () => {
     });
   });
 
-  describe("recoverTmpFiles", () => {
+  // [U4c / G3] tmp 恢复退役（D6）：manifest 已是可丢可重建缓存（权威 = `.state`，
+  // 重建 = RecordStore.rebuildIndexes），promote 半写 tmp 的恢复语义失效——[H4/U5
+  // 更名收口] recoverTmpFiles → sweepTmpFiles（名实对齐静默删除），返回删除计数。
+  describe("sweepTmpFiles", () => {
     it("should delete tmp when manifest exists", async () => {
       const id = "test-recovery-1";
       const manifestPath = path.join(tmpDir, `${id}.json`);
@@ -123,20 +126,20 @@ describe("ManifestStore", () => {
       fs.writeFileSync(manifestPath, '{"id":"test-recovery-1"}');
       fs.writeFileSync(tmpPath, '{"id":"test-recovery-1"}');
 
-      const result = await store.recoverTmpFiles();
+      const result = await store.sweepTmpFiles();
 
-      expect(result.deleted).toBe(1);
+      expect(result).toBe(1);
       expect(fs.existsSync(tmpPath)).toBe(false);
       expect(fs.existsSync(manifestPath)).toBe(true);
     });
 
-    it("should rename valid tmp when manifest missing", async () => {
+    it("should delete valid tmp when manifest missing (promote retired)", async () => {
       const id = "test-recovery-2";
       const tmpPath = path.join(tmpDir, `${id}.json.tmp.12345`);
       const manifestPath = path.join(tmpDir, `${id}.json`);
 
-      // F2 后 recoverTmpFiles 用 isValidManifest 严格校验——tmp 必须含全部必填字段
-      // （id/rootSessionId/agentName/createdAt/status）才会 promote，否则走删除分支 3b。
+      // 旧 promote 分支形态（合法完整 manifest 的 tmp + 正式文件缺失）也删——
+      // 半写 tmp 不再被复活成「看似权威」的索引，缺员由 rebuildIndexes 重建。
       fs.writeFileSync(tmpPath, JSON.stringify({
         id,
         rootSessionId: "session-123",
@@ -145,10 +148,10 @@ describe("ManifestStore", () => {
         createdAt: Date.now(),
       }));
 
-      const result = await store.recoverTmpFiles();
+      const result = await store.sweepTmpFiles();
 
-      expect(result.recovered).toBe(1);
-      expect(fs.existsSync(manifestPath)).toBe(true);
+      expect(result).toBe(1);
+      expect(fs.existsSync(manifestPath)).toBe(false);
       expect(fs.existsSync(tmpPath)).toBe(false);
     });
 
@@ -158,20 +161,18 @@ describe("ManifestStore", () => {
 
       fs.writeFileSync(tmpPath, "invalid json {{{");
 
-      const result = await store.recoverTmpFiles();
+      const result = await store.sweepTmpFiles();
 
-      expect(result.deleted).toBe(1);
+      expect(result).toBe(1);
       expect(fs.existsSync(tmpPath)).toBe(false);
     });
 
-    // F2：合法 JSON 但缺必填字段（非合法 manifest）应走删除（分支 3b），不能 promote
     it("should delete tmp when JSON valid but not a valid manifest (missing required fields)", async () => {
       const id = "test-recovery-4";
       const tmpPath = path.join(tmpDir, `${id}.json.tmp.12345`);
       fs.writeFileSync(tmpPath, JSON.stringify({ foo: "bar" })); // 合法 JSON，非 manifest
-      const result = await store.recoverTmpFiles();
-      expect(result.deleted).toBe(1);
-      expect(result.recovered).toBe(0);
+      const result = await store.sweepTmpFiles();
+      expect(result).toBe(1);
       expect(fs.existsSync(tmpPath)).toBe(false);
     });
   });

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

@@ -1,6 +1,9 @@
 // Medium batch 1 robustness fixes verification
 //
-// M4: dispatchAgentCall .then() clears node.live BEFORE stale guard (not after)
+// M4: [H2 W3 改写] dispatchAgentCall 的 node.live 清理已随 trace.live 字段退役
+//     （设计 subagent-workflow-record-unification.md D2——旁路 progress record 族
+//     整体删除，节点无运行期附属对象）。原「live 清理先于 stale guard」的顺序
+//     断言改为退役回归：pump 无 node.live 写点。
 // M7: handleWorkerMessage validates msg shape before dereferencing msg.opts
 // M8: session-reconstructor guards Array.isArray(msg.content) before for...of
 
@@ -17,24 +20,17 @@ function readSrc(relPath: string): string {
   return readFileSync(join(PKG_ROOT, relPath), "utf-8");
 }
 
-// ── M4: node.live cleared before stale guard ─────────────────
+// ── M4: node.live 写点已退役（[H2 W3] 回归锁定） ─────────────
 
-describe("M4: dispatchAgentCall .then() clears node.live before stale guard", () => {
+describe("M4: [H2 W3] dispatchAgentCall 不再写 node.live", () => {
   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 清理的相对顺序
+  it("整个 pump 源码无 .live 写点（旁路 record 族退役），stale guard 仍在", () => {
+    expect(src).not.toMatch(/\.live\s*=/);
+    // .then 的 stale guard 仍在（原顺序断言的对象消失，守卫本身保留）
     const thenMatch = src.match(/\.then\(\(\)\s*=>\s*\{[\s\S]*?\}\)/);
     expect(thenMatch).toBeTruthy();
-    const thenBlock = thenMatch![0];
-
-    const liveIdx = thenBlock.indexOf("node.live = undefined");
-    const guardIdx = thenBlock.indexOf('run.state.status !== "running"');
-
-    expect(liveIdx).toBeGreaterThan(-1);
-    expect(guardIdx).toBeGreaterThan(-1);
-    // node.live 清理必须在 stale guard 之前（代码行号更小）
-    expect(liveIdx).toBeLessThan(guardIdx);
+    expect(thenMatch![0]).toContain('run.state.status !== "running"');
   });
 });
 

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

@@ -24,11 +24,16 @@ function readSrc(relPath: string): string {
 // ── M6: worktree cleanup decoupled from patchOk ──────────────
 
 describe("M6: worktree cleanup not gated by patchOk", () => {
-  const src = readSrc(join("src", "execution", "subagent-service.ts"));
+  // [H3/R3] worktree cleanup 调用点（disposeAllRecords / cancelBackground）已随终态
+  // 写面迁 execution/service/record-lifecycle.ts（strangler 抽取，壳只留单行转发）——
+  // 源文本守卫随被守卫本体改读聚合文件，断言强度不变（patchOk 解耦锁）。
+  const src = readSrc(join("src", "execution", "service", "record-lifecycle.ts"));
 
   it("worktree cleanup condition does not reference patchOk", () => {
     // 找到 worktree cleanup 调用前的条件判断
-    const cleanupMatch = src.match(/if\s*\([^)]*worktreeHandle[^)]*\)\s*\{[\s\S]*?worktreeManager\.cleanup/);
+    // [H3/R3] cleanup 通道字面随依赖注入改造为 deps.getWorktreeManager().cleanup
+    //（this.worktreeManager → this.deps.getWorktreeManager()，方法体其余逐字节保留）。
+    const cleanupMatch = src.match(/if\s*\([^)]*worktreeHandle[^)]*\)\s*\{[\s\S]*?getWorktreeManager\(\)\.cleanup/);
     expect(cleanupMatch).toBeTruthy();
     const condition = cleanupMatch![0];
     // 条件中不应包含 patchOk（解耦后 worktree cleanup 只依赖 worktreeHandle 存在）

package/src/execution/__tests__/alive-store.test.ts

@@ -4,9 +4,33 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { afterEach,describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// [U1 A4] removeAliveMarker 失败留痕断言需要 warn 可观察。
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+// fs partial mock：unlinkSync 可注错（release 失败留痕用例），其余转发真实实现。
+// ESM namespace 不可直接赋值/spyOn，注错必须走模块 mock（state-marker.test.ts 同款）。
+type UnlinkSyncFn = typeof import("node:fs").unlinkSync;
+const { unlinkSyncMock, actualUnlinkRef } = vi.hoisted(() => ({
+  unlinkSyncMock: vi.fn(),
+  actualUnlinkRef: { current: undefined as UnlinkSyncFn | undefined },
+}));
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  actualUnlinkRef.current = actual.unlinkSync;
+  return {
+    ...actual,
+    unlinkSync: unlinkSyncMock,
+    default: { ...actual, unlinkSync: unlinkSyncMock },
+  };
+});
 
 import {
+  findForeignLiveInstance,
   isProcessAlive,
   readAliveMarker,
   removeAliveMarker,
@@ -18,6 +42,13 @@ function makeTmpDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), "alive-store-test-"));
 }
 
+/**
+ * [U1 A4] 「异进程且存活」的确定性模拟 pid：1 号进程（launchd/init）必然存在且非
+ * 本测试进程——kill(1, 0) 对普通用户返回 EPERM，isProcessAlive 按「存在但无权限」
+ * 保守判活。self-pid 排除后不能再以本进程 pid 模拟异进程实例。
+ */
+const FOREIGN_LIVE_PID = 1;
+
 describe("alive-store", () => {
   let tmpDir: string;
 
@@ -25,6 +56,11 @@ describe("alive-store", () => {
     if (tmpDir) {
       fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
     }
+    // unlinkSync mock 基线复位 = 真实实现（个别用例注错覆盖后恢复）。
+    if (actualUnlinkRef.current !== undefined) {
+      unlinkSyncMock.mockReset().mockImplementation(actualUnlinkRef.current);
+    }
+    loggerMock.warn.mockClear();
   });
 
   // ── writeAliveMarker + readAliveMarker 往返 ──
@@ -144,4 +180,84 @@ describe("alive-store", () => {
       process.kill = originalKill;
     }
   });
+
+  // ── [U1 A4] findForeignLiveInstance：self-pid 排除 + pid 单判据三态 ──
+
+  describe("findForeignLiveInstance（D3c/D3b v7：self-pid 排除 + pid 单判据）", () => {
+    it("本进程 pid（marker.pid === process.pid）→ 放行（视同无 foreign，D3c 排除）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      writeAliveMarker(sessionFile, { pid: process.pid, id: "bg-1", startedAt: Date.now() });
+
+      expect(findForeignLiveInstance(sessionFile)).toBeUndefined();
+    });
+
+    it("异进程 pid 活 → 拦截（返回 marker，在持声明）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const marker: AliveMarker = { pid: FOREIGN_LIVE_PID, id: "bg-1", startedAt: Date.now() };
+      writeAliveMarker(sessionFile, marker);
+
+      expect(findForeignLiveInstance(sessionFile)).toEqual(marker);
+    });
+
+    it("pid 死 → 放行（确死，允许透明重生）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      // 大 pid 用户空间必然不存在（isProcessAlive ESRCH 判死，与既有用例同款手法）
+      writeAliveMarker(sessionFile, { pid: 9999999, id: "bg-1", startedAt: Date.now() });
+
+      expect(findForeignLiveInstance(sessionFile)).toBeUndefined();
+    });
+
+    it("软超时不再参与判定：异进程 pid 活 + startedAt 超 1h 仍拦截（防御不随 idle 时长衰减）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      const stale: AliveMarker = {
+        pid: FOREIGN_LIVE_PID,
+        id: "bg-1",
+        startedAt: Date.now() - 2 * 3_600_000, // 2h 前——旧三判据形态下会超软超时放行
+      };
+      writeAliveMarker(sessionFile, stale);
+
+      expect(findForeignLiveInstance(sessionFile)).toEqual(stale);
+    });
+
+    it("marker 缺失/损坏 → 放行（无声明）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      expect(findForeignLiveInstance(sessionFile)).toBeUndefined();
+      fs.writeFileSync(`${sessionFile}.alive`, "not-json", "utf-8");
+      expect(findForeignLiveInstance(sessionFile)).toBeUndefined();
+    });
+  });
+
+  // ── [U1] removeAliveMarker 失败留痕（D3a：release 失败 bestEffort 留痕）──
+
+  describe("removeAliveMarker 失败留痕", () => {
+    it("删除失败（非 ENOENT）→ warn 留痕不抛出", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      writeAliveMarker(sessionFile, { pid: 1, id: "x", startedAt: 0 });
+      unlinkSyncMock.mockImplementation(() => {
+        const err = new Error("EACCES") as NodeJS.ErrnoException;
+        err.code = "EACCES";
+        throw err;
+      });
+      expect(() => removeAliveMarker(sessionFile)).not.toThrow();
+      expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+    });
+
+    it("ENOENT（marker 不存在）→ 静默（幂等终态，无 warn）", () => {
+      tmpDir = makeTmpDir();
+      const sessionFile = path.join(tmpDir, "session.jsonl");
+      unlinkSyncMock.mockImplementation(() => {
+        const err = new Error("ENOENT") as NodeJS.ErrnoException;
+        err.code = "ENOENT";
+        throw err;
+      });
+      expect(() => removeAliveMarker(sessionFile)).not.toThrow();
+      expect(loggerMock.warn).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/execution/__tests__/batch-finalized.test.ts

@@ -0,0 +1,206 @@
+// src/execution/__tests__/batch-finalized.test.ts
+//
+// [U3 / D1] 批写归口后的 barrier 语义测试（设计 docs/design/subagent-record-
+// persistence-consolidation.md §3.1 markBatchFinalized 行 + §3.3 D4②/D5）：
+//
+//   1. E1 调用面（SyncCollectDomain 直构 + 真 RecordStore）：notifyBatch（写账入口）
+//      被调用的时刻，全部成员 manifest 必已在磁盘——「manifest 落盘完成先于批通知
+//      写账」的构造性保证（违反即红；迁移前 fire-and-forget 形态该时点只大概率成立）；
+//   2. 原语（manifestDir 接线，构造点同步分支）：markBatchFinalized await 返回即
+//      manifest 文件可见（无 fire-and-forget）+ 落标 entry 携带 collectMode/batchFinalized
+//      显式覆写 + 落标写出的时点 manifest 已在（原语内部序）；
+//   3. 原语（降级分支，manifestDir 缺省——双轨期形态）：allSettled 屏障后落标，
+//      barrier 语义与同步分支等价。
+//
+// 与 record-store-intent-api.test.ts（U1，store 单体语义）的分工：本文件断言
+// **调用面时序**——批通知写账（notifyBatch）/ 落标 entry 写出的时刻 manifest 必已
+// 就位，即 D1 验收条款的字面断言面。
+//
+// 通路保真：RecordStore / SyncCollectDomain / ManifestStore 走真实实现（tmpdir
+// 自建自删，红线），仅 pi.appendEntry / notifyHost 为 mock（写账与落标的观察点）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+
+import { ManifestStore } from "../manifest-store.ts";
+import { getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
+import { RecordStore } from "../record-store.ts";
+import { SyncCollectDomain } from "../service/sync-collect-domain.ts";
+import type { SubagentRecord } from "../types.ts";
+
+const ROOT_SESSION = "root-batch-finalized";
+
+/** 种子成员 record（对齐 sync-collect-recovery.test.ts memberRecord 形态——
+ *  rebuildEntryRecord 解析门槛字段齐备）。 */
+function memberRecord(overrides: Partial<SubagentRecord> & { id: string }): SubagentRecord {
+  return {
+    agent: "/agents/worker.md",
+    task: "batch task",
+    slug: "batch",
+    status: "running",
+    mode: "background",
+    startedAt: 1000,
+    rootSessionId: ROOT_SESSION,
+    parentRecordId: undefined,
+    depth: 0,
+    endedAt: undefined,
+    turns: 0,
+    totalTokens: 0,
+    model: "prov/m1",
+    thinkingLevel: undefined,
+    eventLog: [],
+    displayItems: [],
+    result: undefined,
+    error: undefined,
+    sessionFile: undefined,
+    chatMode: false,
+    collectMode: "sync",
+    ...overrides,
+  };
+}
+
+describe("batch-finalized 归口（U3/D1）——barrier：manifest 落盘完成先于批通知写账", () => {
+  let tmpDir: string;
+  let sessionsDir: string;
+  let manifestDir: string;
+  let mainFile: string;
+  let appendEntryMock: Mock<(customType: string, data: unknown) => void>;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "core-batch-finalized-"));
+    sessionsDir = getSubagentSessionDir(tmpDir, tmpDir);
+    manifestDir = getSubagentRecordsDir(tmpDir, tmpDir);
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    fs.mkdirSync(manifestDir, { recursive: true });
+    mainFile = path.join(tmpDir, "main-session.jsonl");
+    appendEntryMock = vi.fn();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  /** 写文件 pi（种子用）：appendEntry 真写主 session JSONL（pi 落盘形态）。 */
+  function makeWritingPi() {
+    return {
+      appendEntry: (customType: string, data: unknown) => {
+        fs.appendFileSync(
+          mainFile,
+          `${JSON.stringify({
+            type: "custom",
+            id: `seed-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+            parentId: null,
+            timestamp: new Date().toISOString(),
+            customType,
+            data,
+          })}\n`,
+          "utf-8",
+        );
+      },
+    };
+  }
+
+  it("E1 调用面：notifyBatch 写账时点全成员 manifest 已落盘（构造性 barrier，违反即红）", async () => {
+    // 种子：两成员（register running+sync → 终态 closed）经真实 reportSubagentRecord
+    // 序列化落主文件——崩溃残留（全员终态 + 无标记）形态。
+    const seedStore = new RecordStore(sessionsDir, undefined, makeWritingPi());
+    for (const id of ["sa-bf-a", "sa-bf-b"]) {
+      seedStore.reportSubagentRecord(memberRecord({ id }));
+      seedStore.reportSubagentRecord(
+        memberRecord({ id, status: "closed", closedReason: "gc", endedAt: 2000, result: `done-${id}` }),
+      );
+    }
+
+    // 被测面：真 RecordStore（manifestDir 接线——构造点形态）+ 直构 SyncCollectDomain。
+    const store = new RecordStore(sessionsDir, undefined, { appendEntry: appendEntryMock }, manifestDir);
+    const notifyBatch = vi.fn(() => true);
+    const domain = new SyncCollectDomain({
+      getStore: () => store,
+      getNotifyHost: () => ({
+        toNotifyRecord: () => undefined,
+        notify: () => {},
+        notifyBatch,
+      }),
+      getPi: () => null,
+      getSessionRootId: () => ROOT_SESSION,
+      getMainSessionFile: () => mainFile,
+      getCollectSyncSection: () => undefined,
+    });
+
+    // 写账时点钩子（严格时序门）：notifyBatch 被调用的时刻，两成员 manifest 必已
+    // 在磁盘——这是 D1 barrier 的字面断言面（「通知可达 ⇒ 索引就位」）。
+    const manifestsAtLedgerWrite: boolean[] = [];
+    notifyBatch.mockImplementation(() => {
+      manifestsAtLedgerWrite.push(
+        fs.existsSync(path.join(manifestDir, "sa-bf-a.json")),
+        fs.existsSync(path.join(manifestDir, "sa-bf-b.json")),
+      );
+      return true;
+    });
+
+    await domain.recoverSyncCollectBatch();
+
+    expect(notifyBatch).toHaveBeenCalledTimes(1);
+    expect(manifestsAtLedgerWrite).toEqual([true, true]);
+    // 落标随 markBatchFinalized 前置完成（U3 归口）：两成员各一笔带标记 entry。
+    const marks = appendEntryMock.mock.calls
+      .filter((c) => c[0] === "subagent-record")
+      .map((c) => c[1] as Record<string, unknown>)
+      .filter((d) => d["batchFinalized"] === true);
+    expect(marks.map((m) => m["id"]).sort()).toEqual(["sa-bf-a", "sa-bf-b"]);
+    for (const mark of marks) expect(mark["collectMode"]).toBe("sync");
+  });
+
+  it("原语（manifestDir 接线 / 同步分支）：await 返回即 manifest 可见；落标 entry 写出时点 manifest 已在", async () => {
+    const store = new RecordStore(sessionsDir, undefined, { appendEntry: appendEntryMock }, manifestDir);
+    const members = [memberRecord({ id: "sa-sync-1" }), memberRecord({ id: "sa-sync-2" })];
+
+    // 落标时点钩子：appendEntry（落标写面）触发的时刻，该成员 manifest 必已存在
+    // （原语内部序 = manifest 落盘完成先于批通知写账/落标 entry）。
+    appendEntryMock.mockImplementation((_type: string, data: unknown) => {
+      const d = data as { id?: string };
+      if (typeof d?.id === "string") {
+        expect(fs.existsSync(path.join(manifestDir, `${d.id}.json`)), `manifest of ${d.id} at entry time`).toBe(true);
+      }
+    });
+
+    await store.markBatchFinalized(members);
+
+    // 写后即刻可见（无 fire-and-forget——D8 writeSync 语义）。
+    expect(fs.existsSync(path.join(manifestDir, "sa-sync-1.json"))).toBe(true);
+    expect(fs.existsSync(path.join(manifestDir, "sa-sync-2.json"))).toBe(true);
+    // 落标 entry：collectMode/batchFinalized 显式覆写（防非 entry 源重建丢标记）。
+    expect(appendEntryMock).toHaveBeenCalledTimes(2);
+    expect(appendEntryMock).toHaveBeenCalledWith(
+      "subagent-record",
+      expect.objectContaining({ id: "sa-sync-1", collectMode: "sync", batchFinalized: true }),
+    );
+  });
+
+  it("原语（降级分支 / manifestDir 缺省——双轨期形态）：allSettled 屏障后落标，barrier 语义等价", async () => {
+    // 缺省 manifestDir：store 降级走 manifestStore.writeManifest 异步屏障（双轨期
+    // 现行语义，D7）——await 完成后 manifest 照常落盘 + 落标在其后（顺序不变）。
+    const store = new RecordStore(
+      sessionsDir,
+      new ManifestStore(manifestDir),
+      { appendEntry: appendEntryMock },
+    );
+    appendEntryMock.mockImplementation((_type: string, data: unknown) => {
+      const d = data as { id?: string };
+      if (typeof d?.id === "string") {
+        expect(fs.existsSync(path.join(manifestDir, `${d.id}.json`)), `manifest of ${d.id} at entry time`).toBe(true);
+      }
+    });
+
+    await store.markBatchFinalized([memberRecord({ id: "sa-degraded" })]);
+
+    expect(fs.existsSync(path.join(manifestDir, "sa-degraded.json"))).toBe(true);
+    expect(appendEntryMock).toHaveBeenCalledWith(
+      "subagent-record",
+      expect.objectContaining({ id: "sa-degraded", collectMode: "sync", batchFinalized: true }),
+    );
+  });
+});

package/src/execution/__tests__/chat-engine-routing.test.ts

@@ -334,6 +334,21 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
   // 2. pi 缺省守护（D5 字节级）
   // ============================================================
 
+  it("[F6] pi 路由 kickOffChatRound：runCtx 带 sessionRootId（initSession 注入的根 id，relay 归属键权威源）", async () => {
+    // [S5 同根] initSession 读 env PI_SUBAGENT_ROOT_SESSION_ID 优先于 init.sessionId——
+    // 在 pi subagent 进程内跑测试（该 env 已注入）必红。显式 stub 为 undefined（空串
+    // 会被条件 spread 过滤为缺键，同样破坏断言），不依赖外层环境。
+    vi.stubEnv("PI_SUBAGENT_ROOT_SESSION_ID", undefined);
+    const { service, piEngine } = setup(agentDir);
+    const handle = await service.execute(baseOpts(agentDir));
+    await vi.waitFor(() => expect(piEngine.runs.length).toBe(1));
+    // initSession({sessionId: "test-session"}) 无 env → sessionRootId = "test-session"；
+    // kickOffChatRound 是 pi 引擎 background 派发主路径（isPiRoute 恒路由至此，含
+    // workflow 域一次性 run），漏注 = GUI pi 派发 relay 拒绝 exit 13（Gate B F6 形态）。
+    expect(piEngine.runs[0]!.ctx.sessionRootId).toBe("test-session");
+    vi.unstubAllEnvs();
+  });
+
   it("[D5] 全缺省 pi record：engine===undefined 且 entry JSON 不含 engine 键", async () => {
     const { service, piEngine } = setup(agentDir);
     const handle = await service.execute(baseOpts(agentDir));
@@ -367,7 +382,7 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
       .execute(baseOpts(agentDir, { engine: "zcode", conversation: true }))
       .catch((e: unknown) => e);
     expect(err).toBeInstanceOf(Error);
-    expect((err as Error).message).toContain("不支持 conversation");
+    expect((err as Error).message).toContain("不支持 resume 续聊");
     // 恢复指引（EngineError.recovery）：W3 协议化口径——调参数 / 修 manifest / 升级
     // 引擎包（引擎包是能力声明载体；「改用 engine: pi」内置兜底指引已随协议化删除）
     expect((err as { recovery?: string }).recovery).toContain("去掉 conversation 参数");
@@ -519,6 +534,47 @@ describe("chat 工具域引擎路由分叉（U0：D4/D5/D10）", () => {
     // 按句移除断言（W10 注）：inproc 双模不回灌 childStateChanged，镜像移除由
     // protocol-blackbox 承载（同 subprocess-agent-runner-routing D10 注）。
   });
+
+  // ============================================================
+  // 6. [F6] sessionRootId 注入（execute / executeAndAwait 两 runCtx 构造点）
+  // ============================================================
+
+  it("[F6] service.sessionRootId 注入 runCtx（根 session id 贯穿引擎派发——relay 归属键 SESSION_ID 权威源）", async () => {
+    // 根进程形态：env 无 PI_SUBAGENT_ROOT_SESSION_ID 时 sessionRootId = init.sessionId。
+    // 删除防外层 env 污染（该键存在时 initSession 走子进程形态，断言基准漂移）。
+    const prevRootEnv = process.env["PI_SUBAGENT_ROOT_SESSION_ID"];
+    delete process.env["PI_SUBAGENT_ROOT_SESSION_ID"];
+    try {
+      const { service, zcode, piEngine } = setup(agentDir);
+      zcode.runImpl = () => Promise.resolve({ handle: fakeHandle(), outcome: doneOutcome("ok") });
+      piEngine.runImpl = () => Promise.resolve({ handle: fakeHandle(), outcome: doneOutcome("ok") });
+
+      // chat 域 background 派发（runEngineTask 的 runCtx 构造点）
+      await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+      await vi.waitFor(() => expect(zcode.runs.length).toBe(1));
+      expect(zcode.runs[0].ctx.sessionRootId).toBe("test-session");
+
+      // workflow 域 sync 派发（runAndFinalize 的 runCtx 构造点；其引擎解析恒走
+      // registry 'pi'——resolveChatEnginePort，不消费 opts.engine）。fire-and-forget：
+      // 本 harness 无 idle-notify 驱动面，收尾链（finalizeRoundToIdle）不收敛——
+      // 只断言构造点（runs 捕获在收尾之前），与既有用例的挂起 record 同等形态。
+      let awaitErr: unknown;
+      void service
+        .executeAndAwait(baseOpts(agentDir, { slug: "f6-await" }))
+        .catch((e: unknown) => {
+          awaitErr = e;
+        });
+      await vi.waitFor(() => {
+        if (awaitErr !== undefined) {
+          throw new Error(`executeAndAwait rejected before engine.run: ${String(awaitErr)}`);
+        }
+        expect(piEngine.runs.length).toBe(1);
+      });
+      expect(piEngine.runs[0].ctx.sessionRootId).toBe("test-session");
+    } finally {
+      if (prevRootEnv !== undefined) process.env["PI_SUBAGENT_ROOT_SESSION_ID"] = prevRootEnv;
+    }
+  }, 10_000);
 });
 
 // ============================================================
@@ -676,6 +732,66 @@ describe("chat 引擎分支 U2：probe 兜底 / journal / engineHandle", () => {
     await vi.waitFor(() => expect(service["findRecord"](handle.subagentId)).toBeUndefined());
   }, 10_000);
 
+  it("[onHandleReady F1] sessionId 先落 + 迟到只补 sessionFile → 按字段补缺落位；已有值不被迟到值覆盖（幂等）", async () => {
+    process.env.XYZ_AGENT_DATA_DIR = agentDir;
+    const { service, zcode, pi } = setup(agentDir);
+    const POOL = "zcode-appserver-home";
+    const LATE_SESSION_FILE = "/tmp/late/session-abc.jsonl";
+    let releaseRun!: (v: { handle: EngineHandle; outcome: AgentOutcome }) => void;
+    zcode.runImpl = (task, ctx) => {
+      ctx.onPoolResolved?.(POOL);
+      // ① create 应答：只带 sessionId（本 replay 批次新打通的可达面——close 期 LC-4
+      // 后缀反查在 sessionId 已知后才补发 sessionFile）。
+      ctx.onHandleReady?.({
+        sessionRef: { dbPath: ".zcode/cli/db/db.sqlite", sessionId: "sess-live-1" },
+        poolKey: POOL,
+      });
+      // ② 迟到 handleReady：只补 sessionFile——旧守卫「有 sessionId 即整条 return」
+      // 会把它整条吞掉，sessionFile 永不落位（消费点：冷续 resume 锚点 / interact 定位）。
+      ctx.onHandleReady?.({
+        sessionRef: { sessionId: "sess-live-1", sessionFile: LATE_SESSION_FILE },
+        poolKey: POOL,
+      });
+      // ③ 再迟到一次且带冲突值：已有值必须原样保留（幂等），poolKey 不被重置。
+      ctx.onHandleReady?.({
+        sessionRef: { sessionId: "sess-OVERWRITE", sessionFile: "/tmp/late/other.jsonl" },
+        poolKey: "hijacked-pool",
+      });
+      return new Promise((resolve) => {
+        releaseRun = resolve;
+      });
+    };
+    const handle = await service.execute(baseOpts(agentDir, { engine: "zcode" }));
+    await vi.waitFor(() => expect(zcode.runs.length).toBe(1));
+
+    const running = service["collectRecords"](10, "running").find((r) => r.id === handle.subagentId);
+    // 补缺落位：sessionFile 进 record.engineHandle（①级会话取证 / 冷续 resume 锚点钥匙）
+    expect(running?.engineHandle?.sessionRef["sessionFile"]).toBe(LATE_SESSION_FILE);
+    expect(running?.engineHandle).toEqual({
+      sessionRef: {
+        dbPath: ".zcode/cli/db/db.sqlite",
+        sessionId: "sess-live-1",
+        sessionFile: LATE_SESSION_FILE,
+      },
+      poolKey: POOL,
+      journalPath: resolveJournalPath(agentDir, "zcode", POOL, handle.subagentId),
+    });
+    // 补缺经 entry 持久化（运行中 GUI 经 entry 重建 record 即可见），且 ③ 的
+    // 「无新字段」重复回调不产生第二条写噪（同 sessionFile 恰好一条）。
+    const entries = pi.appendEntry.mock.calls.filter((c) => c[0] === "subagent-record");
+    const withLateSessionFile = entries.filter(
+      (c) =>
+        ((c[1] as Record<string, unknown>).engineHandle as
+          | { sessionRef?: Record<string, string> }
+          | undefined)?.sessionRef?.["sessionFile"] === LATE_SESSION_FILE,
+    );
+    expect(withLateSessionFile).toHaveLength(1);
+
+    // 终态收口（防 dangling）
+    releaseRun({ handle: fakeHandle(), outcome: doneOutcome("ok") });
+    await vi.waitFor(() => expect(service["findRecord"](handle.subagentId)).toBeUndefined());
+  }, 10_000);
+
   it("[onHandleReady] 引擎不回调（spawn 形态）时零回填——终态回填仍兜底（行为不变）", async () => {
     process.env.XYZ_AGENT_DATA_DIR = agentDir;
     const { service, zcode, pi } = setup(agentDir);