dsh-plan-completion 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 All notable changes to this project are documented here.
 Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versioning: SemVer.
 
+## [0.1.2] - 2026-11-02
+
+### Added
+- Plan persistence: the plan plus the last suggestion are written per session to a local file
+  store (`storageDir/plans/<base64url(sessionId)>.json`, atomic temp+rename). After a DSH restart,
+  `GET /state` hydrates the persisted plan before responding, so the previous plan/version and
+  suggestion are visible immediately (no model call needed).
+- New config: `persistPlans` (default true) and `storageDir` (default `~/.dsh/plan-completion-data`,
+  `~` expanded; `DSH_PLAN_COMPLETION_STORE_DIR` also honored). `persistPlans:false` returns to
+  memory-only behavior.
+- Persisted writes happen on every committed generation, user edit (`/steps`) and are deleted by
+  `/reset`; warm backfill sees the persisted plan and reports `already` instead of re-generating.
+- `store.getState()` / `put(plan, {cas, suggestion})` in both memory and file stores.
+- 9 new tests: store persistence semantics (memory + file, corrupt record tolerance) and a
+  restart-simulation integration suite (restore on mount, continue patching after restart, reset
+  clears disk).
+
+### Changed
+- `npm test` now reports **120/120** tests.
+
+### Security
+- Persisted files contain conversation-derived plan/suggestion text (plain JSON, unencrypted, no
+  automatic expiry); see `docs/security.md`. `persistPlans:false` disables disk persistence.
+
 ## [0.1.1] - 2026-11-02
 
 ### Fixed

package/README.md

