@inetafrica/open-claudia 2.6.32 → 2.6.34

package/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## v2.6.34
+- **Dual-engine memory recall: typed-edge graph + discoverer (opt-in).** Recall is now pluggable behind a narrow engine interface (`core/recall/`), selected per chat via `/engine` (callback `eng:`). The default stays **classic** (FTS keyword match + relevance judge + headline injection) — unchanged behaviour. The new **discoverer** engine adds a typed-edge graph (`parent`/`governed-by`/`related` edges with weight + last_reinforced in a SQLite store at `recall-graph.db`) and runs: heuristic pre-gate → FTS seed → spreading activation across the graph (1–2 hops, top-k, firing threshold — auto-pulls cross-cutting concerns the query never named) → a haiku "walker" that reads each candidate's Stance/State excerpt and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). Edges form structurally from pack `parent` frontmatter and `[[links]]` (a `[[link]]` to a `shared`-tagged pack becomes `governed-by`) and strengthen via **Hebbian co-use** — when the agent actually opens packs together in a turn (📖), their `related` edge is reinforced; weights decay over time. A metrics layer logs every discoverer turn (seeds, activated, kept+why, pre-gate, latency) — view with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`. The nightly dream now runs on a high tier (opus; `DREAM_TIER`/`DREAM_MODEL` override) and tends the graph (structural sync, weight decay, orphan prune). Switch back any time with `/engine classic`.
+
 ## v2.6.30
 - **Cluster self-management for AgentSpace pods.** When running as an AgentSpace pod, the bot can inspect and manage its own deployment through the backend broker — `/cluster status|logs [n]|restart|start|stop|scale <0|1>|sync` (owner-gated) for humans, and `open-claudia cluster …` for the agent. Both are thin clients over `core/cluster-client.js`, which posts to the broker's capability-gated `/pods/self/cluster` endpoint with the pod's bearer token; the bot holds no Kubernetes credentials. `brokerConfigured()` requires both `AGENTSPACE_API_URL` and `AGENTSPACE_POD_TOKEN`, so an unconfigured local install safely replies "not available" while a provisioned pod reaches the broker. Also tightens the `core/pack-guard.js` exfil heuristic: the broad "URL co-occurring with a sensitive word" rule (which false-positived on legitimate infra notes) is replaced by two precise carriers — a send/store/upload verb pointed at a URL/address, and a credential attached directly to a URL as a query/fragment param.
 

package/bin/cli.js

@@ -294,6 +294,15 @@ switch (command) {
     break;
   }
 
