npm - @jhizzard/termdeck - Versions diffs - 0.16.1 → 0.18.0 - Mend

@jhizzard/termdeck 0.16.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/package.json +1 -1
package/packages/client/public/app.js +7 -12
package/packages/client/public/flashback-history.html +35 -0
package/packages/client/public/flashback-history.js +60 -13
package/packages/client/public/graph.html +5 -0
package/packages/client/public/graph.js +37 -0
package/packages/client/public/index.html +2 -3
package/packages/client/public/launcher-resolver.js +5 -1
package/packages/client/public/style.css +31 -0
package/packages/server/src/agent-adapters/claude.js +11 -1
package/packages/server/src/agent-adapters/codex.js +30 -0
package/packages/server/src/agent-adapters/gemini.js +55 -0
package/packages/server/src/agent-adapters/grok.js +139 -0
package/packages/server/src/index.js +67 -1
package/packages/server/src/mcp-autowire.js +253 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.16.1",
+  "version": "0.18.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"

package/packages/client/public/app.js CHANGED Viewed

@@ -4,6 +4,13 @@
     const WS_PROTOCOL = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
     const WS_BASE = `${WS_PROTOCOL}//${window.location.host}/ws`;
+    // ===== Utilities =====
+    function escapeHtml(str) {
+      const div = document.createElement('div');
+      div.textContent = str;
+      return div.innerHTML;
+    }
     // State
     const state = {
       sessions: new Map(),   // id → { session, terminal, ws, fitAddon, el }
@@ -2654,12 +2661,6 @@
       }
     }
