dsh-engram 0.3.4 → 0.3.5

package/README.md

@@ -2,6 +2,8 @@
 
 > **[English](README.md) · [中文](README.zh.md)**
 
+[![CI](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml/badge.svg)](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml)
+
 Minimalist long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness), distilled from the
 [symbolic-index](https://github.com/skepsun/symbolic-index) and [pi-esr](https://github.com/skepsun/pi-esr) ideas —
 with one goal: **save tokens**.
@@ -11,6 +13,16 @@ with one goal: **save tokens**.
   key files, repeated errors), plus an explicit `engram_store`. Nothing on the hot
   path calls a model, and pure plumbing — `git push` / `git stash` / silent
   commits — is deliberately never recorded (see *Auto-capture policy* below).
+  Every write is run through a deterministic **secret redactor** first — API
+  keys, JWTs, `Bearer` tokens, private keys, AWS/Stripe/Slack/GitHub tokens and
+  `key=value` secret shapes are replaced with `<REDACTED:…>` markers before the
+  dedup hash, the char cap, and storage, so sensitive text can never land on
+  disk. Failing **test runs** are recognized by pure patterns (`npm test`,
+  `node --test`, vitest/pytest/jest, failure lines) and captured as
+  `tags:["error","test"]` entries with a raised signal. DSH **goal-domain
+  integration**: a completed or blocked goal (`goal/change` session event)
+  auto-sediments as a `handoff`/`error` memory (`tag:goal`), so the outcome of
+  a goal survives its session (see the `GET /api/dsh-engram/goals` read surface).
 - **Symbolic index + progressive disclosure** — a compact `[ENGRAM]` block (default
   budget 700 chars ≈ 175 tokens; one line per memory) is injected at prompt
   assembly and **frozen per session**, keeping the request prefix byte-stable for
@@ -23,7 +35,25 @@ with one goal: **save tokens**.
   (repeat-failure revival: recency + hit climb toward promoteHits so the
   failure resurfaces instead of piling up), and on zero local hits falls back
   to DSH's own cross-session full-text index (`ctx.sessionQuery`, filtered by
-  cwd) instead of building a parallel SQLite index.
+  cwd) instead of building a parallel SQLite index; when the FTS fallback also
+  comes back empty and the query contains **CJK** characters (Chinese FTS5
+  tokenization), recall runs a bounded substring scan over the newest session
+  logs (zstd-decompressed, LRU-cached) and appends matched past sessions —
+  deterministic `# past sessions` lines, capped files and bytes.
+- **Memory-to-memory semantics** — `engram_store` accepts optional
+  `supersedes` / `contradicts` memory ids (validated against the same
+  workspace). A superseded ("stale truth") memory is demoted to the tail of
+  recall and **excluded from the `[ENGRAM]` block**, while the superseding
+  statement keeps the line; a contradicted memory stays ranked but is flagged
+  `· contradicted by <id>`. Old rows are never deleted — re-fetchable, just
+  honestly ranked. Opt-in `autoSupersede` config (default **off**) auto-marks
+  entity-anchored replacement updates ("改用 / no longer / switched…") as
+  superseding their matching older row; explicit `supersedes` always wins.
+- **Failure→fix closure (zero LLM)** — error memories carry a `cmd:` signature
+  tag; when that same command later succeeds, engram auto-sediments a
+  `procedure` memory (`fixed: <cmd> — N earlier failing runs now succeed`),
+  tags the earlier error rows `resolved` (never re-ranking them), and recall
+  then surfaces the fix instead of the stale failure.
 - **ESR-lite closure protocol** — `esr_task` / `esr_close` / `esr_link` give tasks
   a `draft → active → stable` lifecycle where `stable` requires real evidence
   (`artifact` / `evaluation` / `memory_ref`), surfacing closure gaps instead of
@@ -56,6 +86,18 @@ with one goal: **save tokens**.
   The `tools/result` recorder feeds the actionables' data sources; P4
   conversion metering stays (`#suggest-*` tags + 10-minute attribution +
   `GET /api/dsh-engram/triggerstats`). Pure rules, zero LLM.
+- **Session-end todo auto-sink (draft safety net, `autoSinkTodosOnEnd` default
+  on)** — during a session the native todo stays cheap, per-session working
+  memory that dies with the session. But when a session closes at its teardown
+  edge (`session/disposed`) while its plan still has pending todos, they are
+  **auto-landed as ESR `draft` tasks** (name = the todo text, description
+  marked 「源自会话计划」, deduped against existing task names, capped by
+  `maxTasksPerWorkspace`), so the plan never silently evaporates. Sinking to
+  **draft** — not active — keeps them out of the `[ESR]` active rows and creates
+  no evidence obligation; an explicit `esr_claim` / `esr_task` step is still
+  what promotes a draft to active. The "nothing auto-written during the
+  session" trade-off is unchanged; only the end-of-session data-loss gap is
+  closed. Disable via profile patch or the settings card.
 - **Memory GC (pi-esr constraints)** — a scheduled, mechanical, archive-only
   sweep: TTL-expired memories are archived, over-cap workspaces evict the
   lowest-value entries, stable tasks past their retention window leave the
