@jhizzard/termdeck 0.7.3 → 0.9.0

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

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+
+// `termdeck init --project <name>` — Sprint 37 T2.
+//
+// Scaffolds a new project directory with the orchestration patterns TermDeck
+// itself uses: CLAUDE.md (router), CONTRADICTIONS.md (audit trail),
+// project_facts.md (stable facts), README.md, docs/orchestration/ (sprint +
+// restart-prompt scaffolding), .claude/settings.json (sensible permission
+// defaults), and .gitignore. All content comes from packages/cli/templates/
+// rendered with {{placeholder}} substitution via packages/cli/src/templates.js.
+//
+// Public API (used by the CLI entry and by tests):
+//   initProject({ name, dryRun, force, cwd }) -> Promise<{ exitCode, files }>
+//
+// CLI shim (used by index.js dispatch):
+//   main(argv)                                -> Promise<exitCode>
+//
+// `argv` here is everything AFTER `init --project` in the original argv —
+// i.e. for `termdeck init --project hello --dry-run`, argv is
+// `['hello', '--dry-run']`.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { listTemplates, renderTemplate, TEMPLATES_DIR } = require(path.join(__dirname, 'templates.js'));
+
+// Project name validation: lowercase letters, digits, hyphens, optional
+// scoped prefix (@org/name) is intentionally NOT supported here — the user
+// would clone the result and rename if they want a scoped npm package.
+const NAME_RE = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+function validateName(name) {
+  if (typeof name !== 'string' || name.length === 0) {
+    return 'Project name is required.';
+  }
+  if (name.includes('/') || name.includes('\\') || name.includes('..')) {
+    return `Project name "${name}" must not contain slashes or "..".`;
+  }
+  if (!NAME_RE.test(name)) {
+    return `Project name "${name}" must be lowercase letters, digits, and hyphens (no leading/trailing hyphen).`;
+  }
+  return null;
+}
+
+function readTermdeckVersion() {
+  try {
+    const pkg = require(path.join(__dirname, '..', '..', '..', 'package.json'));
+    return pkg.version || '0.0.0';
+  } catch (_e) {
+    return '0.0.0';
+  }
+}
+
+function buildVars({ name, projectPath }) {
+  return {
+    project_name: name,
+    project_path: projectPath,
+    generated_at: new Date().toISOString(),
+    termdeck_version: readTermdeckVersion(),
+  };
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// Returns true if the directory either does not exist or exists and is empty.
+function isEmptyOrMissing(dir) {
+  if (!fs.existsSync(dir)) return true;
+  const stat = fs.statSync(dir);
+  if (!stat.isDirectory()) return false;
+  return fs.readdirSync(dir).length === 0;
+}
+
+function previewSnippet(content, headLines = 5) {
+  const lines = content.split('\n');
+  const head = lines.slice(0, headLines).join('\n');
+  const remaining = Math.max(0, lines.length - headLines);
+  return remaining === 0 ? head : `${head}\n... (${remaining} more line${remaining === 1 ? '' : 's'})`;
+}
+
+async function initProject(opts) {
+  const { name, dryRun = false, force = false, cwd = process.cwd() } = opts || {};
+
+  const nameError = validateName(name);
+  if (nameError) {
+    process.stderr.write(`\n  ✗ ${nameError}\n\n`);
+    return { exitCode: 1, files: [] };
+  }
+
+  const projectPath = path.resolve(cwd, name);
+
+  if (!dryRun && !force && !isEmptyOrMissing(projectPath)) {
+    process.stderr.write(`\n  ✗ Target ${projectPath} exists and is not empty. Use --force to overwrite, or pick a new name.\n\n`);
+    return { exitCode: 1, files: [] };
+  }
+
+  const vars = buildVars({ name, projectPath });
+  const templates = listTemplates();
+  const written = [];
+
+  if (dryRun) {
+    process.stdout.write(`\n  [dry-run] Would create ${projectPath}/ with ${templates.length} files:\n\n`);
+  } else {
+    ensureDir(projectPath);
+  }
+
+  for (const entry of templates) {
+    const dest = path.join(projectPath, entry.targetPath);
+    const rendered = renderTemplate(entry.name, vars);
+
+    if (dryRun) {
+      process.stdout.write(`  • ${entry.targetPath}\n`);
+      const indented = previewSnippet(rendered).split('\n').map((l) => `      ${l}`).join('\n');
+      process.stdout.write(`${indented}\n\n`);
+      written.push({ template: entry.file, name: entry.name, dest, bytes: Buffer.byteLength(rendered, 'utf8') });
+      continue;
+    }
+
+    ensureDir(path.dirname(dest));
+    fs.writeFileSync(dest, rendered);
+    written.push({ template: entry.file, name: entry.name, dest, bytes: Buffer.byteLength(rendered, 'utf8') });
+  }
+
+  if (dryRun) {
+    process.stdout.write(`  [dry-run] Nothing was written. Re-run without --dry-run to scaffold.\n\n`);
+  } else {
+    process.stdout.write(`
+  Created ${name}/ at ${projectPath}.
+
+  Next steps:
+    cd ${name}
+    git init
+    # Open ${name}/ in TermDeck — it will pick up the .claude/settings.json automatically.
+    # Read CLAUDE.md to see the agent read-order for this project.
+
+`);
+  }
+
+  return { exitCode: 0, files: written };
+}
+
+// CLI shim. Parses argv and calls initProject(). The dispatch in
+// packages/cli/src/index.js strips the leading `init --project` tokens.
+async function main(argv) {
+  const args = argv || [];
+
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  // First positional argument that isn't a flag is the project name.
+  let name = null;
+  let dryRun = false;
+  let force = false;
+
+  for (let i = 0; i < args.length; i++) {
+    const tok = args[i];
+    if (tok === '--dry-run') { dryRun = true; continue; }
+    if (tok === '--force') { force = true; continue; }
+    if (tok === '--name' && args[i + 1]) { name = args[i + 1]; i++; continue; }
+    if (tok.startsWith('--')) {
+      process.stderr.write(`\n  ✗ Unknown flag: ${tok}\n${HELP}`);
+      return 1;
+    }
+    if (name === null) {
+      name = tok;
+      continue;
+    }
+    process.stderr.write(`\n  ✗ Unexpected extra argument: ${tok}\n${HELP}`);
+    return 1;
+  }
+
+  if (!name) {
+    process.stderr.write(`\n  ✗ Missing project name.\n${HELP}`);
+    return 1;
+  }
+
+  const { exitCode } = await initProject({ name, dryRun, force, cwd: process.cwd() });
+  return exitCode;
+}
+
+const HELP = `
+TermDeck Project Scaffolder
+
+Usage: termdeck init --project <name> [flags]
+
+Flags:
+  --dry-run          Print what would be created; write nothing
+  --force            Overwrite an existing non-empty target directory
+  --help, -h         Print this message and exit
+
+What this does:
+  Creates <name>/ in the current directory with a project skeleton:
+    CLAUDE.md                  Agent read-order router
+    CONTRADICTIONS.md          Audit trail of changed facts/decisions
+    project_facts.md           Stable per-project facts
+    README.md                  Human-facing intro
+    docs/orchestration/        Sprint + restart-prompt scaffolding
+    .claude/settings.json      Sensible Claude Code permission defaults
+    .gitignore                 Standard Node + .DS_Store + .termdeck/
+
+Templates live in packages/cli/templates/ and use {{placeholder}} substitution.
+`;
+
+module.exports = main;
+module.exports.initProject = initProject;
+module.exports._validateName = validateName;
+module.exports._buildVars = buildVars;
+module.exports.TEMPLATES_DIR = TEMPLATES_DIR;

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;