@zhushanwen/pi-session-manager 0.1.15 → 0.2.0

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@zhushanwen/pi-session-manager",
-  "version": "0.1.15",
+  "version": "0.2.0",
   "description": "Pi extension for managing agent-managed sessions — create, send, read history, list, status, abort via ctx.ui.select channel.",
   "type": "module",
   "main": "index.ts",
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "taiji": {
@@ -23,11 +26,15 @@
   "files": [
     "index.ts",
     "src/",
+    "skills/",
     "README.md"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.14.0",
-    "@zhushanwen/pi-extension-logger": "0.6.1"
+    "@zhushanwen/extension-protocol": "0.16.0",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
+    "@zhushanwen/pi-extension-logger": "0.6.1",
+    "@zhushanwen/pi-notify-ledger-host": "0.2.0",
+    "@zhushanwen/subagent-core": "0.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

package/skills/session-manager-ext-config/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: session-manager-ext-config
+description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed session 六工具与完成通知）时加载。说明完成通知链（notifyId → watch 长挂通道 → managed-session-notify 送达）、B-ledger 账本存储（session 文件自定义 entry + session_start 重装恢复 + session_compact 补写）、pending 列表 type 'session' 条目的生命周期、willNotify 与 fulfills 合并语义、lifetimeNotifyId 死亡通知、未收到通知与 pending 残留的排查入口。触发词：session-manager、managed session、create_managed_session、send_to_session、完成通知没收到、通知未送达、notifyId、pending 列表有 session 条目、B-ledger、managed-session-notify、willNotify、session-manager-ext-config。"
+---
+
+# session-manager 使用与排查指南
+
+> @zhushanwen/pi-session-manager：agent-managed session 扩展。父 session 通过 6 个工具
+> （create_managed_session / send_to_session / read_session_history / list_my_sessions /
+> get_session_status / abort_session）以子 session 形态并行工作。本指南讲完成通知链、
+> 账本存储与排查入口；工具契约细节（marker 通道 / 超时分档）见包 README。
+
+## 重要前提
+
+- 工具应答端是 taiji runtime 的 SessionManagerHandler——**只在 taiji 桌面环境可用**；
+  独立 pi CLI 无 handler 应答，所有工具等待至超时后报 `cancelled or timed out`。
+  工具失败时先确认运行环境，不要怀疑参数。
+- 本扩展不读磁盘配置文件，无 config JSON——通知状态全部存储在 pi session 文件内
+  （见 B-ledger 一节），没有「改配置文件」这条路径。
+
+## 完成通知链（notifyId → watch → managed-session-notify）
+
+一次带完成通知的工作流分四步：
+
+1. **生成债权**：`create_managed_session` 带 `prompt` 时（或每次 `send_to_session`）生成一个
+   notifyId（`sm-` 前缀 + UUID）。runtime 返回 `willNotify: true` 表示该次调用已受理一笔
+   完成通知债权；`willNotify: false`（create 不带 prompt）不产生通知。
+2. **arm**：工具结果成功后扩展做两件事——emit `pending:register`（{id = notifyId,
+   type: 'session', name = label}，由 pending-notifications 扩展消费落 pending 列表）+
+   开 watch（fire-and-forget，不传 timeout，长挂等待 runtime 应答）。
+3. **watch 应答**：子 session 完成/死亡后 runtime 经 watch 通道回一条应答，reason 词表：
+   `completed` / `failed` / `stopped`（结果新闻）、`exited` / `deleted`（死亡新闻）、
+   `cancelled` / `orphaned`（静默注销，不产出通知）。应答经 50ms trailing debounce 攒批：
+   分拣键 (sessionId, reason)，批身份 settleSeq/deathSeq——同一批合并为一条通知。
+4. **record + 送达**：攒批结果经 B-ledger record 落账（见下节），送达为单通道
+   `pi.sendMessage({triggerTurn: true})`——只在主 session 空闲时刻投递（agent_settled
+   边沿复查 isIdle + 120s 看门狗兜底），送达回执按 notifyId 匹配销账（ack entry）。
+
+通知文案形态：`Managed session "<label>" (<sessionId>) finished with status "<status>"
+(exit code: N). (fulfills N request(s))`；stderr 非空时附 Stderr tail（400 字截尾）；
+runtime 查得到时附 `Full transcript: <sessionFilePath>` 指针行。
+
+**合并与数量语义**：
+
+- 多条 queued 消息在同一轮消费合并为一次通知（fulfills N = 本批兑现笔数）；
+- `create_managed_session` 还返回 `lifetimeNotifyId`：session 终局死亡（exited/deleted）
+  恒产出一次死亡通知，与结果通知相互独立；
+- 每 notifyId 至多一条通知（record 幂等去重），重放不重复发声。
+
+## B-ledger 账本存储
+
+通知落账与恢复不依赖独立磁盘文件，复用 pi session 文件本身：
+
+- **record = session 文件自定义 entry**：通知落账走 `pi.appendEntry` 写入 session 文件
+  （plain custom entry，不进 LLM 上下文），先落盘后投递——进程崩溃后债权不丢。
+- **session_start 重装恢复**：每次 session_start 无条件 bind ledger host +
+  recoverFromSession——吸收 session 文件全部既有账本/回执条目重建内存态（重启重放），
+  按 notifyId 幂等去重：未销账债权重新投递，已销账静默。
+- **session_compact 补写**：compaction 清掉账本/回执 entry 时按内存态补写
+  （compactionCheck），账本不因压缩丢账。
+- ledger 实体在 `@zhushanwen/subagent-core`（Symbol.for 进程级单例槽），与
+  subagent-workflow 的通知账本共享同一实体——两个扩展共存时按 bind 收敛语义合并为
+  单实例，互不重复投递。
+
+## 排查入口
+
+| 症状 | 排查路径 |
+|------|---------|
+| 未收到完成通知 | ① 确认 taiji 桌面环境（standalone pi CLI 无 handler，工具本身就会超时）；② 查扩展日志 `<agentDir>/logs/session-manager-YYYY-MM-DD.log`（agentDir = pi `getAgentDir()`，默认 `~/.pi/agent`，taiji 隔离环境 `~/.taiji/agent`）搜 `[session-manager]`——`notify ledger not bound`（session_start 未跑/装配失败，通知丢弃，下次 session_start 重试装配）、`watch select rejected`（watch 通道被拒）、`watch respond unusable/malformed`（runtime 应答不可解析，协议漂移信号）；③ 日志干净则确认子 session 是否真完成（get_session_status） |
+| pending 列表残留 type 'session' 条目 | register 由 send/create 带 prompt 的 arm 写入，正常由 watch 应答逐条 unregister。残留 = watch 应答未达（pi 进程被杀 / runtime 重启 / 通道折叠 cancelled）；这些活跃 register 由下次 session_start 收口腿逐条重开 watch（入参 = entry id 即 notifyId），应答到达即静默注销，无需手工处理 |
+| 同一完成重复通知 | 不应发生——record 按 notifyId 幂等、死亡槽 (sessionId, deathSeq) 同键只发首条。若复现即协议漂移，查扩展日志 `record failed` / `malformed` 留痕归因 |
+
+## 工具速查
+
+| 工具 | 说明 |
+|------|------|
+| `create_managed_session` | 创建子 session（cwd 必填；可选 label；可选 prompt 原子 create+send） |
+| `send_to_session` | 向子 session 发 prompt（忙时排队，`queued: true` 立即返回） |
+| `read_session_history` | 读子 session 对话历史（可选 tailTurns 截尾部 N 个 turn） |
+| `list_my_sessions` | 列本 agent 管理的 session（顺带回填 label 缓存，修复重启后的文案 label 降级） |
+| `get_session_status` | 查子 session 状态与模型信息 |
+| `abort_session` | 中止运行中的子 session（终态 stopped） |

package/src/__tests__/helpers/extension-harness.ts

@@ -0,0 +1,137 @@
+// extension-harness.ts — session-manager 测试共享的 extension 装配 harness
+//（tool-error-handling / tool-non-json-response / watch-orchestration /
+// session-start-recovery 四份测试的 pi/ctx 桩逐字重复提取）。
+// 提取的只是装配样板——select 通道行为（deferred watch / action 分发）与全部
+// 断言留在各自测试文件。
+//
+// 初始化顺序约束：本文件运行时 import 被测 ../../index.ts（其再 import
+// pi-extension-logger）——测试文件若 mock 该 logger 模块，须先 import
+// ./logger-mock.ts 再 import 本文件（见 logger-mock.ts 文件头）。
+
+import { expect, vi, type Mock } from "vitest";
+
+import registerExtension from "../../index.ts";
+
+/** registerTool 捕获的注册工具形态（execute 以六工具用例的固定五参形态调用） */
+export interface RegisteredTool { // oe-exempt:20260930:test:测试 harness 契约——多测试文件的断言面引用其字段类型
+	name: string;
+	execute: (...args: unknown[]) => Promise<unknown>;
+}
+
+export interface EmittedEvent { // oe-exempt:20260930:test:事件断言形状契约——多测试文件消费
+	event: string;
+	data: Record<string, unknown>;
+}
+
+export interface ExtensionHarness {
+	registered: RegisteredTool[];
+	emitted: EmittedEvent[];
+	/** pi.on 注册的 handler（session_start / session_compact 收口腿触发面） */
+	handlers: Record<string, (event: unknown, ctx: unknown) => unknown>;
+	/** rpc 模式 ctx 桩（sessionManager.getEntries 读 mountExtension 的 entries 入参） */
+	ctx: Record<string, unknown>;
+}
+
+export interface ToolHarness extends ExtensionHarness { // oe-exempt:20260930:test:createToolHarness 返回契约，多测试文件消费其字段
+	selectMock: Mock;
+}
+
+/**
+ * 挂载被测 extension：registerTool 捕获工具、on 记录 handler、events.emit 收集事件，
+ * ctx 为 rpc 模式 + select 桩 + sessionManager（getEntries → entries）。
+ * select 通道实现由用例域提供：tool 级一次性应答（createToolHarness）或
+ * watch 级 deferred（各 watch 测试文件自建后传入）。
+ */
+export function mountExtension(select: Mock, entries: unknown[] = []): ExtensionHarness {
+	const registered: RegisteredTool[] = [];
+	const emitted: EmittedEvent[] = [];
+	const handlers: ExtensionHarness["handlers"] = {};
+	registerExtension({
+		registerTool: (tool: RegisteredTool) => registered.push(tool),
+		on: (event: string, handler: (event: unknown, ctx: unknown) => unknown) => {
+			handlers[event] = handler;
+		},
+		events: {
+			emit: (event: string, data: Record<string, unknown>) => {
+				emitted.push({ event, data });
+			},
+		},
+		getAllTools: vi.fn(() => []),
+		setActiveTools: vi.fn(),
+	} as never);
+	const ctx = {
+		mode: "rpc" as const,
+		hasUI: true,
+		ui: { select },
+		sessionManager: { getEntries: () => entries, getSessionId: () => "parent-1" },
+	};
+	return { registered, emitted, handlers, ctx };
+}
+
+/** tool 级 harness：select 桩由实现函数构成（一次性应答形态） */
+export function createToolHarness(selectImpl: (...args: unknown[]) => Promise<unknown>): ToolHarness {
+	const selectMock = vi.fn(selectImpl);
+	return { ...mountExtension(selectMock), selectMock };
+}
+
+/** 一次 watch 开表调用（deferred——由测试按调用序应答） */
+export interface WatchInvocation { // oe-exempt:20260930:test:watch 调用记录形状——断言面契约
+	notifyId: string;
+	resolve: (value: unknown) => void;
+}
+
+/** 按开表顺序 resolve 第 n 次 watch（value = select 回包原样值） */
+export function makeRespondWatch(watches: WatchInvocation[]): (index: number, value: unknown) => void {
+	return (index, value) => {
+		const inv = watches[index];
+		if (!inv) throw new Error(`no watch invocation at index ${index}`);
+		inv.resolve(value);
+	};
+}
+
+/** 纯微任务排干（不推进假时钟——攒批窗计时不受污染） */
+export async function flushMicrotasks(): Promise<void> {
+	for (let i = 0; i < 12; i++) await Promise.resolve();
+}
+
+/** 工具文本结果形态（六工具 execute 成功路径的 content 投影） */
+export interface ToolTextResult { // oe-exempt:20260930:test:runToolForText 返回契约——断言面消费
+	content: Array<{ type: string; text: string }>;
+}
+
+function findTool(h: Pick<ExtensionHarness, "registered">, name: string): RegisteredTool {
+	const t = h.registered.find((x) => x.name === name);
+	if (!t) throw new Error(`tool not registered: ${name}`);
+	return t;
+}
+
+/** 跑一次工具（callId/params 形态与六工具用例一致：双 undefined + harness ctx） */
+export async function runToolCall(
+	h: Pick<ExtensionHarness, "registered" | "ctx">,
+	name: string,
+	params: Record<string, unknown>,
+	callId = "call-1",
+): Promise<unknown> {
+	return findTool(h, name).execute(callId, params, undefined, undefined, h.ctx);
+}
+
+/** 跑一次工具并取文本结果（成功路径断言用） */
+export async function runToolForText(
+	h: Pick<ExtensionHarness, "registered" | "ctx">,
+	name: string,
+	params: Record<string, unknown>,
+	callId = "call-1",
+): Promise<ToolTextResult> {
+	return (await runToolCall(h, name, params, callId)) as ToolTextResult;
+}
+
+/** 工具执行 reject 断言（W4 throw 范式用例形态） */
+export async function expectToolRejects(
+	h: Pick<ExtensionHarness, "registered" | "ctx">,
+	name: string,
+	params: Record<string, unknown>,
+	pattern: RegExp,
+	callId = "call-1",
+): Promise<void> {
+	await expect(runToolCall(h, name, params, callId)).rejects.toThrow(pattern);
+}

package/src/__tests__/helpers/logger-mock.ts

@@ -0,0 +1,39 @@
+// logger-mock.ts — session-manager 测试共享的 pi-extension-logger 模块 mock
+//（notify-ledger-discipline / tool-non-json-response / watch-orchestration 三份
+// 逐字重复的 vi.hoisted + vi.mock 样板提取）。
+//
+// 使用方式（测试文件内）：
+//   import { createLoggerModuleMock, getLoggerMock } from "./helpers/logger-mock.ts";
+//   vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
+//   const loggerMock = getLoggerMock();
+//
+// 初始化顺序约束（同 subagent-workflow injector-test-mocks 先例）：本文件只有
+// vitest 一个运行时依赖、不 import 被测模块——vi.mock 工厂惰性执行时引用本文件的
+// import 绑定，故测试文件里本 import 必须先于任何会加载 pi-extension-logger 的
+// import（../index.ts / ../notify-ledger.ts / extension-harness helper）。
+// 模块级单例按测试文件隔离（vitest 默认 isolate），getLoggerMock() 与被 mock 模块
+// 的 getLogger() 返回同一引用——断言面与桩面同源。
+
+import { vi } from "vitest";
+
+/** 与被 mock 模块 getLogger() 同源的 spy 集（断言面经 getLoggerMock() 取用） */
+const loggerMock = {
+	error: vi.fn(),
+	warn: vi.fn(),
+	debug: vi.fn(),
+};
+
+export type LoggerMock = typeof loggerMock;
+
+/** 断言面：取本测试文件的 logger spy（与 mock 模块内 getLogger() 返回值同引用） */
+export function getLoggerMock(): LoggerMock {
+	return loggerMock;
+}
+
+/** pi-extension-logger 模块 mock 工厂（vi.mock 内调用；须写 () => createLoggerModuleMock() 惰性形式） */
+export function createLoggerModuleMock() {
+	return {
+		getLogger: () => loggerMock,
+		setPiHandle: vi.fn(),
+	};
+}

package/src/__tests__/notify-content.test.ts

@@ -0,0 +1,108 @@
+// notify-content.test.ts — buildManagedNotifyContent 纯函数（U6_UNIT 随迁 + D9 新形态）。
+// 原 runtime completion-backflow.test.ts 的 U6_UNIT 组随 buildBackflowContent 迁入本包。
+
+import { describe, it, expect } from "vitest";
+
+import {
+	MANAGED_SESSION_NOTIFY_CUSTOM_TYPE,
+	buildManagedNotifyContent,
+} from "../notify-content.ts";
+
+describe("MANAGED_SESSION_NOTIFY_CUSTOM_TYPE SSOT", () => {
+	it("常量值锁定为 managed-session-notify（与 shared COMPLETE_NOTIFY_CUSTOM_TYPES / core extractNotifyRecords 三处同值，防字面量漂移）", () => {
+		expect(MANAGED_SESSION_NOTIFY_CUSTOM_TYPE).toBe("managed-session-notify");
+	});
+});
+
+describe("buildManagedNotifyContent（D9 文案形状）", () => {
+	it("settle 基本形态：label/status + 指针行缺席时省略", () => {
+		expect(
+			buildManagedNotifyContent({ label: "auth-refactor", sessionId: "a1b2", status: "completed" }),
+		).toBe('Managed session "auth-refactor" (a1b2) finished with status "completed".');
+	});
+
+	it("fulfills N 行内追加：单数 request / 复数 requests（裁决4 合并笔数）", () => {
+		expect(
+			buildManagedNotifyContent({
+				label: "L",
+				sessionId: "s1",
+				status: "completed",
+				fulfills: 1,
+			}),
+		).toContain(". (fulfills 1 request)");
+		expect(
+			buildManagedNotifyContent({
+				label: "L",
+				sessionId: "s1",
+				status: "completed",
+				fulfills: 2,
+			}),
+		).toContain(". (fulfills 2 requests)");
+	});
+
+	it("fulfills 0 / 缺席 → 不出行（纯死亡通知无债权）", () => {
+		const zero = buildManagedNotifyContent({
+			label: "L",
+			sessionId: "s1",
+			status: "exited",
+			fulfills: 0,
+		});
+		const absent = buildManagedNotifyContent({ label: "L", sessionId: "s1", status: "exited" });
+		expect(zero).not.toContain("fulfills");
+		expect(absent).not.toContain("fulfills");
+	});
+
+	it("exit code 注入 status 段内（death 文案，exit 腿诊断通路复刻）", () => {
+		const content = buildManagedNotifyContent({
+			label: "L",
+			sessionId: "s1",
+			status: "exited",
+			exitCode: 1,
+			fulfills: 1,
+		});
+		expect(content).toBe(
+			'Managed session "L" (s1) finished with status "exited" (exit code: 1). (fulfills 1 request)',
+		);
+	});
+
+	it("exitCode null → 字面 'null'（迁移自 completion-backflow 语义）", () => {
+		expect(
+			buildManagedNotifyContent({ label: "L", sessionId: "s1", status: "exited", exitCode: null }),
+		).toContain('(exit code: null)');
+	});
+
+	it("stderrTail 非空 → Stderr 行；>400 字取尾部截断；全空白不输出", () => {
+		const long = `${"x".repeat(500)}TAIL`;
+		const tail = `  ${long}  `;
+		const content = buildManagedNotifyContent({
+			label: "L",
+			sessionId: "s1",
+			status: "exited",
+			stderrTail: tail,
+		});
+		// 截尾语义与迁移源一致：对原始 tail 切尾 400 字后 trim
+		expect(content).toContain(`\nStderr: ${tail.slice(-400).trim()}`);
+		expect(content).not.toContain("x".repeat(450));
+
+		const blank = buildManagedNotifyContent({
+			label: "L",
+			sessionId: "s1",
+			status: "exited",
+			stderrTail: "   \n  ",
+		});
+		expect(blank).not.toContain("Stderr");
+	});
+
+	it("sessionFilePath 提供时补 Full transcript 行（watch respond payload 已携该字段；未携 → 整行省略语义不变）", () => {
+		const content = buildManagedNotifyContent({
+			label: "L",
+			sessionId: "s1",
+			status: "completed",
+			sessionFilePath: "/data/agent/sessions/s1.jsonl",
+		});
+		expect(content).toContain("\nFull transcript: /data/agent/sessions/s1.jsonl");
+		expect(
+			buildManagedNotifyContent({ label: "L", sessionId: "s1", status: "completed" }),
+		).not.toContain("Full transcript");
+	});
+});

package/src/__tests__/notify-ledger-discipline.test.ts

@@ -0,0 +1,260 @@
+// notify-ledger-discipline.test.ts — ledger 装配纪律（notify-once D3 ①-⑤ / U4）。
+// 包名 import @zhushanwen/subagent-core（D-10 领地补录后的 canonical 形态，相对路径 hack 已删）。
+// 覆盖：
+//   ① ensureLedgerBound 无条件重 bind（唯一装配方形态，与 subagent-workflow
+//      bindLedgerHostAndRecover 同款——槽上不残留捕获旧 ctx 的 host）；
+//   ② 槽空 → bind + recoverFromSession 成对（recover 吸收 session 文件既有条目——用未销账
+//      ledger entry 种子断言 pendingCount，证明 recover 真跑过）；
+//   ③ 双 bind 收敛——「先 bind 方在后 bind 之后 record 仍返回 true」（动态查槽恒取当前实例；
+//      缓存前实例引用则 record 恒 false 零日志——D3⑤ 事故形态反证）；
+//   ④ compactionCheck 直通当前实例、抛错不外抛（接入点降级，STANDARDS §11.1）；
+//   ⑤ 消费点 record 动态查槽 + deliveryCustomType = managed-session-notify；
+//      record 先 appendEntry 落盘后内存更新（时序钉：append 快照 = 该次 record 前计数）；
+//   sendDelivery stale ctx 守卫：stale 抛错静默降级 + warn 归因（条目标 sentAt 不挂回），
+//      非 stale 错误原样上抛走 settleRejected 留账重试；
+//   槽空降级（ensure 未跑/失败时 record → warn + false，用例登记）。
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+// logger mock helper 必须先于任何会加载 pi-extension-logger 的 import
+//（subagent-core barrel / ../notify-ledger.ts），见 logger-mock.ts 文件头
+import { createLoggerModuleMock, getLoggerMock } from "./helpers/logger-mock.ts";
+import {
+	bindNotifyLedgerHost,
+	getBoundNotifyLedger,
+	type NotifyLedgerHost,
+} from "@zhushanwen/subagent-core";
+import { STALE_CTX_MARKER } from "@zhushanwen/pi-ext-guards";
+
+vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
+
+const loggerMock = getLoggerMock();
+
+import {
+	ensureLedgerBound,
+	recordManagedNotify,
+	runLedgerCompactionCheck,
+} from "../notify-ledger.ts";
+import type { ManagedNotifyDetails } from "../notify-content.ts";
+
+/** recordManagedNotify 的最小合法 details（ManagedNotifyDetails 收紧后的测试桩形状） */
+function makeDetails(notifyId: string): ManagedNotifyDetails {
+	return { notifyId, sessionId: "s-test", reason: "completed", fulfills: 1, label: "test" };
+}
+
+interface HostProbe {
+	host: NotifyLedgerHost;
+	appendLedgerEntries: Array<{ customType: string; data: Record<string, unknown> }>;
+	/** 每次 append 发生时账本 pendingCount 快照——时序钉：恒等于该次 record 前的计数 */
+	pendingCountsAtAppend: number[];
+	attach(pendingCount: () => number): void;
+}
+
+function makeHost(): HostProbe {
+	const appendLedgerEntries: HostProbe["appendLedgerEntries"] = [];
+	const pendingCountsAtAppend: number[] = [];
+	let pendingCount: (() => number) | undefined;
+	const host: NotifyLedgerHost = {
+		appendLedgerEntry(customType, data) {
+			// 时序钉（D3 ③）：record 先 appendEntry 落盘、后内存更新——此刻本条尚未入账
+			if (pendingCount) pendingCountsAtAppend.push(pendingCount());
+			appendLedgerEntries.push({ customType, data: data as Record<string, unknown> });
+		},
+		readSessionEntries: () => [],
+		isIdle: () => false,
+		onAgentSettled: () => {},
+		sendDelivery: () => {},
+	};
+	return {
+		host,
+		appendLedgerEntries,
+		pendingCountsAtAppend,
+		attach: (fn) => {
+			pendingCount = fn;
+		},
+	};
+}
+
+/** ensureLedgerBound 的最小 pi/ctx 桩（appendEntry/on/sendMessage + getEntries/isIdle） */
+function makePiCtx(
+	entries: unknown[],
+	opts?: { isIdle?: boolean; sendMessage?: () => void },
+) {
+	const pi = {
+		appendEntry: vi.fn((customType: string, data: unknown) => {
+			entries.push({ type: "custom", customType, data });
+		}),
+		on: vi.fn(),
+		sendMessage: vi.fn(opts?.sendMessage ?? (() => {})),
+	};
+	const ctx = {
+		sessionManager: { getEntries: vi.fn(() => entries) },
+		isIdle: () => opts?.isIdle ?? false,
+	};
+	return { pi, ctx };
+}
+
+afterEach(() => {
+	// dispose 摘除模块级绑定（bind 路径实例 current===api → setBoundLedger(undefined)）
+	getBoundNotifyLedger()?.dispose();
+});
+
+describe("ledger 装配纪律（D3 ①-⑤，canonical import）", () => {
+	it("槽空 → recordManagedNotify 降级 false（ensure 未跑/失败时的登记降级，warn 留痕）", () => {
+		expect(getBoundNotifyLedger()).toBeUndefined();
+		expect(recordManagedNotify("sm-x", "content", makeDetails("sm-x"))).toBe(false);
+	});
+
+	it("⑤ bind 后 record 经动态查槽入账、deliveryCustomType = managed-session-notify；时序钉：append 先于内存更新", () => {
+		const probe = makeHost();
+		const ledger = bindNotifyLedgerHost(probe.host);
+		probe.attach(() => ledger.pendingCount());
+		expect(getBoundNotifyLedger()).toBe(ledger);
+		expect(recordManagedNotify("sm-a", "hello", makeDetails("sm-a"))).toBe(true);
+		expect(probe.appendLedgerEntries).toHaveLength(1);
+		expect(probe.appendLedgerEntries[0].customType).toBe("subagent-bg-notify-ledger");
+		expect(probe.appendLedgerEntries[0].data.deliveryCustomType).toBe("managed-session-notify");
+		expect(probe.appendLedgerEntries[0].data.content).toBe("hello");
+		expect(probe.pendingCountsAtAppend).toEqual([0]);
+		expect(ledger.pendingCount()).toBe(1);
+	});
+
+	it("③ 先 bind 方在后 bind 之后 record 仍返回 true（后 bind 者收敛单实例；缓存前实例引用则恒 false——D3⑤ 反证）", () => {
+		const probeA = makeHost();
+		const ledgerA = bindNotifyLedgerHost(probeA.host);
+		probeA.attach(() => ledgerA.pendingCount());
+		expect(recordManagedNotify("sm-1", "n1", makeDetails("sm-1"))).toBe(true);
+		expect(probeA.appendLedgerEntries).toHaveLength(1);
+
+		// 后 bind 方（模拟 subagent-workflow session_start 的 re-bind + recover 成对——
+		// bindNotifyLedgerHost 内部先 dispose 旧实例再 set，收敛为单实例全量态）
+		const probeB = makeHost();
+		const ledgerB = bindNotifyLedgerHost(probeB.host);
+		probeB.attach(() => ledgerB.pendingCount());
+
+		// 消费点动态查槽恒取当前实例：先 bind 方的后续 record 落后 bind 实例且返回 true
+		expect(getBoundNotifyLedger()).toBe(ledgerB);
+		expect(recordManagedNotify("sm-2", "n2", makeDetails("sm-2"))).toBe(true);
+		expect(probeB.appendLedgerEntries.map((e) => e.data.notifyId)).toEqual(["sm-2"]);
+		expect(probeA.appendLedgerEntries).toHaveLength(1); // 前实例不再收账
+		// 时序钉跨 bind 仍成立：sm-2 时 B 账面 0（append 快照 = 该次 record 前计数）
+		expect(probeB.pendingCountsAtAppend).toEqual([0]);
+
+		// 反证：若消费点缓存了前实例引用，record 恒 false 且零日志（对半概率丢全部通知的事故形态）
+		expect(ledgerA.record("sm-3", "n3", {})).toBe(false);
+		// 而动态查槽（本包消费面）依旧 true
+		expect(recordManagedNotify("sm-4", "n4", makeDetails("sm-4"))).toBe(true);
+		expect(probeB.appendLedgerEntries).toHaveLength(2);
+		expect(probeB.pendingCountsAtAppend).toEqual([0, 1]);
+	});
+
+	it("② 槽空 + ensureLedgerBound → bind + recoverFromSession 成对（既有未销账 ledger entry 被 recover 吸收）", () => {
+		const entries: unknown[] = [
+			{
+				type: "custom",
+				customType: "subagent-bg-notify-ledger",
+				data: {
+					v: 1,
+					notifyId: "sm-recovered",
+					content: "prior notification",
+					record: { notifyId: "sm-recovered" },
+				},
+			},
+		];
+		const { pi, ctx } = makePiCtx(entries);
+		expect(getBoundNotifyLedger()).toBeUndefined();
+
+		ensureLedgerBound(pi as never, ctx as never);
+		const ledger = getBoundNotifyLedger();
+		expect(ledger).toBeDefined();
+		// recover 真跑过：session 文件的未销账条目被吸收进内存态
+		expect(ctx.sessionManager.getEntries).toHaveBeenCalled();
+		expect(ledger!.pendingCount()).toBe(1);
+		// 装配后消费面就绪
+		expect(recordManagedNotify("sm-new", "n", makeDetails("sm-new"))).toBe(true);
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"subagent-bg-notify-ledger",
+			expect.objectContaining({ notifyId: "sm-new", deliveryCustomType: "managed-session-notify" }),
+		);
+	});
+
+	it("① 槽已有实例 + ensureLedgerBound → 无条件重 bind（后 bind 收敛接管 + recover 重跑）", () => {
+		const probe = makeHost();
+		const ledger = bindNotifyLedgerHost(probe.host);
+		probe.attach(() => ledger.pendingCount());
+
+		const { pi, ctx } = makePiCtx([]);
+		ensureLedgerBound(pi as never, ctx as never);
+		// 后 bind 收敛：旧实例被 dispose，槽切到新实例（槽上不残留捕获旧 ctx 的 host）
+		const rebound = getBoundNotifyLedger();
+		expect(rebound).toBeDefined();
+		expect(rebound).not.toBe(ledger);
+		// recover 重跑：新 host 的 readSessionEntries 被消费
+		expect(ctx.sessionManager.getEntries).toHaveBeenCalled();
+		// 消费面动态查槽：record 落新实例（经新 host 的 appendLedgerEntry = pi.appendEntry）
+		expect(recordManagedNotify("sm-1", "n", makeDetails("sm-1"))).toBe(true);
+		expect(pi.appendEntry).toHaveBeenCalled();
+
+		// 重复调用同款：每次 session_start 都重装配（不查槽短路）
+		ensureLedgerBound(pi as never, ctx as never);
+		expect(getBoundNotifyLedger()).not.toBe(rebound);
+	});
+
+	it("sendDelivery stale ctx 守卫：stale 抛错静默降级 + warn 归因（条目标 sentAt，不外抛不挂回）", () => {
+		const { pi, ctx } = makePiCtx([], {
+			isIdle: true,
+			sendMessage: () => {
+				throw new Error(`ctx ${STALE_CTX_MARKER}`);
+			},
+		});
+		ensureLedgerBound(pi as never, ctx as never);
+		const ledger = getBoundNotifyLedger();
+		expect(ledger).toBeDefined();
+		expect(recordManagedNotify("sm-stale", "n", makeDetails("sm-stale"))).toBe(true);
+		expect(() => ledger!.attemptDeliver()).not.toThrow();
+		// stale 降级语义：本条不投递且按已受理标 sentAt（attemptDeliver 摘除，不挂回反复撞）
+		expect(ledger!.pendingCount()).toBe(0);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"[session-manager] notify delivery skipped (stale ctx)",
+			expect.objectContaining({ error: expect.stringContaining("stale") }),
+		);
+	});
+
+	it("sendDelivery 非 stale 错误原样上抛 → settleRejected 留账重试（pending 不摘、无 stale 归因）", () => {
+		// 清上一用例的 warn 记录——断言只认本用例内的调用
+		loggerMock.warn.mockClear();
+		const { pi, ctx } = makePiCtx([], {
+			isIdle: true,
+			sendMessage: () => {
+				throw new Error("boom");
+			},
+		});
+		ensureLedgerBound(pi as never, ctx as never);
+		const ledger = getBoundNotifyLedger();
+		expect(ledger).toBeDefined();
+		expect(recordManagedNotify("sm-err", "n", makeDetails("sm-err"))).toBe(true);
+		expect(() => ledger!.attemptDeliver()).not.toThrow();
+		// 非 stale 走 attemptDeliver 既有 catch：settleRejected 留账等下一边沿重试
+		expect(ledger!.pendingCount()).toBe(1);
+		expect(loggerMock.warn).not.toHaveBeenCalledWith(
+			"[session-manager] notify delivery skipped (stale ctx)",
+			expect.anything(),
+		);
+	});
+
+	it("④ compactionCheck 经动态查槽直通当前实例", () => {
+		const probe = makeHost();
+		const ledger = bindNotifyLedgerHost(probe.host);
+		probe.attach(() => ledger.pendingCount());
+		const spy = vi.spyOn(getBoundNotifyLedger()!, "compactionCheck").mockReturnValue(0);
+		runLedgerCompactionCheck();
+		expect(spy).toHaveBeenCalledTimes(1);
+	});
+
+	it("④ compactionCheck 抛错 → warn 吞掉不外抛（辅助面接入点降级，STANDARDS §11.1）", () => {
+		bindNotifyLedgerHost(makeHost().host);
+		vi.spyOn(getBoundNotifyLedger()!, "compactionCheck").mockImplementation(() => {
+			throw new Error("boom");
+		});
+		expect(() => runLedgerCompactionCheck()).not.toThrow();
+	});
+});