@jhizzard/termdeck 0.5.1 → 0.6.0

package/README.md

@@ -226,6 +226,18 @@ For users who want more than `npx` — cloning from source, building a macOS `.a
 
 ---
 
+## Staying current
+
+TermDeck, Mnestra, and Rumen all evolve fast — Flashback recall quality, Mnestra search semantics, and Rumen synth quality each shift between minor releases. Running last month's stack means missing fixed bugs and degraded recall. Three layered ways to keep current:
+
+1. **One command for the whole stack:** `npx @jhizzard/termdeck-stack` — re-runs the meta-installer, which detects what's already installed and updates anything that's behind. Idempotent: safe to run any time, won't touch `~/.termdeck/{config.yaml,secrets.env,termdeck.db}`.
+2. **On demand:** `termdeck doctor` — prints a 4-row table (TermDeck, Mnestra, Rumen, termdeck-stack) of installed vs. latest versions with a status column. Exit 0 = all current, 1 = at least one update available, 2 = registry/network failure.
+3. **Passive:** TermDeck prints a single yellow `[hint]` line on startup when an update is available. Rate-limited to once per 24 hours via `~/.termdeck/update-check.json`. Never blocks startup. Suppress with `TERMDECK_NO_UPDATE_CHECK=1` (the kill switch only mutes the startup hint — `termdeck doctor` still works on demand).
+
+See **[docs/SEMVER-POLICY.md](docs/SEMVER-POLICY.md)** for what each kind of bump means across the four packages and how risky a given upgrade path is.
+
+---
+
 ## Related packages
 
 - **[@jhizzard/mnestra](https://www.npmjs.com/package/@jhizzard/mnestra)** — persistent dev memory MCP server. pgvector + hybrid search + 3-layer progressive disclosure. Works standalone with any MCP client.

package/package.json

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

@@ -0,0 +1,255 @@
+// `termdeck doctor` — Sprint 28 T2.
+//
+// Compares installed versions of the four TermDeck-stack packages against
+// the npm registry's `dist-tags.latest` and prints a status table. Zero new
+// deps — uses only node:https, node:child_process, and process.stdout.
+//
+// Module contract (per docs/sprint-28-update-signal/STATUS.md):
+//   module.exports = function doctor(argv): Promise<exitCode>
+//     0 = all current
+//     1 = at least one update available
+//     2 = network/registry failure or unrecoverable error
+//
+// `_detectInstalled` and `_fetchLatest` are exposed as properties on the
+// exported function so tests can monkey-patch the network/process surface
+// without spinning up a real registry. The doctor body calls them via
+// `module.exports.<name>` so monkey-patching takes effect at call time.
+
+const https = require('https');
+const { spawn } = require('child_process');
+
+const STACK_PACKAGES = [
+  '@jhizzard/termdeck',
+  '@jhizzard/mnestra',
+  '@jhizzard/rumen',
+  '@jhizzard/termdeck-stack',
+];
+
+const REGISTRY_TIMEOUT_MS = 5000;
+const NPM_LS_TIMEOUT_MS = 8000;
+
+const STATUS = {
+  UP_TO_DATE: 'up to date',
+  UPDATE: 'update available',
+  NOT_INSTALLED: 'not installed',
+  NETWORK_ERROR: 'network error',
+};
+
+function makeColors(enabled) {
+  if (!enabled) {
+    return { green: (s) => s, yellow: (s) => s, dim: (s) => s, bold: (s) => s };
+  }
+  return {
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+  };
+}
+
+// Detect installed version via `npm ls -g <pkg> --depth=0 --json`. Returns
+// the version string on success, or null on "not installed" / parse failure
+// / npm-missing-from-PATH / timeout. Stderr noise (npm WARN lines) is
+// silently dropped — those are not fatal.
+async function _detectInstalled(pkg) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn('npm', ['ls', '-g', pkg, '--depth=0', '--json'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch {
+      return resolve(null);
+    }
+
+    let stdout = '';
+    let timedOut = false;
+    const t = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch (_e) { /* already gone */ }
+    }, NPM_LS_TIMEOUT_MS);
+
+    child.stdout.on('data', (b) => { stdout += b.toString('utf8'); });
+    child.stderr.on('data', () => { /* discard npm WARNs */ });
+    child.on('error', () => { clearTimeout(t); resolve(null); });
+    child.on('close', () => {
+      clearTimeout(t);
+      if (timedOut) return resolve(null);
+      try {
+        const parsed = JSON.parse(stdout);
+        const dep = parsed && parsed.dependencies && parsed.dependencies[pkg];
+        if (dep && typeof dep.version === 'string') return resolve(dep.version);
+        return resolve(null);
+      } catch {
+        return resolve(null);
+      }
+    });
+  });
+}
+
+// Fetch the `latest` dist-tag for a package from the public npm registry.
+// Returns the version string on success, or null on any failure (offline,
+// non-200, malformed JSON, timeout). The caller treats null as a network
+// error and bumps the exit code to 2.
+async function _fetchLatest(pkg) {
+  return new Promise((resolve) => {
+    // Encode `@scope/name` as `%40scope%2Fname` per the registry's URL spec.
+    const encoded = encodeURIComponent(pkg);
+    const url = `https://registry.npmjs.org/-/package/${encoded}/dist-tags`;
+    let settled = false;
+    const done = (v) => {
+      if (settled) return;
+      settled = true;
+      resolve(v);
+    };
+
+    let req;
+    try {
+      req = https.get(url, { timeout: REGISTRY_TIMEOUT_MS }, (res) => {
+        if (res.statusCode !== 200) {
+          res.resume();
+          return done(null);
+        }
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => { body += chunk; });
+        res.on('end', () => {
+          try {
+            const parsed = JSON.parse(body);
+            if (parsed && typeof parsed.latest === 'string') return done(parsed.latest);
+            return done(null);
+          } catch {
+            return done(null);
+          }
+        });
+        res.on('error', () => done(null));
+      });
+    } catch {
+      return done(null);
+    }
+    req.on('timeout', () => {
+      try { req.destroy(); } catch (_e) { /* already gone */ }
+      done(null);
+    });
+    req.on('error', () => done(null));
+  });
+}
+
+// Lightweight semver compare — only looks at the first three numeric segments,
+// which is all dist-tags.latest ever needs. Returns -1, 0, or 1.
+function _compareSemver(a, b) {
+  const pa = String(a).split('.').map((s) => parseInt(s, 10) || 0);
+  const pb = String(b).split('.').map((s) => parseInt(s, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function classifyRow(installed, latest) {
+  if (latest === null) return STATUS.NETWORK_ERROR;
+  if (installed === null) return STATUS.NOT_INSTALLED;
+  return _compareSemver(installed, latest) < 0 ? STATUS.UPDATE : STATUS.UP_TO_DATE;
+}
+
+function pad(s, n) {
+  const str = String(s);
+  return str.length >= n ? str : str + ' '.repeat(n - str.length);
+}
+
+function renderTable(rows, c) {
+  const out = [];
+  out.push(c.bold('TermDeck stack — version check'));
+  out.push('');
+  out.push(`  ${pad('Package', 32)}${pad('Installed', 12)}${pad('Latest', 12)}Status`);
+  out.push('  ' + '─'.repeat(63));
+  for (const r of rows) {
+    const installedDisplay = r.installed === null ? '(none)' : r.installed;
+    const latestDisplay = r.latest === null ? '?' : r.latest;
+    let statusDisplay = r.status;
+    if (r.status === STATUS.UP_TO_DATE) statusDisplay = c.green(r.status);
+    else if (r.status === STATUS.UPDATE) statusDisplay = c.yellow(r.status);
+    else if (r.status === STATUS.NOT_INSTALLED) statusDisplay = c.dim(r.status);
+    else if (r.status === STATUS.NETWORK_ERROR) statusDisplay = c.dim(r.status);
+    out.push(`  ${pad(r.package, 32)}${pad(installedDisplay, 12)}${pad(latestDisplay, 12)}${statusDisplay}`);
+  }
+  return out.join('\n');
+}
+
+function renderFooter(rows, exitCode) {
+  if (exitCode === 2) {
+    const errors = rows.filter((r) => r.status === STATUS.NETWORK_ERROR).length;
+    return `\n  Could not reach npm registry for ${errors} package${errors === 1 ? '' : 's'}. Try again later.`;
+  }
+  if (exitCode === 1) {
+    const updates = rows.filter((r) => r.status === STATUS.UPDATE).length;
+    return (
+      `\n  ${updates} update${updates === 1 ? '' : 's'} available. ` +
+      `Run: npx @jhizzard/termdeck-stack\n` +
+      `  Or upgrade individually: npm install -g @jhizzard/termdeck@latest`
+    );
+  }
+  return `\n  All packages up to date.`;
+}
+
+function parseArgv(argv) {
+  const args = Array.isArray(argv) ? argv : [];
+  return {
+    json: args.includes('--json'),
+    noColor: args.includes('--no-color'),
+  };
+}
+
+async function doctor(argv) {
+  const opts = parseArgv(argv);
+
+  // Resolve every package's installed + latest in parallel — independent
+  // network/process calls, no reason to serialize.
+  const rows = await Promise.all(
+    STACK_PACKAGES.map(async (pkg) => {
+      const [installed, latest] = await Promise.all([
+        module.exports._detectInstalled(pkg),
+        module.exports._fetchLatest(pkg),
+      ]);
+      return {
+        package: pkg,
+        installed,
+        latest,
+        status: classifyRow(installed, latest),
+      };
+    })
+  );
+
+  // Exit-code priority: any network failure → 2; any update available → 1;
+  // else 0. Computed after all rows resolve so a single transient failure
+  // doesn't mask real updates in stdout.
+  let exitCode = 0;
+  for (const r of rows) {
+    if (r.status === STATUS.NETWORK_ERROR) {
+      exitCode = 2;
+      break;
+    }
+    if (r.status === STATUS.UPDATE && exitCode < 1) exitCode = 1;
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ exitCode, rows }, null, 2) + '\n');
+    return exitCode;
+  }
+
+  const colorEnabled = !opts.noColor && process.stdout.isTTY === true;
+  const c = makeColors(colorEnabled);
+  process.stdout.write(renderTable(rows, c) + '\n');
+  process.stdout.write(renderFooter(rows, exitCode) + '\n');
+  return exitCode;
+}
+
+module.exports = doctor;
+module.exports._detectInstalled = _detectInstalled;
+module.exports._fetchLatest = _fetchLatest;
+module.exports._compareSemver = _compareSemver;
+module.exports.STACK_PACKAGES = STACK_PACKAGES;
+module.exports.STATUS = STATUS;

