dual-brain 7.0.1 → 7.1.0

package/bin/dual-brain.mjs

@@ -5,12 +5,13 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync } from 'node:child_process';
+import { createInterface } from 'node:readline';
 
 import {
   ensureProfile, loadProfile, saveProfile, runOnboarding,
   rememberPreference, forgetPreference, getActivePreferences,
   getAvailableProviders, isSoloBrain, getHeadModel,
-  detectAuth, detectEnvironment,
+  detectAuth, detectEnvironment, setupAuth,
 } from '../src/profile.mjs';
 
 import { detectTask } from '../src/detect.mjs';
@@ -28,6 +29,8 @@ import { dispatch, detectRuntime, dispatchDualBrain } from '../src/dispatch.mjs'
 import { loadRepoCache } from '../src/repo.mjs';
 import { loadSession, saveSession, formatSessionCard } from '../src/session.mjs';
 
+import { box, bar, badge, menu, separator } from '../src/tui.mjs';
+
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -45,8 +48,9 @@ function printHelp() {
 dual-brain <command> [options]
 
 Commands:
-  init                      First-time setup (providers, plans, optimization)
+  init                      First-time setup → flows into interactive REPL
   auth                      Show authentication status for all providers
+  auth setup                Paste API keys directly (recommended for Replit)
   install                   Install Claude Code hooks into the current project
   go "task description"     Detect → decide → dispatch a task
     --dry-run               Show routing decision without executing
@@ -59,6 +63,12 @@ Commands:
   remember "preference"     Save a project-scoped preference
   forget "preference"       Remove a preference by fuzzy match
 
+Interactive mode (entered with no args on a TTY):
+  Shows dashboard screen with menu-driven navigation.
+  [g] Go — dispatch a task
+  [s] Status, [p] Profile, [a] Auth, [d] Diagnostics
+  [c] Command mode (REPL), [q] Exit
+
 Options:
   --version                 Print version
   --help                    Show this help
@@ -74,7 +84,7 @@ Options:
  */
 function printAuthTable(auth) {
   const W = 55; // inner width (wide enough for source labels)
-  const bar = '═'.repeat(W);
+  const hbar = '═'.repeat(W);
   const pad = (s) => {
     const visible = s.replace(/[̀-ͯ]/g, ''); // strip combining chars for length
     return s + ' '.repeat(Math.max(0, W - visible.length));
@@ -85,66 +95,28 @@ function printAuthTable(auth) {
     : `  Claude:  ✗ not found`;
   const claudeLine2 = auth.claude.found
     ? `           ${auth.claude.masked}`
-    : `           run: claude auth login`;
+    : `           run: dual-brain auth setup`;
 
   const openaiLine1 = auth.openai.found
     ? `  OpenAI:  ✓ found via ${auth.openai.source}`
     : `  OpenAI:  ✗ not found`;
   const openaiLine2 = auth.openai.found
     ? `           ${auth.openai.masked}`
-    : `           run: codex auth  OR  export OPENAI_API_KEY=sk-...`;
+    : `           run: dual-brain auth setup`;
 
-  console.log(`╔${bar}╗`);
+  console.log(`╔${hbar}╗`);
   console.log(`║${pad('  Auth Status')}║`);
-  console.log(`╠${bar}╣`);
+  console.log(`╠${hbar}╣`);
   console.log(`║${pad(claudeLine1)}║`);
   console.log(`║${pad(claudeLine2)}║`);
   console.log(`║${pad(openaiLine1)}║`);
   console.log(`║${pad(openaiLine2)}║`);
-  console.log(`╚${bar}╝`);
-}
-
-// ─── Card command (default) ──────────────────────────────────────────────────
-
-async function cmdCard() {
-  const cwd = process.cwd();
-  const { homedir } = await import('node:os');
-  const globalPath  = join(homedir(), '.config', 'dual-brain', 'profile.json');
-  const projectPath = join(cwd, '.dualbrain', 'profile.json');
-
-  if (!existsSync(projectPath) && !existsSync(globalPath)) {
-    console.log('Welcome to dual-brain! Let\'s set up your profile.\n');
-    await cmdInit();
-    return;
-  }
-
-  const repo    = loadRepoCache(cwd);
-  const session = loadSession(cwd);
-  const health  = getHealth(cwd);
-  const card    = formatSessionCard(session, repo, health);
-  console.log(card);
-
-  // Auth status warnings (non-blocking)
-  const auth = await detectAuth();
-  const warnings = [];
-  if (!auth.claude.found) warnings.push('Claude auth not found — run: claude auth login');
-  if (!auth.openai.found) warnings.push('OpenAI auth not found — run: codex auth  OR  export OPENAI_API_KEY=sk-...');
-  if (warnings.length > 0) {
-    console.log('\nAuth warnings:');
-    for (const w of warnings) console.log(`  ⚠  ${w}`);
-  }
-
-  // Environment info
-  const env = detectEnvironment();
-  if (env.isReplit || env.hasReplitTools) {
-    const envLabel = env.hasReplitTools ? 'Replit + replit-tools' : 'Replit';
-    console.log(`\nRuntime: ${envLabel}`);
-  }
+  console.log(`╚${hbar}╝`);
 }
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
-async function cmdInit() {
+async function cmdInit(rl) {
   const cwd = process.cwd();
 
   // --- Step 1: Auth preflight ---
@@ -153,39 +125,61 @@ async function cmdInit() {
 
   const noneFound = !auth.claude.found && !auth.openai.found;
   if (noneFound) {
-    console.log('\nNo AI provider credentials found. Set up at least one before continuing:\n');
-    console.log('  Claude : claude auth login');
-    console.log('  OpenAI : codex auth   OR   export OPENAI_API_KEY=sk-...\n');
-    console.log('Re-run "dual-brain init" after authenticating.');
-    return;
+    console.log('\nNo AI provider credentials found. Let\'s set up at least one now.\n');
+    // Use the provided rl (REPL instance) or create a temporary one
+    const rlOwned = !rl;
+    if (!rl) rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      await setupAuth(rl);
+    } finally {
+      if (rlOwned) rl.close();
+    }
+    // Re-check after setup
+    const authAfter = await detectAuth();
+    if (!authAfter.claude.found && !authAfter.openai.found) {
+      console.log('\nNo credentials configured. You can run "auth setup" in the REPL anytime.');
+      // Still flow into REPL — don't exit
+      return;
+    }
   }
 
-  // --- Step 2: Run onboarding wizard, skipping tiers for auto-detected plans ---
-  const profile = await runOnboarding({ interactive: true, detectedAuth: auth });
+  // --- Step 2: Run onboarding wizard (pass shared rl so it isn't closed) ---
+  const profile = await runOnboarding({ interactive: true, detectedAuth: auth, rl });
   saveProfile(profile, { cwd });
 
-  // --- Step 3: Show dashboard + next step ---
+  // --- Step 3: Show dashboard ---
   console.log('');
   const repo    = loadRepoCache(cwd);
   const session = loadSession(cwd);
   const health  = getHealth(cwd);
   const card    = formatSessionCard(session, repo, health);
   console.log(card);
-  console.log('\nReady! Try: dual-brain go "your task here"\n');
+  console.log('\nReady! Type a task below, or "help" for commands.\n');
 }
 
-async function cmdAuth() {
+async function cmdAuth(subArgs = [], rl) {
+  const sub = subArgs[0];
+
+  if (sub === 'setup') {
+    return cmdAuthSetup(rl);
+  }
+
   const auth = await detectAuth();
   printAuthTable(auth);
 
-  // If anything is missing, print setup commands
-  if (!auth.claude.found) {
-    console.log('\nTo set up Claude:');
-    console.log('  claude auth login');
+  // If anything is missing, point to setup command
+  if (!auth.claude.found || !auth.openai.found) {
+    console.log('\nRun "dual-brain auth setup" (or "auth setup" in REPL) to paste API keys.');
   }
-  if (!auth.openai.found) {
-    console.log('\nTo set up OpenAI:');
-    console.log('  codex auth   OR   export OPENAI_API_KEY=sk-...');
+}
+
+async function cmdAuthSetup(rl) {
+  const rlOwned = !rl;
+  if (!rl) rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await setupAuth(rl);
+  } finally {
+    if (rlOwned) rl.close();
   }
 }
 
@@ -489,6 +483,516 @@ function cmdForget(text) {
   console.log('Preference removed (if matched).');
 }
 
+// ─── Screen helpers ───────────────────────────────────────────────────────────
+
+function profileExists() {
+  const { homedir } = { homedir: () => process.env.HOME || '/root' };
+  const cwd = process.cwd();
+  const globalPath  = join(process.env.HOME || '/root', '.config', 'dual-brain', 'profile.json');
+  const projectPath = join(cwd, '.dualbrain', 'profile.json');
+  return existsSync(projectPath) || existsSync(globalPath);
+}
+
+// ─── Screen: welcomeScreen ────────────────────────────────────────────────────
+
+async function welcomeScreen(rl, ask) {
+  const version = readVersion();
+  console.log(box(`🧠 Dual-Brain v${version} — First-Time Setup`, [
+    'Let\'s configure your AI providers.',
+  ]));
+  console.log('');
+
+  // --- Claude provider selection ---
+  console.log(separator('Claude (Anthropic)'));
+  console.log('  (1) $20/mo Pro');
+  console.log('  (2) $100/mo Max 5x');
+  console.log('  (3) $200/mo Max 20x');
+  console.log('  (4) API key only');
+  console.log('  (5) Skip — don\'t use Claude');
+  const claudeChoice = (await ask('> ')).trim();
+
+  let claudePlan = null;
+  let claudeEnabled = true;
+  if (claudeChoice === '1') { claudePlan = 'pro'; }
+  else if (claudeChoice === '2') { claudePlan = 'max5'; }
+  else if (claudeChoice === '3') { claudePlan = 'max20'; }
+  else if (claudeChoice === '4') {
+    claudePlan = 'api';
+    // Ask for API key immediately
+    const key = (await ask('Paste your Anthropic API key: ')).trim();
+    if (key) {
+      const { saveAuthKey } = await import('../src/profile.mjs').then(m => m).catch(() => ({}));
+      // Inline: set env var for this session, profile will persist
+      process.env.ANTHROPIC_API_KEY = key;
+      console.log('✓ Claude API key set for this session');
+    }
+  } else if (claudeChoice === '5') {
+    claudeEnabled = false;
+    claudePlan = null;
+  } else {
+    // Default: pro
+    claudePlan = 'pro';
+  }
+
+  console.log('');
+
+  // --- OpenAI provider selection ---
+  console.log(separator('OpenAI (ChatGPT/Codex)'));
+  console.log('  (1) $20/mo Plus');
+  console.log('  (2) $100/mo Pro');
+  console.log('  (3) $200/mo Pro (higher limits)');
+  console.log('  (4) API key only');
+  console.log('  (5) Skip — don\'t use OpenAI');
+  const openaiChoice = (await ask('> ')).trim();
+
+  let openaiPlan = null;
+  let openaiEnabled = true;
+  if (openaiChoice === '1') { openaiPlan = 'plus'; }
+  else if (openaiChoice === '2') { openaiPlan = 'pro'; }
+  else if (openaiChoice === '3') { openaiPlan = 'pro200'; }
+  else if (openaiChoice === '4') {
+    openaiPlan = 'api';
+    const key = (await ask('Paste your OpenAI API key: ')).trim();
+    if (key) {
+      process.env.OPENAI_API_KEY = key;
+      console.log('✓ OpenAI API key set for this session');
+    }
+  } else if (openaiChoice === '5') {
+    openaiEnabled = false;
+    openaiPlan = null;
+  } else {
+    openaiPlan = 'plus';
+  }
+
+  console.log('');
+
+  // --- Optimization mode ---
+  console.log(separator('Optimization'));
+  console.log('  (1) Save usage — prefer cheaper models');
+  console.log('  (2) Balanced — best model per tier (recommended)');
+  console.log('  (3) Quality first — always use best available');
+  const modeChoice = (await ask('> ')).trim();
+
+  let mode = 'balanced';
+  if (modeChoice === '1') { mode = 'cost-saver'; }
+  else if (modeChoice === '3') { mode = 'quality-first'; }
+
+  // --- Build and save profile ---
+  const cwd = process.cwd();
+  const existingProfile = loadProfile(cwd);
+  const profile = {
+    ...existingProfile,
+    mode,
+    providers: {
+      claude: {
+        enabled: claudeEnabled,
+        plan: claudePlan || 'pro',
+      },
+      openai: {
+        enabled: openaiEnabled,
+        plan: openaiPlan || 'plus',
+      },
+    },
+  };
+  saveProfile(profile, { cwd });
+
+  // --- Detect environment for summary ---
+  const env = detectEnvironment();
+  const auth = await detectAuth();
+
+  const summaryLines = [
+    `Mode: ${mode}`,
+    claudeEnabled
+      ? `Claude: ${claudePlan} plan ${auth.claude.found ? badge('connected') : badge('missing')}`
+      : 'Claude: disabled',
+    openaiEnabled
+      ? `OpenAI: ${openaiPlan} plan ${auth.openai.found ? badge('connected') : badge('missing')}`
+      : 'OpenAI: disabled',
+    env.isReplit ? '🌀 Replit environment detected' : '',
+  ].filter(Boolean);
+
+  console.log('');
+  console.log(box('Setup Complete', summaryLines));
+  console.log('');
+
+  return { next: 'dashboard' };
+}
+
+// ─── Screen: dashboardScreen ──────────────────────────────────────────────────
+
+async function dashboardScreen(rl, ask) {
+  const cwd = process.cwd();
+  const version = readVersion();
+  const profile = loadProfile(cwd);
+  const auth = await detectAuth();
+  const env = detectEnvironment();
+
+  // Build status lines for box
+  const claudeStatus = auth.claude.found ? `🟢 Claude ${badge('connected')}` : `🔴 Claude ${badge('missing')}`;
+  const openaiStatus = auth.openai.found ? `🟢 OpenAI ${badge('connected')}` : `🔴 OpenAI ${badge('missing')}`;
+  const envLabel = env.hasReplitTools ? 'Replit + replit-tools' : env.isReplit ? 'Replit' : 'local';
+
+  // Enforcement check
+  let guardCount = 0;
+  try {
+    const settingsFile = join(cwd, '.claude', 'settings.json');
+    if (existsSync(settingsFile)) {
+      const settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+      const preToolUse = settings?.hooks?.PreToolUse ?? [];
+      const guardCmd  = 'bash .claude/hooks/head-guard.sh';
+      const tierCmd   = 'node .claude/hooks/enforce-tier.mjs';
+      const hasEdit   = preToolUse.some(e => e.matcher === 'Edit'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasWrite  = preToolUse.some(e => e.matcher === 'Write'  && e.hooks?.some(h => h.command === guardCmd));
+      const hasBash   = preToolUse.some(e => e.matcher === 'Bash'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasAgent  = preToolUse.some(e => e.matcher === 'Agent'  && e.hooks?.some(h => h.command === tierCmd));
+      guardCount = [hasEdit, hasWrite, hasBash, hasAgent].filter(Boolean).length;
+    }
+  } catch { /* ignore */ }
+
+  const authSummary = (auth.claude.found && auth.openai.found)
+    ? 'both providers connected'
+    : auth.claude.found
+      ? 'Claude connected, OpenAI missing'
+      : auth.openai.found
+        ? 'OpenAI connected, Claude missing'
+        : 'no providers connected';
+
+  const dashLines = [
+    `${claudeStatus}   ${openaiStatus}`,
+    `🌀 ${envLabel}`,
+    '',
+    `✓ Profile: ${profile.mode} · ${profile.providers?.claude?.enabled && profile.providers?.openai?.enabled ? 'dual' : 'solo'} mode`,
+    `✓ Enforcement: ${guardCount} guards active`,
+    `✓ Auth: ${authSummary}`,
+  ];
+
+  console.log(box(`🧠 Dual-Brain v${version}`, dashLines));
+  console.log('');
+  console.log(menu([
+    { key: 'g', label: 'Go — dispatch a task',        section: 'Actions' },
+    { key: 's', label: 'Status — detailed provider info', section: 'Actions' },
+    { key: 'p', label: 'Profile & preferences',        section: 'Settings' },
+    { key: 'a', label: 'Auth management',              section: 'Settings' },
+    { key: 'd', label: 'Diagnostics',                  section: 'Settings' },
+    { key: 'c', label: 'Command mode (REPL)',           section: 'Session' },
+    { key: 'q', label: 'Exit',                         section: 'Session' },
+  ]));
+  console.log('');
+
+  const choice = (await ask('  Choice: ')).trim().toLowerCase();
+
+  if (choice === 'g') {
+    const taskDesc = (await ask('  Task description: ')).trim();
+    if (taskDesc) {
+      try {
+        await cmdGo([taskDesc]);
+      } catch (e) {
+        console.error(`Error: ${e.message}`);
+      }
+    }
+    return { next: 'dashboard' };
+  }
+
+  if (choice === 's') {
+    await cmdStatus([]);
+    await ask('\n  Press Enter to return to dashboard...');
+    return { next: 'dashboard' };
+  }
+
+  if (choice === 'p') { return { next: 'profile' }; }
+  if (choice === 'a') { return { next: 'auth' }; }
+  if (choice === 'd') { return { next: 'diagnostics' }; }
+  if (choice === 'c') { return { next: 'repl' }; }
+  if (choice === 'q' || choice === 'exit') { return { next: 'exit' }; }
+
+  // Unknown choice — stay on dashboard
+  return { next: 'dashboard' };
+}
+
+// ─── Screen: authScreen ───────────────────────────────────────────────────────
+
+async function authScreen(rl, ask) {
+  const auth = await detectAuth();
+
+  const authLines = [
+    'Claude:',
+  ];
+
+  if (auth.claude.found) {
+    authLines.push(`  source: ${auth.claude.source}  ${badge('connected')}`);
+    authLines.push(`  key:    ${auth.claude.masked}`);
+  } else {
+    authLines.push(`  not configured  ${badge('missing')}`);
+  }
+
+  authLines.push('');
+  authLines.push('OpenAI:');
+
+  if (auth.openai.found) {
+    authLines.push(`  source: ${auth.openai.source}  ${badge('connected')}`);
+    authLines.push(`  key:    ${auth.openai.masked}`);
+  } else {
+    authLines.push(`  not configured  ${badge('missing')}`);
+  }
+
+  console.log(box('🔑 Auth Management', authLines));
+  console.log('');
+  console.log(menu([
+    { key: 'a', label: 'Add API key',        section: '' },
+    { key: 't', label: 'Test keys',          section: '' },
+    { key: 'b', label: 'Back to dashboard',  section: '' },
+  ]));
+  console.log('');
+
+  const choice = (await ask('  Choice: ')).trim().toLowerCase();
+
+  if (choice === 'a') {
+    await setupAuth(rl);
+    return { next: 'auth' }; // refresh
+  }
+
+  if (choice === 't') {
+    console.log('\n  Testing auth...');
+    const authNow = await detectAuth();
+    console.log(`  Claude: ${authNow.claude.found ? 'OK — ' + authNow.claude.source : 'NOT FOUND'}`);
+    console.log(`  OpenAI: ${authNow.openai.found ? 'OK — ' + authNow.openai.source : 'NOT FOUND'}`);
+    await ask('\n  Press Enter to continue...');
+    return { next: 'auth' };
+  }
+
+  if (choice === 'b' || choice === 'back') { return { next: 'dashboard' }; }
+
+  return { next: 'auth' };
+}
+
+// ─── Screen: profileScreen ────────────────────────────────────────────────────
+
+async function profileScreen(rl, ask) {
+  const cwd = process.cwd();
+  const profile = loadProfile(cwd);
+  const prefs = getActivePreferences(cwd);
+
+  const profileLines = [
+    `Mode:          ${profile.mode}`,
+    `Claude plan:   ${profile.providers?.claude?.enabled ? (profile.providers?.claude?.plan || 'n/a') : 'disabled'}`,
+    `OpenAI plan:   ${profile.providers?.openai?.enabled ? (profile.providers?.openai?.plan || 'n/a') : 'disabled'}`,
+    `Solo brain:    ${isSoloBrain(profile) ? 'yes' : 'no'}`,
+    `Head model:    ${getHeadModel(profile)}`,
+    '',
+    `Preferences (${prefs.length}):`,
+    ...prefs.map(p => `  [${p.scope}] ${p.text}`),
+    ...(prefs.length === 0 ? ['  (none)'] : []),
+  ];
+
+  console.log(box('Profile & Preferences', profileLines));
+  console.log('');
+  console.log(menu([
+    { key: '1', label: 'Switch to cost-saver mode',   section: 'Mode' },
+    { key: '2', label: 'Switch to balanced mode',     section: 'Mode' },
+    { key: '3', label: 'Switch to quality-first mode',section: 'Mode' },
+    { key: 'r', label: 'Add preference',              section: 'Preferences' },
+    { key: 'f', label: 'Remove preference',           section: 'Preferences' },
+    { key: 'b', label: 'Back to dashboard',           section: '' },
+  ]));
+  console.log('');
+
+  const choice = (await ask('  Choice: ')).trim().toLowerCase();
+
+  if (choice === '1' || choice === '2' || choice === '3') {
+    const modeMap = { '1': 'cost-saver', '2': 'balanced', '3': 'quality-first' };
+    profile.mode = modeMap[choice];
+    saveProfile(profile, { cwd });
+    console.log(`  Mode set to: ${profile.mode}`);
+    return { next: 'profile' };
+  }
+
+  if (choice === 'r') {
+    const text = (await ask('  Preference text: ')).trim();
+    if (text) cmdRemember(text);
+    return { next: 'profile' };
+  }
+
+  if (choice === 'f') {
+    const text = (await ask('  Preference to remove (fuzzy): ')).trim();
+    if (text) cmdForget(text);
+    return { next: 'profile' };
+  }
+
+  if (choice === 'b' || choice === 'back') { return { next: 'dashboard' }; }
+
+  return { next: 'profile' };
+}
+
+// ─── Screen: diagnosticsScreen ────────────────────────────────────────────────
+
+async function diagnosticsScreen(rl, ask) {
+  const cwd = process.cwd();
+  const version = readVersion();
+  const env = detectEnvironment();
+  const rt = await detectRuntime();
+
+  // Enforcement check
+  let guardCount = 0;
+  let guardDetails = 'NOT INSTALLED';
+  try {
+    const settingsFile = join(cwd, '.claude', 'settings.json');
+    if (existsSync(settingsFile)) {
+      const settings = JSON.parse(readFileSync(settingsFile, 'utf8'));
+      const preToolUse = settings?.hooks?.PreToolUse ?? [];
+      const guardCmd  = 'bash .claude/hooks/head-guard.sh';
+      const tierCmd   = 'node .claude/hooks/enforce-tier.mjs';
+      const hasEdit   = preToolUse.some(e => e.matcher === 'Edit'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasWrite  = preToolUse.some(e => e.matcher === 'Write'  && e.hooks?.some(h => h.command === guardCmd));
+      const hasBash   = preToolUse.some(e => e.matcher === 'Bash'   && e.hooks?.some(h => h.command === guardCmd));
+      const hasAgent  = preToolUse.some(e => e.matcher === 'Agent'  && e.hooks?.some(h => h.command === tierCmd));
+      guardCount = [hasEdit, hasWrite, hasBash, hasAgent].filter(Boolean).length;
+      guardDetails = guardCount === 4
+        ? `${guardCount}/4 guards active (Edit, Write, Bash, Agent)`
+        : `${guardCount}/4 guards — run: dual-brain install`;
+    }
+  } catch { guardDetails = 'unknown (could not read settings)'; }
+
+  // Hook health: check if hook files exist
+  const hooksDir = join(cwd, '.claude', 'hooks');
+  const expectedHooks = [
+    'head-guard.sh', 'enforce-tier.mjs', 'budget-balancer.mjs',
+    'session-report.mjs', 'quality-gate.mjs', 'health-check.mjs',
+  ];
+  const hookStatus = expectedHooks.map(h => {
+    const present = existsSync(join(hooksDir, h));
+    return `  ${present ? '✓' : '✗'} ${h}`;
+  });
+
+  const diagLines = [
+    `Version:       ${version}`,
+    `Enforcement:   ${guardDetails}`,
+    '',
+    'Environment:',
+    `  Replit:      ${env.isReplit ? 'yes' : 'no'}`,
+    `  replit-tools:${env.hasReplitTools ? 'yes' : 'no'}`,
+    `  CI:          ${env.isCI ? 'yes' : 'no'}`,
+    '',
+    'Runtime:',
+    `  claude CLI:  ${rt.claudeAvailable ? 'available' : 'not found'}`,
+    `  codex CLI:   ${rt.codexAvailable  ? 'available' : 'not found'}`,
+    `  runtime:     ${rt.runtime}`,
+    '',
+    'Hook files:',
+    ...hookStatus,
+  ];
+
+  console.log(box('Diagnostics', diagLines));
+  console.log('');
+  console.log(menu([
+    { key: 'h', label: 'Run health check',    section: '' },
+    { key: 'i', label: 'Install hooks',       section: '' },
+    { key: 'b', label: 'Back to dashboard',  section: '' },
+  ]));
+  console.log('');
+
+  const choice = (await ask('  Choice: ')).trim().toLowerCase();
+
+  if (choice === 'h') {
+    const hookScript = join(cwd, '.claude', 'hooks', 'health-check.mjs');
+    if (existsSync(hookScript)) {
+      try {
+        execSync(`node "${hookScript}"`, { stdio: 'inherit', cwd });
+      } catch { /* hook exits non-zero on issues — already printed output */ }
+    } else {
+      console.log('  health-check.mjs not found — run: dual-brain install');
+    }
+    await ask('\n  Press Enter to continue...');
+    return { next: 'diagnostics' };
+  }
+
+  if (choice === 'i') {
+    await cmdInstall();
+    return { next: 'diagnostics' };
+  }
+
+  if (choice === 'b' || choice === 'back') { return { next: 'dashboard' }; }
+
+  return { next: 'diagnostics' };
+}
+
+// ─── Screen: replScreen ───────────────────────────────────────────────────────
+
+async function replScreen(rl, ask) {
+  console.log('\nCommand mode. Type a task or command. "help" for commands, "back" to return.\n');
+
+  while (true) {
+    const input = (await ask('dual-brain> ')).trim();
+    const line = input;
+
+    if (!line) continue;
+
+    if (line === 'back' || line === 'exit' || line === 'quit' || line === 'q') {
+      return { next: 'dashboard' };
+    }
+
+    try {
+      if (line === 'help') {
+        printHelp();
+      } else if (line === 'status') {
+        await cmdStatus([]);
+      } else if (line === 'auth setup' || line === 'auth-setup') {
+        await cmdAuthSetup(rl);
+      } else if (line === 'auth') {
+        await cmdAuth([], rl);
+      } else if (line.startsWith('go ')) {
+        await cmdGo(line.slice(3).trim().split(/\s+/));
+      } else if (line.startsWith('remember ')) {
+        cmdRemember(line.slice(9).trim());
+      } else if (line.startsWith('forget ')) {
+        cmdForget(line.slice(7).trim());
+      } else if (line.startsWith('hot ')) {
+        cmdHot(line.slice(4).trim());
+      } else if (line.startsWith('cool ')) {
+        cmdCool(line.slice(5).trim());
+      } else if (line === 'init') {
+        await cmdInit(rl);
+      } else if (line === 'dashboard') {
+        return { next: 'dashboard' };
+      } else {
+        // Treat as a task description → go
+        await cmdGo([line]);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e.message}\n`);
+    }
+  }
+}
+
+// ─── Screen state machine ─────────────────────────────────────────────────────
+
+const SCREENS = {
+  welcome:     welcomeScreen,
+  dashboard:   dashboardScreen,
+  auth:        authScreen,
+  profile:     profileScreen,
+  diagnostics: diagnosticsScreen,
+  repl:        replScreen,
+};
+
+async function runScreens(startScreen = 'dashboard') {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(res => rl.question(q, res));
+
+  let current = startScreen;
+  while (current && current !== 'exit') {
+    const screen = SCREENS[current];
+    if (!screen) break;
+    try {
+      const result = await screen(rl, ask);
+      current = result?.next || 'exit';
+    } catch (e) {
+      console.error(`Error: ${e.message}`);
+      current = 'dashboard'; // recover to dashboard on error
+    }
+  }
+  rl.close();
+}
+
 // ─── Entry point ─────────────────────────────────────────────────────────────
 
 async function main() {
@@ -496,12 +1000,46 @@ async function main() {
   const cmd  = args[0];
 
   if (cmd === '--help' || cmd === '-h') { printHelp(); return; }
-  if (!cmd) { await cmdCard(); return; }
-  if (cmd === '--version' || cmd === '-v')      { console.log(readVersion()); return; }
+  if (cmd === '--version' || cmd === '-v') { console.log(readVersion()); return; }
+
+  // Interactive-only commands: enter screen state machine (only when TTY)
+  const isInteractive = process.stdin.isTTY;
 
-  if (cmd === 'init')     { await cmdInit(); return; }
+  if (!cmd) {
+    if (isInteractive) {
+      // Check if first-run (no profile) → welcome screen, else dashboard
+      const startScreen = profileExists() ? 'dashboard' : 'welcome';
+      await runScreens(startScreen);
+    } else {
+      // Non-TTY: print status card and exit
+      const cwd = process.cwd();
+      const repo    = loadRepoCache(cwd);
+      const session = loadSession(cwd);
+      const health  = getHealth(cwd);
+      const card    = formatSessionCard(session, repo, health);
+      console.log(card);
+    }
+    return;
+  }
+
+  if (cmd === 'init') {
+    if (isInteractive) {
+      // Run welcome wizard then dashboard
+      await runScreens('welcome');
+    } else {
+      await cmdInit();
+    }
+    return;
+  }
+
+  // One-shot commands — run and exit
   if (cmd === 'install')  { await cmdInstall(); return; }
-  if (cmd === 'auth')     { await cmdAuth(); return; }
+  if (cmd === 'auth') {
+    const sub = args[1];
+    if (sub === 'setup') { await cmdAuthSetup(); return; }
+    await cmdAuth(args.slice(1));
+    return;
+  }
   if (cmd === 'go')       { await cmdGo(args.slice(1)); return; }
   if (cmd === 'status')   { await cmdStatus(args.slice(1)); return; }
   if (cmd === 'hot')      { cmdHot(args[1]); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "7.0.1",
+  "version": "7.1.0",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {

package/src/profile.mjs

@@ -25,7 +25,7 @@
 import { createInterface } from 'readline';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
-import { join } from 'path';
+import { dirname, join } from 'path';
 
 // ---------------------------------------------------------------------------
 // Claude Code memory integration
@@ -174,6 +174,28 @@ async function detectAuth() {
     } catch { continue; }
   }
 
+  // --- Claude: check .dualbrain/auth.json (before env var) ---
+  if (!results.claude.found) {
+    const storedAuth = loadAuthKeys();
+    const claudeKeys = storedAuth.claude || [];
+    const activeClaudeKey = getActiveKey('claude');
+    if (activeClaudeKey) {
+      results.claude.found   = true;
+      results.claude.source  = '.dualbrain/auth.json';
+      results.claude.masked  = _maskCredential(activeClaudeKey.key);
+      process.env.ANTHROPIC_API_KEY = activeClaudeKey.key;
+      // Report all keys with masked values
+      const now = new Date();
+      results.claude.keys = claudeKeys.map(k => ({
+        label:   k.label || 'unlabeled',
+        masked:  _maskCredential(k.key),
+        priority: k.priority || 99,
+        enabled: k.enabled !== false,
+        expired: !!(k.expiresAt && new Date(k.expiresAt) <= now),
+      }));
+    }
+  }
+
   // --- Claude: fallback to ANTHROPIC_API_KEY env var ---
   if (!results.claude.found && process.env.ANTHROPIC_API_KEY) {
     results.claude.found  = true;
@@ -208,6 +230,28 @@ async function detectAuth() {
     } catch { continue; }
   }
 
+  // --- OpenAI: check .dualbrain/auth.json (before env var) ---
+  if (!results.openai.found) {
+    const storedAuth = loadAuthKeys();
+    const openaiKeys = storedAuth.openai || [];
+    const activeOpenaiKey = getActiveKey('openai');
+    if (activeOpenaiKey) {
+      results.openai.found   = true;
+      results.openai.source  = '.dualbrain/auth.json';
+      results.openai.masked  = _maskCredential(activeOpenaiKey.key);
+      process.env.OPENAI_API_KEY = activeOpenaiKey.key;
+      // Report all keys with masked values
+      const now = new Date();
+      results.openai.keys = openaiKeys.map(k => ({
+        label:   k.label || 'unlabeled',
+        masked:  _maskCredential(k.key),
+        priority: k.priority || 99,
+        enabled: k.enabled !== false,
+        expired: !!(k.expiresAt && new Date(k.expiresAt) <= now),
+      }));
+    }
+  }
+
   // --- OpenAI: fallback to OPENAI_API_KEY env var ---
   if (!results.openai.found && process.env.OPENAI_API_KEY) {
     results.openai.found  = true;
@@ -218,6 +262,258 @@ async function detectAuth() {
   return results;
 }
 
+// ---------------------------------------------------------------------------
+// API key storage (.dualbrain/auth.json)
+// ---------------------------------------------------------------------------
+
+const AUTH_FILE = (cwd) => join(cwd || process.cwd(), '.dualbrain', 'auth.json');
+
+/**
+ * Migrate old single-key format to array format transparently.
+ * Old: { claude: { key, savedAt, expiresAt }, openai: { ... } }
+ * New: { claude: [{ key, label, savedAt, expiresAt, priority, enabled }], openai: [...] }
+ * @param {object} auth
+ * @returns {object} migrated auth object
+ */
+function _migrateAuthFormat(auth) {
+  const migrated = {};
+  for (const [provider, value] of Object.entries(auth)) {
+    if (Array.isArray(value)) {
+      // Already new format
+      migrated[provider] = value;
+    } else if (value && typeof value === 'object' && value.key) {
+      // Old single-key format — wrap in array
+      migrated[provider] = [
+        {
+          key: value.key,
+          label: 'primary',
+          savedAt: value.savedAt || new Date().toISOString(),
+          expiresAt: value.expiresAt || null,
+          priority: 1,
+          enabled: true,
+        },
+      ];
+    } else {
+      migrated[provider] = value;
+    }
+  }
+  return migrated;
+}
+
+/**
+ * Load .dualbrain/auth.json, migrating old single-key format to array format.
+ * @param {string} [cwd]
+ * @returns {object} auth object with arrays per provider
+ */
+function loadAuthKeys(cwd) {
+  try {
+    const raw = JSON.parse(readFileSync(AUTH_FILE(cwd), 'utf8'));
+    return _migrateAuthFormat(raw);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Returns the highest-priority, non-expired, enabled key for a provider.
+ * @param {string} provider
+ * @param {string} [cwd]
+ * @returns {{ key: string, label: string, priority: number, enabled: boolean, expiresAt: string|null }|null}
+ */
+function getActiveKey(provider, cwd) {
+  const auth = loadAuthKeys(cwd);
+  const keys = auth[provider] || [];
+  const now = new Date();
+
+  const valid = keys
+    .filter(k => k.enabled)
+    .filter(k => !k.expiresAt || new Date(k.expiresAt) > now)
+    .sort((a, b) => (a.priority || 99) - (b.priority || 99));
+
+  return valid[0] || null;
+}
+
+/**
+ * Append a new key to the provider's array in .dualbrain/auth.json.
+ * Injects the highest-priority valid key into process.env.
+ * @param {string} provider
+ * @param {string} key
+ * @param {object} [opts]
+ * @param {string} [opts.label]
+ * @param {string|null} [opts.expiresAt]
+ * @param {number} [opts.priority]
+ * @param {string} [opts.cwd]
+ */
+function saveAuthKey(provider, key, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const authFile = AUTH_FILE(cwd);
+  const dir = dirname(authFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const auth = loadAuthKeys(cwd);
+  if (!Array.isArray(auth[provider])) auth[provider] = [];
+
+  // Determine default label and priority
+  const existing = auth[provider];
+  const defaultLabel = `key-${existing.length + 1}`;
+  const defaultPriority = existing.length > 0
+    ? Math.max(...existing.map(k => k.priority || 1)) + 1
+    : 1;
+
+  existing.push({
+    key,
+    label: opts.label || defaultLabel,
+    savedAt: new Date().toISOString(),
+    expiresAt: opts.expiresAt || null,
+    priority: opts.priority !== undefined ? opts.priority : defaultPriority,
+    enabled: true,
+  });
+
+  writeFileSync(authFile, JSON.stringify(auth, null, 2));
+
+  // Inject highest-priority valid key into process.env for this session
+  const active = getActiveKey(provider, cwd);
+  if (active) {
+    if (provider === 'claude') process.env.ANTHROPIC_API_KEY = active.key;
+    if (provider === 'openai') process.env.OPENAI_API_KEY = active.key;
+  }
+}
+
+/**
+ * Remove a key by index from the provider's array.
+ * @param {string} provider
+ * @param {number} index
+ * @param {string} [cwd]
+ */
+function removeAuthKey(provider, index, cwd) {
+  const authFile = AUTH_FILE(cwd);
+  const dir = dirname(authFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const auth = loadAuthKeys(cwd);
+  if (!Array.isArray(auth[provider])) return;
+
+  auth[provider].splice(index, 1);
+  writeFileSync(authFile, JSON.stringify(auth, null, 2));
+}
+
+/**
+ * Mark a key as enabled:false (used during failover when a key hits rate limits).
+ * @param {string} provider
+ * @param {number} index
+ * @param {string} [cwd]
+ */
+function disableKey(provider, index, cwd) {
+  const authFile = AUTH_FILE(cwd);
+  const dir = dirname(authFile);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const auth = loadAuthKeys(cwd);
+  if (!Array.isArray(auth[provider]) || !auth[provider][index]) return;
+
+  auth[provider][index].enabled = false;
+  writeFileSync(authFile, JSON.stringify(auth, null, 2));
+}
+
+/**
+ * Called when the active key hits a rate limit. Disables the current active key
+ * temporarily and returns the next valid key, or null if none available.
+ * @param {string} provider
+ * @param {string} [cwd]
+ * @returns {{ key: string, label: string, priority: number, enabled: boolean, expiresAt: string|null }|null}
+ */
+function rotateToNextKey(provider, cwd) {
+  const auth = loadAuthKeys(cwd);
+  const keys = auth[provider] || [];
+  const now = new Date();
+
+  // Find current active key index
+  const sortedValid = keys
+    .map((k, i) => ({ ...k, _idx: i }))
+    .filter(k => k.enabled)
+    .filter(k => !k.expiresAt || new Date(k.expiresAt) > now)
+    .sort((a, b) => (a.priority || 99) - (b.priority || 99));
+
+  if (sortedValid.length === 0) return null;
+
+  // Disable the current active key
+  const currentIdx = sortedValid[0]._idx;
+  disableKey(provider, currentIdx, cwd);
+
+  // Reload and get the next valid key
+  return getActiveKey(provider, cwd);
+}
+
+/**
+ * Interactive setup flow: walks user through entering API keys for missing providers.
+ * Accepts an existing readline Interface (rl) — does NOT close it.
+ * @param {import('readline').Interface} rl
+ */
+async function setupAuth(rl) {
+  const ask = (q) => new Promise(res => rl.question(q, res));
+  const auth = await detectAuth();
+
+  // Claude setup
+  if (!auth.claude.found) {
+    console.log('\n— Claude Setup —');
+    console.log('Options:');
+    console.log('  (1) Paste API key (recommended for Replit)');
+    console.log('  (2) Skip for now');
+    const choice = (await ask('> ')).trim();
+    if (choice === '1') {
+      const key = (await ask('Paste your Anthropic API key: ')).trim();
+      if (key && (key.startsWith('sk-ant-') || key.startsWith('sk-'))) {
+        const labelStr = (await ask('Label for this key (or Enter for "key-1"): ')).trim();
+        const label = labelStr || undefined;
+        const expiryStr = (await ask('Set expiry in days (or Enter to skip): ')).trim();
+        let expiresAt = null;
+        if (expiryStr && /^\d+$/.test(expiryStr)) {
+          const d = new Date();
+          d.setDate(d.getDate() + parseInt(expiryStr, 10));
+          expiresAt = d.toISOString();
+          console.log(`✓ Key expires in ${expiryStr} days (${d.toISOString().slice(0, 10)})`);
+        }
+        saveAuthKey('claude', key, { expiresAt, label });
+        console.log('✓ Claude API key saved');
+      } else {
+        console.log('Invalid key format. Expected sk-ant-... or sk-...');
+      }
+    }
+  } else {
+    console.log(`\n✓ Claude: already configured via ${auth.claude.source}`);
+  }
+
+  // OpenAI setup
+  if (!auth.openai.found) {
+    console.log('\n— OpenAI Setup —');
+    console.log('Options:');
+    console.log('  (1) Paste API key (recommended for Replit)');
+    console.log('  (2) Skip for now');
+    const choice = (await ask('> ')).trim();
+    if (choice === '1') {
+      const key = (await ask('Paste your OpenAI API key: ')).trim();
+      if (key && key.startsWith('sk-')) {
+        const labelStr = (await ask('Label for this key (or Enter for "key-1"): ')).trim();
+        const label = labelStr || undefined;
+        const expiryStr = (await ask('Set expiry in days (or Enter to skip): ')).trim();
+        let expiresAt = null;
+        if (expiryStr && /^\d+$/.test(expiryStr)) {
+          const d = new Date();
+          d.setDate(d.getDate() + parseInt(expiryStr, 10));
+          expiresAt = d.toISOString();
+          console.log(`✓ Key expires in ${expiryStr} days (${d.toISOString().slice(0, 10)})`);
+        }
+        saveAuthKey('openai', key, { expiresAt, label });
+        console.log('✓ OpenAI API key saved');
+      } else {
+        console.log('Invalid key format. Expected sk-...');
+      }
+    }
+  } else {
+    console.log(`\n✓ OpenAI: already configured via ${auth.openai.source}`);
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Auto-detect subscription plans from provider config files
 // ---------------------------------------------------------------------------
@@ -414,7 +710,10 @@ function saveProfile(profile, opts = {}) {
 async function runOnboarding(opts = {}) {
   if (!opts.interactive) return defaultProfile();
 
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  // Accept an externally-provided readline instance (shared with REPL/auth setup)
+  // or create one internally if not provided. Only close if we created it.
+  const rlProvided = !!opts.rl;
+  const rl = opts.rl || createInterface({ input: process.stdin, output: process.stdout });
   const ask = (q) => new Promise(res => rl.question(q, res));
   const profile = defaultProfile();
 
@@ -440,7 +739,8 @@ async function runOnboarding(opts = {}) {
     profile.mode = n >= 2 ? 'dual' : profile.providers.claude.enabled ? 'solo-claude' : 'solo-openai';
     process.stdout.write('\nProfile saved.\n');
   } finally {
-    rl.close();
+    // Only close if we created the rl instance (not if it was passed in)
+    if (!rlProvided) rl.close();
   }
   return profile;
 }
@@ -582,4 +882,6 @@ export {
   getAvailableProviders, isSoloBrain, getHeadModel,
   detectPlans, syncPreferencesToMemory,
   detectAuth, detectEnvironment,
+  setupAuth, saveAuthKey, loadAuthKeys,
+  getActiveKey, removeAuthKey, disableKey, rotateToNextKey,
 };

package/src/tui.mjs

@@ -0,0 +1,188 @@
+/**
+ * tui.mjs — Zero-dependency terminal UI renderer for the dual-brain CLI.
+ * All functions return strings; callers use console.log to print.
+ */
+
+import { fileURLToPath } from 'node:url';
+
+// ─── Unicode / ASCII mode ─────────────────────────────────────────────────────
+
+export const useUnicode =
+  process.env.DUALBRAIN_ASCII !== '1' && process.stdout.isTTY !== false;
+
+const CH = useUnicode
+  ? { tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║', ts: '╠', te: '╣', fill: '█', empty: '░' }
+  : { tl: '+', tr: '+', bl: '+', br: '+', h: '-', v: '|', ts: '+', te: '+', fill: '#', empty: '.' };
+
+// ─── ANSI / emoji helpers ─────────────────────────────────────────────────────
+
+/** Strip ANSI escape codes from a string. */
+export function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return String(str).replace(/\x1B\[[0-9;]*[A-Za-z]/g, '');
+}
+
+/**
+ * Visible display length of a string.
+ * Strips ANSI codes and counts each emoji as 2 columns wide.
+ */
+export function visibleLength(str) {
+  const plain = stripAnsi(String(str));
+  let len = 0;
+  for (const ch of plain) {
+    const cp = ch.codePointAt(0);
+    // Emoji / wide symbol ranges (covers most common emoji)
+    if (
+      (cp >= 0x1f300 && cp <= 0x1faff) || // Misc symbols, emoji
+      (cp >= 0x2600  && cp <= 0x27bf)  || // Misc symbols
+      (cp >= 0xfe00  && cp <= 0xfe0f)  || // Variation selectors
+      (cp >= 0x1f1e0 && cp <= 0x1f1ff) || // Flags
+      cp === 0x20e3                        // Combining enclosing keycap
+    ) {
+      len += 2;
+    } else {
+      len += 1;
+    }
+  }
+  return len;
+}
+
+/**
+ * Right-pad `str` with spaces so that its visible width equals `width`.
+ * Accounts for emoji (2-wide) and ANSI codes.
+ */
+export function pad(str, width) {
+  const vl = visibleLength(str);
+  const spaces = Math.max(0, width - vl);
+  return String(str) + ' '.repeat(spaces);
+}
+
+// ─── box ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Renders a Unicode (or ASCII) box with a title bar.
+ * @param {string} title
+ * @param {string[]} lines
+ * @param {{ width?: number }} opts
+ * @returns {string}
+ */
+export function box(title, lines = [], opts = {}) {
+  const inner = opts.width ?? 56;
+  const total = inner + 2; // 2 spaces padding on each side counted inside border
+
+  const top    = CH.tl + CH.h.repeat(total) + CH.tr;
+  const divider = CH.ts + CH.h.repeat(total) + CH.te;
+  const bottom = CH.bl + CH.h.repeat(total) + CH.br;
+
+  // Title row: 2-space left pad
+  const titleContent = '  ' + title;
+  const titleRow = CH.v + pad(titleContent, total) + CH.v;
+
+  const bodyRows = lines.map(line => {
+    const content = '  ' + line;
+    return CH.v + pad(content, total) + CH.v;
+  });
+
+  return [top, titleRow, divider, ...bodyRows, bottom].join('\n');
+}
+
+// ─── bar ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Renders a percentage bar.
+ * @param {number} percent  0–100
+ * @param {number} width    bar width in chars (default 20)
+ * @param {{ label?: string }} opts
+ * @returns {string}
+ */
+export function bar(percent, width = 20, opts = {}) {
+  const pct = Math.max(0, Math.min(100, percent));
+  const filled = Math.round((pct / 100) * width);
+  const empty  = width - filled;
+
+  const track = CH.fill.repeat(filled) + CH.empty.repeat(empty);
+  const pctStr = String(Math.round(pct)).padStart(3) + '%';
+  const label  = opts.label ? `  ${opts.label}` : '';
+
+  return `${track}  ${pctStr}${label}`;
+}
+
+// ─── badge ────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns a status badge emoji/symbol.
+ * @param {string} status
+ * @returns {string}
+ */
+export function badge(status) {
+  const map = {
+    healthy:   '🟢',
+    degraded:  '🟡',
+    hot:       '🔴',
+    probing:   '🟠',
+    connected: '✅',
+    missing:   '❌',
+    warning:   '⚠️',
+  };
+  return map[status] ?? '❓';
+}
+
+// ─── separator ───────────────────────────────────────────────────────────────
+
+/**
+ * Returns a section separator line.
+ * @param {string} label
+ * @returns {string}
+ */
+export function separator(label = '') {
+  const dash = useUnicode ? '─' : '-';
+  return label
+    ? `  ${dash}${dash}${dash} ${label}`
+    : `  ${dash}${dash}${dash}`;
+}
+
+// ─── menu ────────────────────────────────────────────────────────────────────
+
+/**
+ * Renders a numbered/lettered menu grouped by section.
+ * @param {{ key: string, label: string, section?: string }[]} options
+ * @param {object} opts  (reserved)
+ * @returns {string}
+ */
+export function menu(options, opts = {}) {
+  const rows = [];
+  let lastSection = Symbol('none');
+
+  for (const opt of options) {
+    const section = opt.section ?? '';
+    if (section !== lastSection) {
+      if (section) {
+        rows.push(separator(section));
+      } else {
+        rows.push(separator());
+      }
+      lastSection = section;
+    }
+    rows.push(`  [${opt.key}] ${opt.label}`);
+  }
+
+  return rows.join('\n');
+}
+
+// ─── Self-test ────────────────────────────────────────────────────────────────
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  console.log(box('🧠 Dual-Brain v7.0.2', [
+    '🟢 Claude ✅  🟢 OpenAI ✅',
+    '🌀 Replit + replit-tools',
+  ]));
+  console.log(bar(75, 20, { label: 'Claude' }));
+  console.log(bar(25, 20, { label: 'OpenAI' }));
+  console.log(menu([
+    { key: 'c', label: 'Continue last session', section: 'Sessions' },
+    { key: 'n', label: 'New session',           section: 'Sessions' },
+    { key: 'a', label: 'Auth management',       section: 'Settings' },
+    { key: 'p', label: 'Profile settings',      section: 'Settings' },
+    { key: 's', label: 'Exit to shell',         section: '' },
+  ]));
+}