dsh-engram 0.3.0 → 0.3.2

package/README.md

@@ -33,6 +33,30 @@ with one goal: **save tokens**.
   `force:true` (or disabling the toggle) skips the disk check, the three gates
   are still mandatory. The tool and the web forms share one gate
   (`store.evidenceGate`), so the two surfaces can never drift.
+  Tasks are never isolated graph nodes: `esr_task(entity=…)` one-call wiring
+  auto-creates the `ent_<slug>` node and hangs the task on it
+  (`task --relates_to--> entity`, idempotent), so a task created with a domain
+  anchor immediately shows a relation; and `esr_dep` writes the dependency edge
+  into both the task's `deps` (blocker logic) and the shared links table, making
+  every task dependency a first-class visible edge in the graph.
+- **Decision-point triggers (P0-A/B + P2 + P3)** — firing where the todo→esr
+  routing decision actually happens and where tasks leak: a `tools/result`
+  watcher snapshots the native `todo_write` plan and, when the session has ≥ 2
+  pending todos that outnumber its active ESR tasks, the [ESR] block appends a
+  concrete `promote:` hint (`esr_task(name="…")`, once per session); recurring
+  failures (error memories with hits ≥ 2) earn a `root-cause:` task candidate;
+  a completed plan (pending → 0) earns a `close:` nudge for evidence-complete
+  tasks; long-unupdated active tasks get a `stale:` nudge; and the task list is
+  ordered READY-first with a `next: esr_close <id>` line, so the model can act
+  top-down. The same subscription feeds an in-memory mem-vs-esr counter that
+  restores `escalationHint` (the per-day `usage` table stopped being written
+  after assessment P3, silently orphaning the old nudge). Pure rules, zero
+  LLM, zero per-render I/O. Every hint line carries a stable `#suggest-*`
+  source tag (traceable in logs) and the same recorder measures hint → esr_*
+  conversion (shown once per session per hint, attributed when an esr tool
+  runs within a 10-minute window) — `GET /api/dsh-engram/triggerstats`
+  reports per-kind shown/converted/rate so you can see which nudge actually
+  moves behaviour.
 - **Memory GC (pi-esr constraints)** — a scheduled, mechanical, archive-only
   sweep: TTL-expired memories are archived, over-cap workspaces evict the
   lowest-value entries, stable tasks past their retention window leave the

package/README.zh.md

@@ -23,6 +23,20 @@
   artifact 按工作区（= 会话 cwd）解析并在磁盘上实存校验，路径不存在则任务保持 ACTIVE、给出原因；
   `force:true`（或关掉该开关）可跳过磁盘校验——三种证据门照样必填。工具与网页表单共享同一个
   证据门（`store.evidenceGate`），口径绝不会漂移。
+  任务不再是孤立节点：`esr_task(entity=…)` 一键挂点——自动建 `ent_<slug>` 节点并挂
+  `task --relates_to--> entity` 边（幂等），挂着领域锚点的任务立刻带关系；
+  `esr_dep` 双写——依赖边同时进 `tasks[].deps`（blocker 逻辑）与 links 表，图谱里每条
+  任务依赖都是一等可见的边。
+- **决策点触发（P0-A/B + P2 + P3）** — 在漏斗最窄处（todo 多、esr 少）与任务泄漏处（建了不关）
+  给模型侧触发：监听 `tools/result` 里的原生 `todo_write`，当会话 pending todo ≥ 2 且多于 active ESR
+  任务时，`[ESR]` 块追加带具体候选的 `promote:` 提示（`esr_task(name="…")`，每会话仅一次）；
+  复发失败（error hits≥2）给 `root-cause:` 任务候选；收工（todo 全部完成）给 `close:` 提示关证据齐的
+  任务；长期无更新的 active 任务给 `stale:` 提示；活动任务按 READY 优先排序并给 `next: esr_close`。
+  并用同一订阅维护进程内 mem-vs-esr 实时计数修复 `escalationHint` 的死数据源（评估 P3 移除了
+  per-call usage 写路径后原 nudge 已静默失效）。纯规则、零 LLM、零每轮 I/O；每条 nudge 带稳定 `#suggest-*` 来源标记，
+  且 recorder 计量「提示曝光 → esr_* 调用」转化（每会话每 kind 记一次曝光，
+  esr 工具 10 分钟窗口内调用即归因），`GET /api/dsh-engram/triggerstats`
+  返回各 kind 的 shown/converted/rate。
 - **记忆 GC（pi-esr 约束）** — 定时、机械、只归档的回收：TTL 过期记忆归档、超容量工作区淘汰低价值条目、
   stable 任务超保留窗离开 `[ESR]` 表面、悬空链接边清理。工作集（active 任务引用 / 任务记忆 / 已入索引命中）
   永不触碰；**不硬删任何东西**——归档条目保留 id、始终可重取。

package/lib/api.js

@@ -442,6 +442,13 @@ export function makeEngramRoutes(service) {
     });
   };
 