package/packages/cli/src/index.js

@@ -76,12 +76,22 @@ if (args[0] === 'stack') {
   return;
 }
 
+// `termdeck doctor` — Sprint 28: version-check the whole stack.
+if (args[0] === 'doctor') {
+  const doctor = require(path.join(__dirname, 'doctor.js'));
+  doctor(args.slice(1)).then((code) => process.exit(code || 0)).catch((err) => {
+    console.error('[cli] doctor failed:', err && err.stack || err);
+    process.exit(2);
+  });
+  return;
+}
+
 // Sprint 24: when `termdeck` is invoked with no subcommand AND a configured
 // stack is detected, route through stack.js so users don't have to remember
 // the `stack` subcommand. `--no-stack` is the explicit opt-out.
 const { shouldAutoOrchestrate } = require(path.join(__dirname, 'auto-orchestrate.js'));
 
-const KNOWN_SUBCOMMANDS = new Set(['init', 'forge', 'stack']);
+const KNOWN_SUBCOMMANDS = new Set(['init', 'forge', 'stack', 'doctor']);
 const noStackIdx = args.indexOf('--no-stack');
 const noStackRequested = noStackIdx !== -1;
 if (noStackRequested) args.splice(noStackIdx, 1); // strip before flag parsing
@@ -120,6 +130,7 @@ for (let i = 0; i < args.length; i++) {
     termdeck init --mnestra     Configure Tier 2 memory (Supabase + Mnestra)
     termdeck init --rumen       Deploy Tier 3 async learning (Rumen)
     termdeck forge              Generate Claude skills from memories (experimental)
+    termdeck doctor             Check whether the stack packages are up to date
 
   Keyboard shortcuts (in browser):
     Ctrl+Shift+N                Focus prompt bar
@@ -175,6 +186,30 @@ if (!LOOPBACK.has(host)) {
   }
 }
 
