@zhushanwen/pi-plan 0.5.1 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # @zhushanwen/pi-plan
 
-轻量级规划模式 pi extension：`/plan [描述]` 触发，只读探索并产出结构化计划文档。与 coding-workflow 的区别：无 gate / review / retrospect，只负责「想清楚再动手」的计划产出（ADR pi-ext-021 prompt-only readonly / pi-ext-022 session-manager state）。
+轻量级规划模式 pi extension：`/plan [描述]` 触发，只读探索并产出结构化计划文档。与 coding-workflow 的区别：无 retrospect/回顾环节与自动 gate，只负责「想清楚再动手」的计划产出 + 执行前的用户审批（ADR pi-ext-021 prompt-only readonly / pi-ext-022 session-manager state）。
 
 ## 用法
 
@@ -18,21 +18,21 @@
 
 ## 计划态生命周期
 
-进入后 agent 限只读工具集（read/bash/grep/find/ls/plan），按注入提示词产出文档：
+进入后 agent 限只读工具集（read/bash/grep/find/ls/plan/ask_user——ask_user 供探索期向用户提问，D10），按注入提示词产出文档：
 
 - **技能流程**（挂载 `--skills`）：按技能 SKILL.md 流程产出文档（AI 自行 read 技能文件）。
 - **模板流程**（未挂载）：从三源发现的模板清单中选型后撰写 plan.md（见下节）。
 
-文档全部就绪后调 `submit-review` 提交审阅；taiji rpc 宿主（`TAIJI_AGENT_EXT_LOG=1` 且 rpc 模式）挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批（approve 确认执行 / revise 提交评论修订，取消走 dismiss 非批准），独立 pi / 非 rpc 形态返回文本软门（对话中反馈评论，满意后调 `complete`）。
+文档全部就绪后先自审（对照需求逐条核覆盖 / 假设审计 / 章节完整性 / 验收场景可执行，自审发现的问题先修文档），再调 `submit-review`（必带 `selfReview` 自审结论）提交审阅；taiji rpc 宿主（`TAIJI_AGENT_EXT_LOG=1` 且 rpc 模式）挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批三键（approve 确认执行 / revise 提交评论修订 / dismiss 搁置——非破坏协议级决策，plan 模式保持、进度不变、被搁置的审批不复活），独立 pi / 非 rpc 形态返回文本软门（对话中反馈评论，满意后调 `complete`）。注意区分「dismiss 搁置」（用户第三键决策）与「取消/超时」（选择框被解散，非批准、不丢状态）。
 
 ## plan 工具
 
 模型经 `plan` tool 驱动状态流转，actions 六项：`enter` / `select-template` / `register-doc` / `submit-review` / `complete` / `abort`。
 
 - `register-doc`：登记一份产物文档（同 fileName 重登 = version+1 覆盖），供 GUI 产物 tab 展示与内容刷新。
-- `submit-review`：全部文档就绪后请求审阅。docs 为空或计划态已退出时返回错误提示（E6 双守卫）。
-- `complete`：先弹执行方式选择（GUI 宿主经统一表单协议单 choice 问题）。选项 = 自动检测的 plan-exec skill 档（≤2 个，label `Execute via skill: <name>`）+ Execute 档（goal 跟踪已整合：可用时先建 goal 跟踪，再按复杂度派发 subagent 并行、小步/紧耦合本会话直执）+ 暂不执行（Not now，留在 plan mode）。headless 无 UI 默认 execute 不弹选择；通道失败（channel-error / non-json）与用户取消同折叠为 complete-cancelled result，留在 plan mode 不炸 turn。
-- `abort`：直接退出。两者退出后恢复工具集；状态落 isActive=false + docs 保留（产物跨重开留存）。
+- `submit-review`：全部文档就绪后请求审阅。**必带非空 `selfReview`（自审硬门，无豁免，含修订后重挂）**：缺失/空 → 纠偏错误不挂审批；文档已变而 selfReview 与上次逐字节相同 → 防照抄袭拒收（必须对新版本重做自审）。docs 为空或计划态已退出时返回错误提示（E6 双守卫）。
+- `complete`：经审批闸口进入执行方式选择（approve 边 → dispatching；未经审批直调被拒并指回 submit-review）。有 plan-exec 技能时弹执行方式选择（GUI 宿主经统一表单协议单 choice 问题）：选项 = ≤2 个技能档（label `Execute via skill: <name>`）+ Execute 档（goal 跟踪已整合：可用时先建 goal 跟踪，再按复杂度派发 subagent 并行、小步/紧耦合本会话直执）+ 暂不执行（later 边：状态落「已批准」，可再调 `complete` 重新选择）。**无 plan-exec 技能（含检测失败降级）时不弹表单，直通 execute**（工具结果明示「无 plan-exec 技能，直接执行」）。无选择解散归口（dissolvedBy 解散来源直传判别）：外部解散（取消/超时/channel-error/non-json）→ review_aborted 边落「已批准」（批准事实保留，可再调 `complete`）；命令解散（`/plan abort` 等 reset 已介入）→ 归口 no-op 不覆写终态。headless 无 UI 默认 execute 不弹选择。
+- `abort`：直接退出。complete/abort 退出后恢复工具集；状态落终态两值 `completed`（批准并派发执行）/ `exited`（主动退出）+ isActive=false，docs 保留（产物跨重开留存），selfReview/resumeHint/指纹快照随退出失效。
 
 ## 执行方式与 plan-exec skill
 
