dual-brain 0.2.25 → 0.2.27

package/bin/dual-brain.mjs

@@ -1094,6 +1094,18 @@ async function cmdStatus(args = []) {
       }
     }
   } catch { /* network unavailable — skip */ }
+
+  // Show top recommendation if available
+  try {
+    const { getTopRecommendation } = await import('../src/recommendations.mjs');
+    const rec = getTopRecommendation(process.cwd());
+    if (rec) {
+      console.log('');
+      console.log(`  \x1b[33m💡 ${rec.title}\x1b[0m`);
+      console.log(`     ${rec.description}`);
+      if (rec.action) console.log(`     → ${rec.action}`);
+    }
+  } catch { /* non-blocking */ }
 }
 
 // ─── cmdHot / cmdCool ─────────────────────────────────────────────────────────
@@ -6532,6 +6544,18 @@ async function main() {
   }
 
   if (cmd === 'init') {
+    // init --reconfigure: run setup-flow reconfiguration
+    if (args.includes('--reconfigure')) {
+      try {
+        const { runSetup } = await import('../src/setup-flow.mjs');
+        await runSetup(process.cwd(), { reconfigure: true });
+      } catch (e) {
+        console.error('setup-flow.mjs not available — skipping reconfigure');
+        if (process.env.DEBUG) console.error(e.message);
+      }
+      return;
+    }
+
     // init --reset: clear credentials.json and re-run wizard
     if (args.includes('--reset')) {
       const cwd = process.cwd();
@@ -6593,6 +6617,23 @@ async function main() {
     return;
   }
 
+  if (cmd === 'setup') {
+    const { runSetup } = await import('../src/setup-flow.mjs');
+    await runSetup(process.cwd(), { reconfigure: args.includes('--reconfigure') });
+    return;
+  }
+
+  if (cmd === 'advice' || cmd === 'recommend') {
+    const { generateRecommendations, formatRecommendations } = await import('../src/recommendations.mjs');
+    const recs = generateRecommendations(process.cwd());
+    if (recs.length === 0) {
+      console.log('  No recommendations yet. Need 20+ dispatches to generate advice.');
+    } else {
+      console.log(formatRecommendations(recs));
+    }
+    return;
+  }
+
   // One-shot commands — run and exit
   if (cmd === 'install') {
     if (args.includes('--global')) { await installGlobal(); return; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -49,7 +49,11 @@
     "./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",
+    "./self-correct": "./src/self-correct.mjs"
   },
   "keywords": [
     "claude-code",
@@ -138,6 +142,10 @@
     "src/context-intel.mjs",
     "src/signal.mjs",
     "src/routing-advisor.mjs",
+    "src/subscription.mjs",
+    "src/recommendations.mjs",
+    "src/setup-flow.mjs",
+    "src/self-correct.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/decide.mjs

@@ -49,6 +49,28 @@ function _loadModelRegistry() {
 // Kick off the load immediately so it is ready before the first routing call.
 _loadModelRegistry();
 
+// ─── Routing Advisor (optional, lazy-loaded) ──────────────────────────────────
+
+/**
+ * Cached reference to routing-advisor.mjs exports. Populated on first import.
+ * Remains null if unavailable — decideRoute skips advisor consultation in that case.
+ */
+let routingAdvisor = null;
+let _advisorLoadAttempted = false;
+
+function _loadRoutingAdvisor() {
+  if (_advisorLoadAttempted) return;
+  _advisorLoadAttempted = true;
+  import('./routing-advisor.mjs').then(mod => {
+    routingAdvisor = mod;
+  }).catch(() => {
+    // routing-advisor.mjs unavailable — skip learned routing
+  });
+}
+
+// Kick off the load immediately so it is ready before the first routing call.
+_loadRoutingAdvisor();
+
 // ─── Work Styles ─────────────────────────────────────────────────────────────
 
 /**
@@ -890,6 +912,28 @@ export function decideRoute({ profile = {}, detection = {}, cwd, thinkResult, se
   // If the pipeline changed the model (downgrade/bias/floor), resolve the new short name to a full ID.
   model = toFullModelId(model, provider, tier);
 
+  // ── Routing advisor: consult learned EMA model for this task type ─────────
+  // Non-blocking: only overrides when advisor has enough observations (confidence > 0.3).
+  // Uses short model names; advisor only covers Claude models (haiku/sonnet/opus).
+  let _advisorOverride = null;
+  if (routingAdvisor && provider === 'claude') {
+    try {
+      const advice = routingAdvisor.adviseModel(
+        { intent: detection.intent, tier, risk: detection.risk },
+        cwd
+      );
+      if (advice.confidence > 0.3 && advice.model) {
+        const advisorShort = advice.model; // advisor returns short names
+        const previousModel = toShortName(model, 'claude');
+        if (advisorShort !== previousModel && available.claude.includes(advisorShort)) {
+          const overrideFullId = toFullModelId(advisorShort, 'claude', tier);
+          _advisorOverride = { from: model, to: overrideFullId, reason: advice.reason, explored: advice.explored };
+          model = overrideFullId;
+        }
+      }
+    } catch { /* non-blocking */ }
+  }
+
   // ── Challenger / dual-brain decision ─────────────────────────────────────
   const hasBothProviders = !!(
     profile?.providers?.claude?.enabled &&
@@ -938,6 +982,7 @@ export function decideRoute({ profile = {}, detection = {}, cwd, thinkResult, se
     explanation: '',
     _healthScores: healthScores,
     _workStyle: workStyle,
+    ...(_advisorOverride   && { _advisorOverride }),
   };
 
   decision.explanation = explainDecision(decision, detection, profileWithEffectiveBias);

package/src/dispatch.mjs

@@ -1181,6 +1181,29 @@ async function dispatch(input = {}) {
       const { recordDispatchOutcome } = await import('./outcome.mjs');
       recordDispatchOutcome(input, nativeResult);
     } catch { /* never block */ }
+
+    // ── Self-correction: intelligent retry after failover exhaustion ──────────
+    if (!success) {
+      const attemptNumber = input._retryAttempt || 1;
+      try {
+        const { shouldRetry } = await import('./self-correct.mjs');
+        const retry = shouldRetry(nativeResult, decision, attemptNumber);
+        if (retry.retry && retry.decision) {
+          if (verbose) process.stderr.write(`[dual-brain] self-correct: ${retry.strategy} (attempt ${attemptNumber + 1}, reason: ${retry.reason})\n`);
+          return dispatch({
+            ...input,
+            decision: retry.decision,
+            _retryAttempt: attemptNumber + 1,
+            _skipPreDispatchThink: retry.strategy !== 'rethink',
+            _skipRelatedContext: true,
+          });
+        } else if (verbose) {
+          process.stderr.write(`[dual-brain] self-correct: giving up (${retry.reason})\n`);
+        }
+      } catch { /* non-blocking — if self-correct fails, return original failure */ }
+    }
+    // ── End self-correction ───────────────────────────────────────────────────
+
     return nativeResult;
   }
 
@@ -1303,6 +1326,29 @@ async function dispatch(input = {}) {
     const { recordDispatchOutcome } = await import('./outcome.mjs');
     recordDispatchOutcome(input, subResult);
   } catch { /* never block */ }
+
+  // ── Self-correction: intelligent retry after failover exhaustion ──────────
+  if (!success) {
+    const attemptNumber = input._retryAttempt || 1;
+    try {
+      const { shouldRetry } = await import('./self-correct.mjs');
+      const retry = shouldRetry(subResult, decision, attemptNumber);
+      if (retry.retry && retry.decision) {
+        if (verbose) process.stderr.write(`[dual-brain] self-correct: ${retry.strategy} (attempt ${attemptNumber + 1}, reason: ${retry.reason})\n`);
+        return dispatch({
+          ...input,
+          decision: retry.decision,
+          _retryAttempt: attemptNumber + 1,
+          _skipPreDispatchThink: retry.strategy !== 'rethink',
+          _skipRelatedContext: true,
+        });
+      } else if (verbose) {
+        process.stderr.write(`[dual-brain] self-correct: giving up (${retry.reason})\n`);
+      }
+    } catch { /* non-blocking — if self-correct fails, return original failure */ }
+  }
+  // ── End self-correction ───────────────────────────────────────────────────
+
   return subResult;
 }
 

package/src/outcome.mjs

@@ -45,6 +45,16 @@ function last7DaysFiles(cwd) {
   return files;
 }
 
+const INTENT_KEYWORDS = ['implement', 'fix', 'refactor', 'review', 'search', 'test'];
+
+function deriveIntent(prompt, tier) {
+  const lower = (prompt ?? '').toLowerCase();
+  for (const kw of INTENT_KEYWORDS) {
+    if (lower.includes(kw)) return kw;
+  }
+  return tier ?? 'execute';
+}
+
 export function recordDispatchOutcome(dispatchInput, result) {
   try {
     const cwd = dispatchInput.cwd ?? process.cwd();
@@ -69,6 +79,24 @@ export function recordDispatchOutcome(dispatchInput, result) {
 
     const filePath = join(outcomesDir(cwd), `outcome_${id}.json`);
     writeFileSync(filePath, JSON.stringify(record, null, 2), 'utf8');
+
+    // Score the outcome for the routing advisor (non-blocking)
+    try {
+      import('./signal.mjs').then(({ scoreOutcome }) =>
+        import('./routing-advisor.mjs').then(({ recordReward }) => {
+          const scored = scoreOutcome(record);
+          const intent = deriveIntent(record.prompt, record.tier);
+          const cellKey = `${record.tier}:${intent}`;
+          // Normalize full model ID to short name for the advisor cell
+          const modelId = record.model ?? 'sonnet';
+          const shortModel = /haiku/i.test(modelId) ? 'haiku'
+            : /opus/i.test(modelId) ? 'opus'
+            : 'sonnet';
+          recordReward(cellKey, shortModel, scored.reward, cwd);
+        })
+      ).catch(() => { /* non-blocking */ });
+    } catch { /* non-blocking */ }
+
     return record;
   } catch {
     return null;

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/self-correct.mjs

@@ -0,0 +1,145 @@
+// self-correct.mjs — Failure analysis and retry strategy selection
+
+const MODEL_TIER = { 'haiku': 1, 'sonnet': 2, 'opus': 3 };
+const TIER_MODEL = { 1: 'haiku', 2: 'sonnet', 3: 'opus' };
+const MAX_ATTEMPTS = 3;
+
+function modelTier(model = '') {
+  const m = model.toLowerCase();
+  if (m.includes('haiku')) return 1;
+  if (m.includes('opus')) return 3;
+  return 2; // sonnet default
+}
+
+function matchesAny(text, keywords) {
+  const t = text.toLowerCase();
+  return keywords.some(k => t.includes(k));
+}
+
+// Export 1: classifyFailure(result)
+export function classifyFailure(result) {
+  try {
+    const err = String(result?.error || result?.stderr || '');
+    const out = String(result?.output || result?.stdout || '');
+    const combined = err + ' ' + out;
+    const duration = result?.durationMs ?? 0;
+    const timeoutThreshold = result?.timeoutMs ?? 60_000;
+
+    if (matchesAny(combined, ['rate limit', 'ratelimit', '429', 'quota exceeded', 'capacity'])) {
+      return { type: 'rate-limit', confidence: 0.95, retryable: true };
+    }
+    if (matchesAny(combined, ['timeout', 'timed out']) || duration > timeoutThreshold) {
+      return { type: 'timeout', confidence: 0.9, retryable: true };
+    }
+    if (matchesAny(combined, ['context length', 'token limit', 'too long', 'maximum context', 'context window'])) {
+      return { type: 'context-overflow', confidence: 0.9, retryable: true };
+    }
+    if (matchesAny(combined, ['ambiguous', 'unclear', 'did you mean', 'which one', 'could you clarify', 'please clarify'])) {
+      return { type: 'specification', confidence: 0.85, retryable: false };
+    }
+    if (matchesAny(combined, ['unable to', "i don't know how", 'beyond my', 'cannot complete', 'incomplete'])) {
+      return { type: 'capability', confidence: 0.8, retryable: true };
+    }
+    // Heuristic: low quality output without explicit error signals capability gap
+    const quality = result?.quality ?? result?.score ?? null;
+    if (quality !== null && quality < 0.5) {
+      return { type: 'capability', confidence: 0.7, retryable: true };
+    }
+
+    return { type: 'unknown', confidence: 0.5, retryable: true };
+  } catch {
+    return { type: 'unknown', confidence: 0, retryable: true };
+  }
+}
+
+// Export 2: selectStrategy(failure, originalDecision, attemptNumber)
+export function selectStrategy(failure, originalDecision, attemptNumber) {
+  try {
+    if (!failure.retryable) {
+      return { strategy: 'give-up', reason: `failure type '${failure.type}' requires user input` };
+    }
+    if (attemptNumber >= MAX_ATTEMPTS) {
+      return { strategy: 'give-up', reason: `max attempts (${MAX_ATTEMPTS}) reached` };
+    }
+
+    const tier = modelTier(originalDecision?.model);
+
+    if (attemptNumber === 1) {
+      switch (failure.type) {
+        case 'capability':
+          if (tier >= 3) return { strategy: 'split', newDecision: originalDecision, reason: 'already at max tier; decompose task' };
+          return { strategy: 'escalate', newDecision: originalDecision, reason: 'model lacked capability; escalating tier' };
+        case 'timeout':
+          return { strategy: 'wait-retry', newDecision: originalDecision, reason: 'timed out; retrying with delay' };
+        case 'rate-limit':
+          return { strategy: 'wait-retry', newDecision: originalDecision, reason: 'rate limited; retrying after delay' };
+        case 'context-overflow':
+          return { strategy: 'compress', newDecision: originalDecision, reason: 'context too large; compressing' };
+        case 'specification':
+          return { strategy: 'give-up', reason: 'ambiguous specification; user clarification needed' };
+        default: // unknown
+          return { strategy: 'escalate', newDecision: originalDecision, reason: 'unknown failure; escalating as precaution' };
+      }
+    }
+
+    if (attemptNumber === 2) {
+      if (tier >= 3) {
+        return { strategy: 'split', newDecision: originalDecision, reason: 'max tier reached; splitting task' };
+      }
+      return { strategy: 'escalate', newDecision: originalDecision, reason: 'retry failed; escalating one final tier' };
+    }
+
+    return { strategy: 'give-up', reason: 'exhausted retry budget' };
+  } catch {
+    return { strategy: 'give-up', reason: 'internal error in strategy selection' };
+  }
+}
+
+// Export 3: buildRetryDecision(originalDecision, strategy, failure)
+export function buildRetryDecision(originalDecision, strategy, failure) {
+  try {
+    const base = {
+      ...originalDecision,
+      _retryAttempt: (originalDecision?._retryAttempt ?? 0) + 1,
+      _retryReason: failure.type,
+      _retryStrategy: strategy,
+    };
+
+    switch (strategy) {
+      case 'escalate': {
+        const tier = modelTier(originalDecision?.model);
+        const nextTier = Math.min(tier + 1, 3);
+        return { ...base, model: TIER_MODEL[nextTier] };
+      }
+      case 'compress':
+        return { ...base, _contextBudget: 0.5 };
+      case 'wait-retry':
+        return { ...base, _delayMs: 5000 };
+      case 'rethink':
+        return { ...base, tier: 'think', _retryAsThink: true };
+      case 'split':
+        return { ...base, _shouldDecompose: true };
+      default:
+        return base;
+    }
+  } catch {
+    return { ...originalDecision, _retryAttempt: 1, _retryReason: 'error', _retryStrategy: strategy };
+  }
+}
+
+// Export 4: shouldRetry(result, originalDecision, attemptNumber)
+export function shouldRetry(result, originalDecision, attemptNumber = 1) {
+  try {
+    const failure = classifyFailure(result);
+    const { strategy, newDecision, reason } = selectStrategy(failure, originalDecision, attemptNumber);
+
+    if (strategy === 'give-up') {
+      return { retry: false, reason, strategy };
+    }
+
+    const decision = buildRetryDecision(newDecision ?? originalDecision, strategy, failure);
+    return { retry: true, decision, reason, strategy };
+  } catch {
+    return { retry: false, reason: 'internal error in shouldRetry', strategy: 'give-up' };
+  }
+}

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