@jhizzard/termdeck 1.8.1 → 1.9.0

package/packages/cli/src/init.js

@@ -102,6 +102,7 @@ const HELP = [
   'Sub-mode wizards (callable independently for advanced users):',
   '  termdeck init --mnestra   Configure Tier 2 memory (Supabase + Mnestra)',
   '  termdeck init --rumen     Deploy Tier 3 async learning (Rumen)',
+  '  termdeck init --bridge    Scaffold the Tier 5 Web-Chat Bridge (named tunnel + supervisor)',
   '  termdeck init --project   Scaffold a new project with CLAUDE.md + orchestration docs',
   '',
   'Get a Personal Access Token at: https://supabase.com/dashboard/account/tokens',

package/packages/client/public/app.js

@@ -361,6 +361,80 @@
       }, { capture: true });
     }
 
+    // ===== termdeck#12 input guard (Sprint 73 T3) =====
+    // Runaway-typed-input defense at the single chokepoint every byte of
+    // human browser input flows through (the onData handler registered in
+    // createTerminalPanel). xterm@5.5.0 reconstructs composition input from
+    // its hidden textarea and can re-emit the accumulated buffer-so-far once
+    // per word boundary on IME/mobile/remote keyboards — the #12 cumulative-
+    // prefix runaway (~110 typed chars became a 3,042-char PTY stream).
+    // Detection logic lives in input-guard.js (UMD, unit-tested from node);
+    // these helpers wire it to panel state and the operator surface.
+    // Suppression is loud (console.error + panel toast), never silent;
+    // oversize chunks can be sent anyway from the toast.
+    function shouldSuppressPanelInput(entry, id, data) {
+      if (!entry._inputGuard) entry._inputGuard = InputGuard.createGuard();
+      const result = InputGuard.check(entry._inputGuard, data, Date.now());
+      if (result.verdict === 'pass') return false;
+      console.error(
+        `[input-guard] suppressed ${result.reason} input on panel ${id} ` +
+        `(chunk ${data.length} chars, chain ${result.chainLength}, ` +
+        `total suppressed ${result.suppressedCount} chunks / ${result.suppressedChars} chars):`,
+        JSON.stringify(data.slice(0, 120))
+      );
+      showInputGuardToast(entry, id, result, data);
+      return true;
+    }
+
+    function showInputGuardToast(entry, id, result, data) {
+      if (!entry || !entry.el) return;
+
+      // One toast per panel: repeated suppressions update the counter line
+      // (a runaway fires per word boundary — stacking toasts would bury the
+      // panel) and refresh the held chunk + auto-dismiss timer.
+      const existing = entry.el.querySelector('.input-guard-toast');
+      if (existing) {
+        const counter = existing.querySelector('.t-meta');
+        if (counter) counter.textContent = `${result.suppressedCount} chunks (${result.suppressedChars} chars) suppressed so far.`;
+        if (result.reason === 'oversize') existing._heldChunk = data;
+        clearTimeout(existing._autoTimer);
+        existing._autoTimer = setTimeout(() => existing.remove(), 60000);
+        return;
+      }
+
+      const toast = document.createElement('div');
+      toast.className = 'input-guard-toast';
+      const why = result.reason === 'oversize'
+        ? 'a single typed chunk was implausibly large'
+        : 'the keyboard started re-sending the whole buffer-so-far per keystroke (xterm composition runaway — termdeck#12)';
+      toast.innerHTML = `
+        <button class="t-dismiss" aria-label="Dismiss">×</button>
+        <div class="t-title">Input guard — runaway typing suppressed</div>
+        <div class="t-body">Blocked because ${why}. Check the terminal's input line before pressing Enter; clear it if it shows repeated text.${result.reason === 'oversize' ? ' If this was intentional, send it below.' : ''}</div>
+        <div class="t-meta">${result.suppressedCount} chunks (${result.suppressedChars} chars) suppressed so far.</div>
+        ${result.reason === 'oversize' ? '<button class="t-send-anyway">Send anyway</button>' : ''}
+      `;
+      if (result.reason === 'oversize') toast._heldChunk = data;
+      entry.el.appendChild(toast);
+
+      toast.querySelector('.t-dismiss').addEventListener('click', () => {
+        clearTimeout(toast._autoTimer);
+        toast.remove();
+      });
+      const sendBtn = toast.querySelector('.t-send-anyway');
+      if (sendBtn) {
+        sendBtn.addEventListener('click', () => {
+          const live = state.sessions.get(id);
+          if (toast._heldChunk && live && live.ws && live.ws.readyState === WebSocket.OPEN) {
+            live.ws.send(JSON.stringify({ type: 'input', data: toast._heldChunk }));
+          }
+          clearTimeout(toast._autoTimer);
+          toast.remove();
+        });
+      }
+      toast._autoTimer = setTimeout(() => toast.remove(), 60000);
+    }
+
     // ===== Create Terminal Panel =====
     function createTerminalPanel(sessionData) {
       const id = sessionData.id;
@@ -592,10 +666,20 @@
         }
       };
 
