dual-brain 7.1.16 → 7.1.17

package/bin/dual-brain.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // dual-brain — CLI entry point. Commands: init, go, status, remember, forget
 
-import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync, unlinkSync } from 'node:fs';
+import { appendFileSync, existsSync, readFileSync, mkdirSync, writeFileSync, statSync, readdirSync, unlinkSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execSync, spawnSync as _spawnSyncTop } from 'node:child_process';
@@ -169,6 +169,14 @@ Commands:
   remember "preference"     Save a project-scoped preference
   forget "preference"       Remove a preference by fuzzy match
   search "keyword"           Search across all sessions
+  specialists               List available specialist agents with descriptions
+  python "task"             Force Python specialist for the task
+  typescript "task"         Force TypeScript specialist for the task
+  html "task"               Force HTML/CSS specialist for the task
+  linux "task"              Force Linux/DevOps specialist for the task
+  security "task"           Force Security specialist for the task
+    --dry-run               (specialist commands) Show routing without executing
+    --files a,b             (specialist commands) Provide file context
   shell-hook                Output bash snippet to add dual-brain to your shell
                             Usage: dual-brain shell-hook >> ~/.bashrc
 
@@ -611,6 +619,53 @@ function cmdForget(text) {
   console.log('Preference removed (if matched).');
 }
 
