@jhizzard/termdeck 1.8.0 → 1.9.0

package/packages/server/src/index.js

@@ -1590,6 +1590,57 @@ function createServer(config) {
   // sync), wire screencast→WS, completion→capture, disconnect→close. Fail-soft
   // at every step — a missing/partial/throwing driver degrades the panel to
   // 'errored', never crashes the server.
+  // Render-watchdog: self-heal a wedged web-chat cold-start. On a brand-new
+  // browser profile the first load very occasionally paints nothing (empty
+  // body.innerText) even though attach + screencast are healthy; a full
+  // re-navigation clears it (a reload does NOT). Polls briefly for paint, then
+  // re-navigates up to `attempts` times. Returns true if the page painted (or
+  // we cannot measure — never block readiness on the watchdog itself), false if
+  // it stayed blank. Provider-neutral: "painted" == the body has any visible
+  // text, which empirically separates the white cold-start wedge (innerText
+  // length 0) from a rendered SPA (>0). (Sprint-72 hardening — 2026-06-09.)
+  async function ensureWebChatRendered(session, handle, startUrl, opts = {}) {
+    const settleMs = opts.settleMs || Number(process.env.TERMDECK_WEBCHAT_RENDER_SETTLE_MS) || 8000;
+    const attempts = opts.attempts != null ? opts.attempts
+      : (Number(process.env.TERMDECK_WEBCHAT_RENDER_ATTEMPTS) || 2);
+    const stepMs = opts.stepMs || Number(process.env.TERMDECK_WEBCHAT_RENDER_STEP_MS) || 500;
+    if (!handle || !handle.page || typeof handle.page.evaluate !== 'function') return true;
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+    const painted = async () => {
+      try {
+        return await handle.page.evaluate(
+          () => !!(document && document.body && (document.body.innerText || '').trim().length > 0),
+        );
+      } catch (_e) {
+        return false;
+      }
+    };
+    const settle = async () => {
+      for (let waited = 0; waited < settleMs; waited += stepMs) {
+        if (session._webChatClosed) return true;
+        if (await painted()) return true;
+        await sleep(stepMs);
+      }
+      return painted();
+    };
+    if (await settle()) return true;
+    for (let tries = 1; tries <= attempts; tries++) {
+      if (session._webChatClosed) return true;
+      applyWebChatStatus(session, { status: 'starting', statusDetail: `Recovering blank page (try ${tries}/${attempts})…` });
+      try {
+        if (typeof handle.navigate === 'function') {
+          await handle.navigate(startUrl, { waitUntil: 'domcontentloaded' });
+        } else {
+          await handle.page.goto(startUrl, { waitUntil: 'domcontentloaded', timeout: 30000 });
+        }
+      } catch (_e) {
+        /* navigation hiccup — re-check paint anyway */
+      }
+      if (await settle()) return true;
+    }
+    return false;
+  }
+
   function setupWebChatSession(session) {
     session.pty = null;
     session.pid = null;
@@ -1647,8 +1698,18 @@ function createServer(config) {
             catch (_e) { /* never disrupt */ }
           }
         };
-        if (handle && typeof handle.screencast === 'function') handle.screencast(onFrame);
-        else if (driver.cdp && typeof driver.cdp.screencast === 'function') driver.cdp.screencast(handle, onFrame);
+        // Render quality (Sprint-72 hardening, 2026-06-09): pass crisp, Retina-friendly
+        // screencast opts. The driver's bare default was a blurry 1280x800 @ jpeg-q60 — fine
+        // on a 1x display, soft on a 2x Mac (the HiDPI canvas then upscales it). Env-tunable
+        // down for slow links: TERMDECK_WEBCHAT_QUALITY / _MAXW / _MAXH / _FORMAT.
+        const scOpts = {
+          format: process.env.TERMDECK_WEBCHAT_FORMAT || 'jpeg',
+          quality: Number(process.env.TERMDECK_WEBCHAT_QUALITY) || 85,
+          maxWidth: Number(process.env.TERMDECK_WEBCHAT_MAXW) || 2560,
+          maxHeight: Number(process.env.TERMDECK_WEBCHAT_MAXH) || 1600,
+        };
+        if (handle && typeof handle.screencast === 'function') handle.screencast(onFrame, scOpts);
+        else if (driver.cdp && typeof driver.cdp.screencast === 'function') driver.cdp.screencast(handle, onFrame, scOpts);
       } catch (err) {
         console.error('[web-chat] screencast wiring failed:', err && err.message ? err.message : err);
       }
