dsh-engram 0.5.0 → 0.6.0

package/lib/ledger.js

@@ -0,0 +1,458 @@
+/**
+ * Context Ledger — the accounting layer of the "context portfolio"
+ * (docs/PROPOSAL-evolution.zh.md §4 v0.6-A).
+ *
+ * Every engram mechanism either spends context (injected index / recall / ESR
+ * blocks, held in the prompt prefix for the rest of the session) or saves it
+ * (pruned / compacted tool results that stop replaying). The ledger turns that
+ * into one auditable number per session, workspace and day:
+ *
+ *   net = avoided − injected − rewriteChars × (1 − cacheDiscount)
+ *
+ * where `rewriteChars` is the prefix size invalidated by a prune (KV cache
+ * break). `cacheDiscount` is the fraction a cached prefix would have cost
+ * (0.1 = 10%, the conservative L0 assumption), so the penalty is the
+ * non-discounted remainder.
+ *
+ * Zero LLM, deterministic, fail-contained. Two layers:
+ *   - live per-session accumulator, ticked by `assistant/message` events
+ *   - durable daily rollup at `~/.dsh/engram/ledger.json`, delta-flushed so a
+ *     restart loses at most `flushEvery` requests of accounting
+ *
+ * Deliberately NOT here: model-quality deltas, actual provider billing, and
+ * compaction savings whose before/after size the host does not expose yet.
+ * Those stay labelled assumptions, never invented numbers.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const FILE_NAME = "ledger.json";
+/** Matches the estimate used by the GUI (`chars / 4`). */
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_CACHE_DISCOUNT = 0.1;
+const DEFAULT_FLUSH_EVERY = 20;
+
+/** Default ledger file under the engram home. */
+export function ledgerFile(home = path.join(os.homedir(), ".dsh", "engram")) {
+  return path.join(home, FILE_NAME);
+}
+
+/** Local YYYY-MM-DD (calendar days for the user, mirrors usage.dayKey). */
+export function ledgerDayKey(now = Date.now()) {
+  const d = new Date(now);
+  const p = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+
+function clampDiscount(value) {
+  if (!Number.isFinite(value)) return DEFAULT_CACHE_DISCOUNT;
+  return Math.min(1, Math.max(0, value));
+}
+
+function count(value) {
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : 0;
+}
+
+function emptyBucket() {
+  return {
+    sessions: 0,
+    requests: 0,
+    injectedChars: 0,
+    avoidedChars: 0,
+    rewriteCount: 0,
+    rewriteChars: 0,
+  };
+}
+
+function addBucket(target, delta) {
+  target.sessions += count(delta.sessions);
+  target.requests += count(delta.requests);
+  target.injectedChars += count(delta.injectedChars);
+  target.avoidedChars += count(delta.avoidedChars);
+  target.rewriteCount += count(delta.rewriteCount);
+  target.rewriteChars += count(delta.rewriteChars);
+  return target;
+}
+
+function deltaOf(session) {
+  const f = session.flushed;
+  return {
+    requests: session.requests - f.requests,
+    injectedChars: session.injectedChars - f.injectedChars,
+    avoidedChars: session.avoidedChars - f.avoidedChars,
+    rewriteCount: session.rewriteCount - f.rewriteCount,
+    rewriteChars: session.rewriteChars - f.rewriteChars,
+  };
+}
+
+function isEmptyDelta(delta) {
+  return (
+    delta.requests === 0 &&
+    delta.injectedChars === 0 &&
+    delta.avoidedChars === 0 &&
+    delta.rewriteCount === 0 &&
+    delta.rewriteChars === 0
+  );
+}
+
+/** Finalize one bucket with the net-token arithmetic (pure). */
+export function finalizeLedgerBucket(bucket, cacheDiscount = DEFAULT_CACHE_DISCOUNT) {
+  const discount = clampDiscount(cacheDiscount);
+  const injectedChars = count(bucket.injectedChars);
+  const avoidedChars = count(bucket.avoidedChars);
+  const rewriteChars = count(bucket.rewriteChars);
+  const netChars = avoidedChars - injectedChars - Math.round(rewriteChars * (1 - discount));
+  return {
+    sessions: count(bucket.sessions),
+    requests: count(bucket.requests),
+    injectedChars,
+    avoidedChars,
+    rewriteCount: count(bucket.rewriteCount),
+    rewriteChars,
+    injectedTokens: Math.ceil(injectedChars / CHARS_PER_TOKEN),
+    avoidedTokens: Math.ceil(avoidedChars / CHARS_PER_TOKEN),
+    netChars,
+    netTokens: Math.round(netChars / CHARS_PER_TOKEN),
+    rewritesCostChars: Math.round(rewriteChars * (1 - discount)),
+  };
+}
+
+function readPersisted(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (parsed === null || typeof parsed !== "object") return null;
+    if (parsed.version !== 1) return null;
+    if (parsed.workspaces === null || typeof parsed.workspaces !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** Atomic-ish write: tmp + rename, so a crash never leaves a torn file. */
+function writeJsonAtomic(file, payload) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(payload)}\n`, "utf8");
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    // best-effort accounting — never throw into the session pipeline
+    return false;
+  }
+}
+
+function contentChars(content) {
+  if (!Array.isArray(content)) return 0;
+  let chars = 0;
+  for (const block of content) {
+    if (block === null || typeof block !== "object") continue;
+    if (typeof block.text === "string") chars += [...block.text].length;
+  }
+  return chars;
+}
+
+/**
+ * Estimate the live prefix size a prune invalidates (in Unicode code points).
+ *
+ * Walks the session surface through the same accessors the host pruner uses
+ * (`surface.nodes` → `eventAt` → `deriveEventMessage`). Fail-contained: an
+ * unknown session shape yields 0, which makes the ledger conservative about
+ * claiming savings.
+ */
+export function estimatePrefixChars(session) {
+  try {
+    const seqs = session?.surface?.nodes;
+    if (seqs === void 0 || seqs === null) return 0;
+    if (typeof session.eventAt !== "function" || typeof session.deriveEventMessage !== "function") return 0;
+    let chars = 0;
+    for (const seq of [...seqs]) {
+      const event = session.eventAt(seq);
+      if (event === void 0 || event === null) continue;
+      const message = session.deriveEventMessage(event);
+      chars += contentChars(message?.content);
+    }
+    return chars;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Create the in-memory ledger + durable rollup writer.
+ *
+ * @param {object} [opts]
+ * @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 {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)
+ */
+export function createLedger({
+  home = path.join(os.homedir(), ".dsh", "engram"),
+  cacheDiscount = DEFAULT_CACHE_DISCOUNT,
+  flushEvery = DEFAULT_FLUSH_EVERY,
+  persist = true,
+  now = Date.now,
+  log = void 0,
+} = {}) {
+  const file = ledgerFile(home);
+  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 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) {
+      session = {
+        sessionId,
+        workspace: typeof workspace === "string" ? workspace : "",
+        indexChars: 0,
+        esrChars: 0,
+        jitChars: 0,
+        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 },
+        firstFlush: false,
+      };
+      sessions.set(sessionId, session);
+    } else if (typeof workspace === "string" && workspace.length > 0) {
+      session.workspace = workspace;
+    }
+    return session;
+  }
+
+  function bucketFor(workspace, day) {
+    const ws = typeof workspace === "string" && workspace.length > 0 ? workspace : "(unknown)";
+    const workspaces = state.workspaces;
+    if (workspaces[ws] === void 0 || workspaces[ws] === null || typeof workspaces[ws] !== "object") {
+      workspaces[ws] = {};
+    }
+    const days = workspaces[ws];
+    if (days[day] === void 0 || days[day] === null || typeof days[day] !== "object") {
+      days[day] = emptyBucket();
+    } else {
+      days[day] = { ...emptyBucket(), ...days[day] };
+    }
+    return days[day];
+  }
+
+  function flushSession(session) {
+    if (session === null || session === void 0) return false;
+    const delta = deltaOf(session);
+    if (isEmptyDelta(delta)) return false;
+    try {
+      const day = ledgerDayKey(now());
+      const bucket = bucketFor(session.workspace, day);
+      if (session.firstFlush === false) {
+        bucket.sessions += 1;
+        session.firstFlush = true;
+      }
+      addBucket(bucket, delta);
+      session.flushed = {
+        requests: session.requests,
+        injectedChars: session.injectedChars,
+        avoidedChars: session.avoidedChars,
+        rewriteCount: session.rewriteCount,
+        rewriteChars: session.rewriteChars,
+      };
+      state.updatedAt = now();
+      if (persist) writeJsonAtomic(file, state);
+      return true;
+    } catch (error) {
+      log?.warn?.(`engram ledger flush failed: ${String(error)}`);
+      return false;
+    }
+  }
+
+  function flush() {
+    for (const session of sessions.values()) flushSession(session);
+  }
+
+  return {
+    /** Record the latest injected block size for one component. */
+    noteInjection(sessionId, workspace, component, chars) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        const size = count(chars);
+        if (component === "esr") session.esrChars = size;
+        else if (component === "jit") session.jitChars = size;
+        else session.indexChars = size;
+      } catch (error) {
+        log?.warn?.(`engram ledger noteInjection failed: ${String(error)}`);
+      }
+    },
+
+    /** One model request completed: charge injected chars, credit savings. */
+    tick(sessionId, workspace) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.requests += 1;
+        session.injectedChars += session.indexChars + session.esrChars + session.jitChars;
+        session.avoidedChars += session.prunedChars + session.compactedChars;
+        if (every > 0 && session.requests % every === 0) flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger tick failed: ${String(error)}`);
+      }
+    },
+
+    /** A prune fired: its removed chars stop replaying from the next request. */
+    notePrune(sessionId, workspace, { charsRemoved = 0, rewriteChars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.prunedChars += count(charsRemoved);
+        session.rewriteCount += 1;
+        session.rewriteChars += count(rewriteChars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger notePrune failed: ${String(error)}`);
+      }
+    },
+
+    /** A compaction replaced history: the saved chars stop replaying too. */
+    noteCompaction(sessionId, workspace, { charsSaved = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.compactedChars += count(charsSaved);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteCompaction failed: ${String(error)}`);
+      }
+    },
+
+    /**
+     * A prefix rewrite that is not a prune (e.g. a JIT push appended to the
+     * prompt): charge the full prefix invalidation, credit nothing.
+     */
+    noteRewrite(sessionId, workspace, { chars = 0 } = {}) {
+      try {
+        const session = ensure(sessionId, workspace);
+        if (session === null) return;
+        session.rewriteCount += 1;
+        session.rewriteChars += count(chars);
+        flushSession(session);
+      } catch (error) {
+        log?.warn?.(`engram ledger noteRewrite failed: ${String(error)}`);
+      }
+    },
+
+    /** Session ended: fold the tail into the durable rollup and forget it. */
+    dispose(sessionId) {
+      try {
+        const session = sessions.get(sessionId);
+        if (session === void 0) return;
+        flushSession(session);
+        sessions.delete(sessionId);
+      } catch (error) {
+        log?.warn?.(`engram ledger dispose failed: ${String(error)}`);
+      }
+    },
+
+    flush,
+
+    /**
+     * Read the ledger: persisted rollup + unflushed live deltas. Pure (never
+     * mutates state), so /stats can call it on every request.
+     */
+    summary() {
+      const byWorkspace = {};
+      const byDay = {};
+
+      // persisted floor
+      for (const [ws, days] of Object.entries(state.workspaces ?? {})) {
+        if (days === null || typeof days !== "object") continue;
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        for (const [day, bucket] of Object.entries(days)) {
+          if (bucket === null || typeof bucket !== "object") continue;
+          addBucket(wsBucket, bucket);
+          const dayBucket = (byDay[day] ??= emptyBucket());
+          addBucket(dayBucket, bucket);
+        }
+      }
+
+      // live, not-yet-flushed tail
+      const today = ledgerDayKey(now());
+      for (const session of sessions.values()) {
+        const delta = deltaOf(session);
+        if (isEmptyDelta(delta)) continue;
+        const ws = session.workspace.length > 0 ? session.workspace : "(unknown)";
+        const wsBucket = (byWorkspace[ws] ??= emptyBucket());
+        if (session.firstFlush === false) wsBucket.sessions += 1;
+        addBucket(wsBucket, delta);
+        const dayBucket = (byDay[today] ??= emptyBucket());
+        if (session.firstFlush === false) dayBucket.sessions += 1;
+        addBucket(dayBucket, delta);
+      }
+
+      const totals = emptyBucket();
+      for (const bucket of Object.values(byWorkspace)) addBucket(totals, bucket);
+
+      const finalizedWorkspaces = {};
+      for (const [ws, bucket] of Object.entries(byWorkspace)) {
+        finalizedWorkspaces[ws] = finalizeLedgerBucket(bucket, discount);
+      }
+      const finalizedDays = Object.entries(byDay)
+        .map(([day, bucket]) => ({ day, ...finalizeLedgerBucket(bucket, discount) }))
+        .sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : 0));
+
+      return {
+        version: 1,
+        updatedAt: state.updatedAt ?? 0,
+        charsPerToken: CHARS_PER_TOKEN,
+        cacheDiscount: discount,
+        openSessions: sessions.size,
+        totals: finalizeLedgerBucket(totals, discount),
+        byWorkspace: finalizedWorkspaces,
+        byDay: finalizedDays,
+      };
+    },
+  };
+}
+
+/** Read the durable ledger without creating a live instance (GUI / tests). */
+export function readLedger({ home, cacheDiscount = DEFAULT_CACHE_DISCOUNT } = {}) {
+  const stored = readPersisted(ledgerFile(home));
+  const workspaces = {};
+  const days = {};
+  if (stored !== null) {
+    for (const [ws, wsDays] of Object.entries(stored.workspaces)) {
+      if (wsDays === null || typeof wsDays !== "object") continue;
+      const wsBucket = (workspaces[ws] ??= emptyBucket());
+      for (const [day, bucket] of Object.entries(wsDays)) {
+        if (bucket === null || typeof bucket !== "object") continue;
+        addBucket(wsBucket, bucket);
+        addBucket((days[day] ??= emptyBucket()), bucket);
+      }
+    }
+  }
+  const totals = emptyBucket();
+  for (const bucket of Object.values(workspaces)) addBucket(totals, bucket);
+  return {
+    version: 1,
+    updatedAt: stored?.updatedAt ?? 0,
+    charsPerToken: CHARS_PER_TOKEN,
+    cacheDiscount: clampDiscount(cacheDiscount),
+    totals: finalizeLedgerBucket(totals, cacheDiscount),
+    byWorkspace: Object.fromEntries(
+      Object.entries(workspaces).map(([ws, bucket]) => [ws, finalizeLedgerBucket(bucket, cacheDiscount)]),
+    ),
+    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)),
+  };
+}

