@jhizzard/termdeck 1.8.1 → 1.10.0

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/health.js

@@ -64,6 +64,21 @@
 
 const http = require('http');
 const https = require('https');
+// Sprint 75 T2 (part C): endpoint-shape classifier — could-not-connect
+// envelopes name the IPv6-only direct endpoint as the likely cause when
+// DATABASE_URL has that shape. Warn-only suffix; never changes categories.
+const { classifyDbEndpoint } = require('./setup/supabase-url');
+
+// Suffix appended to connect-failure details when DATABASE_URL is the
+// IPv6-only direct endpoint (db.<project-ref>.supabase.co — AAAA-only DNS).
+function directEndpointSuffix(databaseUrl) {
+  try {
+    if (classifyDbEndpoint(databaseUrl).kind === 'direct') {
+      return ' (DATABASE_URL is the IPv6-only db.<project-ref> direct endpoint — on IPv4-only hosts pg clients hang until a pool/connect timeout; use the Shared Pooler URL)';
+    }
+  } catch (_e) { /* warn-only */ }
+  return '';
+}
 
 const TTL_SECONDS = 30;
 const TTL_MS = TTL_SECONDS * 1000;
@@ -276,9 +291,10 @@ async function runPgChecks({ databaseUrl, _pgClient }) {
     } else {
       // URL set but connect failed → classify by code (timeout vs unreachable).
       const cat = classifyDbFailure(connectEnvelope || {});
-      const why = connectEnvelope && connectEnvelope.error
+      const why = (connectEnvelope && connectEnvelope.error
         ? `could not connect to Postgres using DATABASE_URL — ${connectEnvelope.error}`
-        : 'could not connect to Postgres using DATABASE_URL';
+        : 'could not connect to Postgres using DATABASE_URL')
+        + directEndpointSuffix(databaseUrl);
       pushPgUnavailableChecks(checks, 'mnestra-pg', cat, why, 'pg unavailable — connect failed');
     }
     return checks;
@@ -479,7 +495,9 @@ async function checkRumenPool(config, options) {
     return warnCheck('rumen-pool', CATEGORIES.DEPENDENCY_DOWN, 'SELECT 1 returned unexpected result');
   } catch (err) {
     const cat = classifyDbFailure(err);
-    return warnCheck('rumen-pool', cat, err && err.message ? err.message : String(err));
+    const detail = (err && err.message ? err.message : String(err))
+      + directEndpointSuffix(dbUrl);
+    return warnCheck('rumen-pool', cat, detail);
   } finally {
     try { await pool.end(); } catch (_e) { /* ignore */ }
   }

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/server/src/preflight.js

@@ -10,6 +10,9 @@ const http = require('http');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+// Sprint 75 T2 (part C): endpoint-shape classifier — used to explain
+// connect failures against the IPv6-only direct endpoint. Warn-only.
+const { classifyDbEndpoint } = require('./setup/supabase-url');
 
 // Cache preflight results for 60s
 let _cachedResult = null;
@@ -352,10 +355,16 @@ async function runPreflight(config) {
       name: 'rumen_recent', passed: false,
       detail: `check failed — ${err.message}`,
     })),
