@jhizzard/termdeck 0.11.0 → 0.13.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/agent-adapters/claude.js

@@ -0,0 +1,158 @@
+// Claude Code adapter — Sprint 44 T3
+//
+// First adapter in the AGENT_ADAPTERS registry (see ./index.js). Lifts the
+// claude-code logic that previously lived as hardcoded branches in
+// packages/server/src/session.js. Behavior is bit-for-bit identical to the
+// pre-Sprint-44 inline path: same regexes, same status strings, same
+// transcript-parser cut-offs. Sprint 45 adds Codex / Gemini / Grok adapters
+// alongside this one; Sprint 46 wires per-lane agent assignment in 4+1.
+//
+// Contract (memorialization doc § 4 + lane brief T3):
+//   {
+//     name:           string,                     // adapter id used in registry
+//     sessionType:    string,                     // session.meta.type produced
+//     matches:        (cmd) => boolean,           // command-string detection
+//     spawn:          { binary, defaultArgs, env },
+//     patterns:       { prompt, thinking, editing, tool, idle, error },
+//     patternNames:   { error: string },          // diag-event label preservation
+//     statusFor:      (data) => { status, statusDetail } | null,
+//     parseTranscript:(raw) => Memory[],          // for memory-session-end hook
+//     bootPromptTemplate: (lane, sprint) => string,
+//     costBand:       'free' | 'pay-per-token' | 'subscription',
+//   }
+//
+// `statusFor` returns null when no pattern matches — preserves the original
+// "no change" semantics for the claude-code switch case. Caller leaves
+// `meta.status` and `meta.statusDetail` untouched on null.
+
+// ──────────────────────────────────────────────────────────────────────────
+// Patterns — verbatim regexes lifted from session.js so the adapter and the
+// shim remain reference-equal. Don't redeclare these elsewhere; import from
+// the adapter so future tweaks land in one place.
+// ──────────────────────────────────────────────────────────────────────────
+
+const PROMPT = /^[>❯]\s/m;
+const THINKING = /\b(thinking|Thinking)\b/;
+const EDITING = /^(Edit|Create|Update|Delete)\s/m;
+const EDITING_DETAIL = /^(Edit|Create|Update|Delete)\s+(.+)$/m;
+const TOOL = /^⏺\s/m;
+const IDLE = /^>\s*$/m;
+
+// errorLineStart from session.js — line-anchored variant for claude-code
+// sessions whose tool output (grep results, test logs, file dumps) routinely
+// mentions "Error" mid-line without representing an actual failure.
+// Sprint 40 T2 added mixed-case `Fatal` + the special-cased `npm ERR!` shape.
+const ERROR = /^\s*(?:(?:error|Error|ERROR|exception|Exception|Traceback|fatal|Fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|No such file or directory|Permission denied)\b|npm ERR!)/m;
+
+// ──────────────────────────────────────────────────────────────────────────
+// statusFor — replaces the `case 'claude-code':` block of _updateStatus.
+// Order matters: thinking → editing → tool → idle. First match wins, exactly
+// as the original switch did with cascading `else if`s.
+// ──────────────────────────────────────────────────────────────────────────
+
+function statusFor(data) {
+  if (THINKING.test(data)) {
+    return { status: 'thinking', statusDetail: 'Claude is reasoning...' };
+  }
+  if (EDITING.test(data)) {
+    const match = data.match(EDITING_DETAIL);
+    return {
+      status: 'editing',
+      statusDetail: match ? `${match[1]} ${match[2]}` : 'Editing files',
+    };
+  }
+  if (TOOL.test(data)) {
+    return { status: 'active', statusDetail: 'Using tools' };
+  }
+  if (IDLE.test(data)) {
+    return { status: 'idle', statusDetail: 'Waiting for input' };
+  }
+  return null;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// parseTranscript — Claude Code JSONL format, lifted from
+// packages/stack-installer/assets/hooks/memory-session-end.js:88-102.
+// Emits records of shape { role: 'user'|'assistant', content: string }
+// truncated to 400 chars per message. The hook itself remains the consumer
+// in Sprint 44; Sprint 45 T4 wires it to read from this adapter so other
+// agents can plug in their own format parsers.
+// ──────────────────────────────────────────────────────────────────────────
+
+function parseTranscript(raw) {
+  if (typeof raw !== 'string' || raw.length === 0) return [];
+  const lines = raw.split('\n').filter(Boolean);
+  const messages = [];
+  for (const line of lines) {
+    let msg;
+    try { msg = JSON.parse(line); } catch (_) { continue; }
+    const role = msg && msg.message && msg.message.role;
+    if (role !== 'user' && role !== 'assistant') continue;
+    const content = msg.message.content;
+    let text = '';
+    if (typeof content === 'string') {
+      text = content;
+    } else if (Array.isArray(content)) {
+      text = content
+        .filter((c) => c && c.type === 'text')
+        .map((c) => c.text)
+        .join(' ');
+    }
+    if (text) messages.push({ role, content: text.slice(0, 400) });
+  }
+  return messages;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// bootPromptTemplate — minimal scaffold matching the global-CLAUDE.md 4+1
+// boot block. Sprint 46 T2 will refine per-agent prompts; this is the
+// placeholder so the adapter contract is complete in Sprint 44.
+// ──────────────────────────────────────────────────────────────────────────
+
+function bootPromptTemplate(lane = {}, sprint = {}) {
+  const tn = lane.id || 'T?';
+  const sprintNum = sprint.number || '?';
+  const sprintName = sprint.name || 'unnamed';
+  const project = (lane.project || sprint.project || 'termdeck');
+  const briefing = lane.briefingPath || `docs/sprint-${sprintNum}-${sprintName}/${tn}-<lane>.md`;
+  return [
+    `You are ${tn} in Sprint ${sprintNum} (${sprintName}). Boot sequence:`,
+    `1. memory_recall(project="${project}", query="<topic>")`,
+    `2. memory_recall(query="<broader topic>")`,
+    `3. Read ~/.claude/CLAUDE.md and ./CLAUDE.md`,
+    `4. Read docs/sprint-${sprintNum}-${sprintName}/PLANNING.md`,
+    `5. Read docs/sprint-${sprintNum}-${sprintName}/STATUS.md`,
+    `6. Read ${briefing}`,
+    '',
+    'Then begin. Stay in your lane. Post FINDING / FIX-PROPOSED / DONE in STATUS.md.',
+    "Don't bump versions, don't touch CHANGELOG, don't commit.",
+  ].join('\n');
+}
+
+const claudeAdapter = {
+  name: 'claude',
+  sessionType: 'claude-code',
+  matches: (cmd) => typeof cmd === 'string' && /claude/i.test(cmd),
+  spawn: {
+    binary: 'claude',
+    defaultArgs: [],
+    env: {},
+  },
+  patterns: {
+    prompt: PROMPT,
+    thinking: THINKING,
+    editing: EDITING,
+    tool: TOOL,
+    idle: IDLE,
+    error: ERROR,
+  },
+  patternNames: {
+    error: 'errorLineStart',
+  },
+  statusFor,
+  parseTranscript,
+  bootPromptTemplate,
+  costBand: 'pay-per-token',
+};
+
+module.exports = claudeAdapter;

package/packages/server/src/agent-adapters/index.js

@@ -0,0 +1,55 @@
+// Agent adapter registry — Sprint 44 T3
+//
+// Single source of truth for per-agent terminal behavior. Each adapter
+// implements the contract documented in ./claude.js (and the memorialization
+// doc § 4) — type detection, status patterns, transcript parsing, boot prompt
+// templating, cost band. session.js consults this registry when analyzing
+// PTY output so adding a new agent (Codex / Gemini / Grok in Sprint 45) is a
+// new file in this directory + one entry in `AGENT_ADAPTERS` below — no
+// switch statements to extend.
+//
+// Sprint 44 lands the Claude adapter only. The other agents stay on the
+// in-file shim path in session.js until Sprint 45 T1-T3 ship their adapters
+// and Sprint 45 T4 wires the launcher UI through the same registry.
+
+const claude = require('./claude');
+
+// Keyed by adapter name (NOT session.meta.type — adapters expose their own
+// `sessionType` field for that mapping). Order is iteration order for the
+// detect loop in session.js, so list more-specific adapters before less.
+const AGENT_ADAPTERS = {
+  claude,
+};
+
+// Convenience accessor — returns the adapter whose `sessionType` matches the
+// session.meta.type value, or undefined if no adapter has claimed that type.
+// session.js calls this in the hot path; keep it cheap.
+function getAdapterForSessionType(type) {
+  if (!type) return undefined;
+  for (const adapter of Object.values(AGENT_ADAPTERS)) {
+    if (adapter.sessionType === type) return adapter;
+  }
+  return undefined;
+}
+
+// Convenience accessor — first adapter whose prompt regex matches `data` or
+// whose `matches(command)` returns true. Returns undefined if no adapter
+// claims the session, leaving the caller to fall back to legacy detection
+// (gemini / python-server / shell). session.js calls this from `_detectType`.
+function detectAdapter(data, command) {
+  for (const adapter of Object.values(AGENT_ADAPTERS)) {
+    const promptHit = adapter.patterns
+      && adapter.patterns.prompt
+      && typeof data === 'string'
+      && adapter.patterns.prompt.test(data);
+    const cmdHit = typeof adapter.matches === 'function' && adapter.matches(command);
+    if (promptHit || cmdHit) return adapter;
+  }
+  return undefined;
+}
+
+module.exports = {
+  AGENT_ADAPTERS,
+  getAdapterForSessionType,
+  detectAdapter,
+};

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;
 }