@aiwayds/dsh-topics-memory 0.18.0 → 0.18.2

package/README.md

@@ -97,7 +97,7 @@ 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>` — 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:
+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. Upgrading from a pre-0.1.7 install: a legacy top-level `topics:` section in the old `settings.yaml` is imported once into the new entry automatically at the next plugin boot (the audit record lands in `~/.dsh/storages/dsh-topics-memory/legacy-import.json`). All keys and defaults:
 
 | Key | Default | Meaning |
 |---|---|---|
@@ -142,7 +142,7 @@ This project's shape is directly inspired and supported by:
 - **Subagents are out of memory by default — one switch to opt in**: by default (`include-subagents` off since 0.7.0) delegated sessions are skipped entirely — no injection, no observation, no distill triggers; `/topics set include-subagents on` applies injection and observation to them too. The topic tools stay on the global layer, so an explicit `topic_save` from a child still lands. Out-of-process subagents (claude-code/codex providers) never load this plugin anyway.
 - **Exit is local-only (0.10.0)**: the plugin's disposer makes one local git commit of the meta sidecars (observations / injections / distill state) and never waits on the network — no pull, no push, no model call, so host exit no longer pays a git round-trip or a bounded distill wait (the old 90s cap is gone; only a 10s guard against a pathological git stall remains). The exit distill trigger is fired fire-and-forget and is skipped entirely while a session-end run is still in flight (the same pool head would otherwise be fed to the model twice). Nothing is lost by skipping: observations are write-through on disk, the deferred push is replayed by the next boot's pull, and the skipped distill is replayed there too (boot-replay). `meta/distill-state.json` records each lane's outcome, checkable via `/topics status`.
 - **Observation GC (three strikes)**: an observation the model actually evaluated (parseable answer, however useless) but no op consumed accrues one failed attempt; the third failed attempt physically deletes it — explicitly authorized cleanup of raw data the lane demonstrably cannot process. Runs that never evaluated the batch never count: infrastructure failures (network errors, unconfigured distill route → readable `no-model` short-circuit) and unparseable output (`invalid-output`) are exempt, and a batch still mid-shrink on output-limit retries is only counted once a verdict is reached (success, floor stop, stall, or an explicit skip). Deletions are committed immediately (data destruction stays git-traceable); pure attempt counters follow the usual flush cadence.
-- **Config read timing**: `/topics set` and `settings.yaml` edits take effect most reliably from the next session start.
+- **Config read timing**: `/topics set` and profile-patch edits take effect most reliably from the next session start (dsh 0.1.7: the settings document is the profile patch; the old `settings.yaml` is imported once and renamed).
 - **Picking a distill model**: `/topics onboard` splits the distill decision into two dependent questions (provider first, then that provider's model catalog), pre-validated with `resolveModelInfo` — a provider with no live route blocks and re-asks, an off-catalog model (a non-NO_ADAPTER failure: outside the advisory catalog, possibly still usable) warns but is allowed; hosts without an ask UI or a usable model route fall back to typed input. The same validation backs the `/topics set` picker panels.
 
 ## Design docs

package/README.zh.md

@@ -97,7 +97,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 
 ## 配置
 
-首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`——0.1.7+ 宿主上写设置页 `dsh-topics-memory` 条目（profile patch），全部键 volatile 免重启即时生效。全部键与默认值：
+首次配置交给 `/topics onboard`；日常微调用 `/topics set <key> <value>`——0.1.7+ 宿主上写设置页 `dsh-topics-memory` 条目（profile patch），全部键 volatile 免重启即时生效。从 0.1.7 之前升级：旧 `settings.yaml` 里的 `topics:` 段会在下次插件 boot 时一次性自动迁入新条目（审计档在 `~/.dsh/storages/dsh-topics-memory/legacy-import.json`）。全部键与默认值：
 
 | 键 | 默认 | 说明 |
 |---|---|---|
@@ -142,7 +142,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 - **子代理默认不参与记忆，可整体打开**：默认（`include-subagents` off，0.7.0 起）delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；`/topics set include-subagents on` 后注入与观察同样作用于子代理会话。topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
 - **退出路径本地化（0.10.0）**：插件 disposer 只做一步本地 git commit（meta 侧车文件：observations / injections / distill state），不再等待任何网络——没有 pull、没有 push、没有模型调用，宿主退出不再支付 git 双程与有界蒸馏等待（旧的 90s 上限移除，仅保留 10s 兜底以防病理性 git 卡死）。退出蒸馏触发改为 fire-and-forget；已有 session-end run 在跑时整体跳过（否则同一全局队头批次会被双份喂给模型）。跳过不丢活：observations 本就 write-through 落盘，推迟的 push 由下次启动的 pull 补推，被跳过的蒸馏同样由下次启动回放（boot-replay）。`meta/distill-state.json` 记录每次 lane 的结局，`/topics status` 可查。
 - **观察 GC（三振删除）**：被模型实际评估（返回了可解析应答，无论内容有无价值）却未被任何 op 消费的观察记一次 failed attempt，连续 3 次即物理删除（用户已明确授权删除 lane 确实无法处理的原始观察）。模型从未评估过的批次永不计数：基础设施失败（网络错误、蒸馏路由未配置 → 可读 `no-model` 短路）与输出不可解析（`invalid-output`）豁免；输出上限减半重试中的批次只有到达裁决（成功 / 触底 / stalled / 明确跳过）才计一次。删除立即 commit（数据销毁 git 可追溯），纯计数沿用 flush 节奏。
