dual-brain 0.2.24 → 0.2.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.24",
+  "version": "0.2.26",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -47,7 +47,12 @@
     "./envelope": "./src/envelope.mjs",
     "./session-lock": "./src/session-lock.mjs",
     "./governance": "./src/governance.mjs",
-    "./context-intel": "./src/context-intel.mjs"
+    "./context-intel": "./src/context-intel.mjs",
+    "./signal": "./src/signal.mjs",
+    "./routing-advisor": "./src/routing-advisor.mjs",
+    "./subscription": "./src/subscription.mjs",
+    "./recommendations": "./src/recommendations.mjs",
+    "./setup-flow": "./src/setup-flow.mjs"
   },
   "keywords": [
     "claude-code",
@@ -134,6 +139,11 @@
     "src/session-lock.mjs",
     "src/governance.mjs",
     "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/outcome.mjs

@@ -1,6 +1,7 @@
-import { mkdirSync, appendFileSync, writeFileSync, readFileSync, existsSync } from 'fs';
+import { mkdirSync, appendFileSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
+import { execSync } from 'child_process';
 
 const STOP_WORDS = new Set([
   'the', 'a', 'an', 'is', 'are', 'was', 'were', 'to', 'from',
@@ -204,6 +205,77 @@ export async function getRelevantOutcomes(prompt, files = [], cwd, options = {})
   }
 }
 
+export async function checkFileSurvival(cwd) {
+  try {
+    const dir = join(cwd, '.dualbrain', 'outcomes');
+    if (!existsSync(dir)) return [];
+
+    // Collect up to the last 20 individual outcome JSON files
+    let files;
+    try {
+      files = readdirSync(dir)
+        .filter(f => f.startsWith('outcome_') && f.endsWith('.json'))
+        .sort()
+        .slice(-20);
+    } catch {
+      return [];
+    }
+
+    // Get current git-modified files (best-effort)
+    let modifiedFiles = new Set();
+    try {
+      const gitOut = execSync('git diff --name-only', { cwd, stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+      for (const f of gitOut.split('\n').map(l => l.trim()).filter(Boolean)) {
+        modifiedFiles.add(f);
+        modifiedFiles.add(join(cwd, f));
+      }
+    } catch {
+      // git unavailable — proceed without modified-file check
+    }
+
+    const scored = [];
+
+    for (const fname of files) {
+      const fpath = join(dir, fname);
+      let record;
+      try {
+        record = JSON.parse(readFileSync(fpath, 'utf8'));
+      } catch {
+        continue;
+      }
+
+      // Skip if already scored or no filesChanged list
+      if (record.survivalScore !== undefined) continue;
+      const changedFiles = record.result?.filesChanged;
+      if (!Array.isArray(changedFiles) || changedFiles.length === 0) continue;
+
+      let survived = 0;
+      for (const f of changedFiles) {
+        const absPath = f.startsWith('/') ? f : join(cwd, f);
+        const exists = existsSync(absPath);
+        const modified = modifiedFiles.has(f) || modifiedFiles.has(absPath);
+        if (exists && !modified) survived++;
+      }
+
+      const survivalScore = survived / changedFiles.length;
+      record.survivalScore = survivalScore;
+
+      try {
+        writeFileSync(fpath, JSON.stringify(record, null, 2), 'utf8');
+      } catch {
+        // write failed — skip
+        continue;
+      }
+
+      scored.push({ id: record.id, survivalScore });
+    }
+
+    return scored;
+  } catch {
+    return [];
+  }
+}
+
 export async function getOutcomeStats(cwd, days = 7) {
   try {
     const allFiles = last7DaysFiles(cwd).slice(0, days);

package/src/pipeline.mjs

@@ -10,7 +10,7 @@ import { detectTask } from './detect.mjs';
 import { decideRoute, getWorkStyle, WORK_STYLES } from './decide.mjs';
 import { dispatch } from './dispatch.mjs';
 import { loadProfile } from './profile.mjs';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { buildContextPack as buildContextPackIntel } from './context.mjs';
 import { compilePacket } from './context-intel.mjs';
@@ -708,6 +708,18 @@ async function preDispatchThink(prompt, files, decision, cwd, profile, opts = {}
     // profile unavailable — proceed
   }
 
+  // Auto-disable if ROI is bad (< 30% hit rate after 10+ observations)
+  {
+    const metricsPath = join(cwd, '.dualbrain', 'think-metrics.json');
+    let metrics = { hits: 0, misses: 0, totalTokens: 0 };
+    try { metrics = JSON.parse(readFileSync(metricsPath, 'utf8')); } catch {}
+    if (metrics.hits + metrics.misses >= 10 && metrics.hits / (metrics.hits + metrics.misses) < 0.3) {
+      const verbose = opts.verbose ?? false;
+      if (verbose) process.stderr.write('[dual-brain] pre-dispatch think disabled: hit rate below 30%\n');
+      return { refined: false, reason: 'think ROI too low, auto-disabled' };
+    }
+  }
+
   try {
     log('[dual-brain] pre-dispatch think: refining work spec...');
 
@@ -756,12 +768,14 @@ async function preDispatchThink(prompt, files, decision, cwd, profile, opts = {}
     if (!parsed || typeof parsed.confidence !== 'number' || parsed.confidence <= 0.7) {
       const reason = !parsed ? 'unparseable response' : `confidence ${parsed.confidence} <= 0.7`;
       log(`[dual-brain] pre-dispatch think: skipped (${reason})`);
+      _recordThinkMetrics(false, cwd);
       return { refined: false };
     }
 
     const ws = parsed.workSpec;
     if (!ws || !ws.objective) {
       log('[dual-brain] pre-dispatch think: skipped (no workSpec.objective)');
+      _recordThinkMetrics(false, cwd);
       return { refined: false };
     }
 
@@ -774,19 +788,44 @@ async function preDispatchThink(prompt, files, decision, cwd, profile, opts = {}
 
     log(`[dual-brain] think refined: "${newObjective.slice(0, 60)}..." (confidence: ${parsed.confidence})`);
 
+    _recordThinkMetrics(true, cwd);
     return {
-      refined:  true,
-      prompt:   newObjective,
-      files:    newFiles,
-      decision: newDecision,
+      refined:    true,
+      prompt:     newObjective,
+      files:      newFiles,
+      decision:   newDecision,
+      confidence: parsed.confidence,
     };
   } catch (err) {
     // Non-blocking on any failure
     log(`[dual-brain] pre-dispatch think: skipped (error: ${err.message})`);
+    _recordThinkMetrics(false, cwd);
     return { refined: false };
   }
 }
 
+/**
+ * Record a think hit or miss into think-metrics.json (non-blocking).
+ * @param {boolean} hit  — true if the think agent produced a usable refinement
+ * @param {string}  cwd
+ */
+function _recordThinkMetrics(hit, cwd) {
+  try {
+    const metricsPath = join(cwd, '.dualbrain', 'think-metrics.json');
+    let metrics = { hits: 0, misses: 0, totalTokens: 0 };
+    try { metrics = JSON.parse(readFileSync(metricsPath, 'utf8')); } catch {}
+    if (hit) {
+      metrics.hits++;
+    } else {
+      metrics.misses++;
+    }
+    metrics.totalTokens += 3000; // budget per think call
+    metrics.lastUpdated = new Date().toISOString();
+    mkdirSync(join(cwd, '.dualbrain'), { recursive: true });
+    writeFileSync(metricsPath, JSON.stringify(metrics, null, 2) + '\n');
+  } catch { /* non-blocking */ }
+}
+
 // ─── Main entry point ─────────────────────────────────────────────────────────
 
 /**
@@ -1230,6 +1269,22 @@ export async function runPipeline(trigger, prompt, options = {}) {
         run._thinkRefinedPrompt  = thinkRefinement.prompt;
         run._thinkRefinedFiles   = thinkRefinement.files;
         decision                 = thinkRefinement.decision;
+
+        // Cascade: if think agent is highly confident and task is simple, downgrade worker model
+        if (thinkRefinement.decision) {
+          const thinkConf = thinkRefinement.confidence || 0;
+          const currentModel = decision.model || 'sonnet';
+          if (thinkConf >= 0.9 && currentModel !== 'haiku') {
+            // High confidence from thinker = clear spec = cheaper model can execute
+            const prevModel = decision.model;
+            decision.model = 'haiku';
+            if (verbose || run?.verbose) process.stderr.write(`[dual-brain] cascade: think confidence ${thinkConf} → downgraded ${prevModel || 'sonnet'} to haiku\n`);
+          } else if (thinkConf >= 0.75 && currentModel === 'opus') {
+            // Moderate confidence but spec is clear enough for sonnet
+            decision.model = 'sonnet';
+            if (verbose || run?.verbose) process.stderr.write(`[dual-brain] cascade: think confidence ${thinkConf} → downgraded opus to sonnet\n`);
+          }
+        }
       }
     }
 

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/routing-advisor.mjs

@@ -0,0 +1,138 @@
+// routing-advisor.mjs — EMA + epsilon-greedy routing advisor
+// Learns which model works best for which task type from outcome signals.
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+
+const ALPHA = 0.3;
+const MIN_EPSILON = 0.1;
+const MIN_OBSERVATIONS = 5;
+const PRIOR_WEIGHT = 5;
+
+const STATIC_PRIORS = {
+  'search:haiku': 0.85,  'search:sonnet': 0.70,  'search:opus': 0.50,
+  'execute:haiku': 0.55, 'execute:sonnet': 0.80,  'execute:opus': 0.85,
+  'think:haiku': 0.30,   'think:sonnet': 0.70,    'think:opus': 0.90,
+  'review:haiku': 0.40,  'review:sonnet': 0.75,   'review:opus': 0.85,
+};
+
+const VALID_MODELS = {
+  search:  ['haiku', 'sonnet'],
+  execute: ['haiku', 'sonnet', 'opus'],
+  think:   ['sonnet', 'opus'],
+  review:  ['sonnet', 'opus'],
+};
+
+function stateFile(cwd) { return join(cwd || process.cwd(), '.dualbrain', 'routing-state.json'); }
+
+function loadState(cwd) {
+  try {
+    const p = stateFile(cwd);
+    return existsSync(p) ? JSON.parse(readFileSync(p, 'utf8')) : {};
+  } catch { return {}; }
+}
+
+function saveState(state, cwd) {
+  try {
+    const dir = join(cwd || process.cwd(), '.dualbrain');
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const p = stateFile(cwd), tmp = p + '.tmp';
+    writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+    renameSync(tmp, p);
+  } catch { /* non-throwing */ }
+}
+
+const staticPrior = (tier, model) => STATIC_PRIORS[`${tier}:${model}`] ?? 0.5;
+const cellObs = (state, key) => Object.values(state[key] ?? {}).reduce((s, m) => s + (m.observations ?? 0), 0);
+const blended = (ema, n, tier, model) =>
+  (n / (n + PRIOR_WEIGHT)) * ema + (PRIOR_WEIGHT / (n + PRIOR_WEIGHT)) * staticPrior(tier, model);
+
+// taskProfile: { intent, tier, risk, files?, complexity? }
+// Returns: { model, reason, confidence, explored }
+export function adviseModel(taskProfile, cwd) {
+  try {
+    const { tier, intent } = taskProfile ?? {};
+    const validTier = tier && VALID_MODELS[tier] ? tier : 'execute';
+    const cellKey = `${validTier}:${intent ?? 'implement'}`;
+    const models = VALID_MODELS[validTier];
+
+    const state = loadState(cwd);
+    const totalObs = cellObs(state, cellKey);
+
+    if (totalObs < MIN_OBSERVATIONS) {
+      // Heuristic: pick highest static prior
+      const best = models.reduce((a, b) => staticPrior(validTier, a) >= staticPrior(validTier, b) ? a : b);
+      return { model: best, reason: 'insufficient data, using heuristic', confidence: 0.3, explored: false };
+    }
+
+    const epsilon = Math.max(MIN_EPSILON, 0.5 * Math.pow(0.9, totalObs));
+    const explored = Math.random() < epsilon;
+
+    if (explored) {
+      const model = models[Math.floor(Math.random() * models.length)];
+      return { model, reason: 'exploration', confidence: epsilon, explored: true };
+    }
+
+    // Exploitation: pick highest blended score
+    const cell = state[cellKey] ?? {};
+    let bestModel = models[0];
+    let bestScore = -Infinity;
+    for (const m of models) {
+      const entry = cell[m];
+      const ema = entry?.ema ?? staticPrior(validTier, m);
+      const n = entry?.observations ?? 0;
+      const score = blended(ema, n, validTier, m);
+      if (score > bestScore) { bestScore = score; bestModel = m; }
+    }
+
+    return { model: bestModel, reason: 'exploitation', confidence: 1 - epsilon, explored: false };
+  } catch {
+    return { model: 'sonnet', reason: 'error fallback', confidence: 0.1, explored: false };
+  }
+}
+
+// reward: number in [0, 1]
+export function recordReward(cellKey, model, reward, cwd) {
+  try {
+    const state = loadState(cwd);
+    if (!state[cellKey]) state[cellKey] = {};
+    const entry = state[cellKey][model] ?? { ema: reward, observations: 0 };
+    entry.ema = ALPHA * reward + (1 - ALPHA) * entry.ema;
+    entry.observations = (entry.observations ?? 0) + 1;
+    entry.lastUpdated = new Date().toISOString();
+    entry.lastReward = reward;
+    state[cellKey][model] = entry;
+    saveState(state, cwd);
+  } catch {
+    // non-throwing
+  }
+}
+
+export function getRoutingStats(cwd) {
+  try {
+    const state = loadState(cwd);
+    const cells = {}, flat = [];
+    let totalObservations = 0;
+    for (const [cellKey, models] of Object.entries(state)) {
+      cells[cellKey] ??= {};
+      for (const [model, entry] of Object.entries(models)) {
+        const obs = entry.observations ?? 0;
+        cells[cellKey][model] = { ema: entry.ema, observations: obs };
+        totalObservations += obs;
+        flat.push({ cell: cellKey, model, ema: entry.ema, observations: obs });
+      }
+    }
+    flat.sort((a, b) => b.ema - a.ema);
+    return { cells, totalObservations, topPerformers: flat.slice(0, 5), worstPerformers: flat.slice(-5).reverse() };
+  } catch {
+    return { cells: {}, totalObservations: 0, topPerformers: [], worstPerformers: [] };
+  }
+}
+
+export function resetAdvisor(cwd) {
+  try {
+    saveState({}, cwd);
+  } catch {
+    // non-throwing
+  }
+}

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/signal.mjs

@@ -0,0 +1,114 @@
+// signal.mjs — Compound outcome signal scoring
+// Combines multiple weak signals into one reliable reward score.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+export const EXPECTED_DURATION_MS = { search: 15000, execute: 45000, think: 30000, review: 40000 };
+
+export function scoreDurationRatio(durationMs, tier) {
+  try {
+    const expected = EXPECTED_DURATION_MS[tier] ?? EXPECTED_DURATION_MS.execute;
+    const ratio = durationMs / expected;
+    if (ratio >= 0.5 && ratio <= 1.5) return 1.0;
+    if (ratio < 0.2) return 0.5;
+    if (ratio > 3.0) return 0.3;
+    if (ratio < 0.5) return 0.5 + ((ratio - 0.2) / (0.5 - 0.2)) * 0.5;
+    // ratio 1.5–3.0
+    return 1.0 - ((ratio - 1.5) / (3.0 - 1.5)) * 0.7;
+  } catch {
+    return null;
+  }
+}
+
+export function measureFileSurvival(outcome, cwd) {
+  try {
+    const files = Array.isArray(outcome.filesChanged)
+      ? outcome.filesChanged
+      : [];
+    if (files.length === 0) return 1.0;
+
+    let changed;
+    try {
+      changed = new Set(
+        execSync('git diff --name-only', { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] })
+          .split('\n')
+          .map(f => f.trim())
+          .filter(Boolean)
+      );
+    } catch {
+      changed = new Set();
+    }
+
+    const survived = files.filter(f => {
+      const abs = join(cwd, f);
+      return existsSync(abs) && !changed.has(f);
+    });
+    return survived.length / files.length;
+  } catch {
+    return null;
+  }
+}
+
+export function scoreOutcome(outcome, context = {}) {
+  try {
+    const tier = outcome.tier ?? 'execute';
+    const signals = [];
+
+    // Signal 1: exit success (weight 0.3)
+    let exitVal;
+    if (outcome.success === true) exitVal = 1.0;
+    else if (outcome.status === 'partial') exitVal = 0.4;
+    else exitVal = 0.0;
+    signals.push({ name: 'exitSuccess', value: exitVal, weight: 0.3 });
+
+    // Signal 2: duration ratio (weight 0.25)
+    const durationMs = outcome.durationMs ?? 0;
+    const durVal = durationMs > 0 ? scoreDurationRatio(durationMs, tier) : null;
+    signals.push({ name: 'durationRatio', value: durVal, weight: 0.25 });
+
+    // Signal 3: token efficiency (weight 0.25)
+    let effVal = null;
+    const filesChanged = outcome.filesChanged ?? 0;
+    const fileCount = typeof filesChanged === 'number' ? filesChanged : filesChanged.length;
+    if (!(fileCount === 0 && tier === 'think')) {
+      const tokensUsed =
+        outcome.tokensUsed?.output ??
+        (durationMs > 0 ? Math.round(durationMs / 100) : null);
+      if (tokensUsed !== null) {
+        const efficiency = fileCount / Math.max(1, tokensUsed / 1000);
+        if (efficiency > 2) effVal = 1.0;
+        else if (efficiency >= 0.5) effVal = 0.5 + ((efficiency - 0.5) / 1.5) * 0.5;
+        else if (efficiency < 0.1) effVal = 0.2;
+        else effVal = 0.2 + ((efficiency - 0.1) / 0.4) * 0.3;
+      }
+    }
+    signals.push({ name: 'tokenEfficiency', value: effVal, weight: 0.25 });
+
+    // Signal 4: file survival (weight 0.2) — delayed, may be null
+    const survivalVal = context.fileSurvival ?? null;
+    signals.push({ name: 'fileSurvival', value: survivalVal, weight: 0.2 });
+
+    // Compound score with weight redistribution
+    const active = signals.filter(s => s.value !== null);
+    const totalWeight = active.reduce((sum, s) => sum + s.weight, 0);
+    const reward = totalWeight > 0
+      ? active.reduce((sum, s) => sum + (s.value * s.weight / totalWeight), 0)
+      : 0;
+    const confidence = totalWeight;
+
+    return {
+      reward: Math.min(1, Math.max(0, reward)),
+      confidence: Math.min(1, confidence),
+      signals: {
+        exitSuccess: exitVal,
+        durationRatio: durVal,
+        tokenEfficiency: effVal,
+        fileSurvival: survivalVal,
+      },
+    };
+  } catch {
+    return { reward: 0, confidence: 0, signals: { exitSuccess: false, durationRatio: null, tokenEfficiency: null, fileSurvival: null } };
+  }
+}

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,
+  }));
+}