mover-os 4.7.7 → 4.7.8

package/src/dashboard/lib/library-indexer.js

@@ -0,0 +1,105 @@
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+const {
+  libraryDir,
+  libraryCheatsheetsDir,
+  libraryPrinciplesDir,
+  librarySopsDir,
+  libraryEntitiesDir,
+  libraryEntitiesPeopleDir,
+  libraryEntitiesOrgsDir,
+  libraryEntitiesPlacesDir,
+  libraryEntitiesDecisionsDir,
+  libraryInputsDir,
+  libraryScriptsDir,
+  libraryMocsDir,
+  safeListDir,
+  safeStat,
+  exists
+} = require("./paths");
+
+// Index 03_Library/* — counts + recent items per subdirectory.
+
+function indexLibrary(vault) {
+  if (!exists(libraryDir(vault))) return { available: false };
+
+  const sections = [
+    { name: "Cheatsheets", dir: libraryCheatsheetsDir(vault) },
+    { name: "Principles", dir: libraryPrinciplesDir(vault) },
+    { name: "SOPs", dir: librarySopsDir(vault) },
+    { name: "MOCs", dir: libraryMocsDir(vault) },
+    { name: "Scripts", dir: libraryScriptsDir(vault) }
+  ];
+
+  const out = { available: true, sections: [], recent: [], counts: { total: 0 } };
+
+  for (const sec of sections) {
+    if (!exists(sec.dir)) {
+      out.sections.push({ name: sec.name, count: 0, recent: [] });
+      continue;
+    }
+    const entries = walkMarkdown(sec.dir);
+    entries.sort((a, b) => b.mtime - a.mtime);
+    const recent = entries.slice(0, 3).map(e => ({
+      name: e.name.replace(/\.md$/, ""),
+      mtime: e.mtime,
+      ageDays: Math.floor((Date.now() - e.mtime) / 86400000)
+    }));
+    out.sections.push({ name: sec.name, count: entries.length, recent });
+    out.counts[sec.name.toLowerCase()] = entries.length;
+    out.counts.total += entries.length;
+  }
+
+  // Entities
+  const entitySubs = [
+    { name: "People", dir: libraryEntitiesPeopleDir(vault) },
+    { name: "Orgs", dir: libraryEntitiesOrgsDir(vault) },
+    { name: "Places", dir: libraryEntitiesPlacesDir(vault) },
+    { name: "Decisions", dir: libraryEntitiesDecisionsDir(vault) }
+  ];
+  out.entities = entitySubs.map(s => {
+    const entries = exists(s.dir) ? walkMarkdown(s.dir) : [];
+    entries.sort((a, b) => b.mtime - a.mtime);
+    return {
+      name: s.name,
+      count: entries.length,
+      recent: entries.slice(0, 5).map(e => ({
+        name: e.name.replace(/\.md$/, ""),
+        mtime: e.mtime,
+        ageDays: Math.floor((Date.now() - e.mtime) / 86400000)
+      }))
+    };
+  });
+
+  // Inputs (Articles, Books, Videos)
+  if (exists(libraryInputsDir(vault))) {
+    const inputSubs = safeListDir(libraryInputsDir(vault), { dirsOnly: true });
+    out.inputs = inputSubs.map(sub => {
+      const entries = walkMarkdown(sub.path);
+      return { name: sub.name, count: entries.length };
+    });
+  } else {
+    out.inputs = [];
+  }
+
+  return out;
+}
+
+function walkMarkdown(dir, depth = 0) {
+  if (depth > 3) return [];
+  const out = [];
+  const entries = safeListDir(dir);
+  for (const e of entries) {
+    if (e.isFile && e.name.endsWith(".md") && !e.name.startsWith("_")) {
+      const stat = safeStat(e.path);
+      if (stat) out.push({ name: e.name, path: e.path, mtime: stat.mtime.getTime() });
+    } else if (e.isDir && !e.name.startsWith("_") && !e.name.startsWith(".")) {
+      out.push(...walkMarkdown(e.path, depth + 1));
+    }
+  }
+  return out;
+}
+
+module.exports = { indexLibrary };