-      // Terminal input → WebSocket
+      // Terminal input → WebSocket. Registered ONCE per Terminal instance and
+      // never re-registered: xterm's onData ADDS listeners, and the
+      // pre-Sprint-73 reconnect path stacked one leaked handler (closed over
+      // its dead socket) per reconnect — the termdeck#12 cause-B family. The
+      // handler dereferences entry.ws at event time, so reconnectSession just
+      // swaps entry.ws and this same registration follows it.
+      // shouldSuppressPanelInput is the #12 runaway chokepoint — every byte
+      // of human browser input to this PTY flows through this closure.
       terminal.onData((data) => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'input', data }));
+        const entry = state.sessions.get(id);
+        if (!entry || entry._mounting || !entry.ws) return;
+        if (shouldSuppressPanelInput(entry, id, data)) return;
+        if (entry.ws.readyState === WebSocket.OPEN) {
+          entry.ws.send(JSON.stringify({ type: 'input', data }));
         }
       });
 
@@ -608,6 +692,49 @@
         panel.classList.remove('active-input');
       });
 
+      // termdeck#12 (Sprint 73 T3) — two defenses on xterm's hidden textarea:
+      //
+      // (a) Paste tracking for the input guard: a DOM `paste` event stamps
+      //     the guard so the following chunk is exempt — pastes are
+      //     deliberate bulk input, and without the stamp a large
+      //     un-bracketed paste would false-trip the oversize detector.
+      //
+      // (b) Idle-clear of the textarea. xterm@5.5.0 clears its helper
+      //     textarea only on non-composition Enter/Ctrl+C keydowns
+      //     (Terminal.ts:1066-1068); on composition keyboards (every keydown
+      //     = keyCode 229: mobile/IME/dictation/remote bridges) that clear
+      //     never fires, the textarea accumulates the whole message, and
+      //     CompositionHelper's replace/substring reconstruction can re-emit
+      //     the accumulated buffer once per word boundary — the #12
+      //     cumulative-prefix runaway. Clearing after a short typing lull
+      //     (never mid-composition; composition state tracked via the public
+      //     compositionstart/end events) bounds what those paths can
+      //     reconstruct to a single typing burst. xterm's own deferred
+      //     textarea reads are setTimeout(0) — far inside the 250ms debounce
+      //     — so the clear cannot race them.
+      const guardTa = terminal.textarea;
+      if (guardTa) {
+        let composing = false;
+        let idleClearTimer = null;
+        const armIdleClear = () => {
+          if (idleClearTimer) clearTimeout(idleClearTimer);
+          idleClearTimer = setTimeout(() => {
+            idleClearTimer = null;
+            if (!composing && guardTa.value) guardTa.value = '';
+          }, 250);
+        };
+        guardTa.addEventListener('compositionstart', () => { composing = true; });
+        guardTa.addEventListener('compositionend', () => { composing = false; armIdleClear(); });
+        guardTa.addEventListener('keydown', armIdleClear);
+        guardTa.addEventListener('input', armIdleClear);
+        guardTa.addEventListener('paste', () => {
+          const entry = state.sessions.get(id);
+          if (!entry) return;
+          if (!entry._inputGuard) entry._inputGuard = InputGuard.createGuard();
+          InputGuard.notePaste(entry._inputGuard, Date.now());
+        });
+      }
+
       // Store reference
       state.sessions.set(id, {
         session: sessionData,
@@ -2443,12 +2570,11 @@
         }
       };
 
