@zhushanwen/pi-delivery-port 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-delivery-port",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "In-process delivery port for the pi half of the unified delivery service (design .tmp/tech-design/unified-delivery.md §3.7): binds pi appendEntry / sessionManager.getEntries / isIdle / sendMessage / message_end / session_compact into the @zhushanwen/session-delivery v3 kernel as the sole executor of the custom lane — outbox journal (entry schema v2 + v1 notify-ledger compat read), details-id delivery proof, session_start difference-set replay, edge-immediate dispatch with external-channel isolation (permanent dedup via the delivery journal), and compaction-wait degradation (shared library, not a Pi extension).",
   "type": "module",
   "main": "src/index.ts",
@@ -17,21 +17,23 @@
     "src/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.24.0"
+    "@zhushanwen/extension-protocol": "0.27.0",
+    "@zhushanwen/pi-ext-guards": "0.5.1",
+    "@zhushanwen/pi-extension-logger": "0.6.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^1.0.0",
-    "@zhushanwen/session-delivery": "2.1.0"
+    "@zhushanwen/session-delivery": "2.2.0"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/session-delivery": "2.1.0"
+    "@zhushanwen/session-delivery": "2.2.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run --pool=threads"
   }
 }

package/src/__tests__/delivery-port.test.ts

@@ -552,6 +552,32 @@ describe("session_start 差集重放", () => {
 		// sent 2 条 = first 实例注入 1（投出未送达——无回执无 ack，差集合法重投）+ 重放 1
 		expect(h.sent).toHaveLength(2);
 	});
+
+	it("重绑交接（in-flight 预占）：前驱已出站条目后继不重放（bindDeliveryPort 双投窗口封住，A4 真机回归）；崩溃形态（无前驱交接）照旧重放", () => {
+		const h = makeHost();
+		// 同一 session 的两次 bind（session_start 连发，真机 10ms 级间隔）：第一次
+		// bind 后受理并出站一条（注入完成、凭据未落——pi 异步写 entry 的窗口）。
+		const first = bindDeliveryPort(h.host);
+		first.deliver(defaultEnvelope({ id: "rb-1", payload: { kind: "custom", customType: DEFAULT_NOTIFY_CUSTOM_TYPE, content: "redelivered", display: true } }));
+		expect(h.sent).toHaveLength(1); // 已出站（sendMessage 交递完成）
+		expect(h.outboxEntries()).toHaveLength(1);
+		const deliveredProofCount = (): number =>
+			h.host.readSessionEntries().filter(
+				(e) => (e as Record<string, unknown>)["type"] === "custom_message",
+			).length;
+		expect(deliveredProofCount()).toBe(0); // 凭据未落（注入异步——重放窗口的构成条件）
+
+		// 第二次 bind：交接 in-flight 集合 + dispose 前驱 → 后继 recover 跳过该条
+		// （消息在途必达，重放 = 双投）。sent 恒 1、recoveryReplays 零计数。
+		const second = bindDeliveryPort(h.host);
+		expect(second.recover()).toBe(0);
+		expect(h.sent).toHaveLength(1);
+
+		// 对照（崩溃形态）：无前驱交接的新实例（进程重启语义）对同一未凭据 outbox
+		// 照旧重放——崩溃恢复通道不受交接影响。
+		const third = createDeliveryPort(h.host);
+		expect(third.recover()).toBe(1);
+	});
 });
 
 // ─── 耐久承诺 ───────────────────────────────────────────────
@@ -577,6 +603,54 @@ describe("受理前落盘（耐久承诺）", () => {
 	});
 });
 
+// ─── 终局持久化失败（磁盘权威）──────────────────────────────
+
+describe("终局持久化失败（磁盘权威：ack 写盘失败 → 内核内存不登记终态）", () => {
+	it("ack entry 写失败 → message_end 边沿不炸、ack 未落、分型错误经 warn 留痕；写盘恢复后下一边沿补落", () => {
+		const h = makeHost();
+		const orig = h.host.appendEntry;
+		let ackBroken = true;
+		h.host.appendEntry = (customType, data) => {
+			if (ackBroken && customType === ACK_CUSTOM_TYPE) throw new Error("disk full (fake)");
+			orig(customType, data);
+		};
+		const port = createDeliveryPort(h.host);
+		port.deliver(defaultEnvelope({ id: "af-1" }));
+		expect(h.sent).toHaveLength(1);
+		// message_end 命中 → 内核终局 ack → appendEntry(ack) 抛错：边沿回调不炸
+		//（内核捕获分型错误返回 false，异常不上抛 pi 事件循环）
+		expect(() => h.injectAndEmit(h.sent[0].message)).not.toThrow();
+		expect(h.ackEntries()).toHaveLength(0); // 持久终局未落
+		expect(h.warn.mock.calls.some((c) => String(c[0]).includes("store.ack failed"))).toBe(true);
+		// 写盘恢复：同一 message 的下一 message_end 边沿重驱动 → ack 补落（重试路径）
+		ackBroken = false;
+		h.fireMessageEnd({ role: "custom", ...h.sent[0].message, timestamp: Date.now() });
+		expect(h.ackEntries()).toHaveLength(1);
+		expect(h.ackEntries()[0]!["data"]).toMatchObject({ v: 2, id: "af-1" });
+		expect(port.recover()).toBe(0); // 终局已落，差集清零
+	});
+
+	it("ack 写失败期间「重启」（新实例重扫）：注入事实（custom_message entry）保持判重——不重投", () => {
+		const h = makeHost();
+		const orig = h.host.appendEntry;
+		h.host.appendEntry = (customType, data) => {
+			if (customType === ACK_CUSTOM_TYPE) throw new Error("disk full (fake)");
+			orig(customType, data);
+		};
+		const port = createDeliveryPort(h.host);
+		port.deliver(defaultEnvelope({ id: "af-2" }));
+		h.injectAndEmit(h.sent[0].message); // 注入事实已落 custom_message entry；ack 写失败
+		expect(h.ackEntries()).toHaveLength(0);
+		port.dispose();
+		// 磁盘权威的送达事实 = 注入 entry 携带的 deliveryId（非 ack entry）：新实例差集
+		// 不含该条，不重投（ack entry 缺席不破坏判重）
+		const revived = createDeliveryPort(h.host);
+		expect(revived.recover()).toBe(0);
+		expect(h.sent).toHaveLength(1);
+		revived.dispose();
+	});
+});
+
 // ─── 装配槽（C-ext-06 惯例）─────────────────────────────────
 
 describe("进程级槽（bindDeliveryPort / getDeliveryPort）", () => {
@@ -599,7 +673,7 @@ describe("进程级槽（bindDeliveryPort / getDeliveryPort）", () => {
 	});
 });
 
