dual-brain 0.2.29 → 0.3.0

package/src/dispatch.mjs

@@ -1,1447 +0,0 @@
-#!/usr/bin/env node
-// dispatch.mjs — Dispatch/execution module for dual-brain.
-// Takes a routing decision and launches the agent via Claude CLI or Codex CLI.
-// CLI: node src/dispatch.mjs --dry-run --provider claude --model sonnet --prompt "fix the bug"
-//      node src/dispatch.mjs --detect-runtime
-// Exports: dispatch, buildCommand, detectRuntime, compressResult, dispatchDualBrain,
-//          validateDispatch, checkWorktreeClean, getRetryBudget,
-//          isInsideClaude, buildNativeDispatch, normalizeResult
-
-import { spawn } from 'node:child_process';
-import { mkdirSync, appendFileSync, existsSync, readFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createHash } from 'node:crypto';
-import { markHot, markDegraded, markHealthy, recordDispatch } from './health.mjs';
-import { redact } from './redact.mjs';
-import { getFailoverOrder } from './decide.mjs';
-import { getTemplate, renderPrompt, quickRender } from './templates.mjs';
-import { compilePacket, shapeForRole } from './context-intel.mjs';
-import { buildContextPack } from './context.mjs';
-import { scoreTask, computeRequiredTier } from './governance.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const USAGE_DIR = join(__dirname, '..', '.dualbrain', 'usage');
-const TIER_TIMEOUT_MS = { search: 60_000, execute: 120_000, think: 180_000 };
-const CLAUDE_MODEL_IDS = { opus: 'claude-opus-4-6', sonnet: 'claude-sonnet-4-6', haiku: 'claude-haiku-4-5-20251001' };
-
-// ─── Specialist prompt loader ─────────────────────────────────────────────────
-
-const SPECIALISTS_DIR = join(__dirname, '..', 'agents', 'specialists');
-
-/**
- * Load specialist registry from agents/specialists/registry.json.
- * Returns null if registry is missing or malformed.
- * @returns {object|null}
- */
-function _loadSpecialistRegistry() {
-  try {
-    const raw = readFileSync(join(SPECIALISTS_DIR, 'registry.json'), 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Read agents/specialists/_base.md and agents/specialists/{specialist}.md,
- * concatenate them (base first, specialist second). Falls back gracefully:
- * - If base is missing, only specialist content is returned.
- * - If specialist file is missing, only base content is returned.
- * - If both are missing, returns an empty string.
- *
- * @param {string} specialist  Specialist key (e.g. 'python', 'security')
- * @returns {string}
- */
-function loadSpecialistPrompt(specialist) {
-  if (!specialist || specialist === 'generic') return '';
-
-  const tryRead = (filePath) => {
-    try { return readFileSync(filePath, 'utf8').trim(); } catch { return ''; }
-  };
-
-  const registry = _loadSpecialistRegistry();
-  const entry = registry?.specialists?.[specialist];
-  const promptFile = entry?.prompt_file ?? `${specialist}.md`;
-
-  const base       = tryRead(join(SPECIALISTS_DIR, '_base.md'));
-  const specific   = tryRead(join(SPECIALISTS_DIR, promptFile));
-
-  const parts = [base, specific].filter(Boolean);
-  return parts.join('\n\n');
-}
-
-// ─── Median dispatch time tracker (in-process, for slow-response detection) ──
-// Rolling window of recent dispatch durations keyed by "provider:modelClass"
-const _durationHistory = new Map();
-const DURATION_WINDOW  = 10; // keep last N durations per model class
-
-function recordDuration(provider, model, durationMs) {
-  const k = `${provider}:${model}`;
-  if (!_durationHistory.has(k)) _durationHistory.set(k, []);
-  const arr = _durationHistory.get(k);
-  arr.push(durationMs);
-  if (arr.length > DURATION_WINDOW) arr.shift();
-}
-
-function medianDuration(provider, model) {
-  const k = `${provider}:${model}`;
-  const arr = _durationHistory.get(k);
-  if (!arr || arr.length < 3) return null; // not enough data
-  const sorted = [...arr].sort((a, b) => a - b);
-  const mid = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0
-    ? (sorted[mid - 1] + sorted[mid]) / 2
-    : sorted[mid];
-}
-
-// Rate-limit error keywords
-const RATE_LIMIT_PATTERNS = /rate.?limit|quota|capacity|too many requests|overloaded|throttl/i;
-
-// ─── Auto-heal failover helpers ───────────────────────────────────────────────
-
-const FAILOVER_LOG_DIR = join(__dirname, '..', '.dualbrain', 'audit');
-
-/** Retryable exit-code-1 patterns: rate limits, quota, capacity, timeouts */
-const RETRYABLE_PATTERNS = /rate.?limit|429|quota.?exceeded|capacity|overloaded|timeout/i;
-
-/** Non-retryable patterns: auth failures, bad input, user cancellation */
-const NON_RETRYABLE_PATTERNS = /unauthorized|forbidden|invalid.?api.?key|authentication|bad.?request|cancelled|canceled/i;
-
-/**
- * Decide if a subprocess result is a retryable failure.
- * Must be exit code 1 (or non-zero) AND match retryable keywords AND NOT match
- * non-retryable keywords.
- * @param {{ exitCode: number, stderr: string, stdout: string }} result
- * @returns {boolean}
- */
-function isRetryableFailure({ exitCode, stderr, stdout }) {
-  if (exitCode === 0) return false;
-  const errText = `${stderr} ${stdout}`.slice(0, 1000);
-  if (NON_RETRYABLE_PATTERNS.test(errText)) return false;
-  return RETRYABLE_PATTERNS.test(errText);
-}
-
-/**
- * Append a failover event to .dualbrain/audit/failover.jsonl.
- * @param {{ from: string, to: string, reason: string, attempt: number }} info
- */
-function logFailover({ from, to, reason, attempt }) {
-  try {
-    mkdirSync(FAILOVER_LOG_DIR, { recursive: true });
-    appendFileSync(
-      join(FAILOVER_LOG_DIR, 'failover.jsonl'),
-      JSON.stringify({ ts: new Date().toISOString(), from, to, reason, attempt }) + '\n',
-    );
-  } catch {}
-}
-
-// ─── Native Claude Code detection ────────────────────────────────────────────
-
-/**
- * Detect whether we are running inside Claude Code (as a subagent or tool call).
- * Checks the CLAUDE_CODE env var or the presence of .claude/settings.json in the project root.
- * @returns {boolean}
- */
-function isInsideClaude() {
-  if (process.env.CLAUDE_CODE) return true;
-  // Walk up from __dirname (src/) to find .claude/settings.json in project root
-  const projectRoot = join(__dirname, '..');
-  return existsSync(join(projectRoot, '.claude', 'settings.json'));
-}
-
-// ─── Tier defaults for maxTurns ──────────────────────────────────────────────
-
-const TIER_MAX_TURNS = { search: 5, execute: 15, think: 10 };
-
-// ─── Agent model mapper ───────────────────────────────────────────────────────
-
-/**
- * Map a model alias or model ID to the canonical agent model name (haiku|sonnet|opus).
- * Falls back to tier-based defaults when no match is found.
- * @param {string} modelAlias  Short alias or full model ID
- * @param {string} [tier]      Tier fallback ('search'|'execute'|'think')
- * @returns {'haiku'|'sonnet'|'opus'}
- */
-function mapToAgentModel(modelAlias, tier) {
-  if (!modelAlias) {
-    const tierDefaults = { search: 'haiku', execute: 'sonnet', think: 'opus' };
-    return tierDefaults[tier] ?? 'sonnet';
-  }
-  const lower = String(modelAlias).toLowerCase();
-  if (lower === 'haiku' || lower.startsWith('claude-3-haiku') || lower.includes('haiku')) return 'haiku';
-  if (lower === 'opus'  || lower.startsWith('claude-opus')   || lower.includes('opus'))  return 'opus';
-  if (lower === 'sonnet'|| lower.startsWith('claude-sonnet') || lower.includes('sonnet')) return 'sonnet';
-  // Tier-based fallback
-  const tierDefaults = { search: 'haiku', execute: 'sonnet', think: 'opus' };
-  return tierDefaults[tier] ?? 'sonnet';
-}
-
-// ─── Native dispatch builder ──────────────────────────────────────────────────
-
-/**
- * Build a structured native Agent tool call descriptor instead of a shell command.
- * The caller (CLI or plugin) is responsible for invoking the Agent tool with this object.
- *
- * @param {object} decision  Routing decision from decide.mjs
- * @param {string} prompt    Task prompt (already redacted)
- * @param {object} [options] Optional extras: worktree, maxTurns
- * @returns {{
- *   type: 'native-agent',
- *   description: string,
- *   model: 'haiku'|'sonnet'|'opus',
- *   prompt: string,
- *   isolation: string|undefined,
- *   maxTurns: number,
- *   disallowedTools: string[],
- *   background: boolean
- * }}
- */
-function buildNativeDispatch(decision, prompt, options = {}) {
-  const tier  = decision.tier  ?? 'execute';
-  const model = mapToAgentModel(decision.model, tier);
-
-  return {
-    type:        'native-agent',
-    description: `dual-brain ${tier}: ${String(prompt).slice(0, 50)}`,
-    model,
-    prompt,
-    isolation:      options.worktree ? 'worktree' : undefined,
-    maxTurns:       options.maxTurns ?? TIER_MAX_TURNS[tier] ?? 15,
-    disallowedTools: tier === 'search' ? ['Edit', 'Write', 'NotebookEdit'] : [],
-    background:     false,
-  };
-}
-
-// ─── Result normalizer ────────────────────────────────────────────────────────
-
-/**
- * Normalize a raw result from either a native Agent call or subprocess stdout
- * into a common result shape.
- *
- * @param {object|string} rawResult  Raw result from agent or subprocess
- * @param {'native-agent'|'subprocess'} dispatchType
- * @returns {{
- *   status: 'success'|'failure'|'partial',
- *   provider: string,
- *   model: string,
- *   tier: string,
- *   filesChanged: string[],
- *   filesFound: string[],
- *   testsRun: number,
- *   edgeCases: string[],
- *   tokensUsed: { input: number, output: number },
- *   errors: string[],
- *   rawOutput: string
- * }}
- */
-function normalizeResult(rawResult, dispatchType) {
-  const raw = rawResult ?? {};
-
-  // Determine raw output string regardless of dispatch type
-  let rawOutput = '';
-  if (typeof raw === 'string') {
-    rawOutput = raw;
-  } else if (typeof raw.stdout === 'string') {
-    rawOutput = raw.stdout;
-  } else if (typeof raw.output === 'string') {
-    rawOutput = raw.output;
-  } else if (typeof raw.result === 'string') {
-    rawOutput = raw.result;
-  } else {
-    try { rawOutput = JSON.stringify(raw); } catch { rawOutput = String(raw); }
-  }
-
-  // Determine status
-  let status = 'success';
-  if (dispatchType === 'subprocess') {
-    const exitCode = typeof raw.exitCode === 'number' ? raw.exitCode : (raw.code ?? null);
-    if (exitCode !== null) {
-      status = exitCode === 0 ? 'success' : 'failure';
-    } else if (raw.status === 'failed' || raw.status === 'error') {
-      status = 'failure';
-    } else if (raw.status === 'partial') {
-      status = 'partial';
-    }
-  } else {
-    // native-agent
-    if (raw.status === 'failed' || raw.status === 'error' || raw.error) {
-      status = 'failure';
-    } else if (raw.status === 'partial') {
-      status = 'partial';
-    }
-  }
-
-  // Extract fields from raw
-  const provider = raw.provider ?? (dispatchType === 'native-agent' ? 'claude' : 'unknown');
-  const model    = raw.model    ?? (raw.agentModel ?? 'unknown');
-  const tier     = raw.tier     ?? 'execute';
-
-  // Files changed / found — best-effort extraction from raw output
-  const filesChangedSet = new Set();
-  const filesFoundSet   = new Set();
-  if (Array.isArray(raw.filesChanged)) raw.filesChanged.forEach(f => filesChangedSet.add(f));
-  if (Array.isArray(raw.filesFound))   raw.filesFound.forEach(f => filesFoundSet.add(f));
-
-  // Scan rawOutput for file hints
-  const changeMatches = rawOutput.matchAll(/(?:changed|edited|wrote|created|modified)\s+([^\s,]+\.[a-z]{1,6})/gi);
-  for (const m of changeMatches) filesChangedSet.add(m[1]);
-  const foundMatches = rawOutput.matchAll(/(?:found|located|in)\s+([^\s,]+\.[a-z]{1,6})/gi);
-  for (const m of foundMatches) filesFoundSet.add(m[1]);
-
-  // Tests run
-  let testsRun = raw.testsRun ?? 0;
-  if (testsRun === 0) {
-    const testMatch = rawOutput.match(/(\d+)\s+(?:tests?|specs?)\s+(?:passed|run|ran)/i);
-    if (testMatch) testsRun = parseInt(testMatch[1], 10);
-  }
-
-  // Edge cases
-  const edgeCases = Array.isArray(raw.edgeCases) ? raw.edgeCases : [];
-
-  // Token usage
-  const tokensUsed = {
-    input:  raw.tokensUsed?.input  ?? raw.usage?.inputTokens  ?? raw.usage?.input_tokens  ?? 0,
-    output: raw.tokensUsed?.output ?? raw.usage?.outputTokens ?? raw.usage?.output_tokens ?? 0,
-  };
-
-  // Errors
-  const errors = [];
-  if (Array.isArray(raw.errors)) errors.push(...raw.errors);
-  if (typeof raw.error === 'string' && raw.error) errors.push(raw.error);
-  if (typeof raw.stderr === 'string' && raw.stderr) errors.push(raw.stderr.slice(0, 200));
-
-  return {
-    status,
-    provider,
-    model,
-    tier,
-    filesChanged: [...filesChangedSet],
-    filesFound:   [...filesFoundSet],
-    testsRun,
-    edgeCases,
-    tokensUsed,
-    errors,
-    rawOutput: rawOutput.slice(0, 2000),
-  };
-}
-
-// ─── Runtime detection (cached) ───────────────────────────────────────────────
-
-let _runtimeCache = null;
-
-async function detectRuntime() {
-  if (_runtimeCache) return _runtimeCache;
-
-  const check = (cmd) => new Promise((resolve) => {
-    const p = spawn(cmd, ['--version'], { stdio: 'pipe' });
-    p.on('error', () => resolve(false));
-    p.on('close', (code) => resolve(code === 0));
-    setTimeout(() => { try { p.kill(); } catch {} resolve(false); }, 3000);
-  });
-
-  const [claudeAvailable, codexAvailable] = await Promise.all([
-    check('claude'),
-    check('codex'),
-  ]);
-
-  const runtime =
-    claudeAvailable && codexAvailable ? 'claude-code'
-    : claudeAvailable                 ? 'claude-code'
-    : codexAvailable                  ? 'codex-cli'
-    : 'none';
-
-  _runtimeCache = { claudeAvailable, codexAvailable, runtime };
-  return _runtimeCache;
-}
-
-// ─── Feature 1: Model validation + graceful fallback ─────────────────────────
-
-/** Valid CLI model flags per provider */
-const VALID_MODELS = {
-  claude: ['opus', 'sonnet', 'haiku'],
-  openai: ['o4-mini', 'o3', 'o1', 'o1-mini', 'gpt-4o', 'gpt-4o-mini', 'gpt-4.1', 'gpt-4.1-mini', 'gpt-4-turbo'],
-};
-
-/** Safest default model for a given provider + tier */
-function _safeModel(provider, tier) {
-  if (provider === 'claude') {
-    return tier === 'search' ? 'haiku' : 'sonnet';
-  }
-  return 'o4-mini';
-}
-
-/**
- * Validate a routing decision against CLI availability and valid model lists.
- * Returns either a (possibly corrected) decision object, or an error sentinel
- * `{ _error: string }` when no CLI is available at all.
- *
- * @param {object} decision
- * @param {{ claudeAvailable: boolean, codexAvailable: boolean }} rt  Runtime info
- * @returns {object}  Corrected decision or `{ _error: string }`
- */
-function validateDispatch(decision, rt) {
-  let { provider = 'claude', model, tier = 'execute' } = decision;
-
-  // ── CLI availability ──────────────────────────────────────────────────────
-  const claudeOk = rt.claudeAvailable;
-  const codexOk  = rt.codexAvailable;
-
-  if (!claudeOk && !codexOk) {
-    return { _error: 'No AI CLI available. Install claude or codex CLI.' };
-  }
-
-  if (provider === 'claude' && !claudeOk && codexOk) {
-    process.stderr.write('[dual-brain] Claude unavailable, falling back to OpenAI (codex)\n');
-    provider = 'openai';
-  } else if (provider === 'openai' && !codexOk && claudeOk) {
-    process.stderr.write('[dual-brain] OpenAI unavailable, falling back to Claude (claude)\n');
-    provider = 'claude';
-  }
-
-  // ── Model validation ──────────────────────────────────────────────────────
-  const validList = VALID_MODELS[provider] ?? [];
-  if (model && !validList.includes(model)) {
-    const safe = _safeModel(provider, tier);
-    process.stderr.write(`[dual-brain] Model "${model}" not valid for ${provider} CLI; defaulting to "${safe}"\n`);
-    model = safe;
-  }
-
-  return { ...decision, provider, model };
-}
-
-// ─── Feature 2: Dirty-worktree guard ─────────────────────────────────────────
-
-/**
- * Simple glob match:
- *  - `dir/*`  → prefix match on `dir/`
- *  - `*.ext`  → suffix match on `.ext`
- *  - otherwise → exact match
- */
-function _globMatch(pattern, filePath) {
-  if (pattern.endsWith('/*')) {
-    const prefix = pattern.slice(0, -1); // 'src/auth/'
-    return filePath.startsWith(prefix);
-  }
-  if (pattern.startsWith('*.')) {
-    const suffix = pattern.slice(1); // '.mjs'
-    return filePath.endsWith(suffix);
-  }
-  return filePath === pattern;
-}
-
-/**
- * Check whether dirty worktree files overlap with the agent's ownership globs.
- *
- * @param {string[]} owns  Glob patterns for files the agent will touch
- * @param {string}   cwd   Working directory for git
- * @returns {Promise<{ safe: boolean, conflicts?: string[] }>}
- */
-async function checkWorktreeClean(owns, cwd) {
-  if (!owns || owns.length === 0) return { safe: true };
-
-  const dirty = await new Promise((resolve) => {
-    const proc = spawn('git', ['status', '--porcelain', '-u'], {
-      cwd: cwd || process.cwd(),
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let out = '';
-    proc.stdout.on('data', (d) => { out += d; });
-    proc.on('close', () => {
-      // Each line: "XY path" — grab the path part (columns 4+, after "XY ")
-      const files = out.split('\n')
-        .map(l => l.slice(3).trim())
-        .filter(Boolean);
-      resolve(files);
-    });
-    proc.on('error', () => resolve([])); // git not available → skip guard
-  });
-
-  if (dirty.length === 0) return { safe: true };
-
-  const conflicts = dirty.filter(f =>
-    owns.some(pattern => _globMatch(pattern, f))
-  );
-
-  if (conflicts.length > 0) return { safe: false, conflicts };
-  return { safe: true };
-}
-
-// ─── Feature 3: Retry budget ──────────────────────────────────────────────────
-
-/** Per-prompt retry count (keyed by first 16 hex chars of SHA-256 of prompt) */
-const _retryCount = new Map();
-
-/** Recent dispatch timestamps for the 5-minute window rate-limit */
-const _recentDispatches = [];
-
-const MAX_RETRIES_PER_TASK    = 2;
-const MAX_DISPATCHES_PER_5MIN = 5;
-const WINDOW_MS = 5 * 60 * 1000;
-
-function _promptKey(prompt) {
-  return createHash('sha256').update(String(prompt)).digest('hex').slice(0, 16);
-}
-
-/**
- * Check whether this dispatch is within budget.
- * @param {string} prompt
- * @returns {{ allowed: boolean, reason?: string }}
- */
-function _checkRetryBudget(prompt) {
-  const now = Date.now();
-
-  // Evict dispatch timestamps older than 5 minutes
-  while (_recentDispatches.length > 0 && now - _recentDispatches[0] > WINDOW_MS) {
-    _recentDispatches.shift();
-  }
-
-  if (_recentDispatches.length >= MAX_DISPATCHES_PER_5MIN) {
-    return { allowed: false, reason: 'Retry budget exhausted. Wait or adjust task.' };
-  }
-
-  const key   = _promptKey(prompt);
-  const count = _retryCount.get(key) ?? 0;
-  if (count > MAX_RETRIES_PER_TASK) {
-    return { allowed: false, reason: 'Retry budget exhausted. Wait or adjust task.' };
-  }
-
-  return { allowed: true };
-}
-
-function _recordDispatchBudget(prompt) {
-  _recentDispatches.push(Date.now());
-  const key = _promptKey(prompt);
-  _retryCount.set(key, (_retryCount.get(key) ?? 0) + 1);
-}
-
-/**
- * Return current retry budget state for status display.
- * @returns {object}
- */
-function getRetryBudget() {
-  const now = Date.now();
-  const active = _recentDispatches.filter(t => now - t <= WINDOW_MS).length;
-  return {
-    perTaskRetries:   Object.fromEntries(_retryCount),
-    recentDispatches: active,
-    windowMs:         WINDOW_MS,
-    maxPerTask:       MAX_RETRIES_PER_TASK,
-    maxPerWindow:     MAX_DISPATCHES_PER_5MIN,
-  };
-}
-
-// ─── Preflight auth check ─────────────────────────────────────────────────────
-
-/**
- * Verify a provider CLI is present and (optionally) responds to --version.
- * Uses `which` for the fast path and a 3s-capped --version call to confirm.
- *
- * @param {'claude'|'openai'} provider
- * @param {string} [cwd]  Working directory (unused, kept for signature parity)
- * @returns {Promise<{ ready: boolean, provider: string, error?: string, suggestion?: string }>}
- */
-async function preflightAuth(provider, _cwd) {
-  const bin = provider === 'openai' ? 'codex' : 'claude';
-
-  // Fast path: check binary existence with `which`
-  const whichResult = await new Promise((resolve) => {
-    const p = spawn('which', [bin], { stdio: 'pipe' });
-    p.on('error', () => resolve(false));
-    p.on('close', (code) => resolve(code === 0));
-    setTimeout(() => { try { p.kill(); } catch {} resolve(false); }, 2000);
-  });
-
-  if (!whichResult) {
-    const installHint = provider === 'openai'
-      ? 'Install: npm install -g @openai/codex'
-      : 'Install: npm install -g @anthropic-ai/claude-code';
-    return {
-      ready:      false,
-      provider,
-      error:      `${bin} CLI not found in PATH`,
-      suggestion: installHint,
-    };
-  }
-
-  // Version check: confirms the binary actually runs (catches broken installs)
-  const versionOk = await new Promise((resolve) => {
-    const p = spawn(bin, ['--version'], { stdio: 'pipe' });
-    p.on('error', () => resolve(false));
-    p.on('close', (code) => resolve(code === 0));
-    setTimeout(() => { try { p.kill(); } catch {} resolve(false); }, 3000);
-  });
-
-  if (!versionOk) {
-    const loginHint = provider === 'openai' ? 'Run: codex login' : 'Run: claude login';
-    return {
-      ready:      false,
-      provider,
-      error:      `${bin} --version failed (auth may have expired)`,
-      suggestion: loginHint,
-    };
-  }
-
-  return { ready: true, provider };
-}
-
-// ─── Command builder ──────────────────────────────────────────────────────────
-
-function buildCommand(decision, prompt, files = [], _cwd) {
-  const provider = decision?.provider ?? 'claude';
-  const modelAlias = decision?.model ?? 'sonnet';
-  const effort = decision?.effort ?? null;
-  const sandbox = decision?.sandbox ?? 'danger-full-access';
-
-  if (provider === 'claude') {
-    const modelId = CLAUDE_MODEL_IDS[modelAlias] ?? modelAlias;
-    const cmd = ['claude', '--model', modelId, '--print', '--output-format', 'json', '-p', prompt];
-    if (effort) cmd.push('--effort', effort);
-    return cmd;
-  }
-
-  // openai / codex
-  const cmd = ['codex', 'exec', '-m', modelAlias, '-s', sandbox, prompt];
-  if (effort) cmd.push('-c', `reasoning.effort="${effort}"`);
-  return cmd;
-}
-
-// ─── Usage recorder ───────────────────────────────────────────────────────────
-function recordUsage(entry) {
-  try {
-    mkdirSync(USAGE_DIR, { recursive: true });
-    const date = new Date().toISOString().slice(0, 10);
-    appendFileSync(
-      join(USAGE_DIR, `${date}.jsonl`),
-      JSON.stringify({ timestamp: new Date().toISOString(), ...entry }) + '\n',
-    );
-  } catch {}
-}
-
-// ─── Result compressor ────────────────────────────────────────────────────────
-function compressResult(rawOutput = '', maxLength = 300) {
-  if (!rawOutput) return '(no output)';
-
-  // Try JSON parse first (claude --output-format json)
-  try {
-    const parsed = JSON.parse(rawOutput);
-    const text = parsed?.result ?? parsed?.content ?? parsed?.message ?? JSON.stringify(parsed);
-    return String(text).slice(0, maxLength);
-  } catch {}
-
-  // Strip code blocks
-  let cleaned = rawOutput
-    .replace(/```[\s\S]*?```/g, '[code block]')
-    .replace(/^\s+at\s+.+$/gm, '')          // stack trace lines
-    .replace(/\n{3,}/g, '\n\n')             // collapse blank lines
-    .trim();
-
-  // Extract first 2 meaningful sentences
-  const sentences = cleaned.match(/[^.!?\n]+[.!?\n]+/g) ?? [cleaned];
-  const meaningful = sentences.filter(s => s.trim().length > 15).slice(0, 2);
-  const head = meaningful.join(' ').trim() || cleaned.slice(0, maxLength);
-
-  // Append file-change hints if present
-  const fileHints = rawOutput.match(/(?:changed|edited|wrote|created|modified)\s+([^\s,]+\.[a-z]+)/gi) ?? [];
-  const suffix = fileHints.length ? ` | files: ${[...new Set(fileHints)].slice(0, 3).join(', ')}` : '';
-
-  return (head + suffix).slice(0, maxLength);
-}
-
-// ─── Core runner ──────────────────────────────────────────────────────────────
-function runProcess(cmd, cwd, timeoutMs, env) {
-  return new Promise((resolve) => {
-    const [bin, ...args] = cmd;
-    const start = Date.now();
-    let stdout = '';
-    let stderr = '';
-
-    const spawnEnv = env ? { ...process.env, ...env } : undefined;
-    const proc = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], ...(spawnEnv ? { env: spawnEnv } : {}) });
-
-    proc.stdout.on('data', (d) => { stdout += d; });
-    proc.stderr.on('data', (d) => { stderr += d; });
-
-    const killer = setTimeout(() => {
-      try { proc.kill('SIGTERM'); } catch {}
-      setTimeout(() => { try { proc.kill('SIGKILL'); } catch {} }, 5000);
-    }, timeoutMs);
-
-    proc.on('close', (code) => {
-      clearTimeout(killer);
-      resolve({ exitCode: code ?? 1, stdout: stdout.trim(), stderr: stderr.trim(), durationMs: Date.now() - start });
-    });
-
-    proc.on('error', (err) => {
-      clearTimeout(killer);
-      resolve({ exitCode: 1, stdout: '', stderr: err.message, durationMs: Date.now() - start });
-    });
-  });
-}
-
-// ─── Template-based prompt rendering ─────────────────────────────────────────
-
-function _renderTemplatedPrompt(prompt, decision, context = {}) {
-  const tier = decision.tier ?? 'execute';
-  const template = getTemplate(tier);
-  if (!template) return prompt;
-
-  if (decision.contract) {
-    const rendered = renderPrompt(tier, decision.contract, context);
-    if (rendered.valid) return rendered.prompt;
-  }
-
-  const rendered = quickRender(tier, prompt, {
-    scope: decision.owns || decision.scope || [],
-    files: decision.files || [],
-    risk: decision.risk || 'medium',
-    criteria: decision.acceptanceCriteria || [],
-    nonGoals: decision.nonGoals || [],
-    context: decision.taskContext || '',
-  });
-
-  return rendered.valid ? rendered.prompt : prompt;
-}
-
-// ─── Dispatch marker ─────────────────────────────────────────────────────────
-// Prepend a marker to every prompt that goes through the official dispatch pipeline.
-// The enforce-tier hook checks for this marker to distinguish legitimate dispatches
-// from raw Agent calls made by the HEAD that bypass the dual-brain pipeline.
-// Format: <!-- dual-brain-dispatch:<runId>|tier:<tier>|model:<model>|risk:<risk>|req:<requiredTier> -->
-// runId is a short timestamp-based ID; governance fields enable over-provisioning validation.
-
-let _dispatchRunId = null;
-
-function _getDispatchRunId() {
-  if (!_dispatchRunId) {
-    // Generate once per process: timestamp + random suffix
-    _dispatchRunId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
-  }
-  return _dispatchRunId;
-}
-
-function _prependDispatchMarker(prompt, decision = {}) {
-  const runId = _getDispatchRunId();
-  const tier = decision.tier || 'execute';
-  const model = decision.model || 'sonnet';
-  const risk = decision.risk || 'medium';
-  const requiredTier = decision._requiredTier || '';
-  const marker = `<!-- dual-brain-dispatch:${runId}|tier:${tier}|model:${model}|risk:${risk}|req:${requiredTier} -->`;
-  return `${marker}\n${prompt}`;
-}
-
-// ─── Related session age label ────────────────────────────────────────────────
-
-/**
- * Human-readable age label for a related session date string.
- * @param {string} isoDate
- * @returns {string}
- */
-function _relatedSessionAge(isoDate) {
-  const diff = Date.now() - Date.parse(isoDate);
-  const mins = Math.floor(diff / 60000);
-  if (mins < 60) return `${mins}m ago`;
-  const hours = Math.floor(mins / 60);
-  if (hours < 24) return `${hours}h ago`;
-  const days = Math.floor(hours / 24);
-  return `${days}d ago`;
-}
-
-// ─── Main dispatch ────────────────────────────────────────────────────────────
-async function dispatch(input = {}) {
-  const { files = [], cwd = process.cwd(), dryRun = false, verbose = false } = input;
-  let decision = input.decision ?? {};
-  let { prompt } = input;
-
-  if (!prompt) throw new Error('prompt is required');
-
-  // Safety gate: redact secrets before anything reaches a subprocess or log
-  prompt = redact(prompt);
-
-  // ── Template-based prompt rendering ─────────────────────────────────────────
-  // When a tier and/or contract are present, render through templates.mjs for
-  // structured, typed prompts. Falls back to raw prompt when no template matches.
-  prompt = _renderTemplatedPrompt(prompt, decision);
-
-  // ── Context intelligence: model-specific prompt shaping ─────────────────────
-  // When we have files and a target model, shape the prompt context for optimal
-  // model consumption. This adds structured context without replacing the template output.
-  if (files.length > 0 || decision.tier) {
-    try {
-      const pack = await buildContextPack(prompt, files, cwd);
-      const role = decision.tier === 'think' ? 'thinker'
-                 : decision.tier === 'review' ? 'reviewer'
-                 : 'worker';
-      const targetModel = decision.model || 'sonnet';
-      const tokenBudget = role === 'thinker' ? 3000
-                        : role === 'reviewer' ? 4000
-                        : 8000;
-      const { shaped, tokenEstimate } = shapeForRole(pack, role, targetModel, tokenBudget);
-      if (shaped && tokenEstimate > 0) {
-        prompt = `${shaped}\n\n---\n\n${prompt}`;
-        if (verbose) process.stderr.write(`[dual-brain] context-intel: ${role} packet shaped for ${targetModel} (~${tokenEstimate} tokens)\n`);
-      }
-    } catch { /* non-blocking — context shaping failure never prevents dispatch */ }
-  }
-  // ── End context intelligence ─────────────────────────────────────────────────
-
-  // ── Resume brief injection ───────────────────────────────────────────────────
-  // Inject the last session's receipt as context when no situationBrief is already set.
-  // This closes the receipt → brief → next session loop automatically.
-  // Falls back to continuity.mjs handoffs when receipt.mjs returns nothing.
-  if (!input.situationBrief) {
-    try {
-      const { buildResumeBrief } = await import('./receipt.mjs');
-      const brief = buildResumeBrief(cwd);
-      if (brief) {
-        input = { ...input, situationBrief: brief };
-      }
-    } catch { /* non-blocking */ }
-
-    // Provider-aware continuity fallback: adapts resume format for target provider
-    if (!input.situationBrief) {
-      try {
-        const { buildProviderResumeBrief } = await import('./provider-context.mjs');
-        const targetProvider = decision.provider || 'claude';
-        const providerBrief = buildProviderResumeBrief(cwd, targetProvider);
-        if (providerBrief) {
-          input = { ...input, situationBrief: providerBrief };
-        }
-      } catch { /* non-blocking */ }
-
-      // Legacy fallback: continuity.mjs handoff (provider-unaware)
-      if (!input.situationBrief) {
-        try {
-          const { buildResumeBrief: buildHandoffBrief } = await import('./continuity.mjs');
-          const handoffBrief = buildHandoffBrief(cwd);
-          if (handoffBrief) {
-            input = { ...input, situationBrief: handoffBrief };
-          }
-        } catch { /* non-blocking */ }
-      }
-    }
-  }
-  // ── End resume brief injection ───────────────────────────────────────────────
-
-  // ── Related session context injection ────────────────────────────────────────
-  // Find past sessions related to this task and prepend a context block.
-  // Only injected when confidence is high (score > 5). Fast: index-only, no JSONL parsing.
-  if (!input._skipRelatedContext) {
-    try {
-      const { findRelatedSessions } = await import('./session.mjs');
-      const related = findRelatedSessions(prompt, files, cwd);
-      const highConfidence = related.filter(r => r.score > 5);
-      if (highConfidence.length > 0) {
-        const lines = highConfidence.map(r => {
-          const dateLabel = r.date ? _relatedSessionAge(r.date) : null;
-          const datePart  = dateLabel ? `, ${dateLabel}` : '';
-          const msgPart   = r.messageCount > 0 ? `, ${r.messageCount} messages` : '';
-          const fileList  = r.matchedFiles.length > 0
-            ? `: touched ${r.matchedFiles.map(f => f.split('/').pop()).join(', ')}`
-            : '';
-          return `- "${r.smartName}"${datePart}${msgPart}${fileList}`;
-        });
-        const contextBlock = `[Prior context from related sessions:]\n${lines.join('\n')}\n[End prior context]\n\n`;
-        prompt = contextBlock + prompt;
-        if (verbose) process.stderr.write(`[dual-brain] injected related session context (${highConfidence.length} sessions)\n`);
-      }
-    } catch { /* non-fatal — never block dispatch */ }
-  }
-  // ── End related session context ──────────────────────────────────────────────
-
-  // Stamp the prompt with the dispatch marker so enforce-tier.mjs can recognise
-  // that this agent call came through the official pipeline.
-  // Compute required tier for governance validation
-  try {
-    const scores = scoreTask({ intent: decision.tier, risk: decision.risk, files, objective: prompt.slice(0, 200) });
-    decision = { ...decision, _requiredTier: computeRequiredTier(scores) };
-  } catch { /* non-blocking */ }
-  prompt = _prependDispatchMarker(prompt, decision);
-
-  // ── Situation brief injection ────────────────────────────────────────────────
-  // Prepend a compact project-state summary when provided by the pipeline.
-  // This gives every dispatched agent immediate context about the project reality.
-  const situationBrief = typeof input.situationBrief === 'string' && input.situationBrief.trim()
-    ? input.situationBrief.trim()
-    : null;
-  if (situationBrief) {
-    prompt = `[SITUATION BRIEF]\n${situationBrief}\n[END BRIEF]\n\n${prompt}`;
-  }
-  // ── End situation brief ──────────────────────────────────────────────────────
-
-  // ── Specialist prompt injection ──────────────────────────────────────────────
-  const specialist = decision.specialist && decision.specialist !== 'generic'
-    ? decision.specialist
-    : null;
-
-  if (specialist) {
-    const specialistPrompt = loadSpecialistPrompt(specialist);
-    if (specialistPrompt) {
-      prompt = `${specialistPrompt}\n\n---\n\n${prompt}`;
-      if (verbose) process.stderr.write(`[dual-brain] specialist: ${specialist}\n`);
-    }
-
-    // Apply tier_bias from registry if decision didn't already pin a tier
-    if (!decision.tier) {
-      const registry = _loadSpecialistRegistry();
-      const tierBias = registry?.specialists?.[specialist]?.tier_bias;
-      if (tierBias) {
-        decision = { ...decision, tier: tierBias };
-        if (verbose) process.stderr.write(`[dual-brain] specialist tier_bias applied: ${tierBias}\n`);
-      }
-    }
-  }
-  // ── End specialist injection ─────────────────────────────────────────────────
-
-  // ── Plugin hint injection (Codex path) ──────────────────────────────────────
-  // When dispatching to OpenAI/Codex, check if any Codex plugins match the task
-  // and append an advisory hint so the agent can choose to use them.
-  // Uses dynamic import so failure is always non-fatal.
-  const targetProvider = decision.provider ?? 'claude';
-  if (targetProvider === 'openai') {
-    try {
-      const { matchPluginsForTask } = await import('./replit.mjs');
-      const matched = matchPluginsForTask(prompt, undefined, cwd);
-      if (matched.length > 0) {
-        const pluginNames = matched.slice(0, 3).map(m => m.plugin.id).join(', ');
-        const hint = `\n\n[Available Codex plugins for this task: ${pluginNames}. Consider using the matching plugin for direct API access.]`;
-        prompt = prompt + hint;
-        if (verbose) process.stderr.write(`[dual-brain] plugin hint injected: ${pluginNames}\n`);
-      }
-    } catch { /* non-fatal — never block dispatch */ }
-  }
-  // ── End plugin hint injection ────────────────────────────────────────────────
-
-  const tier     = decision.tier ?? 'execute';
-  const timeoutMs = TIER_TIMEOUT_MS[tier] ?? 120_000;
-
-  // ── Feature 3: Retry budget check ────────────────────────────────────────
-  const budget = _checkRetryBudget(prompt);
-  if (!budget.allowed) {
-    return {
-      status: 'error',
-      provider: decision.provider ?? 'claude',
-      model: decision.model ?? 'sonnet',
-      command: null,
-      exitCode: null,
-      summary: budget.reason,
-      durationMs: 0,
-      usage: null,
-      error: budget.reason,
-    };
-  }
-
-  // ── Feature 1: Validate dispatch (CLI availability + model) ──────────────
-  const rt = await detectRuntime();
-  const validated = validateDispatch({ ...decision, tier }, rt);
-
-  if (validated._error) {
-    return {
-      status: 'error',
-      provider: decision.provider ?? 'claude',
-      model: decision.model ?? 'sonnet',
-      command: null,
-      exitCode: null,
-      summary: validated._error,
-      durationMs: 0,
-      usage: null,
-      error: validated._error,
-    };
-  }
-
-  const effectiveProvider = validated.provider;
-  let effectiveModel    = validated.model ?? decision.model ?? 'sonnet';
-  let effectiveDecision = { ...validated };
-
-  // modelSuggestion influence: if the pipeline provided a model suggestion from models.mjs,
-  // apply it when the current model is a tier default/fallback (not an explicit override).
-  // The suggestion is advisory — it only applies when the decision didn't pin a specific model.
-  if (input.modelSuggestion?.model && effectiveProvider === 'claude') {
-    const TIER_DEFAULTS = new Set(['haiku', 'sonnet', 'opus']);
-    const decisionModelExplicit = decision._explicit?.model ?? false;
-    const isDefault = !decisionModelExplicit && TIER_DEFAULTS.has(effectiveModel);
-    if (isDefault) {
-      const suggestedAlias = mapToAgentModel(input.modelSuggestion.model, effectiveDecision.tier ?? 'execute');
-      const validList = VALID_MODELS[effectiveProvider] ?? [];
-      if (validList.includes(suggestedAlias)) {
-        effectiveModel = suggestedAlias;
-        effectiveDecision = { ...effectiveDecision, model: suggestedAlias };
-        if (verbose) process.stderr.write(`\x1b[2m[dual-brain] modelSuggestion applied: ${suggestedAlias} (${input.modelSuggestion.reason})\x1b[0m\n`);
-      }
-    }
-  }
-
-  // ── Preflight auth check ─────────────────────────────────────────────────
-  // Verify the target provider CLI is present and responsive before dispatching.
-  // Runs after model/provider resolution so we check the effective provider.
-  const preflight = await preflightAuth(effectiveProvider, cwd);
-  if (!preflight.ready) {
-    // Check if the other provider is available as a fallback
-    const otherProvider = effectiveProvider === 'claude' ? 'openai' : 'claude';
-    const otherPreflight = await preflightAuth(otherProvider, cwd);
-    const fallbackNote = otherPreflight.ready
-      ? ` Fallback available: ${otherProvider}.`
-      : '';
-    const errMsg = `${preflight.error}. ${preflight.suggestion}${fallbackNote}`;
-    return {
-      status:        'error',
-      provider:      effectiveProvider,
-      model:         effectiveModel,
-      command:       null,
-      exitCode:      null,
-      summary:       errMsg,
-      durationMs:    0,
-      usage:         null,
-      error:         errMsg,
-      authVerified:  false,
-      suggestion:    preflight.suggestion,
-    };
-  }
-  // ── End preflight auth check ─────────────────────────────────────────────
-
-  // ── Feature 2: Dirty-worktree guard for execute-tier dispatches ──────────
-  if (tier === 'execute' && decision.owns && !decision._force) {
-    const wtCheck = await checkWorktreeClean(decision.owns, cwd);
-    if (!wtCheck.safe) {
-      const msg = `Uncommitted changes conflict with agent scope: ${wtCheck.conflicts.join(', ')}. Commit or stash before dispatching.`;
-      return {
-        status: 'error',
-        provider: effectiveProvider,
-        model: effectiveModel,
-        command: null,
-        exitCode: null,
-        summary: msg,
-        durationMs: 0,
-        usage: null,
-        error: msg,
-      };
-    }
-  }
-
-  // ── Worktree isolation decision ──────────────────────────────────────────────
-  // Compute whether this dispatch should run in an isolated worktree based on
-  // risk level, file-edit volume, and security/auth signals in the prompt.
-  const SECURITY_PATTERN = /\b(auth|secret|token|credential|password|key|oauth|jwt|session|permission|role|acl)\b/i;
-  const decisionRisk        = (decision.risk ?? 'low').toLowerCase();
-  const decisionFilesEst    = decision.filesEstimate ?? 0;
-  const riskIsElevated      = decisionRisk === 'medium' || decisionRisk === 'high' || decisionRisk === 'critical';
-  const manyFiles           = decisionFilesEst >= 3;
-  const hasSecurity         = SECURITY_PATTERN.test(prompt);
-  const useWorktree         = input.useWorktree ?? (riskIsElevated || manyFiles || hasSecurity);
-
-  // Propagate useWorktree onto effectiveDecision so callers can inspect it
-  if (useWorktree) {
-    effectiveDecision = { ...effectiveDecision, useWorktree: true };
-  }
-  // ── End worktree isolation decision ─────────────────────────────────────────
-
-  // ── Native Claude Code dispatch ──────────────────────────────────────────────
-  // When running inside Claude Code AND the provider is claude, execute via the
-  // claude CLI directly (foreground subprocess) so results are captured and returned.
-  // DUAL_BRAIN_DISPATCH=1 is set so the enforce-tier hook allows this agent call.
-  if (isInsideClaude() && effectiveProvider === 'claude') {
-    const nativeDescriptor = buildNativeDispatch(
-      effectiveDecision,
-      prompt,
-      { worktree: useWorktree, maxTurns: input.maxTurns },
-    );
-
-    const command = buildCommand(effectiveDecision, prompt, files, cwd);
-
-    if (dryRun) {
-      return {
-        status:        'dry-run',
-        provider:      effectiveProvider,
-        model:         effectiveModel,
-        specialist:    specialist ?? 'generic',
-        command,
-        nativeDispatch: nativeDescriptor,
-        exitCode:      null,
-        summary:       null,
-        durationMs:    0,
-        usage:         null,
-        error:         null,
-        authVerified:  true,
-      };
-    }
-
-    _recordDispatchBudget(prompt);
-
-    const dispatchEnv = { DUAL_BRAIN_DISPATCH: '1' };
-
-    // ── Auto-heal failover retry loop (native Claude path) ────────────────
-    const MAX_FAILOVER_ATTEMPTS = 2;
-    let currentProvider = effectiveProvider;
-    let currentModel    = effectiveModel;
-    let currentDecision = effectiveDecision;
-    let currentCommand  = command;
-    let lastRaw;
-
-    for (let attempt = 0; attempt <= MAX_FAILOVER_ATTEMPTS; attempt++) {
-      lastRaw = await runProcess(currentCommand, cwd, timeoutMs, dispatchEnv);
-      if (lastRaw.exitCode === 0 || !isRetryableFailure(lastRaw) || attempt === MAX_FAILOVER_ATTEMPTS) break;
-
-      const failoverList = getFailoverOrder(
-        { provider: currentProvider, model: currentModel, tier },
-        input.profile ?? {},
-      );
-      if (failoverList.length === 0) break;
-
-      const next   = failoverList[0];
-      const reason = `${lastRaw.stderr || lastRaw.stdout}`.slice(0, 120);
-      logFailover({ from: `${currentProvider}/${currentModel}`, to: `${next.provider}/${next.model}`, reason, attempt: attempt + 1 });
-      process.stderr.write(`\x1b[2m[dual-brain] Provider busy, failing over to ${next.label}...\x1b[0m\n`);
-
-      markHot(currentProvider, currentModel, cwd);
-      currentProvider = next.provider;
-      currentModel    = next.model;
-      currentDecision = { ...currentDecision, provider: currentProvider, model: currentModel };
-      currentCommand  = buildCommand(currentDecision, prompt, files, cwd);
-    }
-
-    const { exitCode, stdout, stderr, durationMs } = lastRaw;
-    // ── End failover loop ────────────────────────────────────────────────
-
-    // Extract token usage from JSON output if available
-    let usage = null;
-    try {
-      const parsed = JSON.parse(stdout);
-      if (parsed?.usage) {
-        usage = { inputTokens: parsed.usage.input_tokens ?? 0, outputTokens: parsed.usage.output_tokens ?? 0 };
-      }
-    } catch {}
-
-    const success = exitCode === 0;
-    const errorText = (stderr || stdout).slice(0, 500);
-    const summary = success ? compressResult(stdout) : compressResult(stderr || stdout);
-
-    // ── Health tracking ────────────────────────────────────────────────────
-    if (success) {
-      recordDuration(currentProvider, currentModel, durationMs);
-      const median = medianDuration(currentProvider, currentModel);
-      if (median !== null && durationMs > median * 3) {
-        markDegraded(currentProvider, currentModel, cwd);
-      } else {
-        markHealthy(currentProvider, currentModel, cwd);
-      }
-      const totalTokens = (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0);
-      recordDispatch(currentProvider, currentModel, totalTokens, cwd);
-    } else {
-      if (RATE_LIMIT_PATTERNS.test(errorText)) {
-        markHot(currentProvider, currentModel, cwd);
-      }
-    }
-    // ── End health tracking ────────────────────────────────────────────────
-
-    recordUsage({
-      provider: currentProvider,
-      model:    currentModel,
-      tier,
-      durationMs,
-      inputTokens:  usage?.inputTokens  ?? null,
-      outputTokens: usage?.outputTokens ?? null,
-      success,
-    });
-
-    // ── Auto-review annotation ────────────────────────────────────────────────
-    // When execution changed files at medium+ risk, stamp result with a pending
-    // review note. The opposite provider from the one that did the work reviews
-    // it (true dual-brain). Non-blocking — does not delay the return value.
-    let autoReview;
-    if (success && (decision.risk === 'medium' || decision.risk === 'high' || decision.risk === 'critical')) {
-      try {
-        const reviewProvider = currentProvider === 'claude' ? 'openai' : 'claude';
-        autoReview = { triggered: true, provider: reviewProvider, status: 'pending' };
-      } catch {
-        autoReview = { triggered: false, reason: 'review-dispatch-failed' };
-      }
-    } else {
-      autoReview = { triggered: false, reason: success ? 'low-risk' : 'dispatch-failed' };
-    }
-    // ── End auto-review annotation ────────────────────────────────────────────
-
-    const nativeResult = {
-      status:        success ? 'completed' : 'failed',
-      type:          'native-agent',
-      provider:      currentProvider,
-      model:         currentModel,
-      specialist:    specialist ?? 'generic',
-      command:       currentCommand,
-      nativeDispatch: nativeDescriptor,
-      exitCode,
-      summary,
-      durationMs,
-      usage,
-      worktreeUsed:  useWorktree,
-      autoReview,
-      authVerified:  true,
-      error: success ? null : errorText.slice(0, 200),
-    };
-    try {
-      const { recordDispatchOutcome } = await import('./outcome.mjs');
-      recordDispatchOutcome(input, nativeResult);
-    } catch { /* never block */ }
-
-    // ── Self-correction: intelligent retry after failover exhaustion ──────────
-    if (!success) {
-      const attemptNumber = input._retryAttempt || 1;
-      try {
-        const { shouldRetry } = await import('./self-correct.mjs');
-        const retry = shouldRetry(nativeResult, decision, attemptNumber);
-        if (retry.retry && retry.decision) {
-          if (verbose) process.stderr.write(`[dual-brain] self-correct: ${retry.strategy} (attempt ${attemptNumber + 1}, reason: ${retry.reason})\n`);
-          return dispatch({
-            ...input,
-            decision: retry.decision,
-            _retryAttempt: attemptNumber + 1,
-            _skipPreDispatchThink: retry.strategy !== 'rethink',
-            _skipRelatedContext: true,
-          });
-        } else if (verbose) {
-          process.stderr.write(`[dual-brain] self-correct: giving up (${retry.reason})\n`);
-        }
-      } catch { /* non-blocking — if self-correct fails, return original failure */ }
-    }
-    // ── End self-correction ───────────────────────────────────────────────────
-
-    return nativeResult;
-  }
-
-  const command = buildCommand(effectiveDecision, prompt, files, cwd);
-
-  if (dryRun) {
-    return { status: 'dry-run', provider: effectiveProvider, model: effectiveModel, specialist: specialist ?? 'generic', command, exitCode: null, summary: null, durationMs: 0, usage: null, error: null, authVerified: true };
-  }
-
-  // Record this dispatch against the budget
-  _recordDispatchBudget(prompt);
-
-  // ── Auto-heal failover retry loop (subprocess path) ──────────────────────
-  const MAX_FAILOVER_ATTEMPTS_SUB = 2;
-  let subProvider = effectiveProvider;
-  let subModel    = effectiveModel;
-  let subDecision = effectiveDecision;
-  let subCommand  = command;
-  let subRaw;
-
-  for (let attempt = 0; attempt <= MAX_FAILOVER_ATTEMPTS_SUB; attempt++) {
-    subRaw = await runProcess(subCommand, cwd, timeoutMs);
-    if (subRaw.exitCode === 0 || !isRetryableFailure(subRaw) || attempt === MAX_FAILOVER_ATTEMPTS_SUB) break;
-
-    const failoverList = getFailoverOrder(
-      { provider: subProvider, model: subModel, tier },
-      input.profile ?? {},
-    );
-    if (failoverList.length === 0) break;
-
-    const next   = failoverList[0];
-    const reason = `${subRaw.stderr || subRaw.stdout}`.slice(0, 120);
-    logFailover({ from: `${subProvider}/${subModel}`, to: `${next.provider}/${next.model}`, reason, attempt: attempt + 1 });
-    process.stderr.write(`\x1b[2m[dual-brain] Provider busy, failing over to ${next.label}...\x1b[0m\n`);
-
-    markHot(subProvider, subModel, cwd);
-    subProvider = next.provider;
-    subModel    = next.model;
-    subDecision = { ...subDecision, provider: subProvider, model: subModel };
-    subCommand  = buildCommand(subDecision, prompt, files, cwd);
-  }
-
-  const { exitCode, stdout, stderr, durationMs } = subRaw;
-  // ── End failover loop ──────────────────────────────────────────────────────
-
-  // Extract token usage from JSON output if available
-  let usage = null;
-  try {
-    const parsed = JSON.parse(stdout);
-    if (parsed?.usage) {
-      usage = { inputTokens: parsed.usage.input_tokens ?? 0, outputTokens: parsed.usage.output_tokens ?? 0 };
-    }
-  } catch {}
-
-  const success = exitCode === 0;
-  const errorText = (stderr || stdout).slice(0, 500);
-  const summary = success ? compressResult(stdout) : compressResult(stderr || stdout);
-
-  // ── Health tracking ──────────────────────────────────────────────────────
-  if (success) {
-    recordDuration(subProvider, subModel, durationMs);
-    const median = medianDuration(subProvider, subModel);
-    if (median !== null && durationMs > median * 3) {
-      markDegraded(subProvider, subModel, cwd);
-    } else {
-      markHealthy(subProvider, subModel, cwd);
-    }
-    const totalTokens = (usage?.inputTokens ?? 0) + (usage?.outputTokens ?? 0);
-    recordDispatch(subProvider, subModel, totalTokens, cwd);
-  } else {
-    if (RATE_LIMIT_PATTERNS.test(errorText)) {
-      markHot(subProvider, subModel, cwd);
-    }
-  }
-  // ── End health tracking ──────────────────────────────────────────────────
-
-  recordUsage({
-    provider: subProvider,
-    model:    subModel,
-    tier,
-    durationMs,
-    inputTokens:  usage?.inputTokens  ?? null,
-    outputTokens: usage?.outputTokens ?? null,
-    success,
-  });
-
-  // ── Auto-review annotation ──────────────────────────────────────────────────
-  // When execution changed files at medium+ risk, stamp result with a pending
-  // review note. The opposite provider from the one that did the work reviews
-  // it (true dual-brain). Non-blocking — does not delay the return value.
-  let autoReview;
-  if (success && (decision.risk === 'medium' || decision.risk === 'high' || decision.risk === 'critical')) {
-    try {
-      const reviewProvider = subProvider === 'claude' ? 'openai' : 'claude';
-      autoReview = { triggered: true, provider: reviewProvider, status: 'pending' };
-    } catch {
-      autoReview = { triggered: false, reason: 'review-dispatch-failed' };
-    }
-  } else {
-    autoReview = { triggered: false, reason: success ? 'low-risk' : 'dispatch-failed' };
-  }
-  // ── End auto-review annotation ──────────────────────────────────────────────
-
-  const subResult = {
-    status:      success ? 'completed' : 'failed',
-    provider:    subProvider,
-    model:       subModel,
-    specialist:  specialist ?? 'generic',
-    command:     subCommand,
-    exitCode,
-    summary,
-    durationMs,
-    usage,
-    worktreeUsed: useWorktree,
-    autoReview,
-    authVerified: true,
-    error: success ? null : errorText.slice(0, 200),
-  };
-  try {
-    const { recordDispatchOutcome } = await import('./outcome.mjs');
-    recordDispatchOutcome(input, subResult);
-  } catch { /* never block */ }
-
-  // ── Self-correction: intelligent retry after failover exhaustion ──────────
-  if (!success) {
-    const attemptNumber = input._retryAttempt || 1;
-    try {
-      const { shouldRetry } = await import('./self-correct.mjs');
-      const retry = shouldRetry(subResult, decision, attemptNumber);
-      if (retry.retry && retry.decision) {
-        if (verbose) process.stderr.write(`[dual-brain] self-correct: ${retry.strategy} (attempt ${attemptNumber + 1}, reason: ${retry.reason})\n`);
-        return dispatch({
-          ...input,
-          decision: retry.decision,
-          _retryAttempt: attemptNumber + 1,
-          _skipPreDispatchThink: retry.strategy !== 'rethink',
-          _skipRelatedContext: true,
-        });
-      } else if (verbose) {
-        process.stderr.write(`[dual-brain] self-correct: giving up (${retry.reason})\n`);
-      }
-    } catch { /* non-blocking — if self-correct fails, return original failure */ }
-  }
-  // ── End self-correction ───────────────────────────────────────────────────
-
-  return subResult;
-}
-
-// ─── Dual-brain dispatch (parallel) ───────────────────────────────────────────
-async function dispatchDualBrain(input = {}) {
-  const { decision = {}, files = [], cwd = process.cwd(), dryRun = false, verbose = false } = input;
-  let { prompt } = input;
-  if (!prompt) throw new Error('prompt is required');
-
-  // Safety gate: redact secrets before sending to either provider
-  prompt = redact(prompt);
-
-  // Stamp with dispatch marker so enforce-tier.mjs allows this Agent call
-  // Compute required tier for governance validation
-  try {
-    const scores = scoreTask({ intent: decision.tier, risk: decision.risk, files, objective: prompt.slice(0, 200) });
-    decision = { ...decision, _requiredTier: computeRequiredTier(scores) };
-  } catch { /* non-blocking */ }
-  prompt = _prependDispatchMarker(prompt, decision);
-
-  // ── Situation brief injection ────────────────────────────────────────────────
-  const _dualBrainBrief = typeof input.situationBrief === 'string' && input.situationBrief.trim()
-    ? input.situationBrief.trim()
-    : null;
-  if (_dualBrainBrief) {
-    prompt = `[SITUATION BRIEF]\n${_dualBrainBrief}\n[END BRIEF]\n\n${prompt}`;
-  }
-  // ── End situation brief ──────────────────────────────────────────────────────
-
-  // Feature 1: Validate both sub-decisions before spawning anything
-  const rt = await detectRuntime();
-  const tier = decision.tier ?? 'execute';
-
-  const claudeDecision = { ...decision, provider: 'claude', model: decision.model ?? 'sonnet', tier };
-  const _oaiDefault = tier === 'think' ? 'o3' : tier === 'search' ? 'gpt-4o-mini' : 'gpt-4o';
-  const openaiDecision = { ...decision, provider: 'openai', model: decision.openaiModel ?? _oaiDefault, tier };
-
-  const validatedClaude = validateDispatch(claudeDecision, rt);
-  const validatedOpenai = validateDispatch(openaiDecision, rt);
-
-  const [claudeResult, openaiResult] = await Promise.all([
-    validatedClaude._error
-      ? Promise.resolve({ status: 'error', provider: 'claude', model: claudeDecision.model, command: null, exitCode: null, summary: validatedClaude._error, durationMs: 0, usage: null, error: validatedClaude._error })
-      : dispatch({ decision: validatedClaude, prompt, files, cwd, dryRun, verbose }),
-    validatedOpenai._error
-      ? Promise.resolve({ status: 'error', provider: 'openai', model: openaiDecision.model, command: null, exitCode: null, summary: validatedOpenai._error, durationMs: 0, usage: null, error: validatedOpenai._error })
-      : dispatch({ decision: validatedOpenai, prompt, files, cwd, dryRun, verbose }),
-  ]);
-
-  return {
-    tier,
-    claude: claudeResult,
-    openai: openaiResult,
-    consensus: claudeResult.status === 'completed' && openaiResult.status === 'completed'
-      ? 'both-passed'
-      : claudeResult.status === 'failed' && openaiResult.status === 'failed'
-        ? 'both-failed'
-        : 'split',
-  };
-}
-
-// ─── CLI ──────────────────────────────────────────────────────────────────────
-if (process.argv[1] && new URL(import.meta.url).pathname === process.argv[1]) {
-  const args = process.argv.slice(2);
-  const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? (args[i + 1] ?? true) : null; };
-
-  if (args.includes('--detect-runtime')) {
-    const rt = await detectRuntime();
-    console.log(JSON.stringify(rt, null, 2));
-    process.exit(0);
-  }
-
-  const prompt = flag('--prompt') || args.find(a => !a.startsWith('--'));
-  if (!prompt) {
-    console.error('Usage: node src/dispatch.mjs --prompt "..." [--provider claude|openai] [--model sonnet] [--tier execute] [--dry-run]');
-    console.error('       node src/dispatch.mjs --detect-runtime');
-    process.exit(1);
-  }
-
-  const decision = {
-    provider: flag('--provider') || 'claude',
-    model:    flag('--model')    || 'sonnet',
-    tier:     flag('--tier')     || 'execute',
-    effort:   flag('--effort')   || null,
-  };
-
-  try {
-    const result = await dispatch({ decision, prompt, dryRun: args.includes('--dry-run') });
-    console.log(JSON.stringify(result, null, 2));
-  } catch (err) {
-    console.error('dispatch error:', err.message);
-    process.exit(1);
-  }
-}
-
-export { dispatch, buildCommand, detectRuntime, compressResult, dispatchDualBrain, validateDispatch, checkWorktreeClean, getRetryBudget, isInsideClaude, buildNativeDispatch, normalizeResult, loadSpecialistPrompt, preflightAuth };