@@ -40,11 +40,11 @@
 
 四根扫描（单根枚举复用 pi 公开导出的 `loadSkillsFromDir`，跨根组装同构 pi 本体加载序）：project `.pi/skills` → 祖先链 `.agents/skills`（近→远，git root 级含）→ `<agentDir>/skills` → `~/.agents/skills`；同名 first-writer-wins + realPath 去重；untrusted 项目跳过前两族。complete 时现扫无缓存（技能热装即见）。
 
-检测失败降级为空集，绝不炸 complete 交互闭环：每根 existsSync 守卫 + 整根 try/catch（EACCES 等 fs 错 → 跳过该根 + warn），单 skill frontmatter 读/解析失败跳过该项。
+检测失败降级为空集，绝不炸 complete 交互闭环：每根 existsSync 守卫 + 整根 try/catch（EACCES 等 fs 错 → 跳过该根 + warn），单 skill frontmatter 读/解析失败跳过该项。检测为空集（含失败降级）时不弹执行方式表单，直通 execute（D7②）。
 
 ## Plan File
 
-模板流程的产出物，存储在 `.taiji-harness/{slug}/plan.md`（slug 截断 30 字符）。含 YAML frontmatter 与模板章节。进入 plan mode 时自动扫描既有 plan 文件供续写。技能流程的产物文档同写在该目录下，经 `register-doc` 登记。
+模板流程的产出物，存储在 `<project>/.tmp/plans/<slug>/plan.md`（slug 截断 30 字符）。含 YAML frontmatter 与模板章节。进入 plan mode 时自动扫描既有 plan 文件供续写。技能流程的产物文档同写在该目录下，经 `register-doc` 登记。
 
 ## 模板
 
@@ -60,4 +60,4 @@
 
 ## 依赖
 
-依赖：`@zhushanwen/extension-protocol`（PLAN_REVIEW_MARKER + PlanReviewRequest/Response 契约 + ui-form（`uiFormInteract` / `FormQuestion`，统一提问表单协议），dependencies）；peer 依赖：`@zhushanwen/pi-goal`（plan 完成后衔接 goal 驱动执行）。
+依赖：`@zhushanwen/extension-protocol`（PLAN_REVIEW_MARKER + PlanReviewRequest/Response 契约 + plan 生命周期状态机与审阅值域契约（`src/extensions/plan/`：transition/derivePhase + 值域守卫/selfReview 截断）+ ui-form（`uiFormInteract` / `FormQuestion`，统一提问表单协议），dependencies）；`@zhushanwen/pi-exec-skills`（plan-exec 技能发现/执行门禁单源，ADR-0074，dependencies）；peer 依赖：`@zhushanwen/pi-goal`（plan 完成后衔接 goal 驱动执行）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-plan",
-  "version": "0.5.1",
+  "version": "1.0.0",
   "description": "Lightweight plan mode for Pi coding agent",
   "type": "module",
   "main": "index.ts",
@@ -25,7 +25,7 @@
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
     "@earendil-works/pi-ai": "^0.84.4",
-    "@zhushanwen/pi-goal": "0.14.7"
+    "@zhushanwen/pi-goal": "0.14.10"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-tui": {
@@ -50,10 +50,12 @@
     "templates/"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.14.0",
-    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/extension-protocol": "0.17.0",
+    "@zhushanwen/pi-exec-skills": "0.2.0",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-llm-shared": "0.10.0"
+    "@zhushanwen/pi-llm-shared": "0.11.0",
+    "@zhushanwen/pi-session-path": "0.1.0"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/skills/plan-ext-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-ext-config
-description: "使用或排查 @zhushanwen/pi-plan（计划模式 plan mode）时加载。说明 /plan 命令用法（--skills / --template / status / abort）、plan 工具六 action（enter / select-template / register-doc / submit-review / complete / abort）、审阅两键裁决（approve / revise）、执行方式选项集（plan-exec skill 检测 + Execute + 暂不执行）、数据存储模型（session JSONL 的 plan-state entry，无独立配置文件）、reviewState 崩溃恢复语义。触发词：plan mode、计划模式、/plan、plan 工具、submit-review、register-doc、plan-state、计划文档登记、审阅挂起、计划模式排查、plan-ext-config。"
+description: "使用或排查 @zhushanwen/pi-plan（计划模式 plan mode）时加载。涵盖 /plan 命令用法、plan 工具六 action、审阅三键裁决与自审硬门、执行方式选项集、session JSONL 存储模型（无独立配置文件）与按 state 崩溃恢复——细节见正文各节。触发词：plan mode、计划模式、/plan、plan 工具、submit-review、selfReview、dismiss、搁置、register-doc、plan-state、计划文档登记、审阅挂起、计划模式排查、plan-ext-config。"
 ---
 
 # plan 使用与存储指南
@@ -28,28 +28,39 @@ description: "使用或排查 @zhushanwen/pi-plan（计划模式 plan mode）时
 - **`enter`**：agent 自助进入（无需用户确认——plan mode 只读无害，进入事实经 GUI PlanModeBar 显形，用户随时可退出）。参数 `requirement` + 可选 `skills`。
 - **`select-template`**：模板流程选型（`--template` 直传后调用会报错）。返回 content 携带胜者模板全文；错名报错自带可用清单自愈。
 - **`register-doc`**：登记一份产物文档（参数 `fileName` 必须是 plan 目录内纯文件名，路径分隔符/`..` 被拒；同 fileName 重登 = version+1 原位覆盖，UI tab 顺序不跳动）。absPath 由扩展从 plan 目录推导，不信任 LLM 申报路径。
