@zhushanwen/pi-session-manager 0.3.4 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-manager",
-  "version": "0.3.4",
+  "version": "0.5.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",
@@ -30,11 +30,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.21.0",
+    "@zhushanwen/extension-protocol": "0.22.0",
+    "@zhushanwen/pi-delivery-port": "0.2.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
-    "@zhushanwen/pi-extension-logger": "0.6.2",
-    "@zhushanwen/pi-notify-ledger-host": "0.3.4",
-    "@zhushanwen/subagent-core": "1.5.2"
+    "@zhushanwen/pi-extension-logger": "0.6.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
@@ -43,12 +42,16 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "^1.0.0",
     "typebox": "1.3.27"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
       "optional": true
     },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
     "typebox": {
       "optional": true
     }

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

@@ -1,6 +1,6 @@
 ---
 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。"
+description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed session 六工具与完成通知）时加载。说明完成通知链（notifyId → watch 长挂通道 → managed-session-notify 送达）、投递日志存储（delivery-port outbox/ack entry + session_start 差集重放）、pending 列表 type 'session' 条目的生命周期、willNotify 与 fulfills 合并语义、lifetimeNotifyId 死亡通知、未收到通知与 pending 残留的排查入口。触发词：session-manager、managed session、create_managed_session、send_to_session、完成通知没收到、通知未送达、notifyId、pending 列表有 session 条目、投递日志、delivery-port、managed-session-notify、willNotify、session-manager-ext-config。"
 ---
 
 # session-manager 使用与排查指南
@@ -8,7 +8,7 @@ description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed ses
 > @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。
+> 投递日志与排查入口；工具契约细节（marker 通道 / 超时分档）见包 README。
 
 ## 重要前提
 
@@ -16,7 +16,7 @@ description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed ses
   独立 pi CLI 无 handler 应答，所有工具等待至超时后报 `cancelled or timed out`。
   工具失败时先确认运行环境，不要怀疑参数。
 - 本扩展不读磁盘配置文件，无 config JSON——通知状态全部存储在 pi session 文件内
-  （见 B-ledger 一节），没有「改配置文件」这条路径。
+  （见投递日志一节），没有「改配置文件」这条路径。
 
 ## 完成通知链（notifyId → watch → managed-session-notify）
 
