dual-brain 4.0.1 → 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/quality-gate.mjs

@@ -30,6 +30,40 @@ const DUAL_BRAIN = resolve(__dirname, 'dual-brain-review.mjs');
 
 const RISK_LEVELS = ['low', 'medium', 'high', 'critical'];
 
+const APPROVAL_MAP = {
+  low:      { recommendation: 'self_check',           message: 'Low risk — self-check is sufficient' },
+  medium:   { recommendation: 'review_recommended',   message: 'Medium risk — a code review would catch edge cases' },
+  high:     { recommendation: 'dual_brain_review',    message: 'High risk — recommending dual-brain review for safety' },
+  critical: { recommendation: 'user_approval_needed', message: 'Critical risk — this needs your explicit approval before merging' },
+};
+
+/**
+ * Compute approval recommendation from risk level + profile overrides.
+ * Profile escalation: if dual_brain_minimum is at or below the current risk,
+ * escalate the recommendation by one tier (e.g. medium → dual_brain_review
+ * under quality-first where dual_brain_minimum is 'medium').
+ */
+function computeApproval(risk, profileGate) {
+  let effectiveRisk = risk;
+
+  // Profile escalation: when dual_brain_minimum <= risk and the base
+  // recommendation would be below dual_brain_review, escalate one level.
+  const riskIdx = RISK_LEVELS.indexOf(risk);
+  const dualBrainIdx = RISK_LEVELS.indexOf(profileGate.dual_brain_minimum);
+  if (dualBrainIdx >= 0 && riskIdx >= dualBrainIdx && riskIdx < RISK_LEVELS.length - 1) {
+    const baseRec = APPROVAL_MAP[risk].recommendation;
+    if (baseRec !== 'dual_brain_review' && baseRec !== 'user_approval_needed') {
+      effectiveRisk = RISK_LEVELS[riskIdx + 1];
+    }
+  }
+
+  const entry = APPROVAL_MAP[effectiveRisk] || APPROVAL_MAP[risk];
+  return {
+    approval_recommendation: entry.recommendation,
+    approval_message: entry.message,
+  };
+}
+
 function loadProfileGateSettings() {
   try {
     return _getProfileOverrides('quality-gate');
@@ -189,6 +223,7 @@ function main() {
       reason: `${sensitivity.risk} risk — below profile floor (${profileGate.sensitivity_floor})`,
       profile_floor: profileGate.sensitivity_floor,
       files: qualifyingFiles,
+      ...computeApproval(sensitivity.risk, profileGate),
     });
   }
 
@@ -267,6 +302,7 @@ function main() {
   }
 
   // 9. Build output object — common fields first
+  const approval = computeApproval(sensitivity.risk, profileGate);
   const output = {
     gate: gateStatus,
     risk: sensitivity.risk,
@@ -278,6 +314,8 @@ function main() {
     review_path: reviewFile,
     model: reviewResult.model || null,
     auth_type: reviewResult.auth_type || null,
+    approval_recommendation: approval.approval_recommendation,
+    approval_message: approval.approval_message,
   };
 
   // High risk: recommend dual-brain-think in addition

package/hooks/summary-checkpoint.mjs

@@ -16,9 +16,11 @@
  *   getTokenAverages()           → moving averages of actual tokens by tier
  */
 
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { execSync as _execSync } from 'child_process';
+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));
 
@@ -65,15 +67,23 @@ function emptySummary() {
       dual_brain_useful: false,
       balance_posture: 'no activity yet',
     },