@@ -275,15 +317,20 @@ npm run build:client
 
 | Tool | Purpose | Kind |
 |---|---|---|
-| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor) | write |
+| `engram_store` | Explicitly store one memory (kind, tags, optional entity anchor, optional supersedes/contradicts memory ids) | write |
 | `engram_recall` | Deterministic keyword recall over workspace memories; optional `search_sessions` FTS over past sessions | read |
 | `engram_detail` | Full record of one memory id (provenance, tags, hits) | read |
 | `esr_task` | Create a task entity (draft → active) | write |
 | `esr_close` | Close a task via the evidence protocol (artifact + evaluation + memory_ref) | write |
 | `esr_link` | Add a typed relation between two entities (mini graph) | write |
+| `esr_dep` | Add a dependency edge (blocks / relates-to / parent-of) between tasks | write |
+| `esr_claim` | Atomically claim a task (assignee + claimedAt, draft → active) | write |
+| `esr_unclaim` | Release a claimed task's assignee | write |
 | `esr_ready` | List claimable tasks (no open blocker, unclaimed) | read |
 | `esr_status` | Pull live ESR state + derived hints (`since_revision` short "unchanged" response) | read |
+| `esr_node` | Create/update an entity node (stable symbol) | write |
 | `esr_gc` | Run the memory GC for the workspace (`dry_run:true` previews) | write |
+| `esr_model` | Precomputed mental model of the workspace (`brief`/`full`, `max_chars`) | read |
 
 The `[ESR]` block is a frozen per-session snapshot and never auto-refreshes —
 call `esr_status` for the live truth.
@@ -331,24 +378,74 @@ Triggers follow DSH's own compaction timing (step pressure / context-overflow /
 `/compact`); the lock, replay validation, tool-call/result pairing and token
 pricing are all reused from the basic engine. Any error falls back to the
 default compressor — compaction is never broken; with `gcReplacesCompaction:
-false` (or a host without `dsh-compaction-basic`) the engine never mounts.
-Mounting registers the `compaction` service on the plugin's fiber, so
-unloading/reloading engram restores the default engine.
-
-**Mounting semantics (verified against cordis source)**: cordis refuses a second
-provider of the same service in the same realm (`provide()` throws
-`service "compaction" has been registered` — not "last write wins"). Hence:
-
-- **Host plane**: the plugin patch disables the base `compaction-basic` row
-  (re-armed automatically when engram is uninstalled); dsh-engram is then the
-  sole `compaction` provider, mounting a bare `BasicCompactionEngine` under
-  `gcReplacesCompaction:false` so the service never disappears. Headless / TUI /
-  base-style profiles work out of the box.
-- **Preset plane (web profile)**: web keeps compaction inside each agent
-  preset's isolated realm (the shipped `standard` preset mounts its own
-  `compaction-basic`), unreachable from a host-plane row. Swap that row for the
-  mountable entry dsh-engram ships (`dsh-engram/compaction`, package subpath
-  export) to activate per session:
+false` (or a host without `dsh-compaction-basic`) a bare `BasicCompactionEngine`
+is mounted instead, so the `compaction` service never disappears while
+dsh-engram is installed. Mounting registers the `compaction` service on the
+plugin's fiber, so unloading/reloading engram restores the default engine.
+
+> **Shrink gate**: the harness refuses any checkpoint that is not strictly
+> smaller than the evicted span (`summary is not smaller than the shadowed
+> content`) and rolls the compaction back — otherwise the context never shrinks
+> and the session eventually hits the model-side overflow. Context GC
+> self-predicts that gate: it mirrors the harness framing with the host
+> `tokenMeter` (verified token-for-token identical) and truncates the
+> pointer/narrative body to the evicted span's token budget (the pointer head
+> and working set survive; the trimmed tail stays recoverable in the session
+> log), so compactions actually commit. Full from-scratch usage:
+> [`docs/CONTEXT-GC-GUIDE.zh.md`](docs/CONTEXT-GC-GUIDE.zh.md).
+
+#### Where it is enabled (the entry point)
+
+Assembly happens on **two planes** — and web is now fully automatic, zero config:
+
+- **Host plane (headless / TUI / base profiles) — on by default, zero config**:
+  the main plugin (`lib/index.js`) mounts the engine inside `ctx.effect` via
+  `mountCompactionEngine(ctx, resolved, { readWorkspace }) → new Engine()`,
+  registering the `compaction` service on its own fiber; the plugin patch
+  disables the base `compaction-basic` row, making engram the sole host-plane
+  provider. `gcReplacesCompaction: true` (default) → `ContextGcEngine`;
+  `false` → a bare `BasicCompactionEngine`. Tune via profile patch
+  (`config: { gcReplacesCompaction: false }`) or the settings card's
+  `gcNarrative` knob (narrative off = fully mechanical).
+- **Preset plane (web profile) — fully automatic, zero config, covers every
+  preset**: web keeps compaction inside each agent preset's isolated realm
+  (the shipped presets mount their own `compaction-basic`), unreachable from a
+  host-plane row — and unreachable from a profile patch too (`mountPreset`
+  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:
+  - **on by default** (`autoWebCompaction: true`, toggle in the settings card's
+    memory-GC section), idempotent — an already-wired preset is left alone;
+    **what "off" means**: the plugin stops auto-wiring on later boots (the
+    headless/TUI/base host plane is unaffected) — it does NOT un-wire presets
+    that were already wired; use `npm run web-compaction:revert` for that;
+  - **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
+    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.
+  - **config actually propagates**: the engine config written into each row
+    comes from the live settings (`gcReplacesCompaction` / `gcNarrative`) — with
+    "already wired but with a different config" treated as a refresh, so
+    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):
+    ```bash
+    npx dsh-engram status     # stock = untouched · wired = active · custom = hands-off
+    npx dsh-engram doctor     # status + ranked next steps for every gap found
+    npx dsh-engram enable     # same as the boot-time auto-wiring (usually a no-op)
+    npx dsh-engram revert     # restore the stock row everywhere — run BEFORE uninstalling
+    ```
+    (in the repo, `npm run web-compaction:*` is an alias of the same CLI.)
+    Either way the `compaction` group becomes:
   ```yaml
   - id: compaction
     name: cordis:group