-- **`submit-review`**：全部文档就绪后请求审阅（docs 为空或已退出计划态返回错误提示，不挂交互）。
-- **`complete`**：用户 approve 后退出计划态，先弹执行方式选择（见下节）。
+- **`submit-review`**：全部文档就绪后请求审阅（docs 为空或已退出计划态返回错误提示，不挂交互）。**必带 `selfReview` 参数（自审硬门，无豁免）**：提交前对照需求逐条核覆盖 / 假设审计（[UNVERIFIED] 清零或显式列出）/ 章节完整性对照模板 / 验收场景真实可执行，自审发现的问题先修文档再提交；缺失/空 → tool result 纠偏不挂交互；文档已变而 selfReview 与上次逐字节相同 → 防照抄袭拒收（必须对新版本重做自审）。
+- **`complete`**：用户 approve 后退出计划态，先弹执行方式选择（见下节）。未经审批闸口（如 planning 态直调）会被拒并指回 submit-review——「执行前的用户审批」是结构性保证。
 - **`abort`**：直接退出。
 
 退出（complete/abort）恢复完整工具集；`plan-state` 落 isActive=false，docs 清单保留（产物文档跨重开可回看，至下次 /plan 同 slug 覆写）。
 
-## 审阅闭环（submit-review → 两键裁决）
+## 审阅闭环（submit-review → 三键裁决）
 
-- **taiji rpc 宿主**（`TAIJI_AGENT_EXT_LOG=1` 且 `mode==='rpc'`）：挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批条，用户两键裁决——**approve**（确认执行，自动走 complete 流程）/ **revise**（提交 `{quote, comment}[]` 评论，注入对话要求修订）。取消（dismiss）非批准：result 明确禁止实施、停止审批循环等用户指示。
+- **taiji rpc 宿主**（`TAIJI_AGENT_EXT_LOG=1` 且 `mode==='rpc'`）：挂 `PLAN_REVIEW_MARKER` select 弹 GUI 审批条，payload 携带 docs + selfReview（写侧 4KB 截断），用户三键裁决——**approve**（确认执行，自动走 complete 流程，状态进 dispatching）/ **revise**（提交 `{quote, comment}[]` 评论，注入对话要求修订，状态进 revising）/ **dismiss 搁置**（D3 协议级决策，非破坏：不杀 turn、不丢状态，状态回 planning，被搁置的审批不复活；tool result 指示 agent 告知用户已搁置并询问下一步，不实施改动）。选择框被解散（turn abort / TUI 取消）非批准：按归口判别走 review_aborted 边或 no-op，result 明确禁止实施。
 - **独立 pi / 非 rpc 形态**：文本软门——result 指示 agent 请用户直接在对话中反馈；用户满意确认后 agent 调 `complete`。
-- **修订闭环**：revise 后逐条评论 rewrite 文件 + 重新 `register-doc`（version+1），全部处理完再调 `submit-review` 重挂，循环直至 approve。
+- **修订闭环**：revise 后逐条评论 rewrite 文件 + 重新 `register-doc`（version+1），**对新版本重做自审**后带新 selfReview 再调 `submit-review` 重挂，循环直至 approve。
 - **重提交无变化检测**：上次 submit-review 后无任何 register-doc（docs 指纹相同）再次 submit-review 时，result 末行追加确定性警告，提示必须先 rewrite + re-register。
+- **降级恢复（重新提交审批）**：state=reviewing 而无挂起审批（会话重启等）时，宿主降级分支提供「重新提交审批」按钮——点击注入一条固定文案的用户可见消息，agent 收到后**直接** `submit-review` 重挂（提示词已带此纪律）；会话重启时 E3 steer 会携带上轮 selfReview 全文供原样回传（该文档集的自审不重做，但过门义务不豁免）。
 
 ## 执行方式选项集（complete 时）
 
 选项 = **≤2 个检测到的 plan-exec skill 档**（label `Execute via skill: <name>`）+ **Execute 档** + **暂不执行（Not now）**：
 
-- **plan-exec skill 档**：skill 作者在 SKILL.md frontmatter 标记 `plan-exec: true` 即被提议。四根扫描（project `.pi/skills` → 祖先链 `.agents/skills` → `<agentDir>/skills` → `~/.agents/skills`，同构 pi 本体加载序，untrusted 项目跳过前两族），root 序同名 first-writer-wins，取前 2 个。complete 时现扫无缓存（技能热装即见）；检测失败降级为空集，绝不阻断交互。
+- **plan-exec skill 档（标记写法）**：skill 作者在 SKILL.md **frontmatter 加一行 `plan-exec: true`**（严格布尔 true，字符串 "true" 不算）即被提议，例如：
+
+  ```yaml
+  ---
+  name: dev-flow
+  description: ...
+  plan-exec: true
+  ---
+  ```
+
+  四根扫描（project `.pi/skills` → 祖先链 `.agents/skills` → `<agentDir>/skills` → `~/.agents/skills`，同构 pi 本体加载序，untrusted 项目跳过前两族），root 序同名 first-writer-wins，取前 2 个。complete 时现扫无缓存（技能热装即见）；检测失败降级为空集，绝不阻断交互。无任何 plan-exec 技能时不弹执行方式表单（无技能时确认执行直通，不弹恒两项的死表单）。
 - **Execute 档**：goal 跟踪已整合——goal 扩展可用时先建 goal 跟踪（`/goal`），再按复杂度执行：独立可并行任务派发 subagent、小步/紧耦合在本会话直执；goal 不可用/启动失败降级为直接执行（notify 提示 + result 带恢复动作）。
