@jhizzard/termdeck 0.3.2 → 0.3.4

package/README.md

@@ -22,6 +22,16 @@ Enabling Flashback takes **one additional 15-minute setup step** — see Tier 2
 
 ---
 
+## Documentation hierarchy
+
+- **This README** — quickstart, pitch, and links
+- **[docs/GETTING-STARTED.md](docs/GETTING-STARTED.md)** — full 4-tier installation guide
+- **[termdeck-docs.vercel.app](https://termdeck-docs.vercel.app)** — reference docs (Astro/Starlight)
+- **docs/launch/** — launch collateral (Show HN, Twitter, etc.)
+- **docs/sprint-N-*/** — historical sprint logs (append-only, not maintained post-sprint)
+
+---
+
 ## How Flashback works
 
 When a panel's status transitions to `errored`, the server's output analyzer fires an event. The mnestra bridge takes the session context (type, project, last command, error tail) and queries your Mnestra memory store for the top similar match. If it finds one above the relevance threshold, the result is pushed to the panel's WebSocket as a `proactive_memory` message. The client renders it as a toast anchored to the panel, showing the match's project tag, source type, similarity score, and content snippet. You click the toast to expand into the Memory tab of that panel's drawer.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/client/public/app.js

@@ -48,10 +48,10 @@
         }
       }
 
-      // RAG indicator
-      if (state.config.ragEnabled) {
-        document.getElementById('stat-rag').style.display = '';
-      }
+      // RAG indicator removed (Sprint 9 T2): redundant with health badge which
+      // already surfaces mnestra_reachable / mnestra_has_memories per-check.
+      // The #stat-rag HTML stub is hidden by default; T1 can strip it from
+      // index.html.
 
       // Disable AI input bars if Supabase/OpenAI not configured
       if (!state.config.aiQueryAvailable) {
@@ -2168,6 +2168,145 @@
       try { localStorage.setItem('termdeck:tour:seen', '1'); } catch {}
     }
 