package/src/dashboard/lib/log-activation.sh

@@ -0,0 +1,61 @@
+#!/bin/bash
+# log-activation.sh — POSTs a V5.0 activation event to a running dashboard.
+#
+# Usage:
+#   log-activation.sh <event_type> [meta_json]
+#
+# Examples:
+#   log-activation.sh log_completed
+#   log-activation.sh referral_mentioned '{"source":"twitter"}'
+#   log-activation.sh onboarding_finished
+#
+# Exits silently (best-effort) if:
+#   - No token file at ~/.mover/dashboard/.token (server not running)
+#   - curl missing
+#   - HTTP failure
+#
+# Used by workflow Bash steps (log.md, capture.md, pivot-strategy.md)
+# and Stop hooks. Phase 41.0.7 of V5 backlog.
+
+set -e
+
+EVENT_TYPE="${1:-}"
+META="${2:-}"
+
+if [ -z "$EVENT_TYPE" ]; then
+  exit 0  # silent — no-op when invoked without args
+fi
+
+TOKEN_FILE="$HOME/.mover/dashboard/.token"
+if [ ! -f "$TOKEN_FILE" ]; then
+  exit 0  # silent — server not running
+fi
+
+# Extract token + url with minimal JSON parsing
+TOKEN=$(grep -o '"token"[[:space:]]*:[[:space:]]*"[^"]*"' "$TOKEN_FILE" | head -1 | sed 's/.*: *"//;s/"//')
+URL=$(grep -o '"url"[[:space:]]*:[[:space:]]*"[^"]*"' "$TOKEN_FILE" | head -1 | sed 's/.*: *"//;s/"//')
+
+if [ -z "$TOKEN" ] || [ -z "$URL" ]; then
+  exit 0
+fi
+
+# Build body
+if [ -n "$META" ]; then
+  BODY=$(printf '{"type":"%s","meta":%s}' "$EVENT_TYPE" "$META")
+else
+  BODY=$(printf '{"type":"%s"}' "$EVENT_TYPE")
+fi
+
+# Best-effort POST. Suppress all output — workflow logs shouldn't show this.
+# Timeout = 2s so a hung server can't stall a workflow.
+if command -v curl >/dev/null 2>&1; then
+  curl -s -m 2 \
+    -X POST \
+    -H "Content-Type: application/json" \
+    -H "X-Mover-Token: $TOKEN" \
+    -H "Origin: $URL" \
+    -d "$BODY" \
+    "$URL/api/event" >/dev/null 2>&1 || true
+fi
+
+exit 0

package/src/dashboard/lib/memory-curator.js

