dsh-engram 0.7.2 → 0.8.6

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/preference.js

@@ -28,6 +28,7 @@
  */
 
 import { workspaceKey as wk } from "./util.js";
+import { sessionSeq } from "./session-events.js";
 
 /** Direction of the preference statement, used in the captured text. */
 export const PREFERENCE_DIRECTION = {
@@ -244,7 +245,7 @@ export function installPreferenceCapture(ctx, storeAdapter, config, log, stats)
             signal: PREFERENCE_SIGNAL,
             filePath: null,
             sessionId,
-            seq: Array.isArray(session.events) ? session.events.length : 0,
+            seq: sessionSeq(session),
           },
           config,
         )

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

@@ -0,0 +1,168 @@
+/**
+ * Session event-log access across DSH generations.
+ *
+ * WHY THIS EXISTS (2026-10-20, the second "silent zero"):
+ * DSH ≤0.1.x exposed the conversation log as `session.events`, a plain frozen
+ * array. DSH 0.2.x removed that getter — `Session.prototype` now carries only
+ * `eventAt` / `snapshotEvents` / `ownEvents` / `deriveEventMessage`, and the
+ * synchronous full-log read is deprecated host-internally in favour of
+ * `ctx.sessionQuery.live(session)` leases. Every
+ * `Array.isArray(session.events)` read in this plugin therefore yielded `[]`
+ * on the running host, silently disabling three whole features while their
+ * unit tests (which mock `{ events: [...] }`) stayed green:
+ *
+ *   - `[RECALL]` session-start auto-recall never materialized (no first user
+ *     message → no query), and worse, `index.js` refused to cache the
+ *     `[ENGRAM]` block ("pendingRecall") on every assembly, so the index was
+ *     re-rendered per turn and never metered into the ledger;
+ *   - session episodes were never written → `[RESUME]` briefs never fired;
+ *   - the session-end todo sink never found a pending todo → no ESR drafts.
+ *
+ * The lesson is the same one as the session-log rename (memory #8): a
+ * host-API read must feature-detect and REPORT, never silently degrade to an
+ * empty value. `sessionEventsSource()` names the path taken so the status
+ * snapshot can surface `none` instead of pretending the log was empty.
+ *
+ * Resolution order (first working wins):
+ *   1. `session.events`            — legacy hosts (≤0.1.x), and every unit test;
+ *   2. `sessionQuery.live(session)`— sanctioned ≥0.2.x lease (lazy snapshot);
+ *   3. `session.snapshotEvents()`  — context-free fallback (deprecated host-side,
+ *                                    still the only sync full-log read a plugin has);
+ *   4. `[]`                        — nothing readable; callers degrade and
+ *                                    `sessionEventsSource` reports "none".
+ */
+
+/** Shared empty array: callers only read, so one frozen instance is enough. */
+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"|"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 &&
+    typeof sessionQuery === "object" &&
+    typeof sessionQuery.live === "function"
+  );
+}
+
+/**
+ * Read a session's event log across DSH generations (see module header).
+ *
+ * Returns a frozen-or-plain array of events; never throws. A session that
+ * genuinely has no events and a session whose log is unreadable both return
+ * `[]` — use {@link sessionEventsSource} when the difference matters.
+ *
+ * @param {object} session host session (`agent.session`, or the arg of
+ *   `session/disposed`)
+ * @param {object} [sessionQuery] the `ctx.sessionQuery` service, if mounted
+ * @returns {ReadonlyArray<object>}
+ */
+export function readSessionEvents(session, sessionQuery = void 0) {
+  if (session === null || typeof session !== "object") return NO_EVENTS;
+
+  // 1. Legacy: DSH ≤0.1.x (and every unit-test double).
+  if (Array.isArray(session.events)) return session.events;
+
+  // 2. Sanctioned ≥0.2.x: a live lease exposes a lazily materialized snapshot
+  //    up to the session's current seq. Dispose it immediately — we only need
+  //    the array, not the retention or the projection payload.
+  if (hasLive(sessionQuery)) {
+    let lease;
+    try {
+      lease = sessionQuery.live(session);
+      const events = lease?.events;
+      if (Array.isArray(events)) return events;
+    } catch {
+      // fall through to snapshotEvents
+    } finally {
+      try {
+        lease?.[Symbol.dispose]?.();
+      } catch {
+        // best-effort lease release
+      }
+    }
+  }
+
+  // 3. Context-free fallback.
+  if (typeof session.snapshotEvents === "function") {
+    try {
+      const end = typeof session.seq === "number" ? session.seq : void 0;
+      const events = end === void 0 ? session.snapshotEvents() : session.snapshotEvents(0, end);
+      if (Array.isArray(events)) return events;
+    } catch {
+      // unreadable — degrade
+    }
+  }
+
+  // 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;
+}
+
+/**
+ * The session's current event count, for provenance `seq` stamps.
+ *
+ * `seq` is the next free seq on ≥0.2.x (`session.seq`), so it equals the log
+ * length; on legacy hosts the array length is the same number. Kept here so
+ * the four write sites (capture / tools / preference / episode) agree.
+ */
+export function sessionSeq(session, sessionQuery = void 0) {
+  if (session === null || typeof session !== "object") return 0;
+  const seq = session.seq;
+  if (typeof seq === "number" && Number.isFinite(seq) && seq >= 0) return Math.trunc(seq);
+  const events = readSessionEvents(session, sessionQuery);
+  return events.length;
+}