@aiwayds/dsh-topics-memory 0.16.1-next.1 → 0.18.0

package/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 A dsh plugin: maintains "working topic memory" as an [OKF (Open Knowledge Format v0.2)](https://github.com/GoogleCloudPlatform/open-knowledge-format) knowledge bundle, persisted in a local git repository (optionally synced to a private GitHub repo), with conclusions traceable through git history, sessions automatically observed and distilled into knowledge, and relevant topics injected to the model before every turn.
 
-> **Requires dsh >= 0.1.5-rc.2** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
+> **Requires dsh >= 0.1.7-rc.1** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.**
 
 ## Demo
 
@@ -90,14 +90,14 @@ The host reconciles the profile automatically: the `dsh.profile.bundles` entry i
 What stays on disk (kept on purpose — this is your memory):
 
 - `~/.dsh/topics/` — the whole topic bundle: topic markdown, `meta/`, and the embedded `.git` repo (the full history; it may carry an `origin` remote — GitHub sync stops with the plugin). To archive the bundle elsewhere, copy or clone this directory as-is.
-- `~/.dsh/settings.yaml` `topics:` section — user overrides. Reinstalling silently reactivates sync including any configured `repo`; delete the section first if you want a clean start.
-- The legacy `llmwiki:` settings section left by the 0.5.x → 0.6.x migration is never auto-deleted; remove it by hand once nothing needs it.
+- The settings-page `dsh-topics-memory` entry (profile patch) — user overrides. Reinstalling silently reactivates sync including any configured `repo`; clear the entry first if you want a clean start.
+- A legacy `llmwiki:` section left inside the old `settings.yaml` (renamed `settings.yaml.imported` after the host's one-shot 0.1.7 import) is never touched again; mine it by hand if something still needs it.
 
 Purge everything: back up `~/.dsh/topics` first, then `rm -rf ~/.dsh/topics`.
 
 ## Configuration
 
-First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set <key> <value>` (writes the `topics` namespace in `settings.yaml`, effective from the next session). All keys and defaults:
+First-time setup belongs to `/topics onboard`; day-to-day tuning is `/topics set <key> <value>` — on dsh 0.1.7+ it writes the settings-page `dsh-topics-memory` entry (the profile patch) and every key is volatile: edits take effect immediately, no restart. All keys and defaults:
 
 | Key | Default | Meaning |
 |---|---|---|

package/README.zh.md

@@ -4,7 +4,7 @@
 
 一个 dsh 插件：把「工作 topic 记忆」维护成 [OKF 标准（Open Knowledge Format v0.2）](https://github.com/GoogleCloudPlatform/open-knowledge-format)的知识 bundle，持久化在本地 git 仓库（可选同步到 GitHub 私有仓库），利用 git 历史提供结论可追溯性，自动观察会话沉淀知识，并在每轮对话前向模型注入相关 Topic。
 
-> **要求 dsh >= 0.1.5-rc.2** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
+> **要求 dsh >= 0.1.7-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
 ## 演示
 
@@ -90,14 +90,14 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 以下内容有意保留在磁盘上（这是你的记忆本体）：
 
 - `~/.dsh/topics/` —— 整个话题包：话题 markdown、`meta/`、以及内嵌的 `.git` 仓库（完整历史；可能带有 `origin` 远端 —— GitHub 同步随插件停止）。要异地归档就原样拷贝/克隆这个目录。
-- `~/.dsh/settings.yaml` 的 `topics:` 段 —— 用户覆盖项。注意：重装会静默恢复同步（包括已配置的 `repo`）；想干净重来就先删这一段。
+- 设置页 `dsh-topics-memory` 条目（profile patch）—— 用户覆盖项。注意：重装会静默恢复同步（包括已配置的 `repo`）；想干净重来就先清空该条目。
 - 0.5.x → 0.6.x 迁移留下的 `llmwiki:` 旧设置段不会被自动删除；确认无用后手动移除。
 
 彻底清除：先备份 `~/.dsh/topics`，再 `rm -rf ~/.dsh/topics`。
 
 ## 配置
 
-首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`（写 `settings.yaml` 的 `topics` namespace，下次会话启动生效）。全部键与默认值：
+首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`——0.1.7+ 宿主上写设置页 `dsh-topics-memory` 条目（profile patch），全部键 volatile 免重启即时生效。全部键与默认值：
 
 | 键 | 默认 | 说明 |
 |---|---|---|

package/icon.svg

@@ -0,0 +1,6 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="6.5" cy="6" r="2.2"/>
+  <circle cx="17.5" cy="7.5" r="2.2"/>
+  <circle cx="12" cy="17.5" r="2.2"/>
+  <path d="M8.7 6.5 15.3 7M16.3 9.6 13.5 15.6M9.5 8.1l1.7 7.3"/>
+</svg>

package/lib/commands.js

@@ -112,6 +112,35 @@ async function renderStatus(service) {
         const gc = typeof lastRun.gcDropped === 'number' && lastRun.gcDropped > 0 ? `，GC 回收 ${lastRun.gcDropped}` : '';
         rows.push(['最近蒸馏', `${outcome}${gc} @ ${cell(String(lastRun.at ?? '').slice(0, 19).replace('T', ' '))}`]);
     }
+    // Fast-lane heartbeat (0.17.0): pair "observer lane recorded recently"
+    // with "no injection round for >48h" — exactly the asymmetry a silent
+    // fast-lane death produces (the 0.1.5-rc.2 claim-order incident shape).
+    // With autoInject off there is no fast lane to be stale.
+    if (cfg.autoInject) {
+        const HOUR = 3_600_000;
+        const hb = await service.store.readLaneHeartbeat();
+        const stamp = (iso) => cell(iso.slice(0, 19).replace('T', ' '));
+        const ago = (ms) => {
+            const h = ms / HOUR;
+            if (!Number.isFinite(h))
+                return '';
+            return h < 1 ? `${Math.max(1, Math.round(h * 60))} 分钟前` : h < 48 ? `${Math.round(h)}h 前` : `${Math.round(h / 24)} 天前`;
+        };
+        const lastAt = hb.lastInjectionAt;
+        const fastIdleMs = lastAt !== undefined ? Date.now() - Date.parse(lastAt) : Number.POSITIVE_INFINITY;
+        const obsAgeMs = hb.lastObservationAt !== undefined ? Date.now() - Date.parse(hb.lastObservationAt) : Number.POSITIVE_INFINITY;
+        const obsRecent = obsAgeMs < 24 * HOUR;
+        if (lastAt === undefined) {
+            rows.push(['快道心跳', obsRecent ? `⚠️ 从未注入，但观察 lane ${ago(obsAgeMs)}仍在记录——快道疑似静默死亡` : '从未注入']);
+        }
+        else if (fastIdleMs > 48 * HOUR && obsRecent) {
+            rows.push(['快道心跳', `⚠️ ${stamp(lastAt)}（${ago(fastIdleMs)}）无注入轮次，而观察 lane ${ago(obsAgeMs)}仍在记录——快道疑似静默死亡`]);
+        }
+        else {
+            const since = ago(fastIdleMs);
+            rows.push(['快道心跳', `${stamp(lastAt)}${since === '' ? '' : `（${since}）`}`]);
+        }
+    }
     const lastConsolidate = await service.store.readConsolidateState();
     if (lastConsolidate !== undefined) {
         const count = (v) => (Array.isArray(v) ? v.length : 0);

package/lib/config.d.ts

@@ -5,141 +5,141 @@
  * @module config
  */
 import z from '@deepseek-ai/schemastery';
-export declare const TopicsConfig: z<Schemastery.ObjectS<{
+export declare const TopicsConfig: z<Schemastery.ObjectS<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z<string, string>;
+    repo: z<string, string, "volatile-defined">;
     /** Master switch for per-turn injection. */
-    autoInject: z<boolean, boolean>;
+    autoInject: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z<boolean, boolean>;
+    injectDedup: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z<boolean, boolean>;
+    suppressEcho: z<boolean, boolean, "volatile-defined">;
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z<number, number>;
+    topK: z<number, number, "volatile-defined">;
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z<number, number>;
+    perTopicBudget: z<number, number, "volatile-defined">;
     /** Total injection budget in tokens. */
-    totalBudget: z<number, number>;
+    totalBudget: z<number, number, "volatile-defined">;
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z<number, number>;
+    matchThreshold: z<number, number, "volatile-defined">;
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z<number, number>;
+    tagBoost: z<number, number, "volatile-defined">;
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z<string, string>;
+    injectMode: z<string, string, "volatile-defined">;
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z<string, string>;
+    qualityLane: z<string, string, "volatile-defined">;
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z<number, number>;
+    graphDepth: z<number, number, "volatile-defined">;
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z<number, number>;
+    recencyWindowDays: z<number, number, "volatile-defined">;
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z<boolean, boolean>;
+    autoObserve: z<boolean, boolean, "volatile-defined">;
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z<boolean, boolean>;
+    includeSubagents: z<boolean, boolean, "volatile-defined">;
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z<number, number>;
+    observationMaxChars: z<number, number, "volatile-defined">;
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z<number, number>;
+    distillEveryTurns: z<number, number, "volatile-defined">;
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z<boolean, boolean>;
+    distillOnSessionEnd: z<boolean, boolean, "volatile-defined">;
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z<string, string>;
-    distillModel: z<string, string>;
+    distillProvider: z<string, string, "volatile-defined">;
+    distillModel: z<string, string, "volatile-defined">;
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z<number, number>;
+    distillBatchSize: z<number, number, "volatile-defined">;
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
-    distillMaxModelCalls: z<number, number>;
+    distillMaxModelCalls: z<number, number, "volatile-defined">;
     /** Consolidation lane (整理) cadence: how often a session start may run the
      *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
      *  settled drafts, deprecate superseded, refresh metadata). Reuses the
      *  distill model route; off disables the lane entirely. */
-    consolidateCadence: z<string, string>;
+    consolidateCadence: z<string, string, "volatile-defined">;
     /** Deprecated topics older than this many days are dropped at session start
      *  (local TTL sweep, no model; each drop is its own git commit, so history
      *  stays recoverable on the remote). 0 disables the sweep. */
-    deprecatedTtlDays: z<number, number>;
+    deprecatedTtlDays: z<number, number, "volatile-defined">;
     /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
      *  the last 30 days, folded into the gate score — capped at 0.2 and never
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
-    usageBoost: z<number, number>;
+    usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z<number, number>;
-}>, Schemastery.ObjectT<{
+    pushDebounceSeconds: z<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z<string, string>;
+    repo: z<string, string, "volatile-defined">;
     /** Master switch for per-turn injection. */
-    autoInject: z<boolean, boolean>;
+    autoInject: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z<boolean, boolean>;
+    injectDedup: z<boolean, boolean, "volatile-defined">;
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z<boolean, boolean>;
+    suppressEcho: z<boolean, boolean, "volatile-defined">;
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z<number, number>;
+    topK: z<number, number, "volatile-defined">;
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z<number, number>;
+    perTopicBudget: z<number, number, "volatile-defined">;
     /** Total injection budget in tokens. */
-    totalBudget: z<number, number>;
+    totalBudget: z<number, number, "volatile-defined">;
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z<number, number>;
+    matchThreshold: z<number, number, "volatile-defined">;
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z<number, number>;
+    tagBoost: z<number, number, "volatile-defined">;
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z<string, string>;
+    injectMode: z<string, string, "volatile-defined">;
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z<string, string>;
+    qualityLane: z<string, string, "volatile-defined">;
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z<number, number>;
+    graphDepth: z<number, number, "volatile-defined">;
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z<number, number>;
+    recencyWindowDays: z<number, number, "volatile-defined">;
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z<boolean, boolean>;
+    autoObserve: z<boolean, boolean, "volatile-defined">;
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z<boolean, boolean>;
+    includeSubagents: z<boolean, boolean, "volatile-defined">;
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z<number, number>;
+    observationMaxChars: z<number, number, "volatile-defined">;
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z<number, number>;
+    distillEveryTurns: z<number, number, "volatile-defined">;
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z<boolean, boolean>;
+    distillOnSessionEnd: z<boolean, boolean, "volatile-defined">;
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z<string, string>;
-    distillModel: z<string, string>;
+    distillProvider: z<string, string, "volatile-defined">;
+    distillModel: z<string, string, "volatile-defined">;
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z<number, number>;
+    distillBatchSize: z<number, number, "volatile-defined">;
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
-    distillMaxModelCalls: z<number, number>;
+    distillMaxModelCalls: z<number, number, "volatile-defined">;
     /** Consolidation lane (整理) cadence: how often a session start may run the
      *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
      *  settled drafts, deprecate superseded, refresh metadata). Reuses the
      *  distill model route; off disables the lane entirely. */
-    consolidateCadence: z<string, string>;
+    consolidateCadence: z<string, string, "volatile-defined">;
     /** Deprecated topics older than this many days are dropped at session start
      *  (local TTL sweep, no model; each drop is its own git commit, so history
      *  stays recoverable on the remote). 0 disables the sweep. */
-    deprecatedTtlDays: z<number, number>;
+    deprecatedTtlDays: z<number, number, "volatile-defined">;
     /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
      *  the last 30 days, folded into the gate score — capped at 0.2 and never
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
-    usageBoost: z<number, number>;
+    usageBoost: z<number, number, "volatile-defined">;
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z<number, number>;
-}>>;
+    pushDebounceSeconds: z<number, number, "volatile-defined">;
+}>>, "plain">;
 export type TopicsConfigValue = {
     repo: string;
     autoInject: boolean;

package/lib/config.js

@@ -7,71 +7,71 @@
 import z from '@deepseek-ai/schemastery';
 export const TopicsConfig = z.object({
     /** GitHub repo `owner/name`; empty = local-only mode (ADR 0008). */
-    repo: z.string().default(''),
+    repo: z.string().default('').volatile(),
     /** Master switch for per-turn injection. */
-    autoInject: z.boolean().default(true),
+    autoInject: z.boolean().default(true).volatile(),
     /** Skip re-injecting topics already injected earlier in the same session. */
-    injectDedup: z.boolean().default(true),
+    injectDedup: z.boolean().default(true).volatile(),
     /** Skip re-injecting topics distilled from the CURRENT session's own turns
      *  (蒸馏回声): the conversation already carries that knowledge, so a
      *  pointer is a stale echo at best (2026-09 audit: 3 of 6 useless rounds).
      *  Provenance rides the observations log (sessionId → distilledInto). */
-    suppressEcho: z.boolean().default(true),
+    suppressEcho: z.boolean().default(true).volatile(),
     /** Max topics injected per round (ADR 0006: ≤4). */
-    topK: z.number().default(4),
+    topK: z.number().default(4).volatile(),
     /** Per-topic digest budget in tokens. */
-    perTopicBudget: z.number().default(300),
+    perTopicBudget: z.number().default(300).volatile(),
     /** Total injection budget in tokens. */
-    totalBudget: z.number().default(1500),
+    totalBudget: z.number().default(1500).volatile(),
     /** Retrieval score threshold — tune via /topics stats near-miss evidence. */
-    matchThreshold: z.number().default(0.3),
+    matchThreshold: z.number().default(0.3).volatile(),
     /** Additive boost per tag hit (v4: total cap = this value, was ×3). */
-    tagBoost: z.number().default(0.15),
+    tagBoost: z.number().default(0.15).volatile(),
     /** Injection shape: pointer (default, ≤600 tok) keeps the legacy digest view. */
-    injectMode: z.string().default('pointer'),
+    injectMode: z.string().default('pointer').volatile(),
     /** Slow quality lane (v4 §4.2): off | sampled (1/3 of turns) | always. */
-    qualityLane: z.string().default('sampled'),
+    qualityLane: z.string().default('sampled').volatile(),
     /** depends-graph expansion depth (0 disables). */
-    graphDepth: z.number().default(2),
+    graphDepth: z.number().default(2).volatile(),
     /** Days within which a topic counts as recent (+0.2). */
-    recencyWindowDays: z.number().default(7),
+    recencyWindowDays: z.number().default(7).volatile(),
     /** Capture each turn's user/assistant text as raw observations (M2). */
-    autoObserve: z.boolean().default(true),
+    autoObserve: z.boolean().default(true).volatile(),
     /** Whether injection and observation also engage delegated subagent sessions (ADR 0011).
      *  v4 default flipped to false: one-shot subagent turns diluted the pool.
      *  The slow quality lane never runs for subagents either way (hard guard). */
-    includeSubagents: z.boolean().default(false),
+    includeSubagents: z.boolean().default(false).volatile(),
     /** Max auto-captured chars per side (user/assistant) per turn. */
-    observationMaxChars: z.number().default(2000),
+    observationMaxChars: z.number().default(2000).volatile(),
     /** Background distill cadence: every N turns of a long session. */
-    distillEveryTurns: z.number().default(5),
+    distillEveryTurns: z.number().default(5).volatile(),
     /** Distill once when a session ends. */
-    distillOnSessionEnd: z.boolean().default(true),
+    distillOnSessionEnd: z.boolean().default(true).volatile(),
     /** Distill lane model route; both must be set, else distill stays idle. */
-    distillProvider: z.string().default(''),
-    distillModel: z.string().default(''),
+    distillProvider: z.string().default('').volatile(),
+    distillModel: z.string().default('').volatile(),
     /** Observations per distill model call; auto-halves on output-limit failures (floor 5). */
-    distillBatchSize: z.number().default(40),
+    distillBatchSize: z.number().default(40).volatile(),
     /** Max model calls per distill run — successful batches keep their marks (partial progress).
      *  Default 8: with the batch loop, one run then drains ~30-40 observations
      *  instead of ~10, which is what makes a real backlog actually shrink. */
-    distillMaxModelCalls: z.number().default(8),
+    distillMaxModelCalls: z.number().default(8).volatile(),
     /** Consolidation lane (整理) cadence: how often a session start may run the
      *  LLM gardener over the EXISTING pool (merge near-duplicates, promote
      *  settled drafts, deprecate superseded, refresh metadata). Reuses the
      *  distill model route; off disables the lane entirely. */
-    consolidateCadence: z.string().default('daily'),
+    consolidateCadence: z.string().default('daily').volatile(),
     /** Deprecated topics older than this many days are dropped at session start
      *  (local TTL sweep, no model; each drop is its own git commit, so history
      *  stays recoverable on the remote). 0 disables the sweep. */
-    deprecatedTtlDays: z.number().default(15),
+    deprecatedTtlDays: z.number().default(15).volatile(),
     /** UsageBoost (ADR 0015): behavioral bonus for topics injected/opened in
      *  the last 30 days, folded into the gate score — capped at 0.2 and never
      *  granted to zero-lexical candidates; the structural gate still applies.
      *  0 = off. */
-    usageBoost: z.number().default(0.15),
+    usageBoost: z.number().default(0.15).volatile(),
     /** Debounced push delay in GitHub mode. */
-    pushDebounceSeconds: z.number().default(45),
+    pushDebounceSeconds: z.number().default(45).volatile(),
 });
 export const CONFIG_KEYS = [
     'repo',

package/lib/distill.d.ts

@@ -10,6 +10,14 @@
  * @module distill
  */
 import type { TopicsService } from './service.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Producer context contributed by the dsh-topics-memory plugin. */
+        'topics-memory': {
+            kind: 'topics-memory';
+        };
+    }
+}
 export interface ModelRequest {
     system: string;
     user: string;

package/lib/distill.js

@@ -710,7 +710,7 @@ export function defaultModelCaller(getCandidates, getRoute) {
         const messages = [
             createUserMessage({
                 content: [{ type: 'text', text: req.user }],
-                source: { kind: 'plugin', plugin: 'dsh-topics-memory' },
+                source: { kind: 'topics-memory' },
             }),
         ];
         const options = deepFreeze({

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 import type { Context } from '@deepseek-ai/cordis';
+import { type TopicsConfigValue } from './config.ts';
 export declare const name = "dsh-topics-memory";
 /**
  * Bounded wait for the process-exit meta commit. The exit path is
@@ -17,42 +18,140 @@ export declare function settleBounded(p: Promise<unknown> | undefined, ms: numbe
 /** Services consumed at apply time; llm joins via guarded ctx.inject, and the
  *  skills registry serves the bundled usage/config guide. */
 export declare const inject: string[];
+/** A firehose event as the replay path reads it: envelope fields only. */
+export interface InboxEventLike {
+    seq?: unknown;
+    type?: unknown;
+    data?: unknown;
+}
+/** The pending-inbox projection replayed from a session-log prefix. */
+export interface PendingInboxWindow {
+    'next-turn': readonly unknown[];
+    'next-step': readonly unknown[];
+}
 /**
- * Settings-provider surface the legacy-namespace migration needs. Structurally
- * typed like every other host seam in this file, so bare test harnesses
- * without dsh-settings still load the module: a host lacking `describe` or
- * `mutate` simply skips the migration.
+ * Fold a session-log prefix into the pending-inbox projection state.
+ * Coordinates in the log are already normalize-at-append (dsh-agent-loop
+ * clamps start/deleteCount before appending), so each entry applies as a
+ * plain toSpliced. Events at or past `upToSeqExclusive` are ignored — pass
+ * the current splice's own seq to fold everything BEFORE it. Returns
+ * undefined when any entry is malformed enough to break the fold (the
+ * caller degrades to the projection read, as before).
  */
-interface SettingsNsLike {
-    register(n: unknown, s: unknown): {
-        get(): unknown;
-    };
-    describe?(): {
-        ns: unknown;
-        user?: unknown;
-    }[];
-    mutate?(ns: unknown, ops: readonly {
-        op: 'set';
-        path: string[];
-        value?: unknown;
-    }[]): Promise<void>;
+export declare function replayPendingInbox(events: readonly InboxEventLike[], upToSeqExclusive: number): PendingInboxWindow | undefined;
+/**
+ * Claimed-text extraction, shared verbatim by the projection read and the
+ * log replay: user-kind messages only, text blocks joined per message —
+ * the pre-0.17.0 splice-window semantics.
+ */
+export declare function claimedUserText(messages: readonly unknown[]): string;
+/** Where the resolved claimed text actually came from (see resolveClaimedText). */
+export type ClaimedTextSource = 'log-replay' | 'projection';
+export interface ClaimedTextResolution {
+    text: string;
+    source: ClaimedTextSource;
 }
 /**
- * One-time carry-over of user-tuned values from the pre-rename `llmwiki`
- * settings namespace into `topics` (ADR 0013). Constraints:
- * - one-time: only fires while the new namespace holds NO raw user overrides —
- *   describe().user is the only way to tell user keys from schema defaults,
- *   because scope.get() folds the defaults in;
- * - idempotent: after the copy (or any config written on the new name) the
- *   override check short-circuits every later boot;
- * - fail-open: registering the legacy namespace can throw (duplicate or
- *   schema-invalid stored section) and the write can reject — both contained,
- *   so plugin startup never depends on the migration.
- * Keys whose stored value equals the schema default are not copied (nothing
- * user-tuned to preserve). Returns the in-flight write for tests; apply()
- * fire-and-forgets it.
+ * Resolve the claimed text for one splice, ordering the two sources by
+ * authority (review CONCERN A, 0.17.1):
+ *
+ * 1. Session-log replay — preferred UNCONDITIONALLY whenever the event
+ *    carries a seq and a log prefix is available. The fold reproduces the
+ *    pre-splice window the claim coordinates (start/removedCount) are
+ *    defined against, so it is immune to handler order AND to the backlog
+ *    misalignment: with ≥2 pending messages the post-splice projection
+ *    read is NON-empty but shifted by one (a claim of msg1 would read
+ *    msg2's residual text), which the 0.17.0 empty-projection-only gating
+ *    missed. The replay verdict is FINAL — when the fold succeeds the
+ *    projection is not consulted, even if the replayed slice comes back
+ *    empty (the pre-splice window genuinely held no user text).
+ * 2. Projection read — the fallback for hosts where the replay cannot arm
+ *    (no event.seq on the firehose, or snapshotEvents unreachable/failed).
+ *    Pre-0.1.5 live dispatch precedes the mutation, so this read yields
+ *    the pre-splice window, as it always did.
+ *
+ * `source` names the source that ACTUALLY produced the returned text
+ * (review CONCERN B): 'log-replay' whenever the replay supplied the
+ * verdict (empty included), 'projection' only when the fallback did (or
+ * the replay never armed).
  */
-export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (message: string) => void): Promise<void> | undefined;
+export declare function resolveClaimedText(input: {
+    /** The pending window as read at handler time (post-splice on 0.1.5+). */
+    projection: readonly unknown[];
+    /** Session-log prefix up to (excluding) `seq`, or undefined when unreachable. */
+    logEvents: readonly InboxEventLike[] | undefined;
+    /** The splice event's own seq — a number marks a replay-capable host. */
+    seq: unknown;
+    target: 'next-turn' | 'next-step';
+    start: number;
+    removedCount: number;
+}): ClaimedTextResolution;
+export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+    repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    injectDedup: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    suppressEcho: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    topK: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    perTopicBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    totalBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    matchThreshold: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    tagBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    injectMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    qualityLane: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    graphDepth: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    recencyWindowDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    autoObserve: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    includeSubagents: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    observationMaxChars: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillEveryTurns: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillOnSessionEnd: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    distillProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillBatchSize: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillMaxModelCalls: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    consolidateCadence: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    repo: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    autoInject: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    injectDedup: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    suppressEcho: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    topK: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    perTopicBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    totalBudget: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    matchThreshold: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    tagBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    injectMode: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    qualityLane: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    graphDepth: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    recencyWindowDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    autoObserve: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    includeSubagents: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    observationMaxChars: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillEveryTurns: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillOnSessionEnd: import("@deepseek-ai/schemastery").default<boolean, boolean, "volatile-defined">;
+    distillProvider: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillModel: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    distillBatchSize: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    distillMaxModelCalls: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    consolidateCadence: import("@deepseek-ai/schemastery").default<string, string, "volatile-defined">;
+    deprecatedTtlDays: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    usageBoost: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+    pushDebounceSeconds: import("@deepseek-ai/schemastery").default<number, number, "volatile-defined">;
+}>>, "plain">;
+/** Live config reference as a 0.1.7 host passes it (cron / mcp-adapter
+ * spelling): `.get()` snapshots the current value — the host swaps the
+ * reference in-place when a volatile field is edited on the settings page. */
+interface VolatileRef<T> {
+    get(): T;
+}
+/** apply()-time config: live VolatileRef fields on real hosts, plain values
+ * on bare test harnesses — {@link readConfigValue} accepts both. */
+export type TopicsRuntimeConfig = Partial<{
+    [K in keyof TopicsConfigValue]: VolatileRef<TopicsConfigValue[K]> | TopicsConfigValue[K];
+}>;
 /**
  * Strip a leading YAML frontmatter block (`---` / body / `---`) from a skill
  * markdown file. `SkillDefinition.content` must be the instruction body after
@@ -64,5 +163,5 @@ export declare function migrateLegacySettings(settings: SettingsNsLike, warn?: (
  * delimiter semantics of the upstream skill-filesystem provider.
  */
 export declare function stripFrontmatter(raw: string): string;
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: TopicsRuntimeConfig): void;
 export {};