dsh-engram 0.7.0 → 0.7.1

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.0`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
-- **最后验证日期 / Last verified**: 2026-10-19 — episode / entity pages / anchor revalidation，npm test 381/381 通过
+- **DSH 版本 / DSH versions**: `>=0.1.2-alpha.2 <0.3.0-0` (本版 `0.7.1`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
+- **最后验证日期 / Last verified**: 2026-10-19 — web-plane Context GC 适配 DSH `0.2.0` 声明式预设（`dsh-web-app/presets/*.patch.yml`），npm test 396/396 通过
 - **安装方式已验证 / Verified install**: `dsh plugin --profile web add dsh-engram`
 
 > **Short version.** Every **published** release (`0.2.0` … `0.3.6`) supports
@@ -282,7 +282,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.5.0` (npm) | published | **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` | published | 同 `0.5.0` — 会话扫描修复（`session.v<N>.jsonl.zstd`，issue #8）、数据导出/导入 GUI、替换/冲突可视化（issue #3） | 同 `0.5.0` |
 | `0.6.0` | published | 同 `0.5.0` — Context Ledger、BoundaryPrune/ResultPack 默认开 + 账本否决、JIT 推送、Context GC 改 opt-in | 同 `0.5.0` |
-| `0.7.0` (本期 / this release) | published | 同 `0.5.0` — session episode、resume brief、entity pages/cards、revalidatable anchors + layered TTL | 同 `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` (本期 / this release) | prepared | 同 `0.5.0` — web 平面 Context GC 适配 DSH `0.2.0` 声明式预设（`dsh-web-app/presets/*.patch.yml`，14 空格缩进），状态/doctor CLI 同步 | 同 `0.5.0` |
 
 ### Where the API family broke — `0.1.2-alpha.2`
 
@@ -332,7 +333,37 @@ drives mutations).
 So: keep DSH on `0.1.1-rc.2` or older while running a release ≤ `0.3.6`, and
 upgrade the plugin to `>=0.3.7` before moving DSH to `0.1.2-alpha.2`.
 
-### Current release — `0.7.0`
+### Current release — `0.7.1`
+
+Web-plane Context GC on DSH `0.2.0`'s **declarative presets** — the preset
+format changed shape (one `@deepseek-ai/dsh-agent-preset` declaration inside
+`dsh-web-app/presets/*.patch.yml`), and the auto-wiring was anchored to the old
+`agent.cordis.yml` layout, so `autoWebCompaction` silently skipped every preset
+(and could half-rewrite a stock row: the pattern did not include its trailing
+newline).
+
+- **Structural row location** — the `compaction` group is found by YAML
+  structure (a list item carrying `group: true`), not by column position; the
+  stock/engram rows are validated by BOTH their `- id:` and `name:` values, and
+  the replacement inherits the row's own indent. Legacy `agent.cordis.yml`
+  (4 spaces) and declarative patch files (14/16/18 spaces) both round-trip
+  byte-identically.
+- **Declarative discovery** — the preset roster no longer carries `path` on
+  DSH `0.2.0`; the plugin maps each roster id to the shipped
+  `<presetsDir>/<id>.patch.yml` (resolved through the `dsh` install, with
+  `DSH_WEB_PRESETS_DIR` override) and skips user-defined declarative presets
+  (profile-patch overrides) with an explicit log line instead of failing.
+- **Status/doctor** — `npx dsh-engram status`/`doctor` discover both preset
+  generations, show the detected layout, and flag `autoWebCompaction=false`
+  (the opt-in toggle that makes the web plane a no-op), node_modules preset
+  wiring (survives `npm update dsh` only while auto-wiring stays on), and
+  profile-patch `preset-*` overrides that outrank the shipped files.
+- **Migration** — restart `dsh web` with `autoWebCompaction:true`: the next boot
+  re-wires every stock declarative preset (idempotent refresh; existing
+  hand-wired rows are rewritten to the requested engine config). `npm test`
+  396/396.
+
+### Previous release — `0.7.0`
 
 From event records to **maintainable current truth**: sessions sediment an
 episode at teardown, new sessions get a resume brief, `esr_node` becomes a
@@ -378,7 +409,7 @@ namespace via `settings.installSection`; on `≥0.1.7` / `0.2.x` the form is the
 plugin's `Config` with the 34 GUI knobs marked `.volatile()` (entry id
 `engram`). The browser settings card reads and writes through the plugin's own
 HTTP route (`/api/dsh-engram/settings`, see Route B above) on both. The full
-regression suite (npm test 329/329, incl. the new settings-v2 coverage for the
+regression suite (npm test 396/396, incl. the new settings-v2 coverage for the
 volatile-Config model) passes against the DSH `0.2.0-rc.2` dependency set
 (cordis 4.0.4 + schemastery 3.18.4 + cosmokit, matching the global DSH CLI).
 The `.volatile()`/loader hot-commit path and the describe-side projection were
@@ -678,10 +709,15 @@ default):
   builds its `Include.Config` with no patches; verified against the harness
   source). So on boot, once the `agentPresets` service is ready, the plugin
   **auto-edits every preset that still has the stock layout** — the default
-  preset plus the whole roster (shipped root + `~/.dsh/.agent-presets` user
-  root: `standard`, `code`, `cordis`, and your own presets): it swaps the
-  `compaction-basic` row inside the `compaction` group for
-  `dsh-engram/compaction`. That auto-wiring is:
+  preset plus the whole roster, across BOTH preset generations: legacy
+  `<root>/<id>/agent.cordis.yml` compositions (DSH ≤ 0.1.x, row at 4 spaces)
+  and the declarative `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml` files
+  (DSH ≥ 0.2.0, row at 14 spaces inside the `@deepseek-ai/dsh-agent-preset`
+  declaration; a user-defined declarative preset with no shipped file is left
+  alone). The row is located by YAML structure (a list item carrying
+  `group: true`) and validated by both its `- id:` and `name:` values, so the
+  swap is column-position independent: it swaps the `compaction-basic` row
+  inside the `compaction` group for `dsh-engram/compaction`. That auto-wiring is:
   - **off by default (opt-in)** (`autoWebCompaction: false`, toggle in the
     settings card's memory-GC section); once enabled it is idempotent — an
     already-wired preset is left alone;
@@ -691,8 +727,9 @@ default):
   - **per-preset**: only stock-layout presets are touched — a preset with a
     custom compaction group, or none at all (e.g. the shipped `minimal`
     preset), is never written, only logged;
-  - **backed up + validated**: a create-only `agent.cordis.yml.engram.bak`
-    holds each original next to its file, every result is re-read and verified
+  - **backed up + validated**: a create-only `.engram.bak`
+    (`agent.cordis.yml.engram.bak` or `<id>.patch.yml.engram.bak`) holds each
+    original next to its file, every result is re-read and verified
     after writing, and any doubt rolls that file back; a failure only warns and
     that session keeps DSH's default summarizer — the host plane is never
     affected.
@@ -702,7 +739,9 @@ default):
     changing the settings knobs re-provisions the web rows on the next boot
     instead of being silently ignored.
   - A fully equivalent manual CLI, shipped in the npm package
-    (scans both the shipped and the user root; `--file <path>` targets one):
+    (scans both preset generations — legacy roots, the shipped declarative
+    presets, and the paths recorded at boot; `--presets-dir <dir>` overrides
+    declarative discovery, `--file <path>` targets one):
     ```bash
     npx dsh-engram status     # stock = untouched · wired = active · custom = hands-off
     npx dsh-engram doctor     # status + ranked next steps for every gap found
@@ -872,10 +911,25 @@ adds a "net context tokens" stat card. Durable rollup at
 `~/.dsh/engram/ledger.json` (atomic write, daily buckets, delta flush); the hot
 path is an integer add, zero I/O and zero model calls.
 Defaults: `ledgerEnabled: true`, `ledgerCacheDiscount: 0.1`; off = no listeners,
-no writes. **Honest scope**: tokens are `chars / 4` estimates, not provider
-billing, and no quality delta is claimed; Context GC compaction savings are not
-wired yet (the host does not expose before/after sizes), so the ledger only
-counts what it can prove.
+no writes.
+
+**Two credit legs** (v0.7.1 — before this the ledger only charged costs, so the
+net was structurally negative):
+
+1. **L1 boundary prune** — chars removed by `toolResultPruner`, credited per
+   later request. Requires a host-plane `toolResultPruner`; DSH ≥ 0.2.0 web
+   profiles move that row into each agent preset's isolate realm, so the bundle
+   patch re-enables the host row — check `boundaryPrune.armed` in the status
+   snapshot.
+2. **Compaction (Context GC)** — every checkpoint credits `span chars −
+   checkpoint chars` from the engine that produced it; host plane and the web
+   preset realm (bridged through the `engramLedger` service) write the same
+   ledger.
+
+**Honest scope**: tokens are `chars / 4` estimates, not provider billing, and no
+quality delta is claimed. Until a workspace actually prunes or compacts its
+"saved" leg is 0, so the net equals injected + rewrite penalty (negative is
+expected) — the Telemetry tab says so inline.
 
 ### JIT push (v0.6-C)
 

package/README.zh.md

@@ -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.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 版本**：`>=0.1.2-alpha.2 <0.3.0-0`（本版 `0.7.1`；已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` —— 见下文矩阵）
+- **最后验证日期**：2026-10-19 —— web 平面 Context GC 适配 DSH `0.2.0` 声明式预设（`dsh-web-app/presets/*.patch.yml`），npm test 396/396 通过
 - **安装方式已验证**：`dsh plugin --profile web add dsh-engram`
 
 > **一句话结论**：所有**已真正发布**的版本（`0.2.0` … `0.3.6`）**只支持旧版
@@ -182,7 +182,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `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` | 已发布 | 同 `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` |
+| `0.7.0` | 已发布 | 同 `0.5.0` —— 会话 episode、恢复简报、实体页/实体卡、可重验证锚点 + 分层 TTL | 同 `0.5.0` |
+| `0.7.1`（本期 / this release） | 待发布 | 同 `0.5.0` —— web 平面 Context GC 适配 DSH `0.2.0` 声明式预设（`dsh-web-app/presets/*.patch.yml`，14 空格缩进），status/doctor CLI 同步 | 同 `0.5.0` |
 
 ### API 族断裂点:`0.1.2-alpha.2`
 
@@ -222,7 +223,25 @@ profile 条目 id（`engram`）为命名空间，不再需要任何“挂载”
 所以：跑 ≤ `0.3.6` 的已发布版本时请把 DSH 保持在 `0.1.1-rc.2` 或更旧；升级
 DSH 到 `0.1.2-alpha.2` 之前，先升级插件到 `>=0.3.7`。
 
-### 当前发布版本 —— `0.7.0`
+### 当前发布版本 —— `0.7.1`
+
+修复 **DSH `0.2.0` 声明式预设下的 web 平面 Context GC 接管**：旧版自动装配以
+`agent.cordis.yml` 的 4 空格布局为锚，而 `0.2.0` 把预设换成
+`dsh-web-app/presets/<id>.patch.yml` 里的 `@deepseek-ai/dsh-agent-preset` 声明（行在
+14/16/18 空格缩进），导致 `autoWebCompaction` 静默跳过所有预设。
+
+- **结构化定位 compaction 行**：找 `group: true` 的 `compaction` 组，组内按 `- id:` +
+  `name:` 双重校验定位 stock/engram 行，替换块继承该行自己的缩进；旧版与声明式布局都
+  swap → restore 逐字节还原。顺带修掉旧 stock 替换串不含行尾换行、可能半改写文件的隐患。
+- **声明式预设发现**：roster 不再带 `path` 时把 id 映射到出厂 `<presetsDir>/<id>.patch.yml`
+  （`DSH_WEB_PRESETS_DIR` 可覆盖）；无出厂文件的用户自定义声明式预设跳过并打日志。
+- **status/doctor 适配**：自动发现两种布局并显示布局类型；doctor 新增
+  `autoWebCompaction=false`、node_modules 预设（`npm update dsh` 会恢复出厂布局）、
+  profile patch `preset-*` 覆写（优先于 shipped 文件）三类提示。
+- **迁移**：打开 `autoWebCompaction` 后重启一次 `dsh web`，下一次启动即幂等接管所有
+  stock 声明式预设；`npm test` 396/396。
+
+### 上一发布版本 —— `0.7.0`
 
 把「记忆」从**事件记录**推进到**可维护的当前真相**：会话结束自动沉淀 episode、
 新会话给恢复简报、`esr_node` 升级为实体页、文件锚点让过期真相可被检测。
@@ -256,7 +275,7 @@ Config** 模型（并带特性检测的旧代际回退）。
 走 `settings.installSection` 注册 `dsh-engram` 命名空间；`≥0.1.7` / `0.2.x` 走插件
 `Config`（34 个 GUI 旋钮标记为 `.volatile()`，条目 id `engram`）。浏览器设置卡在两代际
 都经插件自有 HTTP 路由（`/api/dsh-engram/settings`，见上文 Route B）读写。完整回归
-（npm test 329/329，含新增的 volatile-Config 模型 settings-v2 覆盖）在 DSH
+（npm test 396/396，含新增的 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 上完成了**真机启动烟测并
@@ -490,22 +509,27 @@ Context GC 的装配在**两个平面**，但两个开关都是 opt-in（默认
 - **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`。这一自动装配是：
+  （`agentPresets` 服务就绪后）**自动改写每个仍处于出厂 stock 布局的预设**——默认预设 + 整张 roster，
+  两代预设布局都覆盖：旧版 `<root>/<id>/agent.cordis.yml` 组合文件（DSH ≤ 0.1.x，行在 4 空格）与
+  声明式 `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml`（DSH ≥ 0.2.0，行在
+  `@deepseek-ai/dsh-agent-preset` 声明里、14 空格缩进；没有出厂文件的用户自定义声明式预设不碰）：
+  把 `compaction` 组里的 `compaction-basic` 行换成 `dsh-engram/compaction`。行按 YAML 结构定位
+  （带 `group: true` 的列表项）、按 `- id:` 与 `name:` 双重校验，**与缩进列数无关**。这一自动装配是：
   - **默认关（opt-in）**（`autoWebCompaction: false`；设置卡「记忆 GC」可开），开启后幂等——已替换则跳过；
     **关掉的含义**：只是在之后的启动时不再自动接管（headless/TUI/base 的 host 平面不受影响）——
     它**不会**还原之前已接管的预设，要还原用 `npm run web-compaction:revert`；
   - **逐预设判定，只碰 stock 布局**——用户自定义过 compaction 组的预设，以及根本没有 compaction 组的
     预设（如 shipped `minimal`），一律不写、只记日志；
-  - **带备份 + 严格校验**：每个文件写前在旁边留 `agent.cordis.yml.engram.bak`（create-only，保留首次
-    原件），写后重读校验，任何一步可疑即回滚该文件；改写失败只 warn，该会话仍用 DSH 默认摘要，
+  - **带备份 + 严格校验**：每个文件写前在旁边留 `.engram.bak`（create-only，保留首次
+    原件；旧版布局为 `agent.cordis.yml.engram.bak`，声明式布局为 `<id>.patch.yml.engram.bak`），
+    写后重读校验，任何一步可疑即回滚该文件；改写失败只 warn，该会话仍用 DSH 默认摘要，
     **永不影响宿主**。
   - **配置真实传导**：写进预设行的引擎配置来自设置卡/配置里的 `gcReplacesCompaction` 与
     `gcNarrative`——改了这两个开关，下次启动会自动把已接管的行刷新成新配置（幂等重写），
     所以**设置卡对 web 平面同样生效**，不再硬编码 true/true。
-  - 手动的完全等价物（预览 / 审计 / 卸载前回归，随 npm 包发布的 CLI，默认扫 shipped + 用户两个根、
-    可 `--file` 指定单个）：
+  - 手动的完全等价物（预览 / 审计 / 卸载前回归，随 npm 包发布的 CLI，自动发现两代预设布局——
+    旧版根、出厂声明式预设与上次启动记录的路径；`--presets-dir <dir>` 覆盖声明式目录探测、
+    `--file` 指定单个）：
     ```bash
     npx dsh-engram status     # stock → 未动；wired → 已接管；custom → 不碰
     npx dsh-engram doctor     # status + 按缺口排序的下一步建议
@@ -639,9 +663,20 @@ overview）现在返回 `activation: { boundaryPrune, recall }`：
 GUI「遥测」页签直接画这块账本（净 token 大数字 + 节省/注入/重写罚金三卡 + 近 14 天红绿柱），
 记忆概览页也多一张「上下文净 token」卡。落盘在 `~/.dsh/engram/ledger.json`（原子写、按天滚动、
 delta 落盘），进程内只做整数累加，热路径零 I/O、零模型调用。默认 `ledgerEnabled: true`、
-`ledgerCacheDiscount: 0.1`；关掉 = 不挂监听、不写文件。**口径诚实**：token 按
-`chars / 4` 估算，不含 provider 实际计费与模型质量差；Context GC 的压缩节省暂未
-接入（宿主未暴露前后大小），因此账本只记「可证明」的部分。
+`ledgerCacheDiscount: 0.1`；关掉 = 不挂监听、不写文件。
+
+**节省的两条入账腿**（v0.7.1 补齐，此前只记成本所以净值恒负）：
+
+1. **L1 边界剪枝**——`toolResultPruner` 剪掉的 chars，按后续请求数计入（需要有 host
+   平面的 `toolResultPruner`；DSH ≥ 0.2.0 的 web profile 把该行移进 agent preset 的
+   isolate realm，本 bundle 的 `cordis.patch.yml` 会重新启用 host 行，状态快照里
+   `boundaryPrune.armed` 可核对）；
+2. **压缩（Context GC）**——每次 checkpoint 用「被替换区间可见字符数 − checkpoint 字符数」
+   入账，host 平面与 web 预设域（经 `engramLedger` 服务桥接）走同一个账本。
+
+**口径诚实**：token 按 `chars / 4` 估算，不含 provider 实际计费与模型质量差；
+某工作区还没发生过剪枝/压缩时「节省」就是 0，净值等于注入成本 + 重写罚金（负值正常），
+遥测页会直接提示这一点。
 
 ### JIT 推送（v0.6-C）
 

package/cordis.patch.yml

@@ -1,6 +1,6 @@
 # dsh-engram bundle patch: inserts the host plugin row into the web profile
 # roster. Activate with:
-#   dsh plugin --profile web add file:/d1/chuxiong/code/dsh-engram
+#   dsh plugin --profile web add file:/Users/sunchuxiong/dsh-loom
 #
 # The row is a bare host-half plugin by package name. It does not need to
 # enable storage-domain / storage-json / session-query-sqlite — the standard
@@ -15,14 +15,27 @@
 # NOTE: with `gcReplacesCompaction:false`, dsh-engram still mounts a plain
 # BasicCompactionEngine, so compaction never goes away while it is installed.
 # The host-plane provider is mounted by `lib/index.js` (`mountCompactionEngine`);
-# the WEB plane is auto-wired at boot (`autoWebCompaction`, default on): the
-# plugin swaps the `compaction-basic` row for `dsh-engram/compaction` in every
-# stock-layout preset — default + full roster (shipped + user roots; idempotent,
-# backed up, never touches a custom or no-compaction preset; manual CLI
+# the WEB plane is auto-wired at boot when `autoWebCompaction` is on (opt-in
+# since v0.6, default off): the plugin swaps the `compaction-basic` row for
+# `dsh-engram/compaction` in every stock-layout preset — default + full roster
+# (shipped `agent.cordis.yml` roots and DSH ≥ 0.2.0 declarative
+# `dsh-web-app/presets/*.patch.yml`; idempotent, backed up, never touches a
+# custom or no-compaction preset; manual CLI
 # `npm run web-compaction:status|enable|revert`).
 - id: compaction-basic
   disabled: true
 
+# BoundaryPrune (ResultPack L1) needs DSH's `toolResultPruner` service on the
+# HOST plane. DSH ≥ 0.2.0 web profiles move compaction + the pruner into each
+# agent preset's isolate realm and disable the host-plane `tool-result-pruner`
+# row, so the host plugin's L1 found no service and silently went dormant (the
+# Context Ledger then never credited pruning savings). Re-arm the host row here
+# — the preset realm keeps its own copy for compaction-time pruning, so both
+# paths coexist. Without this, `boundaryPrune` only works on headless/TUI/base
+# profiles. Verify via the status snapshot's `boundaryPrune.armed`.
+- id: tool-result-pruner
+  disabled: false
+
 - insert:
     - id: engram
       name: dsh-engram

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

@@ -32,6 +32,13 @@ dsh-engram 的 Context GC 把这一步换成：
 | host 平面 | headless / TUI / base 型 profile | 打开 `gcReplacesCompaction` 后，插件启动时注册 ContextGcEngine；否则挂裸 `BasicCompactionEngine`（宿主摘要） |
 | web 平面 | dsh web 的 agent preset（shipped + 用户预设） | 打开 `autoWebCompaction` 后，启动时把 stock 预设的 `compaction-basic` 行换成 `dsh-engram/compaction` 行 |
 
+web 平面在两种 DSH 预设布局上都生效（插件按 `compaction` 组的结构定位行，不依赖缩进）：
+
+- **DSH ≤ 0.1.x：旧版组合文件** `<root>/<id>/agent.cordis.yml`（行在 4 空格缩进）；
+- **DSH ≥ 0.2.0：声明式出厂预设** `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml`
+  （行在 14/16/18 空格缩进，文件里是 `- insert:` 声明的 `@deepseek-ai/dsh-agent-preset`）。
+  用户自定义的声明式预设（存在 profile patch 里、没有出厂文件）不会被改写。
+
 ---
 
 ## 2. 前提
@@ -57,7 +64,9 @@ cd /path/to/dsh-loom && npm link            # 或 profile package.json 加 "dsh-
 # ③ 启动一次 dsh web —— 这一步做「自动装配」
 #    - host 平面：按 gcReplacesCompaction 注册 Context GC 为 compaction 服务
 #    - web 平面：改写每个 stock 预设文件（compaction-basic 行 → dsh-engram/compaction 行，
-#      每个文件旁留 agent.cordis.yml.engram.bak）
+#      每个文件旁留 .engram.bak 备份）：
+#        DSH ≤ 0.1.x → <root>/<id>/agent.cordis.yml.engram.bak
+#        DSH ≥ 0.2.0 → <presets>/<id>.patch.yml.engram.bak
 dsh web
 
 # ④ 再重启一次 dsh web —— 让已接管的预设真正生效
@@ -144,8 +153,8 @@ Fetch the exact records that are still in the store:
 
 | 键 | 默认 | 作用 |
 |---|---|---|
-| `autoWebCompaction` | `true` | 是否在启动时自动改写 stock 预设并接管 web 平面 |
-| `gcReplacesCompaction` | `true` | `true`=用 Context GC；`false`=回退 DSH 默认 LLM 摘要（`compaction` 服务永不缺席） |
+| `autoWebCompaction` | `false` | 是否在启动时自动改写 stock 预设并接管 web 平面（opt-in，见开头） |
+| `gcReplacesCompaction` | `false` | `true`=用 Context GC；`false`=回退 DSH 默认 LLM 摘要（`compaction` 服务永不缺席）。opt-in |
 | `gcNarrative` | `true` | 无锚轮次是否走 scoped LLM 叙事；`false`=**纯机械、整条路径零 LLM** |
 | `gcNarrativeMaxTokens` | `1024` | 叙事生成的最大 token 数 |
 | `gcNarrativeMaxChars` | `4000` | 无锚轮次原文兜底的截断长度（字符） |
@@ -158,13 +167,15 @@ Fetch the exact records that are still in the store:
 
 | 命令 | 作用 |
 |---|---|
-| `npx dsh-engram status` | 查看 host + 每个预设的接管状态与生效配置 |
+| `npx dsh-engram status` | 查看 host + 每个预设的接管状态与生效配置（自动适配新旧预设布局） |
 | `npx dsh-engram doctor` | status + 按缺口排序的下一步 |
 | `npx dsh-engram enable` | 手动重跑启动时的自动装配（通常 no-op） |
 | `npx dsh-engram revert` | 把全部预设还原成 stock `compaction-basic` 行 |
+| `npx dsh-engram status --presets-dir <dir>` | 声明式预设目录探测失败时手动指定（如 `DSH_WEB_PRESETS_DIR`） |
 
 - 仓库内 `npm run web-compaction:*` 是同一 CLI 的别名。
-- 每个被改写文件旁有 `agent.cordis.yml.engram.bak`（create-only，保留首次原件）。
+- 每个被改写文件旁有 `.engram.bak`（create-only，保留首次原件）：
+  `agent.cordis.yml.engram.bak`（旧版布局）或 `<id>.patch.yml.engram.bak`（声明式布局）。
 - **卸载 dsh-engram 之前先 `npx dsh-engram revert`**——否则预设里的 `dsh-engram/compaction` 行会
   悬空，web 会话挂 loading。
 
@@ -179,13 +190,31 @@ Fetch the exact records that are still in the store:
 | 长会话自动压缩仍不提交（`start` 涨、`summary` 不涨） | 同上 / 或某些后端版本旧 | 重启；确认日志有 `compaction = Context GC` |
 | 日志 `… keeping the existing compaction service` | 同域已有 compaction provider（基座行未禁 / 双 provider） | 检查 patch 与预设行，避免重复注册 |
 | 日志 `web-provision … skipped (custom)` | 该预设是自定义/无 compaction 布局 | **设计如此**，不会碰 |
+| 日志 `preset "x" has no shipped file …` | DSH ≥ 0.2.0 的声明式用户预设（存在 profile patch，无出厂文件） | 在设置卡/编辑器里改；或手动把 compaction 组换成 `dsh-engram/compaction` |
+| 改了 shipped 预设文件却不生效 | profile patch 里有 `preset-*` 覆写行（Web 编辑器保存的 `config.plugins` 优先） | 在编辑器里改，或删掉覆写行 |
 | 日志 `dsh-compaction-basic unavailable` | 环境缺后端依赖 | 安装依赖；自动回退默认压缩，host 不崩 |
 | 极小被驱逐片段（span 小于 checkpoint 开销）不压缩 | harness 收缩闸门对**任何**后端一视同仁 | 属正常，没必要为几十 token 起 checkpoint |
 | 改配置后没变化 | web 行要重启才刷新 | 重启 dsh web |
+| 遥测「节省 · 剪枝/压缩」一直是 0、净 token 恒负 | 两条入账腿都没触发：L1 在 0.2.0 web profile 下拿不到 host 平面的 `toolResultPruner`；压缩节省此前进不了账本 | 确认状态快照 `boundaryPrune.armed: true`（`npx dsh-engram status` 会打印）；升级到 0.7.1+ 后压缩会按 `区间字符数 − checkpoint 字符数` 入账 |
 
 ---
 
-## 9. FAQ
+## 9. 账本口径（为什么净 token 可能为负）
+
+`net = avoided − injected − rewriteChars × (1 − ledgerCacheDiscount)`，三项都按
+`chars / 4` 估算（见 README「Context Ledger」）：
+
+- **injected**：`[ENGRAM]`/`[RECALL]`/`[JIT]`/`[ESR]` 块每请求重计的注入成本；
+- **avoided**：**已入账**的节省，只有两条腿——L1 边界剪枝（`toolResultPruner` 剪掉的
+  chars × 后续请求数）与压缩（每次 checkpoint 的「被替换区间字符数 − checkpoint 字符数」× 后续请求数）；
+- **rewrite penalty**：L1 剪枝会击穿 KV 前缀缓存，按 `1 − 缓存折价` 一次性计价；
+  压缩**不额外计**罚金（压缩是宿主自己的动作，默认后端同样会改写前缀，计了会重复）。
+
+所以：**没剪过、没压缩过的会话，节省必然是 0，净值必然是负的**——负数不代表账本坏了，
+只代表这一段时间只花了钱没省到。状态快照的 `boundaryPrune.armed` 告诉你 L1 是否真的
+武装；压缩入账要等第一次 checkpoint。
+
+## 10. FAQ
 
 - **有损吗？** 锚定细节**无损**（全部可通过工具重取）；只有无锚轮次走叙事/截断；所有原文仍留在
   会话日志里，即使 checkpoint 被裁剪也能找回。

package/docs/RELEASE-NOTES-v0.7.1.md

@@ -0,0 +1,88 @@
+## dsh-engram v0.7.1
+
+自 v0.7.0 以来：**修复 DSH `0.2.0` 声明式预设下的 web 平面 Context GC 接管**。v0.7.0（及
+更早）的自动装配以旧版 `agent.cordis.yml` 的布局为锚（`compaction-basic` 行固定 4 空格缩进），
+而 `0.2.0` 把代理预设换成了 `@deepseek-ai/dsh-web-app/presets/<id>.patch.yml` 里的
+`@deepseek-ai/dsh-agent-preset` 声明（行在 14/16/18 空格缩进）——结果是 **autoWebCompaction
+静默跳过所有预设**，且旧的字符串替换不含行尾换行，极端情况下会半改写 stock 行。
+
+### 修复
+
+- **结构化定位 compaction 行** — 不再按缩进/整行字面量匹配：先找 YAML 结构里的
+  `compaction` 组（带 `group: true` 的列表项），再在组内按 `- id:` **且** `name:` 双重校验
+  定位 stock / engram 行，替换块继承该行自己的缩进。旧版组合文件（4 空格）与声明式补丁文件
+  （14/16/18 空格）都逐字节往返一致（swap → restore 还原原件）。
+- **声明式预设发现** — DSH `0.2.0` 的预设 roster 不再携带 `path`。插件把 roster 的每个 id
+  映射到出厂的 `<presetsDir>/<id>.patch.yml`（经 dsh 安装解析，`DSH_WEB_PRESETS_DIR` 可覆盖），
+  找不到出厂文件（= 用户自定义声明式预设 / profile patch 覆写）时跳过并打明确日志，不再当成故障。
+- **删除一个潜在的半改写 bug** — stock 替换原用不含行尾的固定字符串，若文件恰好把
+  `compaction-basic` 行与下一行同缩进紧挨着，替换会产生缺换行的坏文件；新实现按整块替换。
+- **状态 / doctor CLI 适配两种布局** — `npx dsh-engram status|doctor` 自动发现旧版
+  `agent.cordis.yml` 与声明式 `*.patch.yml`，显示检测到的布局；doctor 新增
+  `autoWebCompaction=false`（opt-in 未打开，web 平面必然 no-op）、node_modules 预设（`npm update dsh`
+  会恢复出厂布局，仅 autoWebCompaction 保持开启时下次启动自动重接管）、profile patch 里
+  `preset-*` 覆写行（Web 编辑器保存的 `config.plugins` 优先于 shipped 文件）的三类提示。
+  `enable` 手动重跑时镜像状态快照里记录的 `gcReplacesCompaction`/`gcNarrative`，不会把手动
+  enable 的预设行翻成与设置卡不一致的开关。
+- **状态快照不再假装「启动中」** — `autoWebCompaction=false` 时 web 平面记为 `disabled`
+  （此前恒为 `pending`，`dsh-engram status` 会误显示「启动中（agentPresets 尚未就绪）」），
+  CLI 增加「未启用（autoWebCompaction=false）」文案并保留 opt-in 警告，旧快照里遗留的
+  `pending` 也会按快照记录的 `configSource` 归一化显示。
+
+### 账本：节省不再是常量 0（净 token 恒负的根因）
+
+遥测里「节省 · 剪枝/压缩」长期为 0、净 token 恒为负，是两条**入账腿同时断开**：
+
+- **L1 边界剪枝在 0.2.0 web profile 下静默失效** — `dsh-web-app` 的 host 层把
+  `tool-result-pruner` 行 `disabled: true` 并移进各 agent preset 的 isolate realm，
+  host 平面的 engram 插件 `ctx.get("toolResultPruner")` 拿到 `undefined`，只打一行 warn
+  就休眠。现在 bundle `cordis.patch.yml` 重新启用 host 行（预设域仍保留自己那份用于
+  compaction 期剪枝），状态快照新增 `boundaryPrune: { armed, reason }`，CLI `status`
+  会打印「L1 边界剪枝：已武装 / 未启用（原因）」，未武装时直接提示节省不会入账。
+- **压缩节省从未接入** — Context GC 引擎现在在 checkpoint 提交前算
+  `被替换区间可见字符数（含 tool-call 参数与嵌套 tool-result） − checkpoint 字符数`，
+  经 `onCompacted` 回调交给账本 `noteCompaction`，按后续请求计入 `avoidedChars`（与剪枝同口径）。
+  host 平面直连账本；web 预设域通过 host 插件提供的 `engramLedger` 普通服务桥接（隔离域里
+  closure 不可达），全进程仍只有一个落盘写入者。回调失败被容器化，绝不影响压缩。
+
+### 遥测口径更直白
+
+- 卡片标签改成「节省 · 剪枝/压缩（已入账）」「注入成本 · 索引/召回/ESR（每请求重计）」；
+- 当 `avoidedTokens === 0` 且已有注入/重写时，页签内直接解释：还没有剪枝/压缩节省入账、
+  L1 需要 host 平面 pruner、净值为负 = 注入 + 重写罚金；
+- README 中英两版与 `docs/CONTEXT-GC-GUIDE.zh.md` 的「口径诚实」段落更新（原文写
+  「Context GC 的压缩节省暂未接入」）。
+
+### 兼容性说明
+
+- 纯**文件改写逻辑**修复，无存储 schema 变化、无新设置键（GUI 旋钮仍 34 个）。
+- `autoWebCompaction` 仍是 opt-in（默认 `false`）：打开后**重启一次 `dsh web`**，下一次启动
+  即把每个 stock 声明式预设接管（幂等；已手写的 engram 行会按请求的引擎配置刷新）。
+- 已接管但位于 node_modules 的预设：`npm update dsh` 会恢复出厂布局，保持 autoWebCompaction
+  开启时下次启动自动重新接管，否则手动 `npx dsh-engram enable`。
+
+### 其他
+
+- 测试 **405/405**（v0.7.1 共新增 24 例：15 例 web-provision/CLI——8 个 web-provision 例——声明式 stock/custom/双组拒绝、
+  14 空格 swap+refresh+逐字节 restore、`--presets-dir` 发现、roster 无 path 的映射/跳过/扫描
+  回退；7 个 CLI 集成例——沙箱 `DSH_HOME` + 声明式目录下 status/enable/revert/`--file`/
+  `DSH_WEB_PRESETS_DIR` 发现/doctor opt-in 提示/未知命令退出码；另有 9 例账本修复——
+  压缩入账滚动 1、`messagesTextChars` 1、`onCompacted` 上报 1、回调抛错不断压缩 1、
+  预设域经 `engramLedger` 入账 1、无账本服务仍可压缩 1、`boundaryPruneAvailability` 3）；
+  `npm test` 全绿。
+- 文档：`docs/CONTEXT-GC-GUIDE.zh.md` 补两种预设布局说明、`.engram.bak` 命名、`--presets-dir`、
+  两条排障条目；顺带修正指南第 6 节里 v0.6 起已改为 opt-in 但表格仍写默认 `true` 的笔误；
+  README 兼容性矩阵新增 `0.7.1` 行。
+
+## DSH 版本支持
+
+- **支持的 DSH 范围**：`>=0.1.2-alpha.2 <0.3.0-0`
+- **peer 声明**：
+  - `@deepseek-ai/dsh-compaction`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-compaction-basic`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-llm`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-settings`: `>=0.1.2-alpha.2 <0.3.0-0`
+  - `@deepseek-ai/dsh-storage-domain`: `>=0.1.2-alpha.2 <0.3.0-0`
+- **验证版本**：`dsh 0.2.0-rc.2`（本机全局安装，`dsh-web-app/presets` 4 个预设实测）
+- **最后验证日期**：2026-10-19
+- **安装方式已验证**：`dsh plugin --profile web add dsh-engram`

package/lib/boundary-prune.js

@@ -45,6 +45,7 @@ import { workspaceKey as wk } from "./util.js";
 
 /** Fixed fallback for the repayment gate when no history exists yet. */
 const DEFAULT_MIN_REMAINING = 50;
