dsh-engram 0.7.4 → 0.8.7

package/lib/ledger.js

@@ -30,9 +30,15 @@ import path from "node:path";
 
 const FILE_NAME = "ledger.json";
 /** Matches the estimate used by the GUI (`chars / 4`). */
-const CHARS_PER_TOKEN = 4;
+export const CHARS_PER_TOKEN = 4;
 const DEFAULT_CACHE_DISCOUNT = 0.1;
 const DEFAULT_FLUSH_EVERY = 20;
+/** Per-session rows kept on disk (newest activity wins; older ones drop). */
+const DEFAULT_MAX_SESSION_ROWS = 200;
+/** Rows returned by `summary()` — the GUI never needs the whole history. */
+const SUMMARY_SESSION_ROWS = 50;
+/** Session ids that would land on the prototype chain if used as row keys. */
+const RESERVED_ROW_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 
 /** Default ledger file under the engram home. */
 export function ledgerFile(home = path.join(os.homedir(), ".dsh", "engram")) {
@@ -84,6 +90,13 @@ function deltaOf(session) {
     avoidedChars: session.avoidedChars - f.avoidedChars,
     rewriteCount: session.rewriteCount - f.rewriteCount,
     rewriteChars: session.rewriteChars - f.rewriteChars,
+    // These three used to be written as absolute values (`row.x = session.x`),
+    // which silently zeroed a session's history on every restart: the in-memory
+    // counters start at 0 and the first flush after boot overwrote the durable
+    // row. Deltas are the only thing a restart can't corrupt.
+    prunedChars: count(session.prunedChars) - count(f.prunedChars),
+    hostPrunedChars: count(session.hostPrunedChars) - count(f.hostPrunedChars),
+    compactedChars: count(session.compactedChars) - count(f.compactedChars),
   };
 }
 
@@ -93,7 +106,10 @@ function isEmptyDelta(delta) {
     delta.injectedChars === 0 &&
     delta.avoidedChars === 0 &&
     delta.rewriteCount === 0 &&
-    delta.rewriteChars === 0
+    delta.rewriteChars === 0 &&
+    delta.prunedChars === 0 &&
+    delta.hostPrunedChars === 0 &&
+    delta.compactedChars === 0
   );
 }
 
@@ -119,6 +135,48 @@ export function finalizeLedgerBucket(bucket, cacheDiscount = DEFAULT_CACHE_DISCO
   };
 }
 
