dsh-engram 0.5.1 → 0.7.0

package/README.zh.md

@@ -85,7 +85,7 @@
 - **记忆 GC（pi-esr 约束）** — 定时、机械、只归档的回收：TTL 过期记忆归档、超容量工作区淘汰低价值条目、
   stable 任务超保留窗离开 `[ESR]` 表面、悬空链接边清理。工作集（active 任务引用 / 任务记忆 / 已入索引命中）
   永不触碰；**不硬删任何东西**——归档条目保留 id、始终可重取。
-- **Context GC（自动 GC = 替代 DSH 自动 compact）** — 不是记忆面板 GC：接管 DSH 自带的上下文压缩
+- **Context GC（自动 GC = 替代 DSH 自动 compact，opt-in）** — 不是记忆面板 GC：开启后接管 DSH 自带的上下文压缩
   （`compaction` 服务），把「有损 LLM 全量摘要」换成**机械驱逐 + 重取指针**——扫描被驱逐轮次里的
   engram/ESR 锚（`#记忆id`、`tsk_*`、`ent_*`、`file_path`），只留一行「细节在 `engram_detail` /
   `engram_recall` / `[ESR]` 里」；只有无锚轮次才走 scoped LLM 叙事兜底（`gcNarrative`，默认开、可关成纯机械）。
@@ -166,8 +166,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 
 <!-- dsh-market 兼容信息块 —— 与 docs/RELEASE-NOTES.TEMPLATE.md 的市场 README 公约保持一致 -->
 
-- **DSH 版本**：`>=0.1.2-alpha.2 <0.3.0-0`（本版 `0.5.1`；已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` —— 见下文矩阵）
-- **最后验证日期**：2026-10-19 —— 会话扫描修复（`session.v<N>.jsonl.zstd`，issue #8）+ 数据导出/导入与替换/冲突可视化（issue #3），npm test 334/334 通过
+- **DSH 版本**：`>=0.1.2-alpha.2 <0.3.0-0`（本版 `0.7.0`；已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` —— 见下文矩阵）
+- **最后验证日期**：2026-10-19 —— episode / 实体页 / 锚点重验证，npm test 381/381 通过
 - **安装方式已验证**：`dsh plugin --profile web add dsh-engram`
 
 > **一句话结论**：所有**已真正发布**的版本（`0.2.0` … `0.3.6`）**只支持旧版
