dual-brain 7.1.27 → 7.1.28

package/package.json

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

package/src/doctor.mjs

@@ -15,9 +15,12 @@
  *   checkFoundations, checkRoleBoundaries, checkEvidence, checkTokenWaste,
  *   runHealthCheck, formatHealthReport, compareHealth,
  *   doctorDiagnose, doctorRecover
+ *
+ * VERIFY system (runtime assumption verification):
+ *   verify, verifyAll, getVerificationCache, getStaleAssumptions, formatVerifications
  */
 
-import { existsSync, readFileSync, writeFileSync, renameSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, renameSync, appendFileSync } from 'fs';
 import { join } from 'path';
 import { readdir, readFile } from 'fs/promises';
 import { exec, execSync } from 'child_process';
@@ -549,6 +552,718 @@ export async function doctorRecover(run, failure = {}) {
   return { proposal, avoidApproaches, escalation };
 }
 
+// ─── VERIFY System ────────────────────────────────────────────────────────────
+
+// TTL constants (ms)
+const TTL_RUNTIME  = 5   * 60 * 1000;   // 5 minutes  — env/key checks
+const TTL_TOOL     = 24  * 60 * 60 * 1000; // 24 hours   — installed tool checks
+const TTL_REGISTRY = 7   * 24 * 60 * 60 * 1000; // 7 days — registry freshness
+
+const VERIFIERS = {
+  'claude-available': { ttl: TTL_TOOL, fn: () => {
+    try { execSync('which claude', { stdio: 'pipe', timeout: 2000 }); return { status: 'verified', evidence: 'claude CLI found', probe: 'which claude' }; }
+    catch { return { status: 'failed', evidence: 'claude CLI not found', probe: 'which claude' }; }
+  }},
+  'openai-key': { ttl: TTL_RUNTIME, fn: () => {
+    const has = !!process.env.OPENAI_API_KEY;
+    return { status: has ? 'verified' : 'failed', evidence: has ? 'OPENAI_API_KEY present' : 'OPENAI_API_KEY missing', probe: 'env check' };
+  }},
+  'anthropic-key': { ttl: TTL_RUNTIME, fn: () => {
+    const has = !!(process.env.ANTHROPIC_API_KEY || process.env.CLAUDE_API_KEY);
+    return { status: has ? 'verified' : 'failed', evidence: has ? 'API key present' : 'API key missing', probe: 'env check' };
+  }},
+  'git-available': { ttl: TTL_TOOL, fn: () => {
+    try { const v = execSync('git --version', { stdio: 'pipe', timeout: 2000 }).toString().trim(); return { status: 'verified', evidence: v, probe: 'git --version' }; }
+    catch { return { status: 'failed', evidence: 'git not found', probe: 'git --version' }; }
+  }},
+  'npm-auth': { ttl: TTL_RUNTIME, fn: () => {
+    try { const who = execSync('npm whoami', { stdio: 'pipe', timeout: 5000 }).toString().trim(); return { status: 'verified', evidence: `logged in as ${who}`, probe: 'npm whoami' }; }
+    catch { return { status: 'failed', evidence: 'npm auth failed', probe: 'npm whoami' }; }
+  }},
+  'database-reachable': { ttl: TTL_RUNTIME, fn: () => {
+    const url = process.env.DATABASE_URL;
+    if (!url) return { status: 'failed', evidence: 'DATABASE_URL not set', probe: 'env check' };
+    return { status: 'verified', evidence: 'DATABASE_URL configured (not connection-tested)', probe: 'env check' };
+  }},
+  'codex-available': { ttl: TTL_TOOL, fn: () => {
+    try { execSync('which codex', { stdio: 'pipe', timeout: 2000 }); return { status: 'verified', evidence: 'codex CLI found', probe: 'which codex' }; }
+    catch { return { status: 'failed', evidence: 'codex CLI not found', probe: 'which codex' }; }
+  }},
+  'rg-available': { ttl: TTL_TOOL, fn: () => {
+    try { execSync('which rg', { stdio: 'pipe', timeout: 2000 }); return { status: 'verified', evidence: 'ripgrep found', probe: 'which rg' }; }
+    catch { return { status: 'failed', evidence: 'ripgrep not found', probe: 'which rg' }; }
+  }},
+  'living-docs-init': { ttl: TTL_RUNTIME, fn: (cwd) => {
+    const exists = existsSync(join(cwd || process.cwd(), '.dual-brain'));
+    return { status: exists ? 'verified' : 'failed', evidence: exists ? '.dual-brain/ exists' : '.dual-brain/ not initialized', probe: 'fs check' };
+  }},
+  'model-registry-fresh': { ttl: TTL_REGISTRY, fn: () => {
+    try {
+      const age = Math.floor((Date.now() - new Date('2026-05-15').getTime()) / 86400000);
+      return { status: age <= 30 ? 'verified' : 'failed', evidence: `Registry ${age} days old`, probe: 'registry age check' };
+    } catch { return { status: 'unknown', evidence: 'Could not check', probe: 'registry age' }; }
+  }},
+};
+
+/**
+ * verify(claim, cwd) — test a single assumption by claim identifier.
+ * Returns a verification result object with status, evidence, probe, and timestamps.
+ */
+export function verify(claim, cwd) {
+  const checkedAt = new Date().toISOString();
+  const verifier = VERIFIERS[claim];
+  if (!verifier) {
+    const expiresAt = new Date(Date.now() + TTL_RUNTIME).toISOString();
+    return { claim, status: 'unknown', evidence: `No verifier registered for "${claim}"`, checkedAt, expiresAt, probe: 'none' };
+  }
+  try {
+    const result = verifier.fn(cwd);
+    const expiresAt = new Date(Date.now() + verifier.ttl).toISOString();
+    return { claim, status: result.status, evidence: result.evidence, checkedAt, expiresAt, probe: result.probe };
+  } catch (err) {
+    const expiresAt = new Date(Date.now() + TTL_RUNTIME).toISOString();
+    return { claim, status: 'unknown', evidence: `Verifier threw: ${err.message || String(err)}`, checkedAt, expiresAt, probe: 'error' };
+  }
+}
+
+/**
+ * verifyAll(cwd) — run all registered verifiers and append results to .dual-brain/verifications.jsonl.
+ * Returns array of verification result objects.
+ */
+export function verifyAll(cwd = process.cwd()) {
+  const results = Object.keys(VERIFIERS).map(claim => verify(claim, cwd));
+
+  // Persist to .dual-brain/verifications.jsonl (append-only)
+  try {
+    const dir = join(cwd, '.dual-brain');
+    if (existsSync(dir)) {
+      const logPath = join(dir, 'verifications.jsonl');
+      const lines = results.map(r => JSON.stringify(r)).join('\n') + '\n';
+      appendFileSync(logPath, lines, 'utf8');
+    }
+  } catch { /* storage failure is non-fatal */ }
+
+  return results;
+}
+
+/**
+ * getVerificationCache(cwd) — read .dual-brain/verifications.jsonl, return most recent
+ * non-expired result per claim. Expired entries are skipped.
+ */
+export function getVerificationCache(cwd = process.cwd()) {
+  const logPath = join(cwd, '.dual-brain', 'verifications.jsonl');
+  if (!existsSync(logPath)) return [];
+
+  let lines;
+  try { lines = readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean); }
+  catch { return []; }
+
+  const now = new Date().toISOString();
+  const latest = {};
+
+  for (const line of lines) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (!entry.claim || !entry.expiresAt) continue;
+    if (entry.expiresAt < now) continue; // expired — skip
+    // Keep the most recent non-expired entry per claim
+    if (!latest[entry.claim] || entry.checkedAt > latest[entry.claim].checkedAt) {
+      latest[entry.claim] = entry;
+    }
+  }
+
+  return Object.values(latest);
+}
+
+/**
+ * getStaleAssumptions(cwd) — return claims that are expired or failed.
+ * Checks cache first; any claim not in cache (or failed in cache) is considered stale.
+ */
+export function getStaleAssumptions(cwd = process.cwd()) {
+  const cached = getVerificationCache(cwd);
+  const cachedMap = Object.fromEntries(cached.map(r => [r.claim, r]));
+  const stale = [];
+
+  for (const claim of Object.keys(VERIFIERS)) {
+    const entry = cachedMap[claim];
+    if (!entry) {
+      // No valid cached result — treat as stale
+      stale.push({ claim, reason: 'no-cache', status: 'unknown', evidence: 'Never verified or all results expired' });
+    } else if (entry.status === 'failed') {
+      stale.push({ claim, reason: 'failed', status: 'failed', evidence: entry.evidence, checkedAt: entry.checkedAt });
+    }
+    // 'verified' and 'unknown' with valid cache are not stale
+  }
+
+  return stale;
+}
+
+/**
+ * formatVerifications(results) — display string for a list of verification results.
+ */
+export function formatVerifications(results) {
+  const lines = ['SYSTEM VERIFICATION'];
+  for (const r of results) {
+    const icon = r.status === 'verified' ? '✓' : r.status === 'failed' ? '✗' : '⚠';
+    lines.push(`  ${icon} ${r.claim}: ${r.evidence}`);
+  }
+  return lines.join('\n');
+}
+
+// ─── LEARN System ─────────────────────────────────────────────────────────────
+
+const THINK_TIER_MODELS = new Set(['claude-opus-4-6', 'o3', 'gpt-5.5']);
+const FAST_TIER_MODELS  = new Set(['claude-haiku-4-5-20251001', 'gpt-4o-mini']);
+const CODE_TASK_TYPES   = new Set(['fix', 'feature', 'refactor', 'implement', 'test', 'build', 'edit']);
+const REASONING_MODELS  = new Set(['o3']);
+
+function learningsPath(cwd) {
+  return join(cwd, '.dual-brain', 'learnings.jsonl');
+}
+
+function readLearnings(cwd) {
+  const p = learningsPath(cwd);
+  if (!existsSync(p)) return [];
+  try {
+    return readFileSync(p, 'utf8').trim().split('\n').filter(Boolean).flatMap(line => {
+      try { return [JSON.parse(line)]; } catch { return []; }
+    });
+  } catch { return []; }
+}
+
+function deriveModelFit(taskResult) {
+  const { success, model, tier, taskType, duration, filesChanged } = taskResult;
+  const isThinkModel = THINK_TIER_MODELS.has(model);
+  const isFastModel  = FAST_TIER_MODELS.has(model);
+  const isReasoningModel = REASONING_MODELS.has(model);
+  const isCodeTask   = CODE_TASK_TYPES.has(taskType);
+
+  if (isReasoningModel && isCodeTask) return 'wrong_type';
+  if (!isCodeTask && !isReasoningModel && isThinkModel && tier === 'search') return 'wrong_type';
+
+  if (!success) {
+    if (isFastModel && tier !== 'search') return 'underpowered';
+    return 'good';
+  }
+
+  if (isThinkModel && (tier === 'search' || (filesChanged <= 1 && duration < 30000))) return 'overkill';
+  if (isFastModel && filesChanged > 3) return 'underpowered';
+
+  return 'good';
+}
+
+function deriveRoutingAccuracy(taskResult) {
+  const { success, modelFit, tier, duration, model } = taskResult;
+  const isFastModel = FAST_TIER_MODELS.has(model);
+  const isThinkModel = THINK_TIER_MODELS.has(model);
+
+  if (success && (modelFit === 'good' || modelFit === 'wrong_type')) return 'correct';
+  if (!success && isFastModel && tier !== 'search') return 'should_have_escalated';
+  if (success && isThinkModel && duration > 120000 && modelFit === 'overkill') return 'should_have_simplified';
+  if (success && modelFit === 'overkill') return 'should_have_simplified';
+  if (!success) return 'should_have_escalated';
+  return 'correct';
+}
+
+export function recordLearning(taskResult, cwd = process.cwd()) {
+  try {
+    const {
+      taskType = 'unknown',
+      prompt = '',
+      model = '',
+      provider = '',
+      tier = '',
+      reasoningDepth = 'low',
+      wasEnriched = false,
+      wasDualBrain = false,
+      success = false,
+      duration = 0,
+      filesChanged = 0,
+    } = taskResult;
+
+    const modelFit = deriveModelFit({ success, model, tier, taskType, duration, filesChanged });
+
+    const record = {
+      id: `learn_${Date.now()}`,
+      timestamp: new Date().toISOString(),
+      taskType,
+      prompt: String(prompt).slice(0, 200),
+      model,
+      provider,
+      tier,
+      reasoningDepth,
+      wasEnriched,
+      wasDualBrain,
+      success,
+      duration,
+      filesChanged,
+      modelFit,
+      routingAccuracy: deriveRoutingAccuracy({ success, modelFit, tier, duration, model }),
+    };
+
+    const p = learningsPath(cwd);
+    const dir = join(cwd, '.dual-brain');
+    if (existsSync(dir)) {
+      appendFileSync(p, JSON.stringify(record) + '\n', 'utf8');
+    }
+    return record;
+  } catch { return null; }
+}
+
+export function getModelSuccessRates(cwd = process.cwd(), days = 7) {
+  const cutoff = new Date(Date.now() - days * 86400000).toISOString();
+  const learnings = readLearnings(cwd).filter(l => l.timestamp >= cutoff);
+
+  const stats = {};
+  for (const l of learnings) {
+    if (!l.model) continue;
+    if (!stats[l.model]) stats[l.model] = { total: 0, success: 0, totalDuration: 0, tierCounts: {} };
+    stats[l.model].total += 1;
+    if (l.success) stats[l.model].success += 1;
+    stats[l.model].totalDuration += (l.duration || 0);
+    const tierKey = `${l.tier || 'unknown'}:${l.taskType || 'unknown'}`;
+    stats[l.model].tierCounts[tierKey] = (stats[l.model].tierCounts[tierKey] || 0) + 1;
+  }
+
+  const result = {};
+  for (const [model, s] of Object.entries(stats)) {
+    const topTiers = Object.entries(s.tierCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([key]) => key.split(':')[0] + ':' + key.split(':')[1]);
+    result[model] = {
+      total: s.total,
+      success: s.success,
+      rate: s.total > 0 ? Math.round((s.success / s.total) * 100) / 100 : 0,
+      avgDuration: s.total > 0 ? Math.round(s.totalDuration / s.total) : 0,
+      bestFor: [...new Set(topTiers.map(t => t.split(':')[0]))],
+    };
+  }
+  return result;
+}
+
+export function getRoutingInsights(cwd = process.cwd()) {
+  const learnings = readLearnings(cwd);
+  if (learnings.length === 0) return [];
+
+  const insights = [];
+  const MIN_POINTS = 5;
+
+  const byModelTask = {};
+  for (const l of learnings) {
+    const key = `${l.model}:${l.taskType}`;
+    if (!byModelTask[key]) byModelTask[key] = { success: 0, total: 0, overkill: 0, underpowered: 0 };
+    byModelTask[key].total += 1;
+    if (l.success) byModelTask[key].success += 1;
+    if (l.modelFit === 'overkill') byModelTask[key].overkill += 1;
+    if (l.modelFit === 'underpowered') byModelTask[key].underpowered += 1;
+  }
+
+  for (const [key, s] of Object.entries(byModelTask)) {
+    if (s.total < MIN_POINTS) continue;
+    const [model, taskType] = key.split(':');
+    const rate = s.success / s.total;
+    const overkillRate = s.overkill / s.total;
+    const underpoweredRate = s.underpowered / s.total;
+
+    if (rate >= 0.9 && overkillRate < 0.1) {
+      insights.push({
+        insight: `${model} succeeds ${Math.round(rate * 100)}% on ${taskType} tasks — reliable for this work`,
+        confidence: Math.min(0.95, 0.6 + s.total * 0.01),
+        evidence: `${s.success}/${s.total} tasks`,
+      });
+    }
+
+    if (overkillRate > 0.3 && rate >= 0.85) {
+      insights.push({
+        insight: `${model} is overkill for ${taskType} — a cheaper model likely sufficient`,
+        confidence: Math.min(0.9, 0.5 + s.total * 0.01),
+        evidence: `${s.overkill}/${s.total} tasks flagged overkill`,
+      });
+    }
+
+    if (underpoweredRate > 0.3 || rate < 0.7) {
+      insights.push({
+        insight: `${model} struggles on ${taskType} (${Math.round(rate * 100)}% success) — consider escalating`,
+        confidence: Math.min(0.9, 0.5 + s.total * 0.01),
+        evidence: `${s.success}/${s.total} tasks`,
+      });
+    }
+  }
+
+  const enriched    = learnings.filter(l => l.wasEnriched);
+  const notEnriched = learnings.filter(l => !l.wasEnriched);
+  if (enriched.length >= MIN_POINTS && notEnriched.length >= MIN_POINTS) {
+    const rateEnriched    = enriched.filter(l => l.success).length / enriched.length;
+    const rateNotEnriched = notEnriched.filter(l => l.success).length / notEnriched.length;
+    const delta = Math.round((rateEnriched - rateNotEnriched) * 100);
+    if (Math.abs(delta) >= 10) {
+      insights.push({
+        insight: delta > 0
+          ? `Prompt enrichment improved success rate by ${delta}%`
+          : `Prompt enrichment had no benefit — success rate ${Math.abs(delta)}% lower`,
+        confidence: Math.min(0.9, 0.5 + Math.min(enriched.length, notEnriched.length) * 0.01),
+        evidence: `${enriched.length} enriched vs ${notEnriched.length} raw`,
+      });
+    }
+  }
+
+  const dualBrain    = learnings.filter(l => l.wasDualBrain);
+  const singleBrain  = learnings.filter(l => !l.wasDualBrain);
+  if (dualBrain.length >= MIN_POINTS && singleBrain.length >= MIN_POINTS) {
+    const rateDual   = dualBrain.filter(l => l.success).length / dualBrain.length;
+    const rateSingle = singleBrain.filter(l => l.success).length / singleBrain.length;
+    const delta = Math.round((rateDual - rateSingle) * 100);
+    if (delta >= 10) {
+      insights.push({
+        insight: `Dual-brain review improves success rate by ${delta}% over single-brain`,
+        confidence: Math.min(0.85, 0.5 + Math.min(dualBrain.length, singleBrain.length) * 0.015),
+        evidence: `${dualBrain.length} dual vs ${singleBrain.length} single`,
+      });
+    }
+  }
+
+  return insights;
+}
+
+export function suggestRoutingAdjustment(taskType, currentModel, cwd = process.cwd()) {
+  const learnings = readLearnings(cwd).filter(
+    l => l.taskType === taskType && l.model === currentModel
+  );
+
+  if (learnings.length < 5) {
+    return { suggestion: 'keep', reason: 'insufficient data', confidence: 0, evidenceCount: learnings.length, suggestedModel: null };
+  }
+
+  const total = learnings.length;
+  const successCount = learnings.filter(l => l.success).length;
+  const successRate = successCount / total;
+  const overkillCount = learnings.filter(l => l.modelFit === 'overkill').length;
+  const overkillRate = overkillCount / total;
+
+  if (successRate > 0.9 && overkillRate > 0.3) {
+    const isFastModel = FAST_TIER_MODELS.has(currentModel);
+    const isThinkModel = THINK_TIER_MODELS.has(currentModel);
+    let suggestedModel = null;
+    if (isThinkModel) {
+      suggestedModel = currentModel.startsWith('claude') ? 'claude-sonnet-4-6' : 'gpt-4o';
+    } else if (!isFastModel) {
+      suggestedModel = currentModel.startsWith('claude') ? 'claude-haiku-4-5-20251001' : 'gpt-4o-mini';
+    }
+    return {
+      suggestion: 'simplify',
+      reason: `${Math.round(successRate * 100)}% success rate with ${Math.round(overkillRate * 100)}% overkill signal`,
+      confidence: Math.min(0.9, 0.5 + total * 0.01),
+      evidenceCount: total,
+      suggestedModel,
+    };
+  }
+
+  if (successRate < 0.7) {
+    const isThinkModel = THINK_TIER_MODELS.has(currentModel);
+    let suggestedModel = null;
+    if (!isThinkModel) {
+      suggestedModel = currentModel.startsWith('claude') ? 'claude-opus-4-6' : 'o3';
+    }
+    return {
+      suggestion: 'escalate',
+      reason: `${Math.round(successRate * 100)}% success rate on ${taskType} — below acceptable threshold`,
+      confidence: Math.min(0.9, 0.5 + total * 0.01),
+      evidenceCount: total,
+      suggestedModel,
+    };
+  }
+
+  return {
+    suggestion: 'keep',
+    reason: `${Math.round(successRate * 100)}% success rate — routing is appropriate`,
+    confidence: Math.min(0.9, 0.5 + total * 0.01),
+    evidenceCount: total,
+    suggestedModel: null,
+  };
+}
+
+export function formatLearnings(insights, cwd = process.cwd()) {
+  const learnings = readLearnings(cwd);
+  const rates = getModelSuccessRates(cwd);
+  const total = learnings.length;
+
+  const lines = [`ROUTING INTELLIGENCE (${total} task${total === 1 ? '' : 's'} analyzed)`];
+
+  for (const [model, s] of Object.entries(rates)) {
+    if (s.total < 3) continue;
+    const pct = Math.round(s.rate * 100);
+    const tasks = s.bestFor.join('/') || 'various';
+    const icon = pct >= 85 ? '📈' : pct >= 70 ? '📊' : '⚠️ ';
+    lines.push(`  ${icon} ${model}: ${pct}% success on ${tasks} tasks (${s.total} tasks)`);
+  }
+
+  for (const ins of (insights || [])) {
+    const pct = Math.round(ins.confidence * 100);
+    const isWarning = ins.insight.toLowerCase().includes('struggle') || ins.insight.toLowerCase().includes('below') || ins.insight.toLowerCase().includes('no benefit');
+    const icon = isWarning ? '⚠️ ' : '💡';
+    lines.push(`  ${icon} ${ins.insight}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function getLearningStats(cwd = process.cwd()) {
+  const learnings = readLearnings(cwd);
+  if (learnings.length === 0) {
+    return { totalLearnings: 0, oldestEntry: null, newestEntry: null, modelsTracked: 0, avgSuccessRate: 0 };
+  }
+  const timestamps = learnings.map(l => l.timestamp).sort();
+  const models = new Set(learnings.map(l => l.model).filter(Boolean));
+  const successCount = learnings.filter(l => l.success).length;
+  return {
+    totalLearnings: learnings.length,
+    oldestEntry: timestamps[0],
+    newestEntry: timestamps[timestamps.length - 1],
+    modelsTracked: models.size,
+    avgSuccessRate: Math.round((successCount / learnings.length) * 100) / 100,
+  };
+}
+
+// ─── DISCOVER System ─────────────────────────────────────────────────────────
+
+const KNOWN_TOOLS = ['git','node','npm','codex','claude','rg','gh','replit','docker','python','python3','pip','cargo','go','java','ruby','deno','bun','pnpm','yarn'];
+const STANDARD_AWARENESS = new Set(['git','node','npm','codex','claude','rg','gh','replit']);
+
+const SERVICE_PATTERNS = {
+  'REDIS_URL':           'Redis',
+  'MONGODB_URI':         'MongoDB',
+  'MONGO_URL':           'MongoDB',
+  'ELASTICSEARCH_URL':   'Elasticsearch',
+  'RABBITMQ_URL':        'RabbitMQ',
+  'S3_BUCKET':           'S3 Storage',
+  'AWS_ACCESS_KEY_ID':   'AWS',
+  'GCP_PROJECT':         'Google Cloud',
+  'STRIPE_SECRET_KEY':   'Stripe',
+  'SENDGRID_API_KEY':    'SendGrid',
+  'TWILIO_ACCOUNT_SID':  'Twilio',
+  'SENTRY_DSN':          'Sentry',
+  'DATADOG_API_KEY':     'Datadog',
+  'SUPABASE_URL':        'Supabase',
+  'FIREBASE_PROJECT_ID': 'Firebase',
+  'NEON_DATABASE_URL':   'Neon DB',
+};
+
+const KNOWN_FRAMEWORKS = ['express','next','react','vue','fastify','prisma','drizzle','nestjs','koa','hapi','svelte','nuxt','remix','astro','trpc'];
+
+function safeExecSyncDiscover(cmd) {
+  try {
+    return execSync(cmd, { timeout: 2000, encoding: 'utf8', stdio: ['pipe','pipe','pipe'] }).trim();
+  } catch { return null; }
+}
+
+function discoverCLITools() {
+  const found = [];
+  for (const tool of KNOWN_TOOLS) {
+    const toolPath = safeExecSyncDiscover(`which ${tool}`);
+    if (toolPath && !STANDARD_AWARENESS.has(tool)) {
+      found.push({ type: 'tool', name: tool, detail: `${tool} CLI available at ${toolPath}`, source: 'PATH scan' });
+    }
+  }
+  return found;
+}
+
+/**
+ * discoverMCPTools(cwd) — scan for MCP servers across known config locations.
+ * Returns array of { name, command, args } for each configured MCP server.
+ */
+export function discoverMCPTools(cwd = process.cwd()) {
+  const locations = [
+    join(process.env.HOME || '/root', '.claude', 'claude_desktop_config.json'),
+    join(cwd, '.claude', 'settings.json'),
+    join(cwd, '.claude', 'settings.local.json'),
+  ];
+  const servers = [];
+  const seen = new Set();
+  for (const loc of locations) {
+    if (!existsSync(loc)) continue;
+    let cfg;
+    try { cfg = JSON.parse(readFileSync(loc, 'utf8')); } catch { continue; }
+    const mcpServers = cfg.mcpServers || (cfg.mcp && cfg.mcp.servers) || {};
+    for (const [name, conf] of Object.entries(mcpServers)) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      servers.push({ name, command: conf.command || null, args: conf.args || [] });
+    }
+  }
+  return servers;
+}
+
+function discoverMCPCapabilities(cwd) {
+  const servers = discoverMCPTools(cwd);
+  return servers.map(s => ({
+    type: 'mcp',
+    name: s.name,
+    detail: `MCP server: ${[s.command, ...(s.args || [])].filter(Boolean).join(' ')}`.trim(),
+    source: 'MCP config scan',
+  }));
+}
+
+function discoverEnvServices() {
+  const found = [];
+  const seen = new Set();
+  for (const [envKey, service] of Object.entries(SERVICE_PATTERNS)) {
+    if (process.env[envKey] !== undefined && !seen.has(service)) {
+      seen.add(service);
+      // Report presence only — NEVER expose values
+      found.push({ type: 'env', name: service, detail: `${service} configured via ${envKey}`, source: 'env scan' });
+    }
+  }
+  return found;
+}
+
+function discoverProjectTools(cwd) {
+  const pkgPath = join(cwd, 'package.json');
+  if (!existsSync(pkgPath)) return [];
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')); } catch { return []; }
+
+  const found = [];
+  for (const [name] of Object.entries(pkg.scripts || {})) {
+    found.push({ type: 'cli', name: `npm run ${name}`, detail: `Project script: ${name}`, source: 'package.json scripts' });
+  }
+  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  for (const fw of KNOWN_FRAMEWORKS) {
+    if (allDeps[fw]) {
+      found.push({ type: 'config', name: fw, detail: `${fw} framework detected (${allDeps[fw]})`, source: 'package.json deps' });
+    }
+  }
+  return found;
+}
+
+function discoverReplitFeatures(cwd) {
+  const replitPath = join(cwd, '.replit');
+  if (!existsSync(replitPath)) return [];
+  let content;
+  try { content = readFileSync(replitPath, 'utf8'); } catch { return []; }
+
+  const found = [];
+  if (/\[deployment\]/i.test(content))
+    found.push({ type: 'service', name: 'replit-deployment', detail: 'Replit deployment config present', source: '.replit' });
+  if (/\[auth\]/i.test(content))
+    found.push({ type: 'service', name: 'replit-auth', detail: 'Replit auth config present', source: '.replit' });
+
+  const moduleMatch = content.match(/^modules\s*=\s*\[([^\]]+)\]/m);
+  if (moduleMatch) {
+    const modules = moduleMatch[1].split(',').map(m => m.trim().replace(/['"]/g, '')).filter(Boolean);
+    for (const mod of modules) {
+      found.push({ type: 'config', name: `replit-module:${mod}`, detail: `Replit module: ${mod}`, source: '.replit' });
+    }
+  }
+
+  const nixChannelPath = join(cwd, '.replit', 'nix', 'channel');
+  if (existsSync(nixChannelPath)) {
+    let channel;
+    try { channel = readFileSync(nixChannelPath, 'utf8').trim(); } catch { channel = 'unknown'; }
+    found.push({ type: 'config', name: 'nix', detail: `Nix channel: ${channel}`, source: '.replit/nix/channel' });
+  }
+
+  return found;
+}
+
+function loadLastDiscovery(cwd) {
+  const logPath = join(cwd, '.dual-brain', 'discoveries.jsonl');
+  if (!existsSync(logPath)) return null;
+  try {
+    const lines = readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+    if (lines.length === 0) return null;
+    return JSON.parse(lines[lines.length - 1]);
+  } catch { return null; }
+}
+
+function appendDiscoveryLog(cwd, entry) {
+  const dir = join(cwd, '.dual-brain');
+  try {
+    if (!existsSync(dir)) execSync(`mkdir -p "${dir}"`, { timeout: 2000 });
+    appendFileSync(join(dir, 'discoveries.jsonl'), JSON.stringify(entry) + '\n', 'utf8');
+  } catch { /* graceful degradation */ }
+}
+
+/**
+ * discover(cwd) — scan for capabilities not in the standard awareness set.
+ * Returns { discoveredAt, newCapabilities, knownCapabilities, totalFound }.
+ */
+export function discover(cwd = process.cwd()) {
+  const discoveredAt = new Date().toISOString();
+  const allFound = [];
+
+  // Each probe is independent — failures don't stop others
+  try { allFound.push(...discoverCLITools()); } catch { /* ignore */ }
+  try { allFound.push(...discoverMCPCapabilities(cwd)); } catch { /* ignore */ }
+  try { allFound.push(...discoverEnvServices()); } catch { /* ignore */ }
+  try { allFound.push(...discoverProjectTools(cwd)); } catch { /* ignore */ }
+  try { allFound.push(...discoverReplitFeatures(cwd)); } catch { /* ignore */ }
+
+  const last = loadLastDiscovery(cwd);
+  const lastNames = new Set(last ? (last.newCapabilities || []).map(c => `${c.type}:${c.name}`) : []);
+  const prevKnown = last ? (last.knownCapabilities || 0) : 0;
+
+  const newCapabilities = allFound.filter(c => !lastNames.has(`${c.type}:${c.name}`));
+
+  const result = {
+    discoveredAt,
+    newCapabilities,
+    knownCapabilities: prevKnown + (allFound.length - newCapabilities.length),
+    totalFound: allFound.length,
+  };
+
+  appendDiscoveryLog(cwd, result);
+  return result;
+}
+
+/**
+ * getDiscoveryLog(cwd, limit) — read recent discovery entries from .dual-brain/discoveries.jsonl.
+ */
+export function getDiscoveryLog(cwd = process.cwd(), limit = 20) {
+  const logPath = join(cwd, '.dual-brain', 'discoveries.jsonl');
+  if (!existsSync(logPath)) return [];
+  try {
+    const lines = readFileSync(logPath, 'utf8').trim().split('\n').filter(Boolean);
+    return lines.slice(-limit).map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * getNewSinceLastScan(cwd) — run discover(), return only capabilities not seen in previous scan.
+ */
+export function getNewSinceLastScan(cwd = process.cwd()) {
+  const last = loadLastDiscovery(cwd);
+  const lastNames = new Set(last ? (last.newCapabilities || []).map(c => `${c.type}:${c.name}`) : []);
+
+  const current = discover(cwd);
+  const trulyNew = current.newCapabilities.filter(c => !lastNames.has(`${c.type}:${c.name}`));
+  return { ...current, newCapabilities: trulyNew };
+}
+
+/**
+ * formatDiscovery(result) — format discovery result as a human-readable string.
+ */
+export function formatDiscovery(result) {
+  const { newCapabilities = [], totalFound = 0 } = result;
+  const newCount = newCapabilities.length;
+  const lines = [`CAPABILITY DISCOVERY (${totalFound} found, ${newCount} new)`];
+
+  for (const cap of newCapabilities) {
+    lines.push(`  🆕 ${cap.type}: ${cap.name} — ${cap.detail}`);
+  }
+
+  const alreadyKnown = totalFound - newCount;
+  if (alreadyKnown > 0) {
+    lines.push(`  ── ${alreadyKnown} known capability${alreadyKnown === 1 ? '' : 'ies'} (already tracked)`);
+  }
+
+  if (newCount === 0 && totalFound === 0) {
+    lines.push('  (no capabilities detected)');
+  }
+
+  return lines.join('\n');
+}
+
 // ─── Health Baseline Comparison ───────────────────────────────────────────────
 export async function compareHealth(cwd = process.cwd()) {
   const bpath = join(cwd, '.dualbrain', 'health-baseline.json');