dual-brain 4.1.0 → 4.2.0

package/README.md

@@ -124,6 +124,24 @@ npx dual-brain status            # check current profile and provider health
 - **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work.
 - **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews.
 
+## Troubleshooting
+
+**Hooks not firing** -- Run `node .claude/hooks/health-check.mjs`. Check that `.claude/settings.json` has the hook entries. Re-run `npx dual-brain` to re-register.
+
+**Codex/GPT features unavailable** -- Run `codex --version` and `codex login`. If Codex CLI isn't installed: `npm i -g @openai/codex`. Re-run `npx dual-brain` to detect.
+
+**Auth expired** -- Run `claude login` for Claude, `codex login` for OpenAI. Re-run `npx dual-brain` to re-detect.
+
+**Duplicate warnings every time** -- Normal during agent waves (3+ agents in 90s). The system auto-suppresses. If persistent with single agents, check for identical task descriptions.
+
+**Budget warnings too aggressive/too lenient** -- Switch profile: `npx dual-brain mode cost-saver` or `npx dual-brain mode quality-first`. Or set custom limits with `npx dual-brain budget <session$> [daily$]`.
+
+**Corrupt state / weird behavior** -- Remove state files and re-run: `rm .claude/dual-brain.profile.json .claude/hooks/dual-brain.*.json 2>/dev/null; npx dual-brain`
+
+**Multiple Claude Code sessions** -- State files may have brief write conflicts. Each session tracks independently. Use a single session for best results.
+
+**Uninstall** -- `npx dual-brain --uninstall` removes hooks from settings.json and cleans state files.
+
 ## Requirements
 
 - Node 20+

package/hooks/atomic-write.mjs

@@ -0,0 +1,107 @@
+/**
+ * atomic-write.mjs — Atomic file operations for the dual-brain orchestrator.
+ *
+ * Prevents race conditions in read-modify-write patterns under multi-session use.
+ * No dependencies — uses only Node.js builtins.
+ *
+ * Exported API:
+ *   atomicWriteJSON(filePath, data)                    → write JSON atomically via tmp+rename
+ *   lockedReadModifyWrite(filePath, modifyFn, default) → locked read-modify-write cycle
+ */
+
+import { openSync, closeSync, readFileSync, writeFileSync, renameSync, unlinkSync, statSync } from 'fs';
+import { constants } from 'fs';
+
+const LOCK_TIMEOUT_MS = 5_000;
+const STALE_LOCK_MS = 10_000;
+
+/**
+ * Atomically write JSON data to filePath using tmp-file + rename.
+ * Tmp file is in the same directory to avoid cross-device rename issues.
+ */
+export function atomicWriteJSON(filePath, data) {
+  const tmp = filePath + '.tmp.' + process.pid;
+  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
+  renameSync(tmp, filePath);
+}
+
+/**
+ * Acquire a .lock file using O_EXCL for atomic creation.
+ * Returns true if lock acquired, false otherwise.
+ * Steals stale locks (older than STALE_LOCK_MS).
+ */
+function acquireLock(lockPath) {
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    try {
+      const fd = openSync(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL);
+      writeFileSync(fd, JSON.stringify({ pid: process.pid, ts: Date.now() }));
+      closeSync(fd);
+      return true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+
+      // Check for stale lock
+      try {
+        const stat = statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > STALE_LOCK_MS) {
+          // Stale lock — process likely died, steal it
+          try { unlinkSync(lockPath); } catch {}
+          continue;
+        }
+      } catch {
+        // Lock disappeared between our check — retry
+        continue;
+      }
+
+      // Wait briefly before retrying
+      const waitMs = 10 + Math.floor(Math.random() * 20);
+      const end = Date.now() + waitMs;
+      while (Date.now() < end) { /* spin */ }
+    }
+  }
+  return false;
+}
+
+function releaseLock(lockPath) {
+  try { unlinkSync(lockPath); } catch {}
+}
+
+/**
+ * Locked read-modify-write cycle.
+ *
+ * 1. Acquire .lock file (O_EXCL atomic creation)
+ * 2. Read current JSON (or use defaultValue if missing/corrupt)
+ * 3. Call modifyFn(currentData) → newData
+ * 4. Atomic write newData via tmp+rename
+ * 5. Release lock
+ *
+ * @param {string} filePath — JSON file to modify
+ * @param {function} modifyFn — (currentData) => newData
+ * @param {*} defaultValue — used if file doesn't exist or is corrupt
+ */
+export function lockedReadModifyWrite(filePath, modifyFn, defaultValue = {}) {
+  const lockPath = filePath + '.lock';
+  const locked = acquireLock(lockPath);
+
+  if (!locked) {
+    // Timeout — fall through without lock (better than hanging)
+    // This matches the previous unlocked behavior as a degraded fallback
+  }
+
+  try {
+    let current;
+    try {
+      current = JSON.parse(readFileSync(filePath, 'utf8'));
+    } catch {
+      current = typeof defaultValue === 'function' ? defaultValue() : defaultValue;
+    }
+
+    const updated = modifyFn(current);
+    atomicWriteJSON(filePath, updated);
+    return updated;
+  } finally {
+    if (locked) releaseLock(lockPath);
+  }
+}

