@zhushanwen/pi-session-manager 0.4.0 → 0.6.0

package/README.md

@@ -1,14 +1,14 @@
 # @zhushanwen/pi-session-manager
 
-agent-managed session pi extension：把 session 的创建/发送/读取/列表/状态/中止交给 agent 自主管理——agent 通过 6 个工具以子 session 形态并行工作，父 session 统一编排。
+agent-managed session pi extension：把 session 的创建/发送/读取/列表/状态/中止/归档/删除交给 agent 自主管理——agent 通过 8 个工具以子 session 形态并行工作，父 session 统一编排。
 
 ## 通道契约
 
-- 工具调用经 `ctx.ui.select(SESSION_MANAGER_MARKER, [JSON], {timeout})` 发出，超时按 action 分档（create/history 60s、其余 30s，SSOT 在 `src/index.ts` 的 `SELECT_TIMEOUT_MS`）；marker 为 `\x00TAIJI_SESSION_MANAGER`（NUL 前缀防与普通 select title 冲突，SSOT 在 `@zhushanwen/extension-protocol`）
+- 工具调用经 `ctx.ui.select(SESSION_MANAGER_MARKER, [JSON])` 发出，全 action 不传 timeout（ADR-0122：无包内挂死兜底，handler 不回包时工具调用长挂）；marker 为 `\x00TAIJI_SESSION_MANAGER`（NUL 前缀防与普通 select title 冲突，SSOT 在 `@zhushanwen/extension-protocol`）
 - 请求体为嵌套形状 `{ action, params }`（形状 SSOT 在 `@zhushanwen/extension-protocol`）；**不要扁平化展开**——runtime event-adapter 按 `data.params` 提取，扁平化会导致 params 丢失
-- 应答方是 taiji runtime 的 `SessionManagerHandler`（select value 通道回写 JSON 字符串；取消/超时返回 null）
+- 应答方是 taiji runtime 的 `SessionManagerHandler`（select value 通道回写 JSON 字符串；取消返回 null——本扩展不传 timeout、无超时态，pi select 层对取消/超时本就不可区分，见 protocol `callMarkerRpc`）
 
-## 工具（6 个工具，每工具 1 个 action）
+## 工具（8 个工具，每工具 1 个 action）
 
 | 工具 | action | 说明 |
 |------|--------|------|
@@ -18,10 +18,12 @@ agent-managed session pi extension：把 session 的创建/发送/读取/列表/
 | `list_my_sessions` | list | 列出本 agent 管理的 session（无过滤参数，自动限定发起方 agent） |
 | `get_session_status` | status | 查询子 session 状态与模型信息 |
 | `abort_session` | abort | 中止运行中的子 session |
+| `archive_session` | archive | 归档子 session（可恢复）：会话退场进归档区（文件压缩搬移），用户可随时查看摘要并恢复；agent 可主动调用做任务收尾整理，生成中的会话拒绝归档（先 `abort_session` 或等完成） |
+| `delete_session` | delete | 彻底删除子 session（不可恢复）：进程 + 历史 + 衍生数据整树进废纸篓。USER-INITIATED ONLY：仅当用户消息明确表达不可恢复的删除意图时调用，agent 永不主动发起；模糊表达（「清理掉/收掉」等）一律归 `archive_session` |
 
 ## 运行要求
 
-应答端（runtime handler）在 taiji 桌面应用内；独立 pi CLI 环境无 handler 应答，工具会等待至超时（create/history 60s、其余 30s）后返回 isError 错误结果（文案 `cancelled or timed out`——pi 实装对取消与超时不可区分，见 protocol `callMarkerRpc`）。
+应答端（runtime handler）在 taiji 桌面应用内；独立 pi CLI 环境无 handler 应答，工具调用长挂（hangs forever——不传 timeout，ADR-0122）。通道取消/断开折叠为 isError 错误结果（文案开头 `cancelled or channel error — check the taiji runtime connection first…`，含重试安全性与 duplicate-notifyId 例外，全文见 `src/index.ts` 的 executeTool）。
 
 ## 安装
 
@@ -31,7 +33,7 @@ pi install npm:@zhushanwen/pi-session-manager
 
 ## 工具激活（deferred）
 