@@ -360,14 +457,51 @@ provider of the same service in the same realm (`provide()` throws
       - id: engram-compaction       # replaces the original compaction-basic
         name: dsh-engram/compaction
         config:
-          gcReplacesCompaction: true   # optional; false = default LLM summary for this session
-          gcNarrative: true
+          gcReplacesCompaction: true   # from settings; false = default LLM summary for this session
+          gcNarrative: true            # from settings; false = fully mechanical
       - id: command-compact
         name: '@deepseek-ai/dsh-command-compact'
       - id: tool-result-pruner
         name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
         # keep the original config
   ```
+  ⚠️ **Uninstall = revert first**: once a preset references
+  `dsh-engram/compaction`, removing dsh-engram leaves every such row dangling
+  and web sessions hang on load — so run `npx dsh-engram revert`
+  (restores every preset) BEFORE uninstalling. A harness upgrade that ships a
+  fresh standard preset overwrites the swap and self-heals the dangling
+  reference.
+
+#### First impressions after an npm install (perceive / guide / configure)
+
+- **Automatic**: install into a profile and boot once — the host plane is taken
+  over by `mountCompactionEngine`, and the web plane by `autoWebCompaction`
+  (default on) rewriting every stock preset at boot. **Zero manual setup.**
+- **Perceivable**: at boot the plugin writes an authoritative snapshot to
+  `$DSH_HOME/engram/context-gc.status.json` (`host` plane mode + the per-preset
+  `web` results + effective config). At any time run `npx dsh-engram status` or
+  `npx dsh-engram doctor`; the web memory board (ESR kanban) also shows a
+  header chip ("Context GC·主机 ·N 预设") fed by the overview API. Two startup
+  log lines confirm it too: `engram context-gc: compaction = Context GC …` and
+  `engram web-provision: wired Context GC into preset …`.
+- **Configurable**: one settings card (memory-GC section) governs everything:
+  `autoWebCompaction` (web auto-wiring on/off), `gcReplacesCompaction`
+  (Context GC vs default summarizer), `gcNarrative` (narrative safety net).
+  Changes take effect after restarting `dsh web`, and the web rows are
+  refreshed to match automatically.
+
+**Verify it took**: after restarting `dsh web` (or the profile) —
+- host plane (headless/TUI/base): the startup log shows
+`engram context-gc: compaction = Context GC (mechanical eviction + re-fetch pointers)`;
+- web plane: the log shows one line per wired preset —
+`engram web-provision: wired Context GC into preset "standard" (…); restart dsh web so sessions pick it up`,
+or `npx dsh-engram status` reports `wired` for each; sessions composed
+from ANY preset then compact via mechanical eviction + re-fetch pointers.
+A line like `… keeping the existing compaction service` means another provider
+already owns `compaction` in that realm (the swap didn't take); `web-provision … skipped (custom)`
+means that preset was customized (or has no compaction group) and was left untouched;
+`dsh-compaction-basic unavailable` means the backend is missing and everything
+falls back to the default compressor.
 
 ## Auto-capture policy
 

package/README.zh.md

@@ -2,6 +2,8 @@
 
 > **[中文](README.zh.md) · [English](README.md) · [已交付 UI 控件清单](FEATURES.zh.md)**
 
+[![CI](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml/badge.svg)](https://github.com/skepsun/dsh-engram/actions/workflows/ci.yml)
+
 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 设计的极简长期记忆插件，融合了
 [symbolic-index](https://github.com/skepsun/symbolic-index) 与 [pi-esr](https://github.com/skepsun/pi-esr) 的思想——
 目标只有一个：**省 token**。
@@ -9,6 +11,12 @@
 - **零 LLM 摄入** — 纯模式匹配从工具结果自动捕获有意义的事件（带书面 `-m` 提交信息的 git 里程碑、
   关键文件编辑、反复出现的错误），另有显式 `engram_store`。热路径上没有任何模型调用，纯粹的操作
   ——`git push` / `git stash` / 无提交信息的 commit——刻意**从不记录**（见下方「自动捕获策略」）。
+  每条写入先过一道确定性**密钥脱敏器**——API key、JWT、`Bearer` token、私钥、AWS/Stripe/Slack/GitHub
+  token 与 `key=value` 形密钥一律替换为 `<REDACTED:…>` 标记，且在去重哈希 / 字符上限 / 落盘之前完成，
+  敏感内容永远进不了磁盘。**测试失败**用纯模式识别（`npm test` / `node --test` / vitest/pytest/jest
+  + 失败行）自动捕获为 `tags:["error","test"]`、信号上调。DSH **goal 域打通**：completed/blocked 的
+  goal（`goal/change` 会话事件）自动沉淀为 `handoff`/`error` 记忆（`tag:goal`），目标结局不随会话消散
+  （读取面见 `GET /api/dsh-engram/goals`）。
 - **符号索引 + 渐进披露** — 一个紧凑的 `[ENGRAM]` 块（默认预算 700 字符 ≈ 175 token；每条记忆一行）在
   组装提示词时注入，并**按会话冻结**，让请求前缀字节稳定以复用 KV 缓存。模型需要细节时用
   `engram_recall` / `engram_detail` 下钻，而不是把命中的原文灌进上下文。召回对内存池做
@@ -16,7 +24,18 @@
   命中实体锚定的记忆时附带**实体邻域关系简表**（复用 esr_link：`node --rel--> node · conf%`）；
   与历史失败**高度同源**的新错误会**唤醒旧 error 记忆**（刷新 recency + 命中，向 promoteHits
   爬升直至重回索引，失败不重复堆积）；本地零命中时自动兜底到 **DSH 自带的跨会话全文索引**
-  （`ctx.sessionQuery`，按 cwd 过滤）——不另建 SQLite，完全复用宿主。
+  （`ctx.sessionQuery`，按 cwd 过滤）——不另建 SQLite，完全复用宿主。当 FTS 兜底也返回空、
+  且查询含 **CJK 中文**（FTS5 中文分词整段只算一个 token）时，召回会对最近若干会话日志做
+  有界的**子串扫描**（zstd 解压 + LRU 缓存，限文件数与字节），追加命中会话的确定性
+  `# past sessions` 行。
+- **记忆间语义（supersede/contradict）** — `engram_store` 可选收 `supersedes` / `contradicts`
+  记忆 id（同工作区校验）。被 supersede 的「过期真相」在召回里**降级到尾部**、并从 `[ENGRAM]`
+  块中**剔除**（新陈述占行）；被 contradicts 的记忆保留排序但标注 `· contradicted by <id>`。
+  旧行永不删除——可重取，只是排得诚实。可选 `autoSupersede` 配置（默认**关**）对"实体锚定 +
+  替换式更新（改用/不再/no longer/switched…）"自动打 supersedes；显式 `supersedes` 永远优先。
+- **失败→解法闭环（零 LLM）** — error 记忆带 `cmd:` 签名标签；同命令随后跑通时自动沉淀
+  `procedure` 记忆（`fixed: <cmd> — N earlier failing runs now succeed`），并把旧 error
+  行打上 `resolved`（不影响其排序），召回因此浮出解法而不是过期失败。
 - **ESR-lite 证据闭环** — `esr_task` / `esr_close` / `esr_link` 给任务一个 `draft → active → stable`
   生命周期，其中 `stable` 必须要有真实证据（`artifact` / `evaluation` / `memory_ref`），把"缺什么"
   摊在明面上，而不是让 agent 没有证据就宣布完成。可开 `verifyArtifact`（默认开）：非 URL 的
@@ -36,6 +55,13 @@
   **拉取**：`esr_status`（全量视图 + `since_revision` 增量短响应 + 派生 actionables）。
   recorder 由 `tools/result` 订阅喂入（actionables 的数据源）；P4 转化度量照常（`#suggest-*` 标记 +
   10 分钟归因 + `GET /api/dsh-engram/triggerstats`）。纯规则、零 LLM。
+- **会话结束 todo 自动沉淀（draft 兜底，`autoSinkTodosOnEnd` 默认开）** — 会话内 todo 仍是
+  轻量、随会话而逝的"工作记忆"；但当会话在其**拆解边界**（`session/disposed`）关闭时仍挂着 pending
+  todo，这些待办会**自动转为该工作区的 ESR draft 任务**（名称=todo 原文、描述「源自会话计划」、
+  按已存在任务名去重、受 `maxTasksPerWorkspace` 上限约束），计划从此不静默蒸发。落到 **draft**
+  而非 active：不占 `[ESR]` 的 active 行、不产生证据义务，仍需刻意的 `esr_claim` / `esr_task`
+  推进才变 active——「进行中默认不写」的取舍不变，只把「收尾丢数据」的缺口补上。可关（profile
+  patch 或设置卡）。
 - **记忆 GC（pi-esr 约束）** — 定时、机械、只归档的回收：TTL 过期记忆归档、超容量工作区淘汰低价值条目、
   stable 任务超保留窗离开 `[ESR]` 表面、悬空链接边清理。工作集（active 任务引用 / 任务记忆 / 已入索引命中）
   永不触碰；**不硬删任何东西**——归档条目保留 id、始终可重取。
@@ -198,15 +224,20 @@ npm run eval  # 离线召回 + 结构基准（确定性语料，跑真实 store/
 
 | 工具 | 用途 | 类型 |
 |---|---|---|
-| `engram_store` | 显式存入一条记忆（kind、tags、可选实体锚点） | 写 |
+| `engram_store` | 显式存入一条记忆（kind、tags、可选实体锚点、可选 supersedes/contradicts 记忆 id） | 写 |
 | `engram_recall` | 工作区记忆的确定性关键词召回；可选 `search_sessions` 跨会话 FTS | 读 |
 | `engram_detail` | 一条记忆 id 的完整记录（来源、标签、命中数） | 读 |
 | `esr_task` | 创建任务实体（draft → active） | 写 |
 | `esr_close` | 按证据协议关闭任务（artifact + evaluation + memory_ref） | 写 |
 | `esr_link` | 在两个实体之间添加类型化关系（迷你图） | 写 |
+| `esr_dep` | 在任务间添加依赖边（blocks / relates-to / parent-of） | 写 |
+| `esr_claim` | 原子认领任务（assignee + claimedAt，draft → active） | 写 |
+| `esr_unclaim` | 释放已认领任务的 assignee | 写 |
 | `esr_ready` | 列出可认领任务（无 blocker、无人认领） | 读 |
 | `esr_status` | 拉取实时 ESR 状态 + 派生提示（`since_revision` 增量短响应） | 读 |
+| `esr_node` | 创建/更新实体节点（稳定符号） | 写 |
 | `esr_gc` | 运行本工作区的记忆 GC（`dry_run:true` 预览不落库） | 写 |
+| `esr_model` | 工作区预计算心智模型（`brief`/`full`，`max_chars`） | 读 |
 
 `[ESR]` 块是每会话冻结快照，绝不中途刷新——要最新状态调 `esr_status`。
 
@@ -243,15 +274,53 @@ BasicCompactionEngine` 只重写唯一的 `summarize()` 钩子，把摘要正文
 tool-call/result 配对、token 定价全部复用基本引擎。任何错误 → 回退默认压缩，**永不破坏 compact**。
 装配即注册 `compaction` 服务，卸载/reload engram 自动还回默认引擎。
 
-**装配语义（已按 cordis 源码验证）**：cordis 拒绝同域第二个同名 provider（`provide()` 抛
-`service "compaction" has been registered`，不是「后注册 wins」）。因此：
-
-- **host 平面**：插件 patch 直接 `disable` 基座 `compaction-basic` 行（卸载 engram 自动还原），由
-  dsh-engram 独占 `compaction`；`gcReplacesCompaction:false` 时仍挂裸 `BasicCompactionEngine`，
-  服务永不缺席。headless / TUI / base 型 profile 开箱即用。
-- **preset 平面（web profile）**：web 面把 compaction 放在 agent preset 的 isolate realm（`standard`
-  预设自挂 `compaction-basic`），host 条目进不去。把 preset `compaction` 组里的 `compaction-basic`
-  行换成 dsh-engram 提供的可挂载条目即可按 session 生效：
+> **收缩闸门（shrink gate）**：harness 拒绝任何不比被驱逐片段更小的 checkpoint（`summary is not
+> smaller than the shadowed content`），否则压缩回滚、上下文永不缩小、最终触发模型侧溢出。Context GC
+> 据此**自预测闸门**：用 host `tokenMeter` 复刻 harness 的 framing 估算（实测逐 token 一致），把指针
+> 摘要/叙事体按被驱逐 span 的 token 预算动态**裁剪尾部**（指针头与工作集保留，细节仍在会话日志可
+> 重取），保证 checkpoint 严格缩得更小、压缩真正提交——不出现"start 涨、summary 不涨"的假接管。
+> 完整用法见 [`docs/CONTEXT-GC-GUIDE.zh.md`](docs/CONTEXT-GC-GUIDE.zh.md)（从 0 开始的使用教程）。
+
+#### 启用入口（这一节就是答案：该功能开在哪）
+
+Context GC 的装配在**两个平面**——web 现在**全部自动**，零配置：
+
+- **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
+  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」可关），幂等——已替换则跳过；
+    **关掉的含义**：只是在之后的启动时不再自动接管（headless/TUI/base 的 host 平面不受影响）——
+    它**不会**还原之前已接管的预设，要还原用 `npm run web-compaction:revert`；
+  - **逐预设判定，只碰 stock 布局**——用户自定义过 compaction 组的预设，以及根本没有 compaction 组的
+    预设（如 shipped `minimal`），一律不写、只记日志；
+  - **带备份 + 严格校验**：每个文件写前在旁边留 `agent.cordis.yml.engram.bak`（create-only，保留首次
+    原件），写后重读校验，任何一步可疑即回滚该文件；改写失败只 warn，该会话仍用 DSH 默认摘要，
+    **永不影响宿主**。
+  - **配置真实传导**：写进预设行的引擎配置来自设置卡/配置里的 `gcReplacesCompaction` 与
+    `gcNarrative`——改了这两个开关，下次启动会自动把已接管的行刷新成新配置（幂等重写），
+    所以**设置卡对 web 平面同样生效**，不再硬编码 true/true。
+  - 手动的完全等价物（预览 / 审计 / 卸载前回归，随 npm 包发布的 CLI，默认扫 shipped + 用户两个根、
+    可 `--file` 指定单个）：
+    ```bash
+    npx dsh-engram status     # stock → 未动；wired → 已接管；custom → 不碰
+    npx dsh-engram doctor     # status + 按缺口排序的下一步建议
+    npx dsh-engram enable     # 等价于启动时自动装配（通常 no-op）
+    npx dsh-engram revert     # 还原全部预设的 stock 行（卸载 dsh-engram 前先跑这个）
+    ```
+    （仓库内 `npm run web-compaction:*` 是同一 CLI 的别名。）
+    替换后的 `compaction` 组形如：
   ```yaml
   - id: compaction
     name: cordis:group
@@ -263,14 +332,40 @@ tool-call/result 配对、token 定价全部复用基本引擎。任何错误
       - id: engram-compaction       # ← 替换原 compaction-basic
         name: dsh-engram/compaction
         config:
-          gcReplacesCompaction: true   # 可选；false=该 session 用默认 LLM 摘要
-          gcNarrative: true
+          gcReplacesCompaction: true   # 来自设置；false=该 session 用默认 LLM 摘要
+          gcNarrative: true            # 来自设置；false=纯机械无 LLM
       - id: command-compact
         name: '@deepseek-ai/dsh-command-compact'
       - id: tool-result-pruner
         name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
         # 原有配置保留
   ```
+  ⚠️ **卸载前先 revert**：预设引用 `dsh-engram/compaction` 后，卸载 dsh-engram 会让该行悬空、
+  web 会话挂 loading。所以**卸载 engram 前**先 `npx dsh-engram revert`（还原全部预设，
+  或逐个恢复各自的 `.engram.bak`）。harness 大版本升级会覆盖 shipped 预设，悬空引用随之自愈。
+
+#### 从 npm 安装后的第一印象（可感知 / 易引导 / 易配置）
+
+- **自动**：装进 profile 后启动一次即可——host 平面由 `mountCompactionEngine` 直接接管；web 平面
+  由 `autoWebCompaction`（默认开）在启动时自动改写全部 stock 预设。**无需任何手动配置。**
+- **可感知**：插件启动时把权威状态写到 `$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`（叙事兜底开关）——
+  改动后 `dsh web` 重启生效，web 预设行会被自动刷新成新配置。
+
+**验证是否生效**：`dsh web`（或对应 profile）重启后——
+- host 平面（headless/TUI/base）：启动日志出现
+  `engram context-gc: compaction = Context GC (mechanical eviction + re-fetch pointers)`；
+- web 平面：日志出现
+  `engram web-provision: wired Context GC into preset "standard" (…); restart dsh web so sessions pick it up`
+  （每个被接管的预设一行）；或 `npx dsh-engram status` 显示 `wired`；任意预设的会话内
+  `command-compact`/压力触发即走机械驱逐 + 重取指针。
+- （若见 `… keeping the existing compaction service` 说明同域已有 provider、未替换成功；`web-provision … skipped (custom)`
+  说明某预设是自定义/无 compaction 布局、未被触碰；`dsh-compaction-basic unavailable` 说明环境缺依赖，自动回退默认压缩。）
 
 ## 自动捕获策略
 

package/cordis.patch.yml

@@ -14,6 +14,12 @@
 # dsh-engram from the profile re-arms the base row automatically.
 # 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
+# `npm run web-compaction:status|enable|revert`).
 - id: compaction-basic
   disabled: true
 

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

@@ -0,0 +1,192 @@
+# dsh-engram Context GC — 从 0 开始的使用教程
+
+> 适用范围：dsh web（preset 平面）+ headless/TUI/base（host 平面）。
+> 一句话：**用「机械驱逐 + 重取指针」替代 DSH 自带的有损 LLM 全量摘要压缩。**
+
+---
+
+## 1. 这是什么
+
+DSH 默认的上下文压缩（`compaction-basic`）在自动 / 手动 compact 时，把被驱逐的历史压成一段
+**不可查询的散文摘要**——有损、且摘要本身还要烧 token。
+
+dsh-engram 的 Context GC 把这一步换成：
+
+1. **扫描**被驱逐轮次里的 provenance 锚——`engram_store`/`engram_recall`/`engram_detail`
+   回显的 `#记忆id`、`esr_*` 涉及的 `tsk_*`/`ent_*`、`file_path` 锚；
+2. **指针摘要**——每条被驱逐类别都带显式重取调用（`engram_detail(id)` / `engram_recall(query)`
+   / `[ESR]` 块 / `esr_ready`）；active 工作集在摘要里**复述**、不驱逐；
+3. **兜底叙事**——只有**无锚轮次**（纯对话/推理，没有任何可重取落点）才走 scoped LLM 摘要
+   （`gcNarrative`，默认开）；关掉后整条路径**零 LLM**，无锚轮次截断原文保留。
+
+触发时机跟 DSH 现有 compact 完全一致：**自动压力（约 80% 窗口阈值）→ context-overflow → 手动
+`/compact`**。任何一步出错都会回退默认压缩，**永不破坏 compact、永不弄丢会话**。
+
+### 两个平面
+
+| 平面 | 覆盖 | 接管方式 |
+|---|---|---|
+| host 平面 | headless / TUI / base 型 profile | 插件启动时直接注册 `compaction` 服务为零配置 ContextGcEngine |
+| web 平面 | dsh web 的 agent preset（shipped + 用户预设） | 启动时自动把 stock 预设 `compaction` 组的 `compaction-basic` 行换成 `dsh-engram/compaction` 行 |
+
+---
+
+## 2. 前提
+
+- 已安装 dsh（含 **dsh web**）与一个 web profile；
+- dsh-engram 已作为 profile 依赖挂好（`link:/path/to/dsh-loom` 或 npm 包），profile patch 里有
+  `engram` 行；
+- 后端依赖 `@deepseek-ai/dsh-compaction-basic` 可被解析（安装 engram 时自动链接）；
+- 记忆/任务侧已配置好 engram 存储域（`engram_store` 有可写域、ESR 可选）。
+
+---
+
+## 3. 从 0 安装并启用（3 步 + 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 服务
+#    - web 平面：改写每个 stock 预设文件（compaction-basic 行 → dsh-engram/compaction 行，
+#      每个文件旁留 agent.cordis.yml.engram.bak）
+dsh web
+
+# ③ 再重启一次 dsh web —— 让已接管的预设真正生效
+dsh web
+```
+
+**铁律：代码/预设改动后必须重启 dsh。** 运行中的进程把旧 `lib/*.js` 和旧预设行都缓存/装载在内存里，
+磁盘上的修复与文件改写不会热生效；只有重启（host 开机自动装配默认 `autoWebCompaction:true`）才会
+加载新代码并接管 web 预设。
+
+> 也可以先手动预写再一次性重启：
+> ```bash
+> npx dsh-engram enable    # 等价于启动时的自动装配（通常 no-op）
+> npx dsh-engram status    # 确认 preset 已 wired
+> # 然后重启 dsh web 一次
+> ```
+
+---
+
+## 4. 验证是否生效
+
+```bash
+npx dsh-engram status      # 每个预设显示 wired（已接管）/ stock（未动）/ custom（不碰）
+npx dsh-engram doctor      # status + 按缺口排序的下一步建议
+```
+
+启动日志的两行金标准：
+
+```
+engram context-gc: compaction = Context GC (mechanical eviction + re-fetch pointers)   # host
+engram web-provision: wired Context GC into preset "standard" (…); restart dsh web …    # web 每个预设一行
+```
+
+其他入口：
+- 记忆看板头部状态徽标（"Context GC · 主机 ·N 预设"）；
+- 权威快照 `$DSH_HOME/engram/context-gc.status.json`。
+
+---
+
+## 5. 日常使用：它替你做掉了什么
+
+在任意会话里照常对话、照常用工具即可。当 compact 触发（自动压力 / 溢出 / 手动 `/compact`），
+落在会话里的 checkpoint 长这样：
+
+```
+## Context GC — evicted detail is RE-FETCHABLE (do not re-derive)
+
+Older conversation was evicted to free context. The detail is NOT lost: it lives in the engram memory
+store and the ESR task store. Re-fetch ONLY when you actually need it, using the tools below.
+
+Evicted 3 turns. 2 with re-fetchable provenance, 1 narrative-only.
+
+### ESR task state
+Reload the full graph with the [ESR] block / `esr_ready` — only re-fetch what you need.
+- Active working set (still tracked in ESR):
+  - `tsk_act1` — migrate compaction engine
+- 2 closed task(s) retained — details stay re-fetchable via the [ESR] block.
+
+### engram memories (re-fetchable)
+Fetch the exact records that are still in the store:
+- `engram_detail(id: "8f7a2c4e-…")` [decision]
+- Re-run recall: `engram_recall(query: "compaction shrink gate")`
+
+### Narrative not captured elsewhere
+（只有无锚轮次的 scoped 叙事；gcNarrative 关掉则为截断原文）
+```
+
+指针类别速查：
+
+| 被驱逐内容 | checkpoint 里留下的指针 |
+|---|---|
+| engram 记忆（含 auto-capture / recall 命中 `#xxxxxx`） | `engram_detail(id)` / `engram_recall(query/entity)` |
+| ESR 任务 / 实体 / stable 任务 | `[ESR]` 块 / `esr_ready` / 实体 `ent_*` |
+| 文件锚 | `filePath` 路径提示 |
+| 无锚轮次（纯对话 / 推理） | `gcNarrative` 叙事（默认开）或截断原文（关闭后） |
+| active 工作集 | **在摘要里复述，绝不驱逐** |
+
+手动触发：`/compact` 命令（来自 `command-compact` 插件）。
+
+---
+
+## 6. 配置项
+
+> 位置：dsh web 设置卡「记忆 GC」区 / profile patch 的 `engram` 行 `config:` / 配置 JSON。
+
+| 键 | 默认 | 作用 |
+|---|---|---|
+| `autoWebCompaction` | `true` | 是否在启动时自动改写 stock 预设并接管 web 平面 |
+| `gcReplacesCompaction` | `true` | `true`=用 Context GC；`false`=回退 DSH 默认 LLM 摘要（`compaction` 服务永不缺席） |
+| `gcNarrative` | `true` | 无锚轮次是否走 scoped LLM 叙事；`false`=**纯机械、整条路径零 LLM** |
+| `gcNarrativeMaxTokens` | `1024` | 叙事生成的最大 token 数 |
+| `gcNarrativeMaxChars` | `4000` | 无锚轮次原文兜底的截断长度（字符） |
+
+**改配置后要重启 dsh web**——web 预设行会在下次启动时被自动刷新成新配置（幂等重写）。
+
+---
+
+## 7. 运维与卸载
+
+| 命令 | 作用 |
+|---|---|
+| `npx dsh-engram status` | 查看 host + 每个预设的接管状态与生效配置 |
+| `npx dsh-engram doctor` | status + 按缺口排序的下一步 |
+| `npx dsh-engram enable` | 手动重跑启动时的自动装配（通常 no-op） |
+| `npx dsh-engram revert` | 把全部预设还原成 stock `compaction-basic` 行 |
+
+- 仓库内 `npm run web-compaction:*` 是同一 CLI 的别名。
+- 每个被改写文件旁有 `agent.cordis.yml.engram.bak`（create-only，保留首次原件）。
+- **卸载 dsh-engram 之前先 `npx dsh-engram revert`**——否则预设里的 `dsh-engram/compaction` 行会
+  悬空，web 会话挂 loading。
+
+---
+
+## 8. 排障速查
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 自动压缩没触发，反而触发模型侧上下文溢出 | 运行中的进程还是**旧代码**（shrink-gate 回滚 bug） | **重启 dsh web** 加载修复（本教程最典型场景） |
+| 手动 `/compact` 报 `manual compaction did not commit cleanly` | 旧 Context GC 代码缺 provider/model 落盘，commit 阶段被拒 | 同上：重启加载新代码 |
+| 长会话自动压缩仍不提交（`start` 涨、`summary` 不涨） | 同上 / 或某些后端版本旧 | 重启；确认日志有 `compaction = Context GC` |
+| 日志 `… keeping the existing compaction service` | 同域已有 compaction provider（基座行未禁 / 双 provider） | 检查 patch 与预设行，避免重复注册 |
+| 日志 `web-provision … skipped (custom)` | 该预设是自定义/无 compaction 布局 | **设计如此**，不会碰 |
+| 日志 `dsh-compaction-basic unavailable` | 环境缺后端依赖 | 安装依赖；自动回退默认压缩，host 不崩 |
+| 极小被驱逐片段（span 小于 checkpoint 开销）不压缩 | harness 收缩闸门对**任何**后端一视同仁 | 属正常，没必要为几十 token 起 checkpoint |
+| 改配置后没变化 | web 行要重启才刷新 | 重启 dsh web |
+
+---
+
+## 9. FAQ
+
+- **有损吗？** 锚定细节**无损**（全部可通过工具重取）；只有无锚轮次走叙事/截断；所有原文仍留在
+  会话日志里，即使 checkpoint 被裁剪也能找回。
+- **会不会更烧 token？** 默认叙事只覆盖无锚轮次；需要完全零 LLM 就开 `gcNarrative:false`。
+- **和记忆面板 GC 什么关系？** 完全正交：面板 GC 管**存储有界**（TTL/超容量归档），Context GC 管
+  **上下文窗口**（compact 时驱逐）。
+- **是强制的吗？** 不是。`gcReplacesCompaction:false` 即回退 DSH 默认 LLM 摘要。
+- **什么时候触发？** 与默认 compact 完全一致：自动压力（约 80% 窗口阈值）→ 溢出 → 手动 `/compact`。
+- **之前失败过的会话有没有被弄坏？** 没有。收紧闸门/commit 失败都会**整事务回滚**并写
+  `compaction/end`（含 error），不留半成品；修复后直接再 `/compact` 即可。