package/hooks/cost-logger.mjs

@@ -272,6 +272,28 @@ async function main() {
     } catch {}
   }
 
+  // Record outcomes (success + failure) to decision ledger for routing feedback
+  if (toolName === 'Agent') {
+    try {
+      const { computePromptHash } = await import('./failure-detector.mjs');
+      const { recordDecision, recordOutcome } = await import('./decision-ledger.mjs');
+      const promptHash = computePromptHash(toolInput);
+      const decisionId = recordDecision({
+        tier,
+        provider: detectProvider(model),
+        model,
+        prompt_hash: promptHash,
+        profile: loadActiveProfile(),
+        session_id: SESSION_ID,
+      });
+      recordOutcome(decisionId, {
+        success: status !== 'error',
+        actual_input_tokens: inputTokens,
+        actual_output_tokens: outputTokens,
+      });
+    } catch {}
+  }
+
   const budgetMsg = await checkBudget();
 
   // PostToolUse hooks must emit a JSON object to stdout

package/hooks/decision-ledger.mjs

@@ -204,6 +204,55 @@ function getInsights(opts = {}) {
   };
 }
 
+/**
+ * getOutcomeStats — lightweight aggregation for the routing hot path.
+ *
+ * Returns success rates by tier and provider over the last 24 hours,
+ * plus flags for any tier with < 50% success (with ≥ 5 outcomes).
+ */
+function getOutcomeStats() {
+  const { decisions, outcomes } = loadLedger();
+  const merged = mergeDecisionsWithOutcomes(decisions, outcomes);
+
+  const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+  const recent = merged.filter(d => d.outcome && d.timestamp >= cutoff);
+
+  const byTier = {};
+  const byProvider = {};
+
+  for (const d of recent) {
+    // Tier stats
+    const t = d.tier || 'execute';
+    if (!byTier[t]) byTier[t] = { total: 0, success: 0 };
+    byTier[t].total++;
+    if (d.outcome.success) byTier[t].success++;
+
+    // Provider stats
+    const p = d.provider || 'claude';
+    if (!byProvider[p]) byProvider[p] = { total: 0, success: 0 };
+    byProvider[p].total++;
+    if (d.outcome.success) byProvider[p].success++;
+  }
+
+  // Flag underperforming tiers (< 50% success with ≥ 5 outcomes)
+  const underperforming = [];
+  for (const [tier, stats] of Object.entries(byTier)) {
+    if (stats.total >= 5) {
+      const rate = Math.round((stats.success / stats.total) * 100);
+      if (rate < 50) {
+        underperforming.push({ tier, rate, total: stats.total });
+      }
+    }
+  }
+
+  return {
+    by_tier: byTier,
+    by_provider: byProvider,
+    total_outcomes: recent.length,
+    underperforming,
+  };
+}
+
 // ─── CLI ────────────────────────────────────────────────────────────────────
 
 function printInsights() {
@@ -296,4 +345,4 @@ if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
   }
 }
 
-export { recordDecision, recordOutcome, getInsights, loadLedger };
+export { recordDecision, recordOutcome, getInsights, getOutcomeStats, loadLedger };

package/hooks/enforce-tier.mjs

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, appendFileSync, renameSync } from 'fs';
+import { readFileSync, writeFileSync, appendFileSync } from 'fs';
 import { dirname, resolve, join } from 'path';
 import { fileURLToPath } from 'url';
 import { classifyRisk, extractPaths } from './risk-classifier.mjs';
 import { computePromptHash, checkFailureLoop, recordFailure } from './failure-detector.mjs';
