@zhushanwen/extension-protocol 0.20.0 → 0.22.0

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 实现）。 */
@@ -434,7 +434,7 @@ interface ChannelErrorResult {
     error: string;
     hint?: string;
 }
-/** 运行时形状守卫：{error: string}（hint 可选，不校验其类型；排数组） */
+/** 运行时形状检查：{error: string}（hint 可选，不校验其类型；排数组） */
 declare function isChannelErrorResult(v: unknown): v is ChannelErrorResult;
 /** error + hint 文本拼接（hint 缺席只回 error）——plugin-bridge errorResult 与
  * session-manager 错误闭环文本的共用单源 */
@@ -537,7 +537,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 +797,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 +810,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;
 /**
@@ -833,7 +833,7 @@ declare function onceCronToDate(cron: string, now?: Date): Date | null;
  *
  * plan 模式的状态散落在 pi 扩展 entry / runtime 挂起注册表 / renderer 派生公式三处时，
  * 任意两者漂移即产「僵尸/谎言」UI（F1-F5）。本模块是全链路共享的单一状态契约：
- * 8 值状态集 + 9 事件边表 + `transition` 纯函数（守卫集中一处）+ `derivePhase` 呈现映射。
+ * 8 值状态集 + 9 事件边表 + `transition` 纯函数（检查集中一处）+ `derivePhase` 呈现映射。
  *
  * 语义要点（设计 D1 逐条锚定）：
  * - 非法转移返回 `{ ok: false }`，由调用方降级（**不 throw 炸 turn**）；副作用不进返回值
@@ -850,7 +850,7 @@ 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）。
@@ -879,13 +879,13 @@ type PlanTransitionResult = {
  *
  * 非法转移（含运行时垃圾 state/event 值——跨版本帧、坏反序列化）返回 `{ ok: false }`
  * 且**不携带 next 键**，由调用方降级（不 throw 炸 turn）。调用方义务：`ok:false` 时
- * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归口点的兜底保险）。
+ * 不落盘、不执行副作用（终态上 `ok:false` 不落盘即 D3 归属划分点的兜底保险）。
  *
- * 入口白名单守卫（与 derivePhase 同一机制）：普通对象字面量查表会沿原型链命中继承键——
+ * 入口白名单检查（与 derivePhase 同一机制）：普通对象字面量查表会沿原型链命中继承键——
  * `transition('reviewing', '__proto__')` 取出 Object.prototype、`('__proto__', 'valueOf')`
  * 取出函数，均被误判为合法 next（违背本契约）。故垃圾键必须先挡在查表前。
  * **选「枚举 includes 白名单」而非 null-prototype 表 / Object.hasOwn**：① transition 与
- * derivePhase 共用同一守卫形态（单一机制，不并存两种写法）；② PLAN_LIFECYCLE_STATES /
+ * derivePhase 共用同一检查形态（单一机制，不并存两种写法）；② PLAN_LIFECYCLE_STATES /
  * PLAN_LIFECYCLE_EVENTS 就是值域 SSOT（测试穷举同源），includes 判定与之同源，
  * 原型键天然不在白名单内。
  */
@@ -904,21 +904,21 @@ type PlanPhase = 'idle' | 'planning' | 'reviewing' | 'approved' | 'terminal';
  * 8 存储态 → 5 呈现相位的单点映射（renderer 阶段指示/状态带共用，禁止消费方各自 if 拼）。
  * 运行时垃圾 state（混装格坏帧）降级 'idle'（无 plan 缺省，fail-safe 不误示进行中）。
  *
- * 入口白名单守卫（理由同 transition，见彼处）：裸查表对继承键 'constructor' / 'toString'
+ * 入口白名单检查（理由同 transition，见彼处）：裸查表对继承键 '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 +928,7 @@ declare function derivePhase(state: PlanLifecycleState): PlanPhase;
  *
  * selfReview 有界字段（D9③ / R3）：有界性由**写侧单点截断**保证（截断点 = 扩展 payload
  * 构造处），4KB 上限与 UTF-8 字节界安全截断的唯一权威在本模块；透传层（runtime）不截、
- * 入站守卫不二次截（上限已在写侧达成）。
+ * 入站检查不二次截（上限已在写侧达成）。
  */
 
 /** selfReview 上限：4KB（UTF-8 字节）。超限即截（全文可要求 agent 贴对话流，R3）。 */