-      // Re-wire terminal input
-      entry.terminal.onData((data) => {
-        if (ws.readyState === WebSocket.OPEN) {
-          ws.send(JSON.stringify({ type: 'input', data }));
-        }
-      });
+      // No input re-wiring (Sprint 73 T3, termdeck#12): the single onData
+      // handler registered at panel creation dereferences entry.ws at event
+      // time, so the `entry.ws = ws` assignment in onopen above is all a
+      // reconnect needs. Pre-Sprint-73 this function re-ran terminal.onData()
+      // here, leaking one handler (closed over its dead socket) per reconnect.
     }
 
     function halfPanel(id) {

package/packages/client/public/index.html

@@ -393,6 +393,7 @@
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-web-links@0.11.0/lib/addon-web-links.min.js"></script>
   <script src="launcher-resolver.js" defer></script>
+  <script src="input-guard.js" defer></script>
   <script src="app.js" defer></script>
 </body>
 </html>

package/packages/client/public/input-guard.js

@@ -0,0 +1,192 @@
+// TermDeck input guard — extracted Sprint 73 T3 (termdeck#12, second half)
+//
+// Pure state-machine: given a stream of xterm `onData` chunks for one panel,
+// decide per chunk whether it is plausible human/protocol input (`pass`) or a
+// runaway re-emission of the input buffer (`suppress`). Lives in its own file
+// so the same code runs in the browser (via <script src="input-guard.js">)
+// AND under `node --test` (via `require('.../input-guard')`) — the
+// launcher-resolver.js pattern.
+//
+// Why this exists (termdeck#12, the "input box accumulates buffer-so-far per
+// keystroke" half): on composition-style keyboards — Android/iOS soft
+// keyboards, IMEs, dictation, remote-access keyboard bridges — every keydown
+// reaches xterm as keyCode 229 and xterm@5.5.0 reconstructs the typed data
+// from its hidden helper <textarea>:
+//
+//   1. The textarea is cleared ONLY on a non-composition Enter/Ctrl+C keydown
+//      (xterm src/browser/Terminal.ts:1066-1068). Composition keydowns return
+//      early, so mid-message the textarea accumulates the entire buffer-so-far.
+//   2. CompositionHelper._handleAnyTextareaChanges computes the keystroke as
+//      `newValue.replace(oldValue, '')` (CompositionHelper.ts:191). When the
+//      keyboard REWRITES text (autocorrect / auto-space / predictive commit —
+//      routine at word boundaries) `oldValue` is no longer a substring, the
+//      replace matches nothing, and the ENTIRE accumulated buffer is emitted
+//      as one data event.
+//   3. CompositionHelper._finalizeComposition emits
+//      `textarea.value.substring(start[, end])` spans with offsets captured at
+//      composition boundaries (CompositionHelper.ts:134,163,168) — stale
+//      offsets re-emit accumulated tails per word commit.
+//
+// Net effect observed in #12: a ~110-char message became a 3,042-char PTY
+// stream of cumulative prefixes ("i think" / "i think there" / "i think there
+// is" …). Each individual chunk was small (~5-110 chars) — so a single-chunk
+// size cap can NOT catch the primary shape. Detection keys on the structure:
+// consecutive multi-char chunks where each strictly extends the previous one
+// as a prefix. Legit input never looks like that: typed keys arrive as 1-char
+// deltas, IME commits arrive as sibling words (not superstrings), pastes
+// arrive as one chunk (and are exempted via the DOM `paste` event and/or
+// bracketed-paste markers), and terminal protocol replies are ESC-prefixed.
+//
+// xterm itself is loaded from CDN, version-pinned (index.html) and not
+// patchable in a zero-build client — but every byte of human browser input
+// reaches the PTY through exactly one chokepoint TermDeck owns: the
+// `terminal.onData` handler in app.js. This module is that chokepoint's
+// brain. See tests/input-guard contract: packages/server/tests/input-guard.test.js.
+
+(function (root, factory) {
+  if (typeof module === 'object' && module.exports) {
+    module.exports = factory();
+  } else {
+    root.InputGuard = factory();
+  }
+})(typeof self !== 'undefined' ? self : this, function () {
+
+  const DEFAULTS = {
+    // A single non-paste, non-protocol chunk this large is not human typing.
+    // Largest legit non-paste chunks are IME phrase commits (CJK conversion,
+    // dictation segments) — realistically well under this. Suppressed chunks
+    // are held for an explicit "send anyway" so a false positive costs one
+    // click, while a true positive saves the session.
+    oversizeChunkChars: 512,
+
+    // Chunks shorter than this never participate in chain detection: 1-2
+    // chars is normal typing, 3 covers short escape sequences. Chain
+    // candidates start at 4 chars.
+    chainMinChunkChars: 4,
+
+    // Consecutive strictly-growing prefix-chained chunks before tripping.
+    // 3 means: chunk B extending chunk A passes (a single predictive-commit
+    // rewrite can legitimately look like that once), but a third consecutive
+    // extension is the #12 runaway. Brad's payload chains 20+ deep.
+    prefixChainTripCount: 3,
+
+    // Consecutive IDENTICAL multi-char chunks before tripping. Belt-and-
+    // suspenders for the stacked-handler / stuck-repeat shape. High threshold
+    // because short identical runs are legit ("ha ha ha ha" via IME commits).
+    repeatChainTripCount: 8,
+
+    // Chain links must arrive within this window of each other. Runaway
+    // emissions arrive at typing cadence; a long pause breaks the chain.
+    chainWindowMs: 5000,
+
+    // Grace period after a DOM `paste` event during which any chunk passes.
+    // Pastes are deliberate; they also reset chain state.
+    pasteGraceMs: 1500,
+  };
+
+  function createGuard(opts) {
+    return {
+      cfg: Object.assign({}, DEFAULTS, opts || {}),
+      lastPasteAt: 0,
+      prevChunk: '',
+      prevChunkAt: 0,
+      prefixChainLen: 0,
+      repeatChainLen: 0,
+      suppressedCount: 0,
+      suppressedChars: 0,
+    };
+  }
+
+  // Record a DOM `paste` event on the panel's textarea (timestamp from the
+  // caller so the module stays clock-free and testable).
+  function notePaste(guard, now) {
+    guard.lastPasteAt = now;
+  }
+
+  function resetChains(guard) {
+    guard.prevChunk = '';
+    guard.prevChunkAt = 0;
+    guard.prefixChainLen = 0;
+    guard.repeatChainLen = 0;
+  }
+
+  // Classify one onData chunk. Returns { verdict: 'pass' } or
+  // { verdict: 'suppress', reason: 'prefix-chain'|'repeat-chain'|'oversize',
+  //   chainLength, suppressedCount, suppressedChars }.
+  function check(guard, data, now) {
+    const cfg = guard.cfg;
+
+    // Bracketed paste (xterm wraps pastes in \x1b[200~ … \x1b[201~ when the
+    // app enabled DECSET 2004): deliberate bulk input — pass and reset
+    // chains. Checked before the generic ESC pass-through so the reset fires.
+    if (data.startsWith('\x1b[200~')) {
+      resetChains(guard);
+      return { verdict: 'pass' };
+    }
+
+    // Terminal protocol traffic (cursor/function keys, mouse tracking
+    // reports, DA/DSR query replies) is ESC-prefixed and must NEVER be
+    // suppressed or held — dropping a query reply can hang a TUI. The #12
+    // runaway is plain text reconstructed from the textarea, which cannot
+    // contain ESC. Protocol chunks don't touch chain state either (mouse
+    // wheel bursts emit many near-identical chunks legitimately).
+    if (data.charCodeAt(0) === 0x1b) {
+      return { verdict: 'pass' };
+    }
+
+    // DOM-paste grace: a `paste` event just fired on this panel's textarea
+    // (un-bracketed paste path). Deliberate bulk input — pass and reset
+    // chains. lastPasteAt === 0 means "never pasted", not "pasted at epoch".
+    if (guard.lastPasteAt > 0 && (now - guard.lastPasteAt) <= cfg.pasteGraceMs) {
+      resetChains(guard);
+      return { verdict: 'pass' };
+    }
+
+    // Small chunks are normal typing / control chars: always pass, and leave
+    // chain state alone (runaway prefix emissions can interleave with real
+    // keystroke deltas; a 1-char delta must not amnesty the chain).
+    if (data.length < cfg.chainMinChunkChars) {
+      return { verdict: 'pass' };
+    }
+
+    // Multi-char plain-text chunk: update chain state.
+    const withinWindow = guard.prevChunk && (now - guard.prevChunkAt) <= cfg.chainWindowMs;
+    if (withinWindow && data.length > guard.prevChunk.length && data.startsWith(guard.prevChunk)) {
+      guard.prefixChainLen += 1;
+      guard.repeatChainLen = 1;
+    } else if (withinWindow && data === guard.prevChunk) {
+      guard.repeatChainLen += 1;
+      // An identical re-emission keeps a prefix chain alive but doesn't grow it.
+    } else {
+      guard.prefixChainLen = 1;
+      guard.repeatChainLen = 1;
+    }
+    guard.prevChunk = data;
+    guard.prevChunkAt = now;
+
+    let reason = null;
+    if (guard.prefixChainLen >= cfg.prefixChainTripCount) {
+      reason = 'prefix-chain';
+    } else if (guard.repeatChainLen >= cfg.repeatChainTripCount) {
+      reason = 'repeat-chain';
+    } else if (data.length >= cfg.oversizeChunkChars) {
+      reason = 'oversize';
+    }
+
+    if (reason) {
+      guard.suppressedCount += 1;
+      guard.suppressedChars += data.length;
+      return {
+        verdict: 'suppress',
+        reason,
+        chainLength: reason === 'repeat-chain' ? guard.repeatChainLen : guard.prefixChainLen,
+        suppressedCount: guard.suppressedCount,
+        suppressedChars: guard.suppressedChars,
+      };
+    }
+
+    return { verdict: 'pass' };
+  }
+
+  return { DEFAULTS, createGuard, notePaste, check };
+});

package/packages/client/public/style.css

@@ -1956,6 +1956,69 @@
       to { opacity: 1; transform: translateY(0); }
     }
 