-上表 6 个工具均为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）加 `"defaultTools": ["+tool_search"]`（`+` 前缀是增量修饰，保留 read/bash/edit/write 默认集）。注意独立 pi 下即便激活，工具功能仍依赖 taiji runtime handler（见上节「运行要求」）。
+上表 8 个工具均为 `exposure: "deferred"`——不占常驻工具声明，由 pi 内置 `tool_search` 工具检索命中后按需激活。taiji 宿主内开箱即用（宿主启动时已激活 `tool_search`）；独立 pi 使用需在 `<agentDir>/settings.json`（默认 `~/.pi/agent/settings.json`）加 `"defaultTools": ["+tool_search"]`（`+` 前缀是增量修饰，保留 read/bash/edit/write 默认集）。注意独立 pi 下即便激活，工具功能仍依赖 taiji runtime handler（见上节「运行要求」）。
 
 ## 测试
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zhushanwen/pi-session-manager",
-  "version": "0.4.0",
-  "description": "Pi extension for managing agent-managed sessions — create, send, read history, list, status, abort via ctx.ui.select channel.",
+  "version": "0.6.0",
+  "description": "Pi extension for agent-managed sessions — create, message, monitor, abort, archive, and delete child sessions via ctx.ui.select channel.",
   "type": "module",
   "main": "index.ts",
   "pi": {
@@ -30,11 +30,10 @@
     "README.md"
   ],
   "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-notify-ledger-host": "0.3.5",
-    "@zhushanwen/subagent-core": "1.5.3"
+    "@zhushanwen/pi-extension-logger": "0.6.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",

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

@@ -1,22 +1,23 @@
 ---
 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 死亡通知、archive_session/delete_session 成功后 watch 收 exited/deleted 的收尾语义、未收到通知与 pending 残留的排查入口。触发词：session-manager、managed session、create_managed_session、send_to_session、archive_session、delete_session、完成通知没收到、通知未送达、notifyId、pending 列表有 session 条目、投递日志、delivery-port、managed-session-notify、willNotify、session-manager-ext-config。"
 ---
 
 # session-manager 使用与排查指南
 
-> @zhushanwen/pi-session-manager：agent-managed session 扩展。父 session 通过 6 个工具
+> @zhushanwen/pi-session-manager：agent-managed session 扩展。父 session 通过 8 个工具
 > （create_managed_session / send_to_session / read_session_history / list_my_sessions /
-> get_session_status / abort_session）以子 session 形态并行工作。本指南讲完成通知链、
-> 账本存储与排查入口；工具契约细节（marker 通道 / 超时分档）见包 README。
+> get_session_status / abort_session / delete_session / archive_session）以子 session 形态
+> 并行工作。本指南讲完成通知链、投递日志与排查入口；工具契约细节（marker 通道 /
+> 无 timeout 长挂语义）见包 README。
 
 ## 重要前提
 
 - 工具应答端是 taiji runtime 的 SessionManagerHandler——**只在 taiji 桌面环境可用**；
-  独立 pi CLI 无 handler 应答，所有工具等待至超时后报 `cancelled or timed out`。
-  工具失败时先确认运行环境，不要怀疑参数。
+  独立 pi CLI 无 handler 应答，所有工具长挂（hangs forever，不传 timeout）；通道取消/断开
+  报 `cancelled or channel error`。工具失败时先确认运行环境，不要怀疑参数。
 - 本扩展不读磁盘配置文件，无 config JSON——通知状态全部存储在 pi session 文件内
-  （见 B-ledger 一节），没有「改配置文件」这条路径。
+  （见投递日志一节），没有「改配置文件」这条路径。
 
 ## 完成通知链（notifyId → watch → managed-session-notify）
 
@@ -29,12 +30,13 @@ description: "使用或排查 @zhushanwen/pi-session-manager（agent-managed ses
    type: 'session', name = label}，由 pending-notifications 扩展消费落 pending 列表）+
    开 watch（fire-and-forget，不传 timeout，长挂等待 runtime 应答）。
 3. **watch 应答**：子 session 完成/死亡后 runtime 经 watch 通道回一条应答，reason 词表：
-   `completed` / `failed` / `stopped`（结果新闻）、`exited` / `deleted`（死亡新闻）、
+   `completed` / `failed` / `stopped`（结果新闻）、`exited` / `deleted`（死亡新闻——
+   archive_session / delete_session 工具成功后的收尾即产出这两种应答）、
    `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 +47,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` 留痕归因 |
 
 ## 工具速查
 
@@ -80,3 +84,5 @@ runtime 查得到时附 `Full transcript: <sessionFilePath>` 指针行。
 | `list_my_sessions` | 列本 agent 管理的 session（顺带回填 label 缓存，修复重启后的文案 label 降级） |
 | `get_session_status` | 查子 session 状态与模型信息 |
 | `abort_session` | 中止运行中的子 session（终态 stopped） |
+| `archive_session` | 归档收尾已完成的子 session（AI 可主动调用；生成中会话报错 archive_generating，先 abort 或等完成；成功后 open watch 收 'exited'，用户可从归档区恢复） |
+| `delete_session` | 彻底删除子 session（仅用户明示不可恢复删除时调用——USER-INITIATED ONLY；模糊整理词归 archive_session；成功后 open watch 收 'deleted'，不可恢复） |

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