+import { getOutcomeStats } from './decision-ledger.mjs';
+import { atomicWriteJSON } from './atomic-write.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CONFIG_FILE = resolve(__dirname, '..', 'orchestrator.json');
@@ -17,7 +19,7 @@ function detectBurst() {
   try { state = JSON.parse(readFileSync(BURST_FILE, 'utf8')); } catch {}
   if (now - state.window_start > 90_000) state = { count: 0, window_start: now };
   state.count++;
-  try { writeFileSync(BURST_FILE, JSON.stringify(state)); } catch {}
+  try { atomicWriteJSON(BURST_FILE, state); } catch {}
   return state.count >= 3;
 }
 
@@ -90,9 +92,7 @@ function logRecommendation(event) {
       summary.recent_hashes = summary.recent_hashes.filter(h => Date.parse(h.ts) >= tenMinAgo);
     }
     summary.updated_at = new Date().toISOString();
-    const tmp = summaryFile + '.tmp.' + process.pid;
-    writeFileSync(tmp, JSON.stringify(summary, null, 2) + '\n');
-    renameSync(tmp, summaryFile);
+    atomicWriteJSON(summaryFile, summary);
   } catch {}
 
   // Sync ledger write (append-only, fast)
@@ -254,10 +254,12 @@ try {
 
   // Balance hint — populated after tier is fully resolved
   let balanceHint = null;
+  // Outcome advisory — populated after tier is fully resolved
+  let outcomeAdvisory = null;
 
-  // Helper to prepend optional warnings (duplicate + drift + balance + auto) before a message
+  // Helper to prepend optional warnings (duplicate + drift + balance + outcome + auto) before a message
   const prependWarnings = (msg) => {
-    const parts = [duplicateWarning, driftWarning, failureMessage, msg, autoStatus, balanceHint].filter(Boolean);
+    const parts = [duplicateWarning, driftWarning, failureMessage, msg, autoStatus, balanceHint, outcomeAdvisory].filter(Boolean);
     return parts.join('\n\n');
   };
 
@@ -349,6 +351,17 @@ try {
     }
   }
 
+  // Outcome stats advisory — best-effort, suppressed in burst mode
+  if (!burstMode) {
+    try {
+      const stats = getOutcomeStats();
+      const tierIssue = stats.underperforming.find(u => u.tier === tier);
+      if (tierIssue) {
+        outcomeAdvisory = `Heads up — ${tierIssue.tier} tasks have been struggling lately (${tierIssue.rate}% success over ${tierIssue.total} recent outcomes). Consider escalating to a higher tier.`;
+      }
+    } catch {}
+  }
+
   const expected = preferredModel(config, tier);
 
   if (tier === 'think') {
@@ -363,7 +376,7 @@ try {
         followed: true,
         profile: profileName,
       });
-      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
+      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint, outcomeAdvisory].filter(Boolean).join('\n\n');
       if (onlyWarnings) {
         process.stdout.write(JSON.stringify({ systemMessage: onlyWarnings }));
       } else {
@@ -394,7 +407,7 @@ try {
         followed: true,
         profile: profileName,
       });