@@ -32,9 +32,9 @@ description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed ses
    `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）。
+4. **入账投递**：攒批结果经 `recordManagedNotify` → delivery-port 的 `port.deliver`
+   提交（见下节），注入直达 pi 唯一队列（steer 档 + `triggerTurn: true`，pi 忙时入队
+   不拒、轮边界注入），送达回执按 notifyId 的 details-id 凭据匹配逐条处理完毕（ack entry）。
 
 通知文案形态：`Managed session "<label>" (<sessionId>) finished with status "<status>"
 (exit code: N). (fulfills N request(s))`；stderr 非空时附 Stderr tail（400 字截尾）；
@@ -45,30 +45,32 @@ runtime 查得到时附 `Full transcript: <sessionFilePath>` 指针行。
 - 多条 queued 消息在同一轮消费合并为一次通知（fulfills N = 本批兑现笔数）；
 - `create_managed_session` 还返回 `lifetimeNotifyId`：session 终局死亡（exited/deleted）
   恒产出一次死亡通知，与结果通知相互独立；
-- 每 notifyId 至多一条通知（record 幂等去重），重放不重复发声。
+- 每 notifyId 至多一条通知（投递日志按 id 幂等判重），重放不重复发声。
 
-## B-ledger 账本存储
+## 投递日志（delivery-port）
 
-通知落账与恢复不依赖独立磁盘文件，复用 pi session 文件本身：
+通知记录与恢复不依赖独立磁盘文件，复用 pi session 文件本身（pi session append-only
+契约：entry 只追加不删改，compaction 不清 entry）：
 
-- **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 收敛语义合并为
-  单实例，互不重复投递。
+- **outbox entry = session 文件自定义 entry**：通知经 `@zhushanwen/pi-delivery-port`
+  的 `port.deliver` 提交（id = notifyId 幂等键，managed-session-notify 外部通道逐条），
+  受理前先 `pi.appendEntry` 写 outbox entry（delivery-port-outbox，plain custom entry
+  不进 LLM 上下文）——先落盘后投递，进程崩溃后债权不丢。
+- **送达回执处理完毕**：注入后 pi 侧出现携带该 id 的 custom_message，port 订阅
+  message_end 按 details-id 凭据命中 → 写 ack entry（delivery-port-ack）终局。
+- **session_start 差集重放**：每次 session_start 扫投递日志 −（对话记录已送达 ∪ ack）
+  差集——未处理的债权重新投递，已处理完毕的静默；按 notifyId 幂等去重，重放不重复发声。
+- 投递端口装配在 `@zhushanwen/pi-base-tool-enhance` 的 session_start（infrastructure
+  档必载），本扩展零装配义务——port 恒可用；缺席仅覆盖装配异常窗口（warn + 弃投该条，
+  下次 session_start 重试装配）。
 
 ## 排查入口
 
 | 症状 | 排查路径 |
 |------|---------|
-| 未收到完成通知 | ① 确认 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` 留痕归因 |
+| 未收到完成通知 | ① 确认 taiji 桌面环境（standalone pi CLI 无 handler，工具本身就会超时）；② 查扩展日志 `<agentDir>/logs/session-manager-YYYY-MM-DD.log`（agentDir = pi `getAgentDir()`，默认 `~/.pi/agent`，taiji 隔离环境 `~/.taiji/agent`）搜 `[session-manager]`——`delivery port not bound`（base-tool-enhance session_start 未跑/装配失败，通知丢弃，下次 session_start 重试装配）、`delivery port rejected notification`（受理被拒：幂等键未登记，watch 重试合法）、`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），应答到达即静默注销，无需手工处理 |
+| 同一完成重复通知 | 不应发生——投递日志按 notifyId 判重、死亡槽 (sessionId, deathSeq) 同键只发首条。若复现即协议漂移，查扩展日志 `delivery port rejected notification` / `notify delivery failed` 留痕归因 |
 
 ## 工具速查
 

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

@@ -13,7 +13,7 @@ import { expect, vi, type Mock } from "vitest";
 import registerExtension from "../../index.ts";
 
 /** registerTool 捕获的注册工具形态（execute 以六工具用例的固定五参形态调用） */
-export interface RegisteredTool { // oe-exempt:20260930:test:测试 harness 契约——多测试文件的断言面引用其字段类型
+export interface RegisteredTool { // oe-exempt:20260930:test:测试 harness 契约——多测试文件的断言范围引用其字段类型
 	name: string;
 	execute: (...args: unknown[]) => Promise<unknown>;
 }
@@ -26,7 +26,7 @@ export interface EmittedEvent { // oe-exempt:20260930:test:事件断言形状契
 export interface ExtensionHarness {
 	registered: RegisteredTool[];
 	emitted: EmittedEvent[];
-	/** pi.on 注册的 handler（session_start / session_compact 收口腿触发面） */
+	/** 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>;
@@ -75,7 +75,7 @@ export function createToolHarness(selectImpl: (...args: unknown[]) => Promise<un
 }
 
 /** 一次 watch 开表调用（deferred——由测试按调用序应答） */
-export interface WatchInvocation { // oe-exempt:20260930:test:watch 调用记录形状——断言面契约
+export interface WatchInvocation { // oe-exempt:20260930:test:watch 调用记录形状——断言范围契约
 	notifyId: string;
 	resolve: (value: unknown) => void;
 }
@@ -94,8 +94,8 @@ 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 返回契约——断言面消费
+/** 工具文本结果形态（六工具 execute 成功路径的 content 派生视图） */
+export interface ToolTextResult { // oe-exempt:20260930:test:runToolForText 返回契约——断言范围消费
 	content: Array<{ type: string; text: string }>;
 }
 

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

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

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

@@ -52,7 +52,7 @@ describe("buildManagedNotifyContent（D9 文案形状）", () => {
 		expect(absent).not.toContain("fulfills");
 	});
 
-	it("exit code 注入 status 段内（death 文案，exit 腿诊断通路复刻）", () => {
+	it("exit code 注入 status 段内（death 文案，exit 路径诊断通路复刻）", () => {
 		const content = buildManagedNotifyContent({
 			label: "L",
 			sessionId: "s1",

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

@@ -0,0 +1,125 @@
+// notify-delivery-discipline.test.ts — recordManagedNotify 的投递接入纪律
+// （unified-delivery 波 2：投递路径切 pi 半区投递端口后的消费纪律锁）。
+//
+// 覆盖（原 notify-ledger-discipline.test.ts 场景的 port 形态对位——账本装配纪律
+// ①②③④与 stale 检查随账本退役：bind/recover 收敛由 pi-delivery-port 套件的
+// 「重复 bind 替换并 dispose 旧实例」锁定，stale 注入 throw → 内核 retain 由其
+// 「注入 throw → retain 留账」锁定，compaction 接线随 append-only 契约裁决删除）：
+//   ⑤ 消费点经 getDeliveryPort() 动态查槽（禁缓存实例引用——后 bind 方 dispose
+//      旧实例后缓存引用的 deliver 静默 rejected，对半概率丢全部通知的 D3⑤ 同律）；
+//   通道 = managed-session-notify 外部通道（payload.customType，port 批组隔离恒
+//   逐条不合批）；槽空降级（port 缺席 → warn + false，STANDARDS §11.1）；port
+//   rejected（persist-failed）→ warn + false（幂等键未登记，watch 重试合法）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createLoggerModuleMock, getLoggerMock } from "./helpers/logger-mock.ts";
+
+vi.mock("@zhushanwen/pi-extension-logger", () => createLoggerModuleMock());
+
+const loggerMock = getLoggerMock();
+
+import { recordManagedNotify } from "../notify-delivery.ts";
+import type { ManagedNotifyDetails } from "../notify-content.ts";
+import { DELIVERY_PORT_SLOT_KEY } from "@zhushanwen/pi-delivery-port";
+
+// pi-delivery-port 进程级槽（C-ext-06；recordManagedNotify 的消费入口）。
+const PORT_SLOT_KEY = DELIVERY_PORT_SLOT_KEY;
+
+/** recordManagedNotify 的最小合法 details（ManagedNotifyDetails 收紧后的测试桩形状）。 */
+function makeDetails(notifyId: string): ManagedNotifyDetails {
+	return { notifyId, sessionId: "s-test", reason: "completed", fulfills: 1, label: "test" };
+}
+
+type DeliverCall = {
+	id: string | undefined;
+	customType: string;
+	content: string;
+	details: unknown;
+	collectKey: string[] | undefined;
+};
+
+function plantPort(behavior: "accept" | "reject" = "accept"): Array<DeliverCall> {
+	const calls: Array<DeliverCall> = [];
+	Reflect.set(globalThis, PORT_SLOT_KEY, {
+		current: {
+			deliver: (
+				envelope: {
+					id?: string;
+					payload: { customType: string; content: string; details?: unknown };
+				},
+				opts?: { collectKey?: string[] },
+			) => {
+				if (behavior === "reject") return { kind: "rejected", reason: "persist-failed (fake)" };
+				calls.push({
+					id: envelope.id,
+					customType: envelope.payload.customType,
+					content: envelope.payload.content,
+					details: envelope.payload.details,
+					collectKey: opts?.collectKey,
+				});
+				return { kind: "accepted", id: envelope.id ?? "gen-id" };
+			},
+			flush: () => {},
+		},
+	});
+	return calls;
+}
+
+beforeEach(() => {
+	loggerMock.warn.mockClear();
+});
+
+afterEach(() => {
+	// 摘除槽注入——防泄漏到同文件后续用例（生产槽由 base-tool-enhance session_start 装配）。
+	Reflect.deleteProperty(globalThis, PORT_SLOT_KEY);
+});
+
+describe("recordManagedNotify 投递接入纪律（unified-delivery 波 2：port 消费方）", () => {
+	it("槽空（port 未装配）→ 降级 false + warn 留痕（通知类接入点降级，非静默吞）", () => {
+		Reflect.deleteProperty(globalThis, PORT_SLOT_KEY);
+		expect(recordManagedNotify("sm-x", "content", makeDetails("sm-x"), ["sm-x"])).toBe(false);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("delivery port not bound"),
+			expect.objectContaining({ notifyId: "sm-x" }),
+		);
+	});
+
+	it("port 在 → 动态查槽投递：id = notifyId、payload.customType = managed-session-notify（外部通道）、details 原样、collectKey 键集透传", () => {
+		const delivered = plantPort();
+		const details = makeDetails("sm-a");
+		expect(recordManagedNotify("sm-a", "hello", details, ["sm-a", "sm-b"])).toBe(true);
+		expect(delivered).toHaveLength(1);
+		expect(delivered[0]!.id).toBe("sm-a");
+		expect(delivered[0]!.customType).toBe("managed-session-notify");
+		expect(delivered[0]!.content).toBe("hello");
+		expect(delivered[0]!.details).toBe(details);
+		// collectKey 债权键集申报（result-collect 设计 §3.4）：批内全部债权键原样透传
+		expect(delivered[0]!.collectKey).toEqual(["sm-a", "sm-b"]);
+	});
+
+	it("port rejected（persist-failed）→ warn + false（幂等键未登记，watch 重试合法；不静默吞）", () => {
+		plantPort("reject");
+		expect(recordManagedNotify("sm-rej", "content", makeDetails("sm-rej"), ["sm-rej"])).toBe(false);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("delivery port rejected notification"),
+			expect.objectContaining({ notifyId: "sm-rej" }),
+		);
+	});
+
+	it("投递异常（port.deliver 抛错）→ warn 留痕不外抛（不拖垮 watch 应答编排，unregister 照常）", () => {
+		Reflect.set(globalThis, PORT_SLOT_KEY, {
+			current: {
+				deliver: () => {
+					throw new Error("session context is no longer active (assertActive)");
+				},
+				flush: () => {},
+			},
+		});
+		expect(() => recordManagedNotify("sm-throw", "content", makeDetails("sm-throw"), ["sm-throw"])).not.toThrow();
+		expect(recordManagedNotify("sm-throw-2", "content", makeDetails("sm-throw-2"), ["sm-throw-2"])).toBe(false);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			expect.stringContaining("notify delivery failed"),
+			expect.objectContaining({ notifyId: "sm-throw-2" }),
+		);
+	});
+});

package/src/__tests__/session-start-recovery.test.ts

@@ -1,12 +1,13 @@
-// session-start-recovery.test.ts — 重启收口腿（notify-once D7③ / U4）。
-// 断言面：活跃 type 'session' register 重开 watch（入参 = entry id 即 notifyId）/
+// session-start-recovery.test.ts — 重启收尾路径（notify-once D7③ / U4）。
+// 断言范围：活跃 type 'session' register 重开 watch（入参 = entry id 即 notifyId）/
 // 类型过滤（workflow 与已注销条目不触碰）/ 覆盖序（W1 悬置被 W2 覆盖后该 entry 恰一次
 // unregister、后续 entry 不受阻塞——每 entry 独立 handler 禁串行 await）/
-// 收口腿 label 降级源 = register 三键 name。
+// 收尾路径 label 降级源 = register 三键 name。
 // pi/ctx 装配、respondWatch、flushMicrotasks 走共享 harness（helpers/extension-harness.ts）；
 // watch-only select（非 watch action 即抛）为本文件域行为，留在本地。
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { DELIVERY_PORT_SLOT_KEY } from "@zhushanwen/pi-delivery-port";
 import {
 	flushMicrotasks,
 	makeRespondWatch,
@@ -15,7 +16,8 @@ import {
 	type WatchInvocation,
 } from "./helpers/extension-harness.ts";
 
-const LEDGER_SLOT_KEY = Symbol.for("@zhushanwen/subagent-core.notifyLedger");
+// pi-delivery-port 进程级槽（recordManagedNotify 的投递观测点——unified-delivery 波 2）。
+const PORT_SLOT_KEY = DELIVERY_PORT_SLOT_KEY;
 
 interface Harness extends ExtensionHarness {
 	watches: WatchInvocation[];
@@ -31,7 +33,7 @@ function staleEntries(): unknown[] {
 	return [
 		{ customType: "pending:register", data: { id: E1, type: "session", name: "Alpha", registeredAt: 1, sessionId: "parent-1" } },
 		{ customType: "pending:register", data: { id: E2, type: "session", name: "Beta", registeredAt: 2, sessionId: "parent-1" } },
-		// workflow 类型归 core 对账 sweep，收口腿不得触碰
+		// workflow 类型归 core 对账 sweep，收尾路径不得触碰
 		{ customType: "pending:register", data: { id: WF, type: "workflow", name: "run-1" } },
 		// 已注销（差集净空）→ 不重开
 		{ customType: "pending:register", data: { id: E3, type: "session", name: "Gamma", registeredAt: 3, sessionId: "parent-1" } },
@@ -64,7 +66,7 @@ function unregistersOf(h: Harness): Array<[string, unknown]> {
 		.map((e) => [String(e.data.id), e.data.reason]);
 }
 
-/** 单条 session register 的收口腿驱动（fail-closed / label 降级两用例共用前置）：
+/** 单条 session register 的收尾路径驱动（fail-closed / label 降级两用例共用前置）：
  * 开表（session_start）→ 排干微任务 → 应答首个 watch → 再排干 */
 async function startSingleEntrySession(respondValue: unknown): Promise<Harness> {
 	const h = createHarness([
@@ -83,10 +85,10 @@ beforeEach(() => {
 
 afterEach(() => {
 	vi.useRealTimers();
-	Reflect.deleteProperty(globalThis, LEDGER_SLOT_KEY);
+	Reflect.deleteProperty(globalThis, PORT_SLOT_KEY);
 });
 
-describe("session_start 重启收口腿（D7③）", () => {
+describe("session_start 重启收尾路径（D7③）", () => {
 	it("重开 watch 覆盖序：W1 悬置被 W2 覆盖后该 entry 恰一次 unregister，且后续 entry 不受阻塞", async () => {
 		const h = createHarness(staleEntries());
 		expect(h.handlers.session_start).toBeTypeOf("function");
@@ -97,7 +99,7 @@ describe("session_start 重启收口腿（D7③）", () => {
 		await flushMicrotasks();
 		expect(h.watches.map((w) => w.notifyId)).toEqual([E1, E2]);
 
-		// E2 先应答 orphaned（杀父腿，触发器②批量转移先行）→ 即时静默 unregister
+		// E2 先应答 orphaned（杀父路径，触发器②批量转移先行）→ 即时静默 unregister
 		h.respondWatch(1, JSON.stringify({ reason: "orphaned", sessionId: "child-b" }));
 		await flushMicrotasks();
 		expect(unregistersOf(h)).toEqual([[E2, "orphaned"]]);
@@ -125,21 +127,28 @@ describe("session_start 重启收口腿（D7③）", () => {
 		expect(watchedIds).not.toContain(E3);
 	});
 
-	it("runtime 已重启查无 claim → fail-closed 'cancelled' 腿：静默注销（活跃集回归基线）", async () => {
+	it("runtime 已重启查无 claim → fail-closed 'cancelled' 路径：静默注销（活跃集回归基线）", async () => {
 		const h = await startSingleEntrySession(JSON.stringify({ reason: "cancelled" }));
 		expect(unregistersOf(h)).toEqual([[E1, "cancelled"]]);
 	});
 
-	it("收口腿 label 降级源 = register 三键 name（D9 label 两路径的恢复路径）", async () => {
-		Reflect.set(globalThis, LEDGER_SLOT_KEY, {
-			current: { record: vi.fn(() => true), compactionCheck: () => 0 },
+	it("收尾路径 label 降级源 = register 三键 name（D9 label 两路径的恢复路径）", async () => {
+		const delivered: Array<{ id?: string; content: string }> = [];
+		Reflect.set(globalThis, PORT_SLOT_KEY, {
+			current: {
+				deliver: (envelope: { id?: string; payload: { content: string } }) => {
+					delivered.push({ id: envelope.id, content: envelope.payload.content });
+					return { kind: "accepted", id: envelope.id ?? "gen-id" };
+				},
+				flush: () => {},
+			},
 		});
-		const record = Reflect.get(globalThis, LEDGER_SLOT_KEY).current.record;
 		const h = await startSingleEntrySession(
 			JSON.stringify({ reason: "completed", sessionId: "child-x", settleSeq: 1, fulfillsN: 1 }),
 		);
 		await vi.advanceTimersByTimeAsync(50);
-		expect(record).toHaveBeenCalledTimes(1);
-		expect(String(record.mock.calls[0][1])).toContain('Managed session "Alpha" (child-x)');
+		expect(delivered).toHaveLength(1);
+		expect(delivered[0]!.content).toContain('Managed session "Alpha" (child-x)');
+		Reflect.deleteProperty(globalThis, PORT_SLOT_KEY);
 	});
 });

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

@@ -0,0 +1,169 @@
+// tool-summary.test.ts — details.summary 产出（六工具文案断言，走 execute 骨架）+
+// renderSessionManagerResult 两态（折叠态一行摘要 / 展开态原始 content 文本）。
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import registerExtension from "../index.ts";
+import { renderSessionManagerResult } from "../render.ts";
+
+/** Capture registered tools and provide a mock ctx.ui.select. */
+function createHarness() {
+	const registered: Array<{ name: string; execute: Function; renderResult?: Function }> = [];
+	const selectMock = vi.fn().mockResolvedValue('{"ok":true}');
+	const pi = {
+		registerTool: (tool: { name: string; execute: Function; renderResult?: Function }) => registered.push(tool),
+		on: vi.fn(),
+		getAllTools: vi.fn(() => []),
+		setActiveTools: vi.fn(),
+	};
+	const ctx = {
+		mode: "rpc" as const,
+		hasUI: true,
+		ui: { select: selectMock },
+	};
+	registerExtension(pi as never);
+	return { registered, selectMock, ctx };
+}
+
+// mock theme（fg 直通，便于断言纯文本；todo render.test.ts 同款）
+const mockTheme = {
+	fg: (_color: string, text: string) => text,
+	bg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+} as unknown as Theme;
+
+function renderedText(result: unknown, expanded: boolean): string {
+	return renderSessionManagerResult(result, { expanded }, mockTheme).render(400).join("\n");
+}
+
+describe("execute 组装 details.summary（六工具文案）", () => {
+	let harness: ReturnType<typeof createHarness>;
+
+	beforeEach(() => {
+		harness = createHarness();
+	});
+
+	async function summaryOf(toolName: string, params: Record<string, unknown>, reply: unknown): Promise<string> {
+		harness.selectMock.mockResolvedValue(JSON.stringify(reply));
+		const tool = harness.registered.find((t) => t.name === toolName)!;
+		const result = (await tool.execute("call-1", params, undefined, undefined, harness.ctx)) as {
+			details: { summary: string };
+		};
+		return result.details.summary;
+	}
+
+	it("create_managed_session：带 label → 引号 label；无 label → 回退 sessionId", async () => {
+		expect(
+			await summaryOf("create_managed_session", { cwd: "/work", label: "worker" }, { sessionId: "s1", status: "created" }),
+		).toBe('Created session "worker"');
+		expect(
+			await summaryOf("create_managed_session", { cwd: "/work" }, { sessionId: "s1", status: "created" }),
+		).toBe("Created session s1");
+	});
+
+	it("send_to_session：Sent message to <sessionId>", async () => {
+		expect(await summaryOf("send_to_session", { sessionId: "s1", prompt: "hi" }, { queued: true, willNotify: true })).toBe(
+			"Sent message to s1",
+		);
+	});
+
+	it("read_session_history：messages 计数后缀", async () => {
+		expect(
+			await summaryOf("read_session_history", { sessionId: "s1" }, { messages: [{}, {}, {}], truncated: false }),
+		).toBe("Read history of s1 · 3 entries");
+	});
+
+	it("list_my_sessions：sessions 计数", async () => {
+		expect(await summaryOf("list_my_sessions", {}, { sessions: [{ id: "s1" }, { id: "s2" }] })).toBe(
+			"Listed 2 managed sessions",
+		);
+	});
+
+	it("get_session_status：<sessionId> · <status>", async () => {
+		expect(await summaryOf("get_session_status", { sessionId: "s1" }, { status: "idle", undeliveredResults: 0 })).toBe(
+			"s1 · idle",
+		);
+	});
+
+	it("abort_session：Aborted <sessionId>", async () => {
+		expect(await summaryOf("abort_session", { sessionId: "s1" }, { success: true })).toBe("Aborted s1");
+	});
+});
+
+describe("toSummary 数据缺失分支（形状漂移退化为短文案，不抛错）", () => {
+	let harness: ReturnType<typeof createHarness>;
+
+	beforeEach(() => {
+		harness = createHarness();
+	});
+
+	async function summaryOf(toolName: string, params: Record<string, unknown>, reply: unknown): Promise<string> {
+		harness.selectMock.mockResolvedValue(JSON.stringify(reply));
+		const tool = harness.registered.find((t) => t.name === toolName)!;
+		const result = (await tool.execute("call-1", params, undefined, undefined, harness.ctx)) as {
+			details: { summary: string };
+		};
+		return result.details.summary;
+	}
+
+	it("create_managed_session：label 与 sessionId 均缺 → 裸文案", async () => {
+		expect(await summaryOf("create_managed_session", { cwd: "/work" }, {})).toBe("Created session");
+	});
+
+	it("read_session_history：messages 缺失/非数组 → 无计数后缀", async () => {
+		expect(await summaryOf("read_session_history", { sessionId: "s1" }, { truncated: false })).toBe("Read history of s1");
+	});
+
+	it("list_my_sessions：sessions 非数组 → 无计数", async () => {
+		expect(await summaryOf("list_my_sessions", {}, { sessions: "bad" })).toBe("Listed managed sessions");
+	});
+
+	it("get_session_status：status 缺失 → Status of <sessionId>", async () => {
+		expect(await summaryOf("get_session_status", { sessionId: "s1" }, {})).toBe("Status of s1");
+	});
+});
+
+describe("renderSessionManagerResult 两态", () => {
+	it("折叠态（expanded=false）：渲染 details.summary 一行摘要，不含原始 JSON", () => {
+		const result = {
+			content: [{ type: "text", text: '{"messages":[{}]}' }],
+			details: { summary: "Read history of s1 · 1 entries" },
+		};
+		const out = renderedText(result, false);
+		expect(out).toContain("Read history of s1 · 1 entries");
+		expect(out).not.toContain("messages");
+	});
+
+	it("展开态（expanded=true）：渲染 content[0] 原始文本，不含摘要", () => {
+		const result = {
+			content: [{ type: "text", text: '{"messages":[{}]}' }],
+			details: { summary: "Read history of s1 · 1 entries" },
+		};
+		const out = renderedText(result, true);
+		expect(out).toContain('{"messages":[{}]}');
+		expect(out).not.toContain("Read history of s1");
+	});
+
+	it("折叠态但 details 缺失 / summary 非字符串 → 回退 content 文本", () => {
+		expect(renderedText({ content: [{ type: "text", text: "raw" }] }, false)).toContain("raw");
+		expect(renderedText({ content: [{ type: "text", text: "raw" }], details: { summary: 7 } }, false)).toContain("raw");
+	});
+
+	it("六工具注册的 renderResult 均存在且折叠态行为一致（共用渲染内核）", () => {
+		const harness = createHarness();
+		const renderFns = harness.registered.map((t) => t.renderResult);
+		expect(renderFns).toHaveLength(6);
+		for (const fn of renderFns) expect(typeof fn).toBe("function");
+		// 抽查一个 handler：折叠态出摘要、不出原始 JSON（handler 是各 registerTool
+		// 的方法包装，内核同为 renderSessionManagerResult）
+		const out = (renderFns[0] as (r: unknown, o: { expanded: boolean }, t: unknown) => { render: (w: number) => string[] })(
+			{ content: [{ type: "text", text: "raw" }], details: { summary: "Aborted s1" } },
+			{ expanded: false },
+			mockTheme,
+		)
+			.render(400)
+			.join("\n");
+		expect(out).toContain("Aborted s1");
+		expect(out).not.toContain("raw");
+	});
+});