+
 /**
  * Empirical expected session length (requests) for coding workspaces, from
  * the L0 corpus (97 sessions, median 43, long tail 1247). Used as the prior
@@ -128,6 +129,32 @@ export function expectedSessionRequests(requestsSoFar, history, workspace, floor
   return Math.max(prior, requestsSoFar * 2);
 }
 
+/**
+ * Whether BoundaryPrune can actually fire on this context, for the durable
+ * status snapshot (and for users asking "why is 节省 always 0?").
+ *
+ * DSH ≥ 0.2.0 web profiles disable the host-plane `tool-result-pruner` row and
+ * mount the pruner inside each agent preset's isolate realm, where a host-plane
+ * plugin cannot see it. The shipped bundle patch re-enables the host row; when
+ * a custom profile keeps it off, this reports why L1 stays dormant.
+ *
+ * @param {object} ctx - the host plugin context.
+ * @param {object} config - resolved engram config.
+ * @returns {{ armed: boolean, reason: string }}
+ */
+export function boundaryPruneAvailability(ctx, config) {
+  if (config?.boundaryPrune === false) return { armed: false, reason: "disabled by config (boundaryPrune:false)" };
+  const pruner = ctx?.get?.("toolResultPruner");
+  if (!pruner || typeof pruner.pruneSession !== "function") {
+    return {
+      armed: false,
+      reason: "no toolResultPruner service in the host plane (the bundle patch must re-enable the tool-result-pruner row)",
+    };
+  }
+  const threshold = pruner.config?.thresholdChars;
+  return { armed: true, reason: `threshold ${Number.isFinite(threshold) ? threshold : "default"}${config?.boundaryPruneThresholdChars > 0 ? ` (override ${config.boundaryPruneThresholdChars})` : ""}` };
+}
+
 /** Install the boundary-prune listener. Returns a disposer. */
 export function installBoundaryPrune(ctx, config, log, hooks = {}, opts = {}) {
   // Default ON (v0.6 default correction): explicit `false` is the opt-out.

package/lib/client.js

@@ -2209,11 +2209,11 @@ function EngramTelemetry({ api, workspace }) {
           /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.grid, marginTop: 8 }, children: [
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#059669" }, children: tokenCount(ledgerBucket.avoidedTokens) }),
-              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u8282\u7701 \xB7 \u526A\u679D/\u538B\u7F29" })
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u8282\u7701 \xB7 \u526A\u679D/\u538B\u7F29\uFF08\u5DF2\u5165\u8D26\uFF09" })
             ] }),
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#d97706" }, children: tokenCount(-ledgerBucket.injectedTokens) }),
-              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u6CE8\u5165\u6210\u672C \xB7 \u7D22\u5F15/\u53EC\u56DE/ESR" })
+              /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: hb2.statLabel, children: "\u6CE8\u5165\u6210\u672C \xB7 \u7D22\u5F15/\u53EC\u56DE/ESR\uFF08\u6BCF\u8BF7\u6C42\u91CD\u8BA1\uFF09" })
             ] }),
             /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: hb2.statCard, children: [
               /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.statNum, color: "#dc2626" }, children: tokenCount(-Math.round(ledgerBucket.rewritesCostChars / ledger.charsPerToken)) }),
