dual-brain 4.8.0 → 5.0.0

package/CLAUDE.md

@@ -43,6 +43,25 @@ Dual-brain is a multi-round conversation between Claude and GPT — not a single
 3. High-risk decisions → dual-brain think
 4. When a task spans tiers: think > execute > search
 
+## Mandatory Workload Distribution
+
+**Claude MUST follow these rules before implementing multi-file changes:**
+
+1. **Before starting any batch of 3+ file edits**: run `node .claude/hooks/budget-balancer.mjs` and `node .claude/hooks/vibe-router.mjs "description"` to check provider balance and classify tasks
+2. **When budget-balancer recommends GPT**: dispatch execution work via `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`
+3. **Security/auth/credential changes**: always require dual-brain think flow before implementation
+4. **Audit remediation batches**: plan waves with dual-brain think, dispatch execution to GPT, Claude reviews
+5. **Claude's role in multi-task work**: define acceptance criteria, dispatch agents, review results — not solo-implement everything
+
+**Triggers that require this workflow:**
+- 3+ production files being edited in one session
+- Any change touching auth, credentials, tokens, or secrets
+- Any change to dispatcher, agent routing, or tier logic
+- Audit or review remediation involving multiple subsystems
+- When Claude's think capacity is above 60% per budget-balancer
+
+**Failure to route is itself a bug.** If Claude implements a large batch solo when GPT has capacity, the user should treat this as a process failure and correct it.
+
 ## Quality Gate
 
 Before ending a session with code changes:

package/hooks/control-panel.mjs

@@ -15,6 +15,7 @@ import { spawnSync } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PROFILE_FILE = join(__dirname, '..', 'dual-brain.profile.json');
+const PERMISSIONS_FILE = join(__dirname, '..', 'dual-brain.permissions.json');
 const LAUNCHED_MARKER = join(__dirname, '..', '.launched');
 const VERSION_STAMP_FILE = join(__dirname, '..', 'dual-brain.version.json');
 const UPDATE_CACHE_FILE = join(__dirname, '..', 'dual-brain.update-check.json');
@@ -56,6 +57,32 @@ function writeJsonFile(path, value) {
   writeFileSync(path, JSON.stringify(value, null, 2) + '\n');
 }
 
