@aiwayds/dsh-topics-memory 0.8.1 → 0.10.0

package/README.md

@@ -6,10 +6,28 @@ A dsh plugin: maintains "working topic memory" as an [OKF (Open Knowledge Format
 
 > **Requires dsh >= 0.1.2-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
+
+The full flow in about four minutes: topics captured, distilled, and injected in a real session.
+
+https://github.com/user-attachments/assets/8c06cc98-b1ed-402b-9110-4f9a93eb15bc
+
 ## The problem it solves
 
 Long sessions forget. Cross-session, even more so. This plugin maintains **structured topic memory**: each Topic records a matter's **name, dependencies, open questions, current conclusion, impact, and recommendations**. When a conclusion changes, edit the file and commit — `git log` directly answers "when, by whom, and why did this conclusion change".
 
+## Why this plugin exists: memory is edited, not accumulated
+
+The short version: **more memory is not better memory.**
+
+Most memory tools assume accumulation — record everything, retrieve broadly. That may work for humans; for LLMs it backfires twice over. Model attention is a finite resource, so a giant memory bank means every turn is spent digging for signal in noise. Worse, process memories hoard intermediate judgments that were right once and wrong later — and they will confidently steer the model into bad decisions.
+
+So this plugin takes a hard editorial line on what deserves to be remembered: **a topic records exactly four things — the question that started it, the conclusion it reached, what it impacts, and what it depends on. Everything in between — the discussion, the dead ends, the wrong turns — is deliberately not memory.** Process belongs to the session; when the session ends, it goes. Only conclusions that survive distillation make it into the bundle.
+
+Short-term memory is the session's own job — the conversation context already is one, and a plugin that feeds it back is noise. Long-term memory belongs to topics: small, structured, git-traceable, injected in budgeted slices with zero hits meaning zero injection. Every turn hands the model the **minimum high-value context**, not the biggest warehouse.
+
+This plugin is not trying to be the model's notebook. It is trying to be the model's editor: deciding what is worth keeping — and, more importantly, what should be forgotten.
+
 ## Core features
 
 - **Strict OKF v0.2 compliance**: each Topic is a `markdown + YAML frontmatter` concept document (`type: Topic`) that the whole OKF ecosystem (Obsidian, OKF validators) can consume directly; ships with the provenance (`sources`), trust (`generated`/`verified`), and lifecycle (`status`/`stale_after`) field families.
@@ -30,7 +48,7 @@ Long sessions forget. Cross-session, even more so. This plugin maintains **struc
 
 | Model tools | Purpose |
 |---|---|
-| `topic_save` | Distill/revise a Topic (name / dependencies / open questions / conclusion / impact / recommendations) |
+| `topic_save` | Save/revise a Topic (name / dependencies / open questions / conclusion / impact / recommendations) |
 | `topic_observe` | Jot an atomic observation (decision/finding/constraint/question), pending distill |
 | `topic_search` | LLM-free keyword search over memory |
 | `topic_history` | A topic's conclusion change history (git log as a tool) |
@@ -115,7 +133,7 @@ This project's shape is directly inspired and supported by:
 ## Known boundaries
 
 - **Subagents engage memory by default — one switch to opt out**: by default (`include-subagents` on), injection and observation apply to subagent sessions too. `/topics set include-subagents off` skips delegated sessions entirely — no injection, no observation, no distill triggers; 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.
-- **Session-end distill in headless one-shot sessions**: the plugin's disposer now waits (bounded, up to 90s) for the exit-triggered distill to land before unload completes, so a headless process no longer loses that race by default; a hanging model call gives up at the cap and exit proceeds without that run. Within that 90s window the exit run may complete only part of its call budget — the remaining backlog waits for the next trigger. The exit trigger is skipped entirely while a session-end run is still in flight (the same pool head would otherwise be fed to the model twice). Manual `/topics distill` runs inside a live session bypass the race entirely; `meta/distill-state.json` records each lane's outcome, checkable via `/topics status`.
+- **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.
 - **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.

package/README.zh.md

@@ -6,10 +6,28 @@
 
 > **要求 dsh >= 0.1.2-rc.1** — 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**
 
+## 演示
+
+约 4 分钟的完整流程：topic 沉淀、蒸馏、注入在真实会话里跑起来。
+
+https://github.com/user-attachments/assets/6e9b346d-2ec9-4148-ae62-7087797d3188
+
 ## 它解决什么问题
 
 长会话会失忆，跨会话更会。本插件维护一份**结构化的 topic 记忆**：每个 Topic 记录一件事的**名字、依赖、未决问题、目前结论、影响、建议**。结论变了就改文件、打 commit——`git log` 直接回答「这个结论什么时候、被谁、为什么改的」。
 
+## 初衷：记忆是编辑出来的，不是攒出来的
+
+先说结论：**记忆不是越多越好。**
+
+「记忆」类产品的常见思路是多多益善——能记的都记，用时全量检索。这对人也许成立，对 LLM 恰恰相反，而且反在两处：模型的注意力是有限资源，巨型记忆库意味着每一轮对话都在噪音里翻找信号；更危险的是，过程记忆里囤着大量「当时正确、事后失效」的中间判断，它们会理直气壮地把模型引向错误的决定。
+
+所以本插件对「记什么」做了一次苛刻的取舍：**一个 topic 只记四件事——它从什么问题开始、得出了什么结论、影响什么、依赖什么。至于得出结论的过程：讨论、试错、绕过的弯路，一概不记。**过程属于 session，session 结束就该随它去；能留下的，只有经得起蒸馏的结论。
+
+短时记忆交给 session，对话上下文本就是它，不需要插件再回喂一遍；长时记忆交给 topics——小、结构化、git 可追溯，注入按预算切片、零命中零注入，每轮给模型的都是**最小的高价值上下文**，而不是越大越好的仓库。
+
+所以这个插件想做的不是模型的记事本，而是模型的编辑：替它决定什么值得记住，以及——更要紧的——什么应该被忘掉。
+
 ## 核心特性
 
 - **OKF v0.2 严格合规**：每个 Topic 是 `markdown + YAML frontmatter` 的 concept 文档（`type: Topic`），可被 Obsidian、OKF 校验器等整个生态直接消费；自带 provenance（`sources`）、trust（`generated`/`verified`）、lifecycle（`status`/`stale_after`）三族字段。
@@ -115,7 +133,7 @@ dsh plugin --profile <name> remove @aiwayds/dsh-topics-memory
 ## 已知边界
 
 - **子代理默认参与记忆，可整体关掉**：默认（`include-subagents` 开）注入与观察同样作用于子代理会话。`/topics set include-subagents off` 后，delegation depth > 0 的子代理会话被整体跳过——不注入、不观察、不触发蒸馏；topic 工具始终在全局层（子代理显式 `topic_save` 不受开关影响）。跨进程子代理（claude-code/codex 等 provider）本就不加载本插件。
-- **headless 单发会话里的 session-end 蒸馏**：插件 disposer 现在会等待退出触发的末次蒸馏落盘（有界等待，上限 90s；挂死的模型调用在超时后放弃、退出照常进行），headless 进程默认不再输掉这场竞速。90s 窗口内退出 run 可能只完成部分调用预算，剩余积压留待下次触发。已有 session-end run 在跑时退出触发整体跳过（否则同一全局队头批次会被双份喂给模型）。会话内 `/topics distill` 手动触发则完全绕开竞速；`meta/distill-state.json` 记录每次 lane 的结局，`/topics status` 可查。
+- **退出路径本地化（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 onboard` 的蒸馏一步拆成两问（先 provider 后 model，模型列表取自该 provider 的目录），选完经 `resolveModelInfo` 预校验——provider 无活路由会阻断重选，模型目录校验非 NO_ADAPTER 失败（目录外，可能仍可用）则警告但放行；无 ask UI 或无可用模型路由的环境自动退回文本输入。`/topics set` 的选择面板走同一套校验。

package/lib/distill.d.ts

@@ -69,8 +69,10 @@ export declare class Distiller {
      * caller can hook post-run cleanup — the per-session llm capture in
      * index.ts must live exactly as long as a run that may read it. `manual`
      * is the /topics distill trigger: same lane, same in-flight guard.
+     * `boot-replay` is the session-start backlog drain: a previous exit's
+     * skipped (or killed-mid-run) distill replays here.
      */
-    request(sessionId: string, reason: 'every-n' | 'session-end' | 'manual'): Promise<DistillResult> | undefined;
+    request(sessionId: string, reason: 'every-n' | 'session-end' | 'manual' | 'boot-replay'): Promise<DistillResult> | undefined;
     /** True while a run for the session is still in flight (teardown guard). */
     hasPending(sessionId: string): boolean;
     /** True while ANY session's run is still in flight (exit-dispose guard). */

package/lib/distill.js

@@ -65,6 +65,8 @@ export class Distiller {
      * caller can hook post-run cleanup — the per-session llm capture in
      * index.ts must live exactly as long as a run that may read it. `manual`
      * is the /topics distill trigger: same lane, same in-flight guard.
+     * `boot-replay` is the session-start backlog drain: a previous exit's
+     * skipped (or killed-mid-run) distill replays here.
      */
     request(sessionId, reason) {
         if (!this.configured)

package/lib/git.d.ts

@@ -51,7 +51,10 @@ export interface PullOutcome {
  * `pull --rebase` with conflict containment: on conflict we abort the rebase
  * (ADR 0003 — no automatic smart merging) and report the conflicted paths so
  * the caller can mark those topics. Remote and branch are explicit — the
- * bundle never depends on upstream tracking config.
+ * bundle never depends on upstream tracking config. IDENTITY rides along:
+ * a rebase REPLAYS local commits, which requires a committer identity, and
+ * a fresh machine (CI, new host) may have none — without this the pull
+ * fails with an empty conflicted list on every session start.
  */
 export declare function pullRebase(cwd: string, token?: string, remote?: string, branch?: string): Promise<PullOutcome>;
 export declare function push(cwd: string, token?: string, remote?: string, branch?: string): Promise<{

package/lib/git.js

@@ -117,10 +117,13 @@ export async function fileAtRev(cwd, path, rev) {
  * `pull --rebase` with conflict containment: on conflict we abort the rebase
  * (ADR 0003 — no automatic smart merging) and report the conflicted paths so
  * the caller can mark those topics. Remote and branch are explicit — the
- * bundle never depends on upstream tracking config.
+ * bundle never depends on upstream tracking config. IDENTITY rides along:
+ * a rebase REPLAYS local commits, which requires a committer identity, and
+ * a fresh machine (CI, new host) may have none — without this the pull
+ * fails with an empty conflicted list on every session start.
  */
 export async function pullRebase(cwd, token, remote = 'origin', branch = 'main') {
-    const r = await runGit(['pull', '--rebase', '--autostash', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
+    const r = await runGit([...IDENTITY, 'pull', '--rebase', '--autostash', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
         return { code: -1, stdout: '', stderr: String(e instanceof Error ? e.message : e) };
     });
     if (r.code === 0)

package/lib/index.d.ts

@@ -18,13 +18,13 @@
 import type { Context } from '@deepseek-ai/cordis';
 export declare const name = "dsh-topics-memory";
 /**
- * Bounded wait for the process-exit distill. Session teardown is the last
- * distill trigger, but the disposer used to fire it fire-and-forget — process
- * exit always won the race and the run died unwritten. The disposer now waits
- * for the run, capped so a pathological (hanging) model call can never wedge
- * the host's exit.
+ * Bounded wait for the process-exit meta commit. The exit path is
+ * local-only: no pull/push, no model call — the deferred push rides the
+ * next boot's pull and the skipped exit distill is replayed there. The
+ * window only bounds the local `git commit` against a pathological stall
+ * (a wedged index.lock, a hung filesystem), which should never fire.
  */
-export declare const EXIT_DISTILL_TIMEOUT_MS = 90000;
+export declare const EXIT_COMMIT_TIMEOUT_MS = 10000;
 /**
  * Resolve when `p` settles (rejection swallowed) or after `ms`, whichever
  * comes first. The cap timer is unref'd: an otherwise-idle event loop exits

package/lib/index.js

@@ -11,13 +11,13 @@ import { CONFIG_KEYS, TopicsConfig } from "./config.js";
 import { isDelegated } from "./delegation.js";
 export const name = 'dsh-topics-memory';
 /**
- * Bounded wait for the process-exit distill. Session teardown is the last
- * distill trigger, but the disposer used to fire it fire-and-forget — process
- * exit always won the race and the run died unwritten. The disposer now waits
- * for the run, capped so a pathological (hanging) model call can never wedge
- * the host's exit.
+ * Bounded wait for the process-exit meta commit. The exit path is
+ * local-only: no pull/push, no model call — the deferred push rides the
+ * next boot's pull and the skipped exit distill is replayed there. The
+ * window only bounds the local `git commit` against a pathological stall
+ * (a wedged index.lock, a hung filesystem), which should never fire.
  */
-export const EXIT_DISTILL_TIMEOUT_MS = 90_000;
+export const EXIT_COMMIT_TIMEOUT_MS = 10_000;
 /**
  * Resolve when `p` settles (rejection swallowed) or after `ms`, whichever
  * comes first. The cap timer is unref'd: an otherwise-idle event loop exits
@@ -301,10 +301,10 @@ export function apply(ctx) {
     // mid-pipeline deferred to THIS pipeline and never fires again.
     const slowLane = new SlowLane(service, caller, releaseSessionLlm);
     // ---- Observer (M2) ----
-    // The process-exit disposer awaits this run (bounded): the callback below
-    // records it synchronously when the fake 'dispose' session's end trigger
-    // fires, so the disposer can wait for the last distill to land.
-    let exitDistill;
+    // Trigger runs are fire-and-forget everywhere now — including the exit
+    // one. Observations are write-through on disk, so a run the process exits
+    // under is never lost work: its input is still undistilled and the next
+    // boot's replay distills it.
     const observer = new Observer(service, (sessionId, reason) => {
         // Trigger-time capture: the agent is still registered here, so its scoped
         // ctx can hand over the llm instance whose adapters are live.
@@ -321,8 +321,6 @@ export function apply(ctx) {
         // and its own settle hook does the release.
         const run = distiller.request(sessionId, reason);
         if (run !== undefined) {
-            if (sessionId === 'dispose')
-                exitDistill = run;
             void run.finally(() => releaseSessionLlm(sessionId)).catch(() => undefined);
         }
     });
@@ -445,36 +443,63 @@ export function apply(ctx) {
             releaseSessionLlm(sessionId);
         }));
     }
-    // ---- Sync lifecycle: pull on session start, flush on dispose ----
+    // ---- Sync lifecycle: pull on session start, local commit on dispose ----
     ctx.on('session/event', ((session, event) => {
         if (event.type === 'agent/session-start') {
             void sync
                 .pull()
                 .catch(() => undefined)
-                .finally(() => store.ensure().catch(() => undefined));
+                .finally(() => store.ensure().catch(() => undefined))
+                .then(() => {
+                // Boot replay: the observations JSONL is the durable distill queue.
+                // Whatever the previous exit skipped (local-only exit since the
+                // no-network exit commit) or a killed run left unmarked is still
+                // undistilled here. Empty pool and no-model are cheap no-ops inside
+                // the distiller; the per-session dedup guards double runs.
+                void store
+                    .undistilledObservations(1)
+                    .then((pending) => {
+                    if (pending.length === 0)
+                        return;
+                    // Same trigger-time capture the observer callback does: the
+                    // replay run's caller resolves candidates lazily and a fresh
+                    // session has no prior capture to lean on.
+                    try {
+                        captureFromAgent(agents()?.get(session.id));
+                    }
+                    catch {
+                        // contained — the run below fails with the readable
+                        // no-adapter detail instead
+                    }
+                    const run = distiller.request(String(session.id), 'boot-replay');
+                    if (run !== undefined)
+                        void run.catch(() => undefined);
+                })
+                    .catch(() => undefined);
+            });
         }
     }));
     ctx.effect(() => {
         void store.ensure().catch(() => undefined);
         // Async disposer: cordis awaits it during unload (Disposable may be
-        // async), so the exit distill gets its bounded window before the
-        // process goes away instead of always losing the exit race.
+        // async). The exit path is local-only — one git commit of the meta
+        // sidecars (observations / injection log / distill state), no pull, no
+        // push, no model call. The deferred push rides the next boot's pull
+        // (sync.pull replays it) and the skipped exit distill is replayed
+        // there too; both only ever needed the on-disk state, which the commit
+        // below makes durable before the process goes away.
         return () => {
             // A real session's session-end run (agent/disposed trigger, moments
             // earlier) may still be in flight — and the fake-'dispose' run would
             // feed the SAME global pool head to the model a second time (double
             // evaluation, double GC attempts). Skip the exit trigger while any
-            // run is pending; the bounded wait below then simply has nothing
-            // extra to await.
+            // run is pending; its capture is already write-through on disk.
             if (!distiller.hasAnyPending()) {
                 observer.onSessionEvent('dispose', 'agent/disposed', undefined);
             }
             sync.dispose();
-            // The exit flush (final meta commit + ledger flush) rides the SAME
-            // bounded window as the exit distill — fire-and-forget here loses the
-            // exit race that window was built to win.
-            const exitFlush = sync.commitMeta().then(() => sync.flush()).catch(() => undefined);
-            return settleBounded(exitDistill === undefined ? exitFlush : Promise.allSettled([exitDistill, exitFlush]), EXIT_DISTILL_TIMEOUT_MS);
+            const exitFlush = sync.commitMeta().catch(() => undefined);
+            return settleBounded(exitFlush, EXIT_COMMIT_TIMEOUT_MS);
         };
     }, 'topics: lifecycle');
     // ---- /topics command (optional peer) ----

package/lib/okf.d.ts

@@ -86,7 +86,25 @@ export declare function slugify(title: string): string;
 export declare function pathToSlug(path: string): string;
 /** `foo` → `topics/foo.md`. */
 export declare function slugToPath(slug: string): string;
-/** Bundle-relative paths of `depends` entries that point at topics. */
+/**
+ * Strip every `topics/` (or `topics:` — a colon form the wild has produced)
+ * prefix and `.md` suffix. The canonical depends entry carries exactly one
+ * of each, but bundles written by the save path that re-wrapped preserved
+ * values (fixed in the same release) can carry any number — idempotent by
+ * construction.
+ */
+export declare function unwrapTopicRef(raw: string): string;
+/**
+ * Canonical bundle-relative path for a `depends` entry, accepting every form
+ * the wild has produced: bare slug (`foo`), canonical path (`topics/foo.md`),
+ * multi-wrapped (`topics/topics/foo.md.md`). Idempotent. A value that still
+ * carries a path separator or scheme after unwrapping is not a bundle-internal
+ * topic reference and comes back as its unwrapped self (a dead edge for the
+ * graph, but never re-wrapped into a fake one); the empty string means the
+ * entry unwrapped to nothing and should be dropped by the caller.
+ */
+export declare function normalizeDependsEntry(raw: string): string;
+/** Topic slugs referenced by `depends`, tolerant of wrapped entries. */
 export declare function dependsSlugs(fm: {
     depends: readonly string[];
 }): string[];
@@ -111,7 +129,9 @@ export declare function normalizeLinkTarget(target: string): string | undefined;
  * Topic slugs referenced from a body: `[[wikilinks]]` (with optional
  * `#heading` / `|alias`) plus markdown links pointing at bundle paths.
  * These are the human-authored edges alongside `depends` — both feed the
- * retrieval graph walk and the backlinks index.
+ * retrieval graph walk and the backlinks index. Inline code and fenced
+ * code blocks are stripped first: topics that document link syntax would
+ * otherwise mint permanent phantom edges out of their own examples.
  */
 export declare function bodyLinkSlugs(body: string): string[];
 /** The conventional profile headings, for validators and tooling. */

package/lib/okf.js

@@ -216,9 +216,47 @@ export function pathToSlug(path) {
 export function slugToPath(slug) {
     return `topics/${slug}.md`;
 }
-/** Bundle-relative paths of `depends` entries that point at topics. */
+/**
+ * Strip every `topics/` (or `topics:` — a colon form the wild has produced)
+ * prefix and `.md` suffix. The canonical depends entry carries exactly one
+ * of each, but bundles written by the save path that re-wrapped preserved
+ * values (fixed in the same release) can carry any number — idempotent by
+ * construction.
+ */
+export function unwrapTopicRef(raw) {
+    let t = raw.trim();
+    for (;;) {
+        if (t.startsWith('topics/'))
+            t = t.slice('topics/'.length);
+        else if (t.startsWith('topics:'))
+            t = t.slice('topics:'.length);
+        else
+            break;
+    }
+    while (t.endsWith('.md'))
+        t = t.slice(0, -3);
+    return t;
+}
+/**
+ * Canonical bundle-relative path for a `depends` entry, accepting every form
+ * the wild has produced: bare slug (`foo`), canonical path (`topics/foo.md`),
+ * multi-wrapped (`topics/topics/foo.md.md`). Idempotent. A value that still
+ * carries a path separator or scheme after unwrapping is not a bundle-internal
+ * topic reference and comes back as its unwrapped self (a dead edge for the
+ * graph, but never re-wrapped into a fake one); the empty string means the
+ * entry unwrapped to nothing and should be dropped by the caller.
+ */
+export function normalizeDependsEntry(raw) {
+    const t = unwrapTopicRef(raw);
+    if (t === '')
+        return '';
+    if (t.includes('/') || t.includes(':'))
+        return t;
+    return slugToPath(t);
+}
+/** Topic slugs referenced by `depends`, tolerant of wrapped entries. */
 export function dependsSlugs(fm) {
-    return fm.depends.map(pathToSlug);
+    return fm.depends.map(unwrapTopicRef);
 }
 /** Render the auto-generated OKF `index.md` (progressive disclosure, §Bundle). */
 export function renderIndex(entries) {
@@ -268,16 +306,21 @@ export function normalizeLinkTarget(target) {
  * Topic slugs referenced from a body: `[[wikilinks]]` (with optional
  * `#heading` / `|alias`) plus markdown links pointing at bundle paths.
  * These are the human-authored edges alongside `depends` — both feed the
- * retrieval graph walk and the backlinks index.
+ * retrieval graph walk and the backlinks index. Inline code and fenced
+ * code blocks are stripped first: topics that document link syntax would
+ * otherwise mint permanent phantom edges out of their own examples.
  */
 export function bodyLinkSlugs(body) {
     const out = new Set();
-    for (const m of body.matchAll(WIKILINK)) {
+    const prose = body
+        .replace(/```[\s\S]*?```/g, '')
+        .replace(/`[^`\n]*`/g, '');
+    for (const m of prose.matchAll(WIKILINK)) {
         const slug = normalizeLinkTarget(m[1]);
         if (slug !== undefined)
             out.add(slug);
     }
-    for (const m of body.matchAll(MD_LINK)) {
+    for (const m of prose.matchAll(MD_LINK)) {
         const slug = normalizeLinkTarget(m[1]);
         if (slug !== undefined)
             out.add(slug);

package/lib/service.js

@@ -446,7 +446,11 @@ export class TopicsService {
             type: 'Topic',
             title: input.title,
             tags: dedupeLower(input.tags ?? existing?.fm.tags ?? []),
-            depends: (input.depends ?? existing?.fm.depends ?? []).map(okf.slugToPath),
+            // normalizeDependsEntry, never bare slugToPath: the preserved-on-update
+            // fallback feeds already-canonical `topics/<slug>.md` entries back in,
+            // and wrapping those again stacked one layer per save (the double-wrap
+            // bug repaired on startup by BundleStore.repairDepends).
+            depends: dedupePaths((input.depends ?? existing?.fm.depends ?? []).map(okf.normalizeDependsEntry)),
             open_questions: input.openQuestions ?? existing?.fm.open_questions ?? [],
             impact: input.impact ?? existing?.fm.impact ?? [],
             status: input.status ?? existing?.fm.status ?? 'draft',
@@ -534,6 +538,17 @@ function dedupeLower(tags) {
     }
     return out;
 }
+function dedupePaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        if (p === '' || seen.has(p))
+            continue;
+        seen.add(p);
+        out.push(p);
+    }
+    return out;
+}
 function sanitizeTriggers(triggers) {
     const out = [];
     for (const t of triggers) {

package/lib/store.d.ts

@@ -66,7 +66,8 @@ export declare class BundleStore {
     /** Last distill-lane run outcome (diagnostics for /topics status and e2e). */
     writeDistillState(state: unknown): Promise<void>;
     readDistillState(): Promise<Record<string, unknown> | undefined>;
-    /** Create the directory skeleton, git repo, and initial index (idempotent). */
+    /** Create the directory skeleton, git repo, initial index, and repair
+     * wrapped depends entries left by older save paths (idempotent). */
     ensure(): Promise<void>;
     /** Repo initialized and not gitDisabled. */
     hasGit(): Promise<boolean>;
@@ -76,6 +77,16 @@ export declare class BundleStore {
     brokenTopics(): Promise<string[]>;
     readTopic(slug: string): Promise<okf.TopicDoc | undefined>;
     exists(slug: string): Promise<boolean>;
+    /**
+     * Upgrade repair for bundles written by the save path that stacked another
+     * `topics/….md` wrap onto preserved-on-update depends entries, leaving
+     * multi-wrapped references (`topics/topics/foo.md.md`) whose edges resolve
+     * to nothing. Unwraps in place behind the write queue, regenerates the
+     * derived files, and lands the result as one traceable commit; file
+     * rewrites happen even without git, the commit just doesn't. Idempotent —
+     * every clean startup re-scans and finds nothing to change.
+     */
+    private repairDepends;
     /** First free slug: `foo`, then `foo-2`, `foo-3`, … */
     uniqueSlug(base: string): Promise<string>;
     /**

package/lib/store.js

@@ -28,6 +28,20 @@ async function atomicWrite(file, content) {
     await writeFile(tmp, content, 'utf8');
     await rename(tmp, file);
 }
+function dedupePaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const p of paths) {
+        if (p === '' || seen.has(p))
+            continue;
+        seen.add(p);
+        out.push(p);
+    }
+    return out;
+}
+function sameStrings(a, b) {
+    return a.length === b.length && a.every((v, i) => v === b[i]);
+}
 export class BundleStore {
     root;
     actor;
@@ -79,7 +93,8 @@ export class BundleStore {
             return undefined;
         }
     }
-    /** Create the directory skeleton, git repo, and initial index (idempotent). */
+    /** Create the directory skeleton, git repo, initial index, and repair
+     * wrapped depends entries left by older save paths (idempotent). */
     async ensure() {
         await mkdir(this.topicsDir(), { recursive: true });
         await mkdir(this.metaDir(), { recursive: true });
@@ -89,6 +104,7 @@ export class BundleStore {
         if (!(await existsSync(join(this.root, 'index.md')))) {
             await this.enqueue(() => this.regenerateIndex());
         }
+        await this.repairDepends();
     }
     /** Repo initialized and not gitDisabled. */
     async hasGit() {
@@ -170,6 +186,49 @@ export class BundleStore {
     async exists(slug) {
         return existsSync(this.topicPath(slug));
     }
+    /**
+     * Upgrade repair for bundles written by the save path that stacked another
+     * `topics/….md` wrap onto preserved-on-update depends entries, leaving
+     * multi-wrapped references (`topics/topics/foo.md.md`) whose edges resolve
+     * to nothing. Unwraps in place behind the write queue, regenerates the
+     * derived files, and lands the result as one traceable commit; file
+     * rewrites happen even without git, the commit just doesn't. Idempotent —
+     * every clean startup re-scans and finds nothing to change.
+     */
+    async repairDepends() {
+        await this.enqueue(async () => {
+            let files;
+            try {
+                files = await readdir(this.topicsDir());
+            }
+            catch {
+                return;
+            }
+            const changed = [];
+            for (const f of files) {
+                if (!f.endsWith('.md') || f === 'index.md')
+                    continue;
+                const file = join(this.topicsDir(), f);
+                let doc;
+                try {
+                    doc = okf.parseTopicDoc(await readFile(file, 'utf8'));
+                }
+                catch {
+                    continue; // broken files are status()'s business, not the repair's
+                }
+                const normalized = dedupePaths(doc.fm.depends.map(okf.normalizeDependsEntry));
+                if (sameStrings(normalized, doc.fm.depends))
+                    continue;
+                doc.fm.depends = normalized;
+                await atomicWrite(file, okf.serializeTopicDoc(doc));
+                changed.push(`topics/${f}`);
+            }
+            if (changed.length === 0)
+                return;
+            await this.regenerateIndex();
+            await this.commit([...changed, 'index.md'], `topics(migrate): repair wrapped depends entries in ${changed.length} topic file(s)`);
+        });
+    }
     /** First free slug: `foo`, then `foo-2`, `foo-3`, … */
     async uniqueSlug(base) {
         const clean = okf.slugify(base);
@@ -508,13 +567,19 @@ export class BundleStore {
     }
     async setConflicts(paths) {
         await this.enqueue(async () => {
-            if (paths.length === 0) {
+            // Only topic files belong here: a rebase can also conflict on meta
+            // sidecars (observations.jsonl is appended on both machines), and
+            // storing those leaked non-topic paths into the conflicts mark, where
+            // /topics status displayed them as if they were topics and the demote
+            // gate keyed on slugs that can never exist.
+            const topics = [...new Set(paths.filter((p) => /^topics\/.+\.md$/.test(p)))];
+            if (topics.length === 0) {
                 await atomicWrite(this.conflictsPath(), '[]\n');
             }
             else {
-                await atomicWrite(this.conflictsPath(), `${JSON.stringify([...paths], null, 2)}\n`);
+                await atomicWrite(this.conflictsPath(), `${JSON.stringify(topics, null, 2)}\n`);
             }
-            await this.commit(['meta/conflicts.json'], `topics(meta): mark ${paths.length} conflicted topic(s)`);
+            await this.commit(['meta/conflicts.json'], `topics(meta): mark ${topics.length} conflicted topic(s)`);
         });
     }
     // ------------------------------------------------------------------

package/lib/sync.d.ts

@@ -32,7 +32,12 @@ export declare class Sync {
     private readonly urlFor;
     constructor(store: BundleStore, cfg: () => SyncConfig, token?: TokenResolver, urlFor?: UrlResolver);
     get active(): boolean;
-    /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+    /**
+     * Session start (or `/topics sync pull`): rebase onto remote, mark
+     * conflicts, then replay any push the previous session's local-only exit
+     * deferred. The replay is best-effort — a failure just marks lastError and
+     * the debounced flush (or the next boot's pull) retries.
+     */
     pull(): Promise<{
         ok: boolean;
         conflicted: string[];

package/lib/sync.js

@@ -35,7 +35,12 @@ export class Sync {
     get active() {
         return this.cfg().repo !== '';
     }
-    /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+    /**
+     * Session start (or `/topics sync pull`): rebase onto remote, mark
+     * conflicts, then replay any push the previous session's local-only exit
+     * deferred. The replay is best-effort — a failure just marks lastError and
+     * the debounced flush (or the next boot's pull) retries.
+     */
     async pull() {
         if (!this.active)
             return { ok: true, conflicted: [], message: 'local-only 模式，无同步' };
@@ -52,6 +57,23 @@ export class Sync {
             const prior = await this.store.getConflicts();
             if (prior.size > 0)
                 await this.store.setConflicts([]);
+            // Deferred-push replay: the previous exit committed locally only, so a
+            // successful rebase here is the moment the backlog lands on the remote.
+            try {
+                if ((await gitmod.unpushedCount(this.store.root)) > 0) {
+                    const pushed = await gitmod.push(this.store.root, token);
+                    if (pushed.ok) {
+                        this.lastPushAt = new Date().toISOString();
+                        this.lastError = '';
+                    }
+                    else {
+                        this.lastError = pushed.output.slice(-500);
+                    }
+                }
+            }
+            catch {
+                // pull must stay best-effort for the session-start caller
+            }
             return { ok: true, conflicted: [], message: '已与远端同步' };
         }
         const conflictedSlugs = outcome.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''));
@@ -59,7 +81,14 @@ export class Sync {
             await this.store.setConflicts(outcome.conflicted);
         }
         this.lastError = outcome.output.slice(-500);
-        return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、') || '未知路径'}（已标记降权，待手工解决）` };
+        // A rebase can fail without producing conflicted paths (identity missing,
+        // fetch failure, corrupt state) — surface the git output tail instead of
+        // the misleading 「未知路径」 so a headless failure is diagnosable.
+        if (conflictedSlugs.length === 0) {
+            const tail = outcome.output.trim().split('\n').slice(-3).join('；').slice(-200);
+            return { ok: false, conflicted: [], message: `rebase 失败（无冲突文件）：${tail !== '' ? tail : 'git 无输出'}` };
+        }
+        return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、')}（已标记降权，待手工解决）` };
     }
     /** Called after every write-through commit — schedules the debounced push. */
     schedulePush() {

package/lib/viz.js

@@ -9,6 +9,7 @@
  *
  * @module viz
  */
+import { unwrapTopicRef } from "./okf.js";
 /** Build the relationship graph: depends edges + body-link edges, no self-loops. */
 export function buildGraph(roster) {
     const bySlug = new Set(roster.map((r) => r.slug));
@@ -31,7 +32,9 @@ export function buildGraph(roster) {
     };
     for (const topic of roster) {
         for (const dep of topic.depends) {
-            const target = dep.replace(/^topics\//, '').replace(/\.md$/, '');
+            // unwrapTopicRef, not a single strip: pre-repair bundles can carry
+            // multi-wrapped depends entries, which would render a dead node here.
+            const target = unwrapTopicRef(dep);
             addEdge(topic.slug, target, 'depends');
         }
         for (const link of topic.links ?? [])

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.8.1",
-  "description": "dsh-plugin: OKF v0.2 topic memory for dsh - local-first git-tracked bundle, hot-path LLM-free injection, two-stage observer with background distill",
+  "version": "0.10.0",
+  "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",
   "types": "lib/index.d.ts",
@@ -38,7 +38,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/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/settings-migration.test.mjs test/quality.test.mjs test/replay-gate.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/viz.test.mjs test/corpus.test.mjs test/llm-scope.test.mjs test/settings-migration.test.mjs test/quality.test.mjs test/replay-gate.test.mjs test/depends-repair.test.mjs",
     "smoke": "node scripts/smoke-boot.mjs"
   },
   "dependencies": {},

package/src/distill.ts

@@ -161,8 +161,10 @@ export class Distiller {
    * caller can hook post-run cleanup — the per-session llm capture in
    * index.ts must live exactly as long as a run that may read it. `manual`
    * is the /topics distill trigger: same lane, same in-flight guard.
+   * `boot-replay` is the session-start backlog drain: a previous exit's
+   * skipped (or killed-mid-run) distill replays here.
    */
-  request(sessionId: string, reason: 'every-n' | 'session-end' | 'manual'): Promise<DistillResult> | undefined {
+  request(sessionId: string, reason: 'every-n' | 'session-end' | 'manual' | 'boot-replay'): Promise<DistillResult> | undefined {
     if (!this.configured) return undefined
     if (this.inFlight.has(sessionId)) return undefined
     const run = this.run(sessionId).finally(() => this.inFlight.delete(sessionId))

package/src/git.ts

@@ -152,10 +152,13 @@ export interface PullOutcome {
  * `pull --rebase` with conflict containment: on conflict we abort the rebase
  * (ADR 0003 — no automatic smart merging) and report the conflicted paths so
  * the caller can mark those topics. Remote and branch are explicit — the
- * bundle never depends on upstream tracking config.
+ * bundle never depends on upstream tracking config. IDENTITY rides along:
+ * a rebase REPLAYS local commits, which requires a committer identity, and
+ * a fresh machine (CI, new host) may have none — without this the pull
+ * fails with an empty conflicted list on every session start.
  */
 export async function pullRebase(cwd: string, token?: string, remote = 'origin', branch = 'main'): Promise<PullOutcome> {
-  const r = await runGit(['pull', '--rebase', '--autostash', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
+  const r = await runGit([...IDENTITY, 'pull', '--rebase', '--autostash', remote, branch], { cwd, token, mayFail: true, timeoutMs: 60_000 }).catch((e) => {
     return { code: -1, stdout: '', stderr: String(e instanceof Error ? e.message : e) } satisfies GitResult
   })
   if (r.code === 0) return { ok: true, conflicted: [], output: r.stdout + r.stderr }

package/src/index.ts

@@ -39,13 +39,13 @@ import { isDelegated } from './delegation.ts'
 export const name = 'dsh-topics-memory'
 
 /**
- * Bounded wait for the process-exit distill. Session teardown is the last
- * distill trigger, but the disposer used to fire it fire-and-forget — process
- * exit always won the race and the run died unwritten. The disposer now waits
- * for the run, capped so a pathological (hanging) model call can never wedge
- * the host's exit.
+ * Bounded wait for the process-exit meta commit. The exit path is
+ * local-only: no pull/push, no model call — the deferred push rides the
+ * next boot's pull and the skipped exit distill is replayed there. The
+ * window only bounds the local `git commit` against a pathological stall
+ * (a wedged index.lock, a hung filesystem), which should never fire.
  */
-export const EXIT_DISTILL_TIMEOUT_MS = 90_000
+export const EXIT_COMMIT_TIMEOUT_MS = 10_000
 
 /**
  * Resolve when `p` settles (rejection swallowed) or after `ms`, whichever
@@ -368,10 +368,10 @@ export function apply(ctx: Context): void {
   const slowLane = new SlowLane(service, caller, releaseSessionLlm)
 
   // ---- Observer (M2) ----
-  // The process-exit disposer awaits this run (bounded): the callback below
-  // records it synchronously when the fake 'dispose' session's end trigger
-  // fires, so the disposer can wait for the last distill to land.
-  let exitDistill: Promise<DistillResult> | undefined
+  // Trigger runs are fire-and-forget everywhere now — including the exit
+  // one. Observations are write-through on disk, so a run the process exits
+  // under is never lost work: its input is still undistilled and the next
+  // boot's replay distills it.
   const observer = new Observer(service, (sessionId, reason) => {
     // Trigger-time capture: the agent is still registered here, so its scoped
     // ctx can hand over the llm instance whose adapters are live.
@@ -387,7 +387,6 @@ export function apply(ctx: Context): void {
     // and its own settle hook does the release.
     const run = distiller.request(sessionId, reason)
     if (run !== undefined) {
-      if (sessionId === 'dispose') exitDistill = run
       void run.finally(() => releaseSessionLlm(sessionId)).catch(() => undefined)
     }
   })
@@ -508,13 +507,37 @@ export function apply(ctx: Context): void {
     }) as never)
   }
 
-  // ---- Sync lifecycle: pull on session start, flush on dispose ----
+  // ---- Sync lifecycle: pull on session start, local commit on dispose ----
   ctx.on('session/event' as never, ((session: { id: unknown }, event: SessionEvent) => {
     if (event.type === 'agent/session-start') {
       void sync
         .pull()
         .catch(() => undefined)
         .finally(() => store.ensure().catch(() => undefined))
+        .then(() => {
+          // Boot replay: the observations JSONL is the durable distill queue.
+          // Whatever the previous exit skipped (local-only exit since the
+          // no-network exit commit) or a killed run left unmarked is still
+          // undistilled here. Empty pool and no-model are cheap no-ops inside
+          // the distiller; the per-session dedup guards double runs.
+          void store
+            .undistilledObservations(1)
+            .then((pending) => {
+              if (pending.length === 0) return
+              // Same trigger-time capture the observer callback does: the
+              // replay run's caller resolves candidates lazily and a fresh
+              // session has no prior capture to lean on.
+              try {
+                captureFromAgent(agents()?.get(session.id) as unknown)
+              } catch {
+                // contained — the run below fails with the readable
+                // no-adapter detail instead
+              }
+              const run = distiller.request(String(session.id), 'boot-replay')
+              if (run !== undefined) void run.catch(() => undefined)
+            })
+            .catch(() => undefined)
+        })
     }
   }) as never)
 
@@ -522,27 +545,24 @@ export function apply(ctx: Context): void {
     () => {
       void store.ensure().catch(() => undefined)
       // Async disposer: cordis awaits it during unload (Disposable may be
-      // async), so the exit distill gets its bounded window before the
-      // process goes away instead of always losing the exit race.
+      // async). The exit path is local-only — one git commit of the meta
+      // sidecars (observations / injection log / distill state), no pull, no
+      // push, no model call. The deferred push rides the next boot's pull
+      // (sync.pull replays it) and the skipped exit distill is replayed
+      // there too; both only ever needed the on-disk state, which the commit
+      // below makes durable before the process goes away.
       return () => {
         // A real session's session-end run (agent/disposed trigger, moments
         // earlier) may still be in flight — and the fake-'dispose' run would
         // feed the SAME global pool head to the model a second time (double
         // evaluation, double GC attempts). Skip the exit trigger while any
-        // run is pending; the bounded wait below then simply has nothing
-        // extra to await.
+        // run is pending; its capture is already write-through on disk.
         if (!distiller.hasAnyPending()) {
           observer.onSessionEvent('dispose', 'agent/disposed', undefined)
         }
         sync.dispose()
-        // The exit flush (final meta commit + ledger flush) rides the SAME
-        // bounded window as the exit distill — fire-and-forget here loses the
-        // exit race that window was built to win.
-        const exitFlush = sync.commitMeta().then(() => sync.flush()).catch(() => undefined)
-        return settleBounded(
-          exitDistill === undefined ? exitFlush : Promise.allSettled([exitDistill, exitFlush]),
-          EXIT_DISTILL_TIMEOUT_MS,
-        )
+        const exitFlush = sync.commitMeta().catch(() => undefined)
+        return settleBounded(exitFlush, EXIT_COMMIT_TIMEOUT_MS)
       }
     },
     'topics: lifecycle',

package/src/okf.ts

@@ -254,9 +254,43 @@ export function slugToPath(slug: string): string {
   return `topics/${slug}.md`
 }
 
-/** Bundle-relative paths of `depends` entries that point at topics. */
+/**
+ * Strip every `topics/` (or `topics:` — a colon form the wild has produced)
+ * prefix and `.md` suffix. The canonical depends entry carries exactly one
+ * of each, but bundles written by the save path that re-wrapped preserved
+ * values (fixed in the same release) can carry any number — idempotent by
+ * construction.
+ */
+export function unwrapTopicRef(raw: string): string {
+  let t = raw.trim()
+  for (;;) {
+    if (t.startsWith('topics/')) t = t.slice('topics/'.length)
+    else if (t.startsWith('topics:')) t = t.slice('topics:'.length)
+    else break
+  }
+  while (t.endsWith('.md')) t = t.slice(0, -3)
+  return t
+}
+
+/**
+ * Canonical bundle-relative path for a `depends` entry, accepting every form
+ * the wild has produced: bare slug (`foo`), canonical path (`topics/foo.md`),
+ * multi-wrapped (`topics/topics/foo.md.md`). Idempotent. A value that still
+ * carries a path separator or scheme after unwrapping is not a bundle-internal
+ * topic reference and comes back as its unwrapped self (a dead edge for the
+ * graph, but never re-wrapped into a fake one); the empty string means the
+ * entry unwrapped to nothing and should be dropped by the caller.
+ */
+export function normalizeDependsEntry(raw: string): string {
+  const t = unwrapTopicRef(raw)
+  if (t === '') return ''
+  if (t.includes('/') || t.includes(':')) return t
+  return slugToPath(t)
+}
+
+/** Topic slugs referenced by `depends`, tolerant of wrapped entries. */
 export function dependsSlugs(fm: { depends: readonly string[] }): string[] {
-  return fm.depends.map(pathToSlug)
+  return fm.depends.map(unwrapTopicRef)
 }
 
 export interface IndexEntry {
@@ -312,15 +346,20 @@ export function normalizeLinkTarget(target: string): string | undefined {
  * Topic slugs referenced from a body: `[[wikilinks]]` (with optional
  * `#heading` / `|alias`) plus markdown links pointing at bundle paths.
  * These are the human-authored edges alongside `depends` — both feed the
- * retrieval graph walk and the backlinks index.
+ * retrieval graph walk and the backlinks index. Inline code and fenced
+ * code blocks are stripped first: topics that document link syntax would
+ * otherwise mint permanent phantom edges out of their own examples.
  */
 export function bodyLinkSlugs(body: string): string[] {
   const out = new Set<string>()
-  for (const m of body.matchAll(WIKILINK)) {
+  const prose = body
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/`[^`\n]*`/g, '')
+  for (const m of prose.matchAll(WIKILINK)) {
     const slug = normalizeLinkTarget(m[1])
     if (slug !== undefined) out.add(slug)
   }
-  for (const m of body.matchAll(MD_LINK)) {
+  for (const m of prose.matchAll(MD_LINK)) {
     const slug = normalizeLinkTarget(m[1])
     if (slug !== undefined) out.add(slug)
   }

package/src/service.ts

@@ -484,7 +484,11 @@ export class TopicsService {
       type: 'Topic',
       title: input.title,
       tags: dedupeLower(input.tags ?? existing?.fm.tags ?? []),
-      depends: (input.depends ?? existing?.fm.depends ?? []).map(okf.slugToPath),
+      // normalizeDependsEntry, never bare slugToPath: the preserved-on-update
+      // fallback feeds already-canonical `topics/<slug>.md` entries back in,
+      // and wrapping those again stacked one layer per save (the double-wrap
+      // bug repaired on startup by BundleStore.repairDepends).
+      depends: dedupePaths((input.depends ?? existing?.fm.depends ?? []).map(okf.normalizeDependsEntry)),
       open_questions: input.openQuestions ?? existing?.fm.open_questions ?? [],
       impact: input.impact ?? existing?.fm.impact ?? [],
       status: input.status ?? existing?.fm.status ?? 'draft',
@@ -577,6 +581,17 @@ function dedupeLower(tags: string[]): string[] {
   return out
 }
 
+function dedupePaths(paths: string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const p of paths) {
+    if (p === '' || seen.has(p)) continue
+    seen.add(p)
+    out.push(p)
+  }
+  return out
+}
+
 function sanitizeTriggers(triggers: readonly string[]): string[] {
   const out: string[] = []
   for (const t of triggers) {

package/src/store.ts

@@ -77,6 +77,21 @@ async function atomicWrite(file: string, content: string): Promise<void> {
   await rename(tmp, file)
 }
 
+function dedupePaths(paths: readonly string[]): string[] {
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const p of paths) {
+    if (p === '' || seen.has(p)) continue
+    seen.add(p)
+    out.push(p)
+  }
+  return out
+}
+
+function sameStrings(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i])
+}
+
 export interface BundleStoreOptions {
   /** Override the stamped actor (tests). Defaults to `agent:dsh-topics-memory@<host>`. */
   actor?: string
@@ -146,7 +161,8 @@ export class BundleStore {
     }
   }
 
-  /** Create the directory skeleton, git repo, and initial index (idempotent). */
+  /** Create the directory skeleton, git repo, initial index, and repair
+   * wrapped depends entries left by older save paths (idempotent). */
   async ensure(): Promise<void> {
     await mkdir(this.topicsDir(), { recursive: true })
     await mkdir(this.metaDir(), { recursive: true })
@@ -156,6 +172,7 @@ export class BundleStore {
     if (!(await existsSync(join(this.root, 'index.md')))) {
       await this.enqueue(() => this.regenerateIndex())
     }
+    await this.repairDepends()
   }
 
   /** Repo initialized and not gitDisabled. */
@@ -234,6 +251,45 @@ export class BundleStore {
     return existsSync(this.topicPath(slug))
   }
 
+  /**
+   * Upgrade repair for bundles written by the save path that stacked another
+   * `topics/….md` wrap onto preserved-on-update depends entries, leaving
+   * multi-wrapped references (`topics/topics/foo.md.md`) whose edges resolve
+   * to nothing. Unwraps in place behind the write queue, regenerates the
+   * derived files, and lands the result as one traceable commit; file
+   * rewrites happen even without git, the commit just doesn't. Idempotent —
+   * every clean startup re-scans and finds nothing to change.
+   */
+  private async repairDepends(): Promise<void> {
+    await this.enqueue(async () => {
+      let files: string[]
+      try {
+        files = await readdir(this.topicsDir())
+      } catch {
+        return
+      }
+      const changed: string[] = []
+      for (const f of files) {
+        if (!f.endsWith('.md') || f === 'index.md') continue
+        const file = join(this.topicsDir(), f)
+        let doc: okf.TopicDoc
+        try {
+          doc = okf.parseTopicDoc(await readFile(file, 'utf8'))
+        } catch {
+          continue // broken files are status()'s business, not the repair's
+        }
+        const normalized = dedupePaths(doc.fm.depends.map(okf.normalizeDependsEntry))
+        if (sameStrings(normalized, doc.fm.depends)) continue
+        doc.fm.depends = normalized
+        await atomicWrite(file, okf.serializeTopicDoc(doc))
+        changed.push(`topics/${f}`)
+      }
+      if (changed.length === 0) return
+      await this.regenerateIndex()
+      await this.commit([...changed, 'index.md'], `topics(migrate): repair wrapped depends entries in ${changed.length} topic file(s)`)
+    })
+  }
+
   /** First free slug: `foo`, then `foo-2`, `foo-3`, … */
   async uniqueSlug(base: string): Promise<string> {
     const clean = okf.slugify(base)
@@ -575,12 +631,18 @@ export class BundleStore {
 
   async setConflicts(paths: readonly string[]): Promise<void> {
     await this.enqueue(async () => {
-      if (paths.length === 0) {
+      // Only topic files belong here: a rebase can also conflict on meta
+      // sidecars (observations.jsonl is appended on both machines), and
+      // storing those leaked non-topic paths into the conflicts mark, where
+      // /topics status displayed them as if they were topics and the demote
+      // gate keyed on slugs that can never exist.
+      const topics = [...new Set(paths.filter((p) => /^topics\/.+\.md$/.test(p)))]
+      if (topics.length === 0) {
         await atomicWrite(this.conflictsPath(), '[]\n')
       } else {
-        await atomicWrite(this.conflictsPath(), `${JSON.stringify([...paths], null, 2)}\n`)
+        await atomicWrite(this.conflictsPath(), `${JSON.stringify(topics, null, 2)}\n`)
       }
-      await this.commit(['meta/conflicts.json'], `topics(meta): mark ${paths.length} conflicted topic(s)`)
+      await this.commit(['meta/conflicts.json'], `topics(meta): mark ${topics.length} conflicted topic(s)`)
     })
   }
 

package/src/sync.ts

@@ -51,7 +51,12 @@ export class Sync {
     return this.cfg().repo !== ''
   }
 
-  /** Session start (or `/topics sync pull`): rebase onto remote, mark conflicts. */
+  /**
+   * Session start (or `/topics sync pull`): rebase onto remote, mark
+   * conflicts, then replay any push the previous session's local-only exit
+   * deferred. The replay is best-effort — a failure just marks lastError and
+   * the debounced flush (or the next boot's pull) retries.
+   */
   async pull(): Promise<{ ok: boolean; conflicted: string[]; message: string }> {
     if (!this.active) return { ok: true, conflicted: [], message: 'local-only 模式，无同步' }
     const token = await this.safeToken()
@@ -66,6 +71,21 @@ export class Sync {
       // A successful rebase clears previous conflict marks.
       const prior = await this.store.getConflicts()
       if (prior.size > 0) await this.store.setConflicts([])
+      // Deferred-push replay: the previous exit committed locally only, so a
+      // successful rebase here is the moment the backlog lands on the remote.
+      try {
+        if ((await gitmod.unpushedCount(this.store.root)) > 0) {
+          const pushed = await gitmod.push(this.store.root, token)
+          if (pushed.ok) {
+            this.lastPushAt = new Date().toISOString()
+            this.lastError = ''
+          } else {
+            this.lastError = pushed.output.slice(-500)
+          }
+        }
+      } catch {
+        // pull must stay best-effort for the session-start caller
+      }
       return { ok: true, conflicted: [], message: '已与远端同步' }
     }
     const conflictedSlugs = outcome.conflicted.map((p) => p.replace(/^topics\//, '').replace(/\.md$/, ''))
@@ -73,7 +93,14 @@ export class Sync {
       await this.store.setConflicts(outcome.conflicted)
     }
     this.lastError = outcome.output.slice(-500)
-    return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、') || '未知路径'}（已标记降权，待手工解决）` }
+    // A rebase can fail without producing conflicted paths (identity missing,
+    // fetch failure, corrupt state) — surface the git output tail instead of
+    // the misleading 「未知路径」 so a headless failure is diagnosable.
+    if (conflictedSlugs.length === 0) {
+      const tail = outcome.output.trim().split('\n').slice(-3).join('；').slice(-200)
+      return { ok: false, conflicted: [], message: `rebase 失败（无冲突文件）：${tail !== '' ? tail : 'git 无输出'}` }
+    }
+    return { ok: false, conflicted: conflictedSlugs, message: `rebase 冲突：${conflictedSlugs.join('、')}（已标记降权，待手工解决）` }
   }
 
   /** Called after every write-through commit — schedules the debounced push. */

package/src/viz.ts

@@ -11,6 +11,7 @@
  */
 
 import type { RetrievableTopic } from './retrieval.ts'
+import { unwrapTopicRef } from './okf.ts'
 
 export interface VizNode {
   id: string
@@ -51,7 +52,9 @@ export function buildGraph(roster: readonly RetrievableTopic[]): VizGraph {
   }
   for (const topic of roster) {
     for (const dep of topic.depends) {
-      const target = dep.replace(/^topics\//, '').replace(/\.md$/, '')
+      // unwrapTopicRef, not a single strip: pre-repair bundles can carry
+      // multi-wrapped depends entries, which would render a dead node here.
+      const target = unwrapTopicRef(dep)
       addEdge(topic.slug, target, 'depends')
     }
     for (const link of topic.links ?? []) addEdge(topic.slug, link, 'link')