package/lib/session-cjk.js

@@ -22,7 +22,7 @@
 import fs from "node:fs";
 import path from "node:path";
 
-import { decodeZstd, sessionsRoot } from "./usage.js";
+import { decodeZstd, sessionLogFile, sessionsRoot } from "./usage.js";
 import { redactText } from "./redact.js";
 
 /** CJK ideographs (incl. Ext-A and compatibility ideographs). */
@@ -135,7 +135,7 @@ export function searchSessionsCJK({
   }
   const files = [];
   for (const sid of sids) {
-    const file = path.join(bucketDir, sid, "session.jsonl.zstd");
+    const file = sessionLogFile(path.join(bucketDir, sid));
     let st;
     try {
       st = fs.statSync(file);

package/lib/settings.js

@@ -43,6 +43,7 @@ export const SETTINGS_KEYS = [
   "autoCapture",
   "autoCapturePreferences",
   "boundaryPrune",
+  "boundaryPruneAdaptive",
   "boundaryPruneThresholdChars",
   "boundaryPruneIdleCadence",
   "resultPack",
@@ -66,6 +67,9 @@ export const SETTINGS_KEYS = [
   "autoSupersede",
   "autoSinkTodosOnEnd",
   "autoWebCompaction",
+  "ledgerEnabled",
+  "ledgerCacheDiscount",
+  "jitEnabled",
   "trustedHosts",
 ];
 
@@ -83,10 +87,11 @@ export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
     autoCapturePreferences: z.boolean().default(defaults.autoCapturePreferences).description("用户纠正/偏好学习（零 LLM）：检测用户消息里的显式 prefer/avoid/switch-to 句式，自动沉淀为 preference 记忆并置顶 [ENGRAM] 索引（correx/PAHF 式偏好提取；关掉=只靠手动 engram_store）"),
-    boundaryPrune: z.boolean().default(defaults.boundaryPrune).description("ResultPack L1（BoundaryPrune 边界剪枝）：在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 的确定性 toolResultPruner 剪掉超阈值旧工具结果（SoL-Pi Online Context Compact；默认关）"),
+    boundaryPrune: z.boolean().default(defaults.boundaryPrune).description("ResultPack L1（BoundaryPrune 边界剪枝）：在 todo 完成推进 / goal 终态这些子任务边界，主动调用 DSH 的确定性 toolResultPruner 剪掉超阈值旧工具结果（SoL-Pi Online Context Compact；默认开，false=关）"),
+    boundaryPruneAdaptive: z.boolean().default(defaults.boundaryPruneAdaptive).description("剪枝自适应（账本否决）：当 Context Ledger 显示该 workspace 在真实剪枝后净收益为负（≥3 次剪枝）时自动停止继续剪；证据只能关、不会自行开；关掉=只受偿还门约束"),
     boundaryPruneThresholdChars: z.natural().default(0).description("边界剪枝阈值覆盖（字符）：宿主 pruner 固定 8192；设更低（如 2048）可更早开剪——L0 仿真显示 T2048 净收益最高（+61.6Mc），前提是 L2 归档已开启可找回被剪中段；0=用宿主 8192"),
     boundaryPruneIdleCadence: z.natural().default(0).description("空闲步数边界（请求计数）：最多每 N 个请求触发一次剪枝，覆盖无 todo/goal 的会话（约 62% 会话永不触发事件边界）；仍受偿还门约束；0=仅事件边界"),
-    resultPack: z.boolean().default(defaults.resultPack).description("ResultPack L2（结果归档召回）：BoundaryPrune 剪掉的中段脱敏归档到本地，剪枝节点尾部追加 handle，模型可用 result_recall(callId) 按页召回（完整 ObservationPack；需与 boundaryPrune 一起开，L2 本身默认关）"),
+    resultPack: z.boolean().default(defaults.resultPack).description("ResultPack L2（结果归档召回）：BoundaryPrune 剪掉的中段脱敏归档到本地，剪枝节点尾部追加 handle，模型可用 result_recall(callId) 按页召回（完整 ObservationPack；默认开，保证默认剪枝无损；需与 boundaryPrune 一起开）"),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
     recallScope: z.union(["workspace", "global"]).default(defaults.recallScope ?? "workspace").description("召回范围：workspace=严格按当前工作区隔离（默认、token 纪律）；global=本工作区命中弱/空时，从其它工作区池按 recency/origin 加权召回并标 [W:<workspace>] 来源。开启会打破跨工作区隔离，请按需选用"),
     autoRecallOnStart: z.boolean().default(defaults.autoRecallOnStart).description("新会话开始时，宿主按首条消息对工作区做确定性召回，把命中记忆直接注入 [RECALL] 块（无需模型自己想起调 engram_recall；关掉=回到纯拉取）"),
@@ -101,12 +106,15 @@ export function makeSettingsSchema(defaults) {
     maxMemoriesPerWorkspace: z.natural().max(10000).default(defaults.maxMemoriesPerWorkspace),
     gcEnabled: z.boolean().default(defaults.gcEnabled),
     gcStableRetentionDays: z.natural().max(3650).default(defaults.gcStableRetentionDays),
-    gcReplacesCompaction: z.boolean().default(defaults.gcReplacesCompaction),
+    gcReplacesCompaction: z.boolean().default(defaults.gcReplacesCompaction).description("Context GC 接管 DSH 自动 compact（指针摘要替代有损 LLM 摘要）；默认关=保留宿主 summarizer。改写宿主预设是最高维护风险，需显式开启"),
     gcNarrative: z.boolean().default(defaults.gcNarrative),
     verifyArtifact: z.boolean().default(defaults.verifyArtifact).description("ESR 闭环时校验 artifact 路径真实存在"),
     autoSupersede: z.boolean().default(defaults.autoSupersede).description("实体锚定 + 替换式更新（改用/不再…）自动把旧记忆标为 superseded（默认关）"),
     autoSinkTodosOnEnd: z.boolean().default(defaults.autoSinkTodosOnEnd).description("会话结束时把仍 pending 的 todo 自动沉淀为 ESR draft 任务（去重、受容量上限约束；关掉=会话结束即弃）"),
-    autoWebCompaction: z.boolean().default(defaults.autoWebCompaction).description("web 面启动时把全部 stock 布局的 agent 预设（shipped + 用户根）的 compaction 组自动换成 dsh-engram/compaction（带备份、幂等、不碰自定义/无 compaction 预设；关掉=不再自动接管，已接管的预设保持 Context GC、需 npm run web-compaction:revert 还原，host 面不受影响）"),
+    autoWebCompaction: z.boolean().default(defaults.autoWebCompaction).description("web 面启动时把全部 stock 布局的 agent 预设（shipped + 用户根）的 compaction 组自动换成 dsh-engram/compaction（带备份、幂等、不碰自定义/无 compaction 预设）。默认关（opt-in）：不主动改写任何预设；已接管的预设保持 Context GC、需 npm run web-compaction:revert 还原，host 面不受影响"),
+    ledgerEnabled: z.boolean().default(defaults.ledgerEnabled).description("上下文账本：按会话统计注入成本、剪枝/压缩节省与前缀重写罚金，输出净 token（/stats.ledger 与概览）；关掉=不记账、零写入"),
+    ledgerCacheDiscount: z.number().min(0).max(1).default(defaults.ledgerCacheDiscount).description("账本缓存折价（0..1）：被剪枝前缀的重写按 (1−该系数) 计罚金；0.1 = 缓存命中只付 10%，重写付 90%（L0 保守假设）"),
+    jitEnabled: z.boolean().default(defaults.jitEnabled).description("JIT 推送：错误复发 / 文件焦点 / goal 完成时把已有记忆压成一行推进上下文（append-only、每会话最多 3 行、无命中沉默；每次推送按前缀重写计入账本）"),
     // Security knob, not rendered in the card: hostnames allowed past the
     // loopback fence for /api/dsh-engram (operator-authorized tunnel hosts).
     trustedHosts: z.array(z.string()).default([]),

package/lib/usage.js

@@ -7,8 +7,8 @@
  * on every engram/esr tool call, and a separate session-log scan that counted
  * tool calls (to include the built-in `todo` tool). Both are now ONE module:
  * both /stats and /toolstats answer from the canonical log stream
- * `~/.dsh/sessions/<bucket>/<sid>/session.jsonl.zstd`, decompressed on demand
- * with a short TTL cache. No tool call pays a write anymore (pure GUI-side
+ * `~/.dsh/sessions/<bucket>/<sid>/session[.v<N>].jsonl.zstd`, decompressed on
+ * demand with a short TTL cache. No tool call pays a write anymore (pure GUI-side
  * observability), and the log stream is the single source of truth.
  *
  * Zero external dependency: Node >=22.19 provides the zstd codec in
@@ -44,6 +44,49 @@ export function sessionsRoot() {
   return path.join(os.homedir(), ".dsh", "sessions");
 }
 
+/**
+ * Session log file names: current DSH stamps the session format version into
+ * the name (`session.v3.jsonl.zstd` on 0.1.x, `session.v4.jsonl.zstd` on 0.2);
+ * older releases used the unversioned `session.jsonl.zstd` (issue #8).
+ */
+const SESSION_LOG_RE = /^session(?:\.v\d+)?\.jsonl\.zstd$/;
+
+/**
+ * Resolve the log file inside one session directory.
+ *
+ * A directory normally holds exactly one log, but a session migrated across
+ * format versions can hold both a v3 and a v4 file (and a legacy unversioned
+ * one). The newest-mtime match wins — that is the file the host is currently
+ * appending to. When nothing matches, the historical unversioned name is
+ * returned so callers keep their existing ENOENT handling (`statSync` throws →
+ * session skipped) instead of silently scanning the wrong corpus.
+ */
+export function sessionLogFile(dir) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return path.join(dir, "session.jsonl.zstd");
+  }
+  let best = null;
+  let bestMtime = -1;
+  for (const name of names) {
+    if (!SESSION_LOG_RE.test(name)) continue;
+    let st;
+    try {
+      st = fs.statSync(path.join(dir, name));
+    } catch {
+      continue; // unreadable entry: ignore
+    }
+    if (!st.isFile()) continue;
+    if (st.mtimeMs > bestMtime) {
+      bestMtime = st.mtimeMs;
+      best = name;
+    }
+  }
+  return path.join(dir, best ?? "session.jsonl.zstd");
+}
+
 /** Byte range of one structurally complete zstd frame in a concatenated stream. */
 function frameRanges(buffer) {
   const frames = [];
@@ -244,7 +287,7 @@ export function collectToolCounts({ root = sessionsRoot(), days = 14, now = Date
   for (const bucket of buckets) {
     const bdir = path.join(root, bucket);
     for (const sid of listDirOrEmpty(bdir)) {
-      const file = path.join(bdir, sid, "session.jsonl.zstd");
+      const file = sessionLogFile(path.join(bdir, sid));
       let st;
       try {
         st = fs.statSync(file);
@@ -330,7 +373,7 @@ export function collectUsageStats({ root = sessionsRoot(), days = 14, now = Date
   const buckets = listDirOrEmpty(root).filter((b) => b.startsWith("--"));
   for (const bucket of buckets) {
     for (const sid of listDirOrEmpty(path.join(root, bucket))) {
-      const file = path.join(root, bucket, sid, "session.jsonl.zstd");
+      const file = sessionLogFile(path.join(root, bucket, sid));
       let st;
       try {
         st = fs.statSync(file);

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.5.0",
+  "version": "0.6.0",
   "packageManager": "pnpm@11.22.0",
   "license": "MIT",
   "repository": {