+  const triggerstats = (_req, res) => {
+    const q = readQuery(_req);
+    const ws = q.get("workspace");
+    const stats = service.recorder?.conversionStats?.(ws && ws.length > 0 ? ws : void 0) ?? null;
+    writeJson(res, 200, { stats });
+  };
+
   const model = async (req, res) => {
     const domain = await withDomain(res);
     if (domain === void 0) return;
@@ -478,6 +485,7 @@ export function makeEngramRoutes(service) {
     make("GET", "/nodes", entities),
     make("GET", "/stats", stats),
     make("GET", "/toolstats", toolstats),
+    make("GET", "/triggerstats", triggerstats),
     make("GET", "/observations", observations),
     make("GET", "/model", model),
     make("GET", "/preview", preview),

package/lib/index-block.js

@@ -130,16 +130,36 @@ function enforceCharCap(lines, maxChars) {
 }
 
 /**
- * One-line, data-driven escalation reminder. Surfaces the workspace real
- * recent mem-vs-esr balance (usage rollup, last 14 days) so the model sees
- * its own under-proactivity at the next session and can self-correct NOW.
- * Returns "" when there is nothing to correct (no data, too small a sample,
- * or the balance is healthy) — the reminder disappears once behaviour
- * improves, closing the loop.
+ * One-line escalation reminder from an arbitrary balance view
+ * ({ memCalls, esrCalls, days }). Surfaces the workspace real recent
+ * mem-vs-esr balance so the model sees its own under-proactivity and can
+ * self-correct NOW. Returns "" when there is nothing to correct (no data,
+ * too small a sample, or the balance is healthy) — the reminder disappears
+ * once behaviour improves, closing the loop. Pure, deterministic.
  */
-export function escalationHint(store, workspace) {
+export function esrBalanceHint(balance) {
+  if (balance === void 0 || balance === null) return "";
+  const memCalls = balance.memCalls ?? 0;
+  const esrCalls = balance.esrCalls ?? 0;
+  const days = balance.days ?? 0;
+  // No data or too little signal — lecturing on <3 memory ops is noise.
+  if (memCalls < 3 || days < 1) return "";
+  const ratio = esrCalls / (memCalls + esrCalls);
+  // Healthy once esr exceeds ~a third of memory-ops volume; otherwise nudge.
+  if (ratio >= 0.34) return "";
+  return `escalate: last ${days}d ${memCalls} mem ops vs ${esrCalls} esr calls (${Math.round(ratio * 100)}%) — multi-step work → esr_task now, recurring objects → esr_node, related things → esr_link, and close with evidence (esr_close) #suggest-escalate`;
+}
+
+/**
+ * Balance view derived from the per-(workspace,day) `usage` table (legacy).
+ * The table is no longer written in production (assessment P3 moved
+ * observability to on-demand session-log scans); this path exists for
+ * backward compatibility and store-driven tests. Production prefers the
+ * live in-memory recorder view (lib/trigger.js) so the nudge is not starved.
+ */
+export function usageBalanceView(store, workspace) {
   const rows = store.usageRows(workspace);
-  if (rows.length === 0) return "";
+  if (rows.length === 0) return null;
   const recent = rows.slice(-14);
   const MEM = ["engram_store", "engram_recall", "engram_detail", "loom_store", "loom_recall", "loom_detail"];
   const ESR = ["esr_task", "esr_node", "esr_close", "esr_link", "esr_gc"];
@@ -150,44 +170,146 @@ export function escalationHint(store, workspace) {
     for (const k of MEM) memCalls += c[k] ?? 0;
     for (const k of ESR) esrCalls += c[k] ?? 0;
   }
-  // No data or too little signal — lecturing on <3 memory ops is noise.
-  if (memCalls < 3) return "";
-  const ratio = esrCalls / (memCalls + esrCalls);
-  // Healthy once esr exceeds ~half the memory-ops volume; otherwise nudge.
-  if (ratio >= 0.34) return "";
-  return `escalate: last ${recent.length}d ${memCalls} mem ops vs ${esrCalls} esr calls (${Math.round(ratio * 100)}%) — multi-step work → esr_task now, recurring objects → esr_node, related things → esr_link, and close with evidence (esr_close)`;
+  return { memCalls, esrCalls, days: recent.length };
+}
+
+/**
+ * Legacy entry point (store-driven escalation nudge). Kept for callers/tests
+ * that predate the decision-point recorder; prefer `esrBalanceHint` with a
+ * live balance view.
+ */
+export function escalationHint(store, workspace) {
+  return esrBalanceHint(usageBalanceView(store, workspace));
+}
+
+/**
+ * The three ESR closure evidence gates for a task. Null/empty counts as a gap.
+ */
+export function evidenceGaps(t) {
+  const gaps = [];
+  if (t.artifact === null || t.artifact === "") gaps.push("artifact");
+  if (t.evaluation === null || t.evaluation === "") gaps.push("evaluation");
+  if (t.memoryRefs.length === 0) gaps.push("memory_ref");
+  return gaps;
+}
+
+/**
+ * "What should I do with this task next" sort rank — READY-to-close first
+ * (evidence complete → esr_close is the highest-value next move), then claimed
+ * in-progress, then other active, then drafts.
+ */
+function taskNextRank(t) {
+  if (t.state === "stable") return 10;
+  if (evidenceGaps(t).length === 0) return 0;
+  if (t.assignee) return 1;
+  if (t.state === "active") return 2;
+  if (t.state === "draft") return 3;
+  return 4;
+}
+
+/** Order active tasks so the model can act top-down without re-scanning. */
+export function sortActiveForNext(tasks) {
+  return [...tasks].sort((a, b) => {
+    const ra = taskNextRank(a);
+    const rb = taskNextRank(b);
+    if (ra !== rb) return ra - rb;
+    const ga = evidenceGaps(a).length;
+    const gb = evidenceGaps(b).length;
+    if (ga !== gb) return ga - gb;
+    return (b.updatedAt ?? 0) - (a.updatedAt ?? 0);
+  });
+}
+
+/**
+ * Recurring-failure candidates (P0-B): error memories that earned
+ * `hits >= minErrorHits` through repeat-failure revival — durable breakage,
+ * the strongest "turn this into a root-cause task" signal. Most-hit first.
+ */
+export function selectRootCauseCandidates(store, workspace, config) {
+  const min = (config?.minErrorHits ?? 2) | 0;
+  if (min < 1) return [];
+  return store
+    .listMemories(workspace, 200)
+    .filter((m) => m.kind === "error" && (m.hits ?? 0) >= min)
+    .sort((a, b) => (b.hits ?? 0) - (a.hits ?? 0) || (b.updatedAt ?? 0) - (a.updatedAt ?? 0))
+    .map((m) => ({ id: m.id, text: String(m.text), hits: m.hits ?? 0 }));
+}
+
+/**
+ * Stale-task candidates (P3): active tasks that have not been touched for
+ * `staleTaskDays` (default 14) — close with evidence or drop the intent.
+ */
+export function selectStaleCandidates(tasks, config) {
+  const days = (config?.staleTaskDays ?? 14) | 0;
+  if (days < 1) return [];
+  const cutoff = Date.now() - days * 86_400_000;
+  return tasks
+    .filter((t) => (t.updatedAt ?? t.createdAt ?? 0) < cutoff)
+    .map((t) => ({ id: t.id, name: t.name, updatedAt: t.updatedAt ?? t.createdAt, createdAt: t.createdAt }));
 }
 
 /**
  * Render the [ESR] block — active tasks with closure gaps. Only appears when
  * at least one task exists. "STABLE" tasks are folded to a count line to save
  * tokens.
+ *
+ * @param opts {{
+ *   recorder?: import("./trigger.js").TriggerRecorder,  // decision-point recorder (P0-A–P3)
+ *   sessionId?: string,                                  // live session for the hints
+ * }}
  */
-export function renderEsr(store, workspace, config) {
+export function renderEsr(store, workspace, config, opts = {}) {
+  const recorder = opts?.recorder;
+  const sessionId = opts?.sessionId;
+  const live = recorder !== void 0 && sessionId !== void 0;
   const active = store.listTasks(workspace, { includeStable: false });
   const stable = store.listTasks(workspace, { includeStable: true }).filter((t) => t.state === "stable");
-  const hint = escalationHint(store, workspace);
+  const ordered = sortActiveForNext(active);
+  // Prefer the live in-memory balance (recorder); fall back to the legacy
+  // usage-table view so store-driven callers/tests keep working unchanged.
+  const balance = recorder !== void 0 ? recorder.recentBalance(workspace) : usageBalanceView(store, workspace);
+  const hint = esrBalanceHint(balance);
+  const promote = live ? recorder.promoteHint(sessionId, workspace, active.length) : "";
+  const rootCause = live ? recorder.errorHint(sessionId, workspace, selectRootCauseCandidates(store, workspace, config)) : "";
+  const closure = live ? recorder.closureHint(sessionId, workspace, ordered.filter((t) => evidenceGaps(t).length === 0)) : "";
+  const stale = live ? recorder.staleHint(sessionId, workspace, selectStaleCandidates(active, config)) : "";
+  // P4: count only what is actually injected for a live session (never the
+  // GUI preview, which renders the same lines without a sessionId).
+  if (live) {
+    if (promote !== "") recorder.emitHint("promote", workspace, sessionId);
+    if (rootCause !== "") recorder.emitHint("rootcause", workspace, sessionId);
+    if (closure !== "") recorder.emitHint("close", workspace, sessionId);
+    if (stale !== "") recorder.emitHint("stale", workspace, sessionId);
+    if (hint !== "") recorder.emitHint("escalate", workspace, sessionId);
+  }
+
   if (active.length === 0 && stable.length === 0) {
     // Keep the mechanism visible even when idle: one compact line teaches the
     // model that multi-step work earns an esr_task closed with real evidence.
     const base = "[ESR] no open tasks — BE PROACTIVE: multi-step work gets a task now (esr_task); recurring domain objects get a node (esr_node); related things get a link (esr_link). Close tasks with real evidence (esr_close)";
-    return hint === "" ? base : `${base}\n${hint}`;
+    const rest = [promote, rootCause, hint].filter((l) => l !== "");
+    return rest.length === 0 ? base : `${base}\n${rest.join("\n")}`;
   }
 
   const lines = [];
   lines.push(`[ESR] tasks: ${active.length} active / ${stable.length} stable`);
-  for (const t of active.slice(0, 8)) lines.push(`- ${t.id.slice(0, 6)}: ${escapeLt(truncate(t.name, 60))} — ${t.state.toUpperCase()}${taskGapSuffix(t)}`);
+  const firstReady = ordered.find((t) => evidenceGaps(t).length === 0);
+  if (firstReady !== void 0) {
+    lines.push(`next: esr_close ${firstReady.id.slice(0, 6)} — ${escapeLt(truncate(firstReady.name, 40))} (all evidence present)`);
+  }
+  for (const t of ordered.slice(0, 8)) lines.push(`- ${t.id.slice(0, 6)}: ${escapeLt(truncate(t.name, 60))} — ${t.state.toUpperCase()}${taskGapSuffix(t)}`);
   if (active.length > 8) lines.push(`- … ${active.length - 8} more`);
   if (stable.length > 0) lines.push(`- closed: ${stable.slice(0, 6).map((t) => `${t.id.slice(0, 6)} (${truncate(t.name, 28)})`).join(" · ")}${stable.length > 6 ? ` +${stable.length - 6}` : ""}`);
+  if (promote !== "") lines.push(promote);
+  if (rootCause !== "") lines.push(rootCause);
+  if (closure !== "") lines.push(closure);
+  if (stale !== "") lines.push(stale);
   if (hint !== "") lines.push(hint);
   return lines.join("\n");
 }
 
 function taskGapSuffix(t) {
   if (t.state === "stable") return "";
-  const gaps = [];
-  if (t.artifact === null || t.artifact === "") gaps.push("artifact");
-  if (t.evaluation === null || t.evaluation === "") gaps.push("evaluation");
-  if (t.memoryRefs.length === 0) gaps.push("memory_ref");
+  const gaps = evidenceGaps(t);
   return gaps.length === 0 ? " · READY to close" : ` · gap: ${gaps.join(", ")}`;
 }

package/lib/index.js

@@ -21,6 +21,7 @@ import { openEngramDomain } from "./store.js";
 import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
 import { renderIndex, renderEsr } from "./index-block.js";
+import { makeTriggerRecorder } from "./trigger.js";
 import { installEngramSettings } from "./settings.js";
 import { makeEngramRoutes } from "./api.js";
 
@@ -66,6 +67,16 @@ const DEFAULTS = {
   // prompt section order (before the persona/tools bands per DSH convention)
   engramIndexOrder: 40,
   esrOrder: 41,
+  // decision-point triggers (P0-A): promote a session plan to an ESR task
+  // when the pending-todo count is at least minTodosForPromote and exceeds
+  // active ESR tasks × todoPromoteRatio (default: pending > active).
+  minTodosForPromote: 2,
+  todoPromoteRatio: 1,
+  // P0-B: an error memory becomes a root-cause task candidate at this many
+  // repeat-failure hits.
+  minErrorHits: 2,
+  // P3: an active task with no update for this many days is surfaced as stale.
+  staleTaskDays: 14,
 };
 
 function resolveConfig(config) {
@@ -127,10 +138,15 @@ export function apply(ctx, config) {
     return domainPromise;
   };
 
+  // Decision-point triggers (P0-A + P1): live mem-vs-esr balance + the
+  // todo_write promote hook. Process-local; fed by a tools/result listener.
+  const recorder = makeTriggerRecorder(resolved);
+
   const service = {
     config: resolved,
     getDomain,
     openedDomain: () => opened,
+    recorder,
     ensureDomain: () => {
       getDomain().catch(() => {});
     },
@@ -153,7 +169,7 @@ export function apply(ctx, config) {
     renderEsrBlock(workspace) {
       if (opened === void 0) return "";
       try {
-        return renderEsr(opened, workspace, resolved);
+        return renderEsr(opened, workspace, resolved, { recorder });
       } catch {
         return "";
       }
@@ -266,7 +282,10 @@ export function apply(ctx, config) {
           if (cwd === void 0 || cwd.length === 0) return "";
           if (opened === void 0) return "";
           try {
-            return renderEsr(opened, resolvePath(cwd), resolved);
+            return renderEsr(opened, resolvePath(cwd), resolved, {
+              recorder,
+              sessionId: session.id,
+            });
           } catch {
             return "";
           }
@@ -275,6 +294,13 @@ export function apply(ctx, config) {
       disposers.push(() => esrDispose());
     }
 
+    // decision-point triggers: always on (independent of autoCapture) —
+    // feeds the live mem-vs-esr balance and the todo_write promote hint.
+    const disposeTrigger = ctx.on("tools/result", (exec, result) => {
+      recorder.handle(exec, result);
+    });
+    disposers.push(disposeTrigger);
+
     // zero-LLM auto-capture
     if (resolved.autoCapture) {
       // The capture handler needs a storeMemory face, but the domain opens

package/lib/store.js

@@ -776,6 +776,22 @@ export async function openEngramDomain(facility) {
     addLink(link) {
       return links.put(link.id, link);
     },
+    /** Idempotent variant: skip when the same (source, relation, target) edge
+     *  already exists in the workspace — used by auto-wiring paths so repeated
+     *  calls never duplicate a relation. */
+    async addLinkOnce(link) {
+      const dup = [...links.entries()]
+        .map(([, l]) => l)
+        .some(
+          (l) =>
+            l.workspace === link.workspace &&
+            l.source === link.source &&
+            l.target === link.target &&
+            (l.relation ?? "") === (link.relation ?? ""),
+        );
+      if (!dup) await links.put(link.id, link);
+      return !dup;
+    },
     linksFor(workspace, entity) {
       return [...links.entries()]
         .map(([, l]) => l)

package/lib/tools.js

@@ -250,19 +250,20 @@ export function registerTools(ctx, service) {
       // ── 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.",
+        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).",
         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" },
           },
           required: ["name"],
         },
         output: TEXT_OUTPUT,
         execute: async (raw, exec) => {
-          const args = parse(z.object({ name: z.string().min(1).max(200), description: z.string().optional(), id: z.string().optional() }), raw, "esr_task");
+          const args = parse(z.object({ name: z.string().min(1).max(200), description: z.string().optional(), id: z.string().optional(), entity: z.string().optional() }), raw, "esr_task");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
           const existing = args.id === void 0 ? void 0 : domain.getTask(caller.cwd, args.id);
@@ -290,9 +291,14 @@ export function registerTools(ctx, service) {
           };
           await domain.putTask(task);
           await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
+          const wiring = args.entity !== void 0
+            ? await wireTaskEntity(domain, caller.cwd, task.id, args.entity, caller.sessionId, now)
+            : "";
           const hint = esrModelingHint(domain, caller.cwd);
-          return `task ${task.id} [${task.state}] — ${task.name}${hint ? `
-${hint}` : ""}`;
+          const parts = [`task ${task.id} [${task.state}] — ${task.name}`];
+          if (wiring !== "") parts.push(wiring);
+          if (hint !== "") parts.push(hint);
+          return parts.join("\n");
         },
       }),
 
@@ -410,9 +416,26 @@ ${hint}` : ""}`;
           const args = parse(z.object({ task_id: z.string().min(1), dep_id: z.string().min(1), kind: z.enum(["blocks", "relates-to", "parent-of"]).optional() }), raw, "esr_dep");
           const caller = callerOf(exec);
           const domain = await requireDomain(service);
-          const t = await domain.addDep(caller.cwd, resolveTaskId(domain, caller.cwd, args.task_id), resolveTaskId(domain, caller.cwd, args.dep_id), args.kind ?? "blocks");
+          const taskId = resolveTaskId(domain, caller.cwd, args.task_id);
+          const depId = resolveTaskId(domain, caller.cwd, args.dep_id);
+          const kind = args.kind ?? "blocks";
+          const t = await domain.addDep(caller.cwd, taskId, depId, kind);
+          // Graph-hygiene (A): the same edge goes into the links table so the
+          // dependency is a first-class, visible relation everywhere (graph,
+          // /links, entity neighbourhood) — not just a blocker counter.
+          const now = Date.now();
+          await domain.addLinkOnce({
+            id: uuid(),
+            workspace: caller.cwd,
+            source: taskId,
+            relation: kind,
+            target: depId,
+            confidence: 1,
+            sessionId: caller.sessionId,
+            createdAt: now,
+          });
           await domain.markModelDirty?.(caller.cwd).catch?.(() => null);
-          return `dep added: ${t.id} --${args.kind ?? "blocks"}--> ${args.dep_id} (total ${(t.deps ?? []).length} edges)`;
+          return `dep added: ${t.id} --${kind}--> ${depId} (total ${(t.deps ?? []).length} edges · now graphed)`;
         },
       }),
 
@@ -604,15 +627,53 @@ export function esrModelingHint(domain, workspace) {
     const entities = domain.listEntities(workspace);
     const links = domain.allLinks(workspace);
     if (entities.length === 0) {
-      return "modeling: no entity graph in this workspace yet — create esr_node entries for recurring domain objects, then esr_link to connect them (graph: GUI Settings → Engram).";
+      return "modeling: no entity graph in this workspace yet — esr_task(entity=…) auto-creates the node and hangs the task on it; or use esr_node for recurring domain objects, then esr_link to connect (graph: GUI Settings → Engram).";
     }
     const names = entities.slice(0, 3).map((e) => e.name).join(", ");
-    return `modeling: entities ${names}${entities.length > 3 ? ` +${entities.length - 3}` : ""} / links ${links.length} — esr_link can wire new tasks & nodes into this graph.`;
+    return `modeling: entities ${names}${entities.length > 3 ? ` +${entities.length - 3}` : ""} / links ${links.length} — esr_task(entity=…) hangs new work onto a node; esr_link can wire tasks & nodes further into this graph.`;
   } catch {
     return "";
   }
 }
 
+/**
+ * Auto-wire a task onto a domain object (graph-hygiene fix): ensure the entity
+ * node exists (id = ent_<slug>, same derivation as esr_node) and add the
+ * one-way `task --relates_to--> entity` edge, idempotently. One call instead
+ * of esr_node + esr_link so a task is never an isolated node. Pure/mechanical,
+ * zero LLM. Returns a short report line ("" when entity is empty).
+ */
+export async function wireTaskEntity(domain, workspace, taskId, entityName, sessionId, now = Date.now()) {
+  const name = String(entityName).trim().slice(0, 120);
+  if (name.length === 0) return "";
+  const entId = `ent_${slugId(name)}`;
+  let created = false;
+  if (domain.getEntity(workspace, entId) === void 0) {
+    await domain.putEntity({
+      id: entId,
+      workspace,
+      name,
+      description: "",
+      kind: "concept",
+      sessionId,
+      createdAt: now,
+      updatedAt: now,
+    });
+    created = true;
+  }
+  const added = await domain.addLinkOnce({
+    id: uuid(),
+    workspace,
+    source: taskId,
+    relation: "relates_to",
+    target: entId,
+    confidence: 1,
+    sessionId,
+    createdAt: now,
+  });
+  return `wired: ${taskId} --relates_to--> ${entId}${created ? " (node created)" : ""}${added ? "" : " (edge already exists)"}`;
+}
+
 function collectNeighborhood(domain, workspace, items) {
   const involved = new Set();
   for (const m of items ?? []) {

package/lib/trigger.js

@@ -0,0 +1,379 @@
+/**
+ * dsh-engram: decision-point ESR triggers (P0-A + P1).
+ *
+ * The old mem-vs-esr escalation nudge (`escalationHint`) read the per-
+ * (workspace, day) `usage` table, but assessment P3 removed the per-call
+ * write path (observability moved to on-demand session-log scans), leaving
+ * the nudge with a dead data source. This module restores that balance
+ * signal with a cheap in-memory counter fed by the SAME tools/result
+ * subscription — zero I/O per prompt render, zero LLM — and adds the P0-A
+ * decision-point trigger:
+ *
+ *   Watch the native `todo_write` calls, snapshot the session's pending
+ *   todos, and let the [ESR] block emit a concrete "promote to esr_task"
+ *   hint — at most once per session, only when the funnel is actually
+ *   narrow (pending todos > active ESR tasks). This mirrors the GUI's
+ *   "沉淀到 ESR" button on the model side, firing exactly where the
+ *   todo→esr routing decision happens.
+ *
+ * All state is process-local (resets on host reload — acceptable for a
+ * nudge, same trade-off as a short-lived cache). Fully contained: handle()
+ * never throws, so a trigger bug can never disturb the tool pipeline.
+ */
+
+import { workspaceKey as wk, truncate } from "./util.js";
+import { dayKey } from "./usage.js";
+
+/** Tools that count as memory-ops in the mem-vs-esr balance. */
+export const MEM_TOOLS = [
+  "engram_store",
+  "engram_recall",
+  "engram_detail",
+  "loom_store",
+  "loom_recall",
+  "loom_detail",
+];
+/** Tools that count as ESR-ops in the mem-vs-esr balance. */
+export const ESR_TOOLS = ["esr_task", "esr_node", "esr_close", "esr_link", "esr_gc"];
+
+/** Keep at most this many workspace snapshots (todo + usage) in memory. */
+const WORKSPACE_CAP = 200;
+/** Balance rolling window (days). */
+const BALANCE_DAYS = 14;
+const DAY_MS = 86_400_000;
+/** Healthy once esr exceeds ~a third of memory-ops volume (matches P0-era). */
+const HEALTHY_RATIO = 0.34;
+/** Under this many memory ops a nudge is lecturing noise. */
+const SAMPLE_FLOOR = 3;
+
+/** Statuses a todo item wears when it is still unfinished. */
+const DONE_STATUSES = new Set(["completed", "done", "complete", "closed"]);
+
+/**
+ * Stable per-hint source tags (P4). Appended to every nudge line so the
+ * model can reference them and any log watcher can attribute which hint was
+ * shown; `emitHint`/`conversionStats` measure hint → esr_* action conversion.
+ */
+export const HINT_TAGS = {
+  promote: "#suggest-promote",
+  rootcause: "#suggest-rootcause",
+  close: "#suggest-close",
+  stale: "#suggest-stale",
+  escalate: "#suggest-escalate",
+};
+
+/** A hint counts as "converted" when an esr_* tool runs within this window. */
+const CONVERSION_WINDOW_MS = 10 * 60 * 1000;
+
+/**
+ * Deterministically extract the list of unfinished todo names from a
+ * `todo_write` arguments object. Never throws; returns [] for anything else.
+ */
+export function pendingTodos(args) {
+  if (args === null || typeof args !== "object") return [];
+  const raw = Array.isArray(args.todos) ? args.todos : [];
+  const names = [];
+  for (const item of raw) {
+    if (item === null || item === void 0) continue;
+    if (typeof item === "string") {
+      const c = item.trim();
+      if (c.length > 0) names.push(c);
+      continue;
+    }
+    if (typeof item !== "object") continue;
+    const status = String(item.status ?? item.state ?? "").toLowerCase();
+    if (DONE_STATUSES.has(status)) continue;
+    const content = String(item.content ?? item.name ?? item.title ?? "").trim();
+    if (content.length > 0) names.push(content);
+  }
+  return names;
+}
+
+/**
+ * The decision-point recorder. Feed every tools/result event to `handle()`;
+ * read back the live balance via `recentBalance(workspace)` and the one-shot
+ * promote prompt via `promoteHint(sessionId, workspace, activeTasks)`.
+ */
+export function makeTriggerRecorder(config = {}) {
+  const minTodosForPromote = config.minTodosForPromote ?? 2;
+  const todoPromoteRatio = config.todoPromoteRatio ?? 1;
+  /** workspace -> Map<day, {mem, esr}> (live balance, replaces dead usage table). */
+  const usage = new Map();
+  /** workspace -> { sessionId, count, names, updatedAt } (pending-todo plan). */
+  const todos = new Map();
+  /** `ws::sessionId` already got its promote hint this session. */
+  const promoted = new Set();
+  /** `ws::sessionId::errId` — root-cause hint already shown for that mem. */
+  const errorSeen = new Set();
+  /** `ws::sessionId` — its todos went pending → 0 (work finished). */
+  const workDone = new Set();
+  /** `ws::sessionId` — closure hint already shown. */
+  const closureSeen = new Set();
+  /** `ws::sessionId::taskId` — stale hint already shown for that task. */
+  const staleSeen = new Set();
+  /** `ws::sessionId::kind` — hint already emitted for that session (P4). */
+  const hintSeen = new Set();
+  /** ws -> Map<kind, shown|converted> — conversion measurement (P4). */
+  const shownCounts = new Map();
+  const convertedCounts = new Map();
+  /** Unconverted hints within the window: {kind, ws, session, shownAt}. */
+  const pending = [];
+
+  function bump(workspace, key) {
+    const day = dayKey();
+    let buckets = usage.get(workspace);
+    if (buckets === void 0) {
+      buckets = new Map();
+      usage.set(workspace, buckets);
+    }
+    const cur = buckets.get(day) ?? { mem: 0, esr: 0 };
+    cur[key] += 1;
+    buckets.set(day, cur);
+    if (buckets.size > BALANCE_DAYS + 2) {
+      const oldest = dayKey(Date.now() - BALANCE_DAYS * DAY_MS);
+      for (const d of [...buckets.keys()]) if (d < oldest) buckets.delete(d);
+    }
+    if (usage.size > WORKSPACE_CAP) {
+      const first = usage.keys().next().value;
+      usage.delete(first);
+    }
+  }
+
+  /** Count one tool call toward the mem/esr balance (no-op for other tools). */
+  function record(name, workspace) {
+    if (!workspace) return;
+    if (MEM_TOOLS.includes(name)) bump(workspace, "mem");
+    else if (ESR_TOOLS.includes(name)) bump(workspace, "esr");
+  }
+
+  /** tools/result listener. Fire-and-forget; never throws. */
+  function handle(exec, result) {
+    // eslint-disable-next-line no-unused-vars
+    void result;
+    try {
+      const name = String(exec?.name ?? "").toLowerCase();
+      const agent = exec?.agent;
+      const sessionId = agent?.session?.id;
+      const cwd = agent?.session?.header?.cwd;
+      if (!sessionId || typeof cwd !== "string" || cwd.length === 0) return;
+      const workspace = wk(cwd);
+      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 (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
+      // "work finished" event → enable the closure hint (P3).
+      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() });
+      if (prevCount > 0 && names.length === 0) {
+        workDone.add(`${workspace}::${sessionId}`);
+      }
+      if (todos.size > WORKSPACE_CAP) {
+        const first = todos.keys().next().value;
+        todos.delete(first);
+      }
+    } catch {
+      // fully contained — a trigger bug must never disturb the tool pipeline
+    }
+  }
+
+  /**
+   * Live mem-vs-esr balance for a workspace (last BALANCE_DAYS).
+   * Returns { memCalls, esrCalls, days }; all zeros when no data yet.
+   */
+  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);
+    let memCalls = 0;
+    let esrCalls = 0;
+    let days = 0;
+    for (const [day, c] of buckets) {
+      if (day < oldest) continue;
+      days += 1;
+      memCalls += c.mem;
+      esrCalls += c.esr;
+    }
+    return { memCalls, esrCalls, days };
+  }
+
+  // ── P4 conversion measurement ────────────────────────────────────────────
+
+  /** Count a per-(workspace, kind) bucket. */
+  function bumpCount(map, workspace, kind, delta) {
+    let perWs = map.get(workspace);
+    if (perWs === void 0) {
+      perWs = new Map();
+      map.set(workspace, perWs);
+    }
+    perWs.set(kind, (perWs.get(kind) ?? 0) + delta);
+  }
+
+  /** Merge per-workspace buckets; when ws is given, read only that one. */
+  function countsFor(map, workspace) {
+    if (workspace !== void 0) return map.get(workspace) ?? new Map();
+    const out = new Map();
+    for (const perWs of map.values()) {
+      for (const [k, n] of perWs) out.set(k, (out.get(k) ?? 0) + n);
+    }
+    return out;
+  }
+
+  /** Drop hints past the conversion window (or when already attributed). */
+  function prunePending() {
+    const cutoff = Date.now() - CONVERSION_WINDOW_MS;
+    for (let i = pending.length - 1; i >= 0; i--) {
+      if (pending[i].shownAt < cutoff) pending.splice(i, 1);
+    }
+  }
+
+  /**
+   * Record that a hint line was actually injected for a session (P4). Each
+   * (workspace, session, kind) counts at most once, matching the once-per-
+   * session hint semantics — repeated renders of the same hint do not inflate
+   * the exposure count.
+   */
+  function emitHint(kind, workspace, sessionId) {
+    if (!kind || !HINT_TAGS[kind] || !workspace || !sessionId) return;
+    const key = `${workspace}::${sessionId}::${kind}`;
+    if (hintSeen.has(key)) return;
+    hintSeen.add(key);
+    bumpCount(shownCounts, workspace, kind, 1);
+    pending.push({ kind, ws: workspace, session: sessionId, shownAt: Date.now() });
+    prunePending();
+  }
+
+  /**
+   * Attribute the most recent pending hint of this workspace (inside the
+   * window) to an esr_* tool call. One call converts one hint — attribution
+   * stays honest, the rest expire on their own.
+   */
+  function attributeConversion(workspace, at) {
+    let best = -1;
+    for (let i = 0; i < pending.length; i++) {
+      const h = pending[i];
+      if (h.ws !== workspace) continue;
+      if (at - h.shownAt > CONVERSION_WINDOW_MS) continue;
+      if (best === -1 || h.shownAt > pending[best].shownAt) best = i;
+    }
+    if (best === -1) return;
+    const h = pending[best];
+    pending.splice(best, 1);
+    bumpCount(convertedCounts, workspace, h.kind, 1);
+  }
+
+  /**
+   * Hint → esr_* action conversion (P4). Returns a plain, serializable object:
+   *   { windowMs, total: {shown, converted, rate}, byKind: { <kind>: {shown, converted, rate} } }
+   * When `workspace` is omitted, aggregates across all workspaces.
+   */
+  function conversionStats(workspace) {
+    prunePending();
+    const shown = countsFor(shownCounts, workspace);
+    const converted = countsFor(convertedCounts, workspace);
+    const byKind = {};
+    let shownTotal = 0;
+    let convertedTotal = 0;
+    for (const kind of Object.keys(HINT_TAGS)) {
+      const sh = shown.get(kind) ?? 0;
+      const cv = converted.get(kind) ?? 0;
+      shownTotal += sh;
+      convertedTotal += cv;
+      byKind[kind] = { shown: sh, converted: cv, rate: sh > 0 ? +(cv / sh).toFixed(4) : null };
+    }
+    return {
+      windowMs: CONVERSION_WINDOW_MS,
+      total: {
+        shown: shownTotal,
+        converted: convertedTotal,
+        rate: shownTotal > 0 ? +(convertedTotal / shownTotal).toFixed(4) : null,
+      },
+      byKind,
+    };
+  }
+
+  /**
+   * One-shot "promote your plan to an ESR task" hint for the live session.
+   * Returns "" unless: this session wrote ≥ minTodosForPromote pending todos,
+   * the funnel is narrow (pending > active * todoPromoteRatio), and the hint
+   * has not already been emitted this session. Marks the hint emitted on
+   * success so it appears at most once per session (no nagging).
+   */
+  function promoteHint(sessionId, workspace, activeTasks) {
+    if (!sessionId || !workspace) return "";
+    const snap = todos.get(workspace);
+    if (snap === void 0 || snap.sessionId !== sessionId) return "";
+    if (snap.count < minTodosForPromote) return "";
+    if (snap.count <= activeTasks * todoPromoteRatio) return "";
+    const key = `${workspace}::${sessionId}`;
+    if (promoted.has(key)) return "";
+    promoted.add(key);
+    const sample = snap.names
+      .slice(0, 2)
+      .map((n) => truncate(String(n).replace(/\s*\n+\s*/g, " ").trim(), 36))
+      .join(" / ");
+    return `promote: ${snap.count} pending todo(s) vs ${activeTasks} ESR task(s) — multi-step work earns a cross-session task now: esr_task(name="${sample}") ${HINT_TAGS.promote}`;
+  }
+
+  /**
+   * One-shot "root-cause a recurring failure" hint (P0-B). Candidates come
+   * from the store (error memories that earned `hits >= minErrorHits` through
+   * repeat-failure revival) — the recorder only dedupes which error ids have
+   * been surfaced per session. Returns the first not-yet-shown candidate as a
+   * line, or "".
+   */
+  function errorHint(sessionId, workspace, candidates) {
+    if (!sessionId || !workspace) return "";
+    if (!Array.isArray(candidates) || candidates.length === 0) return "";
+    for (const c of candidates) {
+      const key = `${workspace}::${sessionId}::${c.id}`;
+      if (errorSeen.has(key)) continue;
+      errorSeen.add(key);
+      const text = truncate(String(c.text).replace(/\s*\n+\s*/g, " ").trim(), 48);
+      return `root-cause: ${text} ×${c.hits ?? 1} — esr_task it so the pattern dies ${HINT_TAGS.rootcause}`;
+    }
+    return "";
+  }
+
+  /**
+   * One-shot "work is finished — close the READY tasks" hint (P3). Fires only
+   * after this session's plan went pending → 0 (recorded from todo_write),
+   * only when at least one active task has all evidence, and at most once per
+   * session.
+   */
+  function closureHint(sessionId, workspace, readyTasks) {
+    if (!sessionId || !workspace) return "";
+    if (!Array.isArray(readyTasks) || readyTasks.length === 0) return "";
+    const key = `${workspace}::${sessionId}`;
+    if (!workDone.has(key)) return "";
+    if (closureSeen.has(key)) return "";
+    closureSeen.add(key);
+    const t = readyTasks[0];
+    return `close: task ${t.id.slice(0, 6)} · ${truncate(t.name, 40)} — evidence complete, esr_close now (artifact/evaluation/memory_ref) ${HINT_TAGS.close}`;
+  }
+
+  /**
+   * One-shot "this task has gone stale" hint (P3). Candidates are active tasks
+   * with no update for `staleTaskDays`. Each task id is surfaced at most once
+   * per session (one line per render).
+   */
+  function staleHint(sessionId, workspace, staleTasks) {
+    if (!sessionId || !workspace) return "";
+    if (!Array.isArray(staleTasks) || staleTasks.length === 0) return "";
+    for (const t of staleTasks) {
+      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));
+      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 "";
+  }
+
+  return { handle, record, recentBalance, promoteHint, errorHint, closureHint, staleHint, emitHint, conversionStats };
+}

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.3.0",
+  "version": "0.3.2",
   "license": "MIT",
   "repository": {
     "type": "git",