@@ -69,6 +69,14 @@ Client 侧用 `fetch(..., {credentials:'same-origin'})`；Electron 的 `dsh-app:
 
 Client 侧关键 API（实测）：`inputActions.captureInsertion()` 返回 `{start,end,draftRev}`；`insertText(text, span)`；`setDraft(text)`；`useInput(s => s)` 返回 `{draft, attachmentIds, draftRev, phase, occurrences, queue}`。
 
+## 计划持久化（v0.1.2）
+
+- 计划 + 最近一条建议按会话持久化到本地文件（`storageDir/plans/<base64url(sessionId)>.json`，原子写）；
+- 插件启动/打开会话时按需恢复（`GET /state` 前 hydrate），**DSH 重启后仍能看到原计划与版本**，无需等下一回合；
+- 每次成功提交（含用户编辑、reset）同步落盘；`reset` 会同时删除磁盘记录；
+- 默认目录 `~/.dsh/plan-completion-data`；可用 `storageDir` 改到别处，`persistPlans: false` 退回纯内存；
+- 注意：存储为本地明文 JSON（含计划/建议文本，可能来自会话）；不加密、不自动清理，不适合多用户共享机器。
+
 ## 模型路由与隐私
 
 - 仅使用宿主 `agentDefaultModel.currentSelection()` 当前默认的 provider/model，不自动改投其他已配置供应商；无可用路由时使用启发式。该默认值不一定是历史会话原先使用的模型。
@@ -90,6 +98,8 @@ Client 侧关键 API（实测）：`inputActions.captureInsertion()` 返回 `{st
         maxTokensRewrite: 1200
         warmBackfill: true
         modelCalls: true         # false：本插件仅用启发式，不向模型发送内容
+        persistPlans: true       # false：计划只存内存
+        storageDir: '~/.dsh/plan-completion-data'
         enableDebugRoutes: false   # 本地调试时才打开
         # debugDir: '<本地日志目录>'  # 可选；发布版留空
 ```
@@ -100,6 +110,8 @@ Client 侧关键 API（实测）：`inputActions.captureInsertion()` 返回 `{st
 | `maxTokensPatch` | 400 | patch 路径输出上限（实测只需 65~120 tok） | 真机 6 样本：输出 75~113 tok |
 | `maxTokensRewrite` | 1200 | rewrite/冷启动输出上限（要输出完整步骤表） | 700 会截断，1200 稳定 |
 | `warmBackfill` | true | 打开「插件从未观察过的旧会话」时，从持久化会话日志回填一次计划+建议 | P0-1；真机老会话回填 2.2s |
+| `persistPlans` | true | 是否把计划+最近建议持久化到本地文件（DSH 重启恢复） | v0.1.2 |
+| `storageDir` | `~/.dsh/plan-completion-data` | 计划文件目录；`~` 会展开为 home；也可用 `DSH_PLAN_COMPLETION_STORE_DIR` | v0.1.2 |
 | `enableDebugRoutes` | false | 是否注册 `debug/diag/theme/experiment/autojob/steps/reset` 调试路由；仍须鉴权 | 发布版最小攻击面 |
 | `modelCalls` | true | false 时关闭本插件全部模型调用，使用启发式 | 隐私控制 |
 | `debugDir` | 空 | 调试日志/实验结果的落盘目录（也可用 `DSH_PLAN_COMPLETION_DEBUG_DIR`）；空则不写文件 | 可移植性 |
@@ -108,7 +120,7 @@ Client 侧关键 API（实测）：`inputActions.captureInsertion()` 返回 `{st
 
 ## 安装 / 卸载
 
-> npm：**`dsh-plan-completion@0.1.0`** 已发布（https://www.npmjs.com/package/dsh-plan-completion）。
+> npm：[`dsh-plan-completion`](https://www.npmjs.com/package/dsh-plan-completion)（版本见上方 npm badge）。
 > DSH 的 profile 安装仍以仓库 `link:` 或路径安装为准（包内是 `dsh.bundle.patch` + `dsh.client` bundle）。
 
 ```powershell
@@ -260,7 +272,7 @@ CI：`.github/workflows/test.yml`（GitHub Actions，Node 20/22 矩阵，push/PR
 
 ## 已知限制（当前）
 
-- 计划只存在 Host 内存，重启 DSH 后丢失（二期接 `storageDomain` / 文件存储）；旧会话可通过 warm 回填，但热重载外的重启仍会清空状态；
+- **计划持久化**（v0.1.2）：计划+最近建议按会话落盘到 `storageDir`，DSH 重启后自动恢复（仍保留"本会话内存态"作为快路径）；默认目录 `~/.dsh/plan-completion-data`，`persistPlans:false` 可退回纯内存。存储为本地明文 JSON，不加密、不自动清理；
 - 模型选择暂用默认路由推导，未做设置页三选一；
 - 计划页是 Popover，右栏形态二期（`ctx.sidebarRightTabs` 已确认对插件开放）；
 - HTTP 路由依赖宿主 `connection.requestRejection`；服务缺失时返回 503，不退回未鉴权访问。已在真实 DSH 完成 v0.1.1 canary（Electron 代理请求正常、直连未认证请求 401）；其他宿主/部署形态仍需各自验证；

package/cordis.patch.yml

@@ -1,13 +1,16 @@
-- insert:
-    - id: plan-completion
-      name: 'dsh-plan-completion'
-      config:
-        evidenceChars: 1500
-        maxTokensPatch: 400
-        maxTokensRewrite: 1200
-        warmBackfill: true
-        modelCalls: true # false: heuristic-only; no plugin model requests
-        # Debug endpoints (debug/diag/theme/experiment/autojob/steps/reset) stay off in production.
-        enableDebugRoutes: false
-        # Optional: set a local directory to persist debug logs / experiment data.
-        # debugDir: '<local debug directory>'
+- insert:
+    - id: plan-completion
+      name: 'dsh-plan-completion'
+      config:
+        evidenceChars: 1500
+        maxTokensPatch: 400
+        maxTokensRewrite: 1200
+        warmBackfill: true
+        modelCalls: true # false: heuristic-only; no plugin model requests
+        # Plans + last suggestion are persisted per session so a DSH restart restores the UI.
+        persistPlans: true
+        storageDir: '~/.dsh/plan-completion-data'
+        # Debug endpoints (debug/diag/theme/experiment/autojob/steps/reset) stay off in production.
+        enableDebugRoutes: false
+        # Optional: set a local directory to persist debug logs / experiment data.
+        # debugDir: '<local debug directory>'

package/docs/delivery-notes.md

@@ -1,6 +1,6 @@
 # 交付说明 · 会话计划补全插件（dsh-plan-completion）v0.1.0
 
-> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。当前未发布修复已接入鉴权、收紧模型路由及诊断数据，详见 [security.md](security.md) 和 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
+> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。**v0.1.1 已发布**（鉴权、状态一致性、隐私边界修复），详见 [security.md](security.md) 与 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
 
 > 一期交付 · 2026-11-02 · 真机验收通过
 > 设计与实现说明见 `README.md`；设计规格见 `docs/design-v1.2.md`
@@ -80,7 +80,7 @@ plugin_manager remove_bundle target='dsh-plan-completion'
 ## 七、已知限制（v0.1.1 现状）
 
 1. **旧会话回填已支持**（v0.1.1）：打开插件从未观察过的会话时，Client 会 POST `/plan-completion/warm`，Host 从持久化会话日志重建计划+建议（同一会话 10 分钟内只回填一次；需要一次模型调用，可用 `warmBackfill:false` 关闭）。不触发回填时仍只有 `▤` 入口。
-2. **计划不持久化**：进程内存保存，DSH 重启后计划丢失，下个回合结束重新生成（二期接 `storageDomain`）。
+2. **计划持久化已支持**（v0.1.2）：计划+最近建议写入 `storageDir`（默认 `~/.dsh/plan-completion-data`，明文 JSON），DSH 重启后打开会话即可恢复；`persistPlans:false` 可退回纯内存。存储不加密、不自动清理，多 profile 共用默认目录时可能互相可见（见 `docs/security.md`）。
 3. **用户编辑锁**：`editedByUser=true` 后模型不能自动 rewrite 覆盖计划，只能 patch；需要整体重构用 `/replan`。
 4. **调试路由**：`experiment|autojob|steps|theme|diag|reset|debug` 仅在 `enableDebugRoutes:true` 时注册，且与其他路由一样必须通过宿主 `connection.requestRejection`（v0.1.1 起）。
 5. **无「核对进度」按钮**：计划页当前只展示状态/证据；按需模型核对按钮在二期清单（见下）。

package/docs/phase-2-plan.md

@@ -1,6 +1,6 @@
 # 会话计划补全插件 · 二期计划
 
-> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。当前未发布修复已接入鉴权、收紧模型路由及诊断数据，详见 [security.md](security.md) 和 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
+> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。**v0.1.1 已发布**（鉴权、状态一致性、隐私边界修复），详见 [security.md](security.md) 与 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
 
 > 版本：v2.0 计划草案 · 2026-11-02
 > 依据：一期交付（见 `dsh-plan-completion/交付说明.md`）+ 本次真机反馈（常驻、计划页视觉、GitHub 发布评估）
@@ -12,13 +12,13 @@
 
 ### P0（必须，决定可用性与发布）
 
-> 更新（v0.1.1）：P0-1（挂载回填）、P0-2（Hero 常驻）、P0-4（路由鉴权）已交付；以下保留原始规划记录，未完成项为 P0-3 / P0-5 / P0-6。
+> 更新（v0.1.2）：P0-1（挂载回填）、P0-2（Hero 常驻）、P0-3（计划持久化）、P0-4（路由鉴权）已交付；以下保留原始规划记录，未完成项为 P0-5 / P0-6。
 
 | # | 事项 | 现状问题 | 方案 | 验收标准 | 预估 |
 |---|---|---|---|---|---|
 | P0-1 | ✅ **挂载时回填（旧会话也能有建议）** | 插件只处理「激活后观察到 turn/end」的会话；老会话打开只有裸入口 | client 挂载时若 `state.stale && !plan`，POST `/plan-completion/warm {sessionId}`；host 用 `session.snapshotEvents` 回填一次计划+建议（可在会话无新回合时工作） | 打开任意历史会话 ≤5s 出现建议；同一会话只回填一次（按 session+seq 去重） | ✅ 已交付（v0.1.1） |
 | P0-2 | ✅ **真·常驻（hero / 新会话也有入口）** | `conversation.input.dock` 在无 Session 的 hero 页不渲染；删除全部消息后栏位消失 | 在 `shell.overlay` 增加一个随 composer 定位的轻量 `▤ 计划` 入口（hero 时显示；已有 dock 时隐藏避免重复）；无计划时保留虚线提示胶囊（一期已做） | 新会话 hero、删除全部消息、旧会话、正常会话四种状态都有入口且不重叠 | ✅ 已交付（v0.1.1） |
-| P0-3 | **计划持久化** | 进程内存，DSH 重启丢失 | `storageDomain` 持久化 plan（按 sessionId 分 key）+ 启动时恢复 + 版本号 `gen.rev` 保留 | 重启 DSH 后同一会话仍显示原计划与版本；schema 变更可迁移 | 1d |
+| P0-3 | ✅ **计划持久化** | 进程内存，DSH 重启丢失 | 本地文件持久化（`storageDir`，按 sessionId 原子写）+ 启动/打开会话时 hydrate + 版本号 `gen.rev` 保留 | 重启 DSH 后同一会话仍显示原计划与版本；schema 变更可迁移 | ✅ 已交付（v0.1.2，文件存储方案） |
 | P0-4 | ✅ **路由鉴权** | `/plan-completion/*` 调试路由无鉴权（本机回环） | 使用 `connection.requestRejection` 校验来源、或改用 `connection.fetch` 同源校验；调试路由默认仅本机、可配置关闭 | 非本机/非 DSH 页面的请求被拒；客户端不受影响 | ✅ 已交付（v0.1.1） |
 | P0-5 | **「核对进度」按钮** | 计划页只能看状态，无法对照实际进度 | 计划页底部加「核对进度」→ POST `/plan-completion/verify` → 一次模型调用生成「计划 vs 实际差异 + 建议修正」→ 展示在计划页（可折叠、可采纳） | 点击后 ≤5s 返回差异清单；采纳后生成 patch；失败有降级文案 | 1d |
 | P0-6 | **发布工程化** | 无 git 仓库 / LICENSE / CI / 包元数据、README 含本地绝对路径 | 见 `发布评估-GitHub.md` 的 P0 清单 | 全部 P0 项 PASS，`node --test` 绿，仓库可公开 | 1d |

package/docs/publish-assessment.md

@@ -1,6 +1,8 @@
 # GitHub 发布评估 · 会话计划补全插件（2026-11-02）
 
-> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。当前未发布修复已接入鉴权、收紧模型路由及诊断数据，详见 [security.md](security.md) 和 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
+> 历史文档：以下保留 v0.1.0 的交付/评估/计划记录。**v0.1.1 已发布**（鉴权、状态一致性、隐私边界修复），详见 [security.md](security.md) 与 [CHANGELOG](../CHANGELOG.md)；旧记录中的“无鉴权”、原始诊断字段与独立评审不代表当前实现。
+>
+> v0.1.1 发布记录（2026-11-02）：tag `v0.1.1` + [Release](https://github.com/Xumi0920/dsh-plan-completion/releases/tag/v0.1.1)；GitHub Actions [run 41366651557](https://github.com/Xumi0920/dsh-plan-completion/actions/runs/41366651557)（Ubuntu/Windows × Node20/22 四 job 全绿）；npm `dsh-plan-completion@0.1.1`（31 files，shasum `18989b0f50b72d5c8c332f3fdee7f43ccb5fd91a`）。
 
 > **2026-11-02 晚更新：P0 清单已全部完成，状态从「不满足全 PASS」→「可按 GitHub 源码仓库发布」。**
 >

package/docs/security.md

@@ -1,6 +1,13 @@
 # 安全与隐私边界
 
-本页描述 **v0.1.1** 的安全与隐私边界。npm `0.1.0` 为旧版本（无鉴权、含原始诊断字段），请以 registry 最新版为准。
+本页描述 **v0.1.2** 的安全与隐私边界。历史版本（npm `0.1.0`/`0.1.1`）不包含本页描述的全部加固，请以 registry 最新版为准。
+
+## 本地计划存储（v0.1.2）
+
+- 计划与最近一条建议按会话写入 `storageDir`（默认 `~/.dsh/plan-completion-data`）下的明文 JSON 文件，用于 DSH 重启恢复；
+- 文件包含计划步骤、更新原因、建议文本等**由会话内容派生的数据**；不加密、不自动过期/清理，无文件锁（单进程假设）；
+- 同一机器多 profile 共用默认目录时可能互相看到计划；多用户共享机器不应使用默认目录；
+- `persistPlans: false` 完全关闭磁盘持久化；`storageDir` 可指向受控目录。
 
 ## 请求访问
 

package/host/store.js

@@ -5,7 +5,9 @@
  *
  * 语义（两个 store 一致）：
  *   get(sessionId)              → plan | null（返回副本，改它不影响存储）
- *   put(plan, {cas})            → boolean；cas 省略=无条件写，null=仅新建，{gen,rev}=期望当前版本
+ *   getState(sessionId)         → { plan, suggestion } | null（持久化恢复用）
+ *   put(plan, {cas,suggestion}) → boolean；cas 省略=无条件写，null=仅新建，{gen,rev}=期望当前版本；
+ *                                 suggestion 存在时一并保存最近一次建议（undefined=保持不变）
  *   history(sessionId)          → plan[]（旧 → 新，含当前版本）
  *   prune(n = 5)                → 每会话只保留最近 n 版
  *   clear(sessionId?)           → boolean | number
@@ -25,6 +27,10 @@ import { validVersion, versionEquals } from './plan.js';
 const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 const isNonEmptyStr = (v) => typeof v === 'string' && v.trim().length > 0;
 
+function hasOwn(obj, key) {
+  return isObj(obj) && Object.prototype.hasOwnProperty.call(obj, key);
+}
+
 function clone(value) {
   if (value == null) return value;
   try {
@@ -69,7 +75,7 @@ function pushHistory(state, plan) {
  * @returns {object}
  */
 export function createMemoryStore() {
-  /** @type {Map<string, {plan: object, history: object[]}>} */
+  /** @type {Map<string, {plan: object, suggestion: object|null, history: object[]}>} */
   const states = new Map();
 
   function get(sessionId) {
@@ -78,13 +84,21 @@ export function createMemoryStore() {
     return state && state.plan ? clone(state.plan) : null;
   }
 
+  function getState(sessionId) {
+    if (!isNonEmptyStr(sessionId)) return null;
+    const state = states.get(sessionId);
+    if (!state || !state.plan) return null;
+    return { plan: clone(state.plan), suggestion: state.suggestion ?? null };
+  }
+
   function put(plan, options = {}) {
     if (!lightValidate(plan)) return false;
-    const cas = isObj(options) && Object.prototype.hasOwnProperty.call(options, 'cas') ? options.cas : undefined;
+    const cas = hasOwn(options, 'cas') ? options.cas : undefined;
     const sessionId = plan.sessionId;
-    const state = states.get(sessionId) ?? { plan: null, history: [] };
+    const state = states.get(sessionId) ?? { plan: null, suggestion: null, history: [] };
     if (!casMatches(cas, state)) return false;
     state.plan = clone(plan);
+    if (hasOwn(options, 'suggestion')) state.suggestion = clone(options.suggestion) ?? null;
     pushHistory(state, plan);
     states.set(sessionId, state);
     return true;
@@ -124,7 +138,7 @@ export function createMemoryStore() {
     return [...states.keys()];
   }
 
-  return { get, put, history, prune, clear, listSessions, size: () => states.size };
+  return { get, getState, put, history, prune, clear, listSessions, size: () => states.size };
 }
 
 /* ──────────────────────────────────────────────────────────────
@@ -171,15 +185,22 @@ export function createFileStore(dir) {
       const data = await readState(sessionId);
       return data && isObj(data.plan) ? clone(data.plan) : null;
     },
+    async getState(sessionId) {
+      if (!enabled || !isNonEmptyStr(sessionId)) return null;
+      const data = await readState(sessionId);
+      if (!data || !isObj(data.plan)) return null;
+      return { plan: clone(data.plan), suggestion: isObj(data.suggestion) ? clone(data.suggestion) : null };
+    },
     async put(plan, options = {}) {
       if (!enabled || !lightValidate(plan)) return false;
       try {
-        const cas = isObj(options) && Object.prototype.hasOwnProperty.call(options, 'cas') ? options.cas : undefined;
+        const cas = hasOwn(options, 'cas') ? options.cas : undefined;
         const sessionId = plan.sessionId;
-        const data = (await readState(sessionId)) ?? { sessionId, plan: null, history: [] };
+        const data = (await readState(sessionId)) ?? { sessionId, plan: null, suggestion: null, history: [] };
         if (!casMatches(cas, data)) return false;
         data.plan = clone(plan);
         data.sessionId = sessionId;
+        if (hasOwn(options, 'suggestion')) data.suggestion = clone(options.suggestion) ?? null;
         if (!Array.isArray(data.history)) data.history = [];
         const last = data.history[data.history.length - 1];
         if (last && versionEquals(last.version, plan.version)) data.history[data.history.length - 1] = clone(plan);

package/index.js

@@ -12,6 +12,7 @@
  * (verified contract: same-origin fetch from the Electron page works and the body is readable).
  */
 import { appendFileSync, mkdirSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
 
 import { DEFAULTS } from './host/config.js'
 import { requestRejection, safeDebugRecord, safeDiagnostics } from './host/security.js'
@@ -20,7 +21,7 @@ import { normalizePlan, patchPlan, rewritePlan, statusFor, applyUserEdit } from
 import { buildPatchPrompt, buildRewritePrompt, buildRepairPrompt, parseModelOutput } from './host/prompt.js'
 import { heuristicSuggestion, fallbackPlan } from './host/heuristics.js'
 import { collectFromEvents } from './host/evidence.js'
-import { createMemoryStore } from './host/store.js'
+import { createMemoryStore, createFileStore } from './host/store.js'
 import { runExperiment } from './host/experiment.js'
 import { sliceEvidence } from './host/experiment.js'
 
@@ -43,6 +44,25 @@ function debugLog(record) {
   }
 }
 
+/**
+ * Resolve the local plan-store directory. `~` is expanded so a shipped config can point at the
+ * user's home without hard-coding an absolute path. Empty means "memory only".
+ */
+function expandStorageDir(value, envValue) {
+  const raw = typeof value === 'string' && value.trim() !== ''
+    ? value.trim()
+    : (typeof envValue === 'string' ? envValue.trim() : '')
+  if (raw === '') return ''
+  if (raw === '~' || raw.startsWith('~/') || raw.startsWith('~\\')) {
+    try {
+      return raw === '~' ? homedir() : join(homedir(), raw.slice(2))
+    } catch {
+      return ''
+    }
+  }
+  return raw
+}
+
 function readJsonBody(req) {
   return new Promise(resolve => {
     let size = 0
@@ -232,6 +252,8 @@ export function apply(ctx, config = {}) {
     maxTokensRewrite: readInt(rawConfig.maxTokensRewrite, 1200, 400, 8000),
     warmBackfill: rawConfig.warmBackfill !== false,
     modelCalls: rawConfig.modelCalls !== false,
+    persistPlans: rawConfig.persistPlans !== false,
+    storageDir: expandStorageDir(rawConfig.storageDir, process.env.DSH_PLAN_COMPLETION_STORE_DIR),
     enableDebugRoutes: rawConfig.enableDebugRoutes === true,
     debugDir: typeof rawConfig.debugDir === 'string' && rawConfig.debugDir.trim() !== ''
       ? rawConfig.debugDir.trim()
@@ -276,7 +298,11 @@ export function apply(ctx, config = {}) {
   const warmAttempts = shared.warmAttempts // sessionId -> { at, seq }
   const inflight = new Map() // sessionId -> AbortController
   const gate = createGate(DEFAULTS.globalConcurrency)
-  const store = shared.store
+  // Persistence: a file-backed plan store when a directory is configured; otherwise memory.
+  // The store keeps the last plan + suggestion per session so a restart can restore the UI.
+  const fileStore = settings.persistPlans && settings.storageDir ? createFileStore(settings.storageDir) : null
+  const store = fileStore ?? createMemoryStore()
+  shared.store = store
   let disposed = false
   const stopGeneration = () => {
     disposed = true
@@ -313,6 +339,53 @@ export function apply(ctx, config = {}) {
     states.set(sessionId, { ...previous, ...patch })
   }
 
+  // ── Persistence ⇄ in-memory state ────────────────────────────────────────
+  const hydration = new Map() // sessionId -> Promise (in-flight disk reads)
+
+  // Adopt plans retained in memory across a hot reload into the file store. `cas:null` means
+  // "only when the file has no plan yet", so a newer on-disk plan is never overwritten.
+  if (fileStore) {
+    for (const [sessionId, state] of states.entries()) {
+      if (!state?.plan) continue
+      void fileStore
+        .put(state.plan, { cas: null, suggestion: state.suggestion ?? null })
+        .catch(() => {})
+    }
+  }
+
+  /**
+   * Load a persisted plan (+ last suggestion) into the shared in-memory state. The UI can show
+   * the previous plan right after a DSH restart, before the next turn runs.
+   */
+  async function hydrateSession(sessionId) {
+    if (!sessionId) return
+    if (states.get(sessionId)?.plan) return
+    const pending = hydration.get(sessionId)
+    if (pending) return pending
+    const task = (async () => {
+      try {
+        const stored = typeof store.getState === 'function'
+          ? await store.getState(sessionId)
+          : { plan: await store.get(sessionId), suggestion: null }
+        if (!stored?.plan || states.get(sessionId)?.plan) return
+        const normalized = normalizePlan(stored.plan)
+        if (!normalized?.ok || !normalized.plan) return
+        states.set(sessionId, {
+          plan: normalized.plan,
+          suggestion: stored.suggestion && typeof stored.suggestion === 'object' ? stored.suggestion : null,
+          stale: false,
+        })
+        debugLog({ phase: 'state-hydrated', sessionId })
+      } catch (error) {
+        debugLog({ phase: 'state-hydrate-error', sessionId, error: String(error) })
+      } finally {
+        hydration.delete(sessionId)
+      }
+    })()
+    hydration.set(sessionId, task)
+    return task
+  }
+
   function seedPlan(sessionId, evidence) {
     const intent = evidence?.intent || evidence?.firstUserMessage || '推进当前会话目标'
     const fallback = (() => {
@@ -429,6 +502,7 @@ export function apply(ctx, config = {}) {
   async function runWarmBackfill(sessionId, options = {}) {
     if (!settings.warmBackfill) return { ok: false, reason: 'disabled' }
     if (!sessionId) return { ok: false, reason: 'no-session-id' }
+    await hydrateSession(sessionId)
     if (states.get(sessionId)?.plan) return { ok: true, already: true }
     const now = Date.now()
     const attempt = warmAttempts.get(sessionId)
@@ -490,6 +564,8 @@ export function apply(ctx, config = {}) {
 
     await gate.acquire()
     try {
+      if (!isCurrent()) return
+      await hydrateSession(sessionId)
       if (!isCurrent()) return
       let events = []
       try {
@@ -499,7 +575,10 @@ export function apply(ctx, config = {}) {
       }
 
       const basePlan = states.get(sessionId)?.plan ?? null
-      const storedVersion = store.get(sessionId)?.version ?? null
+      const storedPlan = typeof store.getState === 'function'
+        ? (await store.getState(sessionId))?.plan ?? null
+        : await store.get(sessionId)
+      const storedVersion = storedPlan?.version ?? null
       const evidence = (() => {
         try {
           const collected = collectFromEvents({ events, plan: basePlan, turn, sessionId })
@@ -668,16 +747,28 @@ export function apply(ctx, config = {}) {
         if (fallbackText) suggestion = { text: fallbackText, alternates: [] }
       }
 
+      const elapsed = Date.now() - startedAt
+      const suggestionDeadline = force ? Number.POSITIVE_INFINITY : Math.max(DEFAULTS.suggestionDeadlineMs, 6000)
+      const withinSuggestionDeadline = elapsed <= suggestionDeadline
+      const finalSuggestion = withinSuggestionDeadline ? suggestion ?? provisionalSuggestion : provisionalSuggestion
+
       if (nextPlan) {
         try {
           // Check CAS even for an unchanged plan; an old snapshot is never an
           // unconditional write. null also protects the first commit from races.
-          const committed = store.put(nextPlan, { cas: storedVersion })
+          // The last suggestion is persisted in the same write so a restart can restore it.
+          const committed = await store.put(nextPlan, { cas: storedVersion, suggestion: finalSuggestion })
           if (!committed) {
             debugLog({ phase: 'store-cas-miss', sessionId })
-            const latest = store.get(sessionId)
-            publishState(sessionId, { plan: latest, suggestion: null, stale: true })
-            debug.lastJob = { sessionId, turn, elapsed: Date.now() - startedAt, outcome: 'conflict', suggestion: false }
+            const winner = typeof store.getState === 'function'
+              ? await store.getState(sessionId)
+              : { plan: await store.get(sessionId), suggestion: null }
+            publishState(sessionId, {
+              plan: winner?.plan ?? null,
+              suggestion: null,
+              stale: Boolean(winner?.plan),
+            })
+            debug.lastJob = { sessionId, turn, elapsed, outcome: 'conflict', suggestion: false }
             return
           }
         } catch (error) {
@@ -686,10 +777,6 @@ export function apply(ctx, config = {}) {
         }
       }
 
-      const elapsed = Date.now() - startedAt
-      const suggestionDeadline = force ? Number.POSITIVE_INFINITY : Math.max(DEFAULTS.suggestionDeadlineMs, 6000)
-      const withinSuggestionDeadline = elapsed <= suggestionDeadline
-      const finalSuggestion = withinSuggestionDeadline ? suggestion ?? provisionalSuggestion : provisionalSuggestion
       publishState(sessionId, {
         plan: nextPlan,
         suggestion: finalSuggestion,
@@ -878,7 +965,9 @@ export function apply(ctx, config = {}) {
             return
           }
           if (pathname === `${ROUTE_PREFIX}state` && method === 'GET') {
-            jsonResponse(res, 200, publicView(url?.searchParams?.get('sessionId') ?? ''))
+            const sessionId = url?.searchParams?.get('sessionId') ?? ''
+            await hydrateSession(sessionId)
+            jsonResponse(res, 200, publicView(sessionId))
             return
           }
           if (pathname === `${ROUTE_PREFIX}debug` && method === 'GET') {
@@ -972,7 +1061,12 @@ export function apply(ctx, config = {}) {
             const sessionId = String(body.sessionId ?? '')
             const existed = states.has(sessionId)
             inflight.get(sessionId)?.abort(new Error('state-reset'))
-            store.clear(sessionId)
+            try {
+              await store.clear(sessionId)
+            } catch (error) {
+              debugLog({ phase: 'reset-store-error', sessionId, error: String(error) })
+            }
+            hydration.delete(sessionId)
             states.delete(sessionId)
             warmAttempts.delete(sessionId)
             handledTurns.delete(sessionId)
@@ -983,6 +1077,7 @@ export function apply(ctx, config = {}) {
           if (pathname === `${ROUTE_PREFIX}steps` && method === 'POST') {
             const body = (await readJsonBody(req)) ?? {}
             const sessionId = String(body.sessionId ?? '')
+            await hydrateSession(sessionId)
             const plan = states.get(sessionId)?.plan ?? null
             if (!plan) {
               jsonResponse(res, 200, { ok: false, error: 'no-plan' })
@@ -1034,7 +1129,11 @@ export function apply(ctx, config = {}) {
               return
             }
             try {
-              store.put(applied.plan, { cas: plan.version })
+              const committed = await store.put(applied.plan, {
+                cas: plan.version,
+                suggestion: states.get(sessionId)?.suggestion ?? null,
+              })
+              if (!committed) await store.put(applied.plan, { suggestion: states.get(sessionId)?.suggestion ?? null })
             } catch (error) {
               debugLog({ phase: 'user-edit-store-error', sessionId, error: String(error) })
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plan-completion",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "Implicit session plans with Tab-completable next-message suggestions for DeepSeek Harness",