+// Sprint 25 T4: non-blocking nudge when RAG is configured but the Supabase MCP
+// (T1's `@supabase/mcp-server-supabase` detection) isn't installed. Lazy-loads
+// T1's module so Tier 1 users with no RAG never pay the require cost. Silent
+// when RAG is off, when the MCP is detected, when ~/.claude/mcp.json already
+// declares a `supabase` server, or when anything below throws.
+async function checkSupabaseMcpHint(cfg) {
+  if (!cfg || !cfg.rag || cfg.rag.enabled !== true) return null;
+  try {
+    const claudeMcpPath = path.join(os.homedir(), '.claude', 'mcp.json');
+    if (fs.existsSync(claudeMcpPath)) {
+      try {
+        const parsed = JSON.parse(fs.readFileSync(claudeMcpPath, 'utf8'));
+        if (parsed && parsed.mcpServers && parsed.mcpServers.supabase) return null;
+      } catch (_e) { /* malformed JSON — fall through and let detectMcp decide */ }
+    }
+    const { detectMcp } = require(path.join(__dirname, '..', '..', 'server', 'src', 'setup', 'supabase-mcp.js'));
+    const result = await detectMcp();
+    if (result && result.available) return null;
+    return 'Supabase MCP not installed — wizard auto-fill unavailable. Install with: npx @jhizzard/termdeck-stack --tier 4';
+  } catch (_e) {
+    return null;
+  }
+}
+
 server.listen(port, host, async () => {
   // Box inner width is 38 (count of ═ between ╔ and ╗). Center the title
   // dynamically so the right border stays aligned regardless of version length.
@@ -205,6 +240,23 @@ server.listen(port, host, async () => {
     console.error(`  \x1b[31m[health] Preflight failed: ${err.message}\x1b[0m\n`);
   });
 
+  // Sprint 28 T3: fire-and-forget update-check banner. Lazy-required so users
+  // who never start the server don't pay the require cost. Errors are swallowed
+  // inside the module; never blocks startup. Double-protected (try/catch around
+  // the require + swallowed .catch on the promise) so a missing or broken T3
+  // module can never break startup.
+  try {
+    const { checkAndPrintHint } = require(path.join(__dirname, 'update-check.js'));
+    checkAndPrintHint(config).catch(() => { /* swallowed inside the module too */ });
+  } catch (_e) { /* never block startup on a hint module load failure */ }
+
+  // Sprint 25 T4: Supabase MCP install nudge — runs alongside (not inside)
+  // runPreflight. Silent unless RAG is on AND the MCP is missing AND the
+  // user hasn't already declared it in ~/.claude/mcp.json.
+  checkSupabaseMcpHint(config).then((msg) => {
+    if (msg) console.log(`  \x1b[33m[hint]\x1b[0m ${msg}`);
+  }).catch(() => { /* silent */ });
+
   // Skip auto-open in Codespaces/CI (port forwarding handles it)
   const isCodespaces = !!process.env.CODESPACES || !!process.env.GITHUB_CODESPACE_TOKEN;
   const isCI = !!process.env.CI;

package/packages/cli/src/update-check.js

@@ -0,0 +1,156 @@
+// Sprint 28 T3 — passive startup update-check banner.
+//
+// Side-effect-only module. checkAndPrintHint() rate-limits a single GET against
+// the npm registry's dist-tags endpoint to once every 24h via a JSON cache at
+// ~/.termdeck/update-check.json, and prints one yellow [hint] line when a
+// newer version of @jhizzard/termdeck is published. All failures are swallowed
+// — startup must never block on this.
+//
+// Suppression order (any one short-circuits before any side effect):
+//   1. process.env.TERMDECK_NO_UPDATE_CHECK === '1'
+//   2. process.stdout.isTTY is falsy (CI, piped output)
+//   3. cache exists and lastCheckedAt is within 24h of now
+//
+// Module contract per docs/sprint-28-update-signal/STATUS.md.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const CACHE_VERSION = 1;
+const TTL_MS = 24 * 60 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 5000;
+const PACKAGE_NAME = '@jhizzard/termdeck';
+const REGISTRY_URL =
+  'https://registry.npmjs.org/-/package/@jhizzard%2Ftermdeck/dist-tags';
+
+function defaultCachePath() {
+  return path.join(os.homedir(), '.termdeck', 'update-check.json');
+}
+
+// The CLI ships inside the @jhizzard/termdeck package; the workspace root
+// package.json is three levels up from packages/cli/src/. If anything goes
+// wrong reading it (renamed file, broken JSON), return null and let the caller
+// suppress.
+function defaultPackageVersion() {
+  try {
+    const pkg = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+    return pkg && pkg.version ? String(pkg.version) : null;
+  } catch {
+    return null;
+  }
+}
+
+function isValidSemver(v) {
+  return typeof v === 'string' && /^\d+\.\d+\.\d+/.test(v);
+}
+
+// Three-way semver compare on [major, minor, patch]. Pre-release suffixes are
+// ignored — "0.5.1-beta" and "0.5.1" compare equal. Good enough for the hint.
+function compareSemver(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function readCache(cachePath) {
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+    if (parsed.version !== CACHE_VERSION) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cachePath, data) {
+  try {
+    fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+    fs.writeFileSync(cachePath, JSON.stringify(data, null, 2), 'utf8');
+  } catch {
+    // Read-only home, ENOSPC, race with another process — all benign here.
+  }
+}
+
+async function fetchLatest(registryUrl) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(registryUrl, { signal: controller.signal });
+    if (!res || !res.ok) return null;
+    const json = await res.json();
+    const latest = json && json.latest;
+    return isValidSemver(latest) ? latest : null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function checkAndPrintHint(_config, opts) {
+  try {
+    if (process.env.TERMDECK_NO_UPDATE_CHECK === '1') return;
+    if (!process.stdout || !process.stdout.isTTY) return;
+
+    const o = opts || {};
+    const now = o.now instanceof Date ? o.now : new Date();
+    const registryUrl = typeof o.registryUrl === 'string' ? o.registryUrl : REGISTRY_URL;
+    const cachePath = typeof o.cachePath === 'string' ? o.cachePath : defaultCachePath();
+    const installed = typeof o.packageVersion === 'string'
+      ? o.packageVersion
+      : defaultPackageVersion();
+
+    if (!isValidSemver(installed)) return;
+
+    const cache = readCache(cachePath);
+    if (cache && cache.lastCheckedAt) {
+      const lastMs = Date.parse(cache.lastCheckedAt);
+      if (Number.isFinite(lastMs) && now.getTime() - lastMs < TTL_MS) {
+        return;
+      }
+    }
+
+    const latest = await fetchLatest(registryUrl);
+    if (!isValidSemver(latest)) return;
+
+    writeCache(cachePath, {
+      version: CACHE_VERSION,
+      lastCheckedAt: now.toISOString(),
+      lastSeenLatest: latest,
+      installedAtCheck: installed,
+    });
+
+    if (compareSemver(installed, latest) >= 0) return;
+
+    console.log(
+      '\x1b[33m[hint]\x1b[0m TermDeck v' +
+        latest +
+        ' available — upgrade with: npm install -g ' +
+        PACKAGE_NAME +
+        '@latest'
+    );
+    console.log(
+      '       Or run `termdeck doctor` for the whole stack. ' +
+        'Suppress with TERMDECK_NO_UPDATE_CHECK=1.'
+    );
+  } catch {
+    // Never throw from a fire-and-forget hook.
+  }
+}
+
+module.exports = {
+  checkAndPrintHint,
+  // Exported for unit testing only — not part of the public contract.
+  _internal: { compareSemver, isValidSemver, readCache, writeCache, CACHE_VERSION, TTL_MS },
+};

package/packages/client/public/app.js

@@ -2478,6 +2478,16 @@
 
     let setupModalOpen = false;
 
+    // Sprint 25 T3 — Supabase MCP auto-flow state. Closure-scoped to this module
+    // so a re-render of the tier list (refreshSetupStatus) doesn't lose an
+    // in-flight picker step. The PAT lives here only between /connect success
+    // and /select success; we null `supabaseAutoState` after /select returns ok.
+    // Never log .pat. Never assign it to a property of `state` or `window`.
+    let supabaseAutoState = null;
+    // Cache of the last /api/setup payload so we can re-render the tier list
+    // (e.g. PAT entry → project picker) without forcing another HTTP fetch.
+    let lastSetupData = null;
+
     function ensureSetupModal() {
       if (document.getElementById('setupModal')) return;
       const modal = document.createElement('div');
@@ -2546,6 +2556,7 @@
       if (recheckBtn) { recheckBtn.disabled = true; recheckBtn.textContent = 're-checking…'; }
       try {
         const data = await api('GET', '/api/setup');
+        lastSetupData = data;
         renderSetupTiers(data);
         const cur = Number(data.tier) || 1;
         if (subtitle) {
@@ -2582,8 +2593,13 @@
         // Sprint 23 T2: tier 2 renders a credential form instead of CLI commands
         // when not active, so users can paste URL/keys directly in the browser.
         const isCredentialForm = tier.id === '2' && status !== 'active';
+        // Sprint 25 T3: above the manual paste form, offer the Supabase MCP
+        // auto-flow. Only render for tier 2 when status is not_configured or
+        // partial — once active there is nothing to configure.
+        const showSupabaseAutoFlow = tier.id === '2' && (status === 'not_configured' || status === 'partial');
+        const autoFlowHtml = showSupabaseAutoFlow ? renderSupabaseAutoFlow() : '';
         const cmds = isCredentialForm
-          ? renderSetupCredentialForm()
+          ? `${autoFlowHtml}${renderSetupCredentialForm()}`
           : (status === 'active' || tier.commands.length === 0)
             ? ''
             : `<div class="setup-cmds">${tier.commands.map((c) => {
@@ -2643,6 +2659,199 @@
           }
         });
       }
+
+      // Sprint 25 T3 — Supabase MCP auto-flow handlers. The form is only in the
+      // DOM when showSupabaseAutoFlow was true above; querying for missing nodes
+      // is a no-op and keeps this branch defensive against re-render order.
+      const autoConnectBtn = tiersEl.querySelector('#supabaseAutoConnect');
+      if (autoConnectBtn) {
+        autoConnectBtn.addEventListener('click', handleSupabaseAutoConnect);
+      }
+      const autoPatInput = tiersEl.querySelector('#supabaseAutoPat');
+      if (autoPatInput) {
+        autoPatInput.addEventListener('keydown', (e) => {
+          if (e.key === 'Enter') {
+            e.preventDefault();
+            handleSupabaseAutoConnect();
+          }
+        });
+      }
+      const autoSelectBtn = tiersEl.querySelector('#supabaseAutoSelect');
+      if (autoSelectBtn) {
+        autoSelectBtn.addEventListener('click', handleSupabaseAutoSelect);
+      }
+      const autoBackBtn = tiersEl.querySelector('#supabaseAutoBack');
+      if (autoBackBtn) {
+        autoBackBtn.addEventListener('click', handleSupabaseAutoBack);
+      }
+    }
+
+    // Sprint 25 T3 — Supabase MCP auto-flow renderer.
+    // Inline-styled (Sprint 23 T1 owns style.css). Renders one of two states
+    // driven by `supabaseAutoState`: the PAT entry form (default), or the
+    // project picker (when state.picking is true). Errors render inline; the
+    // manual credential form is always still visible below as a fallback.
+    function renderSupabaseAutoFlow() {
+      const s = supabaseAutoState || {};
+      const wrapStyle = 'margin-top:10px;padding:12px;background:rgba(0,0,0,0.18);border:1px solid var(--border, #2a2c3a);border-radius:6px;';
+      const titleStyle = 'font-size:11px;font-weight:600;color:var(--text, #e2e3e8);margin-bottom:4px;';
+      const helpStyle = 'font-size:10px;color:var(--text-dim, #8a8d9a);margin-bottom:10px;line-height:1.4;';
+      const inputStyle = 'flex:1;padding:6px 8px;background:var(--bg, #0f1017);color:var(--text, #e2e3e8);border:1px solid var(--border, #2a2c3a);border-radius:4px;font-family:monospace;font-size:12px;box-sizing:border-box;';
+      const btnStyle = 'padding:6px 14px;background:var(--accent, #7aa2f7);color:#000;border:none;border-radius:4px;font-weight:600;cursor:pointer;font-size:11px;';
+      const ghostBtnStyle = 'padding:6px 14px;background:transparent;color:var(--text-dim, #8a8d9a);border:1px solid var(--border, #2a2c3a);border-radius:4px;cursor:pointer;font-size:11px;';
+      const dividerStyle = 'text-align:center;font-size:10px;color:var(--text-dim, #8a8d9a);margin:10px 0 0;text-transform:uppercase;letter-spacing:0.05em;';
+      const errStyle = 'font-size:11px;color:var(--red, #f7768e);margin-top:8px;min-height:14px;line-height:1.4;';
+      const linkStyle = 'color:var(--accent, #7aa2f7);text-decoration:underline;';
+
+      let body;
+      if (s.picking && Array.isArray(s.projects)) {
+        if (s.projects.length === 0) {
+          body = `
+            <div style="${errStyle}">
+              Token accepted, but no projects were found on this account.
+              Create one at <a href="https://supabase.com/dashboard" target="_blank" rel="noopener" style="${linkStyle}">supabase.com/dashboard</a> and try again.
+            </div>
+            <button type="button" id="supabaseAutoBack" style="margin-top:10px;${ghostBtnStyle}">Use a different token</button>
+          `;
+        } else {
+          const opts = s.projects.map((p) => {
+            const id = escapeHtml(String((p && p.id) || ''));
+            const name = (p && p.name) || 'unnamed';
+            const region = p && p.region ? ` — ${p.region}` : '';
+            return `<option value="${id}">${escapeHtml(name + region)}</option>`;
+          }).join('');
+          body = `
+            <label style="display:block;font-size:11px;color:var(--text-dim, #8a8d9a);margin-bottom:4px;">Project</label>
+            <select id="supabaseAutoProject" style="${inputStyle}width:100%;font-family:inherit;">${opts}</select>
+            <div style="display:flex;gap:8px;margin-top:10px;">
+              <button type="button" id="supabaseAutoSelect" style="${btnStyle}">Use this project</button>
+              <button type="button" id="supabaseAutoBack" style="${ghostBtnStyle}">Use a different token</button>
+            </div>
+            <div id="supabaseAutoError" style="${errStyle}">${s.error ? escapeHtml(s.error) : ''}</div>
+          `;
+        }
+      } else {
+        body = `
+          <div style="display:flex;gap:8px;align-items:stretch;">
+            <input type="password" id="supabaseAutoPat" name="supabase_pat_one_time"
+                   autocomplete="new-password" spellcheck="false"
+                   autocapitalize="off" autocorrect="off"
+                   placeholder="sbp_..." aria-label="Supabase Personal Access Token"
+                   style="${inputStyle}">
+            <button type="button" id="supabaseAutoConnect" style="${btnStyle}">Connect</button>
+          </div>
+          <div id="supabaseAutoError" style="${errStyle}">${s.error ? escapeHtml(s.error) : ''}</div>
+        `;
+      }
+
+      return `
+        <div style="${wrapStyle}">
+          <div style="${titleStyle}">Faster: connect Supabase automatically</div>
+          <div style="${helpStyle}">
+            Paste a Supabase Personal Access Token and pick your project from a list — we'll fetch the credentials for you.
+            Mint a PAT at <a href="https://supabase.com/dashboard/account/tokens" target="_blank" rel="noopener" style="${linkStyle}">supabase.com/dashboard/account/tokens</a>.
+          </div>
+          ${body}
+        </div>
+        <div style="${dividerStyle}">— or paste credentials manually below —</div>
+      `;
+    }
+
+    function rerenderSetupTiersFromCache() {
+      if (lastSetupData) renderSetupTiers(lastSetupData);
+    }
+
+    async function handleSupabaseAutoConnect() {
+      const input = document.getElementById('supabaseAutoPat');
+      const errEl = document.getElementById('supabaseAutoError');
+      const btn = document.getElementById('supabaseAutoConnect');
+      const pat = ((input && input.value) || '').trim();
+      if (!pat) {
+        if (errEl) errEl.textContent = 'Paste a Personal Access Token to continue.';
+        return;
+      }
+      if (errEl) errEl.textContent = '';
+      if (btn) { btn.disabled = true; btn.textContent = 'Connecting…'; }
+      try {
+        const res = await fetch(`${API}/api/setup/supabase/connect`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ pat })
+        });
+        let data = {};
+        try { data = await res.json(); } catch { data = {}; }
+        if (res.ok && data && data.ok) {
+          const projects = Array.isArray(data.projects) ? data.projects : [];
+          // Hold the PAT in module-scope state only; never on `state`/`window`.
+          supabaseAutoState = { pat, projects, picking: true, error: null };
+          rerenderSetupTiersFromCache();
+          return;
+        }
+        const code = data && data.code;
+        let msg;
+        if (code === 'mcp_not_installed') {
+          msg = "The Supabase MCP isn't installed on this machine. Run `npx @jhizzard/termdeck-stack --tier 4` to install it, or paste credentials manually below.";
+        } else if (code === 'pat_invalid') {
+          const detail = (data && data.detail) || 'token rejected';
+          msg = `Token rejected: ${detail}. Mint a fresh PAT and try again.`;
+        } else if (code === 'mcp_timeout') {
+          msg = "Supabase didn't respond in time. Try again or paste credentials manually below.";
+        } else {
+          msg = (data && (data.error || data.detail)) || `Connect failed (HTTP ${res.status}). Paste credentials manually below.`;
+        }
+        if (errEl) errEl.textContent = msg;
+      } catch (err) {
+        if (errEl) errEl.textContent = `Request failed: ${err && err.message ? err.message : String(err)}`;
+      } finally {
+        if (btn) { btn.disabled = false; btn.textContent = 'Connect'; }
+      }
+    }
+
+    async function handleSupabaseAutoSelect() {
+      if (!supabaseAutoState || !supabaseAutoState.pat) return;
+      const sel = document.getElementById('supabaseAutoProject');
+      const errEl = document.getElementById('supabaseAutoError');
+      const btn = document.getElementById('supabaseAutoSelect');
+      const projectId = sel ? sel.value : '';
+      if (!projectId) {
+        if (errEl) errEl.textContent = 'Pick a project first.';
+        return;
+      }
+      if (errEl) errEl.textContent = '';
+      if (btn) { btn.disabled = true; btn.textContent = 'Configuring…'; }
+      // Snapshot the PAT locally so we can null out module state before the
+      // network call resolves; the snapshot only lives for the duration of
+      // this async function.
+      const patSnapshot = supabaseAutoState.pat;
+      try {
+        const res = await fetch(`${API}/api/setup/supabase/select`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ pat: patSnapshot, projectId })
+        });
+        let data = {};
+        try { data = await res.json(); } catch { data = {}; }
+        if (res.ok && data && data.ok) {
+          // Null out the PAT before doing anything else with the response.
+          supabaseAutoState = null;
+          await refreshSetupStatus();
+          return;
+        }
+        const detail = (data && (data.error || data.detail)) || `HTTP ${res.status}`;
+        if (errEl) {
+          errEl.textContent = `Couldn't finish setup: ${detail}. Paste credentials manually below if this keeps failing.`;
+        }
+      } catch (err) {
+        if (errEl) errEl.textContent = `Request failed: ${err && err.message ? err.message : String(err)}`;
+      } finally {
+        if (btn) { btn.disabled = false; btn.textContent = 'Use this project'; }
+      }
+    }
+
+    function handleSupabaseAutoBack() {
+      // Drop the PAT and any cached project list and re-render from scratch.
+      supabaseAutoState = null;
+      rerenderSetupTiersFromCache();
     }
 
     // Sprint 23 T2 — credential form for Tier 2.

package/packages/server/src/index.js

@@ -418,6 +418,226 @@ function createServer(config) {
     }
   });
 
+  // ── Sprint 25 T2 — Supabase MCP wizard endpoints ──────────────────────────
+  //
+  // Three thin orchestrators that let the Tier-2 setup wizard skip the manual
+  // 4-credential paste step. They sit on top of T1's `supabase-mcp.callTool`
+  // bridge plus the existing Sprint 23 `configure` + `migrate` flow. The PAT
+  // travels in the request body for the lifetime of the call only — it is
+  // never persisted, never echoed, and never logged.
+  let _supabaseMcp = null;
+  try {
+    _supabaseMcp = require('./setup/supabase-mcp');
+  } catch (_err) {
+    // T1's bridge module may not exist yet on a fresh checkout, or the user
+    // may not have `@supabase/mcp-server-supabase` on PATH. Either case
+    // surfaces as `code: 'mcp_not_installed'` at request time.
+  }
+  let _supabaseSelectInFlight = false;
+
+  function _mapMcpError(err) {
+    const code = err && (err.code || (err.cause && err.cause.code));
+    const msg = (err && err.message) || '';
+    if (code === 'mcp_not_installed' || code === 'ENOENT' || /not.*installed|cannot.*spawn|module not found/i.test(msg)) {
+      return {
+        status: 400,
+        body: { ok: false, code: 'mcp_not_installed', detail: 'run: npm install -g @supabase/mcp-server-supabase' }
+      };
+    }
+    if (code === 'mcp_timeout' || code === 'ETIMEDOUT' || /timeout|timed out/i.test(msg)) {
+      return { status: 504, body: { ok: false, code: 'mcp_timeout' } };
+    }
+    return { status: 401, body: { ok: false, code: 'pat_invalid', detail: msg || 'PAT verification failed' } };
+  }
+
+  function _ensureMcpAvailable(res) {
+    if (_supabaseMcp && typeof _supabaseMcp.callTool === 'function') return true;
+    res.status(400).json({
+      ok: false,
+      code: 'mcp_not_installed',
+      detail: 'run: npm install -g @supabase/mcp-server-supabase'
+    });
+    return false;
+  }
+
+  // POST /api/setup/supabase/connect — verify a PAT works by listing projects.
+  // We only return the count; the project list itself is fetched by /projects.
+  app.post('/api/setup/supabase/connect', async (req, res) => {
+    const pat = (req.body && typeof req.body.pat === 'string') ? req.body.pat : '';
+    if (!pat) {
+      return res.status(400).json({ ok: false, code: 'pat_invalid', detail: 'pat field is required' });
+    }
+    if (!_ensureMcpAvailable(res)) return;
+    try {
+      const result = await _supabaseMcp.callTool(pat, 'list_projects', {}, { timeoutMs: 6000 });
+      const list = Array.isArray(result)
+        ? result
+        : (Array.isArray(result && result.projects) ? result.projects : []);
+      console.log(`[setup] supabase/connect ok (${list.length} projects)`);
+      return res.json({ ok: true, projectCount: list.length });
+    } catch (err) {
+      const m = _mapMcpError(err);
+      console.warn(`[setup] supabase/connect failed: ${m.body.code}`);
+      return res.status(m.status).json(m.body);
+    }
+  });
+
+  // POST /api/setup/supabase/projects — return a stable-shape project list.
+  // Mapping isolates the wizard from MCP field-name churn.
+  app.post('/api/setup/supabase/projects', async (req, res) => {
+    const pat = (req.body && typeof req.body.pat === 'string') ? req.body.pat : '';
+    if (!pat) {
+      return res.status(400).json({ ok: false, code: 'pat_invalid', detail: 'pat field is required' });
+    }
+    if (!_ensureMcpAvailable(res)) return;
+    try {
+      const result = await _supabaseMcp.callTool(pat, 'list_projects', {}, { timeoutMs: 6000 });
+      const raw = Array.isArray(result)
+        ? result
+        : (Array.isArray(result && result.projects) ? result.projects : []);
+      const projects = raw.map((p) => ({
+        id: (p && (p.id || p.ref || p.project_id)) || '',
+        name: (p && p.name) || '',
+        region: (p && (p.region || p.region_name)) || null,
+        createdAt: (p && (p.createdAt || p.created_at)) || null,
+      }));
+      console.log(`[setup] supabase/projects ok (${projects.length} returned)`);
+      return res.json({ ok: true, projects });
+    } catch (err) {
+      const m = _mapMcpError(err);
+      console.warn(`[setup] supabase/projects failed: ${m.body.code}`);
+      return res.status(m.status).json(m.body);
+    }
+  });
+
+  // POST /api/setup/supabase/select — full chain: MCP → configure → migrate.
+  // Concurrency guarded by a module-scoped boolean — second call gets 409.
+  app.post('/api/setup/supabase/select', async (req, res) => {
+    if (_supabaseSelectInFlight) {
+      return res.status(409).json({ ok: false, code: 'select_in_flight', error: 'Supabase select already in progress' });
+    }
+    const pat = (req.body && typeof req.body.pat === 'string') ? req.body.pat : '';
+    const projectId = (req.body && typeof req.body.projectId === 'string') ? req.body.projectId.trim() : '';
+    if (!pat || !projectId) {
+      return res.status(400).json({ ok: false, code: 'bad_request', detail: 'pat and projectId are required' });
+    }
+    if (!_ensureMcpAvailable(res)) return;
+
+    _supabaseSelectInFlight = true;
+    try {
+      // 1. Pull credentials via MCP. Prefer the bundled tool if T1 ships one;
+      //    fall back to the four single-field tools so we are robust to either
+      //    bridge shape.
+      let creds;
+      try {
+        creds = await _supabaseMcp.callTool(pat, 'fetch_project_credentials', { projectId }, { timeoutMs: 8000 });
+      } catch (errBundle) {
+        const code = errBundle && errBundle.code;
+        const msg = (errBundle && errBundle.message) || '';
+        const isUnknownTool = code === 'unknown_tool' || /unknown.?tool|method not found|no such tool/i.test(msg);
+        if (!isUnknownTool) throw errBundle;
+        const [proj, anon, service, db] = await Promise.all([
+          _supabaseMcp.callTool(pat, 'get_project', { projectId }, { timeoutMs: 6000 }),
+          _supabaseMcp.callTool(pat, 'get_anon_key', { projectId }, { timeoutMs: 6000 }),
+          _supabaseMcp.callTool(pat, 'get_service_role_key', { projectId }, { timeoutMs: 6000 }),
+          _supabaseMcp.callTool(pat, 'get_database_url', { projectId }, { timeoutMs: 6000 }),
+        ]);
+        creds = {
+          url: (proj && (proj.url || proj.api_url)) || '',
+          anonKey: (anon && (anon.key || anon.anon_key)) || (typeof anon === 'string' ? anon : ''),
+          serviceRoleKey: (service && (service.key || service.service_role_key)) || (typeof service === 'string' ? service : ''),
+          databaseUrl: (db && (db.connectionString || db.url || db.database_url)) || (typeof db === 'string' ? db : ''),
+        };
+      }
+
+      const supabaseUrl = (creds && (creds.url || creds.supabaseUrl || creds.api_url)) || '';
+      const serviceRoleKey = (creds && (creds.serviceRoleKey || creds.service_role_key)) || '';
+      const databaseUrl = (creds && (creds.databaseUrl || creds.database_url)) || '';
+      const anonKey = (creds && (creds.anonKey || creds.anon_key)) || '';
+
+      if (!supabaseUrl || !serviceRoleKey || !databaseUrl) {
+        return res.status(502).json({
+          ok: false,
+          code: 'mcp_incomplete',
+          detail: 'MCP did not return all required credentials (url, service role key, database url)'
+        });
+      }
+
+      // 2. Hand off to existing /api/setup/configure via in-process loopback
+      //    fetch. This keeps Sprint 23's validators and writers as the single
+      //    source of truth — no validation logic is duplicated here.
+      const port = (config && config.port) || 3000;
+      const headers = { 'content-type': 'application/json' };
+      if (req.headers.authorization) headers.authorization = req.headers.authorization;
+
+      const openaiApiKey = (req.body && typeof req.body.openaiApiKey === 'string')
+        ? req.body.openaiApiKey
+        : (process.env.OPENAI_API_KEY || '');
+      const anthropicApiKey = (req.body && typeof req.body.anthropicApiKey === 'string')
+        ? req.body.anthropicApiKey
+        : (process.env.ANTHROPIC_API_KEY || '');
+
+      const configureRes = await fetch(`http://127.0.0.1:${port}/api/setup/configure`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+          supabaseUrl,
+          supabaseServiceRoleKey: serviceRoleKey,
+          databaseUrl,
+          openaiApiKey,
+          anthropicApiKey,
+          // anonKey is not part of the Sprint 23 contract — we hold it here
+          // for parity with future runtime needs but do not pass it on.
+        })
+      });
+      const configureBody = await configureRes.json().catch(() => ({}));
+      if (!configureRes.ok || configureBody.success === false) {
+        const status = configureRes.status >= 400 ? configureRes.status : 500;
+        return res.status(status).json({
+          ok: false,
+          code: 'configure_failed',
+          detail: configureBody.error || 'configure step failed',
+          validation: configureBody.validation || null,
+        });
+      }
+
+      // 3. Trigger /api/setup/migrate. Pass databaseUrl explicitly so we don't
+      //    depend on the migrate endpoint's dotenv refresh ordering.
+      const migrateRes = await fetch(`http://127.0.0.1:${port}/api/setup/migrate`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ databaseUrl })
+      });
+      const migrateBody = await migrateRes.json().catch(() => ({}));
+      if (!migrateRes.ok || migrateBody.ok === false) {
+        const status = migrateRes.status >= 400 ? migrateRes.status : 500;
+        return res.status(status).json({
+          ok: false,
+          code: 'migrate_failed',
+          detail: migrateBody.error || 'migrate step failed',
+          applied: migrateBody.applied || 0,
+        });
+      }
+
+      console.log(`[setup] supabase/select complete (${migrateBody.applied || 0} migrations applied)`);
+      // Mark the anonKey unused so lint stays clean — see comment above.
+      void anonKey;
+      return res.json({
+        ok: true,
+        configured: true,
+        migrated: true,
+        validation: configureBody.validation || null,
+        applied: migrateBody.applied || 0,
+      });
+    } catch (err) {
+      const m = _mapMcpError(err);
+      console.warn(`[setup] supabase/select failed: ${m.body.code}`);
+      return res.status(m.status).json(m.body);
+    } finally {
+      _supabaseSelectInFlight = false;
+    }
+  });
+
   // GET /api/sessions - list all active sessions
   app.get('/api/sessions', (req, res) => {
     res.json(sessions.getAll());

package/packages/server/src/session.js

@@ -55,7 +55,7 @@ const PATTERNS = {
   // tools (cat, ls, cd, rm, etc.) report filesystem misses in plain English
   // without ever emitting the ENOENT errno code. Flagged as a gap by Rumen's
   // first production kickstart insight on 2026-04-15.
-  error: /\b(error|Error|ERROR|exception|Exception|Traceback|fatal|FATAL|segmentation fault|panic|EACCES|ECONNREFUSED|ENOENT|command not found|undefined reference|cannot find module|failed with exit code|No such file or directory|Permission denied|\b5\d\d\b)\b/,
+  error: /(?:^|\n)\s*(?:Error:\s+\S|error:\s+\S|Traceback \(most recent call last\):|npm ERR!|error\[E\d+\]:|Uncaught Exception|Fatal:)/m,
   // Stricter line-anchored variant for Claude Code, whose tool output (grep
   // results, test logs, file contents) routinely mentions "Error" mid-line
   // without representing an actual failure of the agent itself.

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

@@ -0,0 +1,195 @@
+// Sprint 25 T1 — Supabase MCP bridge.
+//
+// Thin server-side wrapper that spawns @supabase/mcp-server-supabase as a
+// child process and speaks JSON-RPC 2.0 to it on stdio. One spawn per call —
+// no caching, no retries, no business logic. T2's wizard endpoints stack
+// listProjects / readCredentials helpers on top of this primitive.
+//
+// Zero new npm deps: child_process + JSON only.
+//
+// PAT discipline: the caller's Supabase Personal Access Token is passed via
+// the SUPABASE_ACCESS_TOKEN env var on the spawned child and is never logged,
+// echoed, or persisted on disk by this module.
+
+const { spawn, spawnSync } = require('child_process');
+
+const DEFAULT_TIMEOUT_MS = 8000;
+const PACKAGE_SPEC = '@supabase/mcp-server-supabase';
+const BINARY_NAME = 'mcp-server-supabase';
+
+// Detect whether @supabase/mcp-server-supabase can be invoked on this host.
+// Resolution order:
+//   1. A globally installed `mcp-server-supabase` binary on PATH.
+//   2. A locally cached npx package (probed without network install).
+// Both probes are short-running and synchronous-shaped — wrapped in a Promise
+// so the call site can stay async.
+async function detectMcp() {
+  const whichCmd = process.platform === 'win32' ? 'where' : 'which';
+  try {
+    const r = spawnSync(whichCmd, [BINARY_NAME], { encoding: 'utf-8' });
+    if (r.status === 0 && r.stdout && r.stdout.trim()) {
+      return { available: true, mode: 'binary' };
+    }
+  } catch (err) {
+    // `which` itself missing is unusual but not fatal — fall through to npx.
+  }
+
+  try {
+    // --no-install: only succeed if the package is already cached locally.
+    // Avoids surprising a user with a multi-MB install during a wizard probe.
+    const r = spawnSync('npx', ['--no-install', PACKAGE_SPEC, '--version'], {
+      encoding: 'utf-8',
+      timeout: 5000
+    });
+    if (r.status === 0) {
+      return { available: true, mode: 'npx' };
+    }
+  } catch (err) {
+    // npx absent (rare on Node installs) — fall through to "not installed".
+  }
+
+  return {
+    available: false,
+    mode: null,
+    error: `not installed; run: npm install -g ${PACKAGE_SPEC}`
+  };
+}
+
+function buildSpawnInvocation(mode) {
+  if (mode === 'binary') {
+    return { command: BINARY_NAME, args: [] };
+  }
+  // npx path — pin to @latest as the spec calls for, with -y to bypass the
+  // interactive "ok to proceed?" prompt that would otherwise hang stdio.
+  return { command: 'npx', args: ['-y', `${PACKAGE_SPEC}@latest`] };
+}
+
+// One-shot JSON-RPC tools/call. Spawns the MCP, writes a single request
+// envelope, awaits the matching response by id, then kills the child.
+//
+// Resolves with `response.result` on success.
+// Rejects with:
+//   - Error('mcp not installed: <hint>') if detectMcp() reports unavailable
+//   - Error('mcp timeout') if no response inside opts.timeoutMs
+//   - Error('mcp spawn failed: <msg>') on spawn-time errors (ENOENT, EACCES)
+//   - Error('mcp exited (code=<n>): <stderr tail>') if the child exits before
+//     a matching response arrives
+//   - Error(<rpc error message>) if the JSON-RPC response carries an `error`
+async function callTool(pat, method, params, opts) {
+  if (typeof pat !== 'string' || !pat) {
+    throw new Error('callTool requires a Supabase PAT string');
+  }
+  if (typeof method !== 'string' || !method) {
+    throw new Error('callTool requires an MCP method name');
+  }
+  const timeoutMs = (opts && Number.isFinite(opts.timeoutMs))
+    ? opts.timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+
+  const detect = await detectMcp();
+  if (!detect.available) {
+    throw new Error(`mcp not installed: ${detect.error}`);
+  }
+
+  const { command, args } = buildSpawnInvocation(detect.mode);
+
+  const id = Math.floor(Math.random() * 1e9) + 1;
+  const request = {
+    jsonrpc: '2.0',
+    id,
+    method: 'tools/call',
+    params: { name: method, arguments: params || {} }
+  };
+
+  return new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, args, {
+        // Pass PAT only via env — never via argv so it can't show up in `ps`.
+        env: { ...process.env, SUPABASE_ACCESS_TOKEN: pat },
+        stdio: ['pipe', 'pipe', 'pipe']
+      });
+    } catch (err) {
+      reject(new Error(`mcp spawn failed: ${err.message}`));
+      return;
+    }
+
+    let stdoutBuf = '';
+    let stderrBuf = '';
+    let settled = false;
+    let timer = null;
+
+    const cleanup = () => {
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+      try { child.stdin.end(); } catch (_e) { /* stdin already closed */ }
+      // SIGKILL — the MCP doesn't need a graceful shutdown for a one-shot.
+      try { child.kill('SIGKILL'); } catch (_e) { /* child already dead */ }
+    };
+
+    const settle = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      fn(value);
+    };
+
+    timer = setTimeout(() => {
+      settle(reject, new Error('mcp timeout'));
+    }, timeoutMs);
+
+    child.on('error', (err) => {
+      // 'error' fires for ENOENT / EACCES at spawn time and for write-after-end.
+      settle(reject, new Error(`mcp spawn failed: ${err.message}`));
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderrBuf += chunk.toString('utf-8');
+      // Cap so a chatty MCP can't blow memory on a stuck call.
+      if (stderrBuf.length > 8192) stderrBuf = stderrBuf.slice(-8192);
+    });
+
+    child.stdout.on('data', (chunk) => {
+      stdoutBuf += chunk.toString('utf-8');
+      let nl;
+      while ((nl = stdoutBuf.indexOf('\n')) !== -1) {
+        const line = stdoutBuf.slice(0, nl).trim();
+        stdoutBuf = stdoutBuf.slice(nl + 1);
+        if (!line) continue;
+        let msg;
+        try {
+          msg = JSON.parse(line);
+        } catch (_e) {
+          // Non-JSON noise (banner, log line) — ignore and keep buffering.
+          continue;
+        }
+        if (msg && msg.id === id) {
+          if (msg.error) {
+            const detail = msg.error.message || JSON.stringify(msg.error);
+            settle(reject, new Error(detail));
+          } else {
+            settle(resolve, msg.result);
+          }
+          return;
+        }
+      }
+    });
+
+    child.on('exit', (code, signal) => {
+      if (settled) return;
+      const tail = stderrBuf.slice(-512).trim();
+      const why = signal ? `signal=${signal}` : `code=${code}`;
+      settle(reject, new Error(`mcp exited (${why})${tail ? ': ' + tail : ''}`));
+    });
+
+    try {
+      child.stdin.write(JSON.stringify(request) + '\n');
+    } catch (err) {
+      settle(reject, new Error(`mcp stdin write failed: ${err.message}`));
+    }
+  });
+}
+
+module.exports = { callTool, detectMcp };