@jhizzard/termdeck 0.11.0 → 0.12.0

package/packages/client/public/graph.js

@@ -76,14 +76,19 @@
 
   // -------- State ----------------------------------------------------------
 
+  const GC = (typeof window !== 'undefined' && window.GraphControls) || null;
+
   const state = {
     mode: 'project', // 'project' | 'memory'
     project: null,
     memoryId: null,
     depth: 2,
-    nodes: [],
-    edges: [],
+    nodes: [],          // raw nodes from /api/graph/* — unfiltered
+    edges: [],          // raw edges from /api/graph/* — unfiltered
+    visibleNodes: [],   // post-filter, what the simulation sees
+    visibleEdges: [],
     activeKinds: new Set(Object.keys(EDGE_COLORS)),
+    controls: GC ? GC.defaultControls() : { hideIsolated: false, minDegree: 0, window: 'all', layout: 'force' },
     selectedNodeId: null,
     hoverNodeId: null,
     searchTerm: '',
@@ -172,6 +177,7 @@
       state.mode = 'project';
       state.project = project;
     }
+    if (GC) state.controls = GC.decodeControls(qs);
   }
 
   function writeUrlState() {
@@ -182,6 +188,7 @@
     } else if (state.project) {
       qs.set('project', state.project);
     }
+    if (GC) GC.encodeControls(qs, state.controls);
     const url = qs.toString() ? `?${qs.toString()}` : window.location.pathname;
     window.history.replaceState(null, '', url);
   }
@@ -259,6 +266,8 @@
     // node render all paint over each other after a mode/project switch.
     hideEmpty();
     clearGraphSvg();
+    state.rawNodes = [];
+    state.rawEdges = [];
     state.nodes = [];
     state.edges = [];
     setLoading('Loading graph…');
@@ -267,18 +276,18 @@
       if (state.mode === 'project' && state.project === '__all__') {
         data = await api('/api/graph/all');
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
         if (data.truncated) {
           showToast(
-            `Showing ${state.nodes.length} most-recent of ${data.totalAvailable} memories — narrow by project to see specific clusters.`,
+            `Showing ${state.rawNodes.length} most-recent of ${data.totalAvailable} memories — narrow by project to see specific clusters.`,
           );
         }
       } else if (state.mode === 'memory') {
         data = await api(`/api/graph/memory/${encodeURIComponent(state.memoryId)}?depth=${state.depth}`);
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
         // Use the root memory's project as the view's "current project" for
         // the legend / drawer / fallback color when nodes span projects.
         if (data.root && data.root.project) state.project = data.root.project;
@@ -287,19 +296,17 @@
         state.project = name;
         data = await api(`/api/graph/project/${encodeURIComponent(name)}`);
         if (data.enabled === false) return showDisabled(data);
-        state.nodes = data.nodes || [];
-        state.edges = data.edges || [];
+        state.rawNodes = data.nodes || [];
+        state.rawEdges = data.edges || [];
       }
       writeUrlState();
       hideLoading();
-      if (state.nodes.length === 0) {
+      if (state.rawNodes.length === 0) {
         showEmpty();
         return;
       }
       hideEmpty();
-      renderFilters();
-      renderGraph();
-      updateStats();
+      applyControlsAndRender();
     } catch (err) {
       // Even on error, drop the empty-state overlay so the failure message
       // shows alone instead of stacking on top of "No memories yet".
@@ -308,6 +315,35 @@
     }
   }
 
+  // Sprint 43 T1 — re-derive state.nodes/state.edges from the raw API result
+  // and the four user controls, then drive the existing render pipeline.
+  // Called after every fetch and after any control change.
+  function applyControlsAndRender() {
+    const raw = { nodes: state.rawNodes || [], edges: state.rawEdges || [] };
+    let visible;
+    if (GC) {
+      visible = GC.applyControls(raw.nodes, raw.edges, state.controls);
+    } else {
+      visible = { nodes: raw.nodes.slice(), edges: raw.edges.slice() };
+    }
+    state.nodes = visible.nodes;
+    state.edges = visible.edges;
+    renderFilters();
+    renderGraph();
+    updateStats();
+    updateControlStat(raw.nodes.length, visible.nodes.length);
+  }
+
+  function updateControlStat(total, visible) {
+    const el = document.getElementById('ctlVisibleStat');
+    if (!el) return;
+    if (total === visible) {
+      el.textContent = '';
+    } else {
+      el.textContent = `${visible} of ${total} visible`;
+    }
+  }
+
   // -------- Render --------------------------------------------------------
 
   function setLoading(msg) {
@@ -417,6 +453,48 @@
     svg().setAttribute('height', state.height);
   }
 
