dual-brain 0.2.25 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.25",
+  "version": "0.2.26",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -49,7 +49,10 @@
     "./governance": "./src/governance.mjs",
     "./context-intel": "./src/context-intel.mjs",
     "./signal": "./src/signal.mjs",
-    "./routing-advisor": "./src/routing-advisor.mjs"
+    "./routing-advisor": "./src/routing-advisor.mjs",
+    "./subscription": "./src/subscription.mjs",
+    "./recommendations": "./src/recommendations.mjs",
+    "./setup-flow": "./src/setup-flow.mjs"
   },
   "keywords": [
     "claude-code",
@@ -138,6 +141,9 @@
     "src/context-intel.mjs",
     "src/signal.mjs",
     "src/routing-advisor.mjs",
+    "src/subscription.mjs",
+    "src/recommendations.mjs",
+    "src/setup-flow.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/recommendations.mjs

@@ -0,0 +1,291 @@
+// recommendations.mjs — Proactive settings recommendations from HEAD
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+function readJSON(path) {
+  try {
+    return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+  } catch { return null; }
+}
+
+function dbPath(cwd, ...parts) {
+  return join(cwd || process.cwd(), '.dualbrain', ...parts);
+}
+
+// ─── Signal loaders ───────────────────────────────────────────────────────────
+
+function loadRoutingState(cwd) { return readJSON(dbPath(cwd, 'routing-state.json')) || {}; }
+function loadThinkMetrics(cwd) { return readJSON(dbPath(cwd, 'think-metrics.json')) || {}; }
+function loadGovernance(cwd)   { return readJSON(dbPath(cwd, 'governance-state.json')) || {}; }
+function loadSubscription(cwd) { return readJSON(dbPath(cwd, 'subscription.json')) || {}; }
+
+function loadOutcomes(cwd) {
+  try {
+    const dir = dbPath(cwd, 'outcomes');
+    if (!existsSync(dir)) return [];
+    return readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => readJSON(join(dir, f)))
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+// ─── Recommendation rules ─────────────────────────────────────────────────────
+
+function thinkROI(metrics) {
+  const { hitRate, totalHits, totalMisses, avgTokensSaved } = metrics;
+  if (hitRate == null) return null;
+  const observations = (totalHits || 0) + (totalMisses || 0);
+  if (observations < 5) return null;
+
+  if (hitRate < 0.4) {
+    return {
+      id: 'think-roi-low',
+      priority: 'medium',
+      category: 'efficiency',
+      title: 'Think agent underperforming',
+      description: `${Math.round(hitRate * 100)}% hit rate — think preflight isn't saving tokens.`,
+      action: 'Consider disabling think triggers or narrowing trigger conditions.',
+      impact: 'Reduce latency and token overhead on low-complexity tasks.',
+    };
+  }
+  if (hitRate > 0.7) {
+    const savings = avgTokensSaved ? `~${Math.round(avgTokensSaved / 1000)}K tokens` : 'tokens';
+    return {
+      id: 'think-roi-high',
+      priority: 'medium',
+      category: 'efficiency',
+      title: 'Think agent performing well',
+      description: `${Math.round(hitRate * 100)}% hit rate, saving ${savings} per refined task.`,
+      action: 'No action needed, keep enabled.',
+      impact: 'Sustained token efficiency on complex dispatches.',
+    };
+  }
+  return null;
+}
+
+function modelMismatch(routingState) {
+  const recs = [];
+  for (const [taskType, models] of Object.entries(routingState)) {
+    for (const [model, stats] of Object.entries(models)) {
+      const { ema, observations } = stats || {};
+      if (observations >= 10 && ema < 0.4) {
+        recs.push({
+          id: `model-mismatch-low-${taskType}-${model}`,
+          priority: 'high',
+          category: 'routing',
+          title: 'Model mismatch detected',
+          description: `${model} scores ${ema.toFixed(2)} on ${taskType} tasks.`,
+          action: `Route ${taskType} tasks away from ${model}.`,
+          impact: 'Better task outcomes by avoiding poor model-task fit.',
+        });
+      } else if (observations >= 10 && ema > 0.8 && (model === 'haiku' || model.includes('haiku'))) {
+        recs.push({
+          id: `model-mismatch-promote-${taskType}-${model}`,
+          priority: 'high',
+          category: 'routing',
+          title: 'Cheap model excelling',
+          description: `${model} scores ${ema.toFixed(2)} on ${taskType} tasks.`,
+          action: `Promote ${model} as default for ${taskType} tier — quality without the cost.`,
+          impact: 'Same output quality at lower token cost.',
+        });
+      }
+    }
+  }
+  return recs;
+}
+
+function budgetTrajectory(governance) {
+  const { budgetUsedPct, sessionProgressPct, workStyle } = governance;
+  if (budgetUsedPct == null) return null;
+
+  if (budgetUsedPct > 60 && sessionProgressPct != null && sessionProgressPct < 50) {
+    return {
+      id: 'budget-critical',
+      priority: 'high',
+      category: 'budget',
+      title: 'Budget burning fast',
+      description: `${Math.round(budgetUsedPct)}% budget used, ~${Math.round(sessionProgressPct)}% through estimated work.`,
+      action: 'Switch to cost-saver mode: `dual-brain config set workStyle cost-saver`.',
+      impact: 'Avoid hitting budget ceiling before work completes.',
+    };
+  }
+  if (budgetUsedPct < 20 && workStyle === 'cost-saver') {
+    return {
+      id: 'budget-underutilized',
+      priority: 'low',
+      category: 'budget',
+      title: 'Budget well under control',
+      description: `Only ${Math.round(budgetUsedPct)}% budget used in cost-saver mode.`,
+      action: 'You could afford quality-first mode for this session.',
+      impact: 'Better output quality while staying within budget.',
+    };
+  }
+  return null;
+}
+
+function failurePattern(outcomes) {
+  if (!outcomes.length) return null;
+  const recent = outcomes.slice(-20);
+  const failures = recent.filter(o => o.success === false || (o.reward != null && o.reward < 0.3));
+  const failRate = failures.length / recent.length;
+
+  if (failRate > 0.3) {
+    const modelCounts = {};
+    failures.forEach(o => { if (o.model) modelCounts[o.model] = (modelCounts[o.model] || 0) + 1; });
+    const worstModel = Object.entries(modelCounts).sort((a, b) => b[1] - a[1])[0];
+    const modelNote = worstModel && worstModel[1] >= 3
+      ? ` Failures cluster on ${worstModel[0]}.`
+      : '';
+    return {
+      id: 'failure-pattern',
+      priority: 'high',
+      category: 'quality',
+      title: 'High failure rate detected',
+      description: `${Math.round(failRate * 100)}% of recent tasks failed.${modelNote}`,
+      action: worstModel && worstModel[1] >= 3
+        ? `Route away from ${worstModel[0]} — or check task ambiguity.`
+        : 'Review task clarity and model-task fit.',
+      impact: 'Fewer retries, less wasted compute.',
+    };
+  }
+  return null;
+}
+
+function subscriptionUtilization(subscription, routingState) {
+  const { tier, maxMultiplier } = subscription;
+  if (!tier) return null;
+
+  const opusUses = Object.values(routingState)
+    .flatMap(m => Object.entries(m))
+    .filter(([model]) => model === 'opus' || model.includes('opus'))
+    .reduce((s, [, stats]) => s + (stats.observations || 0), 0);
+
+  const totalUses = Object.values(routingState)
+    .flatMap(m => Object.values(m))
+    .reduce((s, stats) => s + (stats.observations || 0), 0);
+
+  if (!totalUses) return null;
+  const opusPct = opusUses / totalUses;
+
+  if ((tier === 'max' || (maxMultiplier && maxMultiplier >= 20)) && opusPct < 0.15) {
+    return {
+      id: 'subscription-underutilized',
+      priority: 'medium',
+      category: 'profile',
+      title: 'Subscription underutilized',
+      description: `Max ${maxMultiplier || ''}x plan but opus used only ${Math.round(opusPct * 100)}% of dispatches.`,
+      action: 'Consider quality-first mode for better output.',
+      impact: 'Get more value from your subscription tier.',
+    };
+  }
+  if ((tier === 'free' || tier === 'pro') && opusPct > 0.4) {
+    return {
+      id: 'subscription-aggressive',
+      priority: 'medium',
+      category: 'profile',
+      title: 'Routing aggressively for plan',
+      description: `${Math.round(opusPct * 100)}% opus usage on a ${tier} plan.`,
+      action: 'Switch to balanced or cost-saver to stay within limits.',
+      impact: 'Avoid rate limits and unexpected cost overruns.',
+    };
+  }
+  return null;
+}
+
+function cascadeEffectiveness(metrics, outcomes) {
+  const { cascadeHits } = metrics;
+  if (!cascadeHits || cascadeHits < 3) return null;
+
+  const cascaded = outcomes.filter(o => o.cascaded === true);
+  if (cascaded.length < 3) return null;
+
+  const avgReward = cascaded.reduce((s, o) => s + (o.reward || 0), 0) / cascaded.length;
+  if (avgReward > 0.7) {
+    return {
+      id: 'cascade-effective',
+      priority: 'low',
+      category: 'efficiency',
+      title: 'Cascade routing working well',
+      description: `${cascadeHits} cascade hits, ${avgReward.toFixed(2)} avg reward on cascaded tasks.`,
+      action: 'Keep cascade enabled — it\'s delivering quality results.',
+      impact: 'Continued token efficiency on eligible tasks.',
+    };
+  }
+  return {
+    id: 'cascade-poor',
+    priority: 'low',
+    category: 'efficiency',
+    title: 'Cascade delivering poor results',
+    description: `${cascadeHits} cascade hits but only ${avgReward.toFixed(2)} avg reward.`,
+    action: 'Consider disabling cascade: `dual-brain config set cascade false`.',
+    impact: 'Better outcomes by routing cascade tasks to full models.',
+  };
+}
+
+// ─── Export 1: generateRecommendations ────────────────────────────────────────
+
+export function generateRecommendations(cwd) {
+  try {
+    const routingState  = loadRoutingState(cwd);
+    const thinkMetrics  = loadThinkMetrics(cwd);
+    const governance    = loadGovernance(cwd);
+    const subscription  = loadSubscription(cwd);
+    const outcomes      = loadOutcomes(cwd);
+
+    const recs = [
+      ...modelMismatch(routingState),
+      failurePattern(outcomes),
+      budgetTrajectory(governance),
+      thinkROI(thinkMetrics),
+      subscriptionUtilization(subscription, routingState),
+      cascadeEffectiveness(thinkMetrics, outcomes),
+    ].filter(Boolean);
+
+    const order = { high: 0, medium: 1, low: 2 };
+    return recs.sort((a, b) => (order[a.priority] ?? 9) - (order[b.priority] ?? 9));
+  } catch { return []; }
+}
+
+// ─── Export 2: formatRecommendations ─────────────────────────────────────────
+
+const ICONS = { high: '⚡', medium: '💡', low: '📊' };
+
+export function formatRecommendations(recs) {
+  const top = recs.slice(0, 4);
+  if (!top.length) {
+    return '╭─ Recommendations ─────────────────────────────────────────────╮\n' +
+           '│  No recommendations — configuration looks healthy.            │\n' +
+           '╰───────────────────────────────────────────────────────────────╯';
+  }
+
+  const WIDTH = 63;
+  // Truncate + pad to fit inside box: WIDTH - 4 accounts for '│ ' and ' │'
+  const INNER = WIDTH - 4;
+  const clip = (str) => str.length > INNER ? str.slice(0, INNER - 1) + '…' : str;
+  const pad = (str) => clip(str).padEnd(INNER);
+  const line = (content) => `│ ${pad(content)} │`;
+
+  const lines = [
+    '╭─ Recommendations ' + '─'.repeat(WIDTH - 19) + '╮',
+    line(''),
+  ];
+
+  for (const rec of top) {
+    const icon = ICONS[rec.priority] || '•';
+    lines.push(line(`${icon} ${rec.priority.toUpperCase()}: ${rec.title}`));
+    lines.push(line(`   ${rec.description}`));
+    lines.push(line(`   → ${rec.action}`));
+    lines.push(line(''));
+  }
+
+  lines.push('╰' + '─'.repeat(WIDTH - 2) + '╯');
+  return lines.join('\n');
+}
+
+// ─── Export 3: getTopRecommendation ──────────────────────────────────────────
+
+export function getTopRecommendation(cwd) {
+  const recs = generateRecommendations(cwd);
+  return recs.length ? recs[0] : null;
+}

package/src/setup-flow.mjs

@@ -0,0 +1,215 @@
+// setup-flow.mjs — Interactive first-run setup for dual-brain
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { execSync } from 'node:child_process';
+
+// ── ANSI helpers ──────────────────────────────────────────────────────────────
+const c = {
+  bold:   s => `\x1b[1m${s}\x1b[0m`,
+  dim:    s => `\x1b[2m${s}\x1b[0m`,
+  green:  s => `\x1b[32m${s}\x1b[0m`,
+  yellow: s => `\x1b[33m${s}\x1b[0m`,
+  cyan:   s => `\x1b[36m${s}\x1b[0m`,
+  red:    s => `\x1b[31m${s}\x1b[0m`,
+};
+
+// ── Detection ─────────────────────────────────────────────────────────────────
+export function detectEnvironment(cwd) {
+  const tryCmd = cmd => { try { execSync(cmd, { stdio: 'pipe' }); return true; } catch { return false; } };
+
+  let language = 'unknown';
+  if (existsSync(join(cwd, 'package.json')))      language = 'node';
+  else if (existsSync(join(cwd, 'pyproject.toml')) ||
+           existsSync(join(cwd, 'setup.py')))      language = 'python';
+  else if (existsSync(join(cwd, 'go.mod')))        language = 'go';
+  else if (existsSync(join(cwd, 'Cargo.toml')))    language = 'rust';
+  else if (existsSync(join(cwd, 'pom.xml')))       language = 'java';
+
+  let gitBranch = null;
+  try { gitBranch = execSync('git -C "' + cwd + '" branch --show-current', { stdio: 'pipe' }).toString().trim(); } catch {}
+
+  return {
+    claude:         tryCmd('claude --version'),
+    codex:          tryCmd('codex --version'),
+    git:            !!gitBranch,
+    gitBranch:      gitBranch || null,
+    language,
+    existingConfig: existsSync(join(cwd, '.dualbrain', 'config.json')),
+  };
+}
+
+// ── Welcome banner ────────────────────────────────────────────────────────────
+export function renderWelcome(detected) {
+  const row = (ok, label) => c.cyan('│') + `   ${ok ? c.green('✓') : c.dim('✗')} ${ok ? label : c.dim(label)}`.padEnd(49) + c.cyan('│');
+  const bar = s => c.cyan('│') + s.padEnd(49) + c.cyan('│');
+  return [
+    c.cyan('╭' + '─'.repeat(49) + '╮'),
+    bar(''),
+    bar(`   ${c.bold('dual-brain')} — intelligent model orchestration`),
+    bar(''),
+    bar('   Detected:'),
+    row(detected.claude, 'Claude CLI available'),
+    row(detected.codex,  'Codex CLI available'),
+    row(detected.git,    `Git repository (${detected.gitBranch || 'no branch'} branch)`),
+    row(detected.language !== 'unknown', `${detected.language} project`),
+    bar(''),
+    c.cyan('╰' + '─'.repeat(49) + '╯'),
+  ].join('\n');
+}
+
+const SUB_LABELS = {
+  'claude-pro': 'Claude Pro', 'claude-max-5x': 'Claude Max 5x',
+  'claude-max-20x': 'Claude Max 20x', 'chatgpt-plus': 'ChatGPT Plus',
+  'chatgpt-pro': 'ChatGPT Pro', 'dual-pro': 'Both Pro tiers', 'dual-max': 'Max + Pro tiers',
+};
+
+// ── Confirmation display ──────────────────────────────────────────────────────
+export function renderConfirmation(config) {
+  const row = (k, v) => `  ${c.dim(k.padEnd(16))} ${c.cyan(v)}`;
+  return [
+    '', c.bold('  Configuration:'), '',
+    row('Subscription:', SUB_LABELS[config.subscription] || config.subscription),
+    row('Work style:', config.workStyle),
+    row('Primary model:', config.models.execute),
+    row('Think agent:', config.routing.thinkEnabled ? 'enabled' : 'disabled'),
+    row('Learning:', config.routing.learningEnabled ? 'on' : 'off'),
+    '',
+  ].join('\n');
+}
+
+// ── Config builder ────────────────────────────────────────────────────────────
+export function buildConfig(answers, detected) {
+  const { subscription = 'claude-pro', workStyle = 'balanced', advanced = {}, setupMode = 'quick' } = answers;
+  const dual = subscription.startsWith('dual-');
+  const isMax = subscription.includes('max') || subscription === 'chatgpt-pro';
+  const topModel = isMax ? 'opus' : 'sonnet';
+  const exploreRate = { aggressive: 0.3, conservative: 0.1, auto: 0.25 }[workStyle] ?? 0.2;
+  return {
+    version: 1, subscription, workStyle,
+    providers: { claude: subscription.startsWith('claude-') || dual, openai: subscription.startsWith('chatgpt-') || dual },
+    routing: {
+      thinkEnabled:    advanced.thinkEnabled    ?? true,
+      cascadeEnabled:  advanced.cascadeEnabled  ?? true,
+      learningEnabled: advanced.learningEnabled ?? true,
+      explorationRate: advanced.explorationRate ?? exploreRate,
+    },
+    models: advanced.models || { search: 'haiku', execute: 'sonnet', think: topModel, review: topModel },
+    budget: { sessionLimitTokens: advanced.sessionLimitTokens ?? null, warnAtPercent: advanced.warnAtPercent ?? 80 },
+    configuredAt: new Date().toISOString(),
+    setupMode,
+    detectedEnv: { claude: detected.claude, codex: detected.codex, language: detected.language },
+  };
+}
+
+// ── Save config ───────────────────────────────────────────────────────────────
+export function saveConfig(config, cwd) {
+  const dir = join(cwd, '.dualbrain');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2), 'utf8');
+  const orchPath = join(cwd, '.claude', 'orchestrator.json');
+  if (existsSync(orchPath)) {
+    try {
+      const orch = JSON.parse(readFileSync(orchPath, 'utf8'));
+      if (!orch.providers) orch.providers = {};
+      orch.providers.claude = { ...(orch.providers.claude || {}), enabled: config.providers.claude, subscription: config.subscription };
+      orch.providers.openai = { ...(orch.providers.openai || {}), enabled: config.providers.openai };
+      if (config.routing) orch.routing = { ...(orch.routing || {}), ...config.routing };
+      writeFileSync(orchPath, JSON.stringify(orch, null, 2), 'utf8');
+    } catch { /* non-fatal */ }
+  }
+}
+
+// ── Readline prompt helper ────────────────────────────────────────────────────
+async function ask(rl, question, options) {
+  const lines = options.map((o, i) => `  ${c.cyan(String(i + 1) + ')')} ${o.label}${o.description ? c.dim(' — ' + o.description) : ''}`);
+  const prompt = `\n${c.bold(question)}\n${lines.join('\n')}\n${c.dim('> ')}`;
+  return new Promise(resolve => {
+    rl.question(prompt, answer => {
+      const trimmed = answer.trim();
+      const idx = parseInt(trimmed, 10) - 1;
+      if (idx >= 0 && idx < options.length) resolve(options[idx].value);
+      else resolve(options[0].value);
+    });
+  });
+}
+
+async function askYN(rl, question, defaultYes = true) {
+  return new Promise(resolve => {
+    rl.question(`\n${c.bold(question)} ${c.dim(defaultYes ? '(Y/n)' : '(y/N)')} `, answer => {
+      const t = answer.trim().toLowerCase();
+      if (!t) resolve(defaultYes);
+      else resolve(t === 'y' || t === 'yes');
+    });
+  });
+}
+
+// ── Main entry point ──────────────────────────────────────────────────────────
+export async function runSetup(cwd, options = {}) {
+  const detected = detectEnvironment(cwd);
+
+  // Non-interactive fast path
+  if (options.nonInteractive) {
+    const config = buildConfig({
+      subscription: options.subscription || 'claude-pro',
+      workStyle:    options.workStyle    || 'balanced',
+      setupMode:    'non-interactive',
+    }, detected);
+    saveConfig(config, cwd);
+    return config;
+  }
+
+  // Already configured?
+  if (detected.existingConfig && !options.reconfigure) {
+    console.log('\n' + c.yellow('dual-brain is already configured.') + ' Pass --reconfigure to change settings.\n');
+    return JSON.parse(readFileSync(join(cwd, '.dualbrain', 'config.json'), 'utf8'));
+  }
+
+  console.log('\n' + renderWelcome(detected) + '\n');
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const close = () => rl.close();
+
+  try {
+    const mode = await ask(rl, 'Setup mode:', [
+      { label: 'Quick setup', value: 'quick',    description: '3 questions, ~20 seconds' },
+      { label: 'Advanced',    value: 'advanced', description: 'full control over routing, budgets, models' },
+    ]);
+    const subscription = await ask(rl, 'Your AI subscription:', [
+      { label: 'Claude Pro ($20/mo)',        value: 'claude-pro' },
+      { label: 'Claude Max 5x ($100/mo)',    value: 'claude-max-5x' },
+      { label: 'Claude Max 20x ($200/mo)',   value: 'claude-max-20x' },
+      { label: 'ChatGPT Plus ($20/mo)',      value: 'chatgpt-plus' },
+      { label: 'ChatGPT Pro ($200/mo)',      value: 'chatgpt-pro' },
+      { label: 'Both providers (Pro tiers)', value: 'dual-pro' },
+      { label: 'Both providers (Max tiers)', value: 'dual-max' },
+    ]);
+    const workStyle = await ask(rl, 'How should dual-brain route your work?', [
+      { label: 'Balanced',     value: 'balanced',     description: 'smart defaults, asks before expensive ops' },
+      { label: 'Conservative', value: 'conservative', description: 'minimize tokens, prefer cheaper models' },
+      { label: 'Aggressive',   value: 'aggressive',   description: 'best model available, maximize quality' },
+      { label: 'Full auto',    value: 'auto',         description: 'never ask, optimize silently' },
+    ]);
+    let advanced = {};
+    if (mode === 'advanced') {
+      const thinkEnabled    = await askYN(rl, 'Enable think agent?', true);
+      const cascadeEnabled  = await askYN(rl, 'Enable cascade routing?', true);
+      const learningEnabled = await askYN(rl, 'Enable learning (improves routing over time)?', true);
+      const explorationRate = await ask(rl, 'Routing exploration rate:', [
+        { label: 'Low (0.1)',    value: 0.1, description: 'rarely tries new routes' },
+        { label: 'Medium (0.2)', value: 0.2, description: 'balanced' },
+        { label: 'High (0.3)',   value: 0.3, description: 'frequently explores alternatives' },
+      ]);
+      advanced = { thinkEnabled, cascadeEnabled, learningEnabled, explorationRate };
+    }
+    const config = buildConfig({ subscription, workStyle, advanced, setupMode: mode }, detected);
+    console.log(renderConfirmation(config));
+    if (!await askYN(rl, 'Save and start?', true)) {
+      console.log('\n' + c.yellow('Setup cancelled.') + '\n');
+      close(); return null;
+    }
+    saveConfig(config, cwd);
+    console.log('\n' + c.green('✓') + ' ' + c.bold('dual-brain configured.') + ' Config saved to ' + c.cyan('.dualbrain/config.json') + '\n');
+    close(); return config;
+  } catch (err) { close(); throw err; }
+}

