dsh-engram 0.3.4 → 0.3.6

package/lib/tools.js

@@ -1,24 +1,26 @@
 /**
  * dsh-engram: model-facing tools.
  *
- * Eight small, tight-schema tools (deliberately fewer than the market's 8-12 —
- * tool schemas cost tokens in every request):
+ * Fourteen small, tight-schema tools (schemas cost tokens in every request):
  *   engram_store / engram_recall / engram_detail    — the engram memory surface
- *   esr_task / esr_node / esr_close / esr_link — the ESR-lite evidence surface
- *   esr_ready / esr_status                    — the pull surface (live state + hints)
- *   esr_gc                                    — pi-esr memory garbage collection
+ *   esr_task / esr_close / esr_link / esr_dep / esr_claim / esr_unclaim /
+ *   esr_node / esr_ready / esr_status / esr_gc / esr_model — ESR-lite surface
  *
  * Every call is recorded into the per-(workspace, day) usage rollup so the
  * GUI can report real ESR-proactivity and recall rates (see usage.js).
  *
  * All reads are deterministic local scans; `engram_recall` may additionally
- * fall back to `ctx.sessionQuery` FTS over past sessions when mounted.
+ * fall back to `ctx.sessionQuery` FTS over past sessions when mounted, and to
+ * a bounded CJK substring scan over the workspace's own session logs when the
+ * query is Chinese (see session-cjk.js).
  */
 
 import { z } from "zod";
+import { basename } from "node:path";
 import { EngramError, hasCode } from "./store.js";
 import { buildEsrStatusView } from "./index-block.js";
 import { truncate, shortId, slugId, fmtDate, escapeLt, workspaceKey as wk, uuid } from "./util.js";
+import { hasCJK, searchSessionsCJK } from "./session-cjk.js";
 
 const KINDS = [
   "decision",
@@ -73,16 +75,27 @@ async function requireDomain(service) {
   }
 }
 