+function loadPermissions() {
+  const defaults = {
+    claude_skip_permissions: false,
+    codex_bypass_sandbox: false,
+  };
+  try {
+    const data = JSON.parse(readFileSync(PERMISSIONS_FILE, 'utf8'));
+    return {
+      claude_skip_permissions: !!data.claude_skip_permissions,
+      codex_bypass_sandbox: !!data.codex_bypass_sandbox,
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+function savePermissions(perms) {
+  const next = {
+    claude_skip_permissions: !!perms.claude_skip_permissions,
+    codex_bypass_sandbox: !!perms.codex_bypass_sandbox,
+  };
+  const tmp = PERMISSIONS_FILE + '.tmp.' + process.pid;
+  writeFileSync(tmp, JSON.stringify(next, null, 2) + '\n');
+  renameSync(tmp, PERMISSIONS_FILE);
+}
+
 function compareVersions(a, b) {
   const aParts = String(a || '').replace(/^v/i, '').split('.').map(n => parseInt(n, 10) || 0);
   const bParts = String(b || '').replace(/^v/i, '').split('.').map(n => parseInt(n, 10) || 0);
@@ -468,8 +495,14 @@ async function showAuthMenu(rl, providers) {
 
     if (choice === 'j') {
       console.log('');
-      spawnSync('claude', ['login'], { stdio: 'inherit' });
-      providers.claude.authed = true;
+      const r = spawnSync('claude', ['login'], { stdio: 'inherit' });
+      const fresh = detectProviders();
+      providers.claude = fresh.claude;
+      if (providers.claude.authed) {
+        console.log(`  ${green('Claude authenticated.')}`);
+      } else {
+        console.log(`  ${yellow('Claude login did not complete.')} Try again or check your subscription.`);
+      }
       continue;
     }
     if (choice === 'k' && providers.codex.installed) {
@@ -479,7 +512,13 @@ async function showAuthMenu(rl, providers) {
         console.log(`  Open: ${cyan('https://auth.openai.com/codex/device')}`);
         console.log('');
         spawnSync(codexPath.stdout.trim(), ['login', '--device-auth'], { stdio: 'inherit' });
-        providers.codex.authed = true;
+        const fresh = detectProviders();
+        providers.codex = fresh.codex;
+        if (providers.codex.authed) {
+          console.log(`  ${green('Codex authenticated.')}`);
+        } else {
+          console.log(`  ${yellow('Codex login did not complete.')} Try again.`);
+        }
       }
       continue;
     }
@@ -623,9 +662,9 @@ function renderFirstRunMenu(providers) {
   lines.push('');
 
   // Provider status
-  const cStat = providers.claude.authed ? '✅' : providers.claude.installed ? '⚠️' : '❌';
-  const xStat = providers.codex.authed ? '✅' : providers.codex.installed ? '⚠️' : '❌';
-  lines.push(`  🟠 Claude ${cStat}  🟢 Codex ${xStat}`);
+  const cStat = providers.claude.authed ? (noColor ? '[OK]' : '✅') : providers.claude.installed ? (noColor ? '[!]' : '⚠️') : (noColor ? '[X]' : '❌');
+  const xStat = providers.codex.authed ? (noColor ? '[OK]' : '✅') : providers.codex.installed ? (noColor ? '[!]' : '⚠️') : (noColor ? '[X]' : '❌');
+  lines.push(`  ${noColor ? '' : '🟠 '}Claude ${cStat}  ${noColor ? '' : '🟢 '}Codex ${xStat}`);
 
   if (providers.claude.authed && providers.codex.authed) {
     lines.push(`  ${green('Both providers ready — full dual-brain mode')}`);
@@ -667,7 +706,8 @@ function renderFirstRunMenu(providers) {
   lines.push(`  ${bold('[a]')} Auth management`);
   lines.push(`  ${bold('[d]')} Dashboard & diagnostics`);
   lines.push(`  ${bold('[s]')} Skip — just shell`);
-  lines.push(`  ${bold('[?]')} What is Dual Brain?`);
+  lines.push(`  ${dim('Enter = new session · [?] help')}`);
+
   lines.push('');
 
   return lines;
@@ -675,6 +715,7 @@ function renderFirstRunMenu(providers) {
 
 function renderReturningMenu(providers, sessions) {
   const profile = loadProfile();
+  const permissions = loadPermissions();
   const pf = PROFILES[profile.name];
   const running = countRunning();
   const balance = loadProviderBalance();
@@ -688,8 +729,8 @@ function renderReturningMenu(providers, sessions) {
   lines.push('');
 
   // Provider status
-  const cStat = providers.claude.authed ? '✅' : '⚠️';
-  const xStat = providers.codex.authed ? '✅' : providers.codex.installed ? '⚠️' : '❌';
+  const cStat = providers.claude.authed ? (noColor ? '[OK]' : '✅') : (noColor ? '[!]' : '⚠️');
+  const xStat = providers.codex.authed ? (noColor ? '[OK]' : '✅') : providers.codex.installed ? (noColor ? '[!]' : '⚠️') : (noColor ? '[X]' : '❌');
   let modeStatus = pf.uiLabel;
   if (profile.name === 'auto') {
     if (balance.total === 0) {
@@ -739,6 +780,7 @@ function renderReturningMenu(providers, sessions) {
   lines.push(`  ${dim('─── Settings')}`);
   lines.push(`  ${bold('[p]')} Mode: ${dim(pf.uiLabel)}`);
   lines.push(`  ${bold('[b]')} Budget: ${dim('$' + profile.budgets.session_limit_usd + '/session, $' + profile.budgets.daily_limit_usd + '/day')}`);
+  lines.push(`  ${bold('[x]')} Permissions: ${dim(permissions.claude_skip_permissions || permissions.codex_bypass_sandbox ? 'skip-permissions enabled' : 'safe mode')}`);
 
   // ── Auth
   lines.push('');
@@ -762,7 +804,12 @@ function renderReturningMenu(providers, sessions) {
   }
 
   lines.push('');
-  lines.push(`  ${bold('[s]')} Exit to shell  ${dim('[?] help')}`);
+  lines.push(`  ${bold('[s]')} Exit to shell`);
+  if (sessions.length > 0) {
+    lines.push(`  ${dim('Enter = continue last · [?] help')}`);
+  } else {
+    lines.push(`  ${dim('Enter = new session · [?] help')}`);
+  }
   lines.push('');
 
   return lines;
@@ -835,13 +882,25 @@ function showProfilePicker(rl) {
 // ─── Session Runner ───────────────────────────────────────────────────────
 
 function runSession(cmd, args, label) {
+  const permissions = loadPermissions();
+  const finalArgs = [...args];
+  if (cmd === 'claude' && permissions.claude_skip_permissions) {
+    finalArgs.push('--dangerously-skip-permissions');
+  }
+  if (cmd === 'codex' && permissions.codex_bypass_sandbox) {
+    finalArgs.push('--dangerously-bypass-approvals-and-sandbox');
+  }
+
   console.log('');
   console.log(`  ${label}`);
   console.log(`  ${dim('Inside Claude: press Ctrl+C twice to return here.')}`);
   console.log('');
   markLaunched();
-  const result = spawnSync(cmd, args, { stdio: 'inherit' });
+  const result = spawnSync(cmd, finalArgs, { stdio: 'inherit' });
   console.log('');
+  if (result.status !== 0 && result.status !== null) {
+    console.log(`  ${yellow('Session exited with code ' + result.status + '.')} ${dim('(' + cmd + ' ' + finalArgs.join(' ') + ')')}`);
+  }
   console.log('  Returned to Data Tools — Dual Brain.');
   return result.status || 0;
 }
@@ -875,12 +934,21 @@ async function mainLoop() {
       if (sessions.length > 0) {
         const s = sessions[0];
         if (s.tool === 'codex') {
-          runSession('codex', ['--dangerously-bypass-approvals-and-sandbox', 'resume', s.id], `Resuming codex ${s.id.slice(0, 8)}...`);
+          runSession('codex', ['resume', s.id], `Resuming codex ${s.id.slice(0, 8)}...`);
         } else {
-          runSession('claude', ['-r', s.id, '--dangerously-skip-permissions'], `Resuming session ${s.id.slice(0, 8)}...`);
+          runSession('claude', ['-r', s.id], `Resuming session ${s.id.slice(0, 8)}...`);
         }
+      } else if (!providers.claude.authed && !providers.claude.installed) {
+        console.log('');
+        console.log(`  ${yellow('Claude is not installed.')} Install first:`);
+        console.log(`  ${cyan('curl -fsSL https://claude.ai/install.sh | sh')}`);
+        console.log('');
+      } else if (!providers.claude.authed) {
+        console.log('');
+        console.log(`  ${yellow('Claude is not authenticated.')} Press ${bold('[j]')} to sign in first.`);
+        console.log('');
       } else {
-        runSession('claude', ['--dangerously-skip-permissions'], 'Starting new session...');
+        runSession('claude', [], 'Starting new session...');
       }
       continue;
     }
@@ -889,15 +957,21 @@ async function mainLoop() {
     if (num >= 1 && num <= 9 && sessions[num - 1]) {
       const s = sessions[num - 1];
       if (s.tool === 'codex') {
-        runSession('codex', ['--dangerously-bypass-approvals-and-sandbox', 'resume', s.id], `Resuming codex ${s.id.slice(0, 8)}...`);
+        runSession('codex', ['resume', s.id], `Resuming codex ${s.id.slice(0, 8)}...`);
       } else {
-        runSession('claude', ['-r', s.id, '--dangerously-skip-permissions'], `Resuming session ${s.id.slice(0, 8)}...`);
+        runSession('claude', ['-r', s.id], `Resuming session ${s.id.slice(0, 8)}...`);
       }
       continue;
     }
 
     if (choice === 'n') {
-      runSession('claude', ['--dangerously-skip-permissions'], 'Starting new session...');
+      if (!providers.claude.authed) {
+        console.log('');
+        console.log(`  ${yellow('Claude needs to be authenticated first.')} Press ${bold('[j]')} to sign in.`);
+        console.log('');
+      } else {
+        runSession('claude', [], 'Starting new session...');
+      }
       continue;
     }
 
@@ -916,6 +990,34 @@ async function mainLoop() {
       continue;
     }
 
+    if (choice === 'x' && !firstRun) {
+      const permissions = loadPermissions();
+      if (permissions.claude_skip_permissions || permissions.codex_bypass_sandbox) {
+        savePermissions({
+          claude_skip_permissions: false,
+          codex_bypass_sandbox: false,
+        });
+        console.log('');
+        console.log(`  ${green('Permissions set to safe mode.')}`);
+        console.log('');
+        continue;
+      }
+
+      console.log('');
+      const confirm = await new Promise(resolve => rl.question('  WARNING: This enables skip-permissions mode for Claude sessions. Type YES to confirm: ', resolve));
+      if (confirm.trim() === 'YES') {
+        savePermissions({
+          claude_skip_permissions: true,
+          codex_bypass_sandbox: true,
+        });
+        console.log(`  ${yellow('Skip-permissions mode enabled for Claude and Codex sessions.')}`);
+      } else {
+        console.log('  No changes made. Safe mode remains enabled.');
+      }
+      console.log('');
+      continue;
+    }
+
     if (choice === 'd') {
       await showToolsMenu(rl);
       continue;
@@ -923,9 +1025,14 @@ async function mainLoop() {
 
     if (choice === 'u') {
       console.log('');
-      console.log('  Updating dual-brain...');
+      console.log('  Updating Dual Brain...');
       console.log('');
-      spawnSync('npx', ['-y', 'dual-brain', 'update'], { stdio: 'inherit', cwd: CWD });
+      const upd = spawnSync('npx', ['-y', 'dual-brain', 'update'], { stdio: 'inherit', cwd: CWD });
+      if (upd.status !== 0) {
+        console.log('');
+        console.log(`  ${yellow('Update failed (exit ' + upd.status + ').')} Try manually: ${cyan('npx -y dual-brain@latest')}`);
+        console.log('');
+      }
       continue;
     }
 

package/hooks/dual-brain-review.mjs

@@ -18,6 +18,8 @@ import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const IS_REPLIT = !!(process.env.REPL_ID || process.env.REPL_SLUG);
+const SANDBOX = IS_REPLIT ? 'danger-full-access' : 'read-only';
 
 const REVIEW_PROMPT_R1 = `You are GPT-5.5 performing Round 1 of a dual-brain code review.
 Claude (Opus) will independently review the same changes, then send you their findings
@@ -189,7 +191,7 @@ function tryCodexReview(diff, { round = 1, claudeReview = null } = {}) {
     const proc = spawnSync(CODEX_BIN, [
       'exec', '--json', '--ephemeral',
       '-c', `model="${model}"`,
-      '-s', 'danger-full-access',
+      '-s', SANDBOX,
       fullPrompt,
     ], {
       input: truncated,

package/hooks/dual-brain-think.mjs

@@ -25,6 +25,8 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const IS_REPLIT = !!(process.env.REPL_ID || process.env.REPL_SLUG);
+const SANDBOX = IS_REPLIT ? 'danger-full-access' : 'read-only';
 
 const CODEX_TIMEOUT_MS = 120_000;
 const MODEL = 'gpt-5.5';
@@ -118,7 +120,7 @@ function runGptAnalysis(codexBin, prompt) {
   const proc = spawnSync(codexBin, [
     'exec', '--json', '--ephemeral',
     '-m', MODEL,
-    '-s', 'danger-full-access',
+    '-s', SANDBOX,
     prompt,
   ], {
     encoding: 'utf8',

package/hooks/enforce-tier.mjs

@@ -14,10 +14,14 @@ const BURST_FILE = resolve(__dirname, '.burst-state');
 function detectBurst() {
   const now = Date.now();
   let state = { count: 0, window_start: now };
-  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 {
+    try { state = JSON.parse(readFileSync(BURST_FILE, 'utf8')); } catch {}
+    if (now - state.window_start > 90_000) state = { count: 0, window_start: now };
+    state.count++;
+    const tmp = BURST_FILE + '.tmp.' + process.pid;
+    writeFileSync(tmp, JSON.stringify(state));
+    renameSync(tmp, BURST_FILE);
+  } catch {}
   return state.count >= 3;
 }
 

package/hooks/gpt-work-dispatcher.mjs

@@ -27,11 +27,10 @@ const CONFIG_FILE = join(__dirname, '..', 'orchestrator.json');
 const EXECUTE_WORDS = /\b(edit|write|fix|implement|modify|refactor|delete|commit|test|build|run|add|update|create)\b/i;
 const SEARCH_WORDS = /\b(explore|search|find|grep|locate|list\s+files|read[-\s]?only|lookup|scan)\b/i;
 const THINK_WORDS = /\b(plan|design|architect|review|audit|security|code[-\s]?review|threat[-\s]?model|complex[-\s]?debug)\b/i;
-const GPT_TIER_SANDBOX = {
-  search: 'read-only',
-  execute: 'danger-full-access',
-  think: 'read-only',
-};
+const IS_REPLIT = !!(process.env.REPL_ID || process.env.REPL_SLUG);
+const GPT_TIER_SANDBOX = IS_REPLIT
+  ? { search: 'danger-full-access', execute: 'danger-full-access', think: 'danger-full-access' }
+  : { search: 'read-only', execute: 'danger-full-access', think: 'read-only' };
 const GPT_TIER_PROMPTS = {
   search: 'You are a READ-ONLY search agent. Do NOT edit files.',
   execute: 'You are an execution agent. Edit files directly.',
@@ -145,10 +144,31 @@ Own this task completely.
 // Codex executor
 // ---------------------------------------------------------------------------
 
-function executeCodex(codexBin, model, prompt, cwd, timeoutMs, sandbox = 'danger-full-access') {
-  const startTime = Date.now();
+function classifyCodexFailure(proc) {
+  let failureType = null;
+
+  if (proc.error?.code === 'ETIMEDOUT') {
+    failureType = 'timeout';
+  } else if (proc.error?.code === 'ENOENT') {
+    failureType = 'not_found';
+  } else if (proc.error) {
+    failureType = 'spawn_error';
+  }
+
+  const stderr = (proc.stderr || '').toLowerCase();
+  if (stderr.includes('unauthorized') || stderr.includes('401') || stderr.includes('not logged in')) {
+    failureType = 'auth';
+  } else if (stderr.includes('rate limit') || stderr.includes('429') || stderr.includes('too many')) {
+    failureType = 'rate_limit';
+  } else if (stderr.includes('timeout') || stderr.includes('timed out')) {
+    failureType = 'timeout';
+  }
 
-  const proc = spawnSync(codexBin, [
+  return failureType;
+}
+
+function runCodexExec(codexBin, model, prompt, cwd, timeoutMs, sandbox) {
+  return spawnSync(codexBin, [
     'exec', '--json', '--ephemeral',
     '-m', model,
     '-s', sandbox,
@@ -159,48 +179,82 @@ function executeCodex(codexBin, model, prompt, cwd, timeoutMs, sandbox = 'danger
     timeout: timeoutMs || 120000,
     cwd: cwd || process.cwd(),
   });
+}
+
+function executeCodex(codexBin, model, prompt, cwd, timeoutMs, sandbox = 'danger-full-access') {
+  const startTime = Date.now();
+
+  function finalizeAttempt(proc, attemptStartTime, attemptCount) {
+    const durationMs = Date.now() - attemptStartTime;
+    const failureType = classifyCodexFailure(proc);
+
+    // Parse JSONL output
+    const messages = (proc.stdout || '')
+      .split('\n')
+      .filter(l => l.trim())
+      .map(l => { try { return JSON.parse(l); } catch { return null; } })
+      .filter(Boolean);
 
-  const durationMs = Date.now() - startTime;
-
-  // Parse JSONL output
-  const messages = (proc.stdout || '')
-    .split('\n')
-    .filter(l => l.trim())
-    .map(l => { try { return JSON.parse(l); } catch { return null; } })
-    .filter(Boolean);
-
-  const agentMessages = messages
-    .filter(m => m.type === 'item.completed' && m.item?.type === 'agent_message')
-    .map(m => m.item.text);
-
-  const usage = messages.find(m => m.type === 'turn.completed')?.usage;
-  const errors = messages.filter(m => m.type === 'error' || m.type === 'turn.failed');
-
-  // Detect changed files from command_execution items
-  const commands = messages
-    .filter(m => m.type === 'item.completed' && m.item?.type === 'command_execution')
-    .map(m => m.item);
-
-  // Estimate startup time: time to first agent message or completed item
-  const firstItemTs = messages.find(m => m.type === 'item.completed')?.timestamp;
-  let startupMs = null;
-  if (firstItemTs) {
-    startupMs = Date.parse(firstItemTs) - startTime;
-    if (startupMs < 0 || startupMs > durationMs) startupMs = null;
+    const agentMessages = messages
+      .filter(m => m.type === 'item.completed' && m.item?.type === 'agent_message')
+      .map(m => m.item.text);
+
+    const usage = messages.find(m => m.type === 'turn.completed')?.usage;
+    const errors = messages.filter(m => m.type === 'error' || m.type === 'turn.failed');
+    const errorMessages = errors.map(e => e.message || e.error?.message || 'unknown');
+
+    if (proc.error?.message) {
+      errorMessages.unshift(proc.error.message);
+    }
+    if (proc.stderr?.trim() && errorMessages.length === 0 && proc.status !== 0) {
+      errorMessages.push(proc.stderr.trim().slice(0, 200));
+    }
+
+    // Detect changed files from command_execution items
+    const commands = messages
+      .filter(m => m.type === 'item.completed' && m.item?.type === 'command_execution')
+      .map(m => m.item);
+
+    // Estimate startup time: time to first agent message or completed item
+    const firstItemTs = messages.find(m => m.type === 'item.completed')?.timestamp;
+    let startupMs = null;
+    if (firstItemTs) {
+      startupMs = Date.parse(firstItemTs) - attemptStartTime;
+      if (startupMs < 0 || startupMs > durationMs) startupMs = null;
+    }
+
+    return {
+      success: proc.status === 0 && errors.length === 0 && !failureType,
+      summary: agentMessages.join('\n\n'),
+      durationMs,
+      startupMs,
+      model,
+      usage: usage || null,
+      errors: errorMessages,
+      commands: commands.length,
+      exitCode: proc.status,
+      signal: proc.signal,
+      failureType: failureType || null,
+      stderrSummary: proc.stderr?.trim().slice(0, 200) || null,
+      spawnErrorMessage: proc.error?.message || null,
+      retryCount: attemptCount - 1,
+    };
   }
 
-  return {
-    success: proc.status === 0 && errors.length === 0,
-    summary: agentMessages.join('\n\n'),
-    durationMs,
-    startupMs,
-    model,
-    usage: usage || null,
-    errors: errors.map(e => e.message || e.error?.message || 'unknown'),
-    commands: commands.length,
-    exitCode: proc.status,
-    signal: proc.signal,
-  };
+  let attemptCount = 1;
+  let attemptStartTime = startTime;
+  let proc = runCodexExec(codexBin, model, prompt, cwd, timeoutMs, sandbox);
+  let result = finalizeAttempt(proc, attemptStartTime, attemptCount);
+
+  if (!result.success && (result.failureType === 'rate_limit' || result.failureType === 'timeout')) {
+    spawnSync('sleep', ['3'], { stdio: 'ignore' });
+    attemptCount += 1;
+    attemptStartTime = Date.now();
+    proc = runCodexExec(codexBin, model, prompt, cwd, timeoutMs, sandbox);
+    result = finalizeAttempt(proc, attemptStartTime, attemptCount);
+  }
+
+  return result;
 }
 
 // ---------------------------------------------------------------------------
@@ -431,6 +485,19 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     console.log(`║ Model: ${result.model}  Duration: ${(result.durationMs / 1000).toFixed(1)}s`);
     console.log('╚══════════════════════════════════════════════════╝');
   } else {
+    if (result.failureType) {
+      const friendlyMessage = {
+        auth: 'Codex not authenticated. Run: codex login --device-auth',
+        rate_limit: 'Rate limited by OpenAI. Try again in a few minutes.',
+        timeout: 'Codex timed out. Try a simpler task or increase timeout.',
+        not_found: 'Codex CLI not found. Run: npm i -g @openai/codex',
+        spawn_error: `Failed to start Codex: ${result.spawnErrorMessage || 'unknown spawn error'}`,
+      }[result.failureType];
+
+      if (friendlyMessage) {
+        console.error(friendlyMessage);
+      }
+    }
     console.error('Task failed:', result.errors?.join(', ') || result.error);
   }
 

package/hooks/health-check.mjs

@@ -6,7 +6,8 @@
  *   node .claude/hooks/health-check.mjs
  *
  * Validates that all hooks are wired, configs are valid, and the system
- * is functioning in a live session. Always exits 0 and outputs valid JSON.
+ * is functioning in a live session. Always exits 0. With --json flag, outputs
+ * only JSON to stdout. Without it, prints both table and JSON.
  *
  * Checks:
  *   1. orchestrator.json    — exists and parses as valid JSON
@@ -29,9 +30,11 @@ import { spawnSync } from "child_process";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOOKS_DIR     = __dirname;
 const CONFIG_FILE   = join(__dirname, "..", "orchestrator.json");
+const SETTINGS_FILE = join(__dirname, "..", "settings.json");
 const USAGE_FILE_LEGACY = join(__dirname, "usage.jsonl");
 const USAGE_FILE_TODAY  = join(__dirname, `usage-${new Date().toISOString().slice(0, 10)}.jsonl`);
 const WORKSPACE     = join(__dirname, "..", "..");
+const jsonOnly      = process.argv.includes("--json");
 
 // ---------------------------------------------------------------------------
 // Status helpers
@@ -174,6 +177,39 @@ function checkHookScripts() {
   );
 }
 
+/** 4b. Hook registration — verify required hooks are configured in settings.json */
+function checkHookRegistration() {
+  if (!existsSync(SETTINGS_FILE)) {
+    return check("hook_registration", STATUS.fail, "settings.json not found");
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(SETTINGS_FILE, "utf8"));
+  } catch (err) {
+    return check("hook_registration", STATUS.warn, `invalid JSON: ${err.message}`);
+  }
+
+  const preToolUse = Array.isArray(settings?.hooks?.PreToolUse) ? settings.hooks.PreToolUse : [];
+  const postToolUse = Array.isArray(settings?.hooks?.PostToolUse) ? settings.hooks.PostToolUse : [];
+
+  const expectedPre = "node .claude/hooks/enforce-tier.mjs";
+  const expectedPost = "node .claude/hooks/cost-logger.mjs";
+
+  const hasPre = preToolUse.includes(expectedPre);
+  const hasPost = postToolUse.includes(expectedPost);
+
+  if (hasPre && hasPost) {
+    return check("hook_registration", STATUS.pass, "required hooks registered");
+  }
+
+  const missing = [];
+  if (!hasPre) missing.push(`PreToolUse: ${expectedPre}`);
+  if (!hasPost) missing.push(`PostToolUse: ${expectedPost}`);
+
+  return check("hook_registration", STATUS.warn, `missing registrations: ${missing.join("; ")}`);
+}
+
 /** 5. usage log active — check dated files and legacy for entries from last 15 minutes */
 function checkUsageJsonl() {
   const usageFile = existsSync(USAGE_FILE_TODAY) ? USAGE_FILE_TODAY
@@ -366,14 +402,21 @@ function main() {
     checkPricingVerified(),
     checkModelIntelligence(),
     checkHookScripts(),
+    checkHookRegistration(),
     checkUsageJsonl(),
     checkCodexCli(),
     checkGitRepo(),
   ];
 
   // Print formatted table
-  console.log(renderTable(checks));
-  console.log();
+  const tableOutput = renderTable(checks);
+  if (jsonOnly) {
+    console.error(tableOutput);
+    console.error();
+  } else {
+    console.log(tableOutput);
+    console.log();
+  }
 
   // Build JSON summary
   const passCount = checks.filter((c) => c.status === "pass").length;

package/hooks/quality-gate.mjs

@@ -163,6 +163,13 @@ function scoreSensitivity(files, config) {
 function matchesSkipPattern(filePath, patterns) {
   const segments = filePath.split('/');
   const basename = segments[segments.length - 1];
+  const isTestFile = /\.(test|spec)\.(js|ts|tsx|jsx|mjs)$/.test(basename);
+  const isTestDirectory = segments.some(seg => seg === '__tests__' || seg === '__mocks__');
+
+  if (isTestFile || isTestDirectory) {
+    return true;
+  }
+
   return patterns.some(p => {
     if (p.startsWith('.')) return basename.endsWith(p);  // extension match
     return segments.some(seg => seg === p || seg.startsWith(p + '.'));  // exact segment match

package/install.mjs

@@ -9,7 +9,7 @@
  *   npx dual-brain --dry-run        # detect only, don't install
  *   npx dual-brain --help
  */
-import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
 import { createInterface } from 'readline';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
@@ -34,6 +34,7 @@ const flag = (f) => argv.includes(f);
 const force = flag('--force');
 const dryRun = flag('--dry-run');
 const jsonOut = flag('--json');
+const restoreNpmFlag = flag('--restore-npm');
 const positional = argv.filter(a => !a.startsWith('-'));
 const subcommand = positional[0] || null;
 
@@ -64,6 +65,7 @@ if (flag('--help') || flag('-h')) {
     --force      Overwrite all existing config
     --dry-run    Detect environment only
     --json       Output detection as JSON
+    --restore-npm Restore persisted npm token before auth flows
     --help       Show this help
 
   🎛️  Routing modes:
@@ -467,9 +469,26 @@ async function authGuidance(env) {
 const CODEX_HOME = join(process.env.HOME || '', '.codex');
 const CODEX_PERSIST = resolve(process.cwd(), '.replit-tools', '.codex-persistent');
 
+function isGitignored(path) {
+  const result = run('git', ['check-ignore', '-q', path], { cwd: process.cwd() });
+  return result.status === 0;
+}
+
+function hasStrictFilePermissions(path) {
+  try {
+    return (statSync(path).mode & 0o777) === 0o600;
+  } catch {
+    return false;
+  }
+}
+
 function saveCodexCredentials() {
   const authFile = join(CODEX_HOME, 'auth.json');
   if (!existsSync(authFile)) return false;
+  if (!isGitignored('.replit-tools')) {
+    console.warn('WARNING: .replit-tools is not gitignored. Skipping credential persistence to avoid leaking secrets.');
+    return false;
+  }
   try {
     const auth = readFileSync(authFile, 'utf8');
     if (!auth.trim() || auth.trim() === '{}') return false;
@@ -477,6 +496,9 @@ function saveCodexCredentials() {
     const persisted = join(CODEX_PERSIST, 'auth.json');
     writeFileSync(persisted, auth, { mode: 0o600 });
     try { chmodSync(persisted, 0o600); } catch {}
+    if (!hasStrictFilePermissions(persisted)) {
+      console.warn(`WARNING: ${relPath(persisted)} permissions are not 0600.`);
+    }
     return true;
   } catch { return false; }
 }
@@ -486,6 +508,10 @@ function restoreCodexCredentials() {
   const targetAuth = join(CODEX_HOME, 'auth.json');
   if (existsSync(targetAuth)) return false;
   if (!existsSync(persistedAuth)) return false;
+  if (!hasStrictFilePermissions(persistedAuth)) {
+    console.warn(`WARNING: ${relPath(persistedAuth)} permissions are not 0600. Skipping restore.`);
+    return false;
+  }
   try {
     const auth = readFileSync(persistedAuth, 'utf8');
     if (!auth.trim() || auth.trim() === '{}') return false;
@@ -757,6 +783,41 @@ function generateClaudeMd(mode) {
   return md;
 }
 
+const CLAUDE_MD_MANAGED_START = '<!-- dual-brain:start -->';
+const CLAUDE_MD_MANAGED_END = '<!-- dual-brain:end -->';
+
+function renderManagedClaudeSection(content) {
+  return `${CLAUDE_MD_MANAGED_START}\n${content.replace(/\s+$/, '')}\n${CLAUDE_MD_MANAGED_END}\n`;
+}
+
+function mergeClaudeMd(existingContent, managedContent) {
+  const managedSection = renderManagedClaudeSection(managedContent);
+  const startIndex = existingContent.indexOf(CLAUDE_MD_MANAGED_START);
+  const endIndex = existingContent.indexOf(CLAUDE_MD_MANAGED_END);
+
+  if (startIndex !== -1 && endIndex !== -1 && endIndex >= startIndex) {
+    const before = existingContent.slice(0, startIndex);
+    const after = existingContent.slice(endIndex + CLAUDE_MD_MANAGED_END.length);
+    const prefix = before.replace(/\s*$/, '');
+    const suffix = after.replace(/^\s*/, '');
+    return `${prefix}${prefix ? '\n\n' : ''}${managedSection}${suffix ? `\n${suffix}` : ''}`.replace(/\s+$/, '') + '\n';
+  }
+
+  const trimmed = existingContent.replace(/\s+$/, '');
+  return `${trimmed}${trimmed ? '\n\n' : ''}${managedSection}`;
+}
+
+function writeClaudeMd(targetPath, content) {
+  const managedContent = content.replace(/\s+$/, '');
+  if (force || !existsSync(targetPath)) {
+    writeFileSync(targetPath, renderManagedClaudeSection(managedContent));
+    return;
+  }
+
+  const existing = readFileSync(targetPath, 'utf8');
+  writeFileSync(targetPath, mergeClaudeMd(existing, managedContent));
+}
+
 function generateGitignoreEntries(workspace) {
   const entries = [
     '.claude/hooks/usage-*.jsonl',
@@ -816,7 +877,7 @@ function install(workspace, env, mode) {
   actions.push('✓ settings.json (hooks registered)');
 
   const claudeMd = generateClaudeMd(mode);
-  writeFileSync(join(target, 'CLAUDE.md'), claudeMd);
+  writeClaudeMd(join(target, 'CLAUDE.md'), claudeMd);
   actions.push('✓ CLAUDE.md (session instructions)');
 
   const rulesTarget = join(target, 'review-rules.md');
@@ -1284,6 +1345,10 @@ function cmdExplain() {
 // ─── Main ───────────────────────────────────────────────────────────────────
 
 async function main() {
+  if (subcommand === 'auth' || restoreNpmFlag) {
+    restoreNpmToken();
+  }
+
   if (subcommand === 'status') {
     launchPanel();
     return;
@@ -1293,9 +1358,6 @@ async function main() {
   if (subcommand === 'budget')  { cmdBudget();  return; }
   if (subcommand === 'explain') { cmdExplain(); return; }
 
-  // Restore npm token if missing (for publish access)
-  restoreNpmToken();
-
   let env = detectEnvironment();
   const startupUpdateInfo = (subcommand === 'update' || dryRun || jsonOut)
     ? null

package/package.json

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