+
+    // Session handoff fields — enriched checkpoint for cross-session continuity
+    session_handoff: {
+      gate_passed: [],              // completed milestones/tasks this session
+      evidence: [],                 // concrete evidence: commit hashes, file paths, PR URLs
+      pickup_prompt: 'none recorded', // one-sentence continuation prompt
+      friction: [],                 // problems encountered during the session
+      cross_workstream_patterns: [], // generalizable lessons beyond this task
+    },
   };
 }
 
 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) {
@@ -158,6 +168,57 @@ function applyEntry(summary, entry) {
     avg.avg_output += (entry.output_tokens - avg.avg_output) / avg.count;
   }
 
+  // Session handoff: auto-populate from entry metadata
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  // Track completed gates/milestones from quality-gate or review results
+  if (entry.type === 'gate_result' && entry.gate === 'pass') {
+    summary.session_handoff.gate_passed.push({
+      what: entry.reason || 'quality gate passed',
+      ts,
+    });
+  }
+
+  // Track evidence: file paths from execute-tier entries, commit hashes, PR URLs
+  if (tier === 'execute' && entry.files_changed) {
+    const files = Array.isArray(entry.files_changed) ? entry.files_changed : [entry.files_changed];
+    for (const f of files) {
+      if (!summary.session_handoff.evidence.includes(f)) {
+        summary.session_handoff.evidence.push(f);
+      }
+    }
+  }
+  if (entry.commit_hash) {
+    const ref = `commit:${entry.commit_hash}`;
+    if (!summary.session_handoff.evidence.includes(ref)) {
+      summary.session_handoff.evidence.push(ref);
+    }
+  }
+  if (entry.pr_url) {
+    if (!summary.session_handoff.evidence.includes(entry.pr_url)) {
+      summary.session_handoff.evidence.push(entry.pr_url);
+    }
+  }
+
+  // Track friction: failures, escalations, retries
+  if (entry.type === 'failure' || entry.escalated || entry.retry) {
+    summary.session_handoff.friction.push({
+      what: entry.error || entry.reason || 'unknown failure',
+      tier,
+      provider,
+      ts,
+    });
+    // Keep friction list bounded
+    if (summary.session_handoff.friction.length > 50) {
+      summary.session_handoff.friction = summary.session_handoff.friction.slice(-50);
+    }
+  }
+
   // Codex latencies
   if (entry.codex_startup_ms != null) {
     summary.codex_latencies.push({
@@ -237,6 +298,125 @@ function getAdaptiveCodexThreshold(date) {
   };
 }
 
+/**
+ * Update a specific session handoff field.
+ * Valid keys: gate_passed, evidence, pickup_prompt, friction, cross_workstream_patterns
+ *
+ * For array fields, `value` is appended (string or object).
+ * For pickup_prompt, `value` replaces the current string.
+ */
+function updateHandoff(key, value, date) {
+  const arrayFields = ['gate_passed', 'evidence', 'friction', 'cross_workstream_patterns'];
+  const validKeys = [...arrayFields, 'pickup_prompt'];
+  if (!validKeys.includes(key)) return;
+
+  const summary = readSummary(date);
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  if (key === 'pickup_prompt') {
+    summary.session_handoff.pickup_prompt = String(value);
+  } else if (arrayFields.includes(key)) {
+    if (!Array.isArray(summary.session_handoff[key])) {
+      summary.session_handoff[key] = [];
+    }
+    summary.session_handoff[key].push(value);
+  }
+
+  summary.updated_at = new Date().toISOString();
+  atomicWrite(summaryPath(date), summary);
+  return summary;
+}
+
+/**
+ * Generate a full session checkpoint for handoff.
+ *
+ * Auto-enriches evidence from git state (changed files, HEAD commit)
+ * and builds a pickup prompt if none was set manually.
+ */
+function generateCheckpoint(date) {
+  const summary = readSummary(date);
+
+  if (!summary.session_handoff) {
+    summary.session_handoff = {
+      gate_passed: [], evidence: [], pickup_prompt: 'none recorded',
+      friction: [], cross_workstream_patterns: [],
+    };
+  }
+
+  const handoff = summary.session_handoff;
+
+  // Auto-enrich evidence from git if available
+  try {
+    // Current HEAD commit
+    const head = _execSync('git rev-parse --short HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (head) {
+      const ref = `commit:${head}`;
+      if (!handoff.evidence.includes(ref)) {
+        handoff.evidence.push(ref);
+      }
+    }
+
+    // Changed files in working tree
+    const diff = _execSync('git diff --name-only HEAD 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (diff) {
+      for (const f of diff.split('\n').filter(Boolean)) {
+        const ref = `changed:${f}`;
+        if (!handoff.evidence.includes(ref)) {
+          handoff.evidence.push(ref);
+        }
+      }
+    }
+
+    // Current branch
+    const branch = _execSync('git branch --show-current 2>/dev/null', { encoding: 'utf8' }).trim();
+    if (branch) {
+      handoff.evidence.push(`branch:${branch}`);
+    }
+  } catch {
+    // Git not available — skip enrichment
+  }
+
+  // Auto-generate pickup_prompt if not manually set
+  if (handoff.pickup_prompt === 'none recorded' && summary.totals.calls > 0) {
+    const topTier = Object.entries(summary.totals.by_tier)
+      .sort(([, a], [, b]) => b - a)[0];
+    const tierLabel = topTier ? topTier[0] : 'mixed';
+    const fileCount = handoff.evidence.filter(e => e.startsWith('changed:')).length;
+    const frictionCount = handoff.friction.length;
+
+    let prompt = `Session had ${summary.totals.calls} calls (mostly ${tierLabel})`;
+    if (fileCount > 0) prompt += `, ${fileCount} files modified`;
+    if (frictionCount > 0) prompt += `, ${frictionCount} friction points to review`;
+    prompt += '.';
+    handoff.pickup_prompt = prompt;
+  }
+
+  // Build the checkpoint object
+  const checkpoint = {
+    version: 1,
+    generated_at: new Date().toISOString(),
+    date: summary.date,
+
+    // Existing summary data
+    totals: summary.totals,
+    session_insights: summary.session_insights,
+
+    // New handoff fields
+    gate_passed: handoff.gate_passed,
+    evidence: handoff.evidence,
+    pickup_prompt: handoff.pickup_prompt,
+    friction: handoff.friction,
+    cross_workstream_patterns: handoff.cross_workstream_patterns,
+  };
+
+  return checkpoint;
+}
+
 export {
   readSummary,
   updateSummary,
@@ -246,5 +426,7 @@ export {
   getTokenAverages,
   getAdaptiveCodexThreshold,
   updateSessionInsight,
+  updateHandoff,
+  generateCheckpoint,
   atomicWrite,
 };

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/hooks/vibe-router.mjs

@@ -140,6 +140,46 @@ function determineQualityGates(tasks) {
   return [...gates];
 }
 
+// ─── Ordered Language Detection ───────────────────────────────────────────
+
+const DEPENDENCY_MARKERS = /\b(then|after\s+that|once\s+\S+\s+is\s+done|before|first|next|finally|afterwards|subsequently|followed\s+by|depends?\s+on|requires?)\b/i;
+
+// ─── Subsystem Detection ─────────────────────────────────────────────────
+
+const SUBSYSTEM_PATTERNS = [
+  { key: 'auth', regex: /\b(auth|login|sign[-\s]?in|sign[-\s]?up|session|credential|password|oauth|jwt|token)\b/i },
+  { key: 'billing', regex: /\b(billing|payment|subscription|invoice|charge|stripe|pricing)\b/i },
+  { key: 'api', regex: /\b(api|endpoint|route|controller|handler|middleware|rest|graphql)\b/i },
+  { key: 'ui', regex: /\b(ui|nav|button|page|component|layout|style|css|modal|form|menu|sidebar|header|footer|dashboard)\b/i },
+  { key: 'db', regex: /\b(database|db|schema|migration|model|query|table|column|index|sql|prisma|sequelize|knex)\b/i },
+  { key: 'infra', regex: /\b(deploy|ci|cd|docker|k8s|terraform|infra|pipeline|build|config|env)\b/i },
+  { key: 'test', regex: /\b(test|spec|fixture|mock|stub|assert|coverage)\b/i },
+  { key: 'docs', regex: /\b(doc|readme|changelog|guide|tutorial|comment)\b/i },
+];
+
+function detectSubsystems(text) {
+  const subs = new Set();
+  for (const pat of SUBSYSTEM_PATTERNS) {
+    if (pat.regex.test(text)) subs.add(pat.key);
+  }
+  return subs;
+}
+
+// ─── Risk Domain Extraction ──────────────────────────────────────────────
+
+function getRiskDomains(task) {
+  const domains = new Set();
+  // Use subsystem as risk domain
+  const subs = detectSubsystems(task.title);
+  for (const s of subs) domains.add(s);
+  // Also include explicit risk reason label
+  if (task.reason) {
+    const match = task.reason.match(/^([^(]+)/);
+    if (match) domains.add(match[1].trim().toLowerCase());
+  }
+  return domains;
+}
+
 // ─── Complexity + Wave Recommendation ──────────────────────────────────────
 
 function determineComplexity(tasks) {
@@ -157,18 +197,102 @@ function determineComplexity(tasks) {
   return 'simple';
 }
 
-function determineWave(tasks, complexity) {
-  if (tasks.length === 1) return 'single';
+/**
+ * determineWave — Sequential by default, parallel only when tasks are truly independent.
+ *
+ * Returns { wave, reasons } where reasons is an array of reason codes:
+ *   shared_surface  — tasks likely touch same files
+ *   high_risk       — risky work should be sequential for review
+ *   dependency_marker — ordered language detected in utterance
+ *   same_subsystem  — tasks in same domain/subsystem
+ *   independent     — truly independent, safe for parallel
+ */
+function determineWave(tasks, complexity, utterance) {
+  if (tasks.length === 1) return { wave: 'single', reasons: [] };
+
+  const reasons = [];
+
+  // 1. Check for ordered language in the original utterance
+  if (utterance && DEPENDENCY_MARKERS.test(utterance)) {
+    reasons.push('dependency_marker');
+  }
 
-  // If any task depends on another (sequential markers like "then", "after that"
-  // were used), we already split them but keep sequential recommendation.
-  // For now, check if tasks share the same tier — parallel is fine for independent work.
-  const tiers = new Set(tasks.map(t => t.tier));
+  // 2. Check for high/critical risk tasks
   const hasHighRisk = tasks.some(t => t.risk === 'high' || t.risk === 'critical');
+  if (hasHighRisk) {
+    reasons.push('high_risk');
+  }
+
+  // 3. Check for overlapping subsystems between tasks
+  const taskSubsystems = tasks.map(t => detectSubsystems(t.title));
+  let hasSharedSubsystem = false;
+  for (let i = 0; i < taskSubsystems.length; i++) {
+    for (let j = i + 1; j < taskSubsystems.length; j++) {
+      for (const sub of taskSubsystems[i]) {
+        if (taskSubsystems[j].has(sub)) {
+          hasSharedSubsystem = true;
+          break;
+        }
+      }
+      if (hasSharedSubsystem) break;
+    }
+    if (hasSharedSubsystem) break;
+  }
+  if (hasSharedSubsystem) {
+    reasons.push('same_subsystem');
+  }
+
+  // 4. Check for overlapping file paths / shared surface area
+  const taskPaths = tasks.map(t => extractPaths(t.title));
+  let hasSharedPaths = false;
+  for (let i = 0; i < taskPaths.length; i++) {
+    for (let j = i + 1; j < taskPaths.length; j++) {
+      for (const p of taskPaths[i]) {
+        // Check if any path from task j shares a directory prefix or exact match
+        for (const q of taskPaths[j]) {
+          if (p === q || p.startsWith(q + '/') || q.startsWith(p + '/') ||
+              p.split('/').slice(0, -1).join('/') === q.split('/').slice(0, -1).join('/')) {
+            hasSharedPaths = true;
+            break;
+          }
+        }
+        if (hasSharedPaths) break;
+      }
+      if (hasSharedPaths) break;
+    }
+    if (hasSharedPaths) break;
+  }
+  if (hasSharedPaths) {
+    reasons.push('shared_surface');
+  }
+
+  // 5. Check for shared risk domains
+  const taskDomains = tasks.map(t => getRiskDomains(t));
+  let hasSharedDomain = false;
+  for (let i = 0; i < taskDomains.length; i++) {
+    for (let j = i + 1; j < taskDomains.length; j++) {
+      for (const d of taskDomains[i]) {
+        if (taskDomains[j].has(d)) {
+          hasSharedDomain = true;
+          break;
+        }
+      }
+      if (hasSharedDomain) break;
+    }
+    if (hasSharedDomain) break;
+  }
+  // Only add same_subsystem if not already added (risk domains overlap with subsystems)
+  if (hasSharedDomain && !reasons.includes('same_subsystem')) {
+    reasons.push('same_subsystem');
+  }
+
+  // Decision: parallel ONLY when no sequential reasons found
+  if (reasons.length === 0) {
+    reasons.push('independent');
+    return { wave: 'parallel', reasons };
+  }
 
-  if (hasHighRisk) return 'sequential'; // high-risk tasks need careful ordering
-  if (tiers.size === 1 && complexity !== 'complex') return 'parallel';
-  return 'parallel';
+  return { wave: 'sequential', reasons };
 }
 
 // ─── Summary Generation ────────────────────────────────────────────────────
@@ -229,7 +353,7 @@ function routeVibe(utterance) {
   const profileHint = detectProfileHint(utterance);
   const qualityGates = determineQualityGates(tasks);
   const complexity = determineComplexity(tasks);
-  const wave = determineWave(tasks, complexity);
+  const { wave, reasons } = determineWave(tasks, complexity, utterance);
   const summary = generateSummary(tasks, complexity, wave, qualityGates, profileHint);
 
   return {
@@ -238,6 +362,7 @@ function routeVibe(utterance) {
     profile_hint: profileHint,
     quality_gates: qualityGates,
     wave_recommendation: wave,
+    wave_reasons: reasons,
     summary,
   };
 }

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.0.1",
+  "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": {