@@ -1673,7 +1734,17 @@ function createServer(config) {
         }
       } catch (_e) { /* optional hook — absence is fine */ }
 
-      applyWebChatStatus(session, { status: 'idle', statusDetail: 'Ready' });
+      // Self-heal a flaky blank cold-start before declaring the panel Ready.
+      let rendered = true;
+      try {
+        rendered = await ensureWebChatRendered(session, handle, startUrl);
+      } catch (err) {
+        console.error('[web-chat] render-watchdog error:', err && err.message ? err.message : err);
+      }
+      if (session._webChatClosed) return;
+      applyWebChatStatus(session, rendered
+        ? { status: 'idle', statusDetail: 'Ready' }
+        : { status: 'errored', statusDetail: 'page did not render (blank after retries)' });
     })();
   }
 
@@ -3396,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({
@@ -3589,6 +3665,24 @@ if (require.main === module) {
   process.on('SIGINT', () => handleShutdown('SIGINT'));
   process.on('SIGTERM', () => handleShutdown('SIGTERM'));
 
+  // Fail-soft crash guards (Sprint-72 hardening, 2026-06-09). One bad async
+  // rejection or uncaught error anywhere — a panel handler, a request, a hook —
+  // must NOT crash the whole server and take every live terminal panel (and the
+  // user's work) down with it. We LOG prominently (per-event ISO timestamp, like
+  // the boot banner, so crash boundaries stay greppable) and keep running. This
+  // trades the small risk of continuing in a degraded state for the much larger
+  // cost of losing every panel; a process supervisor is the backstop if the
+  // process ever truly wedges. Shutdown is exempt — let handleShutdown finish.
+  process.on('unhandledRejection', (reason) => {
+    if (shutdownInProgress) return;
+    const msg = (reason && reason.stack) || (reason && reason.message) || String(reason);
+    console.error(`[server] unhandledRejection (kept alive · ${new Date().toISOString()}):\n${msg}`);
+  });
+  process.on('uncaughtException', (err) => {
+    if (shutdownInProgress) return;
+    console.error(`[server] uncaughtException (kept alive · ${new Date().toISOString()}):\n${(err && err.stack) || err}`);
+  });
+
   server.listen(port, host, () => {
     // Sprint 60 v1.0.14 (Item 5) — per-boot banner with ISO timestamp + PID.
     // Brad's 2026-05-07 forensic: a single 260KB termdeck.log spanned Apr 25

package/packages/server/src/sprints/status-parser.js

@@ -21,9 +21,19 @@ function parseStatusMd(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
   const lines = content.split('\n');
 
-  // Regex per BRIEF (loosened for multiple suffixes):
-  // ^### \[(T\d+(?:-[A-Z0-9-]+)?|ORCH)\] (FINDING|PROPOSE|LANDED|DONE|AUDIT-RED|AUDIT-CONCERN|CHECKPOINT|FINAL-VERDICT|STATUS|RULING) (\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}) ET — (.*?)$
-  const POST_RE = /^### \[(T\d+(?:-[A-Z0-9-]+)?|ORCH)\] (FINDING|PROPOSE|LANDED|DONE|AUDIT-RED|AUDIT-CONCERN|CHECKPOINT|FINAL-VERDICT|STATUS|RULING) (\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}) ET — (.*?)$/;
+  // Canonical post header (global CLAUDE.md § lane post-shape uniformity):
+  //   ### [T<n>] VERB[ (qualifier)] YYYY-MM-DD HH:MM ET — <gist>
+  // The verb is HARD-ANCHORED to the header position (immediately after the
+  // lane tag), so a verb word appearing in a gist/prose — e.g. "DONE" inside a
+  // CHECKPOINT line's gist — is never mis-counted as that verb; it survives
+  // only as gist (capture group 5). Verb vocabulary tracks the REAL lane
+  // vocabulary, incl. FIX-PROPOSED / FIX-LANDED / AUDIT-PASS / AUDIT-FAIL, plus
+  // an optional parenthetical qualifier after the verb (e.g. the real shape
+  // `AUDIT-PASS (cdp/render)`). Order longer compounds before their shorter
+  // prefixes is unnecessary here (all alternatives are anchored + whitespace-
+  // delimited), but FIX-*/AUDIT-* are listed before bare PROPOSE/LANDED for
+  // readability.
+  const POST_RE = /^### \[(T\d+(?:-[A-Z0-9-]+)?|ORCH)\] (FINDING|FIX-PROPOSED|PROPOSE|FIX-LANDED|LANDED|DONE|AUDIT-RED|AUDIT-CONCERN|AUDIT-PASS|AUDIT-FAIL|CHECKPOINT|FINAL-VERDICT|STATUS|RULING)(?:\s+\([^)]*\))? (\d{4}-\d{2}-\d{2}) (\d{2}:\d{2}) ET — (.*?)$/;
 
   const laneLandeds = {}; // laneTag -> latest LANDED timestamp
   const openReds = []; // List of {tag, timestamp, gist}
@@ -57,7 +67,7 @@ function parseStatusMd(filePath) {
       gist
     };
 
-    if (verb === 'LANDED') {
+    if (verb === 'LANDED' || verb === 'FIX-LANDED') {
       laneLandeds[tag] = timestamp;
     }
 

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
 

package/packages/stack-installer/assets/hooks/memory-pre-compact.js

@@ -1,6 +1,13 @@
 /**
  * TermDeck pre-compact memory hook (Mnestra-direct, no rag-system dependency).
  *
+ * @termdeck/stack-installer-hook v2
+ *
+ * ^ Stamp lives at the TOP of the docblock — both readers scan only the first
+ *   4096 bytes (Sprint 73 T1 hit this on the session-end hook when its
+ *   changelog grew past 4 KB and the stamp fell out of the window, silently
+ *   disabling every refresh path). Keep it above the fold.
+ *
  * Vendored into ~/.claude/hooks/memory-pre-compact.js by @jhizzard/termdeck-stack.
  * Wired into ~/.claude/settings.json under hooks.PreCompact — fires BEFORE
  * Claude Code compacts conversation context, capturing the in-flight session
@@ -32,7 +39,9 @@
  *   - Load ~/.termdeck/secrets.env on env-var gaps (Sprint 47.5 discipline).
  *   - Parse transcript via the adapter parser exported by
  *     memory-session-end.js (Sprint 38 module-export contract; no duplication).
- *   - Embed via OpenAI text-embedding-3-small.
+ *   - Embed via the session-end hook's embedText (text-embedding-3-large at
+ *     dimensions:1536 since v5 there — recall-parity with mnestra's query
+ *     embedder; this hook has NO embed call of its own).
  *   - POST ONE row to /rest/v1/memory_items with
  *     source_type='pre_compact_snapshot', category='workflow'.
  *
@@ -43,18 +52,27 @@
  * fail-soft.
  *
  * Version stamp (Sprint 64 T3.2 — initial cut):
- *   The marker `@termdeck/stack-installer-hook v<N>` below is read by both
- *   stack-installer's installPreCompactHook (version-aware overwrite under
- *   --yes) and `termdeck init --mnestra` (refreshBundledPreCompactHookIfNewer
- *   step). Bump the integer whenever a change here should overwrite an
+ *   The marker `@termdeck/stack-installer-hook v<N>` at the TOP of this
+ *   docblock is read by both stack-installer's installPreCompactHook
+ *   (version-aware overwrite under --yes) and `termdeck init --mnestra`
+ *   (refreshBundledPreCompactHookIfNewer step) — both scan only the first
+ *   4096 bytes. Bump the integer whenever a change here should overwrite an
  *   already-installed copy. Comment-only tweaks do not need a bump.
  *
- * @termdeck/stack-installer-hook v1
+ *   v2 (Sprint 73 T1, ORCH handoff — embedding recall-parity marker):
+ *     - Snapshot rows now stamp metadata.embedding_model with the marker
+ *       exported by the session-end hook (v5: 'text-embedding-3-large@1536')
+ *       — Sprint 74 T3's re-embed backfill keys idempotency on it. The marker
+ *       is stamped ONLY when the loaded helpers export it: an older installed
+ *       session-end (still embedding 3-small) exports none, the row stays
+ *       unmarked, and the backfill correctly re-embeds it — a false marker on
+ *       a mis-embedded row would permanently hide it from repair.
  *
  * Required env vars (validated at entry, after the secrets.env fallback):
  *   - SUPABASE_URL              e.g. https://<project-ref>.supabase.co
  *   - SUPABASE_SERVICE_ROLE_KEY      service-role key (needs INSERT on memory_items)
- *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
+ *   - OPENAI_API_KEY            sk-... for the embed model (see embedText in
+ *                               the session-end hook — 3-large@1536 since v5)
  *
  * Optional:
  *   - TERMDECK_HOOK_DEBUG=1               verbose logging
@@ -126,6 +144,7 @@ async function postPreCompactSnapshot({
   content, embedding,
   project, sessionId,
   sourceAgent,
+  embeddingModelMarker,
 }) {
   try {
     const res = await fetch(`${supabaseUrl}/rest/v1/memory_items`, {
@@ -144,6 +163,12 @@ async function postPreCompactSnapshot({
         project,
         source_session_id: sessionId || null,
         source_agent: sourceAgent,
+        // v2 — backfill-idempotency marker, present ONLY when the loaded
+        // helpers export one (i.e. the embed actually ran on that model).
+        // See the v2 header note for the stale-helpers rationale.
+        ...(embeddingModelMarker
+          ? { metadata: { embedding_model: embeddingModelMarker } }
+          : {}),
       }),
     });
     if (!res.ok) {
@@ -240,6 +265,9 @@ async function processPreCompactPayload(input, helpers) {
     supabaseUrl: env.supabaseUrl,
     supabaseKey: env.supabaseKey,
     content, embedding, project, sessionId, sourceAgent,
+    // Marker travels with the embedder: undefined on a pre-v5 session-end
+    // hook (3-small embeds → row stays unmarked → backfill repairs it).
+    embeddingModelMarker: helpers.EMBEDDING_MODEL_MARKER || null,
   });
 
   if (ok) {

package/packages/stack-installer/assets/hooks/memory-session-end.js

@@ -1,6 +1,16 @@
 /**
  * TermDeck session-end memory hook (Mnestra-direct, no rag-system dependency).
  *
+ * @termdeck/stack-installer-hook v5
+ *
+ * ^ The stamp lives HERE, at the top of the docblock — NOT below the changelog
+ *   notes. Both readers (stack-installer's installSessionEndHook and
+ *   init-mnestra's refreshBundledHookIfNewer) scan only the first 4096 bytes
+ *   of the file for the marker; Sprint 73 T1's v4 note grew the header past
+ *   4 KB and a stamp positioned below the notes fell out of the scan window,
+ *   making the bundled hook read as "unsigned" and silently disabling every
+ *   refresh path. Keep the stamp above the fold; let the changelog grow below.
+ *
  * Vendored into ~/.claude/hooks/memory-session-end.js by @jhizzard/termdeck-stack.
  * Wired into ~/.claude/settings.json under hooks.SessionEnd — fires once per
  * Claude Code session close (`/exit`, Ctrl+D, terminal close, or process kill).
@@ -34,7 +44,9 @@
  *      JSONL, Codex JSONL, Gemini single-JSON, or auto-detect when sessionType
  *      is absent. Builds a coarse summary from the resulting message list
  *      (last ~30 message excerpts).
- *   7. Embeds the summary via OpenAI text-embedding-3-small.
+ *   7. Embeds the summary via OpenAI text-embedding-3-large at
+ *      dimensions:1536 — recall-parity: MUST match mnestra's query-side
+ *      embedder (engram src/embeddings.ts) or rows are semantically blind.
  *   8. POSTs ONE row to Supabase /rest/v1/memory_items with source_type='session_summary'.
  *   9. (Sprint 51.6 T3) POSTs ONE row to Supabase /rest/v1/memory_sessions with
  *      Prefer: resolution=merge-duplicates so SessionEnd-fires-twice resolves
@@ -43,9 +55,11 @@
  *  10. Logs every step to ~/.claude/hooks/memory-hook.log.
  *
  * Version stamp (Sprint 51.6 T3 — hook upgrade gap fix):
- *   The marker `@termdeck/stack-installer-hook v<N>` below is read by both
- *   stack-installer's installSessionEndHook (version-aware overwrite under
- *   --yes) and `termdeck init --mnestra` (refreshBundledHookIfNewer step).
+ *   The marker `@termdeck/stack-installer-hook v<N>` at the TOP of this
+ *   docblock is read by both stack-installer's installSessionEndHook
+ *   (version-aware overwrite under --yes) and `termdeck init --mnestra`
+ *   (refreshBundledHookIfNewer step) — both scan only the first 4096 bytes,
+ *   which is why it sits above these notes (see the warning beside it).
  *   Bump the integer whenever a change to this file should overwrite an
  *   already-installed copy on the user's machine — e.g. a new write path,
  *   a new transcript parser, a default PROJECT_MAP change. Comment-only
@@ -61,12 +75,39 @@
  *       to bundled-v2 always passes the `installed >= bundled` short-circuit
  *       at init-mnestra.js:550 and reaches the refresh path.
  *
- * @termdeck/stack-installer-hook v3
+ *   v4 (Sprint 73 T1 — grok-web provenance + web-chat byte-floor exemption):
+ *     - ALLOWED_SOURCE_AGENTS gains the four web-surface tags ('grok-web',
+ *       'claude-web', 'chatgpt-web', 'gemini-web') per the Sprint 74 ORCH
+ *       one-churn addendum; only 'grok-web' has a live producer today (the
+ *       web-chat-grok adapter). New alias 'web-chat-grok' → 'grok-web'
+ *       (registry-name safety net, mirrors 'agy' → 'antigravity').
+ *     - Byte-floor exemption extended from antigravity-only to a sessionType
+ *       set {antigravity, web-chat}: both materialize compact synthesized
+ *       envelopes (<5 KB for short-but-substantive sessions); the gate is
+ *       parsed content (>= 1 assistant turn), not raw bytes.
+ *     - ATOMIC with mnestra migration 024 (Sprint 74 T1): rows tagged
+ *       'grok-web' are unfilterable via MCP source_agents until that ships.
+ *     - Stamp moved to the TOP of the docblock (the readers' 4096-byte head
+ *       scan missed it below these notes — see the warning at the stamp).
+ *
+ *   v5 (Sprint 73 T1, ORCH handoff — embedding recall-parity):
+ *     - embedText flipped text-embedding-3-small → text-embedding-3-large at
+ *       dimensions:1536, matching mnestra's recall query embedder (engram
+ *       src/embeddings.ts) EXACTLY. The two models do not share a vector
+ *       space, so rows embedded 3-small score semantic noise against 3-large
+ *       queries — Sprint 74 T3 quantified 544 production rows half-blind.
+ *       `dimensions:1536` is LOAD-BEARING: 3-large is natively 3072-dim and
+ *       the DB column is vector(1536) — without the param every insert 400s
+ *       and capture is silently lost (hooks are fail-soft).
+ *     - memory_items rows now stamp metadata.embedding_model =
+ *       'text-embedding-3-large@1536' — the marker Sprint 74 T3's re-embed
+ *       backfill keys idempotency on (unmarked rows get re-embedded; marked
+ *       rows are skipped). memory_items.metadata exists from migration 001.
  *
  * Required env vars (validated at entry, after the secrets.env fallback):
  *   - SUPABASE_URL              e.g. https://<project-ref>.supabase.co
  *   - SUPABASE_SERVICE_ROLE_KEY      service-role key (NOT the anon key — needs INSERT on memory_items)
- *   - OPENAI_API_KEY            sk-... for text-embedding-3-small
+ *   - OPENAI_API_KEY            sk-... for text-embedding-3-large (dimensions:1536)
  *
  * Optional:
  *   - TERMDECK_HOOK_DEBUG=1            verbose logging
@@ -148,6 +189,12 @@ const MIN_TRANSCRIPT_BYTES = parseInt(process.env.TERMDECK_HOOK_MIN_BYTES || '50
 // filter; sub-5KB drips still get dropped. Env-configurable for operators who
 // want the legacy permissive-to-zero floor or a higher cutoff than 1.
 const MIN_TRANSCRIPT_MESSAGES = parseInt(process.env.TERMDECK_HOOK_MIN_MESSAGES || '1', 10);
+// Sprint 70 T1 (antigravity) + Sprint 73 T1 (web-chat) — sessionTypes whose
+// transcripts are synthesized COMPACT envelopes (no verbose on-disk JSONL), so
+// the raw-byte floor would wrongly drop short-but-substantive sessions. These
+// skip the MIN_TRANSCRIPT_BYTES gate and are gated on parsed content instead
+// (>= 1 assistant turn) — see the exemption branch in processStdinPayload.
+const BYTE_FLOOR_EXEMPT_SESSION_TYPES = new Set(['antigravity', 'web-chat']);
 const DEBUG = process.env.TERMDECK_HOOK_DEBUG === '1';
 
 function log(msg) {
@@ -602,7 +649,7 @@ function buildSummary(transcriptPath, sessionType) {
   const summary =
     `Session with ${messages.length} messages.\n\n` +
     tail.map((m) => `[${m.role}] ${m.content}`).join('\n');
-  // OpenAI text-embedding-3-small accepts up to 8192 tokens (~32K chars).
+  // OpenAI v3 embedding models accept up to 8192 tokens (~32K chars).
   // 7000 chars is a safe headroom that survives multibyte expansion.
 
   // Sprint 51.7 T2: merge transcript-derived metadata so the caller (
@@ -618,6 +665,23 @@ function buildSummary(transcriptPath, sessionType) {
   };
 }
 
+// Sprint 73 T1 (ORCH handoff, v5) — recall-parity embedding contract.
+// MUST match mnestra's query-side embedder (engram src/embeddings.ts:
+// text-embedding-3-large at dimensions:1536) EXACTLY. OpenAI embedding models
+// do NOT share a vector space — rows embedded with a different model than the
+// query score semantic noise in memory_hybrid_search (Sprint 74 T3 measured
+// 544 production rows half-blind from the 3-small era). `dimensions` is
+// LOAD-BEARING: 3-large natively emits 3072 dims and memory_items.embedding
+// is vector(1536); omitting it turns every insert into a fail-soft 400 (rows
+// silently lost). EMBEDDING_MODEL_MARKER is written to
+// metadata.embedding_model on each row — Sprint 74 T3's re-embed backfill
+// keys its idempotent selection on it (rows without the marker get
+// re-embedded; rows with it are skipped). Bump the marker string in lockstep
+// with any future model/dims change.
+const EMBEDDING_MODEL = 'text-embedding-3-large';
+const EMBEDDING_DIMENSIONS = 1536;
+const EMBEDDING_MODEL_MARKER = `${EMBEDDING_MODEL}@${EMBEDDING_DIMENSIONS}`;
+
 async function embedText(text, openaiKey) {
   try {
     const res = await fetch('https://api.openai.com/v1/embeddings', {
@@ -626,7 +690,11 @@ async function embedText(text, openaiKey) {
         'Content-Type': 'application/json',
         'Authorization': `Bearer ${openaiKey}`,
       },
-      body: JSON.stringify({ model: 'text-embedding-3-small', input: text }),
+      body: JSON.stringify({
+        model: EMBEDDING_MODEL,
+        dimensions: EMBEDDING_DIMENSIONS,
+        input: text,
+      }),
     });
     if (!res.ok) {
       const body = await res.text().catch(() => '');
@@ -653,15 +721,27 @@ async function embedText(text, openaiKey) {
 // binary is `agy` but the canonical provenance tag is `antigravity`, so the
 // alias map below folds `agy` → `antigravity` before the allowlist check —
 // an agy panel's memories must not be mis-tagged `claude`.
+//
+// Sprint 73 T1: the Grok WEB panel (web-chat-grok adapter, sessionType
+// 'web-chat') is distinguishable from the Grok CLI — canonical tag 'grok-web'.
+// Per the Sprint 74 ORCH one-churn addendum, the other three web-surface tags
+// ('claude-web', 'chatgpt-web', 'gemini-web') are forward-declared in the same
+// v4 bump; they have NO termdeck producer yet — inert acceptance-gate entries
+// so the next web-chat adapter doesn't need another stamp/refresh cycle.
+// ATOMIC with mnestra migration 024 (Sprint 74 T1), which adds the same four
+// to the read-side source_agents enum + recall filter.
 const ALLOWED_SOURCE_AGENTS = new Set([
   'claude', 'codex', 'gemini', 'grok', 'orchestrator', 'antigravity',
+  'grok-web', 'claude-web', 'chatgpt-web', 'gemini-web',
 ]);
 
-// Alias → canonical source_agent. Keeps the binary name (`agy`) and any older
-// callers from being dropped to 'claude' by the allowlist gate. Applied (after
-// lowercasing) before the ALLOWED_SOURCE_AGENTS membership test.
+// Alias → canonical source_agent. Keeps the binary name (`agy`), the adapter
+// REGISTRY name (`web-chat-grok` ≠ provenance tag), and any older callers from
+// being dropped to 'claude' by the allowlist gate. Applied (after lowercasing)
+// before the ALLOWED_SOURCE_AGENTS membership test.
 const SOURCE_AGENT_ALIASES = {
   agy: 'antigravity',
+  'web-chat-grok': 'grok-web',
 };
 
 function normalizeSourceAgent(raw) {
@@ -690,6 +770,9 @@ async function postMemoryItem({ supabaseUrl, supabaseKey, content, embedding, pr
         project,
         source_session_id: sessionId || null,
         source_agent: normalizeSourceAgent(sourceAgent),
+        // v5 — backfill-idempotency marker (see EMBEDDING_MODEL_MARKER).
+        // memory_items.metadata exists from migration 001 (jsonb default '{}').
+        metadata: { embedding_model: EMBEDDING_MODEL_MARKER },
       }),
     });
     if (!res.ok) {
@@ -825,24 +908,26 @@ async function processStdinPayload(input) {
   try { stat = statSync(transcriptPath); }
   catch (e) { log(`cannot-stat-transcript: ${transcriptPath} — ${e.message}`); return; }
 
-  // Sprint 70 T1 (A1 RED fix — ORCH 2026-06-07 19:21 ET). The raw-byte floor is
-  // calibrated for verbose on-disk JSONL (claude/codex/gemini/grok session files
-  // run 10s of KB even when short). Antigravity has no on-disk transcript — its
-  // capture is a synthesized COMPACT stdout-tee envelope (cleaned, de-chromed
-  // content only), so a genuinely-substantive short agy session is legitimately
-  // <5KB and the byte floor would wrongly drop it (false zero-row). Exempt
-  // sessionType==='antigravity' from the byte floor and gate on parsed CONTENT
-  // instead — require >= 1 assistant turn so an empty / no-model-output capture
-  // still no-ops. Do NOT lower the global floor; it correctly filters trivial
-  // verbose sessions for every other agent.
-  if (sessionType === 'antigravity') {
-    let agyRaw = '';
-    try { agyRaw = readFileSync(transcriptPath, 'utf8'); }
+  // Sprint 70 T1 (A1 RED fix — ORCH 2026-06-07 19:21 ET) + Sprint 73 T1. The
+  // raw-byte floor is calibrated for verbose on-disk JSONL (claude/codex/
+  // gemini/grok session files run 10s of KB even when short). Antigravity and
+  // web-chat have no on-disk transcript — their captures are synthesized
+  // COMPACT envelopes (agy: cleaned, de-chromed stdout-tee; web-chat: the
+  // in-memory turn buffer — 48/49 live Sprint-72 envelopes measured <5 KB), so
+  // a genuinely-substantive short session is legitimately <5KB and the byte
+  // floor would wrongly drop it (false zero-row). Exempt those sessionTypes
+  // from the byte floor and gate on parsed CONTENT instead — require >= 1
+  // assistant turn so an empty / no-model-output capture still no-ops. Do NOT
+  // lower the global floor; it correctly filters trivial verbose sessions for
+  // every other agent.
+  if (BYTE_FLOOR_EXEMPT_SESSION_TYPES.has(sessionType)) {
+    let exemptRaw = '';
+    try { exemptRaw = readFileSync(transcriptPath, 'utf8'); }
     catch (e) { log(`cannot-read-transcript: ${transcriptPath} — ${e.message}`); return; }
-    const agyTurns = selectTranscriptParser(sessionType).parser(agyRaw);
-    const assistantTurns = agyTurns.filter((m) => m && m.role === 'assistant').length;
+    const exemptTurns = selectTranscriptParser(sessionType).parser(exemptRaw);
+    const assistantTurns = exemptTurns.filter((m) => m && m.role === 'assistant').length;
     if (assistantTurns < 1) {
-      debug(`antigravity-no-assistant-turn: ${agyTurns.length} parsed, 0 assistant — skipping`);
+      debug(`${sessionType}-no-assistant-turn: ${exemptTurns.length} parsed, 0 assistant — skipping`);
       return;
     }
   } else if (stat.size < MIN_TRANSCRIPT_BYTES) {
@@ -943,6 +1028,15 @@ if (require.main === module) {
     // Sprint 50 T2 — source_agent provenance plumbing.
     normalizeSourceAgent,
     ALLOWED_SOURCE_AGENTS,
+    // Sprint 73 T1 — compact-envelope sessionTypes exempt from the byte floor.
+    BYTE_FLOOR_EXEMPT_SESSION_TYPES,
+    // Sprint 73 T1 (v5) — recall-parity embedding contract. The pre-compact
+    // hook reads EMBEDDING_MODEL_MARKER via loadHelpers and stamps it only
+    // when defined, so a stale session-end beside a new pre-compact can never
+    // false-mark rows.
+    EMBEDDING_MODEL,
+    EMBEDDING_DIMENSIONS,
+    EMBEDDING_MODEL_MARKER,
     // Sprint 51.7 T2 — transcript-metadata extractor for memory_sessions.
     parseTranscriptMetadata,
     FACT_TOOL_NAMES,