dsh-engram 0.3.4 → 0.3.6

package/lib/index.js

@@ -6,8 +6,10 @@
  *   - a compact, per-session-frozen [ENGRAM] symbolic index injected through a
  *     systemPrompt section (order 40) — prefix-stable for KV cache reuse
  *   - an [ESR] task/closure block (order 41) listing evidence gaps
- *   - six tight tools: engram_store / engram_recall / engram_detail / esr_task /
- *     esr_close / esr_link
+ *   - fourteen tight tools: memory plane (engram_store / engram_recall /
+ *     engram_detail) + ESR protocol (esr_task / esr_close / esr_link / esr_dep /
+ *     esr_claim / esr_unclaim / esr_ready / esr_status / esr_node / esr_gc /
+ *     esr_model)
  *   - storage on ctx.storageDomain (JSON unit dsh_engram), reads synchronous
  *
  * All model-visible writes are immediate (no approval gate — zero friction,
@@ -20,11 +22,15 @@ import { resolve as resolvePath } from "node:path";
 import { openEngramDomain } from "./store.js";
 import { registerTools } from "./tools.js";
 import { makeCaptureHandler } from "./capture.js";
-import { renderIndex, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
+import { installGoalCapture } from "./goal-capture.js";
+import { renderIndex, renderStartRecall, firstUserMessageText, renderEsr, esrMethodology, buildEsrSnapshot, buildFrozenEsrBlock } from "./index-block.js";
 import { makeTriggerRecorder } from "./trigger.js";
+import { pendingTodosFromSession, sinkPendingTodos } from "./todo-sink.js";
 import { installEngramSettings } from "./settings.js";
 import { makeEngramRoutes } from "./api.js";
-import { loadCompactionEngine, collectPointerContext } from "./context-gc.js";
+import { collectPointerContext, mountCompactionEngine } from "./context-gc.js";
+import { provisionWebCompaction } from "./web-provision.js";
+import { writeContextGcStatus } from "./status.js";
 import { workspaceKey as wk } from "./util.js";
 
 /** Stable cordis plugin name. */
@@ -42,9 +48,25 @@ const DEFAULTS = {
   autoCaptureGlobalCap: 500,
   // recall
   sessionSearch: true,
+  // opt-in cross-workspace recall ("workspace" = current default, strict
+  // per-workspace isolation; "global" = when the local pool has weak/no hits,
+  // also rank entries from other workspaces' pools with a recency/origin-aware
+  // penalty and surface a [W:<workspace>] origin marker). Token-discipline
+  // default is preserved; this is strictly an enable knob.
+  recallScope: "workspace",
   // session-diversified recall: max memories per session before cross-session
   // evidence takes over (agentmemory 候选①; "few and precise")
   maxRecallPerSession: 3,
+  // Host-side session-start auto-recall (方案 B): at the FIRST assembly of a
+  // new session, key a bounded BM25 recall off the session's first user message
+  // and inject the top hits as a [RECALL] block — relevant memory reaches the
+  // model even when it never calls engram_recall on its own (the observed gap:
+  // pull-only recall left everything to model initiative and almost never
+  // fired). Pure rule, zero LLM, per-session frozen with the [ENGRAM] block.
+  // "few and precise" — agentmemory 候选①'s lesson from the coding leaderboard.
+  autoRecallOnStart: true,
+  autoRecallLimit: 3,
+  autoRecallMaxChars: 700,
   // [ENGRAM] index budget (token discipline)
   indexMaxLines: 12,
   indexMaxChars: 700,
@@ -88,9 +110,30 @@ const DEFAULTS = {
   minErrorHits: 2,
   // P3: an active task with no update for this many days is surfaced as stale.
   staleTaskDays: 14,
+  // Session-end todo continuity (audit follow-up): when a session is disposed
+  // while its plan still has pending todos, auto-sink them into ESR as DRAFT
+  // tasks (deduped by name, capped by maxTasksPerWorkspace). During the session
+  // nothing is auto-written — todo stays cheap/ephemeral and the [ESR] prefix
+  // stays stable; the sink only lands drafts, which still need the deliberate
+  // esr_claim / esr_task step to become active.
+  autoSinkTodosOnEnd: true,
+  // Web-plane auto-wiring for Context GC: web sessions resolve `compaction`
+  // inside the agent preset's own realm, which a profile patch cannot reach,
+  // so the plugin edits every stock-layout preset's `compaction` group once —
+  // the default preset plus the whole roster (shipped + user roots) — swapping
+  // the `compaction-basic` row for `dsh-engram/compaction` (backup + strict
+  // validation + idempotent; a preset with a custom compaction layout — or
+  // none, like `minimal` — is never touched). Off = every preset keeps DSH's
+  // default LLM summarizer; the host plane (headless/TUI/base) is unaffected.
+  autoWebCompaction: true,
+  // Memory-to-memory semantics (zero LLM): when ON, an entity-anchored write
+  // that carries a replacement/negation cue ("改用 / no longer / switched…")
+  // auto-marks the matching older same-entity+kind memory as superseded.
+  // OFF by default — explicit `supersedes` is always the primary path.
+  autoSupersede: false,
 };
 
-function resolveConfig(config) {
+export function resolveConfig(config) {
   const src = config && typeof config === "object" ? config : {};
   const out = { ...DEFAULTS };
   for (const key of Object.keys(DEFAULTS)) {
@@ -167,6 +210,12 @@ export function apply(ctx, config) {
     captureStats: { total: 0, git: 0, file: 0, error: 0 },
     /** Last GC sweep totals (GUI overview observability). */
     gcStats: { lastRun: 0, archivedMemories: 0, archivedTasks: 0, removedLinks: 0 },
+    /** Live Context GC status (API overview + durable status file). */
+    compactionStatus: {
+      host: "pending",
+      web: { action: "pending", presets: [] },
+      config: { autoWebCompaction: resolved.autoWebCompaction, gcReplacesCompaction: resolved.gcReplacesCompaction, gcNarrative: resolved.gcNarrative },
+    },
     /** Recompute the exact [ENGRAM] block for a workspace (GUI overview cost). */
     renderIndexBlock(workspace) {
       if (opened === void 0) return "";
@@ -249,12 +298,32 @@ export function apply(ctx, config) {
       return "";
     }
     let block = "";
+    let pendingRecall = false;
     try {
       const workspace = resolvePath(cwd);
       block = renderIndex(opened, workspace, cwd, resolved);
+      // Host-side session-start auto-recall (方案 B): append the [RECALL]
+      // block keyed on the session's FIRST user message. The cache only freezes
+      // once there is a query to key on — if the user text isn't in the events
+      // yet (exotic pre-message assemblies), return the index alone and let the
+      // next assembly retry, so a new conversation never permanently misses its
+      // recalled memory.
+      if (resolved.autoRecallOnStart !== false) {
+        const query = firstUserMessageText(session);
+        if (query.length === 0) {
+          pendingRecall = true;
+        } else {
+          const recall = renderStartRecall(opened, workspace, resolved, { query, allowRecencyFallback: false });
+          block = recall.length > 0 ? `${block}\n${recall}`.trim() : block;
+        }
+      }
     } catch (error) {
       log?.warn?.(`engram index render failed: ${String(error)}`);
     }
+    // Never cache a render that skipped auto-recall for lack of an opening
+    // message — the next assembly will have it and can still materialize the
+    // [RECALL] block.
+    if (pendingRecall) return block;
     sessionCache.set(session, block);
     return block;
   };
@@ -313,6 +382,117 @@ export function apply(ctx, config) {
     // tools
     disposers.push(registerTools(ctx, service));
 
+    // Context GC (host plane) — the auto-GC that REPLACES DSH's built-in
+    // lossy LLM-summary compaction. Mounts the `compaction` service on THIS
+    // fiber (cordis removes it again when the fiber tears down, so reloading /
+    // unloading engram rolls back automatically). The profile patch disables
+    // the base `compaction-basic` row, making engram the sole provider:
+    // `gcReplacesCompaction:true` (default) → ContextGcEngine; `false` → a bare
+    // BasicCompactionEngine so the `compaction` service never disappears while
+    // dsh-engram is installed. Web profiles mount per-session compaction inside
+    // the agent preset's own realm (see README); this host-plane provider
+    // covers headless/TUI/base profiles and any host-plane consumer.
+    const hostCompactionPromise = mountCompactionEngine(ctx, resolved, {
+      readWorkspace: async (workspace, report) => {
+        if (!workspace) return null;
+        try {
+          const domain = await service.getDomain();
+          return collectPointerContext(domain, wk(workspace), report);
+        } catch {
+          return null;
+        }
+      },
+    });
+    disposers.push(() => {
+      // The engine's service registration is fiber-scoped and auto-removed on
+      // teardown; this only settles the async mount and surfaces late errors.
+      void hostCompactionPromise.catch(() => {});
+    });
+
+    // Context GC status: record the settled host/web facts and flush a durable
+    // snapshot to $DSH_HOME/engram/context-gc.status.json once BOTH planes have
+    // settled (the web inject may never fire on a profile without agentPresets,
+    // so a bounded timer marks the web plane done for host-only profiles).
+    let hostSettled = false;
+    let webSettled = resolved.autoWebCompaction === false;
+    let statusTimer = void 0;
+    const flushStatus = () => {
+      if (!hostSettled || !webSettled) return;
+      if (statusTimer !== void 0) { clearTimeout(statusTimer); statusTimer = void 0; }
+      void writeContextGcStatus({
+        planes: resolved.autoWebCompaction === false ? ["host"] : ["host", "web"],
+        host: service.compactionStatus.host,
+        web: service.compactionStatus.web,
+        config: service.compactionStatus.config,
+        configSource: {
+          autoWebCompaction: resolved.autoWebCompaction,
+          gcReplacesCompaction: resolved.gcReplacesCompaction,
+          gcNarrative: resolved.gcNarrative,
+        },
+      }).catch(() => {});
+    };
+    void hostCompactionPromise
+      .then((Engine) => {
+        hostSettled = true;
+        service.compactionStatus.host = Engine
+          ? (resolved.gcReplacesCompaction ? "context-gc" : "default")
+          : "unavailable";
+        flushStatus();
+      })
+      .catch(() => {
+        hostSettled = true;
+        service.compactionStatus.host = "unavailable";
+        flushStatus();
+      });
+
+    // Web-plane auto-wiring (Context GC): web sessions resolve `compaction`
+    // inside the agent preset's own realm, which a profile patch cannot reach.
+    // When the `agentPresets` service is present, swap the stock
+    // `compaction-basic` row for `dsh-engram/compaction` in every stock-layout
+    // preset — the default one plus the whole roster (shipped + user roots) —
+    // so a session composed from any preset gets Context GC. Surgical,
+    // idempotent, backed up, validated; a preset with a custom compaction
+    // layout (or none) is never touched. The row's engine config is derived
+    // from the settings knobs (`gcReplacesCompaction` / `gcNarrative`), so
+    // changing them re-provisions the web rows on the next boot. Flip
+    // `autoWebCompaction:false` to stop auto-wiring on later boots (it does
+    // not un-wire already-wired presets — use `npm run web-compaction:revert`
+    // for that). Best-effort: a failure only warns.
+    if (resolved.autoWebCompaction !== false) {
+      ctx.inject(["agentPresets"], (webCtx) => {
+        const agentPresets = webCtx.get("agentPresets");
+        provisionWebCompaction(agentPresets, {
+          rowConfig: {
+            gcReplacesCompaction: resolved.gcReplacesCompaction,
+            gcNarrative: resolved.gcNarrative,
+          },
+          log: (line) => webCtx.logger.info(line),
+        })
+          .then((report) => {
+            webSettled = true;
+            service.compactionStatus.web = { action: report.action, presets: report.presets };
+            flushStatus();
+          })
+          .catch((error) => {
+            webSettled = true;
+            service.compactionStatus.web = { action: "failed", presets: [], error: String(error?.message ?? error) };
+            webCtx.logger.warn(`engram web-provision failed: ${String(error?.message ?? error)}`);
+            flushStatus();
+          });
+      });
+      // Host-only profiles never provide `agentPresets`; settle the web plane
+      // after a bounded wait so the status flush still happens there.
+      statusTimer = setTimeout(() => {
+        if (!webSettled) {
+          webSettled = true;
+          flushStatus();
+        }
+      }, 15_000);
+      setTimeout(() => { statusTimer = void 0; }, 16_000);
+    } else {
+      flushStatus();
+    }
+
     // systemPrompt sections (frozen per session)
     const systemPrompt = ctx.get("systemPrompt");
     if (systemPrompt !== void 0) {
@@ -359,6 +539,38 @@ export function apply(ctx, config) {
     });
     disposers.push(disposeTrigger);
 
+    // session-end todo auto-sink: a session whose plan still has pending todos
+    // lands them as ESR drafts at its teardown edge, so the plan survives the
+    // session (flip `autoSinkTodosOnEnd` off to opt out). Live-toggleable — the
+    // flag is read per event. Fully contained: a sink failure only warns.
+    const disposeSink = ctx.on("session/disposed", (session) => {
+      if (resolved.autoSinkTodosOnEnd === false) return;
+      const cwd = session?.header?.cwd;
+      const sessionId = session?.id;
+      if (typeof cwd !== "string" || cwd.length === 0) return;
+      if (typeof sessionId !== "string" || sessionId.length === 0) return;
+      const todos = pendingTodosFromSession(session);
+      if (todos.length === 0) return;
+      const workspace = wk(cwd);
+      service
+        .getDomain()
+        .then((domain) =>
+          sinkPendingTodos(domain, workspace, todos, {
+            sessionId,
+            maxTasks: resolved.maxTasksPerWorkspace,
+          }),
+        )
+        .then((report) => {
+          if (report.created.length > 0) {
+            log?.info?.(`engram todo auto-sink: ${report.created.length} pending todo(s) → ${report.created.length} ESR draft(s) in ${workspace}`);
+          } else if (report.existed.length > 0 || report.atCap.length > 0) {
+            log?.info?.(`engram todo auto-sink: ${report.existed.length} already in ESR, ${report.atCap.length} skipped (cap) in ${workspace}`);
+          }
+        })
+        .catch((error) => log?.warn?.(`engram todo auto-sink failed: ${String(error)}`));
+    });
+    disposers.push(disposeSink);
+
     // zero-LLM auto-capture
     if (resolved.autoCapture) {
       // The capture handler needs a storeMemory face, but the domain opens
@@ -374,12 +586,28 @@ export function apply(ctx, config) {
           }
           return domain.storeMemory(...args);
         },
+        // failure→fix closure reads (sync; [] until the domain is open)
+        listMemories(workspace, limit) {
+          const domain = service.openedDomain();
+          return domain === void 0 ? [] : domain.listMemories(workspace, limit);
+        },
+        // failure→fix closure tags prior error rows as resolved (async)
+        tagMemory(workspace, id, tag) {
+          const domain = service.openedDomain();
+          return domain === void 0 ? Promise.resolve(false) : domain.tagMemory(workspace, id, tag);
+        },
       };
       const capture = makeCaptureHandler(captureStore, resolved, log, service.captureStats);
       const disposeCapture = ctx.on("tools/result", (exec, result) => {
         capture(exec, result);
       });
       disposers.push(disposeCapture);
+
+      // DSH goal-domain integration: a completed/blocked goal auto-sediments
+      // as a memory (`goal/change` session event → handoff/error row), so the
+      // outcome survives the session without any LLM call.
+      const disposeGoal = installGoalCapture(ctx, captureStore, log);
+      disposers.push(disposeGoal);
     }
 
     // memory GC scheduling: one sweep after the store is reachable, then on

package/lib/redact.js

@@ -0,0 +1,48 @@
+/**
+ * dsh-engram: deterministic secret redaction for the memory write path.
+ *
+ * Auto-captured tool results, git commit subjects and error messages can
+ * carry real credentials (API keys, tokens, private keys) into long-term
+ * memory — and later straight back into a prompt via recall/[ENGRAM]. This
+ * module strips them BEFORE persistence so nothing sensitive is ever stored.
+ *
+ * Rule-based and deterministic (same input ⇒ same output, zero deps, zero
+ * LLM). Replacement markers are derived from the secret kind, so exact
+ * duplicate detection and error-revival hashing keep behaving consistently
+ * across runs. Applied once at the single store write choke point
+ * (`storeMemory`), which covers engram_store, auto-capture and any future
+ * write path.
+ */
+
+const RULES = [
+  // Private key blocks (longest first so later rules cannot see them).
+  [/-----BEGIN [A-Z0-9 ]+PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]+PRIVATE KEY-----/g, "<REDACTED:private-key>"],
+  // JWT (header.payload.signature).
+  [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g, "<REDACTED:jwt>"],
+  // Stripe live/test keys.
+  [/\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g, "<REDACTED:stripe>"],
+  // OpenAI/Anthropic/OpenRouter style sk-… keys.
+  [/\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}\b/g, "<REDACTED:sk>"],
+  // GitHub fine-grained / classic tokens.
+  [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, "<REDACTED:github>"],
+  // AWS access key IDs.
+  [/\b(?:AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA)[0-9A-Z]{16}\b/g, "<REDACTED:aws>"],
+  // Slack workspace tokens.
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, "<REDACTED:slack>"],
+  // Basic auth user:pass inside URLs.
+  [/\/\/[^:\/\s]+:[^@\s\/]+@/g, "//<REDACTED>@"],
+  // Authorization: Bearer <long token>.
+  [/\bBearer\s+[A-Za-z0-9._~+\/-]{16,}\b/gi, "<REDACTED:bearer>"],
+  // Generic key=value / key: value assignments for obvious secret keys.
+  [/\b(?:api[_-]?key|apikey|access[_-]?token|auth[_-]?token|client[_-]?secret|secret|passwd|password|persist[_-]?token|refresh[_-]?token|token)\b\s*[:=]\s*['"]?[A-Za-z0-9_\-.\/+=]{6,}['"]?/gi, "<REDACTED:key>"],
+];
+
+/**
+ * Redact known secret shapes in `text`. Deterministic: identical input yields
+ * identical output. Non-secret prose is untouched.
+ */
+export function redactText(text) {
+  let out = String(text ?? "");
+  for (const [re, repl] of RULES) out = out.replace(re, repl);
+  return out;
+}

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

@@ -22,6 +22,9 @@ export const SETTINGS_NS = settingsNamespace(SETTINGS_NS_NAME);
 export const SETTINGS_KEYS = [
   "autoCapture",
   "sessionSearch",
+  "recallScope",
+  "autoRecallOnStart",
+  "autoRecallLimit",
   "maxRecallPerSession",
   "autoCapturePerSession",
   "indexMaxLines",
@@ -34,6 +37,10 @@ export const SETTINGS_KEYS = [
   "gcStableRetentionDays",
   "gcReplacesCompaction",
   "gcNarrative",
+  "verifyArtifact",
+  "autoSupersede",
+  "autoSinkTodosOnEnd",
+  "autoWebCompaction",
   "trustedHosts",
 ];
 
@@ -51,6 +58,9 @@ export function makeSettingsSchema(defaults) {
   return z.object({
     autoCapture: z.boolean().default(defaults.autoCapture),
     sessionSearch: z.boolean().default(defaults.sessionSearch),
+    recallScope: z.union(["workspace", "global"]).default(defaults.recallScope ?? "workspace").description("召回范围：workspace=严格按当前工作区隔离（默认、token 纪律）；global=本工作区命中弱/空时，从其它工作区池按 recency/origin 加权召回并标 [W:<workspace>] 来源。开启会打破跨工作区隔离，请按需选用"),
+    autoRecallOnStart: z.boolean().default(defaults.autoRecallOnStart).description("新会话开始时，宿主按首条消息对工作区做确定性召回，把命中记忆直接注入 [RECALL] 块（无需模型自己想起调 engram_recall；关掉=回到纯拉取）"),
+    autoRecallLimit: z.natural().min(1).max(8).default(defaults.autoRecallLimit).description("[RECALL] 块最多注入的记忆条数（agentmemory 候选①：少而准）"),
     maxRecallPerSession: z.natural().min(1).max(10).default(defaults.maxRecallPerSession),
     autoCapturePerSession: z.natural().max(1000).default(defaults.autoCapturePerSession),
     indexMaxLines: z.natural().max(50).default(defaults.indexMaxLines),
@@ -64,6 +74,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;
+  }
+}