-    checkDatabase().catch((err) => ({
-      name: 'database_url', passed: false,
-      detail: `connection failed — ${err.message}`,
-    })),
+    checkDatabase().catch((err) => {
+      // Sprint 75 T2 (part C): a connect failure against the IPv6-only
+      // direct endpoint (db.<project-ref>.supabase.co) on an IPv4-only
+      // host presents as a timeout — name the likely cause in the detail.
+      let detail = `connection failed — ${err.message}`;
+      if (classifyDbEndpoint(process.env.DATABASE_URL).kind === 'direct') {
+        detail += ' (DATABASE_URL is the IPv6-only db.<project-ref> direct endpoint — on IPv4-only hosts pg clients hang until a pool/connect timeout; use the Shared Pooler URL)';
+      }
+      return { name: 'database_url', passed: false, detail };
+    }),
     checkProjectPaths(config).catch((err) => ({
       name: 'project_paths', passed: false,
       detail: `check failed — ${err.message}`,
@@ -413,7 +422,7 @@ const REMEDIATION = {
   mnestra_reachable: 'Start Mnestra with `mnestra serve`',
   mnestra_has_memories: 'Run `mnestra ingest` to populate the memory store',
   rumen_recent: 'Check Rumen Edge Function deployment or run `termdeck init --rumen`',
-  database_url: 'Set DATABASE_URL in ~/.termdeck/secrets.env',
+  database_url: 'Set DATABASE_URL in ~/.termdeck/secrets.env (IPv4-only hosts: use the Shared Pooler URL)',
   project_paths: 'Fix paths in ~/.termdeck/config.yaml → projects',
   shell_sanity: 'Check $SHELL and your login profile (~/.zshrc or ~/.bashrc)',
   graph_health: 'Run T2 inference cron or apply migrations 009/010 to populate edges',

package/packages/server/src/setup/rumen/functions/inbox-promote/index.ts

@@ -0,0 +1,105 @@
+// Rumen Sprint 76 — inbox-promote Supabase Edge Function entry point.
+//
+// Drains Mnestra's memory_inbox quarantine: web-chat proposals (written via
+// the bridge's memory_propose channel into engram migration 026's table) are
+// promoted to canonical memory_items or rejected with an audit trail. One
+// promotion pass per invocation; see src/promote.ts in @jhizzard/rumen for
+// the gate sequence (caps -> source whitelist -> rate cap -> dedup ->
+// kitchen-vs-recipe) and the doctrine amendment notes.
+//
+// Sibling of rumen-tick by design (NOT a step inside it): budget isolation
+// (the tick already spends its wall-clock on the insight cycle), independent
+// cadence, and failure isolation. Same thin-wrapper pattern: the npm:
+// specifier freezes the package version at DEPLOY time — upgrading
+// @jhizzard/rumen does nothing until this function is redeployed (the
+// Sprint 66 Brad-Rumen-zero lesson).
+//
+// IMPORTANT: This file targets the Deno runtime, NOT Node. It will not
+// compile under the root tsconfig.json — it is intentionally excluded.
+// A sibling tsconfig.json in this directory keeps the types sane for
+// editors, but the canonical build target is Deno's own type checker
+// (`deno check`) and Supabase's `supabase functions deploy`.
+//
+// Deployment (ORCH at sprint close — deployable, NOT deployed from a lane):
+//   supabase functions deploy inbox-promote
+//   supabase secrets set DATABASE_URL="$DATABASE_URL"          # Shared Pooler IPv4 URL
+//   supabase secrets set OPENAI_API_KEY="$OPENAI_API_KEY"      # dedup-gate embeddings (3-large@1536)
+//   supabase secrets set ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" # kitchen-vs-recipe Haiku gate
+//   # Optional tuning (defaults shown):
+//   supabase secrets set RUMEN_PROMOTE_BATCH=25
+//   supabase secrets set RUMEN_PROMOTE_RATE_CAP_24H=50
+//   supabase secrets set RUMEN_PROMOTE_MAX_ATTEMPTS=5
+//   supabase secrets set RUMEN_PROMOTE_CLAIM_LEASE_MINUTES=10
+//
+// Both model keys are REQUIRED: without them the pass skips (HTTP 503 below)
+// rather than claiming rows it cannot gate — config absence must not burn
+// promotion attempts across the inbox.
+//
+// Triggered on a schedule by pg_cron — see migrations/003_pg_cron_inbox_promote.sql.
+
+// @ts-ignore  Deno std import resolved at runtime.
+import { serve } from 'https://deno.land/std@0.224.0/http/server.ts';
+// @ts-ignore  npm specifier resolved at runtime. Version is stamped at
+// publish/deploy time by ORCH at sprint close — must be >= 0.6.0, the first
+// version exporting promoteInbox.
+import { promoteInbox, createPoolFromUrl } from 'npm:@jhizzard/rumen@0.6.0';
+
+// @ts-ignore  Deno global available at runtime.
+declare const Deno: { env: { get: (k: string) => string | undefined } };
+
+serve(async (_req: Request) => {
+  // Same fallback as rumen-tick: Supabase auto-injects SUPABASE_DB_URL.
+  const url = Deno.env.get('DATABASE_URL') ?? Deno.env.get('SUPABASE_DB_URL');
+  if (!url) {
+    console.error('[rumen-promote] DATABASE_URL / SUPABASE_DB_URL not set in Edge Function secrets');
+    return new Response(
+      JSON.stringify({ ok: false, error: 'DATABASE_URL not set' }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } },
+    );
+  }
+
+  const pool = createPoolFromUrl(url);
+
+  try {
+    console.log('[rumen-promote] edge function pass starting');
+    const summary = await promoteInbox(pool);
+
+    if (summary.skipped_reason) {
+      // Config-level skip (missing model key, rate-accounting failure):
+      // surface as a non-200 so pg_cron/operator dashboards notice, but the
+      // inbox is untouched and simply drains on a later pass.
+      console.error('[rumen-promote] pass skipped: ' + summary.skipped_reason);
+      return new Response(
+        JSON.stringify({ ok: false, skipped: summary.skipped_reason, summary }),
+        { status: 503, headers: { 'Content-Type': 'application/json' } },
+      );
+    }
+
+    console.log(
+      '[rumen-promote] edge function pass complete claimed=' +
+        summary.claimed +
+        ' promoted=' +
+        summary.promoted +
+        ' rejected=' +
+        summary.rejected,
+    );
+    // Row-level failures are fail-soft by design — the pass itself succeeded.
+    return new Response(
+      JSON.stringify({ ok: true, summary }),
+      { status: 200, headers: { 'Content-Type': 'application/json' } },
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error('[rumen-promote] edge function pass threw:', err);
+    return new Response(
+      JSON.stringify({ ok: false, error: message }),
+      { status: 500, headers: { 'Content-Type': 'application/json' } },
+    );
+  } finally {
+    try {
+      await pool.end();
+    } catch (err) {
+      console.error('[rumen-promote] pool.end() failed:', err);
+    }
+  }
+});

package/packages/server/src/setup/rumen/functions/inbox-promote/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": false,
+    "types": []
+  },
+  "include": ["index.ts"]
+}

package/packages/server/src/setup/supabase-url.js

@@ -186,6 +186,104 @@ function normalizeDatabaseUrl(url) {
   return { url: u.toString(), modified: true };
 }
 
+// ── DATABASE_URL endpoint-shape classification (Sprint 75 T2) ──────────────
+//
+// Ported from engram src/db-endpoint.ts (Sprint 74 T2 — Brad's Dell R730
+// field report, 2026-06-09). Supabase's direct endpoint
+// `db.<project-ref>.supabase.co` — which also hosts the Dedicated Pooler on
+// :6543 — publishes ONLY an AAAA record. On a host without IPv6 (many CI
+// runners and VPSes) pg clients don't fail fast; they hang until a pool
+// timeout. The IPv4-compatible alternative is the Shared Pooler:
+//
+//   postgres://postgres.<project-ref>:<pw>@aws-<n>-<region>.pooler.supabase.com:6543/postgres
+//
+// This classifier lets every DATABASE_URL ingress warn BEFORE the first
+// hang. It never rewrites or rejects anything — `looksLikePostgresUrl`
+// stays the blocking validator; direct URLs remain accepted because
+// IPv6-capable hosts use them legitimately. Warn ≠ reject.
+
+const LOCAL_DB_HOSTS = new Set(['localhost', '127.0.0.1', '0.0.0.0', '::1', '[::1]']);
+
+// Classify a raw DATABASE_URL string by endpoint family. Returns
+// { kind, host?, port?, username?, poolerUserMismatch? } where kind is one of:
+//   'absent'        — nothing usable provided
+//   'invalid'       — set but not parseable as postgres:// / postgresql://
+//   'direct'        — db.<project-ref>.supabase.co|in (IPv6-only: AAAA, no A
+//                     record; covers BOTH :5432 direct and :6543 Dedicated
+//                     Pooler — same hostname, same IPv4 unreachability)
+//   'shared-pooler' — *.pooler.supabase.com (IPv4-compatible)
+//   'local'         — loopback/local Postgres
+//   'other'         — self-hosted, RDS, IPv6 literal, … (no Supabase concerns)
+// poolerUserMismatch is true when the host is the Shared Pooler but the
+// username lacks the mandatory `.<project-ref>` suffix — the documented
+// "Tenant or user not found" failure.
+function classifyDbEndpoint(raw) {
+  if (raw === undefined || raw === null || typeof raw !== 'string') {
+    return { kind: 'absent' };
+  }
+  const trimmed = stripSurroundingQuotes(raw.trim());
+  if (trimmed === '') return { kind: 'absent' };
+
+  let u;
+  try {
+    u = new URL(trimmed);
+  } catch (_err) {
+    return { kind: 'invalid' };
+  }
+  if (u.protocol !== 'postgres:' && u.protocol !== 'postgresql:') {
+    return { kind: 'invalid' };
+  }
+
+  // Normalize: lowercase, drop a trailing FQDN dot.
+  const host = u.hostname.toLowerCase().replace(/\.$/, '');
+  let username = '';
+  try {
+    username = decodeURIComponent(u.username);
+  } catch (_err) {
+    username = u.username;
+  }
+  const base = { host, port: u.port, username };
+
+  if (LOCAL_DB_HOSTS.has(host)) return { kind: 'local', ...base };
+
+  if (/^db\.[a-z0-9-]+\.supabase\.(co|in)$/.test(host)) {
+    return { kind: 'direct', ...base };
+  }
+
+  if (host.endsWith('.pooler.supabase.com')) {
+    // Shared Pooler logins are `postgres.<project-ref>` — a dotless
+    // username means the URL was hand-assembled from direct-connection
+    // parts and will fail with "Tenant or user not found".
+    const poolerUserMismatch = username !== '' && !username.includes('.');
+    return { kind: 'shared-pooler', ...base, poolerUserMismatch };
+  }
+
+  return { kind: 'other', ...base };
+}
+
+// Warning lines for a classification — [] when there is nothing to say.
+// Wording kept byte-similar to engram's doctor probe messages so grep /
+// troubleshooting stays consistent across the stack. Print-only: callers
+// write these to stdout after a PASSING validation and never change exit
+// codes on their account.
+function directEndpointWarningLines(classification) {
+  if (!classification || typeof classification !== 'object') return [];
+  if (classification.kind === 'direct') {
+    return [
+      '⚠ this is the IPv6-only endpoint (db.<project-ref>.supabase.co — AAAA-only DNS, no IPv4)',
+      'on IPv4-only hosts pg clients hang until a pool/connect timeout',
+      'IPv4-safe: Connect modal → Transaction pooler → toggle ON "Use IPv4 connection (Shared Pooler)"',
+      'postgres://postgres.<project-ref>:<password>@aws-<n>-<region>.pooler.supabase.com:6543/postgres'
+    ];
+  }
+  if (classification.kind === 'shared-pooler' && classification.poolerUserMismatch) {
+    return [
+      `⚠ Shared Pooler host but username "${classification.username}" — pooler logins must be postgres.<project-ref>; fails with "Tenant or user not found"`
+    ];
+  }
+  return [];
+}
+
 // Mask all but the last 4 chars of a secret for logging.
 function maskSecret(value) {
   if (!value || typeof value !== 'string') return '';
@@ -202,5 +300,7 @@ module.exports = {
   isTransactionPoolerUrl,
   normalizeDatabaseUrl,
   maskSecret,
-  stripSurroundingQuotes
+  stripSurroundingQuotes,
+  classifyDbEndpoint,
+  directEndpointWarningLines
 };

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) {