@@ -180,7 +180,9 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.2.0` … `0.3.6`（npm 全量 + GitHub v0.3.3–v0.3.6） | 已发布 | **仅旧版** —— `0.1.0-rc.7` / `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2` | peers `@deepseek-ai/dsh-*@^0.1.0-rc.7` |
 | `0.3.7` / `0.4.0`（npm） | 已发布 | **新版 DSH，settings `installSection`** —— `>=0.1.2-alpha.2 <0.2.0-0` | `engines.dsh` + peers 同范围 |
 | `0.5.0`（npm） | 已发布 | **DSH `0.1.2-alpha.2` … `<0.3.0-0`** —— 设置卡迁移到 entry-id volatile Config（`0.1.7+`/`0.2.x`），`≤0.1.5` 自动回退 `installSection` | `engines.dsh` + peers `>=0.1.2-alpha.2 <0.3.0-0` |
-| `0.5.1`（本期 / this release） | 已发布 | 同 `0.5.0` —— 会话扫描修复（`session.v<N>.jsonl.zstd`，issue #8）、数据导出/导入 GUI、替换/冲突可视化（issue #3） | 同 `0.5.0` |
+| `0.5.1` | 已发布 | 同 `0.5.0` —— 会话扫描修复（`session.v<N>.jsonl.zstd`，issue #8）、数据导出/导入 GUI、替换/冲突可视化（issue #3） | 同 `0.5.0` |
+| `0.6.0` | 已发布 | 同 `0.5.0` —— Context Ledger、BoundaryPrune/ResultPack 默认开 + 账本否决、JIT 推送、Context GC 改 opt-in | 同 `0.5.0` |
+| `0.7.0`（本期 / this release） | 已发布 | 同 `0.5.0` —— 会话 episode、恢复简报、实体页/实体卡、可重验证锚点 + 分层 TTL | 同 `0.5.0` |
 
 ### API 族断裂点:`0.1.2-alpha.2`
 
@@ -207,7 +209,7 @@ HTTP 路由（`/api/dsh-engram/settings`，与记忆 viewer 同样的同源 fetc
 profile 条目 id（`engram`）为命名空间，不再需要任何“挂载”调用。`0.5.0`
 在 `installEngramSettings` 里对两代际做特性检测：
 
-- DSH `≥0.1.7` / `0.2.x` —— 27 个 GUI 旋钮即 `Config` 的 volatile 字段
+- DSH `≥0.1.7` / `0.2.x` —— 34 个 GUI 旋钮即 `Config` 的 volatile 字段
   （`lib/settings.js` `makeEngineConfigSchema`，由 `lib/index.js` 导出为
   `Config`）；卡片仍走同一 `/api/dsh-engram/settings` HTTP 路由读写条目 `engram`，
   `service.settings` 接缝在 `loader/volatile-update` 事件上把 `resolved`
@@ -220,13 +222,21 @@ profile 条目 id（`engram`）为命名空间，不再需要任何“挂载”
 所以：跑 ≤ `0.3.6` 的已发布版本时请把 DSH 保持在 `0.1.1-rc.2` 或更旧；升级
 DSH 到 `0.1.2-alpha.2` 之前，先升级插件到 `>=0.3.7`。
 
-### 当前发布版本 —— `0.5.1`
+### 当前发布版本 —— `0.7.0`
 
-在 `0.5.0` 之上的补丁版：会话扫描改为解析**版本化**日志名
-（`session.v3/v4.jsonl.zstd`）而不硬编码 `session.jsonl.zstd`——在当前 DSH 上
-这个错位让 `/stats`、`/toolstats`、BoundaryPrune 的偿还历史、CJK 会话搜索全部
-**静默返回 0**（issue #8）。记忆查看器同时补上数据导出/导入与替换/冲突可视化
-（issue #3）。
+把「记忆」从**事件记录**推进到**可维护的当前真相**：会话结束自动沉淀 episode、
+新会话给恢复简报、`esr_node` 升级为实体页、文件锚点让过期真相可被检测。
+
+- **会话 episode**：`session/disposed` 零 LLM 生成紧凑纪要（文件/命令/失败→修复/
+  决策/未闭环），不进索引，每 workspace 保留 20 条。
+- **恢复简报**：新会话注入最近 7 天最新 episode（`[RESUME]` ≤240 字符 + 下钻指针）。
+- **实体页 + 实体卡**：`truth / timeline / open loops / conflicts / relations`；
+  索引前置最多 2 张实体卡，`engram_detail(entity=…)` 下钻。
+- **可重验证锚点**：带 `filePath` 的记忆记录 `mtime/size/sha256`；会话启动有界
+  重验证，改动/缺失 → `stale`（不进索引/truth，仍可 detail 重取）。
+- **分层 TTL**：preference/procedure 永久、episode 14 天、error 60 天、其余 180 天。
+- **迁移**：只有新写入会落锚（不回溯历史）；升级后重启 `dsh web`；episode 要等一个
+  会话结束，resume brief 在下一个新会话生效。`0.6.0` 的账本/默认值/JIT 保持不变。
 
 已发布的 `0.4.0` 声明 `>=0.1.2-alpha.2 <0.2.0-0`——这个范围被 semver 门槛在
 **所有 DSH `0.2.0-0` 预发布**上拒绝（`<0.2.0-0` 排除 `0.2.0-rc.x`），且其宿主设置端
@@ -244,13 +254,13 @@ Config** 模型（并带特性检测的旧代际回退）。
 
 `0.1.2-alpha.2` 是这组 API 的最低版本：宿主设置注册按代际**特性检测**——DSH `≤0.1.5`
 走 `settings.installSection` 注册 `dsh-engram` 命名空间；`≥0.1.7` / `0.2.x` 走插件
-`Config`（27 个 GUI 旋钮标记为 `.volatile()`，条目 id `engram`）。浏览器设置卡在两代际
+`Config`（34 个 GUI 旋钮标记为 `.volatile()`，条目 id `engram`）。浏览器设置卡在两代际
 都经插件自有 HTTP 路由（`/api/dsh-engram/settings`，见上文 Route B）读写。完整回归
 （npm test 329/329，含新增的 volatile-Config 模型 settings-v2 覆盖）在 DSH
 `0.2.0-rc.2` 依赖集（cordis 4.0.4 + schemastery 3.18.4 + cosmokit，与全局 DSH CLI 同版本）
 上通过；`.volatile()`/loader 热提交路径与 describe 侧投影已针对真实 `dsh-settings
 0.2.0-rc.2` 工具函数验证；并在隔离的 `dsh 0.2.0-rc.2` profile 上完成了**真机启动烟测并
-通过**：插件启动无版本范围拒绝、设置卡表单以条目 `engram` 对外提供（全部 27 个 GUI
+通过**：插件启动无版本范围拒绝、设置卡表单以条目 `engram` 对外提供（全部 34 个 GUI
 旋钮，含 `trustedHosts`）、`/api/dsh-engram/settings` 的 GET → PUT（mutate ops，
 revision 0→1）→ unset 往返落盘并读回。旧的 `0.1.0-rc.7` 与 `0.1.1` API 图不在
 本发布版本的兼容范围内。
@@ -340,6 +350,7 @@ node scripts/setup-links.mjs     # 把 @deepseek-ai 工作区包软链进 node_m
   纯 SVG 实现（无图表库，保持 bundle 纯净）。
   以及一个 **遥测仪表盘** 页签：把 /stats 的真实调用累计（工作区 × 天滚动）画成纯 SVG 仪表盘——三枚大圆环
   直读 **ESR 主动性**（与 escalate 阈值 0.34 比对，偏低标橙并提示）、**召回命中率**、**detail 转化**，
+  外加一块 **Context Ledger** 面板（净 token、节省/注入/重写罚金三卡、近 14 天净收益红绿柱），
   五张小指标卡（累计调用 / esr / 记忆 / 平均命中每查询 / 失败），近 14 天 mem-vs-esr 堆叠柱状图 +
   工具调用 Top 8 横向条形图（mem 蓝 / esr 紫，与全文配色一致），20s 自动刷新，样本不足（<10 次）自动标注。
   以及 **详情侧栏**（主从布局）：任务 / 记忆 / 节点 / 关系行都可一键在右侧打开详情卡——任务含
@@ -356,7 +367,7 @@ node scripts/setup-links.mjs     # 把 @deepseek-ai 工作区包软链进 node_m
 面板同时列出各工具调用计数与最近 14 天逐日滚动。这些是真实会话的真实数字——想提升 ESR 主动性，
 就观察面板上 esr 占比并调整注入提示。
 - **设置 → 插件 → 插件配置 → dsh-engram** — 与内置「终端 / Agent 循环 / 网页搜索」同款的
-  **默认折叠卡片**：标题 + 一行描述 + 箭头，点击展开/收起；展开后 12 个设置项按
+  **默认折叠卡片**：标题 + 一行描述 + 箭头，点击展开/收起；展开后常用 11 项 + 高级分组按
   「捕获与检索 / 索引 / 生命周期与 GC / 安全」四个分组展示。改动对新建会话即时生效
   （已冻结的块保持稳定）；支持放弃修改 / 保存，有未保存改动时标题上出现「未保存」徽标。
   卡片通过连接自身的 settings RPC 直连命名空间（不走 isLoopback 门控的 scope），因此即使
@@ -380,7 +391,7 @@ npm run build:client
 ## 测试与评测
 
 ```sh