-function memoryLine(m, verbosity = "short") {
+function memoryLine(m, verbosity = "short", rel, homeWs) {
+  // origin marker for cross-workspace hits: [W:<ws>] tells the model the memory
+  // came from a different workspace pool (issue #5).
+  const origin = homeWs !== void 0 && homeWs !== null && (m._origin ?? m.workspace) !== homeWs
+    ? ` [W:${basename(m._origin ?? m.workspace) || String(m._origin ?? m.workspace)}]`
+    : "";
   const tags = m.entity !== null ? ` · entity:${m.entity}` : "";
+  const relTail = rel
+    ? `${rel.supersededBy.has(m.id) ? ` · superseded by ${rel.supersededBy.get(m.id).id.slice(0, 8)}` : ""}${rel.contradictedBy.has(m.id) ? ` · contradicted by ${rel.contradictedBy.get(m.id).map((c) => c.id.slice(0, 8)).join(",")}` : ""}`
+    : "";
   if (verbosity === "full") {
     const access = m.lastAccessAt == null ? "never-accessed" : `lastAccess ${fmtDate(m.lastAccessAt)}`;
     const pathLine = m.filePath ? ` · path ${m.filePath}` : "";
-    return [`# ${m.id} [${m.kind}]`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}`, ""].join("\n");
+    const relLine = relTail.length > 0 ? relTail.trim() : "";
+    const sourceLine = m.source ? ` · source ${m.source}` : "";
+    const condLine = m.conditions ? ` · conditions ${m.conditions}` : "";
+    return [`# ${m.id} [${m.kind}]${origin}`, escapeLt(m.text), `tags: ${(m.tags ?? []).join(", ")}${tags}`, `signal ${m.signal} · hits ${m.hits ?? 0} · ${fmtDate(m.createdAt)} · session ${m.sessionId}#${m.seq} · ${access}${pathLine}${relLine ? ` · ${relLine}` : ""}${sourceLine}${condLine}`, ""].join("\n");
   }
   const date = fmtDate(m.createdAt ?? m.updatedAt);
   const path = m.filePath ? ` · ${truncate(m.filePath, 48)}` : "";
-  return `- ${m.id.slice(0, 8)} [${m.kind}] ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}`;
+  return `- ${m.id.slice(0, 8)} [${m.kind}]${origin} ${date} ${escapeLt(truncate(m.text, 200))}${tags}${m.hits > 0 ? ` · ×${m.hits}` : ""}${path}${relTail}`;
 }
 
 /** Stable kind display order for grouped recall output (matches MEMORY_KINDS). */
@@ -95,7 +108,7 @@ const MEMORY_KIND_ORDER = ["decision", "error", "procedure", "fact", "insight",
  * Within a group the original (relevance) order is preserved; unknown kinds
  * (future-proof) trail the fixed order. Pure, deterministic.
  */
-function groupKindLines(items) {
+function groupKindLines(items, rel, homeWs) {
   const buckets = new Map();
   for (const m of items) {
     const kind = typeof m.kind === "string" && m.kind.length > 0 ? m.kind : "unknown";
@@ -105,7 +118,7 @@ function groupKindLines(items) {
   const lines = [];
   const emit = (kind, group) => {
     lines.push(`## ${kind} (${group.length})`);
-    for (const m of group) lines.push(memoryLine(m));
+    for (const m of group) lines.push(memoryLine(m, "short", rel, homeWs));
   };
   for (const kind of MEMORY_KIND_ORDER) if (buckets.has(kind)) emit(kind, buckets.get(kind));
   for (const [kind, group] of buckets) if (!MEMORY_KIND_ORDER.includes(kind)) emit(kind, group);
@@ -122,19 +135,23 @@ export function registerTools(ctx, service) {
       // ── engram_store ────────────────────────────────────────────────────
       registerTool({
         name: "engram_store",
-        description: "Store one memory: kind=(decision|error|procedure|fact|insight|handoff|task), text, optional entity anchor. Exact-duplicate text refreshes instead of adding; auto-capture already handles git/file/error events — use this for anything it misses.",
+        description: "Store one memory (kind, text, optional entity anchor + supersedes/contradicts id). Duplicate text refreshes; auto-capture covers git/file/error — use this for anything missed.",
         parameters: {
           type: "object",
           properties: {
             text: { type: "string", description: "Compact, information-dense memory text (required)" },
             ...p,
             file_path: { type: "string", description: "Optional absolute path this memory anchors to (e.g. the failing file)" },
+            supersedes: { type: "string", description: "Optional memory id this new statement replaces (old row stays, demoted in recall)" },
+            contradicts: { type: "string", description: "Optional memory id this new statement directly contradicts (both stay, flagged)" },
+            source: { type: "string", description: "Optional provenance source class: manual | session | report | upstream | handoff" },
+            conditions: { type: "string", description: "Optional trigger/condition under which this memory should be recalled" },
           },
           required: ["text"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional() }), raw, "engram_store");
+          const args = parse(z.object({ text: z.string().min(1).max(2000), kind: z.enum(KINDS).optional(), tags: z.array(z.string()).optional(), entity: z.string().optional(), file_path: z.string().optional(), supersedes: z.string().optional(), contradicts: z.string().optional(), source: z.string().optional(), conditions: z.string().optional() }), raw, "engram_store");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           await domain.expireSweep(caller.cwd);
@@ -146,6 +163,10 @@ export function registerTools(ctx, service) {
               tags: args.tags ?? [],
               entity: args.entity ?? null,
               filePath: args.file_path ?? null,
+              supersedes: args.supersedes ?? null,
+              contradicts: args.contradicts ?? null,
+              source: args.source ?? null,
+              conditions: args.conditions ?? null,
               sessionId: caller.sessionId,
               seq: caller.seq,
               signal: 0.6,
@@ -161,22 +182,23 @@ export function registerTools(ctx, service) {
       // ── engram_recall ───────────────────────────────────────────────────
       registerTool({
         name: "engram_recall",
-        description: "Deterministic recall of this workspace's memories (BM25: exact tag first, recency ties). Literal, not semantic — query in the memory's likely language. query=filter, entity=timeline, search_sessions=true adds past-session FTS. limit/max_per_session/group_by_kind tune output.",
+        description: "Deterministic recall (BM25: exact tag first, recency ties). Literal, not semantic. query=filter, entity=timeline, search_sessions=true adds past-session FTS; limit/max_per_session/group_by_kind tune.",
         parameters: {
           type: "object",
           properties: {
             query: { type: "string", description: "Words to match against memory text and tags" },
             entity: { type: "string", description: "Return that entity's memories chronologically" },
             limit: { type: "integer", minimum: 1, maximum: 50, description: "Max memories (default 12)" },
-            max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Session-diversified cap: max memories kept per sessionId (default config.maxRecallPerSession=3; >1 sessions get to share the list)" },
+            max_per_session: { type: "integer", minimum: 1, maximum: 10, description: "Max memories kept per sessionId (default 3; sessions share the cap)" },
             group_by_kind: { type: "boolean", description: "Group recall hits by kind into sections (default true); false = one flat list" },
             search_sessions: { type: "boolean", description: "Also FTS search past sessions (requires the session-query index)" },
+            scope: { type: "string", enum: ["workspace", "global", "auto"], description: "Recall scope override: workspace=strict current-workspace only (default); global=include other workspaces' pools when the local pool is weak/empty (marks [W:<ws>] origin); auto=follow the recallScope config (recommended)" },
           },
         },
         output: TEXT_OUTPUT,
         timeoutMs: 30000,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ query: z.string().optional(), entity: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), max_per_session: z.number().int().min(1).max(10).optional(), group_by_kind: z.boolean().optional(), search_sessions: z.boolean().optional() }), raw, "engram_recall");
+          const args = parse(z.object({ query: z.string().optional(), entity: z.string().optional(), limit: z.number().int().min(1).max(50).optional(), max_per_session: z.number().int().min(1).max(10).optional(), group_by_kind: z.boolean().optional(), search_sessions: z.boolean().optional(), scope: z.enum(["workspace", "global", "auto"]).optional() }), raw, "engram_recall");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           let lines = [];
@@ -185,6 +207,11 @@ export function registerTools(ctx, service) {
           // reuses DSH's own cross-session index (ctx.sessionQuery) instead of
           // a self-built index — this keeps proactive coverage without new infra.
           let zeroHits = false;
+          // recallScope resolution: explicit scope wins; else the config knob;
+          // default "workspace" preserves the strict per-workspace isolation.
+          const cfgScope = service.config.recallScope ?? "workspace";
+          const effectiveScope = args.scope === void 0 ? cfgScope : args.scope === "auto" ? cfgScope : args.scope;
+          const globalEnabled = effectiveScope === "global";
           if (args.entity !== void 0 && args.entity.trim().length > 0) {
             items = domain.timeline(caller.cwd, args.entity, args.limit ?? 30);
             if (items.length === 0) zeroHits = true;
@@ -193,10 +220,25 @@ export function registerTools(ctx, service) {
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else if (args.query !== void 0) {
             const maxPerSession = args.max_per_session ?? service.config.maxRecallPerSession ?? 3;
-            items = domain.recall(caller.cwd, args.query, args.limit ?? 12, { maxPerSession });
+            const limit = args.limit ?? 12;
+            items = domain.recall(caller.cwd, args.query, limit, { maxPerSession });
+            let cross = false;
+            // Opt-in global fallback (issue #5): only when the local pool is
+            // weak/no-hit AND the user enabled recallScope=global or passed
+            // scope=global. Cross-workspace hits carry a [W:<ws>] origin marker.
+            if (globalEnabled && items.length === 0) {
+              const extra = domain.recallGlobal(args.query, limit, { maxPerSession, excludeWorkspace: caller.cwd });
+              if (extra.length > 0) {
+                items = extra;
+                cross = true;
+              }
+            }
             if (items.length === 0) zeroHits = true;
-            lines.push(zeroHits ? `no active memories match ${JSON.stringify(args.query)} in this workspace` : `# recall: ${JSON.stringify(args.query)} (${items.length}) · ≤${maxPerSession}/session`);
-            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m)) : groupKindLines(items)));
+            const scopeTag = cross ? " · cross-workspace" : "";
+            lines.push(zeroHits ? `no active memories match ${JSON.stringify(args.query)} in this workspace` + (globalEnabled ? " (global fallback also empty)" : "") : `# recall: ${JSON.stringify(args.query)} (${items.length}) · ≤${maxPerSession}/session${scopeTag}`);
+            const rel = domain.memoryRelations(caller.cwd);
+            const homeWs = caller.cwd;
+            lines.push(...(args.group_by_kind === false ? items.map((m) => memoryLine(m, "short", rel, homeWs)) : groupKindLines(items, rel, homeWs)));
             await Promise.all(items.map((m) => domain.touchMemory(caller.cwd, m.id).catch(() => null)));
           } else {
             items = domain.listMemories(caller.cwd, args.limit ?? 12);
@@ -217,9 +259,23 @@ export function registerTools(ctx, service) {
           }
           const wantSessions = args.search_sessions === true || (zeroHits && service.config.sessionSearch !== false);
           if (wantSessions) {
-            const extra = await searchSessions(service, caller, args.query ?? args.entity ?? "", exec.signal);
-            if (extra.length > 0) lines.push("", "# past sessions (FTS fallback)", ...extra);
-            else if (zeroHits && lines.length === 1) lines[0] += " (no past-session hits either)";
+            const q = args.query ?? args.entity ?? "";
+            const extra = await searchSessions(service, caller, q, exec.signal, globalEnabled);
+            if (extra.length > 0) {
+              lines.push("", "# past sessions (FTS fallback)", ...extra);
+            } else if (hasCJK(q)) {
+              // The host FTS index is tokenizer-blind to Chinese (unicode61
+              // keeps CJK runs as single tokens), so supplement it with a
+              // bounded substring scan over this workspace's own sessions.
+              const cjk = searchSessionsCJK({ cwd: caller.cwd, query: q });
+              if (cjk.length > 0) {
+                lines.push("", "# past sessions (CJK substring scan)", ...cjk.map((h, i) => `${i + 1}. session ${h.sessionId} · ${truncate(h.snippet, 160)}`));
+              } else if (zeroHits && lines.length === 1) {
+                lines[0] += " (no past-session hits either)";
+              }
+            } else if (zeroHits && lines.length === 1) {
+              lines[0] += " (no past-session hits either)";
+            }
           }
           return lines.join("\n");
         },
@@ -228,7 +284,7 @@ export function registerTools(ctx, service) {
       // ── engram_detail ───────────────────────────────────────────────────
       registerTool({
         name: "engram_detail",
-        description: "Full record of one memory id (from engram_recall): text, tags, entity, signal, hits, provenance session#seq.",
+        description: "Full record of one memory id: text, tags, entity, signal, hits, session#seq provenance.",
         parameters: {
           type: "object",
           properties: {
@@ -245,21 +301,21 @@ export function registerTools(ctx, service) {
           const m = domain.getMemory(caller.cwd, id);
           if (m === void 0) throw new EngramError("ENGRAM_NOT_FOUND", `no active memory "${args.id}" in this workspace`);
           await domain.touchMemory(caller.cwd, m.id).catch(() => null);
-          return memoryLine(m, "full");
+          return memoryLine(m, "full", domain.memoryRelations(caller.cwd));
         },
       }),
 
       // ── esr_task ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_task",
-        description: "Create/update an engineering task (draft→active). A task is only 'done' with evidence — finish via esr_close (artifact + evaluation + memory_ref). Set id to update an existing task. Pass entity= to auto-create the node and link the task onto it (one call instead of esr_node+esr_link).",
+        description: "Create/update an engineering task (draft→active). Done only with evidence — esr_close (artifact+evaluation+memory_ref). id=update; entity=auto-create node + relates_to link.",
         parameters: {
           type: "object",
           properties: {
             name: { type: "string", description: "Task name (required on create)" },
             description: { type: "string", description: "What must be produced / satisfied" },
             id: { type: "string", description: "Existing task id to update" },
-            entity: { type: "string", description: "Optional domain object to hang this task on — auto-creates ent_<slug> node and links task --relates_to--> it" },
+            entity: { type: "string", description: "Domain object to hang this task on — auto-creates ent_<slug> node + task --relates_to--> edge" },
           },
           required: ["name"],
         },
@@ -307,12 +363,12 @@ export function registerTools(ctx, service) {
       // ── esr_close ─────────────────────────────────────────────────────
       registerTool({
         name: "esr_close",
-        description: "Close a task via the ESR evidence protocol: requires artifact (path/url), evaluation (how verified) and memory_ref (memory ids) — missing gates keep it active; force:true skips the on-disk artifact check. Auto-stores a closing memory.",
+        description: "Close a task via the ESR evidence protocol: artifact (path/url) + evaluation + memory_ref — missing gates keep it active; force:true skips the disk check. Stores a closing memory.",
         parameters: {
           type: "object",
           properties: {
             task_id: { type: "string", description: "Task id from [ESR] or esr_task" },
-            artifact: { type: "string", description: "Produced artifact (path/url). Paths are resolved against the workspace and must exist on disk unless force:true" },
+            artifact: { type: "string", description: "Produced artifact path/url. Resolved against workspace; must exist on disk unless force:true" },
             evaluation: { type: "string", description: "Verification evidence (test/review/benchmark)" },
             memory_refs: { type: "array", items: { type: "string" }, description: "Memory ids that record the decisions made" },
             force: { type: "boolean", description: "Skip the on-disk artifact existence check (gates are still required)" },
@@ -369,7 +425,7 @@ ${hint}` : ""}`;
       // ── esr_link ──────────────────────────────────────────────────────
       registerTool({
         name: "esr_link",
-        description: "Add a typed relation between two entities (depends_on/implements/refines/contradicts…). Feeds entity queries and the workspace link count.",
+        description: "Add a typed relation between entities (depends_on/implements/refines/contradicts…). Feeds entity queries + link count.",
         parameters: {
           type: "object",
           properties: {
@@ -403,7 +459,7 @@ ${hint}` : ""}`;
 
       registerTool({
         name: "esr_dep",
-        description: "Add a dependency edge between tasks: blocks (waits until dep closes), parent-of (child), relates-to (no blocking). Refuses self-deps and cycles.",
+        description: "Add a dependency edge between tasks: blocks (until dep closes), parent-of (child), relates-to (no blocking). Refuses self-deps/cycles.",
         parameters: {
           type: "object",
           properties: {
@@ -444,7 +500,7 @@ ${hint}` : ""}`;
       // ── esr_claim / esr_unclaim ─────────────────────────────────────
       registerTool({
         name: "esr_claim",
-        description: "Atomically claim a task (assignee+claimedAt, draft→active). Refuses when another agent holds it unless force:true. Find work with esr_ready.",
+        description: "Atomically claim a task (draft→active, assignee+claimedAt). Refuses when another agent holds it unless force:true. Find work with esr_ready.",
         parameters: {
           type: "object",
           properties: {
@@ -467,7 +523,7 @@ ${hint}` : ""}`;
       }),
       registerTool({
         name: "esr_unclaim",
-        description: "Release a claimed task's assignee back to null. Non-holder needs force:true. Inverse of esr_claim.",
+        description: "Release a claimed task's assignee to null. Non-holder needs force:true. Inverse of esr_claim.",
         parameters: {
           type: "object",
           properties: {
@@ -516,12 +572,12 @@ ${hint}` : ""}`;
       registerTool({
         name: "esr_status",
         description:
-          "Pull the live ESR state (deterministic snapshot + revision) plus decision-point hints (promote / root-cause / close / stale / escalate). Pass since_revision to skip unchanged state — returns a short response when nothing changed. The [ESR] block in the prompt is a session-start snapshot that never auto-refreshes; call this for the current truth.",
+          "Live ESR state (deterministic snapshot + revision) + decision-point hints (promote/root-cause/close/stale/escalate). Pass since_revision to skip unchanged state (short response). Prompt [ESR] is a frozen session-start snapshot — call this for current truth.",
         parameters: {
           type: "object",
           properties: {
             workspace: { type: "string", description: "Override the workspace key (default: current session cwd)" },
-            since_revision: { type: "string", description: "Last-seen ESR revision (from a previous esr_status response); unchanged state returns a short response" },
+            since_revision: { type: "string", description: "Last-seen ESR revision; unchanged state returns a short response" },
           },
         },
         output: TEXT_OUTPUT,
@@ -542,7 +598,7 @@ ${hint}` : ""}`;
       // ── esr_node ─────────────────────────────────────
       registerTool({
         name: "esr_node",
-        description: "Create/update an entity node — stable symbol for a recurring thing (package/service/doc/repo/person/bug/concept). Nodes anchor esr_link relations and memory entity. Same name updates; id = ent_<slug>.",
+        description: "Create/update an entity node — stable symbol for a recurring thing (package/service/doc/repo/person…). Anchors esr_link + memory entity; same name updates; id=ent_<slug>.",
         parameters: {
           type: "object",
           properties: {
@@ -584,7 +640,7 @@ ${hint}` : ""}`;
       // ── esr_gc ────────────────────────────────────────────────────────
       registerTool({
         name: "esr_gc",
-        description: "Run memory GC: archives TTL-expired, over-cap low-retention memories, stable tasks past retention, dangling links. Working set protected; archive-only (nothing hard-deleted). dry_run:true previews.",
+        description: "Run memory GC: archives TTL-expired, over-cap low-retention memories, stable tasks past retention, dangling links. Working set protected; archive-only, never hard-deletes. dry_run previews.",
         parameters: {
           type: "object",
           properties: {
@@ -605,7 +661,7 @@ ${hint}` : ""}`;
       // ── esr_model ─────────────────────────────────────────────────────
       registerTool({
         name: "esr_model",
-        description: "Precomputed mental model of the workspace (task counts, entity graph, top evidence-grounded beliefs, risks). Zero LLM. mode=brief → ~50-token one-liner; max_chars trims. Read before scattering recall.",
+        description: "Precomputed mental model (task counts, entity graph, top evidence-grounded beliefs, risks). Zero LLM. mode=brief → one-liner; max_chars trims. Read before scattering recall.",
         parameters: {
           type: "object",
           properties: {
@@ -726,15 +782,17 @@ function collectNeighborhood(domain, workspace, items) {
   return lines;
 }
 
-/** FTS over past sessions via ctx.sessionQuery (mounted by the web profile). */
-async function searchSessions(service, caller, query, signal) {
+/** FTS over past sessions via ctx.sessionQuery (mounted by the web profile).
+ *  `global` (recallScope=global) drops the cwd filter so past-session hits from
+ *  other workspaces are reachable too — matching the cross-workspace scope. */
+async function searchSessions(service, caller, query, signal, global) {
   const sq = service.sessionQuery;
   if (sq === void 0 || query.trim().length === 0) return [];
   try {
     const { items = [] } = await sq.searchSessions(
       {
         query: query.trim(),
-        sessionFilters: [{ kind: "cwd", values: [caller.cwd] }],
+        sessionFilters: global ? [] : [{ kind: "cwd", values: [caller.cwd] }],
         limit: 5,
       },
       signal !== void 0 ? { signal } : undefined,

package/lib/trigger.js

@@ -97,6 +97,8 @@ export function pendingTodos(args) {
 export function makeTriggerRecorder(config = {}) {
   const minTodosForPromote = config.minTodosForPromote ?? 2;
   const todoPromoteRatio = config.todoPromoteRatio ?? 1;
+  // Injectable clock (deterministic unit tests): default to the wall clock.
+  const now = typeof config.now === "function" ? config.now : Date.now;
   /** workspace -> Map<day, {mem, esr}> (live balance, replaces dead usage table). */
   const usage = new Map();
   /** workspace -> { sessionId, count, names, updatedAt } (pending-todo plan). */
@@ -130,7 +132,7 @@ export function makeTriggerRecorder(config = {}) {
     cur[key] += 1;
     buckets.set(day, cur);
     if (buckets.size > BALANCE_DAYS + 2) {
-      const oldest = dayKey(Date.now() - BALANCE_DAYS * DAY_MS);
+      const oldest = dayKey(now() - BALANCE_DAYS * DAY_MS);
       for (const d of [...buckets.keys()]) if (d < oldest) buckets.delete(d);
     }
     if (usage.size > WORKSPACE_CAP) {
@@ -160,7 +162,7 @@ export function makeTriggerRecorder(config = {}) {
       record(name, workspace);
       // P4 conversion: an esr_* call inside the window converts this
       // workspace's most recent pending hint.
-      if (ESR_TOOLS.includes(name)) attributeConversion(workspace, Date.now());
+      if (ESR_TOOLS.includes(name)) attributeConversion(workspace, now());
       if (name !== "todo_write") return;
       // Snapshot this session's pending plan. When a plan that had pending
       // todos transitioned to a fully-completed list, that is a natural
@@ -168,7 +170,7 @@ export function makeTriggerRecorder(config = {}) {
       const names = pendingTodos(exec?.arguments);
       const prev = todos.get(workspace);
       const prevCount = prev !== void 0 && prev.sessionId === sessionId ? prev.count : -1;
-      todos.set(workspace, { sessionId, count: names.length, names, updatedAt: Date.now() });
+      todos.set(workspace, { sessionId, count: names.length, names, updatedAt: now() });
       if (prevCount > 0 && names.length === 0) {
         workDone.add(`${workspace}::${sessionId}`);
       }
@@ -188,7 +190,7 @@ export function makeTriggerRecorder(config = {}) {
   function recentBalance(workspace) {
     const buckets = usage.get(workspace);
     if (buckets === void 0) return { memCalls: 0, esrCalls: 0, days: 0 };
-    const oldest = dayKey(Date.now() - BALANCE_DAYS * DAY_MS);
+    const oldest = dayKey(now() - BALANCE_DAYS * DAY_MS);
     let memCalls = 0;
     let esrCalls = 0;
     let days = 0;
@@ -225,7 +227,7 @@ export function makeTriggerRecorder(config = {}) {
 
   /** Drop hints past the conversion window (or when already attributed). */
   function prunePending() {
-    const cutoff = Date.now() - CONVERSION_WINDOW_MS;
+    const cutoff = now() - CONVERSION_WINDOW_MS;
     for (let i = pending.length - 1; i >= 0; i--) {
       if (pending[i].shownAt < cutoff) pending.splice(i, 1);
     }
@@ -243,7 +245,7 @@ export function makeTriggerRecorder(config = {}) {
     if (hintSeen.has(key)) return;
     hintSeen.add(key);
     bumpCount(shownCounts, workspace, kind, 1);
-    pending.push({ kind, ws: workspace, session: sessionId, shownAt: Date.now() });
+    pending.push({ kind, ws: workspace, session: sessionId, shownAt: now() });
     prunePending();
   }
 
@@ -368,8 +370,8 @@ export function makeTriggerRecorder(config = {}) {
       const key = `${workspace}::${sessionId}::${t.id}`;
       if (staleSeen.has(key)) continue;
       staleSeen.add(key);
-      const at = t.updatedAt ?? t.createdAt ?? Date.now();
-      const days = Math.max(1, Math.round((Date.now() - at) / DAY_MS));
+      const at = t.updatedAt ?? t.createdAt ?? now();
+      const days = Math.max(1, Math.round((now() - at) / DAY_MS));
       return `stale: ${t.id.slice(0, 6)} · ${truncate(t.name, 40)} — no update ${days}d, esr_close with evidence or drop the intent ${HINT_TAGS.stale}`;
     }
     return "";

package/lib/usage.js

@@ -11,13 +11,19 @@
  * 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-dependency: the host already carries the `zstd` CLI.
+ * Zero external dependency: Node >=22.19 provides the zstd codec in
+ * `node:zlib`. Session logs are concatenated zstd frames (each append is an
+ * independent frame), so we scan frame boundaries and reuse one decoder
+ * handle across all frames instead of relying on a system `zstd` CLI (which
+ * Windows hosts commonly lack) or the one-shot `zstdDecompressSync`, which
+ * only decodes the FIRST frame of a multi-frame container.
  */
 
-import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { constants as bufferConstants } from "node:buffer";
+import { createZstdDecompress, zstdDecompressSync } from "node:zlib";
 
 import { workspaceKey as wk } from "./util.js";
 
@@ -28,8 +34,6 @@ export function dayKey(now = Date.now()) {
   return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
 }
 
-/** A big session log far exceeds Node's 1MB default exec buffer. */
-const MAX_BYTES = 300 * 1024 * 1024;
 const CACHE_TTL_MS = 60_000;
 const DAY_MS = 86_400_000;
 
@@ -40,13 +44,151 @@ export function sessionsRoot() {
   return path.join(os.homedir(), ".dsh", "sessions");
 }
 
+/** Byte range of one structurally complete zstd frame in a concatenated stream. */
+function frameRanges(buffer) {
+  const frames = [];
+  let offset = 0;
+  while (offset < buffer.length) {
+    const start = offset;
+    if (buffer.length - offset < 4) break;
+    if (buffer.readUInt32LE(offset) !== 0xfd2fb528) break; // ZSTD_MAGIC
+    offset += 4;
+    if (offset === buffer.length) break;
+    const descriptor = buffer.readUInt8(offset);
+    offset += 1;
+    if ((descriptor & 0x18) !== 0) break; // reserved frame-header bit
+    const contentSizeFlag = descriptor >>> 6;
+    const singleSegment = (descriptor & 0x20) !== 0;
+    const checksum = (descriptor & 0x04) !== 0;
+    const dictionaryFlag = descriptor & 0x03;
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag;
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag;
+    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes;
+    if (buffer.length - offset < remainingHeaderBytes) break;
+    offset += remainingHeaderBytes;
+    for (;;) {
+      if (buffer.length - offset < 3) return frames;
+      const blockHeader = buffer.readUIntLE(offset, 3);
+      offset += 3;
+      const lastBlock = (blockHeader & 1) !== 0;
+      const blockType = (blockHeader >>> 1) & 0x03;
+      const blockSize = blockHeader >>> 3;
+      if (blockType === 0x03) return frames; // reserved block type
+      const payloadBytes = blockType === 0x01 ? 1 : blockSize;
+      if (buffer.length - offset < payloadBytes) return frames;
+      offset += payloadBytes;
+      if (lastBlock) break;
+    }
+    if (checksum) {
+      if (buffer.length - offset < 4) return frames;
+      offset += 4;
+    }
+    frames.push({ start, end: offset });
+  }
+  return frames;
+}
+
+/**
+ * Node-private synchronous multi-frame zstd decoder. Node exposes synchronous
+ * decoding only as a one-shot API that stops at the first frame of a
+ * concatenated container (session logs append a fresh frame per batch).
+ * Reusing one stream's `_handle.writeSync` across frames is the same
+ * optimization the harness's own `NodePrivateZstdFrameDecoder` uses; when the
+ * running Node release lacks that private shape we fall back to per-frame
+ * `zstdDecompressSync` (correct, slower — fine for the occasional /stats poll).
+ */
+function createFrameDecoder() {
+  const stream = createZstdDecompress({ chunkSize: 1024 * 1024 });
+  const handle = stream._handle;
+  const errorKey = Reflect.ownKeys(stream).find(
+    (key) => typeof key === "symbol" && key.description === "kError",
+  );
+  if (
+    typeof handle !== "object" || handle === null ||
+    typeof handle?.writeSync !== "function" ||
+    !(stream._writeState instanceof Uint32Array) ||
+    stream._writeState.length < 2 ||
+    typeof stream._defaultFlushFlag !== "number" ||
+    errorKey === void 0 ||
+    stream[errorKey] !== null
+  ) {
+    stream.close();
+    return null;
+  }
+  const output = Buffer.allocUnsafe(1024 * 1024);
+  let decoderError;
+  stream.on("error", (error) => { decoderError ??= error; });
+  return {
+    decode(frame) {
+      if (decoderError !== void 0) throw decoderError;
+      let inputOffset = 0;
+      let inputRemaining = frame.length;
+      let outputBytes = 0;
+      const fullChunks = [];
+      for (;;) {
+        handle.writeSync(
+          stream._defaultFlushFlag,
+          frame,
+          inputOffset,
+          inputRemaining,
+          output,
+          0,
+          output.length,
+        );
+        if (decoderError !== void 0) throw decoderError;
+        const internalError = stream[errorKey];
+        if (internalError !== null) throw internalError;
+        const outputAfter = stream._writeState[0];
+        const inputAfter = stream._writeState[1];
+        const consumed = inputRemaining - inputAfter;
+        const produced = output.length - outputAfter;
+        if (produced > 0) {
+          outputBytes += produced;
+          if (outputBytes > bufferConstants.MAX_LENGTH) throw new Error("frame output too large");
+        }
+        if (outputAfter !== 0) {
+          if (inputAfter !== 0) throw new Error("decoder left trailing input");
+          const finalChunk = output.subarray(0, produced);
+          if (fullChunks.length === 0) return Buffer.from(finalChunk);
+          if (produced > 0) fullChunks.push(Buffer.from(finalChunk));
+          const onlyChunk = fullChunks[0];
+          return fullChunks.length === 1 ? onlyChunk : Buffer.concat(fullChunks, outputBytes);
+        }
+        fullChunks.push(Buffer.from(output));
+        inputOffset += consumed;
+        inputRemaining = inputAfter;
+      }
+    },
+    close() {
+      stream.close();
+    },
+  };
+}
+
 function decodeZstd(file) {
   try {
-    return execFileSync("zstd", ["-dc", file], { maxBuffer: MAX_BYTES }).toString("utf8");
+    const buffer = fs.readFileSync(file);
+    const frames = frameRanges(buffer);
+    if (frames.length === 0) return "";
+    const decoder = createFrameDecoder();
+    if (decoder !== null) {
+      try {
+        let out = "";
+        for (const frame of frames) out += decoder.decode(buffer.subarray(frame.start, frame.end)).toString("utf8");
+        return out;
+      } finally {
+        decoder.close();
+      }
+    }
+    // Public fallback: one zstdDecompressSync per frame (correct, slower).
+    let out = "";
+    for (const frame of frames) out += zstdDecompressSync(buffer.subarray(frame.start, frame.end)).toString("utf8");
+    return out;
   } catch {
     return "";
   }
 }
+export { decodeZstd };
 
 function listDirOrEmpty(dir) {
   try {