@zhushanwen/extension-protocol 0.21.0 → 0.23.0

package/README.md

@@ -9,12 +9,12 @@ pi extension 跨层契约包：类型 + helper 函数 + 共享行为原语，零
   - `ask-user/` —— 富交互（select 通道 + marker）
   - `plan/` —— plan 生命周期状态机 + 审阅回传值域契约 + 旧 entry legacy 读取（纯函数零 pi 依赖，扩展 / runtime / renderer 三层共用）
   - `scheduler/` —— scheduler 任务条目契约 + entry 重放折叠（replayFoldEntries）+ 时间格式化（纯契约与纯函数，零 pi/node 依赖）
-  - `scheduler-create/` —— scheduler 创建确认共享资产（ScheduleDraft / ScheduleFormResult 类型 + 形状与时间折叠守卫 + marker）
+  - `scheduler-create/` —— scheduler 创建确认共享资产（ScheduleDraft / ScheduleFormResult 类型 + 形状与时间折叠检查 + marker）
   - `session-manager/` —— agent-managed session 嵌套 `{action, params}` 契约（select 通道 + marker）
   - `subagent-engine/` —— 引擎可发现性（`engines.json` 状态文件 + 引擎配置视图）
   - `subagent-inflight/` —— subagent 在途聚合上报（绝对计数报告 + marker，select 通道）
   - `subagent-notify/` —— subagent-workflow 通知通道 customType 常量唯一来源（workflow 结果 / 后台通知 / subagent 指令三类）
-  - `ui-form/` —— 统一提问表单协议（ask-user / scheduler / plan 三方提问统一入口：类型 + marker + 交互 helper + 守卫）
+  - `ui-form/` —— 统一提问表单协议（ask-user / scheduler / plan 三方提问统一入口：类型 + marker + 交互 helper + 检查）
   - 完整子协议清单以 `src/index.ts` 导出为准
 - `pending-entries` —— pending 事件流差集核心（register 去重 + unregister 抵消，纯算法）
 - `background-task` —— base-tool-enhance 后台任务 `registry.json` 文件契约

package/dist/{background-task-B6pdI5nq.d.ts → background-task-B53rQ-4Q.d.ts}

@@ -10,20 +10,26 @@
  *    字段注释），orphaned 终态由 runtime 写入（收殓下沉，设计
  *    docs/architecture/file-lock-unification-and-reaper-sink.md D2）。
  *
- * 目录布局（per-session 隔离）：
- *   <agentDir>/base-tool-enhance/<sessionId>/registry.json
- *   （agentDir = pi getAgentDir() 同源 dataDir，由调用方解析传入，不硬编码）
+ * 目录布局（per-session 隔离，session 存储树域 5）：
+ *   <dataDir>/ext-sessions/<sessionId>/background-tasks/registry.json
+ *   （shared 推导单点 = getSessionBackgroundTasksDir；写侧 extension 不 import
+ *   shared，以同公式镜像推导——SESSION_STORE_DIR_SEGMENT / BACKGROUND_TASKS_DIR_SEGMENT
+ *   段常量，字面量一致性由 scripts/check-artifact-dir-formula-sync.mjs 对拍守护）
  *
  * 字段名/语义/枚举值与写侧现状逐字段一致（基线：extensions/universal/
  * base-tool-enhance/src/background/types.ts + registry.ts），禁止在此单侧改名。
  */
-/** registry 文件名（<agentDir>/base-tool-enhance/<sessionId>/ 下）。 */
+/** registry 文件名（<dataDir>/ext-sessions/<sessionId>/background-tasks/ 下）。 */
 declare const BACKGROUND_TASK_REGISTRY_FILENAME: "registry.json";
-/** 后台任务根目录名（<agentDir>/ 下，内含 per-sessionId 子目录）。 */
+/**
+ * [遗留] 旧布局（<agentDir>/base-tool-enhance/<sessionId>/registry.json）的根目录名
+ * 段——换根到 session 存储树后布局不再经过该目录（现行布局见文件头「目录布局」），
+ * 仓内生产代码零消费（仅测试保活断言 + npm 出口 re-export 保留）；退役待出口面裁决。
+ */
 declare const BASE_TOOL_ENHANCE_DIRNAME: "base-tool-enhance";
 /**
  * 任务 id 前缀（taskId 契约注释已约定：bt- 前缀，对账差集只认该前缀——区别于
- * subagent-workflow 的 bg-/run-）。升级为导出常量：对账/守卫的前缀过滤从此引用
+ * subagent-workflow 的 bg-/run-）。升级为导出常量：对账/检查的前缀过滤从此引用
  * 同一常量，禁止各侧字面量重写。
  */
 declare const BACKGROUND_TASK_ID_PREFIX: "bt-";

package/dist/background-task-entry.d.ts