-npm test    # 311 项单元测试（含 usage 滚动 / /stats 路由 / Context GC / ESR 触发 / BoundaryPrune）
+npm test    # 381 项单元测试（含 usage 滚动 / /stats 路由 / Context GC / ESR 触发 / BoundaryPrune / Context Ledger / JIT 推送）
 npm run eval  # 离线召回 + 结构基准（确定性语料，跑真实 store/recall 路径）
 ```
 
@@ -438,7 +449,7 @@ GC 永不触碰工作集：active 任务 `memory_refs` 引用的记忆、task
 （`hits >= promoteHits`）。用 `esr_gc` + `dry_run: true` 先预览。**不硬删**——报告的末尾为所有
 归档项附上重取指针，归档可恢复、不是丢失。
 
-### Context GC（替换 DSH 自动 compact）
+### Context GC（替换 DSH 自动 compact，opt-in）
 
 DSH 默认的上下文压缩是**有损 LLM 全量摘要**（`compaction-basic`）：被驱逐的历史被压缩成散文，
 不可查询、摘要本身还烧 token。dsh-engram 的自动 GC 替代它：`ContextGcEngine extends
@@ -453,7 +464,9 @@ BasicCompactionEngine` 只重写唯一的 `summarize()` 钩子，把摘要正文
 
 触发时机完全跟随 DSH 现有 compact（step pressure / context-overflow / `/compact`）；锁、回放校验、
 tool-call/result 配对、token 定价全部复用基本引擎。任何错误 → 回退默认压缩，**永不破坏 compact**。
-装配即注册 `compaction` 服务，卸载/reload engram 自动还回默认引擎。
+装配即注册 `compaction` 服务，卸载/reload engram 自动还回默认引擎。**自 v0.6 起默认不接管**：
+默认挂裸 `BasicCompactionEngine`（宿主 LLM 摘要），要换成指针摘要需显式打开
+`gcReplacesCompaction`（web 预设还需 `autoWebCompaction`）。
 
 > **收缩闸门（shrink gate）**：harness 拒绝任何不比被驱逐片段更小的 checkpoint（`summary is not
 > smaller than the shadowed content`），否则压缩回滚、上下文永不缩小、最终触发模型侧溢出。Context GC
@@ -464,24 +477,23 @@ tool-call/result 配对、token 定价全部复用基本引擎。任何错误
 
 #### 启用入口（这一节就是答案：该功能开在哪）
 
-Context GC 的装配在**两个平面**——web 现在**全部自动**，零配置：
+Context GC 的装配在**两个平面**，但两个开关都是 opt-in（默认不接管）：
 
 - **host 平面（headless / TUI / base 型 profile）——开箱即用，无需任何配置**：
   主插件 `lib/index.js` 在 `ctx.effect` 里直接
   `mountCompactionEngine(ctx, resolved, { readWorkspace }) → new Engine()` 注册 `compaction` 服务；
   配合插件 patch 禁用基座 `compaction-basic` 行，engram 即为该平面唯一 provider。
-  - `gcReplacesCompaction: true`（**默认**）→ `ContextGcEngine`（机械驱逐 + 重取指针）；
-  - `gcReplacesCompaction: false` → 挂裸 `BasicCompactionEngine`（退化为 DSH 默认 LLM 摘要），
-    **`compaction` 服务永不缺席**。
-  - 关闭/开启：profile patch 里给 engram 行加 `config: { gcReplacesCompaction: false }`，或设置卡
-    「记忆 GC」区的 `gcNarrative` 关掉叙事。
-- **preset 平面（web profile）——全自动，零配置，覆盖全部预设**：web 面把 compaction 放在 agent
+  - `gcReplacesCompaction: false`（**默认**）→ 挂裸 `BasicCompactionEngine`（DSH 默认 LLM 摘要），
+    **`compaction` 服务永不缺席**；
+  - `gcReplacesCompaction: true` → `ContextGcEngine`（机械驱逐 + 重取指针，opt-in）；
+  - 开启：profile patch 里给 engram 行加 `config: { gcReplacesCompaction: true }`，或在设置卡打开。
+- **preset 平面（web profile）——显式开启后覆盖全部 stock 预设**：web 面把 compaction 放在 agent
   preset 的 isolate realm（shipped 预设自挂 `compaction-basic`），host 条目进不去、profile patch 也
   够不到预设文件（`mountPreset` 的 Include 不带 patches——已对源码核实）。所以插件在启动时
   （`agentPresets` 服务就绪后）**自动改写每个仍处于出厂 stock 布局的预设**——默认预设 + 整张 roster
   （shipped 根 + `~/.dsh/.agent-presets` 用户根，`standard`/`code`/`cordis` 和你自己的预设都覆盖）：
   把 `compaction` 组里的 `compaction-basic` 行换成 `dsh-engram/compaction`。这一自动装配是：
-  - **默认开**（`autoWebCompaction: true`，设置卡「记忆 GC」可关），幂等——已替换则跳过；
+  - **默认关（opt-in）**（`autoWebCompaction: false`；设置卡「记忆 GC」可开），开启后幂等——已替换则跳过；
     **关掉的含义**：只是在之后的启动时不再自动接管（headless/TUI/base 的 host 平面不受影响）——
     它**不会**还原之前已接管的预设，要还原用 `npm run web-compaction:revert`；
   - **逐预设判定，只碰 stock 布局**——用户自定义过 compaction 组的预设，以及根本没有 compaction 组的
@@ -527,15 +539,16 @@ Context GC 的装配在**两个平面**——web 现在**全部自动**，零配
 
 #### 从 npm 安装后的第一印象（可感知 / 易引导 / 易配置）
 
-- **自动**：装进 profile 后启动一次即可——host 平面由 `mountCompactionEngine` 直接接管；web 平面
-  由 `autoWebCompaction`（默认开）在启动时自动改写全部 stock 预设。**无需任何手动配置。**
+- **半自动（opt-in）**：默认保留 DSH 自己的摘要；在设置卡打开 `gcReplacesCompaction`（host 平面）与
+  `autoWebCompaction`（web 预设）后，启动一次即由 `mountCompactionEngine` 接管、并把全部 stock
+  预设改写成 `dsh-engram/compaction`。开启后无需再手动改文件。
 - **可感知**：插件启动时把权威状态写到 `$DSH_HOME/engram/context-gc.status.json`
   （`host` 平面模式 + `web` 平面每个预设的接管结果 + 生效配置）。随时
   `npx dsh-engram status` 或 `npx dsh-engram doctor` 查看；web 记忆看板（ESR 任务看板）头部也有
   一枚状态徽标（"Context GC·主机 ·N 预设"，来自 overview API）。启动日志也有两行关键确认：
   `engram context-gc: compaction = Context GC …` 与 `engram web-provision: wired Context GC into preset …`。
-- **易配置**：一个设置卡（「记忆 GC」区）管全部：`autoWebCompaction`（web 自动接管开关）、
-  `gcReplacesCompaction`（用 Context GC 还是回退默认摘要）、`gcNarrative`（叙事兜底开关）——
+- **易配置**：一个设置卡（「记忆 GC」区）管全部：`autoWebCompaction`（web 自动接管，默认关）、
+  `gcReplacesCompaction`（用 Context GC 还是宿主摘要，默认关）、`gcNarrative`（叙事兜底开关）——
   改动后 `dsh web` 重启生效，web 预设行会被自动刷新成新配置。
 
 **验证是否生效**：`dsh web`（或对应 profile）重启后——
@@ -548,7 +561,7 @@ Context GC 的装配在**两个平面**——web 现在**全部自动**，零配
 - （若见 `… keeping the existing compaction service` 说明同域已有 provider、未替换成功；`web-provision … skipped (custom)`
   说明某预设是自定义/无 compaction 布局、未被触碰；`dsh-compaction-basic unavailable` 说明环境缺依赖，自动回退默认压缩。）
 
-### BoundaryPrune（子任务边界剪枝，默认关）
+### BoundaryPrune（子任务边界剪枝，默认开 + 账本否决）
 
 Context GC 管「压缩的摘要内容」，BoundaryPrune 管「确定性剪枝的触发时机」——
 在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 自带的
@@ -573,10 +586,13 @@ Context GC 管「压缩的摘要内容」，BoundaryPrune 管「确定性剪枝
   并配更小保留边缘（`boundaryPruneHeadChars`/`boundaryPruneTailChars`）可更早
   开剪——T2048+小边缘在真实语料上首剪节省是宿主默认的 2.4 倍（10.14M vs 4.23M
   字符）。降阈值在 `resultPack` 开启时安全（被剪中段有归档兜底）。
-- 默认**关**：`boundaryPrune: false`。开启后启动日志出现
-  `engram boundary-prune (todo @N reqs): pruned …`。
+- 默认**开**：`boundaryPrune: true`；`false` 是 opt-out。自适应闸门
+  （`boundaryPruneAdaptive: true`，默认开）让 Context Ledger 在该 workspace 真实剪枝后
+  净收益为负（≥3 次）时自动停剪——证据只能关、不会自行开。启动日志出现
+  `engram boundary-prune (todo @N reqs): pruned …`；被账本否决时出现
+  `engram boundary-prune: ledger gate holds for …`。
 
-### ResultPack L2（结果归档 + `result_recall`，默认关）
+### ResultPack L2（结果归档 + `result_recall`，默认开）
 
 让 BoundaryPrune 剪枝**无损**：每个被剪工具结果的被移除中段，按与记忆写入
 相同的规则脱敏后归档到 `~/.dsh/engram/resultpack/<callId>.json`，并在剪枝
@@ -591,8 +607,9 @@ Context GC 管「压缩的摘要内容」，BoundaryPrune 管「确定性剪枝
   [ENGRAM] 索引）；保留期 `resultPackRetentionDays`（默认 7 天）按 mtime 清理，
   搭 GC 同一节奏。
 - **自我禁用**：只开 L2 不开 L1 将无内容可归档，故不注册工具并打一条警告。
-- 默认**关**：`resultPack: false`（须与 `boundaryPrune: true` 同开）。开启后
-  启动日志出现 `engram result-pack enabled: result_recall(callId, offset) registered`。
+- 默认**开**：`resultPack: true`（与默认开启的 L1 配对，保证默认剪枝无损）；
+  关掉后 L1 仍可工作，但被剪中段不可召回。开启时启动日志出现
+  `engram result-pack enabled: result_recall(callId, offset) registered`。
 
 ### 激活遥测（SoL-Pi M15/C13）
 
@@ -607,6 +624,89 @@ overview）现在返回 `activation: { boundaryPrune, recall }`：
   （engram_recall 查询 → 命中 → engram_detail 下钻）闭合，可看到
   注入→查询→下钻的完整激活。
 
+### Context Ledger（净收益账本）
+
+把「省 token」变成可核对的账。每个模型请求记一笔：注入的 `[ENGRAM]`/`[RECALL]`
+与 `[ESR]` 块按存活请求数计入成本；被 BoundaryPrune 剪掉的结果按后续请求数计入
+节省；每次剪枝按 `(1 − ledgerCacheDiscount)` 计一次前缀重写罚金（KV 缓存击穿）。
+`GET /api/dsh-engram/stats` 与 `/overview` 返回 `ledger`：
+
+- `totals` — `requests / injectedChars / avoidedChars / rewriteCount / rewriteChars /
+  netChars / netTokens`（`net = avoided − injected − rewriteChars × (1 − discount)`）；
+- `byWorkspace` / `byDay` — 按工作区、按天的同一口径，`byDay` 倒序；
+- `openSessions` — 仍在累计、尚未落盘的会话数（进程重启最多丢 `flushEvery` 个请求的账）。
+
+GUI「遥测」页签直接画这块账本（净 token 大数字 + 节省/注入/重写罚金三卡 + 近 14 天红绿柱），
+记忆概览页也多一张「上下文净 token」卡。落盘在 `~/.dsh/engram/ledger.json`（原子写、按天滚动、
+delta 落盘），进程内只做整数累加，热路径零 I/O、零模型调用。默认 `ledgerEnabled: true`、
+`ledgerCacheDiscount: 0.1`；关掉 = 不挂监听、不写文件。**口径诚实**：token 按
+`chars / 4` 估算，不含 provider 实际计费与模型质量差；Context GC 的压缩节省暂未
+接入（宿主未暴露前后大小），因此账本只记「可证明」的部分。
+
+### JIT 推送（v0.6-C）
+
+拉取式召回被实证休眠（112 会话仅 24 次 `engram_recall`、8 次 `engram_detail`），所以
+v0.6 增加按事件**推送**：三个确定性事件，命中才推、每次一行、每会话最多 3 行（`jitMaxLines`，
+每行 `jitMaxLineChars`=220）：
+
+| 事件 | 触发条件 | 推什么 |
+|---|---|---|
+| 错误复发 | 同一 `cmd:` 签名第二次失败，且已有 error/procedure 记忆 | 该记忆的 id + 一行摘要 + `engram_detail` 下钻 |
+| 文件焦点 | 同一文件连续第二次编辑，且有 filePath/dir 锚定记忆 | 优先 preference，其次 fact/decision |
+| 目标完成 | goal complete/block 且有 active ESR 任务 | 前两个未闭环任务 + `esr_status` 提示 |
+
+- **append-only**：推送行一旦出现就不再改写/撤回，前缀每次推送只变一次；
+  每次推送按 `estimatePrefixChars + 行长度` 记一次重写罚金（Context Ledger 的
+  `rewriteCount` / `rewriteChars`），净收益可在遥测页直接看。
+- **无命中沉默**：没有可指向的记忆/任务就不推——宁可不推，也不灌噪声。
+- **零 LLM、纯规则**；`jitEnabled:false` 一键关，`[JIT]` section 为空时不占任何 token。
+- **尚未做**：resume brief（隔天继续）与「预计剩余请求不足时跳过推送」的显式 ROI 门——
+  当前靠 3 行硬预算 + 账本观测。
+
+### 会话纪要 + 恢复简报（v0.7-A/D）
+
+- **episode**：会话结束（`session/disposed`）时，用零 LLM 规则把事件日志压成一条紧凑纪要——
+  改过哪些文件、跑过哪些命令、哪些失败后修复（`cmd×N→fixed`）、git commit 的书面主题、
+  仍挂着的 todo。只在有实质内容时生成（纯 `ls` 会话不写）；**永不进 `[ENGRAM]` 索引**；
+  每个 workspace 只保留最近 20 条，超出自动归档。
+  数据源全部是已有事件（`tool/call` 的 arguments、`tool/result`、`todo/write`），不调模型。
+- **恢复简报**：新会话第一次组装时，取最近 7 天最新的 episode，注入 ≤240 字符的
+  `[RESUME]` 行 + `engram_detail <id>` 指针；与 `[ENGRAM]`/`[RECALL]` 一起按会话冻结。
+  没有近期 episode 就不注入——隔天继续项目时不用重新交代背景。
+- 设置键：`episodeEnabled`、`resumeBriefEnabled`（均默认开），
+  `episodeMaxPerWorkspace` / `resumeBriefMaxAgeDays` / `resumeBriefMaxChars` 可调。
+
+### 实体页 + 实体卡（v0.7-B）
+
+`esr_node` 从「图上的点」升级成**可读的页**：对一个实体（package / repo / 服务 / bug…）
+聚合当前真相、时间线、未闭环任务、冲突与关系。
+
+- **实体卡（索引内，默认开）**：`[ENGRAM]` 为活跃实体（有锚定记忆或未闭环任务）
+  渲染一行，最多 2 张：
+  `[ENT] dsh-engram · package · 3 mem · 1 open · truth: … #id · page: engram_detail(entity="dsh-engram")`
+  这些实体的平铺记忆行不再重复（真相由卡片承载）；其余实体仍列在 `nodes:` 一行。
+- **完整页（按需下钻）**：`engram_detail(entity="<name|id>")` 返回
+  `truth / timeline / open loops / conflicts / relations` 五段，带 memory id 与证据缺口；
+  没有注册节点但有记忆锚定的名字也会生成虚拟页。
+- 纯函数、确定性排序：preference 排在 truth 最前，superseded 旧真相不进 truth，
+  冲突按无序对去重（`#a vs #b`）。
+- 设置键 `entityCardsEnabled`（默认开）；`entityCardsMax` / `entityCardChars` 可调。
+
+### 可重验证锚点 + 分层 TTL（v0.7-C）
+
+「把过去当真相」是记忆插件最大的可信度问题。v0.7 给带 `filePath` 的记忆加**锚点**：
+
+- 写入时记录 `{path, mtimeMs, size, hash?}`（≤256KB 的文件存 sha256，大文件只存 stat），
+  落盘在记忆行的 `anchor` 字段；相对路径按 workspace 解析为绝对路径。
+- 会话启动时做一次**有界重验证**（最多 40 条）：文件缺失/改动 → 记忆打 `stale` 标签；
+  `[ENGRAM]` 索引与实体页 `truth` **不再自动展示**它，但**不删除**——`engram_detail`
+  仍可重取，实体页 timeline 会标 `· stale`。
+- **分层 TTL**：`preference` / `procedure` 永久；`episode` 默认 14 天；`error` 默认 60 天；
+  其余按 `expireDays`（默认 180 天）。真正删除仍只发生在 GC 的归档（不硬删）。
+- 设置键：`anchorRevalidate`（默认开）、`episodeTtlDays`、`errorTtlDays`。
+- **未做**：离线「巩固任务」（episode 抽象/合并）——确定性规则只能做 rollup，不是语义抽象；
+  在没有证据前不引入，留到 v0.8 与 playbook 一起考虑。
+
 ## 自动捕获策略
 
 捕获是确定性、离线的——只看到工具*结果*，从不看对话本身。什么会被记录成一条记忆：