-- **配置读取时机**：`/topics set` 与 settings.yaml 修改在下次会话启动后生效最稳。
+- **配置读取时机**：`/topics set` 与 profile patch 修改在下次会话启动后生效最稳（dsh 0.1.7 起 settings 文档即 profile patch；旧 settings.yaml 导入一次后改名）。
 - **蒸馏选模型**：`/topics onboard` 的蒸馏一步拆成两问（先 provider 后 model，模型列表取自该 provider 的目录），选完经 `resolveModelInfo` 预校验——provider 无活路由会阻断重选，模型目录校验非 NO_ADAPTER 失败（目录外，可能仍可用）则警告但放行；无 ask UI 或无可用模型路由的环境自动退回文本输入。`/topics set` 的选择面板走同一套校验。
 
 ## 设计文档

package/lib/index.d.ts

@@ -163,5 +163,5 @@ export type TopicsRuntimeConfig = Partial<{
  * delimiter semantics of the upstream skill-filesystem provider.
  */
 export declare function stripFrontmatter(raw: string): string;
-export declare function apply(ctx: Context, config?: TopicsRuntimeConfig): void;
+export declare function apply(ctx: Context, config?: TopicsRuntimeConfig): Promise<void>;
 export {};

package/lib/index.js

@@ -35,6 +35,7 @@ import { Consolidator, dropExpiredDeprecated } from "./consolidate.js";
 import { SlowLane } from "./quality.js";
 import { CONFIG_KEYS, TopicsConfig } from "./config.js";
 import { isDelegated } from "./delegation.js";
+import { runLegacySettingsImport } from "./legacy-import.js";
 export const name = 'dsh-topics-memory';
 /**
  * Bounded wait for the process-exit meta commit. The exit path is
@@ -235,7 +236,7 @@ export function stripFrontmatter(raw) {
     }
     return raw;
 }
-export function apply(ctx, config = {}) {
+export async function apply(ctx, config = {}) {
     // `inject = ['skills']` guarantees the service exists on every real host;
     // register unconditionally so a missing service fails loud instead of
     // silently dropping the bundled skill.
@@ -893,6 +894,30 @@ export function apply(ctx, config = {}) {
         };
         cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate, resolveAsk, resolveLlm, manualDistill, manualConsolidate)), 'topics: /topics');
     });
+    // ---- One-time legacy settings import (0.1.5 → 0.1.7 upgrade path) ----
+    // The 0.1.7 host imports the old settings.yaml ONCE by "section name =
+    // entry id" and renames it settings.yaml.imported — this plugin's legacy
+    // section was named `topics`, so the host's import silently dropped it.
+    // Recover it here (see legacy-import.ts). Wired through
+    // ctx.inject(['settings'], …) instead of a direct `ctx.settings` read: a
+    // real boot can run apply() before the settings service is mounted, the
+    // direct read came up undefined, and the import then took the silent
+    // no-settings exit EVERY boot (no marker, nothing ever recovered). The
+    // inject callback fires the moment the service exists (immediately when
+    // it already does — fake-ctx tests stay synchronous), fire-and-forget so
+    // activation never waits on it. Fully contained: any failure only warns
+    // and leaves the audit marker unwritten, so the next boot retries;
+    // activation never depends on this.
+    ctx.inject(['settings'], (sctx) => {
+        void runLegacySettingsImport({
+            home: paths.resolveDshHome(),
+            settings: sctx.settings,
+            logger: ctx.logger,
+            getCurrent: (key) => cfgNow()[key],
+        }).catch((error) => {
+            warn(`dsh-topics-memory 旧 settings 迁移失败（不影响启动，下次启动重试）：${error instanceof Error ? error.message : String(error)}`);
+        });
+    });
 }
 /** Config defaults for harnesses that skip schemastery's default application. */
 const DEFAULTS = {

package/lib/legacy-import.d.ts

@@ -0,0 +1,109 @@
+/**
+ * One-time legacy settings import for the 0.1.5 → 0.1.7 upgrade: the dsh
+ * 0.1.7 host renames the old `~/.dsh/settings.yaml` to
+ * `settings.yaml.imported` and imports its sections as profile patches keyed
+ * by "section name = entry id". This plugin's old section was named `topics`,
+ * NOT `dsh-topics-memory` — the host's one-shot import silently drops it.
+ * This module recovers it once:
+ *
+ *   1. read `<home>/settings.yaml.imported` (preferred) →
+ *      `<home>/settings.yaml` (fallback);
+ *   2. flat-parse the `topics:` section (scalars only, conservative);
+ *   3. keep keys whose legacy value differs from the current effective value;
+ *   4. `settings.update('dsh-topics-memory', patch)` → on success write the
+ *      audit marker `<home>/storages/dsh-topics-memory/legacy-import.json`;
+ *      on failure warn and write nothing (the next boot retries);
+ *   5. marker present → the whole migration is skipped (idempotent — a
+ *      later manual edit of the imported file must not resurrect old values).
+ *
+ * A marker is written for EVERY settled outcome (imported / no-op /
+ * no-legacy / no-section) so this runs at most once per home. Never throws
+ * into the caller beyond what the apply()-side catch contains: plugin
+ * activation must not depend on this.
+ *
+ * @module legacy-import
+ */
+/** Profile entry id the recovered values are written to. */
+export declare const ENTRY_ID = "dsh-topics-memory";
+/** Legacy top-level section name in the old settings.yaml. */
+export declare const LEGACY_SECTION = "topics";
+/** Storage dir name for the audit marker (repo dir name, host convention). */
+export declare const STORAGE_DIR_NAME = "dsh-topics-memory";
+/** Legacy keys worth recovering, mapped 1:1 onto Config keys of the same name. */
+export declare const LEGACY_KEYS: readonly ["repo", "distillProvider", "distillModel", "topK", "totalBudget", "autoObserve"];
+export type LegacyKey = (typeof LEGACY_KEYS)[number];
+/** The settings seam the import writes through (`ctx.settings.update`). */
+export interface SettingsUpdateSeam {
+    update(ns: string, patch: object): Promise<void>;
+}
+/** Minimal logger surface (both sinks optional — bare harnesses have none). */
+export interface LegacyImportLogger {
+    info?(message: string): void;
+    warn?(message: string): void;
+}
+export interface LegacyImportInput {
+    /** Resolved dsh home (`paths.resolveDshHome()` at the call site). */
+    home: string;
+    /** `ctx.settings` — absent/unusable seams skip the import without a marker. */
+    settings?: SettingsUpdateSeam | undefined;
+    /** Host logger (optional). */
+    logger?: LegacyImportLogger | undefined;
+    /** Current effective value for one legacy key (Volatile ref `.get()` at the call site). */
+    getCurrent(key: LegacyKey): unknown;
+    /**
+     * Retry budget for `settings.update`. The host serializes profile writes
+     * (settings.update → dsh-config-editor) behind the `<profile>/package.json`
+     * writer lock with a 2s per-call deadline, and during BOOT the host itself
+     * holds that lock while preparing the profile — a single bare call almost
+     * always times out (2026-09-25 incident: the import failed EVERY boot and
+     * the migration never converged). Defaults to 5 attempts 2s apart; a
+     * permanently orphaned lock (a SIGKILLed host never releases it — orphan
+     * recovery is an operator action) still exhausts the budget and stays
+     * retry-worthy. Tests shrink this to keep the suite fast.
+     */
+    updateRetry?: {
+        attempts: number;
+        delayMs: number;
+    } | undefined;
+}
+export type LegacyImportOutcome = 'imported' | 'no-op' | 'no-legacy' | 'no-section' | 'marker-exists' | 'no-settings' | 'update-failed';
+export interface LegacyImportResult {
+    outcome: LegacyImportOutcome;
+    /** Keys written through settings.update (also in the marker). */
+    imported: Record<string, unknown>;
+    /** Keys not imported, with the reason (audit trail). */
+    skipped: Record<string, string>;
+}
+/** Candidates in priority order: the host's renamed document first. */
+export declare function legacySettingsCandidates(home: string): string[];
+/** Audit marker path: `<home>/storages/<dir>/legacy-import.json`. */
+export declare function legacyMarkerPath(home: string): string;
+/**
+ * Scalar inference for one flat `key: value` value. Quoted values are
+ * unquoted (mirroring src/yaml.ts); a single-line quoted flow-JSON value
+ * (`'["a","b"]'`) is JSON-parsed after unquoting — a malformed one stays a
+ * string. Unquoted flow collections are kept as strings (conservative:
+ * this is not a full YAML parser). Empty never reaches here (the line
+ * parser skips value-less keys — they open a nested block).
+ */
+export declare function inferScalar(raw: string): unknown;
+/**
+ * Flat section parser: locate the top-level `section:` line and collect its
+ * DIRECT children (`key: value` at one common indent) until the next
+ * top-level key. Deliberately conservative — NOT a YAML parser:
+ * - `key:` with an empty value (opens a nested map/sequence) is skipped, and
+ *   the deeper lines under it never match the child indent, so folded values
+ *   are skipped whole;
+ * - lines at any other indent are ignored;
+ * - an inline value on the header line itself (`section: x`) is not a flat
+ *   map → `{}`.
+ * Pure function — tests run it against literal strings.
+ */
+export declare function parseFlatSection(raw: string, section: string): Record<string, unknown>;
+/**
+ * Run the one-time import. Resolves with the outcome; only throws on truly
+ * unexpected I/O errors (the apply()-side catch contains those). The marker
+ * is written for every settled outcome EXCEPT the retry-worthy failures
+ * (`no-settings`, `update-failed`) — those must re-run at the next boot.
+ */
+export declare function runLegacySettingsImport(input: LegacyImportInput): Promise<LegacyImportResult>;

package/lib/legacy-import.js

@@ -0,0 +1,243 @@
+/**
+ * One-time legacy settings import for the 0.1.5 → 0.1.7 upgrade: the dsh
+ * 0.1.7 host renames the old `~/.dsh/settings.yaml` to
+ * `settings.yaml.imported` and imports its sections as profile patches keyed
+ * by "section name = entry id". This plugin's old section was named `topics`,
+ * NOT `dsh-topics-memory` — the host's one-shot import silently drops it.
+ * This module recovers it once:
+ *
+ *   1. read `<home>/settings.yaml.imported` (preferred) →
+ *      `<home>/settings.yaml` (fallback);
+ *   2. flat-parse the `topics:` section (scalars only, conservative);
+ *   3. keep keys whose legacy value differs from the current effective value;
+ *   4. `settings.update('dsh-topics-memory', patch)` → on success write the
+ *      audit marker `<home>/storages/dsh-topics-memory/legacy-import.json`;
+ *      on failure warn and write nothing (the next boot retries);
+ *   5. marker present → the whole migration is skipped (idempotent — a
+ *      later manual edit of the imported file must not resurrect old values).
+ *
+ * A marker is written for EVERY settled outcome (imported / no-op /
+ * no-legacy / no-section) so this runs at most once per home. Never throws
+ * into the caller beyond what the apply()-side catch contains: plugin
+ * activation must not depend on this.
+ *
+ * @module legacy-import
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/** Profile entry id the recovered values are written to. */
+export const ENTRY_ID = 'dsh-topics-memory';
+/** Legacy top-level section name in the old settings.yaml. */
+export const LEGACY_SECTION = 'topics';
+/** Storage dir name for the audit marker (repo dir name, host convention). */
+export const STORAGE_DIR_NAME = 'dsh-topics-memory';
+/** Legacy keys worth recovering, mapped 1:1 onto Config keys of the same name. */
+export const LEGACY_KEYS = ['repo', 'distillProvider', 'distillModel', 'topK', 'totalBudget', 'autoObserve'];
+/** Candidates in priority order: the host's renamed document first. */
+export function legacySettingsCandidates(home) {
+    return [join(home, 'settings.yaml.imported'), join(home, 'settings.yaml')];
+}
+/** Audit marker path: `<home>/storages/<dir>/legacy-import.json`. */
+export function legacyMarkerPath(home) {
+    return join(home, 'storages', STORAGE_DIR_NAME, 'legacy-import.json');
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** A fully quoted scalar: balanced matching quote pair. */
+function isQuoted(s) {
+    return s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")));
+}
+function unquote(s) {
+    const inner = s.slice(1, -1);
+    // Double quotes: unescape \" and \\; single quotes: '' is a literal '.
+    if (s.startsWith('"'))
+        return inner.replaceAll('\\"', '"').replaceAll('\\\\', '\\');
+    return inner.replaceAll("''", "'");
+}
+/**
+ * Scalar inference for one flat `key: value` value. Quoted values are
+ * unquoted (mirroring src/yaml.ts); a single-line quoted flow-JSON value
+ * (`'["a","b"]'`) is JSON-parsed after unquoting — a malformed one stays a
+ * string. Unquoted flow collections are kept as strings (conservative:
+ * this is not a full YAML parser). Empty never reaches here (the line
+ * parser skips value-less keys — they open a nested block).
+ */
+export function inferScalar(raw) {
+    const s = raw.trim();
+    if (isQuoted(s)) {
+        const inner = unquote(s);
+        const t = inner.trim();
+        if (t.startsWith('[') || t.startsWith('{')) {
+            try {
+                return JSON.parse(t);
+            }
+            catch {
+                // not JSON after all — keep the unquoted string
+            }
+        }
+        return inner;
+    }
+    if (s === 'true' || s === 'True' || s === 'TRUE')
+        return true;
+    if (s === 'false' || s === 'False' || s === 'FALSE')
+        return false;
+    if (/^-?\d+$/.test(s) || /^-?\d+\.\d+$/.test(s))
+        return Number(s);
+    return s;
+}
+/**
+ * Flat section parser: locate the top-level `section:` line and collect its
+ * DIRECT children (`key: value` at one common indent) until the next
+ * top-level key. Deliberately conservative — NOT a YAML parser:
+ * - `key:` with an empty value (opens a nested map/sequence) is skipped, and
+ *   the deeper lines under it never match the child indent, so folded values
+ *   are skipped whole;
+ * - lines at any other indent are ignored;
+ * - an inline value on the header line itself (`section: x`) is not a flat
+ *   map → `{}`.
+ * Pure function — tests run it against literal strings.
+ */
+export function parseFlatSection(raw, section) {
+    const lines = raw.split('\n').map((l) => l.replace(/\r$/, ''));
+    const header = new RegExp(`^${escapeRegExp(section)}:(.*)$`);
+    const start = lines.findIndex((l) => header.test(l));
+    if (start < 0)
+        return {};
+    // An inline header value means the section is not a block map of children.
+    if (lines[start].replace(header, '$1').trim() !== '')
+        return {};
+    const out = {};
+    let childIndent;
+    for (let i = start + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '' || line.trimStart().startsWith('#'))
+            continue;
+        const indent = line.length - line.trimStart().length;
+        if (indent === 0)
+            break; // next top-level key — section over
+        if (childIndent === undefined)
+            childIndent = indent;
+        if (indent !== childIndent)
+            continue; // nested block content — skipped
+        const match = /^([^\s:][^:]*):(?:[ \t]+(.*))?$/.exec(line.trim());
+        if (match === null)
+            continue; // not a `key: value` line — skipped
+        if (match[2] === undefined || match[2].trim() === '')
+            continue; // opens a nested block
+        out[match[1].trim()] = inferScalar(match[2]);
+    }
+    return out;
+}
+/**
+ * Run the one-time import. Resolves with the outcome; only throws on truly
+ * unexpected I/O errors (the apply()-side catch contains those). The marker
+ * is written for every settled outcome EXCEPT the retry-worthy failures
+ * (`no-settings`, `update-failed`) — those must re-run at the next boot.
+ */
+export async function runLegacySettingsImport(input) {
+    const skipped = {};
+    const imported = {};
+    const warn = (message) => {
+        try {
+            input.logger?.warn?.(message);
+        }
+        catch {
+            // contained — a broken logger must not break the import
+        }
+    };
+    const info = (message) => {
+        try {
+            input.logger?.info?.(message);
+        }
+        catch {
+            // contained
+        }
+    };
+    const markerPath = legacyMarkerPath(input.home);
+    if (existsSync(markerPath))
+        return { outcome: 'marker-exists', imported, skipped };
+    // A settings seam that cannot accept the patch is a retry-worthy state:
+    // return WITHOUT reading/marking, so a host that mounts the service later
+    // (and a test harness pointing at a real home) neither imports nor writes.
+    // Not silent: the 2026-09-24 incident hid exactly behind this quiet exit —
+    // the warn is what makes a never-mounting seam observable in a boot log.
+    const settings = input.settings;
+    if (settings === undefined || typeof settings.update !== 'function') {
+        warn(`${ENTRY_ID}: legacy settings import deferred: settings seam unusable (no-settings; will retry next boot)`);
+        return { outcome: 'no-settings', imported, skipped };
+    }
+    // Locate the legacy document.
+    const source = legacySettingsCandidates(input.home).find((p) => existsSync(p));
+    if (source === undefined) {
+        writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-legacy', source: undefined, imported, skipped });
+        return { outcome: 'no-legacy', imported, skipped };
+    }
+    const section = parseFlatSection(readFileSync(source, 'utf8'), LEGACY_SECTION);
+    // The marker records the source BASENAME: the marker lives inside the same
+    // home, so the directory part is implied.
+    const sourceName = source.slice(source.lastIndexOf('/') + 1);
+    const present = Object.keys(section);
+    if (present.length === 0) {
+        writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-section', source: sourceName, imported, skipped });
+        return { outcome: 'no-section', imported, skipped };
+    }
+    // Key-level rule: import only when the legacy value differs from the
+    // current effective value; keys this plugin does not know are recorded and
+    // left alone (an unknown key would be rejected by the host's schema).
+    for (const key of present) {
+        if (!LEGACY_KEYS.includes(key)) {
+            skipped[key] = 'unknown-key';
+            continue;
+        }
+        const legacyValue = section[key];
+        if (legacyValue === input.getCurrent(key))
+            skipped[key] = 'equal';
+        else
+            imported[key] = legacyValue;
+    }
+    if (Object.keys(imported).length === 0) {
+        writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-op', source: sourceName, imported, skipped });
+        info(`${ENTRY_ID}: legacy settings import (${LEGACY_SECTION} → ${ENTRY_ID}): nothing to import (all values equal or unknown)`);
+        return { outcome: 'no-op', imported, skipped };
+    }
+    // The update contends on the host's profile writer lock (see
+    // {@link LegacyImportInput.updateRetry}): retry with a fixed gap before
+    // conceding. Every failed attempt warns — a silent loss here cost a full
+    // day of "the migration never runs" debugging (2026-09-25).
+    const retry = input.updateRetry ?? { attempts: 5, delayMs: 2_000 };
+    let updateFailed;
+    for (let attempt = 1; attempt <= retry.attempts; attempt++) {
+        try {
+            await settings.update(ENTRY_ID, imported);
+            updateFailed = undefined;
+            break;
+        }
+        catch (error) {
+            updateFailed = error;
+            warn(`${ENTRY_ID}: legacy settings import: settings.update attempt ${attempt}/${retry.attempts} failed: ${error instanceof Error ? error.message : String(error)}`);
+            if (attempt < retry.attempts)
+                await new Promise((resolve) => setTimeout(resolve, retry.delayMs));
+        }
+    }
+    if (updateFailed !== undefined) {
+        warn(`${ENTRY_ID}: legacy settings import failed (will retry next boot): ${updateFailed instanceof Error ? updateFailed.message : String(updateFailed)}`);
+        // No marker: the next boot retries the import.
+        return { outcome: 'update-failed', imported, skipped };
+    }
+    writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'imported', source: sourceName, imported, skipped });
+    info(`${ENTRY_ID}: legacy settings import (${LEGACY_SECTION} → ${ENTRY_ID}): ${Object.keys(imported).join(', ')}`);
+    return { outcome: 'imported', imported, skipped };
+}
+/** Persist the audit marker; a failed write leaves no marker (harmless — the
+ *  next boot re-runs and converges, every step after the marker check is
+ *  idempotent). */
+function writeMarker(path, marker) {
+    try {
+        mkdirSync(join(path, '..'), { recursive: true });
+        writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`);
+    }
+    catch {
+        // contained — see above
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "dsh-plugin: quality-first topic memory for dsh — a topic keeps the starting question, conclusion, impact and dependencies, not the process; local-first git-traced OKF bundle, budgeted LLM-free injection",
   "type": "module",
   "main": "lib/index.js",
@@ -42,7 +42,7 @@
     "build": "tsc -p tsconfig.json",
     "check": "tsc --noEmit -p tsconfig.json",
     "pretest": "tsc -p tsconfig.json",
-    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs",
+    "test": "node --test test/yaml.test.mjs test/okf.test.mjs test/retrieval.test.mjs test/digest.test.mjs test/ilog.test.mjs test/store.test.mjs test/paths.test.mjs test/git.test.mjs test/sync.test.mjs test/tools.test.mjs test/dedup.test.mjs test/commands.test.mjs test/onboard.test.mjs test/delegation.test.mjs test/observer.test.mjs test/distill.test.mjs test/consolidate.test.mjs test/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs test/skill.test.mjs test/fast-lane.test.mjs test/legacy-import.test.mjs",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},

package/src/index.ts

@@ -52,6 +52,7 @@ import type { SlowDelivery } from './service.ts'
 import { CONFIG_KEYS, TopicsConfig, type TopicsConfigValue } from './config.ts'
 import type { AskServiceResolver, AskServiceShape, LlmDirectoryResolver, LlmDirectoryShape } from './onboard.ts'
 import { isDelegated } from './delegation.ts'
+import { runLegacySettingsImport, type LegacyImportLogger, type SettingsUpdateSeam } from './legacy-import.ts'
 
 export const name = 'dsh-topics-memory'
 
@@ -354,7 +355,7 @@ export function stripFrontmatter(raw: string): string {
   return raw
 }
 
-export function apply(ctx: Context, config: TopicsRuntimeConfig = {}): void {
+export async function apply(ctx: Context, config: TopicsRuntimeConfig = {}): Promise<void> {
   // `inject = ['skills']` guarantees the service exists on every real host;
   // register unconditionally so a missing service fails loud instead of
   // silently dropping the bundled skill.
@@ -1010,6 +1011,31 @@ export function apply(ctx: Context, config: TopicsRuntimeConfig = {}): void {
     }
     cmdCtx.effect(() => commands.register(buildTopicsCommand(service, mutate as never, resolveAsk, resolveLlm, manualDistill, manualConsolidate)), 'topics: /topics')
   })
+
+  // ---- One-time legacy settings import (0.1.5 → 0.1.7 upgrade path) ----
+  // The 0.1.7 host imports the old settings.yaml ONCE by "section name =
+  // entry id" and renames it settings.yaml.imported — this plugin's legacy
+  // section was named `topics`, so the host's import silently dropped it.
+  // Recover it here (see legacy-import.ts). Wired through
+  // ctx.inject(['settings'], …) instead of a direct `ctx.settings` read: a
+  // real boot can run apply() before the settings service is mounted, the
+  // direct read came up undefined, and the import then took the silent
+  // no-settings exit EVERY boot (no marker, nothing ever recovered). The
+  // inject callback fires the moment the service exists (immediately when
+  // it already does — fake-ctx tests stay synchronous), fire-and-forget so
+  // activation never waits on it. Fully contained: any failure only warns
+  // and leaves the audit marker unwritten, so the next boot retries;
+  // activation never depends on this.
+  ctx.inject(['settings'], (sctx) => {
+    void runLegacySettingsImport({
+      home: paths.resolveDshHome(),
+      settings: (sctx as unknown as { settings?: SettingsUpdateSeam }).settings,
+      logger: (ctx as unknown as { logger?: LegacyImportLogger }).logger,
+      getCurrent: (key) => cfgNow()[key],
+    }).catch((error) => {
+      warn(`dsh-topics-memory 旧 settings 迁移失败（不影响启动，下次启动重试）：${error instanceof Error ? error.message : String(error)}`)
+    })
+  })
 }
 
 /** Config defaults for harnesses that skip schemastery's default application. */

package/src/legacy-import.ts

@@ -0,0 +1,297 @@
+/**
+ * One-time legacy settings import for the 0.1.5 → 0.1.7 upgrade: the dsh
+ * 0.1.7 host renames the old `~/.dsh/settings.yaml` to
+ * `settings.yaml.imported` and imports its sections as profile patches keyed
+ * by "section name = entry id". This plugin's old section was named `topics`,
+ * NOT `dsh-topics-memory` — the host's one-shot import silently drops it.
+ * This module recovers it once:
+ *
+ *   1. read `<home>/settings.yaml.imported` (preferred) →
+ *      `<home>/settings.yaml` (fallback);
+ *   2. flat-parse the `topics:` section (scalars only, conservative);
+ *   3. keep keys whose legacy value differs from the current effective value;
+ *   4. `settings.update('dsh-topics-memory', patch)` → on success write the
+ *      audit marker `<home>/storages/dsh-topics-memory/legacy-import.json`;
+ *      on failure warn and write nothing (the next boot retries);
+ *   5. marker present → the whole migration is skipped (idempotent — a
+ *      later manual edit of the imported file must not resurrect old values).
+ *
+ * A marker is written for EVERY settled outcome (imported / no-op /
+ * no-legacy / no-section) so this runs at most once per home. Never throws
+ * into the caller beyond what the apply()-side catch contains: plugin
+ * activation must not depend on this.
+ *
+ * @module legacy-import
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Profile entry id the recovered values are written to. */
+export const ENTRY_ID = 'dsh-topics-memory'
+
+/** Legacy top-level section name in the old settings.yaml. */
+export const LEGACY_SECTION = 'topics'
+
+/** Storage dir name for the audit marker (repo dir name, host convention). */
+export const STORAGE_DIR_NAME = 'dsh-topics-memory'
+
+/** Legacy keys worth recovering, mapped 1:1 onto Config keys of the same name. */
+export const LEGACY_KEYS = ['repo', 'distillProvider', 'distillModel', 'topK', 'totalBudget', 'autoObserve'] as const
+
+export type LegacyKey = (typeof LEGACY_KEYS)[number]
+
+/** The settings seam the import writes through (`ctx.settings.update`). */
+export interface SettingsUpdateSeam {
+  update(ns: string, patch: object): Promise<void>
+}
+
+/** Minimal logger surface (both sinks optional — bare harnesses have none). */
+export interface LegacyImportLogger {
+  info?(message: string): void
+  warn?(message: string): void
+}
+
+export interface LegacyImportInput {
+  /** Resolved dsh home (`paths.resolveDshHome()` at the call site). */
+  home: string
+  /** `ctx.settings` — absent/unusable seams skip the import without a marker. */
+  settings?: SettingsUpdateSeam | undefined
+  /** Host logger (optional). */
+  logger?: LegacyImportLogger | undefined
+  /** Current effective value for one legacy key (Volatile ref `.get()` at the call site). */
+  getCurrent(key: LegacyKey): unknown
+  /**
+   * Retry budget for `settings.update`. The host serializes profile writes
+   * (settings.update → dsh-config-editor) behind the `<profile>/package.json`
+   * writer lock with a 2s per-call deadline, and during BOOT the host itself
+   * holds that lock while preparing the profile — a single bare call almost
+   * always times out (2026-09-25 incident: the import failed EVERY boot and
+   * the migration never converged). Defaults to 5 attempts 2s apart; a
+   * permanently orphaned lock (a SIGKILLed host never releases it — orphan
+   * recovery is an operator action) still exhausts the budget and stays
+   * retry-worthy. Tests shrink this to keep the suite fast.
+   */
+  updateRetry?: { attempts: number; delayMs: number } | undefined
+}
+
+export type LegacyImportOutcome =
+  | 'imported' // ≥1 key written through settings.update, marker written
+  | 'no-op' // section found but every key equal/unknown, marker written
+  | 'no-legacy' // neither legacy file exists, marker written
+  | 'no-section' // legacy file exists without a `topics:` section, marker written
+  | 'marker-exists' // already migrated before — nothing touched
+  | 'no-settings' // settings seam unusable — no marker, retried next boot
+  | 'update-failed' // settings.update rejected — no marker, retried next boot
+
+export interface LegacyImportResult {
+  outcome: LegacyImportOutcome
+  /** Keys written through settings.update (also in the marker). */
+  imported: Record<string, unknown>
+  /** Keys not imported, with the reason (audit trail). */
+  skipped: Record<string, string>
+}
+
+/** Candidates in priority order: the host's renamed document first. */
+export function legacySettingsCandidates(home: string): string[] {
+  return [join(home, 'settings.yaml.imported'), join(home, 'settings.yaml')]
+}
+
+/** Audit marker path: `<home>/storages/<dir>/legacy-import.json`. */
+export function legacyMarkerPath(home: string): string {
+  return join(home, 'storages', STORAGE_DIR_NAME, 'legacy-import.json')
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** A fully quoted scalar: balanced matching quote pair. */
+function isQuoted(s: string): boolean {
+  return s.length >= 2 && ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'")))
+}
+
+function unquote(s: string): string {
+  const inner = s.slice(1, -1)
+  // Double quotes: unescape \" and \\; single quotes: '' is a literal '.
+  if (s.startsWith('"')) return inner.replaceAll('\\"', '"').replaceAll('\\\\', '\\')
+  return inner.replaceAll("''", "'")
+}
+
+/**
+ * Scalar inference for one flat `key: value` value. Quoted values are
+ * unquoted (mirroring src/yaml.ts); a single-line quoted flow-JSON value
+ * (`'["a","b"]'`) is JSON-parsed after unquoting — a malformed one stays a
+ * string. Unquoted flow collections are kept as strings (conservative:
+ * this is not a full YAML parser). Empty never reaches here (the line
+ * parser skips value-less keys — they open a nested block).
+ */
+export function inferScalar(raw: string): unknown {
+  const s = raw.trim()
+  if (isQuoted(s)) {
+    const inner = unquote(s)
+    const t = inner.trim()
+    if (t.startsWith('[') || t.startsWith('{')) {
+      try {
+        return JSON.parse(t)
+      } catch {
+        // not JSON after all — keep the unquoted string
+      }
+    }
+    return inner
+  }
+  if (s === 'true' || s === 'True' || s === 'TRUE') return true
+  if (s === 'false' || s === 'False' || s === 'FALSE') return false
+  if (/^-?\d+$/.test(s) || /^-?\d+\.\d+$/.test(s)) return Number(s)
+  return s
+}
+
+/**
+ * Flat section parser: locate the top-level `section:` line and collect its
+ * DIRECT children (`key: value` at one common indent) until the next
+ * top-level key. Deliberately conservative — NOT a YAML parser:
+ * - `key:` with an empty value (opens a nested map/sequence) is skipped, and
+ *   the deeper lines under it never match the child indent, so folded values
+ *   are skipped whole;
+ * - lines at any other indent are ignored;
+ * - an inline value on the header line itself (`section: x`) is not a flat
+ *   map → `{}`.
+ * Pure function — tests run it against literal strings.
+ */
+export function parseFlatSection(raw: string, section: string): Record<string, unknown> {
+  const lines = raw.split('\n').map((l) => l.replace(/\r$/, ''))
+  const header = new RegExp(`^${escapeRegExp(section)}:(.*)$`)
+  const start = lines.findIndex((l) => header.test(l))
+  if (start < 0) return {}
+  // An inline header value means the section is not a block map of children.
+  if (lines[start].replace(header, '$1').trim() !== '') return {}
+  const out: Record<string, unknown> = {}
+  let childIndent: number | undefined
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]
+    if (line.trim() === '' || line.trimStart().startsWith('#')) continue
+    const indent = line.length - line.trimStart().length
+    if (indent === 0) break // next top-level key — section over
+    if (childIndent === undefined) childIndent = indent
+    if (indent !== childIndent) continue // nested block content — skipped
+    const match = /^([^\s:][^:]*):(?:[ \t]+(.*))?$/.exec(line.trim())
+    if (match === null) continue // not a `key: value` line — skipped
+    if (match[2] === undefined || match[2].trim() === '') continue // opens a nested block
+    out[match[1].trim()] = inferScalar(match[2])
+  }
+  return out
+}
+
+/**
+ * Run the one-time import. Resolves with the outcome; only throws on truly
+ * unexpected I/O errors (the apply()-side catch contains those). The marker
+ * is written for every settled outcome EXCEPT the retry-worthy failures
+ * (`no-settings`, `update-failed`) — those must re-run at the next boot.
+ */
+export async function runLegacySettingsImport(input: LegacyImportInput): Promise<LegacyImportResult> {
+  const skipped: Record<string, string> = {}
+  const imported: Record<string, unknown> = {}
+  const warn = (message: string): void => {
+    try {
+      input.logger?.warn?.(message)
+    } catch {
+      // contained — a broken logger must not break the import
+    }
+  }
+  const info = (message: string): void => {
+    try {
+      input.logger?.info?.(message)
+    } catch {
+      // contained
+    }
+  }
+
+  const markerPath = legacyMarkerPath(input.home)
+  if (existsSync(markerPath)) return { outcome: 'marker-exists', imported, skipped }
+
+  // A settings seam that cannot accept the patch is a retry-worthy state:
+  // return WITHOUT reading/marking, so a host that mounts the service later
+  // (and a test harness pointing at a real home) neither imports nor writes.
+  // Not silent: the 2026-09-24 incident hid exactly behind this quiet exit —
+  // the warn is what makes a never-mounting seam observable in a boot log.
+  const settings = input.settings
+  if (settings === undefined || typeof settings.update !== 'function') {
+    warn(`${ENTRY_ID}: legacy settings import deferred: settings seam unusable (no-settings; will retry next boot)`)
+    return { outcome: 'no-settings', imported, skipped }
+  }
+
+  // Locate the legacy document.
+  const source = legacySettingsCandidates(input.home).find((p) => existsSync(p))
+  if (source === undefined) {
+    writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-legacy', source: undefined, imported, skipped })
+    return { outcome: 'no-legacy', imported, skipped }
+  }
+
+  const section = parseFlatSection(readFileSync(source, 'utf8'), LEGACY_SECTION)
+  // The marker records the source BASENAME: the marker lives inside the same
+  // home, so the directory part is implied.
+  const sourceName = source.slice(source.lastIndexOf('/') + 1)
+  const present = Object.keys(section)
+  if (present.length === 0) {
+    writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-section', source: sourceName, imported, skipped })
+    return { outcome: 'no-section', imported, skipped }
+  }
+
+  // Key-level rule: import only when the legacy value differs from the
+  // current effective value; keys this plugin does not know are recorded and
+  // left alone (an unknown key would be rejected by the host's schema).
+  for (const key of present) {
+    if (!(LEGACY_KEYS as readonly string[]).includes(key)) {
+      skipped[key] = 'unknown-key'
+      continue
+    }
+    const legacyValue = section[key]
+    if (legacyValue === input.getCurrent(key as LegacyKey)) skipped[key] = 'equal'
+    else imported[key] = legacyValue
+  }
+
+  if (Object.keys(imported).length === 0) {
+    writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'no-op', source: sourceName, imported, skipped })
+    info(`${ENTRY_ID}: legacy settings import (${LEGACY_SECTION} → ${ENTRY_ID}): nothing to import (all values equal or unknown)`)
+    return { outcome: 'no-op', imported, skipped }
+  }
+
+  // The update contends on the host's profile writer lock (see
+  // {@link LegacyImportInput.updateRetry}): retry with a fixed gap before
+  // conceding. Every failed attempt warns — a silent loss here cost a full
+  // day of "the migration never runs" debugging (2026-09-25).
+  const retry = input.updateRetry ?? { attempts: 5, delayMs: 2_000 }
+  let updateFailed: unknown
+  for (let attempt = 1; attempt <= retry.attempts; attempt++) {
+    try {
+      await settings.update(ENTRY_ID, imported)
+      updateFailed = undefined
+      break
+    } catch (error) {
+      updateFailed = error
+      warn(`${ENTRY_ID}: legacy settings import: settings.update attempt ${attempt}/${retry.attempts} failed: ${error instanceof Error ? error.message : String(error)}`)
+      if (attempt < retry.attempts) await new Promise((resolve) => setTimeout(resolve, retry.delayMs))
+    }
+  }
+  if (updateFailed !== undefined) {
+    warn(`${ENTRY_ID}: legacy settings import failed (will retry next boot): ${updateFailed instanceof Error ? updateFailed.message : String(updateFailed)}`)
+    // No marker: the next boot retries the import.
+    return { outcome: 'update-failed', imported, skipped }
+  }
+
+  writeMarker(markerPath, { at: new Date().toISOString(), outcome: 'imported', source: sourceName, imported, skipped })
+  info(`${ENTRY_ID}: legacy settings import (${LEGACY_SECTION} → ${ENTRY_ID}): ${Object.keys(imported).join(', ')}`)
+  return { outcome: 'imported', imported, skipped }
+}
+
+/** Persist the audit marker; a failed write leaves no marker (harmless — the
+ *  next boot re-runs and converges, every step after the marker check is
+ *  idempotent). */
+function writeMarker(path: string, marker: Record<string, unknown>): void {
+  try {
+    mkdirSync(join(path, '..'), { recursive: true })
+    writeFileSync(path, `${JSON.stringify(marker, null, 2)}\n`)
+  } catch {
+    // contained — see above
+  }
+}