@jhizzard/termdeck 0.3.8 → 0.4.0

package/README.md

@@ -161,7 +161,7 @@ Honest limits, stated upfront so the skeptic has nothing to chase:
 - **Not a replacement for reading docs.** It's the shortest path to a memory you already wrote. If the memory isn't there, the feature does nothing.
 - **Not fully local by default.** Tier 2+ reaches out to Supabase for storage and OpenAI for embeddings. Tier 1 is fully local. A fully-local Tier 2 (local Postgres + local embeddings) is on the roadmap.
 - **Not free forever.** Tier 2+ pays OpenAI fractions of a cent per memory for embeddings. Self-hosted embeddings via Ollama are on the roadmap.
-- **Not proven at scale.** v0.3.8, validated against 3,527 memories in one developer's production store. First full Rumen kickstart on 2026-04-15 processed 111 sessions into 111 insights in one pass. No multi-user data yet. Bug reports and issues welcome.
+- **Not proven at scale.** v0.4.0, validated against 3,527 memories in one developer's production store. First full Rumen kickstart on 2026-04-15 processed 111 sessions into 111 insights in one pass. No multi-user data yet. Bug reports and issues welcome.
 
 ---
 

package/config/config.example.yaml

@@ -7,6 +7,14 @@ shell: /bin/zsh    # or /bin/bash
 
 defaultTheme: tokyo-night
 
+# Mnestra (pgvector memory store) integration
+# Controls whether scripts/start.sh launches `mnestra serve` automatically.
+#   autoStart: true   — start mnestra serve automatically when TermDeck boots
+#   autoStart: false  — never auto-start (leave Mnestra management to the user)
+#   (unset)           — start.sh prints a hint but does not launch
+mnestra:
+  autoStart: true
+
 # Project definitions
 # Each project maps a name to a directory + defaults
 # These appear in the prompt bar dropdown and enable auto-cd + default themes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"
@@ -34,7 +34,7 @@
     "express": "^4.18.2",
     "open": "^10.0.0",
     "pg": "^8.20.0",
-    "uuid": "^9.0.0",
+    "uuid": "^13.0.0",
     "ws": "^8.16.0",
     "yaml": "^2.3.4"
   },

package/packages/client/public/app.js

@@ -1,7 +1,8 @@
 /* Extracted from index.html 2026-04-15 — see git blame on index.html prior to commit UNCOMMITTED for history */
     // ===== TermDeck Client =====
     const API = window.location.origin;
-    const WS_BASE = `ws://${window.location.host}/ws`;
+    const WS_PROTOCOL = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    const WS_BASE = `${WS_PROTOCOL}//${window.location.host}/ws`;
 
     // State
     const state = {
@@ -122,6 +123,7 @@
             <span class="panel-type">${getTypeLabel(meta.type)}</span>
             ${meta.project ? `<span class="panel-project ${projClass}">${meta.project}</span>` : ''}
             <span class="panel-index" id="idx-${id}"></span>
+            <span class="panel-sid" title="Session ID: ${id}">${id.slice(0, 8)}</span>
             <span class="panel-status" id="status-${id}">${meta.statusDetail || meta.status}</span>
           </div>
           <div class="panel-header-right">
@@ -2032,7 +2034,7 @@
       {
         target: '.topbar-center',
         title: 'Layout modes',
-        body: `Seven preset grid layouts — <kbd>1x1</kbd> through <kbd>4x2</kbd> plus <strong>control</strong> (aggregate activity feed). Click any layout to switch instantly; all terminals re-fit to the new grid. Keyboard shortcuts <kbd>Cmd+Shift+1</kbd>–<kbd>Cmd+Shift+6</kbd> (or <kbd>Ctrl+Shift+1</kbd>–<kbd>6</kbd>) do the same.`,
+        body: `Eight preset grid layouts — <kbd>1x1</kbd> through <kbd>4x2</kbd>, <strong>orch</strong> (1 large + stacked, for 4+1 sprints), plus <strong>control</strong> (aggregate activity feed). Click any layout to switch instantly; all terminals re-fit to the new grid. Keyboard shortcuts <kbd>Cmd+Shift+1</kbd>–<kbd>Cmd+Shift+7</kbd> (or <kbd>Ctrl+Shift+1</kbd>–<kbd>7</kbd>) do the same.`,
       },
       {
         target: '#termSwitcher',
@@ -2508,10 +2510,10 @@
           document.getElementById('promptInput').focus();
         }
       }