-// ─── collect 挂起面（result-collect 设计 §3.1②；§4 中断形态单测分工）───
+// ─── collect 挂起行为（result-collect 设计 §3.1②；§4 中断形态单测分工）───
 
 /** pending register entry fixture（写侧落盘形态：index.ts safeAppendEntry 同构）。 */
 const pendingRegister = (id: string, type = "bash") => ({

package/src/__tests__/journal.test.ts

@@ -1,6 +1,6 @@
 // journal schema v2 定形与 v1 兼容读映射的单测锁定（设计「待验证检查点 1」，
 // unified-delivery.impl-plan §0：检查点 1 → u2-delivery-port）。
-// 锁定面：① v2 outbox/ack data 字段定形与形态校验宽容度；② v1（notify 账本）
+// 锁定范围：① v2 outbox/ack data 字段定形与形态校验宽容度；② v1（notify 账本）
 // 映射函数全字段（notifyId→id / timing / customType 通道映射 / record→details）；
 // ③ 差集扫描基线（outbox 后写覆盖 / ack 双形态 / delivered details-id 双形态与
 // 接受域）。schema 漂移在此红。

package/src/__tests__/pi-host.test.ts

@@ -1,5 +1,5 @@
 // createPiDeliveryPortHost 接线行为锁：八个端口的透传语义逐成员断言（pi-host.ts 头注
-// 接线纪律的行为面）——原样透传不加工、订阅面返回 pi 退订函数、事件回调只裁剪事件体、
+// 接线纪律的行为集）——原样透传不加工、订阅返回 pi 退订函数、事件回调只裁剪事件体、
 // sendMessage 恒 { triggerTurn: true }。fake pi/ctx 全内存，无 fs。
 import { describe, expect, it } from "vitest";
 
@@ -62,7 +62,7 @@ describe("createPiDeliveryPortHost 接线（七端口逐成员）", () => {
 		expect(host.readSessionEntries()).toBe(entries);
 		expect(host.isIdle()).toBe(false);
 		// [subagent-observability §3.3.7③] hasRunningBackground 已随攒批窗退役删除，
-		// 接线面不再含该成员（结构断言：host 对象无此键）。
+		// 接线结果不再含该成员（结构断言：host 对象无此键）。
 		expect("hasRunningBackground" in host).toBe(false);
 	});
 
@@ -81,7 +81,7 @@ describe("createPiDeliveryPortHost 接线（七端口逐成员）", () => {
 		expect(sent[0].options).toEqual({ triggerTurn: true, deliverAs: "steer" });
 	});
 
-	it("订阅面注册到 pi.on 对应事件、handler 只收事件体、退订兑现 pi 退订函数", () => {
+	it("订阅类端口注册到 pi.on 对应事件、handler 只收事件体、退订兑现 pi 退订函数", () => {
 		const { pi, registered, unsubscribed } = makePi();
 		const host = createPiDeliveryPortHost(
 			pi as never,
@@ -113,7 +113,7 @@ describe("createPiDeliveryPortHost 接线（七端口逐成员）", () => {
 		messageEndHandler({ message: { role: "custom" } });
 		expect(received).toEqual({ role: "custom" });
 
-		// 退订函数 = pi.on 返回的退订（port dispose 时兑现的契约面）
+		// 退订函数 = pi.on 返回的退订（port dispose 时兑现的契约）
 		offMessageEnd();
 		expect(unsubscribed).toEqual(["message_end"]);
 	});

package/src/__tests__/reconcile-edge.test.ts

@@ -0,0 +1,102 @@
+// reconcile-edge.test.ts —— 切回边沿对账转发注册槽（completion-signal-delivery
+// D8② 三入口同构的跨扩展接线件）行为锁：订阅派发 / 多域分发 / 同域覆盖（reload
+// 生命周期）/ 域隔离围栏（单域 throw 不阻断其余域 + 失败清单报告）/ 空槽缺席
+// 语义 / 测试重置。槽挂 globalThis（C-ext-06），跨实例共享由 Symbol.for 键保证。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+	RESUME_RECONCILE_SLOT_KEY,
+	_resetResumeReconcileForTest,
+	dispatchResumeReconcile,
+	subscribeResumeReconcile,
+	type ResumeReconcileContext,
+} from "../reconcile-edge.ts";
+
+function makeCtx(): ResumeReconcileContext {
+	return {
+		sessionManager: {
+			getEntries: () => [],
+			getSessionFile: () => "/sessions/slot.jsonl",
+			getSessionId: () => "sess-slot",
+		},
+	};
+}
+
+beforeEach(() => {
+	_resetResumeReconcileForTest();
+});
+
+afterEach(() => {
+	_resetResumeReconcileForTest();
+});
+
+describe("subscribeResumeReconcile / dispatchResumeReconcile", () => {
+	it("订阅后派发：listener 收到 ctx 原样引用", () => {
+		const listener = vi.fn();
+		subscribeResumeReconcile("session-manager", listener);
+		const ctx = makeCtx();
+
+		const failures = dispatchResumeReconcile(ctx);
+
+		expect(failures).toEqual([]);
+		expect(listener).toHaveBeenCalledTimes(1);
+		expect(listener).toHaveBeenCalledWith(ctx);
+	});
+
+	it("多域订阅全部收到（Map 插入序派发）", () => {
+		const calls: string[] = [];
+		subscribeResumeReconcile("session-manager", () => calls.push("session-manager"));
+		subscribeResumeReconcile("subagent-workflow", () => calls.push("subagent-workflow"));
+
+		expect(dispatchResumeReconcile(makeCtx())).toEqual([]);
+		expect(calls).toEqual(["session-manager", "subagent-workflow"]);
+	});
+
+	it("同域重复订阅覆盖前值（extension reload 生命周期：新闭包覆盖旧闭包，旧订阅不再收）", () => {
+		const stale = vi.fn();
+		const fresh = vi.fn();
+		subscribeResumeReconcile("subagent-workflow", stale);
+		subscribeResumeReconcile("subagent-workflow", fresh);
+
+		expect(dispatchResumeReconcile(makeCtx())).toEqual([]);
+		expect(stale).not.toHaveBeenCalled();
+		expect(fresh).toHaveBeenCalledTimes(1);
+	});
+
+	it("单域 listener throw 不阻断其余域：失败逐域收集返回（派发方 warn 留痕的报告通道）", () => {
+		const boom = new Error("listener fence leak");
+		const healthy = vi.fn();
+		subscribeResumeReconcile("session-manager", () => {
+			throw boom;
+		});
+		subscribeResumeReconcile("subagent-workflow", healthy);
+
+		const failures = dispatchResumeReconcile(makeCtx());
+
+		expect(failures).toEqual([{ domain: "session-manager", error: boom }]);
+		expect(healthy).toHaveBeenCalledTimes(1);
+	});
+
+	it("空槽派发（两域扩展未启用 / 装配前）→ 空失败清单，不抛（缺席语义非错误）", () => {
+		expect(dispatchResumeReconcile(makeCtx())).toEqual([]);
+	});
+
+	it("_resetResumeReconcileForTest 清空全部订阅", () => {
+		const listener = vi.fn();
+		subscribeResumeReconcile("session-manager", listener);
+		_resetResumeReconcileForTest();
+
+		expect(dispatchResumeReconcile(makeCtx())).toEqual([]);
+		expect(listener).not.toHaveBeenCalled();
+	});
+
+	it("槽挂 globalThis（C-ext-06：Symbol.for 进程级槽，防 jiti 多实例槽分裂）", () => {
+		subscribeResumeReconcile("session-manager", () => {});
+		const slot = Reflect.get(globalThis, RESUME_RECONCILE_SLOT_KEY) as {
+			listeners: Map<string, unknown>;
+		} | undefined;
+		expect(slot).toBeDefined();
+		expect(slot!.listeners.has("session-manager")).toBe(true);
+	});
+});

package/src/__tests__/reconcile-judgement.test.ts

@@ -0,0 +1,187 @@
+// reconcile-judgement.test.ts —— 对账补投判据链收编单源的行为锁（原 bash 域
+// notify-reconcile-judgement.test.ts 骨架段 + session-manager / subagent-workflow
+// 域真值表对拍段随判据链收编迁此，三域物理副本退役）：三重事实骨架真值表 / 投递
+// 日志幂等键提取（v2 id + collectKey 键集展开 + v1 兼容读 + ack 终局并入 + 畸形
+// 跳过）/ session JSONL 磁盘读侧容错（ENOENT 常态空 / 读错误 warn + 空 / 脏行
+// 单行跳过）。域侧只剩「域事实 → 布尔」映射与编排测试（各域 __tests__）。
+
+import { chmodSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+}));
+
+import {
+	collectJournaledDeliveryIds,
+	isReconcileNotifyCandidate,
+	type ReconcileNotifyFacts,
+} from "../reconcile-judgement.ts";
+import { readSessionFileEntries } from "../session-journal-read.ts";
+import { readSessionFileEntries as indexExport } from "../index.ts";
+
+// 测试 fixture 的通知条目 customType（与 bash 域 BACKGROUND_BASH_CUSTOM_TYPE 同词表
+// ——判据对通知条目形态不敏感，只按结构化字段收集；此处仅作非投递日志条目的占位）。
+const BACKGROUND_BASH_CUSTOM_TYPE = "background-bash";
+
+const TASK_ID = "bt-1700000000-abcd12";
+const OTHER_TASK_ID = "bt-1700000000-efgh34";
+
+afterEach(() => {
+	loggerMock.warn.mockClear();
+});
+
+// ── 三重事实判据骨架真值表（跨域单源——bash / session-manager / subagent-workflow
+// 域侧映射进同一组合；原三域真值表对拍段的单点归并）──
+
+describe("isReconcileNotifyCandidate 骨架真值表（判据链收编单源）", () => {
+	const base: ReconcileNotifyFacts = {
+		isTerminal: true,
+		excludedByOrigin: false,
+		delivered: false,
+		journaled: false,
+	};
+	const truthTable: Array<[Partial<ReconcileNotifyFacts>, boolean, string]> = [
+		[{ ...base }, true, "rejected 丢失形态（四事实全命中）→ 候选"],
+		[{ isTerminal: false }, false, "在途/未终局 → 非候选"],
+		[{ excludedByOrigin: true }, false, "域排除位命中 → 非候选"],
+		[{ delivered: true }, false, "送达痕迹命中 → 非候选"],
+		[{ journaled: true }, false, "投递日志承载命中 → 非候选"],
+	];
+	for (const [facts, expected, label] of truthTable) {
+		it(label, () => {
+			expect(isReconcileNotifyCandidate({ ...base, ...facts })).toBe(expected);
+		});
+	}
+});
+
+// ── 投递日志幂等键提取（事实三事实源；原 judgement.test.ts「journal entry shapes」
+// 段 + session-manager/workflow 域 collectKey 展开用例的归并）──
+
+/** 投递日志 outbox entry（journal v2 落盘形态——port 受理前 appendEntry 写入）。 */
+function journaledOutboxEntry(id: string, dataOverrides: Record<string, unknown> = {}) {
+	return {
+		type: "custom",
+		customType: "delivery-port-outbox",
+		data: {
+			v: 2,
+			id,
+			timing: "steer",
+			payload: {
+				kind: "custom",
+				customType: BACKGROUND_BASH_CUSTOM_TYPE,
+				content: `notify ${id}`,
+				display: true,
+			},
+			recordedAt: 1,
+			...dataOverrides,
+		},
+	};
+}
+
+describe("collectJournaledDeliveryIds: journal entry shapes (fact-three source, D2)", () => {
+	it("v2 outbox entry hits via data.id", () => {
+		const ids = collectJournaledDeliveryIds([journaledOutboxEntry(TASK_ID)]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("v2 outbox collectKey 键集展开（承载反查——条目 id ≠ 业务键的承载形态，session-manager 合批成员键 / workflow 裸 runId 双源）", () => {
+		const ids = collectJournaledDeliveryIds([
+			journaledOutboxEntry("batch-head-key", { collectKey: [TASK_ID, OTHER_TASK_ID] }),
+		]);
+		expect([...ids].sort()).toEqual(["batch-head-key", TASK_ID, OTHER_TASK_ID].sort());
+	});
+
+	it("legacy v1 ledger entry (subagent-bg-notify-ledger) hits via notifyId mapping", () => {
+		const ids = collectJournaledDeliveryIds([
+			{
+				type: "custom",
+				customType: "subagent-bg-notify-ledger",
+				data: { v: 1, notifyId: TASK_ID, content: "c", record: {} },
+			},
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("ack terminal entry hits (defensive union with outbox in the same pass)", () => {
+		const ids = collectJournaledDeliveryIds([
+			{
+				type: "custom",
+				customType: "delivery-port-ack",
+				data: { v: 2, id: TASK_ID, outcome: "delivered" },
+			},
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("malformed / non-journal entries are skipped (tolerance aligned with port scanJournal)", () => {
+		const ids = collectJournaledDeliveryIds([
+			null,
+			42,
+			{ type: "custom_message", customType: BACKGROUND_BASH_CUSTOM_TYPE, content: `x ${TASK_ID}`, details: { taskId: TASK_ID } }, // 通知条目——非投递日志
+			{ type: "custom", customType: "delivery-port-outbox", data: { v: 2 } }, // data 畸形
+			{ type: "custom", customType: "delivery-port-outbox" }, // data 缺失
+			journaledOutboxEntry(TASK_ID),
+		]);
+		expect([...ids]).toEqual([TASK_ID]);
+	});
+
+	it("multiple ids across entries collect all", () => {
+		const ids = collectJournaledDeliveryIds([
+			journaledOutboxEntry(TASK_ID),
+			journaledOutboxEntry(OTHER_TASK_ID),
+		]);
+		expect([...ids].sort()).toEqual([TASK_ID, OTHER_TASK_ID].sort());
+	});
+});
+
+// ── session JSONL 磁盘读侧容错（原三域 readSessionFileEntries 容错段的单点归并；
+// 口径登记见 session-journal-read.ts 函数头注）──
+
+describe("readSessionFileEntries（磁盘读侧容错）", () => {
+	const DATA_DIR = mkdtempSync(join(tmpdir(), "port-readfile-"));
+
+	it("文件缺失（ENOENT，首条对话消息前常态）→ 空数组（静默，无 warn）", () => {
+		expect(readSessionFileEntries(join(DATA_DIR, "no-such-file.jsonl"))).toEqual([]);
+		expect(loggerMock.warn).not.toHaveBeenCalled();
+	});
+
+	it("脏行跳过、合法行解析（JSONL 逐行容错）", () => {
+		mkdirSync(DATA_DIR, { recursive: true });
+		const file = join(DATA_DIR, "dirty.jsonl");
+		writeFileSync(
+			file,
+			['{"type":"custom","customType":"x"}', "not-json", "", '{"type":"message"}'].join("\n"),
+		);
+		const entries = readSessionFileEntries(file);
+		expect(entries).toHaveLength(2);
+		expect(entries[0]).toEqual({ type: "custom", customType: "x" });
+	});
+
+	it("不可读文件（chmod 0000）→ 空 + warn（宽容口径：磁盘事实不可得 = 无条目）", () => {
+		mkdirSync(DATA_DIR, { recursive: true });
+		const file = join(DATA_DIR, "locked.jsonl");
+		writeFileSync(file, "{}\n");
+		chmodSync(file, 0o000);
+		try {
+			expect(readSessionFileEntries(file)).toEqual([]);
+			expect(loggerMock.warn).toHaveBeenCalledWith(
+				expect.stringContaining("disk entries treated as empty"),
+				expect.anything(),
+			);
+		} finally {
+			chmodSync(file, 0o644);
+		}
+	});
+
+	it("barrel 导出与实现模块同一符号（单源单实例）", () => {
+		expect(indexExport).toBe(readSessionFileEntries);
+	});
+});

package/src/delivery-port.ts

@@ -45,7 +45,7 @@
 // send 内保留第二道防线（标记检查，覆盖提交同步链与 compaction 边沿交叠的残余窗口）；
 // 标记读取无异常面（原 isIdle 探测的保守 busy 吞咽随预检移除）。
 //
-// ── collect 挂起面（result-collect 设计 §3.1②）──────────────
+// ── collect 挂起行为（result-collect 设计 §3.1②）──────────────
 // 批量收取的分流发生在提交编排层（deliver 入口）：条目照常受理前落盘（I2 耐久不
 // 变），随后按「collectKey 键集 ∩ 在途等待集 ≠ ∅」分流——命中 → 挂起缓冲（纯内存，
 // 不进投递内核）+ onCollectArrival 唤醒等待器；未命中 → push 现状零变化。挂起不独立
@@ -56,7 +56,7 @@
 // collect 阻塞期不可达（设计 §3.1 [重绑] 登记），dispose 只做在途等待器 warn 留痕
 // 不变量检查，不定义唤醒与返回语义。
 //
-// ── 耐久面的分工（为什么 store.persist 是 no-op）─────────────
+// ── 耐久职责的分工（为什么 store.persist 是 no-op）─────────────
 // outbox 权威 = 成员记录（deliver 入口 appendEntry，先于受理——「耐久承诺先于投递
 // 尝试」内核契约由该同步时序等价兑现：appendEntry 抛错 = 承诺未落 → deliver 返回
 // rejected("persist-failed")，不进投递流程）。内核侧 store.persist 因此有意 no-op：
@@ -126,10 +126,22 @@ function getSlot(): DeliveryPortSlot {
  * /new 的 session_start）先 dispose 旧实例再绑定新实例（dispose 旧实例 + 重建
  * ——内核态按 session 重建，防跨 session 重投）。
  * 调用方随后应调 handle.recover() 完成差集重放（装配点接线）。
+ *
+ * 出站交接（重绑双投窗口封住）：dispose 前取走前驱「in-flight（已交递 pi，注入由
+ * pi 侧异步完成）」的已受理 id 集合交接给后继预占——session_start 对同会话连发两次
+ * （真机实证，10ms 级间隔）时，前驱在两次 bind 间隙受理并出站的条目（如 subagent
+ * 域对账补投）尚未产生送达凭据，后继构造期扫描只见「outbox 无凭据」→ recover 重放
+ * = 同一条通知双投（A4 真机实证 recoveryReplays=1 + notify=2）。in-flight 条目由
+ * pi 侧必达注入，重放对它们是纯重复；预占后后继 recover 跳过、条目留 state.outbox，
+ * 凭据若最终未落地由后续 rebind 的重放兜底（跨进程重启无前驱可交接，崩溃恢复通道
+ * 不变）。queued / failed（未出站——dispose 丢弃）不在交接集合，后继重放恢复语义
+ * 不变。
  */
 export function bindDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
-  getSlot().current?.dispose();
-  const handle = createDeliveryPort(host);
+  const predecessor = getSlot().current;
+  const handoff = predecessor?.takeInFlightHandoff?.();
+  predecessor?.dispose();
+  const handle = createDeliveryPort(host, { predecessorInFlightIds: handoff });
   getSlot().current = handle;
   return handle;
 }
@@ -145,7 +157,7 @@ export function _resetDeliveryPortForTest(): void {
   getSlot().current = undefined;
 }
 
-// ─── 子系统装配（createDeliveryPort 的两个内聚子面：内核接线 / collect 挂起面）───
+// ─── 子系统装配（createDeliveryPort 的两个内聚子系统：内核接线 / collect 挂起）───
 //
 // createDeliveryPort 是装配壳：持提交侧闭包态（双缓冲 / hold 标志 / 幂等索引），两个
 // 子系统经工厂构造、以 deps 注入读端口闭包态——可变标志经 getter 出站时点读取（装配
@@ -157,7 +169,7 @@ function emitBucketLog(host: DeliveryPortHost, bucket: keyof DeliveryPortMetrics
   host.logger.warn(`delivery-port bucket [${bucket}]`, { detail: { total } });
 }
 
-/** 内核装配对端口闭包态的最小依赖面。 */
+/** 内核装配对端口闭包态的最小依赖集。 */
 interface KernelAssemblyDeps {
   host: DeliveryPortHost;
   state: JournalState;
@@ -180,11 +192,13 @@ function createKernelAssembly(deps: KernelAssemblyDeps): { kernel: ReturnType<ty
 
   const store: DeliveryStore = {
     persist(_record: DeliveryStoreRecord): void {
-      // 有意 no-op：port 半区落盘在 deliver 提交层前置完成（文件头「耐久面的分工」）。
+      // 有意 no-op：port 半区落盘在 deliver 提交层前置完成（文件头「耐久职责的分工」）。
     },
     ack(id: string): void {
-      // 内核终局（delivered / cancelled）→ 持久终局列。抛错由内核 ackStore 捕获
-      // warn（终局事实已发生不回滚）——本层不重复吞咽。
+      // 内核终局（delivered / cancelled）→ 持久终局列。磁盘权威：appendEntry 抛错 =
+      // 持久终局未写入 → state.ackedIds 不登记（内存派生数据只在落盘成功后登记），
+      // 错误上抛由内核包装分型错误 DeliveryAckPersistError——内核不登记内存终态、条目
+      // 留守非终态（恢复后可能重投，at-least-once 显式接受），本层不吞咽。
       host.appendEntry(ACK_CUSTOM_TYPE, { v: 2, id });
       state.ackedIds.add(id);
     },
@@ -267,7 +281,7 @@ function createKernelAssembly(deps: KernelAssemblyDeps): { kernel: ReturnType<ty
   return { kernel: createDelivery(kernelPort, kernelConfig) };
 }
 
-/** collect 挂起面对端口闭包态的最小依赖面（result-collect 设计 §3.1②）。 */
+/** collect 挂起子系统对端口闭包态的最小依赖集（result-collect 设计 §3.1②）。 */
 interface CollectFaceDeps {
   host: DeliveryPortHost;
   state: JournalState;
@@ -279,7 +293,7 @@ interface CollectFaceDeps {
   routeDirect(records: readonly JournalRecord[]): void;
 }
 
-/** collect 挂起面对端口的路由面（deliver 分流判定 / handle 装配 / dispose 清理）。 */
+/** collect 挂起子系统对端口的路由接口（deliver 分流判定 / handle 装配 / dispose 清理）。 */
 interface CollectFace {
   /** deliver 分流判定：键集 ∩ 在途等待集 ≠ ∅。 */
   hasWaiterFor(collectKeys: readonly string[]): boolean;
@@ -289,12 +303,12 @@ interface CollectFace {
   consume(): CollectedEntry[];
   collectRelease(): void;
   onCollectArrival(cb: () => void): () => void;
-  /** 清空挂起面三集合；返回清空前的在途量（dispose 不变量 warn 的判定与数据）。 */
+  /** 清空挂起行为的三个集合；返回清空前的在途量（dispose 不变量 warn 的判定与数据）。 */
   dispose(): { waiting: number; suspended: number };
 }
 
 /**
- * collect 挂起面（result-collect 设计 §3.1②，纯内存分流态，投递日志即耐久层）：
+ * collect 挂起行为（result-collect 设计 §3.1②，纯内存分流态，投递日志即耐久层）：
  * 登记等待集 / 挂起缓冲 / 到达唤醒 + consume 收取 + collectRelease 解散，自成
  * 子系统；对 push 管线只有两个触点——deliver 分流（hasWaiterFor / suspend）与
  * 解散直通（routeDirect 回调）。
@@ -334,6 +348,11 @@ function createCollectFace(deps: CollectFaceDeps): CollectFace {
     };
   }
 
+  /** 注销 key 的 outcome（结清视图优先——权威通道 resolveSettlementReason；legacy status 兜底）。 */
+  function unregisterOutcomeOf(pending: PendingBaseline, key: string) {
+    return pending.unregisterSettlements.get(key) ?? pending.unregisterStatus.get(key);
+  }
+
   /**
    * 登记在途等待集 + 对每个 key 按五态判据定态（同步段：JS 单线程内无交错窗口，
    * 与 deliver 分流读同一等待集——I3 等待集原子性）。
@@ -352,12 +371,7 @@ function createCollectFace(deps: CollectFaceDeps): CollectFace {
    *   曾注册集的补集。不登记等待集（防空等到 timeout 挂死）、不虚构终态；工具侧
    *   读本态组装 errors（不再伪装 waiting——端口是唯一未知判定点，词表诚实表达）。
    */
-  /** 注销 key 的 outcome（结清视图优先——权威通道 resolveSettlementReason；legacy status 兜底）。 */
-function unregisterOutcomeOf(pending: PendingBaseline, key: string) {
-  return pending.unregisterSettlements.get(key) ?? pending.unregisterStatus.get(key);
-}
-
-function collectArm(keys: string[]): CollectSnapshot {
+  function collectArm(keys: string[]): CollectSnapshot {
     if (deps.isDisposed()) throw new Error("collectArm on disposed delivery port");
     const pending = scanPendingBaseline(host.readSessionEntries());
     const snapshot: CollectSnapshot = [];
@@ -491,7 +505,10 @@ function collectArm(keys: string[]): CollectSnapshot {
  * 构造投递端口（内核装配 + 提交侧机制 + 回执订阅 + 重放）。
  * 事件订阅在构造期建立、dispose 时退订——构造即生效，不依赖调用方再接线。
  */
-export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
+export function createDeliveryPort(
+  host: DeliveryPortHost,
+  options?: { predecessorInFlightIds?: ReadonlySet<string> },
+): DeliveryPortHandle {
   const scan = scanJournal(host.readSessionEntries(), Date.now());
   const state = new JournalState(scan);
   const buckets: DeliveryPortMetrics = { settleRejected: 0, recoveryReplays: 0 };
@@ -505,6 +522,10 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
   /** 已受理 id 索引（deliver 幂等预检的全窗口快路径；内核三级判重对已入内核条目
    *  兜底）。仅增量添加，无淘汰——量级 = 每 session 通知总量（数十~数百）。 */
   const seenIds = new Set<string>();
+  // 前驱出站交接预占（重绑双投窗口封住，见 bindDeliveryPort 头注）：预占进 seenIds
+  // 同时封住 recover 重放与同 id 再 deliver 两条路径；条目本身仍在 state.outbox
+  // （构造期扫描收录），凭据最终未落地时由后续 rebind 重放兜底。
+  for (const id of options?.predecessorInFlightIds ?? []) seenIds.add(id);
   /** merge-commit 期标志：默认通道组逐条提交内核期间 hold 注入，使成员聚合为内核
    *  queued 集，最后 kernel.flush() 一次合批出站（见文件头分组放行段）。 */
   let mergeCommitting = false;
@@ -521,7 +542,7 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
   /**
    * 显式覆写的失败保留策略（deliver opts.onFailure → submitToKernel 的单次传递）：
    * 条目在提交缓冲期（compaction 挂起等提交期悬置；攒批窗已删 §3.3.7③）暂存 id → policy，提交内核时
-   * 消费并摘除。不进 JournalRecord / outbox schema（§3.7 耐久面行 schema 定形，
+   * 消费并摘除。不进 JournalRecord / outbox schema（§3.7 耐久职责行 schema 定形，
    * 策略是提交时选项非账目字段）。重放重建的条目不在册（缺省 retain）：forget
    * 条目首败即 discard 落终局列、不在重放差集；「首败前崩溃」的残留条目重放按
    * retain 重投（通知域安全侧，多留账不丢不重）。
@@ -543,7 +564,7 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
     isCompacting: () => compacting,
   });
 
-  // ─── collect 挂起面（result-collect 设计 §3.1②；子系统实现见 createCollectFace）───
+  // ─── collect 挂起子系统（result-collect 设计 §3.1②；实现见 createCollectFace）───
   // routeDirect = 解散等待集后未收条目的直通放行（进 pumpDirect 分组放行管线——
   // 边沿即投，攒批窗已删 §3.3.7③，不逐条唤醒泵）。
   const collectFace = createCollectFace({
@@ -694,8 +715,13 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
   ): void {
     // collect 挂起分流（result-collect 设计 §3.1②，先于放行）：键集 ∩ 在途
     // 等待集 ≠ ∅ → 挂起缓冲（不进内核，push 管线零感知）+ 唤醒等待器；否则 push
-    // 现状零变化。
+    // 现状零变化。分流命中 debug 留痕：挂起条目对 push 读面（对话流/事件流）完全
+    // 不可见，无留痕时「受理成功但消息未出站」无从与下游断裂区分（A15 排障
+    // 9 轮迷路于此）。
     if (collectKeys !== undefined && collectKeys.length > 0 && collectFace.hasWaiterFor(collectKeys)) {
+      host.logger.debug("delivery-port accepted entry suspended by collect waiter (redelivery deferred until consume/collectRelease)", {
+        detail: { id, collectKey: [...collectKeys] },
+      });
       collectFace.suspend(id, record);
       seenIds.add(id);
       return;
@@ -762,7 +788,7 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
   /**
    * 单成员提交内核。返回值处置：swallowed = 已终局（幂等命中，丢弃即正确——该
    * 通知已送达过）；rejected 理论不可达（store.persist no-op 恒成功、payload 恒
-   * custom、放行前已挡 disposed），warn 防御留痕；accepted 出站面由内核托管
+   * custom、放行前已挡 disposed），warn 防御留痕；accepted 出站环节由内核托管
    * （retain 留守 → settled 边沿 / compaction 边沿重投）。
    */
   function submitToKernel(rec: JournalRecord): void {
@@ -797,6 +823,21 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
 
   // ─── 重放（session_start 差集重放）─────────────────────────
 
+  /**
+   * 重绑交接面（bindDeliveryPort 专用，dispose 前调用）：内核 entriesFull 快照中
+   * state=in-flight 的已受理 id 集。in-flight = 已交递 pi（sendMessage 完成，注入
+   * 由 pi 侧异步完成）——pi 持有必达，后继重放对它们构成同条通知双投（A4 真机实证
+   * recoveryReplays=1 + notify=2），交接预占封住；queued（merge-commit-hold 残留）
+   * 与 failed（retain 留守）未出站——dispose 丢弃后由后继重放恢复，不在交接集合。
+   */
+  function takeInFlightHandoff(): ReadonlySet<string> {
+    const handoff = new Set<string>();
+    for (const entry of kernel.entriesFull().active) {
+      if (entry.state === "in-flight") handoff.add(entry.id);
+    }
+    return handoff;
+  }
+
   function recover(): number {
     if (disposed) return 0;
     let replayed = 0;
@@ -862,6 +903,7 @@ export function createDeliveryPort(host: DeliveryPortHost): DeliveryPortHandle {
     metrics,
     flush,
     dispose,
+    takeInFlightHandoff,
     collectArm: collectFace.collectArm,
     consume: collectFace.consume,
     collectRelease: collectFace.collectRelease,

package/src/index.ts

@@ -53,4 +53,21 @@ export {
   getDeliveryPort,
 } from "./delivery-port.ts";
 
+export {
+  RESUME_RECONCILE_SLOT_KEY,
+  _resetResumeReconcileForTest,
+  dispatchResumeReconcile,
+  subscribeResumeReconcile,
+  type ResumeReconcileContext,
+  type ResumeReconcileListener,
+} from "./reconcile-edge.ts";
+
+export {
+  collectJournaledDeliveryIds,
+  isReconcileNotifyCandidate,
+  type ReconcileNotifyFacts,
+} from "./reconcile-judgement.ts";
+
+export { readSessionFileEntries, resolveReconcileFactEntries } from "./session-journal-read.ts";
+
 export { createPiDeliveryPortHost, type CreatePiDeliveryPortHostOptions } from "./pi-host.ts";

package/src/journal.ts

@@ -1,6 +1,6 @@
 // src/journal.ts
 //
-// 投递日志（delivery journal，设计 §3.3 词条 / §3.7 耐久面行）的 entry schema 与
+// 投递日志（delivery journal，设计 §3.3 词条 / §3.7 耐久职责行）的 entry schema 与
 // 扫描/映射函数。schema 定形与 v1 兼容读映射 = 设计「待验证检查点 1」（unified-
 // delivery §7）落点，由 src/__tests__/journal.test.ts 单测锁定。
 //
@@ -56,7 +56,7 @@ export interface OutboxEntryDataV1 { // oe-exempt:20261017:framework:投递日
 }
 
 /**
- * v2 outbox entry data（待验证检查点 1 定形；设计 §3.7 耐久面行字段集）。
+ * v2 outbox entry data（待验证检查点 1 定形；设计 §3.7 耐久职责行字段集）。
  * payload 为调用方业务原样（不含 deliveryId——凭据 id 由端口在注入前统一写入
  * details，重放重投时同样注入；journal 记录保持业务原样使记录与注入形态解耦）。
  */
@@ -113,7 +113,7 @@ export interface JournalRecord { // oe-exempt:20261017:framework:投递日志记
 }
 
 /** 扫描结果（构造期全量 + 运行时增量维护的基线形态）。 */
-export interface JournalScan { // oe-exempt:20261017:framework:投递日志差集扫描契约（session_start 重放面）
+export interface JournalScan { // oe-exempt:20261017:framework:投递日志差集扫描契约（session_start 重放）
   /** outbox 记录（id → record；后写覆盖——同 id 多条 entry 取最新）。 */
   outbox: Map<string, JournalRecord>;
   /** 终局 id（ack ∪ discard）。 */

package/src/pi-host.ts

@@ -5,11 +5,11 @@
 //
 // 接线纪律：
 // - 原样透传（appendEntry / getEntries / isIdle / sendMessage），不加工不缓存；
-// - 订阅面（message_end / agent_settled / session_before_compact / session_compact /
+// - 订阅类端口（message_end / agent_settled / session_before_compact / session_compact /
 //   session_compact_failed）透传 handler 并返回 pi 的退订函数（pi 1.0.0 起 on 返回
 //   unsubscribe，port dispose 时兑现——防 session_start 重绑累积死 handler）；
 // - 事件回调的入参裁剪：port 只消费事件的事件体（message 等），ctx 参数不透传
-//   （port 的宿主状态面只经构造期注入的 ctx）；
+//   （port 的宿主状态只经构造期注入的 ctx）；
 // - 注入 sendMessage 恒 { triggerTurn: true }（custom 消息 append 后若无 turn 则成
 //   死文——deliverAs 两档控制队列位置，triggerTurn 控制空闲唤醒，两者正交）。
 
@@ -18,7 +18,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import type { DeliveryPortHost } from "./types.ts";
 
 /** 工厂选项：装配观测差异参数化。 */
-export interface CreatePiDeliveryPortHostOptions { // oe-exempt:20261017:framework:pi 半区装配契约接口（宿主注入面，适配层持久契约）
+export interface CreatePiDeliveryPortHostOptions { // oe-exempt:20261017:framework:pi 半区装配契约接口（宿主注入侧，适配层持久契约）
   /** warn/debug 归因标签（建议装配扩展名，如 "base-tool-enhance"）。 */
   component: string;
   /** 降级与诊断出口（@zhushanwen/pi-extension-logger 的 ExtensionLogger）。 */

package/src/reconcile-edge.ts

@@ -0,0 +1,92 @@
+// src/reconcile-edge.ts
+//
+// 切回边沿对账转发注册槽（completion-signal-delivery D8② 三入口同构的跨扩展
+// 接线件）：`__taiji_bg_reconcile__` 内部命令（切回补强边沿——taiji runtime 在
+// getCommands 时 fire-and-forget 触发，无节流——原 60s per-session 节流窗已随
+// ADR-0122 防御机制清查退役，高频防护由订阅域对账预检判据早退承担；覆盖
+// 「切走切回同进程重挂接、session_start 不重发」场景）的注册方是
+// @zhushanwen/pi-base-tool-enhance，而 session-manager /
+// subagent-workflow 两域的对账编排在各自扩展内装配（deps 需当前 pi / session
+// entries / 域闭包状态，外部无法直构）。subagent 域的同类转发走 SubagentService
+// 进程单例（base-tool-enhance 直依 subagent-core，A5 先例）；两域与
+// base-tool-enhance 无依赖边（跨扩展依赖通道不存在），本槽作为三方共同依赖包
+// 内的进程级转发点补上该通道：两域 extension load 时订阅，切回 handler 派发。
+//
+// 生命周期（与 pi.on 装配期订阅的 RL13 论证同款）：订阅点 = extension load
+// 装配期，同域 key 重复订阅覆盖前值——同进程 session 替换会重建 eventBus 并
+// 重新 load extension，新实例的订阅覆盖旧实例（旧闭包捕获的 stale pi 随之被
+// 替换），无死 handler 累积。槽本体挂 globalThis（C-ext-06：Symbol.for +
+// 进程级槽，防 jiti 多实例模块图槽分裂——delivery-port.ts 的
+// DELIVERY_PORT_SLOT_KEY 同款形态）。
+
+/** 切回边沿上下文（派发方 handler ctx 的结构化最小子集——本包不依赖 pi 类型，
+ *  与 ExtensionCommandContext.sessionManager 结构兼容；getEntries / getSessionFile /
+ *  getSessionId 三成员即两域对账 deps 的全部 ctx 侧输入）。 */
+export interface ResumeReconcileContext { // oe-exempt:20261102:framework:跨扩展契约接口（delivery-port 定义、两消费域结构兼容锚，非单实现抽象）
+	sessionManager: {
+		getEntries(): readonly unknown[];
+		getSessionFile(): string | undefined;
+		getSessionId(): string;
+	};
+}
+
+/** 域订阅回调（切回边沿 → 该域对账编排；域侧自带围栏——对账编排内部全量
+ *  catch，失败 warn 留痕后下一对账边沿幂等重查，异常原则上不向派发方传播，
+ *  本侧围栏只兜「域侧围栏漏网」的防御位）。 */
+export type ResumeReconcileListener = (ctx: ResumeReconcileContext) => void;
+
+/** 进程级槽键（C-ext-06：Symbol.for + globalThis，防 jiti 多实例槽分裂）。 */
+export const RESUME_RECONCILE_SLOT_KEY = Symbol.for(
+	"@zhushanwen/pi-delivery-port.resumeReconcile",
+);
+
+type ResumeReconcileSlot = { listeners: Map<string, ResumeReconcileListener> };
+
+function getSlot(): ResumeReconcileSlot {
+	// globalThis 无 symbol 索引签名，Reflect 安全读写（delivery-port.ts getSlot 同款）
+	let slot = Reflect.get(globalThis, RESUME_RECONCILE_SLOT_KEY) as
+		| ResumeReconcileSlot
+		| undefined;
+	if (!slot) {
+		slot = { listeners: new Map() };
+		Reflect.set(globalThis, RESUME_RECONCILE_SLOT_KEY, slot);
+	}
+	return slot;
+}
+
+/**
+ * 域订阅（extension load 装配期调用；同域重复订阅覆盖前值——reload 后新闭包
+ * 覆盖旧闭包，防 stale pi 转发）。domain = 域名单（如 "session-manager" /
+ * "subagent-workflow"），仅作槽内键与失败报告的归因标签。
+ */
+export function subscribeResumeReconcile(
+	domain: string,
+	listener: ResumeReconcileListener,
+): void {
+	getSlot().listeners.set(domain, listener);
+}
+
+/**
+ * 切回边沿派发（`__taiji_bg_reconcile__` handler 调用）：逐域同步调用，单个
+ * listener 异常不阻断其余域；失败逐域收集返回，由派发方 warn 留痕（本包无
+ * logger 依赖——错误语义不吞：返回清单即报告通道）。无订阅（两域扩展未启用 /
+ * 装配前）= 空清单，缺席语义非错误（与 SubagentService 单例缺席语义同族）。
+ */
+export function dispatchResumeReconcile(
+	ctx: ResumeReconcileContext,
+): Array<{ domain: string; error: unknown }> {
+	const failures: Array<{ domain: string; error: unknown }> = [];
+	for (const [domain, listener] of getSlot().listeners) {
+		try {
+			listener(ctx);
+		} catch (err) {
+			failures.push({ domain, error: err });
+		}
+	}
+	return failures;
+}
+
+/** 测试隔离：清空全部域订阅（生产禁用——订阅生命周期与 extension load 一致）。 */
+export function _resetResumeReconcileForTest(): void {
+	getSlot().listeners.clear();
+}

package/src/reconcile-judgement.ts

@@ -0,0 +1,112 @@
+// src/reconcile-judgement.ts
+//
+// 对账补投判据的共享纯函数层（completion-signal-delivery D2 三重事实判据骨架 +
+// 投递日志幂等键提取）——无 I/O、无 pi 依赖。原角色载体 = base-tool-enhance
+// background/notify-reconcile-judgement.ts（u1 抽出的「跨域共享语义落点」）；
+// 判据链曾以「域侧同构落位 + 真值表测试逐行对拍」形态在 bash / session-manager /
+// subagent-workflow 三域各持物理副本（subagent-core 受 core ← extensions 依赖
+// 方向红线不能反向共享，第四域仍为同构落位——见 execution/notify/notify-reconcile.ts
+// 文件头），本文件是四域判据链收编进三方共同依赖包后的单源：骨架真值组合与幂等键
+// 提取各只此一份，域侧只留「域事实 → 布尔」映射，真值表测试随迁本包单点锁定
+// （reconcile-judgement.test.ts），域侧逐行对拍的人工同步义务退役。
+//
+// 域侧消费形态（调用方判定好的事实布尔进骨架；骨架零 I/O）：bash 域 =
+// pending-reconcile.ts registryFacts（registry 条目）；session-manager 域 =
+// notify-reconcile.ts 预检 + reconcileOneManagedCandidate；workflow 域 =
+// workflow-notify-reconcile.ts reconcileOneCandidate；subagent-core 域 = 世代
+// 匹配变体（本包不可达，同构锚定）。排除位语义随域参数化（「主路径不发者排除」
+// 原理，D5 裁决同源），判据演化不产生第二套真值组合。
+
+import {
+	ACK_CUSTOM_TYPE,
+	OUTBOX_CUSTOM_TYPE,
+	V1_ACK_CUSTOM_TYPE,
+	V1_OUTBOX_CUSTOM_TYPE,
+	mapV1OutboxData,
+	readAckId,
+	readOutboxDataV2,
+} from "./journal.ts";
+
+/** 三重事实判据的输入（调用方在域内完成事实源映射后传入；骨架零 I/O）。 */
+export interface ReconcileNotifyFacts { // oe-exempt:20261102:framework:port 契约层判据输入形状，域侧以对象字面量消费、无 implements 变体（四域判据链已收编本包单源）
+	/** 事实一：任务/记录已终态（域事实源判定——bash 域 = registry 终态枚举成员）。 */
+	isTerminal: boolean;
+	/**
+	 * 排除位（「主路径不发者排除」原理，D5 裁决同源）：主路径对该终态成因不发的
+	 * 通知，补投无从恢复也不该发。bash 域 = killed；u3 subagent 域 = cancelled 族
+	 * + workflow origin 整体排除；session-manager/workflow 域 = 静默注销类 /
+	 * 恒 false（主路径全终态发通知）。真 = 非候选。
+	 */
+	excludedByOrigin: boolean;
+	/** 事实二：送达痕迹命中（该键的完成通知消息已在会话 entries）。 */
+	delivered: boolean;
+	/**
+	 * 事实三：投递日志已含该幂等键条目（受理已发生）。有条目未送达 = 差集重放
+	 * （port.recover）的职责；已终局 = ack/凭据判据的职责——均非补投对象（D2
+	 * 采用段：补投只认「从未受理成功」形态，与重放职责不重叠）。
+	 */
+	journaled: boolean;
+}
+
+/**
+ * 三重事实判据骨架（D2）：终态 ∧ 未排除 ∧ 无送达痕迹 ∧ 投递日志无条目。
+ *
+ * 单源位（原 judgement.ts RL12 行为锁收编）：bash 域对账（isReapNotifyCandidate）
+ * 与三边沿入口（session_start / 切回 / agent_settled）经同一函数消费；session-
+ * manager / workflow 域终判循环复用同一真值组合——判据演化不产生第二套真值逻辑。
+ */
+export function isReconcileNotifyCandidate(facts: ReconcileNotifyFacts): boolean {
+	return facts.isTerminal && !facts.excludedByOrigin && !facts.delivered && !facts.journaled;
+}
+
+/**
+ * 从会话 entries 提取投递日志已登记的幂等键与承载键集（事实三的事实源）。outbox
+ * （受理落盘）与 ack/discard（终局列）v2/v1 四类 entry 兼容读。
+ *
+ * collectKey 键集展开（单源统一裁决——原 bash 域副本只收条目 id、session-manager/
+ * workflow 域副本带展开的分叉收敛）：主路径受理条目可按 collectKey 申报承载键
+ * （条目 id ≠ 业务幂等键的承载形态——workflow 域裸 runId、session-manager 域合批
+ * 成员键），只收 id 会漏「主路径成功受理」形态（误补投由 port 幂等预检吞并，多余
+ * 但无害；判据侧直接补齐）。展开是 id 收集的无损超集：多命中方向 = 漏补投（保守，
+ * 与「漏补投优于重复投」取向一致）；各域键词表不相交（bt- / run / managed notify
+ * 键形态互斥），跨域展开无误命中面。
+ *
+ * 解析复用本包 journal 单点（readOutboxDataV2 / mapV1OutboxData / readAckId），
+ * 宽容口径与 port scanJournal 一致：data 畸形按无条目——误判「无条目」的残余
+ * 风险由 port 幂等预检承接（重投被 swallowed 吞并，无实害）。
+ */
+export function collectJournaledDeliveryIds(entries: readonly unknown[]): Set<string> {
+	const ids = new Set<string>();
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as Record<string, unknown>;
+		if (entry["type"] !== "custom") continue;
+		switch (entry["customType"]) {
+			case OUTBOX_CUSTOM_TYPE: {
+				const record = readOutboxDataV2(entry["data"]);
+				if (record === undefined) break;
+				ids.add(record.id);
+				if (record.collectKey !== undefined) {
+					for (const key of record.collectKey) ids.add(key);
+				}
+				break;
+			}
+			case V1_OUTBOX_CUSTOM_TYPE: {
+				// v1 存量（旧通知账本）兼容读；scannedAt 只填 record.recordedAt 元数据，
+				// 本判据只取 id——传 0 保持纯函数无时钟依赖
+				const record = mapV1OutboxData(entry["data"], 0);
+				if (record !== undefined) ids.add(record.id);
+				break;
+			}
+			case ACK_CUSTOM_TYPE:
+			case V1_ACK_CUSTOM_TYPE: {
+				const id = readAckId(entry["data"]);
+				if (id !== undefined) ids.add(id);
+				break;
+			}
+			default:
+				break;
+		}
+	}
+	return ids;
+}

package/src/session-journal-read.ts

@@ -0,0 +1,95 @@
+// src/session-journal-read.ts
+//
+// session JSONL 落盘条目的磁盘读侧（对账补投判据事实源的共享读原语）——原角色
+// 载体 = 三域各自持有的同构副本（bash pending-reconcile.ts / session-manager
+// notify-reconcile.ts / subagent-workflow workflow-notify-reconcile.ts 的
+// readSessionFileEntries，近逐字同构、容错口径一致），随判据链收编进本包单源。
+// 机制动机（pi SessionManager._appendEntry 幽灵内存 entry 形态——persist 失败无
+// 回滚，内存账不可作判据事实源）的 pi 侧实锚登记 = docs/pi-semantics.json PS-97。
+// 域侧退化语义（no-persist 形态退化内存账 + warn）经 resolveReconcileFactEntries
+// 收编本文件单源（session-manager / workflow 两域消费；bash 域文案词序与其余两域
+// 不同，保持域内原样，登记在该域）。
+//
+// logger 归因：本包共享原语的 warn 走本包通道（getLogger("pi-delivery-port")），
+// 不按消费域归因（三域调用点零参数差异；读失败本身是共享原语事件，域归因由调用
+// 栈排障定位）。容错口径与 packages/subagent-core 的同构读原语
+// readSessionEntriesFromFile 互指登记见该函数头注（core 受 core ← extensions
+// 依赖方向红线不进本包；读错误 warn + [] 口径两侧一致，warn 文本同串——
+// ENOENT 静默空、脏行跳过亦同；差异仅 logger 通道归因）。
+
+import { readFileSync } from "node:fs";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
+
+const logger = getLogger("pi-delivery-port");
+
+/** 脏行 warn 留痕的截断长度（taste/no-magic-numbers 抽常量）。 */
+const DIRTY_LINE_SNIPPET_LEN = 120;
+
+/**
+ * 读 session JSONL 文件的落盘条目（判据事实源的磁盘读侧）。pi _persist 落盘形态
+ * = 每条 entry 一行 JSON.stringify，逐行 parse 产出与 getEntries() 同构的条目数组。
+ *
+ * 容错口径（与 collectJournaledDeliveryIds「data 畸形按无条目」宽容口径同源）：
+ *  - ENOENT → []：session 首条对话消息前文件不存在（pi _persist 首次 flush 前置
+ *    条件，PS-97 :797-799 未 flush 无对话早退），常态非异常；
+ *  - 其他读错误（EACCES 等）→ warn + []：磁盘事实不可得按「无条目」，候选源与
+ *    抵消事实同按空（保守 miss + warn 修复信号——按内存账退化则会沿幽灵态静默
+ *    吞补投，即 A1 缺陷形态本身）；
+ *  - 脏行（JSON.parse 失败 / 非对象）单行跳过（JSONL 容错纪律，protocol
+ *    pending-entries 扫描同款）。
+ */
+export function readSessionFileEntries(sessionFile: string): unknown[] {
+	let text: string;
+	try {
+		text = readFileSync(sessionFile, "utf8");
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException | null)?.code === "ENOENT") return [];
+		logger.warn("reconcile journal facts read failed; disk entries treated as empty (candidates retried at next reconcile edge)", {
+			detail: { sessionFile, err: toErrorMessage(err) },
+		});
+		return [];
+	}
+	const entries: unknown[] = [];
+	for (const line of text.split("\n")) {
+		if (line.trim() === "") continue;
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (parsed !== null && typeof parsed === "object") entries.push(parsed);
+		} catch (e) {
+			// 脏行跳过：单行损坏不拖垮整盘事实；warn 留痕（taste/no-silent-catch）
+			logger.warn("session JSONL 脏行跳过（对账事实按其余行继续）", {
+				detail: { line: line.slice(0, DIRTY_LINE_SNIPPET_LEN), error: toErrorMessage(e) },
+			});
+		}
+	}
+	return entries;
+}
+
+/**
+ * 对账事实源解析（session-manager / workflow 两域对账编排共用的 no-persist 退化
+ * 形态单源）：sessionFile 在场 = 读磁盘落盘条目（readSessionFileEntries）；缺席
+ * （no-persist 形态，磁盘事实结构性不存在）退化内存 entries + warn——该形态
+ * _persist no-op 恒成功、无幽灵态，内存账即完整事实。warn 文案 domain 段参数化
+ * （域标签进文案首位，子串 "fell back to in-memory entries" 为两域测试的共享断言锚）。
+ */
+export function resolveReconcileFactEntries(opts: {
+	/** 域标签（warn 文案归因段：如 "managed notify reconcile" / "workflow notify reconcile"）。 */
+	domain: string;
+	/** 入口来源（warn detail 透传——入口来源日志可辨）。 */
+	reason: string;
+	/** 当前 session entries（内存账——退化事实源）。 */
+	entries: readonly unknown[];
+	/** 当前 session JSONL 路径；undefined = no-persist 形态。 */
+	sessionFile?: string;
+}): readonly unknown[] {
+	if (opts.sessionFile !== undefined) return readSessionFileEntries(opts.sessionFile);
+	logger.warn(
+		`${opts.domain} journal facts fell back to in-memory entries: session file unavailable (no-persist session?); ghost in-memory entries would misjudge delivered/journaled facts`,
+		{
+			detail: { reason: opts.reason },
+		},
+	);
+	return opts.entries;
+}

package/src/types.ts

@@ -1,6 +1,6 @@
 // src/types.ts
 //
-// @zhushanwen/pi-delivery-port 契约面（设计 .tmp/tech-design/unified-delivery.md
+// @zhushanwen/pi-delivery-port 契约（设计 .tmp/tech-design/unified-delivery.md
 // §3.7 pi 半区组件表 / §3.4 提交选项缺省值表）。
 //
 // 本包是「知 pi 又知内核」的适配层：把 pi 扩展运行时
@@ -69,7 +69,7 @@ export interface DeliveryDeliverOptions { // oe-exempt:20261017:framework:统一
  */
 export type DeliveryDeliverResult =
   | { kind: "accepted"; id: string }
-  | { kind: "swallowed"; reason: "already-seen" | "duplicate-content" }
+  | { kind: "swallowed"; reason: "already-seen" }
   | { kind: "rejected"; reason: string };
 
 // ─── collect 面（批量收取；result-collect 设计 §3.1②③）──────
@@ -136,7 +136,7 @@ export interface DeliveryPortMetrics { // oe-exempt:20261017:framework:分桶诊
 
 // ─── host 端口（装配点接线点）───────────────────────────────
 
-/** host logger 最小面（@zhushanwen/pi-extension-logger 的 ExtensionLogger 结构性满足）。 */
+/** host logger 最小接口（@zhushanwen/pi-extension-logger 的 ExtensionLogger 结构性满足）。 */
 export interface DeliveryPortLogger { // oe-exempt:20261017:framework:日志注入契约（宿主提供实现）
   warn(msg: string, data?: unknown): void;
   debug(msg: string, data?: unknown): void;
@@ -146,10 +146,10 @@ export interface DeliveryPortLogger { // oe-exempt:20261017:framework:日志注
  * port 宿主最小端口面（session_start 装配点经 createPiDeliveryPortHost 接线；
  * 接口化解耦便于测试，内核/端口本体零 pi import）。
  *
- * 订阅面全部返回退订函数（pi 1.0.0 起 on 返回 unsubscribe；port dispose 时兑现，
+ * 订阅类端口全部返回退订函数（pi 1.0.0 起 on 返回 unsubscribe；port dispose 时兑现，
  * 防 session_start 重绑累积死 handler）。
  */
-export interface DeliveryPortHost { // oe-exempt:20261017:framework:pi 能力注入契约（sendMessage/appendEntry/on 事件宿主面）
+export interface DeliveryPortHost { // oe-exempt:20261017:framework:pi 能力注入契约（sendMessage/appendEntry/on 事件宿主接口）
   /** 写 plain custom entry（outbox / ack 通道；pi.appendEntry——不进 LLM 上下文）。 */
   appendEntry(customType: string, data: unknown): void;
   /** 读当前 session 全部 entry（回执扫描 / 重放扫描；ctx.sessionManager.getEntries()）。 */
@@ -217,7 +217,16 @@ export interface DeliveryPortHandle { // oe-exempt:20261017:framework:进程级
   /** 销毁：内核 dispose + 退订全部事件订阅 + 摘进程级槽绑定。 */
   dispose(): void;
   /**
-   * collect 面（result-collect 设计 §3.1② 端口挂起面，方法语义以该节为准）。
+   * 重绑交接面（bindDeliveryPort 专用消费，dispose 前调用）：返回本实例内核
+   * in-flight（已交递 pi，注入由 pi 侧异步完成）的已受理 id 快照。后继实例把集合
+   * 作为 predecessorInFlightIds 预占——差集重放对这批 id 跳过（消息已在途，重放
+   * 构成同条通知双投，A4 真机实证）；跨进程重启无前驱可交接，崩溃恢复通道不变。
+   * queued / failed（未出站或出站失败——dispose 丢弃）不在集合内，后继重放恢复
+   * 语义不变。
+   */
+  takeInFlightHandoff?(): ReadonlySet<string>;
+  /**
+   * collect 面（result-collect 设计 §3.1② 端口挂起行为，方法语义以该节为准）。
    * collectArm：同步段登记在途等待集 + 对每个 key 按五态判据定态（快照形态
    * CollectSnapshotEntry——unknown 态键不登记等待集，由消费方组装 errors）。
    */