@aiwayds/dsh-topics-memory 0.9.0 → 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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aiwayds/dsh-topics-memory",
-  "version": "0.9.0",
-  "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",

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/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. */