dsh-engram 0.8.6 → 0.8.7

package/README.md

@@ -264,7 +264,7 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 <!-- dsh-market compatibility block — keep labels bilingual and in sync with
      docs/RELEASE-NOTES.TEMPLATE.md (market README convention) -->
 
-- **DSH 版本 / DSH versions**: `>=0.1.2-alpha.2 <0.3.0-0` (本版 `0.8.6`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
+- **DSH 版本 / DSH versions**: `>=0.1.2-alpha.2 <0.3.0-0` (本版 `0.8.7`; 已发布的 `0.3.7`、`0.4.0` 仍声明旧的 `0.1.x` 范围 `>=0.1.2-alpha.2 <0.2.0-0` — 见下方矩阵)
 - **最后验证日期 / Last verified**: 2026-10-27 — DSH `0.2.1-rc.2` (`dsh --version`), web profile live composition; npm test 483/483
 - **安装方式已验证 / Verified install**: `dsh plugin --profile web add dsh-engram`
 
@@ -293,7 +293,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.8.0`–`0.8.2` | 本地 | 同 `0.5.0` — 证据化 procedure（v0.8-A）、导出为 DSH Skill（v0.8-B）、subagent 交接胶囊（v0.8-C） | 同 `0.5.0` |
 | `0.8.3`–`0.8.4` | 本地 | 同 `0.5.0` — 审批门（v0.8-D）+ 其 GUI；G6 门槛改单边（Δ ≥ −2pp）+ 隐藏规格语料 | 同 `0.5.0` |
 | `0.8.5` | 本地 | 同 `0.5.0` — 记忆行文件信号（`⚠file-changed` / `⚠file-missing`），G6 第三/四轮（撤回 +30pp，Δ=+58.3pp） | 同 `0.5.0` |
-| `0.8.6` (本期 / this release) | 本地 | 同 `0.5.0` — 修 issue #9：宿主没有 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
+| `0.8.6` (npm) | published | 同 `0.5.0` — 修 issue #9：宿主没有 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
+| `0.8.7` (本期 / this release) | 本地 | 同 `0.5.0` — 推送腿落盘（`$DSH_HOME/engram/push-legs.jsonl`）+ `status` 打印事件日志读法；`minimal` 预设不再承诺永远不会发生的自动接管 | 同 `0.5.0` |
 
 ### Where the API family broke — `0.1.2-alpha.2`
 
@@ -1035,6 +1036,12 @@ and silence when there is nothing relevant to point at:
 > session object does offer — that line is the thing to paste into a bug report.
 > Known case: the **desktop runtime** (`@deepseek-ai/dsh-desktop-runtime`) on
 > Windows, tracked as issue #9.
+>
+> `dsh-engram status` also prints a **push-legs** line — `推送腿：事件日志读法
+> sessionQuery · 最近 …` — the read path the live process actually took, written
+> to `$DSH_HOME/engram/push-legs.jsonl`. A dormant host shows
+> `事件日志不可读（none）… 休眠中` there, so the four features can be checked
+> without hunting a startup log.
 
 ### Entity pages + entity cards (v0.7-B)
 

package/README.zh.md

@@ -188,7 +188,8 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
 | `0.7.3`–`0.7.4`（npm `latest`） | 已发布 | 同 `0.5.0` —— 设置卡迁到「Engram 记忆 → 设置」tab（DSH `0.2.1` 删了旧 section）；修 DSH `0.2.x` 上「推送腿」整条静默失效（`[RECALL]` 启动召回、JIT 推送） | 同 `0.5.0` |
 | `0.7.5`–`0.7.13` | 本地 | 同 `0.5.0` —— 账本按会话落行 + `gate-audit`；L1 从「自己剪」转成「记账 + 归因」；压缩入账读真实事件形状；会话计数重启不清零；CLI 尊重 `DSH_HOME` | 同 `0.5.0` |
 | `0.8.0`–`0.8.5` | 本地 | 同 `0.5.0` —— 证据化 procedure、导出 DSH Skill、subagent 交接胶囊、审批门 + GUI、记忆行文件信号（`⚠file-changed`/`⚠file-missing`）、G6 门改单边 + 隐藏规格语料（Δ=+58.3pp） | 同 `0.5.0` |
-| `0.8.6`（本期 / this release） | 本地 | 同 `0.5.0` —— 修 issue #9：宿主不暴露 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
+| `0.8.6`（npm） | 已发布 | 同 `0.5.0` —— 修 issue #9：宿主不暴露 `sessionQuery`/`snapshotEvents` 时退回 `seq`+`eventAt` 逐条读，四项注入特性不再静默休眠；warn 报出宿主 surface；G6 第五轮 Δ=+90.0pp | 同 `0.5.0` |
+| `0.8.7`（本期 / this release） | 本地 | 同 `0.5.0` —— 推送腿落盘（`$DSH_HOME/engram/push-legs.jsonl`）+ `status` 打印事件日志读法；`minimal` 预设不再承诺永远不会发生的自动接管 | 同 `0.5.0` |
 
 ### API 族断裂点:`0.1.2-alpha.2`
 

package/docs/RELEASE-NOTES-v0.8.7.md

@@ -0,0 +1,69 @@
+# dsh-engram v0.8.7
+
+**「特性睡着了」这件事，现在有离线证据可查；顺手拆掉一句永远不会兑现的状态承诺。**
+
+0.8.6 修了 issue #9 的**能力**问题（宿主不暴露批量读接口时退回 `seq`+`eventAt`）。
+这一版补的是**可观测**问题：就算下一次再遇到同类宿主，也不该有人靠解 zstd 帧
+才能证明「不是还没触发，是根本不会触发」。
+
+## 新增：推送腿（push legs）有了落盘证据
+
+`[RECALL]`、会话 episode、`[RESUME]` 简报、会话结束的 todo sink —— 这四件事共享
+同一个前提：会话事件日志可读。它们一起醒，也一起睡。
+
+以前这里只有一个 `warn`，打在一个没人留着的终端上。现在每个会话装配时，插件把
+**实际走了哪条读法**追加进 `$DSH_HOME/engram/push-legs.jsonl`（有界：超 32 KB 只留尾 50 行）：
+
+```json
+{"at":1793086321920,"pid":59392,"sessionId":"session-…","source":"sessionQuery"}
+```
+
+`source` 就是 `sessionEventsSource()` 的裁决：`legacy` / `sessionQuery` /
+`snapshotEvents` / `eventAt` / `none`。
+
+`dsh-engram status` 多一行：
+
+```
+推送腿：事件日志读法 sessionQuery · 最近 2026/10/27 15:32:01 · sessionQuery×3 · eventAt×1
+推送腿：⚠ 事件日志不可读（none）—— [RECALL]/episode/resume/todo-sink 休眠中 · 2026/10/27 15:32:01 · none×1
+```
+
+第二条就是 issue #9 那台机器的样子——不用开日志、不用解帧，一眼能看出是休眠还是没触发。
+
+## 修复：`minimal` 预设的状态行在撒谎
+
+`dsh-engram status` 对未接管的预设一直打印「出厂布局，重启 dsh web 后自动接管」。
+但 DSH 0.2.1-rc.2 的 `minimal.patch.yml` 里 compaction 组**缺 `tool-result-pruner` 行**，
+换行不变量（要标准形状）不成立，`swapCompactionRow` 返回 `null`，boot 时记的是
+`skipped / layout-mismatch`——那句承诺永远不会兑现，重启多少次都是 `stock`。
+
+现在对 `stock` 再做一次换行探测，换不动就直说：
+
+```
+minimal: stock — 出厂布局但与标准形状不同（行不全），自动接管不会发生；要 Context GC 请手工接线或改用 standard
+```
+
+## 证据
+
+- `npm test` **488/488**（+5：push-legs 落盘、最新裁决、休眠措辞、有界重写、坏文件不抛）
+- `npm run typecheck` 通过；`prepublishOnly` 真实 tarball + peers 装上后 host/client 双入口导入通过
+- 本机 0.8.6 实机取证：状态快照 `pid 59392`（15:31:47 写入）→ `recall-injections.json`
+  的 `lastInjection` 为 **15:32:01**，即重启后 14 秒推送腿真的动了
+
+## 升级后请做的一件事（如果你在 issue #9 里报过障）
+
+```sh
+npx dsh-engram status
+```
+
+把「推送腿」那一行贴回 issue。如果它写 `none`，说明桌面运行时的 Session 连
+`eventAt` 都不给，那才需要走「直接读 `session.v4.jsonl.zstd`」这条重路子
+（Node 22 无内置 zstd，要引依赖）；如果写 `eventAt` 或 `sessionQuery`，说明已经修好。
+
+## DSH 版本支持（必填）
+
+- **支持的 DSH 范围**：`>=0.1.2-alpha.2 <0.3.0-0`
+- **验证版本**：`dsh 0.2.1-rc.2`（本机 CLI + web）
+- **最后验证日期**：2026-10-27
+- **安装方式已验证**：`prepublishOnly` 用真实 tarball 装 peers 后导入 host/client 双入口
+- **peer 声明**：`@deepseek-ai/dsh-{settings,storage-domain,compaction,compaction-basic,llm}@>=0.1.2-alpha.2 <0.3.0-0`、`@deepseek-ai/cordis@^4.0.2`、`@deepseek-ai/schemastery@^3.18.2`

package/lib/index.js

@@ -33,6 +33,7 @@ import { buildEpisode } from "./episode.js";
 import { collectStaleAnchors } from "./anchor.js";
 import { renderIndex, renderStartRecall, renderResumeBrief, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
 import { describeSessionSurface, sessionEventsSource, sessionSeq } from "./session-events.js";
+import { noteSessionEventsSource } from "./push-legs.js";
 import { makeTriggerRecorder } from "./trigger.js";
 import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
 import { installEngramSettings, makeEngineConfigSchema, SETTINGS_KEYS } from "./settings.js";
@@ -543,6 +544,8 @@ export function apply(ctx, config) {
   const sessionCache = new WeakMap();
   /** One-time-per-process notice: the host's session log is unreadable. */
   let warnedUnreadableLog = false;
+  /** Sessions whose event-log read path was already recorded (push-legs.jsonl). */
+  const notedSessionEvents = new WeakSet();
   const blockFor = (agent) => {
     if (agent === void 0) return "";
     const session = agent.session;
@@ -581,6 +584,17 @@ export function apply(ctx, config) {
       // next assembly retry, so a new conversation never permanently misses its
       // recalled memory.
       if (resolved.autoRecallOnStart !== false) {
+        // Push-legs telemetry (issue #9): record which read path this session
+        // took, once per session object, so `dsh-engram status` can answer
+        // "were [RECALL]/episode/resume/todo-sink awake?" without a log capture.
+        if (!notedSessionEvents.has(session)) {
+          notedSessionEvents.add(session);
+          noteSessionEventsSource({
+            home: engramHome(),
+            source: sessionEventsSource(session, sessionQuery),
+            sessionId: session.header?.id ?? session.id,
+          });
+        }
         const query = firstUserMessageText(session, sessionQuery);
         if (query.length === 0) {
           // Retry on the next assembly ONLY when the log is readable and the

package/lib/push-legs.js

@@ -0,0 +1,121 @@
+/**
+ * Observability for the four features that read the session event log.
+ *
+ * WHY THIS EXISTS (2026-10-27, issue #9): `[RECALL]`, the session episode, the
+ * resume brief and the session-end todo sink all depend on ONE host capability
+ * — a readable session event log. When a host stops exposing every read path,
+ * the four of them sleep together and the only trace is a single `warn` line on
+ * a terminal nobody kept. The reporter in issue #9 had to decompress
+ * `session.v4.jsonl.zstd` frames by hand to prove the features were not merely
+ * "not triggered yet".
+ *
+ * A warning is not an artifact. This module records which read path the live
+ * process actually took, once per session, into
+ * `$DSH_HOME/engram/push-legs.jsonl` so `dsh-engram status` can answer
+ * "were the push legs awake?" without a session, a log capture, or a report.
+ *
+ * The record is append-only and bounded (tail kept, like the other telemetry
+ * files): diagnostics must never grow without limit or throw into the
+ * assembly path.
+ * @module dsh-engram/push-legs
+ */
+
+import { appendFileSync, existsSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** Rows kept before the file is rewritten (tail-first). */
+export const PUSH_LEGS_KEEP = 50;
+/** Size at which the file is rewritten to the kept tail. */
+const PUSH_LEGS_MAX_BYTES = 32 * 1024;
+
+/** `<home>/engram/push-legs.jsonl` */
+export function pushLegsPath(home) {
+  return join(home, "engram", "push-legs.jsonl");
+}
+
+/**
+ * Record the read path taken for one session. Best effort: never throws.
+ *
+ * @param {object} options
+ * @param {string} options.home DSH home
+ * @param {string} options.source `sessionEventsSource()` verdict
+ * @param {string} [options.sessionId]
+ * @param {number} [options.pid]
+ * @param {number} [options.now]
+ * @returns {boolean} whether the row was written
+ */
+export function noteSessionEventsSource({ home, source, sessionId, pid = process.pid, now = Date.now() } = {}) {
+  if (typeof home !== "string" || home.length === 0) return false;
+  if (typeof source !== "string" || source.length === 0) return false;
+  const path = pushLegsPath(home);
+  const row = `${JSON.stringify({ at: now, pid, sessionId: sessionId ?? null, source })}\n`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    if (existsSync(path) && statSync(path).size > PUSH_LEGS_MAX_BYTES) {
+      const kept = readFileSync(path, "utf8").split("\n").filter((line) => line.length > 0).slice(-PUSH_LEGS_KEEP);
+      writeFileSync(`${path}.tmp`, `${kept.join("\n")}\n`, "utf8");
+      renameSync(`${path}.tmp`, path);
+    }
+    appendFileSync(path, row, "utf8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Newest recorded read path (and how many rows mention each verdict).
+ * Never throws; returns `undefined` when nothing was ever recorded.
+ *
+ * @param {string} home DSH home
+ * @returns {{at: number, source: string, sessionId: string|null, pid: number, counts: Record<string, number>} | undefined}
+ */
+export function readPushLegsHealth(home) {
+  if (typeof home !== "string" || home.length === 0) return undefined;
+  let raw;
+  try {
+    raw = readFileSync(pushLegsPath(home), "utf8");
+  } catch {
+    return undefined;
+  }
+  const counts = {};
+  let newest;
+  for (const line of raw.split("\n")) {
+    if (line.length === 0) continue;
+    let row;
+    try {
+      row = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (typeof row?.source !== "string") continue;
+    counts[row.source] = (counts[row.source] ?? 0) + 1;
+    if (newest === undefined || (typeof row.at === "number" && row.at >= (newest.at ?? 0))) newest = row;
+  }
+  if (newest === undefined) return undefined;
+  return {
+    at: typeof newest.at === "number" ? newest.at : 0,
+    source: newest.source,
+    sessionId: typeof newest.sessionId === "string" ? newest.sessionId : null,
+    pid: typeof newest.pid === "number" ? newest.pid : 0,
+    counts,
+  };
+}
+
+/**
+ * One-line human summary for `dsh-engram status`.
+ * @param {ReturnType<typeof readPushLegsHealth>} health
+ * @returns {string}
+ */
+export function describePushLegs(health) {
+  if (health === undefined) return "推送腿：还没记录（本机还没有会话装配过）";
+  const when = new Date(health.at).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" });
+  const tally = Object.entries(health.counts)
+    .map(([source, count]) => `${source}×${count}`)
+    .join(" · ");
+  if (health.source === "none") {
+    return `推送腿：⚠ 事件日志不可读（none）—— [RECALL]/episode/resume/todo-sink 休眠中 · ${when} · ${tally}`;
+  }
+  return `推送腿：事件日志读法 ${health.source} · 最近 ${when} · ${tally}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "packageManager": "pnpm@11.22.0",
   "license": "MIT",
   "repository": {

package/scripts/dsh-engram.mjs

@@ -25,6 +25,7 @@ import { execFileSync } from "node:child_process";
 import { dirname, basename, resolve, join } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
+import { describePushLegs, readPushLegsHealth } from "../lib/push-legs.js";
 import {
   compactionWireStatus,
   discoverPresetsDir,
@@ -37,7 +38,7 @@ import { defaultSkillDir, exportSkills, skillDescription, skillName, planSkillEx
 import { approvedIds, isApproved, loadApprovals, recordApproval, revokeApproval } from "../lib/approvals.js";
 import { isProvenProcedure, invalidatedProcedure } from "../lib/status-insights.js";
 import { workspaceKey } from "../lib/util.js";
-import { ENGRAM_PRUNE_ROW_NAME } from "../lib/web-provision.js";
+import { ENGRAM_PRUNE_ROW_NAME, swapCompactionRow } from "../lib/web-provision.js";
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -236,6 +237,15 @@ async function printStatus(presetsDirFlag) {
     }
   } catch {}
 
+  // Push legs (issue #9): which session-event read path the live process took.
+  // Printed from data, not from startup logs — a dormant leg must be visible
+  // without the terminal that printed the warning.
+  try {
+    const home = process.env.DSH_HOME ?? join(homedir(), ".dsh");
+    log(`  ${describePushLegs(readPushLegsHealth(home))}`);
+    log("");
+  } catch {}
+
   if (status === undefined) {
     log("  尚无状态文件（插件还没写过，或本机没跑过 dsh web）。");
   } else {
@@ -299,7 +309,14 @@ async function printStatus(presetsDirFlag) {
       const note = cs === "wired"
         ? `已接管（dsh-engram/compaction 行${hasPrune ? " + dsh-engram/prune 行" : " · 缺 prune 行：L1 在这个预设里看不见边界，重跑 enable 补齐"}）`
         : cs === "stock"
-          ? "出厂布局，重启 dsh web 后自动接管"
+          ? swapCompactionRow(text) === null
+            // "stock" only says the stock row is present; it does not promise
+            // the swap will take. `minimal` ships a compaction group without
+            // the result pruner, so the swap refuses to guess and the preset
+            // stays stock forever — saying "重启后自动接管" there would be a
+            // status line that lies.
+            ? "出厂布局但与标准形状不同（行不全），自动接管不会发生；要 Context GC 请手工接线或改用 standard"
+            : "出厂布局，重启 dsh web 后自动接管"
           : "自定义/无 compaction，插件不碰";
       log(`  ${preset.id}: ${cs} — ${note}`);
     }