dual-brain 4.2.0 → 4.5.0

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, readdirSync, renameSync, unlinkSync, writeFileSync } from 'fs';
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { spawnSync } from 'child_process';
@@ -43,38 +43,95 @@ if (flag('--help') || flag('-h')) {
 
   Usage:  npx -y dual-brain [command] [options]
 
-  ⌨️  Commands:
-    (none)       🧠 Auto-detect and install/update orchestrator
-    status       🟢 Open live control panel
-    mode         🎛️  Show or switch profile
-    budget       💵 Set session/daily spend limits
-    explain      🧭 Explain last routing decision
+  Setup:
+    (none)       Auto-detect and install/update orchestrator
     init         Alias for default install
+    doctor       Check system health and report issues
+    reset        Clear all state files (keeps config/hooks)
+    repair       Fix corrupt files, stale locks, re-register hooks
+    --uninstall  Remove dual-brain hooks and state files
+
+  Status:
+    status       Open live control panel
+    health       Verify system health
+    budget       Show or set session/daily spend limits
+    cost         Activity and cost estimates
+    report       Generate session report
+
+  Routing:
+    mode         Show or switch profile
+    explain      Explain last routing decision
+    gate         Run quality gate
+    ledger       Routing outcome insights
+
+  GPT:
+    think        Dual-brain think (--question "..." [--round 2])
+    review       Dual-brain code review
+    dispatch     Dispatch work to GPT via Codex CLI
+
+  Vibe:
+    vibe         Decompose casual requests into structured work
+    plan         Generate execution plans (--utterance "...")
+    memory       Persistent preferences and work threads
+
+  Agents:
+    agent        Run a specialist agent template (explorer, security-review, test-writer, bug-hunter)
+    agents       List all available agent templates
+    chain        Run a built-in agent chain (explore-then-fix, review-and-test, audit-and-plan)
+    chains       List all available agent chains
+
+  Ship Captain:
+    do "<goal>"         Run full pipeline: agents → tests → gate → PR
+                      --yolo        Skip all confirmations
+                      --careful     Confirm every step
+                      --plan-only   Show plan without executing
+                      --no-pr       Skip PR creation
+    ship                Create branch, run tests, open PR
+    test-run            Discover and run project tests
+    diff                Show current changes summary
+    runs                List recent Ship Captain runs
+    resume              Resume last incomplete run
+
+  Dev:
+    test         Run self-tests
 
   Options:
     --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:
-    🤖 Auto (default) Adapts routing based on risk, health, outcomes
-    ⚖️  Balanced       Auto-routes, uses both providers evenly
-    🛡️  Conservative   Fewer GPT dispatches, sticks to Claude
-    🚀 Aggressive     Maximizes both subscriptions, dual-brain for medium+
+  Routing modes:
+    Auto (default) Adapts routing based on risk, health, outcomes
+    Balanced       Auto-routes, uses both providers evenly
+    Conservative   Fewer GPT dispatches, sticks to Claude
+    Aggressive     Maximizes both subscriptions, dual-brain for medium+
 
-  🚀 Examples:
+  Examples:
     ${cmd('npx dual-brain')}                  # install or update
     ${cmd('npx dual-brain status')}           # open control panel
     ${cmd('npx dual-brain mode cost-saver')}  # switch profile
     ${cmd('npx dual-brain budget 8 25')}      # \$8 session / \$25 daily
-    ${cmd('npx dual-brain explain')}          # last routing decision
+    ${cmd('npx dual-brain think --question "should we use Redis?"')}
+    ${cmd('npx dual-brain vibe "fix login and update nav"')}
+    ${cmd('npx dual-brain agents')}                         # list agent templates
+    ${cmd('npx dual-brain agent explorer --question "where is auth handled?"')}
+    ${cmd('npx dual-brain agent security-review --scope src/auth --severity high')}
+    ${cmd('npx dual-brain chains')}                         # list available chains
+    ${cmd('npx dual-brain chain explore-then-fix --question "auth bug" --scope "src/auth"')}
   `);
   process.exit(0);
 }
 
-const SUBCOMMANDS = ['init', 'status', 'mode', 'budget', 'explain'];
+const SUBCOMMANDS = [
+  'init', 'status', 'mode', 'budget', 'explain',
+  'review', 'think', 'health', 'report', 'gate',
+  'vibe', 'plan', 'cost', 'dispatch', 'memory',
+  'test', 'ledger', 'doctor', 'reset', 'repair',
+  'chain', 'chains',
+  'agent', 'agents',
+  'do', 'ship', 'test-run', 'diff', 'runs', 'resume',
+];
 if (subcommand && !SUBCOMMANDS.includes(subcommand)) {
   console.error(`  Unknown command: ${subcommand}`);
   console.error(`  Run: ${cmd('npx dual-brain --help')}`);
@@ -268,7 +325,7 @@ function generateSettings(workspace) {
     ],
     PostToolUse: [
       {
-        matcher: '',
+        matcher: 'Agent|Bash|Write|Edit',
         hooks: [{ type: 'command', command: 'node .claude/hooks/cost-logger.mjs' }],
       },
     ],
@@ -341,6 +398,8 @@ function install(workspace, env, mode) {
     'summary-checkpoint.mjs', 'decision-ledger.mjs', 'control-panel.mjs',
     'risk-classifier.mjs', 'failure-detector.mjs',
     'vibe-router.mjs', 'plan-generator.mjs', 'vibe-memory.mjs',
+    'agent-templates.mjs', 'agent-chains.mjs',
+    'ship-captain.mjs', 'ship-gate.mjs', 'confirmation-policy.mjs',
   ];
   for (const h of HOOKS) cpSync(join(__dirname, 'hooks', h), join(target, 'hooks', h));
   actions.push(`✓ ${HOOKS.length} hook scripts`);
@@ -385,6 +444,134 @@ function install(workspace, env, mode) {
   return actions;
 }
 
+// ─── Guided Auth ────────────────────────────────────────────────────────────
+
+function printGuidedAuth(env) {
+  const claudeOk = env.claude.installed && env.claude.authed;
+  const codexOk = env.codex.installed && env.codex.authed;
+
+  if (claudeOk && codexOk) return false; // nothing to guide
+
+  const claudeMissing = !env.claude.installed || !env.claude.authed;
+  const codexMissing = !env.codex.installed || !env.codex.authed;
+
+  console.log('');
+
+  if (claudeMissing && codexMissing) {
+    console.log('  ⚠️  No AI providers detected. You need at least one:');
+    console.log('');
+    console.log('  Claude (recommended):');
+    console.log('    npm install -g @anthropic-ai/claude-code && claude login');
+    console.log('');
+    console.log('  OpenAI (optional, enables dual-brain):');
+    console.log('    npm install -g @openai/codex && codex login');
+    console.log('');
+    console.log('  Then re-run: npx dual-brain');
+    console.log('');
+    return true;
+  }
+
+  if (claudeMissing) {
+    if (!env.claude.installed) {
+      console.log('  ⚠️  Claude CLI not detected. To enable Claude routing:');
+    } else {
+      console.log('  ⚠️  Claude CLI not authenticated. To enable Claude routing:');
+    }
+    console.log('');
+    console.log('  1. Install: npm install -g @anthropic-ai/claude-code');
+    console.log('  2. Login:   claude login');
+    console.log('');
+    console.log('  Run these commands, then re-run: npx dual-brain');
+    console.log('');
+  }
+
+  if (codexMissing) {
+    if (!env.codex.installed) {
+      console.log('  ℹ️  Codex CLI not detected. To enable GPT routing:');
+    } else {
+      console.log('  ℹ️  Codex CLI not authenticated. To enable GPT routing:');
+    }
+    console.log('');
+    console.log('  1. Install: npm install -g @openai/codex');
+    console.log('  2. Login:   codex login');
+    console.log('');
+    if (claudeMissing) {
+      console.log('  Run these commands, then re-run: npx dual-brain');
+    } else {
+      console.log('  Run these commands, then re-run: npx dual-brain');
+      console.log('  GPT features will be disabled until Codex is configured.');
+    }
+    console.log('');
+  }
+
+  return claudeMissing; // only block/poll if Claude (primary provider) is missing
+}
+
+async function waitForAuth(env) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return;
+
+  const claudeMissing = !env.claude.installed || !env.claude.authed;
+  if (!claudeMissing) return; // only wait if primary provider needs setup
+
+  process.stdout.write('  Would you like me to wait while you authenticate? [Y/n] ');
+
+  const answer = await new Promise((resolve) => {
+    process.stdin.setEncoding('utf8');
+    process.stdin.once('data', (chunk) => resolve(chunk.trim().toLowerCase()));
+    process.stdin.resume();
+  });
+
+  if (answer === 'n' || answer === 'no') {
+    process.stdin.pause();
+    console.log('');
+    console.log('  Re-run `npx dual-brain` after authenticating.');
+    console.log('');
+    process.exit(0);
+  }
+
+  console.log('');
+  console.log('  Waiting for Claude CLI to become available (checking every 5s, max 5 min)...');
+  console.log('');
+
+  const maxAttempts = 60; // 60 × 5s = 5 minutes
+  for (let i = 0; i < maxAttempts; i++) {
+    await new Promise(r => setTimeout(r, 5000));
+    process.stdout.write('.');
+    const fresh = detectClaude();
+    if (fresh.installed) {
+      console.log('');
+      console.log('');
+      console.log('  Claude CLI detected! Continuing setup...');
+      console.log('');
+      process.stdin.pause();
+      // Update env in-place
+      env.claude = fresh;
+      return;
+    }
+  }
+
+  console.log('');
+  console.log('');
+  console.log('  Timed out after 5 minutes. Re-run `npx dual-brain` after authenticating.');
+  console.log('');
+  process.stdin.pause();
+  process.exit(1);
+}
+
+// ─── Quick Start Block ───────────────────────────────────────────────────────
+
+function printQuickStart() {
+  console.log('  ✓ dual-brain installed successfully');
+  console.log('');
+  console.log('  Quick start:');
+  console.log(`    npx dual-brain do "fix a bug and write tests"   ← full pipeline`);
+  console.log('    npx dual-brain status                            ← check system');
+  console.log('    npx dual-brain doctor                            ← diagnose issues');
+  console.log('');
+  console.log('  All commands: npx dual-brain --help');
+  console.log('');
+}
+
 // ─── Status Report ──────────────────────────────────────────────────────────
 
 function printReport(env, mode, actions, isDryRun) {
@@ -405,8 +592,6 @@ function printReport(env, mode, actions, isDryRun) {
   if (actions) {
     lines.push(sep());
     for (const a of actions) lines.push(ln(`  ${a}`));
-    lines.push(sep());
-    lines.push(ln('✅ Installed — launching session manager...'));
   } else if (isDryRun) {
     lines.push(sep());
     lines.push(ln('Dry run — no files written'));
@@ -698,6 +883,431 @@ function cmdExplain() {
   console.log('');
 }
 
+// ─── Subcommand: doctor ───────────────────────────────────────────────────
+
+function cmdDoctor() {
+  const workspace = resolve(process.cwd());
+  const claudeDir = join(workspace, '.claude');
+  const hooksDir = join(claudeDir, 'hooks');
+  const results = [];
+
+  // 1. Hook installation check
+  const settingsPath = join(claudeDir, 'settings.json');
+  const DUAL_BRAIN_CMDS = [
+    'node .claude/hooks/enforce-tier.mjs',
+    'node .claude/hooks/cost-logger.mjs',
+  ];
+  if (existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+      const registeredCmds = [];
+      if (settings.hooks) {
+        for (const entries of Object.values(settings.hooks)) {
+          for (const entry of entries) {
+            for (const h of (entry.hooks || [])) {
+              if (DUAL_BRAIN_CMDS.includes(h.command)) registeredCmds.push(h.command);
+            }
+          }
+        }
+      }
+      const missing = DUAL_BRAIN_CMDS.filter(c => !registeredCmds.includes(c));
+      if (missing.length === 0) {
+        results.push({ name: 'Hook registration', status: 'pass', detail: `${DUAL_BRAIN_CMDS.length}/${DUAL_BRAIN_CMDS.length} hooks registered` });
+      } else {
+        results.push({ name: 'Hook registration', status: 'fail', detail: `Missing: ${missing.map(c => c.split('/').pop()).join(', ')}`, fix: 'Run: npx dual-brain repair' });
+      }
+    } catch (err) {
+      results.push({ name: 'Hook registration', status: 'fail', detail: `settings.json parse error: ${err.message}`, fix: 'Run: npx dual-brain repair' });
+    }
+  } else {
+    results.push({ name: 'Hook registration', status: 'fail', detail: 'settings.json not found', fix: 'Run: npx dual-brain' });
+  }
+
+  // 2. Config validity
+  const orchPath = join(claudeDir, 'orchestrator.json');
+  if (existsSync(orchPath)) {
+    try {
+      const config = JSON.parse(readFileSync(orchPath, 'utf8'));
+      const requiredKeys = ['subscriptions', 'tiers', 'providers', 'budgets'];
+      const missing = requiredKeys.filter(k => !config[k]);
+      if (missing.length === 0) {
+        results.push({ name: 'Config validity', status: 'pass', detail: 'orchestrator.json valid, all required keys present' });
+      } else {
+        results.push({ name: 'Config validity', status: 'warn', detail: `Missing keys: ${missing.join(', ')}`, fix: 'Run: npx dual-brain --force' });
+      }
+    } catch (err) {
+      results.push({ name: 'Config validity', status: 'fail', detail: `orchestrator.json corrupt: ${err.message}`, fix: 'Run: npx dual-brain repair' });
+    }
+  } else {
+    results.push({ name: 'Config validity', status: 'fail', detail: 'orchestrator.json not found', fix: 'Run: npx dual-brain' });
+  }
+
+  // 3. Auth status
+  const claude = detectClaude();
+  if (claude.authed) {
+    results.push({ name: 'Claude CLI', status: 'pass', detail: 'installed and authenticated' });
+  } else if (claude.installed) {
+    results.push({ name: 'Claude CLI', status: 'warn', detail: 'installed but not authenticated' });
+  } else {
+    results.push({ name: 'Claude CLI', status: 'warn', detail: 'not found' });
+  }
+
+  const codexResult = detectCodex();
+  if (codexResult.authed) {
+    results.push({ name: 'Codex CLI', status: 'pass', detail: 'installed and authenticated' });
+  } else if (codexResult.installed) {
+    results.push({ name: 'Codex CLI', status: 'warn', detail: 'installed but not authenticated' });
+  } else {
+    results.push({ name: 'Codex CLI', status: 'warn', detail: 'not found (GPT features disabled)' });
+  }
+
+  // 4. State file health
+  const stateCheckFiles = [
+    { path: join(hooksDir, '.burst-state'), label: '.burst-state', format: 'json' },
+    { path: join(hooksDir, 'burst-state.json'), label: 'burst-state.json', format: 'json' },
+    { path: join(hooksDir, '.drift-warned'), label: '.drift-warned', format: 'any' },
+    { path: join(claudeDir, 'dual-brain.profile.json'), label: 'dual-brain.profile.json', format: 'json' },
+    { path: join(hooksDir, 'decision-ledger.jsonl'), label: 'decision-ledger.jsonl', format: 'jsonl' },
+  ];
+
+  // Add any usage-*.jsonl files
+  try {
+    for (const f of readdirSync(hooksDir)) {
+      if (f.startsWith('usage-') && f.endsWith('.jsonl')) {
+        stateCheckFiles.push({ path: join(hooksDir, f), label: f, format: 'jsonl' });
+      }
+    }
+  } catch {}
+
+  let stateHealthy = 0, stateWarns = 0, stateFails = 0;
+  const stateIssues = [];
+
+  for (const sf of stateCheckFiles) {
+    if (!existsSync(sf.path)) continue;
+    try {
+      const raw = readFileSync(sf.path, 'utf8');
+      if (sf.format === 'json') {
+        JSON.parse(raw);
+        stateHealthy++;
+      } else if (sf.format === 'jsonl') {
+        const lines = raw.split('\n').filter(Boolean);
+        let badLines = 0;
+        for (const line of lines) {
+          try { JSON.parse(line); } catch { badLines++; }
+        }
+        if (badLines > 0) {
+          stateWarns++;
+          stateIssues.push(`${sf.label}: ${badLines}/${lines.length} unparseable lines`);
+        } else {
+          stateHealthy++;
+        }
+      } else {
+        stateHealthy++;
+      }
+    } catch (err) {
+      stateFails++;
+      stateIssues.push(`${sf.label}: corrupt (${err.message})`);
+    }
+  }
+
+  // Check for stale locks
+  let staleLocks = 0;
+  for (const dir of [hooksDir, claudeDir]) {
+    try {
+      for (const f of readdirSync(dir)) {
+        if (f.endsWith('.lock')) {
+          try {
+            const st = statSync(join(dir, f));
+            if (Date.now() - st.mtimeMs > 30_000) staleLocks++;
+          } catch {}
+        }
+      }
+    } catch {}
+  }
+
+  if (staleLocks > 0) {
+    stateIssues.push(`${staleLocks} stale lock file(s)`);
+    stateWarns++;
+  }
+
+  if (stateFails > 0) {
+    results.push({ name: 'State files', status: 'fail', detail: stateIssues.join('; '), fix: 'Run: npx dual-brain repair' });
+  } else if (stateWarns > 0) {
+    results.push({ name: 'State files', status: 'warn', detail: stateIssues.join('; '), fix: 'Run: npx dual-brain repair' });
+  } else {
+    results.push({ name: 'State files', status: 'pass', detail: `${stateHealthy} file(s) healthy` });
+  }
+
+  // 5. Error channel
+  const errorsFile = join(hooksDir, 'errors.jsonl');
+  if (existsSync(errorsFile)) {
+    try {
+      const raw = readFileSync(errorsFile, 'utf8');
+      const lines = raw.split('\n').filter(Boolean);
+      const entries = [];
+      for (const line of lines) {
+        try { entries.push(JSON.parse(line)); } catch {}
+      }
+
+      const cutoff24h = Date.now() - 24 * 60 * 60 * 1000;
+      const recent = entries.filter(e => e.timestamp && Date.parse(e.timestamp) >= cutoff24h);
+
+      if (recent.length === 0) {
+        results.push({ name: 'Error channel', status: 'pass', detail: 'no errors in last 24h' });
+      } else {
+        const last3 = recent.slice(-3);
+        const detail = `${recent.length} error(s) in last 24h`;
+        results.push({ name: 'Error channel', status: 'warn', detail, errors: last3 });
+      }
+    } catch {
+      results.push({ name: 'Error channel', status: 'warn', detail: 'errors.jsonl unreadable' });
+    }
+  } else {
+    results.push({ name: 'Error channel', status: 'pass', detail: 'no errors.jsonl (clean)' });
+  }
+
+  // Output
+  const passCount = results.filter(r => r.status === 'pass').length;
+  const warnCount = results.filter(r => r.status === 'warn').length;
+  const failCount = results.filter(r => r.status === 'fail').length;
+
+  console.log('');
+  console.log(`  🩺 dual-brain v${VERSION} — doctor`);
+  console.log('  ' + '─'.repeat(50));
+
+  for (const r of results) {
+    const icon = r.status === 'pass' ? '✓' : r.status === 'warn' ? '⚠' : '✗';
+    console.log(`  ${icon} ${r.name}: ${r.detail}`);
+    if (r.fix) console.log(`    → ${r.fix}`);
+    if (r.errors) {
+      for (const e of r.errors) {
+        const ts = e.timestamp ? e.timestamp.slice(11, 19) : '??:??:??';
+        console.log(`    ${ts} [${e.hook || '?'}] ${e.error || '?'}`);
+      }
+    }
+  }
+
+  console.log('  ' + '─'.repeat(50));
+  if (failCount > 0) {
+    console.log(`  ✗ Needs repair: ${failCount} issue(s) require attention`);
+  } else if (warnCount > 0) {
+    console.log(`  ⚠ Warnings: ${warnCount} — system functional but has issues`);
+  } else {
+    console.log(`  ✓ Healthy: all ${passCount} checks passed`);
+  }
+  console.log('');
+}
+
+// ─── Subcommand: reset ────────────────────────────────────────────────────
+
+function cmdReset() {
+  const workspace = resolve(process.cwd());
+  const claudeDir = join(workspace, '.claude');
+  const hooksDir = join(claudeDir, 'hooks');
+
+  // Collect state files (NOT config, hooks, or profile)
+  const STATE_FIXED = [
+    join(hooksDir, 'usage.jsonl'),
+    join(hooksDir, 'decision-ledger.jsonl'),
+    join(hooksDir, 'failure-ledger.json'),
+    join(hooksDir, '.burst-state'),
+    join(hooksDir, 'burst-state.json'),
+    join(hooksDir, '.drift-warned'),
+    join(hooksDir, '.budget-alerted'),
+    join(hooksDir, 'errors.jsonl'),
+    join(hooksDir, 'summary-checkpoint.json'),
+    join(claudeDir, '.launched'),
+  ];
+
+  const toDelete = [];
+  for (const f of STATE_FIXED) {
+    if (existsSync(f)) toDelete.push(f);
+  }
+
+  // Scan for date-stamped files and lock files
+  try {
+    for (const f of readdirSync(hooksDir)) {
+      if (f.startsWith('usage-') && f.endsWith('.jsonl')) toDelete.push(join(hooksDir, f));
+      if (f.startsWith('usage-summary-') && f.endsWith('.json')) toDelete.push(join(hooksDir, f));
+      if (f.endsWith('.lock')) toDelete.push(join(hooksDir, f));
+    }
+  } catch {}
+  try {
+    for (const f of readdirSync(claudeDir)) {
+      if (f.endsWith('.lock')) toDelete.push(join(claudeDir, f));
+    }
+  } catch {}
+
+  const unique = [...new Set(toDelete)].filter(f => existsSync(f));
+
+  if (unique.length === 0) {
+    console.log('');
+    console.log('  🔄 Nothing to reset — no state files found.');
+    console.log('');
+    return;
+  }
+
+  // Require --force or confirmation
+  if (!force) {
+    console.log('');
+    console.log(`  🔄 dual-brain reset — will delete ${unique.length} state file(s):`);
+    console.log('');
+    for (const f of unique) {
+      const rel = f.startsWith(workspace) ? f.slice(workspace.length + 1) : f;
+      console.log(`    ${rel}`);
+    }
+    console.log('');
+    console.log('  Preserved: orchestrator.json, settings.json, hooks, profile, CLAUDE.md');
+    console.log('');
+    console.log(`  To confirm: ${cmd('npx dual-brain reset --force')}`);
+    console.log('');
+    return;
+  }
+
+  let removed = 0;
+  const errors = [];
+  for (const f of unique) {
+    try {
+      unlinkSync(f);
+      removed++;
+    } catch (err) {
+      errors.push(`  ⚠ Could not remove ${f.split('/').pop()}: ${err.message}`);
+    }
+  }
+
+  console.log('');
+  console.log(`  🔄 dual-brain v${VERSION} — reset`);
+  console.log('  ' + '─'.repeat(40));
+  console.log(`  ✓ Removed ${removed} state file(s)`);
+  for (const e of errors) console.log(e);
+  console.log('');
+  console.log('  Preserved: orchestrator.json, settings.json, hooks, profile, CLAUDE.md');
+  console.log('  State will rebuild automatically on next session.');
+  console.log('');
+}
+
+// ─── Subcommand: repair ───────────────────────────────────────────────────
+
+function cmdRepair() {
+  const workspace = resolve(process.cwd());
+  const claudeDir = join(workspace, '.claude');
+  const hooksDir = join(claudeDir, 'hooks');
+  const actions = [];
+
+  // 1. Remove stale lock files (older than 30 seconds)
+  let staleLocks = 0;
+  for (const dir of [hooksDir, claudeDir]) {
+    try {
+      for (const f of readdirSync(dir)) {
+        if (!f.endsWith('.lock')) continue;
+        const lockPath = join(dir, f);
+        try {
+          const st = statSync(lockPath);
+          if (Date.now() - st.mtimeMs > 30_000) {
+            unlinkSync(lockPath);
+            staleLocks++;
+          }
+        } catch {}
+      }
+    } catch {}
+  }
+  if (staleLocks > 0) {
+    actions.push(`✓ Removed ${staleLocks} stale lock file(s)`);
+  } else {
+    actions.push('⊘ No stale locks found');
+  }
+
+  // 2. Repair corrupt JSONL files
+  const jsonlFiles = [
+    join(hooksDir, 'decision-ledger.jsonl'),
+    join(hooksDir, 'errors.jsonl'),
+    join(hooksDir, 'usage.jsonl'),
+  ];
+  try {
+    for (const f of readdirSync(hooksDir)) {
+      if (f.startsWith('usage-') && f.endsWith('.jsonl')) {
+        jsonlFiles.push(join(hooksDir, f));
+      }
+    }
+  } catch {}
+
+  let repairedJsonl = 0;
+  for (const filePath of [...new Set(jsonlFiles)]) {
+    if (!existsSync(filePath)) continue;
+    try {
+      const raw = readFileSync(filePath, 'utf8');
+      const lines = raw.split('\n').filter(Boolean);
+      let badCount = 0;
+      const goodLines = [];
+      for (const line of lines) {
+        try {
+          JSON.parse(line);
+          goodLines.push(line);
+        } catch {
+          badCount++;
+        }
+      }
+      if (badCount > 0) {
+        const tmp = filePath + '.tmp.' + process.pid;
+        writeFileSync(tmp, goodLines.length > 0 ? goodLines.join('\n') + '\n' : '');
+        renameSync(tmp, filePath);
+        repairedJsonl++;
+        actions.push(`✓ ${filePath.split('/').pop()}: removed ${badCount} corrupt line(s), kept ${goodLines.length}`);
+      }
+    } catch (err) {
+      actions.push(`⚠ ${filePath.split('/').pop()}: could not repair (${err.message})`);
+    }
+  }
+  if (repairedJsonl === 0) {
+    actions.push('⊘ No corrupt JSONL files found');
+  }
+
+  // 3. Re-validate and fix orchestrator.json formatting
+  const orchPath = join(claudeDir, 'orchestrator.json');
+  if (existsSync(orchPath)) {
+    try {
+      const raw = readFileSync(orchPath, 'utf8');
+      const config = JSON.parse(raw);
+      const pretty = JSON.stringify(config, null, 2) + '\n';
+      if (raw !== pretty) {
+        const tmp = orchPath + '.tmp.' + process.pid;
+        writeFileSync(tmp, pretty);
+        renameSync(tmp, orchPath);
+        actions.push('✓ orchestrator.json: re-formatted');
+      } else {
+        actions.push('⊘ orchestrator.json: already well-formatted');
+      }
+    } catch (err) {
+      actions.push(`✗ orchestrator.json: invalid JSON — ${err.message}`);
+      actions.push('  → Run: npx dual-brain --force (to regenerate from template)');
+    }
+  } else {
+    actions.push('✗ orchestrator.json: not found — run: npx dual-brain');
+  }
+
+  // 4. Re-run hook registration (ensure hooks are in settings.json)
+  if (existsSync(join(claudeDir, 'settings.json')) || existsSync(orchPath)) {
+    try {
+      const settings = generateSettings(workspace);
+      const tmp = join(claudeDir, 'settings.json.tmp.' + process.pid);
+      writeFileSync(tmp, JSON.stringify(settings, null, 2) + '\n');
+      renameSync(tmp, join(claudeDir, 'settings.json'));
+      actions.push('✓ settings.json: hooks re-registered');
+    } catch (err) {
+      actions.push(`⚠ settings.json: could not re-register hooks (${err.message})`);
+    }
+  }
+
+  // Print report
+  console.log('');
+  console.log(`  🔧 dual-brain v${VERSION} — repair`);
+  console.log('  ' + '─'.repeat(40));
+  for (const a of actions) {
+    console.log(`  ${a}`);
+  }
+  console.log('');
+}
+
 // ─── Uninstall ─────────────────────────────────────────────────────────────
 
 function cmdUninstall() {
@@ -817,9 +1427,140 @@ function cmdUninstall() {
   console.log('');
 }
 
+// ─── Hook Delegation ───────────────────────────────────────────────────────
+
+const HOOK_COMMANDS = {
+  review:   'dual-brain-review.mjs',
+  think:    'dual-brain-think.mjs',
+  health:   'health-check.mjs',
+  report:   'session-report.mjs',
+  gate:     'quality-gate.mjs',
+  vibe:     'vibe-router.mjs',
+  plan:     'plan-generator.mjs',
+  cost:     'cost-report.mjs',
+  dispatch: 'gpt-work-dispatcher.mjs',
+  memory:   'vibe-memory.mjs',
+  test:     'test-orchestrator.mjs',
+  ledger:   'decision-ledger.mjs',
+  chains:   'agent-chains.mjs',
+};
+
+function resolveHookScript(hookFile) {
+  const workspace = resolve(process.cwd());
+  const installed = join(workspace, '.claude', 'hooks', hookFile);
+  const bundled = join(__dirname, 'hooks', hookFile);
+  return existsSync(installed) ? installed : existsSync(bundled) ? bundled : null;
+}
+
+function delegateToHook(hookFile) {
+  const script = resolveHookScript(hookFile);
+
+  if (!script) {
+    console.error(`  Hook not found: ${hookFile}`);
+    console.error(`  Run: ${cmd('npx dual-brain')} to install hooks first.`);
+    process.exit(1);
+  }
+
+  // Pass through all args after the subcommand
+  const extraArgs = process.argv.slice(3);
+  const { status } = spawnSync(process.execPath, [script, ...extraArgs], {
+    stdio: 'inherit',
+    cwd: resolve(process.cwd()),
+  });
+  process.exit(status || 0);
+}
+
+function delegateToHookWithArgs(hookFile, args) {
+  const script = resolveHookScript(hookFile);
+
+  if (!script) {
+    console.error(`  Hook not found: ${hookFile}`);
+    console.error(`  Run: ${cmd('npx dual-brain')} to install hooks first.`);
+    process.exit(1);
+  }
+
+  const { status } = spawnSync(process.execPath, [script, ...args], {
+    stdio: 'inherit',
+    cwd: resolve(process.cwd()),
+  });
+  process.exit(status || 0);
+}
+
 // ─── Main ───────────────────────────────────────────────────────────────────
 
-function main() {
+// ─── Replit-Tools Check ────────────────────────────────────────────────────
+
+async function checkReplitTools() {
+  // Only run this check when actually on Replit
+  if (!IS_REPLIT) return;
+
+  // Check if replit-tools is installed
+  const hasReplitTools = existsSync(resolve(process.cwd(), '.replit-tools'));
+  if (hasReplitTools) return;
+
+  const yesFlag = flag('--yes') || flag('-y');
+
+  console.log('');
+  console.log('  ━━━ replit-tools Required ━━━');
+  console.log('');
+  console.log('  dual-brain is built on data-tools/replit-tools by Steve Moraco.');
+  console.log('  replit-tools provides persistent auth, session management, and');
+  console.log('  container survival that dual-brain depends on.');
+  console.log('');
+
+  let install = yesFlag;
+
+  if (!install) {
+    process.stdout.write('  Install now? [Y/n] ');
+
+    if (process.stdin.isTTY) {
+      install = await new Promise((resolve) => {
+        process.stdin.setEncoding('utf8');
+        process.stdin.once('data', (chunk) => {
+          const answer = chunk.trim().toLowerCase();
+          // Default yes: empty input (just Enter) or explicit y/yes
+          resolve(answer === '' || answer === 'y' || answer === 'yes');
+        });
+        process.stdin.resume();
+      });
+      process.stdin.pause();
+    } else {
+      // Non-TTY: default to yes
+      console.log('');
+      install = true;
+    }
+  }
+
+  console.log('');
+
+  if (install) {
+    console.log('  Installing replit-tools...');
+    console.log('');
+    const result = spawnSync('npx', ['-y', 'replit-tools'], { stdio: 'inherit', shell: true });
+    console.log('');
+    if (result.status !== 0) {
+      console.log('  ⚠  replit-tools install exited with a non-zero status.');
+      console.log('  Continuing with dual-brain install anyway.');
+      console.log('');
+    } else {
+      // Re-check that replit-tools is now present
+      if (existsSync(resolve(process.cwd(), '.replit-tools'))) {
+        console.log('  ✓ replit-tools installed successfully.');
+      } else {
+        console.log('  replit-tools may need a shell reload. Continuing with dual-brain install.');
+      }
+      console.log('');
+    }
+  } else {
+    console.log('  dual-brain will work with reduced functionality. Some features');
+    console.log('  (persistent state, session resume, auth survival) require replit-tools.');
+    console.log('');
+  }
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
   if (flag('--uninstall')) { cmdUninstall(); return; }
 
   if (subcommand === 'status') {
@@ -829,6 +1570,287 @@ function main() {
   if (subcommand === 'mode')    { cmdMode();    return; }
   if (subcommand === 'budget')  { cmdBudget();  return; }
   if (subcommand === 'explain') { cmdExplain(); return; }
+  if (subcommand === 'doctor')  { cmdDoctor();  return; }
+  if (subcommand === 'reset')   { cmdReset();   return; }
+  if (subcommand === 'repair')  { cmdRepair();  return; }
+
+  // agent <template> [flags] → agent-templates.mjs --run <template> [flags]
+  if (subcommand === 'agent') {
+    const templateName = positional[1];
+    if (!templateName) {
+      // No template name — fall through to list
+      delegateToHookWithArgs('agent-templates.mjs', ['--list']);
+      return;
+    }
+    const extraFlags = process.argv.slice(4); // skip node, install.mjs, 'agent', <template>
+    delegateToHookWithArgs('agent-templates.mjs', ['--run', templateName, ...extraFlags]);
+    return;
+  }
+
+  // agents → agent-templates.mjs --list
+  if (subcommand === 'agents') {
+    delegateToHookWithArgs('agent-templates.mjs', ['--list']);
+    return;
+  }
+
+  // chain <name> [flags] → agent-chains.mjs --run <name> [flags]
+  if (subcommand === 'chain') {
+    const chainName = positional[1];
+    if (!chainName) {
+      // No chain name given — fall through to list
+      delegateToHookWithArgs('agent-chains.mjs', ['--list']);
+      return;
+    }
+    const extraFlags = process.argv.slice(4); // skip node, install.mjs, 'chain', <name>
+    delegateToHookWithArgs('agent-chains.mjs', ['--run', chainName, ...extraFlags]);
+    return;
+  }
+
+  // chains → agent-chains.mjs --list
+  if (subcommand === 'chains') {
+    delegateToHookWithArgs('agent-chains.mjs', ['--list']);
+    return;
+  }
+
+  // ─── Ship Captain commands ─────────────────────────────────────────────────
+
+  // do "<goal>" → ship-captain.mjs --goal "<goal>" [remaining flags]
+  if (subcommand === 'do') {
+    const goal = positional[1] || '';
+    if (!goal) {
+      console.error('  Usage: npx dual-brain do "<goal>"');
+      process.exit(1);
+    }
+    // Collect remaining flags (everything after the goal string)
+    const extraFlags = process.argv.slice(4).filter(a => a.startsWith('-'));
+    delegateToHookWithArgs('ship-captain.mjs', ['--goal', goal, ...extraFlags]);
+    return;
+  }
+
+  // ship → ship-gate.mjs --ship [remaining flags]
+  if (subcommand === 'ship') {
+    const extraFlags = process.argv.slice(3).filter(a => a.startsWith('-'));
+    delegateToHookWithArgs('ship-gate.mjs', ['--ship', ...extraFlags]);
+    return;
+  }
+
+  // test-run → ship-gate.mjs --test-only
+  if (subcommand === 'test-run') {
+    const extraFlags = process.argv.slice(3).filter(a => a.startsWith('-'));
+    delegateToHookWithArgs('ship-gate.mjs', ['--test-only', ...extraFlags]);
+    return;
+  }
+
+  // diff → ship-gate.mjs --diff-only
+  if (subcommand === 'diff') {
+    delegateToHookWithArgs('ship-gate.mjs', ['--diff-only']);
+    return;
+  }
+
+  // runs → list recent Ship Captain runs from .claude/runs/
+  if (subcommand === 'runs') {
+    const workspace = resolve(process.cwd());
+    const runsDir = join(workspace, '.claude', 'runs');
+    if (!existsSync(runsDir)) {
+      console.log('');
+      console.log('  No Ship Captain runs found.');
+      console.log(`  Run: ${cmd('npx dual-brain do "<goal>"')} to start your first run.`);
+      console.log('');
+      return;
+    }
+    let files;
+    try {
+      files = readdirSync(runsDir).filter(f => f.endsWith('.json')).sort().reverse();
+    } catch {
+      files = [];
+    }
+    if (files.length === 0) {
+      console.log('');
+      console.log('  No run records found in .claude/runs/');
+      console.log('');
+      return;
+    }
+    const rows = [];
+    for (const f of files) {
+      try {
+        const rec = JSON.parse(readFileSync(join(runsDir, f), 'utf8'));
+        const id = rec.id || f.replace('.json', '');
+        const goal = (rec.goal || '').slice(0, 35);
+        const status = rec.status || '?';
+        const steps = Array.isArray(rec.steps) ? rec.steps.length : (rec.step_count || '?');
+        const dur = rec.duration_ms != null ? `${(rec.duration_ms / 1000).toFixed(1)}s` : rec.duration || '?';
+        const date = rec.started_at ? rec.started_at.slice(0, 16).replace('T', ' ') : (rec.date || '?');
+        rows.push({ id, goal, status, steps, dur, date });
+      } catch {}
+    }
+    if (rows.length === 0) {
+      console.log('  No readable run records.');
+      return;
+    }
+    const colW = { id: 14, goal: 37, status: 10, steps: 6, dur: 8, date: 16 };
+    const header = [
+      'ID'.padEnd(colW.id), 'GOAL'.padEnd(colW.goal), 'STATUS'.padEnd(colW.status),
+      'STEPS'.padStart(colW.steps), 'DUR'.padStart(colW.dur), 'DATE'.padEnd(colW.date),
+    ].join('  ');
+    console.log('');
+    console.log(`  Ship Captain Runs (${rows.length})`);
+    console.log('  ' + '─'.repeat(header.length));
+    console.log('  ' + header);
+    console.log('  ' + '─'.repeat(header.length));
+    for (const r of rows) {
+      const line = [
+        String(r.id).padEnd(colW.id), String(r.goal).padEnd(colW.goal),
+        String(r.status).padEnd(colW.status), String(r.steps).padStart(colW.steps),
+        String(r.dur).padStart(colW.dur), String(r.date).padEnd(colW.date),
+      ].join('  ');
+      console.log('  ' + line);
+    }
+    console.log('');
+    return;
+  }
+
+  // resume → find most recent incomplete/failed run, offer to re-execute from the failed step
+  if (subcommand === 'resume') {
+    const workspace = resolve(process.cwd());
+    const runsDir = join(workspace, '.claude', 'runs');
+    if (!existsSync(runsDir)) {
+      console.log('');
+      console.log("  No runs found. Start with: npx dual-brain do '<goal>'");
+      console.log('');
+      return;
+    }
+    let files;
+    try {
+      files = readdirSync(runsDir).filter(f => f.endsWith('.json')).sort().reverse();
+    } catch {
+      files = [];
+    }
+    if (files.length === 0) {
+      console.log('');
+      console.log("  No runs found. Start with: npx dual-brain do '<goal>'");
+      console.log('');
+      return;
+    }
+
+    // Load the most recent run record
+    let rec = null;
+    let recFile = null;
+    try {
+      recFile = files[0];
+      rec = JSON.parse(readFileSync(join(runsDir, recFile), 'utf8'));
+    } catch {}
+
+    if (!rec) {
+      console.log('');
+      console.log("  No runs found. Start with: npx dual-brain do '<goal>'");
+      console.log('');
+      return;
+    }
+
+    const INCOMPLETE_STATUSES = ['failed', 'error', 'partial', 'running', 'pending', 'incomplete', 'aborted'];
+    const steps = Array.isArray(rec.steps) ? rec.steps : [];
+    const isCompleted = (rec.status || '').toLowerCase() === 'completed';
+    const allDone = steps.length > 0 && steps.every(s =>
+      s.status === 'done' || s.status === 'complete' || s.status === 'skipped'
+    );
+
+    if (isCompleted && (allDone || steps.length === 0)) {
+      const goal = rec.goal || '(unknown)';
+      console.log('');
+      console.log('  Last run completed successfully.');
+      console.log(`  Start a new one with: npx dual-brain do '${goal}'`);
+      console.log('');
+      return;
+    }
+
+    // Run has failed/aborted/incomplete — print summary
+    const done = steps.filter(s => s.status === 'done' || s.status === 'complete').length;
+    const failedSteps = steps.filter(s => s.status === 'failed' || s.status === 'error');
+    const incompleteIdx = steps.findIndex(s =>
+      s.status !== 'done' && s.status !== 'complete' && s.status !== 'skipped'
+    );
+    const resumeFromIdx = incompleteIdx >= 0 ? incompleteIdx : steps.length;
+
+    console.log('');
+    console.log('  Last Run State');
+    console.log('  ' + '─'.repeat(50));
+    console.log(`  ID:       ${rec.id || recFile.replace('.json', '')}`);
+    console.log(`  Goal:     ${rec.goal || '(unknown)'}`);
+    console.log(`  Status:   ${rec.status || '(unknown)'}`);
+    if (steps.length > 0) {
+      console.log(`  Steps:    ${done}/${steps.length} done, ${failedSteps.length} failed`);
+      const failedStep = failedSteps[0];
+      if (failedStep) {
+        const fi = steps.indexOf(failedStep);
+        const fname = failedStep.task || failedStep.name || failedStep.label || `step ${fi}`;
+        console.log(`  Failed:   ${fname}`);
+        if (failedStep.error) console.log(`  Error:    ${failedStep.error}`);
+      }
+    }
+    if (rec.started_at) console.log(`  Started:  ${rec.started_at.slice(0, 16).replace('T', ' ')}`);
+    if (rec.error) console.log(`  Error:    ${rec.error}`);
+    console.log('');
+
+    const isResumable = INCOMPLETE_STATUSES.includes((rec.status || '').toLowerCase()) && rec.goal;
+
+    if (!isResumable) {
+      console.log("  Use npx dual-brain do '<goal>' to start fresh");
+      console.log('');
+      return;
+    }
+
+    const stepNum = resumeFromIdx + 1;
+    const totalSteps = steps.length || '?';
+    console.log(`  Resume from step ${stepNum}/${totalSteps}? [Y/n]`);
+
+    const yesFlag = flag('--yes') || flag('-y');
+
+    if (!yesFlag && process.stdin.isTTY) {
+      const { createInterface } = await import('readline');
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await new Promise((res) => {
+        rl.question('  > ', (a) => { rl.close(); res(a.trim()); });
+      });
+      if (answer !== '' && !/^y(es)?$/i.test(answer)) {
+        console.log('');
+        console.log(`  Use npx dual-brain do '${rec.goal}' to start fresh`);
+        console.log('');
+        return;
+      }
+    }
+
+    // Reconstruct flags from stored options in the run record
+    const storedOpts = rec.options || {};
+
+    // Dynamically import and invoke ship-captain's executeShipCaptain
+    const captainPath = resolveHookScript('ship-captain.mjs');
+    if (!captainPath) {
+      console.error('  ship-captain.mjs not found. Run: npx dual-brain to reinstall hooks.');
+      process.exit(1);
+    }
+    const { executeShipCaptain } = await import(captainPath);
+    await executeShipCaptain(rec.goal, {
+      yes: yesFlag || storedOpts.yes || false,
+      yolo: storedOpts.yolo || false,
+      careful: storedOpts.careful || false,
+      noPr: storedOpts.noPr || false,
+      mode: storedOpts.mode || null,
+      resumeFrom: resumeFromIdx,
+      resumedFromId: rec.id,
+    });
+    return;
+  }
+
+  // Delegate hook-backed commands
+  if (subcommand && HOOK_COMMANDS[subcommand]) {
+    delegateToHook(HOOK_COMMANDS[subcommand]);
+    return;
+  }
+
+  // ── replit-tools check — first thing before auth detection or install ──
+  if (!dryRun && !jsonOut) {
+    await checkReplitTools();
+  }
 
   const env = detectEnvironment();
   const mode = resolveMode(env);
@@ -842,23 +1864,34 @@ function main() {
     process.exit(0);
   }
 
-  // Check for replit-tools on Replit
-  if (env.isReplit && !env.hasReplitTools) {
-    console.log('');
-    console.log('  ⚠️  replit-tools not found — recommended for Replit environments.');
-    console.log('  Dual-brain works best alongside replit-tools for persistent auth,');
-    console.log('  session management, and shell integration.');
-    console.log('');
-    console.log(`  Install: ${cmd('npx -y data-tools')}`);
-    console.log('');
+  // Guided auth: print instructions if a provider is missing/not authed
+  // and offer to wait (interactive only)
+  const needsGuidance = printGuidedAuth(env);
+  if (needsGuidance && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI) {
+    await waitForAuth(env);
+    // Re-resolve mode after potential auth
+    Object.assign(mode, resolveMode(env));
   }
 
   const actions = install(env.workspace, env, mode);
   printReport(env, mode, actions);
 
-  // After install, launch the session manager (interactive TTY only)
+  // Always print quick-start block after successful install
+  printQuickStart();
+
+  // Offer to launch control panel (opt-in, interactive TTY only)
   if (process.stdin.isTTY && process.stdout.isTTY && !process.env.CI) {
-    launchPanel();
+    process.stdout.write('  Launch control panel? [y/N] ');
+    const answer = await new Promise((resolve) => {
+      process.stdin.setEncoding('utf8');
+      process.stdin.once('data', (chunk) => resolve(chunk.trim().toLowerCase()));
+      process.stdin.resume();
+    });
+    process.stdin.pause();
+    console.log('');
+    if (answer === 'y' || answer === 'yes') {
+      launchPanel();
+    }
   }
 }