dsh-engram 0.3.4 → 0.3.5

package/lib/session-cjk.js

@@ -0,0 +1,159 @@
+/**
+ * dsh-engram: bounded CJK substring search over the workspace's own session
+ * corpus.
+ *
+ * WHY: the cross-session FTS fallback (`ctx.sessionQuery`) is tokenizer-blind
+ * to Chinese. The harness's session-query SQLite builds its FTS5 index with
+ * `tokenize='unicode61'` (packages/session-query/session-query-sqlite), which
+ * keeps a contiguous CJK run as ONE token — a mid-run substring like 「中间表示」
+ * never matches a session containing 「…的中间表示生成」 (verified against the
+ * harness source and empirically). The host search API additionally
+ * double-quotes every query (`quoteFtsData`), so FTS5 prefix/OR tricks like
+ * `编译*` are unavailable through it either.
+ *
+ * This module is the in-constraint fix: pure mechanical, zero LLM, bounded
+ * (newest N session files, LRU text cache, contiguous substring match), and
+ * consulted ONLY for CJK queries after the official FTS has returned zero.
+ * Same privacy scope as the FTS fallback — a single workspace === one cwd
+ * bucket under `~/.dsh/sessions`, so we never look outside the caller's
+ * workspace. Deterministic ordering: match count desc, then mtime desc.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { decodeZstd, sessionsRoot } from "./usage.js";
+import { redactText } from "./redact.js";
+
+/** CJK ideographs (incl. Ext-A and compatibility ideographs). */
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+
+/** Newest session files scanned per query (keeps the hot path bounded). */
+const MAX_FILES = 4;
+/** Max decompressed files kept in the LRU cache. */
+const MAX_CACHE_FILES = 6;
+/** Max cached decompressed bytes (~24 MB). */
+const MAX_CACHE_BYTES = 24 * 1024 * 1024;
+/** Snippet length around the first match. */
+const SNIPPET = 160;
+
+/** Does the query contain CJK ideographs? */
+export function hasCJK(text) {
+  return CJK_RE.test(String(text));
+}
+
+/**
+ * Map a session cwd to its bucket directory name under `~/.dsh/sessions`
+ * (`--` + workspace-key with separators flattened + `--`), mirroring the
+ * workspaceKey() normalization (win32 lowercasing included).
+ */
+export function bucketFromCwd(cwd) {
+  let norm = path.resolve(String(cwd)).replace(/[\\/]+$/, "");
+  if (process.platform === "win32") norm = norm.toLowerCase();
+  return `--${norm.replace(/^\/*/, "").replace(/[\\/]/g, "-")}--`;
+}
+
+// LRU-ish text cache keyed by file path; re-set moves the entry last.
+const textCache = new Map(); // file -> { mtimeMs, size, text }
+let cacheBytes = 0;
+
+function decodedText(file, st) {
+  const hit = textCache.get(file);
+  if (hit !== void 0 && hit.mtimeMs === st.mtimeMs && hit.size === st.size) return hit.text;
+  const text = decodeZstd(file);
+  while (textCache.size >= MAX_CACHE_FILES || cacheBytes + text.length > MAX_CACHE_BYTES) {
+    const oldest = textCache.keys().next().value;
+    if (oldest === void 0) break;
+    const evicted = textCache.get(oldest);
+    textCache.delete(oldest);
+    cacheBytes -= evicted.text.length;
+  }
+  textCache.set(file, { mtimeMs: st.mtimeMs, size: st.size, text });
+  cacheBytes += text.length;
+  return text;
+}
+
+/** Count contiguous occurrences of `needle` in `text` (ASCII case-folded). */
+export function countMatches(text, needle) {
+  let t = String(text);
+  let n = String(needle);
+  if (t.length === 0 || n.length === 0) return 0;
+  // Case-folding only matters for the non-CJK part of a mixed query.
+  if (/[a-zA-Z]/.test(n)) {
+    t = t.toLowerCase();
+    n = n.toLowerCase();
+  }
+  let count = 0;
+  let idx = 0;
+  while ((idx = t.indexOf(n, idx)) !== -1) {
+    count += 1;
+    idx += n.length;
+  }
+  return count;
+}
+
+function snippetAround(text, needle) {
+  const t = String(text);
+  const n = String(needle);
+  let hay = t;
+  let at = hay.indexOf(n);
+  if (at === -1 && /[a-zA-Z]/.test(n)) {
+    hay = t.toLowerCase();
+    at = hay.toLowerCase().indexOf(n.toLowerCase());
+  }
+  const start = Math.max(0, at - 60);
+  const end = Math.min(t.length, at + n.length + 100);
+  // PRIVACY: these snippets come from RAW session logs (never redacted at the
+  // source), so they run through the same deterministic secret redactor as
+  // the memory write path before any text reaches the model or the GUI.
+  const raw = redactText(t.slice(start, end).replace(/\s*\n+\s*/g, " ").replace(/\s+/g, " ").trim());
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < t.length ? "…" : "";
+  return prefix + raw.slice(0, SNIPPET) + suffix;
+}
+
+/**
+ * Bounded CJK substring search over the workspace's own recent sessions.
+ * @returns [{ sessionId, snippet, hits }] ordered by hits desc, then recency.
+ *   Empty when the query has no CJK or no session file matched.
+ */
+export function searchSessionsCJK({
+  cwd,
+  query,
+  limit = 3,
+  maxFiles = MAX_FILES,
+  root = sessionsRoot(),
+} = {}) {
+  const q = String(query ?? "").trim();
+  if (q.length === 0 || !hasCJK(q)) return [];
+  const bucketDir = path.join(root, bucketFromCwd(cwd));
+  let sids = [];
+  try {
+    sids = fs.readdirSync(bucketDir);
+  } catch {
+    return [];
+  }
+  const files = [];
+  for (const sid of sids) {
+    const file = path.join(bucketDir, sid, "session.jsonl.zstd");
+    let st;
+    try {
+      st = fs.statSync(file);
+    } catch {
+      continue;
+    }
+    files.push({ file, sid, mtimeMs: st.mtimeMs, size: st.size });
+  }
+  files.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  const matches = [];
+  for (const f of files.slice(0, maxFiles)) {
+    const text = decodedText(f.file, f);
+    const hits = countMatches(text, q);
+    if (hits > 0) {
+      matches.push({ sessionId: f.sid, snippet: snippetAround(text, q), hits, mtimeMs: f.mtimeMs });
+    }
+  }
+  matches.sort((a, b) => b.hits - a.hits || b.mtimeMs - a.mtimeMs);
+  return matches.slice(0, limit).map(({ sessionId, snippet, hits }) => ({ sessionId, snippet, hits }));
+}

