dsh-engram 0.3.2 → 0.3.3

package/README.md

@@ -39,30 +39,39 @@ with one goal: **save tokens**.
   anchor immediately shows a relation; and `esr_dep` writes the dependency edge
   into both the task's `deps` (blocker logic) and the shared links table, making
   every task dependency a first-class visible edge in the graph.
-- **Decision-point triggers (P0-A/B + P2 + P3)** — firing where the todo→esr
-  routing decision actually happens and where tasks leak: a `tools/result`
-  watcher snapshots the native `todo_write` plan and, when the session has ≥ 2
-  pending todos that outnumber its active ESR tasks, the [ESR] block appends a
-  concrete `promote:` hint (`esr_task(name="…")`, once per session); recurring
-  failures (error memories with hits ≥ 2) earn a `root-cause:` task candidate;
-  a completed plan (pending → 0) earns a `close:` nudge for evidence-complete
-  tasks; long-unupdated active tasks get a `stale:` nudge; and the task list is
-  ordered READY-first with a `next: esr_close <id>` line, so the model can act
-  top-down. The same subscription feeds an in-memory mem-vs-esr counter that
-  restores `escalationHint` (the per-day `usage` table stopped being written
-  after assessment P3, silently orphaning the old nudge). Pure rules, zero
-  LLM, zero per-render I/O. Every hint line carries a stable `#suggest-*`
-  source tag (traceable in logs) and the same recorder measures hint → esr_*
-  conversion (shown once per session per hint, attributed when an esr tool
-  runs within a 10-minute window) — `GET /api/dsh-engram/triggerstats`
-  reports per-kind shown/converted/rate so you can see which nudge actually
-  moves behaviour.
+- **ESR trigger mechanism (pi-esr-aligned, hybrid: static protocol + frozen
+  snapshot + monotonically accumulated actionables + pull)** — prefix-cache
+  stability is the point. Teaching the model WHEN to use ESR is a **static
+  methodology** section (byte-identical every turn); the `[ESR]` block is a
+  deterministic **per-session frozen snapshot** (set at session start,
+  deterministically sorted, timestamps excluded, explicitly "WILL NOT
+  auto-refresh") **plus the session's monotonically accumulated actionables**:
+  the `promote:` / `root-cause:` / `close:` / `stale:` / `escalate:` lines are
+  APPENDED exactly once, the moment each matures, and stay frozen for the rest
+  of the session (never removed) — so the prefix changes only when genuinely
+  new decision-point info appears, never per-turn, while the timely nudges
+  (narrow funnel / recurring failure / work done / stale / balance) stay in
+  context. Live state is still **pulled** via `esr_status` (full deterministic
+  view + `since_revision` short "unchanged" response + derived actionables).
+  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.
 - **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
   `[ESR]` surface, and dangling link edges are dropped. The working set (active
   task refs, task memories, indexed hits) is never touched, and nothing is
   hard-deleted — every archived entry keeps its id and stays re-fetchable.
+- **Context GC (auto-GC = replaces DSH's auto-compact)** — NOT the memory-panel
+  GC. It takes over the host's `compaction` service and swaps DSH's lossy
+  LLM-summary compression for **mechanical eviction + re-fetch pointers**:
+  evicted turns are scanned for engram/ESR anchors (`#memory-id`, `tsk_*`,
+  `ent_*`, `file_path`) and replaced with one line "this detail lives at
+  `engram_detail` / `engram_recall` / the [ESR] block"; only un-provenanced
+  turns get a scoped LLM narrative (`gcNarrative`, default on, off = fully
+  mechanical). All six GC constraints hold (working-set-protected,
+  pointer-salience, no-provenance-no-evict…); any error falls back to the
+  default compressor — compaction is never broken.
 - **Web viewer** — a memory browser with benchmark-ish stats and a config card,
   built entirely on DSH's native settings slots (no third-party UI package).
 
@@ -272,9 +281,16 @@ npm run build:client
 | `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_ready` | List claimable tasks (no open blocker, unclaimed) | read |
+| `esr_status` | Pull live ESR state + derived hints (`since_revision` short "unchanged" response) | read |
 | `esr_gc` | Run the memory GC for the workspace (`dry_run:true` previews) | write |
 
-## Memory GC
+The `[ESR]` block is a frozen per-session snapshot and never auto-refreshes —
+call `esr_status` for the live truth.
+
+## GC: two planes — memory-panel reclamation + Context GC (replacing auto-compact)
+
+### Memory-panel reclamation (store maintenance)
 
 A scheduled sweep (`gcIntervalHours`, default 24h) plus a manual `esr_gc` /
 GUI button keeps the store bounded the pi-esr way — **mechanical, working-set
@@ -292,6 +308,67 @@ GC never touches the working set: memories referenced by an active task
 is hard-deleted — the report ends with re-fetch pointers for everything it
 archived, so archives are recoverable, not lost.
 
+### Context GC (replaces DSH's auto-compact)
+
+DSH's default context compression is a **lossy LLM full summary**
+(`compaction-basic`): evicted history is crushed into prose — un-queryable, and
+the summary itself burns tokens. dsh-engram's auto-GC replaces it:
+`ContextGcEngine extends BasicCompactionEngine` overrides the single
+`summarize()` hook and swaps the summary body for:
+
+1. **Scan** — the evicted messages are scanned for provenance anchors: memory
+   ids echoed by `engram_store`/`engram_recall`/`engram_detail`, `tsk_*`/`ent_*`
+   touched by `esr_*`, and `file_path` anchors (`esr_gc` and other management
+   calls are NOT anchors);
+2. **Pointer summary** — every evicted category carries an explicit re-fetch
+   call (`engram_detail(id: "…")` / `engram_recall(query)` / the [ESR] block /
+   `esr_ready`); the active working set is restated, never evicted;
+3. **Narrative safety net** — only un-provenanced turns (pure chat / reasoning)
+   get a scoped LLM summary (`gcNarrative`, default on; off = the whole path is
+   zero-LLM and un-provenanced turns are kept as truncated verbatim).
+
+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:
+  ```yaml
+  - id: compaction
+    name: cordis:group
+    group: true
+    isolate:
+      compaction: true
+      toolResultPruner: true
+    config:
+      - 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
+      - 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
+  ```
+
 ## Auto-capture policy
 
 Capture is deterministic and offline — it only sees tool *results*, never the
@@ -323,6 +400,11 @@ injected".
 What the model actually sees (rendered once per session, then frozen):
 
 ```
+ESR operating protocol (static, byte-identical every turn)
+  1. Before starting: esr_ready to see claimable work; esr_status for live state.
+  2. Multi-step work → esr_task (draft first); claim → esr_claim; finish → esr_close (all three gates).
+  state is the single source of truth: unsure → call esr_status.
+
 [ENGRAM] workspace: symbolic-index · 2 memories · 1 task(s) active · 0 links
 [D] 06-18 Decided: use sqlite-vec for retrieval #a2331d87
 [T] 06-18 Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref #tsk_8b26
@@ -331,6 +413,9 @@ drill: engram_store (user asks to remember) | engram_recall <query> | engram_det
 [ESR] tasks: 1 active / 1 stable
 - tsk_0d: Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref
 - closed: tsk_9a (RAG eval)  ·  +1
+snapshot from session start — WILL NOT auto-refresh; call esr_status for live state
+# this-session actionables (frozen)
+promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-promote
 ```
 
 Prefixes: `[D]` decision · `[E]` error · `[P]` procedure · `[F]` fact ·
@@ -367,6 +452,8 @@ Defaults are token-conscious; override any key via the profile patch
     gcEnabled: true          # scheduled memory GC
     gcIntervalHours: 24      # sweep cadence
     gcStableRetentionDays: 120  # stable tasks leave [ESR] after this
+    gcReplacesCompaction: true # Context GC: take over DSH auto-compact (false = keep the default LLM summarizer)
+    gcNarrative: true        # scoped LLM narrative for un-provenanced turns; false = fully mechanical (zero LLM)
     engramIndexOrder: 40    # systemPrompt section order (before tools band)
     esrOrder: 41
 ```
@@ -374,7 +461,7 @@ Defaults are token-conscious; override any key via the profile patch
 ## Development
 
 ```sh
-npm test            # 29 tests: core + web API + GC + usage-observability (node:test)
+npm test            # 152 tests: core + web API + GC + usage-observability + Context GC + ESR triggers (node:test)
 npm run eval        # offline recall + structure benchmark (deterministic)
 npm run build:client
 ```

package/README.zh.md

@@ -27,19 +27,24 @@
   `task --relates_to--> entity` 边（幂等），挂着领域锚点的任务立刻带关系；
   `esr_dep` 双写——依赖边同时进 `tasks[].deps`（blocker 逻辑）与 links 表，图谱里每条
   任务依赖都是一等可见的边。
-- **决策点触发（P0-A/B + P2 + P3）** — 在漏斗最窄处（todo 多、esr 少）与任务泄漏处（建了不关）
-  给模型侧触发：监听 `tools/result` 里的原生 `todo_write`，当会话 pending todo ≥ 2 且多于 active ESR
-  任务时，`[ESR]` 块追加带具体候选的 `promote:` 提示（`esr_task(name="…")`，每会话仅一次）；
-  复发失败（error hits≥2）给 `root-cause:` 任务候选；收工（todo 全部完成）给 `close:` 提示关证据齐的
-  任务；长期无更新的 active 任务给 `stale:` 提示；活动任务按 READY 优先排序并给 `next: esr_close`。
-  并用同一订阅维护进程内 mem-vs-esr 实时计数修复 `escalationHint` 的死数据源（评估 P3 移除了
-  per-call usage 写路径后原 nudge 已静默失效）。纯规则、零 LLM、零每轮 I/O；每条 nudge 带稳定 `#suggest-*` 来源标记，
-  且 recorder 计量「提示曝光 → esr_* 调用」转化（每会话每 kind 记一次曝光，
-  esr 工具 10 分钟窗口内调用即归因），`GET /api/dsh-engram/triggerstats`
-  返回各 kind 的 shown/converted/rate。
+- **ESR 触发机制（pi-esr 对齐，混合：静态协议 + 冻结快照 + 单调渐进 actionables + 拉取）** —
+  前缀缓存稳定是核心。模型「何时用 ESR」靠**静态方法论**（`engram:esr-method`，每轮逐字节相同）；
+  `[ESR]` 块 = 确定性**冻结快照**（会话开始定下、确定性排序、时间戳排除、明示 WILL NOT
+  auto-refresh）+ 本会话**单调渐进的 actionables**：`promote:/root-cause:/close:/stale:/escalate:`
+  在它们成熟的那一刻被**一次追加进块并冻结**（永不回撤）——前缀只在「真正出现新决策点信息」时变化、
+  绝不逐轮漂移，同时保留决策点提醒（漏斗最窄处 / 复发失败 / 收工 / stale / 平衡）。实时状态仍可
+  **拉取**：`esr_status`（全量视图 + `since_revision` 增量短响应 + 派生 actionables）。
+  recorder 由 `tools/result` 订阅喂入（actionables 的数据源）；P4 转化度量照常（`#suggest-*` 标记 +
+  10 分钟归因 + `GET /api/dsh-engram/triggerstats`）。纯规则、零 LLM。
 - **记忆 GC（pi-esr 约束）** — 定时、机械、只归档的回收：TTL 过期记忆归档、超容量工作区淘汰低价值条目、
   stable 任务超保留窗离开 `[ESR]` 表面、悬空链接边清理。工作集（active 任务引用 / 任务记忆 / 已入索引命中）
   永不触碰；**不硬删任何东西**——归档条目保留 id、始终可重取。
+- **Context GC（自动 GC = 替代 DSH 自动 compact）** — 不是记忆面板 GC：接管 DSH 自带的上下文压缩
+  （`compaction` 服务），把「有损 LLM 全量摘要」换成**机械驱逐 + 重取指针**——扫描被驱逐轮次里的
+  engram/ESR 锚（`#记忆id`、`tsk_*`、`ent_*`、`file_path`），只留一行「细节在 `engram_detail` /
+  `engram_recall` / `[ESR]` 里」；只有无锚轮次才走 scoped LLM 叙事兜底（`gcNarrative`，默认开、可关成纯机械）。
+  六条 GC 约束（working-set-protected / pointer-salience / no-provenance-no-evict…）全部落地；任何错误回退
+  默认压缩，永不破坏 compact。
 - **Web 查看器** — 一个带统计的记忆浏览器和配置卡片，完全构建在 DSH 原生设置槽位上（不碰任何第三方 UI 包）。
 
 ```
@@ -176,7 +181,7 @@ npm run build:client
 ## 测试与评测
 
 ```sh
-npm test    # 29 项单元测试（含 usage 滚动 / /stats 路由）
+npm test    # 152 项单元测试（含 usage 滚动 / /stats 路由 / Context GC / ESR 触发）
 npm run eval  # 离线召回 + 结构基准（确定性语料，跑真实 store/recall 路径）
 ```
 
@@ -199,9 +204,15 @@ npm run eval  # 离线召回 + 结构基准（确定性语料，跑真实 store/
 | `esr_task` | 创建任务实体（draft → active） | 写 |
 | `esr_close` | 按证据协议关闭任务（artifact + evaluation + memory_ref） | 写 |
 | `esr_link` | 在两个实体之间添加类型化关系（迷你图） | 写 |
+| `esr_ready` | 列出可认领任务（无 blocker、无人认领） | 读 |
+| `esr_status` | 拉取实时 ESR 状态 + 派生提示（`since_revision` 增量短响应） | 读 |
 | `esr_gc` | 运行本工作区的记忆 GC（`dry_run:true` 预览不落库） | 写 |
 
-## 记忆 GC
+`[ESR]` 块是每会话冻结快照，绝不中途刷新——要最新状态调 `esr_status`。
+
+## GC：两块——记忆面板回收 + Context GC（替代自动 compact）
+
+### 记忆面板回收（存储维护）
 
 定时回收（`gcIntervalHours`，默认 24h）+ `esr_gc` 手动触发 + GUI 按钮，按 pi-esr 方式把存储保持在
 有界内——**机械、工作集保护、只归档**：
@@ -215,6 +226,51 @@ GC 永不触碰工作集：active 任务 `memory_refs` 引用的记忆、task
 （`hits >= promoteHits`）。用 `esr_gc` + `dry_run: true` 先预览。**不硬删**——报告的末尾为所有
 归档项附上重取指针，归档可恢复、不是丢失。
 
+### Context GC（替换 DSH 自动 compact）
+
+DSH 默认的上下文压缩是**有损 LLM 全量摘要**（`compaction-basic`）：被驱逐的历史被压缩成散文，
+不可查询、摘要本身还烧 token。dsh-engram 的自动 GC 替代它：`ContextGcEngine extends
+BasicCompactionEngine` 只重写唯一的 `summarize()` 钩子，把摘要正文换成：
+
+1. **扫描**被驱逐消息的 provenance 锚——`engram_store`/`engram_recall`/`engram_detail` 回显的
+   `#记忆id`、`esr_*` 涉及的 `tsk_*`/`ent_*`、`file_path` 锚（`esr_gc` 等管理工具**不算**锚）；
+2. **指针摘要**：每条被驱逐类别都带显式重取调用（`engram_detail(id: "…")` / `engram_recall(query)`
+   / `[ESR]` 块 / `esr_ready`），active 工作集在摘要里**复述**不驱逐；
+3. **兜底叙事**：只有无锚轮次（纯对话/推理）才走 scoped LLM 摘要（`gcNarrative`，默认开；关掉后整条
+   路径零 LLM，无锚轮次截断原文保留）。
+
+触发时机完全跟随 DSH 现有 compact（step pressure / context-overflow / `/compact`）；锁、回放校验、
+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 生效：
+  ```yaml
+  - id: compaction
+    name: cordis:group
+    group: true
+    isolate:
+      compaction: true
+      toolResultPruner: true
+    config:
+      - id: engram-compaction       # ← 替换原 compaction-basic
+        name: dsh-engram/compaction
+        config:
+          gcReplacesCompaction: true   # 可选；false=该 session 用默认 LLM 摘要
+          gcNarrative: true
+      - id: command-compact
+        name: '@deepseek-ai/dsh-command-compact'
+      - id: tool-result-pruner
+        name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+        # 原有配置保留
+  ```
 
 ## 自动捕获策略
 
@@ -243,6 +299,11 @@ GC 永不触碰工作集：active 任务 `memory_refs` 引用的记忆、task
 模型实际看到的内容（每个会话渲染一次，然后冻结）：
 
 ```
+ESR 操作协议（静态，每轮逐字节相同）
+  1. 动工前：esr_ready 看可认领工作；esr_status 拿实时状态。
+  2. 多步工作 → esr_task（draft 起步）；动工 → esr_claim；收工 → esr_close（三证齐）。
+  state 是唯一真相：拿不准 state 就 call esr_status。
+
 [ENGRAM] workspace: symbolic-index · 2 memories · 1 task(s) active · 0 links
 [D] 06-18 Decided: use sqlite-vec for retrieval #a2331d87
 [T] 06-18 Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref #tsk_8b26
@@ -251,6 +312,9 @@ drill: engram_store (user asks to remember) | engram_recall <query> | engram_det
 [ESR] tasks: 1 active / 1 stable
 - tsk_0d: Retrieval upgrade — ACTIVE · gap: artifact, evaluation, memory_ref
 - closed: tsk_9a (RAG eval)  ·  +1
+snapshot from session start — WILL NOT auto-refresh; call esr_status for live state
+# this-session actionables (frozen)
+promote: 2 pending todo(s) vs 1 ESR task(s) — esr_task(name="…") #suggest-promote
 ```
 
 前缀：`[D]` 决定 · `[E]` 错误 · `[P]` 流程 · `[F]` 事实 · `[I]` 洞察 · `[H]` 交接 · `[T]` 任务。
@@ -281,6 +345,8 @@ drill: engram_store (user asks to remember) | engram_recall <query> | engram_det
     gcEnabled: true          # 定时记忆 GC
     gcIntervalHours: 24      # 回收节奏
     gcStableRetentionDays: 120  # 超过此天数的 stable 任务离开 [ESR]
+    gcReplacesCompaction: true # Context GC：接管 DSH 自动 compact（false=回退默认 LLM 压缩）
+    gcNarrative: true        # 无锚轮次走 scoped LLM 叙事；false=纯机械（零 LLM）
     engramIndexOrder: 40    # systemPrompt section 顺序（位于 tools 段之前）
     esrOrder: 41
 ```
@@ -288,7 +354,7 @@ drill: engram_store (user asks to remember) | engram_recall <query> | engram_det
 ## 开发
 
 ```sh
-npm test            # 21 个测试：核心 + Web API + GC（node:test）
+npm test            # 152 个测试：核心 + Web API + GC + Context GC + ESR 触发（node:test）
 npm run build:client
 ```
 

package/cordis.patch.yml

@@ -5,6 +5,18 @@
 # 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
 # web profile (dsh-base x dsh-web-app) already mounts them.
+
+# dsh-engram REPLACES the host-plane auto-compact: its Context GC engine
+# provides the `compaction` service (see docs/PROPOSAL-contextgc.zh.md).
+# cordis refuses two sibling rows registering the same service key, so the
+# base row must be disabled here — this patch layer wins because bundle patch
+# layers apply in bundle order and dsh-engram loads after dsh-base. Removing
+# 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.
+- id: compaction-basic
+  disabled: true
+
 - insert:
     - id: engram
       name: dsh-engram

package/lib/api.js

@@ -477,10 +477,33 @@ export function makeEngramRoutes(service) {
     handler: (req, res) => guard(req, res, method, handler),
   });
 
+  /** One exact route serving several methods on the same path. The host
+      webServer's exact table is keyed by pathname only — two separate routes
+      on `/tasks` (GET + POST) collide and the second register() throws
+      "duplicate route", which the mount silently skips. So a shared path must
+      be a single route that dispatches on req.method itself. */
+  const makeUnion = (path, byMethod) => {
+    const methods = Object.keys(byMethod);
+    return {
+      kind: "exact",
+      path: `${API_PREFIX}${path}`,
+      method: methods,
+      handler: (req, res) => {
+        const m = String(req.method ?? "GET").toUpperCase();
+        const inner = byMethod[m];
+        if (inner === void 0) {
+          writeError(res, 405, "method not allowed");
+          return;
+        }
+        return guard(req, res, m, inner);
+      },
+    };
+  };
+
   return [
     make("GET", "/overview", overview),
     make("GET", "/memories", memories),
-    make("GET", "/tasks", tasks),
+    makeUnion("/tasks", { GET: tasks, POST: createTask }),
     make("GET", "/links", links),
     make("GET", "/nodes", entities),
     make("GET", "/stats", stats),
@@ -492,7 +515,6 @@ export function makeEngramRoutes(service) {
     make("GET", "/config", readConfig),
     make("POST", "/memories/archive", archive),
     make("POST", "/memories/delete", remove),
-    make("POST", "/tasks", createTask),
     make("POST", "/tasks/close", closeTask),
     make("POST", "/gc", gcRun),
   ];

package/lib/client.js

@@ -329,6 +329,7 @@ function EngramTaskDock({ sessionId, useSessions, useWorkspaces, useProjection,
   const [expandedId, setExpandedId] = (0, import_react2.useState)(null);
   const [taskPage, setTaskPage] = (0, import_react2.useState)(0);
   const [promoted, setPromoted] = (0, import_react2.useState)(/* @__PURE__ */ new Set());
+  const [promoteNote, setPromoteNote] = (0, import_react2.useState)(null);
   const [promoteBusy, setPromoteBusy] = (0, import_react2.useState)(false);
   const [toolStats, setToolStats] = (0, import_react2.useState)(null);
   const [closeArtifact, setCloseArtifact] = (0, import_react2.useState)("");
@@ -456,18 +457,26 @@ function EngramTaskDock({ sessionId, useSessions, useWorkspaces, useProjection,
   const promoteAll = async () => {
     if (!effWs || promoteBusy || toPromote.length === 0) return;
     setPromoteBusy(true);
+    setPromoteNote(null);
     const done = [];
+    const failed = [];
     for (const it of toPromote) {
       try {
         await api.createTask(effWs, it.content, "\u6E90\u81EA\u4F1A\u8BDD\u8BA1\u5212\uFF08todo_write \u4E00\u952E\u6C89\u6DC0\uFF09");
         done.push(it.content);
       } catch {
+        failed.push(it.content);
       }
     }
     if (done.length > 0) {
       setPromoted((prev) => /* @__PURE__ */ new Set([...prev, ...done]));
       void load();
     }
+    if (failed.length > 0) {
+      setPromoteNote(
+        failed.length === done.length ? `\u6C89\u6DC0\u5931\u8D25\uFF1A${failed.length} \u9879\u672A\u80FD\u521B\u5EFA\uFF08\u5DE5\u4F5C\u533A\u5DF2\u6EE1\u6216\u670D\u52A1\u4E0D\u53EF\u8FBE\uFF09\uFF0C\u8BF7\u5237\u65B0\u540E\u91CD\u8BD5` : `\u90E8\u5206\u5931\u8D25\uFF1A${failed.length}/${toPromote.length} \u9879\u672A\u80FD\u521B\u5EFA`
+      );
+    }
     setPromoteBusy(false);
   };
   const submitClose = async (task) => {
@@ -726,6 +735,10 @@ function EngramTaskDock({ sessionId, useSessions, useWorkspaces, useProjection,
               /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "ed-btn", style: { ...btn, ...btnSolid, padding: "3px 9px", fontSize: 11.5 }, disabled: promoteBusy || toPromote.length === 0, onClick: () => void promoteAll(), title: "\u628A\u672C\u8F6E\u5F85\u529E\u8F6C\u6210 ESR \u4EFB\u52A1\u8349\u7A3F\uFF08\u8DE8\u4F1A\u8BDD\u4FDD\u7559\uFF09", children: promoteBusy ? "\u2026" : promoted.size > 0 ? toPromote.length > 0 ? `\u5DF2\u6C89\u6DC0 ${promoted.size} \u9879 \xB7 \u518D\u6C89\u6DC0 ${toPromote.length} \u9879` : `\u5DF2\u6C89\u6DC0 ${promoted.size} \u9879` : `\u6C89\u6DC0\u5230 ESR\uFF08${toPromote.length} \u9879\uFF09` }),
               /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { style: { fontSize: 10.5, color: "var(--dsw-alias-label-dimmed, var(--dsh-color-muted-weak, #9ca3af))" }, children: "\u8F6C\u8349\u7A3F \xB7 \u8DE8\u4F1A\u8BDD\u95ED\u73AF" })
             ] }),
+            promoteNote && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { fontSize: 11, color: "#dc2626", lineHeight: 1.4 }, role: "alert", children: [
+              "\u26A0 ",
+              promoteNote
+            ] }),
             activeTasks.length === 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { style: { display: "flex", gap: 6, alignItems: "flex-start", fontSize: 11.5, lineHeight: 1.5, color: "var(--dsw-alias-label-dimmed, var(--dsh-color-muted, #6b7280))", paddingTop: 2 }, children: [
               /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "aria-hidden": true, style: { color: badgeEsr.color }, children: "\u21B3" }),
               /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { children: [
@@ -3330,10 +3343,11 @@ var ADVANCED_GROUPS = [
   {
     id: "retention-adv",
     title: "\u751F\u547D\u5468\u671F\u4E0E GC\uFF08\u9AD8\u7EA7\uFF09",
-    description: "\u5BB9\u91CF\u4E0A\u9650\u4E0E\u5B9A\u671F\u56DE\u6536",
+    description: "\u5BB9\u91CF\u4E0A\u9650\u4E0E\u5B9A\u671F\u56DE\u6536\uFF08\u81EA\u52A8 GC = \u66FF\u4EE3 DSH \u81EA\u52A8 compact\uFF09",
     fields: [
       { key: "maxMemoriesPerWorkspace", label: "\u5DE5\u4F5C\u533A\u8BB0\u5FC6\u4E0A\u9650", kind: "num", min: 0, max: 1e4 },
       { key: "gcEnabled", label: "\u8BB0\u5FC6 GC", hint: "\u5B9A\u65F6\u56DE\u6536\uFF08\u8FC7\u671F/\u8D85\u5BB9\u91CF/stable \u8D85\u7A97/\u60AC\u7A7A\u94FE\u63A5\uFF09", kind: "bool" },
+      { key: "gcNarrative", label: "Context GC \u53D9\u4E8B\u515C\u5E95", hint: "\u81EA\u52A8 compact \u65F6\u65E0\u951A\u8F6E\u6B21\u7528 LLM \u6458\u8981\uFF1B\u5173\u6389=\u7EAF\u673A\u68B0\uFF08\u96F6 LLM\uFF09", kind: "bool" },
       { key: "gcStableRetentionDays", label: "stable \u4EFB\u52A1\u4FDD\u7559\uFF08\u5929\uFF09", hint: "\u8D85\u7A97\u540E\u7531 GC \u5F52\u6863\u3001\u79BB\u5F00 [ESR] \u8868\u9762", kind: "num", min: 0, max: 3650 },
       { key: "verifyArtifact", label: "\u6821\u9A8C artifact \u5B58\u5728", hint: "esr_close \u7684 artifact \u987B\u5728\u5DE5\u4F5C\u533A\u78C1\u76D8\u4E0A\u771F\u5B9E\u5B58\u5728\uFF08URL \u8C41\u514D\uFF09\uFF1Bforce:true/\u5173\u6389\u53EF\u8DF3\u8FC7", kind: "bool" }
     ]

package/lib/compaction.js

@@ -0,0 +1,85 @@
+/**
+ * dsh-engram — Context GC as a mountable HOST plugin entry (agent-preset row).
+ *
+ * Web/agent-preset compositions keep compaction on the AGENT plane: the
+ * `standard` preset (and friends) mount `@deepseek-ai/dsh-compaction-basic`
+ * inside a `compaction` group carrying its own isolate realm. A host-plane row
+ * cannot reach that realm, so replacing the default summarizer per-session
+ * needs a row that can be listed IN the preset's `compaction` group:
+ *
+ * ```yaml
+ * - id: compaction
+ *   name: cordis:group
+ *   group: true
+ *   isolate:
+ *     compaction: true
+ *     toolResultPruner: true
+ *   config:
+ *     - id: engram-compaction
+ *       name: dsh-engram/compaction        # this entry
+ *     - id: command-compact
+ *       name: '@deepseek-ai/dsh-command-compact'
+ *     ...
+ * ```
+ *
+ * Config (all optional): `gcReplacesCompaction` (true → Context GC; false →
+ * plain BasicCompactionEngine), `gcNarrative`, `gcNarrativeMaxTokens`,
+ * `gcNarrativeMaxChars`. Values default to the plugin DEFAULTS.
+ *
+ * The engine reads engram/ESR state through the storage-domain service shared
+ * with the host plane (best-effort reads for pointer classification — the
+ * entry never writes).
+ */
+import { openEngramDomain } from "./store.js";
+import { loadCompactionEngine, collectPointerContext } from "./context-gc.js";
+import { workspaceKey as wk } from "./util.js";
+
+export const name = "dsh-engram-compaction";
+export const inject = ["llm", "tokenMeter", "sessions"];
+
+/** One cached domain per storage-domain service (read-only for compaction). */
+const domains = new WeakMap();
+
+async function domainFor(ctx) {
+  const storageDomain = ctx.get("storageDomain");
+  if (!storageDomain) return null;
+  let domain = domains.get(storageDomain);
+  if (!domain) {
+    domain = await openEngramDomain(storageDomain).catch(() => null);
+    if (domain) domains.set(storageDomain, domain);
+  }
+  return domain;
+}
+
+export function apply(ctx, config = {}) {
+  const mode = config.gcReplacesCompaction === false ? "default" : "context-gc";
+  const deps =
+    mode === "context-gc"
+      ? {
+          narrativeEnabled: config.gcNarrative !== false,
+          narrativeMaxTokens: config.gcNarrativeMaxTokens ?? 1024,
+          narrativeMaxChars: config.gcNarrativeMaxChars ?? 4000,
+          readWorkspace: async (workspace, report) => {
+            if (!workspace) return null;
+            const domain = await domainFor(ctx);
+            if (!domain) return null;
+            return collectPointerContext(domain, wk(workspace), report);
+          },
+        }
+      : {};
+
+  return loadCompactionEngine(ctx, { auto: true }, deps, { mode })
+    .then((Engine) => {
+      if (!Engine) {
+        ctx.logger?.warn?.("engram context-gc: dsh-compaction-basic unavailable — no compaction engine");
+        return;
+      }
+      new Engine();
+      ctx.logger?.info?.(
+        `engram context-gc: compaction = ${mode === "context-gc" ? "Context GC (mechanical eviction + re-fetch pointers)" : "default LLM summarizer (gcReplacesCompaction:false)"}`,
+      );
+    })
+    .catch((error) => {
+      ctx.logger?.warn?.(`engram context-gc mount failed: ${String(error)}`);
+    });
+}