@@ -679,12 +779,13 @@ promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-pr
     autoCapture: true        # 零 LLM 工具结果捕获
     autoCapturePreferences: true  # 零 LLM 用户纠正/偏好捕获（prefer/avoid/switch-to 句式）
     preferenceCapturePerSession: 8  # 每会话偏好记忆条数上限
-    boundaryPrune: false       # ResultPack L1：todo/goal 边界剪掉超阈值旧工具结果（默认关）
+    boundaryPrune: true        # ResultPack L1：todo/goal 边界剪掉超阈值旧工具结果（默认开）
+    boundaryPruneAdaptive: true  # 账本否决：该 workspace 净收益为负（≥3 次剪枝）时自动停剪
     boundaryPruneThresholdChars: 0   # 阈值覆盖（0=宿主 8192；如 2048 可更早开剪）
     boundaryPruneHeadChars: 0  # 覆盖时的保留头部（0=宿主 4096）
     boundaryPruneTailChars: 0  # 覆盖时的保留尾部（0=宿主 1024）
     boundaryPruneIdleCadence: 0   # 空闲步数边界（0=仅事件边界；覆盖无 todo/goal 会话）
-    resultPack: false          # ResultPack L2：剪掉的中段脱敏归档 + result_recall 按页召回（默认关，须与 L1 同开）
+    resultPack: true           # ResultPack L2：剪掉的中段脱敏归档 + result_recall 按页召回（默认开，须与 L1 同开）
     resultPackRetentionDays: 7 # 归档保留天数（mtime 清理，走 GC 节奏）
     sessionSearch: true      # engram_recall 也可对历史会话 FTS
     recallScope: workspace   # 召回范围：workspace（严格工作区隔离，默认）| global（可选跨工作区召回，带 [W:<ws>] 来源标记）