package/src/subscription.mjs

@@ -0,0 +1,212 @@
+// subscription.mjs — Subscription-aware routing defaults
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SUBSCRIPTIONS = {
+  // Claude subscriptions
+  'claude-pro': {
+    label: 'Claude Pro ($20/mo)',
+    provider: 'claude',
+    tokenBudget: 'moderate', // 5-hr rolling window, weekly cap
+    recommendedProfile: 'balanced',
+    modelWeights: { haiku: 0.4, sonnet: 0.5, opus: 0.1 },
+    notes: 'One extended Opus session can use 20% of your allocation. Prefer sonnet for routine work.',
+  },
+  'claude-max-5x': {
+    label: 'Claude Max 5x ($100/mo)',
+    provider: 'claude',
+    tokenBudget: 'generous',
+    recommendedProfile: 'quality-first',
+    modelWeights: { haiku: 0.2, sonnet: 0.5, opus: 0.3 },
+    notes: '5x Pro capacity. Opus is available for complex/creative work without worry.',
+  },
+  'claude-max-20x': {
+    label: 'Claude Max 20x ($200/mo)',
+    provider: 'claude',
+    tokenBudget: 'unlimited',
+    recommendedProfile: 'quality-first',
+    modelWeights: { haiku: 0.1, sonnet: 0.4, opus: 0.5 },
+    notes: 'Effectively unlimited. Use the best model for every task.',
+  },
+  'claude-team': {
+    label: 'Claude Team ($30/seat/mo)',
+    provider: 'claude',
+    tokenBudget: 'moderate',
+    recommendedProfile: 'balanced',
+    modelWeights: { haiku: 0.3, sonnet: 0.5, opus: 0.2 },
+    notes: 'Team tier with admin controls. Collaboration triggers recommended.',
+  },
+  // ChatGPT subscriptions
+  'chatgpt-plus': {
+    label: 'ChatGPT Plus ($20/mo)',
+    provider: 'openai',
+    tokenBudget: 'limited', // 50 o3/day on Plus
+    recommendedProfile: 'cost-saver',
+    modelWeights: { 'o4-mini': 0.6, 'gpt-4.1': 0.3, 'o3': 0.1 },
+    notes: '50 o3 messages/day limit. Heavy on o4-mini for routine, save o3 for critical decisions.',
+  },
+  'chatgpt-pro': {
+    label: 'ChatGPT Pro ($200/mo)',
+    provider: 'openai',
+    tokenBudget: 'generous',
+    recommendedProfile: 'quality-first',
+    modelWeights: { 'o4-mini': 0.3, 'gpt-4.1': 0.4, 'o3': 0.3 },
+    notes: 'Unlimited access to all models. Use o3 freely for complex reasoning.',
+  },
+  // Dual subscription (both providers)
+  'dual-pro': {
+    label: 'Both Pro tiers',
+    provider: 'both',
+    tokenBudget: 'moderate',
+    recommendedProfile: 'balanced',
+    modelWeights: { haiku: 0.2, sonnet: 0.3, 'gpt-4.1': 0.3, 'o4-mini': 0.2 },
+    notes: 'Split load across providers. Route by model strength: Claude for code, GPT for reasoning.',
+  },
+  'dual-max': {
+    label: 'Max + Pro (or both Max)',
+    provider: 'both',
+    tokenBudget: 'unlimited',
+    recommendedProfile: 'quality-first',
+    modelWeights: { sonnet: 0.3, opus: 0.2, 'gpt-4.1': 0.2, 'o3': 0.3 },
+    notes: 'Full power from both providers. Route by task fit, not by cost.',
+  },
+};
+
+const DEFAULT_WEIGHTS = {
+  modelWeights: { haiku: 0.3, sonnet: 0.5, opus: 0.2 },
+  profile: 'balanced',
+  notes: 'No subscription configured. Using balanced defaults.',
+};
+
+function subFile(cwd) {
+  return join(cwd || process.cwd(), '.dualbrain', 'subscription.json');
+}
+
+/** Returns the subscription config object or null. */
+export function getSubscription(subType) {
+  return SUBSCRIPTIONS[subType] ?? null;
+}
+
+/** Returns { modelWeights, profile, notes } for the subscription. Falls back to balanced defaults. */
+export function getRecommendedWeights(subType) {
+  const sub = SUBSCRIPTIONS[subType];
+  if (!sub) return DEFAULT_WEIGHTS;
+  return {
+    modelWeights: sub.modelWeights,
+    profile: sub.recommendedProfile,
+    notes: sub.notes,
+  };
+}
+
+/** Writes { subscription, configuredAt } to .dualbrain/subscription.json. */
+export function saveUserSubscription(subType, cwd) {
+  const dir = join(cwd || process.cwd(), '.dualbrain');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    subFile(cwd),
+    JSON.stringify({ subscription: subType, configuredAt: new Date().toISOString() }, null, 2),
+    'utf8'
+  );
+}
+
+/** Reads the saved subscription. Returns subType string or null. */
+export function loadUserSubscription(cwd) {
+  try {
+    const p = subFile(cwd);
+    if (!existsSync(p)) return null;
+    const data = JSON.parse(readFileSync(p, 'utf8'));
+    return data.subscription ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generates a text recommendation based on subscription + current routing stats.
+ * routingStats: return value of getRoutingStats() from routing-advisor.mjs
+ */
+export function generateRecommendation(subType, routingStats) {
+  const sub = SUBSCRIPTIONS[subType];
+  if (!sub) return 'No subscription configured. Run `dual-brain subscription set <type>` to enable smart routing defaults.';
+
+  // Tally actual model usage from routing stats cells
+  const actualUsage = {};
+  let totalObs = 0;
+  for (const models of Object.values(routingStats?.cells ?? {})) {
+    for (const [model, entry] of Object.entries(models)) {
+      actualUsage[model] = (actualUsage[model] ?? 0) + (entry.observations ?? 0);
+      totalObs += entry.observations ?? 0;
+    }
+  }
+
+  if (totalObs === 0) {
+    return `You're on ${sub.label}. No routing history yet — recommended profile is ${sub.recommendedProfile}. ${sub.notes}`;
+  }
+
+  // Compute actual share per model
+  const actualShare = {};
+  for (const [model, count] of Object.entries(actualUsage)) {
+    actualShare[model] = count / totalObs;
+  }
+
+  const rec = sub.modelWeights;
+  const budget = sub.tokenBudget;
+  const lines = [];
+
+  // Check expensive model utilization vs. recommended
+  const expensiveModels = ['opus', 'o3'];
+  for (const model of expensiveModels) {
+    const recW = rec[model] ?? 0;
+    const actW = actualShare[model] ?? 0;
+
+    if (recW > 0 && budget === 'unlimited' && actW < recW * 0.5) {
+      lines.push(
+        `You're on ${sub.label} but only using ${model} ${Math.round(actW * 100)}% of the time` +
+        ` (recommended: ${Math.round(recW * 100)}%). You're paying for capacity you're not using.` +
+        ` Consider switching to ${sub.recommendedProfile} mode.`
+      );
+    } else if (recW < 0.2 && budget === 'limited' && actW > recW * 2 && actW > 0.1) {
+      lines.push(
+        `Your ${sub.label} subscription is token-limited. ${model} usage at ${Math.round(actW * 100)}%` +
+        ` may exhaust daily limits — recommended cap is ~${Math.round(recW * 100)}%.`
+      );
+    }
+  }
+
+  // Cheap model suggestions on budget-constrained plans
+  const cheapModels = ['haiku', 'o4-mini'];
+  if (budget === 'moderate' || budget === 'limited') {
+    for (const model of cheapModels) {
+      const recW = rec[model] ?? 0;
+      const actW = actualShare[model] ?? 0;
+      if (recW > 0 && actW < recW * 0.5) {
+        lines.push(
+          `Your ${sub.label} subscription has a ${budget} budget. Increasing ${model} usage` +
+          ` (currently ${Math.round(actW * 100)}%, recommended ${Math.round(recW * 100)}%)` +
+          ` for search and routine tasks would preserve your allocation.`
+        );
+        break; // one cheap-model tip is enough
+      }
+    }
+  }
+
+  // Dominant model confirmation — find the most-used model
+  const topModel = Object.entries(actualShare).sort((a, b) => b[1] - a[1])[0];
+  if (lines.length === 0 && topModel) {
+    lines.push(
+      `Your ${sub.label} subscription is well-matched. ${Math.round(topModel[1] * 100)}% of dispatches` +
+      ` use ${topModel[0]} — a good fit for your ${budget} budget. ${sub.notes}`
+    );
+  }
+
+  return lines.slice(0, 3).join(' ');
+}
+
+/** Returns array of { key, label, provider } for display in UX. */
+export function listSubscriptions() {
+  return Object.entries(SUBSCRIPTIONS).map(([key, sub]) => ({
+    key,
+    label: sub.label,
+    provider: sub.provider,
+  }));
+}