@jhizzard/termdeck 0.6.5 → 0.6.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.6.5",
+  "version": "0.6.9",
   "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

@@ -43,7 +43,8 @@ const {
   yaml,
   supabaseUrl: urlHelper,
   migrations,
-  pgRunner
+  pgRunner,
+  preconditions
 } = require(SETUP_DIR);
 
 const HELP = [
@@ -385,12 +386,24 @@ async function verifyStatus(client) {
 // on disk first; config.yaml only flips to rag.enabled=true once the
 // schema is actually in place.
 function writeSecretsFile(inputs, dryRun) {
+  // Normalize transaction-pooler URLs by appending pgbouncer=true&
+  // connection_limit=1 when missing. Brad's Rumen logs (2026-04-26)
+  // surfaced the warning Supabase recommends: transaction-mode pooling
+  // (port 6543) needs those params or PgBouncer can return prepared-
+  // statement errors under load. Direct connections and session-mode
+  // pooler URLs are returned unchanged. See setup/supabase-url.js.
+  const normalized = urlHelper.normalizeDatabaseUrl(inputs.databaseUrl);
+  if (normalized.modified) {
+    step('Detected transaction pooler URL — appending ?pgbouncer=true&connection_limit=1...');
+    ok();
+  }
+
   step('Writing ~/.termdeck/secrets.env...');
   if (dryRun) { ok('(dry-run)'); return; }
   dotenv.writeSecrets({
     SUPABASE_URL: inputs.projectUrl.url,
     SUPABASE_SERVICE_ROLE_KEY: inputs.serviceRoleKey,
-    DATABASE_URL: inputs.databaseUrl,
+    DATABASE_URL: normalized.url,
     OPENAI_API_KEY: inputs.openaiKey,
     ...(inputs.anthropicKey ? { ANTHROPIC_API_KEY: inputs.anthropicKey } : {})
   });
@@ -502,7 +515,19 @@ async function main(argv) {
     await checkExistingStore(client);
     await applyMigrations(client, false);
     writeYamlConfig(false);
+    // v0.6.9: post-write outcome verification. Confirms each migration's
+    // expected schema bits actually landed — including memory_items.
+    // source_session_id (the v0.6.5 column whose absence cascaded into
+    // Brad's Rumen failures). This is the test that, if it had existed
+    // before v0.6.5, would have caught the silent-shadow saga at install
+    // time instead of cron-tick time.
     if (!flags.skipVerify) {
+      const verify = await preconditions.verifyMnestraOutcomes({ secrets: { DATABASE_URL: inputs.databaseUrl }, _pgClient: client });
+      preconditions.printVerifyReport(verify, 'mnestra');
+      if (!verify.ok) {
+        printResumeHint();
+        return 8;
+      }
       const verified = await verifyStatus(client);
       if (!verified) {
         process.stdout.write(

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

@@ -34,7 +34,8 @@ const {
   dotenv,
   supabaseUrl: urlHelper,
   migrations,
-  pgRunner
+  pgRunner,
+  preconditions
 } = require(SETUP_DIR);
 
 // Pinned fallback used only when the npm registry is unreachable. Bump this
@@ -166,6 +167,20 @@ function preflight() {
   }
   ok();
 
+  // Normalize DATABASE_URL for transaction-pooler usage (v0.6.6+). Users
+  // whose ~/.termdeck/secrets.env was written by an earlier wizard version
+  // may have a Shared Pooler URL without ?pgbouncer=true. The Edge Function
+  // logs a warning when that's the case (Brad's 2026-04-26 report). Fix it
+  // here in-memory before forwarding to `supabase secrets set` so the
+  // Function gets a clean URL even on partial-upgrade installs. Direct
+  // connections and session-mode pooler URLs are returned unchanged.
+  const normalized = urlHelper.normalizeDatabaseUrl(secrets.DATABASE_URL);
+  if (normalized.modified) {
+    step('Detected transaction pooler URL — appending ?pgbouncer=true&connection_limit=1 for the Edge Function...');
+    secrets.DATABASE_URL = normalized.url;
+    ok();
+  }
+
   // OPENAI_API_KEY is optional: when present, Rumen's Relate phase generates
   // real embeddings for semantic+keyword hybrid search. When absent, Rumen
   // falls back to keyword-only matching (still works, but loses cross-project
@@ -455,6 +470,78 @@ async function applySchedule(projectRef, secrets, dryRun) {
   }
 }
 
+// Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json's Supabase MCP
+// server entry. Background: the meta-installer (`@jhizzard/termdeck-stack`)
+// writes `SUPABASE_ACCESS_TOKEN: 'SUPABASE_PAT_HERE'` as a literal
+// placeholder when it wires the Supabase MCP entry. The user is expected
+// to replace it after install. v0.6.4 unblocked the Rumen install path by
+// telling users to `export SUPABASE_ACCESS_TOKEN=sbp_...` in their shell —
+// but that token only got used for `supabase link`, never propagated into
+// `~/.claude/mcp.json`. So Brad's Claude Code was talking to a Supabase
+// MCP server with a placeholder token. He had to update the JSON file
+// manually. Reported 2026-04-26 — Brad's quote: "the token hadn't been
+// written to the Json file which we updated manually, but you may want
+// to put that in the patch at some point."
+//
+// This helper closes the loop. Idempotent and conservative:
+//   - Only runs if process.env.SUPABASE_ACCESS_TOKEN is set
+//   - Only updates when the existing value is the literal placeholder
+//     'SUPABASE_PAT_HERE' — preserves any real token the user already set
+//   - No-op when ~/.claude/mcp.json doesn't exist (user never ran the
+//     meta-installer's Tier 4) or when there's no `supabase` MCP entry
+//   - No-op (with a soft warning) when the JSON is malformed
+//   - Atomic write via tmp-and-rename; mode 0600 to match the file's
+//     existing permissions (it already holds the placeholder)
+//   - All other mcpServers entries preserved verbatim
+//
+// Returns one of: { status: 'updated', path }, { status: 'already-set', path },
+//   { status: 'no-file' }, { status: 'no-supabase-entry', path },
+//   { status: 'no-token-in-env' }, { status: 'malformed', path, error }.
+function wireAccessTokenInMcpJson({ token, mcpJsonPath, _testFs } = {}) {
+  const fsImpl = _testFs || fs;
+  const tokenValue = token || process.env.SUPABASE_ACCESS_TOKEN;
+  if (!tokenValue) return { status: 'no-token-in-env' };
+
+  const targetPath = mcpJsonPath || path.join(os.homedir(), '.claude', 'mcp.json');
+  if (!fsImpl.existsSync(targetPath)) return { status: 'no-file' };
+
+  let raw;
+  try {
+    raw = fsImpl.readFileSync(targetPath, 'utf-8');
+  } catch (err) {
+    return { status: 'malformed', path: targetPath, error: err.message };
+  }
+
+  let cfg;
+  try {
+    cfg = JSON.parse(raw);
+  } catch (err) {
+    return { status: 'malformed', path: targetPath, error: err.message };
+  }
+
+  const supabaseEntry = cfg && cfg.mcpServers && cfg.mcpServers.supabase;
+  if (!supabaseEntry || typeof supabaseEntry !== 'object') {
+    return { status: 'no-supabase-entry', path: targetPath };
+  }
+
+  supabaseEntry.env = supabaseEntry.env || {};
+  const current = supabaseEntry.env.SUPABASE_ACCESS_TOKEN;
+  if (current === tokenValue) return { status: 'already-set', path: targetPath };
+  if (current && current !== 'SUPABASE_PAT_HERE') {
+    // User has set a real token already — don't touch it.
+    return { status: 'already-set', path: targetPath };
+  }
+
+  supabaseEntry.env.SUPABASE_ACCESS_TOKEN = tokenValue;
+
+  const tmpPath = `${targetPath}.tmp.${process.pid}`;
+  fsImpl.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  fsImpl.renameSync(tmpPath, targetPath);
+  try { fsImpl.chmodSync(targetPath, 0o600); } catch (_e) { /* best-effort */ }
+
+  return { status: 'updated', path: targetPath };
+}
+
 function printNextSteps(projectRef) {
   const functionUrl = `https://${projectRef}.supabase.co/functions/v1/rumen-tick`;
   const now = new Date();
@@ -507,7 +594,39 @@ async function main(argv) {
     }
   }
 
+  // v0.6.9: front-loaded precondition audit. Runs BEFORE link so we don't
+  // create state (function deploy, function secrets, schedule SQL) that the
+  // user would have to manually clean up if a precondition is missing. Every
+  // gap is reported in one pass with actionable hints. The audit class — env
+  // tokens, pg extensions, Vault secret — covers the v0.6.4 / v0.6.6 / v0.6.7
+  // / v0.6.9-equivalent failure modes that previously surfaced one-per-patch.
+  if (!flags.dryRun) {
+    const audit = await preconditions.auditRumenPreconditions({ secrets, env: process.env });
+    preconditions.printAuditReport(audit, 'rumen');
+    if (!audit.ok) return 10;
+  }
+
   if (!(await link(projectRef, flags.dryRun))) return 4;
+
+  // Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json now that
+  // `supabase link` succeeded (the token is verified-real). The
+  // meta-installer wrote a literal 'SUPABASE_PAT_HERE' placeholder
+  // there during Tier 4 install — this closes that loop.
+  if (!flags.dryRun) {
+    const r = wireAccessTokenInMcpJson();
+    if (r.status === 'updated') {
+      step('Backfilled SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json...');
+      ok();
+    } else if (r.status === 'malformed') {
+      process.stderr.write(
+        `\n  ! ${r.path} is not valid JSON — skipping token backfill (${r.error}).\n` +
+        `    Update the supabase mcpServers entry manually if Claude Code's Supabase MCP is misbehaving.\n\n`
+      );
+    }
+    // Other statuses (no-file, no-supabase-entry, no-token-in-env,
+    // already-set) are silent — they're all expected paths.
+  }
+
   if (!(await applyRumenTables(secrets, flags.dryRun))) return 5;
 
   step('Resolving @jhizzard/rumen version from npm registry...');
@@ -524,6 +643,15 @@ async function main(argv) {
   if (!(await testFunction(projectRef, secrets, flags.dryRun))) return 8;
   if (!flags.skipSchedule) {
     if (!(await applySchedule(projectRef, secrets, flags.dryRun))) return 9;
+    // v0.6.9: post-write outcome verification. Confirms cron.job has the
+    // active rumen-tick row. Doesn't poll for the first 15-min tick — that's
+    // too long for an interactive wizard — but tells the user the exact
+    // query to run after waiting if they want firing-confirmation.
+    if (!flags.dryRun) {
+      const verify = await preconditions.verifyRumenOutcomes({ secrets });
+      preconditions.printVerifyReport(verify, 'rumen');
+      if (!verify.ok) return 11;
+    }
   } else {
     process.stdout.write('→ Skipping pg_cron schedule (per --skip-schedule) ✓\n');
   }
@@ -545,3 +673,4 @@ module.exports = main;
 // Test surface — kept on the same export object so the regression suite can
 // pin the access-token detection without spawning a real `supabase` binary.
 module.exports._looksLikeMissingAccessToken = looksLikeMissingAccessToken;
+module.exports._wireAccessTokenInMcpJson = wireAccessTokenInMcpJson;

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

@@ -11,5 +11,6 @@ module.exports = {
   supabaseUrl: require('./supabase-url'),
   migrations: require('./migrations'),
   pgRunner: require('./pg-runner'),
-  migrationRunner: require('./migration-runner')
+  migrationRunner: require('./migration-runner'),
+  preconditions: require('./preconditions')
 };

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

@@ -1,16 +1,28 @@
 // Discover the SQL migration files that ship bundled inside the TermDeck
-// package. Both init wizards call this — init-mnestra for the six Mnestra
+// package. Both init wizards call this — init-mnestra for the seven Mnestra
 // migrations, init-rumen for the two Rumen migrations.
 //
 // The wizards intentionally do NOT fall back to a sibling `../../mnestra`
-// working copy. Resolution order:
+// working copy. Resolution order (BUNDLED FIRST as of v0.6.8):
 //
 //   1. Files bundled at `packages/server/src/setup/mnestra-migrations/*.sql`
 //      (this directory is covered by the root package.json `files` glob).
+//      ALWAYS preferred when it has any .sql files.
 //   2. Files at `node_modules/@jhizzard/mnestra/migrations/*.sql` if that
-//      package is installed alongside TermDeck (future-proof path — shipping
-//      `@jhizzard/mnestra` as an optional peer would let us drop the bundled
-//      copy).
+//      package is installed alongside TermDeck. Used ONLY as a fallback when
+//      the bundled directory is missing (e.g. someone deleted it manually).
+//
+// Why bundled-first: the meta-installer (`@jhizzard/termdeck-stack`) installs
+// `@jhizzard/mnestra` globally as a peer. When TermDeck releases a new
+// migration ahead of a Mnestra release, or when a user upgrades TermDeck
+// without also upgrading the global Mnestra package, the previous loader
+// silently picked the older Mnestra migration set. This bit Brad on
+// 2026-04-26 with v0.6.5: he upgraded TermDeck, ran `init --mnestra --yes`,
+// the wizard reported "6 migrations applied cleanly" (because his global
+// mnestra@0.2.1 had only 6), and the bundled 007 — the one we shipped to
+// fix his Rumen schema-drift issue — was never seen. Bundled is the source
+// of truth TermDeck developed and tested against. Fall-back to node_modules
+// is preserved as a safety valve, not a preference.
 
 const fs = require('fs');
 const path = require('path');
@@ -45,15 +57,20 @@ function tryNodeModules(packageName, migrationSubdir = 'migrations') {
 }
 
 function listMnestraMigrations() {
-  const fromNm = tryNodeModules('@jhizzard/mnestra');
-  if (fromNm.length > 0) return fromNm;
-  return listBundled('mnestra-migrations');
+  // Bundled FIRST (v0.6.8+). See the file header for why — this prevents
+  // a stale `@jhizzard/mnestra` install in global node_modules from
+  // silently shadowing migrations TermDeck ships with the latest version.
+  const bundled = listBundled('mnestra-migrations');
+  if (bundled.length > 0) return bundled;
+  return tryNodeModules('@jhizzard/mnestra');
 }
 
 function listRumenMigrations() {
-  const fromNm = tryNodeModules('@jhizzard/rumen');
-  if (fromNm.length > 0) return fromNm;
-  return listBundled(path.join('rumen', 'migrations'));
+  // Bundled FIRST (v0.6.8+). Same rationale as listMnestraMigrations —
+  // a stale global `@jhizzard/rumen` cannot shadow newer bundled migrations.
+  const bundled = listBundled(path.join('rumen', 'migrations'));
+  if (bundled.length > 0) return bundled;
+  return tryNodeModules('@jhizzard/rumen');
 }
 
 function rumenFunctionDir() {

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

@@ -0,0 +1,370 @@
+// Front-loaded precondition audits and post-write outcome verifications for
+// the `termdeck init --mnestra` and `termdeck init --rumen` wizards.
+//
+// Why this module exists (v0.6.9)
+// ───────────────────────────────
+// The v0.6.x lineage shipped 8 patch releases in 48 hours. Four of them —
+// v0.6.4 (SUPABASE_ACCESS_TOKEN), v0.6.6 (pgbouncer params), v0.6.7
+// (mcp.json placeholder), and what would have been v0.6.9 (pg_cron +
+// pg_net extensions, Vault secret) — were the SAME failure mode: a
+// precondition was DOCUMENTED in GETTING-STARTED.md or a migration-file
+// header but not VERIFIED in code. Each unsupervised user (Brad) hit
+// them sequentially because there was no audit step at the start of the
+// wizard. Documentation is not verification.
+//
+// Shape of the defense
+// ────────────────────
+// `auditRumenPreconditions()` runs FIRST in init-rumen, before any
+// state-changing operation. It collects EVERY external precondition gap
+// in a single pass — supabase CLI auth, pg_cron + pg_net extensions,
+// Vault secret presence — and returns a structured `{ ok, gaps[] }`.
+// Callers that see `ok=false` print the gaps with actionable hints and
+// refuse to proceed. No partial work, no half-applied state.
+//
+// `verifyRumenOutcomes()` runs LAST after the schedule SQL applies. It
+// confirms `cron.job` has an active rumen-tick row. Doesn't poll for the
+// first 15-min tick (too long for an interactive wizard) — but tells the
+// user the exact query to run after waiting if they want to confirm
+// firing.
+//
+// `verifyMnestraOutcomes()` runs after migrations apply and confirms
+// the column we shipped in v0.6.5 (`source_session_id`) actually landed.
+// This is the test that — if it had existed — would have caught Brad's
+// v0.6.5/v0.6.8 saga at install time instead of pg_cron-tick time.
+//
+// All async, all defensive: any unexpected error is captured into a gap
+// rather than thrown, so the audit always returns a complete picture.
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const pgRunner = require('./pg-runner');
+
+// Render a single gap into 2-3 lines of CLI output (one indented hint per
+// non-empty `hint` line). Format aligned with the rest of the wizard's
+// step lines.
+function printGap(gap, index) {
+  process.stdout.write(`  ${index + 1}. ✗ ${gap.message}\n`);
+  if (gap.hint) {
+    for (const line of gap.hint.split('\n')) {
+      if (line.trim().length > 0) {
+        process.stdout.write(`     ${line}\n`);
+      }
+    }
+  }
+  process.stdout.write('\n');
+}
+
+// Print the audit report. Returns no value — the caller decides what to
+// do with `result.ok`.
+function printAuditReport(result, context) {
+  if (result.ok) {
+    process.stdout.write(`→ Auditing ${context} preconditions... ✓\n`);
+    return;
+  }
+  process.stdout.write(`\n→ Auditing ${context} preconditions... ✗\n\n`);
+  process.stdout.write(`${result.gaps.length} precondition${result.gaps.length === 1 ? '' : 's'} failed:\n\n`);
+  result.gaps.forEach((g, i) => printGap(g, i));
+  process.stdout.write(
+    `Fix the items above and re-run \`termdeck init --${context}\`. The wizard ` +
+    `will not proceed; it would create state you'd have to manually clean up.\n\n`
+  );
+}
+
+// Same structure for outcome verification — same { ok, gaps[] } shape so
+// callers don't branch on which kind of report they're handling.
+function printVerifyReport(result, context) {
+  if (result.ok) {
+    process.stdout.write(`→ Verifying ${context} outcomes... ✓\n`);
+    return;
+  }
+  process.stdout.write(`\n→ Verifying ${context} outcomes... ✗\n\n`);
+  process.stdout.write(`${result.gaps.length} expected outcome${result.gaps.length === 1 ? '' : 's'} not found:\n\n`);
+  result.gaps.forEach((g, i) => printGap(g, i));
+}
+
+// ── Rumen precondition audit ────────────────────────────────────────────────
+
+// Probe the supabase CLI's auth state without running `link`. If the user
+// has run `supabase login` previously, `supabase projects list` succeeds.
+// If they have SUPABASE_ACCESS_TOKEN in env, same. If neither, this exits
+// non-zero and we surface the gap.
+function probeSupabaseAuth() {
+  // Cheap, network-bound, ~1-2s. Capture both streams so we can inspect
+  // for the "Access token not provided" signal.
+  const r = spawnSync('supabase', ['projects', 'list', '--output', 'env'], {
+    encoding: 'utf-8',
+    timeout: 15000
+  });
+  return { ok: r.status === 0, stderr: r.stderr || '' };
+}
+
+// Run all Rumen preconditions in parallel where independent. Returns
+// `{ ok: boolean, gaps: [{ key, message, hint }] }`.
+//
+// Inputs:
+//   - secrets: dotenv-loaded ~/.termdeck/secrets.env (must have DATABASE_URL)
+//   - env: process.env or test fixture
+//
+// Optional `_pgClient` injection lets tests substitute a fake client; in
+// production we open one and close it at the end of the audit.
+async function auditRumenPreconditions({ secrets, env, _pgClient } = {}) {
+  const gaps = [];
+
+  // 1. Supabase CLI auth — sync; doesn't need pg.
+  if (!env || !env.SUPABASE_ACCESS_TOKEN) {
+    const probe = probeSupabaseAuth();
+    if (!probe.ok) {
+      gaps.push({
+        key: 'SUPABASE_ACCESS_TOKEN',
+        message: 'Supabase CLI is not authenticated and no SUPABASE_ACCESS_TOKEN in environment',
+        hint:
+          'Generate a Personal Access Token:\n' +
+          '  https://supabase.com/dashboard/account/tokens\n' +
+          'Then export it in this shell:\n' +
+          '  export SUPABASE_ACCESS_TOKEN=sbp_...\n' +
+          '(`supabase login` works on desktops but opens a browser; not viable over SSH.)'
+      });
+    }
+  }
+
+  // 2-4. DB-side checks — open one connection, run them sequentially,
+  //      close it at the end. Errors get captured per-check so a single
+  //      flaky query doesn't blank the whole audit.
+  const client = _pgClient || (await safeConnect(secrets && secrets.DATABASE_URL));
+  if (!client) {
+    gaps.push({
+      key: 'DATABASE_URL',
+      message: 'Could not connect to Postgres using DATABASE_URL from ~/.termdeck/secrets.env',
+      hint:
+        'Verify the URL is reachable from this host:\n' +
+        '  psql "$DATABASE_URL" -c "SELECT 1;"\n' +
+        'If the connection is fine but you see another error, copy the wizard output and report it.'
+    });
+    return { ok: gaps.length === 0, gaps };
+  }
+
+  try {
+    // pg_cron extension
+    const cron = await safeQuery(client,
+      "SELECT 1 AS ok FROM pg_extension WHERE extname = 'pg_cron'");
+    if (!cron.ok) {
+      gaps.push({
+        key: 'pg_cron',
+        message: 'The pg_cron extension is not enabled on this Supabase project',
+        hint:
+          'Enable it in the Supabase dashboard:\n' +
+          '  Database → Extensions → pg_cron → toggle ON\n' +
+          '(Without pg_cron, the rumen-tick schedule cannot run.)'
+      });
+    }
+
+    // pg_net extension
+    const net = await safeQuery(client,
+      "SELECT 1 AS ok FROM pg_extension WHERE extname = 'pg_net'");
+    if (!net.ok) {
+      gaps.push({
+        key: 'pg_net',
+        message: 'The pg_net extension is not enabled on this Supabase project',
+        hint:
+          'Enable it in the Supabase dashboard:\n' +
+          '  Database → Extensions → pg_net → toggle ON\n' +
+          '(pg_net is what the cron schedule uses to call the Edge Function.)'
+      });
+    }
+
+    // Vault secret rumen_service_role_key — accessing vault.decrypted_secrets
+    // requires service_role privileges. Distinguish "no row" from "permission
+    // denied" so the hint is actionable.
+    const vault = await safeQuery(client,
+      "SELECT 1 AS ok FROM vault.decrypted_secrets WHERE name = 'rumen_service_role_key'");
+    if (vault.error) {
+      gaps.push({
+        key: 'vault.decrypted_secrets',
+        message: `Cannot read vault.decrypted_secrets: ${vault.error}`,
+        hint:
+          'Verify your DATABASE_URL is using the service_role connection (port 6543 + service_role auth).\n' +
+          'If permission is denied, the Vault is not accessible to this connection — double-check secrets.env.'
+      });
+    } else if (!vault.ok) {
+      gaps.push({
+        key: 'rumen_service_role_key',
+        message: 'Vault secret "rumen_service_role_key" is missing',
+        hint:
+          'Create it in the Supabase dashboard:\n' +
+          '  Project Settings → Vault → New secret\n' +
+          '  Name: rumen_service_role_key  (exact, case-sensitive)\n' +
+          '  Value: your service_role key from Project Settings → API\n' +
+          '(The pg_cron schedule calls the Edge Function with this key as the bearer token.)'
+      });
+    }
+  } finally {
+    if (!_pgClient) {
+      try { await client.end(); } catch (_e) { /* ignore */ }
+    }
+  }
+
+  return { ok: gaps.length === 0, gaps };
+}
+
+// ── Rumen outcome verification ──────────────────────────────────────────────
+//
+// Runs after the pg_cron schedule SQL applies. Confirms the row is in
+// cron.job and active. Doesn't wait for first run (15 min is too long
+// to block an interactive wizard) — instead tells the user the query to
+// run after waiting if they want firing-confirmation.
+
+async function verifyRumenOutcomes({ secrets, _pgClient } = {}) {
+  const gaps = [];
+  const client = _pgClient || (await safeConnect(secrets && secrets.DATABASE_URL));
+  if (!client) {
+    gaps.push({
+      key: 'DATABASE_URL',
+      message: 'Could not reconnect to Postgres to verify the schedule landed',
+      hint: 'Re-run `termdeck init --rumen` once connectivity is restored.'
+    });
+    return { ok: false, gaps };
+  }
+
+  try {
+    const job = await safeQuery(client,
+      "SELECT active FROM cron.job WHERE jobname = 'rumen-tick'",
+      { wantRows: true });
+    if (job.error) {
+      gaps.push({
+        key: 'cron.job',
+        message: `Cannot read cron.job: ${job.error}`,
+        hint: 'pg_cron may have been disabled after the schedule was applied. Re-enable it and re-run the wizard.'
+      });
+    } else if (!job.rows || job.rows.length === 0) {
+      gaps.push({
+        key: 'cron.job',
+        message: 'Schedule was applied but cron.job has no rumen-tick row',
+        hint:
+          'This usually means the SELECT cron.schedule(...) call returned NULL. Re-run `termdeck init --rumen` ' +
+          'or apply migrations/002_pg_cron_schedule.sql manually to investigate.'
+      });
+    } else if (!job.rows[0].active) {
+      gaps.push({
+        key: 'cron.job.active',
+        message: 'rumen-tick exists but is paused (active=false)',
+        hint:
+          'Resume it with:\n' +
+          "  SELECT cron.alter_job((SELECT jobid FROM cron.job WHERE jobname = 'rumen-tick'), active := true);"
+      });
+    }
+  } finally {
+    if (!_pgClient) {
+      try { await client.end(); } catch (_e) { /* ignore */ }
+    }
+  }
+
+  return { ok: gaps.length === 0, gaps };
+}
+
+// ── Mnestra outcome verification ────────────────────────────────────────────
+//
+// After the 7 migrations apply, confirm:
+//   - memory_items table exists
+//   - source_session_id column exists on it (the v0.6.5 fix actually landed)
+//   - memory_status_aggregation function exists
+//
+// This is the test that would have caught the v0.6.5 / v0.6.8 silent-shadow
+// saga at install time instead of cron-tick time.
+
+async function verifyMnestraOutcomes({ secrets, _pgClient } = {}) {
+  const gaps = [];
+  const client = _pgClient || (await safeConnect(secrets && secrets.DATABASE_URL));
+  if (!client) {
+    gaps.push({
+      key: 'DATABASE_URL',
+      message: 'Could not reconnect to Postgres to verify migrations landed',
+      hint: 'This is unexpected — the migrations just ran. Check connectivity and re-run with --yes.'
+    });
+    return { ok: false, gaps };
+  }
+
+  try {
+    // memory_items table
+    const tbl = await safeQuery(client,
+      "SELECT 1 AS ok FROM information_schema.tables WHERE table_schema = 'public' AND table_name = 'memory_items'");
+    if (!tbl.ok) {
+      gaps.push({
+        key: 'memory_items',
+        message: 'memory_items table is missing after migrations',
+        hint: 'Migration 001 should have created it. Re-run with --reset to start fresh, or report a bug.'
+      });
+    } else {
+      // source_session_id column (v0.6.5 fix)
+      const col = await safeQuery(client,
+        "SELECT 1 AS ok FROM information_schema.columns " +
+        "WHERE table_schema = 'public' AND table_name = 'memory_items' AND column_name = 'source_session_id'");
+      if (!col.ok) {
+        gaps.push({
+          key: 'memory_items.source_session_id',
+          message: 'memory_items.source_session_id column is missing — Rumen will fail',
+          hint:
+            'Migration 007 should have added it. If you see this, the migration loader picked up a stale\n' +
+            'set — upgrade with: npm cache clean --force && npm i -g @jhizzard/termdeck@latest\n' +
+            'then re-run `termdeck init --mnestra --yes`.'
+        });
+      }
+    }
+
+    // memory_status_aggregation RPC
+    const rpc = await safeQuery(client,
+      "SELECT 1 AS ok FROM pg_proc WHERE proname = 'memory_status_aggregation'");
+    if (!rpc.ok) {
+      gaps.push({
+        key: 'memory_status_aggregation',
+        message: 'memory_status_aggregation() function is missing',
+        hint: 'Migration 006 should have created it. The wizard\'s status check will fall back to client-side aggregation, but that hits PostgREST row caps.'
+      });
+    }
+  } finally {
+    if (!_pgClient) {
+      try { await client.end(); } catch (_e) { /* ignore */ }
+    }
+  }
+
+  return { ok: gaps.length === 0, gaps };
+}
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+async function safeConnect(databaseUrl) {
+  if (!databaseUrl) return null;
+  try {
+    return await pgRunner.connect(databaseUrl);
+  } catch (_err) {
+    return null;
+  }
+}
+
+// Run a query that returns at most one row. Returns:
+//   { ok: true } when the row exists / value is truthy
+//   { ok: false } when no rows or the value is falsy
+//   { error: string } on query failure
+//
+// `wantRows: true` returns the rows array instead of just an ok bit.
+async function safeQuery(client, sql, opts = {}) {
+  try {
+    const r = await client.query(sql);
+    if (opts.wantRows) return { rows: r.rows };
+    if (r.rows && r.rows.length > 0 && r.rows[0].ok) return { ok: true };
+    return { ok: false };
+  } catch (err) {
+    return { error: err && err.message ? err.message : String(err) };
+  }
+}
+
+module.exports = {
+  auditRumenPreconditions,
+  verifyRumenOutcomes,
+  verifyMnestraOutcomes,
+  printAuditReport,
+  printVerifyReport,
+  // Test surface
+  _probeSupabaseAuth: probeSupabaseAuth,
+  _safeQuery: safeQuery
+};

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

@@ -97,6 +97,65 @@ function looksLikePostgresUrl(url) {
   return null;
 }
 
+// Detect a Supabase Shared Pooler URL in TRANSACTION mode. Pattern:
+//   postgres://postgres.<ref>:<pw>@aws-0-<region>.pooler.supabase.com:6543/postgres
+// Session mode (port 5432 on the pooler) and direct connections
+// (db.<ref>.supabase.co:5432) do NOT need pgbouncer params and must be
+// left alone. Returns true only for the transaction-pooler shape.
+function isTransactionPoolerUrl(parsedUrl) {
+  if (!parsedUrl) return false;
+  const host = (parsedUrl.hostname || '').toLowerCase();
+  // pooler hosts end in `.pooler.supabase.com`. Be lenient on the regional
+  // prefix — Supabase has used `aws-0-` historically and may add others.
+  if (!host.endsWith('.pooler.supabase.com')) return false;
+  // Transaction mode is port 6543. Session mode on the same host is 5432
+  // and doesn't want pgbouncer flags.
+  return parsedUrl.port === '6543';
+}
+
+// Normalize a DATABASE_URL by appending the pgbouncer transaction-mode
+// params Supabase requires when connecting through a transaction pooler.
+//
+// Brad's Rumen logs (2026-04-26) warned:
+//   "DATABASE_URL is a Shared Pooler URL but does not have ?pgbouncer=true.
+//    Append ?pgbouncer=true&connection_limit=1 for transaction-mode
+//    compatibility."
+//
+// The warning is harmless on its own — Rumen's runtime didn't fail because
+// of it — but missing the params can manifest as prepared-statement errors
+// or stuck connections under load with PgBouncer in transaction mode. The
+// safest path is for the wizard to add them on the user's behalf when the
+// URL shape clearly indicates they're needed.
+//
+// Returns `{ url, modified }`. `modified` is true when params were added.
+// Idempotent: a URL that already has pgbouncer=true is returned unchanged.
+// Only touches transaction-pooler URLs (port 6543 on *.pooler.supabase.com).
+// Direct connections (port 5432, db.* hostname) and session-pooler URLs
+// (port 5432 on pooler hostname) are returned unchanged.
+//
+// Errors are swallowed — a malformed URL returns `{ url: original, modified: false }`
+// because validation is the caller's job (looksLikePostgresUrl handles that).
+function normalizeDatabaseUrl(url) {
+  if (!url || typeof url !== 'string') return { url, modified: false };
+  let u;
+  try {
+    u = new URL(url);
+  } catch (_err) {
+    return { url, modified: false };
+  }
+  if (!isTransactionPoolerUrl(u)) return { url, modified: false };
+
+  // Already has pgbouncer set? Don't touch.
+  if (u.searchParams.has('pgbouncer')) return { url, modified: false };
+
+  u.searchParams.set('pgbouncer', 'true');
+  // Set connection_limit only if not already set — preserve user intent.
+  if (!u.searchParams.has('connection_limit')) {
+    u.searchParams.set('connection_limit', '1');
+  }
+  return { url: u.toString(), modified: true };
+}
+
 // Mask all but the last 4 chars of a secret for logging.
 function maskSecret(value) {
   if (!value || typeof value !== 'string') return '';
@@ -110,5 +169,7 @@ module.exports = {
   looksLikeOpenAiKey,
   looksLikeAnthropicKey,
   looksLikePostgresUrl,
+  isTransactionPoolerUrl,
+  normalizeDatabaseUrl,
   maskSecret
 };