+function cmdBreakGlass(reason) {
+  if (!reason) err('Usage: dual-brain break-glass "reason"');
+  const cwd = process.cwd();
+  const dualbrain = join(cwd, '.dualbrain');
+  const tokenPath = join(dualbrain, 'break-glass.json');
+  const auditDir  = join(dualbrain, 'audit');
+  const auditFile = join(auditDir, 'head-audit.jsonl');
+  const TTL_MINUTES = 5;
+
+  mkdirSync(dualbrain, { recursive: true });
+  mkdirSync(auditDir, { recursive: true });
+
+  const token = {
+    createdAt: Date.now(),
+    ttlMinutes: TTL_MINUTES,
+    reason,
+  };
+  writeFileSync(tokenPath, JSON.stringify(token, null, 2));
+
+  // Audit entry
+  const auditEntry = {
+    ts: new Date().toISOString(),
+    event: 'break-glass-activated',
+    reason,
+    ttlMinutes: TTL_MINUTES,
+    expiresAt: new Date(token.createdAt + TTL_MINUTES * 60 * 1000).toISOString(),
+  };
+  try {
+    appendFileSync(auditFile, JSON.stringify(auditEntry) + '\n');
+  } catch { /* non-fatal */ }
+
+  const width = 51;
+  const inner = width - 2;
+  const pad = (s) => ' ' + s + ' '.repeat(inner - 1 - s.length);
+  const reasonLine  = `Reason: ${reason}`;
+  const expiresLine = `Expires: ${TTL_MINUTES} minutes`;
+  const auditLine   = 'All tool calls logged to audit.';
+
+  console.log('┌' + '─'.repeat(inner) + '┐');
+  console.log('│' + pad('🔓 Break-Glass Activated') + '│');
+  console.log('├' + '─'.repeat(inner) + '┤');
+  console.log('│' + pad(reasonLine) + '│');
+  console.log('│' + pad(expiresLine) + '│');
+  console.log('│' + pad(auditLine) + '│');
+  console.log('└' + '─'.repeat(inner) + '┘');
+}
+
 // ─── Screen helpers ───────────────────────────────────────────────────────────
 
 /**
@@ -1582,6 +1637,282 @@ async function subscriptionsScreen(rl, ask) {
   return { next: 'main' };
 }
 
+// ─── Onboarding Wizard ───────────────────────────────────────────────────────
+
+/**
+ * 5-step onboarding wizard shown on first run (no .dualbrain/profile.json).
+ * Matches the rounded ┌─┐ box style used in mainScreen / renderHeader.
+ * @param {{ auth, plans, existingSessions }} detection
+ * @param {string} cwd
+ * @param {object} rl  readline interface
+ * @returns {object|null}  profile object to save, or null if cancelled/skipped
+ */
+async function runOnboardingWizard(detection, cwd, rl) {
+  const ask = (q) => new Promise(res => rl.question(q, res));
+  const version = readVersion();
+
+  // ── Rounded box helpers (matching mainScreen style) ────────────────────────
+  const W = 51;
+  const wTop    = `  ┌${'─'.repeat(W)}┐`;
+  const wSep    = `  ├${'─'.repeat(W)}┤`;
+  const wBottom = `  └${'─'.repeat(W)}┘`;
+  const wPad = (s) => {
+    const plain = s.replace(/\x1b\[[0-9;]*m/g, '');
+    let vlen = 0;
+    for (const ch of plain) {
+      const cp = ch.codePointAt(0);
+      if (
+        (cp >= 0x1f300 && cp <= 0x1faff) ||
+        (cp >= 0x2600  && cp <= 0x27bf)  ||
+        cp === 0xfe0f || cp === 0x20e3
+      ) { vlen += 2; } else { vlen += 1; }
+    }
+    return s + ' '.repeat(Math.max(0, W - vlen));
+  };
+  const wRow = (s) => `  │ ${wPad(s)}│`;
+
+  // ── Collected wizard state ─────────────────────────────────────────────────
+  const state = {
+    claudePlan:     null,
+    openaiPlan:     null,
+    headModel:      null,
+    importSessions: false,
+    profile:        'auto',
+  };
+
+  const { auth, plans, existingSessions } = detection;
+  const claudeReady = auth.claude.found;
+  const openaiReady = auth.openai.found;
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Step 1 — Welcome & provider detection
+  // ══════════════════════════════════════════════════════════════════════════
+  console.log('');
+  console.log(wTop);
+  console.log(wRow(`🧠 Dual-Brain v${version} — First-time Setup`));
+  console.log(wSep);
+  console.log(wRow(`Step 1 of 5: Detected providers`));
+  console.log(wSep);
+
+  const claudePlanLabel = claudeReady
+    ? (CLAUDE_PLAN_LABELS[plans.claude] ?? plans.claude ?? 'plan unknown')
+    : null;
+  const openaiPlanLabel = openaiReady
+    ? (OPENAI_PLAN_LABELS[plans.openai] ?? plans.openai ?? 'plan unknown')
+    : null;
+
+  console.log(wRow(claudeReady
+    ? `✓ Claude CLI  ${claudePlanLabel ? `(${claudePlanLabel})` : ''}`
+    : `✗ Claude CLI  not logged in`));
+  console.log(wRow(openaiReady
+    ? `✓ Codex CLI   ${openaiPlanLabel ? `(${openaiPlanLabel})` : ''}`
+    : `✗ Codex CLI   not logged in`));
+  if (existingSessions.length > 0) {
+    console.log(wRow(`✓ ${existingSessions.length} data-tools session${existingSessions.length !== 1 ? 's' : ''} found`));
+  }
+  console.log(wSep);
+  console.log(wRow(`[Enter] Continue setup   [s] Skip wizard`));
+  console.log(wBottom);
+  console.log('');
+
+  if (!claudeReady && !openaiReady) {
+    console.log('  No AI provider found. Log in first:');
+    console.log('    claude auth login   — for Claude');
+    console.log('    codex login         — for OpenAI/Codex');
+    console.log('  Then re-run: dual-brain init\n');
+    return null;
+  }
+
+  const step1 = (await ask('  > ')).trim().toLowerCase();
+  if (step1 === 's') {
+    // Skip: auto-save detected plans and proceed directly
+    const skippedProfile = loadProfile(cwd);
+    if (claudeReady) skippedProfile.providers.claude = { enabled: true, plan: plans.claude || 'pro' };
+    if (openaiReady) skippedProfile.providers.openai = { enabled: true, plan: plans.openai || 'plus' };
+    const enabledCount = [claudeReady, openaiReady].filter(Boolean).length;
+    skippedProfile.mode = enabledCount >= 2 ? 'auto' : claudeReady ? 'solo-claude' : 'solo-openai';
+    return skippedProfile;
+  }
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Step 2 — Budget / plan selection
+  // ══════════════════════════════════════════════════════════════════════════
+  console.log('');
+  console.log(wTop);
+  console.log(wRow(`🧠 Dual-Brain v${version} — First-time Setup`));
+  console.log(wSep);
+  console.log(wRow(`Step 2 of 5: Subscription plans`));
+  console.log(wSep);
+
+  if (claudeReady) {
+    const detectedClaudePlan = plans.claude || 'pro';
+    const detectedClaudeLabel = CLAUDE_PLAN_LABELS[detectedClaudePlan] ?? detectedClaudePlan;
+    console.log(wRow(`Claude — detected: ${detectedClaudeLabel}`));
+    console.log(wRow(`  [1] Pro ($20/mo)`));
+    console.log(wRow(`  [2] Max x5 ($100/mo)`));
+    console.log(wRow(`  [3] Max x20 ($200/mo)`));
+    console.log(wRow(`  [Enter] Keep detected (${detectedClaudeLabel})`));
+    console.log(wSep);
+    const claudeChoice = (await ask('  Claude plan [1/2/3/Enter]: ')).trim();
+    const claudePlanMap = { '1': 'pro', '2': 'max5', '3': 'max20' };
+    state.claudePlan = claudePlanMap[claudeChoice] || detectedClaudePlan;
+  }
+
+  if (openaiReady) {
+    const detectedOpenaiPlan = plans.openai || 'plus';
+    const detectedOpenaiLabel = OPENAI_PLAN_LABELS[detectedOpenaiPlan] ?? detectedOpenaiPlan;
+    console.log(wRow(`OpenAI — detected: ${detectedOpenaiLabel}`));
+    console.log(wRow(`  [1] Plus ($20/mo)`));
+    console.log(wRow(`  [2] Pro ($100/mo)`));
+    console.log(wRow(`  [3] Pro ($200/mo higher limits)`));
+    console.log(wRow(`  [Enter] Keep detected (${detectedOpenaiLabel})`));
+    console.log(wSep);
+    const openaiChoice = (await ask('  OpenAI plan [1/2/3/Enter]: ')).trim();
+    const openaiPlanMap = { '1': 'plus', '2': 'pro', '3': 'pro200' };
+    state.openaiPlan = openaiPlanMap[openaiChoice] || detectedOpenaiPlan;
+  }
+
+  console.log(wBottom);
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Step 3 — HEAD model selection
+  // ══════════════════════════════════════════════════════════════════════════
+  const hasBigPlan = state.claudePlan === 'max5' || state.claudePlan === 'max20';
+  const recommendedModel = hasBigPlan ? 'claude-opus-4-5' : 'claude-sonnet-4-5';
+  const recommendedLabel = hasBigPlan
+    ? 'Opus (Max plan — best quality)'
+    : 'Sonnet (Pro plan — balanced speed/quality)';
+
+  console.log('');
+  console.log(wTop);
+  console.log(wRow(`🧠 Dual-Brain v${version} — First-time Setup`));
+  console.log(wSep);
+  console.log(wRow(`Step 3 of 5: HEAD model (think-tier)`));
+  console.log(wSep);
+  console.log(wRow(`Recommended: ${recommendedLabel}`));
+  console.log(wSep);
+  console.log(wRow(`  [1] Haiku   — fastest, lowest cost`));
+  console.log(wRow(`  [2] Sonnet  — balanced (recommended for Pro)`));
+  console.log(wRow(`  [3] Opus    — best quality (recommended for Max)`));
+  console.log(wRow(`  [Enter] Use recommended`));
+  console.log(wBottom);
+  console.log('');
+
+  const step3 = (await ask('  HEAD model [1/2/3/Enter]: ')).trim();
+  const modelMap = {
+    '1': 'claude-haiku-4-5',
+    '2': 'claude-sonnet-4-5',
+    '3': 'claude-opus-4-5',
+  };
+  state.headModel = modelMap[step3] || recommendedModel;
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Step 4 — Import sessions + profile selection
+  // ══════════════════════════════════════════════════════════════════════════
+  console.log('');
+  console.log(wTop);
+  console.log(wRow(`🧠 Dual-Brain v${version} — First-time Setup`));
+  console.log(wSep);
+  console.log(wRow(`Step 4 of 5: Sessions & routing profile`));
+  console.log(wSep);
+
+  if (existingSessions.length > 0) {
+    console.log(wRow(`Import ${existingSessions.length} data-tools session${existingSessions.length !== 1 ? 's' : ''}?`));
+    console.log(wRow(`  [y] Yes   [Enter/n] Skip`));
+    console.log(wSep);
+    const importChoice = (await ask('  Import sessions [y/Enter]: ')).trim().toLowerCase();
+    state.importSessions = importChoice === 'y';
+    if (state.importSessions) {
+      console.log('');
+      console.log(`  Importing ${existingSessions.length} sessions...`);
+      const recent = existingSessions.slice(0, 5);
+      for (const sess of recent) {
+        console.log(`  ${sess.age.padEnd(6)}  ${sess.name}`);
+      }
+      if (existingSessions.length > 5) {
+        console.log(`  ... and ${existingSessions.length - 5} more`);
+      }
+    }
+    console.log(wSep);
+  }
+
+  console.log(wRow(`Routing profile:`));
+  console.log(wRow(`  [1] auto         — adapts based on task risk & outcomes`));
+  console.log(wRow(`  [2] balanced     — best model per tier, normal budgets`));
+  console.log(wRow(`  [3] cost-saver   — prefer cheaper models, skip GPT`));
+  console.log(wRow(`  [4] quality-first — dual-brain for medium+ risk`));
+  console.log(wRow(`  [Enter] auto (recommended)`));
+  console.log(wBottom);
+  console.log('');
+
+  const step4 = (await ask('  Profile [1/2/3/4/Enter]: ')).trim();
+  const profileMap = { '1': 'auto', '2': 'balanced', '3': 'cost-saver', '4': 'quality-first' };
+  state.profile = profileMap[step4] || 'auto';
+
+  // ══════════════════════════════════════════════════════════════════════════
+  // Step 5 — Summary & confirm
+  // ══════════════════════════════════════════════════════════════════════════
+  const claudeSummary = state.claudePlan
+    ? `Claude:     ${CLAUDE_PLAN_LABELS[state.claudePlan] ?? state.claudePlan}`
+    : `Claude:     not configured`;
+  const openaiSummary = state.openaiPlan
+    ? `OpenAI:     ${OPENAI_PLAN_LABELS[state.openaiPlan] ?? state.openaiPlan}`
+    : `OpenAI:     not configured`;
+  const modelSummary   = `HEAD model: ${state.headModel}`;
+  const profileSummary = `Profile:    ${state.profile}`;
+  const sessionSummary = existingSessions.length > 0
+    ? `Sessions:   ${state.importSessions ? `${existingSessions.length} imported` : 'skipped'}`
+    : null;
+
+  console.log('');
+  console.log(wTop);
+  console.log(wRow(`🧠 Dual-Brain v${version} — First-time Setup`));
+  console.log(wSep);
+  console.log(wRow(`Step 5 of 5: Summary`));
+  console.log(wSep);
+  console.log(wRow(claudeSummary));
+  console.log(wRow(openaiSummary));
+  console.log(wRow(modelSummary));
+  console.log(wRow(profileSummary));
+  if (sessionSummary) console.log(wRow(sessionSummary));
+  console.log(wSep);
+  console.log(wRow(`[Enter] Save and start   [q] Quit without saving`));
+  console.log(wBottom);
+  console.log('');
+
+  const step5 = (await ask('  > ')).trim().toLowerCase();
+  if (step5 === 'q') {
+    console.log('\n  Setup cancelled.\n');
+    return null;
+  }
+
+  // ── Build and return the profile object ────────────────────────────────────
+  const finalProfile = loadProfile(cwd);
+
+  if (state.claudePlan) {
+    finalProfile.providers.claude = { enabled: true, plan: state.claudePlan };
+  } else if (claudeReady) {
+    finalProfile.providers.claude = { enabled: true, plan: plans.claude || 'pro' };
+  }
+
+  if (state.openaiPlan) {
+    finalProfile.providers.openai = { enabled: true, plan: state.openaiPlan };
+  } else if (openaiReady) {
+    finalProfile.providers.openai = { enabled: true, plan: plans.openai || 'plus' };
+  }
+
+  const enabledCount = [
+    finalProfile.providers?.claude?.enabled,
+    finalProfile.providers?.openai?.enabled,
+  ].filter(Boolean).length;
+
+  finalProfile.mode = enabledCount >= 2 ? state.profile : claudeReady ? 'solo-claude' : 'solo-openai';
+  finalProfile.headModel = state.headModel;
+  finalProfile.bias = state.profile;
+
+  return finalProfile;
+}
+
 // ─── Screen: dashboardScreen (kept for internal reference, unreachable) ───────
 
 async function dashboardScreen(rl, ask) {
@@ -2223,6 +2554,151 @@ async function runScreens(startScreen = 'dashboard') {
   rl.close();
 }
 
+// ─── Specialist commands ──────────────────────────────────────────────────────
+
+const SPECIALIST_DEFAULTS = {
+  python:     { name: 'Python',       description: 'Python stdlib, typing, async' },
+  typescript: { name: 'TypeScript',   description: 'TS type system, React, Node' },
+  html:       { name: 'HTML/CSS',     description: 'Semantic HTML, CSS, accessibility' },
+  linux:      { name: 'Linux/DevOps', description: 'Sysadmin, Docker, nginx, shell' },
+  security:   { name: 'Security',     description: 'Auth, crypto, OWASP, threat model' },
+};
+
+function loadSpecialistRegistry() {
+  const regPath = join(__dirname, '..', 'agents', 'specialists', 'registry.json');
+  try {
+    const raw = JSON.parse(readFileSync(regPath, 'utf8'));
+    const out = {};
+    for (const [key, val] of Object.entries(raw.specialists || {})) {
+      out[key] = { name: val.name || key, description: val.description || '' };
+    }
+    return out;
+  } catch {
+    return SPECIALIST_DEFAULTS;
+  }
+}
+
+function cmdSpecialists() {
+  const registry = loadSpecialistRegistry();
+  const entries  = Object.entries(registry);
+
+  // Build padded rows
+  const rows = entries.map(([key, val]) => {
+    const k = key.padEnd(12);
+    const d = val.description;
+    return `│  ${k}${d}`;
+  });
+
+  // Find longest row for width
+  const inner = Math.max(
+    ...rows.map(r => r.length),
+    '│ Usage: dual-brain python "task description"     │'.length - 2,
+  );
+  const width = inner + 1; // account for trailing │
+
+  function pad(str) {
+    return str + ' '.repeat(Math.max(0, width - str.length - 1)) + '│';
+  }
+
+  const top    = '┌' + '─'.repeat(width - 1) + '┐';
+  const title  = pad('│ 🎯 Available Specialists');
+  const divTop = '├' + '─'.repeat(width - 1) + '┤';
+  const divBot = '├' + '─'.repeat(width - 1) + '┤';
+  const bot    = '└' + '─'.repeat(width - 1) + '┘';
+
+  console.log(top);
+  console.log(title);
+  console.log(divTop);
+  for (const row of rows) console.log(pad(row));
+  console.log(divBot);
+  console.log(pad('│ Usage: dual-brain python "task description"'));
+  console.log(pad('│ Auto-routing: off (use dual-brain go for auto)'));
+  console.log(bot);
+}
+
+async function cmdSpecialistGo(specialist, args) {
+  const dryRun   = args.includes('--dry-run');
+  const verbose  = args.includes('--verbose') || args.includes('-v');
+  const filesRaw = flag(args, '--files');
+  const files    = filesRaw && typeof filesRaw === 'string'
+    ? filesRaw.split(',').map(f => f.trim()).filter(Boolean)
+    : [];
+
+  const prompt = args.find(a => !a.startsWith('--') && !a.startsWith('-') && a !== (filesRaw ?? ''));
+  if (!prompt) err(`Usage: dual-brain ${specialist} "task description" [--dry-run] [--files a,b]`);
+
+  const cwd     = process.cwd();
+  const profile = await ensureProfile(cwd);
+  const detection = detectTask({ prompt, files });
+
+  // Override specialist, preserve everything else
+  detection.specialist = specialist;
+
+  console.log(`[specialist: ${specialist}] ${detection.explanation}`);
+
+  if (verbose) {
+    vtrace(`Intent: ${detection.intent} | Risk: ${detection.risk} | Complexity: ${detection.complexity} | Effort: ${detection.effort ?? 'n/a'}`);
+    vtrace(`Tier: ${detection.tier} | Specialist override: ${specialist}`);
+  }
+
+  const decision = decideRoute({ profile, detection, cwd });
+
+  if (verbose) {
+    const modelLabel = decision.effort ? `${decision.model} (${decision.effort})` : decision.model;
+    vtrace(`Model selection: ${modelLabel}`);
+    vtrace(`Dual-brain: ${decision.dualBrain ? 'yes' : 'no'}`);
+  }
+
+  console.log(`  specialist : ${specialist}`);
+  console.log(`  provider   : ${decision.provider}`);
+  console.log(`  model      : ${decision.model}${decision.effort ? ' (' + decision.effort + ')' : ''}`);
+  console.log(`  tier       : ${decision.tier}`);
+  console.log(`  dual-brain : ${decision.dualBrain ? 'yes' : 'no'}`);
+  console.log(`  reason     : ${decision.explanation}`);
+
+  if (dryRun) {
+    console.log('\n(dry-run — not executing)');
+    return;
+  }
+
+  console.log('\nDispatching...');
+  let result;
+  if (decision.dualBrain) {
+    result = await dispatchDualBrain({ decision, prompt, files, cwd });
+    console.log(`\nConsensus: ${result.consensus}`);
+    if (result.claude?.summary) console.log(`Claude : ${result.claude.summary}`);
+    if (result.openai?.summary) console.log(`OpenAI : ${result.openai.summary}`);
+    saveSession({
+      objective:    prompt,
+      branch:       null,
+      filesChanged: files,
+      commandsRun:  [`dual-brain ${specialist} "${prompt}"`],
+      lastResult:   { status: 'success', summary: result.consensus || 'dual-brain complete' },
+      provider:     decision.provider,
+      nextAction:   null,
+    }, cwd);
+  } else {
+    result = await dispatch({ decision, prompt, files, cwd });
+    const statusLine = result.status === 'completed' ? 'Done' : `Failed (exit ${result.exitCode})`;
+    console.log(`\n${statusLine} in ${(result.durationMs / 1000).toFixed(1)}s`);
+    if (result.summary) console.log(result.summary);
+    if (result.error)   process.stderr.write(`${result.error}\n`);
+    saveSession({
+      objective:    prompt,
+      branch:       null,
+      filesChanged: files,
+      commandsRun:  [`dual-brain ${specialist} "${prompt}"`],
+      lastResult:   {
+        status:  result.status === 'completed' ? 'success' : 'failure',
+        summary: result.summary || (result.status === 'completed' ? 'completed' : `exit ${result.exitCode}`),
+      },
+      provider:     decision.provider,
+      nextAction:   null,
+    }, cwd);
+    if (result.status !== 'completed') process.exit(1);
+  }
+}
+
 // ─── Entry point ─────────────────────────────────────────────────────────────
 
 async function main() {
@@ -2246,9 +2722,20 @@ async function main() {
       if (profileExists(cwd)) {
         await runScreens('main');
       } else {
-        // First run: welcomeScreen handles auto-setup detection internally,
-        // then falls through to manual wizard if needed.
-        await runScreens('welcome');
+        // First run: run the 5-step onboarding wizard, then go to main.
+        process.stdout.write(`\ndual-brain v${readVersion()} — Setup\n\nDetecting your setup...\n`);
+        const auth  = await detectAuth();
+        const plans = detectPlans();
+        const existingSessions = importReplitSessions(cwd);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const wizardProfile = await runOnboardingWizard({ auth, plans, existingSessions }, cwd, rl);
+        if (wizardProfile) {
+          saveProfile(wizardProfile, { cwd });
+          await cmdInstall(cwd);
+          console.log('\n  ✅ Setup complete! Starting dual-brain...\n');
+        }
+        rl.close();
+        await runScreens('main');
       }
     } else {
       // Non-TTY: print status card and exit
@@ -2264,8 +2751,21 @@ async function main() {
 
   if (cmd === 'init') {
     if (isInteractive) {
-      // Run welcome wizard then dashboard
-      await runScreens('welcome');
+      // Run 5-step onboarding wizard then main screen
+      const cwd = process.cwd();
+      process.stdout.write(`\ndual-brain v${readVersion()} — Setup\n\nDetecting your setup...\n`);
+      const auth  = await detectAuth();
+      const plans = detectPlans();
+      const existingSessions = importReplitSessions(cwd);
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const wizardProfile = await runOnboardingWizard({ auth, plans, existingSessions }, cwd, rl);
+      if (wizardProfile) {
+        saveProfile(wizardProfile, { cwd });
+        await cmdInstall(cwd);
+        console.log('\n  ✅ Setup complete! Starting dual-brain...\n');
+      }
+      rl.close();
+      await runScreens('main');
     } else {
       await cmdInit();
     }
@@ -2282,8 +2782,14 @@ async function main() {
   if (cmd === 'status')   { await cmdStatus(args.slice(1)); return; }
   if (cmd === 'hot')      { cmdHot(args[1]); return; }
   if (cmd === 'cool')     { cmdCool(args[1]); return; }
-  if (cmd === 'remember') { cmdRemember(args[1]); return; }
-  if (cmd === 'forget')   { cmdForget(args[1]); return; }
+  if (cmd === 'remember')    { cmdRemember(args[1]); return; }
+  if (cmd === 'forget')      { cmdForget(args[1]); return; }
+  if (cmd === 'break-glass') { cmdBreakGlass(args.slice(1).join(' ')); return; }
+
+  if (cmd === 'specialists') { cmdSpecialists(); return; }
+
+  const SPECIALIST_CMDS = new Set(Object.keys(loadSpecialistRegistry()));
+  if (SPECIALIST_CMDS.has(cmd)) { await cmdSpecialistGo(cmd, args.slice(1)); return; }
 
   if (cmd === 'search') {
     const query = args.slice(1).filter(a => !a.startsWith('--')).join(' ');

package/install.mjs

@@ -14,6 +14,7 @@ import { createInterface } from 'readline';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
+import { createHash } from 'crypto';
 
 // Skip hook installation during global npm install — hooks are installed
 // when the user runs 'dual-brain install' in their project directory.
@@ -863,6 +864,39 @@ function generateGitignoreEntries(workspace) {
   return { existing, needed };
 }
 
+// ─── Hook Manifest ──────────────────────────────────────────────────────────
+
+function hashString(s) {
+  return createHash('sha256').update(s).digest('hex');
+}
+
+function generateHookManifest(settings) {
+  const hooks = settings.hooks || {};
+  const preHooks = (hooks.PreToolUse || []).flatMap(entry =>
+    (entry.hooks || []).map(h => hashString(h.command || ''))
+  );
+  const postHooks = (hooks.PostToolUse || []).flatMap(entry =>
+    (entry.hooks || []).map(h => hashString(h.command || ''))
+  );
+  const settingsHash = hashString(JSON.stringify(hooks));
+  return {
+    generatedAt: new Date().toISOString(),
+    expectedHooks: {
+      PreToolUse: preHooks,
+      PostToolUse: postHooks,
+    },
+    settingsHash,
+  };
+}
+
+function writeHookManifest(workspace, settings) {
+  const dualbrain = join(workspace, '.dualbrain');
+  mkdirSync(dualbrain, { recursive: true });
+  const manifest = generateHookManifest(settings);
+  writeFileSync(join(dualbrain, 'hook-manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+  return manifest;
+}
+
 // ─── Installation ───────────────────────────────────────────────────────────
 
 function install(workspace, env, mode) {
@@ -915,6 +949,9 @@ function install(workspace, env, mode) {
   writeFileSync(join(target, 'settings.json'), JSON.stringify(settings, null, 2) + '\n');
   actions.push('✓ settings.json (hooks registered)');
 
+  writeHookManifest(workspace, settings);
+  actions.push('✓ .dualbrain/hook-manifest.json (integrity manifest)');
+
   const claudeMd = generateClaudeMd(mode);
   writeClaudeMd(join(target, 'CLAUDE.md'), claudeMd);
   actions.push('✓ CLAUDE.md (session instructions)');

package/package.json

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

package/src/detect.mjs

@@ -1,6 +1,12 @@
 #!/usr/bin/env node
 // detect.mjs — Task detection for dual-brain. Self-contained, no internal imports.
-// Exports: detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths
+// Exports: detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths, classifySpecialist
+
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
 // ─── Intent definitions ────────────────────────────────────────────────────────
 
@@ -118,10 +124,13 @@ function estimateComplexity({ prompt, fileCount = 0, risk = 'low', intent = 'edi
 }
 
 /** Map intent + risk + complexity → tier (think / search / execute). */
-function inferTier({ intent, risk, complexity, effort }) {
+function inferTier({ intent, risk, complexity, effort, specialistTierBias }) {
   const thinkIntents = ['architecture', 'security', 'planning', 'compare', 'review'];
   if (thinkIntents.includes(intent) || risk === 'critical') return 'think';
 
+  // Specialist tier_bias can elevate to think before general tier logic
+  if (specialistTierBias === 'think') return 'think';
+
   const searchIntents = ['search', 'explain', 'format'];
   if (searchIntents.includes(intent) && effort === 'low') return 'search';
 
@@ -193,10 +202,15 @@ function detectTask(input) {
     effort = 'high';
   }
 
-  // 6. Tier
-  const tier = inferTier({ intent, risk, complexity, effort });
+  // 6. Specialist
+  const specialistResult = classifySpecialist(prompt, files);
+  const specialistDef = SPECIALIST_DEFS[specialistResult.specialist] || null;
+  const specialistTierBias = specialistDef?.tier_bias || null;
+
+  // 7. Tier
+  const tier = inferTier({ intent, risk, complexity, effort, specialistTierBias });
 
-  // 7. Explanation
+  // 8. Explanation
   const explanation = buildExplanation({ intent, risk, complexity, fileCount, priorFailures });
 
   return {
@@ -210,9 +224,99 @@ function detectTask(input) {
     designImpact,
     requiresWrite: requiresWrite(intent),
     explanation,
+    specialist: specialistResult,
   };
 }
 
+// ─── Specialist registry ──────────────────────────────────────────────────────
+
+const SPECIALIST_REGISTRY_PATH = resolve(__dirname, '../agents/specialists/registry.json');
+
+const DEFAULT_SPECIALISTS = {
+  python:     { triggers: { extensions: ['.py', '.pyx', '.pyi'], keywords: ['python', 'pip', 'pytest', 'django', 'flask', 'asyncio'] } },
+  typescript: { triggers: { extensions: ['.ts', '.tsx', '.mts'], keywords: ['typescript', 'tsc', 'generics', 'react', 'next', 'node'] } },
+  html:       { triggers: { extensions: ['.html', '.css', '.scss', '.svg'], keywords: ['html', 'css', 'accessibility', 'a11y', 'aria', 'responsive', 'tailwind'] } },
+  linux:      { triggers: { extensions: ['.sh', '.bash', '.conf', '.service', '.dockerfile'], keywords: ['linux', 'bash', 'shell', 'systemd', 'nginx', 'docker', 'ssh', 'deploy'] } },
+  security:   { triggers: { extensions: [], keywords: ['auth', 'oauth', 'jwt', 'credential', 'secret', 'encrypt', 'vulnerability', 'owasp', 'xss', 'csrf'] }, tier_bias: 'think' },
+};
+
+function loadSpecialistRegistry() {
+  try {
+    const raw = readFileSync(SPECIALIST_REGISTRY_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed.specialists || DEFAULT_SPECIALISTS;
+  } catch {
+    return DEFAULT_SPECIALISTS;
+  }
+}
+
+const SPECIALIST_DEFS = loadSpecialistRegistry();
+
+/**
+ * Classify which specialist domain best matches the prompt and file list.
+ * Returns { specialist, confidence, triggers }.
+ */
+function classifySpecialist(prompt = '', files = []) {
+  const promptLower = prompt.toLowerCase();
+  const scores = {};
+  const matchedTriggers = {};
+
+  for (const [name, def] of Object.entries(SPECIALIST_DEFS)) {
+    const { extensions = [], keywords = [] } = def.triggers || {};
+    let score = 0;
+    const hits = [];
+
+    // +2 per matching file extension
+    for (const file of files) {
+      for (const ext of extensions) {
+        if (file.endsWith(ext)) {
+          score += 2;
+          hits.push(ext);
+          break; // count each file once per specialist
+        }
+      }
+    }
+
+    // +1 per matching keyword in prompt
+    for (const kw of keywords) {
+      // Use word-boundary-aware match where possible
+      const re = new RegExp(`\\b${kw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'i');
+      if (re.test(promptLower)) {
+        score += 1;
+        hits.push(kw);
+      }
+    }
+
+    scores[name] = score;
+    matchedTriggers[name] = hits;
+  }
+
+  // Find highest score
+  let best = null;
+  let bestScore = 0;
+  let bestExtCount = 0;
+
+  for (const [name, score] of Object.entries(scores)) {
+    if (score < 2) continue;
+    const extCount = matchedTriggers[name].filter(t => t.startsWith('.')).length;
+    if (
+      score > bestScore ||
+      (score === bestScore && extCount > bestExtCount)
+    ) {
+      best = name;
+      bestScore = score;
+      bestExtCount = extCount;
+    }
+  }
+
+  if (!best) {
+    return { specialist: 'generic', confidence: 'low', triggers: [] };
+  }
+
+  const confidence = bestScore >= 4 ? 'high' : 'medium';
+  return { specialist: best, confidence, triggers: matchedTriggers[best] };
+}
+
 // ─── CLI ──────────────────────────────────────────────────────────────────────
 
 if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
@@ -238,4 +342,4 @@ if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
   console.log(JSON.stringify(result, null, 2));
 }
 
-export { detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths };
+export { detectTask, classifyIntent, classifyRisk, estimateComplexity, inferTier, extractPaths, classifySpecialist };

package/src/dispatch.mjs

@@ -8,7 +8,7 @@
 //          isInsideClaude, buildNativeDispatch, normalizeResult
 
 import { spawn } from 'node:child_process';
-import { mkdirSync, appendFileSync, existsSync } from 'node:fs';
+import { mkdirSync, appendFileSync, existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash } from 'node:crypto';
@@ -20,6 +20,52 @@ const USAGE_DIR = join(__dirname, '..', '.dualbrain', 'usage');
 const TIER_TIMEOUT_MS = { search: 60_000, execute: 120_000, think: 180_000 };
 const CLAUDE_MODEL_IDS = { opus: 'claude-opus-4-6', sonnet: 'claude-sonnet-4-6', haiku: 'claude-haiku-4-5-20251001' };
 
+// ─── Specialist prompt loader ─────────────────────────────────────────────────
+
+const SPECIALISTS_DIR = join(__dirname, '..', 'agents', 'specialists');
+
+/**
+ * Load specialist registry from agents/specialists/registry.json.
+ * Returns null if registry is missing or malformed.
+ * @returns {object|null}
+ */
+function _loadSpecialistRegistry() {
+  try {
+    const raw = readFileSync(join(SPECIALISTS_DIR, 'registry.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read agents/specialists/_base.md and agents/specialists/{specialist}.md,
+ * concatenate them (base first, specialist second). Falls back gracefully:
+ * - If base is missing, only specialist content is returned.
+ * - If specialist file is missing, only base content is returned.
+ * - If both are missing, returns an empty string.
+ *
+ * @param {string} specialist  Specialist key (e.g. 'python', 'security')
+ * @returns {string}
+ */
+function loadSpecialistPrompt(specialist) {
+  if (!specialist || specialist === 'generic') return '';
+
+  const tryRead = (filePath) => {
+    try { return readFileSync(filePath, 'utf8').trim(); } catch { return ''; }
+  };
+
+  const registry = _loadSpecialistRegistry();
+  const entry = registry?.specialists?.[specialist];
+  const promptFile = entry?.prompt_file ?? `${specialist}.md`;
+
+  const base       = tryRead(join(SPECIALISTS_DIR, '_base.md'));
+  const specific   = tryRead(join(SPECIALISTS_DIR, promptFile));
+
+  const parts = [base, specific].filter(Boolean);
+  return parts.join('\n\n');
+}
+
 // ─── Median dispatch time tracker (in-process, for slow-response detection) ──
 // Rolling window of recent dispatch durations keyed by "provider:modelClass"
 const _durationHistory = new Map();
@@ -561,7 +607,8 @@ function _prependDispatchMarker(prompt) {
 
 // ─── Main dispatch ────────────────────────────────────────────────────────────
 async function dispatch(input = {}) {
-  const { decision = {}, files = [], cwd = process.cwd(), dryRun = false } = input;
+  const { files = [], cwd = process.cwd(), dryRun = false } = input;
+  let decision = input.decision ?? {};
   let { prompt } = input;
 
   if (!prompt) throw new Error('prompt is required');
@@ -573,6 +620,30 @@ async function dispatch(input = {}) {
   // that this agent call came through the official pipeline.
   prompt = _prependDispatchMarker(prompt);
 
+  // ── Specialist prompt injection ──────────────────────────────────────────────
+  const specialist = decision.specialist && decision.specialist !== 'generic'
+    ? decision.specialist
+    : null;
+
+  if (specialist) {
+    const specialistPrompt = loadSpecialistPrompt(specialist);
+    if (specialistPrompt) {
+      prompt = `${specialistPrompt}\n\n---\n\n${prompt}`;
+      process.stderr.write(`[dual-brain] specialist: ${specialist}\n`);
+    }
+
+    // Apply tier_bias from registry if decision didn't already pin a tier
+    if (!decision.tier) {
+      const registry = _loadSpecialistRegistry();
+      const tierBias = registry?.specialists?.[specialist]?.tier_bias;
+      if (tierBias) {
+        decision = { ...decision, tier: tierBias };
+        process.stderr.write(`[dual-brain] specialist tier_bias applied: ${tierBias}\n`);
+      }
+    }
+  }
+  // ── End specialist injection ─────────────────────────────────────────────────
+
   const tier     = decision.tier ?? 'execute';
   const timeoutMs = TIER_TIMEOUT_MS[tier] ?? 120_000;
 
@@ -651,6 +722,7 @@ async function dispatch(input = {}) {
         status:        'dry-run',
         provider:      effectiveProvider,
         model:         effectiveModel,
+        specialist:    specialist ?? 'generic',
         command,
         nativeDispatch: nativeDescriptor,
         exitCode:      null,
@@ -712,6 +784,7 @@ async function dispatch(input = {}) {
       type:          'native-agent',
       provider:      effectiveProvider,
       model:         effectiveModel,
+      specialist:    specialist ?? 'generic',
       command,
       nativeDispatch: nativeDescriptor,
       exitCode,
@@ -725,7 +798,7 @@ async function dispatch(input = {}) {
   const command = buildCommand(effectiveDecision, prompt, files, cwd);
 
   if (dryRun) {
-    return { status: 'dry-run', provider: effectiveProvider, model: effectiveModel, command, exitCode: null, summary: null, durationMs: 0, usage: null, error: null };
+    return { status: 'dry-run', provider: effectiveProvider, model: effectiveModel, specialist: specialist ?? 'generic', command, exitCode: null, summary: null, durationMs: 0, usage: null, error: null };
   }
 
   // Record this dispatch against the budget
@@ -778,6 +851,7 @@ async function dispatch(input = {}) {
     status:     success ? 'completed' : 'failed',
     provider:   effectiveProvider,
     model:      effectiveModel,
+    specialist: specialist ?? 'generic',
     command,
     exitCode,
     summary,
@@ -865,4 +939,4 @@ if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
   }
 }
 
-export { dispatch, buildCommand, detectRuntime, compressResult, dispatchDualBrain, validateDispatch, checkWorktreeClean, getRetryBudget, isInsideClaude, buildNativeDispatch, normalizeResult };
+export { dispatch, buildCommand, detectRuntime, compressResult, dispatchDualBrain, validateDispatch, checkWorktreeClean, getRetryBudget, isInsideClaude, buildNativeDispatch, normalizeResult, loadSpecialistPrompt };

package/src/profile.mjs

@@ -26,6 +26,7 @@ import { createInterface } from 'readline';
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { execFile } from 'child_process';
 
 // ---------------------------------------------------------------------------
 // Claude Code memory integration
@@ -752,6 +753,230 @@ async function autoRefreshToken(cwd) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// detectExistingAuth — silent onboarding scan
+// ---------------------------------------------------------------------------
+
+/**
+ * Run a CLI command with a timeout, returning stdout as a string.
+ * Resolves with null on timeout, error, or non-zero exit.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @param {number} timeoutMs
+ * @returns {Promise<string|null>}
+ */
+function _runWithTimeout(cmd, args, timeoutMs) {
+  return new Promise(resolve => {
+    let settled = false;
+    const done = (val) => { if (!settled) { settled = true; resolve(val); } };
+
+    let child;
+    try {
+      child = execFile(cmd, args, { timeout: timeoutMs, windowsHide: true }, (err, stdout) => {
+        done(err ? null : (stdout || '').trim());
+      });
+    } catch {
+      done(null);
+      return;
+    }
+
+    // Belt-and-suspenders timeout fallback
+    const timer = setTimeout(() => {
+      try { child.kill('SIGTERM'); } catch {}
+      done(null);
+    }, timeoutMs + 500);
+
+    if (child?.on) {
+      child.on('close', () => clearTimeout(timer));
+    }
+  });
+}
+
+/**
+ * Derive a human-readable plan label from a plan tier string.
+ * @param {'claude'|'openai'} provider
+ * @param {string} plan  e.g. '$20' | '$100' | '$200'
+ */
+function _planLabel(provider, plan) {
+  const labels = {
+    claude: { '$20': 'Claude Pro ($20)', '$100': 'Claude Max x5 ($100)', '$200': 'Claude Max x20 ($200)' },
+    openai: { '$20': 'ChatGPT Plus ($20)', '$100': 'ChatGPT Pro ($100)', '$200': 'ChatGPT Pro ($200)' },
+  };
+  return labels[provider]?.[plan] ?? `${provider} ${plan}`;
+}
+
+/**
+ * Silently scan for existing auth from all known sources and return what was
+ * found, together with smart setup recommendations.
+ *
+ * Checks (in order, all non-throwing):
+ *   1. data-tools / replit-tools  — ~/.claude/credentials.json or
+ *      .replit-tools/.claude-persistent/.credentials.json for a session key
+ *   2. Claude CLI                 — `claude auth status` with 3 s timeout
+ *   3. Codex CLI                  — `codex auth status` with 3 s timeout or
+ *                                   ~/.codex/ config files
+ *   4. Existing dual-brain config — .dualbrain/profile.json
+ *
+ * Returns:
+ * {
+ *   claude:          { found: boolean, source: string|null, plan: string|null, expiresAt: string|null },
+ *   openai:          { found: boolean, source: string|null, plan: string|null },
+ *   existingProfile: boolean,
+ *   recommendations: { headModel: string, budget: string, profile: string },
+ * }
+ *
+ * @param {string} [cwd]
+ */
+async function detectExistingAuth(cwd) {
+  const home = homedir();
+  const root = cwd || process.cwd();
+
+  // -------------------------------------------------------------------------
+  // Result skeleton
+  // -------------------------------------------------------------------------
+  const result = {
+    claude:          { found: false, source: null, plan: null, expiresAt: null },
+    openai:          { found: false, source: null, plan: null },
+    existingProfile: false,
+    recommendations: { headModel: 'claude-sonnet-4-6', budget: '$20', profile: 'balanced' },
+  };
+
+  // -------------------------------------------------------------------------
+  // 1. data-tools / replit-tools — credentials.json session key
+  // -------------------------------------------------------------------------
+  const credPaths = [
+    join(root, '.replit-tools', '.claude-persistent', '.credentials.json'),
+    join(home, '.claude', '.credentials.json'),
+    // legacy replit persistent path
+    '/home/runner/workspace/.replit-tools/.claude-persistent/.credentials.json',
+  ];
+  for (const credPath of credPaths) {
+    try {
+      const creds = JSON.parse(readFileSync(credPath, 'utf8'));
+      const oauth  = creds?.claudeAiOauth;
+      if (oauth?.accessToken || oauth?.sessionKey) {
+        result.claude.found  = true;
+        result.claude.source = credPath.includes('.replit-tools') ? 'data-tools' : 'credentials.json';
+        // Expiry
+        if (oauth.expiresAt) {
+          try { result.claude.expiresAt = new Date(oauth.expiresAt).toISOString(); } catch {}
+        }
+        break;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // -------------------------------------------------------------------------
+  // 2. Claude CLI auth detection (config files + `claude auth status`)
+  // -------------------------------------------------------------------------
+  if (!result.claude.found) {
+    // Config-file scan (same paths as detectAuth)
+    const claudeConfigPaths = [
+      join(root, '.replit-tools', '.claude-persistent', '.claude.json'),
+      '/home/runner/workspace/.replit-tools/.claude-persistent/.claude.json',
+      join(home, '.claude', '.claude.json'),
+    ];
+    for (const p of claudeConfigPaths) {
+      try {
+        const data = JSON.parse(readFileSync(p, 'utf8'));
+        if (data?.oauthAccount || (data?.apiKey && typeof data.apiKey === 'string')) {
+          result.claude.found  = true;
+          result.claude.source = p.includes('.replit-tools') ? 'claude CLI (replit-tools)' : 'claude CLI';
+          break;
+        }
+      } catch { /* non-fatal */ }
+    }
+
+    // CLI fallback: `claude auth status`
+    if (!result.claude.found) {
+      const out = await _runWithTimeout('claude', ['auth', 'status'], 3000);
+      if (out && /logged.in|authenticated|signed.in/i.test(out)) {
+        result.claude.found  = true;
+        result.claude.source = 'claude CLI (auth status)';
+      }
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // 3. Codex CLI / OpenAI auth detection
+  // -------------------------------------------------------------------------
+  const codexConfigPaths = [
+    join(root, '.replit-tools', '.codex-persistent', 'auth.json'),
+    '/home/runner/workspace/.replit-tools/.codex-persistent/auth.json',
+    join(home, '.codex', 'auth.json'),
+  ];
+  for (const p of codexConfigPaths) {
+    try {
+      const data        = JSON.parse(readFileSync(p, 'utf8'));
+      const accessToken = data?.tokens?.access_token || data?.access_token;
+      const idToken     = data?.tokens?.id_token     || data?.id_token;
+      if (accessToken || idToken) {
+        result.openai.found  = true;
+        result.openai.source = p.includes('.replit-tools') ? 'codex CLI (replit-tools)' : 'codex CLI';
+        break;
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  // CLI fallback: `codex auth status`
+  if (!result.openai.found) {
+    const out = await _runWithTimeout('codex', ['auth', 'status'], 3000);
+    if (out && /logged.in|authenticated|signed.in/i.test(out)) {
+      result.openai.found  = true;
+      result.openai.source = 'codex CLI (auth status)';
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // 4. Existing dual-brain profile
+  // -------------------------------------------------------------------------
+  for (const p of [projectPath(root), GLOBAL_PATH]) {
+    if (existsSync(p)) {
+      result.existingProfile = true;
+      break;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Plan detection (re-use detectPlans which reads the same config files)
+  // -------------------------------------------------------------------------
+  const plans = detectPlans();
+  if (result.claude.found && plans.claude) result.claude.plan = plans.claude;
+  if (result.openai.found && plans.openai) result.openai.plan = plans.openai;
+
+  // -------------------------------------------------------------------------
+  // Smart recommendations
+  // -------------------------------------------------------------------------
+  const claudeRank = PLAN_RANK[result.claude.plan] || 0;
+  const openaiRank = PLAN_RANK[result.openai.plan] || 0;
+
+  if (result.claude.found && !result.openai.found) {
+    // Solo Claude
+    result.recommendations.headModel = 'claude-sonnet-4-6';
+    result.recommendations.budget    = result.claude.plan || '$20';
+    result.recommendations.profile   = claudeRank >= 2 ? 'quality-first' : 'balanced';
+  } else if (result.openai.found && !result.claude.found) {
+    // Solo OpenAI
+    result.recommendations.headModel = 'gpt-4o';
+    result.recommendations.budget    = result.openai.plan || '$20';
+    result.recommendations.profile   = openaiRank >= 2 ? 'quality-first' : 'balanced';
+  } else if (result.claude.found && result.openai.found) {
+    // Both available — higher-ranked provider drives HEAD model
+    if (openaiRank > claudeRank) {
+      result.recommendations.headModel = 'gpt-4o';
+    } else {
+      result.recommendations.headModel = 'claude-sonnet-4-6';
+    }
+    const topPlan = openaiRank >= claudeRank ? result.openai.plan : result.claude.plan;
+    result.recommendations.budget  = topPlan || '$20';
+    const topRank = Math.max(claudeRank, openaiRank);
+    result.recommendations.profile = topRank >= 2 ? 'quality-first' : 'balanced';
+  }
+  // else: no auth found — defaults remain (claude-sonnet-4-6 / $20 / balanced)
+
+  return result;
+}
+
 export {
   loadProfile, saveProfile, ensureProfile, runOnboarding,
   rememberPreference, forgetPreference, getActivePreferences,
@@ -760,4 +985,5 @@ export {
   detectAuth, detectEnvironment,
   saveSubscription, listSubscriptions,
   defaultProfile, autoSetup, autoRefreshToken,
+  detectExistingAuth,
 };