@jhizzard/termdeck 1.0.14 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.0.14",
+  "version": "1.1.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/cli/src/init-mnestra.js

@@ -332,23 +332,63 @@ async function promptSecretWithValidation(validator) {
   throw new Error('Too many invalid attempts — cancelling.');
 }
 
+// Sprint 61 T2 — collapsed fresh-install / upgrade paths. Pre-Sprint-61, the
+// wizard re-applied every bundled mnestra migration on every invocation,
+// relying on per-file IF NOT EXISTS / CREATE OR REPLACE idempotency. That
+// works for fresh installs but doesn't tell the wizard which migrations the
+// live database has actually received — so a user running
+// `npm install -g @latest` against an existing project lands in Class A
+// (schema drift on package upgrade): the npm package files upgrade, the
+// database stays at first-kickstart state. Brad reported this 2026-05-02.
+//
+// applyPendingMigrations (migrations.js) replaces the loop with a tracker-
+// aware diff: SELECT applied filenames from public.mnestra_migrations, run
+// only the bundled-but-unapplied ones, INSERT a tracker row per apply.
+// Pre-020 installs trigger a one-time backfill probe pass that seeds the
+// tracker for migrations whose schema artifacts are already present.
 async function applyMigrations(client, dryRun) {
   const files = migrations.listMnestraMigrations();
   if (files.length === 0) {
     throw new Error('No Mnestra migrations found. TermDeck install looks corrupted.');
   }
 
-  for (const file of files) {
-    const base = path.basename(file);
-    step(`Applying migration ${base}...`);
-    if (dryRun) { ok('(dry-run)'); continue; }
-    const result = await pgRunner.applyFile(client, file);
-    if (result.ok) {
-      ok(`(${result.elapsedMs}ms)`);
-    } else {
-      fail(result.error);
-      throw new Error(`Migration failed: ${base}`);
+  if (dryRun) {
+    // Preserve the per-file dry-run banner so the user sees the planned
+    // sequence without touching the database.
+    for (const file of files) {
+      const base = path.basename(file);
+      step(`Applying migration ${base}...`);
+      ok('(dry-run)');
     }
+    return;
+  }
+
+  step('Running tracker-aware diff-and-apply (skips already-applied migrations)...');
+  const summary = await migrations.applyPendingMigrations(client);
+
+  if (summary.errored) {
+    fail(`${summary.errored.file}: ${summary.errored.error}`);
+    throw new Error(`Migration failed: ${summary.errored.file}`);
+  }
+
+  ok(
+    `(applied ${summary.applied.length}, backfilled ${summary.backfilled.length}, ` +
+    `skipped ${summary.skipped.length})`
+  );
+
+  for (const f of summary.applied) {
+    process.stdout.write(`    ✓ applied ${f}\n`);
+  }
+  for (const f of summary.backfilled) {
+    process.stdout.write(`    ◇ backfilled ${f} (schema already present, recorded in tracker)\n`);
+  }
+  for (const w of summary.warnings) {
+    const tracked = (w.trackedChecksum || '').slice(0, 12) || '<empty>';
+    const bundled = (w.bundledChecksum || '').slice(0, 12) || '<empty>';
+    process.stdout.write(
+      `    ! checksum drift on ${w.file}: tracked=${tracked}, bundled=${bundled} ` +
+      `(no auto-overwrite — investigate before re-running)\n`
+    );
   }
 }
 

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

@@ -26,9 +26,120 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 const SETUP_DIR = __dirname;
 
+// Sprint 61 T2 — durable migration tracking table + filename + table name.
+// `mnestra_migrations` is created by bundled migration 020 (RLS-on,
+// service_role-only, no policies). The applyPendingMigrations diff loop and
+// the backfill probe both target this table.
+const TRACKER_TABLE = 'public.mnestra_migrations';
+const TRACKER_FILE = '020_migration_tracking.sql';
+
+// Sprint 61 T2 — declarative probe set.
+//
+// One row per bundled mnestra migration 001-019 (020 itself is the tracker
+// and is bootstrap-special-cased; not probed). Each probe is a single
+// presence-style SQL statement: returns ≥1 row when the migration's schema
+// artifact is in place, 0 rows otherwise.
+//
+// Used by applyPendingMigrations() during the backfill pass: when an install
+// is pre-020 (no tracker table yet) and a bundled migration is not in the
+// applied-set, the probe decides whether the migration's effects are already
+// present (→ INSERT a backfill tracker row, skip apply) or genuinely missing
+// (→ run the migration via the normal apply path, INSERT a real tracker row).
+//
+// Probe values:
+//   - string: SQL fragment to run via client.query(). Probe is "present"
+//             when the result has ≥1 row.
+//   - null:   no schema artifact to introspect (DML migrations, comments-only
+//             placeholders). The first apply runs the migration; the tracker
+//             row prevents re-application on subsequent passes. The brief
+//             notes 003 (event_webhook placeholder), 011 (project_tag_backfill
+//             DML), and 012 (project_tag_re_taxonomy DML) fall here.
+const MIGRATION_PROBES = Object.freeze({
+  '001_mnestra_tables.sql':
+    "select 1 from information_schema.tables where table_schema='public' and table_name='memory_items'",
+  '002_mnestra_search_function.sql':
+    "select 1 from pg_proc where proname='memory_hybrid_search'",
+  // 003 is a comments-only placeholder migration with no DDL/DML body. The
+  // apply path is a no-op on every install. Always-present probe is the
+  // honest schema fingerprint — every install for which 001 has run is
+  // also "compatible with 003." Post-Sprint-61-T2-audit refinement.
+  '003_mnestra_event_webhook.sql':
+    "select 1",
+  '004_mnestra_match_count_cap_and_explain.sql':
+    "select 1 from pg_proc where proname='memory_hybrid_search_explain'",
+  '005_v0_1_to_v0_2_upgrade.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_items' and column_name='archived'",
+  '006_memory_status_rpc.sql':
+    "select 1 from pg_proc where proname='memory_status_aggregation'",
+  '007_add_source_session_id.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_items' and column_name='source_session_id'",
+  '008_legacy_rag_tables.sql':
+    "select 1 from information_schema.tables where table_schema='public' and table_name='mnestra_session_memory'",
+  '009_memory_relationship_metadata.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_relationships' and column_name='weight'",
+  '010_memory_recall_graph.sql':
+    "select 1 from pg_proc where proname='memory_recall_graph'",
+  // 011 retags chopin-nashville rows into post-Sprint-41 buckets (termdeck,
+  // rumen, podium, pvb, dor). Probe present iff any row carries one of those
+  // tags — meaning either 011 has run, or the install legitimately has rows
+  // tagged that way through other means. Either way the apply is a no-op
+  // (the UPDATEs are gated on `project = 'chopin-nashville'`), so a false-
+  // positive backfill costs nothing. Post-Sprint-61-T2-audit refinement.
+  '011_project_tag_backfill.sql':
+    "select 1 from memory_items where project in ('termdeck', 'rumen', 'podium', 'pvb', 'dor') limit 1",
+  // 012 expands 011's taxonomy with chopin-in-bohemia, chopin-scheduler, and
+  // claimguard buckets. Probe present iff any row is in those expanded
+  // buckets. Same false-positive-is-harmless reasoning as 011.
+  // Post-Sprint-61-T2-audit refinement.
+  '012_project_tag_re_taxonomy.sql':
+    "select 1 from memory_items where project in ('chopin-in-bohemia', 'chopin-scheduler', 'claimguard') limit 1",
+  '013_reclassify_uncertain.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_items' and column_name='reclassified_by'",
+  '014_explicit_grants.sql':
+    "select 1 where has_table_privilege('service_role', 'public.memory_items', 'INSERT')",
+  '015_source_agent.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_items' and column_name='source_agent'",
+  '016_mnestra_doctor_probes.sql':
+    "select 1 from pg_proc where proname='mnestra_doctor_vault_secret_exists'",
+  '017_memory_sessions_session_metadata.sql':
+    "select 1 from information_schema.columns where table_schema='public' and table_name='memory_sessions' and column_name='session_id'",
+  '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%'"
+});
+
+// Sprint 61 T2 — self-transactional detection.
+//
+// Bundled migrations 011 + 012 contain top-level `BEGIN;` and `COMMIT;`
+// statements (011:75/217, 012:76/353). When the diff-apply loop wrapped
+// these in its own outer BEGIN/COMMIT, the inner COMMIT closed the outer
+// transaction prematurely and the subsequent `recordApplied` INSERT ran
+// auto-committed — defeating the per-file atomicity contract. T4-CODEX
+// audit-concern 2026-05-07 18:51 ET surfaced this.
+//
+// Detection: case-sensitive match for a line that is exactly `BEGIN;` or
+// `COMMIT;` (top-level). PL/pgSQL anonymous block delimiters (`begin ... end`
+// inside `do $$ ... $$`) use lowercase without trailing semicolon-on-its-
+// own-line, so they don't match.
+//
+// Behavior for self-transactional migrations: SKIP the outer wrapper.
+// Apply via pgRunner.applyFile (which sends the file as a single batched
+// query, inner BEGIN/COMMIT handled by Postgres). Then INSERT the tracker
+// row in a separate auto-commit. The tracker INSERT is recoverable on
+// failure: 011/012 are idempotent (`WHERE project = 'chopin-nashville'`
+// gates every UPDATE; re-running on an already-retagged install is a no-op),
+// so a missing tracker row from a failed INSERT will be re-applied on the
+// next pass and the INSERT retried. The brief explicitly notes this
+// recovery shape under "out-of-T2 scope: rumen migration tracker."
+function isSelfTransactional(sql) {
+  return /^[ \t]*(BEGIN|COMMIT)[ \t]*;[ \t]*$/m.test(sql);
+}
+
 function listBundled(subdir) {
   const dir = path.join(SETUP_DIR, subdir);
   if (!fs.existsSync(dir)) return [];
@@ -127,11 +238,387 @@ function readFile(filepath) {
   return fs.readFileSync(filepath, 'utf-8');
 }
 
+// ── Sprint 61 T2 — durable migration tracker + diff-and-apply ──────────────
+//
+// applyPendingMigrations(client, opts) replaces the per-wizard
+// "apply every bundled migration" loop with a tracker-aware diff loop:
+//
+//   1. Try `SELECT filename, checksum FROM public.mnestra_migrations`.
+//      On 42P01 (relation does not exist), the project is pre-020 — bootstrap
+//      by applying 020 directly, then INSERT 020's own tracker row, then
+//      re-query.
+//   2. Iterate bundled migrations 001..N in lex-filename order. For each
+//      bundled file:
+//        - Already in tracker: skip; if tracked checksum != bundled checksum,
+//          push to warnings[] (do NOT auto-overwrite).
+//        - Not in tracker AND probe says present: INSERT backfill row
+//          (applied_at = '1970-01-01T00:00:00Z', schema_version = 'backfill'),
+//          skip apply. (As of Sprint 61 T2 audit refinement, every bundled
+//          migration 001-019 has a non-null probe in MIGRATION_PROBES; the
+//          null-probe branch is preserved for forward-compatibility.)
+//        - Not in tracker AND probe absent (or null probe):
+//            * Self-transactional file (top-level BEGIN; / COMMIT;, currently
+//              011/012): SKIP the outer wrapper. apply via pgRunner.applyFile
+//              (the file's own transaction control runs through Postgres).
+//              INSERT tracker row in a separate auto-commit. Tracker INSERT
+//              failure is recoverable: re-running applyPendingMigrations
+//              re-applies the migration (idempotent — the bundled self-tx
+//              files are gated on chopin-nashville rows, no-op on subsequent
+//              runs) and retries the tracker INSERT.
+//            * Non-self-transactional file: BEGIN, apply via
+//              pgRunner.applyFile, INSERT real tracker row, COMMIT. On
+//              error, ROLLBACK and halt — record errored summary, do not
+//              attempt subsequent migrations.
+//
+// Returns:
+//   {
+//     applied:     string[]                       // filenames applied this pass
+//     skipped:     string[]                       // filenames already in tracker
+//     backfilled:  string[]                       // filenames probe-seeded this pass
+//     warnings:    Array<{ file, trackedChecksum, bundledChecksum }>
+//     errored:     null | { file, error }
+//   }
+//
+// Idempotent: a second invocation against an up-to-date project reports
+// applied=[], backfilled=[], errored=null, and skipped=[...all bundled].
+//
+// Test injection (every dependency is replaceable):
+//   opts._migrations  — module override for listMnestraMigrations / readFile
+//                       (defaults to this module's own exports).
+//   opts._readFile    — file-read shim (defaults to fs.readFileSync utf-8).
+//   opts._applyFile   — pgRunner.applyFile shim (defaults to lazy-required
+//                       ./pg-runner.applyFile to avoid pulling node-postgres
+//                       at module-load time).
+//   opts._probes      — MIGRATION_PROBES override (defaults to the constant).
+
+function computeChecksum(content) {
+  return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+// Lazy-resolve pgRunner.applyFile so callers in test environments can avoid
+// the `require('pg')` cost. Tests override via opts._applyFile.
+function defaultApplyFile() {
+  const pgRunner = require('./pg-runner');
+  return (client, file) => pgRunner.applyFile(client, file);
+}
+
+// Returns Map<filename, checksum> when the tracker exists, null when the
+// table is missing (PG error code 42P01 — relation does not exist). Any
+// other error propagates.
+async function loadAppliedSet(client) {
+  let res;
+  try {
+    res = await client.query(
+      `SELECT filename, checksum FROM ${TRACKER_TABLE}`
+    );
+  } catch (err) {
+    if (err && err.code === '42P01') return null;
+    throw err;
+  }
+  const map = new Map();
+  for (const row of (res && res.rows) || []) {
+    map.set(row.filename, row.checksum);
+  }
+  return map;
+}
+
+// Pre-020 bootstrap: the tracker doesn't exist yet, so apply 020 to create
+// it, then INSERT 020's own tracker row. Caller re-queries the tracker
+// afterwards to pick up the seeded row.
+async function bootstrapTracker(client, files, applyFile, readFileImpl) {
+  const trackerPath = files.find(
+    (f) => path.basename(f) === TRACKER_FILE
+  );
+  if (!trackerPath) {
+    throw new Error(
+      `applyPendingMigrations: bundled ${TRACKER_FILE} not found in migration set — ` +
+      `the migration tracker cannot bootstrap. Re-publish the package or sync ` +
+      `the engram migrations directory into packages/server/src/setup/mnestra-migrations/.`
+    );
+  }
+  const result = await applyFile(client, trackerPath);
+  if (!result || result.ok !== true) {
+    const detail = (result && result.error) || 'apply returned not-ok with no error message';
+    throw new Error(
+      `applyPendingMigrations: failed to bootstrap tracker via ${TRACKER_FILE}: ${detail}`
+    );
+  }
+  const sql = readFileImpl(trackerPath);
+  const checksum = computeChecksum(sql);
+  await client.query(
+    `INSERT INTO ${TRACKER_TABLE} (filename, applied_at, checksum, schema_version) ` +
+    `VALUES ($1, now(), $2, $3) ` +
+    `ON CONFLICT (filename) DO UPDATE SET applied_at = EXCLUDED.applied_at, ` +
+    `checksum = EXCLUDED.checksum, schema_version = EXCLUDED.schema_version`,
+    [TRACKER_FILE, checksum, null]
+  );
+}
+
+// Run a probe SQL string and return whether the schema artifact is present.
+// Null probes always return false. Probe-side errors (e.g. relation does
+// not exist when probing into the live schema) are swallowed and degrade
+// to "absent" — same posture as audit-upgrade.js::probeOne. The artifact's
+// real apply path will surface any underlying error with full context.
+async function probePresent(client, probeSql) {
+  if (!probeSql) return false;
+  try {
+    const res = await client.query(probeSql);
+    return Array.isArray(res && res.rows) && res.rows.length > 0;
+  } catch (_err) {
+    return false;
+  }
+}
+
+// Insert a backfill row for a migration whose probe came back present on
+// a pre-020 install. applied_at is the epoch sentinel so audit queries
+// can distinguish "applied at install" from "tracked from day one." The
+// checksum is recorded too so future bundle drift can still be detected
+// against backfilled rows.
+async function recordBackfill(client, filename, checksum) {
+  await client.query(
+    `INSERT INTO ${TRACKER_TABLE} (filename, applied_at, checksum, schema_version) ` +
+    `VALUES ($1, $2::timestamptz, $3, $4) ` +
+    `ON CONFLICT (filename) DO NOTHING`,
+    [filename, '1970-01-01T00:00:00Z', checksum, 'backfill']
+  );
+}
+
+// Insert a real tracker row after a successful apply.
+async function recordApplied(client, filename, checksum) {
+  await client.query(
+    `INSERT INTO ${TRACKER_TABLE} (filename, applied_at, checksum, schema_version) ` +
+    `VALUES ($1, now(), $2, $3) ` +
+    `ON CONFLICT (filename) DO UPDATE SET applied_at = EXCLUDED.applied_at, ` +
+    `checksum = EXCLUDED.checksum, schema_version = EXCLUDED.schema_version`,
+    [filename, checksum, null]
+  );
+}
+
+async function applyPendingMigrations(client, opts = {}) {
+  if (!client || typeof client.query !== 'function') {
+    throw new Error('applyPendingMigrations: client with .query() is required');
+  }
+
+  const _migrations = opts._migrations || module.exports;
+  const _readFile = opts._readFile || ((p) => fs.readFileSync(p, 'utf-8'));
+  const _applyFile = opts._applyFile || defaultApplyFile();
+  const _probes = opts._probes || MIGRATION_PROBES;
+
+  const files = _migrations.listMnestraMigrations();
+  if (!files || files.length === 0) {
+    throw new Error(
+      'applyPendingMigrations: no Mnestra migrations bundled — TermDeck install looks corrupted.'
+    );
+  }
+
+  const summary = {
+    applied: [],
+    skipped: [],
+    backfilled: [],
+    warnings: [],
+    errored: null
+  };
+
+  // Step 1: load applied-set (or bootstrap if missing).
+  let applied = await loadAppliedSet(client);
+  let bootstrapped = false;
+  if (applied === null) {
+    // Pre-020 — apply 020 + INSERT row.
+    await bootstrapTracker(client, files, _applyFile, _readFile);
+    bootstrapped = true;
+    summary.applied.push(TRACKER_FILE);
+    applied = await loadAppliedSet(client);
+    if (applied === null) {
+      throw new Error(
+        'applyPendingMigrations: tracker still missing after bootstrap — ' +
+        'check that 020_migration_tracking.sql actually created public.mnestra_migrations.'
+      );
+    }
+  }
+
+  // Step 2: iterate bundled files in lex order.
+  for (const file of files) {
+    const base = path.basename(file);
+
+    // Tracker file: bootstrap already accounted for it in summary.applied.
+    // On a non-bootstrap pass (post-020 install where 020 is in the tracker),
+    // record as skipped. On any other state (tracker present but somehow
+    // missing 020), fall through to the normal apply path so the diff loop
+    // can re-record it.
+    if (base === TRACKER_FILE) {
+      if (bootstrapped) {
+        // Already in summary.applied via bootstrap; do not duplicate.
+        continue;
+      }
+      if (applied.has(TRACKER_FILE)) {
+        summary.skipped.push(base);
+        continue;
+      }
+      // Defensive fall-through: tracker exists (loadAppliedSet succeeded) but
+      // doesn't have 020's row. Apply path below will re-record it.
+    }
+
+    let sql;
+    try {
+      sql = _readFile(file);
+    } catch (err) {
+      summary.errored = {
+        file: base,
+        error: err && err.message ? err.message : String(err)
+      };
+      return summary;
+    }
+    const checksum = computeChecksum(sql);
+
+    if (applied.has(base)) {
+      // Already applied — checksum-drift guard.
+      const trackedChecksum = applied.get(base);
+      if (trackedChecksum && trackedChecksum !== checksum) {
+        summary.warnings.push({
+          file: base,
+          trackedChecksum,
+          bundledChecksum: checksum
+        });
+      }
+      summary.skipped.push(base);
+      continue;
+    }
+
+    // Not applied. Try probe-backfill (only meaningful on pre-020 installs
+    // that just bootstrapped, but cheap to evaluate on every pass; an
+    // already-tracked migration short-circuits above before reaching here).
+    const probeSql = Object.prototype.hasOwnProperty.call(_probes, base)
+      ? _probes[base]
+      : null;
+    if (probeSql) {
+      const present = await probePresent(client, probeSql);
+      if (present) {
+        try {
+          await recordBackfill(client, base, checksum);
+        } catch (err) {
+          summary.errored = {
+            file: base,
+            error: `backfill INSERT failed: ${err && err.message ? err.message : String(err)}`
+          };
+          return summary;
+        }
+        summary.backfilled.push(base);
+        applied.set(base, checksum);
+        continue;
+      }
+    }
+
+    // Genuinely needs apply. Self-transactional migrations (011, 012) ship
+    // top-level BEGIN/COMMIT in their bodies — see isSelfTransactional + the
+    // header comment near its definition. For those, skip the outer wrapper
+    // and rely on the file's own transaction control + idempotency for
+    // recovery on tracker INSERT failure. For everything else, wrap in
+    // outer BEGIN/COMMIT for per-file atomicity (apply + tracker row commit
+    // or roll back together).
+    const selfTx = isSelfTransactional(sql);
+
+    if (selfTx) {
+      let applyResult;
+      try {
+        applyResult = await _applyFile(client, file);
+      } catch (err) {
+        summary.errored = {
+          file: base,
+          error: err && err.message ? err.message : String(err)
+        };
+        return summary;
+      }
+      if (!applyResult || applyResult.ok !== true) {
+        summary.errored = {
+          file: base,
+          error: (applyResult && applyResult.error) || 'apply returned not-ok with no error message'
+        };
+        return summary;
+      }
+      try {
+        await recordApplied(client, base, checksum);
+      } catch (err) {
+        summary.errored = {
+          file: base,
+          error: `tracker INSERT failed (self-transactional ${base} applied; re-run will replay it idempotently and retry the tracker insert): ${err && err.message ? err.message : String(err)}`
+        };
+        return summary;
+      }
+      summary.applied.push(base);
+      applied.set(base, checksum);
+      continue;
+    }
+
+    // Non-self-transactional path: outer BEGIN/COMMIT wrapper.
+    try {
+      await client.query('BEGIN');
+    } catch (err) {
+      summary.errored = {
+        file: base,
+        error: `BEGIN failed: ${err && err.message ? err.message : String(err)}`
+      };
+      return summary;
+    }
+
+    let applyResult;
+    try {
+      applyResult = await _applyFile(client, file);
+    } catch (err) {
+      try { await client.query('ROLLBACK'); } catch (_e) { /* best-effort */ }
+      summary.errored = {
+        file: base,
+        error: err && err.message ? err.message : String(err)
+      };
+      return summary;
+    }
+
+    if (!applyResult || applyResult.ok !== true) {
+      try { await client.query('ROLLBACK'); } catch (_e) { /* best-effort */ }
+      summary.errored = {
+        file: base,
+        error: (applyResult && applyResult.error) || 'apply returned not-ok with no error message'
+      };
+      return summary;
+    }
+
+    try {
+      await recordApplied(client, base, checksum);
+      await client.query('COMMIT');
+    } catch (err) {
+      try { await client.query('ROLLBACK'); } catch (_e) { /* best-effort */ }
+      summary.errored = {
+        file: base,
+        error: `tracker INSERT failed: ${err && err.message ? err.message : String(err)}`
+      };
+      return summary;
+    }
+
+    summary.applied.push(base);
+    applied.set(base, checksum);
+  }
+
+  return summary;
+}
+
 module.exports = {
   listMnestraMigrations,
   listRumenMigrations,
   rumenFunctionsRoot,
   listRumenFunctions,
   rumenFunctionDir,
-  readFile
+  readFile,
+  // Sprint 61 T2 — migration tracker.
+  applyPendingMigrations,
+  MIGRATION_PROBES,
+  TRACKER_TABLE,
+  TRACKER_FILE,
+  // Test surface — kept exported so tests/migration-tracker.test.js can pin
+  // each helper without a live pg client.
+  _computeChecksum: computeChecksum,
+  _loadAppliedSet: loadAppliedSet,
+  _bootstrapTracker: bootstrapTracker,
+  _probePresent: probePresent,
+  _recordBackfill: recordBackfill,
+  _recordApplied: recordApplied,
+  _isSelfTransactional: isSelfTransactional
 };

package/packages/server/src/setup/mnestra-migrations/001_mnestra_tables.sql

@@ -79,8 +79,8 @@ create index if not exists memory_relationships_target_idx on memory_relationshi
 -- ── match_memories helper RPC ─────────────────────────────────────────────
 -- Used by remember.ts (dedup) and consolidate.ts (cluster seeding).
 --
--- Sprint 52.1 — signature-drift guard. On long-lived v0.6.x-era installs
--- (Joshua's petvetbid, Brad's jizzard-brain), match_memories was created by
+-- Sprint 52.1 — signature-drift guard. On long-lived v0.6.x-era installs,
+-- match_memories was created by
 -- a prior Mnestra version with a different RETURN-table column shape:
 --   (id, content, metadata, source_type, category, project, created_at, similarity)
 -- vs the canonical:

package/packages/server/src/setup/mnestra-migrations/002_mnestra_search_function.sql

@@ -16,7 +16,7 @@
 -- Sprint 51.9 — signature-drift guard. Same Class A pattern Sprint 52.1
 -- closed for `match_memories` (mig 001:81-95). Codex T4 surfaced the cousin
 -- 2026-05-04 14:42 ET during Sprint 51.5b dogfood: long-lived v0.6.x-era
--- installs (Joshua's petvetbid, likely Brad's jizzard-brain) ALSO have a
+-- installs ALSO have a
 -- 10-arg drift overload of `memory_hybrid_search` coexisting with the
 -- canonical 8-arg signature. The drift overload carries the never-shipped
 -- `recency_weight`/`decay_days` parameters from a pre-canonical Mnestra

package/packages/server/src/setup/mnestra-migrations/009_memory_relationship_metadata.sql

@@ -8,7 +8,7 @@
 --
 -- Idempotent: safe to re-run.
 --
--- Pre-existing state (verified against petvetbid 2026-04-27 17:25 ET):
+-- Pre-existing state (verified against the reference Mnestra project 2026-04-27 17:25 ET):
 --   memory_relationships has 749 live edges. The migration adds nullable
 --   columns and a wider CHECK; no existing row violates the new constraint.
 --

package/packages/server/src/setup/mnestra-migrations/011_project_tag_backfill.sql

@@ -36,7 +36,10 @@
 --     1. termdeck / mnestra      — keywords: termdeck, mnestra, "4+1 sprint"
 --     2. rumen                   — keyword:  rumen
 --     3. podium                  — keyword:  podium
---     4. pvb                     — keywords: PVB, petvetbid, pet vet bid
+--     4. pvb                     — keywords: PVB, pet vet bid (and the
+--                                   legacy single-word identifier matched
+--                                   by the load-bearing classifier on
+--                                   line 156)
 --     5. dor / openclaw          — TIGHTENED:
 --                                    word-boundary uppercase DOR  (rules out
 --                                    "dormant", "vendored", "indoor", etc.),
@@ -49,7 +52,8 @@
 --   rumen:            92 rows, all 6 sampled were true positives.
 --   podium:           58 rows, all 6 sampled were true positives.
 --   pvb:               7 rows, 1 of those overlaps with mnestra ("Mnestra
---                     repo … petvetbid project") and gets claimed by bucket 1.
+--                     repo … legacy single-word project name") and gets
+--                     claimed by bucket 1.
 --   dor (tightened):   3 rows after tightening from 6 — the original
 --                     `%dor%` ILIKE pattern caught false positives like
 --                     "dormant", "vendored". Final 3 rows are all true
@@ -143,7 +147,7 @@ BEGIN
 END $$;
 
 -- ============================================================
--- BUCKET 4 — PVB (case-insensitive PVB / petvetbid markers)
+-- BUCKET 4 — PVB (case-insensitive content markers — see code below)
 -- ============================================================
 DO $$
 DECLARE

package/packages/server/src/setup/mnestra-migrations/012_project_tag_re_taxonomy.sql

@@ -49,7 +49,7 @@
 --                              by Joshua; case-sensitive word-boundary token
 --                              avoids matching unrelated "[maestro]" log
 --                              prefixes)
---     6. pvb                 — PVB, petvetbid, "pet vet bid"
+--     6. pvb                 — PVB, "pet vet bid"
 --     7. claimguard          — claimguard, gorgias-ticket-monitor,
 --                              "gorgias ticket monitor"
 --     8. dor                 — \mDOR\M, /DOR/, ~/Documents/DOR, dor.config,
@@ -234,7 +234,7 @@ BEGIN
 END $$;
 
 -- ============================================================
--- BUCKET 6 — pvb (case-insensitive PVB / petvetbid markers)
+-- BUCKET 6 — pvb (case-insensitive content markers — see code below)
 --
 -- Same pattern as 011 bucket 4. PVB is small in the chopin-nashville bucket
 -- (Sprint 39 dry-run found 7 rows; live apply landed 3 because bucket 1

package/packages/server/src/setup/mnestra-migrations/014_explicit_grants.sql

@@ -17,9 +17,9 @@
 -- PostgREST checks table-level privileges before evaluating RLS, so
 -- service_role's bypassrls attribute does not help.
 --
--- Reported and root-caused by Brad Heath 2026-04-28 against project
--- ref rrzkceirgciiqgeefvbe; fix verified end-to-end on his install
--- before being upstreamed here.
+-- Reported and root-caused by Brad Heath 2026-04-28 against his Mnestra
+-- project; fix verified end-to-end on his install before being upstreamed
+-- here.
 --
 -- This migration is idempotent and safe on greenfield projects where
 -- the auto-grant default already fired (the GRANTs become no-ops).

package/packages/server/src/setup/mnestra-migrations/016_mnestra_doctor_probes.sql

@@ -27,8 +27,8 @@
 -- their grants are now wrapped in a do$$ guard that only emits them
 -- when `pg_cron` is enabled. The doctor's cron-related probes return
 -- the existing `unknown` band (Sprint 51.5 T2 already established it)
--- when the wrappers don't exist — graceful degradation. Petvetbid +
--- jizzard-brain are unaffected because both have rumen installed,
+-- when the wrappers don't exist — graceful degradation. Existing
+-- rumen-bearing installs are unaffected because both have rumen installed,
 -- which enables pg_cron via rumen's mig 002. Closes the
 -- mnestra-only-no-rumen fresh-install path.
 
@@ -103,7 +103,7 @@ grant execute on function mnestra_doctor_vault_secret_exists(text)        to ser
 --
 -- Idempotent: do$$ runs every replay; CREATE OR REPLACE keeps the
 -- function definitions in sync if pg_cron later gets enabled and the
--- migration re-runs. Existing installs (petvetbid, jizzard-brain) have
+-- migration re-runs. Existing installs typically have
 -- pg_cron from Rumen's install path and emit these unconditionally.
 
 do $cron_guard$

package/packages/server/src/setup/mnestra-migrations/017_memory_sessions_session_metadata.sql

@@ -3,7 +3,7 @@
 -- Sprint 51.6 T3 (TermDeck v1.0.2 hotfix wave). Brings the canonical engram
 -- memory_sessions schema in line with the rag-system writer's column set so
 -- TermDeck's bundled session-end hook can write a uniform shape on both
--- fresh-canonical installs and Joshua's daily-driver petvetbid (where the
+-- fresh-canonical installs and Joshua's daily-driver the reference Mnestra project (where the
 -- columns were already added by hand when rag-system bootstrap ran).
 --
 -- Why: until v1.0.2 the bundled hook only wrote memory_items. The actual
@@ -17,7 +17,7 @@
 -- the schema it expects exists everywhere.
 --
 -- Idempotent — safe on:
---   1. petvetbid (where these columns are already present from hand-applied
+--   1. the reference Mnestra project (where these columns are already present from hand-applied
 --      DDL Joshua ran when setting up rag-system; the IF NOT EXISTS guards
 --      no-op on every column).
 --   2. Fresh canonical installs that ran migrations 001-016 only (the canonical
@@ -26,11 +26,11 @@
 --
 -- The unique constraint on session_id is wrapped in a do-block because
 -- ADD CONSTRAINT does not support IF NOT EXISTS in PostgreSQL. Joshua's
--- petvetbid already has the constraint as memory_sessions_session_id_key
+-- the reference Mnestra project already has the constraint as memory_sessions_session_id_key
 -- (auto-named by the rag-system bootstrap); this block detects that name
 -- and skips re-adding.
 --
--- session_id is added NULLABLE on canonical installs even though petvetbid's
+-- session_id is added NULLABLE on canonical installs even though the reference Mnestra project's
 -- existing constraint is NOT NULL. Adding NOT NULL via ALTER TABLE on a
 -- table with existing rows would fail; the bundled hook always supplies
 -- session_id at write time, so nullability is non-blocking. A future sprint
@@ -56,7 +56,7 @@ alter table public.memory_sessions
 -- Unique constraint on session_id. Skip if any unique constraint on
 -- (session_id) is already in place — covers both the canonical name
 -- memory_sessions_session_id_key and any alternate name from a manual
--- ALTER TABLE Joshua may have run on petvetbid.
+-- ALTER TABLE Joshua may have run on the reference Mnestra project.
 do $$
 declare
   has_unique boolean;

package/packages/server/src/setup/mnestra-migrations/018_rumen_processed_at.sql

@@ -19,7 +19,7 @@
 --   1. Joshua's daily-driver (pre-Sprint-53; column will be added with
 --      every existing memory_sessions row at NULL → all become candidates
 --      on the first post-deploy tick, which is the desired bootstrap).
---   2. Brad's jizzard-brain (Linux SSH; same shape, same null-bootstrap).
+--   2. Linux SSH installs (same shape, same null-bootstrap).
 --   3. Fresh canonical installs (post-mig-017 schema; column added on
 --      first run, no rows to backfill).
 --   4. Re-runs (ADD COLUMN IF NOT EXISTS + CREATE INDEX IF NOT EXISTS).

package/packages/server/src/setup/mnestra-migrations/019_security_hardening.sql

@@ -0,0 +1,190 @@
+-- Mnestra v0.4.6 — security hardening (revised from 0.4.4 / 0.4.5).
+--
+-- Source: external Supabase-advisor sweep by Brad Heath / Nacho Money LLC,
+-- 2026-05-06. See docs/SECURITY-HARDENING-2026-05-06.md for the full flag
+-- and root-cause analysis. The standing rule lives in the global Claude
+-- Code instructions: "MANDATORY: Supabase RLS + privilege hygiene".
+--
+-- Two corrections folded into this revision:
+--
+--   A. **search_path must include `extensions`.** The 0.4.4/0.4.5 version of
+--      this migration set search_path = public, pg_catalog on the memory_*
+--      RPCs. Supabase >= 2024 installs pgvector in the `extensions` schema,
+--      so the `<=>` cosine-distance operator becomes unreachable from those
+--      RPCs after the alter — semantic recall fails with "operator does not
+--      exist: extensions.vector <=> extensions.vector". Confirmed live
+--      against the reference Mnestra project on 2026-05-06; fixed by
+--      including `extensions` in search_path.
+--
+--   B. **Schema-generation-aware.** Some Mnestra installs are on the older
+--      "memory_items-only" generation — they have memory_items /
+--      memory_relationships / memory_sessions + the 6 memory_* RPCs, but
+--      NOT the layered-memory tables (mnestra_session_memory,
+--      mnestra_developer_memory, mnestra_project_memory, mnestra_commands)
+--      and NOT the mnestra_doctor_* SECURITY DEFINER probes. The 0.4.4 / 0.4.5
+--      migration body assumed the layered shape and threw "relation does
+--      not exist" / "function does not exist" mid-migration on older
+--      installs. Brad caught this on three of his projects (Structural,
+--      aetheria-payroll, aetheria-phase1) and worked around with a
+--      signature-agnostic DO-block subset.
+--
+--      This revision restructures every section as defensive lookups
+--      against pg_class / pg_proc / pg_views, so each statement only fires
+--      when its target exists. The migration runs cleanly on:
+--        - layered-memory generation (Josh's reference project): full fix
+--        - memory_items-only generation (Brad's three projects): function
+--          hardening only; mnestra_*-targeting statements are skipped
+--        - mixed generation: each statement applies to whatever exists
+--
+-- Closes four hole classes (where applicable to the install's schema
+-- generation):
+--
+--   1. Permissive PUBLIC INSERT RLS on mnestra_{commands,developer_memory,
+--      project_memory,session_memory}. Created by Supabase Studio's
+--      "Allow insert for all" default-policy template at table-creation
+--      time. Anyone with the project's anon key could write directly to
+--      memory tables, poisoning the corpus or session-id-squatting.
+--
+--   2. PUBLIC EXECUTE on every Mnestra function. Postgres defaults
+--      function EXECUTE to PUBLIC; the explicit `grant ... to service_role`
+--      in earlier migrations is additive, not exclusive.
+--
+--   3. Mutable search_path on memory_* and mnestra_doctor_* functions
+--      (Supabase lint 0011).
+--
+--   4. mnestra_recent_activity SECURITY DEFINER view (Supabase lint 0010)
+--      with anon+authenticated SELECT.
+--
+-- Backward-compat: zero behavior change for any Mnestra installation that
+-- follows the documented architecture (service-role writes via MCP server).
+-- service_role keeps EXECUTE on every function and SELECT on the view.
+--
+-- Idempotent: every section guards on object existence and uses
+-- IF EXISTS / signature-agnostic patterns. Re-running this migration is
+-- safe and is in fact the recommended way to upgrade a 0.4.4/0.4.5 install
+-- to pick up the search_path fix.
+
+-- ====================================================================
+-- 1. Drop permissive PUBLIC INSERT policies on mnestra_* tables, when
+--    those tables exist on this install. Skipped silently on older
+--    memory_items-only schema generation.
+-- ====================================================================
+
+do $$
+declare
+  tbl text;
+  tables text[] := array[
+    'mnestra_commands',
+    'mnestra_developer_memory',
+    'mnestra_project_memory',
+    'mnestra_session_memory'
+  ];
+begin
+  foreach tbl in array tables loop
+    if to_regclass(format('public.%I', tbl)) is not null then
+      execute format('drop policy if exists "Allow insert for all" on public.%I', tbl);
+    end if;
+  end loop;
+end $$;
+
+-- ====================================================================
+-- 2 + 3. Revoke EXECUTE from public + anon + authenticated AND pin
+-- search_path on every Mnestra function. Signature-agnostic — iterates
+-- pg_proc to apply to whatever functions exist on this install. Covers
+-- memory_*, match_memories, expand_memory_neighborhood, and
+-- mnestra_doctor_*.
+--
+-- search_path includes `extensions` for the pgvector operator and
+-- pg_catalog for built-ins; doctor functions don't use vectors but the
+-- inclusion is harmless and keeps every Mnestra function uniform.
+-- ====================================================================
+
+do $$
+declare
+  fn record;
+  sig text;
+begin
+  for fn in
+    select n.nspname,
+           p.proname,
+           pg_get_function_identity_arguments(p.oid) as ident_args
+      from pg_proc p
+      join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = 'public'
+       and p.prokind = 'f'
+       and (
+         p.proname like 'memory_%'
+         or p.proname in ('match_memories', 'expand_memory_neighborhood')
+         or p.proname like 'mnestra_doctor_%'
+       )
+  loop
+    sig := format('%I.%I(%s)', fn.nspname, fn.proname, fn.ident_args);
+    execute format('revoke execute on function %s from public, anon, authenticated', sig);
+    execute format('alter function %s set search_path = public, extensions, pg_catalog', sig);
+    -- service_role keeps EXECUTE; the revoke above only targets public/anon/authenticated.
+  end loop;
+end $$;
+
+-- ====================================================================
+-- 4. Recreate mnestra_recent_activity view without SECURITY DEFINER and
+-- restrict SELECT to service_role. Skipped silently if the view doesn't
+-- exist or any of the three underlying tables are missing.
+-- ====================================================================
+
+do $$
+begin
+  if to_regclass('public.mnestra_session_memory') is not null
+     and to_regclass('public.mnestra_project_memory') is not null
+     and to_regclass('public.mnestra_developer_memory') is not null
+  then
+    drop view if exists public.mnestra_recent_activity;
+
+    execute $view$
+      create view public.mnestra_recent_activity as
+        select 'session'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_session_memory
+        union all
+        select 'project'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_project_memory
+        union all
+        select 'developer'::text as layer, id, session_id, event_type, payload, project, developer_id, "timestamp", created_at from public.mnestra_developer_memory
+        order by 8 desc
+        limit 100
+    $view$;
+
+    revoke all on public.mnestra_recent_activity from public, anon, authenticated;
+    grant select on public.mnestra_recent_activity to service_role;
+  end if;
+end $$;
+
+-- ====================================================================
+-- Post-apply verification (run separately in Studio SQL editor):
+--
+--   -- Should return zero rows:
+--   with bad_policies as (
+--     select policyname from pg_policies
+--      where schemaname='public' and tablename like 'mnestra_%'
+--        and ('public' = any(roles) or roles = '{}')
+--        and (with_check='true' or qual='true')
+--   ),
+--   public_exec as (
+--     select p.proname from pg_proc p join pg_namespace n on n.oid=p.pronamespace
+--      where n.nspname='public'
+--        and (p.proname like 'mnestra_doctor_%' or p.proname like 'memory_%'
+--             or p.proname in ('match_memories','expand_memory_neighborhood'))
+--        and has_function_privilege('public', p.oid, 'EXECUTE')
+--   ),
+--   mutable_path as (
+--     select p.proname from pg_proc p join pg_namespace n on n.oid=p.pronamespace
+--      where n.nspname='public' and p.prokind='f'
+--        and (p.proname like 'memory_%' or p.proname like 'mnestra_doctor_%')
+--        and not exists (
+--          select 1 from unnest(coalesce(p.proconfig,'{}'::text[])) c
+--          where c like 'search_path=%'
+--        )
+--   )
+--   select 'BAD_POLICY' as kind, policyname as detail from bad_policies
+--   union all select 'PUBLIC_EXEC', proname from public_exec
+--   union all select 'MUTABLE_SEARCH_PATH', proname from mutable_path;
+--
+-- Verified zero rows on the reference Mnestra project on 2026-05-06.
+-- Smoke test: select count(*) from memory_hybrid_search('smoke', array_fill(0::real, ARRAY[1536])::vector, 1) → 1 row, no operator-resolution error.
+-- ====================================================================

package/packages/server/src/setup/mnestra-migrations/020_migration_tracking.sql

@@ -0,0 +1,57 @@
+-- 020_migration_tracking.sql
+-- Adds durable tracking of which Mnestra migrations have been applied to a project,
+-- so upgrade paths can compute (bundled - applied) and apply only the diff.
+-- Sprint 61 (TermDeck Convergence Keystone), Mnestra 0.4.7.
+--
+-- Why this exists: prior to 020, the mnestra/rumen wizards re-applied every
+-- bundled migration on every invocation, relying on per-migration
+-- `IF NOT EXISTS` / `CREATE OR REPLACE` idempotency to avoid duplicate work.
+-- That works for a fresh install but doesn't tell the wizard which migrations
+-- the live database is missing — so a user running `npm install -g @latest`
+-- against an existing project gets the new package files without any way to
+-- detect schema drift. Class A (schema drift on package upgrade) per
+-- termdeck/docs/INSTALLER-PITFALLS.md.
+--
+-- Shape:
+--   - `filename`        text PK — the bundled migration filename, e.g.
+--                                 `015_source_agent.sql`. PK because each
+--                                 bundled file applies at most once.
+--   - `applied_at`      timestamptz — wall-clock time of apply. Backfilled
+--                                 rows (rows seeded by the post-020 backfill
+--                                 probe for migrations applied pre-020) use
+--                                 epoch (1970-01-01T00:00:00Z) as a sentinel.
+--   - `checksum`        text — SHA-256 of the bundled file content at apply
+--                                 time. Lets future runs detect bundle drift
+--                                 without auto-overwriting the live schema.
+--   - `schema_version`  text — optional free-text marker. Backfill rows use
+--                                 the literal `'backfill'` so audit queries
+--                                 can distinguish them.
+--
+-- RLS posture: ENABLE ROW LEVEL SECURITY + REVOKE ALL FROM PUBLIC. No
+-- policies are intentional — anon and authenticated have NO access, full
+-- stop. service_role bypasses RLS in Postgres by default, which is the only
+-- caller that should ever touch this table (the migration runner connects
+-- via DATABASE_URL using service-role credentials).
+--
+-- Idempotent: re-applying this migration on a project that already has the
+-- table is a no-op (CREATE TABLE IF NOT EXISTS, ALTER TABLE ... ENABLE RLS
+-- is a no-op when already enabled, REVOKE/GRANT are idempotent).
+
+CREATE TABLE IF NOT EXISTS public.mnestra_migrations (
+  filename       text PRIMARY KEY,
+  applied_at     timestamptz NOT NULL DEFAULT now(),
+  checksum       text NOT NULL,
+  schema_version text
+);
+
+ALTER TABLE public.mnestra_migrations ENABLE ROW LEVEL SECURITY;
+
+-- Service-role-only. anon and authenticated have NO access (no policies = denied by RLS).
+-- Service role bypasses RLS by default; the table is queried only by the migration runner
+-- which uses the service-role key.
+
+REVOKE ALL ON public.mnestra_migrations FROM PUBLIC;
+GRANT  ALL ON public.mnestra_migrations TO service_role;
+
+COMMENT ON TABLE public.mnestra_migrations IS
+  'Tracking table for applied Mnestra migrations. service_role-only; RLS-on; no policies.';

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

@@ -52,40 +52,10 @@ serve(async (_req: Request) => {
 
   const pool = createPoolFromUrl(url);
 
-  // Sprint 56 (T3 Cell #1 backlog catch-up) — env-var overrides for one-off
-  // historic processing. Set via `supabase secrets set`:
-  //   RUMEN_LOOKBACK_HOURS_OVERRIDE=2880   (120 days; bypasses default 72h)
-  //   RUMEN_MAX_SESSIONS_OVERRIDE=300      (processes whole 289-session
-  //                                         backlog in one tick rather than
-  //                                         28 ticks at default 10 each)
-  // After the catch-up settles, unset both with
-  //   `supabase secrets unset RUMEN_LOOKBACK_HOURS_OVERRIDE
-  //                           RUMEN_MAX_SESSIONS_OVERRIDE`
-  // and the function reverts to the rumen-package defaults (72h / 10 sessions).
-  // Both gates fail closed: invalid integer string → ignored, default used.
-  const lookbackOverrideRaw = Deno.env.get('RUMEN_LOOKBACK_HOURS_OVERRIDE');
-  const maxSessionsOverrideRaw = Deno.env.get('RUMEN_MAX_SESSIONS_OVERRIDE');
-  const lookbackOverride = lookbackOverrideRaw && /^\d+$/.test(lookbackOverrideRaw)
-    ? parseInt(lookbackOverrideRaw, 10)
-    : undefined;
-  const maxSessionsOverride = maxSessionsOverrideRaw && /^\d+$/.test(maxSessionsOverrideRaw)
-    ? parseInt(maxSessionsOverrideRaw, 10)
-    : undefined;
-  if (lookbackOverride !== undefined || maxSessionsOverride !== undefined) {
-    console.log(
-      '[rumen] override active: lookbackHours=' +
-        (lookbackOverride ?? 'default') +
-        ' maxSessions=' +
-        (maxSessionsOverride ?? 'default'),
-    );
-  }
-
   try {
     console.log('[rumen] edge function tick starting');
     const summary = await runRumenJob(pool, {
       triggeredBy: 'schedule',
-      ...(lookbackOverride !== undefined ? { lookbackHours: lookbackOverride } : {}),
-      ...(maxSessionsOverride !== undefined ? { maxSessions: maxSessionsOverride } : {}),
     });
     console.log(
       '[rumen] edge function tick complete job_id=' +