@jhizzard/termdeck 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "1.9.0",
+  "version": "1.10.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/doctor.js

@@ -346,6 +346,16 @@ async function _runSchemaCheck(opts = {}) {
   let client = optsObj._pgClient || null;
   let ownsClient = false;
   if (!client) {
+    // Sprint 75 T2 (part C): classify + warn BEFORE the connect attempt —
+    // a direct-endpoint URL on an IPv4-only host doesn't fail fast, it
+    // hangs until a pool timeout, so the warning must print first.
+    // Warn-only; fail-soft if the helper is unavailable.
+    try {
+      const urlHelper = require(path.join(SETUP_DIR, 'supabase-url'));
+      for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(secrets.DATABASE_URL))) {
+        process.stdout.write(`  ${line}\n`);
+      }
+    } catch (_e) { /* warn-only — never block the doctor pass */ }
     try {
       client = await pgRunner.connect(secrets.DATABASE_URL);
       ownsClient = true;
@@ -524,6 +534,7 @@ function renderSchemaResult(result, c) {
   if (result.connectError) {
     out.push(`  ${c.yellow('✗')} could not connect: ${result.connectError}`);
     out.push(`  ${c.dim('Check DATABASE_URL in ~/.termdeck/secrets.env, then re-run.')}`);
+    out.push(`  ${c.dim('If this host is IPv4-only and the URL is the db.<project-ref> direct endpoint, that is the cause — switch to the Shared Pooler.')}`);
     return out.join('\n');
   }
   for (const section of result.sections) {

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

@@ -72,8 +72,9 @@ const HELP = [
   '  --skip-verify     Skip the final memory_status_aggregation() sanity call',
   '',
   'What this does:',
-  '  1. Prompts for Supabase URL, service_role key, direct Postgres connection',
-  '     string, OpenAI API key, and (optional) Anthropic API key — or reuses',
+  '  1. Prompts for Supabase URL, service_role key, Postgres connection',
+  '     string (Shared Pooler; IPv4-safe), OpenAI API key, and (optional)',
+  '     Anthropic API key — or reuses',
   '     saved values if a complete set already exists in secrets.env.',
   '  2. Writes ~/.termdeck/secrets.env IMMEDIATELY (merge-aware) so a later',
   '     pg connect or migration failure does not lose what you typed in.',
@@ -157,6 +158,11 @@ function inputsFromEnv() {
 
   const dbErr = urlHelper.looksLikePostgresUrl(required.DATABASE_URL);
   if (dbErr) throw new Error(`DATABASE_URL: ${dbErr}`);
+  // Sprint 75 T2 (part B): warn-only — a direct-endpoint URL passes
+  // validation (warn ≠ reject) but gets the IPv4 trap warning printed once.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(required.DATABASE_URL))) {
+    process.stdout.write(`  ${line}\n`);
+  }
 
   const srErr = urlHelper.looksLikeServiceRole(required.SUPABASE_SERVICE_ROLE_KEY);
   if (srErr) throw new Error(`SUPABASE_SERVICE_ROLE_KEY: ${srErr}`);
@@ -188,7 +194,7 @@ TermDeck Mnestra Setup
 
 This wizard configures TermDeck's Tier 2 memory layer (Mnestra) by:
   1. Asking for your Supabase URL and service_role key
-  2. Asking for a direct Postgres connection string
+  2. Asking for a Postgres connection string (Shared Pooler)
   3. Asking for an OpenAI API key (embeddings)
   4. Asking for an Anthropic API key (optional, summaries)
   5. Writing ~/.termdeck/secrets.env (before any database work, so a
@@ -253,6 +259,12 @@ async function collectInputs({ yes, reset }) {
       process.stdout.write(
         `Found saved secrets in ~/.termdeck/secrets.env (project ${ref}, db ${masked}).\n`
       );
+      // Sprint 75 T2 (part B): highest-value warn site — an operator whose
+      // EARLIER install stored a direct-endpoint URL (the Brad case) would
+      // otherwise sail through reuse with zero feedback. Warn-only.
+      for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(found.inputs.databaseUrl))) {
+        process.stdout.write(`  ${line}\n`);
+      }
       const reuse = yes ? true : await prompts.confirm('  Reuse saved secrets?', { defaultYes: true });
       if (reuse) {
         process.stdout.write('  Reusing saved secrets. Skipping prompts.\n\n');
@@ -284,11 +296,19 @@ async function collectInputs({ yes, reset }) {
   );
 
   process.stdout.write(
-    '? Direct Postgres connection string\n' +
-    `  (Supabase dashboard → Project Settings → Database → Connection String → Transaction pooler)\n` +
-    '  postgres://postgres.REF:PW@... '
+    '? Postgres connection string (Shared Pooler)\n' +
+    '  (Supabase dashboard → Connect (green button) → Transaction pooler →\n' +
+    '   toggle ON "Use IPv4 connection (Shared Pooler)" — the OFF default shows an\n' +
+    '   IPv6-only URL that hangs on IPv4-only hosts)\n' +
+    '  postgres://postgres.<project-ref>:PW@aws-<n>-<region>.pooler.supabase.com:6543/postgres '
   );
   const databaseUrl = await promptSecretWithValidation(urlHelper.looksLikePostgresUrl);
+  // Sprint 75 T2 (part B): warn-only endpoint-shape feedback. The validator
+  // above ACCEPTS direct URLs (IPv6-capable hosts use them legitimately);
+  // this prints the IPv4 trap warning without changing acceptance.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(databaseUrl))) {
+    process.stdout.write(`  ${line}\n`);
+  }
 
   process.stdout.write('? OpenAI API key (starts sk-proj- or sk-): ');
   const openaiKey = await promptSecretWithValidation(urlHelper.looksLikeOpenAiKey);
@@ -713,13 +733,34 @@ function refreshBundledHookIfNewer(opts = {}) {
 // actually run after upgrading the package.
 
 const SETTINGS_JSON_PATH = path.join(require('os').homedir(), '.claude', 'settings.json');
-const HOOK_COMMAND = 'node ~/.claude/hooks/memory-session-end.js';
+
+// Sprint 75 T2 — hook commands are written into ~/.claude/settings.json with
+// ABSOLUTE paths. The pre-1.10 literal `node ~/.claude/hooks/...` shape relied
+// on shell tilde expansion — it worked on macOS/Linux only by luck of how the
+// harness invokes hook commands, and is a hard break on Windows (audit item 4).
+// Computed at CALL time (not require time) from os.homedir() so a process that
+// re-points HOME (tests, sandboxed installs) gets the right path. The path is
+// double-quoted so a home dir containing spaces (`/Users/First Last/`) still
+// produces a command the harness shell can execute. Lockstep twin lives in
+// packages/stack-installer/src/index.js (`_hookCommandFor`) — INSTALLER-
+// PITFALLS Class N: change both or neither.
+function _hookCommandFor(filename) {
+  return `node "${path.join(require('os').homedir(), '.claude', 'hooks', filename)}"`;
+}
+
+// True when an entry's command still carries the legacy tilde shape and
+// should be rewritten to the absolute form.
+function _isTildeHookCommand(command) {
+  return typeof command === 'string' && command.includes('~/');
+}
+
+const HOOK_COMMAND = _hookCommandFor('memory-session-end.js');
 const HOOK_TIMEOUT_SECONDS = 30;
 
 // Sprint 64 T3 — PreCompact hook (Investigation 2 of CRITICAL-READ-FIRST-
 // 2026-05-07.md). Lives alongside the SessionEnd hook; refreshes via the
 // same Sprint 51.6 T3 version-stamp gate.
-const PRECOMPACT_HOOK_COMMAND = 'node ~/.claude/hooks/memory-pre-compact.js';
+const PRECOMPACT_HOOK_COMMAND = _hookCommandFor('memory-pre-compact.js');
 const PRECOMPACT_HOOK_TIMEOUT_SECONDS = 30;
 
 function _isSessionEndHookEntry(entry) {
@@ -734,7 +775,8 @@ function _isSessionEndHookEntry(entry) {
 // `packages/stack-installer/src/index.js:451` byte-for-byte (modulo
 // constants pulled from this file's scope).
 function _mergeSessionEndHookEntry(settings, opts = {}) {
-  const command = opts.command || HOOK_COMMAND;
+  // Command computed at call time (Sprint 75 T2) — see _hookCommandFor.
+  const command = opts.command || _hookCommandFor('memory-session-end.js');
   const timeout = opts.timeout != null ? opts.timeout : HOOK_TIMEOUT_SECONDS;
   const entry = { type: 'command', command, timeout };
 
@@ -759,10 +801,29 @@ function _mergeSessionEndHookEntry(settings, opts = {}) {
 
   if (!Array.isArray(settings.hooks.SessionEnd)) settings.hooks.SessionEnd = [];
 
+  // Sprint 75 T2 — rewrite a stale literal-`~` command (written by installers
+  // ≤ v1.9.x) to the absolute form. The "already wired?" predicate matches by
+  // hook FILENAME substring, so without this rewrite a legacy entry would be
+  // reported already-installed and keep its `~` forever. Idempotent: absolute
+  // commands (and user-custom commands without `~/`) are never touched.
+  let tildeMigrated = false;
+  for (const group of settings.hooks.SessionEnd) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const e of group.hooks) {
+      if (_isSessionEndHookEntry(e) && _isTildeHookCommand(e.command)) {
+        e.command = command;
+        tildeMigrated = true;
+      }
+    }
+  }
+
   for (const group of settings.hooks.SessionEnd) {
     if (!group || !Array.isArray(group.hooks)) continue;
     if (group.hooks.some(_isSessionEndHookEntry)) {
-      return { settings, status: migrated ? 'migrated-from-stop' : 'already-installed' };
+      const status = tildeMigrated ? 'migrated-tilde-path'
+        : migrated ? 'migrated-from-stop'
+        : 'already-installed';
+      return { settings, status };
     }
   }
 
@@ -788,17 +849,30 @@ function _isPreCompactHookEntry(entry) {
 }
 
 function _mergePreCompactHookEntry(settings, opts = {}) {
-  const command = opts.command || PRECOMPACT_HOOK_COMMAND;
+  // Command computed at call time (Sprint 75 T2) — see _hookCommandFor.
+  const command = opts.command || _hookCommandFor('memory-pre-compact.js');
   const timeout = opts.timeout != null ? opts.timeout : PRECOMPACT_HOOK_TIMEOUT_SECONDS;
   const entry = { type: 'command', command, timeout };
 
   if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
   if (!Array.isArray(settings.hooks.PreCompact)) settings.hooks.PreCompact = [];
 
+  // Sprint 75 T2 — same stale literal-`~` rewrite as the SessionEnd merge.
+  let tildeMigrated = false;
+  for (const group of settings.hooks.PreCompact) {
+    if (!group || !Array.isArray(group.hooks)) continue;
+    for (const e of group.hooks) {
+      if (_isPreCompactHookEntry(e) && _isTildeHookCommand(e.command)) {
+        e.command = command;
+        tildeMigrated = true;
+      }
+    }
+  }
+
   for (const group of settings.hooks.PreCompact) {
     if (!group || !Array.isArray(group.hooks)) continue;
     if (group.hooks.some(_isPreCompactHookEntry)) {
-      return { settings, status: 'already-installed' };
+      return { settings, status: tildeMigrated ? 'migrated-tilde-path' : 'already-installed' };
     }
   }
 
@@ -934,10 +1008,14 @@ function runSettingsJsonMigration({ dryRun = false } = {}) {
       ok(r.backup ? `installed (SessionEnd; backup: ${path.basename(r.backup)})` : 'installed (SessionEnd)');
     } else if (r.status === 'migrated-from-stop') {
       ok(r.backup ? `migrated Stop → SessionEnd (was firing on every turn; backup: ${path.basename(r.backup)})` : 'migrated Stop → SessionEnd (was firing on every turn)');
+    } else if (r.status === 'migrated-tilde-path') {
+      ok(r.backup ? `rewrote legacy ~ command to absolute path (backup: ${path.basename(r.backup)})` : 'rewrote legacy ~ command to absolute path');
     } else if (r.status === 'would-installed') {
       ok('would install (SessionEnd) (dry-run)');
     } else if (r.status === 'would-migrated-from-stop') {
       ok('would migrate Stop → SessionEnd (dry-run)');
+    } else if (r.status === 'would-migrated-tilde-path') {
+      ok('would rewrite legacy ~ command to absolute path (dry-run)');
     } else if (r.status === 'malformed') {
       ok(`(skipped: settings.json malformed: ${r.error})`);
     } else {
@@ -964,8 +1042,12 @@ function runSettingsJsonMigration({ dryRun = false } = {}) {
       ok('already wired (PreCompact)');
     } else if (r.status === 'installed') {
       ok(r.backup ? `installed (PreCompact; backup: ${path.basename(r.backup)})` : 'installed (PreCompact)');
+    } else if (r.status === 'migrated-tilde-path') {
+      ok(r.backup ? `rewrote legacy ~ command to absolute path (backup: ${path.basename(r.backup)})` : 'rewrote legacy ~ command to absolute path');
     } else if (r.status === 'would-installed') {
       ok('would install (PreCompact) (dry-run)');
+    } else if (r.status === 'would-migrated-tilde-path') {
+      ok('would rewrite legacy ~ command to absolute path (dry-run)');
     } else if (r.status === 'malformed') {
       ok(`(skipped: settings.json malformed: ${r.error})`);
     } else {
@@ -1162,7 +1244,10 @@ async function main(argv) {
   } catch (err) {
     fail(err.message);
     process.stderr.write(
-      '\nDouble-check the connection string from Supabase → Project Settings → Database → Connection String.\n'
+      '\nDouble-check the connection string: Supabase dashboard → Connect → Transaction pooler →\n' +
+      'toggle ON "Use IPv4 connection (Shared Pooler)". If the connect HUNG (timeout rather than\n' +
+      'auth error), the URL is probably the IPv6-only db.<project-ref> endpoint and this host has\n' +
+      'no IPv6 route — use the Shared Pooler URL.\n'
     );
     printResumeHint();
     return 3;
@@ -1233,3 +1318,9 @@ module.exports._isSessionEndHookEntry = _isSessionEndHookEntry;
 module.exports.SETTINGS_JSON_PATH = SETTINGS_JSON_PATH;
 module.exports.HOOK_COMMAND = HOOK_COMMAND;
 module.exports.HOOK_TIMEOUT_SECONDS = HOOK_TIMEOUT_SECONDS;
+// Sprint 75 T2 — absolute-path hook-command builders (lockstep twin in
+// packages/stack-installer/src/index.js; exported for tests).
+module.exports._hookCommandFor = _hookCommandFor;
+module.exports._isTildeHookCommand = _isTildeHookCommand;
+module.exports._mergePreCompactHookEntry = _mergePreCompactHookEntry;
+module.exports.migrateSettingsJsonPreCompactEntry = migrateSettingsJsonPreCompactEntry;

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

@@ -212,6 +212,13 @@ function preflight() {
     ok();
   }
 
+  // Sprint 75 T2 (part B): warn-only endpoint-shape feedback — the same
+  // stored URL feeds the Edge Function secrets, so a direct-endpoint URL
+  // (IPv6-only) carried over from an earlier install gets flagged here too.
+  for (const line of urlHelper.directEndpointWarningLines(urlHelper.classifyDbEndpoint(secrets.DATABASE_URL))) {
+    process.stdout.write(`  ${line}\n`);
+  }
+
   // 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

package/packages/server/src/health.js

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

package/packages/server/src/preflight.js

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

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

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

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

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

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

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