@jhizzard/termdeck 1.1.0 → 1.2.0

package/packages/server/src/index.js

@@ -16,10 +16,28 @@ const { createCachedLookup, createFailureLogger } = require('./rumen-pool-resili
 // Conditional imports (graceful fallback if not installed yet)
 let pty, Database, pg;
 try { pty = require('@homebridge/node-pty-prebuilt-multiarch'); } catch { pty = null; }
-try { Database = require('better-sqlite3'); } catch { Database = null; }
+try {
+  Database = require('better-sqlite3');
+} catch (err) {
+  // Brad Heath 2026-05-11: distinguish a native-ABI mismatch (Node upgraded
+  // after install) from "package not installed yet." ABI mismatch leaves
+  // Database=null and cascades into a null-handle storm downstream that
+  // masquerades as "Mnestra unreachable / DB timeout" in health probes.
+  // Fail fast with the actionable rebuild hint instead.
+  const msg = err && err.message ? String(err.message) : '';
+  if (err && err.code === 'ERR_DLOPEN_FAILED' && /NODE_MODULE_VERSION/.test(msg)) {
+    console.error('[db] better-sqlite3 native ABI mismatch (Node was upgraded after install).');
+    console.error('[db] TermDeck cannot serve memory features without a working SQLite.');
+    console.error('[db] Fix:');
+    console.error('       cd "$(npm root -g)/@jhizzard/termdeck" && npm rebuild better-sqlite3');
+    console.error('[db] Then restart TermDeck. Aborting.');
+    process.exit(1);
+  }
+  Database = null;
+}
 try { pg = require('pg'); } catch { pg = null; }
 
-// Module-level singleton Postgres pool for rumen_insights (petvetbid DB).
+// Module-level singleton Postgres pool for rumen_insights (the daily-driver DB).
 // Lazy-initialized on first rumen endpoint hit so startup stays fast and
 // servers without DATABASE_URL never pay the connection cost.
 //
@@ -274,31 +292,42 @@ function _termdeckVersion() {
 // `pty.resize()` ioctls a stale fd. The error is race-expected, not a bug,
 // but the noisy console.error trace pollutes diagnostics and obscures real
 // errors. This helper guards against the race and downgrades the known
-// race-class errors (EBADF, ENOTTY, generic "ioctl failed" message shape) to
-// a silent return. Set TERMDECK_DEBUG_PTY_RACES=1 to log to console.debug
-// for diagnostics.
+// race-class errors (EBADF, ENOTTY) to a silent return. Set
+// TERMDECK_DEBUG_PTY_RACES=1 to log to console.debug for diagnostics.
+//
+// Sprint 63 T1 — `isPtyRaceError(err)` extracted so the WS message-handler
+// outer catch can also downgrade race-class errors that escape the helper's
+// own catch (e.g. if `pty.write` ever races the close, future code paths).
+// `session.pty._destroyed` short-circuit added as belt-and-suspenders for the
+// `term.kill()` → before-`term.onExit`-fires window: the DELETE handler now
+// stamps `_destroyed = true` immediately after kill(), so resize attempts in
+// that interval short-circuit without an ioctl call.
+function isPtyRaceError(err) {
+  if (!err) return false;
+  const msg = (err.message) || '';
+  const code = err.code;
+  return code === 'EBADF' ||
+    code === 'ENOTTY' ||
+    /\b(?:EBADF|ENOTTY)\b/.test(msg);
+}
+
 function safelyResizePty(session, cols, rows) {
   if (!session || !session.pty) return false;
+  if (session.pty._destroyed) return false;
   if (session.meta && session.meta.status === 'exited') return false;
   try {
     session.pty.resize(cols || 120, rows || 30);
     return true;
   } catch (err) {
-    const msg = (err && err.message) || '';
-    const code = err && err.code;
     // Sprint 60 v1.0.14 + T4-CODEX AUDIT-CONCERN narrowing: race classifier
     // requires explicit EBADF or ENOTTY (in code OR message). The earlier
     // shape — any "ioctl(N) failed" message — was too broad: it would have
     // silently dropped a non-race ioctl failure (e.g. EINTR, EFAULT) that
     // might indicate a real bug. Now: only the specific race-class signals
     // get suppressed; everything else rethrows so it surfaces in logs.
-    const isRace =
-      code === 'EBADF' ||
-      code === 'ENOTTY' ||
-      /\b(?:EBADF|ENOTTY)\b/.test(msg);
-    if (isRace) {
+    if (isPtyRaceError(err)) {
       if (process.env.TERMDECK_DEBUG_PTY_RACES) {
-        console.debug(`[ws] resize-after-pty-exit (race-expected): session=${session.id} ${code || msg}`);
+        console.debug(`[ws] resize-after-pty-exit (race-expected): session=${session.id} ${err.code || err.message}`);
       }
       return false;
     }
@@ -306,6 +335,35 @@ function safelyResizePty(session, cols, rows) {
   }
 }
 
+// Sprint 63 T1 (Item 1.3) — body-parser hardening. The pre-existing
+// `entity.verify.failed` / `entity.parse.failed` handler logged the error
+// message but not WHICH bytes triggered the parse failure. Operators on
+// Brad's r730 saw 9× SyntaxError flood over 13h with no fingerprint to
+// identify the offending caller. `hexEscapePrefix` renders a 32-byte
+// prefix of the raw body in a single-line, log-safe form: printable ASCII
+// kept verbatim, non-printables rendered as `\xNN`, backslash escaped as
+// `\\`. PII-conservative because we cap at 32 bytes (truncation marker `…`
+// appended if more). The error middleware injects this into the existing
+// `console.warn` line so the log signature is identifiable without
+// dumping the full body.
+function hexEscapePrefix(buf, maxBytes = 32) {
+  if (!buf || buf.length === 0) return '<no-body>';
+  const len = Math.min(buf.length, maxBytes);
+  let out = '';
+  for (let i = 0; i < len; i++) {
+    const b = buf[i];
+    if (b === 0x5c) {
+      out += '\\\\';
+    } else if (b >= 0x20 && b < 0x7f) {
+      out += String.fromCharCode(b);
+    } else {
+      out += '\\x' + b.toString(16).padStart(2, '0');
+    }
+  }
+  if (buf.length > maxBytes) out += '…';
+  return out;
+}
+
 function createServer(config) {
   const app = express();
   const server = http.createServer(app);
@@ -328,6 +386,13 @@ function createServer(config) {
   // logs so real errors aren't drowned in noise.
   app.use(express.json({
     verify: (req, res, buf) => {
+      // Sprint 63 T1 (Item 1.3) — capture a stable copy of the raw body so
+      // the error middleware below can render a 32-byte hex-escaped prefix.
+      // `Buffer.from(buf)` copies because express may pool the underlying
+      // accumulator across requests; without the copy the error handler
+      // could see bytes from a later request.
+      req.rawBody = Buffer.from(buf);
+
       // O(N) single-pass scan. Only checks bytes inside double-quoted string
       // regions so structural whitespace doesn't trigger false positives.
       let inString = false;
@@ -372,7 +437,13 @@ function createServer(config) {
       err.type === 'entity.verify.failed' ||
       err instanceof SyntaxError
     )) {
-      console.warn(`[body-parser] ${err.code || err.type || 'parse-error'}: ${err.message} (${req.method} ${req.path})`);
+      // Sprint 63 T1 (Item 1.3) — append a 32-byte hex-escaped prefix of the
+      // raw body so the operator can identify which caller is sending bad
+      // JSON without exposing the full payload. Falls through to `<no-body>`
+      // if the verify callback never ran (parse error before verify, or no
+      // body at all).
+      const prefix = hexEscapePrefix(req.rawBody);
+      console.warn(`[body-parser] ${err.code || err.type || 'parse-error'}: ${err.message} (${req.method} ${req.path}) prefix="${prefix}"`);
       return res.status(400).json({
         error: 'Malformed JSON body',
         detail: err.message,
@@ -1171,6 +1242,18 @@ function createServer(config) {
             const sessUploadDir = path.join(os.tmpdir(), 'termdeck-uploads', session.id);
             fs.rmSync(sessUploadDir, { recursive: true, force: true });
           } catch (_err) { /* non-blocking */ }
+
+          // Sprint 63 T1 (Item 1.1) — null `session.pty` so the wrapper is
+          // eligible for GC and downstream `if (session.pty)` guards correctly
+          // identify the exited state. Root cause of Joshua's 2026-05-08/09
+          // overnight `kern.tty.ptmx_max=511` exhaustion (516 fds for 4 panels):
+          // without this nulling, node-pty's wrapper stayed pinned by onData /
+          // onExit closures even after the child exited, holding the master
+          // fd until next GC pass. Set AFTER `onPanelClose` fires (fire-and-
+          // forget; reads `session.meta` + `session.id`, not `session.pty`) and
+          // AFTER the upload-dir cleanup so any sync reader above this line
+          // sees the original wrapper.
+          session.pty = null;
         });
 
         // Wire command logging to SQLite + RAG
@@ -1328,7 +1411,7 @@ function createServer(config) {
   });
 
   // Graph endpoints (Sprint 38 T4) — knowledge-graph view backing graph.html.
-  // Reuses the petvetbid pg pool (same DATABASE_URL serves memory_items +
+  // Reuses the daily-driver pg pool (same DATABASE_URL serves memory_items +
   // memory_relationships alongside rumen_*). Graceful-degrades when the pool
   // is absent.
   createGraphRoutes({
@@ -1358,6 +1441,14 @@ function createServer(config) {
     // Kill PTY process
     if (session.pty) {
       try { session.pty.kill(); } catch (err) { console.error('[pty] kill failed for session', req.params.id + ':', err); }
+      // Sprint 63 T1 (Item 1.2) — stamp `_destroyed = true` on the pty wrapper
+      // so `safelyResizePty` can short-circuit any resize attempts that arrive
+      // in the kill()→onExit window. node-pty's `kill()` only signals the
+      // child; onExit fires asynchronously once the child reaps. Without this
+      // marker, a WS resize message in that window would ioctl a fd whose
+      // child has just SIGHUP'd, surfacing as EBADF/ENOTTY. node-pty doesn't
+      // set this property itself; the convention is owned by TermDeck.
+      session.pty._destroyed = true;
     }
 
     sessions.remove(req.params.id);
@@ -1577,15 +1668,23 @@ function createServer(config) {
   });
 
   // POST /api/sessions/:id/resize - resize terminal
+  // Sprint 63 T1 (Item 1.2) — distinguish "session never existed" (404) from
+  // "session exists but PTY has exited" (410 Gone). Pre-Sprint-63 both paths
+  // collapsed to 404 (when session.pty was null after the PTY-leak fix) or
+  // 409 (when safelyResizePty returned false). 410 is the semantically
+  // correct response: the resource was here, the resource is now gone.
   app.post('/api/sessions/:id/resize', (req, res) => {
     const session = sessions.get(req.params.id);
-    if (!session?.pty) return res.status(404).json({ error: 'Session not found' });
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+    if (!session.pty || (session.meta && session.meta.status === 'exited')) {
+      return res.status(410).json({ error: 'PTY is gone (session exited)' });
+    }
 
     const { cols, rows } = req.body;
     try {
       const resized = safelyResizePty(session, cols, rows);
       if (!resized) {
-        return res.status(409).json({ error: 'Session is exited or its PTY is no longer alive' });
+        return res.status(410).json({ error: 'PTY is gone (session exited)' });
       }
       res.json({ ok: true, cols, rows });
     } catch (err) {
@@ -2009,7 +2108,7 @@ function createServer(config) {
   });
 
   // ==================== Rumen insights (Sprint 4 T2) ====================
-  // Read-only access to rumen_insights + rumen_jobs in the petvetbid Postgres
+  // Read-only access to rumen_insights + rumen_jobs in the daily-driver Postgres
   // instance. Contract frozen in docs/sprint-4-rumen-integration/API-CONTRACT.md.
 
   function rumenUnreachable(res) {
@@ -2250,7 +2349,7 @@ function createServer(config) {
 
         switch (parsed.type) {
           case 'input':
-            if (session.pty) {
+            if (session.pty && !session.pty._destroyed) {
               session.pty.write(parsed.data);
               session.trackInput(parsed.data);
             }
@@ -2271,7 +2370,21 @@ function createServer(config) {
             }));
             break;
         }
-      } catch (err) { console.error('[ws] message handler error:', err); }
+      } catch (err) {
+        // Sprint 63 T1 (Item 1.2) — belt-and-suspenders: if a race-class
+        // ioctl error somehow escapes safelyResizePty's own catch (or comes
+        // from a future write/ioctl path), downgrade to console.debug
+        // instead of polluting stderr with the noisy ws-message-handler
+        // error log. safelyResizePty itself already catches the resize
+        // path; this catches any other race-class shape that bubbles here.
+        if (isPtyRaceError(err)) {
+          if (process.env.TERMDECK_DEBUG_PTY_RACES) {
+            console.debug(`[ws] message handler race-class (suppressed): ${err.code || err.message}`);
+          }
+        } else {
+          console.error('[ws] message handler error:', err);
+        }
+      }
     });
 
     ws.on('close', () => {
@@ -2581,6 +2694,11 @@ module.exports = {
   // helper instead of re-implementing it. T4-CODEX AUDIT-CONCERN flagged that
   // the prior re-implementation pattern in the test could drift silently.
   safelyResizePty,
+  // Sprint 63 T1 (Item 1.2 + 1.3) — race-class classifier + raw-body hex
+  // prefix renderer exported so fence tests can import the production
+  // helpers instead of re-implementing them.
+  isPtyRaceError,
+  hexEscapePrefix,
   // Sprint 48 T4 — exported for unit testing the secrets.env → PTY env merge.
   readTermdeckSecretsForPty,
   _resetTermdeckSecretsCache,

package/packages/server/src/preflight.js

@@ -261,7 +261,13 @@ async function checkShellSanity() {
     let output = '';
     let resolved = false;
 
-    const proc = ptyMod.spawn(shell, ['-l', '-c', 'echo TERMDECK_OK'], {
+    // Sprint 63 T3 §3.3 — drop `-l` (login mode). `-l` sources ~/.bash_profile
+    // / ~/.zshrc and friends, which on heavy profiles (nvm, conda, plugin
+    // managers — Brad's r730 has conda) routinely exceeds the 3s timeout
+    // budget below. A PTY-spawn health check answers "can $SHELL spawn a
+    // PTY and emit output?" — not "does the user's interactive profile
+    // complete fast?" Login-mode startup time is unrelated to PTY health.
+    const proc = ptyMod.spawn(shell, ['-c', 'echo TERMDECK_OK'], {
       name: 'xterm-256color',
       cols: 80,
       rows: 24,

package/packages/server/src/setup/migrations.js

@@ -110,7 +110,33 @@ const MIGRATION_PROBES = Object.freeze({
   '018_rumen_processed_at.sql':
     "select 1 from information_schema.columns where table_schema='public' and table_name='memory_sessions' and column_name='rumen_processed_at'",
   '019_security_hardening.sql':
-    "select 1 from pg_proc p, unnest(coalesce(p.proconfig,'{}'::text[])) c where p.proname='memory_hybrid_search' and c like 'search_path=%' and c like '%extensions%'"
+    "select 1 from pg_proc p, unnest(coalesce(p.proconfig,'{}'::text[])) c where p.proname='memory_hybrid_search' and c like 'search_path=%' and c like '%extensions%'",
+  // 021 canonicalizes legacy gorgias / gorgias-ticket-monitor project tags to
+  // claimguard. Probe is NOT-EXISTS-shaped: returns 1 row when both legacy
+  // tags carry zero rows (021's effects are in place OR the install never had
+  // legacy data). Returns 0 rows when at least one legacy tag still has rows
+  // (021 has not yet run). False-positive backfill costs nothing because the
+  // migration's UPDATE is gated on `project IN ('gorgias', 'gorgias-ticket-monitor')`
+  // so a re-apply against an already-canonicalized corpus is a 0-row no-op.
+  // Sprint 62 T2 added this; 020 is bootstrap-special-cased and intentionally
+  // absent from MIGRATION_PROBES.
+  '021_project_tag_canonicalize_claimguard.sql':
+    "select 1 where not exists (select 1 from memory_items where project in ('gorgias', 'gorgias-ticket-monitor'))",
+  // 022 backfills source_agent for the rows where the writer is inferable from
+  // row shape (Predicate A: decision/bug_fix/architecture/preference/code_context
+  // → 'claude'; Predicate B: fact rows with source_session_id → 'claude';
+  // Predicate D: document_chunk → 'orchestrator'). Predicate C (fact rows
+  // with no session and no path) is intentionally NOT backfilled — see the
+  // migration body for the provenance-preservation rationale. Probe is
+  // NOT-EXISTS-shaped over the A/B/D row-set: returns 1 when those targets
+  // all have source_agent set (022's effects in place), 0 when any A/B/D
+  // target still has NULL (022 has not yet run). Excludes Predicate C from
+  // the probe predicate so the residual NULL slice doesn't keep the probe
+  // false forever. False-positive backfill costs nothing because the
+  // migration body is gated on `source_agent IS NULL` and a re-apply against
+  // an already-tagged corpus is a 0-row no-op. Sprint 62 T3.
+  '022_source_agent_backfill.sql':
+    "select 1 where not exists (select 1 from memory_items where source_agent is null and (source_type in ('decision','bug_fix','architecture','preference','code_context') or (source_type='fact' and source_session_id is not null) or source_type='document_chunk'))"
 });
 
 // Sprint 61 T2 — self-transactional detection.

package/packages/server/src/setup/mnestra-migrations/021_project_tag_canonicalize_claimguard.sql

@@ -0,0 +1,175 @@
+-- 021_project_tag_canonicalize_claimguard.sql
+-- Sprint 62 T2 — finishes the gorgias / gorgias-ticket-monitor → claimguard
+-- rename that migration 012 (Sprint 41 T2) explicitly scoped out.
+--
+-- Why this exists:
+--   Same project (the ClaimGuard repo at ~/Documents/Unagi/gorgias-ticket-monitor)
+--   was tagged three ways across history. As of 2026-05-08:
+--     - 'claimguard'              ~29 rows  (newest tag, written by the
+--                                            post-Sprint-41 PROJECT_MAP)
+--     - 'gorgias-ticket-monitor' ~245 rows  (mid tag, the on-disk dir name)
+--     - 'gorgias'                ~541 rows  (oldest tag, pre-Sprint-41)
+--
+--   Migration 012's §"What this migration does NOT do" called out the merge
+--   as a separate cleanup pass:
+--
+--     - Does NOT consolidate duplicate tags like 'gorgias' vs
+--       'gorgias-ticket-monitor', 'pvb' vs 'PVB', or 'mnestra' vs 'engram'.
+--       Visible in `SELECT project, count(*) FROM memory_items GROUP BY
+--       project` but a separate cleanup pass.
+--
+--   That separate pass is 021. Sprint 21 T2's earlier rename plan never
+--   landed; Sprint 35's harness-hook fix addressed the upstream PROJECT_MAP
+--   so new rows tag correctly, and Sprint 62 T2 (this migration) closes the
+--   historical-corpus gap so memory_recall(project="claimguard") returns the
+--   full ~815-row history rather than just the post-Sprint-41 tail.
+--
+-- The companion T2 invariant test at
+-- termdeck/tests/project-tag-invariant.test.js currently skips the claimguard
+-- invariant via `deferredToSprint35`; with 021 applied that invariant would
+-- pass cleanly if un-deferred. Un-deferring is out of T2's lane (test edits
+-- are owned by orchestrator close-out).
+--
+-- Why the *project*-column merge and not a content-keyword rebucket: rows
+-- already-tagged 'gorgias' or 'gorgias-ticket-monitor' carry definitive
+-- project provenance — the row is from the ClaimGuard project by virtue of
+-- the writer's prior tag, regardless of content keywords. We are not
+-- inferring; we are renaming an exact-match tag set that the SOURCE-BRIEF
+-- and 012's prologue both confirm refer to the same on-disk codebase.
+--
+-- Idempotence:
+--   The UPDATE is gated by `WHERE project IN ('gorgias','gorgias-ticket-monitor')`.
+--   After the first apply those rows carry project='claimguard', so a re-run
+--   matches zero rows — RAISE NOTICE prints 0 and the migration succeeds. The
+--   bundled migration runner (packages/server/src/setup/migration-runner.js)
+--   also checksums applied migrations into mnestra_migrations (table from
+--   020) and skips re-application by filename, so the in-runner path is
+--   idempotent at two layers.
+--
+-- RLS posture:
+--   memory_items has RLS enabled (per migration 019 security hardening), but
+--   service_role bypasses RLS. The migration runner authenticates as
+--   service_role via DATABASE_URL, so the UPDATE lands without policy
+--   changes. This migration does NOT touch policies or roles.
+--
+-- Reversibility:
+--   Down-migration is documented at the bottom (commented). Splitting the
+--   merged set back into three is destructive — once project='claimguard'
+--   replaces the prior values, the row provenance for which tag it ORIGINALLY
+--   carried is gone (no audit column tracks pre-image). Reversal requires
+--   restore from a pg_dump snapshot taken before the migration was applied.
+--   Do NOT attempt heuristic reversal.
+--
+-- Application:
+--   Applied via the bundled migration runner using node-postgres
+--   client.query(). DO blocks + GET DIAGNOSTICS ROW_COUNT (no psql
+--   metacommands — \gset / \echo / etc are not supported in client.query).
+--   Manual fallback: `psql "$DATABASE_URL" -f 021_project_tag_canonicalize_claimguard.sql`.
+
+BEGIN;
+
+-- ============================================================
+-- AUDIT BEFORE
+-- ============================================================
+DO $$
+DECLARE
+  before_claimguard               int;
+  before_gorgias                  int;
+  before_gorgias_ticket_monitor   int;
+  before_total_three              int;
+BEGIN
+  SELECT count(*) INTO before_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO before_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO before_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  before_total_three := before_claimguard + before_gorgias + before_gorgias_ticket_monitor;
+  RAISE NOTICE '[021-canonicalize] BEFORE  claimguard=% gorgias=% gorgias-ticket-monitor=%  (sum=%)',
+    before_claimguard, before_gorgias, before_gorgias_ticket_monitor, before_total_three;
+END $$;
+
+-- ============================================================
+-- CANONICALIZE — gorgias + gorgias-ticket-monitor → claimguard
+--
+-- Single-statement UPDATE on the project column. No content scoping required:
+-- the source tags refer unambiguously to the ClaimGuard project per Sprint 41
+-- T2's analysis (012's prologue) and the SOURCE-BRIEF for Sprint 62 §1.
+-- ============================================================
+DO $$
+DECLARE
+  affected_count integer;
+BEGIN
+  UPDATE public.memory_items
+     SET project = 'claimguard'
+   WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+  GET DIAGNOSTICS affected_count = ROW_COUNT;
+  RAISE NOTICE '[021-canonicalize] canonicalized % memory_items rows  (gorgias + gorgias-ticket-monitor) -> claimguard',
+    affected_count;
+END $$;
+
+-- ============================================================
+-- AUDIT AFTER + CONSERVATION CHECK
+-- ============================================================
+DO $$
+DECLARE
+  after_claimguard               int;
+  after_gorgias                  int;
+  after_gorgias_ticket_monitor   int;
+BEGIN
+  SELECT count(*) INTO after_claimguard
+    FROM public.memory_items WHERE project = 'claimguard';
+  SELECT count(*) INTO after_gorgias
+    FROM public.memory_items WHERE project = 'gorgias';
+  SELECT count(*) INTO after_gorgias_ticket_monitor
+    FROM public.memory_items WHERE project = 'gorgias-ticket-monitor';
+  RAISE NOTICE '[021-canonicalize] AFTER   claimguard=% gorgias=% gorgias-ticket-monitor=%',
+    after_claimguard, after_gorgias, after_gorgias_ticket_monitor;
+  IF after_gorgias <> 0 OR after_gorgias_ticket_monitor <> 0 THEN
+    RAISE EXCEPTION
+      '[021-canonicalize] post-apply invariant violated: expected zero rows in gorgias / gorgias-ticket-monitor, got gorgias=% gorgias-ticket-monitor=%',
+      after_gorgias, after_gorgias_ticket_monitor;
+  END IF;
+END $$;
+
+COMMIT;
+
+-- ============================================================
+-- POST-APPLY: verification queries (NOT part of the migration; run separately
+-- to confirm the merge took, the invariant tests stay green, and the recall
+-- path returns the full history). Each query is safe to run repeatedly.
+-- ============================================================
+--
+-- 1. Tag distribution after migration — claimguard should be the only
+--    bucket among the three; gorgias / gorgias-ticket-monitor should be 0:
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE project IN ('claimguard', 'gorgias', 'gorgias-ticket-monitor')
+--       GROUP BY project ORDER BY project;
+--
+-- 2. Confirm no orphan rows remain under either legacy tag (these should
+--    return 0):
+--      SELECT count(*) FROM public.memory_items
+--       WHERE project IN ('gorgias', 'gorgias-ticket-monitor');
+--
+-- 3. Spot-check that the merged set carries content from all three
+--    historical eras (look for varied dates, varied source_types):
+--      SELECT date_trunc('week', created_at) AS week, count(*)
+--        FROM public.memory_items
+--       WHERE project = 'claimguard'
+--       GROUP BY 1 ORDER BY 1;
+--
+-- 4. Confirm the project-tag invariant test for claimguard would now pass
+--    if un-deferred (rows whose content matches gorgias-ticket-monitor or
+--    Unagi/ identifiers should be top-tagged claimguard):
+--      SELECT project, count(*) FROM public.memory_items
+--       WHERE content ILIKE '%gorgias-ticket-monitor%'
+--          OR content ILIKE '%Unagi/%'
+--       GROUP BY project ORDER BY count(*) DESC LIMIT 5;
+--
+-- DOWN-MIGRATION (manual, NOT auto-applied):
+--   Splitting the merged set back into three is non-trivial (no source-of-
+--   truth on which rows were originally which tag — provenance is lost when
+--   the UPDATE replaces the project string). If a roll-back is needed,
+--   restore from a pg_dump taken before this migration was applied. Do NOT
+--   attempt to reverse via heuristic — the row provenance is destroyed by
+--   the merge.