+    // ===== Status / Config dropdowns (Sprint 9 T2) =====
+    // Generic toolbar-button → dropdown factory. Opens below the button,
+    // click-outside closes, re-fetches every open so the data isn't stale.
+    function setupInfoDropdown({ btnId, dropdownId, fetch, render }) {
+      const btn = document.getElementById(btnId);
+      if (!btn) return;
+
+      const dropdown = document.createElement('div');
+      dropdown.className = 'health-dropdown info-dropdown';
+      dropdown.id = dropdownId;
+      dropdown.innerHTML = '<div class="hd-loading">Loading…</div>';
+      document.body.appendChild(dropdown);
+
+      let open = false;
+
+      const close = () => {
+        dropdown.classList.remove('open');
+        open = false;
+      };
+
+      const openDropdown = async () => {
+        const rect = btn.getBoundingClientRect();
+        dropdown.style.top = `${rect.bottom + 4}px`;
+        // Right-align under the button; clamp to viewport
+        const desiredLeft = Math.min(
+          window.innerWidth - 320,
+          Math.max(8, rect.right - 300)
+        );
+        dropdown.style.left = `${desiredLeft}px`;
+        dropdown.innerHTML = '<div class="hd-loading">Loading…</div>';
+        dropdown.classList.add('open');
+        open = true;
+        try {
+          const data = await fetch();
+          // If user closed it while we were fetching, abort
+          if (!open) return;
+          dropdown.innerHTML = render(data);
+        } catch (err) {
+          dropdown.innerHTML = `<div class="hd-empty">Failed to load: ${escapeHtml(err.message || String(err))}</div>`;
+        }
+      };
+
+      btn.addEventListener('click', (e) => {
+        e.stopPropagation();
+        if (open) close(); else openDropdown();
+      });
+      document.addEventListener('click', (e) => {
+        if (open && !dropdown.contains(e.target) && e.target !== btn) close();
+      });
+      document.addEventListener('keydown', (e) => {
+        if (open && e.key === 'Escape') close();
+      });
+    }
+
+    function renderStatusDropdown(data) {
+      const total = data.totalSessions || 0;
+      const byStatus = data.byStatus || {};
+      const byProject = data.byProject || {};
+      const byType = data.byType || {};
+      const uptime = fmtUptime(data.uptime || 0);
+      const heapMB = data.memory && data.memory.heapUsed
+        ? (data.memory.heapUsed / 1024 / 1024).toFixed(1) + ' MB'
+        : '—';
+      const rag = data.ragEnabled ? 'on' : 'off';
+
+      const row = (label, value) => `<div class="hd-check">
+        <span class="hd-icon">·</span>
+        <span class="hd-name">${escapeHtml(label)}</span>
+        <span class="hd-dots"></span>
+        <span class="hd-status">${escapeHtml(String(value))}</span>
+      </div>`;
+
+      const kvBlock = (title, obj) => {
+        const keys = Object.keys(obj);
+        if (keys.length === 0) return '';
+        const lines = keys.map(k => row(k, obj[k])).join('');
+        return `<div class="hd-detail" style="grid-column:1/-1;margin-top:6px;color:var(--tg-text-dim);font-size:10px">${escapeHtml(title)}</div>${lines}`;
+      };
+
+      return row('sessions', total)
+        + row('uptime', uptime)
+        + row('heap', heapMB)
+        + row('rag sync', rag)
+        + kvBlock('by status', byStatus)
+        + kvBlock('by project', byProject)
+        + kvBlock('by type', byType);
+    }
+
+    function renderConfigDropdown(data) {
+      const projects = data.projects || {};
+      const projectCount = Object.keys(projects).length;
+      const defaultTheme = data.defaultTheme || '—';
+      const rag = data.ragEnabled ? 'enabled' : 'disabled';
+      const aiQuery = data.aiQueryAvailable ? 'yes' : 'no';
+
+      const row = (label, value, ok) => {
+        const icon = ok == null ? '·' : (ok ? '✓' : '✗');
+        const cls = ok == null ? '' : (ok ? 'hd-ok' : 'hd-fail');
+        return `<div class="hd-check ${cls}">
+          <span class="hd-icon">${icon}</span>
+          <span class="hd-name">${escapeHtml(label)}</span>
+          <span class="hd-dots"></span>
+          <span class="hd-status">${escapeHtml(String(value))}</span>
+        </div>`;
+      };
+
+      let html = ''
+        + row('projects', projectCount)
+        + row('default theme', defaultTheme)
+        + row('RAG sync', rag, data.ragEnabled)
+        + row('AI query', aiQuery, data.aiQueryAvailable);
+
+      if (projectCount > 0) {
+        html += `<div class="hd-detail" style="grid-column:1/-1;margin-top:6px;color:var(--tg-text-dim);font-size:10px">projects</div>`;
+        for (const [name, cfg] of Object.entries(projects)) {
+          const path = (cfg && cfg.path) || '';
+          html += `<div class="hd-check">
+            <span class="hd-icon">·</span>
+            <span class="hd-name">${escapeHtml(name)}</span>
+            <span class="hd-dots"></span>
+            <span class="hd-status" style="font-size:10px;color:var(--tg-text-dim)">${escapeHtml(path)}</span>
+          </div>`;
+        }
+      }
+
+      html += `<div class="hd-detail" style="grid-column:1/-1;margin-top:8px;color:var(--tg-text-dim);font-size:10px">edit <code>~/.termdeck/config.yaml</code> and restart to apply</div>`;
+      return html;
+    }
+
+    function fmtUptime(sec) {
+      const s = Math.floor(sec);
+      const h = Math.floor(s / 3600);
+      const m = Math.floor((s % 3600) / 60);
+      const rs = s % 60;
+      if (h > 0) return `${h}h ${m}m`;
+      if (m > 0) return `${m}m ${rs}s`;
+      return `${rs}s`;
+    }
+
     // ===== Event Listeners =====
     document.querySelectorAll('.layout-btn').forEach(btn => {
       btn.addEventListener('click', () => setLayout(btn.dataset.layout));
@@ -2189,6 +2328,23 @@
       if (e.key === 'Escape') { e.preventDefault(); closeAddProjectModal(); }
     });
 