@@ -702,9 +803,17 @@ promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-pr
     gcEnabled: true          # 定时记忆 GC
     gcIntervalHours: 24      # 回收节奏
     gcStableRetentionDays: 120  # 超过此天数的 stable 任务离开 [ESR]
-    gcReplacesCompaction: true # Context GC：接管 DSH 自动 compact（false=回退默认 LLM 压缩）
+    gcReplacesCompaction: false # Context GC：接管 DSH 自动 compact（默认关=宿主 LLM 压缩；true=opt-in 指针摘要）
     gcNarrative: true        # 无锚轮次走 scoped LLM 叙事；false=纯机械（零 LLM）
-    boundaryPrune: false     # BoundaryPrune：todo/goal 边界主动剪超阈值旧工具结果（默认关）
+    jitEnabled: true         # JIT 推送：错误复发/文件焦点/goal 完成时推一行已有记忆
+    episodeEnabled: true     # 会话纪要：结束时零 LLM 生成 episode（不进索引，供恢复简报）
+    resumeBriefEnabled: true # 恢复简报：新会话注入最近 7 天最新 episode
+    entityCardsEnabled: true # 实体卡：[ENGRAM] 为活跃实体渲染一行真相 + 任务 + 下钻指针
+    anchorRevalidate: true   # 会话启动重验证 filePath 锚点（改动/缺失 → stale，不进索引/truth）
+    episodeTtlDays: 14       # episode TTL（preference/procedure 永久，error 60 天，其余 expireDays）
+    ledgerEnabled: true      # Context Ledger：注入成本/剪枝节省/前缀重写罚金 → 净 token
+    ledgerCacheDiscount: 0.1 # 缓存折价：重写按 (1−0.1) 计罚金；0.1 = 命中只付 10%
+    autoWebCompaction: false   # web 预设自动改写（默认关；开启需显式确认，可用 revert 还原）
     boundaryPruneMinRemaining: 50  # 偿还门：预计剩余请求数低于此值不剪
     engramIndexOrder: 40    # systemPrompt section 顺序（位于 tools 段之前）
     esrOrder: 41
