@jhizzard/termdeck 0.7.3 → 0.8.0

package/package.json

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

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/index.js

@@ -52,6 +52,23 @@ function reclaimStalePort(port) {
   }
 
   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) {}
@@ -232,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');
@@ -262,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();

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

@@ -38,6 +38,12 @@ const {
   preconditions
 } = require(SETUP_DIR);
 
+const {
+  CLAUDE_MCP_PATH_CANONICAL,
+  readMcpServers,
+  writeMcpServers,
+} = require('./mcp-config');
+
 // Pinned fallback used only when the npm registry is unreachable. Bump this
 // when you republish @jhizzard/rumen and can't (or won't) rely on `npm view`
 // at deploy time. The wizard prefers the live registry answer — this value
@@ -470,28 +476,29 @@ async function applySchedule(projectRef, secrets, dryRun) {
   }
 }
 
-// Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json's Supabase MCP
+// Backfill SUPABASE_ACCESS_TOKEN into ~/.claude.json's Supabase MCP
 // server entry. Background: the meta-installer (`@jhizzard/termdeck-stack`)
 // writes `SUPABASE_ACCESS_TOKEN: 'SUPABASE_PAT_HERE'` as a literal
 // placeholder when it wires the Supabase MCP entry. The user is expected
 // to replace it after install. v0.6.4 unblocked the Rumen install path by
 // telling users to `export SUPABASE_ACCESS_TOKEN=sbp_...` in their shell —
 // but that token only got used for `supabase link`, never propagated into
-// `~/.claude/mcp.json`. So Brad's Claude Code was talking to a Supabase
-// MCP server with a placeholder token. He had to update the JSON file
-// manually. Reported 2026-04-26 — Brad's quote: "the token hadn't been
-// written to the Json file which we updated manually, but you may want
-// to put that in the patch at some point."
+// the MCP config. So Brad's Claude Code was talking to a Supabase MCP
+// server with a placeholder token. Reported 2026-04-26.
+//
+// Sprint 36 T2: default target moved from ~/.claude/mcp.json (legacy) to
+// ~/.claude.json (canonical — what Claude Code v2.1.119+ actually reads).
+// Internal write goes through writeMcpServers so the ~55 unrelated
+// top-level keys Claude Code stores in ~/.claude.json (oauthAccount,
+// projects, installMethod, …) are preserved byte-equivalent.
 //
-// This helper closes the loop. Idempotent and conservative:
-//   - Only runs if process.env.SUPABASE_ACCESS_TOKEN is set
+// Idempotent and conservative:
+//   - Only runs if a token is provided via env or arg
 //   - Only updates when the existing value is the literal placeholder
 //     'SUPABASE_PAT_HERE' — preserves any real token the user already set
-//   - No-op when ~/.claude/mcp.json doesn't exist (user never ran the
-//     meta-installer's Tier 4) or when there's no `supabase` MCP entry
+//   - No-op when the file doesn't exist or has no `supabase` entry
 //   - No-op (with a soft warning) when the JSON is malformed
-//   - Atomic write via tmp-and-rename; mode 0600 to match the file's
-//     existing permissions (it already holds the placeholder)
+//   - Atomic write via tmp-and-rename; mode 0600
 //   - All other mcpServers entries preserved verbatim
 //
 // Returns one of: { status: 'updated', path }, { status: 'already-set', path },