-      // Ctrl+Shift+1-6 OR Cmd+Shift+1-6 → layout switch (Mac friendly)
-      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key >= '1' && e.key <= '6') {
+      // Ctrl+Shift+1-7 OR Cmd+Shift+1-7 → layout switch (Mac friendly)
+      if ((e.ctrlKey || e.metaKey) && e.shiftKey && e.key >= '1' && e.key <= '7') {
         e.preventDefault();
-        const layouts = ['1x1', '2x1', '2x2', '3x2', '2x4', '4x2'];
+        const layouts = ['1x1', '2x1', '2x2', '3x2', '2x4', '4x2', 'orch'];
         setLayout(layouts[parseInt(e.key) - 1]);
       }
       // Ctrl+Shift+] / [ → cycle between terminals

package/packages/client/public/index.html

@@ -41,6 +41,7 @@
         <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" data-layout="orch" title="Orchestrator: 1 large left + stacked right">orch</button>
         <button class="layout-btn control-btn" data-layout="control" title="Aggregate activity feed">control</button>
       </div>
     </div>

package/packages/client/public/style.css

@@ -312,6 +312,16 @@
     .grid-container.layout-4x2 { grid-template-columns: 1fr 1fr 1fr 1fr; grid-template-rows: 1fr 1fr; }
     .grid-container.layout-2x4 { grid-template-columns: 1fr 1fr; grid-template-rows: 1fr 1fr 1fr 1fr; }
 
+    /* Orchestrator: 1 large left panel (60%), remaining stack on the right (40%). */
+    .grid-container.layout-orch {
+      grid-template-columns: 3fr 2fr;
+      grid-auto-rows: 1fr;
+    }
+    .grid-container.layout-orch .term-panel:first-child {
+      grid-row: 1 / -1;
+      grid-column: 1;
+    }
+
     /* Focus mode: single terminal fills the grid */
     .grid-container.layout-focus { grid-template-columns: 1fr; grid-template-rows: 1fr; }
     .grid-container.layout-focus .term-panel:not(.focused) { display: none; }
@@ -393,6 +403,19 @@
     }
     .panel-index:empty { display: none; }
 
