dsh-engram 0.7.4 → 0.8.6

package/README.md

@@ -264,8 +264,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 <!-- dsh-market compatibility block — keep labels bilingual and in sync with
      docs/RELEASE-NOTES.TEMPLATE.md (market README convention) -->
 
-- **DSH 版本 / DSH versions**: `>=0.1.2-alpha.2 <0.3.0-0` (本版 `0.7.2`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
-- **最后验证日期 / Last verified**: 2026-10-20 — DSH `0.2.0` live composition (`dsh-context` + `dshmarket` + `dsh-engram`) arms L1 boundary prune; npm test 406/406
+- **DSH 版本 / DSH versions**: `>=0.1.2-alpha.2 <0.3.0-0` (本版 `0.8.6`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
+- **最后验证日期 / Last verified**: 2026-10-27 — DSH `0.2.1-rc.2` (`dsh --version`), web profile live composition; npm test 483/483
 - **安装方式已验证 / Verified install**: `dsh plugin --profile web add dsh-engram`
 
 > **Short version.** Every **published** release (`0.2.0` … `0.3.6`) supports
@@ -284,7 +284,16 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.6.0` | published | 同 `0.5.0` — Context Ledger、BoundaryPrune/ResultPack 默认开 + 账本否决、JIT 推送、Context GC 改 opt-in | 同 `0.5.0` |
 | `0.7.0` | published | 同 `0.5.0` — session episode、resume brief、entity pages/cards、revalidatable anchors + layered TTL | 同 `0.5.0` |
 | `0.7.1` (npm) | published | 同 `0.5.0` — web-plane Context GC on DSH `0.2.0` declarative presets (14-space rows), bundle patch re-enables the host `tool-result-pruner`, compaction savings feed the Context Ledger | 同 `0.5.0` |
-| `0.7.2` (本期 / this release) | prepared | 同 `0.5.0` — L1 boundary prune arms through `ctx.inject`, fixing the boot-ordering race where a pruner activating one tick after the plugin stayed dormant for the whole process | 同 `0.5.0` |
+| `0.7.2` (npm) | published | 同 `0.5.0` — L1 boundary prune arms through `ctx.inject`, fixing the boot-ordering race where a pruner activating one tick after the plugin stayed dormant for the whole process | 同 `0.5.0` |
+| `0.7.3` | 未发布 | 设置卡迁到「Engram 记忆 → 设置」tab（DSH `0.2.1` 删了旧 section）——随 `0.7.4` 一起发布 | 同 `0.5.0` |
+| `0.7.4` (npm) | published | 同 `0.5.0` — 修「推送腿」在 DSH `0.2.x` 上整条静默失效（`[RECALL]` 启动召回、JIT 推送） | 同 `0.5.0` |
+| `0.7.5`–`0.7.9` | 本地 | 同 `0.5.0` — 账本按会话落行 + `gate-audit`；L1 三个真机 bug：还款闸门工作区键（`Users-x-proj` vs `/Users/x/proj`）、`session.append` 重入、归因不对称；L1 从「自己剪」转成「记账 + 归因」 | 同 `0.5.0` |
+| `0.7.10`–`0.7.12` | 本地 | 同 `0.5.0` — 归因对称（宿主剪枝不进我们的 rewrite 账）、`boundaryPrune` 默认关闭改 opt-in、`status` 打印「账本两条腿」让开关判断可复核 | 同 `0.5.0` |
+| `0.7.13` | 本地 | 同 `0.5.0` — 压缩入账读真实事件形状（`event.data`，此前 82 个 GC checkpoint 全部未入账 + 29.6M 字符）、会话计数重启不再清零（delta 累加）、CLI 尊重 `DSH_HOME` | 同 `0.5.0` |
+| `0.8.0`–`0.8.2` | 本地 | 同 `0.5.0` — 证据化 procedure（v0.8-A）、导出为 DSH Skill（v0.8-B）、subagent 交接胶囊（v0.8-C） | 同 `0.5.0` |
+| `0.8.3`–`0.8.4` | 本地 | 同 `0.5.0` — 审批门（v0.8-D）+ 其 GUI；G6 门槛改单边（Δ ≥ −2pp）+ 隐藏规格语料 | 同 `0.5.0` |
+| `0.8.5` | 本地 | 同 `0.5.0` — 记忆行文件信号（`⚠file-changed` / `⚠file-missing`），G6 第三/四轮（撤回 +30pp，Δ=+58.3pp） | 同 `0.5.0` |
+| `0.8.6` (本期 / this release) | 本地 | 同 `0.5.0` — 修 issue #9：宿主没有 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
 
 ### Where the API family broke — `0.1.2-alpha.2`
 
@@ -846,7 +855,7 @@ means that preset was customized (or has no compaction group) and was left untou
 `dsh-compaction-basic unavailable` means the backend is missing and everything
 falls back to the default compressor.
 
-### BoundaryPrune (subtask-boundary pruning, default ON + ledger veto)
+### BoundaryPrune (subtask-boundary pruning, opt-in since v0.7.11 + ledger veto)
 
 Context GC owns *what a compaction summary says*; BoundaryPrune owns *when a
 deterministic prune fires*: at todo-completion progress and goal terminal
@@ -869,6 +878,11 @@ later request. The two switches are independent.
   simply never trigger (no boundary → no prune, zero side effects); the
   corpus-wide dry run activates on 38% of sessions. If the pruner service is
   absent the mechanism disables itself with one log line.
+- **Live read (2026-10-26, two days of real use)**: the Context Ledger recorded
+  the host pruning 64,200 chars on its own across two sessions (4 prunes in a
+  220-request session that never wrote a completed todo), while engram's own
+  leg produced 7,841 chars from a single boundary prune. The chain itself works
+  (v0.7.7–v0.7.9 fixed gate/execution/accounting); the *coverage* does not.
 - **Boundary sources**: todo-progress completion and goal terminal events
   (default), plus an optional **request-count cadence**
   (`boundaryPruneIdleCadence`, default 0/off) — the "step idle" source that
@@ -881,7 +895,11 @@ later request. The two switches are independent.
   T2048+small-edges lands 2.4× the first-prune savings of the host default on
   the real corpus (10.14M vs 4.23M chars). Lowering the threshold is safe with
   `resultPack` on, which archives the removed middles.
-- Default **on**: `boundaryPrune: true` (`false` is the opt-out). Adaptive gate
+- Default **off since v0.7.11**: `boundaryPrune: true` is the opt-in. Fifteen
+  hours of live ledger proved the host prunes over-threshold results on its own
+  (64,200 chars across two sessions, zero engram involvement) and that the
+  boundary source never fires in an ordinary 220-request session — only planning
+  sessions that use todos/goals get anything out of it. Adaptive gate
   `boundaryPruneAdaptive: true` lets the Context Ledger stop further fires once
   this workspace's own accounting is net negative (≥3 fires) — evidence can only
   turn pruning off. The log shows
@@ -1006,6 +1024,18 @@ and silence when there is nothing relevant to point at:
 - Settings: `episodeEnabled`, `resumeBriefEnabled` (both default on), plus
   `episodeMaxPerWorkspace` / `resumeBriefMaxAgeDays` / `resumeBriefMaxChars`.
 
+> **Host requirement (silent-dormancy warning).** Episode, resume brief, `[RECALL]`
+> and the session-end todo sink all read the session's event log. On ≥0.2.x hosts
+> the log arrives through `ctx.sessionQuery.live()`, `session.snapshotEvents()` or,
+> as a last resort, `session.seq` + `session.eventAt(seq)`. A host that exposes
+> **none** of these keeps the three features dormant: memory storage, `engram_recall`
+> and `engram_detail` still work, but nothing is injected at session start and no
+> episode is written. The plugin logs one `engram: this host exposes no readable
+> session event log … Session surface: …` warning per session naming what the
+> session object does offer — that line is the thing to paste into a bug report.
+> Known case: the **desktop runtime** (`@deepseek-ai/dsh-desktop-runtime`) on
+> Windows, tracked as issue #9.
+
 ### Entity pages + entity cards (v0.7-B)
 
 `esr_node` grows from a dot on the graph into a readable **page**: current
@@ -1065,7 +1095,61 @@ Explicit `engram_store` writes are always recorded regardless of these rules
 
 **Who earns a `[ENGRAM]` index line** (this is what actually touches the prompt):
 `signal >= minIndexSignal` **or** `hits >= promoteHits` **or** `kind === "task"`,
-then capped by `indexMaxLines` / `indexMaxChars`. One extra guard keeps the pipe
+then capped by `indexMaxLines` / `indexMaxChars`.
+
+**Procedures are evidence-gated (v0.8-A).** An auto-captured `fixed: <cmd>` row is
+a hypothesis, not a lesson: it starts with `evidenceCount = 1` and stays out of
+the index until the same command is verified **3** times with the last
+verification younger than **14 days** (`procedureMinEvidence` /
+`procedureMaxAgeDays`). The moment that command fails again the row is
+invalidated (`invalidatedBy` = the failing memory's id, signal → 0.2) and leaves
+the index immediately — a just-broken procedure is worse than none, because the
+next agent would copy it verbatim. Hand-written procedures with no evidence
+fields keep the older `hits >= promoteHits` path.
+
+**Promoted procedures can become real Skills (v0.8-B).** An index line is a
+hint; a DSH Skill is an artifact the host discovers, advertises in the session
+catalog, and any agent (or subagent) can load in full:
+
+```bash
+npx dsh-engram skill export            # → <workspace>/.dsh/skills/<name>/SKILL.md
+npx dsh-engram skill export --dry-run  # show the plan, touch nothing
+```
+
+Only procedures that pass the evidence gate are exported (`≥3` verified
+successes, verified within 14 days, not invalidated). Each file carries a
+`generated-by` marker: the exporter rewrites and eventually **deletes** only its
+own files, so a hand-written skill sharing the root is never touched. When a
+procedure stops holding, its skill file disappears on the next export — the host
+catalog must not keep advertising a fix that just broke. `npm run skill:check`
+proves the seam end-to-end by loading DSH's own `dsh-skill-filesystem` provider
+and listing the exported skill through it.
+
+**The approval queue is in the GUI too (v0.8.4).** The memory tab shows
+"Playbook 待批准" with evidence counts and approve/revoke buttons, backed by
+`GET|POST /api/dsh-engram/approvals`. The route recomputes the list with the same
+planner `skill export` uses, so a click can never approve something the CLI would
+skip; revoking returns a row to pending rather than deleting its evidence.
+
+**Writing a skill needs a human yes (v0.8-D).** Evidence (`≥3` verified
+successes) gets a procedure into the private index line; it does not, on its own,
+put a file where the host advertises it to every agent. `skill export` therefore
+writes only **approved** procedures — `skill pending` lists what is waiting,
+`skill approve <id>` / `skill revoke <id>` maintain the record in
+`~/.dsh/engram/playbook-approvals.json` (kept out of the memory store: an approval
+is a human act, and a pool must not approve itself), and `--force` is the audited
+escape hatch. Three successful runs prove a command worked; they do not prove the
+instruction is sound.
+
+**Subagent reports become durable capsules (v0.8-C, advisory).** A child's final
+report above `capsuleMinSourceChars` (1500) is distilled by structure — headings,
+bullets, question marks, next-step cues — into a `handoff` memory (结论 / 证据 /
+未决 / 下一步) whose footer records `source → capsule` chars. It does **not** shrink
+what the parent reads: DSH emits `tools/result` to observers only ("without
+exposing a mutation or error channel into the outcome"), so substitution needs a
+host seam that does not exist yet. What you get today is durability — the
+conclusion survives the child session and compaction — plus a real measurement of
+the saving for the day that seam lands. One extra guard keeps the pipe
 clean: auto-captured git command echoes — text that embeds a shell chain
 (`git push: cd … && …`) — stay out of the index even when above the signal
 threshold, until recall hits have promoted them. Everything else sits quietly in
@@ -1150,6 +1234,9 @@ Defaults are token-conscious; override any key via the profile patch
                              # (git command echoes are excluded regardless,
                              # until promoted by recall hits)
     promoteHits: 3           # ...until recalled this many times
+    procedureMinEvidence: 3  # verified successes before a `fixed:` procedure
+                             # earns an index line (one success proves nothing)
+    procedureMaxAgeDays: 14  # ...and the last verification must be this fresh
     expireDays: 180          # memory TTL (0 = never)
     maxMemoriesPerWorkspace: 2000
     gcEnabled: true          # scheduled memory GC

package/README.zh.md

@@ -167,7 +167,7 @@ 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.7.2`；已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` —— 见下文矩阵）
-- **最后验证日期**：2026-10-20 —— DSH `0.2.0` 实机组合（`dsh-context` + `dshmarket` + `dsh-engram`）验证 L1 边界剪枝武装；npm test 406/406 通过
+- **最后验证日期**：2026-10-27 —— DSH `0.2.1-rc.2`（`dsh --version`）+ web profile 实机组合；npm test 483/483 通过
 - **安装方式已验证**：`dsh plugin --profile web add dsh-engram`
 
 > **一句话结论**：所有**已真正发布**的版本（`0.2.0` … `0.3.6`）**只支持旧版
@@ -184,7 +184,11 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.6.0` | 已发布 | 同 `0.5.0` —— Context Ledger、BoundaryPrune/ResultPack 默认开 + 账本否决、JIT 推送、Context GC 改 opt-in | 同 `0.5.0` |
 | `0.7.0` | 已发布 | 同 `0.5.0` —— 会话 episode、恢复简报、实体页/实体卡、可重验证锚点 + 分层 TTL | 同 `0.5.0` |
 | `0.7.1`（npm） | 已发布 | 同 `0.5.0` —— web 平面 Context GC 适配 DSH `0.2.0` 声明式预设（14 空格缩进）、bundle patch 重新启用 host 平面 `tool-result-pruner`、压缩节省接入 Context Ledger | 同 `0.5.0` |
-| `0.7.2`（本期 / this release） | 待发布 | 同 `0.5.0` —— L1 边界剪枝改经 `ctx.inject` 武装，修掉「pruner 行比插件晚激活一帧就永久休眠」的启动时序竞态 | 同 `0.5.0` |
+| `0.7.2` | 已发布 | 同 `0.5.0` —— L1 边界剪枝改经 `ctx.inject` 武装，修掉「pruner 行比插件晚激活一帧就永久休眠」的启动时序竞态 | 同 `0.5.0` |
+| `0.7.3`–`0.7.4`（npm `latest`） | 已发布 | 同 `0.5.0` —— 设置卡迁到「Engram 记忆 → 设置」tab（DSH `0.2.1` 删了旧 section）；修 DSH `0.2.x` 上「推送腿」整条静默失效（`[RECALL]` 启动召回、JIT 推送） | 同 `0.5.0` |
+| `0.7.5`–`0.7.13` | 本地 | 同 `0.5.0` —— 账本按会话落行 + `gate-audit`；L1 从「自己剪」转成「记账 + 归因」；压缩入账读真实事件形状；会话计数重启不清零；CLI 尊重 `DSH_HOME` | 同 `0.5.0` |
+| `0.8.0`–`0.8.5` | 本地 | 同 `0.5.0` —— 证据化 procedure、导出 DSH Skill、subagent 交接胶囊、审批门 + GUI、记忆行文件信号（`⚠file-changed`/`⚠file-missing`）、G6 门改单边 + 隐藏规格语料（Δ=+58.3pp） | 同 `0.5.0` |
+| `0.8.6`（本期 / this release） | 本地 | 同 `0.5.0` —— 修 issue #9：宿主不暴露 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
 
 ### API 族断裂点:`0.1.2-alpha.2`
 

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

@@ -195,7 +195,11 @@ Fetch the exact records that are still in the store:
 | 日志 `dsh-compaction-basic unavailable` | 环境缺后端依赖 | 安装依赖；自动回退默认压缩，host 不崩 |
 | 极小被驱逐片段（span 小于 checkpoint 开销）不压缩 | harness 收缩闸门对**任何**后端一视同仁 | 属正常，没必要为几十 token 起 checkpoint |
 | 改配置后没变化 | web 行要重启才刷新 | 重启 dsh web |
-| 遥测「节省 · 剪枝/压缩」一直是 0、净 token 恒负 | 两条入账腿都没触发：L1 拿不到 host 平面的 `toolResultPruner`（0.2.0 的 host 行被禁），压缩节省此前进不了账本 | 确认状态快照 `boundaryPrune.armed: true`（`npx dsh-engram status` 会打印）；压缩在 0.7.1+ 按 `区间字符数 − checkpoint 字符数` 入账 |
+| 遥测「节省 · 剪枝/压缩」一直是 0、净 token 恒负 | 两条入账腿都没触发：L1 拿不到 host 平面的 `toolResultPruner`（0.2.0 的 host 行被禁），压缩节省此前进不了账本 | 确认状态快照 `boundaryPrune.armed: true`（`npx dsh-engram status` 会打印）；压缩自 0.7.5 起按**已提交的** `compaction/summary` 入账（`shadowedTokenCount×4 − 摘要字符数`） |
+| `boundaryPrune.armed: true` 但 `activation.boundaryPrune: null`、剪枝节省恒 0 | **工作区键不一致**：历史表键是 `Users-x-proj`（桶名），查询键是 `/Users/x/proj`（header.cwd）→ 历史永远 miss → 还款闸门恒跳过。0.7.7 起两侧归一见 `normalizeWorkspaceKey` | 看 `~/.dsh/engram/boundary-attempts.jsonl`：`kind: skipped` 且 `expectedTotal` 恰等于 50 就是它；修好后 `expectedTotal` 应变成 120（有历史的工作区） |
+| 日志里有 `kind: fired` 但 `pruned: 0`，放个大结果再做边界就**一行都没有** | 剪枝在 `session/event` 的 publish 窗口里调 `session.append`，host 的重入检查直接抛错，被监听器的防崩兜底吞掉。0.7.8 起 `queueMicrotask` 把 fire 挪出窗口，抛错也落盘成 `kind: error` | 看 `boundary-attempts.jsonl` 有没有 `kind: error`；没有 error 且 `pruned > 0` 才算真剪到 |
+| `fired` 但 `pruned: 0`，而会话里有 `compaction/prune` 事件**没有**对应 todo 边界 | 宿主自己在步与步之间剪超阈值结果（0.2.x 行为）。L1 到达边界时候选已被剪过 → 没得剪 | 0.7.9 起这些剪枝记在账本 `hostPrunedChars` 腿（可见、不认领）。若该腿很大而 engram 腿恒 0，说明 L1 的「再剪一遍」在宿主版本上已无价值，该考虑退场或只留阈值覆盖 || 状态文件说 `host: unavailable` / `web: disabled`，但 `/overview` 说 `host: context-gc` | 同一进程里两个插件实例（一个拿到 profile 配置、一个拿到出厂默认）抢写同一个状态文件，后写的把好的覆盖了 | 0.7.5+ 同 pid 内不允许降级覆盖；以 `/overview` 与 `npx dsh-engram gate-audit --api` 为准 |
+| 老会话还在用默认 LLM 摘要（checkpoint 没有 GC 页眉） | 该会话的 agent realm 是在插件接管**之前**组合出来的，realm 里没有 `dsh-engram/compaction` 行；新开会话才拿到 | 新开一次会话即可；已存在的 realm 不会热换 provider |
 | L1 状态报 `no toolResultPruner service …` 但 `--dump-config` 里行是启用的 | 行存在却被**运行时**关掉（如 `- id: tool-result-pruner, disabled: true` 的 profile override） | 删掉该 override；bundle patch 只负责重新启用出厂行 |
 | L1 状态报 `registered but its fiber is not active yet` | 启动时序：剪枝器 fiber 比插件晚激活（v0.7.2 前会因此永久休眠） | 升到 0.7.2+（改经 `ctx.inject` 武装），然后重启 |
 
@@ -209,6 +213,10 @@ Fetch the exact records that are still in the store:
 - **injected**：`[ENGRAM]`/`[RECALL]`/`[JIT]`/`[ESR]` 块每请求重计的注入成本；
 - **avoided**：**已入账**的节省，只有两条腿——L1 边界剪枝（`toolResultPruner` 剪掉的
   chars × 后续请求数）与压缩（每次 checkpoint 的「被替换区间字符数 − checkpoint 字符数」× 后续请求数）；
+- **压缩节省按「已提交」记账**（0.7.5+）：账本不认引擎在 `summarize()` 里算出的数字，只认会话里
+  真正落地的 `compaction/summary` 事件——且摘要必须带 Context GC 页眉/尾注（证明是本插件写的）。
+  被宿主拒绝、回滚、或退了默认摘要器的压缩，**一律不入账**。这条是踩过的坑：早期版本按引擎
+  自报记账，结果把一次没落地的 checkpoint 也记了 29 万字符；
 - **rewrite penalty**：L1 剪枝会击穿 KV 前缀缓存，按 `1 − 缓存折价` 一次性计价；
   压缩**不额外计**罚金（压缩是宿主自己的动作，默认后端同样会改写前缀，计了会重复）。
 
@@ -216,6 +224,12 @@ Fetch the exact records that are still in the store:
 只代表这一段时间只花了钱没省到。状态快照的 `boundaryPrune.armed` 告诉你 L1 是否真的
 武装；压缩入账要等第一次 checkpoint。
 
+**L1 自 0.7.11 起默认关闭**（`boundaryPrune: false`，需要时手动打开）。打开前先跑
+`npx dsh-engram status`，看顶部那行「账本两条腿」——宿主腿远超 engram 腿时，打开只是重复劳动。
+依据是两天的真机账本：
+宿主自己剪了 64,200 字符，而 engram 的边界剪枝在一个 220 请求、没有 todo 进度的会话里一次都没
+触发——只有规划型会话（真的在用 todo/goal）才吃得到这份收益。
+
 ## 10. FAQ
 
 - **有损吗？** 锚定细节**无损**（全部可通过工具重取）；只有无锚轮次走叙事/截断；所有原文仍留在