-- **暂不执行**：留在 plan mode，不派发实施。
+- **暂不执行**：留在 plan mode，状态落「已批准」（later 边），不派发实施——需要时说『执行』或再调 `complete` 重新选执行方式。
 
-headless（json/print 无 UI）默认 execute 不弹选择；通道失败（channel-error / non-json）与用户取消同折叠为 complete-cancelled result，留在 plan mode 不炸 turn。
+headless（json/print 无 UI）默认 execute 不弹选择；交互框被解散（取消 / 超时 / channel-error / non-json）按「无选择解散」归口：无命令介入时状态落「已批准」（批准事实保留）+ result 可再调 complete；plan abort 等命令已退出时归口 no-op（不覆写终态）。
 
 **goal 桥结构建议**：计划文档建议包含 `## Implementation Steps` 编号步骤节——Execute 档的 goal 步骤提取硬依赖该节；缺失会退化 fallback（扫全部编号项）或提取失败（no-steps，有恢复文案）。
 
@@ -58,22 +69,26 @@ headless（json/print 无 UI）默认 execute 不弹选择；通道失败（chan
 **当前版本采用 session JSONL 的 append-only event sourcing，没有独立数据文件。**
 
 - 每次状态变更调 `pi.appendEntry('plan-state', {...})`，customType 固定为 `plan-state`；重建时取 session 内**最后一条** plan-state entry 为当前态（逐字段白名单降级读，旧版 entry 缺字段归一为空/无值）。
-- 字段：`isActive` / `planFilePath` / `requirement` / `templateName` / `templateProvidedPath`（--template 直传标记）/ `skills`（挂载技能名）/ `docs`（产物清单 `PlanDocMeta[]`：fileName + absPath + sourceSkill + version）/ `reviewState` / `lastSubmitReviewDocsFingerprint` / `reviewStateSource`。
+- 字段：`isActive` / `planFilePath` / `requirement` / `templateName` / `templateProvided`（布尔，--template 直传标记；旧字段 `templateProvidedPath` 已停写，读侧映射 readTemplateProvided）/ `skills`（挂载技能名）/ `docs`（产物清单 `PlanDocMeta[]`：fileName + absPath + sourceSkill + version）/ `state`（生命周期状态八值：idle/planning/reviewing/revising/approved/dispatching/completed/exited——取代式演进，旧字段 `reviewState`/`reviewStateSource` 已停写，读侧映射：awaiting→reviewing、revising→revising、无→planning|idle 按 isActive，reviewStateSource:'resubmit'→resumeHint:'resubmit'）/ `selfReview`（上次提交的自审结论，≤4KB——E3 回传源 + 防照抄比较基线）/ `resumeHint`（降级等待原因：`resubmit` 会话重启待重提交，清除点三处，不跨轮残留）/ `lastSubmitReviewDocsFingerprint`。
 - **产物文档本体**写在 `<cwd>/.tmp/plans/<slug>/`（slug 截断 30 字符）——文档是普通文件，agent 经 bash 写入；`register-doc` 只登记元数据。未产任何文档即退出会清理空 slug 目录（非空一律保留）。
 - **模板三源发现**（同名 last-writer-wins，项目 > 用户 > 内置）：内置（包内 `templates/`，5 个）+ 用户级 `~/.agents/plans/*.md` + 项目级 `<project>/.agents/plans/*.md`。进入时清单以 `<available-plans>` 段一次性注入。
 
-## reviewState 崩溃恢复（E3）
+## 崩溃恢复（E3，按 state 查表）
 
-`reviewState` 两值：`awaiting`（submit-review 挂起前落盘）| `revising`（revise 消费后落盘）| 无值 = 进行中。挂起的交互（审批 select / 执行方式 form）随 pi 进程消亡，但持久态经 entry 存活：
+挂起的交互（审批 select / 执行方式 form）随 pi 进程消亡，但持久态经 entry 存活。session 重启（session_start）时按 `state` 查表恢复：
 
-- session 重启（session_start）时若 `reviewState='awaiting'`：steer 指示 agent 重调 `submit-review` 重挂审批，并落 `reviewStateSource='resubmit'`（GUI 据此渲染「会话已重启，尚未重新提交」降级态；submit-review 重挂起时清空）。
-- `reviewState='revising'`：steer 指示继续按已注入的评论修订文档并重新提交。
-- 「approve 后执行方式选择窗口中断」不自动恢复（与探索期在持久态上不可区分，防误报），由用户重发消息自然恢复。
+- `state='reviewing'`：steer 指示 agent 重调 `submit-review` 重挂审批（**携带上轮 selfReview 全文**供原样回传——该文档集的自审不重做，过门义务不豁免），并落 `resumeHint='resubmit'`（GUI 据此渲染「会话已重启，尚未重新提交」降级态；submit-review 重挂起时清空）。
+- `state='revising'`：steer 指示继续按已注入的评论修订文档并重新提交。
+- `state='dispatching'`：执行方式选择窗口中断恢复（D5 E3 新支）——先按 review_aborted 边落 `approved`（批准事实保留），再 steer 指示重调 `complete` 重新发起执行方式选择。
+- 其余态（planning/approved/终态）不打扰。
+- 旧 entry（无 state 字段）经 reviewState 映射后同样落本表。
 
 ## 排障
 
 - **submit-review 返回「taiji host does not understand the plan review marker」**：taiji 宿主版本过旧（select 回显 payload 的确定性识别）。不要重挂（会同样回显循环），指引升级 taiji 或固定 plan 扩展版本。