package/lib/settings.js

@@ -34,6 +34,10 @@ export const SETTINGS_KEYS = [
   "gcStableRetentionDays",
   "gcReplacesCompaction",
   "gcNarrative",
+  "verifyArtifact",
+  "autoSupersede",
+  "autoSinkTodosOnEnd",
+  "autoWebCompaction",
   "trustedHosts",
 ];
 
@@ -64,6 +68,9 @@ export function makeSettingsSchema(defaults) {
     gcReplacesCompaction: z.boolean().default(defaults.gcReplacesCompaction),
     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 面不受影响）"),
     // 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/status.js

@@ -0,0 +1,57 @@
+/**
+ * Durable Context GC status artifact.
+ *
+ * The plugin writes a tiny JSON file under the DSH home at boot once the host
+ * compaction engine and the web-plane wiring have both settled. It is the
+ * offline, inspectable truth for "is Context GC actually active and where?" —
+ * readable by the shipped `dsh-engram` CLI and by support/diagnostics without
+ * booting a session or parsing startup logs.
+ * @module dsh-engram/status
+ */
+
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+/** The DSH home directory (env override, else `~/.dsh`). */
+export function engramHomeDir() {
+  return process.env.DSH_HOME !== undefined && process.env.DSH_HOME.length > 0
+    ? process.env.DSH_HOME
+    : join(homedir(), ".dsh");
+}
+
+/** Absolute path of the Context GC status file. */
+export function contextGcStatusPath() {
+  return join(engramHomeDir(), "engram", "context-gc.status.json");
+}
+
+/**
+ * Atomically write the status snapshot (tmp + rename). Never throws for the
+ * caller's convenience; a failure is logged by the caller if it cares.
+ * @param {object} payload
+ * @returns {Promise<void>}
+ */
+export async function writeContextGcStatus(payload) {
+  const path = contextGcStatusPath();
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp`;
+  await writeFile(
+    tmp,
+    `${JSON.stringify({ version: 1, ...payload, writtenAt: Date.now() }, null, 2)}\n`,
+    "utf8",
+  );
+  await rename(tmp, path);
+}
+
+/**
+ * Read the last status snapshot. Returns `undefined` when none exists yet
+ * (safe to treat as "not yet initialized").
+ * @returns {Promise<Record<string, any> | undefined>}
+ */
+export async function readContextGcStatus() {
+  try {
+    return JSON.parse(await readFile(contextGcStatusPath(), "utf8"));
+  } catch {
+    return undefined;
+  }
+}

package/lib/store.js

@@ -1,7 +1,7 @@
 /**
  * dsh-engram: storage layer over DSH's own `ctx.storageDomain`.
  *
- * One domain `dsh_engram` (JSON unit `~/.dsh/storages/dsh_engram.json`) with three
+ * One domain `dsh_engram` (JSON unit `~/.dsh/storages/dsh_engram.json`) with four
  * tables:
  *   - `memories` — the memory pool (kinds: decision/error/procedure/fact/
  *     insight/handoff/task), with provenance, signal strength, hit counts,
@@ -22,6 +22,7 @@ import path from "node:path";
 import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 import { hashText, byRecency, uuid, now, truncate as truncateText, bm25Rank, tokenize as tokenizeLocal, dedupeBySession } from "./util.js";
 import { deriveObservations } from "./obs.js";
+import { redactText } from "./redact.js";
 
 export const DOMAIN_VERSION = 1;
 
@@ -64,6 +65,10 @@ const MemorySchema = z.object({
   status: z.enum(["active", "archived"]).default("active"),
   /** Absolute TTL expiry (epoch ms), null = no expiry. */
   expiresAt: z.number().int().nullable().default(null),
+  /** Memory id this row supersedes (newer statement replaces older truth). */
+  supersedes: z.string().nullable().default(null),
+  /** Memory id this row directly contradicts (conflicting claim, keep both). */
+  contradicts: z.string().nullable().default(null),
 });
 
 const TaskSchema = z.object({
@@ -201,6 +206,72 @@ function repeatOverlap(previous, incoming) {
   return repeatOverlapRatio(previous, incoming) >= REPEAT_OVERLAP;
 }
 
+/**
+ * Validate a memory-to-memory supersedes/contradicts target: must be a real
+ * memory in the same workspace (fail loud on typos / cross-workspace refs).
+ */
+function validateRelationTarget(workspace, target, kind, memories) {
+  if (target === null || target === void 0 || target === "") return null;
+  const mem = memories.find((m) => m.id === target);
+  if (mem === void 0 || mem.workspace !== workspace) {
+    throw new EngramError("ENGRAM_INVALID_ARGS", `${kind} target memory "${target}" does not exist in this workspace`);
+  }
+  return target;
+}
+
+/** Build supersede/contradiction lookup maps from a memory pool (deterministic). */
+function memoryRelationMaps(pool) {
+  const supersededBy = new Map(); // target id -> newer row
+  const contradictedBy = new Map(); // target id -> rows[]
+  for (const m of pool) {
+    if (m.supersedes !== null && m.supersedes !== void 0) supersededBy.set(m.supersedes, m);
+    if (m.contradicts !== null && m.contradicts !== void 0) {
+      const list = contradictedBy.get(m.contradicts) ?? [];
+      list.push(m);
+      contradictedBy.set(m.contradicts, list);
+    }
+  }
+  return { supersededBy, contradictedBy };
+}
+
+/**
+ * Conservative replacement/negation cues that justify an auto-supersede edge.
+ * Kept explicit and small on purpose: a plain fact update must NOT silently
+ * stale-mark its sibling — only "replaced / switched / no longer / 改用 / 不再"
+ * style statements do.
+ */
+const SUPERSEDE_CUES = [
+  "supersedes", "replaces", "replaced", "deprecated", "no longer", "instead",
+  "switched", "migrated", "dropped", "removed",
+  "改用", "换成", "切换", "改为", "取代", "替代", "迁移", "废除", "弃用", "不再",
+];
+
+/**
+ * Deterministic auto-supersede candidate (config.autoSupersede, default OFF).
+ * Fires only when ALL hold:
+ *   - the new entry has a non-empty entity anchor,
+ *   - its text carries a replacement/negation cue (SUPERSEDE_CUES),
+ *   - an older ACTIVE memory shares that entity AND kind AND ≥1 token with it.
+ * The most recent such memory is superseded; already-superseded rows and
+ * cross-kind/entity rows are never picked. Zero LLM, conservative by design.
+ */
+function autoSupersedeCandidate(all, entry, text) {
+  const kind = entry.kind ?? "fact";
+  if (typeof entry.entity !== "string" || entry.entity.length === 0) return null;
+  const lowered = text.toLowerCase();
+  if (!SUPERSEDE_CUES.some((cue) => lowered.includes(cue))) return null;
+  const newTokens = new Set(tokenizeLocal(text));
+  let best = null;
+  for (const m of all) {
+    if (m.kind !== kind || m.entity !== entry.entity || m.status !== "active") continue;
+    if (m.supersedes !== null) continue;
+    const overlap = tokenizeLocal(m.text).some((t) => newTokens.has(t));
+    if (!overlap) continue;
+    if (best === null || (m.updatedAt ?? m.createdAt ?? 0) > (best.updatedAt ?? best.createdAt ?? 0)) best = m;
+  }
+  return best;
+}
+
 /** Identity validation (mirrors shipped defineDomain; fails loud at load). */
 export const engramDomainSpec = defineDomain({
   name: "dsh_engram",
@@ -290,7 +361,7 @@ export async function openEngramDomain(facility) {
      * is falsy) every workspace. Optional kind/status filters; `q` reuses the
      * deterministic recall scorer.
      */
-    searchMemories({ workspace, q, kind, status, limit = 100 } = {}) {
+    searchMemories({ workspace, q, kind, tag, status, limit = 100 } = {}) {
       const bounded = Math.max(1, Math.min(500, Math.trunc(limit) || 100));
       let pool = [...memories.entries()].map(([, m]) => m);
       if (workspace) pool = pool.filter((m) => m.workspace === workspace);
@@ -298,6 +369,7 @@ export async function openEngramDomain(facility) {
       // (GC archives expired memories; the archive view is their pointer).
       if (status !== "archived") pool = pool.filter(notExpiredNow);
       if (kind) pool = pool.filter((m) => m.kind === kind);
+      if (tag) pool = pool.filter((m) => (m.tags ?? []).includes(tag));
       if (status) pool = pool.filter((m) => m.status === status);
       if (q !== void 0 && String(q).trim().length > 0) {
         return bm25Rank(pool, String(q).trim(), bounded);
@@ -362,12 +434,19 @@ export async function openEngramDomain(facility) {
      * near-repeat of a past ERROR re-warms that entry (failure revival).
      */
     async storeMemory(entry, config) {
-      const text = String(entry.text).trim();
+      // Redact secrets before anything else: before the char cap, before the
+      // dedup hash, and before the revive overlap ratio — so sensitive text
+      // never lands in storage and two identical secrets collapse the same
+      // way as two identical plain texts.
+      const text = redactText(String(entry.text).trim());
       if (text.length === 0) throw new EngramError("ENGRAM_INVALID_ARGS", "memory text must not be empty");
       if ([...text].length > config.maxMemoryChars) {
         throw new EngramError("ENGRAM_CAP_EXCEEDED", `memory text is ${[...text].length} characters, over the cap of ${config.maxMemoryChars}`);
       }
-      const dup = allMemories(entry.workspace).find((m) => hashText(m.text) === hashText(text) && m.kind === (entry.kind ?? "fact"));
+      const all = allMemories(entry.workspace);
+      let supersedes = validateRelationTarget(entry.workspace, entry.supersedes ?? null, "supersedes", all);
+      const contradicts = validateRelationTarget(entry.workspace, entry.contradicts ?? null, "contradicts", all);
+      const dup = all.find((m) => hashText(m.text) === hashText(text) && m.kind === (entry.kind ?? "fact"));
       if (dup !== void 0) {
         // Repeat of the exact same failure is itself a signal: refresh recency
         // AND climb the hit counter (errors only) so the [ENGRAM] index can
@@ -396,6 +475,13 @@ export async function openEngramDomain(facility) {
       if (allMemories(entry.workspace).length >= config.maxMemoriesPerWorkspace) {
         throw new EngramError("ENGRAM_CAP_EXCEEDED", `workspace already holds ${config.maxMemoriesPerWorkspace} active memories (the cap)`);
       }
+      // Auto-supersede (config.autoSupersede, OFF by default): only when the
+      // writer did not name a target AND the hired heuristic fires (see
+      // autoSupersedeCandidate) — explicit supersedes always wins.
+      if (supersedes === null && config?.autoSupersede === true) {
+        const auto = autoSupersedeCandidate(all, entry, text);
+        if (auto !== null) supersedes = auto.id;
+      }
       const expiresAt =
         entry.expiresAt !== void 0 && entry.expiresAt !== null
           ? entry.expiresAt
@@ -418,6 +504,8 @@ export async function openEngramDomain(facility) {
         filePath: entry.filePath ?? null,
         signal: typeof entry.signal === "number" ? Math.max(0, Math.min(1, entry.signal)) : 0.5,
         status: "active",
+        supersedes,
+        contradicts,
         expiresAt,
       };
       await memories.put(stored.id, stored);
@@ -444,12 +532,29 @@ export async function openEngramDomain(facility) {
       const active = allMemories(workspace).filter(notExpiredNow);
       const bounded = Math.max(1, Math.min(50, Math.trunc(limit) || 20));
       if (query !== void 0 && String(query).trim().length > 0) {
+        const { supersededBy } = memoryRelationMaps(active);
         const ranked = bm25Rank(active, String(query).trim(), bounded);
-        if (maxPerSession === void 0 || maxPerSession === null) return ranked;
-        return dedupeBySession(ranked, maxPerSession); // 候选① per-session cap
+        // Superseded = stale truth: an active memory marked itself as replacing
+        // that row. Keep it re-fetchable, but never let it win the ranking —
+        // demote it to the tail so the current statement surfaces first.
+        const main = ranked.filter((m) => !supersededBy.has(m.id));
+        const stale = ranked.filter((m) => supersededBy.has(m.id));
+        const merged = main.concat(stale).slice(0, bounded);
+        if (maxPerSession === void 0 || maxPerSession === null) return merged;
+        return dedupeBySession(merged, maxPerSession); // 候选① per-session cap
       }
       return active.sort(byRecency).slice(0, bounded);
     },
+    /**
+     * Memory-to-memory relation lookup maps for a workspace (deterministic):
+     *   supersededBy: id -> { newer } (a row marked m.supersedes === id)
+     *   contradictedBy: id -> [ rows ] (rows marked m.contradicts === id)
+     * Built purely from the active pool; used by recall rendering and the
+     * [ENGRAM] index to surface "stale truth" honestly without deleting.
+     */
+    memoryRelations(workspace) {
+      return memoryRelationMaps(allMemories(workspace).filter(notExpiredNow));
+    },
     timeline(workspace, entity, limit = 30) {
       const active = allMemories(workspace).filter(notExpiredNow);
       const bounded = Math.max(1, Math.min(100, Math.trunc(limit) || 30));
@@ -468,6 +573,19 @@ export async function openEngramDomain(facility) {
       await memories.put(id, { ...m, status: "archived", updatedAt: now() });
       return true;
     },
+    /**
+     * Append a tag to an ACTIVE memory (idempotent; does NOT touch updatedAt,
+     * so a resolution annotation never re-ranks an error into recall).
+     * Used by the failure→fix closure to mark resolved errors. Zero LLM.
+     */
+    async tagMemory(workspace, id, tag) {
+      const m = memories.get(id);
+      if (m === void 0 || m.workspace !== workspace || m.status !== "active") return false;
+      if (typeof tag !== "string" || tag.length === 0) return true;
+      const tags = (m.tags ?? []).includes(tag) ? m.tags : [...(m.tags ?? []), tag];
+      await memories.put(id, { ...m, tags });
+      return true;
+    },
     /** Lazy TTL sweep (write path only; async). Returns archived count. */
     async expireSweep(workspace) {
       let n = 0;

package/lib/todo-sink.js

@@ -0,0 +1,146 @@
+/**
+ * dsh-engram: session-end todo auto-sink (audit follow-up).
+ *
+ * The todo plane (`todo_write`) is per-session working memory: last-write-wins,
+ * dies with the session. The promote hint (P0-A) and the GUI 「沉淀到 ESR」 button
+ * cover the INTENTIONAL path, but both only fire/run while the session is alive
+ * and the funnel is narrow — a session that ends with pending todos silently
+ * evaporates its plan (the observed "todo 一直建、esr 长期空" leak).
+ *
+ * This module closes that gap at the ONE safe boundary: `session/disposed`
+ * (the session's teardown edge). The trade-off from the design audit is kept
+ * intact:
+ *   - nothing is auto-written DURING the session — todo stays cheap/ephemeral
+ *     and the [ESR] prefix stays stable;
+ *   - the sink never pollutes the active list — landed tasks are `draft`
+ *     (excluded from [ESR] active rows by buildEsrSnapshot), deduped against
+ *     existing non-stable tasks by name, and capped by `maxTasksPerWorkspace`;
+ *   - a draft still needs the deliberate `esr_claim` / `esr_task` step to
+ *     become active, so the "committed work" obligation is never created
+ *     implicitly — the session plan becomes lossless, not obligated.
+ *
+ * All functions are pure / contained and unit-testable without the harness.
+ */
+
+import { pendingTodos } from "./trigger.js";
+import { shortId, uuid } from "./util.js";
+
+/** Description stamped on every auto-sunk draft (mirrors the GUI button's note). */
+export const SINK_DESCRIPTION = "源自会话计划（会话结束自动沉淀）";
+
+/**
+ * Extract the FINAL pending todo list from a session's event log: the last
+ * `todo/write` event (whole-list snapshot) filtered to unfinished items, in
+ * order. Returns [] when the session never wrote todos or everything is done.
+ * Deterministic — this is a pure function of the session log, so it survives
+ * process restarts (no reliance on the process-local recorder snapshot).
+ */
+export function pendingTodosFromSession(session) {
+  if (session === null || typeof session !== "object") return [];
+  const events = Array.isArray(session.events) ? session.events : [];
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event === null || typeof event !== "object" || event.type !== "todo/write") continue;
+    // Event data is the same { todos: TodoItem[] } shape todo_write args wear.
+    return pendingTodos(event.data);
+  }
+  return [];
+}
+
+/**
+ * Decide which pending todos should sink into ESR, and in what order. Pure:
+ *   - names already held by a non-stable task are skipped (dedupe — a task the
+ *     promote hint / GUI button already created is not re-created);
+ *   - within-list duplicates sink only once;
+ *   - the workspace cap (`maxTasksPerWorkspace`, counting drafts) is honoured:
+ *     once `activeCount + created` reaches `maxTasks`, the rest are reported as
+ *     `atCap` instead of created.
+ *
+ * @param {string[]} todos pending todo names, in plan order
+ * @param {Array<{name?: string}>} existingTasks non-stable tasks of the workspace
+ * @param {{ maxTasks?: number, activeCount?: number }} opts
+ * @returns {{ toCreate: string[], existed: string[], atCap: string[] }}
+ */
+export function planTodoSink(todos, existingTasks, opts = {}) {
+  const maxTasks = Number.isFinite(opts.maxTasks) && opts.maxTasks > 0 ? opts.maxTasks : 10;
+  const activeCount = opts.activeCount !== void 0
+    ? opts.activeCount
+    : (Array.isArray(existingTasks) ? existingTasks.length : 0);
+  const existing = new Set(
+    (Array.isArray(existingTasks) ? existingTasks : [])
+      .map((t) => String(t?.name ?? "").trim().toLowerCase())
+      .filter(Boolean),
+  );
+  const toCreate = [];
+  const existed = [];
+  const atCap = [];
+  const seen = new Set();
+  for (const todo of todos ?? []) {
+    const name = String(todo ?? "").trim().slice(0, 200);
+    if (name.length === 0) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue; // within-list duplicate → single sink
+    seen.add(key);
+    if (existing.has(key)) {
+      existed.push(name);
+      continue;
+    }
+    if (activeCount + toCreate.length >= maxTasks) {
+      atCap.push(name);
+      continue;
+    }
+    toCreate.push(name);
+  }
+  return { toCreate, existed, atCap };
+}
+
+/**
+ * Sink a finished session's pending todos into ESR as DRAFT tasks. Best-effort,
+ * never throws into the caller — failures surface via the returned counts plus
+ * whatever the caller logs. Returns { created, existed, atCap } name lists.
+ *
+ * @param {object} domain the opened engram store domain (putTask/listTasks/activeTaskCount)
+ * @param {string} workspace normalized workspace key
+ * @param {string[]} todos pending todo names
+ * @param {{ sessionId?: string, maxTasks?: number, description?: string, now?: number }} opts
+ */
+export async function sinkPendingTodos(domain, workspace, todos, opts = {}) {
+  const record = { created: [], existed: [], atCap: [] };
+  if (!Array.isArray(todos) || todos.length === 0) return record;
+  if (domain === null || typeof domain !== "object" || typeof domain.putTask !== "function") return record;
+  const sessionId = opts.sessionId ?? "auto-sink";
+  const nowMs = typeof opts.now === "function" ? opts.now() : Number.isFinite(opts.now) ? opts.now : Date.now();
+  const existingTasks = typeof domain.listTasks === "function"
+    ? domain.listTasks(workspace, { includeStable: false })
+    : [];
+  const activeCount = typeof domain.activeTaskCount === "function"
+    ? domain.activeTaskCount(workspace)
+    : existingTasks.length;
+  const { toCreate, existed, atCap } = planTodoSink(todos, existingTasks, {
+    maxTasks: opts.maxTasks,
+    activeCount,
+  });
+  record.existed = existed;
+  record.atCap = atCap;
+  for (const name of toCreate) {
+    await domain.putTask({
+      id: `tsk_${shortId(uuid())}`,
+      workspace,
+      name,
+      description: opts.description ?? SINK_DESCRIPTION,
+      state: "draft",
+      artifact: null,
+      evaluation: null,
+      memoryRefs: [],
+      sessionId,
+      createdAt: nowMs,
+      updatedAt: nowMs,
+      stateChangedAt: 0,
+      deps: [],
+      assignee: null,
+      claimedAt: null,
+    });
+    record.created.push(name);
+  }
+  return record;
+}