-      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
+      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint, outcomeAdvisory].filter(Boolean).join('\n\n');
       if (onlyWarnings) {
         process.stdout.write(JSON.stringify({ systemMessage: onlyWarnings }));
       } else {

package/hooks/failure-detector.mjs

@@ -12,6 +12,7 @@ import { createHash } from 'crypto';
 import { readFileSync, appendFileSync, writeFileSync, renameSync, unlinkSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { atomicWriteJSON } from './atomic-write.mjs';
 
 
 const __dirname = dirname(fileURLToPath(import.meta.url));

package/hooks/summary-checkpoint.mjs

@@ -17,9 +17,10 @@
  */
 
 import { execSync as _execSync } from 'child_process';
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
+import { atomicWriteJSON } from './atomic-write.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -80,10 +81,9 @@ function emptySummary() {
 
 const COST_PER_CALL = { search: 0.003, execute: 0.012, think: 0.055 };
 
+/** @deprecated Use atomicWriteJSON directly. Kept as re-export for backward compat. */
 function atomicWrite(path, data) {
-  const tmp = path + '.tmp.' + process.pid;
-  writeFileSync(tmp, JSON.stringify(data, null, 2) + '\n');
-  renameSync(tmp, path);
+  atomicWriteJSON(path, data);
 }
 
 function readSummary(date) {

package/hooks/test-orchestrator.mjs

@@ -313,31 +313,116 @@ test('orchestrator.json: dual_thinking configured', () => {
   return true;
 });
 
-// ─── Test 15: profile consistency across modules ────────────────────────────
+// ─── Test 15: profile consistency (behavioral) ─────────────────────────────
 test('profiles: consistent across modules', () => {
-  const profilesSrc = readFileSync(resolve(__dirname, 'profiles.mjs'), 'utf8');
-  const profileNames = ['auto', 'balanced', 'cost-saver', 'quality-first'];
-  for (const name of profileNames) {
-    if (!profilesSrc.includes(`${name}:`) && !profilesSrc.includes(`'${name}':`)) return `profiles.mjs missing: ${name}`;
-  }
+  const script = `
+    import { PROFILES, getActiveProfile } from './profiles.mjs';
+    const results = { errors: [] };
+
+    // 1. All 4 profiles exist
+    const expected = ['auto', 'balanced', 'cost-saver', 'quality-first'];
+    for (const name of expected) {
+      if (!PROFILES[name]) results.errors.push('missing profile: ' + name);
+    }
 
-  const installSrc = readFileSync(resolve(__dirname, '..', 'install.mjs'), 'utf8');
-  for (const name of profileNames) {
-    if (!installSrc.includes(`${name}:`) && !installSrc.includes(`'${name}':`)) return `install.mjs missing profile: ${name}`;
-  }
+    // 2. Each profile has required fields
+    const requiredFields = ['description', 'routing', 'budgets', 'quality_gate'];
+    const routingFields = ['prefer_provider', 'think_threshold', 'gpt_dispatch_bias'];
+    const budgetFields = ['session_warn_usd', 'session_limit_usd', 'daily_warn_usd', 'daily_limit_usd'];
 
-  const enforceSrc = readFileSync(resolve(__dirname, 'enforce-tier.mjs'), 'utf8');
-  if (!enforceSrc.includes('auto:')) return 'enforce-tier.mjs missing auto in PROFILE_SETTINGS';
+    for (const name of expected) {
+      const p = PROFILES[name];
+      if (!p) continue;
+      for (const f of requiredFields) {
+        if (!p[f]) results.errors.push(name + ' missing field: ' + f);
+      }
+      for (const f of routingFields) {
+        if (p.routing[f] === undefined) results.errors.push(name + ' routing missing: ' + f);
+      }
+      for (const f of budgetFields) {
+        if (typeof p.budgets[f] !== 'number' || p.budgets[f] <= 0)
+          results.errors.push(name + ' budget not positive number: ' + f + '=' + p.budgets[f]);
+      }
+    }
 
+    // 3. getActiveProfile returns a valid profile
+    const active = getActiveProfile();
+    if (!active.name) results.errors.push('getActiveProfile missing name');
+    if (!active.routing) results.errors.push('getActiveProfile missing routing');
+    if (!active.budgets) results.errors.push('getActiveProfile missing budgets');
+
+    process.stdout.write(JSON.stringify(results));
+  `;
+  const proc = spawnSync(process.execPath, [
+    '--input-type=module',
+    '-e', script,
+  ], { encoding: 'utf8', timeout: 5000, cwd: HOOKS });
+
+  if (proc.status !== 0) return `profiles script failed: ${proc.stderr}`;
+  let results;
+  try { results = JSON.parse(proc.stdout.trim()); } catch { return `output not JSON: ${proc.stdout}`; }
+  if (results.errors.length > 0) return results.errors.join('; ');
   return true;
 });
 
-// ─── Test 16: failure-detector only counts real failures ─────────────────────
-test('failure-detector: ignores followed=false', () => {
-  const src = readFileSync(resolve(__dirname, 'failure-detector.mjs'), 'utf8');
-  if (src.includes('followed === false')) return 'still conflates followed=false with failure';
-  if (!src.includes('success === false') && !src.includes('success !== false')) return 'missing success check';
-  return true;
+// ─── Test 16: failure-detector API contract (behavioral) ────────────────────
+test('failure-detector: API contract', () => {
+  const LEDGER = resolve(HOOKS, 'decision-ledger.jsonl');
+  const backup = existsSync(LEDGER) ? readFileSync(LEDGER, 'utf8') : null;
+
+  try {
+    // Start with clean ledger
+    writeFileSync(LEDGER, '', 'utf8');
+
+    const script = `
+      import { computePromptHash, checkFailureLoop, recordFailure } from './failure-detector.mjs';
+      const results = { errors: [] };
+
+      // 1. computePromptHash returns 12-char hex string
+      const hash = computePromptHash({ prompt: 'test prompt', description: 'test desc' });
+      if (typeof hash !== 'string') results.errors.push('hash not a string: ' + typeof hash);
+      else if (hash.length !== 12) results.errors.push('hash length not 12: ' + hash.length);
+      else if (!/^[0-9a-f]{12}$/.test(hash)) results.errors.push('hash not hex: ' + hash);
+
+      // 2. checkFailureLoop returns { isLoop, score } shape (before any failures)
+      const check1 = checkFailureLoop(hash);
+      if (typeof check1 !== 'object' || check1 === null) results.errors.push('checkFailureLoop did not return object');
+      else {
+        if (typeof check1.isLoop !== 'boolean' && typeof check1.isLoop !== 'undefined')
+          // isLoop should be boolean
+          results.errors.push('isLoop not boolean: ' + typeof check1.isLoop);
+        if (!('weightedScore' in check1 || 'score' in check1))
+          results.errors.push('checkFailureLoop missing score field');
+      }
+
+      // 3. recordFailure is callable without throwing
+      try {
+        recordFailure(hash, 'execute', 'test_reason');
+      } catch (e) {
+        results.errors.push('recordFailure threw: ' + e.message);
+      }
+
+      // 4. After recording failures, checkFailureLoop detects them
+      recordFailure(hash, 'execute', 'test_reason_2');
+      const check2 = checkFailureLoop(hash);
+      if (check2.count < 2) results.errors.push('expected count >= 2 after 2 recordFailure calls, got: ' + check2.count);
+
+      process.stdout.write(JSON.stringify(results));
+    `;
+    const proc = spawnSync(process.execPath, [
+      '--input-type=module',
+      '-e', script,
+    ], { encoding: 'utf8', timeout: 5000, cwd: HOOKS });
+
+    if (proc.status !== 0) return `failure-detector script failed: ${proc.stderr}`;
+    let results;
+    try { results = JSON.parse(proc.stdout.trim()); } catch { return `output not JSON: ${proc.stdout}`; }
+    if (results.errors.length > 0) return results.errors.join('; ');
+    return true;
+  } finally {
+    if (backup !== null) writeFileSync(LEDGER, backup, 'utf8');
+    else try { writeFileSync(LEDGER, '', 'utf8'); } catch {}
+  }
 });
 
 // ─── Test 17: enforce-tier: malformed stdin ─────────────────────────────────
@@ -642,7 +727,7 @@ test('adaptive: cost-logger records Agent errors', () => {
     let entry;
     try { entry = JSON.parse(newEntry); } catch { return `last line not valid JSON: ${newEntry}`; }
     if (entry.success !== false) return `expected success=false, got: ${entry.success}`;
-    if (entry.type !== 'failure') return `expected type=failure, got: ${entry.type}`;
+    if (entry.type !== 'outcome') return `expected type=outcome, got: ${entry.type}`;
     return true;
   } finally {
     if (backup !== null) writeFileSync(LEDGER, backup, 'utf8');
@@ -799,7 +884,7 @@ test('hooks: output files use dual-brain-namespaced paths', () => {
     const src = readFileSync(resolve(__dirname, hookFile), 'utf8');
 
     // Find all file paths the hook writes to (writeFileSync / appendFileSync targets)
-    const writeTargets = [...src.matchAll(/(?:writeFileSync|appendFileSync|renameSync)\(\s*([^,)]+)/g)].map(m => m[1].trim());
+    const writeTargets = [...src.matchAll(/(?:writeFileSync|appendFileSync|renameSync|atomicWriteJSON)\(\s*([^,)]+)/g)].map(m => m[1].trim());
 
     if (writeTargets.length === 0) return `${hookFile}: no write targets found`;
 

package/install.mjs

@@ -8,7 +8,7 @@
  *   npx dual-brain --dry-run        # detect only, don't install
  *   npx dual-brain --help
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
@@ -55,6 +55,7 @@ if (flag('--help') || flag('-h')) {
     --force      Overwrite all existing config
     --dry-run    Detect environment only
     --json       Output detection as JSON
+    --uninstall  Remove dual-brain hooks and state files
     --help       Show this help
 
   🎛️  Routing modes:
@@ -697,9 +698,130 @@ function cmdExplain() {
   console.log('');
 }
 
+// ─── Uninstall ─────────────────────────────────────────────────────────────
+
+function cmdUninstall() {
+  const workspace = resolve(process.cwd());
+  const claudeDir = join(workspace, '.claude');
+  const hooksDir = join(claudeDir, 'hooks');
+  const actions = [];
+
+  // 1. Remove dual-brain hooks from settings.json
+  const settingsPath = join(claudeDir, 'settings.json');
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const DUAL_BRAIN_CMDS = [
+        'node .claude/hooks/enforce-tier.mjs',
+        'node .claude/hooks/cost-logger.mjs',
+      ];
+
+      if (settings.hooks) {
+        let removedCount = 0;
+        for (const event of Object.keys(settings.hooks)) {
+          const before = settings.hooks[event].length;
+          settings.hooks[event] = settings.hooks[event].filter(entry =>
+            !entry.hooks?.some(h => DUAL_BRAIN_CMDS.includes(h.command))
+          );
+          removedCount += before - settings.hooks[event].length;
+
+          // Clean up empty arrays
+          if (settings.hooks[event].length === 0) {
+            delete settings.hooks[event];
+          }
+        }
+
+        // Clean up empty hooks object
+        if (Object.keys(settings.hooks).length === 0) {
+          delete settings.hooks;
+        }
+
+        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+        if (removedCount > 0) {
+          actions.push(`✓ Removed ${removedCount} hook(s) from settings.json`);
+        } else {
+          actions.push('⊘ No dual-brain hooks found in settings.json');
+        }
+      } else {
+        actions.push('⊘ No hooks section in settings.json');
+      }
+    } catch (err) {
+      actions.push(`⚠ Could not parse settings.json: ${err.message}`);
+    }
+  } else {
+    actions.push('⊘ No settings.json found');
+  }
+
+  // 2. Remove state files
+  const stateFiles = [
+    join(claudeDir, 'dual-brain.profile.json'),
+    join(claudeDir, 'dual-brain.memory.json'),
+    join(claudeDir, '.launched'),
+  ];
+
+  // Add date-stamped usage files and summary files
+  const today = new Date().toISOString().slice(0, 10);
+  stateFiles.push(join(hooksDir, 'usage.jsonl'));
+  stateFiles.push(join(hooksDir, `usage-${today}.jsonl`));
+  stateFiles.push(join(hooksDir, 'decision-ledger.jsonl'));
+  stateFiles.push(join(hooksDir, '.drift-warned'));
+  stateFiles.push(join(hooksDir, '.budget-alerted'));
+
+  // Scan for any usage-*.jsonl and usage-summary-*.json files
+  try {
+    const files = readdirSync(hooksDir);
+    for (const f of files) {
+      if (f.startsWith('usage-') && f.endsWith('.jsonl')) {
+        stateFiles.push(join(hooksDir, f));
+      }
+      if (f.startsWith('usage-summary-') && f.endsWith('.json')) {
+        stateFiles.push(join(hooksDir, f));
+      }
+      if (f === 'burst-state.json' || f === 'failure-ledger.json') {
+        stateFiles.push(join(hooksDir, f));
+      }
+    }
+  } catch {}
+
+  // Deduplicate
+  const uniqueFiles = [...new Set(stateFiles)];
+
+  let removedFiles = 0;
+  for (const f of uniqueFiles) {
+    try {
+      if (existsSync(f)) {
+        unlinkSync(f);
+        removedFiles++;
+      }
+    } catch {}
+  }
+
+  if (removedFiles > 0) {
+    actions.push(`✓ Removed ${removedFiles} state file(s)`);
+  } else {
+    actions.push('⊘ No state files to remove');
+  }
+
+  // 3. Print summary
+  console.log('');
+  console.log(`  🧠 dual-brain v${VERSION} — uninstall`);
+  console.log('  ' + '─'.repeat(40));
+  for (const a of actions) {
+    console.log(`  ${a}`);
+  }
+  console.log('');
+  console.log('  Hook scripts in .claude/hooks/ were left in place');
+  console.log('  (they are part of the npm package, not your repo).');
+  console.log('');
+  console.log('  To reinstall: npx -y dual-brain');
+  console.log('');
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 function main() {
+  if (flag('--uninstall')) { cmdUninstall(); return; }
+
   if (subcommand === 'status') {
     launchPanel();
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Dual-provider orchestration for Claude Code — tiered routing, budget balancing, and GPT dual-brain review across Claude + OpenAI subscriptions",
   "type": "module",
   "bin": {