-- **submit-review 返回 cancelled**：用户 dismiss 或 plan mode 退出——非批准，禁止实施，等用户指示。
+- **submit-review 返回 no-self-review / stale-self-review**：自审硬门拒收（D9①）——前者补自审后带 selfReview 重调；后者是文档已变而自审照抄，必须对新版本重做自审。
+- **submit-review 回传 decision 不在值域（unknown-decision）**：落 bad-response 出口、result 引导重挂（重挂即恢复）；版本错配信号只在日志 warn 留痕——原子发版下生产不可达（唯一窗口 = dev-link 版本错开），生产出现 = 错配组合真实可达的反证，恢复动作 = dev-link 对齐版本后重试。
+- **submit-review 返回 cancelled / review-interrupted**：审批选择框被解散——非批准，禁止实施，等用户指示；cancelled = plan mode 已退出（命令解散），review-interrupted = plan 模式保持在规划态（外部解散，可按用户要求重挂）。
 - **重提交总带「no documents changed」警告**：必须先 rewrite 文件 + `register-doc`（version+1）再 submit-review，警告按 docs 指纹逐次检测。
 - **plan-exec skill 没出现在执行选项里**：确认 frontmatter 有 `plan-exec: true`（严格布尔 true，字符串 "true" 不算）；确认 skill 过了 pi 的 description 必填门且未被 settings overrides（`-`/`!`）禁用；untrusted 项目不扫 `.pi/skills` 与祖先链两族。
 - **goal 跟踪未启动（no-steps / plan-unreadable 等）**：result 文本带逐原因恢复动作（如补 `## Implementation Steps` 节后重调 complete）；goal 扩展未装时属正常降级（直接执行）。
@@ -81,6 +96,6 @@ headless（json/print 无 UI）默认 execute 不弹选择；通道失败（chan
 
 ## 备注
 
-- **宿主信号**：taiji runtime 对托管 pi 恒注入 `TAIJI_AGENT_EXT_LOG=1`（引导文案注入 + marker 交互判据之一）；marker 交互另需 `mode==='rpc'`，env 泄漏到独立 pi TUI 时回落文本软门（不挂乱码 select）。
-- **计划态工具白名单**：read / bash / grep / find / ls / plan——bash 在白名单内，文件写约束来自注入的计划模式提示词（产物只写 plan 目录）。
+- **宿主信号**：taiji runtime 对托管 pi 恒注入 `TAIJI_AGENT_EXT_LOG=1`（扩展日志落盘开关 + marker 交互宿主分流判据）；marker 交互另需 `mode==='rpc'`，env 泄漏到独立 pi TUI 时回落文本软门（不挂乱码 select）。
+- **计划态工具白名单**：read / bash / grep / find / ls / plan / ask_user（D10：探索期提问可用；ask-user 扩展被禁时 pi 静默跳过，回退对话流提问）——bash 在白名单内，文件写约束来自注入的计划模式提示词（产物只写 plan 目录）。
 - **无配置 schema 可编辑**：plan 的所有状态都由运行时命令/工具产生，没有可手动编辑的配置文件。

package/src/__tests__/active-path.test.ts