@@ -939,7 +939,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 +966,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,7 +986,7 @@ declare const PLAN_STATE_CUSTOM_TYPE = "plan-state";
 /**
  * 生命周期状态读取（D2 读方①②共用映射，原扩展 state.ts / runtime extractor 内联拷贝的
  * 单源归并）：
- * ① 新字段直读（值域守卫：PLAN_LIFECYCLE_STATES 之外的垃圾值按缺失处理，落映射——
+ * ① 新字段直读（值域检查：PLAN_LIFECYCLE_STATES 之外的垃圾值按缺失处理，落映射——
  *    不信任外部写入）；
  * ② 旧 entry 无 state（或垃圾 state）时映射 reviewState（awaiting→reviewing /
  *    revising→revising / 其余值→planning|idle 按 isActive）。
@@ -1008,7 +1008,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 +1131,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 +1152,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 +1167,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;
 
 /**
@@ -1225,7 +1225,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;
@@ -1256,7 +1256,7 @@ interface SessionManagerAbortParams {
 /**
  * watch action 参数（notify-once D2/D6）：通知债权的纯应答通道，**单键寻址**——
  * runtime 按 `(调用方 parentSid, notifyId)` 反查 claim，parentSid 取自调用方连接身份、
- * **协议面不定义不携带**（可推导字段免传，多余字段被守卫拒绝）。不传 timeout、
+ * **协议范围不定义不携带**（可推导字段免传，多余字段被检查拒绝）。不传 timeout、
  * fire-and-forget 长挂 select；每 claim 单 watch 槽（新覆盖旧，runtime 只 respond 最新）。
  */
 interface SessionManagerWatchParams {
@@ -1264,9 +1264,9 @@ 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;
@@ -1276,9 +1276,9 @@ declare function isSessionManagerAbortParams(v: unknown): v is SessionManagerAbo
 /** 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 +1289,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 正交——后者恒存在（死亡通知与债权无关）。
      */
@@ -1365,15 +1365,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 +1382,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 +1393,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 +1408,7 @@ type SessionManagerErrorResult = ChannelErrorResult & {
 };
 
 /**
- * subagent 在途上报的类型定义（u7a 协议面）。
+ * subagent 在途上报的类型定义（u7a 协议范围）。
  *
  * 契约两端：
  *   - 写侧（生产）：@zhushanwen/pi-subagent-workflow 壳层（src/host/inflight-reporter.ts）
@@ -1452,12 +1452,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 +1470,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 +1537,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 +1564,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 +1579,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";
@@ -1644,6 +1644,680 @@ interface SubagentEngineConfigView {
     engineDefaults?: Record<string, string>;
 }
 
+/**
+ * problem-solve-canvas 契约模块 —— marker 与 action 词表（U1 SSOT）。
+ *
+ * 设计锚点：.tmp/tech-design/problem-solve-canvas.md §3.1(1)/(2) + §5-U1。
+ * 本目录是画布三侧（pi extension 工具面 / runtime CanvasService / renderer 视图）
+ * 共享的唯一词表与 schema 来源——防 GUI 与工具两个入口各自发明语义。
+ *
+ * 两层词表（有意分开，勿合并）：
+ * - CANVAS_ACTIONS（16）：CanvasService.mutate 唯一入口的 action 域，
+ *   per-action × actor 权限矩阵按此建制（matrix.ts）。
+ * - CANVAS_MARKER_ACTIONS（16 + 'enter'）：marker 通道（extension select 挂起）
+ *   的 action 域。'enter' 是 canvas_enter 工具「打开已有画布」形态的通道动作：
+ *   读全量（归属校验在 readState，非 owner → forbidden）；回推对象 = 归属会话
+ *   本身（owner 持久在落盘路径），无登记动作、不产事件——非画布 mutation、
+ *   不在权限矩阵内（marker 通道调用方恒为 agent 工具）。创建形态走 'create'
+ *   （marker 通道的 create 只可能来自 canvas_enter 工具；GUI 托盘新建走 WS RPC
+ *   通道，两通道行为无分叉）。
+ */
+/**
+ * canvas 工具请求的 title marker。runtime event-adapter / CanvasHandler 检测此
+ * marker 区分 canvas 请求与普通 select（SESSION_MANAGER 同款形态）。
+ *
+ * NUL 前缀确保不会与 extension 正常的 select title 冲突。
+ * 属内部服务类 marker：走 translateInteractiveRequest 显式分支，
+ * 不入 MARKER_DIALOG_FALLBACKS 降级表（畸形 payload 以结构化错误应答回
+ * marker 通道，不降级为用户可见对话框）。
+ */
+declare const CANVAS_MARKER = "\0TAIJI_CANVAS";
+/**
+ * 16 个 mutate / 查询 action 的运行时集合（与 CanvasAction 类型同源——从本目录
+ * actions.ts 的 CANVAS_ACTIONS 数组派生，不写行号：跨 commit 推移会失准）。
+ *
+ * 词序按领域生命周期排列：创建 → 生长 → 编辑 → 方向裁决 → 选定 → 状态转移 →
+ * 评论 → 评论响应 → 审查三动作 → 收敛确认 → 导出 → 派发 → 查询两类。
+ *
+ * 'read' / 'list' 是查询类：不产领域事件、不在「每个 mutation action 至少产出
+ * 一个事件」的对账范围（U2 承接对账，ACTION_EVENT_MAP 为对账 SSOT——state.ts）。
+ */
+declare const CANVAS_ACTIONS: readonly ["create", "grow", "patch", "decide-direction", "select", "transition", "comment", "comment-respond", "review-request", "review-append", "review-resolve", "converge-check", "export", "dispatch", "read", "list"];
+/**
+ * marker 通道词表 = CANVAS_ACTIONS + 'enter'（两层词表的通道层，见文件头说明）。
+ * event-adapter 用它把 JSON 解析出的 action 字符串收窄；表外值折叠为畸形
+ * → 结构化错误应答（不降级对话框）。
+ */
+declare const CANVAS_MARKER_ACTIONS: readonly ["create", "grow", "patch", "decide-direction", "select", "transition", "comment", "comment-respond", "review-request", "review-append", "review-resolve", "converge-check", "export", "dispatch", "read", "list", "enter"];
+
+/**
+ * problem-solve-canvas 契约 —— 领域状态 schema（CanvasState / ReviewReport）与领域事件词表。
+ *
+ * 形状对齐概念文档（.tmp/problem-solve-canvas.md）§2 领域模型：四类图节点 + 评论附件 +
+ * MVP 四种边（decompose / resolve / argue / rebut；constrain / reference 第二版不入词表）+
+ * 生命周期 × 派发二维状态机（§2.4）。
+ *
+ * 本 schema 同时承载两处消费：
+ * - canvas.get RPC reply / canvas_enter（打开形态）的工具结果 = 全量只读视图
+ * - runtime canvas.json 加速快照的落盘形状（events.jsonl 为唯一持久权威，
+ *   快照可由事件流全量重放推导——U2 落盘契约）
+ *
+ * 唯一形状分叉：activeBindings 只在 canvas.get reply 出现（查询侧派生，见字段注释），
+ * 快照与 marker 工具结果不携带。
+ *
+ * 时间字段一律 ISO string（不用 Date）——wire 与落盘 JSON 往返无损，序列化即契约。
+ */
+/** 四类图节点（概念文档 §2.2）。评论不是图节点（裁决点 R2：降为锚定附件）。 */
+type CanvasNodeType = 'question' | 'option' | 'argument' | 'constraint';
+/**
+ * 节点生命周期状态机（概念文档 §2.4，全部图节点；根节点不可搁置/否决）。
+ * 合法转移：draft→under-review / draft→shelved / under-review→passed /
+ * under-review→rejected / under-review→shelved / rejected→draft（复活，须留理由）/
+ * shelved→draft。表外转移 fail-fast（U2 状态机穷举单测承接）。
+ */
+type CanvasNodeLifecycle = 'draft' | 'under-review' | 'passed' | 'rejected' | 'shelved';
+/** MVP 四种边（概念文档 §2.3）。constrain / reference 第二版，词表不预留。 */
+type CanvasEdgeType = 'decompose' | 'resolve' | 'argue' | 'rebut';
+/** 论据极性（裁决点 R1：原「证据」「反对」合并为论据的极性字段）。 */
+type ArgumentPolarity = 'support' | 'object';
+/** 论据素材性：fact 事实（必带核实状态）/ claim 主张。 */
+type ArgumentMateriality = 'fact' | 'claim';
+/** 主干边支撑度三值（裁决点 R3：只评 decompose/resolve 主干边，论证边不评级）。 */
+type SupportRating = 'sufficient' | 'gap' | 'invalid';
+/** 图节点。per-type 字段全部 optional——类型面宽松、领域约束归 U2 不变量校验
+ * （契约层不复制不变量逻辑，避免双权威）。 */
+interface CanvasNode {
+    id: string;
+    type: CanvasNodeType;
+    content: string;
+    lifecycle: CanvasNodeLifecycle;
+    /** option：selected 标记（不变量 3：任一 question 的 resolve 边中 selected 至多一条）。 */
+    selected?: boolean;
+    /** option：选定对比理由（不变量 3：selected 变更须留对比与理由）。 */
+    selectionReason?: string;
+    /** lifecycle=rejected 时的否决记录——不可删除（MVP 不可砍：防 agent 重复提出已否决项）。 */
+    rejection?: {
+        reason: string;
+        reviveCondition?: string;
+    };
+    /** argument：极性。 */
+    polarity?: ArgumentPolarity;
+    /** argument：素材性；fact 时 factVerified 必填（不变量 5）。 */
+    materiality?: ArgumentMateriality;
+    /** argument：核实状态（fact 论据必填；未核实 fact 不得作为 passed 依据——不变量 5）。 */
+    factVerified?: boolean;
+    /** option：执行叶子显式标记（裁决点 R5：叶子是结构派生、执行叶子是规划决策，两不混同）。 */
+    dispatchable?: boolean;
+    /** option：执行叶子完成判据（passed 前必填——不变量 7）。 */
+    criterias?: string[];
+    /** 派发维度（与 lifecycle 正交，仅执行叶子）：dispatched 后登记下游产物指针（不变量 7）。 */
+    dispatch?: {
+        pointer: string;
+        dispatchedAt: string;
+    };
+    createdAt: string;
+}
+/** 图边。argue 边的 to 可指向主干边 id（论证一条分解/解边本身）——targetId 域校验归 U2。 */
+interface CanvasEdge {
+    id: string;
+    type: CanvasEdgeType;
+    /** 起点节点 id（argument 节点）。 */
+    from: string;
+    /** 终点：节点 id 或主干边 id（仅 argue 边可指边）。 */
+    to: string;
+    /** argue 边极性。 */
+    polarity?: ArgumentPolarity;
+    /** 主干边支撑度（decompose/resolve 专用；审查轮次溯源）。 */
+    support?: {
+        rating: SupportRating;
+        gaps?: string[];
+        round?: number;
+    };
+}
+/** 评论附件（锚定在节点或边上，非图成员）。响应状态机承载 agent 响应义务（不变量 8）。 */
+interface CanvasComment {
+    id: string;
+    /** 锚定目标：节点 id 或边 id。 */
+    anchorId: string;
+    text: string;
+    /** 待响应 / 已响应；转已响应前必须留采纳或反驳的痕（不变量 8）。 */
+    status: 'pending' | 'responded';
+    /** 响应留痕：采纳（并落实到图）/ 反驳（留理由）二选一。 */
+    response?: {
+        disposition: 'adopted' | 'rebutted';
+        note: string;
+    };
+    createdAt: string;
+}
+/** 方向裁决记录（裁决点 R4：画布元数据 + 事件留痕，不是图节点）。矩阵限 user 拍板。 */
+interface CanvasDirectionDecision {
+    direction: 'top-down' | 'bottom-up';
+    reason: string;
+    decidedAt: string;
+}
+/** 六维度审查清单（概念文档 §4.3：逐维度打靶，不泛泛「是否合理」）。 */
+type ReviewDimension = 'completeness' | 'necessity' | 'support' | 'authenticity' | 'conflict' | 'depth';
+/** 条目分级：must-fix 清零不收敛；suggestion 处置制（三选一）。 */
+type ReviewSeverity = 'must-fix' | 'suggestion';
+/** 审查终态族（对齐 review-fix-loop 终态集；除 converged 外全部停回用户）。
+ * 各值的驻留口径：converged / max-rounds 驻留于 status；escalated 不驻留——升级经
+ * ReviewEscalated 事件留痕，放行后即回 in-progress（每次升级裁决恰放行一轮，轮次
+ * 预算随放行抬升）；stuck 为终态族词表值，MVP 无触发路径（reviewer 派发失败经
+ * 错误显式上报，不落聚合终态）。 */
+type ReviewReportStatus = 'in-progress' | 'converged' | 'max-rounds' | 'escalated' | 'stuck';
+/** 处置三选一（采纳 / 登记后做 / 拒绝留理由）。 */
+type ReviewResolutionDisposition = 'accepted' | 'deferred' | 'rejected';
+/** 审查报告条目：经图元素 id 引用画布（聚合 2 不变量 1：id 必须存在；R6 裁决点：
+ * 图承载内容、报告承载过程）。 */
+interface ReviewEntry {
+    id: string;
+    round: number;
+    dimension: ReviewDimension;
+    severity: ReviewSeverity;
+    /** 引用的图元素 id（节点 / 边 / 评论）。 */
+    targetId: string;
+    note: string;
+    /** 随条目写回的支撑度评价输入原文（评价结果落 edge.support；round 溯源取条目 round）。 */
+    supportRating?: SupportRating;
+    /** rating='gap' 的缺口清单（与 edge.support.gaps 同源）。 */
+    supportGaps?: string[];
+    /**
+     * 处置记录（first-writer-wins：已有处置记录后再次 review-resolve = 拒绝 +
+     * already_resolved 错误——覆盖会让 R2 审到与登记方实际动作不符的处置表）。
+     */
+    resolution?: {
+        disposition: ReviewResolutionDisposition;
+        /** 处置登记方（agent 执行侧 / user 复核直处）。 */
+        by: 'user' | 'agent';
+        note: string;
+    };
+}
+/** 审查报告聚合（ReviewReport）。挂于 CanvasState.review；null = 从未发起审查。 */
+interface ReviewReport {
+    status: ReviewReportStatus;
+    /** 当前 / 最近轮次（R1 全面审，R2+ 只审上轮处置表 + 攻击点）。 */
+    round: number;
+    maxRounds: number;
+    entries: ReviewEntry[];
+    /** 非 converged 终态的停回说明（聚合 2 不变量 2：max-rounds / escalated / stuck 必附）。 */
+    stopNote?: string;
+    /** 恢复动作建议（停回说明的配套：升级裁决后可再发起）。 */
+    recoverHint?: string;
+}
+/** 画布状态（聚合 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，带完成判据与范围排除）。 */
+    root: {
+        nodeId: string;
+        statement: string;
+        /** 完成判据（可证伪）。 */
+        criterias: string[];
+        /** 范围排除（设计文档 enter 参数表记作 scope 的全称形态）。 */
+        scopeExclusions: string[];
+        /** 根判据经用户确认（收敛判据 1）。 */
+        confirmed?: boolean;
+    };
+    /** 生长方向裁决；未裁决为 null。 */
+    direction: CanvasDirectionDecision | null;
+    nodes: CanvasNode[];
+    edges: CanvasEdge[];
+    comments: CanvasComment[];
+    /** 待重审集合（节点 id；不变量 9：用户改动后该节点到根的路径进入本集合）。 */
+    dirtyPaths: string[];
+    /** 审查报告聚合；null = 从未发起审查。 */
+    review: ReviewReport | null;
+    /** 规划收敛终态（converge-check 校验不变量 10 后置位；export 同校验）。 */
+    converged: boolean;
+    /**
+     * 活跃绑定数（绑定记录 ∩ 存活 session，设计 §3.1(1) 回推节 / §3.1(3) 绑定徽标
+     * 数据源）——canvas.get reply 的查询侧派生值：transport 装配层附加（存活判定经
+     * sessionService，CanvasService 无该依赖），domain 产物与 canvas.json 快照均不含
+     * （绑定是 runtime 内存态、不可由事件流重放推导——落盘会污染「快照可由事件流
+     * 全量重放重建」的唯一权威承诺）。optional = marker 通道（enter/read 工具结果）
+     * 与旧 runtime reply 不携带；消费方缺字段按未知处理（徽标不渲染）。
+     */
+    activeBindings?: number;
+    /**
+     * 收敛阻断清单（canvas-foundation convergenceBlockers 的现算结果，导出面板
+     * 门禁区②格「规划就绪」的逐项呈现数据源——门禁②的判定是 runtime 领域规则
+     * 不跨 wire，本字段把判定结论（缺什么）随 canvas.get 携带给界面）。与
+     * activeBindings 同款查询侧派生：transport 装配层附加，domain 产物与
+     * canvas.json 快照均不含（纯派生值，落盘即与画布状态二源漂移）。optional =
+     * marker 通道（enter/read 工具结果）与旧 runtime reply 不携带；消费方缺字段
+     * 按未知处理（②格退回「由权威校验」措辞形态）。空数组 = 无阻断（已收敛或
+     * 收敛后再改动时仅剩待重审类条目，与门禁③计数互补）。
+     */
+    convergenceBlockers?: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** canvas.list 条目：托盘画布列表的数据源（名称 + 阶段徽标 + must-fix 计数）。
+ * 阶段徽标本身是 renderer 派生值（开放 must-fix 或审查进行中 = 审查中；
+ * converged = 已收敛；其余 = 生长中），契约只给派生输入。清单按请求 sessionId
+ * 过滤（只返回归属该会话的画布），ownerSessionId 即过滤判据的回显。 */
+interface CanvasListEntry {
+    canvasId: string;
+    /** 归属会话 id（= 请求的过滤 sessionId；语义同 CanvasState.ownerSessionId）。 */
+    ownerSessionId: string;
+    name: string;
+    statement: string;
+    converged: boolean;
+    /** 未关闭 must-fix 条目数。 */
+    openMustFix: number;
+    /** 审查报告状态；从未审查为 null。 */
+    reviewStatus: ReviewReportStatus | null;
+}
+/**
+ * 领域事件类型词表（过去式命名，概念文档 §2.6 + U2 增补）。
+ *
+ * 广播 canvas.updated 的 evType 取值域；renderer 按值分流——CanvasCreated 驱动
+ * 创建后自动唤起（U5），其余类型仅作失效提示（重新拉取收敛）。
+ *
+ * SSOT 对账义务（U2 承接）：每个 mutation action 至少产出一个事件，主事件映射
+ * 见 ACTION_EVENT_MAP；read / list 为查询类不产事件、不在对账范围；DirtiedPathMarked
+ * 与审查终态族是 mutate 事务 / 审查编排内的附属事件，不独立对应 action。
+ */
+declare const CANVAS_EVENT_TYPES: readonly ["CanvasCreated", "GrowthDirectionDecided", "NodeCreated", "NodeModified", "StateTransitioned", "OptionSelected", "NodeDispatched", "CommentAdded", "CommentResponded", "ReviewRequested", "ReviewEntryAppended", "ReviewEntryResolved", "ConvergenceChecked", "CanvasExported", "DirtiedPathMarked", "ReviewConverged", "ReviewMaxRoundsReached", "ReviewEscalated"];
+type CanvasEventType = (typeof CANVAS_EVENT_TYPES)[number];
+/**
+ * mutation action → 主领域事件映射（「每个 mutation action 至少产出一个事件」
+ * 的对账 SSOT）。键集约束（= 16 action 减 read/list 的 14 个 mutation action）
+ * 由一致性测试锁定（不在此回引 actions 层——保持依赖单向 actions → state）；
+ * read / list（查询类）不在表内 = 不产事件、不在对账范围——查询写事件会使
+ * append-only 日志体积随读取次数无界增长。U2 实现的事件产出与本表对账；
+ * 本表缺失键即对账红。
+ */
+declare const ACTION_EVENT_MAP: {
+    readonly create: "CanvasCreated";
+    readonly grow: "NodeCreated";
+    readonly patch: "NodeModified";
+    readonly 'decide-direction': "GrowthDirectionDecided";
+    readonly select: "OptionSelected";
+    readonly transition: "StateTransitioned";
+    readonly comment: "CommentAdded";
+    readonly 'comment-respond': "CommentResponded";
+    readonly 'review-request': "ReviewRequested";
+    readonly 'review-append': "ReviewEntryAppended";
+    readonly 'review-resolve': "ReviewEntryResolved";
+    readonly 'converge-check': "ConvergenceChecked";
+    readonly export: "CanvasExported";
+    readonly dispatch: "NodeDispatched";
+};
+
+/**
+ * problem-solve-canvas 契约 —— 错误码词表与恢复动作文案。
+ *
+ * 对齐分级错误处理契约：mutate / marker 调用被拒时返回结构化错误
+ * （code + message + recover），每码附一句恢复指引（设计 §3.1(1)）——
+ * 错误必须指向恢复动作，GUI toast 与 agent 工具结果双呈现同一文案。
+ * 文案面向用户（中文），agent 可读。
+ */
+/** 结构化错误形状（CanvasMutateReply 失败腿 / marker 畸形请求应答共用）。 */
+interface CanvasError {
+    code: CanvasErrorCode;
+    /** 错误概述（发生了什么）。 */
+    message: string;
+    /** 恢复动作指引（下一步怎么做；SSOT = CANVAS_ERROR_RECOVERY，runtime 可附加动态数值）。 */
+    recover: string;
+}
+/**
+ * 错误码词表（封闭 16 值）。分组：
+ * - 寻址 / 形状：canvas_not_found / node_not_found / edge_not_found /
+ *   invalid_params / unknown_action
+ * - 权限：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", "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 字段取此处
+ * 模板，可前缀动态数值如「先处置 3 条 must-fix」。缺码 = 词表与文案表漂移，
+ * 由测试锁定非空全覆盖）。
+ */
+declare const CANVAS_ERROR_RECOVERY: Record<CanvasErrorCode, string>;
+/** 构造结构化错误（recover 缺省取词表模板——每码必有恢复指引，构造性保证）。 */
+declare function canvasError(code: CanvasErrorCode, message: string): CanvasError;
+
+/**
+ * problem-solve-canvas 契约 —— action 参数 / 结果与运行时守卫。
+ *
+ * params 形状对齐设计文档 §3.1(1) action 要点与 §3.1(2) 工具面：
+ * - grow/patch 的节点 id 由 agent 侧生成（全局唯一：时间戳 + 随机），写入按 id
+ *   upsert（同 id 重复写入无副作用）——崩溃窗口（marker 挂起期间 pi 死亡）重试安全
+ * - select 带 replace 参数（换选 = 同一调用事务内先迁出旧 selected 再置新，
+ *   附对比理由——不变量 3 的迁移语义承载）
+ * - canvas_edit 族共享 reason 强制字段（留痕纪律）
+ *
+ * 守卫边界（对齐 session-manager 先例）：类型面校验——形状 / 词表成员资格；
+ * 领域校验（不变量 1-11、邻接矩阵、状态机合法转移）归 U2 CanvasService，
+ * 契约层不复制不变量逻辑（避免双权威）。
+ */
+
+/** 三类写入方（权限矩阵建制维度）：user = GUI 直改 / agent = 工具面 / review = reviewer subagent。 */
+type CanvasActor = 'user' | 'agent' | 'review';
+/** create：根三要素必填（不变量 1）。GUI 托盘「＋新建」与 canvas_enter 创建形态共用。 */
+interface CanvasCreateParams {
+    /** 画布名（缺省由 runtime 按 statement 派生）。 */
+    name?: string;
+    statement: string;
+    /** 完成判据（可证伪），至少一条。 */
+    criterias: string[];
+    /** 范围排除（设计文档 enter 参数表记作 scope）。 */
+    scopeExclusions: string[];
+}
+/** grow 批条目：一条 = 一个新节点 + 其与既有图的一条连接边。 */
+interface CanvasGrowItem {
+    /** agent 生成全局唯一 id（时间戳 + 随机）；幂等 upsert 键——崩溃窗口重试不产生重复节点。 */
+    id: string;
+    type: CanvasNodeType;
+    content: string;
+    /** 连接目标：既有节点 id（或 argue 指主干边时的边 id）。 */
+    attachTo: string;
+    /** 连接边类型。 */
+    edge: CanvasEdgeType;
+    /** edge='argue' 时必带极性；同时作为 argument 节点的极性（裁决点 R1：极性是论据字段）。 */
+    edgePolarity?: ArgumentPolarity;
+    /**
+     * type='argument' 时的素材性（缺省 claim）。fact 时核实状态随事件必带
+     * （不变量 5：fact 论据必须携带核实状态）——U2 领域层补写的通道。
+     */
+    materiality?: ArgumentMateriality;
+    /** materiality='fact' 时的核实状态（缺省 false = 已携带「未核实」）。 */
+    factVerified?: boolean;
+    /** type='option' 时可显式标记执行叶子。 */
+    dispatchable?: boolean;
+}
+interface CanvasGrowParams {
+    canvasId: string;
+    /** 批量生长：批内任一校验失败 = 整批拒绝、无部分写入（原子事务）。 */
+    batch: CanvasGrowItem[];
+    /** 变更理由（留痕纪律：没有理由的 agent 改动不可审计）。 */
+    reason: string;
+}
+interface CanvasPatchParams {
+    canvasId: string;
+    nodeId: string;
+    content?: string;
+    /** 执行叶子完成判据编辑。 */
+    criterias?: string[];
+    /** 执行叶子标记变更。 */
+    dispatchable?: boolean;
+    /** fact 论据核实状态翻转。 */
+    factVerified?: boolean;
+    reason: string;
+}
+interface CanvasDecideDirectionParams {
+    canvasId: string;
+    direction: 'top-down' | 'bottom-up';
+    reason: string;
+}
+interface CanvasSelectParams {
+    canvasId: string;
+    /** 被选定方案所属的 question 节点 id。 */
+    questionId: string;
+    optionId: string;
+    /**
+     * 换选迁移语义：同一调用事务内先迁出旧 selected（fromOptionId）再置新，
+     * 旧选中方案的整个子树进入待重审（D9）。不带 replace 时旧选定已存在
+     * → selection_conflict 拒绝（不变量 3）。
+     */
+    replace?: {
+        fromOptionId: string;
+    };
+    /** 对比理由（不变量 3：选择须留对比与理由）。 */
+    reason: string;
+}
+interface CanvasTransitionParams {
+    canvasId: string;
+    nodeId: string;
+    /** 目标生命周期态（合法转移表校验归 U2；rejected 须附否决记录——不可删除）。 */
+    to: CanvasNodeLifecycle;
+    /** 否决记录（to='rejected' 时必填：否决理由，可附复活条件）。 */
+    rejection?: {
+        reason: string;
+        reviveCondition?: string;
+    };
+    reason: string;
+}
+interface CanvasCommentParams {
+    canvasId: string;
+    /** 锚定目标：节点 id 或边 id。 */
+    anchorId: string;
+    text: string;
+}
+interface CanvasCommentRespondParams {
+    canvasId: string;
+    commentId: string;
+    /** 采纳（并落实到图）/ 反驳（留理由）二选一——不允许无视（不变量 8 响应义务）。 */
+    disposition: 'adopted' | 'rebutted';
+    /** 响应留痕（采纳的落实说明 / 反驳的理由）。 */
+    note: string;
+}
+interface CanvasReviewRequestParams {
+    canvasId: string;
+    /** R2+ 轮次的审查范围收窄描述（「上轮处置表 + 攻击点」）；R1 全面审缺省。 */
+    scope?: string;
+}
+/** review-append 单条报告条目输入（id 由 reviewer 生成，幂等 upsert 同 grow）。 */
+interface CanvasReviewEntryInput {
+    id: string;
+    round: number;
+    dimension: ReviewDimension;
+    severity: ReviewSeverity;
+    /** 引用的图元素 id（必须存在于画布——聚合 2 不变量 1）。 */
+    targetId: string;
+    note: string;
+    /**
+     * 支撑度评价（概念 §2.4「边的缺陷经支撑度表达」的写入通道——审查结论随条目落
+     * edge.support，round 由 runtime 按报告轮次注入「审查轮次溯源」）：targetId 须为
+     * 主干边（decompose/resolve，裁决点 R3——论证边不评级），非主干边携带即拒。
+     */
+    supportRating?: SupportRating;
+    /** rating='gap' 的缺口清单（「有缺口附清单」词条语义：至少一条）；sufficient/invalid 不带。 */
+    supportGaps?: string[];
+}
+interface CanvasReviewAppendParams {
+    canvasId: string;
+    /** 报告归属轮次。 */
+    round: number;
+    entries: CanvasReviewEntryInput[];
+}
+interface CanvasReviewResolveParams {
+    canvasId: string;
+    entryId: string;
+    /** 处置三选一（采纳 / 登记后做 / 拒绝留理由）。 */
+    disposition: 'accepted' | 'deferred' | 'rejected';
+    /** 处置说明（拒绝时为拒绝理由）。 */
+    note: string;
+}
+/** converge-check：无业务参数——三门禁校验（不变量 10）+ 置 converged 终态。 */
+interface CanvasConvergeCheckParams {
+    canvasId: string;
+}
+type CanvasExportTarget = {
+    target: 'planning-doc';
+} | {
+    target: 'requirement-card'; /** 需求卡对应的执行叶子节点 id。 */
+    leafId: string;
+};
+interface CanvasExportParams {
+    canvasId: string;
+    target: CanvasExportTarget;
+}
+interface CanvasDispatchParams {
+    canvasId: string;
+    /** 执行叶子节点 id（dispatched 前必须 passed——不变量 7）。 */
+    nodeId: string;
+    /** 下游产物指针（必填：设计文档 / impl-plan 位置，用户手填）。 */
+    pointer: string;
+}
+interface CanvasReadParams {
+    canvasId: string;
+    /** 子树读取：从该节点 id 向下的主干子树；缺省读全量。 */
+    subtree?: string;
+}
+/** 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 {
+    create: CanvasCreateParams;
+    grow: CanvasGrowParams;
+    patch: CanvasPatchParams;
+    'decide-direction': CanvasDecideDirectionParams;
+    select: CanvasSelectParams;
+    transition: CanvasTransitionParams;
+    comment: CanvasCommentParams;
+    'comment-respond': CanvasCommentRespondParams;
+    'review-request': CanvasReviewRequestParams;
+    'review-append': CanvasReviewAppendParams;
+    'review-resolve': CanvasReviewResolveParams;
+    'converge-check': CanvasConvergeCheckParams;
+    export: CanvasExportParams;
+    dispatch: CanvasDispatchParams;
+    read: CanvasReadParams;
+    list: CanvasListParams;
+}
+type CanvasAction = (typeof CANVAS_ACTIONS)[number];
+/** mutate 请求判别联合：按 action 收窄 params（renderer / handler 两侧 switch 同构收窄）。 */
+type CanvasMutateRequest = {
+    [A in CanvasAction]: {
+        action: A;
+        params: CanvasActionParams[A];
+    };
+}[CanvasAction];
+type CanvasMarkerAction = (typeof CANVAS_MARKER_ACTIONS)[number];
+/** enter（canvas_enter 打开形态）：读全量（归属校验在 readState，非 owner → forbidden）；非画布 mutation、不产事件、无登记动作。 */
+interface CanvasEnterParams {
+    canvasId: string;
+}
+/** marker 通道 params 映射 = mutate 词表 params + enter。 */
+interface CanvasMarkerParams extends CanvasActionParams {
+    enter: CanvasEnterParams;
+}
+/** marker 请求条目（extension select 挂起载荷：[{action, params}]，session-manager 同构）。 */
+interface CanvasMarkerRequest {
+    action: CanvasMarkerAction;
+    params: CanvasMarkerParams[CanvasMarkerAction];
+}
+/** mutate 统一两态信封（mcp McpMutationResult 先例；广播 canvas.updated 与本信封
+ * 的成功腿同源同值——调用方拿本 mutation 的事件回执，全量状态经 canvas.get 拉取）。 */
+type CanvasMutateReply = {
+    ok: true;
+    eventId: string;
+    evType: CanvasEventType;
+    summary: string;
+} | {
+    ok: false;
+    error: CanvasError;
+};
+/** canvas.list reply。 */
+interface CanvasListReply {
+    canvases: CanvasListEntry[];
+}
+/** enter / read 的结果：画布全量（打开即完整图——设计目标 1「用户点开即见完整图」）。 */
+type CanvasReadReply = CanvasState;
+declare function isCanvasCreateParams(v: unknown): v is CanvasCreateParams;
+declare function isCanvasGrowParams(v: unknown): v is CanvasGrowParams;
+declare function isCanvasPatchParams(v: unknown): v is CanvasPatchParams;
+declare function isCanvasDecideDirectionParams(v: unknown): v is CanvasDecideDirectionParams;
+declare function isCanvasSelectParams(v: unknown): v is CanvasSelectParams;
+declare function isCanvasTransitionParams(v: unknown): v is CanvasTransitionParams;
+declare function isCanvasCommentParams(v: unknown): v is CanvasCommentParams;
+declare function isCanvasCommentRespondParams(v: unknown): v is CanvasCommentRespondParams;
+declare function isCanvasReviewRequestParams(v: unknown): v is CanvasReviewRequestParams;
+declare function isCanvasReviewAppendParams(v: unknown): v is CanvasReviewAppendParams;
+declare function isCanvasReviewResolveParams(v: unknown): v is CanvasReviewResolveParams;
+declare function isCanvasConvergeCheckParams(v: unknown): v is CanvasConvergeCheckParams;
+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 同款；
+ * 归属过滤字段是通道级的，见 CanvasListParams 注释）。 */
+declare function isCanvasListParams(v: unknown): v is CanvasListParams;
+/** enter（canvas_enter 打开形态）：封闭单键 canvasId。 */
+declare function isCanvasEnterParams(v: unknown): v is CanvasEnterParams;
+/** marker 通道总守卫：action + params 按 marker 词表分派；表外 action 返回 false
+ * （event-adapter / CanvasHandler 据此走结构化错误应答）。 */
+declare function isCanvasMarkerRequest(v: unknown): v is CanvasMarkerRequest;
+/** 材料性守卫（grow item 的 materiality 类型面收窄备用；U2 重建回放读侧消费）。 */
+declare function isArgumentMateriality(v: unknown): v is ArgumentMateriality;
+/** 论据极性守卫（读侧收窄备用）。 */
+declare function isArgumentPolarity(v: unknown): v is ArgumentPolarity;
+
+/**
+ * 权限矩阵：action × actor → 是否合法。逐格对齐设计 §3.1(1) 矩阵表：
+ * - decide-direction / comment / converge-check / dispatch 仅 user（用户裁决性动作，
+ *   agent 侧走对话文本建议 / 代执行边界见设计；review 无）
+ * - review-append 仅 review（reviewer subagent 的报告写回通道）
+ * - read / list 全 actor 开放（查询类）
+ * - select 的 agent 格 = 仅代执行用户明示指令——语义约束落 prompt 指引层（U4），
+ *   runtime 按通道放行、不按意图判定（矩阵此格为 true）
+ */
+declare const CANVAS_ACTOR_MATRIX: Record<CanvasAction, Record<CanvasActor, boolean>>;
+/** 矩阵单格查询（CanvasService 唯一入口的校验原语；表外组合 = false → fail-fast）。 */
+declare function isActionAllowed(action: CanvasAction, actor: CanvasActor): boolean;
+/** 六工具动词族（全部 exposure: "deferred"）：工具名 → 该工具承载的 action 清单。
+ * enter 打开形态走 marker 通道 'enter' 动作（非 mutation、不在本表——本表只登记
+ * mutate 词表落点）；canvas_enter 创建形态落 create。 */
+declare const TOOL_ACTION_MAP: {
+    readonly canvas_enter: readonly ["create"];
+    readonly canvas_edit: readonly ["grow", "patch", "select", "transition", "comment-respond"];
+    readonly canvas_read: readonly ["read"];
+    readonly canvas_review: readonly ["review-request", "review-append", "review-resolve"];
+    readonly canvas_export: readonly ["export"];
+    readonly canvas_list: readonly ["list"];
+};
+type CanvasToolName = keyof typeof TOOL_ACTION_MAP;
+/** 六工具名清单（U4 工具面注册对账用）。 */
+declare const CANVAS_TOOL_NAMES: readonly CanvasToolName[];
+/**
+ * 非工具入口动作（4 个）：不进任何工具、仅 GUI（WS RPC mutate, actor=user）直达的
+ * 用户裁决性动作——「16 action 全部进入映射对账」的另一半（工具可达 12 + GUI-only 4
+ * = 词表 16）。全部仅 user（权限矩阵）：
+ * - decide-direction：方向裁决是终裁决动作，agent 不得自主（方向推荐走对话文本建议）
+ * - comment：评论 = 用户注入议题；响应义务方是 agent（走 comment-respond）
+ * - converge-check：确认收敛 = 用户点击（三门禁校验后置 converged 终态）
+ * - dispatch：派发 = 用户逐叶确认 + 手填下游指针（D8 裁决：派发 = 用户拍板）
+ */
+declare const NON_TOOL_ACTIONS: readonly [{
+    readonly action: "decide-direction";
+    readonly entry: "gui-only（用户拍板：方向裁决是终裁决动作，agent 不得自主）";
+}, {
+    readonly action: "comment";
+    readonly entry: "gui-only（评论 = 用户注入议题；响应义务方是 agent，走 comment-respond）";
+}, {
+    readonly action: "converge-check";
+    readonly entry: "gui-only（确认收敛 = 用户点击，三门禁校验后置终态）";
+}, {
+    readonly action: "dispatch";
+    readonly entry: "gui-only（派发 = 用户逐叶确认 + 手填下游指针，用户拍板）";
+}];
+/** 反查：action 由哪个工具承载（未命中 = 非工具动作，见 NON_TOOL_ACTIONS）。 */
+declare function toolOfAction(action: CanvasAction): CanvasToolName | undefined;
+/** 全部映射动作的并集（对账辅助；一致性测试断言其与 CANVAS_ACTIONS 的关系）。 */
+declare function allToolActions(): CanvasAction[];
+/** 词表全集（对账辅助：-export const 引用，保持三方对账口径单点）。 */
+declare function allCanvasActions(): readonly CanvasAction[];
+
 /**
  * pending entries 差集核心（落盘形态语义：customType 字符串 + 抵消/去重规则）——
  * 跨端单一实现（ext-simplify-13 D3）。
@@ -1651,7 +2325,7 @@ interface SubagentEngineConfigView {
  * 契约两端（此前各持一份同构差集实现，对齐手段是注释）：
  *  - 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 侧，不在本模块）
  *
@@ -1671,19 +2345,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: 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 scanPendingEntries(entries: unknown[]): PendingEntriesScan;
+declare function scanPendingFields(entries: readonly unknown[]): PendingFieldsScan;
 /**
  * 差集本体（规则单点）：register 首见去重 + unregister 全局抵消 + id 非法跳过。
  * 首见判定先于任何消费方过滤（seen.add 后即使调用方对首个 data 过滤丢弃，后续
@@ -1725,5 +2428,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 { ASK_USER_MARKER, type AskUserAnswers, type AskUserOption, type AskUserQuestion, 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, 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, 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, TASK_ENTRY_TYPE, 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, appendExecutionRecord, applyPendingDiff, callMarkerRpc, collectActivePendingIds, dateToOnceCron, derivePhase, extractGui, firstContentText, formatChannelErrorText, formatDuration, formatRelativeTime, formatSchedule, getAskUserAnswer, getAskUserOther, guiComponent, guiResult, guiSetWidget, isAskUserQuestion, 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, 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 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, scanPendingFields, setWidgetDual, snapshotToTask, toolOfAction, transition, truncateSelfReview, uiFormInteract, validateWidgetIconPaths };