dsh-memoir 0.5.1 → 0.5.3

package/README.en.md

@@ -81,9 +81,11 @@ need long-tail history? memoir_read (local relevance-ranked recall)
 
 **Session Snapshot freezing semantics**: one session's injected text is built once and frozen (stable prompt prefix, maximizing prompt-prefix cache hits); the current session does not re-consume memory it just wrote, and a new session rebuilds and sees the latest memory. Since v0.4.2, when there is no unique session identity (session.id / agent.id), freezing is skipped — a cache miss beats wrongly reusing another session's snapshot.
 
-## v0.5.1 lifecycle completion and rc8 compatibility
+## v0.5.3 Web-configurable auto-distill and rc2 compatibility
 
-- The development and peer-dependency baseline is `@deepseek-ai/dsh-* 0.1.0-rc.8`.
+- The development and peer-dependency baseline is `@deepseek-ai/dsh-* 0.1.1-rc.2`.
+- Auto-distill now supports per-agent worked-turn intervals, time cooldowns, and tool-call thresholds; defaults `1 / 0 / 1` preserve prior behavior.
+- The Web panel now includes Auto-distill Settings for enabling/disabling and editing those three parameters. Saves apply to subsequent turns immediately and persist in `~/.dsh/dsh-memoir.settings.json`; one action removes the Web override and restores the profile values captured at startup.
 - Store format v3 migrates v2 entries without changing their `id`, content, or timestamp. The first mutation materializes `importance`, `pinned`, `status`, `supersedes`, and `tags`; startup reads do not rewrite old files.
 - Retrieval defaults to `active`. Archived and superseded history is retained and can be inspected from the Web panel. Explicit `supersedes` marks its targets as superseded; history is never deleted automatically.
 - Agents can use `memoir_update` to edit an entry's section, title, content, and lifecycle in place; the Web panel also supports editing, pinning, marking superseded, archiving, and restoring.
