dsh-engram 0.3.4 → 0.3.6

package/docs/PROPOSAL-beads.zh.md

@@ -0,0 +1,81 @@
+# dsh-engram 改进方案 · 借自 Beads（依赖图 / 可逆压缩 / prime 注入）
+
+> 依据：[gastownhall/beads](https://github.com/gastownhall/beads) 深度研究（Go + Dolt 的分布式图式 issue tracker）。
+> 约束：全部**纯规则 / 零向量 / 零 LLM 蒸馏 / 确定性单测 / host 等自然重启**。
+> 现状：ESR 任务有 draft→active→stable + 证据门，但**无任务依赖 / 无认领所有权 / 无会话开始注入**。
+
+---
+
+## 总览
+
+| # | 概念（来源） | 解决什么 | 落点 | 成本 |
+|---|---|---|---|---|
+| ① | **依赖图 + ready 队列 + 原子 claim**（blockedstate.go / claimer.go / ready） | 任务各自为政：没有「谁挡谁」、没有可认领队列、没有所有权 | TaskSchema deps/assignee + `esr_dep`/`esr_claim`/`esr_unclaim`/`esr_ready` + board 阻塞标记 | host ~350 行 |
+| ② | **可逆压缩**（compactor.go SnapshotIssue 先归档再覆盖） | 闭环任务全文占看板/上下文；丢了细节 | esr_close 自动 `snapshot` + 规则 `summary`；board 显示摘要、可回看原文 | host ~60 行 + board |
+| ③ | **prime 注入模式**（prime.go 预算分层） | esr_model 只能按需查全文，无法 50-token 会话注入 | `esr_model` 加 `brief/full` + `max_chars` | host ~50 行 |
+
+顺序：**① → ② → ③**（① 是核心增量，②③ 轻量收尾）。
+
+**状态：① ✅ ② ✅ ③ ✅**（单 commit 落地，见 git log）。宿主 84/84（beads 12 + compaction 2 + prime 3）、
+dock 63/63、board 59/59（含 4 条 beads UI）。host 侧（esr_dep/esr_claim/esr_unclaim/esr_ready、compactOnClose、
+esr_model mode/max_chars）随下次 `dsh web` 重启生效；board 三处显示（🔒 blocker / @assignee / 🗜 摘要）
+client-hmr 即时生效。
+
+---
+
+## ① 依赖图 + ready + claim
+
+### 数据模型（TaskSchema 增量，向后兼容）
+```jsonc
+// 既有字段不动；新增：
+"deps": [{ "id": "tsk_2", "kind": "blocks" | "relates-to" | "parent-of" }],
+"assignee": null,          // claim 者
+"claimedAt": null
+```
+旧任务无这些字段 → schema default 兜底，不动存量。
+
+### 语义（借鉴 BlockedStateInvariant，纯派生）
+- `isBlocked(ws, id)`：存在一条**未关闭**（非 stable/未 archive）的 `blocks` 边指向自己 → blocked；或被 `parent-of` 链上父级 blocked 继承 → blocked。
+- `readyTasks(ws)`：active/draft 中 `!isBlocked` → 可认领队列。
+- `claimTask(ws, id, agent, {force})`：已被他人 claim（assignee 非空且 ≠ agent）且非 force → 拒绝（anti-yank fence）；成功置 assignee+claimedAt+state=active。
+- `unclaimTask(ws, id, agent, {force})`：同上 fence 反向。
+- 校验：`addDep` 防自引用 + **有向环检测**（BFS 从 dep 出发不可达自身即可）。
+- close 解锁：blocked 是派生的，无需显式释放（读时计算）；cycle 检测写时校验。
+
+### 工具（host）
+- `esr_dep {task_id, dep_id, kind}` → addDep，返回当前 dep 列表
+- `esr_claim {task_id, agent?, force?}` / `esr_unclaim {task_id, force?}`
+- `esr_ready {ws?, limit?}` → 无 blocker 的 active/draft 列表（一行一条 + 缺口）
+- 全部走既有 parse/guard/中文返回；拆写不入 dock。
+
+### Web
+- board 卡上：被 blocker 阻塞 → 卡头 🔒 + title 提示「被 N 个未闭环任务阻塞」；有 assignee → 卡 meta 显示 `@assignee`。（不做编辑，编辑走工具。）
+
+### 测试
+`test/beads.test.mjs`（或并入现有）：addDep 自引用拒 / 环拒 / isBlocked 直连+继承 / ready 过滤 / claim fence / unclaim fence / close 后 blocker 解锁 / route 注册。
+
+---
+
+## ② 可逆压缩（闭环快照）
+
+- esr_close 进入 stable 时：若 `description.length > 240` 字符 → `summary = 首行/前 120 字`（规则截断，无 LLM），`snapshot = { description, artifact, evaluation, memoryRefs }` 原文入库存档；否则 summary=null。
+- board 卡：`summary` 存在则显示摘要并标注「已压缩 · 原文见详情」；展开区回看全文（snapshot）。
+- 语义：上下文只看摘要、信息可逆，与 compact.go 的「先归档再覆盖」同序（我们是先归档再展示）。
+- 新增 `esr_task --full`（或 esr_detail 变体）回看 snapshot？最小：board 展开即可，不加新工具。
+
+---
+
+## ③ prime 注入模式（预算分层）
+
+- `esr_model` 加参数 `mode: "brief"|"full"`（默认 full）、`max_chars`。
+- `lib/mental.js` 加 `compileBriefSummary(domain, ws)`：只输出核心一行（任务 X 进行中/Y 就绪 · 实体 a b · 观测 N 条 · 风险 0）——对应 beads 的 ~50-token MCP 提醒。
+- brief 同样吃 dirty/水印缓存（复用 getModel，仅渲染模式不同）。
+- 工具文档更新：建议会话开始用 `esr_model --brief` 注入；全量按需用 full。
+
+---
+
+## 风险与不做
+- 不做 Dolt/分布式 sync / wisp 消息平面 / AI Haiku 压缩 / contributor-maintainer 路由。
+- 不做 board 依赖编辑 UI（工具优先，dock 保持极简）。
+- cycle 检测 O(V+E) 每写一次，任务数小（≤40/ws）无压力。
+- addDep 对 stable/archived 目标仍放行（可引用历史），仅校验存在性。

package/docs/PROPOSAL-contextgc.zh.md

@@ -0,0 +1,188 @@
+# dsh-engram 改进方案 · Context GC（自动 GC = 替代自动 compact，而非记忆面板回收）
+
+> 依据：[pi-esr Context GC](https://github.com/skepsun/pi-esr/blob/master/extensions/CONTEXT_GC.md)
+> （`extensions/context-gc.ts` + `CONTEXT_GC.md`，v0.7.0 落地）deep-dive。
+> 一句话定位（用户口径）：**pi-esr 的自动 GC 用于替代自动 compact（如 DSH 自带的上下文压缩），
+> 而不仅仅是记忆面板里的 gc**。
+> 约束：全部**纯规则 / 确定性 / 可回退 / 默认不烧额外 LLM（可配置）**；host 随 `dsh web` 重启生效。
+> **状态：提案待审（未实施）。**
+
+---
+
+## 1. 现状与缺口
+
+| 面 | 现状 | 缺口 |
+|---|---|---|
+| 记忆面板 GC | `esr_gc` 工具 + 定时 `runGcAll()` → `store.gc()`：TTL 过期归档、超容量淘汰、stable 任务 retention、悬空链接清理（只归档、不硬删） | 这**只是存储维护**，完全不参与上下文窗口 |
+| DSH 自动 compact | 基座 bundle 挂 `@deepseek-ai/dsh-compaction-basic`（`BasicCompactionEngine`）：pressure / context-overflow 时用 `ctx.llm.stream()` 做**有损全量 LLM 摘要**，替换旧轮次 | 有损、不可查询、摘要本身烧上下文；与 engram 已持久化的可重取细节重复付费 |
+
+> 结论：dsh-engram 目前**没有**接入 DSH 的 compaction 接缝，所以「自动 GC = 替代自动 compact」这一层完全缺失。
+> 本提案只补这一层；记忆面板 GC 保留原样（两者职责正交，互不干扰）。
+
+---
+
+## 2. 核心思路（对齐 pi-esr，落到 DSH 接缝）
+
+pi-esr 在 pi 侧 hook `session_before_compact`，把「被驱逐消息」扫描出 provenance 锚，返回**指针摘要**
+替代 LLM 压缩；只有**无锚轮次**才走 scoped LLM 叙事兜底。
+
+DSH 侧的等价接缝（已核实源码）：
+
+- `ctx.compaction` = 抽象的 `CompactionEngine`，默认实现 `BasicCompactionEngine`（`@deepseek-ai/dsh-compaction-basic`）。
+- `BasicCompactionEngine` 的**唯一子类钩子**是 `protected summarize(input, agent, signal)`；
+  其 `SummarizationInput.messages` = **被驱逐的 shadowed region（surface 顺序的完整消息）** ——
+  正好等价于 pi 的 `messagesToSummarize`。
+- `summarize` 返回 `SummaryResult` 后，`compactSurfaceRegion` 会统一经 `frameSummary()` 包装成
+  `user/message`（compactCheckpointSource + `<compacted-summary>` framing）落盘 —— 锁、回放校验、
+  tool-call/result 配对平衡、token 定价全都不用我们碰。
+
+**方案：`ContextGcEngine extends BasicCompactionEngine`，只重写 `summarize()`**，
+把「LLM 全量摘要」换成「provenance 扫描 → 指针摘要 +（可选）无锚叙事」。
+DSH 的自动 compact 一切触发/机制照旧（pressure / context-overflow / `/compact`），只是**摘要内容换成 GC 产物**。
+这就是「替代自动 compact」在 DSH 里的最小正确落地。
+
+六条 GC 约束映射（pi-esr `concept-context-gc` → dsh-engram）：
+
+| pi-esr 约束 | dsh-engram / DSH 行为 |
+|---|---|
+| stable-task-evictable | stable 任务（含 artifact/snapshot，记忆面板已归档原文）→ 指针 `esr_ready` / 看板回看，不逐字复述 |
+| indexed-output-evictable | engram 已落库记忆（`engram_store` / auto-capture / recall 命中的 `#xxxxxx`）→ 指针 `engram_detail(id)` |
+| loom-stored-evictable | 同 engram 记忆 + `filePath` 锚（提示性，不单独作重取调用） |
+| working-set-protected | active 任务 + 其 `memoryRefs` 引用记忆 + 相关 constraint → 在摘要里**复述**，永不驱逐 |
+| pointer-salience | 每个被驱逐类别都带**显式重取调用**（工具名 + 参数） |
+| no-provenance-no-evict | 无锚轮次 → scoped LLM 叙事（默认开，可配 `gcNarrative`）；失败/关闭 → 截断原文兜底 |
+
+---
+
+## 3. 实现设计
+
+### 3.1 新文件 `lib/context-gc.js`（host，~380 行）
+
+```
+scanProvenance(messages)          # 纯函数：消息 → ProvenanceReport
+groupTurns(messages, anchored)    # 纯函数：按 user 消息切轮次，标 anchored
+buildPointerSummary(report, domain, ws)   # 纯函数：→ 指针摘要（零 LLM）
+summarizeUnprovenanced(turns, ctx, signal, { narrative })  # 叙事/截断兜底
+ContextGcEngine extends BasicCompactionEngine
+  - summarize(input, agent, signal)   # 唯一重写点
+  - gcConfig (gcNarrative / gcNarrativeMaxTokens / gcNarrativeMaxChars / gcFallback)
+```
+
+**扫描规则**（DSH `Message.content` 的 `tool-call` / `tool-result` block）：
+- 锚工具：`engram_store` / `engram_recall` / `engram_detail` / `esr_task` / `esr_close` /
+  `esr_ready` / `esr_link` / `esr_dep` / `esr_claim` / `esr_unclaim` / `esr_node` / `esr_model`。
+- 提取：memory id（`#xxxxxx` / `mt…`，工具结果回显 + `engram_detail` 参数）、task/entity id
+  （`task-*` / `ent_*`）、`filePath` 存在性。
+- **管理工具不算锚**：`esr_gc`（同 ctx_purge 不重跑原则，绝不指示模型重跑 GC）。
+- 无模型调用、纯字符串/正则，确定性可单测。
+
+**指针摘要**（替换默认摘要正文，仍走 `frameSummary` 包装）：
+```
+## Context GC — 被驱逐细节可重取
+Evicted N turn(s): X with re-fetchable provenance, Y narrative-only.
+### engram 记忆（可精确重取）
+- `engram_detail(id: "…")`   # 被驱逐段内已落库的记忆
+- `engram_recall(query: "…")`  # 被驱逐段的检索线索（来源查询）
+### ESR 任务状态
+- active 工作集复述：`tsk_… [active] · 约束 …`
+- stable（已闭环/已快照）→ `esr_ready` / 看板回看
+### 未在其他地方保留的叙事
+<narrative 或 "None — all evicted turns had re-fetchable provenance.">
+---
+_优先重取，不要重新推导。_
+```
+
+**叙事兜底**（`summarizeUnprovenanced`）：
+- `gcNarrative: true`（默认）且存在可用路由 → scoped `ctx.llm.stream()` 一次性调用
+  （`purpose: 'compaction'`、`maxTokens: gcNarrativeMaxTokens=1024`、复用被驱逐消息前缀），
+  仅此路标记 `llmStreamCall: true`。
+- 无模型 / 失败 / `gcNarrative: false` → 截断原文（`serializeConversation`，上限 4000 字符，标注截断）。
+- 无无锚轮次 → 输出 `_None_`，**完全零模型调用**（最常见路径：编程会话大多有工具锚）。
+
+**可回退（永不破坏 compact）**：
+- `summarize()` 内任何扫描/读取/叙事错误 → `return super.summarize(input, agent, signal)`（默认 LLM 摘要）。
+- `gcReplacesCompaction: false` → 引擎根本不加载，DSH 继续走 compaction-basic。
+- engram 域未就绪（无 storage-domain 的 profile）→ 同上回退，不阻塞宿主启动。
+
+### 3.2 `lib/index.js` 增量
+
+- `DEFAULTS` 加：
+  ```js
+  gcReplacesCompaction: true,   // 接管 DSH 自动 compact（false=完全回退默认）
+  gcNarrative: true,            // 无锚轮次走 scoped LLM 叙事；false=截断原文（纯机械）
+  gcNarrativeMaxTokens: 1024,   // 固化默认即可，不进设置 UI
+  ```
+- `ctx.effect` 内（`index.js`）：`loadCompactionEngine(ctx, { auto: true }, deps, { mode })` → `new Engine()`，
+  注册 `compaction` 服务；`mode = gcReplacesCompaction ? "context-gc" : "default"`。Service 实例注册即生效、
+  随 fiber 卸载自动移除（cordis `Service` 语义）→ 卸载/reload engram 自动回滚，天然可逆。
+- 记忆面板 GC（`gcEnabled` / `esr_gc`）原样保留。
+
+### 3.3 装配（mounting，实施时已运行时验证 cordis 同名 service 语义）
+
+**验证结论**（cordis `reflect.provide` + loader `isolate` 源码 + loader-composition 测试）：
+cordis **拒绝**同一隔离域的第二个同名 provider——`provide()` 直接抛
+`service "compaction" has been registered at <fiber>`，**不是**「更深/更晚 wins」。
+因此装配=下面两条，都已落库：
+
+1. **基座行禁用（必须）**：dsh-engram 的 `cordis.patch.yml` 增加
+   ```yaml
+   - id: compaction-basic
+     disabled: true
+   ```
+   bundle patch 层按 bundle 顺序应用、dsh-engram 晚于 dsh-base → 该行生效；卸载 engram 即自动还原。
+   禁用后 `compaction` 由 dsh-engram 独占提供：`gcReplacesCompaction:true` → ContextGcEngine，
+   `false` → 裸 `BasicCompactionEngine`（与默认行为一致），因此 **`compaction` 服务永不缺席**。
+2. **preset 面条目（web profile 必需）**：web 面把 compaction 移到 agent preset 的 isolate realm
+   （dsh-web-app 禁用基座行、`standard` 预设自挂 `compaction-basic`），host 平面条目进不去该 realm。
+   为此新增可挂载条目 `lib/compaction.js`（`name: dsh-engram-compaction`、`inject: [llm, tokenMeter,
+   sessions]`、`package.json` `./compaction` export），把预设 `compaction` 组里的 `compaction-basic`
+   行换成 `- name: dsh-engram/compaction` 即按 session 生效（recipe 见 README）。
+
+### 3.4 依赖与设置
+
+- `package.json` peerDependencies 追加（均 optional）：
+  `@deepseek-ai/dsh-compaction`、`@deepseek-ai/dsh-compaction-basic`（宿主基座已装，此处仅声明类型与导入契约）。
+- `settings.js` schema 追加 `gcReplacesCompaction` / `gcNarrative`；`SETTINGS_KEYS` 同时收录二者。
+  设置 UI 收敛原则（assessment P4）下**只把 `gcNarrative` 放进高级折叠**，`gcReplacesCompaction` 走
+  profile / preset 配置。
+- `peerDependencies` 追加（均 optional）：`@deepseek-ai/dsh-compaction`、`@deepseek-ai/dsh-compaction-basic`、
+  `@deepseek-ai/dsh-llm`；`setup-links.mjs` 补三条 junction（`.mjs` 开发工作流）。
+
+---
+
+## 4. 测试（`test/context-gc.test.mjs`）
+
+| 组 | 用例 |
+|---|---|
+| 扫描 | tool-call/tool-result 提取 memory id / task/entity id / filePath；`esr_gc` 排除；tool-result 回显关联 |
+| 轮次 | 按 user 切轮、anchored 透传、无锚轮次归集 |
+| 指针 | 合成 report + 假 domain：working-set 复述、stable 指针、`_None_` 叙事、footer |
+| 叙事 | 关（纯机械、无 llmStreamCall）/ 开且成功（llmStreamCall）/ 失败截断兜底 |
+| 引擎 | 假 ctx + 假 session：`summarize()` 产指针块不落错；**错误 → 回退 super**（注入可替换的 defaultSummarize 以便单测）；`gcReplacesCompaction:false` 不加载 |
+| 装配 | config 合并键存在；`loadCompactionEngine` 两 mode 各返回正确类；preset 条目 shape + apply 挂载（default/context-gc 各断言受托引擎） |
+
+回归：`npm test`（当前 143/143 全绿）+ `npm run build:client`。
+
+---
+
+## 5. 风险与不做
+
+- **不做主动触发**（等价 pi `--gc-auto` / `--gc-auto-percent`）：只跟随 DSH 现有时机（pressure /
+  context-overflow `/compact`）——用户已确认，改动最小。
+- **不重写** retention walk / token 定价 / 锁 / 回放校验 / tool 配对平衡：全部复用 `BasicCompactionEngine`。
+- **不与 tool-result pruner 冲突**：`ctx.toolResultPruner` 在 range 选择前先压大 `tool/result` 节点，
+  我们的 `summarize` 收的是 prune 后的 shadowed region；指针指向 engram 本体记忆（不受 prune 影响）。
+- 指针摘要比默认摘要短 → 每次 compact 省 token 可量化（落盘前用 `ctx.tokenMeter.estimateMessage` 记一次）。
+- 极端场景：无任何锚且 `gcNarrative` 关 → 截断原文可能比默认 LLM 摘要长；有 `gcNarrativeMaxChars` 上限兜底，
+  且这是用户显式关闭叙事的取舍。
+
+---
+
+## 6. 落地顺序
+
+1. `lib/context-gc.js` 纯函数层（scan / group / pointer / narrative-fallback）+ 单测（先行，无依赖）。
+2. `ContextGcEngine` + `summarize()` 重写 + 回退注入 + 单测。
+3. `index.js` 装配 + config 键 + 装配单测（含「卸载回退」验证）。
+4. 设置 schema / UI 高级折叠（`gcNarrative`）。
+5. README.zh.md「记忆 GC」章节扩为「自动 GC = Context GC（替换自动 compact）+ 记忆面板 GC」，FEATURES.zh.md 记一笔。
+6. 全量 `npm test` 回归 + `npm run build:client`（若 UI 有改动）。

package/docs/PROPOSAL-esrtrigger.zh.md

@@ -0,0 +1,199 @@
+# 提案：ESR 触发机制对齐 pi-esr —— 静态方法论 + 会话快照 + 拉取式触发
+
+- 状态：**已实施**（含范围「完整实施」+「提示行挪到 esr_status」两项批准决策）
+- 面向：dsh-engram `[ESR]` 块的触发/提示机制（P0-A/B + P2 + P3 + P4）
+- 参考：pi-esr（`@pi-esr/…`）——README「为 LLM 前缀缓存稳定性而生，每字节确定」（三个不变式 + 状态机 + 增量读取）
+
+---
+
+## 1. 为什么现在改（当前机制的不稳定点）
+
+`[ESR]` 块是 dsh-engram 模型侧触发 ESR 的全部入口。当前实现（`lib/index-block.js` `renderEsr` +
+`lib/trigger.js` `makeTriggerRecorder` + `lib/index.js` systemPrompt section 装配）：
+
+1. **`[ESR]` 块每轮系统提示词装配都重新渲染**。对比 `[ENGRAM]` 走 `blockFor()` 的每会话
+   `sessionCache` 冻结缓存，`engram:esr` section 的 `text()` 直接调 `renderEsr(...)`——每次都带着
+   live recorder 重跑。于是逐轮注入内容漂移 → **打断前缀缓存（KV cache）**，会话越长成本越高。
+2. **块内混入推式启发式提示行**：`promote:` / `root-cause:` / `close:` / `stale:` / `escalate:`
+   随运行态出现/消失（一旦强制一次/会话抑制、magic 阈值 `minTodosForPromote`/`todoPromoteRatio`/
+   `minErrorHits`/`staleTaskDays`/`escalate 0.34`）。`sortActiveForNext` 的末位 tiebreak 用
+   `updatedAt` → 同状态任务排序随时间漂移。这些行**每轮都可能不同**，无法复现、难以测试，也不稳定。
+3. **教模型「何时用 ESR」靠运行时 nudge，而非静态方法论**：协议（建任务→升 active→证据闭环）
+   依赖提示行出现才被记得；提示被 once 抑制后协议也就不可见了。
+4. **推式状态全在进程内内存**（todo 快照、mem/esr 计数、once 抑制集合）→ 宿主重启即清、跨会话
+   不可见、纯时序依赖。
+
+> 一句话：**触发信号从「每轮推送进前缀」变成「每轮推送进前缀」的错误姿势**——正确姿势是
+> 「前缀里只有字节恒定的方法论+快照，实时状态按需拉取」。
+
+---
+
+## 2. pi-esr 参考（「稳定」的三个不变式 + 状态机）
+
+pi-esr README.zh-CN：*「一个受约束的语义图状态机，专为……设计。为 LLM 前缀缓存稳定性而生——
+每个字节都是确定性的。」*
+
+| # | 不变式 | pi-esr 落地 | 我们当前的违背点 |
+|---|---|---|---|
+| 1 | **系统提示词运行时永不变化** | `prompts/esr.md` 静态方法论 + Golden Rules + Minimum workflow，每轮逐字节相同 | `[ESR]` 块每轮重渲染、提示行增删 |
+| 2 | **会话快照注入一次、绝不中途自动刷新** | `[ESR_CONTEXT]` 在 SessionStart 注入，末尾明示 "This snapshot WILL NOT auto-refresh. Call `esr_get_context`…"；上下文**确定性排序**（entity by id、relation by (from,type,to)），**时间戳排除在上下文外**（保字节稳定） | `[ESR]` 从未冻结；`sortActiveForNext` 用 `updatedAt` 排序 |
+| 3 | **增量读取** | `esr_get_context(since_revision=N)`：版本一致 → ~10 token 的 "ESR state unchanged since revision N"；不一致 → 全量确定性快照 | 没有拉取工具；状态只在块里 |
+| 4 | **状态机** | draft → active → stable（blocked/deprecated）；每次转换自动 journal；`esr_complete_task` 一站式证据闭环；「State is the single source of truth」 | 已有 draft→active→stable + 证据门（对齐），无需大改 |
+
+另外 pi-esr 把「何时该创建/提升/闭环」写进**协议文本**（`When to call ESR` / `Minimum workflow` /
+`Golden rules`），而不是运行时 nudge——稳定且提示串可复用。
+
+---
+
+## 3. 推荐设计（dsh-engram 落地：静态 + 快照 + 拉取）
+
+### 3.1 静态方法论 section（新增 `engram:esr-method`，字节恒定）
+
+固定文本（仿 pi-esr Golden Rules / Minimum workflow，改成 dsh-engram 工具名），每轮逐字节相同：
+
+```
+ESR（工程状态）操作协议 —— 多步工作建任务、用证据闭环：
+  1. 动工前：esr_ready 看可认领工作；esr_status 拿实时状态（本块是会话开始快照，不会自动刷新）。
+  2. 多步工作 → esr_task(name="…", entity=…) 建任务（draft 起步）；重复对象 → esr_node；关系 → esr_link。
+  3. 动工 → esr_claim（draft → active）。
+  4. 收工 → esr_close（artifact + evaluation + memory_ref 三证齐才算数；不齐的活继续挂着，别硬关）。
+  state 是唯一真相：拿不准 state 就 call esr_status。
+```
+
+装配在 `esrOrder` 之前（如 order-1），**不依赖任何运行态**。DSH systemPrompt section 本身就
+按 section 缓存；该 section 返回的文本只由静态内容组成 → 字节稳定。
+
+### 3.2 `[ESR]` 块改为「每会话冻结快照」（复用 `blockFor` 的 sessionCache）
+
+- `renderEsr` 放进与 `[ENGRAM]` 相同的 `sessionCache` WeakMap（新 session → 渲染一次）。
+- 快照内容（全部**确定性派生**，无 LLM、无 recorder、无时间戳）：
+  - `[ESR] tasks: N active / M stable / K draft`
+  - 证据齐的最优先行：`next: esr_close <id>`（`evidenceGaps` 纯派生）——保留
+  - 活动任务列表按 `READY→claimed→active→draft` 排序列出；**最后 tiebreak 从 `updatedAt`
+    改为 `id` 字典序**（等价 pi-esr「时间戳排除在上下文外」；同一 store 快照 → 字节相等）
+  - `closed:` 行（stable 汇总）——保留
+  - 固定尾行：`snapshot from this session's start — WILL NOT auto-refresh; call esr_status for live state`
+  - **删除**全部 `promote:/root-cause:/close:/stale:/escalate:` 行与 `#suggest-*` 来源标记（从块内）
+  - 空态时保留一行固定的「BE PROACTIVE」教模型建任务（静态文本，非 nudge）
+- 无 session 的渲染（GUI 预览）天然不带 hints，行为不变。
+
+### 3.3 `esr_status` 拉取工具（新增，替代推式提示的全部「实时」职责）
+
+工具（读类，zero-写）：`esr_status(workspace?, since_revision?)`
+
+- **全量视图**：确定性排序的活动/稳定/draft 任务 + `next:` 行 + stable 汇总（≈现 `renderEsr`
+  的静态部分，但含活数据）。
+- **增量**：进程内维护 workspace 级 `revision`（每次任务写操作 +1，或像 pi-esr 那样用
+  DJB2 指纹 `buildGraphFingerprint`，二选一，实施时定）；`since_revision ≥ 当前` →
+  返回 `ESR state unchanged since revision N (~5 行小响应)`；不一致 → 全量。
+- **派生 actionables（原 P0-A/P0-B/P2/P3 转变而来，只在「拉」时产生）**：
+  - `promote:` — 读 recorder 的 todo 快照（`minTodosForPromote`/`todoPromoteRatio` 保留，但只在此 apply）
+  - `root-cause:` — 读 store 的复发错误候选（`minErrorHits` 保留）
+  - `close:` / `stale:` — 读 `workDone` 标记 / `staleTaskDays` 计算（stale 按 task update 时间
+    在**拉取时**算——不进前缀，时间敏感无碍）
+  - `escalate:` — 读 recorder 的 mem/esr 实时计数
+  - 每条仍带 `#suggest-*` 标记（可引用、可归因）
+- 由于这些行只在按需返回里出现，**永不进入每轮前缀** → 前缀稳定性不受影响。
+
+### 3.4 `[ENGRAM]` index 块保持现状（已经冻结，不在此提案范围）
+
+### 3.5 P4 转化度量适配
+
+- `emitHint(kind, ws, sessionId)` 从「`renderEsr` 注入块时调用」改为「`esr_status` 返回该 hint
+  时调用」（真实返回路径）；`tools/result` 订阅里 esr_* 的 10 分钟窗口归因**保持不变**。
+- `/triggerstats` API/口径文案微调（触发源：`esr_status` 返回，而非块注入），路由不变。
+
+### 3.6 保留 / 移除对照
+
+| 现状 | 动作 |
+|---|---|
+| `[ENGRAM]` 冻结块 | 保留 |
+| 记忆面板 GC、Context GC | 保留（刚实施） |
+| `esr_task/esr_close/esr_link/esr_dep/esr_ready/esr_node/esr_claim` 工具与证据门 | 保留 |
+| GUI「沉淀到 ESR」按钮 | 保留 |
+| `tools/result` 订阅喂 recorder（todo 快照、mem/esr 计数） | **保留**（转成 esr_status 的拉取数据源；不再喂块渲染） |
+| `[ESR]` 块逐轮重渲染 | **移除** → 每会话冻结快照 |
+| 块内 `promote/root-cause/close/stale/escalate` 行 | **移除** → 移到 `esr_status` 拉取结果 |
+| `sortActiveForNext` 的 `updatedAt` tiebreak | 改为 `id` 字典序（确定性） |
+| 静态方法论 | 新增 `engram:esr-method` |
+| `esr_status` | 新增（含增量 revision） |
+| 配置键 `minTodosForPromote/todoPromoteRatio/minErrorHits/staleTaskDays` | 保留（仅作用于 esr_status 派生行） |
+
+---
+
+## 4. 测试（`test/` 新增/改动）
+
+| 组 | 用例 |
+|---|---|
+| 快照确定性 | 同一 store 快照下 `renderEsr` 两次调用输出**逐字节相等**；输出**不含** `#suggest-*`/`promote:`/`escalate:` 等 hint 行 |
+| 排序确定性 | `sortActiveForNext` 对同 rank 任务按 id 稳定排序（不再用 updatedAt 漂移） |
+| 版本/增量 | `revision` 单调递增（写任务 +1）；`esr_status(since_revision=当前)` → short "unchanged" 响应；过期 rev → 全量 |
+| 派生行 | esr_status 含 promote（todo 快照条件）/ root-cause（hits≥阈值）/ close（workDone）/ stale（超窗）/ escalate（mem ratio），每条带 `#suggest-*` |
+| 静态方法论 | `engram:esr-method` 文本与运行态无关（两轮装配字节相等） |
+| 回归 | 现有 143 测试全绿（`renderEsr` 的既有调用方/测试按新语义适配：无 recorder 时=纯快照） |
+
+---
+
+## 5. 风险与不做
+
+- **不做**：不删 `tools/result` 的 recorder 订阅（它是 esr_status 派生行的数据源）；
+  不做 pi-esr 式「协议硬门」（PreToolUse 强拦）——DSH 是自由 agent，硬门会进交互层，暂不做；
+  不做 `since_revision` 的持久化（进程内 revision 足够；跨宿主重启全量返回，代价可接受）。
+- **行为变化**：`[ESR]` 块不再逐轮提醒 → 依赖提示的旧行为消失，由静态方法论 + 用户/模型主动
+  `esr_status` 替代。这是「稳定换主动」的取舍，正是 pi-esr 的取向。
+- **GUI 预览**：`renderEsr` 不带 recorder 时本来就渲染静态视图，改动后预览与真实快照一致。
+- `updatedAt` 不进入快照（连 tiebreak 都不依赖它）→ stale 只存在于拉取视图，天然与缓存解耦。
+
+---
+
+## 6. 落地顺序
+
+1. `index-block.js`：`sortActiveForNext` tiebreak 改 id；`renderEsr` 去掉 hint 分支（保留
+   `next:`/列表/closed/静态 BE PROACTIVE/尾行）；配套单测。
+2. `index.js`：`[ESR]` 并入 `sessionCache` 冻结渲染；新增 `engram:esr-method` 静态 section。
+3. `store.js`：workspace 级 `revision` 计数（写路径 +1）+ `buildWorkspaceFingerprint`（可选）。
+4. `tools.js`：新增 `esr_status`（全量 / since_revision 增量 / 派生 actionables）。
+5. `trigger.js`：`emitHint` 改从 esr_status 返回路径调用；其余逻辑保留为拉取数据源。
+6. 文档：README.zh/README.md 的「决策点触发」章节改写为「静态协议 + 会话快照 + 拉取触发」；
+   FEATURES.zh.md 记一笔。
+7. 回归 `npm test` + `npm run build:client`。
+
+---
+
+## 7. 验收
+
+- `[ESR]` 块在同一会话内两次装配**逐字节相同**（前缀缓存稳定）。
+- 同一 store 快照下 `renderEsr` 输出确定性（无时间戳、无 recorder、无 `#suggest-*`）。
+- `esr_status` 提供增量短响应 + 全量确定性视图 + 全部派生 actionables，各自带稳定来源标记。
+- 现有 143 测试全绿 + 新增测试通过；客户端构建通过。
+
+---
+
+## 8. 实施记录（与提案的差异）
+
+- **revision 采用任务表面指纹，而非单调计数器**：`store.esrFingerprint(workspace)` 对
+  id/state/evidence/认领人排序后 sha256 前缀（`hashText`）——零持久化、跨重启一致、时间戳天然排除
+  （提案 §4「决定在实施时定」：计数器 vs 指纹 → 选指纹；持久化 → 不持久化全量兜底）。
+- **`[ESR]` 头部把 draft 单列**：`tasks: N active / M stable / K draft`（N 不含 draft，避免歧义）。
+- **`esr_status` 响应统一走 `buildEsrStatusView`**（index-block.js 导出）：始终重算 actionables
+  （易变部分——balance/stale 窗口），`since_revision` 只短路**状态视图**；actionables 在
+  unchanged 分支仍会返回。
+- **gui/api 的 `renderEsrBlock` 变为纯快照**（hint-free），与冻结前缀一致；预览即真值。
+- **测试**：143 → 148（新增：指纹时间戳排除、buildEsrStatusView 全量/增量/过期、方法论字节恒定、
+  快照 hint-free 确定性）；`trigger.test.mjs` 全部提示测试改走 `esrHintLines` / `buildEsrStatusView`。
+
+### 8.5 再修订：混合方案（提升行为主动性，用户二轮拍板）
+
+- 用户反馈：纯拉取让「主动建任务/实体/关系」不保证（模型不调 `esr_status` 就看不到提示）。
+  批准混合：`[ESR]` 块 = **冻结快照 + 本会话单调追加的 actionables**。
+- **实现是「单调渐进」而非字面「会话开始冻结一次」**：会话第一帧装配时 recorder 还是空的，
+  字面冻结等于没提示。正确做法是每条 actionable 在它成熟的那一刻（如模型写完 todo 计划后的
+  下一轮）被 `esrHintLines` 一次性产出 → 追加进块并永久冻结（`holder.actionables` 按 kind 存储、
+  `ESR_HINT_ORDER` 固定排序），永不回撤 → 前缀只在「真正出现新决策点信息」时变化一次。
+- 若干细节：`buildFrozenEsrBlock(store, ws, config, {recorder, sessionId, holder})` 是宿主装配入口；
+  `[ESR]` 不再用 WeakMap 缓存（渲染是纯确定性派生，变化只来自新 actionables）；
+  快照本体保持 hint-free（GUI 预览 `renderEsrBlock` 仍是纯快照）；
+  `esr_status` 保持纯拉取（实时状态 + 会话中后期才成熟的派生）。
+- 测试：新增「快照纯净 + actionables 单次追加」「单调增长 / 已追加不回撤」、「无 recorder 状态时纯快照」。
+- 文档：README.zh/README.md/FEATURES.zh.md 的 0a 章节改为混合语义，注入块示例含
+  `# this-session actionables (frozen)`。

package/docs/PROPOSAL-hindsight.zh.md

@@ -0,0 +1,156 @@
+# dsh-engram 改进方案 · 借自 Hindsight（三个概念，不引重路线）
+
+> 依据：[vectorize-io/hindsight](https://github.com/vectorize-io/hindsight) 深度研究（2026 春季快照）。
+> 原则：三条全部**纯规则 / 无向量 / 无 LLM 蒸馏 / 确定性可单测**，符合既有约束
+> （不引重路线、中文、host 改动等自然重启、dock 极简）。
+> 真实基线：Kototoro memories 71（扁平）/ tasks 1 / links 4 / nodes 3；toolstats 近 14 天
+> todo 48 · ESR ~6 · esr_node/esr_link 接近零。
+
+---
+
+## 总览
+
+| # | 概念（来源） | 解决什么 | 落点 | 成本 | 依赖 |
+|---|---|---|---|---|---|
+| A | **Observation 范式**：证据引用 + proof_count + refine-not-overwrite（consolidator.py） | 71 条扁平记忆无从浓缩；失败/成功经验被覆盖不保留证据链 | `lib/store.js` 写入侧 + `lib/obs.js` 新模块 + board 观测区 | host ~250 行 | 无 |
+| B | **Mental model 预计算**：常驻答案读零计算 + 水印刷新（mental_models + last_memory_seen_at） | 每次会话现查照样费 tokens；dock/board 每次重算 | `lib/mental.js` + 新工具 `esr_model` + board 常驻条 | host ~200 行 | 依赖 A 提供的 observation 汇总 |
+| C | **召回重排信号**：proof_count boost × recency 半衰期（reranking.py） | 现行排序只有 recency+精确匹配；失败复活性差 | `lib/rerank.js` 纯函数 + bm25Rank 接入 | host ~80 行 | 无 |
+
+状态：C ✅（7093fb5）/ A ✅（7103a22）/ B ✅。建议实施顺序：**C → A → B**。
+B 落地要点：`models` 表注册（ws/content/generated_at/dirty/sources_hash）；
+`lib/mental.js` 纯函数 compileSummary（任务/实体/观测/记忆种类聚合 → markdown）、
+computeSourcesHash、modelStale（dirty ∨ 超 10min ∨ 输入 hash 变）、getModel（冷缓存重算并持久化）；
+esr_* 六个写工具成功路径统一 `markModelDirty`；agent 工具 `esr_model`（返回常驻摘要+生成分钟数）
+与 `/model` 端点；board 顶部可折叠「常驻摘要 · 生成于 N 分钟前」。新测试 6 个（宿主 67/67）。
+C/A/B 的 host 部分（rerank、/observations、/model、esr_model、dirty 钩子）随下次 `dsh web` 重启生效；
+board 观测条/常驻条 client-hmr 即时生效。
+A 落地要点（相对本稿）：`observations` 表注册进 `engramDomainSpec`；
+`storeMemory` 三路（新建/exact-dup/失败复活）均触发 `integrateObservation`，其中
+**失败复活（revive）是「新发生」→ forceEvidence 爬 proof**，exact-dup（同源）只刷
+span；`engram_recall` 尾部注入 proof≥2 的观测段；board 加可折叠「观测 · 信念 N」条；
+`/observations` 端点与 /toolstats 同批等重启；新测试 12 个（宿主 61/61）。
+
+---
+
+## A. Observation：证据浓缩 + 证据计数 + 增强而非覆盖
+
+### 问题
+- 记忆是扁平列表；同一主题的多次失败/多次成功没有聚合，`esr_recall` 返回的是散点。
+- D1/D3 的「失败记忆复活」只恢复了单条，没有形成「这个模式被证明 N 次」的信念。
+
+### 数据模型（新增 `tables.observations`，存 storages/dsh_engram.json）
+```jsonc
+{
+  "id": "obs_<8>",
+  "ws": "/ws/A",                 // "" = 全局
+  "text": "浓缩后的信念语句（初始 = 触发记忆文本）",
+  "kind": "belief",              // belief | pattern | risk（由触发记忆 tags 推导，不引 LLM）
+  "proof": { "count": 3, "sources": ["mem_<8>", ...] },
+  "span": { "first_seen_at": 1, "last_seen_at": 2 },
+  "negations": 0,                // 反证计数 → 触发 weaken/stale
+  "trend": "stable",             // new|strengthening|stable|weakening|stale（算法计算）
+  "tags": ["fail"],
+  "updated_at": 3
+}
+```
+
+### 算法（`lib/obs.js`，全部纯函数 + 一个写入钩子）
+1. **`concentrate(ws, memText, memId, tags)`** —— host 写入记忆（esr_store_memory / 失败复活 / engram 自动捕获）后调用：
+   - 桶化：按 `(entity 锚点 或 tags) + 字符 n-gram Jaccard ≥ 阈值(0.45)` 找既有 observation（中文无需向量）。
+   - 命中 → **merge 而非覆盖**：`proof.count+1`、`sources.push(memId)`、`span.last_seen_at = now`、`updated_at=now`；`text` 仅在新增细节时 append（简单规则：新文本含旧文本不存在的 token 段则并句）。
+   - 命中且可判定为**反证**（tags 含 `error`+当前 text 与旧 text 出现否定词对）→ `negations+1`，`proof.count` 不变。
+   - 未命中 → 新建 observation（`proof.count=1`）。
+2. **`computeTrend(span, now, recentDays=30, oldDays=90)`** —— 借鉴 observations.py 的 `Trend`：
+   - last_seen 在 30 天内且 first_seen 更早 → `strengthening`
+   - 全部证据在 30 天内 → `new`
+   - 90 天内有证据 → `stable`
+   - 90 天内无新证据但有历史 → `weakening`；无证据 → 不存在的桶自清（GC 归入 esr_gc）。
+3. **读取注入**：`esr_recall` 把 `proof.count ≥ 2` 的 observations 作为高权重候选混入返回（标记 `source: observation`），证据门语义不变。
+
+### Web 展示
+- 只进 **board**（dock 保持极简）：columns 上方一行可折叠「观测 · N 条信念」条，展示 `text · ✓×count · 趋势图标`，展开可看 sources 列表。
+- KPI 行（toolstats 那行）旁加 `观测 N`。
+
+### 测试
+`test/obs.test.mjs`（node:test 直接 import）：
+- 首次写入建桶 / 二次相同语义 merge（count 2 且 sources 追加）/ 反证 negations+1 /
+  trend 四种时间窗 / 阈值下不误并 / Jaccard 中文样例。
+
+---
+
+## B. Mental model：常驻摘要 + 水印刷新
+
+### 问题
+- agent 每轮现查「这个工作区现在什么状态」要花多次 recall；看板每次挂载重算 overview + tasks + links。
+- 产出一个可被反复读取、只在数据变化时才重算的「常驻答案」→ 读零计算。
+
+### 数据模型（新增 `tables.models`）
+```jsonc
+{
+  "ws": "/ws/A",
+  "content": "## /ws/A 常驻摘要\n- 任务：2 active（1 就绪）/ 1 stable\n- 实体 3 · 链接 4\n- 观测 6 条信念（2 失败模式已重复 3 次）\n- 近 14 天：todo 48 · ESR 6\n- 生成于 N 分钟前",
+  "generated_at": 1,
+  "dirty": true,           // 任何 esr_* 写操作后置 true
+  "sources_hash": "sha256 摘要（惰性校验可跳过重算）"
+}
+```
+
+### 算法（`lib/mental.js`）
+- **`bumpDirty(ws)`** —— host 工具写钩子（esr_task/esr_close/esr_node/esr_link/esr_store_memory/todo 沉淀）之后调用。
+- **`getModel(ws)`** —— 读缓存；`dirty` 或过期（>10min）则**纯聚合重算**（无 LLM）：复用 `domain` API 的 tasks/entities/links 计数 + `collectToolCounts` 的近况 + `tables.observations` 的 top 信念 → 拼 markdown；重算后 `dirty=false`。
+- **暴露**：
+  - agent 工具 `esr_model(ws?)` —— 返回常驻摘要 markdown（**零 LLM、一次 DB 读**）放在工具说明顶部「先看 model 再 recall」；response 带 `modeling:` 行同款风格。
+  - web endpoint `/model?ws=`（route 注册随下次重启，与 /toolstats 同批）。
+
+### Web 展示
+- board 顶部「常驻摘要 · 生成于 N 分钟前」可折叠条（可复制、可下载为 md——复用自己的 buildTasksMarkdown 思路，纯 client 无依赖）。
+
+### 测试
+`test/mental.test.mjs`：dirty→重算 / 未 dirty→命中缓存（generated_at 不变）/ 写操作触发 bump（route 注入假 service）/ 空工作区占位内容。
+
+---
+
+## C. 召回重排：proof_count × recency 半衰期
+
+### 问题与现状核实
+- 现行 `util.js bm25Rank` **已含** recency 半衰期因子 `1 + 0.5·exp(-ageDays/14)`（14 天、最多 +50%，
+  不覆盖强词法相关），也有 tag-exact/fuzzy/phrase/BM25 权重——真正缺失的是**证据强度信号**：
+  同样词频的记忆，被证明过 N 次的（hits）没有被排序优待。
+- D2 失败复活已在 error 记忆重复时递增 `hits`；它就是现成的 proof 计数。
+
+### 实现（已落地：`lib/rerank.js` + `util.js bm25Rank` 接线）
+```
+score_final = score_lexical                     // BM25 + tag/phrase boost（既有）
+            × (1 + 0.5·exp(-ageDays/14))        // recency 半衰期（既有）
+            × evidenceBoost(hits)               // 新增：1 + 0.1·min(max(0,hits), 5)，饱和 ±5%
+```
+- `evidenceBoost(hits, {alpha=0.1, cap=5})`：0→1.0、5→1.5（封顶），保守不喧宾夺主（借鉴 reranking.py 的 proof alpha）。
+- `scoreCandidate(matchScore, hits)`、`sortByEvidence(list, opts)`（稳定、可注入 tiebreak）。
+- 接入点：`bm25Rank` 词法分后乘 `evidenceBoost(r.hits ?? 0)`——encerence recall/searchMemories 全走这里，零额外改动。
+- 「失败复活」天然增强：高 hits 的失败记忆在同词频下与新鲜记忆竞争更接近。
+
+### 测试
+`test/rerank.test.mjs`：三种 matchKind 基准 / 半衰期形状（t=0, halflife, 2*halflife 分别为 1, 0.5, 0.25）/ proof cap / 稳定排序（同分保序）/ 未来时间戳钳制。
+
+---
+
+## 分阶段计划（每阶段：代码 + 测试 + client-hmr 即时 / host 待重启 + 中文总结）
+
+| 阶段 | 内容 | 交付物 | 生效 |
+|---|---|---|---|
+| C | rerank 纯函数 + 接入 esr_recall | `lib/rerank.js` + `test/rerank.test.mjs` | 等自然重启 |
+| A | observations 表 + concentrate/trend + recall 注入 + board 观测条 | `lib/obs.js` + `lib/store.js` 钩子 + `test/obs.test.mjs` + board | host 待重启；board 即时 |
+| B | mental 缓存 + esr_model 工具 + /model 端点 + board 常驻条 | `lib/mental.js` + `test/mental.test.mjs` + board | host 待重启；board 即时 |
+
+每阶段与既有实现正交：不动 dock 交互（除可选 KPI 一列）、不动证据门、不动 esr_close 语义。
+
+## 明确不做（保留约束）
+- 不做 LLM 抽取/浓缩（Hindsight retain 管线）——成本与我们的形态不匹配。
+- 不做向量/图库/交叉编码器重排。
+- 不做 mental model 的「用户定义问题」自由文本——用固定模板，纯聚合。
+- observations 的「来源逐 quote 引用」简化为 sources 列表（证据门已足够）。
+
+## 风险
+- 浓缩误并（Jaccard 阈值误命中）→ 反证机制 + GC 可兜；阈值可配。
+- observation 桶增长失控 → 每 ws 上限（默认 50 条），超出按 proof 降序逐出（保留计数进 audit），归入 esr_gc。
+- mental 缓存脏标记漏置 → `bumpDirty` 挂全量写钩子 + 过期兜底（10min 强制重算）。