@@ -12,8 +12,8 @@ import { expect, vi, type Mock } from "vitest";
 
 import registerExtension from "../../index.ts";
 
-/** registerTool 捕获的注册工具形态（execute 以六工具用例的固定五参形态调用） */
-export interface RegisteredTool { // oe-exempt:20260930:test:测试 harness 契约——多测试文件的断言面引用其字段类型
+/** registerTool 捕获的注册工具形态（execute 以八工具用例的固定五参形态调用） */
+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 }>;
 }
 
@@ -105,7 +105,7 @@ function findTool(h: Pick<ExtensionHarness, "registered">, name: string): Regist
 	return t;
 }
 
-/** 跑一次工具（callId/params 形态与六工具用例一致：双 undefined + harness ctx） */
+/** 跑一次工具（callId/params 形态与八工具用例一致：双 undefined + harness ctx） */
 export async function runToolCall(
 	h: Pick<ExtensionHarness, "registered" | "ctx">,
 	name: 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-error-handling.test.ts

@@ -1,7 +1,8 @@
 // tool-error-handling.test.ts — U5-A4: null/undefined returns → cancelled throw; exceptions → propagate;
-// {error} respond → throw（W4 throw 范式：pi agent-loop 仅在 execute throw 时置 isError:true——
-// pi-agent-core dist/agent-loop.js:453-483 executePreparedToolCall 正常 return 硬编码 isError:false；
-// 语义登记 PS-56）
+// {error} respond → throw（W4 throw 范式：execute throw → pi agent-loop catch 置 isError:true——
+// pi-agent-core dist/agent-loop.js executePreparedToolCall，1.0.0 实读 catch :581-588；1.0.0 起
+// 正常 return 的 isError 也被尊重（同文件 :579 `isError: result.isError === true`，0.84.4 才是
+// 硬编码 false）——本包失败恒走 throw，两版语义等价（语义登记 PS-56）
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { createToolHarness, expectToolRejects, runToolForText } from "./helpers/extension-harness.ts";
@@ -58,6 +59,23 @@ describe("U5-A4 tool-error-handling", () => {
 		);
 	});
 
+	it("runtime respond 携带 {error, code}（ArchiveError 码透传）→ throw 文本含结构化错误码（决策 5：archive_generating 对模型可见）", async () => {
+		await expectToolRejects(
+			createToolHarness(
+				vi.fn().mockResolvedValue(
+					JSON.stringify({
+						error: "会话正在生成中，无法归档 (sessionId=s1)",
+						code: "archive_generating",
+						hint: "abort first or wait for completion, then retry archive",
+					}),
+				),
+			),
+			"archive_session",
+			{ sessionId: "s1" },
+			/archive_generating/,
+		);
+	});
+
 	it("runtime respond 正常 JSON → 成功返回（不含 isError 字段）", async () => {
 		const result = await runToolForText(
 			createToolHarness(vi.fn().mockResolvedValue(JSON.stringify({ queued: true }))),
@@ -68,7 +86,7 @@ describe("U5-A4 tool-error-handling", () => {
 		expect(JSON.parse(result.content[0].text)).toEqual({ queued: true });
 	});
 
-	it("all 6 tools handle null gracefully（cancelled throw）", async () => {
+	it("all 8 tools handle null gracefully（cancelled throw）", async () => {
 		const { registered, ctx } = createToolHarness(vi.fn().mockResolvedValue(null));
 		for (const tool of registered) {
 			const params = tool.name === "create_managed_session"

package/src/__tests__/tool-non-json-response.test.ts

@@ -5,8 +5,10 @@
 // isError）——runtime 协议漂移对 agent 不可辨。D8
 //（docs/architecture/ext-simplify-17-shared-extraction.md §3.3，有意微变）统一为
 // 对齐 plugin-bridge 形态：logger.error 留痕（callMarkerRpc 原语经注入的 log 承担）
-// + 错误路径 throw（W4 范式：pi agent-loop 仅在 execute throw 时置 isError:true——
-// pi-agent-core dist/agent-loop.js:453-483，语义登记 PS-56）。
+// + 错误路径 throw（W4 范式：execute throw → pi agent-loop catch 置 isError:true——
+// pi-agent-core dist/agent-loop.js executePreparedToolCall，1.0.0 实读 catch :581-588；
+// 1.0.0 起正常 return 的 isError 也被尊重（同文件 :579，0.84.4 才硬编码 false），本包
+// 失败恒走 throw、两版语义等价（语义登记 PS-56）。
 
 import { describe, it, expect, vi, beforeEach } from "vitest";
 // logger mock helper 必须先于 extension-harness（其 import 链触发被 mock 模块加载）