@inetafrica/open-claudia 2.6.57 → 2.6.59

package/core/recall/kpi.js

@@ -0,0 +1,227 @@
+// Per-version KPI aggregation over recall telemetry. Ground truth is the
+// per-turn JSONL (every record version+model stamped); the nightly dream
+// snapshots in recall-kpi.jsonl are the time series. Deterministic and
+// read-only — powers `open-claudia kpi` (text table, JSON, and a
+// self-contained HTML report with inline SVG charts, no CDN).
+
+const fs = require("fs");
+const metrics = require("./metrics");
+
+const LEGACY_VERSION = "pre-2.6.59"; // records logged before version stamping shipped
+
+function emptyBucket(v) {
+  return {
+    v, models: new Set(), firstTs: "", lastTs: "",
+    turns: 0, gated: 0, seedsTier: 0, keptTotal: 0,
+    rescueTurns: 0, rescues: 0, walkerFailed: 0,
+    latencyMsTotal: 0, costUsd: 0, autoKept: 0, autoDropped: 0,
+    opens: 0, reviewerUses: 0, byTier: {},
+  };
+}
+
+// Stream the per-turn log into per-version buckets. Use-records (📖 opens /
+// reviewer adjudications) are attributed to the version that observed the use.
+function scanLog() {
+  let lines = [];
+  try { lines = fs.readFileSync(metrics.LOG_FILE, "utf8").split("\n").filter(Boolean); }
+  catch (e) { return new Map(); }
+  const byV = new Map();
+  const bucket = (v) => { if (!byV.has(v)) byV.set(v, emptyBucket(v)); return byV.get(v); };
+  for (const line of lines) {
+    let rec; try { rec = JSON.parse(line); } catch (e) { continue; }
+    const b = bucket(rec.v || LEGACY_VERSION);
+    if (!b.firstTs) b.firstTs = rec.ts || "";
+    if (rec.ts) b.lastTs = rec.ts;
+    if (Array.isArray(rec.use)) {
+      if (rec.source === "reviewer") b.reviewerUses += rec.use.length;
+      else b.opens += rec.use.length;
+      continue;
+    }
+    b.turns++;
+    if (rec.model) b.models.add(rec.model);
+    b.latencyMsTotal += rec.latencyMs || 0;
+    b.costUsd += rec.costUsd || 0;
+    if (rec.tier) {
+      const t = b.byTier[rec.tier] || { n: 0, ms: 0 };
+      t.n++; t.ms += rec.latencyMs || 0;
+      b.byTier[rec.tier] = t;
+    }
+    if (rec.gated) { b.gated++; continue; }
+    if (rec.tier === "seeds") b.seedsTier++;
+    if (rec.walker === "failed") b.walkerFailed++;
+    const kept = rec.kept || [];
+    b.keptTotal += kept.length;
+    const seedIds = new Set((rec.seeds || []).map((s) => s.id));
+    const rescues = kept.filter((k) => !seedIds.has(k.id)).length;
+    if (rescues > 0) { b.rescueTurns++; b.rescues += rescues; }
+    if (rec.auto) {
+      b.autoKept += (rec.auto.kept || []).length;
+      b.autoDropped += (rec.auto.dropped || []).length;
+    }
+  }
+  return byV;
+}
+
+const r1 = (n) => Math.round(n * 10) / 10;
+const pct = (n, d) => (d ? Math.round((n / d) * 100) : null);
+
+// One comparable row per version, ordered oldest→newest by first sighting.
+function aggregate() {
+  const rows = [];
+  for (const b of scanLog().values()) {
+    const used = b.opens + b.reviewerUses;
+    rows.push({
+      v: b.v,
+      models: [...b.models].sort(),
+      from: (b.firstTs || "").slice(0, 10),
+      to: (b.lastTs || "").slice(0, 10),
+      turns: b.turns,
+      gatedPct: pct(b.gated, b.turns),
+      seedsTierPct: pct(b.seedsTier, b.turns),
+      keptTotal: b.keptTotal,
+      avgKept: b.turns - b.gated ? r1(b.keptTotal / (b.turns - b.gated)) : 0,
+      rescuePct: pct(b.rescueTurns, b.turns - b.gated),
+      noisePct: b.keptTotal ? Math.max(0, 100 - Math.round((used / b.keptTotal) * 100)) : null,
+      opens: b.opens,
+      reviewerUses: b.reviewerUses,
+      avgLatencyMs: b.turns ? Math.round(b.latencyMsTotal / b.turns) : 0,
+      byTier: Object.fromEntries(Object.entries(b.byTier).map(([t, x]) => [t, { turns: x.n, avgMs: x.n ? Math.round(x.ms / x.n) : 0 }])),
+      costUsd: r1(b.costUsd * 10) / 10,
+      costPerTurnUsd: b.turns ? Math.round((b.costUsd / b.turns) * 10000) / 10000 : 0,
+      walkerFailPct: pct(b.walkerFailed, b.turns - b.gated),
+      autoKept: b.autoKept,
+      autoDropped: b.autoDropped,
+    });
+  }
+  rows.sort((a, b) => (a.from || "").localeCompare(b.from || ""));
+  return rows;
+}
+
+function trend() { return metrics.readKpi(); }
+
+// ── text table (CLI) ──────────────────────────────────────────────────
+function renderTable(rows) {
+  if (!rows.length) return "No recall telemetry yet.";
+  const cols = [
+    ["version", (r) => r.v],
+    ["turns", (r) => String(r.turns)],
+    ["rescue", (r) => (r.rescuePct == null ? "—" : r.rescuePct + "%")],
+    ["noise", (r) => (r.noisePct == null ? "—" : r.noisePct + "%")],
+    ["avg", (r) => (r.avgLatencyMs / 1000).toFixed(1) + "s"],
+    ["gated", (r) => (r.gatedPct == null ? "—" : r.gatedPct + "%")],
+    ["$ / turn", (r) => "$" + r.costPerTurnUsd.toFixed(3)],
+    ["cascade", (r) => (r.autoKept || r.autoDropped ? `${r.autoKept}/${r.autoDropped}` : "—")],
+    ["walker-fail", (r) => (r.walkerFailPct == null ? "—" : r.walkerFailPct + "%")],
+    ["window", (r) => `${r.from}→${r.to}`],
+    ["models", (r) => r.models.join(",") || "—"],
+  ];
+  const widths = cols.map(([h, f]) => Math.max(h.length, ...rows.map((r) => f(r).length)));
+  const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
+  const out = [line(cols.map(([h]) => h)), line(widths.map((w) => "-".repeat(w)))];
+  for (const r of rows) out.push(line(cols.map(([, f]) => f(r))));
+  return out.join("\n");
+}
+
+// ── HTML report (inline SVG, no dependencies) ─────────────────────────
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" }[c]));
+const PALETTE = ["#4f8ef7", "#f7734f", "#3dbf7a", "#b06ef7", "#f0b429", "#e8618c", "#38bdc8"];
+
+function barChart(title, items, { fmt = (v) => String(v), max = null } = {}) {
+  const data = items.filter((i) => i.value != null && Number.isFinite(i.value));
+  if (!data.length) return "";
+  const W = 560, ROW = 30, LABEL = 150, PAD = 8;
+  const H = data.length * ROW + 34;
+  const top = max != null ? max : Math.max(...data.map((d) => d.value), 1e-9);
+  const bars = data.map((d, i) => {
+    const w = Math.max(2, Math.round((d.value / top) * (W - LABEL - 90)));
+    const y = 30 + i * ROW;
+    return `<text x="${LABEL - PAD}" y="${y + 15}" text-anchor="end" class="lb">${esc(d.label)}</text>` +
+      `<rect x="${LABEL}" y="${y + 3}" width="${w}" height="${ROW - 10}" rx="4" fill="${PALETTE[i % PALETTE.length]}"/>` +
+      `<text x="${LABEL + w + 6}" y="${y + 15}" class="vl">${esc(fmt(d.value))}</text>`;
+  }).join("");
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">` +
+    `<text x="0" y="16" class="tt">${esc(title)}</text>${bars}</svg>`;
+}
+
+function lineChart(title, series, { fmt = (v) => String(v) } = {}) {
+  const all = series.flatMap((s) => s.points.map((p) => p.y)).filter((y) => Number.isFinite(y));
+  const n = Math.max(...series.map((s) => s.points.length), 0);
+  if (!all.length || n < 2) return "";
+  const W = 560, H = 190, L = 46, B = 24, T = 26;
+  const top = Math.max(...all, 1e-9);
+  const x = (i) => L + (i / (n - 1)) * (W - L - 12);
+  const y = (v) => T + (1 - v / top) * (H - T - B);
+  const paths = series.map((s, si) => {
+    const pts = s.points.map((p, i) => `${x(i).toFixed(1)},${y(p.y).toFixed(1)}`).join(" ");
+    return `<polyline points="${pts}" fill="none" stroke="${PALETTE[si % PALETTE.length]}" stroke-width="2"/>`;
+  }).join("");
+  const legend = series.map((s, si) =>
+    `<circle cx="${L + si * 130}" cy="${H - 8}" r="4" fill="${PALETTE[si % PALETTE.length]}"/>` +
+    `<text x="${L + si * 130 + 9}" y="${H - 4}" class="lb">${esc(s.label)}</text>`).join("");
+  const grid = [0, 0.5, 1].map((f) =>
+    `<line x1="${L}" y1="${y(top * f)}" x2="${W - 12}" y2="${y(top * f)}" class="gr"/>` +
+    `<text x="${L - 5}" y="${y(top * f) + 4}" text-anchor="end" class="vl">${esc(fmt(top * f))}</text>`).join("");
+  return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg">` +
+    `<text x="0" y="16" class="tt">${esc(title)}</text>${grid}${paths}${legend}</svg>`;
+}
+
+function htmlReport() {
+  const rows = aggregate();
+  const snaps = trend().filter((s) => s.health && s.window && s.window.turns > 0);
+  const label = (r) => `${r.v} (${r.turns}t)`;
+  const charts = [
+    barChart("Graph rescue rate — % of judged turns where memory was saved by the graph, not keywords (higher = better transfer)",
+      rows.map((r) => ({ label: label(r), value: r.rescuePct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Noise — % of injected memories never opened or credited by the reviewer (lower is better)",
+      rows.map((r) => ({ label: label(r), value: r.noisePct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Average recall latency", rows.map((r) => ({ label: label(r), value: r.avgLatencyMs / 1000 })), { fmt: (v) => v.toFixed(1) + "s" }),
+    barChart("Recall cost per turn", rows.map((r) => ({ label: label(r), value: r.costPerTurnUsd })), { fmt: (v) => "$" + v.toFixed(3) }),
+    barChart("Gated turns — pleasantries skipped for free", rows.map((r) => ({ label: label(r), value: r.gatedPct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+    barChart("Walker failure rate", rows.map((r) => ({ label: label(r), value: r.walkerFailPct })), { fmt: (v) => Math.round(v) + "%", max: 100 }),
+  ].filter(Boolean).map((s) => `<div class="card">${s}</div>`).join("\n");
+
+  const trendChart = snaps.length >= 2 ? lineChart(
+    "Nightly trend (per dream window)",
+    [
+      { label: "rescue %", points: snaps.map((s) => ({ y: (s.health.rescueRate || 0) * 100 })) },
+      { label: "noise %", points: snaps.map((s) => ({ y: (s.health.noiseRate || 0) * 100 })) },
+      { label: "latency s", points: snaps.map((s) => ({ y: (s.health.avgLatencyMs || 0) / 1000 })) },
+    ],
+    { fmt: (v) => Math.round(v) }) : "";
+
+  const tierRows = rows.map((r) => {
+    const t = Object.entries(r.byTier).map(([k, v]) => `${k}: ${v.turns}× @ ${(v.avgMs / 1000).toFixed(1)}s`).join(" · ") || "—";
+    return `<tr><td>${esc(r.v)}</td><td>${esc(r.from)}→${esc(r.to)}</td><td>${r.turns}</td><td>${t}</td>` +
+      `<td>${r.opens} / ${r.reviewerUses}</td><td>${r.autoKept} / ${r.autoDropped}</td><td>${esc(r.models.join(", ") || "—")}</td></tr>`;
+  }).join("\n");
+
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Open Claudia — recall KPIs</title>
+<style>
+body{font-family:-apple-system,Segoe UI,Roboto,sans-serif;background:#101418;color:#e6edf3;margin:0;padding:24px;max-width:660px;margin:auto}
+h1{font-size:20px;margin:0 0 4px} .sub{color:#8b98a5;font-size:13px;margin-bottom:20px}
+.card{background:#161c23;border:1px solid #232c36;border-radius:10px;padding:14px;margin-bottom:14px}
+svg{width:100%;height:auto} .tt{fill:#e6edf3;font-size:12px;font-weight:600} .lb{fill:#aeb8c2;font-size:11px}
+.vl{fill:#8b98a5;font-size:10px} .gr{stroke:#232c36;stroke-width:1}
+table{width:100%;border-collapse:collapse;font-size:12px} td,th{padding:6px 8px;border-bottom:1px solid #232c36;text-align:left}
+th{color:#8b98a5;font-weight:600}
+</style></head><body>
+<h1>🧠 Open Claudia — recall KPIs by version</h1>
+<div class="sub">Generated ${new Date().toISOString().slice(0, 16).replace("T", " ")} · ${rows.reduce((a, r) => a + r.turns, 0)} recall turns · ${snaps.length} dream snapshot${snaps.length === 1 ? "" : "s"}</div>
+${charts}
+${trendChart ? `<div class="card">${trendChart}</div>` : ""}
+<div class="card"><table>
+<tr><th>version</th><th>window</th><th>turns</th><th>latency by tier</th><th>opens / reviewer</th><th>cascade kept / dropped</th><th>walker model</th></tr>
+${tierRows}
+</table></div>
+</body></html>`;
+}
+
+function writeHtmlReport(outPath) {
+  const p = outPath || require("path").join(require("../../config-dir"), "kpi-report.html");
+  fs.writeFileSync(p, htmlReport());
+  return p;
+}
+
+module.exports = { LEGACY_VERSION, aggregate, trend, renderTable, htmlReport, writeHtmlReport };

package/core/recall/metrics.js

@@ -10,50 +10,104 @@ const CONFIG_DIR = require("../../config-dir");
 
 const LOG_FILE = path.join(CONFIG_DIR, "recall-metrics.jsonl");
 const SUMMARY_FILE = path.join(CONFIG_DIR, "recall-metrics-summary.json");
+const NODE_STATS_FILE = path.join(CONFIG_DIR, "recall-node-stats.json");
+const KPI_FILE = path.join(CONFIG_DIR, "recall-kpi.jsonl");
+let VERSION = "";
+try { VERSION = require("../../package.json").version || ""; } catch (e) {}
 const MAX_OPEN_TRACK = 400; // recent turns kept to reconcile surfaced→opened
+const MAX_NODES = 800; // node-stats map cap; lowest-activity entries pruned past this
+const MAX_CO_RESCUE = 300;
 
 function enabled() {
   return String(process.env.RECALL_METRICS || "on").toLowerCase() !== "off";
 }
 
 // Record one recall turn. `entry`:
-//   { engine, query, seeds:[{id,score}], activated:[{id,activation,hop}],
-//     kept:[{id,why}], gated (bool), latencyMs, costUsd }
+//   { engine, query, tier, seeds:[{id,score}], activated:[{id,activation,hop}],
+//     cand:[{id,act}], kept:[{id,why}], auto:{kept:[],dropped:[],shadow:{checks,agree}},
+//     gated (bool), latencyMs, seedMs, expandMs, walkerMs,
+//     walker ("warm"|"cold"|"off"|"failed"), costUsd }
 function logTurn(entry) {
   if (!enabled()) return;
   try {
     const rec = {
       ts: new Date().toISOString(),
+      v: VERSION,
+      model: entry.model || "",
       engine: entry.engine || "discoverer",
       query: String(entry.query || "").slice(0, 200),
+      tier: entry.tier || "",
       seeds: (entry.seeds || []).map((s) => ({ id: s.id, score: s.score })),
       activated: (entry.activated || []).map((a) => ({ id: a.id, activation: round(a.activation), hop: a.hop })),
+      cand: (entry.cand || []).map((c) => ({ id: c.id, act: !!c.act })),
       kept: (entry.kept || []).map((k) => ({ id: k.id, why: String(k.why || "").slice(0, 200) })),
+      auto: entry.auto || null,
       gated: !!entry.gated,
       latencyMs: entry.latencyMs || 0,
+      seedMs: entry.seedMs || 0,
+      expandMs: entry.expandMs || 0,
+      walkerMs: entry.walkerMs || 0,
+      walker: entry.walker || "",
       costUsd: entry.costUsd || 0,
     };
     fs.appendFileSync(LOG_FILE, JSON.stringify(rec) + "\n");
     bumpSummary(rec);
+    bumpNodeStats(rec);
   } catch (e) {}
 }
 
-// Record which nodes were actually opened (📖) this turn. Matched against the
-// most recent surfaced sets to derive precision/noise without a second pass
-// over the whole log.
-function logUse(openedIds) {
+// Record which nodes were actually used this turn. Matched against the most
+// recent surfaced sets to derive precision/noise without a second pass over
+// the whole log. `source` distinguishes how use was observed: "" / undefined
+// for 📖 opens (agent explicitly read the note), "reviewer" for post-turn
+// reviewer adjudication (the turn's work updated that pack/entity).
+function logUse(openedIds, source) {
   if (!enabled()) return;
   const ids = [...new Set((openedIds || []).filter(Boolean))];
   if (!ids.length) return;
   try {
-    fs.appendFileSync(LOG_FILE, JSON.stringify({ ts: new Date().toISOString(), use: ids }) + "\n");
+    const rec = { ts: new Date().toISOString(), v: VERSION, use: ids };
+    if (source) rec.source = String(source);
+    fs.appendFileSync(LOG_FILE, JSON.stringify(rec) + "\n");
+    const s = readSummary();
+    if (source === "reviewer") s.reviewerUses = (s.reviewerUses || 0) + ids.length;
+    else s.opens = (s.opens || 0) + ids.length;
+    writeSummary(s);
+    const ns = readNodeStats();
+    for (const id of ids) {
+      const n = nodeEntry(ns, id);
+      if (source === "reviewer") n.rev = (n.rev || 0) + 1;
+      else n.open = (n.open || 0) + 1;
+      n.last = today();
+    }
+    writeNodeStats(ns);
+  } catch (e) {}
+}
+
+// One walker-cascade shadow sample compared: the deterministic verdict vs the
+// judge's. Divergence here is what tells the dream to distrust the cascade.
+function logShadow(agree) {
+  if (!enabled()) return;
+  try {
+    const s = readSummary();
+    s.shadowChecks = (s.shadowChecks || 0) + 1;
+    if (agree) s.shadowAgree = (s.shadowAgree || 0) + 1;
+    writeSummary(s);
+  } catch (e) {}
+}
+
+// Reviewer skip-gate fired: a turn deterministically judged not memory-worthy.
+function logReviewerSkip() {
+  if (!enabled()) return;
+  try {
     const s = readSummary();
-    s.opens = (s.opens || 0) + ids.length;
+    s.reviewerSkipped = (s.reviewerSkipped || 0) + 1;
     writeSummary(s);
   } catch (e) {}
 }
 
 function round(n) { return Math.round((Number(n) || 0) * 1000) / 1000; }
+function today() { return new Date().toISOString().slice(0, 10); }
 
 function readSummary() {
   try { return JSON.parse(fs.readFileSync(SUMMARY_FILE, "utf8")) || {}; } catch (e) { return {}; }
@@ -62,10 +116,84 @@ function writeSummary(s) {
   try { fs.writeFileSync(SUMMARY_FILE, JSON.stringify(s, null, 2)); } catch (e) {}
 }
 
+function readNodeStats() {
+  try { return JSON.parse(fs.readFileSync(NODE_STATS_FILE, "utf8")) || { nodes: {}, coRescue: {} }; }
+  catch (e) { return { nodes: {}, coRescue: {} }; }
+}
+function writeNodeStats(ns) {
+  try {
+    pruneNodeStats(ns);
+    ns.updatedAt = new Date().toISOString();
+    fs.writeFileSync(NODE_STATS_FILE, JSON.stringify(ns));
+  } catch (e) {}
+}
+function nodeEntry(ns, id) {
+  ns.nodes = ns.nodes || {};
+  if (!ns.nodes[id]) ns.nodes[id] = { seen: 0, act: 0, kept: 0, open: 0, rev: 0, resc: 0 };
+  return ns.nodes[id];
+}
+function pruneNodeStats(ns) {
+  const ids = Object.keys(ns.nodes || {});
+  if (ids.length > MAX_NODES) {
+    const scored = ids.map((id) => {
+      const n = ns.nodes[id];
+      return { id, w: (n.seen || 0) + (n.kept || 0) * 3 + (n.open || 0) * 3 + (n.rev || 0) * 3 };
+    }).sort((a, b) => a.w - b.w);
+    for (const { id } of scored.slice(0, ids.length - MAX_NODES)) delete ns.nodes[id];
+  }
+  const pairs = Object.entries(ns.coRescue || {});
+  if (pairs.length > MAX_CO_RESCUE) {
+    ns.coRescue = Object.fromEntries(pairs.sort((a, b) => b[1] - a[1]).slice(0, MAX_CO_RESCUE));
+  }
+}
+
+// Per-node rolling counters — the evidence base for the walker cascade
+// (keep-rates), negative Hebbian (activated-never-kept), and dream targeting.
+// seen = surfaced as a candidate; act = of those, arrived via graph expansion;
+// kept = walker/cascade kept it; open/rev = actually used; resc = kept without
+// a seed match (graph rescue).
+function bumpNodeStats(rec) {
+  if (rec.gated) return;
+  const ns = readNodeStats();
+  const keptIds = new Set(rec.kept.map((k) => k.id));
+  const seedIds = new Set(rec.seeds.map((x) => x.id));
+  const candList = rec.cand && rec.cand.length
+    ? rec.cand
+    : [...rec.seeds.map((s) => ({ id: s.id, act: false })), ...rec.activated.map((a) => ({ id: a.id, act: true }))];
+  const seenIds = new Set();
+  for (const c of candList) {
+    if (seenIds.has(c.id) || c.id.startsWith("episode:")) continue;
+    seenIds.add(c.id);
+    const n = nodeEntry(ns, c.id);
+    n.seen++;
+    if (c.act) n.act++;
+    if (keptIds.has(c.id)) n.kept++;
+    n.last = today();
+  }
+  const rescued = [];
+  for (const k of rec.kept) {
+    if (k.id.startsWith("episode:")) continue;
+    if (!seenIds.has(k.id)) { const n = nodeEntry(ns, k.id); n.seen++; n.kept++; n.last = today(); }
+    if (!seedIds.has(k.id)) { nodeEntry(ns, k.id).resc++; rescued.push(k.id); }
+  }
+  // Co-rescue pairs: nodes repeatedly rescued together are missing a direct
+  // edge — the dream adds one deterministically past a threshold.
+  rescued.sort();
+  ns.coRescue = ns.coRescue || {};
+  for (let i = 0; i < rescued.length; i++) {
+    for (let j = i + 1; j < rescued.length; j++) {
+      const key = `${rescued[i]}|${rescued[j]}`;
+      ns.coRescue[key] = (ns.coRescue[key] || 0) + 1;
+    }
+  }
+  writeNodeStats(ns);
+}
+
 function bumpSummary(rec) {
   const s = readSummary();
   s.turns = (s.turns || 0) + 1;
   if (rec.gated) s.gatedTurns = (s.gatedTurns || 0) + 1;
+  if (rec.tier === "seeds") s.seedsOnlyTurns = (s.seedsOnlyTurns || 0) + 1;
   s.seedsTotal = (s.seedsTotal || 0) + rec.seeds.length;
   s.activatedTotal = (s.activatedTotal || 0) + rec.activated.length;
   s.keptTotal = (s.keptTotal || 0) + rec.kept.length;
@@ -75,6 +203,16 @@ function bumpSummary(rec) {
   if (rescues > 0) { s.rescueTurns = (s.rescueTurns || 0) + 1; s.rescues = (s.rescues || 0) + rescues; }
   s.costUsd = round((s.costUsd || 0) + (rec.costUsd || 0));
   s.latencyMsTotal = (s.latencyMsTotal || 0) + (rec.latencyMs || 0);
+  if (rec.tier) {
+    s.byTier = s.byTier || {};
+    const t = s.byTier[rec.tier] || { n: 0, ms: 0 };
+    t.n++; t.ms += rec.latencyMs || 0;
+    s.byTier[rec.tier] = t;
+  }
+  if (rec.auto) {
+    s.autoKept = (s.autoKept || 0) + ((rec.auto.kept || []).length);
+    s.autoDropped = (s.autoDropped || 0) + ((rec.auto.dropped || []).length);
+  }
   s.updatedAt = new Date().toISOString();
   writeSummary(s);
 }
@@ -88,6 +226,8 @@ function summary() {
     turns,
     gatedTurns: s.gatedTurns || 0,
     gatedPct: fmtPct(s.gatedTurns || 0, turns),
+    seedsOnlyTurns: s.seedsOnlyTurns || 0,
+    seedsOnlyPct: fmtPct(s.seedsOnlyTurns || 0, turns),
     avgSeeds: turns ? round((s.seedsTotal || 0) / turns) : 0,
     avgActivated: turns ? round((s.activatedTotal || 0) / turns) : 0,
     avgKept: turns ? round((s.keptTotal || 0) / turns) : 0,
@@ -95,15 +235,82 @@ function summary() {
     rescuePct: fmtPct(s.rescueTurns || 0, turns),
     rescues: s.rescues || 0,
     opens: s.opens || 0,
+    reviewerUses: s.reviewerUses || 0,
+    reviewerSkipped: s.reviewerSkipped || 0,
+    autoKept: s.autoKept || 0,
+    autoDropped: s.autoDropped || 0,
+    shadowChecks: s.shadowChecks || 0,
+    shadowAgreePct: fmtPct(s.shadowAgree || 0, s.shadowChecks || 0),
+    byTier: Object.fromEntries(Object.entries(s.byTier || {}).map(([t, v]) => [t, { turns: v.n, avgMs: v.n ? Math.round(v.ms / v.n) : 0 }])),
     avgLatencyMs: turns ? Math.round((s.latencyMsTotal || 0) / turns) : 0,
     costUsd: s.costUsd || 0,
     updatedAt: s.updatedAt || "",
   };
 }
 
+function nodeStats() { return readNodeStats(); }
+
+// Dream-facing evidence pack: raw summary (for windowed deltas against a prior
+// snapshot) plus targeted node lists the consolidation/tuning passes act on.
+function evidence({ minSeen = 6, coRescueMin = 3 } = {}) {
+  const s = readSummary();
+  const ns = readNodeStats();
+  const nodes = ns.nodes || {};
+  const neverKept = [];
+  const highKeep = [];
+  const topRescued = [];
+  for (const [id, n] of Object.entries(nodes)) {
+    const used = (n.open || 0) + (n.rev || 0);
+    if ((n.seen || 0) >= minSeen && (n.kept || 0) === 0 && used === 0) {
+      neverKept.push({ id, seen: n.seen, act: n.act || 0 });
+    }
+    if ((n.seen || 0) >= 5 && (n.kept || 0) / n.seen >= 0.8 && used >= 1) {
+      highKeep.push({ id, seen: n.seen, kept: n.kept, used });
+    }
+    if ((n.resc || 0) >= 2) topRescued.push({ id, rescues: n.resc });
+  }
+  neverKept.sort((a, b) => b.seen - a.seen);
+  topRescued.sort((a, b) => b.rescues - a.rescues);
+  const coRescuePairs = Object.entries(ns.coRescue || {})
+    .filter(([, n]) => n >= coRescueMin)
+    .map(([key, n]) => { const [a, b] = key.split("|"); return { a, b, n }; })
+    .sort((x, y) => y.n - x.n);
+  return {
+    summary: s,
+    neverKept: neverKept.slice(0, 25),
+    highKeep: highKeep.slice(0, 25),
+    topRescued: topRescued.slice(0, 15),
+    coRescuePairs: coRescuePairs.slice(0, 15),
+  };
+}
+
+// One version-stamped KPI snapshot per dream night. This is the durable
+// series `open-claudia kpi` aggregates to compare harness versions/models —
+// per-turn ground truth stays in LOG_FILE, this is the cheap nightly rollup.
+function appendKpi(snapshot) {
+  if (!enabled()) return;
+  try {
+    fs.appendFileSync(KPI_FILE, JSON.stringify({ ts: new Date().toISOString(), v: VERSION, ...snapshot }) + "\n");
+  } catch (e) {}
+}
+
+function readKpi() {
+  try {
+    return fs.readFileSync(KPI_FILE, "utf8").split("\n").filter(Boolean).map((l) => {
+      try { return JSON.parse(l); } catch (e) { return null; }
+    }).filter(Boolean);
+  } catch (e) { return []; }
+}
+
 function _resetForTest() {
   try { fs.rmSync(LOG_FILE, { force: true }); } catch (e) {}
   try { fs.rmSync(SUMMARY_FILE, { force: true }); } catch (e) {}
+  try { fs.rmSync(NODE_STATS_FILE, { force: true }); } catch (e) {}
+  try { fs.rmSync(KPI_FILE, { force: true }); } catch (e) {}
 }
 
-module.exports = { LOG_FILE, SUMMARY_FILE, enabled, logTurn, logUse, summary, _resetForTest };
+module.exports = {
+  LOG_FILE, SUMMARY_FILE, NODE_STATS_FILE, KPI_FILE, VERSION, enabled,
+  logTurn, logUse, logShadow, logReviewerSkip, appendKpi, readKpi,
+  summary, nodeStats, evidence, _resetForTest,
+};

package/core/recall/tuning.js

@@ -0,0 +1,125 @@
+// Dream-tunable recall knobs. The nightly dream is the ONLY writer; recall
+// paths read lazily (mtime-cached) so a knob change applies without a bot
+// restart. Every knob is hard-bounded here — a wild model proposal can never
+// push a value outside its safe range. Precedence: env var (operator pin)
+// > tuning file (dream) > default.
+
+const fs = require("fs");
+const path = require("path");
+const CONFIG_DIR = require("../../config-dir");
+
+const TUNING_FILE = path.join(CONFIG_DIR, "recall-tuning.json");
+const MAX_HISTORY = 40;
+
+// name -> { def, min, max, env } (numeric) or { def, values, env } (enum).
+const KNOBS = {
+  walkerMaxCandidates: { def: 14, min: 8, max: 20, env: "RECALL_WALKER_MAX_CANDIDATES" },
+  episodeLimit: { def: 3, min: 1, max: 5, env: "RECALL_EPISODE_LIMIT" },
+  seedsTierMaxWords: { def: 4, min: 2, max: 6, env: "RECALL_SEEDS_TIER_MAX_WORDS" },
+  decayHalfLifeDays: { def: 60, min: 10, max: 90, env: "RECALL_DECAY_HALF_LIFE_DAYS" },
+  cascade: { def: "on", values: ["on", "off"], env: "RECALL_CASCADE" },
+};
+
+let _cache = null;
+let _cacheMtime = -1;
+
+function readFile() {
+  let mtime = 0;
+  try { mtime = fs.statSync(TUNING_FILE).mtimeMs; } catch (e) { mtime = 0; }
+  if (_cache && mtime === _cacheMtime) return _cache;
+  let data = {};
+  try { data = JSON.parse(fs.readFileSync(TUNING_FILE, "utf8")) || {}; } catch (e) { data = {}; }
+  _cache = data;
+  _cacheMtime = mtime;
+  return data;
+}
+
+function clampKnob(name, value) {
+  const spec = KNOBS[name];
+  if (!spec) return null;
+  if (spec.values) {
+    const v = String(value).toLowerCase();
+    return spec.values.includes(v) ? v : spec.def;
+  }
+  const n = Number(value);
+  if (!Number.isFinite(n)) return spec.def;
+  return Math.min(spec.max, Math.max(spec.min, n));
+}
+
+// Effective value of a knob, honouring env pin > tuning file > default.
+function get(name) {
+  const spec = KNOBS[name];
+  if (!spec) return undefined;
+  if (spec.env && process.env[spec.env] !== undefined && process.env[spec.env] !== "") {
+    return clampKnob(name, process.env[spec.env]);
+  }
+  const data = readFile();
+  if (data.knobs && data.knobs[name] !== undefined) return clampKnob(name, data.knobs[name]);
+  return spec.def;
+}
+
+function knobTable() {
+  return Object.entries(KNOBS).map(([name, spec]) => ({
+    name,
+    current: get(name),
+    default: spec.def,
+    min: spec.min,
+    max: spec.max,
+    values: spec.values,
+    pinned: !!(spec.env && process.env[spec.env]),
+  }));
+}
+
+// Dream-only writer. Applies ONE bounded change with provenance; returns the
+// applied {knob, from, to} or null when rejected (unknown knob / no-op / env-pinned).
+function set(name, value, { reason = "", evidence = "" } = {}) {
+  const spec = KNOBS[name];
+  if (!spec) return null;
+  if (spec.env && process.env[spec.env]) return null; // operator pin wins — don't fight it
+  const from = get(name);
+  const to = clampKnob(name, value);
+  if (to === from) return null;
+  const data = readFile();
+  data.knobs = data.knobs || {};
+  data.knobs[name] = to;
+  data.history = data.history || [];
+  data.history.push({ ts: new Date().toISOString(), knob: name, from, to, reason: String(reason).slice(0, 300), evidence: String(evidence).slice(0, 300) });
+  data.history = data.history.slice(-MAX_HISTORY);
+  write(data);
+  return { knob: name, from, to };
+}
+
+// Revert the most recent change of a knob (auto-rollback path).
+function revert(name, { reason = "" } = {}) {
+  const data = readFile();
+  if (!data.knobs || data.knobs[name] === undefined) return null;
+  const hist = (data.history || []).filter((h) => h.knob === name);
+  const last = hist[hist.length - 1];
+  if (!last) return null;
+  const from = data.knobs[name];
+  data.knobs[name] = clampKnob(name, last.from);
+  data.history.push({ ts: new Date().toISOString(), knob: name, from, to: data.knobs[name], reason: `rollback: ${reason}`.slice(0, 300) });
+  data.history = data.history.slice(-MAX_HISTORY);
+  write(data);
+  return { knob: name, from, to: data.knobs[name] };
+}
+
+function lastChange() {
+  const data = readFile();
+  const hist = (data.history || []).filter((h) => !/^rollback:/.test(h.reason || ""));
+  return hist[hist.length - 1] || null;
+}
+
+function history() { return readFile().history || []; }
+
+function write(data) {
+  try { fs.writeFileSync(TUNING_FILE, JSON.stringify(data, null, 2)); } catch (e) {}
+  _cache = null; _cacheMtime = -1;
+}
+
+function _resetForTest() {
+  try { fs.rmSync(TUNING_FILE, { force: true }); } catch (e) {}
+  _cache = null; _cacheMtime = -1;
+}
+
+module.exports = { TUNING_FILE, KNOBS, get, set, revert, lastChange, history, knobTable, clampKnob, _resetForTest };