@@ -0,0 +1,97 @@
+"use strict";
+
+// memory-curator.js — Mover memory engine, Layer 5 (curator lifecycle + reflection loop).
+//
+// curate(): ages every indexed session active -> stale (30d) -> archived (90d) and decays its
+//   trust so recall naturally favours fresh context. It NEVER deletes — old sessions stay
+//   searchable, just lower-weighted (the Curator pattern: forget gracefully, lose nothing).
+//
+// reflect(): drafts the DATA half of /analyse-day from the index (recent arcs + trending
+//   entities) for the owner to ENGAGE with. Auto-analysis nobody reads is theatre — the
+//   judgment half stays human. Writes nothing.
+
+const fs = require("fs");
+const path = require("path");
+const { moverDir, safeReadJson } = require("./paths");
+const { parseSessionLogs } = require("./session-log-parser");
+
+const MEM_DIR = process.env.MOVER_MEMORY_DIR || path.join(moverDir(), "memory");
+const SEG_DIR = path.join(MEM_DIR, "segments");
+const MANIFEST = path.join(MEM_DIR, "manifest.json");
+
+const ACTIVE_DAYS = 30, ARCHIVE_DAYS = 90;
+const TRUST = { active: 1.0, stale: 0.85, archived: 0.6 };
+
+function loadManifest() { return safeReadJson(MANIFEST); }
+function loadSeg(n) { return safeReadJson(path.join(SEG_DIR, n + ".json")); }
+function atomicWrite(file, obj) { const t = file + ".tmp"; fs.writeFileSync(t, JSON.stringify(obj)); fs.renameSync(t, file); }
+
+function tier(ts) {
+  const t = ts ? Date.parse(ts) : NaN;
+  if (!Number.isFinite(t)) return "active";
+  const days = (Date.now() - t) / 86400000;
+  if (days > ARCHIVE_DAYS) return "archived";
+  if (days > ACTIVE_DAYS) return "stale";
+  return "active";
+}
+
+// Age sessions + write trust weights into the manifest (consumed by memory-index query()).
+function curate(opts = {}) {
+  const man = loadManifest();
+  if (!man) return { available: false, active: 0, stale: 0, archived: 0, adjusted: 0, written: 0 };
+  man.trust = man.trust || {};
+  const counts = { active: 0, stale: 0, archived: 0 };
+  let adjusted = 0;
+  for (const seg of (man.segments || []).filter((s) => s.startsWith("raw-"))) {
+    const s = loadSeg(seg);
+    if (!s) continue;
+    for (const id in s.docs) {
+      const tr = tier(s.docs[id].ts);
+      counts[tr]++;
+      const w = TRUST[tr];
+      if (w !== 1.0) {
+        if (man.trust[id] !== w) { man.trust[id] = w; adjusted++; }
+      } else if (man.trust[id] != null && man.trust[id] !== 1.0) {
+        delete man.trust[id]; adjusted++; // a session refreshed back into the active window
+      }
+    }
+  }
+  man.curatedAt = new Date().toISOString();
+  atomicWrite(MANIFEST, man);
+  return { available: true, ...counts, adjusted, total: counts.active + counts.stale + counts.archived, written: adjusted };
+}
+
+// Draft a reflection from the index: recent arcs + entities trending across sessions.
+function reflect(opts = {}) {
+  const man = loadManifest();
+  if (!man) return { available: false, draft: "", trendingEntities: [], recentArcs: [], written: 0 };
+  const N = Object.keys(man.indexedSessions || {}).length || 1;
+
+  const trendingEntities = Object.keys(man.linkFreq || {})
+    .map((note) => { const f = man.linkFreq[note]; const idf = Math.log(N / Math.max(1, f)); return { note, sessions: f, score: +(f * idf).toFixed(2) }; })
+    .filter((x) => x.sessions / N <= 0.6) // drop the ubiquitous (Engine files etc.)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, opts.limit || 10);
+
+  let recentArcs = [];
+  try {
+    const vault = opts.vault || man.vault;
+    if (vault) recentArcs = parseSessionLogs(vault).docs.slice(0, 8).map((d) => ({ date: d.date, title: d.title }));
+  } catch {}
+
+  const lines = ["## Reflection (auto-draft — engage with it, don't just read it)", ""];
+  if (recentArcs.length) { lines.push("Recent arcs:"); recentArcs.forEach((a) => lines.push(`- ${a.date} — ${a.title}`)); lines.push(""); }
+  if (trendingEntities.length) { lines.push("Entities trending across your sessions:"); trendingEntities.forEach((t) => lines.push(`- [[${t.note}]] (${t.sessions} sessions)`)); lines.push(""); }
+  lines.push("What pattern is forming? What's the one decision to make next? (your call — this is the /analyse-day judgment half.)");
+
+  return { available: true, draft: lines.join("\n"), trendingEntities, recentArcs, written: 0 };
+}
+
+module.exports = { curate, reflect, MEM_DIR };
+
+// ── CLI ──
+if (require.main === module) {
+  const vault = require("./paths").resolveVault();
+  console.log("curate:", JSON.stringify(curate()));
+  console.log("\n" + reflect({ vault }).draft);
+}