+    // Status + config dropdowns (Sprint 9 T2): btn-status/btn-config were
+    // stubs with no listeners. Each now opens a dropdown with live data
+    // fetched from /api/status and /api/config. Reuses .health-dropdown
+    // styling (from T1's style.css) for visual consistency.
+    setupInfoDropdown({
+      btnId: 'btn-status',
+      dropdownId: 'statusDropdown',
+      fetch: () => api('GET', '/api/status'),
+      render: renderStatusDropdown
+    });
+    setupInfoDropdown({
+      btnId: 'btn-config',
+      dropdownId: 'configDropdown',
+      fetch: () => api('GET', '/api/config'),
+      render: renderConfigDropdown
+    });
+
     // Onboarding tour wiring
     document.getElementById('btn-how').addEventListener('click', startTour);
     document.getElementById('tourNextBtn').addEventListener('click', nextTourStep);

package/packages/client/public/index.html

@@ -9,41 +9,43 @@
 </head>
 <body>
 
-  <!-- TOP BAR -->
+  <!-- TOP BAR (Sprint 9 T1: two-row layout) -->
   <div class="topbar">
-    <div class="topbar-left">
-      <div class="topbar-logo">
-        <svg width="18" height="18" viewBox="0 0 18 18" fill="none">
-          <rect x="1" y="1" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
-          <rect x="10" y="1" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
-          <rect x="1" y="10" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
-          <rect x="10" y="10" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
-        </svg>
-        TermDeck
+    <div class="topbar-row topbar-row-1">
+      <div class="topbar-left">
+        <div class="topbar-logo">
+          <svg width="18" height="18" viewBox="0 0 18 18" fill="none">
+            <rect x="1" y="1" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
+            <rect x="10" y="1" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
+            <rect x="1" y="10" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
+            <rect x="10" y="10" width="7" height="7" rx="1.5" stroke="currentColor" stroke-width="1.2"/>
+          </svg>
+          TermDeck
+        </div>
+        <div class="topbar-stats" id="globalStats">
+          <span class="topbar-stat"><span class="dot" style="background:var(--tg-green)"></span> <span id="stat-active">0</span> active</span>
+          <span class="topbar-stat"><span class="dot" style="background:var(--tg-purple)"></span> <span id="stat-thinking">0</span> thinking</span>
+          <span class="topbar-stat"><span class="dot" style="background:var(--tg-amber)"></span> <span id="stat-idle">0</span> idle</span>
+          <span class="topbar-stat" id="stat-rag" style="display:none">RAG</span>
+          <button type="button" class="rumen-badge" id="rumenBadge" title="Rumen insights" aria-haspopup="dialog" aria-controls="rumenModal" aria-label="Open Rumen insights briefing">
+            <span class="rb-icon" aria-hidden="true">💡</span>
+            <span id="rumenBadgeLabel">0 insights</span>
+          </button>
+        </div>
       </div>
-      <div class="topbar-stats" id="globalStats">
-        <span class="topbar-stat"><span class="dot" style="background:var(--tg-green)"></span> <span id="stat-active">0</span> active</span>
-        <span class="topbar-stat"><span class="dot" style="background:var(--tg-purple)"></span> <span id="stat-thinking">0</span> thinking</span>
-        <span class="topbar-stat"><span class="dot" style="background:var(--tg-amber)"></span> <span id="stat-idle">0</span> idle</span>
-        <span class="topbar-stat" id="stat-rag" style="display:none">RAG</span>
-        <button type="button" class="rumen-badge" id="rumenBadge" title="Rumen insights" aria-haspopup="dialog" aria-controls="rumenModal" aria-label="Open Rumen insights briefing">
-          <span class="rb-icon" aria-hidden="true">💡</span>
-          <span id="rumenBadgeLabel">0 insights</span>
-        </button>
-      </div>
-    </div>
 