@@ -502,24 +509,15 @@ function wireAccessTokenInMcpJson({ token, mcpJsonPath, _testFs } = {}) {
   const tokenValue = token || process.env.SUPABASE_ACCESS_TOKEN;
   if (!tokenValue) return { status: 'no-token-in-env' };
 
-  const targetPath = mcpJsonPath || path.join(os.homedir(), '.claude', 'mcp.json');
+  const targetPath = mcpJsonPath || CLAUDE_MCP_PATH_CANONICAL;
   if (!fsImpl.existsSync(targetPath)) return { status: 'no-file' };
 
-  let raw;
-  try {
-    raw = fsImpl.readFileSync(targetPath, 'utf-8');
-  } catch (err) {
-    return { status: 'malformed', path: targetPath, error: err.message };
-  }
-
-  let cfg;
-  try {
-    cfg = JSON.parse(raw);
-  } catch (err) {
-    return { status: 'malformed', path: targetPath, error: err.message };
+  const read = readMcpServers(targetPath);
+  if (read.malformed) {
+    return { status: 'malformed', path: targetPath, error: read.error };
   }
 
-  const supabaseEntry = cfg && cfg.mcpServers && cfg.mcpServers.supabase;
+  const supabaseEntry = read.servers && read.servers.supabase;
   if (!supabaseEntry || typeof supabaseEntry !== 'object') {
     return { status: 'no-supabase-entry', path: targetPath };
   }
@@ -528,16 +526,15 @@ function wireAccessTokenInMcpJson({ token, mcpJsonPath, _testFs } = {}) {
   const current = supabaseEntry.env.SUPABASE_ACCESS_TOKEN;
   if (current === tokenValue) return { status: 'already-set', path: targetPath };
   if (current && current !== 'SUPABASE_PAT_HERE') {
-    // User has set a real token already — don't touch it.
     return { status: 'already-set', path: targetPath };
   }
 
   supabaseEntry.env.SUPABASE_ACCESS_TOKEN = tokenValue;
 
-  const tmpPath = `${targetPath}.tmp.${process.pid}`;
-  fsImpl.writeFileSync(tmpPath, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
-  fsImpl.renameSync(tmpPath, targetPath);
-  try { fsImpl.chmodSync(targetPath, 0o600); } catch (_e) { /* best-effort */ }
+  // writeMcpServers re-reads `targetPath` to preserve every top-level key
+  // (oauthAccount, projects, installMethod, …) that Claude Code owns. Only
+  // .mcpServers gets replaced with our mutated map.
+  writeMcpServers(targetPath, read.servers);
 
   return { status: 'updated', path: targetPath };
 }
@@ -608,14 +605,14 @@ async function main(argv) {
 
   if (!(await link(projectRef, flags.dryRun))) return 4;
 
-  // Backfill SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json now that
+  // Backfill SUPABASE_ACCESS_TOKEN into ~/.claude.json now that
   // `supabase link` succeeded (the token is verified-real). The
   // meta-installer wrote a literal 'SUPABASE_PAT_HERE' placeholder
   // there during Tier 4 install — this closes that loop.
   if (!flags.dryRun) {
     const r = wireAccessTokenInMcpJson();
     if (r.status === 'updated') {
-      step('Backfilled SUPABASE_ACCESS_TOKEN into ~/.claude/mcp.json...');
+      step(`Backfilled SUPABASE_ACCESS_TOKEN into ${r.path}...`);
       ok();
     } else if (r.status === 'malformed') {
       process.stderr.write(

package/packages/cli/src/mcp-config.js

@@ -0,0 +1,174 @@
+'use strict';
+
+// Canonical schema/CRUD for the Claude Code MCP server config.
+//
+// Sprint 36 T2: Claude Code v2.1.119+ reads its MCP config from
+// ~/.claude.json (top-level `mcpServers` key, alongside ~55 other internal
+// keys it owns). Earlier installs wrote to ~/.claude/mcp.json, which the
+// current Claude Code never reads. Fresh users hit this as "the install is
+// broken" — Mnestra was wired into the wrong file.
+//
+// This module is the single source of truth for path constants and the
+// read-modify-write helpers all installer/CLI code paths use. Two physical
+// copies exist (this one + packages/stack-installer/src/mcp-config.js) so
+// each published npm package stays self-contained. The stack-installer
+// copy must stay in sync with this one — same exports, same semantics.
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const CLAUDE_MCP_PATH_CANONICAL = path.join(os.homedir(), '.claude.json');
+const CLAUDE_MCP_PATH_LEGACY = path.join(os.homedir(), '.claude', 'mcp.json');
+
+// readMcpServers(filePath) → { servers, raw, missing, malformed, error }
+//
+//   servers   the .mcpServers map (always an object, never undefined)
+//   raw       the full parsed top-level object (for structure-preserving
+//             write-back). Empty object on missing/malformed.
+//   missing   true when the file doesn't exist
+//   malformed true when the file exists but JSON.parse failed
+//   error     parse error message when malformed
+function readMcpServers(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return { servers: {}, raw: {}, missing: true, malformed: false };
+  }
+  let text;
+  try {
+    text = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (text.trim() === '') {
+    return { servers: {}, raw: {}, missing: false, malformed: false };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: err.message };
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return { servers: {}, raw: {}, missing: false, malformed: true, error: 'top-level must be an object' };
+  }
+  const servers = (parsed.mcpServers && typeof parsed.mcpServers === 'object' && !Array.isArray(parsed.mcpServers))
+    ? parsed.mcpServers
+    : {};
+  return { servers, raw: parsed, missing: false, malformed: false };
+}
+
+// mergeMcpServers(currentServers, legacyServers) → merged map
+//
+// Current wins on key collision — current is the source of truth, legacy
+// is a migration source. Both inputs are tolerated as null/undefined.
+function mergeMcpServers(currentServers, legacyServers) {
+  const out = {};
+  const legacy = (legacyServers && typeof legacyServers === 'object') ? legacyServers : {};
+  const current = (currentServers && typeof currentServers === 'object') ? currentServers : {};
+  for (const [name, entry] of Object.entries(legacy)) {
+    out[name] = entry;
+  }
+  for (const [name, entry] of Object.entries(current)) {
+    out[name] = entry;
+  }
+  return out;
+}
+
+// writeMcpServers(filePath, servers) — atomic, structure-preserving.
+//
+// If the file exists with other top-level keys (the common case for
+// ~/.claude.json), only `.mcpServers` is replaced; everything else
+// survives byte-equivalent through JSON.parse → JSON.stringify. If the
+// file is missing or empty, writes a minimal `{ mcpServers: {...} }`.
+// Atomic via tmp-and-rename. Mode 0600.
+function writeMcpServers(filePath, servers) {
+  const existing = readMcpServers(filePath);
+  const next = (existing.malformed || existing.missing)
+    ? {}
+    : { ...existing.raw };
+  next.mcpServers = servers || {};
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, filePath);
+  try { fs.chmodSync(filePath, 0o600); } catch (_e) { /* best-effort */ }
+}
+
+// migrateLegacyIfPresent({ dryRun, canonicalPath, legacyPath })
+//   → { migrated, kept, wrote, canonicalPath, legacyPath, malformed }
+//
+//   migrated  array of server names copied from legacy → canonical
+//   kept      array of names that existed in both (canonical wins,
+//             legacy version skipped)
+//   wrote     true if the canonical file was written
+//   malformed { canonical?: error, legacy?: error } when either parse failed
+//
+// Idempotent: a second invocation with no new legacy entries returns
+// migrated: []. Never deletes or modifies the legacy file.
+function migrateLegacyIfPresent(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const canonicalPath = opts.canonicalPath || CLAUDE_MCP_PATH_CANONICAL;
+  const legacyPath = opts.legacyPath || CLAUDE_MCP_PATH_LEGACY;
+
+  const canonical = readMcpServers(canonicalPath);
+  const legacy = readMcpServers(legacyPath);
+
+  const malformed = {};
+  if (canonical.malformed) malformed.canonical = canonical.error || true;
+  if (legacy.malformed) malformed.legacy = legacy.error || true;
+
+  if (legacy.missing || legacy.malformed) {
+    return {
+      migrated: [],
+      kept: [],
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  const migrated = [];
+  const kept = [];
+  const merged = { ...canonical.servers };
+  for (const [name, entry] of Object.entries(legacy.servers)) {
+    if (Object.prototype.hasOwnProperty.call(canonical.servers, name)) {
+      kept.push(name);
+    } else {
+      merged[name] = entry;
+      migrated.push(name);
+    }
+  }
+
+  if (migrated.length === 0) {
+    return {
+      migrated: [],
+      kept,
+      wrote: false,
+      canonicalPath,
+      legacyPath,
+      malformed: Object.keys(malformed).length ? malformed : undefined,
+    };
+  }
+
+  if (!dryRun) writeMcpServers(canonicalPath, merged);
+
+  return {
+    migrated,
+    kept,
+    wrote: !dryRun,
+    canonicalPath,
+    legacyPath,
+    malformed: Object.keys(malformed).length ? malformed : undefined,
+  };
+}
+
+module.exports = {
+  CLAUDE_MCP_PATH_CANONICAL,
+  CLAUDE_MCP_PATH_LEGACY,
+  readMcpServers,
+  mergeMcpServers,
+  writeMcpServers,
+  migrateLegacyIfPresent,
+};

package/packages/cli/src/stack.js

@@ -22,6 +22,16 @@ const SECRETS_FILE = path.join(CONFIG_DIR, 'secrets.env');
 const DEFAULT_MNESTRA_PORT = parseInt(process.env.MNESTRA_PORT || '37778', 10);
 const MNESTRA_LOG = path.join(os.tmpdir(), 'termdeck-mnestra.log');
 
+// Sprint 36: Claude Code v2.1.119+ reads MCP servers from ~/.claude.json
+// (canonical). The legacy ~/.claude/mcp.json is still accepted by older
+// versions. Detection checks BOTH; T2 migrates writes to the canonical path.
+// Exported so T2 (init-rumen, stack-installer, supabase-mcp) and any other
+// caller stays in sync — single source of truth for "where does Claude Code
+// look for MCP entries today".
+const CLAUDE_MCP_PATH_CANONICAL = path.join(HOME, '.claude.json');
+const CLAUDE_MCP_PATH_LEGACY = path.join(HOME, '.claude', 'mcp.json');
+const CLAUDE_MCP_PATHS = [CLAUDE_MCP_PATH_CANONICAL, CLAUDE_MCP_PATH_LEGACY];
+
 const ANSI = {
   green: '\x1b[32m', red: '\x1b[31m', yellow: '\x1b[33m', blue: '\x1b[34m',
   dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m',
@@ -51,6 +61,23 @@ function subNote(msg) {
   process.stdout.write(`  ${ANSI.dim}└ ${msg}${ANSI.reset}\n`);
 }
 
+// Sprint 36: scan both Claude Code MCP config paths for a Mnestra entry.
+// Returns true if either file parses and contains the substring "mnestra"
+// anywhere in its JSON (covers top-level mcpServers.mnestra AND per-project
+// blocks). Malformed JSON or missing files count as "no entry" — the hint
+// will fire and tell the user to run the installer, which is the desired
+// recovery for both states.
+function hasMnestraMcpEntry() {
+  for (const p of CLAUDE_MCP_PATHS) {
+    if (!fs.existsSync(p)) continue;
+    try {
+      const j = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (JSON.stringify(j).includes('mnestra')) return true;
+    } catch (_e) { /* malformed — skip, treat as missing */ }
+  }
+  return false;
+}
+
 // ── Args ─────────────────────────────────────────────────────────────
 
 function parseArgs(argv) {
@@ -181,11 +208,32 @@ function isPidTermDeck(pid) {
   return /packages\/cli\/src\/index\.js|termdeck/.test(r.stdout || '');
 }
 
+// Liveness probe — a TermDeck that answers /api/sessions with a JSON array is
+// not stale; it's the orchestrator's live server, and killing it cascades to
+// every child PTY. On 2026-04-27 this caused two Sprint 36 server-kill
+// incidents (lane workers triggering reclaimPort against the live :3000).
+async function isTermDeckLive(port) {
+  try {
+    const j = await httpJson(`http://localhost:${port}/api/sessions`, 1500);
+    return Array.isArray(j);
+  } catch (_e) {
+    return false;
+  }
+}
+
 async function reclaimPort(port) {
   const pids = lsofPids(port);
   if (pids.length === 0) return { reclaimed: false, blockerPids: [] };
   const termdeckPids = pids.filter(isPidTermDeck);
   if (termdeckPids.length === 0) return { reclaimed: false, blockerPids: pids };
+
+  // Self-recognition guard: never kill a responsive TermDeck. Use --port to
+  // start a second instance instead.
+  if (await isTermDeckLive(port)) {
+    subNote(`TermDeck on port ${port} is live (PIDs: ${termdeckPids.join(' ')}) — not killing. Use --port <other> to start a second instance.`);
+    return { reclaimed: false, blockerPids: termdeckPids, alreadyLive: true };
+  }
+
   for (const pid of termdeckPids) {
     try { process.kill(pid, 'SIGTERM'); } catch (_e) { /* already dead */ }
   }
@@ -449,17 +497,11 @@ async function main(rawArgs) {
 
   const mnestra = await startMnestra({ skip: args.noMnestra });
 
-  // MCP config hint
-  if (mnestra.active) {
-    const mcpPath = path.join(HOME, '.claude', 'mcp.json');
-    let needsHint = !fs.existsSync(mcpPath);
-    if (!needsHint) {
-      try {
-        const j = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
-        if (!JSON.stringify(j).includes('mnestra')) needsHint = true;
-      } catch (_e) { needsHint = true; }
-    }
-    if (needsHint) subNote(`Hint: add a 'mnestra' entry to ~/.claude/mcp.json for Claude Code`);
+  // Sprint 36: MCP-absence hint. Claude Code v2.1.119+ reads from
+  // ~/.claude.json; legacy versions read ~/.claude/mcp.json. Mnestra is
+  // "wired" if EITHER file mentions it — otherwise the hint fires.
+  if (mnestra.active && !hasMnestraMcpEntry()) {
+    subNote(`TermDeck doesn't see Mnestra wired in Claude Code yet. Run: npx @jhizzard/termdeck-stack`);
   }
 
   const rumen = await checkRumen();
@@ -482,3 +524,11 @@ module.exports = function (argv) {
     return 1;
   });
 };
+
+// Sprint 36: shared MCP-config path constants. Other CLI/installer modules
+// (T2's lane: init-rumen.js, stack-installer, supabase-mcp.js) import from
+// here so the canonical-vs-legacy decision lives in exactly one file.
+module.exports.CLAUDE_MCP_PATH_CANONICAL = CLAUDE_MCP_PATH_CANONICAL;
+module.exports.CLAUDE_MCP_PATH_LEGACY = CLAUDE_MCP_PATH_LEGACY;
+module.exports.CLAUDE_MCP_PATHS = CLAUDE_MCP_PATHS;
+module.exports.hasMnestraMcpEntry = hasMnestraMcpEntry;

package/packages/client/public/app.js

@@ -25,6 +25,7 @@
     async function init() {
       // Load config
       state.config = await api('GET', '/api/config');
+      updateRagIndicator();
 
       // Populate project dropdown
       const sel = document.getElementById('promptProject');
@@ -247,6 +248,16 @@
             case 'status_broadcast':
               updateGlobalStats(msg.sessions);
               break;
+            case 'config_changed':
+              // Sprint 36 T3 Deliverable A: server-broadcast on PATCH /api/config.
+              // Each open panel WebSocket receives one copy; the handler is
+              // idempotent so multiple receipts settle the same state.
+              if (msg.config) {
+                state.config = { ...state.config, ...msg.config };
+                if (typeof renderSettingsPanel === 'function') renderSettingsPanel();
+                if (typeof updateRagIndicator === 'function') updateRagIndicator();
+              }
+              break;
           }
         } catch (err) { console.error('[client] ws message parse failed:', err); }
       };
@@ -2299,8 +2310,17 @@
       // Explicitly show the spotlight. CSS default is `display:none` so the
       // 9999px box-shadow doesn't darken the page before/after a tour runs.
       document.getElementById('tourSpotlight').style.display = 'block';
-      await ensurePanelForTour();
-      renderTourStep();
+      // Defensive cleanup: if ensurePanelForTour or renderTourStep throws
+      // after the spotlight is shown, the 9999px box-shadow stays up with no
+      // tooltip on top — that's the "dark veil" symptom users hit with no
+      // visible way out. Roll back to a clean state on any failure.
+      try {
+        await ensurePanelForTour();
+        renderTourStep();
+      } catch (err) {
+        console.error('[tour] start failed, rolling back:', err);
+        endTour();
+      }
     }
 
     function nextTourStep() {
@@ -2523,6 +2543,7 @@
             <button type="button" class="setup-close" id="setupClose" aria-label="Close">×</button>
           </header>
           <div class="setup-body">
+            <div class="setup-settings" id="setupSettings"></div>
             <div class="setup-tiers" id="setupTiers">
               <div class="setup-loading">Checking tier status…</div>
             </div>
@@ -2553,6 +2574,7 @@
       ensureSetupModal();
       document.getElementById('setupModal').classList.add('open');
       setupModalOpen = true;
+      renderSettingsPanel();
       await refreshSetupStatus();
     }
 
@@ -2562,6 +2584,96 @@
       setupModalOpen = false;
     }
 
+    // ===== Settings panel inside the setup modal (Sprint 36 T3 Deliverable A) =====
+    // Renders the writable subset of /api/config — currently just the RAG toggle.
+    // Body is mutated in place; the panel is idempotent so config_changed WS
+    // events can call it without reflow flicker.
+    function renderSettingsPanel() {
+      const el = document.getElementById('setupSettings');
+      if (!el) return;
+      const cfg = state.config || {};
+      const intent = !!cfg.ragConfigEnabled;
+      const effective = !!cfg.ragEnabled;
+      const supabaseConfigured = !!cfg.ragSupabaseConfigured;
+
+      // Mismatch: user enabled RAG in config but Supabase isn't wired → show
+      // a hint so the toggle's "ON but not pushing" state is explainable.
+      const mismatch = intent && !effective && !supabaseConfigured;
+
+      const offCopy = 'MCP-only mode. Memory tools available through Claude Code; the in-CLI <code>termdeck flashback</code> command and the hybrid search are disabled. Faster boot, slimmer surface.';
+      const onCopy = 'Enables <code>termdeck flashback</code> and the in-CLI hybrid search. Requires a Mnestra connection at boot — adds a few hundred ms to startup.';
+
+      el.innerHTML = `
+        <div class="settings-section">
+          <h4 class="settings-heading">RAG mode</h4>
+          <div class="settings-row">
+            <label class="toggle" for="settingsRagToggle">
+              <input type="checkbox" id="settingsRagToggle" ${intent ? 'checked' : ''}>
+              <span class="toggle-track" aria-hidden="true"><span class="toggle-thumb"></span></span>
+              <span class="toggle-label">${intent ? 'On' : 'Off'}</span>
+            </label>
+            <p class="settings-copy">${intent ? onCopy : offCopy}</p>
+          </div>
+          ${mismatch ? `
+            <div class="settings-warn">
+              RAG is enabled in <code>config.yaml</code> but Supabase isn't configured yet, so it isn't actually pushing.
+              Configure Tier 2 below or run <code>npx @jhizzard/termdeck-stack</code>.
+            </div>
+          ` : ''}
+        </div>
+      `;
+
+      const toggle = document.getElementById('settingsRagToggle');
+      if (toggle) {
+        toggle.addEventListener('change', async (e) => {
+          const desired = !!e.target.checked;
+          // Optimistic UI: lock the toggle while the round-trip is in flight.
+          toggle.disabled = true;
+          try {
+            const updated = await api('PATCH', '/api/config', { rag: { enabled: desired } });
+            state.config = { ...state.config, ...updated };
+            renderSettingsPanel();
+            updateRagIndicator();
+          } catch (err) {
+            console.error('[settings] PATCH /api/config failed:', err);
+            // Revert: refetch and re-render.
+            try {
+              state.config = await api('GET', '/api/config');
+              renderSettingsPanel();
+            } catch {}
+          } finally {
+            const t = document.getElementById('settingsRagToggle');
+            if (t) t.disabled = false;
+          }
+        });
+      }
+    }
+
+    // Topbar RAG indicator. The #stat-rag stub in index.html was hidden by
+    // Sprint 9 T2; re-purpose it as a live state line so users can see, at a
+    // glance, what the toggle is doing without opening Settings each time.
+    function updateRagIndicator() {
+      const el = document.getElementById('stat-rag');
+      if (!el) return;
+      const cfg = state.config || {};
+      const intent = !!cfg.ragConfigEnabled;
+      const effective = !!cfg.ragEnabled;
+      el.style.display = '';
+      if (effective) {
+        el.textContent = 'RAG · on';
+        el.className = 'topbar-stat rag-on';
+        el.title = 'Mnestra hybrid search + termdeck flashback enabled';
+      } else if (intent) {
+        el.textContent = 'RAG · pending';
+        el.className = 'topbar-stat rag-pending';
+        el.title = 'RAG enabled in config.yaml but Supabase not wired — see Settings';
+      } else {
+        el.textContent = 'RAG · mcp-only';
+        el.className = 'topbar-stat rag-off';
+        el.title = 'MCP-only mode; toggle in Settings to enable';
+      }
+    }
+
     async function refreshSetupStatus() {
       const tiersEl = document.getElementById('setupTiers');
       const subtitle = document.getElementById('setupSubtitle');

package/packages/client/public/style.css

@@ -2002,6 +2002,127 @@
       justify-content: center;
     }
     .setup-modal.open { display: flex; }
+
+    /* Settings panel inside the setup modal (Sprint 36 T3 Deliverable A) */
+    .setup-settings {
+      padding: 0 0 16px;
+      margin-bottom: 14px;
+      border-bottom: 1px solid var(--tg-border);
+    }
+    .settings-section {
+      display: flex;
+      flex-direction: column;
+      gap: 6px;
+    }
+    .settings-heading {
+      margin: 0;
+      font-size: 12px;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--tg-text-dim);
+      font-family: var(--tg-sans);
+    }
+    .settings-row {
+      display: grid;
+      grid-template-columns: 120px 1fr;
+      gap: 14px;
+      align-items: start;
+    }
+    .settings-copy {
+      margin: 0;
+      font-size: 12px;
+      line-height: 1.45;
+      color: var(--tg-text);
+    }
+    .settings-copy code {
+      font-family: var(--tg-mono);
+      font-size: 11px;
+      background: var(--tg-bg);
+      padding: 1px 5px;
+      border-radius: 3px;
+    }
+    .settings-warn {
+      margin-top: 4px;
+      padding: 8px 10px;
+      font-size: 12px;
+      line-height: 1.4;
+      color: var(--tg-text);
+      background: rgba(224, 175, 104, 0.10);
+      border: 1px solid var(--tg-amber);
+      border-radius: 4px;
+    }
+    .settings-warn code {
+      font-family: var(--tg-mono);
+      font-size: 11px;
+      background: var(--tg-bg);
+      padding: 1px 5px;
+      border-radius: 3px;
+    }
+    /* iOS-style toggle. The native checkbox is visually hidden but stays in
+       the tab order so keyboard + screen reader navigation still work. */
+    .toggle {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      cursor: pointer;
+      user-select: none;
+    }
+    .toggle input[type="checkbox"] {
+      position: absolute;
+      opacity: 0;
+      width: 1px;
+      height: 1px;
+      pointer-events: none;
+    }
+    .toggle-track {
+      position: relative;
+      display: inline-block;
+      width: 36px;
+      height: 20px;
+      background: var(--tg-border);
+      border-radius: 999px;
+      transition: background 0.15s ease;
+    }
+    .toggle-thumb {
+      position: absolute;
+      top: 2px;
+      left: 2px;
+      width: 16px;
+      height: 16px;
+      background: var(--tg-text-bright);
+      border-radius: 50%;
+      transition: transform 0.15s ease, background 0.15s ease;
+    }
+    .toggle input[type="checkbox"]:checked + .toggle-track {
+      background: var(--tg-green);
+    }
+    .toggle input[type="checkbox"]:checked + .toggle-track .toggle-thumb {
+      transform: translateX(16px);
+      background: var(--tg-bg);
+    }
+    .toggle input[type="checkbox"]:focus-visible + .toggle-track {
+      outline: 2px solid var(--tg-accent);
+      outline-offset: 2px;
+    }
+    .toggle input[type="checkbox"]:disabled + .toggle-track {
+      opacity: 0.5;
+    }
+    .toggle-label {
+      font-size: 12px;
+      color: var(--tg-text);
+      font-family: var(--tg-mono);
+    }
+    /* Topbar #stat-rag — re-purposed as a live RAG state line */
+    .topbar-stat.rag-on {
+      color: var(--tg-green);
+      font-weight: 500;
+    }
+    .topbar-stat.rag-pending {
+      color: var(--tg-amber);
+    }
+    .topbar-stat.rag-off {
+      color: var(--tg-text-dim);
+    }
     .setup-backdrop {
       position: absolute;
       inset: 0;

package/packages/server/src/config.js

@@ -298,11 +298,107 @@ function addProject({ name, path: projectPath, defaultTheme, defaultCommand }) {
   return parsed.projects;
 }
 
+// Apply a structural patch to ~/.termdeck/config.yaml. Sprint 36 introduces
+// this for the dashboard RAG toggle (PATCH /api/config) but the helper is
+// generic — pass a deep partial of the config tree, every leaf in `patch` that
+// matches the whitelist gets written through. Returns the parsed-from-disk
+// post-write tree (NOT post-substitution; we only persist user-authored values
+// here, never substituted secrets).
+//
+// Whitelist deliberately tight. Only fields a UI can safely flip live belong
+// here. Adding a new field is an explicit one-line edit (vs. a freeform writer
+// that would let a buggy/malicious client change `port`, `shell`, or projects).
+//
+// Comments and formatting in config.yaml are NOT preserved — same trade-off
+// as `addProject`. The yaml package's parseDocument API can preserve comments
+// but we'd need to migrate addProject too for consistency; that's a follow-up.
+const UPDATABLE_PATHS = new Set([
+  'rag.enabled'
+]);
+
+function flattenPatch(obj, prefix = '') {
+  const out = [];
+  if (obj == null || typeof obj !== 'object' || Array.isArray(obj)) return out;
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v != null && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(...flattenPatch(v, key));
+    } else {
+      out.push([key, v]);
+    }
+  }
+  return out;
+}
+
+function setPath(obj, segs, value) {
+  let cur = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    const s = segs[i];
+    if (cur[s] == null || typeof cur[s] !== 'object') cur[s] = {};
+    cur = cur[s];
+  }
+  cur[segs[segs.length - 1]] = value;
+}
+
+function updateConfig(patch, configPath = CONFIG_PATH) {
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) {
+    throw new Error('updateConfig: patch must be a plain object');
+  }
+
+  const flat = flattenPatch(patch);
+  if (flat.length === 0) {
+    throw new Error('updateConfig: patch is empty');
+  }
+
+  for (const [key, val] of flat) {
+    if (!UPDATABLE_PATHS.has(key)) {
+      throw new Error(`updateConfig: ${key} is not in the updatable whitelist`);
+    }
+    if (key === 'rag.enabled' && typeof val !== 'boolean') {
+      throw new Error('updateConfig: rag.enabled must be a boolean');
+    }
+  }
+
+  const yaml = require('yaml');
+  let parsed = {};
+  if (fs.existsSync(configPath)) {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    try {
+      parsed = yaml.parse(raw) || {};
+    } catch (err) {
+      throw new Error(`config.yaml is not valid YAML — refusing to overwrite: ${err.message}`);
+    }
+  }
+
+  for (const [key, val] of flat) {
+    setPath(parsed, key.split('.'), val);
+  }
+
+  if (fs.existsSync(configPath)) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const bak = `${configPath}.${ts}.bak`;
+    try {
+      fs.copyFileSync(configPath, bak);
+    } catch (err) {
+      console.warn('[config] Could not write backup before updateConfig:', err.message);
+    }
+  }
+
+  const out = yaml.stringify(parsed);
+  fs.writeFileSync(configPath, out, 'utf-8');
+  console.log(`[config] updateConfig wrote ${flat.map(([k]) => k).join(', ')}`);
+
+  return parsed;
+}
+
 module.exports = {
   loadConfig,
   addProject,
+  updateConfig,
   // exported for tests / introspection
   _parseDotenv: parseDotenv,
   _substituteEnv: substituteEnv,
+  _flattenPatch: flattenPatch,
+  _UPDATABLE_PATHS: UPDATABLE_PATHS,
   _paths: { CONFIG_DIR, CONFIG_PATH, SECRETS_PATH }
 };

package/packages/server/src/index.js

@@ -61,7 +61,7 @@ const { TranscriptWriter } = require('./transcripts');
 const { createHealthHandler, runPreflight } = require('./preflight');
 const { getFullHealth } = require('./health');
 const { themes, statusColors } = require('./themes');
-const { loadConfig, addProject } = require('./config');
+const { loadConfig, addProject, updateConfig } = require('./config');
 const { createAuthMiddleware, verifyWebSocketUpgrade, hasAuth } = require('./auth');
 
 function createServer(config) {
@@ -1069,16 +1069,64 @@ function createServer(config) {
     res.json(t);
   });
 
-  // GET /api/config - current config (sanitized)
-  app.get('/api/config', (req, res) => {
-    res.json({
+  // Public-shape helper so GET and PATCH return the same envelope.
+  function publicConfigPayload() {
+    return {
       projects: config.projects || {},
       defaultTheme: config.defaultTheme,
+      // ragEnabled is the EFFECTIVE state (after credential eligibility).
+      // ragConfigEnabled is the user's intent from config.yaml. The dashboard
+      // toggle reads ragConfigEnabled (intent) but renders a warning when it
+      // diverges from ragEnabled (e.g. enabled in config but Supabase creds
+      // missing → effective state stays off).
       ragEnabled: rag.enabled,
+      ragConfigEnabled: !!(config.rag && config.rag.enabled),
+      ragSupabaseConfigured: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey),
       aiQueryAvailable: !!(config.rag?.supabaseUrl && config.rag?.supabaseKey && config.rag?.openaiApiKey),
       statusColors,
       firstRun
-    });
+    };
+  }
+
+  // GET /api/config - current config (sanitized)
+  app.get('/api/config', (req, res) => {
+    res.json(publicConfigPayload());
+  });
+
+  // PATCH /api/config - update writable config fields. Sprint 36 T3 Deliverable A.
+  // Body: { rag: { enabled: boolean } } — the only currently writable path.
+  // Persists to ~/.termdeck/config.yaml, live-updates the in-memory integration,
+  // and broadcasts a `config_changed` WS event so all open dashboards re-render
+  // their RAG indicator without a refresh.
+  app.patch('/api/config', (req, res) => {
+    const body = req.body;
+    if (!body || typeof body !== 'object' || Array.isArray(body)) {
+      return res.status(400).json({ error: 'body must be a JSON object' });
+    }
+    try {
+      updateConfig(body);
+    } catch (err) {
+      return res.status(400).json({ error: err.message });
+    }
+
+    if (body.rag && typeof body.rag.enabled === 'boolean') {
+      rag.setEnabled(body.rag.enabled);
+    }
+
+    const payload = publicConfigPayload();
+
+    try {
+      const wsPayload = JSON.stringify({ type: 'config_changed', config: payload });
+      wss.clients.forEach((client) => {
+        if (client.readyState === 1) {
+          try { client.send(wsPayload); } catch (err) { console.error('[ws] config_changed send failed:', err); }
+        }
+      });
+    } catch (err) {
+      console.error('[ws] config_changed broadcast failed:', err);
+    }
+
+    res.json(payload);
   });
 
   // POST /api/projects - add a new project on the fly, persist to config.yaml
@@ -1466,6 +1514,14 @@ function createServer(config) {
 
     ws.on('close', () => {
       console.log(`[ws] Client disconnected from session ${sessionId}`);
+      // Intentional: PTYs survive WS close. The session stays in the manager,
+      // the PTY keeps running, and reconnecting (?session=<id>) re-binds.
+      // PTY teardown happens only via DELETE /api/sessions/:id (user-initiated)
+      // or the PTY's own exit event. Hard-refresh is therefore non-destructive.
+      // Sprint 36 T3 Deliverable C audit (2026-04-27): the briefing predicted
+      // this handler would call pty.kill() — it does not. Joshua's original
+      // hard-refresh-loses-PTYs symptom was the reclaimStalePort SIGKILL chain
+      // (orchestrator hotfix #2, 15:25 ET), not a WS-close cascade.
       if (session.ws === ws) {
         session.ws = null;
       }

package/packages/server/src/rag.js

@@ -66,6 +66,14 @@ class RAGIntegration {
     this._circuitBreaker = new Map(); // table -> { count, open, openedAt, halfOpen }
     this._halfOpenDelayMs = 5 * 60 * 1000;
 
+    // Status-change debounce: rapid `active ↔ thinking` cycling from busy
+    // Claude Code workers (4+1 sprint lanes) produces dozens of status_changed
+    // events per second. Untreated, this floods stdout and the outbox; on
+    // 2026-04-27 it contributed to two server-kill incidents during Sprint 36.
+    // Drop intra-second status edges; let error transitions always pass.
+    this._statusWriteAt = new Map(); // sessionId -> last write timestamp (ms)
+    this._statusDebounceMs = 1000;
+
     if (this.enabled) {
       this._startSync();
     }
@@ -148,6 +156,16 @@ class RAGIntegration {
   }
 
   onStatusChanged(session, oldStatus, newStatus) {
+    // Always pass through error transitions — those carry signal worth ingesting
+    // every time. Debounce only the active ↔ thinking churn that floods the log
+    // when a worker cycles tool calls rapidly.
+    const isError = newStatus === 'errored' || oldStatus === 'errored';
+    if (!isError) {
+      const now = Date.now();
+      const last = this._statusWriteAt.get(session.id) || 0;
+      if (now - last < this._statusDebounceMs) return;
+      this._statusWriteAt.set(session.id, now);
+    }
     this._recordForSession(session, 'status_changed', {
       from: oldStatus,
       to: newStatus,
@@ -351,7 +369,32 @@ class RAGIntegration {
   stop() {
     if (this._syncTimer) {
       clearInterval(this._syncTimer);
+      this._syncTimer = null;
+    }
+    this._statusWriteAt.clear();
+  }
+
+  // Live-toggle for the dashboard RAG settings panel (Sprint 36 T3 Deliverable A).
+  // Re-evaluates eligibility — flipping `enabled: true` without configured
+  // Supabase creds is a no-op so the live integration never claims to be on
+  // when it can't actually push. Returns the resolved effective flag.
+  setEnabled(value) {
+    const desired = !!value;
+    if (this.config && this.config.rag) {
+      this.config.rag.enabled = desired;
+    }
+    const effective = !!(desired && this.supabaseUrl && this.supabaseKey);
+    if (effective === this.enabled) return effective;
+    this.enabled = effective;
+    if (effective) {
+      if (!this._syncTimer) this._startSync();
+    } else {
+      if (this._syncTimer) {
+        clearInterval(this._syncTimer);
+        this._syncTimer = null;
+      }
     }
+    return effective;
   }
 }