@zhushanwen/pi-base-tool-enhance 0.9.0 → 0.10.1

package/README.md

@@ -1,8 +1,8 @@
 # @zhushanwen/pi-base-tool-enhance
 
-同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。能力面：测试类命令 force-test 白名单命中自动转后台（模式登记于 force-patterns.ts）、前台挂死保护（可配置前台默认超时，对一切未显式填 timeout 的前台命令生效——典型挂死场景是网络类命令）、工具报错审计（tool_error 审计 hook，entry customType 为 `unified-hooks:tool-error`）。
+同名 override pi 内置 bash 工具的增强层：前台行为 100% 委托 pi 官方工厂（`createBashToolDefinition`），增量提供 background 模式、强制后台白名单与双模式可配置超时。能力侧：测试类命令 force-test 白名单命中自动转后台（模式登记于 force-patterns.ts）、前台挂死保护（可配置前台默认超时，对一切未显式填 timeout 的前台命令生效——典型挂死场景是网络类命令）、工具报错审计（tool_error 审计 hook，entry customType 为 `unified-hooks:tool-error`）。
 
-设计决策沉淀在包内源码注释与本文档。
+设计决策记录在案于包内源码注释与本文档。
 
 ## 安装
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design decisions documented in source comments)",
   "type": "module",
   "main": "src/index.ts",
@@ -28,11 +28,12 @@
     "skills/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.23.0",
+    "@zhushanwen/pi-delivery-port": "0.2.1",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/pi-file-lock": "0.4.1",
-    "@zhushanwen/pi-llm-shared": "0.11.3"
+    "@zhushanwen/pi-llm-shared": "0.12.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -42,7 +43,7 @@
     "@earendil-works/pi-coding-agent": "^1.0.0",
     "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27",
-    "@zhushanwen/pi-pending-notifications": "0.9.0"
+    "@zhushanwen/pi-pending-notifications": "0.10.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {

package/skills/base-tool-enhance-ext-config/SKILL.md

@@ -61,7 +61,7 @@ description: "使用或排查 @zhushanwen/pi-base-tool-enhance 的 bash 后台/
 
 用户正则**自动加命令位置锚定前缀**（`CMD_ANCHOR`：行首，或 `;` / `&&` / `||` / `|` / 换行之后的命令起始位，后随可选空白）——与内置条目统一匹配语义：
 
-- **无需也不应自带 `^`**：写 `pnpm\s+typecheck` 即可。自带 `^` 反而收窄匹配（`^` 只钉死整条命令第一段，`cmd1 && pnpm typecheck` 中的第二段就匹配不到了）。
+- **无需也不应自带 `^`**：写 `pnpm\s+typecheck` 即可。自带 `^` 反而收窄匹配（`^` 只固定整条命令第一段，`cmd1 && pnpm typecheck` 中的第二段就匹配不到了）。
 - **不做裸子串匹配（防误伤）**：参数文本里的命令词不会命中——`git commit -m "fix: npm test"` 不触发后台（unified-hooks 时代的 `\s` 前缀会误伤，本包已收紧为命令位置锚定）。
 - **wrapper 局限（漏报方向）**：`sudo npm test` / `timeout 300 npm test` / `xargs npm test` 这类 wrapper 形态不命中（wrapper 名占命令位置）。漏报无害——force 命中本就是非破坏性的，模型可显式传 `background: true` 兜底。
 

package/src/__tests__/background-lifecycle.test.ts

@@ -11,12 +11,8 @@ import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from "vites
 vi.setConfig({ testTimeout: 20000 });
 
 // getAgentDir → 测试临时数据目录（工具 execute 内部调用，不写真 ~/.pi/agent）。
-// hoisted 回调里不能引用顶层 import（初始化顺序），用可变引用在 import 完成后注入
-const { dataDirRef } = vi.hoisted(() => ({ dataDirRef: { dir: "" } }));
-vi.mock("@earendil-works/pi-coding-agent", () => ({
-	getAgentDir: () => dataDirRef.dir,
-}));
-
+// [session-store-layout-inversion 域 5] 工具的 dataDir 来源已换为 resolveTaijiDataDir()
+// （env 注入）——getAgentDir mock 随换根退役，改 beforeEach stubEnv + afterEach 还原。
 // 进程原语（ext-simplify-13 后单点在 protocol 子出口）转发真实杀 + 记录调用
 //（timeout 分支断言 killProcessTree 被调）
 const { killTreeCalls } = vi.hoisted(() => ({ killTreeCalls: [] as number[] }));
