@jhizzard/termdeck 0.7.2 → 0.8.0

package/config/transcript-migration.sql

@@ -0,0 +1,34 @@
+-- termdeck_transcripts: append-only log of all PTY output
+-- Run with: psql -f config/transcript-migration.sql "$DATABASE_URL"
+-- Idempotent — safe to re-run.
+
+CREATE TABLE IF NOT EXISTS termdeck_transcripts (
+  id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  session_id    TEXT NOT NULL,              -- TermDeck session UUID
+  chunk_index   BIGINT NOT NULL,            -- monotonic per session, for ordering
+  content       TEXT NOT NULL,              -- raw PTY output (ANSI stripped)
+  raw_bytes     BIGINT NOT NULL DEFAULT 0,  -- byte count before stripping
+  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- Index for session replay (ordered chunks)
+CREATE INDEX IF NOT EXISTS idx_transcripts_session_order
+  ON termdeck_transcripts (session_id, chunk_index);
+
+-- Index for time-range queries (crash recovery: "what happened in the last hour?")
+CREATE INDEX IF NOT EXISTS idx_transcripts_created
+  ON termdeck_transcripts (created_at DESC);
+
+-- Full-text search for finding specific output across all sessions
+ALTER TABLE termdeck_transcripts
+  ADD COLUMN IF NOT EXISTS fts tsvector
+  GENERATED ALWAYS AS (to_tsvector('english', content)) STORED;
+
+CREATE INDEX IF NOT EXISTS idx_transcripts_fts
+  ON termdeck_transcripts USING GIN (fts);
+
+-- RLS: service-role only (no anon access to raw terminal output)
+ALTER TABLE termdeck_transcripts ENABLE ROW LEVEL SECURITY;
+
+-- Cleanup policy: transcripts older than 30 days get purged
+-- (implement as a pg_cron job or scheduled function, not in this migration)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.7.2",
+  "version": "0.8.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"
@@ -12,6 +12,7 @@
     "packages/client/public/**",
     "config/config.example.yaml",
     "config/secrets.env.example",
+    "config/transcript-migration.sql",
     "LICENSE",
     "README.md"
   ],

package/packages/cli/src/auto-orchestrate.js