@@ -713,7 +822,7 @@ promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-pr
 ## 开发
 
 ```sh
-npm test            # 152 个测试：核心 + Web API + GC + Context GC + ESR 触发（node:test）
+npm test            # 381 个测试：核心 + Web API + GC + Context GC + ESR 触发 + Context Ledger + JIT（node:test）
 npm run build:client
 ```
 

package/docs/CONTEXT-GC-GUIDE.zh.md

@@ -2,6 +2,9 @@
 
 > 适用范围：dsh web（preset 平面）+ headless/TUI/base（host 平面）。
 > 一句话：**用「机械驱逐 + 重取指针」替代 DSH 自带的有损 LLM 全量摘要压缩。**
+>
+> **v0.6 起是 opt-in**：`gcReplacesCompaction` 与 `autoWebCompaction` 默认都是 `false`，
+> 插件默认保留 DSH 自己的摘要。要启用 Context GC，先打开这两个开关（见第 3 步）。
 
 ---
 
@@ -26,8 +29,8 @@ dsh-engram 的 Context GC 把这一步换成：
 
 | 平面 | 覆盖 | 接管方式 |
 |---|---|---|
-| host 平面 | headless / TUI / base 型 profile | 插件启动时直接注册 `compaction` 服务为零配置 ContextGcEngine |
-| web 平面 | dsh web 的 agent preset（shipped + 用户预设） | 启动时自动把 stock 预设 `compaction` 组的 `compaction-basic` 行换成 `dsh-engram/compaction` 行 |
+| host 平面 | headless / TUI / base 型 profile | 打开 `gcReplacesCompaction` 后，插件启动时注册 ContextGcEngine；否则挂裸 `BasicCompactionEngine`（宿主摘要） |
+| web 平面 | dsh web 的 agent preset（shipped + 用户预设） | 打开 `autoWebCompaction` 后，启动时把 stock 预设的 `compaction-basic` 行换成 `dsh-engram/compaction` 行 |
 
 ---
 