+  case "recall-stats": {
+    require("./recall").run(["stats", ...args.slice(1)]);
+    break;
+  }
+  case "recall": {
+    require("./recall").run(args.slice(1));
+    break;
+  }
+
   case "dream": {
     require("./dream").run(args.slice(1));
     break;

package/bin/recall.js

@@ -0,0 +1,64 @@
+// open-claudia recall-stats [--json]
+// open-claudia recall graph [--sync] [--json]
+//
+// Inspect the recall system: discoverer metrics (precision/miss-rescue/noise,
+// latency, cost) and the typed-edge graph (node/edge counts, sync).
+
+const path = require("path");
+
+const HELP = `
+Inspect the memory recall system.
+
+  open-claudia recall-stats [--json]      Discoverer metrics summary
+  open-claudia recall graph [--sync]      Recall-graph stats (optionally re-sync structural edges first)
+
+The discoverer engine logs one line per turn to recall-metrics.jsonl and a
+rolling summary to recall-metrics-summary.json. Switch engines per chat with
+the /engine command (classic stays the default).
+`;
+
+function stats(args) {
+  const metrics = require(path.join(__dirname, "..", "core", "recall", "metrics"));
+  const s = metrics.summary();
+  if (args.includes("--json")) { console.log(JSON.stringify(s, null, 2)); return; }
+  console.log("Recall metrics (discoverer engine)");
+  console.log("──────────────────────────────────");
+  console.log(`Turns logged:        ${s.turns}`);
+  console.log(`Pre-gated (skipped): ${s.gatedTurns} (${s.gatedPct})`);
+  console.log(`Avg seeds/turn:      ${s.avgSeeds}`);
+  console.log(`Avg activated/turn:  ${s.avgActivated}`);
+  console.log(`Avg kept/turn:       ${s.avgKept}`);
+  console.log(`Graph rescues:       ${s.rescues} over ${s.rescueTurns} turns (${s.rescuePct})`);
+  console.log(`Nodes opened (📖):    ${s.opens}`);
+  console.log(`Avg latency:         ${s.avgLatencyMs}ms`);
+  console.log(`Cost:                $${s.costUsd}`);
+  if (s.updatedAt) console.log(`Updated:             ${s.updatedAt}`);
+}
+
+function graph(args) {
+  const g = require(path.join(__dirname, "..", "core", "recall", "graph"));
+  if (!g.available()) { console.error("Recall graph unavailable (node:sqlite not present)."); process.exit(1); }
+  if (args.includes("--sync")) {
+    const packs = require(path.join(__dirname, "..", "core", "packs"));
+    const entities = require(path.join(__dirname, "..", "core", "entities"));
+    const r = g.syncFromCorpus(packs, entities);
+    console.error(`Synced ${r.edges} structural edge(s).`);
+  }
+  const s = g.stats();
+  if (args.includes("--json")) { console.log(JSON.stringify(s, null, 2)); return; }
+  console.log("Recall graph");
+  console.log("────────────");
+  console.log(`Nodes: ${s.nodes}`);
+  console.log(`Edges: ${s.edges}`);
+  for (const [type, n] of Object.entries(s.byType || {})) console.log(`  ${type}: ${n}`);
+}
+
+function run(args) {
+  const sub = args[0];
+  if (sub === "--help" || sub === "help") { console.log(HELP); process.exit(0); }
+  if (sub === "graph") { graph(args.slice(1)); return; }
+  // default / "stats": metrics summary
+  stats(args.filter((a) => a !== "stats"));
+}
+
+module.exports = { run, HELP };

package/core/actions.js

@@ -274,6 +274,14 @@ async function handleAction(envelope) {
   if (d.startsWith("m:")) { state.settings.model = d.slice(2) === "default" ? null : d.slice(2); await send(`Model: ${state.settings.model || "default"}`); return; }
   if (d.startsWith("e:")) { const e = d.slice(2); state.settings.effort = e === "default" ? null : e; await send(`Effort: ${state.settings.effort || "default"}`); return; }
   if (d.startsWith("b:")) { const b = d.slice(2); state.settings.budget = b === "none" ? null : parseFloat(b); await send(`Budget: ${state.settings.budget ? "$" + state.settings.budget : "none"}`); return; }
+  if (d.startsWith("eng:")) {
+    const v = d.slice(4);
+    const recall = require("./recall");
+    state.settings.recallEngine = recall.listEngines().includes(v) ? v : null;
+    saveState();
+    await send(`Recall engine: ${state.settings.recallEngine || "classic (default)"}`);
+    return;
+  }
   if (d.startsWith("cw:")) {
     const v = d.slice(3);
     if (v === "default") state.settings.compactWindow = null;

package/core/dream.js

@@ -21,7 +21,19 @@ const packGuard = require("./pack-guard");
 const persona = require("./persona");
 const { spawnSubagent } = require("./subagent");
 
-const DREAM_MODEL = process.env.DREAM_MODEL || "sonnet";
+// Graph surgery + threshold tuning is the highest-judgment work in the recall
+// system, so the dream runs on the best available high tier. Honour an explicit
+// DREAM_MODEL override; otherwise prefer opus (strongest reliably-available
+// Claude tier) with sonnet as graceful fallback. Provider-specific high tiers
+// (e.g. a connected Codex 5.5) can extend pickDreamModel later.
+function pickDreamModel() {
+  if (process.env.DREAM_MODEL) return process.env.DREAM_MODEL;
+  const tier = String(process.env.DREAM_TIER || "high").toLowerCase();
+  if (tier === "low") return "haiku";
+  if (tier === "medium") return "sonnet";
+  return "opus";
+}
+const DREAM_MODEL = pickDreamModel();
 const DREAM_CRON = process.env.DREAM_CRON || "0 4 * * *";
 const MAX_PACK_CHARS = 2500;
 const MAX_ENTITY_CHARS = 900;
@@ -372,14 +384,25 @@ async function runDream({ trigger = "manual" } = {}) {
     const applied = applyDream(decision, backupRoot);
     const report = decision.report || (applied.length > 0 ? "Tidied up my memory overnight." : "");
 
+    // Recall-graph maintenance: refresh structural edges, decay reinforced
+    // weights, prune orphans. Deterministic + safe, runs every dream.
+    let graphNote = "";
+    try {
+      const g = require("./recall/graph").tend(packs, entities);
+      if (g.synced || g.decayed || g.pruned) {
+        graphNote = `🕸 Recall graph: ${g.edges} edges / ${g.nodes} nodes (synced ${g.synced}, decayed ${g.decayed}, pruned ${g.pruned}).`;
+      }
+    } catch (e) { /* graph is best-effort */ }
+
     const staleNote = staleTaskReport();
 
     let message = applied.length > 0
       ? `💤 ${report}\n\n${applied.join("\n")}\n\n🗄 Anything merged away is backed up under ${backupRoot}`
       : (report ? `💤 ${report}` : "");
+    if (graphNote) message = message ? `${message}\n\n${graphNote}` : `💤 ${graphNote}`;
     if (staleNote) message = message ? `${message}\n\n${staleNote}` : `💤 ${staleNote}`;
 
-    return { applied, report, message, staleNote, trigger };
+    return { applied, report, message, staleNote, graphNote, trigger };
   } finally {
     _dreaming = false;
   }

package/core/handlers.js

@@ -122,7 +122,7 @@ register({
     if (!authorized(env)) return;
     send([
       "Session: /session /sessions /projects /continue /status /stop /end",
-      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode",
+      "Settings: /model /effort /budget /plan /compact /compactwindow /worktree /mode /engine",
       "Identity: /whoami /link",
       "Team: /people /intros /auth (owner)",
       "Automation: /cron /vault /soul /dreamsummary",
@@ -693,6 +693,32 @@ register({
   },
 });
 
+register({
+  name: "engine", description: "Switch memory recall engine", args: "[classic|discoverer]",
+  handler: async (env, { tail }) => {
+    if (!authorized(env)) return;
+    const { settings } = currentState();
+    const recall = require("./recall");
+    const active = recall.activeEngineName(settings);
+    if (tail) {
+      const v = tail.trim().toLowerCase();
+      if (v === "classic" || v === "default") settings.recallEngine = null;
+      else if (recall.listEngines().includes(v)) settings.recallEngine = v;
+      else return send(`Unknown engine "${v}". Options: ${recall.listEngines().join(", ")}.`);
+      saveState();
+      return send(`Recall engine: ${settings.recallEngine || "classic (default)"}`);
+    }
+    send(
+      `Recall engine: ${active}${settings.recallEngine ? "" : " (default)"}\n\n` +
+      "• classic — keyword FTS + relevance judge (stable default)\n" +
+      "• discoverer — typed-edge graph + spreading activation + why-bullets (new, opt-in)",
+      { keyboard: { inline_keyboard: [
+        [{ text: "Classic (default)", callback_data: "eng:classic" }, { text: "Discoverer", callback_data: "eng:discoverer" }],
+      ] } },
+    );
+  },
+});
+
 register({
   name: "budget", description: "Set max spend for next task", args: "[$N]",
   handler: async (env, { tail }) => {

package/core/pack-review.js

@@ -216,7 +216,7 @@ function reviewTurn({ userText, assistantText, channelId, announce }) {
         } else if (r) {
           lines.push(r.kind === "create"
             ? `📦 New pack: ${r.name}\n${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`
-            : `✏️ ${r.name} — ${clipWords(r.note, 180)}`);
+            : `✏️ ${r.name} — ${clipWords(r.note, 180)}\n↳ open-claudia pack show ${r.dir}`);
         }
       } catch (e) {
         console.warn(`[pack-review] apply failed: ${e.message}`);

package/core/recall/classic.js

@@ -0,0 +1,49 @@
+// Classic recall engine: FTS keyword match (user words + context) → LLM
+// relevance judge → headline injection. This is the original pipeline,
+// extracted behind the RecallEngine interface with NO behaviour change.
+//
+// RecallEngine interface:
+//   async run(ctx) -> { packBlock, entityBlock, packMatches, entityMatches }
+// ctx = { userText, contextText, fullContext, packLimit, budget, helpers }
+// helpers = { packsLib, entitiesLib, mergeMatches, filterMatches, logRecall,
+//             buildPackBlock, buildEntityBlock }
+// The renderers (buildPackBlock/buildEntityBlock) stay in system-prompt.js and
+// are injected here so module-local injection caches / lastInjected keep working.
+
+async function run(ctx) {
+  const { userText, fullContext, packLimit, budget, helpers } = ctx;
+  const {
+    packsLib, entitiesLib, mergeMatches, filterMatches, logRecall,
+    buildPackBlock, buildEntityBlock,
+  } = helpers;
+
+  let packMatches = [];
+  let entityMatches = [];
+  try {
+    packMatches = mergeMatches(
+      packsLib.matchPacks(userText, { limit: packLimit }),
+      fullContext ? packsLib.matchPacks(fullContext, { limit: packLimit }) : [],
+      (m) => m.dir,
+    );
+  } catch (e) {}
+  try {
+    entityMatches = mergeMatches(
+      entitiesLib.matchEntities(userText, { limit: 4 }),
+      fullContext ? entitiesLib.matchEntities(fullContext, { limit: 4 }) : [],
+      (m) => m.slug,
+    );
+  } catch (e) {}
+
+  const candPacks = packMatches;
+  const candEntities = entityMatches;
+  ({ packMatches, entityMatches } = await filterMatches(userText, fullContext, packMatches, entityMatches));
+  packMatches = packMatches.slice(0, packLimit);
+  entityMatches = entityMatches.slice(0, 4);
+  logRecall(userText, candPacks, candEntities, packMatches, entityMatches);
+
+  const packBlock = buildPackBlock(packMatches, budget);
+  const entityBlock = buildEntityBlock(entityMatches, budget);
+  return { packBlock, entityBlock, packMatches, entityMatches };
+}
+
+module.exports = { name: "classic", run };

package/core/recall/discoverer.js

@@ -0,0 +1,231 @@
+// Discoverer recall engine. Same shared corpus as classic, different retrieval:
+//
+//   1. Pre-gate (cheap heuristic) — skip recall on trivial/terse turns.
+//   2. Seed — FTS match (user words + context), same matchers as classic.
+//   3. Spreading activation — propagate from seeds across the typed-edge graph
+//      1-2 hops; nodes over the firing threshold join the candidate set. This
+//      auto-pulls governed-by concerns (theme, commit style) the query never
+//      named, which is the whole point of the graph.
+//   4. Walker (haiku) — reads the seed+activated candidates' live sections and
+//      returns the truly-relevant set WITH a one-line "why" per node. Facts are
+//      quoted, not paraphrased. Fail-open: any error keeps the seeds (classic
+//      baseline), so the discoverer never recalls worse than keyword matching.
+//   5. Inject — render via the shared block builders, prefixed with why-bullets.
+//
+// Conforms to RecallEngine: run(ctx) -> { packBlock, entityBlock, packMatches,
+// entityMatches }. Downstream injection/budget/banner logic stays engine-agnostic.
+
+const graph = require("./graph");
+const metrics = require("./metrics");
+const { spawnSubagent } = require("../subagent");
+
+const WALKER_MODEL = process.env.RECALL_DISCOVERER_MODEL || "haiku";
+const WALKER_TIMEOUT_MS = Number(process.env.RECALL_DISCOVERER_TIMEOUT_MS || 25000);
+const WALKER_ENABLED = String(process.env.RECALL_DISCOVERER_WALKER || "on").toLowerCase() !== "off";
+const EXCERPT_CHARS = 600;
+const CONTEXT_CLIP = 3000;
+
+let _lastSync = 0;
+const SYNC_INTERVAL_MS = 60000;
+
+// Keep the structural graph fresh without paying on every turn.
+function maybeSync(packsLib, entitiesLib) {
+  if (!graph.available()) return;
+  const t = Date.now();
+  if (t - _lastSync < SYNC_INTERVAL_MS) return;
+  _lastSync = t;
+  try { graph.syncFromCorpus(packsLib, entitiesLib); } catch (e) {}
+}
+
+// Cheap pre-gate: terse acknowledgements / pure pleasantries don't need recall.
+function needsRecall(userText, seedCount) {
+  const t = String(userText || "").trim().toLowerCase();
+  if (!t) return false;
+  if (seedCount > 0) return true; // FTS already found something — never gate it out
+  // No seeds: only bother with graph/walker work for a substantive message.
+  const words = t.split(/\s+/).filter(Boolean);
+  if (words.length <= 2) return false;
+  if (/^(ok|okay|thanks|thank you|yes|yep|no|nope|cool|nice|great|done|sure|got it|k)\b/.test(t)) return false;
+  return true;
+}
+
+function idFor(m) { return m.dir ? `pack:${m.dir}` : `entity:${m.slug}`; }
+
+function clip(s, n) { return s && s.length > n ? s.slice(0, n) + "…" : (s || ""); }
+
+// Build the candidate excerpt the walker judges against — real content, not
+// just a description, so "reads into the node" is meaningful.
+function excerptFor(id, packsLib, entitiesLib) {
+  try {
+    if (id.startsWith("pack:")) {
+      const p = packsLib.readPack(id.slice(5));
+      if (!p) return null;
+      const body = [p.sections.Stance, p.sections.State].filter(Boolean).join("\n").trim();
+      return { id, name: p.name, description: p.description, excerpt: clip(body, EXCERPT_CHARS) };
+    }
+    const e = entitiesLib.readEntity(id.slice(7));
+    if (!e) return null;
+    return { id, name: e.name, description: e.description, excerpt: clip((e.sections.Notes || "").trim(), EXCERPT_CHARS) };
+  } catch (e) { return null; }
+}
+
+const WALKER_SYSTEM = [
+  "You are the recall walker for an assistant's long-term memory.",
+  "You are given the user's message, recent conversation, and candidate memory nodes (some matched by keyword, some pulled in by graph links).",
+  "Decide which nodes are GENUINELY relevant to what the user is doing now.",
+  "Keep graph-linked nodes ONLY if they actually bear on the task (e.g. a shared theme/commit-style that governs the thing being worked on). Drop incidental keyword overlaps.",
+  "For each kept node write a terse why (≤12 words). Quote concrete facts verbatim; never invent.",
+  'Reply with ONLY a JSON array: [{"id":"pack:foo","why":"shared lime theme governs this app"}]. Use [] if none.',
+].join("\n");
+
+async function walk(userText, contextText, candidates) {
+  if (!WALKER_ENABLED || candidates.length === 0) return null;
+  const lines = candidates.map((c) => {
+    const tag = c.activated ? ` [linked via ${c.via || "graph"}]` : "";
+    return `- ${c.id}: ${c.name}${tag}${c.description ? `\n    ${c.description}` : ""}${c.excerpt ? `\n    excerpt: ${c.excerpt.replace(/\n/g, " ")}` : ""}`;
+  });
+  const prompt = [
+    "User message:",
+    "<<<", clip(String(userText || ""), 1500), ">>>",
+    ...(contextText ? ["", "Recent conversation:", "<<<", clip(String(contextText), CONTEXT_CLIP), ">>>"] : []),
+    "",
+    "Candidate memory nodes:",
+    ...lines,
+    "",
+    'Reply ONLY with the JSON array of kept nodes and their why, e.g. [{"id":"' + candidates[0].id + '","why":"..."}].',
+  ].join("\n");
+  try {
+    const { text } = await spawnSubagent(prompt, {
+      model: WALKER_MODEL, systemPrompt: WALKER_SYSTEM, timeoutMs: WALKER_TIMEOUT_MS,
+    });
+    const match = String(text || "").match(/\[[\s\S]*\]/);
+    if (!match) return null;
+    const arr = JSON.parse(match[0]);
+    if (!Array.isArray(arr)) return null;
+    const known = new Set(candidates.map((c) => c.id));
+    const out = new Map();
+    for (const item of arr) {
+      if (item && typeof item.id === "string" && known.has(item.id)) {
+        out.set(item.id, String(item.why || "").slice(0, 120));
+      }
+    }
+    return out;
+  } catch (e) {
+    return null;
+  }
+}
+
+async function run(ctx) {
+  const { userText, contextText, fullContext, packLimit, budget, helpers } = ctx;
+  const { packsLib, entitiesLib, mergeMatches, buildPackBlock, buildEntityBlock } = helpers;
+  const started = Date.now();
+
+  maybeSync(packsLib, entitiesLib);
+
+  // 1+2: seed via FTS (user words + context), same as classic.
+  let packSeeds = [];
+  let entSeeds = [];
+  try {
+    packSeeds = mergeMatches(
+      packsLib.matchPacks(userText, { limit: packLimit }),
+      fullContext ? packsLib.matchPacks(fullContext, { limit: packLimit }) : [],
+      (m) => m.dir,
+    );
+  } catch (e) {}
+  try {
+    entSeeds = mergeMatches(
+      entitiesLib.matchEntities(userText, { limit: 4 }),
+      fullContext ? entitiesLib.matchEntities(fullContext, { limit: 4 }) : [],
+      (m) => m.slug,
+    );
+  } catch (e) {}
+
+  const seedCount = packSeeds.length + entSeeds.length;
+
+  // 1: pre-gate.
+  if (!needsRecall(userText, seedCount)) {
+    metrics.logTurn({ engine: "discoverer", query: userText, gated: true, latencyMs: Date.now() - started });
+    return { packBlock: "", entityBlock: "", packMatches: [], entityMatches: [] };
+  }
+
+  // 3: spreading activation from seeds across the graph.
+  const seedNodes = [
+    ...packSeeds.map((m) => ({ id: `pack:${m.dir}`, score: m.score || 2 })),
+    ...entSeeds.map((m) => ({ id: `entity:${m.slug}`, score: m.score || 2 })),
+  ];
+  const seedIds = new Set(seedNodes.map((s) => s.id));
+  let activated = new Map();
+  try { activated = graph.expand(seedNodes, {}); } catch (e) {}
+
+  // 4: assemble candidates (seeds + activated), build excerpts, run the walker.
+  const candIds = new Set(seedIds);
+  for (const id of activated.keys()) candIds.add(id);
+  const candidates = [];
+  for (const id of candIds) {
+    const base = excerptFor(id, packsLib, entitiesLib);
+    if (!base) continue;
+    const act = activated.get(id);
+    candidates.push({ ...base, activated: !seedIds.has(id), via: act ? act.via : null });
+  }
+
+  const whyById = (await walk(userText, contextText || fullContext, candidates)) || null;
+
+  // Decide the kept set. Walker result wins; on fail-open keep the user-origin
+  // seeds only (classic baseline) and drop graph-expanded/context guesses.
+  let keptIds;
+  if (whyById) {
+    keptIds = new Set(whyById.keys());
+  } else {
+    keptIds = new Set(
+      [...packSeeds.filter((m) => m.origin === "user").map((m) => `pack:${m.dir}`),
+       ...entSeeds.filter((m) => m.origin === "user").map((m) => `entity:${m.slug}`)],
+    );
+  }
+
+  const packMatches = [];
+  for (const m of packSeeds) if (keptIds.has(`pack:${m.dir}`)) packMatches.push(m);
+  for (const id of keptIds) {
+    if (id.startsWith("pack:") && !packMatches.some((m) => m.dir === id.slice(5))) {
+      const dir = id.slice(5);
+      const p = packsLib.readPack(dir);
+      if (p) packMatches.push({ dir, name: p.name, origin: "graph" });
+    }
+  }
+  const entityMatches = [];
+  for (const m of entSeeds) if (keptIds.has(`entity:${m.slug}`)) entityMatches.push(m);
+  for (const id of keptIds) {
+    if (id.startsWith("entity:") && !entityMatches.some((m) => m.slug === id.slice(7))) {
+      const slug = id.slice(7);
+      const e = entitiesLib.readEntity(slug);
+      if (e) entityMatches.push({ slug, name: e.name, origin: "graph" });
+    }
+  }
+
+  const finalPacks = packMatches.slice(0, packLimit);
+  const finalEnts = entityMatches.slice(0, 4);
+
+  // 5: render via shared builders, then weave in the why-bullets.
+  let packBlock = buildPackBlock(finalPacks, budget);
+  const entityBlock = buildEntityBlock(finalEnts, budget);
+  if (packBlock && whyById) {
+    const bullets = finalPacks
+      .map((m) => ({ m, why: whyById.get(`pack:${m.dir}`) }))
+      .filter((x) => x.why)
+      .map((x) => `- ${x.m.name || x.m.dir}: ${x.why}`);
+    if (bullets.length) packBlock = `\n\n### Why these surfaced (discoverer)\n${bullets.join("\n")}${packBlock}`;
+  }
+
+  metrics.logTurn({
+    engine: "discoverer",
+    query: userText,
+    seeds: seedNodes,
+    activated: [...activated.entries()].map(([id, a]) => ({ id, activation: a.activation, hop: a.hop })),
+    kept: [...keptIds].map((id) => ({ id, why: whyById ? whyById.get(id) : "" })),
+    gated: false,
+    latencyMs: Date.now() - started,
+  });
+
+  return { packBlock, entityBlock, packMatches: finalPacks, entityMatches: finalEnts };
+}
+
+module.exports = { name: "discoverer", run, needsRecall, walk };