@@ -0,0 +1,204 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+// index.ts 只做装配：mock 掉子模块注册函数，只捕获 pi.on 的 hook、sessions 缓存与
+// widget 刷新（session_tree handler 纯重建断言的观察面）
+vi.mock("../tool.js", () => ({
+  registerPlanTool: vi.fn(
+    (_pi: unknown, planCtx: { states: Map<string, unknown> }) => {
+      captured.sessions = planCtx.states as Map<string, import("../state.js").PlanState>;
+    },
+  ),
+  PLAN_MODE_TOOLS: ["read", "bash", "grep", "find", "ls", "plan"],
+}));
+vi.mock("../command.js", () => ({ registerPlanCommand: vi.fn() }));
+vi.mock("../widget.js", () => ({ updatePlanWidget: vi.fn() }));
+
+import planExtension from "../index.js";
+import { updatePlanWidget } from "../widget.js";
+import {
+  DEFAULT_PLAN_STATE,
+  getPlanState,
+  type PlanSessionMap,
+  type PlanState,
+  reconstructPlanState,
+} from "../state.js";
+
+/**
+ * U6b：reconstructPlanState 接活跃路径裁剪 + session_tree handler 即时重建。
+ * 被撤子树的 plan-state entry 不进重建态；handler 为纯重建体（无 steer / 写盘副作用）
+ * 且缓存同步更新（getPlanState 缓存命中 = 最新重建态）。
+ */
+
+const captured: { sessions?: PlanSessionMap } = {};
+
+type Handler = (event: unknown, ctx: ExtensionContext) => Promise<unknown> | unknown;
+
+function planStateEntry(id: string, parentId: string | null, data: Record<string, unknown>) {
+  return { type: "custom", id, parentId, timestamp: "2026-09-24T00:00:00.000Z", customType: "plan-state", data };
+}
+
+/** 撤回后真实形态：label entry 落文件尾（parentId = 回退后叶子） */
+function labelEntry(id: string, parentId: string | null) {
+  return { type: "label", id, parentId, timestamp: "2026-09-24T00:00:01.000Z", targetId: "u-x", label: "taiji:revoked" };
+}
+
+function makeCtx(entries: unknown[], leafId: string | null): ExtensionContext {
+  return {
+    sessionManager: {
+      getSessionId: () => "test-session",
+      getEntries: () => entries,
+      getLeafId: () => leafId,
+    },
+  } as unknown as ExtensionContext;
+}
+
+describe("reconstructPlanState 活跃路径裁剪（U6b）", () => {
+  it("有分支 fixture：被撤子树的 plan-state entry 不进重建态——逆序取活跃路径内最后一条", () => {
+    // 树：e1(base) → e2(active-branch)；e1 → e3(revoked-branch，物理后写=被撤子树)；
+    // 撤回落 label 锚 L（parentId = 回退后叶子 e2），leafId = L → 活跃路径 {L, e2, e1}
+    const entries = [
+      planStateEntry("e1", null, { isActive: true, planFilePath: "/p/base.md", requirement: "base", templateName: "" }),
+      planStateEntry("e2", "e1", { isActive: true, planFilePath: "/p/active.md", requirement: "active-branch", templateName: "" }),
+      planStateEntry("e3", "e1", { isActive: true, planFilePath: "/p/revoked.md", requirement: "revoked-branch", templateName: "" }),
+      labelEntry("L", "e2"),
+    ];
+
+    const state = reconstructPlanState(makeCtx(entries, "L"));
+
+    // 逆序扫描在裁剪后 entries 内取第一条：e2（active-branch），非物理最后的 e3
+    expect(state.requirement).toBe("active-branch");
+    expect(state.planFilePath).toBe("/p/active.md");
+  });
+
+  it("活跃路径内无 plan-state（plan 进入随子树整个被撤）→ 重建 DEFAULT，不回退到旧分支 entry", () => {
+    // 无裁剪的旧实现逆序全量扫描会命中 e2（被撤子树）——这正是撤回要封堵的注入面
+    const entries = [
+      { type: "message", id: "e1", parentId: null, timestamp: "t", message: { role: "user", content: "hi" } },
+      planStateEntry("e2", "e1", { isActive: true, planFilePath: "/p/revoked.md", requirement: "revoked", templateName: "" }),
+      labelEntry("L", "e1"),
+    ];
+
+    const state = reconstructPlanState(makeCtx(entries, "L"));
+
+    expect(state.isActive).toBe(false);
+    expect(state.requirement).toBe("");
+    expect(state).toEqual({ ...DEFAULT_PLAN_STATE });
+  });
+
+  it("无分支回归：leafId = 文件尾 → 逆序全量取最后一条（现行为不变）", () => {
+    const entries = [
+      planStateEntry("e1", null, { isActive: true, requirement: "first", templateName: "" }),
+      planStateEntry("e2", "e1", { isActive: false, requirement: "second-final", templateName: "" }),
+    ];
+
+    const state = reconstructPlanState(makeCtx(entries, "e2"));
+
+    expect(state.requirement).toBe("second-final");
+    expect(state.isActive).toBe(false);
+  });
+
+  it("leafId 防御：null / 指向不存在 entry → 回退文件尾全量逆序（不静默清空重建态）", () => {
+    const entries = [
+      planStateEntry("e1", null, { isActive: true, requirement: "first", templateName: "" }),
+      planStateEntry("e2", "e1", { isActive: true, requirement: "tail-snapshot", templateName: "" }),
+    ];
+
+    for (const leafId of [null, "missing-id"]) {
+      const state = reconstructPlanState(makeCtx(entries, leafId));
+      expect(state.requirement).toBe("tail-snapshot");
+    }
+  });
+});
+
+describe("环状 parentId 防御（损坏文件 / 非 pi 产出写入）", () => {
+  it("环状 parentId（a↔b，leafId 指向环内）→ 回溯终止不挂死，重建完成且不抛错", () => {
+    // 环：a.parentId=b、b.parentId=a；leafId=a → 回溯 a→b→(二次命中 a) 守卫终止
+    const entries = [
+      planStateEntry("a", "b", { isActive: true, planFilePath: "/p/cycle-a.md", requirement: "cycle-a", templateName: "" }),
+      planStateEntry("b", "a", { isActive: true, planFilePath: "/p/cycle-b.md", requirement: "cycle-b", templateName: "" }),
+    ];
+
+    const state = reconstructPlanState(makeCtx(entries, "a"));
+
+    // 终止形态（实现语义）：activeIds = {a, b}，逆序扫描命中回溯链上最后一条 plan-state b
+    expect(state.requirement).toBe("cycle-b");
+    expect(state.planFilePath).toBe("/p/cycle-b.md");
+  });
+});
+
+describe("session_tree handler 即时重建（U6b：纯重建体 + 缓存同步）", () => {
+  type PiMock = ExtensionAPI & {
+    sendMessage: ReturnType<typeof vi.fn>;
+    appendEntry: ReturnType<typeof vi.fn>;
+    setActiveTools: ReturnType<typeof vi.fn>;
+  };
+
+  function setup(): { handlers: Map<string, Handler>; pi: PiMock } {
+    const handlers = new Map<string, Handler>();
+    const pi = {
+      on: vi.fn((event: string, handler: Handler) => {
+        handlers.set(event, handler);
+      }),
+      sendMessage: vi.fn(),
+      setActiveTools: vi.fn(),
+      appendEntry: vi.fn(),
+    } as unknown as PiMock;
+    planExtension(pi);
+    return { handlers, pi };
+  }
+
+  const branchedEntries = [
+    planStateEntry("e1", null, { isActive: true, planFilePath: "/p/base.md", requirement: "base", templateName: "" }),
+    planStateEntry("e2", "e1", { isActive: true, planFilePath: "/p/active.md", requirement: "active-branch", templateName: "" }),
+    planStateEntry("e3", "e1", { isActive: true, planFilePath: "/p/revoked.md", requirement: "revoked-branch", templateName: "" }),
+    labelEntry("L", "e2"),
+  ];
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.sessions = undefined;
+  });
+
+  it("纯重建：无 sendMessage / appendEntry / setActiveTools 副作用，只重建内存态 + widget 刷新", async () => {
+    const { handlers, pi } = setup();
+    // 预填 stale 缓存：模拟撤回前已缓存的旧分支态（getPlanState 缓存命中短路的 stale 窗口）
+    captured.sessions!.set("test-session", {
+      ...DEFAULT_PLAN_STATE,
+      isActive: true,
+      requirement: "stale-revoked",
+    });
+
+    await handlers.get("session_tree")!({ type: "session_tree" }, makeCtx(branchedEntries, "L"));
+
+    // 纯重建体：绝不复刻 session_start 块的 E3 steer / persist / 工具限制副作用
+    // （本事件由撤回编排触发——steer 会让撤回编排自己注入消息，persist 会污染新分支）
+    expect(pi.sendMessage).not.toHaveBeenCalled();
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    // widget 刷新（显示面与重建态一致）
+    expect(updatePlanWidget).toHaveBeenCalledTimes(1);
+  });
+
+  it("缓存同步：sessions 缓存更新为重建态——getPlanState 缓存命中返回活跃路径态而非 stale", async () => {
+    const { handlers } = setup();
+    captured.sessions!.set("test-session", {
+      ...DEFAULT_PLAN_STATE,
+      isActive: true,
+      requirement: "stale-revoked",
+    });
+
+    await handlers.get("session_tree")!({ type: "session_tree" }, makeCtx(branchedEntries, "L"));
+
+    // 「缓存命中 = 最新重建态」：stale 窗口消除（压缩摘要注入面读 getPlanState 不再拿到被撤 requirement）
+    const cached = captured.sessions!.get("test-session");
+    expect(cached?.requirement).toBe("active-branch");
+    expect(cached?.requirement).not.toBe("stale-revoked");
+
+    // 缓存命中路径直接返回重建态对象（不再触发 reconstruct）
+    const ctx = makeCtx(branchedEntries, "L");
+    const hit = getPlanState(captured.sessions!, "test-session", ctx);
+    expect(hit).toBe(cached);
+    expect(hit.requirement).toBe("active-branch");
+  });
+});