@@ -41,29 +44,32 @@ dsh-engram 的 Context GC 把这一步换成：
 
 ---
 
-## 3. 从 0 安装并启用（3 步 + 1 条铁律）
+## 3. 从 0 安装并启用（4 步 + 1 条铁律）
 
 ```bash
 # ① 安装（源码开发方式；生产用 npm install dsh-engram）
 cd /path/to/dsh-loom && npm link            # 或 profile package.json 加 "dsh-engram": "link:..."
 
-# ② 启动一次 dsh web —— 这一步做「自动装配」
-#    - host 平面：立即注册 Context GC 为 compaction 服务
+# ② 打开两个 opt-in 开关（设置卡「记忆 GC」区，或 profile patch）
+#    gcReplacesCompaction: true   # host 平面换 ContextGcEngine
+#    autoWebCompaction: true      # web 预设自动改写（带 .engram.bak）
+
+# ③ 启动一次 dsh web —— 这一步做「自动装配」
+#    - host 平面：按 gcReplacesCompaction 注册 Context GC 为 compaction 服务
 #    - web 平面：改写每个 stock 预设文件（compaction-basic 行 → dsh-engram/compaction 行，
 #      每个文件旁留 agent.cordis.yml.engram.bak）
 dsh web
 
-# ③ 再重启一次 dsh web —— 让已接管的预设真正生效
+# ④ 再重启一次 dsh web —— 让已接管的预设真正生效
 dsh web
 ```
 
 **铁律：代码/预设改动后必须重启 dsh。** 运行中的进程把旧 `lib/*.js` 和旧预设行都缓存/装载在内存里，
-磁盘上的修复与文件改写不会热生效；只有重启（host 开机自动装配默认 `autoWebCompaction:true`）才会
-加载新代码并接管 web 预设。
+磁盘上的修复与文件改写不会热生效；只有在两个开关打开的前提下重启，才会加载新代码并接管 web 预设。
 
 > 也可以先手动预写再一次性重启：
 > ```bash
-> npx dsh-engram enable    # 等价于启动时的自动装配（通常 no-op）
+> npx dsh-engram enable    # 等价于启动时的自动装配（需 autoWebCompaction；通常 no-op）
 > npx dsh-engram status    # 确认 preset 已 wired
 > # 然后重启 dsh web 一次
 > ```