-    function escapeHtml(str) {
-      const div = document.createElement('div');
-      div.textContent = str;
-      return div.innerHTML;
-    }
     function updateGlobalStats(sessions) {
       let active = 0, thinking = 0, idle = 0;
       for (const s of sessions) {
@@ -4257,12 +4258,6 @@
       dropdown.innerHTML = html;
     }
-    function escapeHtml(str) {
-      const div = document.createElement('div');
-      div.textContent = str;
-      return div.innerHTML;
-    }
     function toggleHealthDropdown() {
       if (healthState.dropdownOpen) {
         closeHealthDropdown();

package/packages/client/public/flashback-history.html CHANGED Viewed

@@ -271,6 +271,41 @@
       margin-bottom: 16px;
       font-size: 13px;
     }
+    /* Pagination (Sprint 49 T2) */
+    .fb-pagination {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      gap: 12px;
+      padding: 16px;
+      margin-top: 8px;
+    }
+    .fb-pag-info {
+      font-size: 12px;
+      color: var(--tg-text-dim);
+      font-family: var(--tg-mono);
+    }
+    .fb-pag-btn {
+      background: var(--tg-bg);
+      color: var(--tg-text);
+      border: 1px solid var(--tg-border);
+      border-radius: var(--tg-radius-sm);
+      padding: 4px 10px;
+      font-size: 12px;
+      font-family: var(--tg-mono);
+      cursor: pointer;
+      transition: all 0.15s;
+    }
+    .fb-pag-btn:hover:not(:disabled) {
+      background: var(--tg-surface-hover);
+      border-color: var(--tg-border-active);
+      color: var(--tg-text-bright);
+    }
+    .fb-pag-btn:disabled {
+      opacity: 0.3;
+      cursor: not-allowed;
+    }
   </style>
 </head>
 <body class="fb-page">

package/packages/client/public/flashback-history.js CHANGED Viewed

@@ -13,10 +13,13 @@
 // Vanilla JS, no framework — matches the rest of public/.
 (() => {
-  const API = window.location.origin;
+const API = window.location.origin;
+const PAGE_SIZE = 25;
-  const els = {
-    windowSel: document.getElementById('fbWindow'),
+let _allEvents = [];
+let _currentPage = 1;
+const els = {    windowSel: document.getElementById('fbWindow'),
     refreshBtn: document.getElementById('fbRefresh'),
     errorBanner: document.getElementById('fbErrorBanner'),
     content: document.getElementById('fbContent'),
@@ -154,8 +157,12 @@
     `;
   }
-  function renderTable(events) {
-    const rows = events.map((e) => {
+  function renderTable(events, page = 1) {
+    const totalPages = Math.ceil(events.length / PAGE_SIZE) || 1;
+    const start = (page - 1) * PAGE_SIZE;
+    const slice = events.slice(start, start + PAGE_SIZE);
+    const rows = slice.map((e) => {
       const projectCell = e.project
         ? `<span class="fb-cell-project">${escapeHtml(e.project)}</span>`
         : `<span class="fb-cell-project" style="color:var(--tg-text-dim)">—</span>`;
@@ -183,7 +190,7 @@
       `;
     }).join('');
-    els.content.innerHTML = `
+    let html = `
       <div class="fb-table-wrap">
         <table class="fb-table">
           <thead>
@@ -200,6 +207,36 @@
         </table>
       </div>
     `;
+    if (events.length > PAGE_SIZE) {
+      html += `
+        <div class="fb-pagination">
+          <button type="button" class="fb-pag-btn" id="fbPrev" ${page <= 1 ? 'disabled' : ''}>&larr; Prev</button>
+          <span class="fb-pag-info">Page ${page} of ${totalPages}</span>
+          <button type="button" class="fb-pag-btn" id="fbNext" ${page >= totalPages ? 'disabled' : ''}>Next &rarr;</button>
+        </div>
+      `;
+    }
+    els.content.innerHTML = html;
+    // Wire pagination buttons
+    const prevBtn = document.getElementById('fbPrev');
+    const nextBtn = document.getElementById('fbNext');
+    if (prevBtn) {
+      prevBtn.onclick = () => {
+        _currentPage--;
+        localStorage.setItem('fbHistoryPage', String(_currentPage));
+        renderTable(_allEvents, _currentPage);
+      };
+    }
+    if (nextBtn) {
+      nextBtn.onclick = () => {
+        _currentPage++;
+        localStorage.setItem('fbHistoryPage', String(_currentPage));
+        renderTable(_allEvents, _currentPage);
+      };
+    }
   }
   function showError(msg) {
@@ -211,7 +248,7 @@
     els.errorBanner.textContent = '';
   }
-  async function refresh() {
+  async function refresh(resetPage = true) {
     clearError();
     els.content.innerHTML = `<div class="fb-loading">Loading flashback history…</div>`;
@@ -219,7 +256,7 @@
     const since = sinceFromWindow(winKey);
     const qs = new URLSearchParams();
     if (since) qs.set('since', since);
-    qs.set('limit', '200');
+    qs.set('limit', '500'); // Sprint 49: raised from 200 for better pagination scale
     let data;
     try {
@@ -235,24 +272,34 @@
       return;
     }
+    _allEvents = data.events || [];
     renderFunnel(data.funnel || { fires: 0, dismissed: 0, clicked_through: 0 });
-    if (!Array.isArray(data.events) || data.events.length === 0) {
+    if (_allEvents.length === 0) {
       renderZeroState(winKey);
       return;
     }
-    renderTable(data.events);
+    if (resetPage) {
+      _currentPage = 1;
+      localStorage.setItem('fbHistoryPage', '1');
+    } else {
+      _currentPage = parseInt(localStorage.getItem('fbHistoryPage') || '1', 10);
+      const maxPage = Math.ceil(_allEvents.length / PAGE_SIZE) || 1;
+      if (_currentPage > maxPage) _currentPage = 1;
+    }
+    renderTable(_allEvents, _currentPage);
   }
   // Wire controls
   els.windowSel.addEventListener('change', () => {
     writeStateToUrl();
-    refresh();
+    refresh(true);
   });
-  els.refreshBtn.addEventListener('click', () => refresh());
+  els.refreshBtn.addEventListener('click', () => refresh(true));
   // Boot
   loadStateFromUrl();
-  refresh();
+  refresh(false);
 })();

package/packages/client/public/graph.html CHANGED Viewed

@@ -40,6 +40,11 @@
     </div>
   </header>
+  <div class="graph-presets" id="graphPresets" role="toolbar" aria-label="Filter presets">
+    <button type="button" class="gf-preset" id="presetAll">All</button>
+    <button type="button" class="gf-preset" id="presetNone">None</button>
+  </div>
   <div class="graph-filters" id="graphFilters" role="toolbar" aria-label="Edge type filters"></div>
   <div class="graph-filters graph-filters-row2" id="graphControls" role="toolbar" aria-label="Graph view controls">

package/packages/client/public/graph.js CHANGED Viewed

@@ -410,6 +410,7 @@
     const keys = Object.keys(EDGE_COLORS).filter((k) => present.has(k));
     if (keys.length === 0) {
       wrap.style.display = 'none';
+      updatePresetButtons();
       return;
     }
     wrap.style.display = '';
@@ -429,10 +430,27 @@
         if (state.activeKinds.has(k)) state.activeKinds.delete(k);
         else state.activeKinds.add(k);
         chip.classList.toggle('active');
+        updatePresetButtons();
         applyFilter();
       });
       wrap.appendChild(chip);
     }
+    updatePresetButtons();
+  }
+  function isAllKindsActive() {
+    return state.activeKinds.size === Object.keys(EDGE_COLORS).length;
+  }
+  function isNoKindsActive() {
+    return state.activeKinds.size === 0;
+  }
+  function updatePresetButtons() {
+    const allBtn = $('presetAll');
+    const noneBtn = $('presetNone');
+    if (allBtn) allBtn.disabled = isAllKindsActive();
+    if (noneBtn) noneBtn.disabled = isNoKindsActive();
   }
   function applyFilter() {
@@ -843,6 +861,25 @@
     });
     $('graphFit').addEventListener('click', () => fitToView());
+    // Sprint 49 T3 — chip filter presets (All/None). Wire once; renderFilters()
+    // keeps their disabled state in sync with activeKinds boundary conditions.
+    const presetAll = $('presetAll');
+    const presetNone = $('presetNone');
+    if (presetAll) {
+      presetAll.addEventListener('click', () => {
+        state.activeKinds = new Set(Object.keys(EDGE_COLORS));
+        renderFilters();
+        applyFilter();
+      });
+    }
+    if (presetNone) {
+      presetNone.addEventListener('click', () => {
+        state.activeKinds = new Set();
+        renderFilters();
+        applyFilter();
+      });
+    }
     // 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).

package/packages/client/public/index.html CHANGED Viewed

@@ -58,9 +58,8 @@
         <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-sprint" title="Define and kick off a 4+1 sprint">sprint</button>
+      <button id="btn-status" title="Global metrics: session counts, RAG mode, and memory bridge status">status</button>
+      <button id="btn-config" title="Configuration: project list, theme defaults, and live RAG-mode toggle">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>

package/packages/client/public/launcher-resolver.js CHANGED Viewed

@@ -24,6 +24,10 @@
     root.LauncherResolver = factory();
   }
 })(typeof self !== 'undefined' ? self : this, function () {
+  function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  }
   function resolve(command, project, agentAdapters, projects) {
     let resolvedCommand = command;
     let resolvedType = 'shell';
@@ -36,7 +40,7 @@
     }
     const adapter = (agentAdapters || []).find((a) =>
-      a && a.binary && new RegExp(`^${a.binary}\\b`, 'i').test(canonical)
+      a && a.binary && new RegExp(`^${escapeRegex(a.binary)}\\b`, 'i').test(canonical)
     );
     if (adapter) {

package/packages/client/public/style.css CHANGED Viewed

@@ -3567,6 +3567,37 @@
       background: rgba(255, 255, 255, 0.08);
     }
+    /* Sprint 49 T3 — graph chip filter presets (Surface 2 from Sprint 46 audit).
+       Subtle variant of .gf-chip: smaller, no dot/count, secondary tint,
+       disabled state for boundary (all/none already active). Placed above
+       the chip row. */
+    .graph-presets {
+      display: flex;
+      gap: 6px;
+      padding: 8px 16px 4px;
+      background: var(--tg-surface);
+      border-bottom: 1px solid var(--tg-border);
+      flex-shrink: 0;
+    }
+    .gf-preset {
+      padding: 2px 10px;
+      font-size: 10px;
+      font-family: var(--tg-mono);
+      color: var(--tg-text-dim);
+      background: var(--tg-bg);
+      border: 1px solid var(--tg-border);
+      border-radius: 999px;
+      cursor: pointer;
+      transition: all 150ms;
+      opacity: 0.7;
+    }
+    .gf-preset:hover { opacity: 1; background: var(--tg-surface-hover); }
+    .gf-preset:disabled {
+      opacity: 0.35;
+      cursor: not-allowed;
+      background: transparent;
+    }
     /* 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

package/packages/server/src/agent-adapters/claude.js CHANGED Viewed

@@ -7,7 +7,8 @@
 // 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):
+// Contract (memorialization doc § 4 + lane brief T3, extended in Sprint 47
+// T3 with `acceptsPaste` and Sprint 48 T1 with `mcpConfig`):
 //   {
 //     name:           string,                     // adapter id used in registry
 //     sessionType:    string,                     // session.meta.type produced
@@ -19,6 +20,10 @@
 //     parseTranscript:(raw) => Memory[],          // for memory-session-end hook
 //     bootPromptTemplate: (lane, sprint) => string,
 //     costBand:       'free' | 'pay-per-token' | 'subscription',
+//     acceptsPaste:   boolean,                    // Sprint 47 T3 — bracketed-paste capable
+//     mcpConfig:      { path, format, mnestraBlock, detectExisting } | null,
+//                                                 // Sprint 48 T1 — per-agent MCP auto-wire
+//                                                 // null = user-managed (Claude only)
 //   }
 //
 // `statusFor` returns null when no pattern matches — preserves the original
@@ -157,6 +162,11 @@ const claudeAdapter = {
   // The two-stage submit pattern (paste then \r alone) is the canonical inject
   // shape for this adapter; chunked-fallback is unnecessary.
   acceptsPaste: true,
+  // Sprint 48 T1 — Claude's MCP config (~/.claude.json) is owned by the user
+  // and `claude mcp add`. Auto-wiring a Mnestra block here would conflict
+  // with that surface. `null` declares the contract field while signalling
+  // "user-managed; mcp-autowire.js short-circuits to skipped:no-mcpConfig".
+  mcpConfig: null,
 };
 module.exports = claudeAdapter;

package/packages/server/src/agent-adapters/codex.js CHANGED Viewed

@@ -197,6 +197,36 @@ const codexAdapter = {
   // Sprint 47 T3 — Codex's Ratatui TUI accepts bracketed-paste per the
   // Sprint 45 T1 audit; safe to use the two-stage submit pattern unchanged.
   acceptsPaste: true,
+  // Sprint 48 T1 — per-agent MCP auto-wire descriptor consumed by
+  // packages/server/src/mcp-autowire.js. Codex reads MCP servers from
+  // ~/.codex/config.toml in the canonical `[mcp_servers.NAME]` shape with a
+  // sibling `[mcp_servers.NAME.env]` table (snake_case, NOT camelCase — that
+  // distinguishes Codex's TOML schema from the JSON-based agents).
+  mcpConfig: {
+    path: '~/.codex/config.toml',
+    format: 'toml',
+    mnestraBlock: ({ secrets }) => {
+      const lines = ['[mcp_servers.mnestra]', 'command = "mnestra"'];
+      const wanted = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+      const env = {};
+      for (const k of wanted) {
+        if (secrets && typeof secrets[k] === 'string' && secrets[k].length > 0) {
+          env[k] = secrets[k];
+        }
+      }
+      if (Object.keys(env).length > 0) {
+        lines.push('');
+        lines.push('[mcp_servers.mnestra.env]');
+        for (const [k, v] of Object.entries(env)) {
+          // TOML basic-string escaping — backslash + double-quote.
+          const escaped = String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+          lines.push(`${k} = "${escaped}"`);
+        }
+      }
+      return lines.join('\n') + '\n';
+    },
+    detectExisting: (text) => /^\s*\[mcp_servers\.mnestra\]\s*$/m.test(text),
+  },
 };
 module.exports = codexAdapter;

package/packages/server/src/agent-adapters/gemini.js CHANGED Viewed

@@ -126,6 +126,54 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
   ].join('\n');
 }
+// ──────────────────────────────────────────────────────────────────────────
+// mcpConfig — Sprint 48 T2. Declarative description of where Gemini reads
+// its MCP-server registry and how to write a Mnestra entry into it. The
+// shared helper at packages/server/src/mcp-autowire.js (Sprint 48 T1) uses
+// this on panel spawn to ensure `memory_recall` is available out-of-the-box
+// for outside users running mixed 4+1 with a Gemini lane.
+//
+// Schema reference: https://www.geminicli.com/docs/tools/mcp-server
+// (verified 2026-05-02). Top-level key is `mcpServers` (camelCase). Each
+// entry must specify exactly one transport — `command` (stdio), `url`
+// (SSE), or `httpUrl` (HTTP streaming). Mnestra ships as a stdio binary
+// (`mnestra`), so we use `command`.
+//
+// Note (no `type` field): the `type: 'stdio'` field used in the Claude
+// Code config (~/.claude.json `mcp_servers.mnestra.type`) is a Claude-Code
+// extension. Gemini infers transport from which of command/url/httpUrl is
+// set, so we omit `type` here to keep the entry valid against the
+// documented Gemini schema.
+//
+// Note (restart required): Gemini CLI discovers MCP servers at startup, so
+// adding a new entry only takes effect on the next `gemini` launch. The
+// helper still writes immediately on panel spawn — by the time the user
+// types `gemini` in the panel, the entry is in place.
+//
+// Note (env-key omission): empty/missing secrets are intentionally
+// dropped from the env object instead of written as empty strings. This
+// matches stack-installer/src/index.js:336-339 — concrete-or-omit, never
+// placeholder, because Gemini (like Claude Code) does not shell-expand
+// `${VAR}` references in MCP env. Mnestra's own secrets.env fallback
+// loads what's missing at process start.
+// ──────────────────────────────────────────────────────────────────────────
+const MNESTRA_ENV_KEYS = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+function buildMnestraBlock({ secrets } = {}) {
+  const env = {};
+  for (const key of MNESTRA_ENV_KEYS) {
+    const value = secrets && secrets[key];
+    if (value) env[key] = value;
+  }
+  return {
+    mnestra: {
+      command: 'mnestra',
+      env,
+    },
+  };
+}
 const geminiAdapter = {
   name: 'gemini',
   sessionType: 'gemini',
@@ -156,6 +204,13 @@ const geminiAdapter = {
   // Sprint 47 T3 — Gemini's CLI is paste-friendly per the single-JSON-object
   // session shape captured in Sprint 45 T2; bracketed-paste injects cleanly.
   acceptsPaste: true,
+  // Sprint 48 T2 — see comment block above for schema notes + provenance.
+  mcpConfig: {
+    path: '~/.gemini/settings.json',
+    format: 'json',
+    mcpServersKey: 'mcpServers',
+    mnestraBlock: buildMnestraBlock,
+  },
 };
 module.exports = geminiAdapter;

package/packages/server/src/agent-adapters/grok.js CHANGED Viewed

@@ -218,6 +218,136 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
   ].join('\n');
 }
+// ──────────────────────────────────────────────────────────────────────────
+// mcpConfig — Sprint 48 T3. Grok's MCP-server registry lives at
+// `~/.grok/user-settings.json` under the `mcp.servers` key, which is an
+// **ARRAY** of `McpServerConfig` items, NOT a record `mcpServers.NAME` like
+// Codex/Gemini use. Authoritative schema lifted from
+// `/usr/local/lib/node_modules/grok-dev/dist/utils/settings.{d.ts,js}`
+// (Bun-bundled source, package `grok-dev` v1.1.5):
+//
+//   interface McpServerConfig {
+//     id: string; label: string; enabled: boolean;
+//     transport: "http" | "sse" | "stdio";
+//     command?, args?, env?, cwd?, url?, headers?
+//   }
+//   interface McpSettings { servers?: McpServerConfig[] }
+//   interface UserSettings { ..., mcp?: McpSettings }
+//   function loadMcpServers(): UserSettings.mcp?.servers ?? []
+//   function saveMcpServers(servers): saveUserSettings({ mcp: { servers } })
+//
+// Hot-load behavior: agent.js calls `loadMcpServers()` at the start of every
+// agent turn (3 sites: stream / batch / child-agent), so MCP changes are
+// picked up on the next user message — no Grok restart required.
+//
+// Schema-divergence implication: the `mcpServersKey + mnestraBlock` record-
+// merge shape used by gemini.js (Sprint 48 T2) and the TOML-append shape used
+// by codex.js cannot represent Grok's array-with-explicit-id-fields layout.
+// Grok therefore declares a `merge(rawText, { secrets }) -> { changed, output }`
+// escape-hatch on its `mcpConfig`. The shared `mcp-autowire.js` helper
+// (Sprint 48 T1) checks for `mcpConfig.merge` first; if present, the adapter
+// owns parse + mutate + serialize, the helper still owns tilde-expansion +
+// parent-dir creation + atomic write + idempotency reporting. See Sprint 48
+// STATUS.md § T3 FIX-PROPOSED for the coordination decision.
+//
+// Env-key omission discipline matches stack-installer/src/index.js:336-339
+// and the Gemini adapter: empty/missing/`${VAR}`-placeholder values are
+// dropped from the env object instead of written as empty strings, because
+// Grok (like Claude Code and Gemini) does not shell-expand `${VAR}` in MCP
+// env. Mnestra's own secrets.env stdio fallback (mnestra@0.3.4) loads what
+// is missing at process start.
+// ──────────────────────────────────────────────────────────────────────────
+const MNESTRA_ENV_KEYS = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+function _pickConcreteEnv(secrets) {
+  const env = {};
+  if (!secrets || typeof secrets !== 'object') return env;
+  for (const key of MNESTRA_ENV_KEYS) {
+    const value = secrets[key];
+    if (typeof value !== 'string') continue;
+    if (value.length === 0) continue;
+    // Reject literal `${VAR}` placeholders — Grok won't shell-expand them.
+    if (/^\$\{[^}]*\}$/.test(value)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+function _buildMnestraServer({ secrets } = {}) {
+  return {
+    id: 'mnestra',
+    label: 'Mnestra',
+    enabled: true,
+    transport: 'stdio',
+    command: 'mnestra',
+    args: [],
+    env: _pickConcreteEnv(secrets),
+  };
+}
+// Deep-equal check scoped to the fields we manage. Unknown extra fields on
+// the existing entry (e.g. user-added `cwd` overrides) are tolerated — we
+// only refresh the entry when one of OUR managed fields drifts. Prevents
+// the helper from clobbering hand-edited Grok customizations on every spawn.
+function _mnestraEntryEqual(existing, desired) {
+  if (!existing || typeof existing !== 'object') return false;
+  for (const key of ['id', 'label', 'enabled', 'transport', 'command']) {
+    if (existing[key] !== desired[key]) return false;
+  }
+  const a = Array.isArray(existing.args) ? existing.args : [];
+  const b = desired.args;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  const ea = existing.env && typeof existing.env === 'object' ? existing.env : {};
+  const eb = desired.env;
+  const eaKeys = Object.keys(ea).sort();
+  const ebKeys = Object.keys(eb).sort();
+  if (eaKeys.length !== ebKeys.length) return false;
+  for (let i = 0; i < eaKeys.length; i += 1) {
+    if (eaKeys[i] !== ebKeys[i]) return false;
+    if (ea[eaKeys[i]] !== eb[ebKeys[i]]) return false;
+  }
+  return true;
+}
+function _mergeMnestraIntoGrokSettings(rawText, { secrets } = {}) {
+  let current = {};
+  if (typeof rawText === 'string' && rawText.trim().length > 0) {
+    try {
+      const parsed = JSON.parse(rawText);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch (_) {
+      // Malformed JSON → start fresh. Helper's atomic-write contract means
+      // we don't risk corrupting the user's file partway through; on read
+      // failure the conservative path is to write a clean replacement that
+      // preserves the keys we know how to round-trip (none — we only own
+      // the mcp branch). User's other settings in a corrupt file are
+      // unrecoverable from text anyway.
+      current = {};
+    }
+  }
+  const next = { ...current };
+  next.mcp = next.mcp && typeof next.mcp === 'object' && !Array.isArray(next.mcp)
+    ? { ...next.mcp }
+    : {};
+  const servers = Array.isArray(next.mcp.servers) ? [...next.mcp.servers] : [];
+  const desired = _buildMnestraServer({ secrets });
+  const existingIdx = servers.findIndex((s) => s && s.id === 'mnestra');
+  if (existingIdx >= 0 && _mnestraEntryEqual(servers[existingIdx], desired)) {
+    return { changed: false, output: rawText };
+  }
+  if (existingIdx >= 0) {
+    servers[existingIdx] = desired;
+  } else {
+    servers.push(desired);
+  }
+  next.mcp.servers = servers;
+  return { changed: true, output: `${JSON.stringify(next, null, 2)}\n` };
+}
 // ──────────────────────────────────────────────────────────────────────────
 // Adapter export. spawn.env.GROK_MODEL defaults to the cheap-fast tier;
 // per-lane override is the launcher's job at session-spawn time (Sprint 46
@@ -260,6 +390,15 @@ const grokAdapter = {
   // lane-time test shows the OpenTUI input handler eats the paste markers,
   // flip this to false and the inject helper falls back to chunked stdin.
   acceptsPaste: true,
+  // Sprint 48 T3 — see comment block above for schema notes + provenance.
+  // Grok deviates from Codex (TOML) and Gemini (JSON record) — its `mcp.servers`
+  // is an array with explicit `id`/`label`/`enabled`/`transport` fields, so the
+  // adapter declares a `merge` escape-hatch instead of `mcpServersKey + mnestraBlock`.
+  mcpConfig: {
+    path: '~/.grok/user-settings.json',
+    format: 'json',
+    merge: _mergeMnestraIntoGrokSettings,
+  },
 };
 module.exports = grokAdapter;

package/packages/server/src/index.js CHANGED Viewed

@@ -81,6 +81,53 @@ const orchestrationPreview = require('./orchestration-preview');
 const { createPtyReaper } = require('./pty-reaper');
 const { AGENT_ADAPTERS } = require('./agent-adapters');
+// Sprint 48 T4 deliverable 2: PTY env-var propagation.
+// Reads ~/.termdeck/secrets.env once per server lifetime so each PTY spawn
+// inherits SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY / OPENAI_API_KEY etc.
+// without depending on the user's shell to have sourced the file.
+//
+// Why this exists: `memory-session-end.js` (the bundled Stop hook installed by
+// `@jhizzard/termdeck-stack`) writes session_summary rows to Mnestra by
+// reading those three vars from `process.env`. When TermDeck spawns a Claude
+// Code panel directly via `pty.spawn`, the child shell inherits the server's
+// `process.env` — but if the *user* didn't source secrets.env in their
+// `.zshrc` before running `termdeck`, those vars are absent and every session
+// close hits `env-var-missing`. Sprint 47 close-out audit confirmed 0
+// session_summary rows had ever landed.
+//
+// Treats `${VAR}` placeholders as unset (Sprint 47.5 hotfix lesson — Claude
+// Code does not shell-expand MCP env values; same trap applies anywhere the
+// secrets file flows through a non-shell consumer).
+let _termdeckSecretsCache = null;
+function readTermdeckSecretsForPty() {
+  if (_termdeckSecretsCache !== null) return _termdeckSecretsCache;
+  const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
+  const out = {};
+  try {
+    const text = fs.readFileSync(secretsPath, 'utf8');
+    for (const raw of text.split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if (v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0]) {
+        v = v.slice(1, -1);
+      }
+      if (v.startsWith('${') && v.endsWith('}')) continue;
+      if (v === '') continue;
+      out[m[1]] = v;
+    }
+  } catch (_err) {
+    // File absent or unreadable — empty merge, hook still hits env-var-missing
+    // until the user runs the wizard. Better than a crash on spawn.
+  }
+  _termdeckSecretsCache = out;
+  return out;
+}
+// Test hook — clear the cache between tests that mutate the on-disk file.
+function _resetTermdeckSecretsCache() { _termdeckSecretsCache = null; }
 // Sprint 37 T3 — lazy resolution of T2's CLI modules. The orchestration-preview
 // helper is decoupled from T2's templates.js / init-project.js; we resolve
 // them here and pass them into the helper. If a module is missing (e.g.
@@ -805,6 +852,18 @@ function createServer(config) {
       const args = (cmdTrim && !isPlainShell) ? ['-c', cmdTrim] : [];
       try {
+        // Sprint 48 T4: merge ~/.termdeck/secrets.env into the PTY env so
+        // the bundled session-end memory hook (`memory-session-end.js`) sees
+        // SUPABASE_URL / SERVICE_ROLE_KEY / OPENAI_API_KEY without depending
+        // on the user's shell to have sourced the file. process.env is the
+        // base; any concrete value the parent already exported wins.
+        const termdeckSecrets = readTermdeckSecretsForPty();
+        const secretFallback = {};
+        for (const [k, v] of Object.entries(termdeckSecrets)) {
+          if (process.env[k] === undefined || process.env[k] === '') {
+            secretFallback[k] = v;
+          }
+        }
         const term = pty.spawn(spawnShell, args, {
           name: 'xterm-256color',
           cols: 120,
@@ -812,6 +871,7 @@ function createServer(config) {
           cwd: resolvedCwd,
           env: {
             ...process.env,
+            ...secretFallback,
             TERMDECK_SESSION: session.id,
             TERMDECK_PROJECT: project || '',
             TERM: 'xterm-256color',
@@ -2162,4 +2222,10 @@ if (require.main === module) {
   });
 }
-module.exports = { createServer, loadConfig };
+module.exports = {
+  createServer,
+  loadConfig,
+  // Sprint 48 T4 — exported for unit testing the secrets.env → PTY env merge.
+  readTermdeckSecretsForPty,
+  _resetTermdeckSecretsCache,
+};

package/packages/server/src/mcp-autowire.js ADDED Viewed

@@ -0,0 +1,253 @@
+// Sprint 48 T1 — Shared per-agent MCP auto-wire helper.
+//
+// Single export: ensureMnestraBlock(adapter, opts?). Idempotent. T1/T2/T3
+// agent adapters (codex, gemini, grok) each ship an `mcpConfig` field
+// describing where their MCP-server config lives, what format it's in,
+// and how to merge a Mnestra entry into it. This helper is the agent-
+// agnostic glue: read the file, dispatch on shape, render+merge+write
+// using the secrets in ~/.termdeck/secrets.env.
+//
+// Why this exists: cross-project memory recall (Mnestra MCP) was unavailable
+// to non-Claude agents by default in Sprint 47's Grok smoke — those CLIs
+// ship without an MCP block and outside users would hit memory_recall
+// failures the first time they spawned a non-Claude lane. This is the
+// v1.0.0 gate-blocker fix.
+//
+// Three adapter shapes are supported (precedence top → bottom):
+//
+//   1. Escape-hatch (Grok-style — array-shape JSON or anything bespoke):
+//        mcpConfig: { path, format, merge: (rawText, {secrets}) =>
+//                                          ({ changed: bool, output: string }) }
+//      Adapter owns parse + mutate + serialize entirely. Helper still owns
+//      tilde expand, mkdir, read, atomic write, return shape.
+//
+//   2. JSON-record (Gemini-style — `{mcpServers: {NAME: {...}}}`):
+//        mcpConfig: { path, format: 'json', mcpServersKey: 'mcpServers',
+//                     mnestraBlock: ({secrets}) => ({mnestra: {command, env}}) }
+//      Helper deep-merges the returned object under `config[mcpServersKey]`.
+//      Existence detected by checking `existing[mcpServersKey]?.mnestra`.
+//
+//   3. TOML-append (Codex-style — `[mcp_servers.NAME]` tables):
+//        mcpConfig: { path, format: 'toml',
+//                     mnestraBlock: ({secrets}) => '[mcp_servers.mnestra]\n...',
+//                     detectExisting: (text) => /\[mcp_servers\.mnestra\]/m.test(text) }
+//      Helper appends the rendered string to the file with one blank-line
+//      separator. Idempotent via the adapter's `detectExisting` predicate.
+//
+// Claude is intentionally exempt — its MCP config (~/.claude.json) is
+// owned by the user and `claude mcp add`. Adding a Mnestra block here
+// would conflict with that surface. Claude's adapter declares
+// `mcpConfig: null` to satisfy the contract-parity tests.
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const SECRETS_PATH = path.join(os.homedir(), '.termdeck', 'secrets.env');
+function expandTilde(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+// dotenv-subset parser. Mirrors stack-installer's readTermdeckSecrets so the
+// two stay byte-equivalent (KEY=value, optional matched single/double quotes,
+// `#` comments, blanks ignored). Returns {} on absent / unreadable file.
+// Rejects literal `${VAR}` placeholder shapes — same defense as the mnestra
+// MCP stdio fallback (Claude Code et al. don't shell-expand them, so writing
+// the literal placeholder is worse than omitting the key entirely).
+function readSecrets(secretsPath = SECRETS_PATH) {
+  try {
+    const text = fs.readFileSync(secretsPath, 'utf8');
+    const out = {};
+    for (const raw of text.split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      let v = m[2];
+      if (
+        v.length >= 2
+        && (v[0] === '"' || v[0] === "'")
+        && v[v.length - 1] === v[0]
+      ) {
+        v = v.slice(1, -1);
+      }
+      if (v.startsWith('${') && v.endsWith('}')) continue;
+      out[m[1]] = v;
+    }
+    return out;
+  } catch (_err) {
+    return {};
+  }
+}
+// One-level-deep merge sufficient for the `mcpServers.NAME` shape. Nested
+// objects under matching keys are themselves merged shallowly; arrays +
+// primitives are replaced.
+function mergeJson(base, addition) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(addition)) {
+    if (
+      v && typeof v === 'object' && !Array.isArray(v)
+      && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k])
+    ) {
+      out[k] = { ...out[k], ...v };
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+// Append a TOML block to existing file content with one blank-line separator
+// (or none if the file is empty). Codex's TOML parser accepts tables in any
+// order so appending is the safe operation; we don't try to surgically
+// rewrite mid-file.
+function appendTomlBlock(existing, block) {
+  const trailing = existing.endsWith('\n') ? '' : '\n';
+  const sep = existing.length === 0 ? '' : trailing + '\n';
+  const blockTail = block.endsWith('\n') ? '' : '\n';
+  return existing + sep + block + blockTail;
+}
+// Detect whether a JSON-shape object already has a Mnestra entry under
+// `mcpServersKey`. Tolerant of the key being absent or non-object.
+function jsonAlreadyHasMnestra(parsedConfig, mcpServersKey) {
+  const bag = parsedConfig && parsedConfig[mcpServersKey];
+  return !!(bag && typeof bag === 'object' && !Array.isArray(bag) && bag.mnestra);
+}
+// Idempotent. Returns one of:
+//   { skipped: true, reason: '...' }     — adapter omits or malforms mcpConfig
+//   { unchanged: true, path }            — block already present
+//   { wrote: true, path, bytes }         — block written / appended
+//
+// opts.secretsPath overrides the default ~/.termdeck/secrets.env (used by
+// tests); opts.secrets passes a pre-parsed object directly (also tests).
+function ensureMnestraBlock(adapter, opts = {}) {
+  if (!adapter || !adapter.mcpConfig) {
+    return { skipped: true, reason: 'no-mcpConfig' };
+  }
+  const cfg = adapter.mcpConfig;
+  if (typeof cfg.path !== 'string') {
+    return { skipped: true, reason: 'malformed-mcpConfig' };
+  }
+  const useMerge = typeof cfg.merge === 'function';
+  const useJsonRecord = !useMerge
+    && cfg.format === 'json'
+    && typeof cfg.mcpServersKey === 'string'
+    && typeof cfg.mnestraBlock === 'function';
+  const useTomlAppend = !useMerge && !useJsonRecord
+    && cfg.format === 'toml'
+    && typeof cfg.mnestraBlock === 'function'
+    && typeof cfg.detectExisting === 'function';
+  const useJsonAppend = !useMerge && !useJsonRecord && !useTomlAppend
+    && cfg.format === 'json'
+    && typeof cfg.mnestraBlock === 'function'
+    && typeof cfg.detectExisting === 'function';
+  if (!useMerge && !useJsonRecord && !useTomlAppend && !useJsonAppend) {
+    return { skipped: true, reason: 'malformed-mcpConfig' };
+  }
+  const target = expandTilde(cfg.path);
+  const dir = path.dirname(target);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  let existing = '';
+  try { existing = fs.readFileSync(target, 'utf8'); } catch (_) { existing = ''; }
+  const secrets = opts.secrets || readSecrets(opts.secretsPath || SECRETS_PATH);
+  // 1. Escape-hatch — adapter owns the merge entirely.
+  if (useMerge) {
+    let result;
+    try { result = cfg.merge(existing, { secrets, adapter }); }
+    catch (e) { return { skipped: true, reason: `merge-threw-${e.message}` }; }
+    if (!result || typeof result !== 'object') {
+      return { skipped: true, reason: 'merge-bad-return' };
+    }
+    if (!result.changed) return { unchanged: true, path: target };
+    if (typeof result.output !== 'string') {
+      return { skipped: true, reason: 'merge-output-not-string' };
+    }
+    fs.writeFileSync(target, result.output, { mode: 0o600 });
+    return { wrote: true, path: target, bytes: Buffer.byteLength(result.output) };
+  }
+  // 2. JSON record-merge (Gemini shape).
+  if (useJsonRecord) {
+    let parsed = {};
+    if (existing.trim() !== '') {
+      try { parsed = JSON.parse(existing); }
+      catch (_) { return { skipped: true, reason: 'existing-json-malformed' }; }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};
+    }
+    if (jsonAlreadyHasMnestra(parsed, cfg.mcpServersKey)) {
+      return { unchanged: true, path: target };
+    }
+    let block;
+    try { block = cfg.mnestraBlock({ secrets, adapter }); }
+    catch (e) { return { skipped: true, reason: `mnestraBlock-threw-${e.message}` }; }
+    if (!block || typeof block !== 'object' || Array.isArray(block)) {
+      return { skipped: true, reason: 'mnestraBlock-not-object' };
+    }
+    const next = { ...parsed };
+    const bag = (next[cfg.mcpServersKey] && typeof next[cfg.mcpServersKey] === 'object'
+                 && !Array.isArray(next[cfg.mcpServersKey]))
+      ? { ...next[cfg.mcpServersKey] }
+      : {};
+    Object.assign(bag, block);
+    next[cfg.mcpServersKey] = bag;
+    const serialized = JSON.stringify(next, null, 2) + '\n';
+    fs.writeFileSync(target, serialized, { mode: 0o600 });
+    return { wrote: true, path: target, bytes: Buffer.byteLength(serialized) };
+  }
+  // 3 & 4. detectExisting + mnestraBlock-string paths (TOML or JSON-append).
+  if (cfg.detectExisting(existing)) {
+    return { unchanged: true, path: target };
+  }
+  let block;
+  try { block = cfg.mnestraBlock({ secrets, adapter }); }
+  catch (e) { return { skipped: true, reason: `mnestraBlock-threw-${e.message}` }; }
+  if (typeof block !== 'string') {
+    return { skipped: true, reason: 'mnestraBlock-not-string' };
+  }
+  let next;
+  if (useTomlAppend) {
+    next = appendTomlBlock(existing, block);
+  } else {
+    // useJsonAppend — original brief shape: mnestraBlock returns JSON text,
+    // helper deep-merges. Used by adapters that prefer to control the
+    // serialization but don't want the escape-hatch's full responsibility.
+    let parsed = {};
+    if (existing.trim() !== '') {
+      try { parsed = JSON.parse(existing); }
+      catch (_) { return { skipped: true, reason: 'existing-json-malformed' }; }
+    }
+    let blockObj;
+    try { blockObj = JSON.parse(block); }
+    catch (_) { return { skipped: true, reason: 'mnestraBlock-not-parseable-json' }; }
+    const merged = mergeJson(parsed, blockObj);
+    next = JSON.stringify(merged, null, 2) + '\n';
+  }
+  fs.writeFileSync(target, next, { mode: 0o600 });
+  return { wrote: true, path: target, bytes: Buffer.byteLength(next) };
+}
+module.exports = {
+  ensureMnestraBlock,
+  readSecrets,
+  expandTilde,
+  // Internals exposed for unit tests; not part of the public API.
+  _internals: { mergeJson, appendTomlBlock, jsonAlreadyHasMnestra, SECRETS_PATH },
+};