package/src/dashboard/lib/memory-gardener.js

@@ -0,0 +1,177 @@
+"use strict";
+
+// memory-gardener.js — Mover memory engine, Layer 2 (the differentiator / the moat).
+//
+// Memory's job is to GROW the vault graph; recall is the side effect. The gardener reads the
+// index + re-reads recent sessions and PROPOSES two kinds of growth:
+//   1. link  — rare (high-IDF) existing notes worth wiring into the graph (the connections
+//              you never got around to drawing). IDF buries ubiquitous Engine files.
+//   2. stub  — recurring NEW entities (people/projects/concepts) mentioned across sessions
+//              that have NO note yet — candidates for a Library/Entities stub.
+//
+// IT NEVER WRITES TO THE VAULT. Every proposal is owner-gated (written:0, gated:true). The
+// compounding growth — drawn only with your approval — is the data-gravity moat: it can only
+// accrue inside your vault, so a competitor can't ship it.
+
+const fs = require("fs");
+const path = require("path");
+const { buildVocab, STOPWORDS } = require("./memory-text");
+const { enumerateSessions, parseTranscript } = require("./transcript-parser");
+const { moverDir, safeReadJson } = require("./paths");
+
+const MEM_DIR = process.env.MOVER_MEMORY_DIR || path.join(moverDir(), "memory");
+
+// Leading words that signal a non-entity Title-Case phrase ("The Standing", "Single Test").
+const STUB_LEAD_STOP = new Set([
+  "the", "this", "that", "these", "those", "single", "active", "mover", "phase",
+  "session", "daily", "weekly", "strategy", "engine", "library", "project", "your", "our",
+]);
+
+// Mover/Claude/system boilerplate that recurs in transcripts (CLAUDE.md headers, /log
+// summary sections, compaction scaffolding) but is NEVER a real entity. Exact lowercased
+// match. Without this the stub heuristic drowns in "Final Output" / "Solutions Ledger" noise.
+const STUB_DENY = new Set([
+  "final output", "rules loaded", "risk tier", "global rules", "experiment loop",
+  "solutions ledger", "primary request", "key technical concepts", "code sections",
+  "problem solving", "session log", "active context", "daily note", "execution log",
+  "engine health", "pattern manifest", "single test", "session start", "user prompt",
+  "tool use", "session id", "pre flight", "key accomplishments", "still pending",
+  "strategic redirect", "files updated", "remaining today", "engine writer",
+  "claude code", "mover os", "system state", "agent notes", "next milestone",
+]);
+
+// Frequent English words. A Title-Case candidate whose words are ALL common is a generic
+// header ("Deep Research", "Current Work", "Pending Tasks"), not an entity. Real entities
+// (people/orgs/products) carry at least one uncommon/proper word ("Jane Doe", "Acme Corp").
+const COMMON_WORDS = new Set((
+  "pending tasks current work optional next step deep research market tool selection first " +
+  "search broad survey verify library experiment runner parallel agents orchestrator final " +
+  "output key technical concepts code sections problem solving primary request summary context " +
+  "state system notes report analysis review plan build fix update change result status error " +
+  "test check phase mode risk level gap flag item list set type value data file path line block " +
+  "group stage round batch pass run call view page card panel board grid chart label title header " +
+  "footer menu button field form input query index score count total rate time date day week month " +
+  "year today now recent latest real full main core base top end start open close done new old big " +
+  "small high low more less all both each every some many few next last first second third final " +
+  "good bad best worst fast slow hard easy clear clean quick deep wide long short live dead working " +
+  "session daily weekly monthly project task goal idea note step move thing stuff part piece bit"
+).split(/\s+/).filter(Boolean));
+
+function loadManifest() { return safeReadJson(path.join(MEM_DIR, "manifest.json")); }
+function loadSeg(name) { return safeReadJson(path.join(MEM_DIR, "segments", name + ".json")); }
+
+// LINK proposals — rare existing notes (high IDF) referenced in sessions, worth connecting.
+// Ubiquitous notes (in > maxFreqRatio of sessions) are dropped: they're noise, not signal.
+function proposeLinks(opts = {}) {
+  const man = loadManifest();
+  if (!man) return { available: false, proposals: [], written: 0, gated: true };
+  const N = Object.keys(man.indexedSessions || {}).length || 1;
+  const maxFreqRatio = opts.maxFreqRatio != null ? opts.maxFreqRatio : 0.5;
+  const minIdf = opts.minIdf != null ? opts.minIdf : 0.5;
+
+  // note -> set of sessions that mention it (from the raw segments' stored candidateLinks).
+  const noteSessions = Object.create(null);
+  for (const seg of (man.segments || []).filter((s) => s.startsWith("raw-"))) {
+    const s = loadSeg(seg);
+    if (!s) continue;
+    for (const id in s.docs) {
+      const d = s.docs[id];
+      const links = (d.meta && d.meta.candidateLinks) || [];
+      const sid = (d.meta && d.meta.sessionId) || id;
+      for (const note of new Set(links)) {
+        (noteSessions[note] || (noteSessions[note] = new Set())).add(sid);
+      }
+    }
+  }
+
+  const proposals = [];
+  for (const note in noteSessions) {
+    const freq = man.linkFreq[note] != null ? man.linkFreq[note] : noteSessions[note].size;
+    if (freq / N > maxFreqRatio) continue; // ubiquitous → skip
+    const idf = Math.log(N / Math.max(1, freq));
+    if (idf < minIdf) continue;
+    proposals.push({
+      type: "link", note, idf: +idf.toFixed(2), sessions: [...noteSessions[note]].slice(0, 5),
+      suggestion: `Link [[${note}]] — referenced in ${freq} session(s) but likely under-connected in the graph.`,
+    });
+  }
+  proposals.sort((a, b) => b.idf - a.idf);
+  return { available: true, proposals: proposals.slice(0, opts.limit || 25), written: 0, gated: true };
+}
+
+// STUB proposals — recurring Title-Case entities that have NO existing note. Re-reads recent
+// sessions (original case) and counts candidates across sessions; proposes those seen in
+// >= minSessions distinct sessions. Heuristic on purpose — the owner gates every creation.
+async function proposeStubs(opts = {}) {
+  const man = loadManifest();
+  const vault = opts.vault || (man && man.vault);
+  if (!vault) return { available: false, proposals: [], written: 0, gated: true };
+
+  const vocab = buildVocab(vault);
+  const known = new Set(vocab.entries.map((e) => e.lower));
+  const sessions = enumerateSessions(opts.projectsDir).slice(0, opts.scan || 40);
+
+  const TITLE = /\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,2})\b/g;
+  const sessionCount = Object.create(null); // lower -> # sessions
+  const display = Object.create(null);      // lower -> first display form
+
+  for (const s of sessions) {
+    const r = await parseTranscript(s.file, {});
+    if (r.error) continue;
+    const seenHere = new Set();
+    let m; TITLE.lastIndex = 0;
+    while ((m = TITLE.exec(r.sampleText)) !== null) {
+      const phrase = m[1].trim();
+      const lower = phrase.toLowerCase();
+      if (known.has(lower)) continue;                          // already a note
+      if (STUB_DENY.has(lower)) continue;                      // system boilerplate
+      const w = lower.split(/\s+/);
+      if (STUB_LEAD_STOP.has(w[0])) continue;                  // "The Standing", "Single Test"…
+      if (w.every((x) => STOPWORDS.has(x))) continue;
+      if (w.every((x) => COMMON_WORDS.has(x) || STOPWORDS.has(x))) continue; // all-common header
+      if (seenHere.has(lower)) continue;
+      seenHere.add(lower);
+      sessionCount[lower] = (sessionCount[lower] || 0) + 1;
+      if (!display[lower]) display[lower] = phrase;
+    }
+  }
+
+  const minSessions = opts.minSessions || 2;
+  const proposals = Object.keys(sessionCount)
+    .filter((k) => sessionCount[k] >= minSessions)
+    .map((k) => ({
+      type: "stub", name: display[k], sessions: sessionCount[k],
+      suggestion: `No note for "${display[k]}" (seen in ${sessionCount[k]} sessions) — create a Library/Entities stub?`,
+    }))
+    .sort((a, b) => b.sessions - a.sessions);
+
+  return { available: true, proposals: proposals.slice(0, opts.limit || 25), written: 0, gated: true };
+}
+
+// Pretty one-block render for the owner to approve/reject (display only — no writes).
+function renderProposals(links, stubs) {
+  const out = [];
+  if (links && links.proposals.length) {
+    out.push("LINKS worth drawing (rare, high-signal — IDF-ranked):");
+    for (const p of links.proposals.slice(0, 12)) out.push(`  • [[${p.note}]] (idf ${p.idf}, ${p.sessions.length} sessions)`);
+  }
+  if (stubs && stubs.proposals.length) {
+    out.push("STUBS for entities with no home:");
+    for (const p of stubs.proposals.slice(0, 12)) out.push(`  • ${p.name} (${p.sessions} sessions)`);
+  }
+  if (!out.length) out.push("Nothing to garden — the graph is current.");
+  return out.join("\n");
+}
+
+module.exports = { proposeLinks, proposeStubs, renderProposals, MEM_DIR };
+
+// ── CLI ──
+if (require.main === module) {
+  (async () => {
+    const vault = require("./paths").resolveVault();
+    const links = proposeLinks({ vault });
+    const stubs = await proposeStubs({ vault });
+    if (process.argv.includes("--json")) console.log(JSON.stringify({ links, stubs }, null, 2));
+    else console.log(renderProposals(links, stubs));
+  })();
+}