+/** A durable per-session row: what ONE session spent and saved (raw counts). */
+function emptySessionRow(sessionId, workspace) {
+  return {
+    sessionId,
+    workspace: typeof workspace === "string" ? workspace : "",
+    firstDay: "",
+    lastDay: "",
+    updatedAt: 0,
+    requests: 0,
+    injectedChars: 0,
+    avoidedChars: 0,
+    rewriteCount: 0,
+    rewriteChars: 0,
+    prunedChars: 0,
+    hostPrunedChars: 0,
+    compactedChars: 0,
+  };
+}
+
+/**
+ * Finalize a session row with the same net arithmetic as a bucket (pure).
+ *
+ * The gates in docs/PROPOSAL-evolution.zh.md §6 are per-session questions
+ * ("净收益 > 0 的会话占比", "长会话占比"), which a day-level rollup cannot
+ * answer — it aggregates them away. These rows exist so the answer is a
+ * read, not an estimate.
+ */
+export function finalizeSessionRow(row, cacheDiscount = DEFAULT_CACHE_DISCOUNT) {
+  const { sessions: _bucketSessions, ...base } = finalizeLedgerBucket(row, cacheDiscount);
+  return {
+    sessionId: String(row?.sessionId ?? ""),
+    workspace: String(row?.workspace ?? ""),
+    firstDay: String(row?.firstDay ?? ""),
+    lastDay: String(row?.lastDay ?? ""),
+    updatedAt: count(row?.updatedAt),
+    prunedChars: count(row?.prunedChars),
+    hostPrunedChars: count(row?.hostPrunedChars),
+    compactedChars: count(row?.compactedChars),
+    ...base,
+  };
+}
+
 function readPersisted(file) {
   try {
     const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -188,6 +246,7 @@ export function estimatePrefixChars(session) {
  * @param {string} [opts.home] engram home (defaults to ~/.dsh/engram)
  * @param {number} [opts.cacheDiscount] cached-prefix price share (0..1)
  * @param {number} [opts.flushEvery] requests between durable flushes
+ * @param {number} [opts.maxSessionRows] per-session rows kept on disk
  * @param {boolean} [opts.persist] false = pure in-memory (tests, dry runs)
  * @param {() => number} [opts.now] clock injection for tests
  * @param {object} [opts.log] optional logger (warn only)
@@ -196,6 +255,7 @@ export function createLedger({
   home = path.join(os.homedir(), ".dsh", "engram"),
   cacheDiscount = DEFAULT_CACHE_DISCOUNT,
   flushEvery = DEFAULT_FLUSH_EVERY,
+  maxSessionRows = DEFAULT_MAX_SESSION_ROWS,
   persist = true,
   now = Date.now,
   log = void 0,
@@ -204,13 +264,17 @@ export function createLedger({
   const discount = clampDiscount(cacheDiscount);
   const every = Number.isFinite(flushEvery) && flushEvery > 0 ? Math.trunc(flushEvery) : 0;
   const stored = persist ? readPersisted(file) : null;
-  const state = stored ?? { version: 1, updatedAt: 0, workspaces: {} };
+  const state = stored ?? { version: 1, updatedAt: 0, workspaces: {}, sessions: {} };
+  if (state.sessions === null || typeof state.sessions !== "object") state.sessions = {};
+  const rowCap = Number.isFinite(maxSessionRows) && maxSessionRows > 0 ? Math.trunc(maxSessionRows) : DEFAULT_MAX_SESSION_ROWS;
   const sessions = new Map();
 
   function ensure(sessionId, workspace) {
     if (typeof sessionId !== "string" || sessionId.length === 0) return null;
     let session = sessions.get(sessionId);
     if (session === void 0) {
+      const persisted = state.sessions?.[sessionId];
+      const seed = persisted !== null && typeof persisted === "object" ? persisted : null;
       session = {
         sessionId,
         workspace: typeof workspace === "string" ? workspace : "",
@@ -220,11 +284,22 @@ export function createLedger({
         requests: 0,
         injectedChars: 0,
         avoidedChars: 0,
-        prunedChars: 0,
-        compactedChars: 0,
-        rewriteCount: 0,
-        rewriteChars: 0,
-        flushed: { requests: 0, injectedChars: 0, avoidedChars: 0, rewriteCount: 0, rewriteChars: 0 },
+        prunedChars: count(seed?.prunedChars),
+        hostPrunedChars: count(seed?.hostPrunedChars),
+        compactedChars: count(seed?.compactedChars),
+        rewriteCount: count(seed?.rewriteCount),
+        rewriteChars: count(seed?.rewriteChars),
+        updatedAt: 0,
+        flushed: {
+          requests: 0,
+          injectedChars: 0,
+          avoidedChars: 0,
+          rewriteCount: count(seed?.rewriteCount),
+          rewriteChars: count(seed?.rewriteChars),
+          prunedChars: count(seed?.prunedChars),
+          hostPrunedChars: count(seed?.hostPrunedChars),
+          compactedChars: count(seed?.compactedChars),
+        },
         firstFlush: false,
       };
       sessions.set(sessionId, session);
@@ -249,6 +324,34 @@ export function createLedger({
     return days[day];
   }
 
+  /** The durable row for one session, created on first flush. */
+  function rowFor(session, day) {
+    // session ids are host-generated, but a row key must never hit the
+    // prototype chain.
+    if (RESERVED_ROW_KEYS.has(session.sessionId)) return null;
+    let row = state.sessions[session.sessionId];
+    if (row === null || row === void 0 || typeof row !== "object") {
+      row = emptySessionRow(session.sessionId, session.workspace);
+      state.sessions[session.sessionId] = row;
+    }
+    if (row.firstDay === void 0 || row.firstDay.length === 0) row.firstDay = day;
+    row.lastDay = day;
+    row.updatedAt = Math.max(count(row.updatedAt), count(session.updatedAt), now());
+    if (typeof session.workspace === "string" && session.workspace.length > 0) row.workspace = session.workspace;
+    return row;
+  }
+
+  /** Keep the newest `rowCap` rows; a session that never ran is not history. */
+  function pruneRows() {    const entries = Object.entries(state.sessions);
+    if (entries.length <= rowCap) return;
+    entries
+      .sort((a, b) => count(b[1]?.updatedAt) - count(a[1]?.updatedAt))
+      .slice(rowCap)
+      .forEach(([id]) => {
+        delete state.sessions[id];
+      });
+  }
+
   function flushSession(session) {
     if (session === null || session === void 0) return false;
     const delta = deltaOf(session);
@@ -261,12 +364,29 @@ export function createLedger({
         session.firstFlush = true;
       }
       addBucket(bucket, delta);
+      // Per-session row (same delta, same instant) — the gates need the
+      // distribution, not the sum.
+      const row = rowFor(session, day);
+      if (row !== null) {
+        row.requests += count(delta.requests);
+        row.injectedChars += count(delta.injectedChars);
+        row.avoidedChars += count(delta.avoidedChars);
+        row.rewriteCount += count(delta.rewriteCount);
+        row.rewriteChars += count(delta.rewriteChars);
+        row.prunedChars += count(delta.prunedChars);
+        row.hostPrunedChars += count(delta.hostPrunedChars);
+        row.compactedChars += count(delta.compactedChars);
+        pruneRows();
+      }
       session.flushed = {
         requests: session.requests,
         injectedChars: session.injectedChars,
         avoidedChars: session.avoidedChars,
         rewriteCount: session.rewriteCount,
         rewriteChars: session.rewriteChars,
+        prunedChars: count(session.prunedChars),
+        hostPrunedChars: count(session.hostPrunedChars),
+        compactedChars: count(session.compactedChars),
       };
       state.updatedAt = now();
       if (persist) writeJsonAtomic(file, state);
@@ -281,6 +401,40 @@ export function createLedger({
     for (const session of sessions.values()) flushSession(session);
   }
 
+  /**
+   * Per-session rows for reading (persisted rows + the open sessions'
+   * unflushed tails merged in). Non-mutating, newest activity first.
+   */
+  function sessionRows(limit = SUMMARY_SESSION_ROWS) {
+    const rows = new Map();
+    for (const [id, row] of Object.entries(state.sessions ?? {})) {
+      if (row === null || typeof row !== "object") continue;
+      rows.set(id, { ...emptySessionRow(id, row.workspace), ...row });
+    }
+    const today = ledgerDayKey(now());
+    for (const session of sessions.values()) {
+      const delta = deltaOf(session);
+      const row = rows.get(session.sessionId) ?? emptySessionRow(session.sessionId, session.workspace);
+      row.requests += count(delta.requests);
+      row.injectedChars += count(delta.injectedChars);
+      row.avoidedChars += count(delta.avoidedChars);
+      row.rewriteCount += count(delta.rewriteCount);
+      row.rewriteChars += count(delta.rewriteChars);
+      row.prunedChars = count(session.prunedChars);
+      row.hostPrunedChars = count(session.hostPrunedChars);
+      row.compactedChars = count(session.compactedChars);
+      if (session.workspace.length > 0) row.workspace = session.workspace;
+      if (typeof row.firstDay !== "string" || row.firstDay.length === 0) row.firstDay = today;
+      row.lastDay = today;
+      if (session.updatedAt > 0) row.updatedAt = Math.max(count(row.updatedAt), count(session.updatedAt));
+      rows.set(session.sessionId, row);
+    }
+    return [...rows.values()]
+      .map((row) => finalizeSessionRow(row, discount))
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .slice(0, limit);
+  }
+
   return {
     /** Record the latest injected block size for one component. */
     noteInjection(sessionId, workspace, component, chars) {
@@ -288,6 +442,7 @@ export function createLedger({
         const session = ensure(sessionId, workspace);
         if (session === null) return;
         const size = count(chars);
+        session.updatedAt = now();
         if (component === "esr") session.esrChars = size;
         else if (component === "jit") session.jitChars = size;
         else session.indexChars = size;
@@ -302,6 +457,7 @@ export function createLedger({
         const session = ensure(sessionId, workspace);
         if (session === null) return;
         session.requests += 1;
+        session.updatedAt = now();
         session.injectedChars += session.indexChars + session.esrChars + session.jitChars;
         session.avoidedChars += session.prunedChars + session.compactedChars;
         if (every > 0 && session.requests % every === 0) flushSession(session);
@@ -310,11 +466,29 @@ export function createLedger({
       }
     },
 
-    /** A prune fired: its removed chars stop replaying from the next request. */
-    notePrune(sessionId, workspace, { charsRemoved = 0, rewriteChars = 0 } = {}) {
+    /**
+     * A prune happened: its removed chars stop replaying from the next request.
+     *
+     * `source` keeps the attribution honest — only prunes engram CAUSED count
+     * toward `prunedChars` (and therefore toward avoidedChars/NetTokens). The
+     * host prunes over-threshold results on its own (observed live: 12,491
+     * tokens shadowed with no boundary in sight); those land in
+     * `hostPrunedChars`, visible but never claimed as engram's saving.
+     */
+    notePrune(sessionId, workspace, { charsRemoved = 0, rewriteChars = 0, source = "boundary" } = {}) {
       try {
         const session = ensure(sessionId, workspace);
         if (session === null) return;
+        session.updatedAt = now();
+        if (source === "host") {
+          // Symmetry: we do not claim the host's savings, so we do not pay its
+          // rewrite cost either. Charging both ways made ordinary sessions look
+          // catastrophic (1.22M chars of rewrite for prunes engram never asked
+          // for) — the exact bias that turns a neutral session into -1.7M.
+          session.hostPrunedChars += count(charsRemoved);
+          flushSession(session);
+          return;
+        }
         session.prunedChars += count(charsRemoved);
         session.rewriteCount += 1;
         session.rewriteChars += count(rewriteChars);
@@ -329,6 +503,7 @@ export function createLedger({
       try {
         const session = ensure(sessionId, workspace);
         if (session === null) return;
+        session.updatedAt = now();
         session.compactedChars += count(charsSaved);
       } catch (error) {
         log?.warn?.(`engram ledger noteCompaction failed: ${String(error)}`);
@@ -343,6 +518,7 @@ export function createLedger({
       try {
         const session = ensure(sessionId, workspace);
         if (session === null) return;
+        session.updatedAt = now();
         session.rewriteCount += 1;
         session.rewriteChars += count(chars);
         flushSession(session);
@@ -402,6 +578,11 @@ export function createLedger({
       const totals = emptyBucket();
       for (const bucket of Object.values(byWorkspace)) addBucket(totals, bucket);
 
+      const rowsHostPruned = sessionRows(SUMMARY_SESSION_ROWS).reduce(
+        (sum, row) => sum + count(row.hostPrunedChars),
+        0,
+      );
+
       const finalizedWorkspaces = {};
       for (const [ws, bucket] of Object.entries(byWorkspace)) {
         finalizedWorkspaces[ws] = finalizeLedgerBucket(bucket, discount);
@@ -417,8 +598,11 @@ export function createLedger({
         cacheDiscount: discount,
         openSessions: sessions.size,
         totals: finalizeLedgerBucket(totals, discount),
+        // Savings the HOST performed on its own (visible, never claimed).
+        hostPrunedChars: rowsHostPruned,
         byWorkspace: finalizedWorkspaces,
         byDay: finalizedDays,
+        sessions: sessionRows(SUMMARY_SESSION_ROWS),
       };
     },
   };
@@ -442,6 +626,10 @@ export function readLedger({ home, cacheDiscount = DEFAULT_CACHE_DISCOUNT } = {}
   }
   const totals = emptyBucket();
   for (const bucket of Object.values(workspaces)) addBucket(totals, bucket);
+  const rows = Object.values(stored?.sessions ?? {})
+    .filter((row) => row !== null && typeof row === "object")
+    .map((row) => finalizeSessionRow(row, cacheDiscount))
+    .sort((a, b) => b.updatedAt - a.updatedAt);
   return {
     version: 1,
     updatedAt: stored?.updatedAt ?? 0,
@@ -454,5 +642,7 @@ export function readLedger({ home, cacheDiscount = DEFAULT_CACHE_DISCOUNT } = {}
     byDay: Object.entries(days)
       .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, cacheDiscount) }))
       .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0)),
+    sessions: rows,
+    hostPrunedChars: rows.reduce((sum, row) => sum + count(row.hostPrunedChars), 0),
   };
 }

package/lib/pack-telemetry.js

@@ -21,9 +21,16 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-/** Default engram home (mirrors result-pack.js). */
-export function engramHome(home = path.join(os.homedir(), ".dsh", "engram")) {
-  return home;
+/** Default engram home: `$DSH_HOME/engram` when set (tests, sandboxes, custom
+ *  installs), else `~/.dsh/engram` (mirrors status.js / result-pack.js). A
+ *  plain `~/.dsh` default made every test run write live telemetry into the
+ *  developer's real install. */
+export function engramHome(home = void 0) {
+  if (typeof home === "string" && home.length > 0) return home;
+  const dshHome = process.env.DSH_HOME;
+  return dshHome !== void 0 && dshHome.length > 0
+    ? path.join(dshHome, "engram")
+    : path.join(os.homedir(), ".dsh", "engram");
 }
 
 function statusFile(home, name) {

package/lib/prune.js

@@ -0,0 +1,89 @@
+/**
+ * dsh-engram — BoundaryPrune (L1) as a mountable entry INSIDE the agent preset.
+ *
+ * Why this entry exists: web sessions live in the agent preset's own realm, and
+ * their `session/event`s are only observed by plugins mounted in that realm.
+ * The host-plane install armed fine (`boundaryPrune.armed: true`) and still never
+ * fired across every session on the profile: the listener was on the wrong side
+ * of the realm boundary, so a real `todo/write` boundary produced nothing — the
+ * ledger's prune credit leg was structurally dead for `dsh web`.
+ *
+ * This row sits in the same `compaction` group as `dsh-engram/compaction`
+ * (which already isolates `toolResultPruner` for the agent plane), so it sees
+ * the sessions' events and holds that realm's pruner:
+ *
+ * ```yaml
+ * - id: compaction
+ *   name: cordis:group
+ *   group: true
+ *   isolate: { compaction: true, toolResultPruner: true }
+ *   config:
+ *     - id: engram-compaction
+ *       name: dsh-engram/compaction
+ *     - id: engram-prune
+ *       name: dsh-engram/prune        # this entry
+ *     - id: command-compact
+ *       name: '@deepseek-ai/dsh-command-compact'
+ *     - id: tool-result-pruner
+ *       name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+ * ```
+ *
+ * The host plugin still installs its own L1 for host-plane (headless/TUI)
+ * sessions. Running both is safe: `toolResultPruner.pruneSession` only prunes
+ * over-threshold results, so a second pass over an already-pruned surface finds
+ * nothing and credits nothing.
+ *
+ * Config: the same keys the host entries read (`boundaryPrune`,
+ * `boundaryPruneMinRemaining`, `boundaryPruneThresholdChars`,
+ * `boundaryPruneHeadChars`, `boundaryPruneTailChars`,
+ * `boundaryPruneIdleCadence`, `boundaryPruneAdaptive`). Ledger credit goes
+ * through the host-provided `engramLedger` service so there is exactly one
+ * ledger writer.
+ */
+import { installBoundaryPrune, boundaryPruneAvailability } from "./boundary-prune.js";
+import { estimatePrefixChars } from "./ledger.js";
+import { recordBoundaryPruneFire, engramHome } from "./pack-telemetry.js";
+import { recordPruneAttempt } from "./status.js";
+import { workspaceKey as wk } from "./util.js";
+
+export const name = "dsh-engram-prune";
+export const inject = ["toolResultPruner"];
+
+/** The plane tag every attempt from this entry carries. */
+export const PLANE = "preset";
+
+export function apply(ctx, config = {}) {
+  const log = typeof ctx?.logger === "function" ? ctx.logger("dsh-engram-prune") : undefined;
+
+  // Diagnostics first: proves the row loaded at all (a row that fails to load
+  // looks exactly like one that works, until nothing ever fires).
+  try {
+    ctx.logger?.info?.(`engram boundary-prune (preset plane): ${boundaryPruneAvailability(ctx, config).reason ?? "armed"}`);
+  } catch { /* never break the mount for a log line */ }
+
+  const hooks = {
+    onPruned: (session, report, boundary) => {
+      const workspace = wk(session?.header?.cwd);
+      // Durable activation telemetry (shared with the host plane; the summary
+      // reports `activation.boundaryPrune` from it).
+      recordBoundaryPruneFire({ home: engramHome(), boundary, report, workspace });
+      // The prune rewrote the prefix: credit the removed chars, price the
+      // invalidation with the pre-prune size (mirrors the host-plane path).
+      const removed = Number.isFinite(report?.charsRemoved) ? report.charsRemoved : 0;
+      const prefixChars = estimatePrefixChars(session);
+      try {
+        const ledger = ctx.get?.("engramLedger");
+        ledger?.notePrune?.(session?.id, workspace, {
+          charsRemoved: removed,
+          rewriteChars: prefixChars + removed,
+        });
+      } catch { /* accounting must never break pruning */ }
+    },
+  };
+
+  return installBoundaryPrune(ctx, config, log, hooks, {
+    onAttempt: (attempt) => {
+      void recordPruneAttempt({ plane: PLANE, ...attempt });
+    },
+  });
+}

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/lib/session-events.js

@@ -39,16 +39,39 @@ const NO_EVENTS = Object.freeze([]);
  * Which read path a session exposes, without materializing the log.
  * @param {object} session
  * @param {object} [sessionQuery] the `ctx.sessionQuery` service, if mounted
- * @returns {"legacy"|"sessionQuery"|"snapshotEvents"|"none"}
+ * @returns {"legacy"|"sessionQuery"|"snapshotEvents"|"eventAt"|"none"}
  */
 export function sessionEventsSource(session, sessionQuery = void 0) {
   if (session === null || typeof session !== "object") return "none";
   if (Array.isArray(session.events)) return "legacy";
   if (hasLive(sessionQuery)) return "sessionQuery";
   if (typeof session.snapshotEvents === "function") return "snapshotEvents";
+  // Last-resort hand: the per-seq accessor is the primitive every other read
+  // is built on, so a host can drop the bulk readers and still answer `eventAt`.
+  // The Windows desktop runtime (issue #9) is exactly that host.
+  if (typeof session.eventAt === "function") return "eventAt";
   return "none";
 }
 
+/**
+ * What the session object actually offers, for the dormancy warning. A bare
+ * "nothing is readable" tells the reporter nothing; the method names tell us
+ * which generation of the host we are talking to.
+ * @param {object} session
+ * @returns {string[]} sorted prototype method names (own properties included)
+ */
+export function describeSessionSurface(session) {
+  if (session === null || typeof session !== "object") return [];
+  const names = new Set();
+  for (let proto = session; proto !== null && proto !== Object.prototype; proto = Object.getPrototypeOf(proto)) {
+    for (const name of Object.getOwnPropertyNames(proto)) {
+      if (name === "constructor" || name.startsWith("_")) continue;
+      names.add(name);
+    }
+  }
+  return [...names].sort();
+}
+
 function hasLive(sessionQuery) {
   return (
     sessionQuery !== null &&
@@ -106,7 +129,26 @@ export function readSessionEvents(session, sessionQuery = void 0) {
     }
   }
 
-  // 4. Nothing.
+  // 4. Per-seq accessor: read the log one event at a time. Slower than the bulk
+  //    readers and only used when they are gone, but it keeps [RECALL] /
+  //    episode / todo-sink alive on hosts that dropped `snapshotEvents`.
+  if (typeof session.eventAt === "function") {
+    const total = typeof session.seq === "number" && session.seq >= 0 ? Math.trunc(session.seq) : Number.POSITIVE_INFINITY;
+    const events = [];
+    for (let seq = 0; seq < total; seq += 1) {
+      let event;
+      try {
+        event = session.eventAt(seq);
+      } catch {
+        return events.length > 0 ? events : NO_EVENTS;
+      }
+      if (event === undefined || event === null) break;
+      events.push(event);
+    }
+    return events;
+  }
+
+  // 5. Nothing.
   return NO_EVENTS;
 }