@@ -46,11 +42,15 @@ import { clearTaskStoreForTest, getActiveTasks, getTask, markKillingIntent } fro
 import { reapBackgroundTasksNow, resetProcessExitGuardForTest } from "../background/process-exit-guard.ts";
 
 const DATA_DIR = mkdtempSync(join(tmpdir(), "bte-data-"));
-dataDirRef.dir = DATA_DIR;
 
 const SESSION_ID = "sess-lifecycle";
 const REGISTRY_PATH = getRegistryPath(DATA_DIR, SESSION_ID);
 
+beforeEach(() => {
+	// 工具 execute 的 dataDir 来源 = resolveTaijiDataDir()（env，域 5 换根）
+	vi.stubEnv("TAIJI_AGENT_DATA_DIR", DATA_DIR);
+});
+
 function makeCtx(sessionId: string = SESSION_ID): { cwd: string; sessionManager: { getSessionId: () => string } } {
 	return { cwd: process.cwd(), sessionManager: { getSessionId: () => sessionId } };
 }
@@ -124,6 +124,8 @@ beforeEach(() => {
 });
 
 afterEach(() => {
+	// env stub 逐用例还原（防同 worker 跨文件残留）
+	vi.unstubAllEnvs();
 	// 残留活跃任务先杀干净再清表（防句柄/进程泄漏影响后续测试）
 	for (const task of getActiveTasks()) {
 		try {

package/src/__tests__/bash-tool.test.ts

@@ -6,7 +6,7 @@ import { join } from "node:path";
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
-// mock pi 官方工厂：前台行为是委托（方案 B），测试断言「透传面」而非真实 spawn
+// mock pi 官方工厂：前台行为是委托（方案 B），测试断言「透传侧」而非真实 spawn
 // 行为——真实行为由 pi 上游保证 + 探针 P2 实测。
 const { createBashToolDefinitionMock, officialExecuteMock, agentDirRef } = vi.hoisted(() => ({
 	createBashToolDefinitionMock: vi.fn(),
@@ -68,6 +68,8 @@ afterEach(() => {
 	}
 	agentDirRef.dir = "/tmp/bte-fake-agent-dir";
 	clearConfigCache();
+	// background 分支的 dataDir 来源是 env（resolveTaijiDataDir），逐用例 stub 后在此还原
+	vi.unstubAllEnvs();
 });
 
 function createOfficialFactoryResult(cwd: string) {
@@ -166,7 +168,7 @@ describe("createBashOverrideToolDefinition", () => {
 		const tool = createBashOverrideToolDefinition();
 		// 引用级相等证明 delegate 的 render 闭包原样透传（未覆写未丢弃）——官方
 		// renderCall（命令格式化）/ renderResult（elapsed 计时/富结果组件）是 TUI
-		// 渲染面，独立 pi 用户安装本包后不降级为通用组件
+		// 渲染范围，独立 pi 用户安装本包后不降级为通用组件
 		expect(tool.renderCall).toBe(renderCall);
 		expect(tool.renderResult).toBe(renderResult);
 	});
@@ -245,6 +247,9 @@ describe("createBashOverrideToolDefinition", () => {
 describe("background branch routing (M2)", () => {
 	it("background:true routes to spawnBackgroundTask with ctx-derived paths and returns task_id message", async () => {
 		setupFactory();
+		// dataDir 来源 = resolveTaijiDataDir()（env 注入，session-store-layout-inversion 域 5）；
+		// 断言值与 stub 值同字面（getAgentDir mock 已随换根退役）
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", "/tmp/bte-fake-agent-dir");
 		spawnBackgroundTaskMock.mockReturnValue({
 			ok: true,
 			task: {

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

@@ -0,0 +1,145 @@
+// src/__tests__/delivery-port-assembly.test.ts —— 统一投递端口装配点行为锁
+//（unified-delivery 波 2 前半，设计 §3.7 装配点：base-tool-enhance 的 session_start）。
+// 锁三类装配行为：
+// ① session_start 触发端口装配且经进程级槽可达（getDeliveryPort）；
+// ② 装配后端口是活的投递通路（deliver → pi.appendEntry outbox + pi.sendMessage
+//   直达唯一队列——用真 deliver 链验证 host 接线正确，非仅槽非空）；
+// ③ 重复 session_start 重绑（旧实例 dispose 拒收）+ 差集重放触发。
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { createBashToolDefinitionMock, dataDirRef } = vi.hoisted(() => ({
+	createBashToolDefinitionMock: vi.fn(),
+	dataDirRef: { dir: "/tmp/bte-fake-agent-dir-delivery-port" },
+}));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+	createBashToolDefinition: createBashToolDefinitionMock,
+	getAgentDir: () => dataDirRef.dir,
+}));
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { _resetDeliveryPortForTest, getDeliveryPort } from "@zhushanwen/pi-delivery-port";
+import { resetNotifyForTest } from "../background/notify.ts";
+import { clearTaskStoreForTest } from "../background/task-store.ts";
+import baseToolEnhanceExtension from "../index.ts";
+
+function setupOfficialFactory(): void {
+	// bash 同名 override 依赖官方工厂 mock（index.test.ts setupOfficialFactory 同款）；
+	// 本文件只走 session_start 链，工厂 mock 仅为 registerTool 路径不炸。
+	createBashToolDefinitionMock.mockReset();
+	createBashToolDefinitionMock.mockReturnValue({
+		name: "bash",
+		label: "bash",
+		description: "official",
+		parameters: {},
+		execute: vi.fn(),
+	});
+}
+
+function createMockPi(entries: unknown[] = []) {
+	return {
+		registerTool: vi.fn(),
+		registerCommand: vi.fn(),
+		// pi 1.0.0 契约：on 返回退订函数（types.d.ts `): () => void`）——port dispose 兑现
+		on: vi.fn(() => () => {}),
+		// appendEntry 落 entries（真 pi 持久化 session JSONL 的 mock 对应——重放扫描读它）
+		appendEntry: vi.fn((customType: string, data: unknown) => {
+			entries.push({ type: "custom", customType, data });
+		}),
+		events: { emit: vi.fn(), on: vi.fn() },
+		sendMessage: vi.fn(),
+	};
+}
+
+function createMockCtx(entries: unknown[]): ExtensionContext {
+	return {
+		mode: "rpc",
+		sessionManager: {
+			getSessionId: () => "sess-1",
+			getEntries: () => entries,
+		},
+		isIdle: () => true,
+	} as unknown as ExtensionContext;
+}
+
+/** 从 mock pi 提取 session_start handler 并触发（startup reason）。 */
+function fireSessionStart(pi: ReturnType<typeof createMockPi>, ctx: ExtensionContext): void {
+	const call = pi.on.mock.calls.find((c) => c[0] === "session_start");
+	expect(call).toBeDefined();
+	(call![1] as (event: unknown, ctx: ExtensionContext) => unknown)(
+		{ type: "session_start", reason: "startup" },
+		ctx,
+	);
+}
+
+describe("session_start 装配统一投递端口（unified-delivery §3.7）", () => {
+	it("session_start 后端口经进程级槽可达", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+		expect(getDeliveryPort()).toBeUndefined(); // 装配前缺席
+
+		fireSessionStart(pi, createMockCtx([]));
+		expect(getDeliveryPort()).toBeDefined(); // 装配后可达
+		_resetDeliveryPortForTest();
+	});
+
+	it("装配的端口是活的投递通路：deliver 落 outbox + sendMessage 直达唯一队列", () => {
+		setupOfficialFactory();
+		const pi = createMockPi();
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+		fireSessionStart(pi, createMockCtx([]));
+
+		const port = getDeliveryPort()!;
+		const receipt = port.deliver({
+			id: "task-1:0",
+			payload: { kind: "custom", customType: "workflow-result", content: "workflow done", display: true, details: { runId: "r-1" } },
+		});
+		expect(receipt).toEqual({ kind: "accepted", id: "task-1:0" });
+		// 受理前落盘（经 pi.appendEntry 接线）
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"delivery-port-outbox",
+			expect.objectContaining({ v: 2, id: "task-1:0", timing: "steer" }),
+		);
+		// 直达唯一队列（经 pi.sendMessage 接线，deliveryId 注入前写入 details）
+		expect(pi.sendMessage).toHaveBeenCalledWith(
+			expect.objectContaining({
+				customType: "workflow-result",
+				details: expect.objectContaining({ deliveryId: "task-1:0" }),
+			}),
+			{ deliverAs: "steer", triggerTurn: true },
+		);
+		_resetDeliveryPortForTest();
+	});
+
+	it("重复 session_start 重绑：旧实例 dispose（deliver 拒收）、新实例差集重放", () => {
+		setupOfficialFactory();
+		const entries: unknown[] = [];
+		const pi = createMockPi(entries);
+		baseToolEnhanceExtension(pi as unknown as ExtensionAPI);
+		fireSessionStart(pi, createMockCtx(entries));
+
+		const first = getDeliveryPort()!;
+		// 落一条账（已注入未送达——无 custom_message entry 无 ack，差集合法重投）
+		first.deliver({ id: "w-1", payload: { kind: "custom", customType: "workflow-result", content: "x", display: true } });
+		(pi.sendMessage as ReturnType<typeof vi.fn>).mockClear();
+
+		// 新 session_start（同 entries——同 session 文件语义）：重绑 + recover
+		fireSessionStart(pi, createMockCtx(entries));
+		const second = getDeliveryPort()!;
+		expect(second).not.toBe(first);
+		expect(first.deliver({ id: "w-2", payload: { kind: "custom", customType: "workflow-result", content: "y", display: true } }).kind).toBe("rejected");
+		// 差集重放：w-1 未送达未处理完毕 → 重投（经新实例 sendMessage）
+		expect(pi.sendMessage).toHaveBeenCalledWith(
+			expect.objectContaining({ customType: "workflow-result", details: expect.objectContaining({ deliveryId: "w-1" }) }),
+			expect.anything(),
+		);
+		_resetDeliveryPortForTest();
+	});
+});
+
+afterEach(() => {
+	_resetDeliveryPortForTest();
+	resetNotifyForTest();
+	clearTaskStoreForTest();
+});

package/src/__tests__/index.test.ts

@@ -12,7 +12,6 @@ const { createBashToolDefinitionMock, dataDirRef } = vi.hoisted(() => ({
 }));
 vi.mock("@earendil-works/pi-coding-agent", () => ({
 	createBashToolDefinition: createBashToolDefinitionMock,
-	getAgentDir: () => dataDirRef.dir,
 }));
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -91,12 +90,14 @@ describe("baseToolEnhanceExtension entry", () => {
 	});
 });
 
-describe("__taiji_bg_reconcile__ command: runtime-resume trigger face (bg-task-notify-durability)", () => {
+describe("__taiji_bg_reconcile__ command: runtime-resume trigger face", () => {
 	it("handler runs the same maintenance chain as session_start (zombie settle via appendEntry on the SAME pi reference)", async () => {
 		setupOfficialFactory();
-		// 独立临时 dataDir（同 session_start 用例：维护链只读不扫），registry 预置终态僵尸条目
+		// 独立临时 dataDir（同 session_start 用例：维护链只读不扫），registry 预置终态僵尸条目。
+		// 维护链 dataDir 来源 = resolveTaijiDataDir()（env，session-store-layout-inversion 域 5）
 		const dataDir = mkdtempSync(join(tmpdir(), "bte-bgcmd-"));
 		dataDirRef.dir = dataDir;
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", dataDir);
 		try {
 			const sessionId = "sess-bgcmd";
 			writeRegistryEntry(getRegistryPath(dataDir, sessionId), {
@@ -138,6 +139,7 @@ describe("__taiji_bg_reconcile__ command: runtime-resume trigger face (bg-task-n
 		} finally {
 			rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 			dataDirRef.dir = "/tmp/bte-fake-agent-dir";
+			vi.unstubAllEnvs();
 			resetNotifyForTest();
 		}
 	});
@@ -146,9 +148,11 @@ describe("__taiji_bg_reconcile__ command: runtime-resume trigger face (bg-task-n
 describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-remove)", () => {
 	it("settles a zombie register via appendEntry on the SAME pi reference", async () => {
 		setupOfficialFactory();
-		// 独立临时 dataDir（维护链只读不扫：收殓已下沉 runtime），registry 预置终态僵尸条目
+		// 独立临时 dataDir（维护链只读不扫：收殓已下沉 runtime），registry 预置终态僵尸条目。
+		// 维护链 dataDir 来源 = resolveTaijiDataDir()（env，session-store-layout-inversion 域 5）
 		const dataDir = mkdtempSync(join(tmpdir(), "bte-index-"));
 		dataDirRef.dir = dataDir;
+		vi.stubEnv("TAIJI_AGENT_DATA_DIR", dataDir);
 		try {
 			const sessionId = "sess-index";
 			writeRegistryEntry(getRegistryPath(dataDir, sessionId), {
@@ -197,6 +201,7 @@ describe("session_start chain: reconcile (M3, reap sunk into runtime by u-bte-re
 		} finally {
 			rmSync(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
 			dataDirRef.dir = "/tmp/bte-fake-agent-dir";
+			vi.unstubAllEnvs();
 			resetNotifyForTest();
 		}
 	});

package/src/__tests__/maintenance-once.test.ts

@@ -3,17 +3,17 @@
 // reap 类操作不再执行）：
 //  - reconcilePendingEntries 是 session 级豁免类，每 session_start 派发都执行
 //    （startup/resume/new 多派发 ×N——含 factory 二调 handler 累积的真实形态）
-//  - 触发面消失：reaper.ts 模块文件已删除（文件级断言，见首条用例）+ 维护链不再触发
+//  - 触发点消失：reaper.ts 模块文件已删除（文件级断言，见首条用例）+ 维护链不再触发
 //    全局文件锁（原 reapOrphanedTasks 的 reaper.lock 路径随模块删除一并消失）
 //  - 入口无条件 debug 日志按派发次数出现，detail 仅含 reason（reapSkipped 字段
 //    随 reap 调用移除，S6 观测通道语义更新）
 // 断言方式：reconcile / logger 间谍注入观察调用次数与参数；file-lock 为 mock
-// 缺键守卫 + withFileLockSync throw 哨兵（不计数）。
+// 缺键检查 + withFileLockSync throw 哨兵（不计数）。
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { describe, expect, it, vi, beforeEach } from "vitest";
+import { describe, expect, it, vi, beforeEach, afterEach } from "vitest";
 
 const { reconcileMock, loggerMock, officialBashFactoryMock, dataDirRef } =
 	vi.hoisted(() => ({
@@ -25,12 +25,11 @@ const { reconcileMock, loggerMock, officialBashFactoryMock, dataDirRef } =
 
 vi.mock("@earendil-works/pi-coding-agent", () => ({
 	createBashToolDefinition: officialBashFactoryMock,
-	getAgentDir: () => dataDirRef.dir,
 }));
 vi.mock("@zhushanwen/pi-extension-logger", () => ({
 	getLogger: () => loggerMock,
 }));
-// 守卫形态 = mock 工厂缺键：包入口已删除的 async 锁导出不在工厂注册——维护链若
+// 检查形态 = mock 工厂缺键：包入口已删除的 async 锁导出不在工厂注册——维护链若
 // 误回流，对已删导出的任何访问（调用与 typeof 均计）即抛错（vitest mock 缺键语义；
 // 模块导入本身不抛）。withFileLockSync 哨兵保留：registry 写路径误入维护链即抛
 vi.mock("@zhushanwen/pi-file-lock", () => ({
@@ -47,10 +46,12 @@ import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-
 function createMockPi() {
 	return {
 		registerTool: vi.fn(),
-		// __taiji_bg_reconcile__ 第二触发面（runtime 切回补投）注册桩——本文件只验证
-		// session_start 入口，命令注册面断言在 index.test.ts
+		// __taiji_bg_reconcile__ 第二触发点（runtime 切回补投）注册桩——本文件只验证
+		// session_start 入口，命令注册点断言在 index.test.ts
 		registerCommand: vi.fn(),
-		on: vi.fn(),
+		// pi 1.0.0 契约：on 返回退订函数（delivery-port 装配在 session_start 重绑时
+		// dispose 旧实例兑现退订，mock 需符合真契约）
+		on: vi.fn(() => () => {}),
 		appendEntry: vi.fn(),
 		events: { emit: vi.fn(), on: vi.fn() },
 		sendMessage: vi.fn(),
@@ -60,7 +61,7 @@ function createMockPi() {
 function getSessionStartHandler(pi: ReturnType<typeof createMockPi>) {
 	const handler = pi.on.mock.calls.find((call) => call[0] === "session_start")?.[1];
 	expect(handler).toBeTypeOf("function");
-	// handler 返回 promise（补投 await sendMessage 使维护链 async 化，bg-task-notify-durability）
+	// handler 返回 promise（pi runner emit await handler 消费，维护链 async 形态——unified-delivery 波 3 口径）
 	return handler as (event: SessionStartEvent, ctx: unknown) => Promise<void>;
 }
 
@@ -80,6 +81,9 @@ async function loadExtension() {
 
 beforeEach(() => {
 	reconcileMock.mockReset();
+	// 维护链 dataDir 来源 = resolveTaijiDataDir()（env，session-store-layout-inversion 域 5）：
+	// getAgentDir mock 已随换根退役，改 stub env（dataDirRef.dir 仍是断言与 stub 的同一值源）
+	vi.stubEnv("TAIJI_AGENT_DATA_DIR", dataDirRef.dir);
 	// 官方 bash 工厂返回最小工具定义（override 定义 spread initial.name）
 	officialBashFactoryMock.mockReset();
 	officialBashFactoryMock.mockReturnValue({
@@ -94,11 +98,16 @@ beforeEach(() => {
 	loggerMock.error.mockClear();
 });
 
+afterEach(() => {
+	// env stub 逐用例还原（防同 worker 跨文件残留）
+	vi.unstubAllEnvs();
+});
+
 describe("session_start maintenance chain after reap sink (u-bte-remove)", () => {
 	it("no longer ships a reaper: the module is gone from the extension (trigger surface removed)", () => {
 		// 等价改写（fallow unresolved-import）：原断言动态 import 已删除模块期待
 		// rejects——静态分析无法理解故意性。模块文件不存在 ⟹ import 必 rejects，
-		// 蕴含成立，断言价值不变（触发面消失），文件级判定更直接。路径用 join 逐段
+		// 蕴含成立，断言价值不变（触发点消失），文件级判定更直接。路径用 join 逐段
 		// 拼装：fallow 会把 ../reaper.ts 形态的相对路径字符串按 import specifier 扫描
 		const reaperModulePath = join(dirname(fileURLToPath(import.meta.url)), "..", "reaper.ts");
 		expect(existsSync(reaperModulePath)).toBe(false);
@@ -120,7 +129,7 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 		expect(reconcileMock).toHaveBeenCalledTimes(3);
 		expect(reconcileMock).toHaveBeenNthCalledWith(1, expect.anything(), dataDirRef.dir, "sid-once", []);
 		expect(reconcileMock).toHaveBeenLastCalledWith(expect.anything(), dataDirRef.dir, "sid-once", []);
-		// 无全局扫描回流：误触发已删锁导出的任何访问会被 mock 缺键直接抛错（守卫见工厂注释），无告警
+		// 无全局扫描回流：误触发已删锁导出的任何访问会被 mock 缺键直接抛错（检查见工厂注释），无告警
 		expect(loggerMock.warn).not.toHaveBeenCalled();
 	});
 
@@ -147,7 +156,7 @@ describe("session_start maintenance chain after reap sink (u-bte-remove)", () =>
 	});
 
 	it("keeps reconcile failures non-fatal: handler promise resolves, warn logged", async () => {
-		// async 化后的非致命语义（bg-task-notify-durability U3 防假绿改写）：维护链已
+		// async 化后的非致命语义（unified-delivery 防假绿改写）：维护链已
 		// async——同步 not.toThrow() 断言恒真，改为显式断言「handler 的 promise resolve
 		//（错误在链内被 async 捕获，不向上传播成 unhandled rejection）+ warn 日志确实
 		// 记录」。两个断言缺一即红：吞掉后不打日志 = 观测丢失；打日志但 reject = fire

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

@@ -1,16 +1,13 @@
-// src/__tests__/notify-reconcile-judgement.test.ts —— 补投判据纯函数（设计 §5 U1）：
-// ① collectDeliveredTaskIds 五形态（正常消息/fork 副本/缺 details 旧消息/非 bash
-// 通知/killed 无痕迹任务）+ content 双落盘形态容错；② 补投标记 entry 读写形态
-// （customType background-bash:reconciled，data {taskId, reconciledAt}）
+// src/__tests__/notify-reconcile-judgement.test.ts —— 收殓终态补投的送达痕迹提取
+// （unified-delivery D3 裁决 1）：collectDeliveredTaskIds 五形态（正常消息/fork 副本/
+// 缺 details 旧消息/非 bash 通知/killed 无痕迹任务）+ content 双落盘形态容错。
+// 旧补投标记（background-bash:reconciled）随波 3 补投机制退役：防双投由 port 幂等
+// 接管，marker 判据/读写形态及其测试一并删除（反向锁见 pending-reconcile.test.ts
+// 「legacy reconciled marker present WITHOUT trace → still re-notified」用例）
 import { describe, expect, it } from "vitest";
 
 import { BACKGROUND_BASH_CUSTOM_TYPE } from "../background/notify.ts";
-import {
-	buildReconciledMarkerData,
-	collectDeliveredTaskIds,
-	collectReconciledTaskIds,
-	RECONCILED_MARKER_CUSTOM_TYPE,
-} from "../background/notify-reconcile-judgement.ts";
+import { collectDeliveredTaskIds } from "../background/notify-reconcile-judgement.ts";
 
 const TASK_ID = "bt-1700000000-abcd12";
 const OTHER_TASK_ID = "bt-1700000000-efgh34";
@@ -58,7 +55,7 @@ describe("collectDeliveredTaskIds: five entry shapes (design §5 U1)", () => {
 	it("non-bash notification (different customType, content mentions bt- token): does NOT hit", () => {
 		const ids = collectDeliveredTaskIds([
 			deliveredEntry({ customType: "subagent-bg-notify" }),
-			deliveredEntry({ customType: "background-bash:reconciled", details: undefined }),
+			deliveredEntry({ customType: "managed-session-notify", details: undefined }),
 		]);
 		expect(ids.size).toBe(0);
 	});
@@ -107,42 +104,3 @@ describe("collectDeliveredTaskIds: content落盘形态与脏数据容错", () =>
 		expect([...ids].sort()).toEqual([TASK_ID, OTHER_TASK_ID].sort());
 	});
 });
-
-describe("reconciled marker entry: write/read shape contract (design decision 1)", () => {
-	it("buildReconciledMarkerData produces {taskId, reconciledAt}", () => {
-		expect(buildReconciledMarkerData(TASK_ID, 1_700_000_000_000)).toEqual({
-			taskId: TASK_ID,
-			reconciledAt: 1_700_000_000_000,
-		});
-	});
-
-	it("marker customType is the plain-entry channel, distinct from the delivery customType", () => {
-		// 通道纪律：账务走 plain custom entry（appendEntry），送达消息走 sendMessage——
-		// 两者 customType 不得混用（NotifyLedger 同款纪律）
-		expect(RECONCILED_MARKER_CUSTOM_TYPE).toBe("background-bash:reconciled");
-		expect(RECONCILED_MARKER_CUSTOM_TYPE).not.toBe(BACKGROUND_BASH_CUSTOM_TYPE);
-	});
-
-	it("collectReconciledTaskIds picks marker entries and tolerates malformed data", () => {
-		const ids = collectReconciledTaskIds([
-			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: TASK_ID, reconciledAt: 1 } },
-			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE }, // data 缺失
-			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { reconciledAt: 2 } }, // taskId 缺
-			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: 42 } }, // 非字符串
-			{ type: "custom_message", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: OTHER_TASK_ID } }, // 误入消息通道的形态仍按 data 读
-			deliveredEntry(), // 送达消息不是标记
-			null,
-			7,
-		]);
-		expect([...ids].sort()).toEqual([TASK_ID, OTHER_TASK_ID].sort());
-	});
-
-	it("delivered and reconciled collectors partition the two anchors without cross-talk", () => {
-		const entries = [
-			deliveredEntry(), // TASK_ID 送达痕迹在
-			{ type: "custom", customType: RECONCILED_MARKER_CUSTOM_TYPE, data: { taskId: OTHER_TASK_ID, reconciledAt: 1 } },
-		];
-		expect(collectDeliveredTaskIds(entries).has(OTHER_TASK_ID)).toBe(false);
-		expect(collectReconciledTaskIds(entries).has(TASK_ID)).toBe(false);
-	});
-});