+    /* Short session ID (first 8 chars) — orchestrator-friendly: lets the
+       overseer reference a terminal without hitting the API. */
+    .panel-sid {
+      font-family: 'SF Mono', 'JetBrains Mono', Consolas, monospace;
+      font-size: 10px;
+      color: var(--tg-text-dim);
+      background: var(--tg-surface-hover);
+      padding: 1px 5px;
+      border-radius: 3px;
+      letter-spacing: 0.3px;
+      white-space: nowrap;
+    }
+
     .panel-project {
       font-size: 10px;
       padding: 1px 7px;

package/packages/server/src/index.js

@@ -133,6 +133,11 @@ function createServer(config) {
   // ==================== REST API ====================
 
   // GET /api/health - preflight health checks (Sprint 6 T1, wired by T3)
+  // SECURITY NOTE: Returns operational detail (memory counts, DB latency, project paths,
+  // RAG breaker state). Intentional for local-first use — TermDeck binds to 127.0.0.1 by
+  // default and the CLI guardrail blocks beyond-localhost binds without explicit opt-in.
+  // For any non-loopback deployment (Sprint 18+ remote story), gate this route behind auth
+  // or scope the response to a minimal {status, version} payload.
   app.get('/api/health', createHealthHandler(config));
 
   // GET /api/sessions - list all active sessions

package/packages/server/src/rag.js

@@ -59,8 +59,12 @@ class RAGIntegration {
     };
 
     // Circuit breaker: track consecutive 404s per table name.
-    // After 3 consecutive 404s, disable pushes to that table until restart.
-    this._circuitBreaker = new Map(); // table -> { count: number, open: boolean }
+    // After 3 consecutive 404s, open the breaker. The breaker auto-transitions
+    // to half-open after 5 minutes, allowing one retry attempt. A successful
+    // retry fully resets the breaker; a failed retry re-opens it for another
+    // 5-minute backoff window.
+    this._circuitBreaker = new Map(); // table -> { count, open, openedAt, halfOpen }
+    this._halfOpenDelayMs = 5 * 60 * 1000;
 
     if (this.enabled) {
       this._startSync();
@@ -142,23 +146,35 @@ class RAGIntegration {
     }, this._projectFor(session));
   }
 
-  // Circuit breaker check — returns true if pushes to this table are disabled
+  // Circuit breaker check — returns true if pushes to this table are disabled.
+  // Has a side effect: when the 5-minute half-open window has elapsed, flips
+  // the breaker to half-open and permits one retry attempt through.
   _isCircuitOpen(table) {
     const state = this._circuitBreaker.get(table);
-    return !!(state && state.open);
+    if (!state || !state.open) return false;
+    if (state.halfOpen) return true; // retry already in flight — block concurrent pushes
+
+    const elapsed = Date.now() - (state.openedAt || 0);
+    if (elapsed >= this._halfOpenDelayMs) {
+      state.halfOpen = true;
+      console.log(`[rag] circuit breaker half-open for ${table}, retrying`);
+      return false; // allow one attempt through
+    }
+    return true;
   }
 
   // Record a 404 for a table; opens the breaker after 3 consecutive hits
   _record404(table) {
     let state = this._circuitBreaker.get(table);
     if (!state) {
-      state = { count: 0, open: false };
+      state = { count: 0, open: false, openedAt: null, halfOpen: false };
       this._circuitBreaker.set(table, state);
     }
     state.count += 1;
     if (state.count >= 3 && !state.open) {
       state.open = true;
-      console.error(`[rag] circuit breaker open for ${table} — 3 consecutive 404s, disabling pushes until server restart`);
+      state.openedAt = Date.now();
+      console.warn(`[rag] circuit breaker open for ${table} — disabling pushes (table may not exist in Supabase)`);
     }
   }
 
@@ -208,7 +224,16 @@ class RAGIntegration {
       // Success — reset any accumulated 404 count for this table
       this._resetCircuit(table);
     } catch (err) {
-      console.error('[mnestra] Push failed:', err.message);
+      const state = this._circuitBreaker.get(table);
+      if (state && state.halfOpen) {
+        // Half-open retry failed — re-open for another 5-minute backoff window
+        state.halfOpen = false;
+        state.openedAt = Date.now();
+        console.warn(`[rag] circuit breaker re-opened for ${table} after half-open retry failed`);
+      } else if (!state || !state.open) {
+        // Log at warn (not error) to reduce noise — the circuit breaker handles persistence
+        console.warn('[rag] push to', table, 'failed:', err.message);
+      }
       throw err; // Propagate to caller so sync loop knows this event failed
     }
   }
@@ -243,7 +268,8 @@ class RAGIntegration {
             });
             synced.push(event.id);
           } catch (err) {
-            console.error('[rag] sync push failed for event', event.id + ':', err);
+            // Don't print full stack traces for expected 404s (missing tables)
+            console.debug('[rag] sync push failed for event', event.id + ':', err.message);
             break; // Stop on first failure, retry next cycle
           }
         }

package/packages/server/src/transcripts.js

@@ -46,6 +46,8 @@ class TranscriptWriter {
     // Lazy pool
     this._pool = null;
     this._poolFailed = false;
+    this._poolFailedAt = 0;
+    this._poolRetryMs = 30_000;
 
     // Start flush timer
     this._timer = null;
@@ -56,7 +58,13 @@ class TranscriptWriter {
 
   // Lazy-init pg.Pool (same pattern as getRumenPool in index.js)
   _getPool() {
-    if (this._pool || this._poolFailed) return this._pool;
+    if (this._pool) return this._pool;
+    if (this._poolFailed) {
+      if (Date.now() - this._poolFailedAt < this._poolRetryMs) return null;
+      console.warn('[transcript] retrying pool creation after 30s cooldown');
+      this._poolFailed = false;
+      this._poolFailedAt = 0;
+    }
     if (!pg || !this._databaseUrl) return null;
     try {
       this._pool = new pg.Pool({
@@ -72,6 +80,7 @@ class TranscriptWriter {
     } catch (err) {
       console.error('[transcript] pool creation failed:', err.message);
       this._poolFailed = true;
+      this._poolFailedAt = Date.now();
       return null;
     }
   }