-    <div class="topbar-center">
-      <button class="layout-btn" data-layout="1x1">1x1</button>
-      <button class="layout-btn active" data-layout="2x1">2x1</button>
-      <button class="layout-btn" data-layout="2x2">2x2</button>
-      <button class="layout-btn" data-layout="3x2">3x2</button>
-      <button class="layout-btn" data-layout="2x4">2x4</button>
-      <button class="layout-btn" data-layout="4x2">4x2</button>
-      <button class="layout-btn control-btn" data-layout="control" title="Aggregate activity feed">control</button>
+      <div class="topbar-center">
+        <button class="layout-btn" data-layout="1x1">1x1</button>
+        <button class="layout-btn active" data-layout="2x1">2x1</button>
+        <button class="layout-btn" data-layout="2x2">2x2</button>
+        <button class="layout-btn" data-layout="3x2">3x2</button>
+        <button class="layout-btn" data-layout="2x4">2x4</button>
+        <button class="layout-btn" data-layout="4x2">4x2</button>
+        <button class="layout-btn control-btn" data-layout="control" title="Aggregate activity feed">control</button>
+      </div>
     </div>
 
-    <div class="topbar-right">
+    <div class="topbar-row topbar-row-2 topbar-right">
       <!-- TERMINAL SWITCHER (T1.2 / F1.2): lives in chrome, not over PTY content -->
       <div class="term-switcher" id="termSwitcher" aria-label="Terminal switcher">
         <div class="term-switcher-label">Alt+1…9</div>
@@ -54,6 +56,7 @@
         <button class="topbar-ql-btn" onclick="quickLaunch('claude')" title="Open Claude Code">claude</button>
         <button class="topbar-ql-btn" onclick="quickLaunch('python3 -m http.server 8080')" title="Open a Python HTTP server on :8080">python</button>
       </div>
+      <div class="topbar-row-2-spacer"></div>
       <button id="btn-status">status</button>
       <button id="btn-config">config</button>
       <button id="btn-how" title="Walkthrough of every TermDeck feature">how this works</button>

package/packages/client/public/style.css

@@ -34,22 +34,47 @@
       flex-direction: column;
     }
 
-    /* ===== TOP BAR ===== */
+    /* ===== TOP BAR (Sprint 9 T1: two-row layout) =====
+       Row 1 = primary (logo, stats, badges, layout buttons) at 42px.
+       Row 2 = controls (quick-launch + chrome buttons) at 32px, dimmer.
+       Total ~74px. No horizontal scroll at 1440px. */
     .topbar {
       display: flex;
-      align-items: center;
-      justify-content: space-between;
-      padding: 0 16px;
-      height: 42px;
+      flex-direction: column;
       background: var(--tg-surface);
       border-bottom: 1px solid var(--tg-border);
       flex-shrink: 0;
+      min-width: 0;
+    }
+
+    .topbar-row {
+      display: flex;
+      align-items: center;
+      gap: 10px;
+      padding: 0 12px;
+      flex-shrink: 0;
+      min-width: 0;
+    }
+
+    .topbar-row-1 {
+      height: 42px;
+      justify-content: space-between;
+    }
+
+    .topbar-row-2 {
+      height: 32px;
+      background: var(--tg-bg);
+      border-top: 1px solid var(--tg-border);
+      gap: 6px;
     }
 