@@ -116,11 +118,12 @@ Curated-query Top-5 hit rate: 100% (quality gate ≥ 90%, see `test/recall-quali
 
 ## GUI
 
-The v0.4 Project / Global / Search / Add / Delete / Diagnostics architecture is kept; since v0.4.2:
+The v0.4 Project / Global / Search / Add / Delete / Diagnostics architecture is kept and extended:
 
 - **Search unified on RetrievalEngine**: a non-empty query calls `GET /api/dsh-memoir/search` — the same BM25 ranking as the agent's `memoir_read` — results ordered by relevance with scores shown
 - **Hot Memory Inspector**: expand to see the Hot Memory that will actually be injected for the current workspace (Actions / Lessons / Recent state) — i.e. "what exactly the next session inherits"
 - **Retrieval Diagnostics**: Retrieval Index (docs/terms/epoch), Query Cache (hits/misses/evictions/hit rate/size/capacity), Last Query (latency/returned), Session Snapshot (hash/createdAt/storeRevision)
+- **Auto-distill Settings (v0.5.3)**: enable or disable auto-distill and edit the worked-turn interval, cooldown minutes, and minimum tool calls in the panel; validated saves persist and apply immediately without restarting DSH
 
 ## Screenshots
 
@@ -148,6 +151,7 @@ The v0.4 Project / Global / Search / Add / Delete / Diagnostics architecture is
 
 ```text
 ~/.dsh/dsh-memoir.json        ← structured JSON (single source of truth / SSOT)
+~/.dsh/dsh-memoir.settings.json ← auto-distill overrides saved by the Web panel
 <workspace>/PROJECT_MEMORY.md ← human-readable projection regenerated from the JSON (git-friendly)
 
 No cloud memory DB · No embedding API · No vector DB
@@ -167,6 +171,9 @@ Add a `config` block on the plugin row in `cordis.patch.yml` (all optional; defa
         enabled: true            # master switch (tools, routes, prompt section)
         announceToAgent: true    # system-prompt announcement section
         autoDistill: true        # auto distill reminder after each worked turn
+        autoDistillEvery: 1      # remind at most once per N worked turns
+        autoDistillCooldownMin: 0 # require M minutes between successful reminders
+        autoDistillMinTools: 1   # triggering turn must contain at least K tool calls
         hotMemoryTokens: 900     # Hot Memory target tokens
         hotMemoryMaxTokens: 1200 # Hot Memory hard ceiling (never exceeded)
         readDefaultLimit: 8      # memoir_read default result count
@@ -175,6 +182,10 @@ Add a `config` block on the plugin row in `cordis.patch.yml` (all optional; defa
         queryCacheSize: 128      # ranked-query LRU cache size
 ```
 
+The three auto-distill frequency conditions are combined with AND and isolated per agent. Idle, aborted, subagent, and prior-`memoir_record` turns do not advance the interval. A worked turn below `autoDistillMinTools` advances the interval but cannot trigger by itself. Cooldown changes only after a successful steer.
+
+The auto-distill fields in `cordis.patch.yml` are startup defaults. Since v0.5.3, the Auto-distill Settings section at the bottom of the Memory panel can override them: saving atomically writes `~/.dsh/dsh-memoir.settings.json`, and subsequent turns read the new policy immediately. Restore Startup Config removes that override and returns to the profile values resolved when the plugin mounted. Other Hot Memory, recall, and cache settings remain profile-managed.
+
 ## Design Trade-offs
 
 - **Bounded vs full injection**: v0.3 injected the full history into the prompt and it kept growing; v0.4+ injects only budgeted Hot Memory, with long-tail history recalled on demand. Token benchmarks below.
@@ -183,6 +194,7 @@ Add a `config` block on the plugin row in `cordis.patch.yml` (all optional; defa
 - **Multi-process safety**: store record/remove runs inside a cross-process critical section on `~/.dsh/dsh-memoir.lock` (exclusive O_EXCL creation with timeout); the section force-reloads from disk before mutating, so two interleaved DSH processes lose no updates (v0.4.2).
 - **Windows paths**: canonical keys are fully lowercased (`C:\A` / `c:\a\` / `C:/A` share one bucket) while display paths keep the original casing (v0.4.2).
 - **GUI and Agent share one engine**: panel search and `memoir_read` use the same RetrievalEngine instead of separate filter logic (v0.4.2).
+- **Auto-distill cadence**: the default still reminds after every worked turn; research-heavy sessions can combine interval, cooldown, and activity thresholds and tune them immediately from the Web panel (v0.5.3).
 
 ## Use Cases
 
@@ -213,7 +225,7 @@ Each plugin has its own focus — pick per need; no "which is stronger" narrativ
 pnpm install          # install devDeps (typescript, esbuild, @deepseek-ai/* type packages)
 pnpm run build        # tsc builds the host + esbuild builds the client bundle
 pnpm run typecheck    # full type check (src + test)
-pnpm test             # 142 tests: store (incl. multi-process lock) / snapshot / selector / retrieval / tools / routes / auto-distill / integration / client pure logic / bundle protocol & purity / release notes
+pnpm test             # 154 tests: store (incl. multi-process lock) / settings / snapshot / selector / retrieval / tools / routes / auto-distill / integration / client pure logic / bundle protocol & purity / release notes
 npm run bench         # benchmark (100/1k/10k/100k entries); results written to bench/report.md
 ```
 
@@ -230,7 +242,7 @@ v0.4.2 benchmark summary (node v22.23.2, budget 900/1200 tokens; full report in
 
 ## Implementation
 
-- **Full-stack TypeScript**: `src/host/*.ts` (store / tools / retrieval / selector / snapshot / routes / autodistill / index — tsc emits `lib/*.js`) + `src/client/*.ts(x)` (esbuild emits the `lib/client.js` closure-factory bundle).
+- **Full-stack TypeScript**: `src/host/*.ts` (store / settings / tools / retrieval / selector / snapshot / routes / autodistill / index — tsc emits `lib/*.js`) + `src/client/*.ts(x)` (esbuild emits the `lib/client.js` closure-factory bundle).
 - **Two-sided plugin**: the host half registers the agent tools, `/api/dsh-memoir` routes, the `agent/turn-stopping` auto-distill listener, and the per-project system-prompt injection section; the client half renders the panel. Runtime deps are official NPM SDK packages only.
 - Mounted via the `dsh.bundle.patch` manifest (`insert` row in `cordis.patch.yml`); no DSH source changes.
 - Auto-distill safety boundaries: top-level sessions only (subagents / nested delegations skipped), turns with tool activity that haven't recorded yet, aborted turns skipped, at most one steer per turn.
@@ -247,7 +259,7 @@ Bug reports must include screenshot / log evidence, a smoke test, code reference
 
 ## Release
 
-Current stable release: **v0.5.1** (2026-08-20) · [GitHub Release](https://github.com/Qinling-Melon-Farmers/dsh-memoir/releases/tag/v0.5.1) · [npm](https://www.npmjs.com/package/dsh-memoir/v/0.5.1). Full history is in [CHANGELOG.md](./CHANGELOG.md).
+Current stable release: **v0.5.3** (2026-08-22) · [GitHub Release](https://github.com/Qinling-Melon-Farmers/dsh-memoir/releases/tag/v0.5.3) · [npm](https://www.npmjs.com/package/dsh-memoir/v/0.5.3). Full history is in [CHANGELOG.md](./CHANGELOG.md).
 
 Every version keeps Chinese and English release notes in sync. GitHub Releases show Chinese by default and place the English notes in a collapsible `English` section.
 

package/README.md

@@ -81,9 +81,11 @@ memoir_record 沉淀工作 / 教训 / 下一步
 
 **Session Snapshot 冻结语义**：同一 session 的注入文本只构建一次并冻结（prompt 前缀稳定，最大化 prompt-prefix cache 命中）；当前 session 不重新消费自己刚写的记忆，新 session 重建并看到最新记忆。v0.4.2 起，没有唯一会话身份（session.id / agent.id）时**不做冻结**——宁可 cache miss，不可跨 session 错复用旧快照。
 
-## v0.5.1 生命周期完成与 rc8 兼容性
+## v0.5.3 Web 可调自动收尾与 rc2 兼容性
 
-- 当前开发基线为 `@deepseek-ai/dsh-* 0.1.0-rc.8`；peer dependency 与开发依赖已统一到 rc8。
+- 当前开发基线为 `@deepseek-ai/dsh-* 0.1.1-rc.2`；peer dependency 与开发依赖已统一到 rc2。
+- 自动收尾支持按 agent 配置 worked-turn 间隔、时间冷却和工具调用阈值；默认值 `1 / 0 / 1` 与旧版行为一致。
+- Web 面板新增「自动蒸馏设置」，可启停并修改上述三个参数；保存后立即作用于后续回合，并持久化到 `~/.dsh/dsh-memoir.settings.json`。可一键删除 Web 覆盖并恢复本次启动时的 profile 配置。
 - 存储格式从 v2 迁移到 v3：旧条目保持原有 `id`、内容和时间，首次变更时补齐 `importance`、`pinned`、`status`、`supersedes` 与 `tags`；启动读取不会重写旧文件。
 - 默认只召回 `active` 条目；归档和被替代条目保留在历史中，可在 Web 面板切换状态查看。显式 `supersedes` 会把目标条目标记为 `superseded`，不会自动删除历史。
 - Agent 可用 `memoir_update` 原地编辑条目的分类、标题、正文和生命周期；Web 面板也支持编辑、置顶、标记过时、归档与恢复。
@@ -116,11 +118,12 @@ curated 查询 Top-5 命中率 100%（质量门禁 ≥90%，见 `test/recall-qua
 
 ## GUI
 
-保留 v0.4 的 Project / Global / Search / Add / Delete / Diagnostics 架构，v0.4.2 起：
+保留 v0.4 的 Project / Global / Search / Add / Delete / Diagnostics 架构，并持续扩展：
 
 - **搜索统一走 RetrievalEngine**：query 非空时面板调用 `GET /api/dsh-memoir/search`，与 agent 的 `memoir_read` 共用同一套 BM25 排序，结果按相关性排列并显示分数
 - **Hot Memory Inspector**：展开查看当前工作区实际会被注入的 Hot Memory（Actions / Lessons / Recent state），即「下一会话到底自动继承什么」
 - **Retrieval Diagnostics**：Retrieval Index（docs/terms/epoch）、Query Cache（hits/misses/evictions/hit rate/size/capacity）、Last Query（latency/returned）、Session Snapshot（hash/createdAt/storeRevision）
+- **自动蒸馏设置（v0.5.3）**：面板内启停 auto-distill，编辑 worked-turn 间隔、冷却分钟数和最低工具调用数；严格校验后持久化并即时应用，无需重启 DSH
 
 ## 界面预览
 
@@ -148,6 +151,7 @@ curated 查询 Top-5 命中率 100%（质量门禁 ≥90%，见 `test/recall-qua
 
 ```text
 ~/.dsh/dsh-memoir.json   ← 结构化 JSON（唯一事实源 / SSOT）
+~/.dsh/dsh-memoir.settings.json ← Web 面板保存的自动蒸馏覆盖设置
 <工作区>/PROJECT_MEMORY.md ← 由 JSON 重新生成的人类可读投影（git 友好）
 
 No cloud memory DB · No embedding API · No vector DB
@@ -167,6 +171,9 @@ JSON 是 source of truth，Markdown 是 generated projection：面板、工具
         enabled: true            # 总开关（工具、路由、注入段）
         announceToAgent: true    # system prompt 公告段
         autoDistill: true        # 每轮有实际工作的回合结束自动提醒归纳
+        autoDistillEvery: 1      # 每 N 个 worked turn 最多提醒一次
+        autoDistillCooldownMin: 0 # 两次成功提醒之间至少间隔 M 分钟
+        autoDistillMinTools: 1   # 触发提醒的 turn 至少包含 K 次工具调用
         hotMemoryTokens: 900     # Hot Memory 目标 token 数
         hotMemoryMaxTokens: 1200 # Hot Memory 硬上限（永不超过）
         readDefaultLimit: 8      # memoir_read 默认返回条数
@@ -175,6 +182,10 @@ JSON 是 source of truth，Markdown 是 generated projection：面板、工具
         queryCacheSize: 128      # 排序查询的 LRU 缓存大小
 ```
 
+三个 auto-distill 频率条件按 AND 关系判定并按 agent 隔离。idle、aborted、subagent、已调用 `memoir_record` 的 turn 不推进间隔计数；低于 `autoDistillMinTools` 的 worked turn 会推进间隔，但自身不能触发提醒。冷却只在 steer 成功后更新。
+
+`cordis.patch.yml` 中的 auto-distill 字段是启动默认值。v0.5.3 起，可在记忆面板底部展开「自动蒸馏设置」进行修改：保存会原子写入 `~/.dsh/dsh-memoir.settings.json`，后续 turn 立即读取新策略；「恢复启动配置」会删除该覆盖文件并回到本次插件挂载时解析出的 profile 值。其余 Hot Memory、召回和缓存参数仍由 profile 配置。
+
 ## Design Trade-offs
 
 - **有界注入 vs 全量注入**：v0.3 把完整历史注入 prompt，越用越膨胀；v0.4+ 只注入预算内的 Hot Memory，长尾历史按需召回。token 基准见下方 Benchmark。
@@ -183,6 +194,7 @@ JSON 是 source of truth，Markdown 是 generated projection：面板、工具
 - **多进程安全**：store 的 record/remove 走 `~/.dsh/dsh-memoir.lock` 跨进程临界区（O_EXCL 独占创建 + 超时），临界区内强制从磁盘重读再改，两个 DSH 进程交错写入不丢更新（v0.4.2）。
 - **Windows 路径**：canonical key 全小写（`C:\A` / `c:\a\` / `C:/A` 一个桶），display path 保留原始大小写（v0.4.2）。
 - **GUI 与 Agent 同源**：面板搜索与 `memoir_read` 共用 RetrievalEngine，不再各写一套过滤逻辑（v0.4.2）。
+- **自动收尾节奏**：默认仍逐 worked turn 提醒；研究型会话可组合轮次间隔、冷却与活动阈值降低打扰，并从 Web 面板即时调节（v0.5.3）。
 
 ## Use Cases
 
@@ -213,7 +225,7 @@ JSON 是 source of truth，Markdown 是 generated projection：面板、工具
 pnpm install          # 安装 devDeps（typescript、esbuild、@deepseek-ai/* 类型包）
 pnpm run build        # tsc 构建 host + esbuild 构建 client bundle
 pnpm run typecheck    # 全量类型检查（src + test）
-pnpm test             # 142 项测试：store（含多进程锁） / snapshot / selector / retrieval / tools / routes / 自动收尾 / 集成 / client 纯逻辑 / bundle 协议与纯净性 / 发布说明
+pnpm test             # 154 项测试：store（含多进程锁） / settings / snapshot / selector / retrieval / tools / routes / 自动收尾 / 集成 / client 纯逻辑 / bundle 协议与纯净性 / 发布说明
 npm run bench         # benchmark（100/1k/10k/100k 条目），结果写入 bench/report.md
 ```
 
@@ -230,7 +242,7 @@ v0.4.2 benchmark 摘要（node v22.23.2，budget 900/1200 tokens；完整报告
 
 ## 实现说明
 
-- **TypeScript 全栈**：`src/host/*.ts`（store / tools / retrieval / selector / snapshot / routes / autodistill / index，tsc 构建出 `lib/*.js`）+ `src/client/*.ts(x)`（esbuild 打出 `lib/client.js` 闭包工厂 bundle）。
+- **TypeScript 全栈**：`src/host/*.ts`（store / settings / tools / retrieval / selector / snapshot / routes / autodistill / index，tsc 构建出 `lib/*.js`）+ `src/client/*.ts(x)`（esbuild 打出 `lib/client.js` 闭包工厂 bundle）。
 - **双面插件**：host 半注册 agent 工具、`/api/dsh-memoir` 路由、`agent/turn-stopping` 自动收尾监听与按项目求值的 system prompt 注入段；client 半提供面板。运行时仅依赖官方 NPM SDK。
 - 通过 `dsh.bundle.patch` manifest（`cordis.patch.yml` 的 `insert` 行）挂载，不改 DSH 源码。
 - 自动收尾安全边界：仅顶级会话（跳过 subagent / 嵌套委托）、仅「有工具调用且未记录过」的回合、已中止回合不打扰、每回合至多一次。
@@ -248,7 +260,7 @@ PR 请先提 Issue 讨论。
 
 ## Release
 
-当前稳定版：**v0.5.1**（2026-08-20） · [GitHub Release](https://github.com/Qinling-Melon-Farmers/dsh-memoir/releases/tag/v0.5.1) · [npm](https://www.npmjs.com/package/dsh-memoir/v/0.5.1)。完整历史见 [CHANGELOG.md](./CHANGELOG.md)。
+当前稳定版：**v0.5.3**（2026-08-22） · [GitHub Release](https://github.com/Qinling-Melon-Farmers/dsh-memoir/releases/tag/v0.5.3) · [npm](https://www.npmjs.com/package/dsh-memoir/v/0.5.3)。完整历史见 [CHANGELOG.md](./CHANGELOG.md)。
 
 每个版本的更新日志均同步维护中英文；GitHub Release 默认展开中文，英文说明收纳在可折叠的 `English` 区域。
 

package/cordis.patch.yml

@@ -16,6 +16,11 @@
 #     enabled: true          # master switch (tools, routes, prompt section)
 #     announceToAgent: true  # system-prompt announcement
 #     autoDistill: true      # steer a distill prompt after each worked turn
+#     autoDistillEvery: 1    # remind at most once per N worked turns
+#     autoDistillCooldownMin: 0 # minimum minutes between successful reminders
+#     autoDistillMinTools: 1 # minimum tool calls on the triggering turn
+# These auto-distill values are startup defaults. v0.5.3+ can persist a live
+# Web-panel override in ~/.dsh/dsh-memoir.settings.json and restore defaults.
 - insert:
     - id: memoir
       name: dsh-memoir

package/lib/autodistill.d.ts

@@ -19,11 +19,13 @@ export interface TurnEventLike {
     type: string;
     data?: unknown;
 }
-/** Scan the tail of a session log for one turn's tool activity. */
-export declare function turnActivity(events: readonly TurnEventLike[], turn: number): {
+export interface TurnActivity {
     worked: boolean;
     recorded: boolean;
-};
+    toolCalls: number;
+}
+/** Scan the tail of a session log for one turn's tool activity. */
+export declare function turnActivity(events: readonly TurnEventLike[], turn: number): TurnActivity;
 /** The agent surface the turn-stopping listener needs. */
 export interface AutoDistillAgentLike {
     id: string;
@@ -38,11 +40,21 @@ export interface AutoDistillAgentLike {
 }
 /** Subagent sessions (and any nested delegation) never get distilled. */
 export declare function isSubagentSession(agent: AutoDistillAgentLike): boolean;
-/** Per-agent memory of turns already steered (with pruning). */
+export interface AutoDistillPolicy {
+    every: number;
+    cooldownMs: number;
+    minTools: number;
+}
+/** Per-agent frequency, cooldown, and duplicate-turn state (with pruning). */
 export declare class AutoDistillGate {
-    private steered;
-    /** Claim a turn for steering; false when already claimed (or pruned-out). */
-    consume(agentId: string, turn: number): boolean;
+    private states;
+    /**
+     * Consume one eligible worked turn and decide whether all policy conditions
+     * are ready. Duplicate events never advance the worked-turn counter.
+     */
+    consume(agentId: string, turn: number, toolCalls: number, policy: AutoDistillPolicy, now: number): boolean;
+    /** Record a successful steer; failed steer attempts do not start cooldown. */
+    recordSteer(agentId: string, now: number): void;
     /** Drop all state for one agent (disposal hygiene). */
     forget(agentId: string): void;
 }
@@ -62,4 +74,14 @@ export interface AutoDistillWire {
  */
 export declare function installAutoDistill(wire: AutoDistillWire, options: {
     enabled: () => boolean;
+    every?: number;
+    cooldownMin?: number;
+    minTools?: number;
+    /** Optional live policy source used by the Web settings panel. */
+    policy?: () => {
+        every?: number;
+        cooldownMin?: number;
+        minTools?: number;
+    };
+    now?: () => number;
 }): () => void;

package/lib/autodistill.js

@@ -19,8 +19,8 @@ export const DISTILL_PROMPT = '（dsh-memoir 自动收尾）本轮工作已结
 export const AUTO_DISTILL_PLUGIN = 'dsh-memoir';
 /** Scan the tail of a session log for one turn's tool activity. */
 export function turnActivity(events, turn) {
-    let worked = false;
     let recorded = false;
+    let toolCalls = 0;
     for (let i = events.length - 1; i >= 0; i--) {
         const event = events[i];
         const data = event.data;
@@ -31,39 +31,54 @@ export function turnActivity(events, turn) {
         if (data.turn !== turn)
             continue;
         if (event.type === 'tool/call') {
-            worked = true;
+            toolCalls += 1;
             if (data.name === 'memoir_record')
                 recorded = true;
         }
     }
-    return { worked, recorded };
+    return { worked: toolCalls > 0, recorded, toolCalls };
 }
 /** Subagent sessions (and any nested delegation) never get distilled. */
 export function isSubagentSession(agent) {
     return agent.session.header.origin === 'subagent' || (agent.session.header.delegationDepth ?? 0) > 0;
 }
-/** Per-agent memory of turns already steered (with pruning). */
+/** Per-agent frequency, cooldown, and duplicate-turn state (with pruning). */
 export class AutoDistillGate {
-    steered = new Map();
-    /** Claim a turn for steering; false when already claimed (or pruned-out). */
-    consume(agentId, turn) {
-        let set = this.steered.get(agentId);
-        if (set === undefined) {
-            set = new Set();
-            this.steered.set(agentId, set);
+    states = new Map();
+    /**
+     * Consume one eligible worked turn and decide whether all policy conditions
+     * are ready. Duplicate events never advance the worked-turn counter.
+     */
+    consume(agentId, turn, toolCalls, policy, now) {
+        let state = this.states.get(agentId);
+        if (state === undefined) {
+            state = { processedTurns: new Set(), workedSinceSteer: 0 };
+            this.states.set(agentId, state);
         }
-        if (set.has(turn))
+        if (state.processedTurns.has(turn))
             return false;
-        set.add(turn);
-        for (const t of [...set]) {
-            if (t < turn - 100)
-                set.delete(t);
+        state.processedTurns.add(turn);
+        for (const value of [...state.processedTurns]) {
+            if (value < turn - 100)
+                state.processedTurns.delete(value);
         }
-        return true;
+        state.workedSinceSteer += 1;
+        const intervalReady = state.workedSinceSteer >= policy.every;
+        const activityReady = toolCalls >= policy.minTools;
+        const cooldownReady = state.lastSteeredAt === undefined || now - state.lastSteeredAt >= policy.cooldownMs;
+        return intervalReady && activityReady && cooldownReady;
+    }
+    /** Record a successful steer; failed steer attempts do not start cooldown. */
+    recordSteer(agentId, now) {
+        const state = this.states.get(agentId);
+        if (state === undefined)
+            return;
+        state.workedSinceSteer = 0;
+        state.lastSteeredAt = now;
     }
     /** Drop all state for one agent (disposal hygiene). */
     forget(agentId) {
-        this.steered.delete(agentId);
+        this.states.delete(agentId);
     }
 }
 /**
@@ -73,6 +88,8 @@ export class AutoDistillGate {
  */
 export function installAutoDistill(wire, options) {
     const gate = new AutoDistillGate();
+    const integerAtLeast = (value, fallback, minimum) => typeof value === 'number' && Number.isFinite(value) ? Math.max(minimum, Math.floor(value)) : fallback;
+    const numberAtLeast = (value, fallback, minimum) => typeof value === 'number' && Number.isFinite(value) ? Math.max(minimum, value) : fallback;
     return wire.on('agent/turn-stopping', (payload) => {
         if (!options.enabled())
             return;
@@ -81,14 +98,22 @@ export function installAutoDistill(wire, options) {
             return;
         if (signal.aborted)
             return;
-        const { worked, recorded } = turnActivity(agent.session.events, turn);
+        const { worked, recorded, toolCalls } = turnActivity(agent.session.events, turn);
         if (!worked || recorded)
             return;
-        if (!gate.consume(agent.id, turn))
+        const live = options.policy?.();
+        const policy = {
+            every: integerAtLeast(live?.every ?? options.every, 1, 1),
+            cooldownMs: numberAtLeast(live?.cooldownMin ?? options.cooldownMin, 0, 0) * 60_000,
+            minTools: integerAtLeast(live?.minTools ?? options.minTools, 1, 1),
+        };
+        const now = options.now?.() ?? Date.now();
+        if (!gate.consume(agent.id, turn, toolCalls, policy, now))
             return;
         agent.steer(createUserMessage({
             content: [{ type: 'text', text: DISTILL_PROMPT }],
             source: { kind: 'plugin', plugin: AUTO_DISTILL_PLUGIN },
         }));
+        gate.recordSteer(agent.id, now);
     });
 }

package/lib/client.js

@@ -114,6 +114,29 @@ var MemoirApi = class {
     const response = await this.fetchImpl("/api/dsh-memoir/diagnostics" + query({ path }));
     return readEnvelope(response);
   }
+  /** Read the live auto-distill policy and whether it comes from Web overrides. */
+  async settings() {
+    const response = await this.fetchImpl("/api/dsh-memoir/settings");
+    return readEnvelope(response);
+  }
+  /** Persist and immediately apply the auto-distill policy. */
+  async updateSettings(settings) {
+    const response = await this.fetchImpl("/api/dsh-memoir/settings", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(settings)
+    });
+    return readEnvelope(response);
+  }
+  /** Remove the Web override and restore the profile defaults captured at boot. */
+  async resetSettings() {
+    const response = await this.fetchImpl("/api/dsh-memoir/settings", {
+      method: "DELETE",
+      headers: { "content-type": "application/json" },
+      body: "{}"
+    });
+    return readEnvelope(response);
+  }
   /**
    * Ranked search over the host RetrievalEngine (v0.4.2) — the same ranking
    * memoir_read uses, so the GUI search and the agent recall never diverge.
@@ -254,7 +277,28 @@ var dictionaries = {
     "lifecycle.supersede": "\u6807\u8BB0\u5DF2\u66FF\u4EE3",
     "lifecycle.unsupersede": "\u6062\u590D\u6D3B\u8DC3",
     "lifecycle.archive": "\u5F52\u6863",
-    "lifecycle.restore": "\u6062\u590D"
+    "lifecycle.restore": "\u6062\u590D",
+    "settings.title": "\u81EA\u52A8\u84B8\u998F\u8BBE\u7F6E",
+    "settings.description": "\u4FEE\u6539\u540E\u7ACB\u5373\u4F5C\u7528\u4E8E\u540E\u7EED\u56DE\u5408\uFF0C\u5E76\u6301\u4E45\u5316\u5230\u672C\u673A DSH \u7528\u6237\u76EE\u5F55\u3002",
+    "settings.enabled": "\u542F\u7528\u81EA\u52A8\u84B8\u998F",
+    "settings.enabledHint": "\u5728\u9876\u5C42 agent \u7684\u6709\u6548\u5DE5\u4F5C\u56DE\u5408\u7ED3\u675F\u65F6\u63D0\u9192\u5F52\u7EB3\u8BB0\u5FC6\u3002",
+    "settings.every": "\u5DE5\u4F5C\u56DE\u5408\u95F4\u9694",
+    "settings.everyHint": "\u6BCF\u7D2F\u8BA1 N \u4E2A worked turn \u6700\u591A\u63D0\u9192\u4E00\u6B21\uFF08\u6700\u5C0F 1\uFF09\u3002",
+    "settings.cooldown": "\u51B7\u5374\u65F6\u95F4\uFF08\u5206\u949F\uFF09",
+    "settings.cooldownHint": "\u4E24\u6B21\u6210\u529F\u63D0\u9192\u81F3\u5C11\u95F4\u9694 M \u5206\u949F\uFF08\u6700\u5C0F 0\uFF09\u3002",
+    "settings.minTools": "\u6700\u4F4E\u5DE5\u5177\u8C03\u7528\u6570",
+    "settings.minToolsHint": "\u89E6\u53D1\u56DE\u5408\u81F3\u5C11\u5305\u542B K \u6B21\u5DE5\u5177\u8C03\u7528\uFF08\u6700\u5C0F 1\uFF09\u3002",
+    "settings.andHint": "\u4E09\u4E2A\u9891\u7387\u6761\u4EF6\u6309 AND \u5224\u5B9A\uFF1Bidle\u3001aborted\u3001subagent \u548C\u5DF2\u8BB0\u5F55\u8BB0\u5FC6\u7684\u56DE\u5408\u4E0D\u4F1A\u89E6\u53D1\u3002",
+    "settings.source": "\u5F53\u524D\u6765\u6E90",
+    "settings.source.profile": "\u542F\u52A8\u914D\u7F6E",
+    "settings.source.web": "Web \u6301\u4E45\u5316\u8986\u76D6",
+    "settings.save": "\u4FDD\u5B58\u5E76\u7ACB\u5373\u5E94\u7528",
+    "settings.reset": "\u6062\u590D\u542F\u52A8\u914D\u7F6E",
+    "settings.saved": "\u5DF2\u4FDD\u5B58\uFF0C\u540E\u7EED\u56DE\u5408\u7ACB\u5373\u751F\u6548\u3002",
+    "settings.resetDone": "\u5DF2\u6062\u590D\u672C\u6B21\u542F\u52A8\u65F6\u7684\u914D\u7F6E\u3002",
+    "settings.invalid": "\u8BF7\u8F93\u5165\u6709\u6548\u6570\u503C\uFF1A\u95F4\u9694\u548C\u5DE5\u5177\u6570\u4E3A\u4E0D\u5C0F\u4E8E 1 \u7684\u6574\u6570\uFF0C\u51B7\u5374\u65F6\u95F4\u4E0D\u5C0F\u4E8E 0\u3002",
+    "settings.loadFailed": "\u8BBE\u7F6E\u52A0\u8F7D\u5931\u8D25",
+    "settings.saveFailed": "\u8BBE\u7F6E\u4FDD\u5B58\u5931\u8D25"
   },
   en: {
     "entry.label": "Memory",
@@ -316,7 +360,28 @@ var dictionaries = {
     "lifecycle.supersede": "Mark superseded",
     "lifecycle.unsupersede": "Restore active",
     "lifecycle.archive": "Archive",
-    "lifecycle.restore": "Restore"
+    "lifecycle.restore": "Restore",
+    "settings.title": "Auto-distill settings",
+    "settings.description": "Changes apply to subsequent turns immediately and persist in the local DSH user directory.",
+    "settings.enabled": "Enable auto-distill",
+    "settings.enabledHint": "Prompt top-level agents to distill memory after eligible worked turns.",
+    "settings.every": "Worked-turn interval",
+    "settings.everyHint": "Remind at most once per N accumulated worked turns (minimum 1).",
+    "settings.cooldown": "Cooldown (minutes)",
+    "settings.cooldownHint": "Require at least M minutes between successful reminders (minimum 0).",
+    "settings.minTools": "Minimum tool calls",
+    "settings.minToolsHint": "The triggering turn must contain at least K tool calls (minimum 1).",
+    "settings.andHint": "All three frequency conditions use AND semantics; idle, aborted, subagent, and already-recorded turns do not trigger.",
+    "settings.source": "Current source",
+    "settings.source.profile": "startup profile config",
+    "settings.source.web": "persistent Web override",
+    "settings.save": "Save and apply now",
+    "settings.reset": "Restore startup config",
+    "settings.saved": "Saved; subsequent turns use the new policy immediately.",
+    "settings.resetDone": "Restored the configuration captured at startup.",
+    "settings.invalid": "Enter valid values: interval and tool count are integers of at least 1; cooldown is at least 0.",
+    "settings.loadFailed": "Failed to load settings",
+    "settings.saveFailed": "Failed to save settings"
   }
 };
 var SECTION_KEYS = ["work", "lessons", "actions", "note"];
@@ -385,6 +450,7 @@ html[data-dsh-memoir-active] [class*="centerCol"] > *:not([data-dsh-memoir-view]
   border-radius: 6px; padding: 6px 12px; cursor: pointer; font-size: 13px;
 }
 .memoir-primary:hover { filter: brightness(1.05); }
+.memoir-primary:disabled, .memoir-iconbtn:disabled { cursor: not-allowed; opacity: .45; }
 
 .memoir-body { flex: 1; overflow-y: auto; padding: 4px 14px 16px; }
 .memoir-section-title {
@@ -434,6 +500,27 @@ html[data-dsh-memoir-active] [class*="centerCol"] > *:not([data-dsh-memoir-view]
 .memoir-field textarea { min-height: 72px; resize: vertical; }
 .memoir-form-actions { display: flex; justify-content: flex-end; gap: 8px; }
 
+/* v0.5.3 live auto-distill settings */
+.memoir-settings { margin: 0 14px; border-top: 1px solid var(--border, rgba(0,0,0,.1)); padding-top: 8px; }
+.memoir-settings-body {
+  display: flex; flex-direction: column; gap: 10px; margin-top: 7px; padding: 10px;
+  border: 1px solid var(--border, rgba(0,0,0,.1)); border-radius: 8px;
+  background: var(--bg-card, rgba(0,0,0,.02)); max-height: min(50vh, 430px); overflow-y: auto;
+}
+.memoir-settings-description, .memoir-settings-note, .memoir-settings-source { font-size: 11px; opacity: .72; line-height: 1.45; }
+.memoir-settings-switch { display: flex; align-items: flex-start; gap: 8px; cursor: pointer; }
+.memoir-settings-switch input { margin-top: 3px; }
+.memoir-settings-switch span { display: flex; flex-direction: column; gap: 2px; }
+.memoir-settings-switch small, .memoir-settings-grid small { font-size: 10px; opacity: .65; line-height: 1.35; }
+.memoir-settings-grid { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px; }
+.memoir-settings-grid .memoir-field { min-width: 0; }
+.memoir-settings-grid .memoir-field > span { font-size: 11px; opacity: .8; }
+.memoir-settings-feedback { padding: 0; }
+.memoir-settings-success { color: var(--success, #15803d); font-size: 12px; }
+@media (max-width: 760px) {
+  .memoir-settings-grid { grid-template-columns: 1fr; }
+}
+
 /* Sidebar entry row (plain DOM, matches the shell's nav rows). */
 .memoir-entry-row {
   display: flex; align-items: center; gap: 8px; width: 100%;
@@ -723,6 +810,123 @@ function AddForm({ t, onSubmit, onCancel }) {
     ] })
   ] });
 }
+function AutoDistillSettingsPanel({ api, t, refreshKey, onChanged }) {
+  const [open, setOpen] = (0, import_react.useState)(false);
+  const [settings, setSettings] = (0, import_react.useState)(null);
+  const [source, setSource] = (0, import_react.useState)("profile");
+  const [every, setEvery] = (0, import_react.useState)("1");
+  const [cooldown, setCooldown] = (0, import_react.useState)("0");
+  const [minTools, setMinTools] = (0, import_react.useState)("1");
+  const [busy, setBusy] = (0, import_react.useState)(false);
+  const [message, setMessage] = (0, import_react.useState)(null);
+  const [error, setError] = (0, import_react.useState)(null);
+  const applySnapshot = (snapshot) => {
+    setError(null);
+    setSettings(snapshot.settings);
+    setSource(snapshot.source);
+    setEvery(String(snapshot.settings.autoDistillEvery));
+    setCooldown(String(snapshot.settings.autoDistillCooldownMin));
+    setMinTools(String(snapshot.settings.autoDistillMinTools));
+  };
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    api.settings().then((value) => {
+      if (!cancelled) applySnapshot(value);
+    }).catch((e) => {
+      if (!cancelled) setError(`${t("settings.loadFailed")}: ${e.message}`);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [api, refreshKey]);
+  const save = () => {
+    if (settings === null) return;
+    const parsedEvery = Number(every);
+    const parsedCooldown = Number(cooldown);
+    const parsedMinTools = Number(minTools);
+    if (!Number.isSafeInteger(parsedEvery) || parsedEvery < 1 || !Number.isFinite(parsedCooldown) || parsedCooldown < 0 || !Number.isSafeInteger(parsedMinTools) || parsedMinTools < 1) {
+      setMessage(null);
+      setError(t("settings.invalid"));
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    setMessage(null);
+    api.updateSettings({
+      autoDistill: settings.autoDistill,
+      autoDistillEvery: parsedEvery,
+      autoDistillCooldownMin: parsedCooldown,
+      autoDistillMinTools: parsedMinTools
+    }).then((value) => {
+      applySnapshot(value);
+      setMessage(t("settings.saved"));
+      onChanged();
+    }).catch((e) => setError(`${t("settings.saveFailed")}: ${e.message}`)).finally(() => setBusy(false));
+  };
+  const reset = () => {
+    setBusy(true);
+    setError(null);
+    setMessage(null);
+    api.resetSettings().then((value) => {
+      applySnapshot(value);
+      setMessage(t("settings.resetDone"));
+      onChanged();
+    }).catch((e) => setError(`${t("settings.saveFailed")}: ${e.message}`)).finally(() => setBusy(false));
+  };
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-settings", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("button", { type: "button", className: "memoir-diagnostics-toggle", onClick: () => setOpen((value) => !value), children: [
+      t("settings.title"),
+      " ",
+      open ? "\u25BE" : "\u25B8"
+    ] }),
+    open ? settings === null ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-settings-body", children: error ?? "\u2026" }) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-settings-body", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-settings-description", children: t("settings.description") }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { className: "memoir-settings-switch", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            type: "checkbox",
+            checked: settings.autoDistill,
+            onChange: (event) => setSettings({ ...settings, autoDistill: event.target.checked })
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("span", { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("strong", { children: t("settings.enabled") }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("small", { children: t("settings.enabledHint") })
+        ] })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-settings-grid", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { className: "memoir-field", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: t("settings.every") }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "number", min: "1", step: "1", value: every, onChange: (event) => setEvery(event.target.value) }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("small", { children: t("settings.everyHint") })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { className: "memoir-field", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: t("settings.cooldown") }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "number", min: "0", step: "0.1", value: cooldown, onChange: (event) => setCooldown(event.target.value) }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("small", { children: t("settings.cooldownHint") })
+        ] }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("label", { className: "memoir-field", children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: t("settings.minTools") }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("input", { type: "number", min: "1", step: "1", value: minTools, onChange: (event) => setMinTools(event.target.value) }),
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("small", { children: t("settings.minToolsHint") })
+        ] })
+      ] }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-settings-note", children: t("settings.andHint") }),
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-settings-source", children: [
+        t("settings.source"),
+        ": ",
+        t(`settings.source.${source}`)
+      ] }),
+      error !== null ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-error memoir-settings-feedback", children: error }) : null,
+      message !== null ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-settings-success", children: message }) : null,
+      /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-form-actions", children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "memoir-iconbtn", disabled: busy || source === "profile", onClick: reset, children: t("settings.reset") }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("button", { type: "button", className: "memoir-primary", disabled: busy, onClick: save, children: t("settings.save") })
+      ] })
+    ] }) : null
+  ] });
+}
 function MemoirPanel({ controller, api, cwdTracker, t }) {
   const cwd = (0, import_react.useSyncExternalStore)(cwdTracker.subscribe, cwdTracker.getSnapshot);
   const [tab, setTab] = (0, import_react.useState)("project");
@@ -890,6 +1094,7 @@ function MemoirPanel({ controller, api, cwdTracker, t }) {
       ] }, p.key);
     }) }),
     busy ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "memoir-empty", children: "\u2026" }) : null,
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(AutoDistillSettingsPanel, { api, t, refreshKey, onChanged: reload }),
     /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { className: "memoir-inspector", children: [
       /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("button", { type: "button", className: "memoir-diagnostics-toggle", onClick: () => setInspectorOpen((v) => !v), children: [
         t("inspector.title"),