+    /* ===== Input-guard toast (Sprint 73 T3, termdeck#12) =====
+       Same chrome as .proactive-toast but red-accented (it reports suppressed
+       input, not a memory hit) and not cursor-pointer (clicking it does
+       nothing; actions are the explicit buttons). */
+    .input-guard-toast {
+      position: absolute;
+      right: 10px;
+      bottom: 44px;
+      max-width: 320px;
+      padding: 8px 10px 8px 12px;
+      background: rgba(23, 15, 15, 0.95);
+      border: 1px solid var(--tg-accent-dim);
+      border-left: 3px solid #f7768e;
+      border-radius: var(--tg-radius-sm);
+      box-shadow: 0 6px 18px rgba(0,0,0,0.35);
+      color: var(--tg-text);
+      font-size: 11px;
+      z-index: 26;
+      animation: toast-in 0.18s ease;
+    }
+    .input-guard-toast .t-title {
+      font-size: 10px;
+      text-transform: uppercase;
+      letter-spacing: 0.4px;
+      color: #f7768e;
+      margin-bottom: 3px;
+    }
+    .input-guard-toast .t-body {
+      font-size: 11px;
+      line-height: 1.35;
+      color: var(--tg-text);
+    }
+    .input-guard-toast .t-meta {
+      margin-top: 4px;
+      font-size: 9px;
+      color: var(--tg-text-dim);
+    }
+    .input-guard-toast .t-dismiss {
+      position: absolute;
+      top: 2px;
+      right: 4px;
+      background: none;
+      border: none;
+      color: var(--tg-text-dim);
+      cursor: pointer;
+      font-size: 12px;
+      padding: 0 4px;
+    }
+    .input-guard-toast .t-dismiss:hover { color: var(--tg-text); }
+    .input-guard-toast .t-send-anyway {
+      margin-top: 6px;
+      padding: 2px 8px;
+      background: none;
+      border: 1px solid #f7768e;
+      border-radius: var(--tg-radius-sm);
+      color: #f7768e;
+      font-size: 10px;
+      cursor: pointer;
+    }
+    .input-guard-toast .t-send-anyway:hover {
+      background: rgba(247, 118, 142, 0.15);
+    }
+
     /* ===== Flashback modal (Sprint 16 T2) ===== */
     .flashback-modal {
       display: none;

package/packages/server/src/agent-adapters/web-chat-grok.js

@@ -13,8 +13,8 @@
 // Grok's reasoning model, which the CLI rejects (`reasoningEffort` → HTTP 400;
 // see grok-models.js). Same provider, different runtime + different cost
 // realization, so it is a separate `sessionType:'web-chat'`. Provenance is
-// tagged `sourceAgent:'grok'` this sprint (ORCH zero-touch decision — see the
-// "source_agent attribution" section); a distinct 'grok-web' tag is deferred.
+// tagged `sourceAgent:'grok-web'` (Sprint 73 T1 — see the "source_agent
+// attribution" section), distinguishing web rows from Grok-CLI rows in Mnestra.
 //
 // ── The one hard constraint: NO node-pty, NO on-disk transcript ──────────────
 // There is no PTY stream and no conversation file on disk. The server seam
@@ -39,22 +39,22 @@
 // error) — index.js does not route web-chat text through `_detectErrors`.
 //
 // ── source_agent attribution ─────────────────────────────────────────────────
-// `sourceAgent:'grok'` (ORCH decision 2026-06-08, Blocker 3): we reuse the
-// already-allow-listed 'grok' tag so this sprint touches ZERO release-sensitive
-// surface — the bundled hooks in packages/stack-installer/assets/hooks/* (Brad
-// runs the installed copy) stay pristine. The provenance is still accurate
-// (it IS Grok producing the content); it just doesn't yet distinguish web from
-// CLI. A distinct 'grok-web' tag — which WOULD require adding 'grok-web' to the
-// hook's ALLOWED_SOURCE_AGENTS (else normalizeSourceAgent coerces the row to
-// 'claude') + a hook-version-stamp bump + an install refresh — is deferred to a
-// follow-up. onPanelClose emits `adapter.sourceAgent || adapter.name`.
+// `sourceAgent:'grok-web'` (Sprint 73 T1 — flips the Sprint 72 ORCH zero-touch
+// decision that shipped 'grok' to keep that sprint off the release-sensitive
+// hook surface). Web and CLI Grok rows are now distinguishable in Mnestra:
+// onPanelClose/periodic emit `adapter.sourceAgent || adapter.name`, the bundled
+// hook allow-lists 'grok-web' (stamp v4, plus a `web-chat-grok` registry-name
+// alias as the agy→antigravity-style safety net), and mnestra's source_agents
+// enum + recall filter gain 'grok-web' via migration 024 (Sprint 74 T1 —
+// ATOMIC release partner; neither side ships without the other, else rows are
+// unfilterable or, on a stale installed hook, coerced to 'claude').
 //
-// Byte-floor note (also deferred with grok-web): the bundled hook skips
-// transcripts < 5 KB unless sessionType is specifically exempted (only
-// 'antigravity' is today). Our materialized envelope is compact, so a SHORT
-// (<5 KB) web-chat session is currently dropped — substantive auditor/worker
-// sessions (the real use case) run well past 5 KB and capture normally. The
-// exemption is a hook edit, so it rides the same deferred follow-up.
+// Byte-floor (shipped with the flip, hook v4): the bundled hook skips
+// transcripts < 5 KB unless the sessionType is exempted. Our materialized
+// envelope is compact — synthesized turn content, no JSONL metadata bloat;
+// 48/49 live Sprint-72 envelopes were <5 KB — so 'web-chat' is exempted
+// alongside 'antigravity', gated on parsed content (≥1 assistant turn)
+// instead of raw bytes.
 //
 // Contract — see ./claude.js header for the full annotated adapter shape.
 
@@ -211,11 +211,11 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
 const webChatGrokAdapter = {
   name: 'web-chat-grok',
   sessionType: 'web-chat',
-  // ORCH decision 2026-06-08 (Blocker 3): reuse the already-allow-listed 'grok'
-  // tag so this sprint touches zero release-sensitive hook surface. A distinct
-  // 'grok-web' tag is deferred (needs a hook allowlist edit + version bump).
-  // See the "source_agent attribution" header for the full rationale.
-  sourceAgent: 'grok',
+  // Sprint 73 T1 — distinct web provenance (was 'grok', the Sprint 72 ORCH
+  // zero-touch decision). Pairs ATOMICALLY with hook v4 (ALLOWED_SOURCE_AGENTS
+  // + byte-floor exemption) and mnestra migration 024 (Sprint 74 T1). See the
+  // "source_agent attribution" header for the full rationale.
+  sourceAgent: 'grok-web',
   // Sprint 50 T3 — human-readable label for launcher buttons + panel headers.
   displayName: 'Grok (Web)',
   // Provider URL the CDP driver navigates the dedicated-profile tab to on

package/packages/server/src/index.js

@@ -3467,8 +3467,13 @@ function validateSupabase(url, key) {
 
 function validateOpenAI(key) {
   return new Promise((resolve) => {
+    // Probe with the EXACT request shape the bundled hooks use in production
+    // (session-end v5: 3-large @ dimensions:1536, recall-parity with mnestra)
+    // so a passing preflight means the real capture pipeline's call works —
+    // not some other model the account may gate differently.
     const payload = JSON.stringify({
-      model: 'text-embedding-3-small',
+      model: 'text-embedding-3-large',
+      dimensions: 1536,
       input: 'termdeck setup test'
     });
     const req = https.request({

package/packages/stack-installer/assets/hooks/README.md

@@ -2,13 +2,14 @@
 
 The `@jhizzard/termdeck-stack` installer can drop `memory-session-end.js`
 into `~/.claude/hooks/` and wire it into `~/.claude/settings.json` under
-`hooks.Stop`. The installer prompts you before doing this; default is
-yes.
+`hooks.SessionEnd`. The installer prompts you before doing this; default
+is yes. (Early versions wired `hooks.Stop`, which fires every assistant
+turn — the wizard migrates that to `SessionEnd` automatically.)
 
 ## What the hook does
 
-On every Claude Code session close, Claude Code fires its `Stop` hook
-with a JSON payload on stdin:
+On every Claude Code session close, Claude Code fires its `SessionEnd`
+hook with a JSON payload on stdin:
 
 ```json
 { "transcript_path": "/path/to/session.jsonl", "cwd": "/path/where/you/were/working", "session_id": "..." }
@@ -17,20 +18,28 @@ with a JSON payload on stdin:
 The hook:
 
 1. Skips transcripts smaller than 5 KB (no signal in tiny sessions —
-   override via `TERMDECK_HOOK_MIN_BYTES`).
+   override via `TERMDECK_HOOK_MIN_BYTES`). Compact-envelope session
+   types (`antigravity`, `web-chat`) are exempt from the byte floor and
+   gate on parsed content instead (≥ 1 assistant turn).
 2. Validates env vars (`SUPABASE_URL`, `SUPABASE_SERVICE_ROLE_KEY`,
    `OPENAI_API_KEY`); if any are missing, logs the missing list and
    exits cleanly without blocking the session close.
 3. Detects the project from `cwd` against a built-in regex table; falls
-   back to `"global"` when nothing matches. **The default table is
-   intentionally empty** — see "Customizing the project map" below to
-   add your own entries.
+   back to `"global"` when nothing matches. The hook ships with a
+   default most-specific-first table — see "Customizing the project
+   map" below to extend it with your own entries.
 4. Builds a coarse session summary from the last ~30 messages of the
    transcript (~7 KB cap to stay inside OpenAI's embedding-input
    budget).
-5. Embeds the summary via OpenAI `text-embedding-3-small` (1,536-dim).
+5. Embeds the summary via OpenAI `text-embedding-3-large` at
+   `dimensions: 1536` — deliberately identical to Mnestra's recall-query
+   embedder, so rows and queries share one vector space (rows embedded
+   with any other model rank as semantic noise in hybrid search).
 6. POSTs **one row** to Supabase `/rest/v1/memory_items` with
-   `source_type='session_summary'`.
+   `source_type='session_summary'` (stamped
+   `metadata.embedding_model='text-embedding-3-large@1536'`), plus a
+   companion upsert to `/rest/v1/memory_sessions` keyed on
+   `session_id`.
 7. Logs every step to `~/.claude/hooks/memory-hook.log`.
 
 The hook is **fail-soft**: any error (network, parse, env-var-missing,
@@ -70,9 +79,9 @@ If any of the three is missing the log line will name them:
 
 ## Customizing the project map
 
-The hook ships with an **empty `PROJECT_MAP`** by default — every
-session lands under `project: 'global'` until you add entries. To add
-your own:
+The hook ships with a default `PROJECT_MAP` (most-specific-first); a
+session lands under `project: 'global'` only when no entry matches its
+`cwd`. To add your own entries:
 
 1. Open `~/.claude/hooks/memory-session-end.js` after the installer
    has dropped it.
@@ -146,8 +155,8 @@ before overwriting; choose accordingly.
 Two options:
 
 1. Edit `~/.claude/settings.json` and remove the entry under
-   `hooks.Stop` that references `memory-session-end.js`. Leave the
-   file in place; it simply won't fire.
+   `hooks.SessionEnd` that references `memory-session-end.js`. Leave
+   the file in place; it simply won't fire.
 2. Or delete `~/.claude/hooks/memory-session-end.js` AND remove the
    `settings.json` entry. (Removing only the file leaves a broken
    `command` in settings — Claude Code will log a missing-file error
@@ -162,6 +171,7 @@ re-prompt to install. Decline at the prompt to stay opted out.
 |---|---|
 | `TERMDECK_HOOK_DEBUG=1` | Verbose `[debug]` lines in the log |
 | `TERMDECK_HOOK_MIN_BYTES=10000` | Override the 5 KB skip threshold |
+| `TERMDECK_HOOK_MIN_MESSAGES=5` | Override the parsed-message floor (default 1) |
 
 ## Log file