@@ -2224,6 +2224,7 @@ function EngramTelemetry({ api, workspace }) {
               ] })
             ] })
           ] }),
+          ledgerBucket.avoidedTokens === 0 && (ledgerBucket.injectedTokens > 0 || ledgerBucket.rewriteCount > 0) && /* @__PURE__ */ (0, import_jsx_runtime5.jsx)("div", { style: { ...hb2.sub, marginTop: 6 }, children: "\u8282\u7701\u4ECD\u4E3A 0\uFF1A\u672C\u5DE5\u4F5C\u533A\u8FD8\u6CA1\u6709\u526A\u679D/\u538B\u7F29\u8282\u7701\u5165\u8D26\u2014\u2014L1 \u8FB9\u754C\u526A\u679D\u9700\u8981 host \u5E73\u9762\u7684 toolResultPruner\uFF08DSH \u2265 0.2.0 \u7531 bundle patch \u91CD\u65B0\u542F\u7528\u8BE5\u884C\uFF09\uFF0C\u538B\u7F29\u8282\u7701\u7531 Context GC \u5F15\u64CE\u5728 checkpoint \u65F6\u4E0A\u62A5\uFF1B\u51C0\u503C\u4E3A\u8D1F = \u6CE8\u5165\u6210\u672C + \u91CD\u5199\u7F5A\u91D1\u7684\u5408\u8BA1\u3002" }),
           /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("div", { style: { ...hb2.sub, marginTop: 6 }, children: [
             "\u53E3\u5F84\uFF1Achars/",
             ledger.charsPerToken,

package/lib/compaction.js

@@ -62,6 +62,17 @@ export function apply(ctx, config = {}) {
             if (!domain) return null;
             return collectPointerContext(domain, wk(workspace), report);
           },
+          // Context Ledger bridge: this row runs inside the agent preset's
+          // isolate realm, where the host plugin's ledger closure is not
+          // reachable. The host plugin provides `engramLedger` as a plain
+          // (non-isolated) service, so compaction savings are credited to the
+          // one durable ledger instead of vanishing with the realm.
+          onCompacted: ({ session, workspace, charsSaved }) => {
+            try {
+              const hub = ctx.get("engramLedger");
+              hub?.noteCompaction?.(session?.id, workspace, { charsSaved });
+            } catch { /* contained: accounting never breaks compaction */ }
+          },
         }
       : {};
 

package/lib/context-gc.js

@@ -73,6 +73,38 @@ export function blockText(content) {
   return out.trim();
 }
 
+/** Recursive visible-text char count over DSH content blocks (code points). */
+function contentTextChars(value) {
+  if (typeof value === "string") return [...value].length;
+  if (Array.isArray(value)) {
+    let chars = 0;
+    for (const part of value) chars += contentTextChars(part);
+    return chars;
+  }
+  if (value === null || typeof value !== "object") return 0;
+  let chars = 0;
+  // Text blocks, tool-call arguments and nested tool-result content are all
+  // replayed context — count each once.
+  if (typeof value.text === "string") chars += [...value.text].length;
+  if (typeof value.arguments === "string") chars += [...value.arguments].length;
+  if (value.content !== undefined) chars += contentTextChars(value.content);
+  return chars;
+}
+
+/**
+ * Total visible text characters (Unicode code points) across a message list —
+ * the size side of the Context Ledger credit: a compaction replaces this span
+ * with the checkpoint, so `span − summary` is the part that stops replaying.
+ * @param {Array<object>} messages
+ * @returns {number}
+ */
+export function messagesTextChars(messages) {
+  if (!Array.isArray(messages)) return 0;
+  let chars = 0;
+  for (const message of messages) chars += contentTextChars(message?.content);
+  return chars;
+}
+
 /**
  * The durable checkpoint framing the harness applies to a compaction summary
  * before accepting it (`frameSummary()` in dsh-compaction-basic): the summary
@@ -762,6 +794,21 @@ export async function loadContextGcEngine(ctx, config = {}, deps = {}) {
       }
       summaryText = fit.text;
 
+      // Context Ledger credit: the span the checkpoint replaces stops
+      // replaying, so `span − summary` is a measured saving the accounting
+      // layer never had (the host does not expose compaction sizes). Best
+      // effort — accounting must never break the compaction path.
+      try {
+        if (typeof this.gcDeps?.onCompacted === "function") {
+          const spanChars = messagesTextChars(messages);
+          const summaryChars = [...summaryText].length;
+          const charsSaved = spanChars - summaryChars;
+          if (charsSaved > 0) {
+            this.gcDeps.onCompacted({ session: agent?.session, workspace: ws, charsSaved, spanChars, summaryChars });
+          }
+        }
+      } catch { /* contained: a credit bug must never fail a compaction */ }
+
       const result = { summary: [{ type: "text", text: summaryText }] };
       if (narrative.llm && typeof narrative.llm === "object") Object.assign(result, narrative.llm);
       // The harness's durable `compaction/summary` record ALWAYS carries