package/src/__tests__/command.test.ts

@@ -24,13 +24,14 @@ import * as path from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { parsePlanArgs, registerPlanCommand, resolveTemplateFile } from "../command.js";
-import { MAX_PLAN_REQUIREMENT_LENGTH, PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
+import type { PlanAbortControllers } from "../state.js";
+import { createPlanCtx, freshPendingSelect, MAX_PLAN_REQUIREMENT_LENGTH, PLAN_CONTEXT_CUSTOM_TYPE } from "../state.js";
 
 const ALL_TOOL_NAMES = ["read", "bash", "grep", "find", "ls", "plan", "write", "edit"];
 
 function createMocks() {
   let capturedHandler: (args: string, ctx: ExtensionContext) => Promise<void>;
-  const controllers = new Map<string, AbortController>();
+  const planCtx = createPlanCtx();
 
   const pi = {
     registerCommand: vi.fn((_name: string, def: { handler: (args: string, ctx: ExtensionContext) => Promise<void> }) => {
@@ -47,6 +48,7 @@ function createMocks() {
     cwd: "/tmp/test-project",
     sessionManager: {
       getSessionId: () => "test-session",
+      getLeafId: () => null,
       getEntries: () => [] as unknown[],
     },
     ui: {
@@ -60,7 +62,8 @@ function createMocks() {
   return {
     pi,
     ctx,
-    controllers,
+    planCtx,
+    controllers: planCtx.controllers,
     getHandler: () => capturedHandler!,
   };
 }
@@ -74,7 +77,7 @@ describe("registerPlanCommand", () => {
   let pi: ExtensionAPI;
   let ctx: ExtensionContext;
   let handler: (args: string, ctx: ExtensionContext) => Promise<void>;
-  let controllers: Map<string, AbortController>;
+  let controllers: PlanAbortControllers;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -82,8 +85,7 @@ describe("registerPlanCommand", () => {
     pi = mocks.pi;
     ctx = mocks.ctx;
     controllers = mocks.controllers;
-    const sessions = new Map();
-    registerPlanCommand(pi, sessions, controllers);
+    registerPlanCommand(pi, mocks.planCtx);
     handler = mocks.getHandler();
   });
 
@@ -93,38 +95,54 @@ describe("registerPlanCommand", () => {
 
   // --- abort subcommand ---
 
-  it("abort: notifies 'No active plan mode' when idle", async () => {
+  it("abort（idle 常态格）: warn 纠偏文案 + 幂等退出——不落盘、工具集幂等恢复（D-B1-1 单入口守卫极性，原 info no-op 取消）", async () => {
     await handler("abort", ctx);
-    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "info");
-    expect(pi.setActiveTools).not.toHaveBeenCalled();
+    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("No active plan mode.", "warning");
+    // ④ 工具集照常幂等恢复（idle 格已是全量，重设全量 = 可观察零变化）
+    expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
+    // ② 跳过：idle 删 exit 边后 ok:false 不落盘（无噪音 exited entry）
+    expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
-  it("abort: resets state and restores tools when active", async () => {
-    // Enter plan mode first — handler uses the sessions map from registerPlanCommand closure
-    await handler("implement user auth", ctx);
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
-    vi.clearAllMocks();
-
-    // Now abort — state is active in the sessions map
-    await handler("abort", ctx);
-
-    expect(pi.setActiveTools).toHaveBeenCalledWith(ALL_TOOL_NAMES);
-    expect((ctx as ReturnType<typeof createMocks>["ctx"]).ui.notify).toHaveBeenCalledWith("Plan mode aborted.", "info");
+  it("abort（终态格 isActive=false）: warn 纠偏指令文案 + 不落盘（V1 ⑤ 幂等退出锚）", async () => {
+    // 注入终态格：上一轮已 complete，缓存重建自 entries（空）→ 直接预置 sessions 难以
+    // 穿透 handler 闭包，改走 entries 注入 completed 残留形态
+    const terminalCtx = {
+      ...ctx,
+      sessionManager: {
+        getSessionId: () => "test-session",
+        getEntries: () => [
+          {
+            type: "custom",
+            customType: "plan-state",
+            data: { isActive: false, state: "completed", planFilePath: "", requirement: "", templateName: "" },
+          },
+        ],
+      },
+    } as unknown as ExtensionContext;
+    await handler("abort", terminalCtx);
+    expect(terminalCtx.ui.notify).toHaveBeenCalledWith(
+      expect.stringContaining("Plan mode is not active"),
+      "warning",
+    );
+    // completed 终态记录不被 exited 覆写（ok:false 跳过状态值写入，isActive=false 非坏格）
+    expect(pi.appendEntry).not.toHaveBeenCalled();
   });
 
-  it("abort 联动（E10）：controller.abort() 先于 resetPlanState 的 entry 落盘", async () => {
+  it("abort 联动（E10）：controller.abort() 先于 resetPlanState 的 entry 落盘，markDissolved('self') 先行打标", async () => {
     await handler("implement user auth", ctx);
     vi.clearAllMocks();
 
-    // 模拟一个挂起 select 的 controller（submit-review / complete 执行方式两处共用注册表）
-    const controller = new AbortController();
-    const abortSpy = vi.spyOn(controller, "abort");
-    controllers.set("test-session", controller);
+    // 模拟一个挂起 select 的 PendingSelect（submit-review / complete 执行方式两处共用注册表）
+    const pending = freshPendingSelect(controllers, "test-session");
+    const abortSpy = vi.spyOn(pending.controller, "abort");
 
     await handler("abort", ctx);
 
-    // 挂起 select 被 abort（→ resolve undefined → tool execute 已取消分支 → turn 结束 → settled → busy defer 恢复）
-    expect(controller.signal.aborted).toBe(true);
+    // 挂起 select 被 abort（→ resolve undefined → tool execute 归口分支 → turn 结束 → settled → busy defer 恢复）
+    expect(pending.controller.signal.aborted).toBe(true);
+    // D-B1-2：入口解散先打 'self' 标（同步先于 abort，等待处归口按来源直传判别）
+    expect(pending.dissolvedBy).toBe("self");
     // 顺序断言：abort 必须先于 reset entry 落盘（反序 = 挂起 select 无人 resolve → session 卡死）
     const resetCallIndex = (pi.appendEntry as ReturnType<typeof vi.fn>).mock.calls.findIndex(
       (c) => (c[1] as { isActive?: boolean }).isActive === false,
@@ -168,7 +186,7 @@ describe("registerPlanCommand", () => {
       "/tmp/test-project/.tmp/plans/implement-user-auth",
       { recursive: true },
     );
-    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+    expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("[PLAN MODE]")));
     expect(pi.sendMessage).toHaveBeenCalledWith(...planContextMessage(expect.stringContaining("Implement User Auth")));
     expect(pi.appendEntry).toHaveBeenCalledWith("plan-state", {
@@ -176,9 +194,13 @@ describe("registerPlanCommand", () => {
       planFilePath: "/tmp/test-project/.tmp/plans/implement-user-auth/plan.md",
       requirement: "Implement User Auth",
       templateName: "",
+      templateProvided: undefined,
       skills: [],
       docs: [],
-      reviewState: undefined,
+      state: "planning",
+      selfReview: undefined,
+      resumeHint: undefined,
+      lastSubmitReviewDocsFingerprint: undefined,
     });
   });
 
@@ -221,6 +243,7 @@ describe("registerPlanCommand", () => {
       ...ctx,
       sessionManager: {
         getSessionId: () => "test-session",
+        getLeafId: () => null,
         getEntries: () => [
           {
             type: "custom",
@@ -327,11 +350,11 @@ describe("registerPlanCommand", () => {
           isActive: true,
           requirement: "retro meeting",
           templateName: "retro-template",
-          templateProvidedPath: "/tmp/test-project/docs/retro-template.md",
+          templateProvided: true,
           skills: [],
         }),
       );
-      expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan"]);
+      expect(pi.setActiveTools).toHaveBeenCalledWith(["read", "bash", "grep", "find", "ls", "plan", "ask_user"]);
       const prompt = sentMessage();
       // 直传声明 + 全文内嵌（文件内容直达模型，不赌自发 read——D5）
       expect(prompt).toContain("template was provided via --template");
@@ -349,7 +372,7 @@ describe("registerPlanCommand", () => {
 
       expect(pi.appendEntry).toHaveBeenCalledWith(
         "plan-state",
-        expect.objectContaining({ isActive: true, templateName: "retro template", templateProvidedPath: spacedAbs }),
+        expect.objectContaining({ isActive: true, templateName: "retro template", templateProvided: true }),
       );
       const prompt = sentMessage();
       expect(prompt).toContain(spacedAbs);