package/src/dashboard/lib/memory-gepa.js

@@ -0,0 +1,102 @@
+"use strict";
+
+// memory-gepa.js — Mover memory engine, Layer 6 (GEPA: trace-based self-improvement).
+//
+// The flagship Hermes feature, reachable ONLY because the jsonl is a real trace corpus.
+// Skills/workflows fail leaving evidence in the transcript (tool errors, retries). GEPA
+// clusters those failure traces across sessions and PROPOSES targeted fixes — so the system
+// learns WHY it failed, not just that it did. Every proposal is human-PR gated; GEPA never
+// edits a skill, workflow, or rule on its own (written:0, gated:true).
+
+const path = require("path");
+const { moverDir, safeReadJson } = require("./paths");
+
+const MEM_DIR = process.env.MOVER_MEMORY_DIR || path.join(moverDir(), "memory");
+const SEG_DIR = path.join(MEM_DIR, "segments");
+
+function loadManifest() { return safeReadJson(path.join(MEM_DIR, "manifest.json")); }
+function loadSeg(n) { return safeReadJson(path.join(SEG_DIR, n + ".json")); }
+
+// Collapse an error string to a stable signature so the same failure clusters across sessions
+// even when the volatile parts (ids, paths, ports, hex) differ.
+function normalizeError(e) {
+  return String(e || "").toLowerCase()
+    .replace(/0x[0-9a-f]+/g, "0x#")
+    .replace(/\b\d+\b/g, "#")
+    .replace(/\/[^\s"']+/g, "/path")
+    .replace(/\s+/g, " ").trim().slice(0, 90);
+}
+
+// Cluster recurring runtime failures from the index and propose fixes (gated). A failure that
+// recurs in >= minSessions distinct sessions is a pattern worth fixing; a one-off is noise.
+function analyzeFailures(opts = {}) {
+  const man = loadManifest();
+  if (!man) return { available: false, proposals: [], written: 0, gated: true };
+
+  const sigSessions = Object.create(null);    // signature -> Set(sessionId)
+  const sigSample = Object.create(null);      // signature -> first raw sample
+  const sigCmdSessions = Object.create(null); // signature -> { command -> Set(sessionId) } — C1 attribution
+  for (const seg of (man.segments || []).filter((s) => s.startsWith("raw-"))) {
+    const s = loadSeg(seg);
+    if (!s) continue;
+    for (const id in s.docs) {
+      const d = s.docs[id];
+      const errs = (d.meta && d.meta.errors) || [];
+      const sid = (d.meta && d.meta.sessionId) || id;
+      // ONE workflow per session-doc (the command active at the session's last error). Counted
+      // per (signature, session) below so a session with N copies of the same error votes once.
+      const cmd = d.meta && d.meta.lastCommand;
+      for (const e of errs) {
+        const sig = normalizeError(e);
+        if (sig.length < 6) continue;
+        (sigSessions[sig] || (sigSessions[sig] = new Set())).add(sid);
+        if (!sigSample[sig]) sigSample[sig] = String(e).slice(0, 120);
+        if (cmd) {
+          const m = sigCmdSessions[sig] || (sigCmdSessions[sig] = Object.create(null));
+          (m[cmd] || (m[cmd] = new Set())).add(sid); // Set dedupes the same session voting twice
+        }
+      }
+    }
+  }
+
+  // Rank the workflows a signature failed under by DISTINCT-session count (most-implicated first),
+  // so a proposal can name WHICH workflow to fix — not just the bare error string.
+  function workflowsFor(sig) {
+    const m = sigCmdSessions[sig];
+    if (!m) return [];
+    return Object.keys(m)
+      .map((command) => ({ command, sessions: m[command].size }))
+      .sort((a, b) => b.sessions - a.sessions);
+  }
+
+  const minSessions = opts.minSessions || 2;
+  const proposals = Object.keys(sigSessions)
+    .filter((k) => sigSessions[k].size >= minSessions)
+    .map((k) => {
+      const workflows = workflowsFor(k);
+      const top = workflows[0];
+      return {
+        type: "fix", signature: k, sessions: sigSessions[k].size,
+        sessionIds: [...sigSessions[k]].slice(0, 5), sample: sigSample[k],
+        workflows, // C1→C2: which workflow(s) were running when it broke — names the thing to fix
+        suggestion: `Recurring failure across ${sigSessions[k].size} sessions: "${sigSample[k].replace(/\s+/g, " ").slice(0, 70)}". ` +
+          (top ? `Most often while running ${top.command} (×${top.sessions}). ` : "") +
+          `Read the traces, root-cause it, and propose a guard/fix (human-PR gated — GEPA does not auto-edit).`,
+      };
+    })
+    .sort((a, b) => b.sessions - a.sessions);
+
+  return { available: true, proposals: proposals.slice(0, opts.limit || 25), written: 0, gated: true };
+}
+
+module.exports = { analyzeFailures, normalizeError, MEM_DIR };
+
+// ── CLI ──
+if (require.main === module) {
+  const r = analyzeFailures({ minSessions: Number(process.argv[2]) || 3 });
+  console.log(`${r.proposals.length} recurring failure patterns (gated, human-PR review):\n`);
+  r.proposals.slice(0, 15).forEach((p) => {
+    const wf = p.workflows && p.workflows[0] ? `  ${p.workflows[0].command}` : "";
+    console.log(`  ×${p.sessions} sessions${wf}  ${p.sample.replace(/\s+/g, " ").slice(0, 80)}`);
+  });
+}