@@ -1,4 +1,4 @@
-import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './background-task-B6pdI5nq.js';
+import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './background-task-B53rQ-4Q.js';
 
 /**
  * 后台任务进程原语（pid 判活 / 进程树处置 / start time 身份判据）——跨端单一实现。
@@ -9,8 +9,8 @@ import { B as BackgroundTaskState, a as BackgroundTaskRegistryEntry } from './ba
  *  - runtime 侧：taiji background-task-reaper（孤儿收殓三分支判定），原实现在
  *    background-task-reaper.ts 原语区
  *
- * 分支语义（与 pi 实装对齐，勿单侧擅改）：Windows `taskkill /F /T`；POSIX 杀进程组
- * `kill -- -<pgid>`（后台任务 detached spawn 自成进程组，pgid = pid）；进程组杀不到时
+ * 分支语义（与 pi 实装对齐，勿单侧擅改）：Windows `taskkill /F /T`；POSIX 按进程组终止
+ * `kill -- -<pgid>`（后台任务 detached spawn 自成进程组，pgid = pid）；按进程组终止不到时
  * 回退单 pid + `pgrep -P` 递归杀残留子进程。
  *
  * 日志通道：本模块零日志依赖（protocol 零运行时依赖纪律）——回退路径的诊断经可选
@@ -31,7 +31,7 @@ type ProcessFallbackLogger = (step: string, err: unknown) => void;
 declare function isPidAlive(pid: number): boolean;
 /**
  * 杀整棵进程树（同步；收殓路径在 process.on("exit") 里跑，必须同步）。
- * POSIX 杀进程组（pgid = pid）一次性覆盖全部子孙；进程组杀不到（组长已死）回退
+ * POSIX 按进程组终止（pgid = pid）一次性覆盖全部子孙；按进程组终止不到（组长已死）回退
  * 单 pid + pgrep -P 递归清理残留子进程（先杀孙辈再杀子辈，防孙辈在父死后被
  * reparent 逃逸枚举）。Windows taskkill /F /T。幂等：目标已死时静默成功
  * （回退路径的诊断经 onFallback 上报，无回调则静默）。
@@ -93,7 +93,7 @@ declare function parseRegistryContent(raw: string): BackgroundTaskRegistryEntry[
 declare function corruptPathFor(registryPath: string): string;
 /**
  * 读取 registry 全量条目 + 损坏标记（runtime 现形态为超集；extension 侧 Map 形态
- * 由各侧薄壳投影）。UI 读侧需要区分「真的空表」与「损坏被隔离的空表」。
+ * 由各侧薄壳派生）。UI 读侧需要区分「真的空表」与「损坏被隔离的空表」。
  *
  * 文件不存在 / 读失败 → 空表 + corrupted:false（常态/降级，非损坏）；解析失败 →
  * 重命名 .corrupt 保留现场 + onLog warn + 空表 + corrupted:true（「空表重建」由

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { b as BACKGROUND_TASK_ID_PREFIX, c as BACKGROUND_TASK_REGISTRY_FILENAME, d as BACKGROUND_TASK_REGISTRY_VERSION, e as BASE_TOOL_ENHANCE_DIRNAME, f as BackgroundTaskEndReason, a as BackgroundTaskRegistryEntry, g as BackgroundTaskRegistryFile, B as BackgroundTaskState, M as MAX_TERMINAL_REGISTRY_ENTRIES, i as isActiveBackgroundTaskState, h as isBackgroundTaskRegistryEntry, j as isTerminalBackgroundTaskState } from './background-task-B6pdI5nq.js';
+export { b as BACKGROUND_TASK_ID_PREFIX, c as BACKGROUND_TASK_REGISTRY_FILENAME, d as BACKGROUND_TASK_REGISTRY_VERSION, e as BASE_TOOL_ENHANCE_DIRNAME, f as BackgroundTaskEndReason, a as BackgroundTaskRegistryEntry, g as BackgroundTaskRegistryFile, B as BackgroundTaskState, M as MAX_TERMINAL_REGISTRY_ENTRIES, i as isActiveBackgroundTaskState, h as isBackgroundTaskRegistryEntry, j as isTerminalBackgroundTaskState } from './background-task-B53rQ-4Q.js';
 
 /**
  * GUI 渲染协议核心类型定义。
@@ -168,7 +168,7 @@ type TreeItemIcon = 'arrow' | 'check' | 'cross' | 'circle' | 'dot' | 'pause' | '
 /**
  * 计划产物文档元数据——agent 调 register-doc 登记的一份产物。
  * version 由 extension 侧维护：修订后重写文档须重调 register-doc（version+1），
- * 前端凭 version 变化重拉 file.read 刷新渲染。
+ * 前端凭 version 变化重新拉取 file.read 刷新渲染。
  */
 interface PlanDocMeta {
     /** 文件名（drawer L2 文档 tab 标题，不含目录） */
@@ -184,7 +184,7 @@ interface PlanDocMeta {
  * submit-review 挂起审批时的 select payload（序列化为 options[0] JSON）。
  * extension 侧解析失败走 E5（logger.warn + tool result 报错提示重挂，垃圾数据不进对话流）。
  *
- * selfReview（自审结论，D9①③）：agent 提交审批前的自审摘要，投影面到审批请求帧为止
+ * selfReview（自审结论，D9①③）：agent 提交审批前的自审摘要，派生范围到审批请求帧为止
  * （不进 PlanStateView / session.planState 帧）；有界性由写侧 4KB 单点截断保证
  * （canonical 上限与截断 = src/extensions/plan/review-contract.ts，R3）。**optional 是兼容契约**：
  * 旧扩展不携带 → 宿主自审行不渲染的降级形态；submit-review 的必填硬门在 tool 层执行
@@ -197,7 +197,7 @@ interface PlanReviewRequest {
 /**
  * 审批三键裁决（D3）：approve 确认执行 / revise 提交修订（必带评论）/ dismiss 搁置
  * （非破坏：不杀 turn、不丢状态，计划进度保留）。revise 携带评论、approve/dismiss
- * 不携带（结构上不可混带）。值域守卫 canonical 版 = src/extensions/plan/review-contract.ts
+ * 不携带（结构上不可混带）。值域检查 canonical 版 = src/extensions/plan/review-contract.ts
  * （运行时判别 TS 穷尽性管不到——未知值域降级语义见该模块「降级双分源」）。
  */
 type PlanReviewDecision = 'approve' | 'revise' | 'dismiss';
@@ -295,7 +295,7 @@ declare function guiComponent<T extends GuiComponentType>(type: T, props: GuiCom
 /**
  * 设置 GUI widget。RPC 模式下用 marker 编码 GuiRenderResult JSON 进 string[]，
  * runtime event-adapter 检测 marker 解码为结构化 WS 帧（component + meta）。
- * 本函数无 isGui 守卫（仅查 ctx.ui?.setWidget 存在性），调用方需先判定
+ * 本函数无 isGui 检查（仅查 ctx.ui?.setWidget 存在性），调用方需先判定
  * isGuiCapable(ctx)——TUI 模式误调会把 marker 编码行推给原生 widget 造成乱码。
  *
  * meta（标题/状态/进度）由宿主壳层渲染成统一 head；extension 不再用 card 原语
@@ -303,12 +303,12 @@ declare function guiComponent<T extends GuiComponentType>(type: T, props: GuiCom
  */
 declare function guiSetWidget(ctx: GuiContext, key: string, result: GuiRenderResult | undefined): void;
 /**
- * [守卫单点化——本约束的说明全仓只写这一处，调用方不得再各自复写]
+ * [检查单点化——本约束的说明全仓只写这一处，调用方不得再各自复写]
  * 「isGuiCapable 外层判定不可省略，否则 TUI 误调 marker 乱码」：guiSetWidget 无
- * isGui 守卫（仅查 ctx.ui?.setWidget 存在性），TUI 模式误调会把 marker 编码行推
+ * isGui 检查（仅查 ctx.ui?.setWidget 存在性），TUI 模式误调会把 marker 编码行推
  * 给原生 widget 造成乱码。带双模内容的 widget 推送一律走 setWidgetDual，由本
  * helper 内化模式分派——消费方（todo/goal 及后续带 widget 的 extension）不再
- * 自持 isGui 判定与守卫注释。
+ * 自持 isGui 判定与检查注释。
  */
 /** 双模 widget 内容：按值立即构造两侧（构造均为廉价纯函数，成本可忽略）。 */
 interface DualWidgetContent {
@@ -322,8 +322,8 @@ interface DualWidgetContent {
  *  - content 为 undefined → 清屏 ctx.ui.setWidget(key, undefined)，模式无关
  *    （guiSetWidget 的清屏分支本就两臂同落 setWidget，判别是死分支）
  *  - 有内容 → isGuiCapable(ctx) ? guiSetWidget(gui) : setWidget(text)——TUI 分支
- *    推原生文本行，结构性不触达 marker（见上方守卫单点化说明）
- * hasUI 守卫留在调用方（goal FR-6.6 语义，本 helper 不感知）。
+ *    推原生文本行，结构性不触达 marker（见上方检查单点化说明）
+ * hasUI 检查留在调用方（goal FR-6.6 语义，本 helper 不感知）。
  */
 declare function setWidgetDual(ctx: GuiContext, key: string, content: DualWidgetContent | undefined): void;
 /** 拒绝原因（宿主 warn 文案与 fallback 分诊用；判定顺序同 validateWidgetIconPaths 实现）。 */
@@ -404,8 +404,9 @@ declare function firstContentText(result: {
  *   {action,params} / 快照帧，不引入内部 stringify 异常面）；
  * - mode 门控留调用方（inflight 在 attachSession 处 / session-manager 无门控——
  *   四态 reason 无 non-rpc 语义）；
- * - `ui.select` 缺席（非 GUI ctx）由调用方前置判定（沿 ask-user askUserInteract 的
- *   `isGuiCapable(ctx) && ctx.ui?.select` 先例）；误用即 throw 明确错误。
+ * - `ui.select` 缺席（非 GUI ctx）由调用方前置判定（沿已退役的 ask-user askUserInteract
+ *   先例——`isGuiCapable(ctx) && ctx.ui?.select`，git 历史可溯；isGuiCapable 现存于本包
+ *   core/helpers 并经包入口导出）；误用即 throw 明确错误。
  *
  * 设计权威源：docs/architecture/ext-simplify-17-shared-extraction.md §3.3 D8（v7 冻结形态）。
  */
@@ -429,15 +430,24 @@ interface MarkerRpcOptions {
 }
 /** 错误回包底层形状：select+marker 通道各协议（session-manager）
  * runtime 侧异常折叠的共用单源（不裸 reject，error 闭环走同一回包通道）。
- * SessionManagerErrorResult 是本形状的 alias（D8 单源化）。 */
+ * SessionManagerErrorResult 是本形状的 alias（D8 单源化）。
+ *
+ * `code`（session-manager-archive-delete U2，additive optional）：结构化错误码
+ * 透传通道（如 ArchiveError 的 `archive_generating`）——旧 runtime 不产出、旧
+ * extension 不消费，只加字段不破坏现有消费方。 */
 interface ChannelErrorResult {
     error: string;
     hint?: string;
+    code?: string;
 }
-/** 运行时形状守卫：{error: string}（hint 可选，不校验其类型；排数组） */
+/** 运行时形状检查：{error: string}（hint 可选，不校验其类型；code additive 宽容
+ * ——缺席放行（旧 runtime 兼容象限）、present 须为 string；排数组） */
 declare function isChannelErrorResult(v: unknown): v is ChannelErrorResult;
-/** error + hint 文本拼接（hint 缺席只回 error）——plugin-bridge errorResult 与
- * session-manager 错误闭环文本的共用单源 */
+/** error + code + hint 文本拼接（code/hint 缺席各自省略对应行）——plugin-bridge
+ * errorResult 与 session-manager 错误闭环文本的共用单源。code present 时以
+ * `error_code: <code>` 行拼入（session-manager-archive-delete 决策 5：结构化错误码
+ * 对模型可见——工具 description 教 agent 认的码词在 throw 文本里在场，善后层恢复
+ * 指引的第一跳不断链）；code 缺席（旧 runtime 回包 / canvas 等无码消费方）行为不变 */
 declare function formatChannelErrorText(err: ChannelErrorResult): string;
 /**
  * 经 select 通道发起一次 marker RPC。
@@ -537,7 +547,7 @@ declare function getAskUserAnswer(answers: AskUserAnswers, question: AskUserQues
 /** 从 answers 中提取 Other 自由文本 */
 declare function getAskUserOther(answers: AskUserAnswers, question: AskUserQuestion): string | undefined;
 /**
- * 类型守卫：验证 unknown 是否为合法的 AskUserQuestion。
+ * 类型检查：验证 unknown 是否为合法的 AskUserQuestion。
  * 供 legacy 帧消费方（runtime marker 分支侧形状参照 / 扩展自测）收窄 unknown[] 用。
  */
 declare function isAskUserQuestion(value: unknown): value is AskUserQuestion;
@@ -797,8 +807,8 @@ declare const SCHEDULE_CREATE_MARKER = "\0TAIJI_SCHEDULE_CREATE";
  * 交互入口在 extensions/universal/scheduler/src/tool.ts。
  *
  * 本模块保留三类跨端共享资产：
- * - isScheduleDraft / isScheduleFormResult 形状守卫：前者供 runtime event-adapter
- *   legacy 分支（SCHEDULE_CREATE_MARKER 帧 payload 判定）与 ui-form 守卫的
+ * - isScheduleDraft / isScheduleFormResult 形状检查：前者供 runtime event-adapter
+ *   legacy 分支（SCHEDULE_CREATE_MARKER 帧 payload 判定）与 ui-form 检查的
  *   schedule 分支（initial 深度校验）消费；后者供 scheduler 包回包判别
  *   （uiFormInteract answers[key] 解包后收窄为 ScheduleFormResult）。
  * - dateToOnceCron / onceCronToDate 时间折叠单点（D2）：GUI（ScheduleForm 渲染器）
@@ -810,13 +820,13 @@ declare const SCHEDULE_CREATE_MARKER = "\0TAIJI_SCHEDULE_CREATE";
  */
 
 /**
- * 类型守卫：验证 unknown 是否为合法的 ScheduleDraft。
+ * 类型检查：验证 unknown 是否为合法的 ScheduleDraft。
  * 用于 runtime event-adapter 判定 marker select 的 payload 是否为本协议 draft
  * （检测失败降级普通 select），以及前端从 runtime 透传值中安全收窄。
  * 字段白名单校验（与 isAskUserQuestion 同构）：可选字段校验类型，未知附加字段忽略。
  */
 declare function isScheduleDraft(value: unknown): value is ScheduleDraft;
-/** 回传形状守卫（导出消费：scheduler 包对 uiFormInteract answers[key] 解包值收窄；
+/** 回传形状检查（导出消费：scheduler 包对 uiFormInteract answers[key] 解包值收窄；
  *  FormOverlay schedule 渲染器提交的 value = JSON.stringify(ScheduleFormResult)） */
 declare function isScheduleFormResult(value: unknown): value is ScheduleFormResult;
 /**
@@ -829,14 +839,20 @@ declare function dateToOnceCron(date: Date): string;
 declare function onceCronToDate(cron: string, now?: Date): Date | null;
 
 /**
- * plan 模式生命周期状态机（plan 模式状态机显式化 D1）——纯数据 + 纯函数，零依赖。
+ * plan 模式生命周期状态机（plan 模式状态机显式化 D1）——8 值状态集 + 9 事件
+ * 边表的单一状态契约。表与判定迁移 @zhushanwen/state-machine 基建承载（M4）：
+ * 矩阵改行式声明 + errorPolicy:'result'（表外 `{ ok: false }` 不炸 turn）+ 原型链
+ * 白名单口径统一到机器 coerceState（域内枚举 includes 白名单先例被基建吸收，
+ * V10）；对外 `transition` / `derivePhase` 签名与返回形态保形（消费方零改动，
+ * 消费方清单 = consumers.md）。
  *
  * plan 模式的状态散落在 pi 扩展 entry / runtime 挂起注册表 / renderer 派生公式三处时，
  * 任意两者漂移即产「僵尸/谎言」UI（F1-F5）。本模块是全链路共享的单一状态契约：
- * 8 值状态集 + 9 事件边表 + `transition` 纯函数（守卫集中一处）+ `derivePhase` 呈现映射。
+ * 8 值状态集 + 9 事件边表 + `transition` 纯函数（检查集中一处）+ `derivePhase` 呈现映射。
  *
  * 语义要点（设计 D1 逐条锚定）：
- * - 非法转移返回 `{ ok: false }`，由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
+ * - 非法转移返回 `{ ok: false }`（机器 errorPolicy:'result' 的表外分支转译——不携带
+ *   next 键、不 throw），由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
  *   （effects-as-data 无已登记消费方属投机间接层），各 action 在转移成功后内联执行自身副作用。
  * - `reviewing --dismiss--> planning`：用户「搁置」（协议级 dismiss 决策，D3）——落盘即
  *   planning，被搁置的审批不复活（F1/F2/F3 构造性消除）。
@@ -850,17 +866,17 @@ declare function onceCronToDate(cron: string, now?: Date): Date | null;
  * - `approved --approve--> dispatching`：批准后 agent 再调 `complete` 重新选择执行方式
  *   （D1「approved 上 agent 再调 complete → dispatching」）。事件命名裁决：9 事件表无
  *   `complete` 员，本边取「执行确认」语义族最近员 `approve`（用户点确认执行与批准后重选
- *   执行方式同为「确认执行、进入执行方式选择」的决策事件）——消费面接线见 consumers.md。
+ *   执行方式同为「确认执行、进入执行方式选择」的决策事件）——消费方接线见 consumers.md。
  * - `approved` 其余转移仅 `exit`；活跃族非终态 `--exit--> exited`；idle 从未进入，
  *   exit 非法（防从未进 plan 的会话落噪音 exited entry）；终态 `--enter--> planning`
  *   （新一轮）；`revising` 保留独立态（E3 恢复文案分叉依赖，前提 P-7）。
  * - `reviewing --submit--> reviewing`：审批重挂自环（E3 会话重启恢复 / D8「重新提交审批」
  *   按钮——重提交不推进生命周期，落盘回 reviewing 重挂即等价于旧调用方特判放行形态）。
  *
- * 呈现映射（derivePhase）：用户视角四主态 + idle 缺省——四主态是呈现，不是存储
- * （用户口述模型 = 呈现层，reviewing/dispatching 两个挂起态是崩溃恢复的真实分叉点，
- * 存储层保留 8 值）。终态两值（completed = 批准并派发执行 / exited = 主动退出）共享
- * 全部终态规则，呈现层同映 'terminal'（诊断/审计语义保留存储区分）。
+ * 发布位次登记（D7③）：本包（@zhushanwen/extension-protocol）自 M4 起依赖
+ * @zhushanwen/state-machine（workspace 协议），npm 发布顺序必须基建包在先——
+ * 位次断链时 npm 消费者会装到缺依赖的 extension-protocol（changeset 依赖图
+ * 自然保证，发布 PR 人工核对本条）。
  */
 type PlanLifecycleState = 'idle' | 'planning' | 'reviewing' | 'revising' | 'approved' | 'dispatching' | 'completed' | 'exited';
 /** 状态穷举表（运行时消费：E3 恢复查表 / 测试穷举基座）——顺序 = 生命周期自然序。 */
@@ -875,19 +891,20 @@ type PlanTransitionResult = {
     ok: false;
 };
 /**
- * 纯函数转移：`(state, event) → { ok: true, next } | { ok: false }`。
+ * 纯函数转移：`(state, event) → { ok: true, next } | { ok: false }`——机器
+ * errorPolicy:'result' 判定的保形包装（签名与返回形态不变，消费方零改动）。
  *
  * 非法转移（含运行时垃圾 state/event 值——跨版本帧、坏反序列化）返回 `{ ok: false }`
  * 且**不携带 next 键**，由调用方降级（不 throw 炸 turn）。调用方义务：`ok:false` 时
- * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归口点的兜底保险）。
+ * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归属划分点的兜底保险）。
  *
- * 入口白名单守卫（与 derivePhase 同一机制）：普通对象字面量查表会沿原型链命中继承键——
- * `transition('reviewing', '__proto__')` 取出 Object.prototype、`('__proto__', 'valueOf')`
- * 取出函数，均被误判为合法 next（违背本契约）。故垃圾键必须先挡在查表前。
- * **选「枚举 includes 白名单」而非 null-prototype 表 / Object.hasOwn**：① transition 与
- * derivePhase 共用同一守卫形态（单一机制，不并存两种写法）；② PLAN_LIFECYCLE_STATES /
- * PLAN_LIFECYCLE_EVENTS 就是值域 SSOT（测试穷举同源），includes 判定与之同源，
- * 原型键天然不在白名单内。
+ * 垃圾输入的分层判定（原型链白名单口径已统一到基建 coerceState 的同族机制）：
+ * 词表外 state 由机器词表集合拒绝（Set 查询不走原型链）；词表外 event 字符串由
+ * 机器 (from, on) 行索引拒绝（Map 复合键查询不走原型链）；非字符串 event 由基建
+ * 归一 undefined 落入表外拒绝（§5.2 失败路径表第 3 行，不 crash），下方前置守卫
+ * 是域内显式等价拒绝（同结果先行返回，「不炸 turn」契约双保险）。plan 表无
+ * to:null 消亡行（基建 null 语义 = 实体离开机器，plan 8 态全在机器内），state 为
+ * null 的分支运行时不可达，收窄仅为类型完备。
  */
 declare function transition(state: PlanLifecycleState, event: PlanLifecycleEvent): PlanTransitionResult;
 /**
@@ -904,21 +921,22 @@ type PlanPhase = 'idle' | 'planning' | 'reviewing' | 'approved' | 'terminal';
  * 8 存储态 → 5 呈现相位的单点映射（renderer 阶段指示/状态带共用，禁止消费方各自 if 拼）。
  * 运行时垃圾 state（混装格坏帧）降级 'idle'（无 plan 缺省，fail-safe 不误示进行中）。
  *
- * 入口白名单守卫（理由同 transition，见彼处）：裸查表对继承键 'constructor' / 'toString'
- * 会取出 Object 构造函数等并经 `?? 'idle'` 流出（非 nullish 不落兜底）——垃圾 state
- * 必须精确落 'idle'，函数/对象不得作为相位流入 renderer。
+ * 入口白名单检查 = 机器 coerceState（原型链白名单口径统一到基建，V10）：裸查表对
+ * 继承键 'constructor' / 'toString' 会取出 Object 构造函数等并经 `?? 'idle'` 流出
+ * （非 nullish 不落兜底）——垃圾 state 必须精确落 'idle'，函数/对象不得作为相位
+ * 流入 renderer。
  */
 declare function derivePhase(state: PlanLifecycleState): PlanPhase;
 
 /**
- * plan 审阅回传值域契约（plan 模式状态机显式化 D3①⑤ / D9③）——纯函数守卫，零依赖。
+ * plan 审阅回传值域契约（plan 模式状态机显式化 D3①⑤ / D9③）——纯函数检查，零依赖。
  *
- * 为什么守卫是契约级承重：TS 判别联合的穷尽性（switch/never 断言）管不到运行时值域——
- * respond 通道透传的是任意字符串 parse 出的 unknown（P-2），值域守卫漏改即「搁置应答被判
- * 垃圾 → bad-response 引导重挂」再入循环（F1 复活路径）。canonical 守卫与判别联合同住
- * 契约包，消费面（extensions/universal/plan tool.ts）接线见同目录 consumers.md。
+ * 为什么检查是契约级承重：TS 判别联合的穷尽性（switch/never 断言）管不到运行时值域——
+ * respond 通道透传的是任意字符串 parse 出的 unknown（P-2），值域检查漏改即「搁置应答被判
+ * 垃圾 → bad-response 引导重挂」再入循环（F1 复活路径）。canonical 检查与判别联合同住
+ * 契约包，消费方（extensions/universal/plan tool.ts）接线见同目录 consumers.md。
  *
- * 降级双分源（D3①）——parse 失败必须区分两类（envelope 判别保留），消费面出口同款：
+ * 降级双分源（D3①）——parse 失败必须区分两类（envelope 判别保留），消费方出口同款：
  * - `unknown-decision`（对象合法但 decision 不在值域）：版本错配信号（R2），消费方
  *   额外 logger.warn 留痕；出口与文案与 malformed 同款——bad-response 报错提示重挂。
  *   裁决与重审触发（候选替代 = 恢复独立 version-mismatch 不重挂出口）登记于消费方
@@ -928,7 +946,7 @@ declare function derivePhase(state: PlanLifecycleState): PlanPhase;
  *
  * selfReview 有界字段（D9③ / R3）：有界性由**写侧单点截断**保证（截断点 = 扩展 payload
  * 构造处），4KB 上限与 UTF-8 字节界安全截断的唯一权威在本模块；透传层（runtime）不截、
- * 入站守卫不二次截（上限已在写侧达成）。
+ * 入站检查不二次截（上限已在写侧达成）。
  */
 
 /** selfReview 上限：4KB（UTF-8 字节）。超限即截（全文可要求 agent 贴对话流，R3）。 */
@@ -939,7 +957,7 @@ declare const PLAN_SELF_REVIEW_MAX_BYTES = 4096;
  */
 declare function truncateSelfReview(text: string): string;
 /**
- * `PlanReviewRequest` 形状守卫（E5 垃圾数据判据）：
+ * `PlanReviewRequest` 形状检查（E5 垃圾数据判据）：
  * docs 必为 `PlanDocMeta[]`（逐项形状）；selfReview 缺省或 string——**optional 是兼容契约**
  * （旧扩展不携带 → 自审行不渲染的降级形态，D9③），值域上限不在此拒绝（写侧截断已界）。
  * 空载荷（undefined/null/非对象/缺 docs）与非法形态（docs 非数组 / 元素形状不合法 /
@@ -966,19 +984,19 @@ type PlanReviewResponseEnvelope = {
     code: 'malformed';
 };
 /**
- * respond 回传解析（值域守卫的判别版）：dismiss 样本必通（D3 主干），未知 decision 值域
- * 落降级枚举而非垃圾（两类降级可判别分离；消费面出口同款引导重挂，见文件头「降级双分源」）。
+ * respond 回传解析（值域检查的判别版）：dismiss 样本必通（D3 主干），未知 decision 值域
+ * 落降级枚举而非垃圾（两类降级可判别分离；消费方出口同款引导重挂，见文件头「降级双分源」）。
  */
 declare function parsePlanReviewResponse(value: unknown): PlanReviewResponseEnvelope;
 /**
- * `PlanReviewResponse` 值域守卫（含 dismiss 员，D3①）——`parsePlanReviewResponse` 的谓词形。
+ * `PlanReviewResponse` 值域检查（含 dismiss 员，D3①）——`parsePlanReviewResponse` 的谓词形。
  * 消费方需要区分 unknown-decision / malformed 两类降级时用 parse 版。
  */
 declare function isPlanReviewResponse(value: unknown): value is PlanReviewResponse;
 
 /**
  * plan-state entry 的 customType（pi appendEntry custom entry 判别键）。磁盘形态冻结：
- * 扩展写读两侧（persistPlanState / isPlanStateEntry）与 runtime 投影链（plan-state-extractor /
+ * 扩展写读两侧（persistPlanState / isPlanStateEntry）与 runtime 派生视图链（plan-state-extractor /
  * session-records）均消费本常量，值同源——改值即历史会话全部失联，禁改（冻结锚测试见
  * 本目录 legacy-entries.test.ts）。
  */
@@ -986,8 +1004,8 @@ declare const PLAN_STATE_CUSTOM_TYPE = "plan-state";
 /**
  * 生命周期状态读取（D2 读方①②共用映射，原扩展 state.ts / runtime extractor 内联拷贝的
  * 单源归并）：
- * ① 新字段直读（值域守卫：PLAN_LIFECYCLE_STATES 之外的垃圾值按缺失处理，落映射——
- *    不信任外部写入）；
+ * ① 新字段直读（值域检查 = 机器 coerceState 归化，词表外/原型链键垃圾值按缺失处理，
+ *    落映射——不信任外部写入；M4 白名单口径统一）；
  * ② 旧 entry 无 state（或垃圾 state）时映射 reviewState（awaiting→reviewing /
  *    revising→revising / 其余值→planning|idle 按 isActive）。
  */
@@ -1008,7 +1026,7 @@ declare function readResumeHint(data: {
 /**
  * 统一提问表单协议（ui-form）的类型定义。
  *
- * 把 plan / scheduler / ask-user 三个 extension 的提问交互收口为一个表单协议：
+ * 把 plan / scheduler / ask-user 三个 extension 的提问交互收敛为一个表单协议：
  * 问题即数据（类型化问题集），GUI 链路统一（wire 协议 + 渲染器）——多问 = 多 tab，
  * 单问 = 单视图。extension 侧经 uiFormInteract() 序列化进 select 的 options[0]，
  * runtime event-adapter 检测 UI_FORM_MARKER 广播 form 帧，前端 FormOverlay
@@ -1131,7 +1149,7 @@ interface UiFormInteractOptions {
      * （undefined 为缺省态：存量扩展与未声明者，桥接 = 现状，方向安全）；
      * `false` = 无 turn 预期——命令 handler 内 select（提交后结构性无 turn），respond 侧
      * 提交即收尾，消除 30s 假忙。消费方判定必须是 `=== false` 显式式：truthy 简化
-     * （`!expectTurn`）会把 undefined 也当无 turn、误清桥接（D2 被否谱系）。
+     * （`!expectTurn`）会把 undefined 也当无 turn、误清桥接（D2 不采用其余方案的理由）。
      *
      * 缺省（undefined）经 stripUndefined 剥键——未声明者的 wire payload 逐字节不变，
      * 旧 runtime 读不到即忽略（JSON.parse 容忍未知键）。
@@ -1152,14 +1170,14 @@ interface UiFormInteractOptions {
 declare function uiFormInteract(ctx: GuiContext, form: FormQuestion[], opts?: UiFormInteractOptions): Promise<UiFormInteractResult>;
 
 /**
- * 统一提问表单（ui-form）的形状守卫。
+ * 统一提问表单（ui-form）的形状检查。
  *
  * isFormQuestion 按 type 判别分支逐项校验（白名单风格：必填字段类型校验、可选
  * 字段校验、未知字段忽略——与 isAskUserQuestion / isScheduleDraft 同构语义）。
  * 三个消费点失败策略各异（设计 D2）：
  * - 发送侧（uiFormInteract 内）：不合法项抛错（调用方编码 bug，fail-fast）；
  * - event-adapter：逐项过滤，合法项 ≥1 才产 form 帧、全不合法降级普通 select；
- * - renderer：复核守卫，不合法项跳过 + warn，全部不合法 → overlay 错误占位仅取消可点。
+ * - renderer：复核检查，不合法项跳过 + warn，全部不合法 → overlay 错误占位仅取消可点。
  *
  * isFormAnswers 校验回包形状（Record<string, string>）：键动态（key = header ??
  * question）无法枚举白名单，故只校验值域全 string；JSON 合法但非本形状由
@@ -1167,11 +1185,11 @@ declare function uiFormInteract(ctx: GuiContext, form: FormQuestion[], opts?: Ui
  */
 
 /**
- * 类型守卫：验证 unknown 是否为合法的 FormQuestion（choice / text / schedule 三分支）。
+ * 类型检查：验证 unknown 是否为合法的 FormQuestion（choice / text / schedule 三分支）。
  * 用于发送侧 fail-fast、event-adapter 逐项过滤与 renderer 复核（三消费点见文件头）。
  */
 declare function isFormQuestion(value: unknown): value is FormQuestion;
-/** 类型守卫：验证 unknown 是否为合法的 FormAnswers（值域全 string 的普通对象） */
+/** 类型检查：验证 unknown 是否为合法的 FormAnswers（值域全 string 的普通对象） */
 declare function isFormAnswers(value: unknown): value is FormAnswers;
 
 /**
@@ -1183,25 +1201,29 @@ declare function isFormAnswers(value: unknown): value is FormAnswers;
  */
 declare const SESSION_MANAGER_MARKER = "\0TAIJI_SESSION_MANAGER";
 /**
- * 7 个 action 的运行时集合（与 SessionManagerAction 类型同源——types.ts 从此派生）。
+ * 9 个 action 的运行时集合（与 SessionManagerAction 类型同源——types.ts 从此派生）。
  * event-adapter 用它把 JSON 解析出的 action 字符串收窄为联合类型，
  * 非法值折叠为 '__malformed__' 哨兵（与 handler default 分支同走 cancelled）。
  *
+ * 'delete' / 'archive'（session-manager-archive-delete U2）：终局操作双 action——
+ * delete 整树废纸篓不可恢复（USER-INITIATED ONLY，约束承载在 extension 工具文案层）、
+ * archive 归档退场可由用户恢复；扩展归属校验在 runtime handler 侧（协议层只定契约）。
+ *
  * 'watch'（notify-once D6）：通知债权的纯应答通道——单键 params={notifyId} 寻址、
  * 不传 timeout、fire-and-forget 长挂 select；必须在本集合内，否则 event-adapter
  * 把它折叠成 '__malformed__'（旧 runtime 兼容象限的静默降级形态），watch 永远到不了
  * handler 路由。
  */
-declare const SESSION_MANAGER_ACTIONS: readonly ["create", "send", "history", "status", "list", "abort", "watch"];
+declare const SESSION_MANAGER_ACTIONS: readonly ["create", "send", "history", "status", "list", "abort", "delete", "archive", "watch"];
 
 /**
  * session-manager extension 的类型定义。
  *
- * 7 个 action 的请求 params 和结果类型，供 handler 和 extension 共用。
+ * 9 个 action 的请求 params 和结果类型，供 handler 和 extension 共用。
  * marker 检测后按 action 分发到对应 handler 分支。
  */
 
-/** session-manager 支持的 7 个 action（从 SESSION_MANAGER_ACTIONS 集合派生，值与类型同源） */
+/** session-manager 支持的 9 个 action（从 SESSION_MANAGER_ACTIONS 集合派生，值与类型同源） */
 type SessionManagerAction = (typeof SESSION_MANAGER_ACTIONS)[number];
 /** 各 action 的请求参数映射 */
 interface SessionManagerParams {
@@ -1211,6 +1233,8 @@ interface SessionManagerParams {
     status: SessionManagerStatusParams;
     list: SessionManagerListParams;
     abort: SessionManagerAbortParams;
+    delete: SessionManagerDeleteParams;
+    archive: SessionManagerArchiveParams;
     watch: SessionManagerWatchParams;
 }
 /** create action 参数 */
@@ -1225,7 +1249,7 @@ interface SessionManagerCreateParams {
      * 完成通知债权的幂等键（optional，notify-once D2/D6）：extension 侧
      * `crypto.randomUUID()` 前缀 `sm-` 生成。缺省/畸形 → runtime 不 arm、
      * `willNotify:false`、零完成通知——兼容判据从版本二分改为字段有无。
-     * 形态判定不在 params 守卫（畸形不构成 params 错误、动作照常执行），
+     * 形态判定不在 params 检查（畸形不构成 params 错误、动作照常执行），
      * 由 runtime 受理点消费 `isSessionManagerNotifyId` 作 arm 判据。
      */
     notifyId?: string;
@@ -1253,10 +1277,27 @@ type SessionManagerListParams = Record<string, never>;
 interface SessionManagerAbortParams {
     sessionId: string;
 }
+/**
+ * delete action 参数（session-manager-archive-delete U2）：彻底删除目标会话
+ * （进程 + 历史 + 衍生数据整树废纸篓，不可恢复）。人身约束（USER-INITIATED ONLY）
+ * 承载在 extension 工具文案层，协议层只定契约。归属校验用扩展归属校验
+ * （含磁盘回退）在 runtime handler 侧执行。
+ */
+interface SessionManagerDeleteParams {
+    sessionId: string;
+}
+/**
+ * archive action 参数（session-manager-archive-delete U2）：归档目标会话——
+ * 退场进归档区、文件压缩搬移、可由用户恢复。生成中会话拒绝（错误码
+ * archive_generating 经 ChannelErrorResult.code 透传）。
+ */
+interface SessionManagerArchiveParams {
+    sessionId: string;
+}
 /**
  * watch action 参数（notify-once D2/D6）：通知债权的纯应答通道，**单键寻址**——
  * runtime 按 `(调用方 parentSid, notifyId)` 反查 claim，parentSid 取自调用方连接身份、
- * **协议面不定义不携带**（可推导字段免传，多余字段被守卫拒绝）。不传 timeout、
+ * **协议范围不定义不携带**（可推导字段免传，多余字段被检查拒绝）。不传 timeout、
  * fire-and-forget 长挂 select；每 claim 单 watch 槽（新覆盖旧，runtime 只 respond 最新）。
  */
 interface SessionManagerWatchParams {
@@ -1264,21 +1305,23 @@ interface SessionManagerWatchParams {
     notifyId: string;
 }
 declare function isSessionManagerNotifyId(v: unknown): v is string;
-/** create：字段可选 string + optional notifyId（类型面，sm- 形态判定归 arm 判据） */
+/** create：字段可选 string + optional notifyId（类型范围，sm- 形态判定归 arm 判据） */
 declare function isSessionManagerCreateParams(v: unknown): v is SessionManagerCreateParams;
-/** send：sessionId + prompt 必填，notifyId optional（类型面校验同 create） */
+/** send：sessionId + prompt 必填，notifyId optional（类型范围校验同 create） */
 declare function isSessionManagerSendParams(v: unknown): v is SessionManagerSendParams;
 /** history：sessionId 必填、tailTurns 可选 number */
 declare function isSessionManagerHistoryParams(v: unknown): v is SessionManagerHistoryParams;
-/** status / abort：sessionId 必填 */
+/** status / abort / delete / archive：sessionId 必填 */
 declare function isSessionManagerStatusParams(v: unknown): v is SessionManagerStatusParams;
 declare function isSessionManagerAbortParams(v: unknown): v is SessionManagerAbortParams;
+declare function isSessionManagerDeleteParams(v: unknown): v is SessionManagerDeleteParams;
+declare function isSessionManagerArchiveParams(v: unknown): v is SessionManagerArchiveParams;
 /** list：无参数（过滤由 handler 固化，params 不携带任何过滤字段） */
 declare function isSessionManagerListParams(v: unknown): v is SessionManagerListParams;
 /**
- * watch：**封闭单键** `{notifyId}` 守卫（notify-once D2 形态入站自检）——
+ * watch：**封闭单键** `{notifyId}` 检查（notify-once D2 形态入站自检）——
  * 空载荷 / 缺字段 / 夹带任何额外字段（如 parentSid：归属由 runtime 取连接身份，
- * 协议面不定义）/ notifyId 非 string / 形态不符（缺 `sm-` 前缀、非 UUID 体、超长）
+ * 协议范围不定义）/ notifyId 非 string / 形态不符（缺 `sm-` 前缀、非 UUID 体、超长）
  * → false → handler dispatch 抛错走 respond({error}) 错误闭环（error envelope）。
  * 形态函数与 lifetimeNotifyId 同一实现（防自检拒掉 runtime 生成的 lifetime watch）。
  */
@@ -1289,7 +1332,7 @@ interface SessionManagerCreateResult {
     status: 'created';
     modelId?: string;
     /**
-     * 完成通知债权是否已 arm（notify-once D6，LLM 契约面显式化）：create 无 prompt /
+     * 完成通知债权是否已 arm（notify-once D6，LLM 契约范围显式化）：create 无 prompt /
      * notifyId 缺省或畸形 → false（零完成通知）；true 时首次完成恰回一条通知。
      * 注意与 lifetimeNotifyId 正交——后者恒存在（死亡通知与债权无关）。
      */
@@ -1345,6 +1388,24 @@ interface SessionManagerSessionSummary {
 interface SessionManagerAbortResult {
     success: boolean;
 }
+/**
+ * delete 结果（session-manager-archive-delete U2）：字段名以设计 §3.1 交互样例为权威
+ * ——成功回包 `{sessionId, deleted:true}`。侧栏消失 + 整树废纸篓由 runtime delete 链
+ * 内建，协议回包只做完成陈述。
+ */
+interface SessionManagerDeleteResult {
+    deleted: true;
+    sessionId: string;
+}
+/**
+ * archive 结果（session-manager-archive-delete U2）：字段名以设计 §3.1 交互样例为权威
+ * ——成功回包 `{sessionId, archived:true}`。归档成功后该会话全部通知债权由 runtime
+ * handler 三步收尾统一应答 'exited'（协议范围外，契约属 handler 编排）。
+ */
+interface SessionManagerArchiveResult {
+    archived: true;
+    sessionId: string;
+}
 /**
  * watch 应答 reason 词表（封闭 7 值）——与 pending-entries `mapReasonToStatus` 的
  * 4 个新 case 同词形（stopped→aborted、exited/deleted/orphaned→cancelled），
@@ -1365,15 +1426,15 @@ type SessionManagerWatchReason =
  * 折叠 cancelled——null 不在本类型内，消费方须同时处理。
  */
 interface SessionManagerWatchRespondPayload {
-    /** 分拣键 (sessionId, reason) 的 reason 腿（D3 两层模型：cancelled/orphaned → 仅
+    /** 分拣键 (sessionId, reason) 的 reason 路径（D3 两层模型：cancelled/orphaned → 仅
      *  unregister；exited/deleted → 死亡新闻槽；completed/failed/stopped → 结果新闻） */
     reason: SessionManagerWatchReason;
     /**
      * claim 所属子会话 id 回带——D3 槽键 (sessionId, deathSeq) / 分拣键 (sessionId,
-     * reason) / D9 文案 `<sid>` 的唯一数据源（收口腿闭包仅有父 sid，缺此字段则同父
+     * reason) / D9 文案 `<sid>` 的唯一数据源（收敛路径闭包仅有父 sid，缺此字段则同父
      * 多子 deathSeq 跨 child 碰撞）。claim 命中路径（settle/death/orphaned/二次校验）
      * 恒带；fail-closed（查无 claim）无 claim 可回带 → 缺席——该路径 reason 恒
-     * 'cancelled'，extension 静默收口不消费 sessionId。
+     * 'cancelled'，extension 静默收尾不消费 sessionId。
      */
     sessionId?: string;
     /** death 批身份（per session 递增；同一死亡事件循环 respond 时 runtime 直供） */
@@ -1382,7 +1443,7 @@ interface SessionManagerWatchRespondPayload {
     settleSeq?: number;
     /** 本批兑现总笔数（同批每条应答携带同值）；death 侧 = 同 deathSeq 的 claim 数（D3 合批口径，runtime 直供，死亡/结果新闻正文消费 fulfills N） */
     fulfillsN?: number;
-    /** death 应答携带：exit 腿诊断数据通路复刻（400 字截尾沿用现值），extension 文案构造消费 */
+    /** death 应答携带：exit 路径诊断数据通路复刻（400 字截尾沿用现值），extension 文案构造消费 */
     exitCode?: number | null;
     stderrTail?: string;
     /**
@@ -1393,7 +1454,7 @@ interface SessionManagerWatchRespondPayload {
     sessionFilePath?: string;
 }
 /**
- * watch respond payload 运行时守卫（extension 读侧不信任外部格式——AGENTS 关键规则 5）：
+ * watch respond payload 运行时检查（extension 读侧不信任外部格式——AGENTS 关键规则 5）：
  * null（旧 runtime 象限）/ 非 record / reason 缺失、非 string 或词表外 / 可选 meta
  * 类型不符 → false（可选字段缺席一律放行——含 sessionFilePath）。消费方对 false 与
  * null 同路折叠静默 unregister（fail-safe：未知 reason 不得落 default 误标）。
@@ -1408,7 +1469,7 @@ type SessionManagerErrorResult = ChannelErrorResult & {
 };
 
 /**
- * subagent 在途上报的类型定义（u7a 协议面）。
+ * subagent 在途上报的类型定义（u7a 协议范围）。
  *
  * 契约两端：
  *   - 写侧（生产）：@zhushanwen/pi-subagent-workflow 壳层（src/host/inflight-reporter.ts）
@@ -1452,12 +1513,12 @@ interface SubagentInFlightReport {
  */
 declare const INFLIGHT_REPORT_ACK: "{\"ack\":true}";
 /**
- * SubagentInFlightReport 形状守卫：inFlight 非负整数、emittedAt 数字、sessionId
+ * SubagentInFlightReport 形状检查：inFlight 非负整数、emittedAt 数字、sessionId
  * 缺席或 string。event-adapter（u7b）路由分支消费；非法帧返回 false（调用方丢弃，
  * 不抛错不镜像）。
  */
 declare function isSubagentInFlightReport(v: unknown): v is SubagentInFlightReport;
-/** 确认回包形状守卫（pi 侧 reporter 消费——非本字符串即未确认，折叠重试）。 */
+/** 确认回包形状检查（pi 侧 reporter 消费——非本字符串即未确认，折叠重试）。 */
 declare function isInFlightReportAck(v: unknown): v is typeof INFLIGHT_REPORT_ACK;
 
 /**
@@ -1470,12 +1531,12 @@ declare function isInFlightReportAck(v: unknown): v is typeof INFLIGHT_REPORT_AC
  * 与 ASK_USER_MARKER / SESSION_MANAGER_MARKER / BRIDGE_MARKER 同理。
  *
  * 设计权威源：docs/architecture/crash-forensics-and-watchdog.md §3.3 D5
- * 「在途判定谓词 + 求值位置」——extension 聚合上报通道的协议面（u7a）。
+ * 「在途判定谓词 + 求值位置」——extension 聚合上报通道的协议范围（u7a）。
  */
 declare const SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
 
 /**
- * journal 事件推送的类型定义（event-push-channel 协议面）。
+ * journal 事件推送的类型定义（event-push-channel 协议范围）。
  *
  * 契约两端：
  *   - 写侧（生产）：@zhushanwen/pi-subagent-workflow 壳层（src/host/journal-reporter.ts）
@@ -1537,12 +1598,12 @@ interface SubagentJournalReport {
  */
 declare const JOURNAL_REPORT_ACK: "{\"ack\":true}";
 /**
- * SubagentJournalReport 形状守卫：domain 落两域词表、fileKey 非空串、events 逐条
- * 过信封守卫、sessionId 缺席或 string。event-adapter 路由分支消费；非法帧返回
+ * SubagentJournalReport 形状检查：domain 落两域词表、fileKey 非空串、events 逐条
+ * 过信封检查、sessionId 缺席或 string。event-adapter 路由分支消费；非法帧返回
  * false（调用方丢弃，不 fold 不 ack）。
  */
 declare function isSubagentJournalReport(v: unknown): v is SubagentJournalReport;
-/** 确认回包形状守卫（pi 侧 reporter 消费——非本字符串即未确认）。 */
+/** 确认回包形状检查（pi 侧 reporter 消费——非本字符串即未确认）。 */
 declare function isJournalReportAck(v: unknown): v is typeof JOURNAL_REPORT_ACK;
 
 /**
@@ -1564,7 +1625,7 @@ declare const SUBAGENT_JOURNAL_MARKER = "\0TAIJI_SUBAGENT_JOURNAL";
  * subagent-workflow 通知通道的 custom_message customType 词表（单源）。
  *
  * 契约两端（值逐字节依赖，改名 = 跨侧破坏性变更）：
- *   - 写侧：@zhushanwen/pi-subagent-workflow extension（workflow 收口通知 / bg-notify
+ *   - 写侧：@zhushanwen/pi-subagent-workflow extension（workflow 收敛通知 / bg-notify
  *     送达 / 定向消息留痕，经 pi.sendMessage 落 custom_message entry 进 session JSONL）
  *     与 @zhushanwen/subagent-core（notifier 送达 + notify ledger 默认通道）；
  *   - 读侧：taiji 三层——@taiji/shared（COMPLETE_NOTIFY_CUSTOM_TYPES display 覆写
@@ -1579,7 +1640,7 @@ declare const SUBAGENT_JOURNAL_MARKER = "\0TAIJI_SUBAGENT_JOURNAL";
  * worker-script-builder 的 postMessage 帧 type）是同名不同域——那是引擎进程内 RPC 形状，
  * 不跨 pi session 边界，不进本词表。
  */
-/** workflow run 收口通知的送达 customType。runtime event-interpreter 按它识别 run 完成
+/** workflow run 收敛通知的送达 customType。runtime event-interpreter 按它识别 run 完成
  *  并驱动 W18 workflow-record 失效信号；shared 完成通知 display 覆写集合亦按它收录。
  *  与 SUBAGENT_BG_NOTIFY_CUSTOM_TYPE 通道互斥（互用会让失效信号误判通道语义）。 */
 declare const WORKFLOW_RESULT_CUSTOM_TYPE: "workflow-result";
@@ -1656,10 +1717,11 @@ interface SubagentEngineConfigView {
  *   per-action × actor 权限矩阵按此建制（matrix.ts）。
  * - CANVAS_MARKER_ACTIONS（16 + 'enter'）：marker 通道（extension select 挂起）
  *   的 action 域。'enter' 是 canvas_enter 工具「打开已有画布」形态的通道动作：
- *   读全量 + 登记绑定（sessionId ↔ canvasId），非画布 mutation——不产事件、
+ *   读全量（归属校验在 readState，非 owner → forbidden）；回推对象 = 归属会话
+ *   本身（owner 持久在落盘路径），无登记动作、不产事件——非画布 mutation、
  *   不在权限矩阵内（marker 通道调用方恒为 agent 工具）。创建形态走 'create'
- *   （marker 通道的 create 只可能来自 canvas_enter 工具，runtime 在该通道
- *   create 成功时一并登记绑定；GUI 托盘新建走 WS RPC 通道、不登记绑定）。
+ *   （marker 通道的 create 只可能来自 canvas_enter 工具；GUI 托盘新建走 WS RPC
+ *   通道，两通道行为无分叉）。
  */
 /**
  * canvas 工具请求的 title marker。runtime event-adapter / CanvasHandler 检测此
@@ -1846,6 +1908,14 @@ interface ReviewReport {
 /** 画布状态（聚合 1 全量投影；canvas.get reply 与 canvas.json 快照共用形状）。 */
 interface CanvasState {
     canvasId: string;
+    /**
+     * 归属会话 id（画布归属 = 创建它的 session，1:N——一个 session 可有多张画布）。
+     * 归属即落盘路径（`<dataDir>/ext-sessions/<ownerSessionId>/canvases/<canvasId>/`），
+     * 路径即归属的构造性承载：该字段由 runtime 从落盘路径推导填充（服务层唯一写入点），
+     * 领域事件流不承载归属（CanvasCreated 事件 data 不含 sessionId——事件流内容与格式
+     * 不随布局反转变化，只挪位置）；跨会话访问按本字段归属校验拒绝（forbidden）。
+     */
+    ownerSessionId: string;
     /** 画布名（canvasId = 短随机 id；重命名属第二版多画布管理，MVP 只读）。 */
     name: string;
     /** 根问题三要素（不变量 1：有且仅有一个根节点，类型 question，带完成判据与范围排除）。 */
@@ -1895,9 +1965,12 @@ interface CanvasState {
 }
 /** canvas.list 条目：托盘画布列表的数据源（名称 + 阶段徽标 + must-fix 计数）。
  * 阶段徽标本身是 renderer 派生值（开放 must-fix 或审查进行中 = 审查中；
- * converged = 已收敛；其余 = 生长中），契约只给派生输入。 */
+ * converged = 已收敛；其余 = 生长中），契约只给派生输入。清单按请求 sessionId
+ * 过滤（只返回归属该会话的画布），ownerSessionId 即过滤判据的回显。 */
 interface CanvasListEntry {
     canvasId: string;
+    /** 归属会话 id（= 请求的过滤 sessionId；语义同 CanvasState.ownerSessionId）。 */
+    ownerSessionId: string;
     name: string;
     statement: string;
     converged: boolean;
@@ -1960,17 +2033,18 @@ interface CanvasError {
     recover: string;
 }
 /**
- * 错误码词表（封闭 15 值）。分组：
+ * 错误码词表（封闭 16 值）。分组：
  * - 寻址 / 形状：canvas_not_found / node_not_found / edge_not_found /
  *   invalid_params / unknown_action
- * - 权限：actor_not_allowed（矩阵表外组合 fail-fast）
+ * - 权限：actor_not_allowed（矩阵表外组合 fail-fast）/ forbidden（画布不属当前会话——
+ *   归属校验拒绝，画布归属 = 创建它的 session，跨会话访问一律结构化拒绝）
  * - 不变量拦截：selection_conflict（不变量 3 双选定）/ cycle_detected（不变量 2 成环）/
  *   unverified_fact（不变量 5）/ dispatch_blocked（不变量 7）/ not_converged（不变量 10）/
  *   lifecycle_transition_illegal（状态机表外转移）
  * - 审查聚合：entry_ref_missing（聚合 2 不变量 1）/ already_resolved（first-writer-wins）/
  *   review_max_rounds（轮次上限后再发起）
  */
-declare const CANVAS_ERROR_CODES: readonly ["canvas_not_found", "node_not_found", "invalid_params", "unknown_action", "actor_not_allowed", "selection_conflict", "cycle_detected", "unverified_fact", "dispatch_blocked", "not_converged", "lifecycle_transition_illegal", "entry_ref_missing", "already_resolved", "review_max_rounds", "edge_not_found"];
+declare const CANVAS_ERROR_CODES: readonly ["canvas_not_found", "node_not_found", "invalid_params", "unknown_action", "actor_not_allowed", "forbidden", "selection_conflict", "cycle_detected", "unverified_fact", "dispatch_blocked", "not_converged", "lifecycle_transition_illegal", "entry_ref_missing", "already_resolved", "review_max_rounds", "edge_not_found"];
 type CanvasErrorCode = (typeof CANVAS_ERROR_CODES)[number];
 /**
  * 每码一句恢复动作文案（SSOT；runtime 构造 CanvasError 时 recover 字段取此处
@@ -2159,7 +2233,10 @@ interface CanvasReadParams {
     /** 子树读取：从该节点 id 向下的主干子树；缺省读全量。 */
     subtree?: string;
 }
-/** list：无参数（全量画布清单；过滤无字段——Record 结构性拒绝夹带）。 */
+/** list：无参数（全量画布清单的 action 侧形状——归属过滤字段不在共享 params 内：
+ * sessionId 是**通道级字段**（WS payload 携带、marker 通道由 dispatch 上下文的发起
+ * 会话注入，与 canvas.mutate 的 actor/sessionId 同款通道字段模式），runtime 按归属
+ * 会话过滤（D4 裁决 3）。Record 结构性拒绝夹带任何过滤字段）。 */
 type CanvasListParams = Record<string, never>;
 /** 16 action 的 params 映射（SSOT；两通道共用——WS RPC 与 marker 的 params 同构）。 */
 interface CanvasActionParams {
@@ -2189,7 +2266,7 @@ type CanvasMutateRequest = {
     };
 }[CanvasAction];
 type CanvasMarkerAction = (typeof CANVAS_MARKER_ACTIONS)[number];
-/** enter（canvas_enter 打开形态）：读全量 + 登记绑定；非画布 mutation、不产事件。 */
+/** enter（canvas_enter 打开形态）：读全量（归属校验在 readState，非 owner → forbidden）；非画布 mutation、不产事件、无登记动作。 */
 interface CanvasEnterParams {
     canvasId: string;
 }
@@ -2234,7 +2311,8 @@ declare function isCanvasConvergeCheckParams(v: unknown): v is CanvasConvergeChe
 declare function isCanvasExportParams(v: unknown): v is CanvasExportParams;
 declare function isCanvasDispatchParams(v: unknown): v is CanvasDispatchParams;
 declare function isCanvasReadParams(v: unknown): v is CanvasReadParams;
-/** list：无参数——Record 结构性拒绝夹带任何过滤字段（session-manager list 同款）。 */
+/** list：无参数——Record 结构性拒绝夹带任何过滤字段（session-manager list 同款；
+ * 归属过滤字段是通道级的，见 CanvasListParams 注释）。 */
 declare function isCanvasListParams(v: unknown): v is CanvasListParams;
 /** enter（canvas_enter 打开形态）：封闭单键 canvasId。 */
 declare function isCanvasEnterParams(v: unknown): v is CanvasEnterParams;
@@ -2308,7 +2386,7 @@ declare function allCanvasActions(): readonly CanvasAction[];
  * 契约两端（此前各持一份同构差集实现，对齐手段是注释）：
  *  - extension 侧：@zhushanwen/pi-base-tool-enhance 对账（原 collectUnsettledTaskIds：
  *    session_start 时对「entries 显示活跃但任务已终态」的 bt- 任务补写注销）
- *  - extension 侧：@zhushanwen/pi-pending-notifications 守卫判据（原
+ *  - extension 侧：@zhushanwen/pi-pending-notifications 检查判据（原
  *    scanPendingEntries + filterActiveRegisters；其 types/currentSessionId/normalize
  *    过滤是 pending 产品语义，留在 pending 侧，不在本模块）
  *
@@ -2328,19 +2406,48 @@ interface CollectPendingIdsOptions {
     /** 只保留该前缀的 id（如 'bt-'）；缺省不过滤。 */
     idPrefix?: string;
 }
-/** scanPendingEntries 的结果：register 原始 data 列表 + 已注销 id 集合。 */
+/** scanPendingEntries 的结果：register 原始 data 列表 + 已注销 id 集 + collect 字段映射视图。 */
 interface PendingEntriesScan {
     registerEntries: Array<{
         data: Record<string, unknown>;
     }>;
     unregisteredIds: Set<string>;
+    /**
+     * register 首见字段视图（MF-2-1 单点）：id → type（string 才收，原样透传——归一化
+     * 归消费方）。首见规则 = 首条 register 胜出：同 id 重复条目不覆盖；首条无 type
+     * 则该 id 恒无映射（不被后续重复条目补位——与 applyPendingDiff 的首条 data 语义
+     * 同口径，工具侧旧「首条带 type 胜出」的补位行为是漂移，收敛时已废除）。
+     */
+    registerTypes: Map<string, string>;
+    /**
+     * 注销条目 status 视图：id → status（写侧经 mapReasonToStatus 已映射落盘）。仅收
+     * MAPPED_PENDING_STATUSES 成员（词表外/畸形不收，不虚构终态）；同 id 多条注销取
+     * 末次合法值（后条非法不抹除前条合法值）。
+     */
+    unregisterStatuses: Map<string, MappedPendingStatus>;
 }
 /**
  * 单趟扫描 entries 按 customType 分流（容错对齐 pending 侧 S-10：null/非对象
- * 元素先守卫再访问字段）。register 侧不校验 id（合法性判定归差集层）；unregister
- * 仅收 string id。data 用最小结构类型 Record<string, unknown>，消费方自行窄化。
+ * 元素先检查再访问字段）。register 侧 registerEntries 不校验 id（合法性判定归差集
+ * 层）；unregister 仅收 string id。data 用最小结构类型 Record<string, unknown>，
+ * 消费方自行窄化。字段映射视图（registerTypes / unregisterStatuses）顺路产出：
+ * collect 链路的 type/outcome 映射规则单点在本次扫描（delivery-port 快照基线与
+ * pending-notifications 终局回填此前各持一份同构扫描器且首见语义已分歧，MF-2-1
+ * 收敛——消费方禁止本地复制映射段）。
  */
-declare function scanPendingEntries(entries: unknown[]): PendingEntriesScan;
+declare function scanPendingEntries(entries: readonly unknown[]): PendingEntriesScan;
+/** scanPendingFields 的结果：collect 链路消费的字段映射投影（首见 type + 注销 status）。 */
+interface PendingFieldsScan {
+    registerTypes: Map<string, string>;
+    unregisterStatuses: Map<string, MappedPendingStatus>;
+}
+/**
+ * collect 终局回填的字段视图（MF-2-1 单点入口）：scanPendingEntries 产物中
+ * register 首见 type + 全部注销 status 的 MAPPED 成员投影。消费方（delivery-port
+ * 快照基线 / pending-notifications consume 后回填）按 id 查表补 type/outcome，
+ * 查无保持 undefined（诚实缺省，不虚构终态）。
+ */
+declare function scanPendingFields(entries: readonly unknown[]): PendingFieldsScan;
 /**
  * 差集本体（规则单点）：register 首见去重 + unregister 全局抵消 + id 非法跳过。
  * 首见判定先于任何消费方过滤（seen.add 后即使调用方对首个 data 过滤丢弃，后续
@@ -2382,5 +2489,14 @@ declare function collectActivePendingIds(entries: unknown[], opts?: CollectPendi
  * 字面量联合锁定值域，switch 分支编译期受限。 */
 type MappedPendingStatus = 'completed' | 'failed' | 'cancelled' | 'expired' | 'time_limited' | 'aborted';
 declare function mapReasonToStatus(reason: string): MappedPendingStatus;
+/**
+ * MappedPendingStatus 的值集（MF-1-5 词表单源）：由 REASON_STATUS_MAP 派生——映射表
+ * 演化（新增 reason / 改映射目标）时值集构造性跟随，无第二份手工词表可漂移。消费方
+ * （delivery-port / pending-notifications 读取侧）按成员资格判定落盘 status 合法性时
+ * import 本常量，禁止本地复制六值 Set（曾两包各持一份本地拷贝注释自认「同步维护」）。
+ * Set 成员与 MappedPendingStatus 联合的相等性由 pending-entries.test.ts 断言锁定。
+ * string 元素类型是消费面要求（对任意落盘 status 做成员判定，窄化前的原始值）。
+ */
+declare const MAPPED_PENDING_STATUSES: ReadonlySet<string>;
 
-export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerCreateParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };
+export { ACTION_EVENT_MAP, ASK_USER_MARKER, type ArgumentMateriality, type ArgumentPolarity, type AskUserAnswers, type AskUserOption, type AskUserQuestion, CANVAS_ACTIONS, CANVAS_ACTOR_MATRIX, CANVAS_ERROR_CODES, CANVAS_ERROR_RECOVERY, CANVAS_EVENT_TYPES, CANVAS_MARKER, CANVAS_MARKER_ACTIONS, CANVAS_TOOL_NAMES, type CanvasAction, type CanvasActionParams, type CanvasActor, type CanvasComment, type CanvasCommentParams, type CanvasCommentRespondParams, type CanvasConvergeCheckParams, type CanvasCreateParams, type CanvasDecideDirectionParams, type CanvasDirectionDecision, type CanvasDispatchParams, type CanvasEdge, type CanvasEdgeType, type CanvasEnterParams, type CanvasError, type CanvasErrorCode, type CanvasEventType, type CanvasExportParams, type CanvasExportTarget, type CanvasGrowItem, type CanvasGrowParams, type CanvasListEntry, type CanvasListParams, type CanvasListReply, type CanvasMarkerAction, type CanvasMarkerParams, type CanvasMarkerRequest, type CanvasMutateReply, type CanvasMutateRequest, type CanvasNode, type CanvasNodeLifecycle, type CanvasNodeType, type CanvasPatchParams, type CanvasReadParams, type CanvasReadReply, type CanvasReviewAppendParams, type CanvasReviewEntryInput, type CanvasReviewRequestParams, type CanvasReviewResolveParams, type CanvasSelectParams, type CanvasState, type CanvasToolName, type CanvasTransitionParams, type ChannelErrorResult, type ChoiceQuestion, type CollectPendingIdsOptions, type DualWidgetContent, type ExecutionRecord, type FormAnswers, type FormOption, type FormQuestion, GUI_WIDGET_MARKER, type GuiComponent, type GuiComponentProps, type GuiComponentType, type GuiContext, type GuiRenderResult, HISTORY_LIMIT, INFLIGHT_REPORT_ACK, JOURNAL_REPORT_ACK, MAPPED_PENDING_STATUSES, MS_PER_DAY, MS_PER_HOUR, MS_PER_MINUTE, MS_PER_SECOND, type MappedPendingStatus, type MarkerRpcOptions, type MarkerRpcResult, NON_TOOL_ACTIONS, PENDING_REGISTER_ENTRY_TYPE, PENDING_UNREGISTER_ENTRY_TYPE, PLAN_LIFECYCLE_EVENTS, PLAN_LIFECYCLE_STATES, PLAN_REVIEW_MARKER, PLAN_SELF_REVIEW_MAX_BYTES, PLAN_STATE_CUSTOM_TYPE, PROTOCOL_VERSION, type PendingEntriesScan, type PendingFieldsScan, type PlanDocMeta, type PlanLifecycleEvent, type PlanLifecycleState, type PlanPhase, type PlanReviewComment, type PlanReviewDecision, type PlanReviewRequest, type PlanReviewResponse, type PlanReviewResponseEnvelope, type PlanTransitionResult, type ReplayFoldOptions, type ReviewDimension, type ReviewEntry, type ReviewReport, type ReviewReportStatus, type ReviewResolutionDisposition, type ReviewSeverity, SCHEDULER_MODAL_VIEW_ID, SCHEDULE_CREATE_MARKER, SESSION_MANAGER_ACTIONS, SESSION_MANAGER_MARKER, SUBAGENTS_ENGINES_FILENAME, SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, SUBAGENT_DIRECTIVE_CUSTOM_TYPE, SUBAGENT_INFLIGHT_MARKER, SUBAGENT_JOURNAL_MARKER, type ScheduleDraft, type ScheduleFormResult, type ScheduleKind, type ScheduleQuestion, type ScheduleSpec, type ScheduledTask, type SchedulerEntryLike, type SchedulerEntryOp, type SessionManagerAbortParams, type SessionManagerAbortResult, type SessionManagerAction, type SessionManagerArchiveParams, type SessionManagerArchiveResult, type SessionManagerCreateParams, type SessionManagerCreateResult, type SessionManagerDeleteParams, type SessionManagerDeleteResult, type SessionManagerErrorResult, type SessionManagerHistoryParams, type SessionManagerHistoryResult, type SessionManagerListParams, type SessionManagerListResult, type SessionManagerParams, type SessionManagerSendParams, type SessionManagerSendResult, type SessionManagerSessionSummary, type SessionManagerStatusParams, type SessionManagerStatusResult, type SessionManagerWatchParams, type SessionManagerWatchReason, type SessionManagerWatchRespondPayload, type StatItem, type SubagentEngineConfigView, type SubagentEngineModelInfo, type SubagentEnginesFile, type SubagentInFlightReport, type SubagentJournalDomain, type SubagentJournalEvent, type SubagentJournalReport, type SupportRating, TASK_ENTRY_TYPE, TOOL_ACTION_MAP, type TaskKind, type TaskSnapshot, type TaskStatus, type TextQuestion, type TreeItem, type TreeItemIcon, UI_FORM_MARKER, type UiFormInteractOptions, type UiFormInteractResult, WORKFLOW_RESULT_CUSTOM_TYPE, type WidgetIconPathsRejection, type WidgetIconPathsValidation, type WidgetMeta, allCanvasActions, allToolActions, appendExecutionRecord, applyPendingDiff, callMarkerRpc, canvasError, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isActionAllowed, isArgumentMateriality, isArgumentPolarity, isAskUserQuestion, isCanvasCommentParams, isCanvasCommentRespondParams, isCanvasConvergeCheckParams, isCanvasCreateParams, isCanvasDecideDirectionParams, isCanvasDispatchParams, isCanvasEnterParams, isCanvasExportParams, isCanvasGrowParams, isCanvasListParams, isCanvasMarkerRequest, isCanvasPatchParams, isCanvasReadParams, isCanvasReviewAppendParams, isCanvasReviewRequestParams, isCanvasReviewResolveParams, isCanvasSelectParams, isCanvasTransitionParams, isChannelErrorResult, isFormAnswers, isFormQuestion, isGuiCapable, isGuiComponent, isGuiRenderResult, isInFlightReportAck, isJournalReportAck, isPlanReviewRequest, isPlanReviewResponse, isScheduleDraft, isScheduleFormResult, isSessionManagerAbortParams, isSessionManagerArchiveParams, isSessionManagerCreateParams, isSessionManagerDeleteParams, isSessionManagerHistoryParams, isSessionManagerListParams, isSessionManagerNotifyId, isSessionManagerSendParams, isSessionManagerStatusParams, isSessionManagerWatchParams, isSessionManagerWatchRespondPayload, isSubagentInFlightReport, isSubagentJournalReport, mapReasonToStatus, onceCronToDate, parsePlanReviewResponse, readLifecycleState, readResumeHint, replayFoldEntries, scanPendingEntries, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };

package/dist/index.js

@@ -110,11 +110,14 @@ function stripUndefined(obj) {
 // src/core/select-rpc.ts
 var RESPONSE_PREVIEW_LENGTH = 200;
 function isChannelErrorResult(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v) && typeof v.error === "string";
+  const rec = v;
+  return typeof v === "object" && v !== null && !Array.isArray(v) && typeof rec.error === "string" && (rec.code === void 0 || typeof rec.code === "string");
 }
 function formatChannelErrorText(err) {
-  return err.hint ? `${err.error}
-hint: ${err.hint}` : err.error;
+  const lines = [err.error];
+  if (err.code) lines.push(`error_code: ${err.code}`);
+  if (err.hint) lines.push(`hint: ${err.hint}`);
+  return lines.join("\n");
 }
 function emitRpcLog(opts, msg, detail) {
   opts?.log?.(msg, detail);
@@ -123,7 +126,7 @@ async function callMarkerRpc(ctx, marker, payload, opts) {
   const select = ctx.ui?.select;
   if (!select) {
     throw new Error(
-      `callMarkerRpc() requires ctx.ui.select (marker ${JSON.stringify(marker)}). Non-GUI ctx must be gated by the caller first \u2014 see askUserInteract precedent (isGuiCapable(ctx) && ctx.ui?.select, or a mode check).`
+      `callMarkerRpc() requires ctx.ui.select (marker ${JSON.stringify(marker)}). Non-GUI ctx must be gated by the caller first \u2014 gate with isGuiCapable(ctx) && ctx.ui?.select (exported from @zhushanwen/extension-protocol), or a mode check.`
     );
   }
   let value;
@@ -415,6 +418,7 @@ function onceCronToDate(cron, now = /* @__PURE__ */ new Date()) {
 }
 
 // src/extensions/plan/state-machine.ts
+import { defineStateMachine } from "@zhushanwen/state-machine";
 var PLAN_LIFECYCLE_STATES = [
   "idle",
   "planning",
@@ -436,34 +440,57 @@ var PLAN_LIFECYCLE_EVENTS = [
   "later",
   "exit"
 ];
-var TRANSITION_TABLE = {
-  idle: { enter: "planning" },
-  planning: { submit: "reviewing", exit: "exited" },
-  reviewing: {
-    submit: "reviewing",
-    revise: "revising",
-    dismiss: "planning",
-    review_aborted: "planning",
-    approve: "dispatching",
-    exit: "exited"
+var PLAN_MACHINE = defineStateMachine({
+  name: "plan-lifecycle",
+  states: {
+    idle: {},
+    planning: {},
+    reviewing: {},
+    revising: {},
+    approved: {},
+    dispatching: {},
+    completed: { terminal: true },
+    exited: { terminal: true }
   },
-  revising: { submit: "reviewing", exit: "exited" },
-  approved: { approve: "dispatching", exit: "exited" },
-  dispatching: {
-    review_aborted: "approved",
-    exec_chosen: "completed",
-    later: "approved",
-    exit: "exited"
+  initial: "idle",
+  events: {
+    enter: {},
+    submit: {},
+    revise: {},
+    dismiss: {},
+    review_aborted: {},
+    approve: {},
+    exec_chosen: {},
+    later: {},
+    exit: {}
   },
-  completed: { enter: "planning" },
-  exited: { enter: "planning" }
-};
+  transitions: [
+    { from: "idle", on: "enter", to: "planning" },
+    { from: "planning", on: "submit", to: "reviewing" },
+    { from: "planning", on: "exit", to: "exited" },
+    { from: "reviewing", on: "submit", to: "reviewing" },
+    { from: "reviewing", on: "revise", to: "revising" },
+    { from: "reviewing", on: "dismiss", to: "planning" },
+    { from: "reviewing", on: "review_aborted", to: "planning" },
+    { from: "reviewing", on: "approve", to: "dispatching" },
+    { from: "reviewing", on: "exit", to: "exited" },
+    { from: "revising", on: "submit", to: "reviewing" },
+    { from: "revising", on: "exit", to: "exited" },
+    { from: "approved", on: "approve", to: "dispatching" },
+    { from: "approved", on: "exit", to: "exited" },
+    { from: "dispatching", on: "review_aborted", to: "approved" },
+    { from: "dispatching", on: "exec_chosen", to: "completed" },
+    { from: "dispatching", on: "later", to: "approved" },
+    { from: "dispatching", on: "exit", to: "exited" },
+    { from: ["completed", "exited"], on: "enter", to: "planning" }
+  ],
+  errorPolicy: "result"
+});
 function transition(state, event) {
-  if (!PLAN_LIFECYCLE_STATES.includes(state) || !PLAN_LIFECYCLE_EVENTS.includes(event)) {
-    return { ok: false };
-  }
-  const next = TRANSITION_TABLE[state][event];
-  return next === void 0 ? { ok: false } : { ok: true, next };
+  if (typeof event !== "string") return { ok: false };
+  const result = PLAN_MACHINE.transition(state, event);
+  if (!result.ok) return { ok: false };
+  return result.state === null ? { ok: false } : { ok: true, next: result.state };
 }
 var PHASE_OF_STATE = {
   idle: "idle",
@@ -476,8 +503,9 @@ var PHASE_OF_STATE = {
   exited: "terminal"
 };
 function derivePhase(state) {
-  if (!PLAN_LIFECYCLE_STATES.includes(state)) return "idle";
-  return PHASE_OF_STATE[state];
+  const coerced = PLAN_MACHINE.coerceState(state);
+  if (coerced === null) return "idle";
+  return PHASE_OF_STATE[coerced];
 }
 
 // src/extensions/plan/review-contract.ts
@@ -552,10 +580,8 @@ function isPlanReviewResponse(value) {
 // src/extensions/plan/legacy-entries.ts
 var PLAN_STATE_CUSTOM_TYPE = "plan-state";
 function readLifecycleState(data, isActive) {
-  const raw = data.state;
-  if (typeof raw === "string" && PLAN_LIFECYCLE_STATES.includes(raw)) {
-    return raw;
-  }
+  const coerced = PLAN_MACHINE.coerceState(data.state);
+  if (coerced !== null) return coerced;
   if (data.reviewState === "awaiting") return "reviewing";
   if (data.reviewState === "revising") return "revising";
   return isActive ? "planning" : "idle";
@@ -700,6 +726,12 @@ function isSessionManagerStatusParams(v) {
 function isSessionManagerAbortParams(v) {
   return isSessionIdParams(v);
 }
+function isSessionManagerDeleteParams(v) {
+  return isSessionIdParams(v);
+}
+function isSessionManagerArchiveParams(v) {
+  return isSessionIdParams(v);
+}
 function isSessionManagerListParams(v) {
   return isRecord(v);
 }
@@ -732,7 +764,17 @@ function isSessionManagerWatchRespondPayload(v) {
 
 // src/extensions/session-manager/marker.ts
 var SESSION_MANAGER_MARKER = "\0TAIJI_SESSION_MANAGER";
-var SESSION_MANAGER_ACTIONS = ["create", "send", "history", "status", "list", "abort", "watch"];
+var SESSION_MANAGER_ACTIONS = [
+  "create",
+  "send",
+  "history",
+  "status",
+  "list",
+  "abort",
+  "delete",
+  "archive",
+  "watch"
+];
 
 // src/extensions/subagent-inflight/marker.ts
 var SUBAGENT_INFLIGHT_MARKER = "\0TAIJI_SUBAGENT_INFLIGHT";
@@ -1009,6 +1051,7 @@ var CANVAS_ERROR_CODES = [
   "invalid_params",
   "unknown_action",
   "actor_not_allowed",
+  "forbidden",
   "selection_conflict",
   "cycle_detected",
   "unverified_fact",
@@ -1027,6 +1070,7 @@ var CANVAS_ERROR_RECOVERY = {
   invalid_params: "\u8BF7\u6C42\u53C2\u6570\u5F62\u72B6\u975E\u6CD5\uFF1A\u5BF9\u7167\u8BE5 action \u7684 params \u5951\u7EA6\u4FEE\u6B63\u5B57\u6BB5\u540E\u91CD\u8BD5",
   unknown_action: "action \u4E0D\u5728\u8BCD\u8868\uFF1A\u5BF9\u7167 CANVAS_ACTIONS \u8BCD\u8868\u4FEE\u6B63 action \u540D",
   actor_not_allowed: "\u5F53\u524D\u64CD\u4F5C\u65B9\u65E0\u6B64\u52A8\u4F5C\u6743\u9650\uFF1A\u67E5\u6743\u9650\u77E9\u9635\uFF08\u8BE5\u52A8\u4F5C\u4EC5\u9650\u7279\u5B9A\u64CD\u4F5C\u65B9\uFF09\uFF0C\u6539\u7531\u6709\u6743\u65B9\u6267\u884C",
+  forbidden: "\u753B\u5E03\u4E0D\u5C5E\u4E8E\u5F53\u524D\u4F1A\u8BDD\uFF08\u753B\u5E03\u5F52\u5C5E\u521B\u5EFA\u5B83\u7684\u4F1A\u8BDD\uFF0C\u8DE8\u4F1A\u8BDD\u8BBF\u95EE\u88AB\u62D2\u7EDD\uFF09\uFF1A\u8BF7\u8BA9\u7528\u6237\u5207\u6362\u5230\u753B\u5E03\u5F52\u5C5E\u4F1A\u8BDD\u540E\u91CD\u8BD5\uFF0C\u6216\u7ECF canvas_list \u67E5\u770B\u5F53\u524D\u4F1A\u8BDD\u53EF\u7528\u7684\u753B\u5E03",
   selection_conflict: "\u8BE5\u95EE\u9898\u5DF2\u6709\u9009\u5B9A\u65B9\u6848\uFF1A\u6362\u9009\u8D70 select \u7684 replace \u53C2\u6570\uFF08\u540C\u4E00\u8C03\u7528\u5185\u8FC1\u79FB\u65E7\u9009\u5B9A\uFF09\u5E76\u9644\u5BF9\u6BD4\u7406\u7531",
   cycle_detected: "\u8BE5\u8FB9\u4F1A\u4F7F\u4E3B\u5E72\u6210\u73AF\uFF1A\u5206\u89E3/\u89E3\u8FB9\u53EA\u80FD\u6307\u5411\u4E0A\u5C42\u8282\u70B9\u7684\u4E0B\u5C42\uFF0C\u53BB\u6389\u56DE\u8FB9\u540E\u91CD\u8BD5",
   unverified_fact: "\u672A\u6838\u5B9E\u7684 fact \u8BBA\u636E\u4E0D\u5F97\u4F5C\u4E3A\u901A\u8FC7\u4F9D\u636E\uFF1A\u5148\u8865\u6838\u5B9E\u72B6\u6001\uFF08factVerified\uFF09\u518D\u91CD\u8BD5",
@@ -1102,19 +1146,39 @@ function allCanvasActions() {
 var PENDING_REGISTER_ENTRY_TYPE = "pending:register";
 var PENDING_UNREGISTER_ENTRY_TYPE = "pending:unregister";
 function scanPendingEntries(entries) {
-  const scan = { registerEntries: [], unregisteredIds: /* @__PURE__ */ new Set() };
+  const scan = {
+    registerEntries: [],
+    unregisteredIds: /* @__PURE__ */ new Set(),
+    registerTypes: /* @__PURE__ */ new Map(),
+    unregisterStatuses: /* @__PURE__ */ new Map()
+  };
+  const seenRegisterIds = /* @__PURE__ */ new Set();
   for (const raw of entries) {
     if (!raw || typeof raw !== "object") continue;
     const entry = raw;
+    const data = entry.data ?? {};
     if (entry.customType === PENDING_REGISTER_ENTRY_TYPE) {
-      scan.registerEntries.push({ data: entry.data ?? {} });
+      scan.registerEntries.push({ data });
+      if (typeof data.id === "string" && data.id !== "" && !seenRegisterIds.has(data.id)) {
+        seenRegisterIds.add(data.id);
+        if (typeof data.type === "string") scan.registerTypes.set(data.id, data.type);
+      }
     } else if (entry.customType === PENDING_UNREGISTER_ENTRY_TYPE) {
-      const data = entry.data ?? {};
-      if (typeof data.id === "string") scan.unregisteredIds.add(data.id);
+      if (typeof data.id === "string") {
+        scan.unregisteredIds.add(data.id);
+        const status = data.status;
+        if (data.id !== "" && typeof status === "string" && MAPPED_PENDING_STATUSES.has(status)) {
+          scan.unregisterStatuses.set(data.id, status);
+        }
+      }
     }
   }
   return scan;
 }
+function scanPendingFields(entries) {
+  const { registerTypes, unregisterStatuses } = scanPendingEntries(entries);
+  return { registerTypes, unregisterStatuses };
+}
 function applyPendingDiff(scan) {
   const active = [];
   const seen = /* @__PURE__ */ new Set();
@@ -1157,6 +1221,7 @@ var REASON_STATUS_MAP = {
 function mapReasonToStatus(reason) {
   return REASON_STATUS_MAP[reason] ?? "completed";
 }
+var MAPPED_PENDING_STATUSES = new Set(Object.values(REASON_STATUS_MAP));
 export {
   ACTION_EVENT_MAP,
   ASK_USER_MARKER,
@@ -1176,6 +1241,7 @@ export {
   HISTORY_LIMIT,
   INFLIGHT_REPORT_ACK,
   JOURNAL_REPORT_ACK,
+  MAPPED_PENDING_STATUSES,
   MAX_TERMINAL_REGISTRY_ENTRIES,
   MS_PER_DAY,
   MS_PER_HOUR,
@@ -1260,7 +1326,9 @@ export {
   isScheduleDraft,
   isScheduleFormResult,
   isSessionManagerAbortParams,
+  isSessionManagerArchiveParams,
   isSessionManagerCreateParams,
+  isSessionManagerDeleteParams,
   isSessionManagerHistoryParams,
   isSessionManagerListParams,
   isSessionManagerNotifyId,
@@ -1278,6 +1346,7 @@ export {
   readResumeHint,
   replayFoldEntries,
   scanPendingEntries,
+  scanPendingFields,
   setWidgetDual,
   snapshotToTask,
   toolOfAction,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/extension-protocol",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Cross-layer pi extension contract package: dual-mode (TUI/GUI) rendering helpers, session/background-task/pending-entries protocols, and shared behavior primitives",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,9 @@
     "README.md"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@zhushanwen/state-machine": "0.2.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "tsup": "^8.5.1",