@zhushanwen/subagent-core 0.7.1 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-core",
-  "version": "0.7.1",
+  "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",
@@ -73,8 +73,8 @@
     "ajv": "^8.20.0",
     "proper-lockfile": "^4.1.2",
     "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.8.2",
-    "@zhushanwen/subagent-engine-sdk": "0.2.1"
+    "@xyz-agent/extension-protocol": "0.9.0",
+    "@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.1.2"
+    "@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__/record-store-last-line.test.ts

@@ -21,6 +21,18 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { ManifestStore } from "../execution/manifest-store";
 import { RecordStore } from "../execution/record-store";
 
+// [Gate A teardown 稳定性] no-op 掉索引落盘。根因：recoverOrphanRecords 走的
+// reconstructAll（record-store.ts）扫描尾 fire-and-forget saveIndex（tmp+fsync+rename
+// 异步 fs），满载下该 promise 可能在本文件 teardown 之后才 settle，其失败分支经
+// logger.warn → console.warn 上报 vitest（rpc onUserConsoleLog 在途）——worker 关闭
+// rpc 时在途调用被 reject 为 EnvironmentTeardownError（0 断言失败，纯 teardown 时序）。
+// 本文件用一次性 tmpdir、断言只观察 appendEntry 捕获的判定结果，落盘与否无观察者——
+// no-op 消除在途 IO 链，任何负载下确定；loadIndex 等其余导出保留原实现。
+vi.mock("../execution/sessions-index.ts", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../execution/sessions-index.ts")>()),
+  saveIndex: async () => {},
+}));
+
 interface CapturedEntry {
   type: string;
   data: Record<string, unknown>;

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/core/logger.ts

@@ -13,7 +13,7 @@
 
 import { getHostServices } from "./host-services.ts";
 
-/** 日志级别。对齐 @zhushanwen/pi-extension-logger 的 LogLevel（三值，无 info）。 */
+/** 日志级别。级别集合对齐 pi-extension-logger（其 LogLevel 为包内部类型、含 info 四值；实例 API 仅 debug/warn/error 三方法，core facade 据此收窄为三值）。 */
 export type LogLevel = "debug" | "warn" | "error";
 
 /** core logger 接口。与 pi-extension-logger 的 ExtensionLogger 结构兼容——

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 }),
+    );
+  });
+});