@@ -1,26 +1,32 @@
-// Detection helper for Sprint 24: should `termdeck` (no subcommand)
-// auto-route through stack.js? Pure function, isolated for testability —
-// the dispatcher in index.js still owns the actual routing decision.
+// Detection helper for default-entry routing — does plain `termdeck`
+// (no subcommand) route through stack.js? Pure function, isolated for
+// testability — the dispatcher in index.js still owns the actual
+// routing decision.
+//
+// Sprint 24 policy (original): only auto-orchestrate when both
+// ~/.termdeck/secrets.env and ~/.termdeck/config.yaml exist AND either
+// mnestra.autoStart or rag.enabled is true. Fresh boxes fell through to
+// Tier-1-only.
+//
+// Sprint 36 policy (current): always orchestrate by default. Acceptance
+// criterion #2 of Sprint 36 (`docs/sprint-36-launcher-ui-parity/PLANNING.md`)
+// requires `npx @jhizzard/termdeck` to match `scripts/start.sh` step-by-step
+// on every machine, fresh or configured. stack.js handles the fresh-machine
+// case via `ensureFirstRunConfig()` — it auto-writes a minimal
+// ~/.termdeck/config.yaml on first run, then proceeds through Step 1/4–4/4
+// with mostly-SKIP statuses (no secrets → SKIP, no mnestra binary → SKIP,
+// no DATABASE_URL → SKIP, BOOT). That output mirrors what start.sh produces
+// on a fresh box.
+//
+// The escape hatch is the explicit `--no-stack` flag handled in index.js.
+//
+// The function signature stays the same so callers and tests don't break;
+// the body is just a constant now. Keeping the function (rather than
+// inlining the boolean) leaves a hook for future telemetry — e.g., emitting
+// "why we orchestrated" reasons — without another dispatcher rewrite.
 
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-function shouldAutoOrchestrate(homeDir) {
-  const home = homeDir || os.homedir();
-  const secretsPath = path.join(home, '.termdeck', 'secrets.env');
-  const configPath = path.join(home, '.termdeck', 'config.yaml');
-  if (!fs.existsSync(secretsPath) || !fs.existsSync(configPath)) return false;
-  let parsed;
-  try {
-    const yaml = require('yaml');
-    parsed = yaml.parse(fs.readFileSync(configPath, 'utf8')) || {};
-  } catch (_e) {
-    return false;
-  }
-  const mnestraAuto = parsed.mnestra && parsed.mnestra.autoStart === true;
-  const ragEnabled = parsed.rag && parsed.rag.enabled === true;
-  return Boolean(mnestraAuto || ragEnabled);
+function shouldAutoOrchestrate(_homeDir) {
+  return true;
 }
 
 module.exports = { shouldAutoOrchestrate };

package/packages/cli/src/doctor.js

@@ -1,22 +1,33 @@
-// `termdeck doctor` — Sprint 28 T2.
+// `termdeck doctor` — Sprint 28 T2 + Sprint 35 T3.
 //
-// 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.
+// Two-section diagnostic:
+//   Section 1 (Sprint 28) — npm version-check across the four stack packages,
+//     comparing installed (`npm ls -g`) to the registry's `dist-tags.latest`.
+//   Section 2 (Sprint 35) — Supabase schema state. Connects via DATABASE_URL
+//     from ~/.termdeck/secrets.env and verifies the tables / columns / RPCs /
+//     extensions that TermDeck + Mnestra + Rumen depend on.
 //
-// Module contract (per docs/sprint-28-update-signal/STATUS.md):
+// Read-only — no auto-fix. Each fail prints a remediation hint.
+//
+// Module contract:
 //   module.exports = function doctor(argv): Promise<exitCode>
-//     0 = all current
-//     1 = at least one update available
-//     2 = network/registry failure or unrecoverable error
+//     0 = all current and schema clean
+//     1 = at least one update available OR at least one schema gap
+//     2 = network/registry failure or DB-unreachable when --schema requested
+//
+// Flags:
+//   --json        Emit a parseable JSON document (shape extended for Sprint 35:
+//                 `{ exitCode, rows, schema? }` — `rows` retained for back-compat)
+//   --no-color    Strip ANSI codes
+//   --no-schema   Skip the Supabase schema section (used by tests + offline runs)
 //
-// `_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.
+// Test seams (monkey-patchable):
+//   _detectInstalled / _fetchLatest — npm probes (Sprint 28)
+//   _runSchemaCheck — Supabase probe (Sprint 35) — tests stub to `{ skipped: true }`
 
 const https = require('https');
 const { spawn } = require('child_process');
+const path = require('path');
 
 const STACK_PACKAGES = [
   '@jhizzard/termdeck',
@@ -200,9 +211,255 @@ function parseArgv(argv) {
   return {
     json: args.includes('--json'),
     noColor: args.includes('--no-color'),
+    noSchema: args.includes('--no-schema'),
+  };
+}
+
+// ── Sprint 35 T3: Supabase schema-check ────────────────────────────────────
+//
+// Connects via DATABASE_URL from ~/.termdeck/secrets.env and runs the schema
+// invariants TermDeck + Mnestra + Rumen depend on. Read-only — no DDL.
+//
+// Returns `{ skipped, sections, passed, total, hasGaps, error? }` where
+// `sections` is an ordered list of `{ name, checks: [{ label, status, hint? }] }`.
+// `status` is one of 'pass' | 'fail'. A `skipped: true` result short-circuits
+// rendering with an informational note.
+
+const SCHEMA_QUERIES = {
+  table: (name) =>
+    `SELECT EXISTS(SELECT 1 FROM information_schema.tables ` +
+    `WHERE table_schema = 'public' AND table_name = '${name}') AS ok`,
+  column: (table, column) =>
+    `SELECT EXISTS(SELECT 1 FROM information_schema.columns ` +
+    `WHERE table_schema = 'public' AND table_name = '${table}' ` +
+    `AND column_name = '${column}') AS ok`,
+  rpc: (name) =>
+    `SELECT EXISTS(SELECT 1 FROM pg_proc WHERE proname = '${name}') AS ok`,
+  extension: (name) =>
+    `SELECT EXISTS(SELECT 1 FROM pg_extension WHERE extname = '${name}') AS ok`,
+};
+
+// pgvector ships under extname 'vector' on Supabase; some older installs
+// or self-hosted boxes use 'pgvector' directly. Accept either.
+async function checkPgVector(client) {
+  try {
+    const r = await client.query(
+      "SELECT EXISTS(SELECT 1 FROM pg_extension WHERE extname IN ('vector', 'pgvector')) AS ok"
+    );
+    return r.rows && r.rows[0] && r.rows[0].ok === true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+async function probeSchema(client, sql) {
+  try {
+    const r = await client.query(sql);
+    return r.rows && r.rows[0] && r.rows[0].ok === true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+async function _runSchemaCheck(opts = {}) {
+  const optsObj = opts || {};
+  // Lazy-require so users running version-check-only never load pg / fs.
+  const fs = require('fs');
+  const os = require('os');
+  const SETUP_DIR = path.join(__dirname, '..', '..', 'server', 'src', 'setup');
+  let pgRunner;
+  let dotenv;
+  try {
+    pgRunner = require(path.join(SETUP_DIR, 'pg-runner'));
+    dotenv = require(path.join(SETUP_DIR, 'dotenv-io'));
+  } catch (err) {
+    return {
+      skipped: true,
+      reason: `setup helpers unavailable: ${err.message}`,
+      sections: [], passed: 0, total: 0, hasGaps: false,
+    };
+  }
+
+  const secretsPath = optsObj.secretsPath ||
+    path.join(os.homedir(), '.termdeck', 'secrets.env');
+  if (!fs.existsSync(secretsPath)) {
+    return {
+      skipped: true,
+      reason: `~/.termdeck/secrets.env not found — run \`termdeck init --mnestra\` first`,
+      sections: [], passed: 0, total: 0, hasGaps: false,
+    };
+  }
+  const secrets = optsObj.secrets || dotenv.readSecrets(secretsPath);
+  if (!secrets.DATABASE_URL) {
+    return {
+      skipped: true,
+      reason: `DATABASE_URL not set in ${secretsPath}`,
+      sections: [], passed: 0, total: 0, hasGaps: false,
+    };
+  }
+
+  let client = optsObj._pgClient || null;
+  let ownsClient = false;
+  if (!client) {
+    try {
+      client = await pgRunner.connect(secrets.DATABASE_URL);
+      ownsClient = true;
+    } catch (err) {
+      return {
+        skipped: false,
+        connectError: err.message,
+        sections: [], passed: 0, total: 0, hasGaps: true,
+      };
+    }
+  }
+
+  const sections = [
+    { name: 'Mnestra modern schema',  checks: [] },
+    { name: 'Mnestra legacy schema',  checks: [] },
+    { name: 'Transcript backup',      checks: [] },
+    { name: 'Rumen schema',           checks: [] },
+    { name: 'Postgres extensions',    checks: [] },
+  ];
+
+  try {
+    // Mnestra modern
+    const modern = sections[0].checks;
+    for (const t of ['memory_items', 'memory_sessions', 'memory_relationships']) {
+      modern.push({
+        label: `${t} table`,
+        status: (await probeSchema(client, SCHEMA_QUERIES.table(t))) ? 'pass' : 'fail',
+        hint: `run: termdeck init --mnestra (applies migrations 001–007)`,
+      });
+    }
+    modern.push({
+      label: `memory_items.source_session_id column (v0.6.5+)`,
+      status: (await probeSchema(client, SCHEMA_QUERIES.column('memory_items', 'source_session_id'))) ? 'pass' : 'fail',
+      hint: `migration 007 adds it — run: npm cache clean --force && npm i -g @jhizzard/termdeck@latest && termdeck init --mnestra --yes`,
+    });
+    for (const fn of ['match_memories', 'search_memories', 'memory_status_aggregation']) {
+      modern.push({
+        label: `${fn}() RPC`,
+        status: (await probeSchema(client, SCHEMA_QUERIES.rpc(fn))) ? 'pass' : 'fail',
+        hint: `migration 005/006 creates it — re-run: termdeck init --mnestra --yes`,
+      });
+    }
+
+    // Mnestra legacy (Sprint 35 T2 ships these via 008_legacy_rag_tables.sql)
+    const legacy = sections[1].checks;
+    for (const t of ['mnestra_session_memory', 'mnestra_project_memory', 'mnestra_developer_memory', 'mnestra_commands']) {
+      legacy.push({
+        label: `${t} table`,
+        status: (await probeSchema(client, SCHEMA_QUERIES.table(t))) ? 'pass' : 'fail',
+        hint: `run: termdeck init --mnestra --yes (applies migration 008 — Sprint 35)`,
+      });
+    }
+
+    // Transcript
+    sections[2].checks.push({
+      label: `termdeck_transcripts table`,
+      status: (await probeSchema(client, SCHEMA_QUERIES.table('termdeck_transcripts'))) ? 'pass' : 'fail',
+      hint: `run: psql "$DATABASE_URL" -f config/transcript-migration.sql`,
+    });
+
+    // Rumen — table existence and the created_at column drift Brad hit
+    const rumen = sections[3].checks;
+    for (const t of ['rumen_jobs', 'rumen_insights', 'rumen_questions']) {
+      const tableOk = await probeSchema(client, SCHEMA_QUERIES.table(t));
+      rumen.push({
+        label: `${t} table`,
+        status: tableOk ? 'pass' : 'fail',
+        hint: `run: termdeck init --rumen (applies rumen migration 001)`,
+      });
+      // Only check the column when the table exists — otherwise the column
+      // line is redundant noise.
+      if (tableOk) {
+        rumen.push({
+          label: `${t}.created_at column`,
+          status: (await probeSchema(client, SCHEMA_QUERIES.column(t, 'created_at'))) ? 'pass' : 'fail',
+          hint: `column drift detected — re-run: termdeck init --rumen`,
+        });
+      }
+    }
+
+    // Extensions — pg_cron / pg_net / pgvector / pg_trgm / pgcrypto
+    const exts = sections[4].checks;
+    const dashboardHint = (() => {
+      if (!secrets.SUPABASE_URL) return `enable in dashboard: Database → Extensions`;
+      const m = String(secrets.SUPABASE_URL).match(/https:\/\/([a-z0-9-]+)\.supabase\.(co|in)/i);
+      if (!m) return `enable in dashboard: Database → Extensions`;
+      return `enable: https://supabase.com/dashboard/project/${m[1]}/database/extensions`;
+    })();
+    for (const ext of ['pg_cron', 'pg_net', 'pg_trgm', 'pgcrypto']) {
+      exts.push({
+        label: `${ext}`,
+        status: (await probeSchema(client, SCHEMA_QUERIES.extension(ext))) ? 'pass' : 'fail',
+        hint: dashboardHint,
+      });
+    }
+    exts.push({
+      label: `pgvector (extname: vector)`,
+      status: (await checkPgVector(client)) ? 'pass' : 'fail',
+      hint: dashboardHint,
+    });
+  } finally {
+    if (ownsClient) {
+      try { await client.end(); } catch (_e) { /* ignore */ }
+    }
+  }
+
+  let passed = 0;
+  let total = 0;
+  for (const s of sections) {
+    for (const c of s.checks) {
+      total += 1;
+      if (c.status === 'pass') passed += 1;
+    }
+  }
+  return {
+    skipped: false,
+    sections,
+    passed,
+    total,
+    hasGaps: passed < total,
   };
 }
 
+function renderSchemaResult(result, c) {
+  const out = [];
+  out.push('');
+  out.push(c.bold('TermDeck stack — Supabase schema check'));
+  out.push('');
+  if (result.skipped) {
+    out.push(`  ${c.dim(`(skipped) ${result.reason}`)}`);
+    return out.join('\n');
+  }
+  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.')}`);
+    return out.join('\n');
+  }
+  for (const section of result.sections) {
+    out.push(`  ${c.bold(section.name)}`);
+    if (section.checks.length === 0) {
+      out.push(`    ${c.dim('(no checks ran)')}`);
+      continue;
+    }
+    for (const check of section.checks) {
+      if (check.status === 'pass') {
+        out.push(`    ${c.green('✓')} ${check.label}`);
+      } else {
+        out.push(`    ${c.yellow('✗')} ${check.label}`);
+        if (check.hint) {
+          out.push(`        ${c.dim(check.hint)}`);
+        }
+      }
+    }
+    out.push('');
+  }
+  out.push(`  ${result.passed}/${result.total} schema checks passed`);
+  return out.join('\n');
+}
+
 async function doctor(argv) {
   const opts = parseArgv(argv);
 
@@ -223,9 +480,24 @@ async function doctor(argv) {
     })
   );
 
-  // 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.
+  // Sprint 35 T3: schema check (skippable for tests / offline runs).
+  let schema = null;
+  if (!opts.noSchema) {
+    try {
+      schema = await module.exports._runSchemaCheck();
+    } catch (err) {
+      schema = {
+        skipped: false,
+        connectError: `unexpected error: ${err && err.message || err}`,
+        sections: [], passed: 0, total: 0, hasGaps: true,
+      };
+    }
+  }
+
+  // Exit-code priority: any network failure → 2; any update available OR
+  // schema gap → 1; else 0. Computed after all rows resolve so a single
+  // transient failure doesn't mask real updates in stdout. A schema connect
+  // error counts as 2 (same class as a registry fetch failure).
   let exitCode = 0;
   for (const r of rows) {
     if (r.status === STATUS.NETWORK_ERROR) {
@@ -234,9 +506,13 @@ async function doctor(argv) {
     }
     if (r.status === STATUS.UPDATE && exitCode < 1) exitCode = 1;
   }
+  if (schema && schema.connectError && exitCode < 2) exitCode = 2;
+  if (schema && !schema.skipped && schema.hasGaps && exitCode < 1) exitCode = 1;
 
   if (opts.json) {
-    process.stdout.write(JSON.stringify({ exitCode, rows }, null, 2) + '\n');
+    const payload = { exitCode, rows };
+    if (schema) payload.schema = schema;
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
     return exitCode;
   }
 
@@ -244,6 +520,9 @@ async function doctor(argv) {
   const c = makeColors(colorEnabled);
   process.stdout.write(renderTable(rows, c) + '\n');
   process.stdout.write(renderFooter(rows, exitCode) + '\n');
+  if (schema) {
+    process.stdout.write(renderSchemaResult(schema, c) + '\n');
+  }
   return exitCode;
 }
 
@@ -251,5 +530,6 @@ module.exports = doctor;
 module.exports._detectInstalled = _detectInstalled;
 module.exports._fetchLatest = _fetchLatest;
 module.exports._compareSemver = _compareSemver;
+module.exports._runSchemaCheck = _runSchemaCheck;
 module.exports.STACK_PACKAGES = STACK_PACKAGES;
 module.exports.STATUS = STATUS;

package/packages/cli/src/index.js

@@ -14,7 +14,92 @@
 const path = require('path');
 const fs = require('fs');
 const os = require('os');
-const { execSync } = require('child_process');
+const { exec, execSync } = require('child_process');
+
+// Sprint 35 T4: stale-port reclaim. If the target port is held by a previous
+// TermDeck instance (crash, runaway, prior `termdeck` left orphaned), kill it
+// and continue. If it's held by something else, print a clear error and exit
+// instead of letting `server.listen()` throw a generic EADDRINUSE.
+// Lifted from scripts/start.sh:127–154 so npm-installed users (who never see
+// start.sh) get the same recovery behavior.
+function reclaimStalePort(port) {
+  let pids = [];
+  try {
+    const out = execSync(`lsof -ti TCP:${port} -sTCP:LISTEN 2>/dev/null`, { encoding: 'utf8' });
+    pids = out.split(/\s+/).filter(Boolean);
+  } catch (_e) {
+    // lsof exits 1 when no PIDs match — empty case, not an error.
+    pids = [];
+  }
+  if (pids.length === 0) {
+    // Linux fallback for systems without lsof
+    try {
+      const out = execSync(`fuser -n tcp ${port} 2>/dev/null`, { encoding: 'utf8' });
+      pids = out.split(/\s+/).filter((s) => /^\d+$/.test(s));
+    } catch (_e) { pids = []; }
+  }
+  if (pids.length === 0) return;
+
+  let isTermDeck = false;
+  for (const pid of pids) {
+    try {
+      const cmd = execSync(`ps -o command= -p ${pid}`, { encoding: 'utf8' });
+      if (/packages\/cli\/src\/index\.js/.test(cmd) || /termdeck/i.test(cmd)) {
+        isTermDeck = true;
+        break;
+      }
+    } catch (_e) { /* PID gone between lsof and ps — ignore */ }
+  }
+
+  if (isTermDeck) {
+    // Liveness probe — never kill a TermDeck that's actively serving requests.
+    // A responsive /api/sessions means it's the orchestrator's live server, and
+    // killing it cascades to every child PTY. This was the actual root cause of
+    // four Sprint 36 server-kill incidents on 2026-04-27 (a sibling reclaimPort
+    // in stack.js had the same flaw and was already patched; this twin in the
+    // CLI entry was missed). Mirror of stack.js:isTermDeckLive.
+    let alreadyLive = false;
+    try {
+      const probe = execSync(`curl -sf -m 1.5 -o /dev/null -w "%{http_code}" http://127.0.0.1:${port}/api/sessions 2>/dev/null`, { encoding: 'utf8' });
+      if (probe.trim() === '200') alreadyLive = true;
+    } catch (_e) { /* curl missing or non-200 → treat as stale */ }
+
+    if (alreadyLive) {
+      console.log(`  \x1b[2m[port] :${port} held by live TermDeck (PIDs: ${pids.join(' ')}) — not killing. Use --port <other> for a second instance.\x1b[0m`);
+      process.exit(0); // graceful exit; don't try to bind a port that's already serving
+    }
+
+    console.log(`  \x1b[2m[port] Reclaiming :${port} from stale TermDeck (PIDs: ${pids.join(' ')})\x1b[0m`);
+    for (const pid of pids) {
+      try { process.kill(parseInt(pid, 10), 'SIGTERM'); } catch (_e) {}
+    }
+    try { execSync('sleep 1'); } catch (_e) {}
+    for (const pid of pids) {
+      try { process.kill(parseInt(pid, 10), 'SIGKILL'); } catch (_e) {}
+    }
+  } else {
+    console.error(`\n  \x1b[31m✗ Port ${port} is in use by a non-TermDeck process (PIDs: ${pids.join(' ')})\x1b[0m`);
+    console.error(`  \x1b[2mTry a different port: termdeck --port ${port + 1}\x1b[0m\n`);
+    process.exit(1);
+  }
+}
+
+// Sprint 35 T4: transcript-table-missing hint. If DATABASE_URL is set and
+// psql is on PATH, probe for termdeck_transcripts. Fire-and-forget so a slow
+// network round-trip to Supabase never blocks boot. Lifted from
+// scripts/start.sh:309–313.
+function checkTranscriptTableHint(databaseUrl) {
+  if (!databaseUrl) return;
+  try { execSync('command -v psql', { stdio: 'ignore' }); } catch (_e) { return; }
+  exec('psql "$DATABASE_URL" -c "SELECT 1 FROM termdeck_transcripts LIMIT 0"', {
+    env: { ...process.env, DATABASE_URL: databaseUrl },
+    timeout: 5000,
+  }, (err) => {
+    if (err) {
+      console.log(`  \x1b[33m[hint]\x1b[0m Transcript backup table missing. Run: \x1b[1mtermdeck doctor\x1b[0m (or psql $DATABASE_URL -f config/transcript-migration.sql)`);
+    }
+  });
+}
 
 // Parse CLI args
 const args = process.argv.slice(2);
@@ -130,7 +215,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
+    termdeck doctor             Diagnose stack — npm versions + Supabase schema (use --no-schema to skip the DB probe)
 
   Keyboard shortcuts (in browser):
     Ctrl+Shift+N                Focus prompt bar
@@ -164,6 +249,7 @@ const firstRun = !fs.existsSync(path.join(os.homedir(), '.termdeck', 'config.yam
 
 const config = loadConfig();
 if (flags.port) config.port = flags.port;
+else if (process.env.TERMDECK_PORT) config.port = parseInt(process.env.TERMDECK_PORT, 10);
 if (flags.sessionLogs) {
   config.sessionLogs = { ...(config.sessionLogs || {}), enabled: true };
   console.log('[cli] session logs enabled — writing to ~/.termdeck/sessions/ on panel exit');
@@ -174,6 +260,11 @@ const port = config.port || 3000;
 const host = config.host || '127.0.0.1';
 const url = `http://${host}:${port}`;
 
+// Sprint 35 T4: reclaim the port if a previous TermDeck is squatting on it,
+// or hard-stop with a useful hint if a non-TermDeck process holds it. Runs
+// before server.listen() so EADDRINUSE never bubbles up.
+reclaimStalePort(port);
+
 // Bind guardrail: refuse non-loopback without auth token
 const LOOPBACK = new Set(['127.0.0.1', 'localhost', '::1']);
 if (!LOOPBACK.has(host)) {
@@ -189,17 +280,20 @@ 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.
+// when RAG is off, when the MCP is detected, when the MCP config (canonical
+// ~/.claude.json or legacy ~/.claude/mcp.json) already declares a `supabase`
+// server, or when anything below throws.
+//
+// Sprint 36 T2: read order is canonical → legacy. Claude Code v2.1.119+ reads
+// only the canonical file; the legacy fallback covers users who haven't yet
+// migrated and pinned other tooling to the old path.
 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 { CLAUDE_MCP_PATH_CANONICAL, CLAUDE_MCP_PATH_LEGACY, readMcpServers } = require('./mcp-config');
+    for (const candidate of [CLAUDE_MCP_PATH_CANONICAL, CLAUDE_MCP_PATH_LEGACY]) {
+      const read = readMcpServers(candidate);
+      if (read.servers && read.servers.supabase) return null;
     }
     const { detectMcp } = require(path.join(__dirname, '..', '..', 'server', 'src', 'setup', 'supabase-mcp.js'));
     const result = await detectMcp();
@@ -229,10 +323,23 @@ server.listen(port, host, async () => {
   ╚══════════════════════════════════════╝
   `);
 
+  // Sprint 35 T4: RAG state line. Always-visible indicator of what mode the
+  // user is in — MCP-only (the new default after Sprint 35 T1) or full RAG
+  // writing to mnestra_*_memory tables. Dim line, single sentence.
+  if (config.rag && config.rag.enabled === true) {
+    console.log(`  \x1b[2mRAG: on — events syncing to mnestra_session_memory / mnestra_project_memory / mnestra_developer_memory\x1b[0m\n`);
+  } else {
+    console.log(`  \x1b[2mRAG: off (MCP-only mode) — toggle in dashboard at ${url}/#config to enable session/project/developer memory tables\x1b[0m\n`);
+  }
+
   if (firstRun) {
     console.log("  First run detected. Open http://localhost:3000 and click 'config' to set up.\n");
   }
 
+  // Sprint 35 T4: probe Supabase for the transcript backup table; print a
+  // hint if it's missing. Non-blocking — the result lands after the banner.
+  checkTranscriptTableHint(process.env.DATABASE_URL || (config.rag && config.rag.databaseUrl));
+
   // Run preflight health checks (non-blocking — warn but don't prevent startup)
   runPreflight(config).then((result) => {
     printHealthBanner(result);