+  // Sprint 43 T1 — apply layout-specific forces to the simulation.
+  //   force        — forceCenter at midpoint (default).
+  //   hierarchical — forceY from BFS levels over directional edges (supersedes /
+  //                  caused_by / blocks). Roots float top, leaves drift down.
+  //   radial       — forceRadial centered at midpoint, radius from inverse
+  //                  degree (high degree → near center).
+  function applyLayoutForces(sim, nodes, links) {
+    const cx = state.width / 2;
+    const cy = state.height / 2;
+    const layout = (state.controls && state.controls.layout) || 'force';
+
+    sim.force('center', null);
+    sim.force('hier-y', null);
+    sim.force('hier-x', null);
+    sim.force('radial', null);
+
+    if (layout === 'hierarchical' && GC) {
+      const levels = GC.computeHierarchyLevels(state.nodes, state.edges);
+      let maxLevel = 0;
+      for (const v of levels.values()) if (v > maxLevel) maxLevel = v;
+      const denom = Math.max(1, maxLevel);
+      const top = state.height * 0.10;
+      const bottom = state.height * 0.90;
+      sim.force('hier-y', window.d3.forceY((d) => {
+        const lvl = levels.get(d.id) || 0;
+        return top + (lvl / denom) * (bottom - top);
+      }).strength(0.65));
+      sim.force('hier-x', window.d3.forceX(cx).strength(0.04));
+      return;
+    }
+
+    if (layout === 'radial' && GC) {
+      const deg = GC.computeDegrees(state.nodes, state.edges);
+      const rMax = Math.min(state.width, state.height) * 0.42;
+      const radiusFn = GC.radialRadiusFn(deg, rMax);
+      sim.force('radial', window.d3.forceRadial(radiusFn, cx, cy).strength(0.55));
+      return;
+    }
+
+    sim.force('center', window.d3.forceCenter(cx, cy));
+  }
+
   function renderGraph() {
     if (!window.d3) {
       setLoading('D3.js failed to load (CDN blocked?)');
@@ -441,10 +519,11 @@
     const sim = window.d3.forceSimulation(nodes)
       .force('link', window.d3.forceLink(links).id((d) => d.id).distance((l) => 60 + (1 - (l.weight ?? 0.5)) * 40))
       .force('charge', window.d3.forceManyBody().strength(-260))
-      .force('center', window.d3.forceCenter(state.width / 2, state.height / 2))
       .force('collide', window.d3.forceCollide().radius((d) => nodeRadius(d) + 4))
       .alphaDecay(0.02);
 
+    applyLayoutForces(sim, nodes, links);
+
     state.sim = sim;
 
     const rootSel = window.d3.select(root());
@@ -742,6 +821,41 @@
     });
     $('graphFit').addEventListener('click', () => fitToView());
 