+    .topbar-row-2-spacer { flex: 1 1 auto; min-width: 0; }
+
     .topbar-left {
       display: flex;
       align-items: center;
       gap: 12px;
+      flex-shrink: 0;
     }
 
     .topbar-logo {
@@ -66,7 +91,7 @@
 
     .topbar-stats {
       display: flex;
-      gap: 16px;
+      gap: 10px;
       font-size: 11px;
       color: var(--tg-text-dim);
     }
@@ -84,6 +109,7 @@
       background: var(--tg-bg);
       padding: 3px;
       border-radius: var(--tg-radius-sm);
+      flex-shrink: 0;
     }
 
     .layout-btn {
@@ -104,7 +130,8 @@
     .topbar-right {
       display: flex;
       align-items: center;
-      gap: 8px;
+      gap: 4px;
+      flex-shrink: 0;
     }
 
     .topbar-right button {
@@ -112,7 +139,7 @@
       border: 1px solid var(--tg-border);
       color: var(--tg-text-dim);
       font-size: 11px;
-      padding: 4px 12px;
+      padding: 4px 8px;
       border-radius: var(--tg-radius-sm);
       cursor: pointer;
       font-family: var(--tg-sans);

package/packages/server/src/auth.js

@@ -0,0 +1,164 @@
+// Optional token authentication for TermDeck (Sprint 9 T3).
+//
+// When no token is configured, auth is a no-op — `createAuthMiddleware()` returns
+// null and callers skip wiring. When a token is configured (config.auth.token
+// OR the TERMDECK_AUTH_TOKEN env var), every request except /api/health must
+// present the token via one of:
+//   - Authorization: Bearer <token>
+//   - ?token=<token> query parameter
+//   - termdeck_token=<token> cookie
+//
+// Browser requests without a valid token receive a minimal HTML login page that
+// stores the token in a cookie client-side and retries. API requests get a
+// JSON 401.
+
+function getConfiguredToken(config) {
+  const fromConfig = config && config.auth && config.auth.token;
+  if (typeof fromConfig === 'string' && fromConfig.trim()) return fromConfig.trim();
+  const fromEnv = process.env.TERMDECK_AUTH_TOKEN;
+  if (typeof fromEnv === 'string' && fromEnv.trim()) return fromEnv.trim();
+  return null;
+}
+
+function readCookieToken(cookieHeader) {
+  if (!cookieHeader || typeof cookieHeader !== 'string') return null;
+  const parts = cookieHeader.split(';');
+  for (const part of parts) {
+    const eq = part.indexOf('=');
+    if (eq === -1) continue;
+    const name = part.slice(0, eq).trim();
+    if (name !== 'termdeck_token') continue;
+    try {
+      return decodeURIComponent(part.slice(eq + 1).trim());
+    } catch (err) {
+      return null;
+    }
+  }
+  return null;
+}
+
+function extractToken(req) {
+  const header = req.headers && req.headers['authorization'];
+  if (typeof header === 'string') {
+    const stripped = header.replace(/^Bearer\s+/i, '').trim();
+    if (stripped) return stripped;
+  }
+  if (req.query && typeof req.query.token === 'string' && req.query.token) {
+    return req.query.token;
+  }
+  // Fallback for callers that did not parse query (e.g. WS upgrade path).
+  if (!req.query && req.url) {
+    try {
+      const host = (req.headers && req.headers.host) || 'localhost';
+      const parsed = new URL(req.url, `http://${host}`);
+      const q = parsed.searchParams.get('token');
+      if (q) return q;
+    } catch (err) {
+      // malformed URL — fall through
+    }
+  }
+  const cookie = req.headers && req.headers.cookie;
+  const fromCookie = readCookieToken(cookie);
+  if (fromCookie) return fromCookie;
+  return null;
+}
+
+function loginPage() {
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>TermDeck — Sign in</title>
+<style>
+  html, body { height: 100%; }
+  body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+    background: #0d1117; color: #c9d1d9; display: flex; align-items: center; justify-content: center; }
+  form { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 28px 32px;
+    width: 320px; box-shadow: 0 8px 24px rgba(0,0,0,0.4); }
+  h1 { margin: 0 0 6px; font-size: 18px; }
+  p { margin: 0 0 18px; color: #8b949e; font-size: 13px; }
+  label { display: block; font-size: 12px; margin-bottom: 6px; color: #8b949e; }
+  input { width: 100%; padding: 8px 10px; border: 1px solid #30363d; border-radius: 6px;
+    background: #0d1117; color: #c9d1d9; font: 13px ui-monospace, monospace; box-sizing: border-box; }
+  input:focus { outline: 1px solid #1f6feb; }
+  button { margin-top: 16px; width: 100%; padding: 8px; background: #238636; color: #fff;
+    border: 0; border-radius: 6px; font-weight: 600; cursor: pointer; font-size: 13px; }
+  button:hover { background: #2ea043; }
+  .err { color: #f85149; font-size: 12px; margin-top: 10px; min-height: 15px; }
+</style>
+</head>
+<body>
+<form onsubmit="return submitToken(event)">
+  <h1>TermDeck</h1>
+  <p>Enter the access token to continue.</p>
+  <label for="t">Access token</label>
+  <input id="t" type="password" autocomplete="current-password" autofocus required>
+  <button type="submit">Sign in</button>
+  <div class="err" id="err"></div>
+</form>
+<script>
+function submitToken(e) {
+  e.preventDefault();
+  var err = document.getElementById('err');
+  err.textContent = '';
+  var t = document.getElementById('t').value.trim();
+  if (!t) return false;
+  document.cookie = 'termdeck_token=' + encodeURIComponent(t) +
+    '; path=/; SameSite=Strict; Max-Age=2592000';
+  var next = new URLSearchParams(location.search).get('next') || '/';
+  fetch('/api/config', { credentials: 'same-origin' }).then(function(r) {
+    if (r.ok) { location.href = next; return; }
+    document.cookie = 'termdeck_token=; path=/; Max-Age=0';
+    err.textContent = 'Invalid token.';
+  }).catch(function() {
+    err.textContent = 'Network error.';
+  });
+  return false;
+}
+</script>
+</body>
+</html>`;
+}
+
+function createAuthMiddleware(config) {
+  const token = getConfiguredToken(config);
+  if (!token) return null;
+
+  return function authMiddleware(req, res, next) {
+    // Health check stays open so external monitors can verify liveness
+    // without being handed a secret.
+    if (req.path === '/api/health') return next();
+
+    const provided = extractToken(req);
+    if (provided && provided === token) return next();
+
+    // API clients always get JSON; browsers get the login page.
+    if (req.path.startsWith('/api/')) {
+      return res.status(401).json({ error: 'unauthorized' });
+    }
+    if (req.accepts && req.accepts('html')) {
+      res.status(401);
+      res.set('Content-Type', 'text/html; charset=utf-8');
+      return res.send(loginPage());
+    }
+    return res.status(401).json({ error: 'unauthorized' });
+  };
+}
+
+// Verify a WebSocket upgrade request. Used by the WS connection handler
+// (Express middleware does not run on upgrades). Returns true if no token is
+// configured OR the request presents a matching token.
+function verifyWebSocketUpgrade(config, req) {
+  const token = getConfiguredToken(config);
+  if (!token) return true;
+  const provided = extractToken(req);
+  return !!provided && provided === token;
+}
+
+module.exports = {
+  createAuthMiddleware,
+  verifyWebSocketUpgrade,
+  getConfiguredToken,
+  loginPage
+};

package/packages/server/src/index.js

@@ -20,9 +20,17 @@ try { pg = require('pg'); } catch { pg = null; }
 // servers without DATABASE_URL never pay the connection cost.
 let _rumenPool = null;
 let _rumenPoolFailed = false;
+let _rumenPoolFailedAt = 0;
+const RUMEN_POOL_RETRY_MS = 30_000;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function getRumenPool() {
-  if (_rumenPool || _rumenPoolFailed) return _rumenPool;
+  if (_rumenPool) return _rumenPool;
+  if (_rumenPoolFailed) {
+    if (Date.now() - _rumenPoolFailedAt < RUMEN_POOL_RETRY_MS) return null;
+    console.warn('[rumen] retrying pool creation after 30s cooldown');
+    _rumenPoolFailed = false;
+    _rumenPoolFailedAt = 0;
+  }
   if (!pg || !process.env.DATABASE_URL) return null;
   try {
     _rumenPool = new pg.Pool({
@@ -38,6 +46,7 @@ function getRumenPool() {
   } catch (err) {
     console.warn('[rumen] failed to create pg pool:', err.message);
     _rumenPoolFailed = true;
+    _rumenPoolFailedAt = Date.now();
     return null;
   }
 }
@@ -51,6 +60,7 @@ const { TranscriptWriter } = require('./transcripts');
 const { createHealthHandler } = require('./preflight');
 const { themes, statusColors } = require('./themes');
 const { loadConfig, addProject } = require('./config');
+const { createAuthMiddleware, verifyWebSocketUpgrade } = require('./auth');
 
 function createServer(config) {
   const app = express();
@@ -59,6 +69,15 @@ function createServer(config) {
 
   app.use(express.json());
 
+  // Optional token auth (Sprint 9 T3). Zero-op when no token is configured,
+  // so local users see no behavior change. Mounted before static + routes so
+  // unauthenticated requests never touch app.js / index.html.
+  const authMiddleware = createAuthMiddleware(config);
+  if (authMiddleware) {
+    app.use(authMiddleware);
+    console.log('[auth] Token authentication enabled');
+  }
+
   // Serve client files
   const clientDir = path.join(__dirname, '..', '..', 'client', 'public');
   app.use(express.static(clientDir));
@@ -731,6 +750,13 @@ function createServer(config) {
   // ==================== WebSocket ====================
 
   wss.on('connection', (ws, req) => {
+    // Optional token auth for WS upgrades (Sprint 9 T3). Express middleware
+    // does not run on the upgrade path, so the check has to live here.
+    if (!verifyWebSocketUpgrade(config, req)) {
+      ws.close(4003, 'Unauthorized');
+      return;
+    }
+
     const url = new URL(req.url, `http://${req.headers.host}`);
     const sessionId = url.searchParams.get('session');
 

package/packages/server/src/preflight.js

@@ -23,12 +23,12 @@ const CACHE_TTL_MS = 60_000;
 async function checkMnestra(config) {
   const rag = config.rag || {};
   const url = rag.mnestraWebhookUrl
-    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '/health')
-    : 'http://localhost:37778/health';
+    ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '/healthz')
+    : 'http://localhost:37778/healthz';
 
   const body = await httpGet(url, 3000);
   const data = tryParseJSON(body);
-  const total = data && (data.total || data.memories || data.count);
+  const total = data && (data.store?.rows ?? data.total ?? data.memories ?? data.count ?? null);
   if (total != null) {
     return { name: 'mnestra_reachable', passed: true, detail: `${Number(total).toLocaleString()} memories` };
   }
@@ -45,9 +45,9 @@ async function checkMnestraMemories(config) {
     ? rag.mnestraWebhookUrl.replace(/\/mnestra\/?$/, '')
     : 'http://localhost:37778';
 
-  const body = await httpGet(`${baseUrl}/health`, 3000);
+  const body = await httpGet(`${baseUrl}/healthz`, 3000);
   const data = tryParseJSON(body);
-  const total = data && (data.total || data.memories || data.count);
+  const total = data && (data.store?.rows ?? data.total ?? data.memories ?? data.count ?? null);
   if (total != null && Number(total) > 0) {
     return { name: 'mnestra_has_memories', passed: true, detail: `${Number(total).toLocaleString()} memories loaded` };
   }