+    // Sprint 43 T1 — graph view-controls. Hydrate input values from state, then
+    // wire change handlers that mutate state.controls + URL + re-render from
+    // the cached raw fetch so toggling is fast (no API round-trip).
+    const ctlHide = $('ctlHideIsolated');
+    const ctlMin = $('ctlMinDegree');
+    const ctlWin = $('ctlWindow');
+    const ctlLay = $('ctlLayout');
+    if (ctlHide) ctlHide.checked = !!state.controls.hideIsolated;
+    if (ctlMin) ctlMin.value = String(state.controls.minDegree || 0);
+    if (ctlWin) ctlWin.value = state.controls.window || 'all';
+    if (ctlLay) ctlLay.value = state.controls.layout || 'force';
+
+    function onControlChange() {
+      state.controls = (GC ? GC.normalizeControls(state.controls) : state.controls);
+      writeUrlState();
+      if ((state.rawNodes || []).length === 0) return;
+      applyControlsAndRender();
+    }
+    if (ctlHide) ctlHide.addEventListener('change', () => {
+      state.controls.hideIsolated = !!ctlHide.checked;
+      onControlChange();
+    });
+    if (ctlMin) ctlMin.addEventListener('change', () => {
+      state.controls.minDegree = parseInt(ctlMin.value, 10) || 0;
+      onControlChange();
+    });
+    if (ctlWin) ctlWin.addEventListener('change', () => {
+      state.controls.window = ctlWin.value;
+      onControlChange();
+    });
+    if (ctlLay) ctlLay.addEventListener('change', () => {
+      state.controls.layout = ctlLay.value;
+      onControlChange();
+    });
+
     $('gdClose').addEventListener('click', closeDrawer);
     $('gdExpand').addEventListener('click', () => {
       if (!state.selectedNodeId) return;
@@ -763,7 +877,9 @@
     window.addEventListener('resize', () => {
       sizeStage();
       if (state.sim) {
-        state.sim.force('center', window.d3.forceCenter(state.width / 2, state.height / 2));
+        // Re-apply layout-specific forces with the new dimensions; this
+        // handles all three layouts (force / hierarchical / radial).
+        applyLayoutForces(state.sim, null, null);
         state.sim.alpha(0.3).restart();
       }
     });

package/packages/client/public/index.html

@@ -62,6 +62,7 @@
       <button id="btn-config">config</button>
       <button id="btn-sprint" title="Define and kick off a 4+1 sprint">sprint</button>
       <button id="btn-graph" title="Open the knowledge-graph view (memory_items + memory_relationships, force-directed)" onclick="window.open('/graph.html','_blank','noopener')">graph</button>
+      <button id="btn-flashback-history" title="Audit dashboard: every Flashback fire, dismiss/click-through funnel" onclick="window.open('/flashback-history.html','_blank','noopener')">flashback history</button>
       <button id="btn-how" title="Walkthrough of every TermDeck feature">how this works</button>
       <button id="btn-help" title="Open the TermDeck documentation" onclick="window.open('https://termdeck-docs.vercel.app','_blank','noopener')">help</button>
     </div>

package/packages/client/public/style.css

@@ -3567,6 +3567,61 @@
       background: rgba(255, 255, 255, 0.08);
     }
 
+    /* Sprint 43 T1 — second toolbar row: hide-isolated / min-degree / window
+       / layout selectors. Mirrors .graph-filters spacing but shifts the
+       background a notch darker so the two rows are visually distinguishable
+       and the edge-type chips above feel like their own band. */
+    .graph-filters-row2 {
+      gap: 14px;
+      padding: 6px 16px;
+      background: rgba(0, 0, 0, 0.18);
+      border-bottom: 1px solid var(--tg-border);
+    }
+    .graph-control {
+      display: inline-flex;
+      align-items: center;
+      gap: 6px;
+      font-size: 11px;
+      font-family: var(--tg-mono);
+      color: var(--tg-text-dim);
+    }
+    .graph-control select {
+      background: var(--tg-bg);
+      color: var(--tg-text);
+      border: 1px solid var(--tg-border);
+      border-radius: var(--tg-radius-sm);
+      padding: 3px 6px;
+      font-family: var(--tg-mono);
+      font-size: 11px;
+      cursor: pointer;
+    }
+    .graph-control select:focus {
+      outline: none;
+      border-color: var(--tg-accent);
+    }
+    .graph-control-toggle {
+      cursor: pointer;
+      user-select: none;
+    }
+    .graph-control-toggle input[type="checkbox"] {
+      accent-color: var(--tg-accent);
+      cursor: pointer;
+    }
+    .graph-control-stat {
+      margin-left: auto;
+      font-size: 10px;
+      color: var(--tg-text-dim);
+      font-family: var(--tg-mono);
+      padding: 2px 8px;
+      border: 1px solid transparent;
+      border-radius: 999px;
+    }
+    .graph-control-stat:not(:empty) {
+      background: rgba(122, 162, 247, 0.10);
+      border-color: rgba(122, 162, 247, 0.35);
+      color: var(--tg-text);
+    }
+
     .graph-stage {
       position: relative;
       flex: 1;

package/packages/server/src/database.js

@@ -2,12 +2,50 @@
 
 const path = require('path');
 const os = require('os');
+const fs = require('fs');
+
+// Sprint 43 T2: load a numbered migration .sql file from the repo-root
+// `migrations/` directory if present, falling back to an inline string for
+// packaged npm installs where the `files` allowlist in package.json does not
+// ship `migrations/`. Authoritative source-of-truth is the .sql file; the
+// fallback is kept in lockstep when the schema changes.
+function loadMigrationSql(name, fallback) {
+  const candidates = [
+    path.join(__dirname, '..', '..', '..', 'migrations', name),
+    path.join(__dirname, '..', '..', '..', '..', 'migrations', name),
+  ];
+  for (const candidate of candidates) {
+    try {
+      const sql = fs.readFileSync(candidate, 'utf8');
+      if (sql && sql.trim().length) return sql;
+    } catch (_e) { /* try next */ }
+  }
+  return fallback;
+}
+
+const FLASHBACK_EVENTS_INLINE_SQL = `
+  CREATE TABLE IF NOT EXISTS flashback_events (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    fired_at        TEXT    NOT NULL,
+    session_id      TEXT    NOT NULL,
+    project         TEXT,
+    error_text      TEXT    NOT NULL,
+    hits_count      INTEGER NOT NULL DEFAULT 0,
+    top_hit_id      TEXT,
+    top_hit_score   REAL,
+    dismissed_at    TEXT,
+    clicked_through INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE INDEX IF NOT EXISTS flashback_events_fired_at_idx
+    ON flashback_events(fired_at DESC);
+  CREATE INDEX IF NOT EXISTS flashback_events_session_idx
+    ON flashback_events(session_id);
+`;
 
 function initDatabase(Database) {
   const dbPath = path.join(os.homedir(), '.termdeck', 'termdeck.db');
 
   // Ensure directory exists
-  const fs = require('fs');
   fs.mkdirSync(path.dirname(dbPath), { recursive: true });
 
   const db = new Database(dbPath);
@@ -115,6 +153,16 @@ function initDatabase(Database) {
     console.warn('[db] projects.default_theme drop migration failed:', err.message);
   }
 
+  // Sprint 43 T2: flashback_events durable audit table. Schema lives in
+  // migrations/001_flashback_events.sql (repo-root, source-of-truth) with
+  // an inline fallback for packaged installs. Idempotent CREATE so this
+  // replays safely on every server start.
+  try {
+    db.exec(loadMigrationSql('001_flashback_events.sql', FLASHBACK_EVENTS_INLINE_SQL));
+  } catch (err) {
+    console.warn('[db] flashback_events migration failed:', err.message);
+  }
+
   return db;
 }
 

package/packages/server/src/flashback-diag.js

@@ -1,15 +1,37 @@
-// Flashback diagnostic ring buffer (Sprint 39 T1).
+// Flashback diagnostic ring buffer (Sprint 39 T1) + durable audit table
+// (Sprint 43 T2).
 //
-// Six decision points along the Flashback pipeline write structured events
-// here so production-flow regressions surface as a readable timeline instead
-// of a silent gate failure. The ring is in-memory and lost on restart by
-// design — persistence is a Sprint-40+ concern. Public surface:
+// Two layers of observability for the Flashback pipeline:
 //
-//   log({ sessionId, event, ...fields })  — append one event
-//   snapshot({ sessionId?, eventType?, limit? }) — read back filtered tail
-//   _resetForTest()                                — test-only ring clear
+//   (1) IN-MEMORY RING — six decision points along the pipeline write
+//       structured events to a 200-event ring. Lost on restart. Powers the
+//       /api/flashback/diag endpoint and the live diagnostic UI. This is
+//       fine-grained: every pattern match, every rate-limit hit, every
+//       bridge query gets logged.
 //
-// Event shape (all events): { ts, sessionId, event, ...event-specific fields }.
+//   (2) SQLITE AUDIT TABLE (flashback_events) — every actual fire (the
+//       moment a proactive_memory frame is sent over WS to the user's
+//       panel) gets one durable row. Survives restart. Powers the
+//       /flashback-history.html dashboard and the click-through funnel.
+//       This is coarse-grained: one row per fire, plus dismiss/click-through
+//       outcome.
+//
+// Public surface:
+//
+//   In-memory ring (Sprint 39):
+//     log({ sessionId, event, ...fields }) — append one event
+//     snapshot({ sessionId?, eventType?, limit? }) — read back filtered tail
+//     _resetForTest() — test-only ring clear
+//
+//   SQLite audit (Sprint 43 T2):
+//     recordFlashback(db, { sessionId, project, error_text, hits_count,
+//                           top_hit_id, top_hit_score, fired_at? }) → id
+//     markDismissed(db, eventId, dismissedAt?) → bool
+//     markClickedThrough(db, eventId) → bool
+//     getRecentFlashbacks(db, { since?, limit? }) → row[]
+//     getFunnelStats(db, { since? }) → { fires, dismissed, clicked_through }
+//
+// Event shape (ring): { ts, sessionId, event, ...event-specific fields }.
 //
 // Event types and their producers:
 //   pattern_match           — session.js _detectErrors (PATTERNS.error /
@@ -21,9 +43,13 @@
 //   bridge_result           — mnestra-bridge queryMnestra at call return
 //   proactive_memory_emit   — index.js onErrorDetected WS send block
 //
-// The route GET /api/flashback/diag (registered in index.js) returns
-// snapshot() output as JSON for ad-hoc inspection by Joshua and consumption
-// by T4's production-flow e2e test.
+// The audit table is an EXTENSION of the ring, not a replacement. Ring stays
+// for the live UI; SQLite is for the historical question "did flashback fire
+// when I needed it, and did I act on it?"
+//
+// SQLite functions are SAFE when db is null/undefined: they no-op and return
+// null/false/[] so test fixtures and Database-unavailable installs don't
+// break the live emit path.
 
 const RING_SIZE = 200;
 
@@ -48,4 +74,152 @@ function _resetForTest() {
   ring = [];
 }
 
-module.exports = { log, snapshot, _resetForTest, RING_SIZE };
+// ---- SQLite audit (Sprint 43 T2) ----------------------------------------
+
+// Persists one row per actual flashback fire. Returns the inserted row id
+// (number) or null when persistence is unavailable. Errors are caught and
+// logged — flashback persistence must never break the live emit path.
+function recordFlashback(db, event) {
+  if (!db) return null;
+  if (!event || (!event.sessionId && !event.session_id)) return null;
+  try {
+    const fired_at = event.fired_at || new Date().toISOString();
+    const session_id = event.session_id || event.sessionId;
+    const hits_count = Number.isFinite(event.hits_count) ? event.hits_count : 0;
+    const top_hit_score = (typeof event.top_hit_score === 'number'
+      && Number.isFinite(event.top_hit_score)) ? event.top_hit_score : null;
+    const result = db.prepare(`
+      INSERT INTO flashback_events
+        (fired_at, session_id, project, error_text, hits_count,
+         top_hit_id, top_hit_score)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      fired_at,
+      session_id,
+      event.project || null,
+      event.error_text || '',
+      hits_count,
+      event.top_hit_id || null,
+      top_hit_score,
+    );
+    // better-sqlite3 returns BigInt for lastInsertRowid; coerce to Number
+    // so it serializes naturally into JSON and the WS frame.
+    return Number(result.lastInsertRowid);
+  } catch (err) {
+    console.warn('[flashback-diag] recordFlashback INSERT failed:', err.message);
+    return null;
+  }
+}
+
+// Marks an event as dismissed (toast went away — by user, by 30s timeout,
+// or implicitly via click-through). Idempotent: only writes when
+// dismissed_at is currently NULL, so the FIRST dismiss wins. Returns true
+// when a row was actually updated.
+function markDismissed(db, eventId, dismissedAt) {
+  if (!db || !eventId) return false;
+  const id = Number(eventId);
+  if (!Number.isFinite(id) || id <= 0) return false;
+  try {
+    const ts = dismissedAt || new Date().toISOString();
+    const result = db.prepare(`
+      UPDATE flashback_events
+         SET dismissed_at = ?
+       WHERE id = ? AND dismissed_at IS NULL
+    `).run(ts, id);
+    return result.changes > 0;
+  } catch (err) {
+    console.warn('[flashback-diag] markDismissed UPDATE failed:', err.message);
+    return false;
+  }
+}
+
+// Marks an event as clicked-through (user opened the modal). Click-through
+// is also an implicit dismiss, so if dismissed_at is still NULL we set it
+// at the same moment. Idempotent: clicking twice is a no-op on the second
+// pass. Returns true when a row was actually updated.
+function markClickedThrough(db, eventId) {
+  if (!db || !eventId) return false;
+  const id = Number(eventId);
+  if (!Number.isFinite(id) || id <= 0) return false;
+  try {
+    const ts = new Date().toISOString();
+    const result = db.prepare(`
+      UPDATE flashback_events
+         SET clicked_through = 1,
+             dismissed_at    = COALESCE(dismissed_at, ?)
+       WHERE id = ? AND clicked_through = 0
+    `).run(ts, id);
+    return result.changes > 0;
+  } catch (err) {
+    console.warn('[flashback-diag] markClickedThrough UPDATE failed:', err.message);
+    return false;
+  }
+}
+
+// Reads the most-recent N flashback fires, optionally filtered to events
+// fired at-or-after the `since` ISO timestamp. Hard cap of 500 rows so
+// pathological queries can't OOM the dashboard.
+function getRecentFlashbacks(db, { since, limit } = {}) {
+  if (!db) return [];
+  try {
+    const cap = Math.max(1, Math.min(500, Number(limit) || 100));
+    const cols = `id, fired_at, session_id, project, error_text, hits_count,
+                  top_hit_id, top_hit_score, dismissed_at, clicked_through`;
+    if (since) {
+      return db.prepare(
+        `SELECT ${cols} FROM flashback_events
+          WHERE fired_at >= ?
+          ORDER BY fired_at DESC
+          LIMIT ?`
+      ).all(since, cap);
+    }
+    return db.prepare(
+      `SELECT ${cols} FROM flashback_events
+        ORDER BY fired_at DESC
+        LIMIT ?`
+    ).all(cap);
+  } catch (err) {
+    console.warn('[flashback-diag] getRecentFlashbacks SELECT failed:', err.message);
+    return [];
+  }
+}
+
+// Click-through funnel aggregates: total fires, dismissed (any reason),
+// clicked-through (modal opened). Optional `since` ISO timestamp filter.
+// All three are scalar counts — the dashboard renders them as a percentage
+// funnel chart.
+function getFunnelStats(db, { since } = {}) {
+  const empty = { fires: 0, dismissed: 0, clicked_through: 0 };
+  if (!db) return empty;
+  try {
+    const where = since ? `WHERE fired_at >= ?` : '';
+    const args = since ? [since] : [];
+    const row = db.prepare(
+      `SELECT
+         COUNT(*) AS fires,
+         SUM(CASE WHEN dismissed_at IS NOT NULL THEN 1 ELSE 0 END) AS dismissed,
+         SUM(CASE WHEN clicked_through = 1 THEN 1 ELSE 0 END) AS clicked_through
+       FROM flashback_events ${where}`
+    ).get(...args);
+    return {
+      fires: Number(row?.fires || 0),
+      dismissed: Number(row?.dismissed || 0),
+      clicked_through: Number(row?.clicked_through || 0),
+    };
+  } catch (err) {
+    console.warn('[flashback-diag] getFunnelStats SELECT failed:', err.message);
+    return empty;
+  }
+}
+
+module.exports = {
+  log,
+  snapshot,
+  _resetForTest,
+  RING_SIZE,
+  recordFlashback,
+  markDismissed,
+  markClickedThrough,
+  getRecentFlashbacks,
+  getFunnelStats,
+};

package/packages/server/src/index.js

@@ -911,10 +911,22 @@ function createServer(config) {
               return;
             }
             if (sess.ws && sess.ws.readyState === 1) {
-              const frame = JSON.stringify({ type: 'proactive_memory', hit });
+              // Sprint 43 T2: persist the fire to flashback_events BEFORE
+              // serializing the WS frame so we can include the row id. The
+              // client uses flashback_event_id to POST dismiss/click-through
+              // updates back to the audit dashboard.
+              const flashback_event_id = flashbackDiag.recordFlashback(db, {
+                sessionId: sess.id,
+                project: sess.meta.project || null,
+                error_text: question,
+                hits_count: count,
+                top_hit_id: hit.id || null,
+                top_hit_score: typeof hit.similarity === 'number' ? hit.similarity : null,
+              });
+              const frame = JSON.stringify({ type: 'proactive_memory', hit, flashback_event_id });
               try {
                 sess.ws.send(frame);
-                console.log(`[flashback] proactive_memory sent to session ${sess.id} (source_type=${hit.source_type}, project=${hit.project})`);
+                console.log(`[flashback] proactive_memory sent to session ${sess.id} (source_type=${hit.source_type}, project=${hit.project}, event_id=${flashback_event_id})`);
                 flashbackDiag.log({
                   sessionId: sess.id,
                   event: 'proactive_memory_emit',
@@ -922,6 +934,7 @@ function createServer(config) {
                   frame_size_bytes: Buffer.byteLength(frame, 'utf8'),
                   result_count_in_frame: 1,
                   outcome: 'emitted',
+                  flashback_event_id,
                 });
               } catch (err) {
                 console.error('[flashback] proactive_memory send failed:', err);
@@ -1442,6 +1455,49 @@ function createServer(config) {
     res.json({ count: events.length, events });
   });
 
+  // GET /api/flashback/history - Sprint 43 T2 durable audit dashboard.
+  // Returns the most-recent flashback fires from SQLite (survives restart)
+  // plus the click-through funnel aggregate. The dashboard uses one fetch
+  // for both so it can render the table and the funnel in lockstep.
+  // Optional filters: ?since=<ISO8601>, ?limit=N (default 100, max 500).
+  app.get('/api/flashback/history', (req, res) => {
+    const rawSince = req.query && req.query.since;
+    const since = (typeof rawSince === 'string' && rawSince.length) ? rawSince : undefined;
+    const rawLimit = req.query && req.query.limit;
+    const limit = rawLimit != null ? parseInt(rawLimit, 10) : undefined;
+    const events = flashbackDiag.getRecentFlashbacks(db, {
+      since,
+      limit: Number.isFinite(limit) && limit > 0 ? limit : undefined,
+    });
+    const funnel = flashbackDiag.getFunnelStats(db, { since });
+    res.json({ count: events.length, events, funnel });
+  });
+
+  // POST /api/flashback/:id/dismissed - mark a flashback toast as dismissed.
+  // Called by the client when the user clicks ×, presses Escape, lets the
+  // 30s auto-timer fire, OR clicks "Not relevant" / "Dismiss" in the modal.
+  // Idempotent: subsequent calls are no-ops (first dismiss timestamp wins).
+  app.post('/api/flashback/:id/dismissed', (req, res) => {
+    const id = parseInt(req.params.id, 10);
+    if (!Number.isFinite(id) || id <= 0) {
+      return res.status(400).json({ error: 'Invalid id' });
+    }
+    const updated = flashbackDiag.markDismissed(db, id);
+    res.json({ ok: true, updated });
+  });
+
+  // POST /api/flashback/:id/clicked - mark a flashback toast as clicked-
+  // through (user opened the modal). Click-through is also an implicit
+  // dismiss, so this updates dismissed_at if it's still NULL. Idempotent.
+  app.post('/api/flashback/:id/clicked', (req, res) => {
+    const id = parseInt(req.params.id, 10);
+    if (!Number.isFinite(id) || id <= 0) {
+      return res.status(400).json({ error: 'Invalid id' });
+    }
+    const updated = flashbackDiag.markClickedThrough(db, id);
+    res.json({ ok: true, updated });
+  });
+
   // GET /api/pty-reaper/status — Sprint 42 T2 observability surface.
   // Returns the live registry (per-session PTY pid + tracked descendants) and
   // the reaped-history ring buffer so heavy-use installs can tell whether the