dual-brain 0.2.4 → 0.2.5

package/src/ci-triage.mjs

@@ -0,0 +1,191 @@
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Detect CI system in use.
+ * @param {string} [cwd]
+ * @returns {{ systems: string[], primary: string|null }}
+ */
+export function detectCI(cwd) {
+  const root = cwd || process.cwd();
+  const systems = [];
+
+  if (existsSync(join(root, '.github/workflows'))) systems.push('github-actions');
+  if (existsSync(join(root, '.circleci')))          systems.push('circleci');
+  if (existsSync(join(root, '.gitlab-ci.yml')))     systems.push('gitlab-ci');
+  if (existsSync(join(root, 'Jenkinsfile')))        systems.push('jenkins');
+  if (existsSync(join(root, '.travis.yml')))        systems.push('travis');
+  if (existsSync(join(root, 'vercel.json')) || existsSync(join(root, '.vercel'))) systems.push('vercel');
+  if (existsSync(join(root, 'netlify.toml')))       systems.push('netlify');
+
+  return { systems, primary: systems[0] || null };
+}
+
+/**
+ * Get recent CI run status using gh CLI.
+ * @param {string} [cwd]
+ * @returns {{ available: boolean, runs: object[], hasFailures: boolean, lastRun: object|null }}
+ */
+export function getCIStatus(cwd) {
+  try {
+    const json = execSync(
+      'gh run list --limit 5 --json databaseId,name,status,conclusion,headBranch,createdAt',
+      { cwd, encoding: 'utf8', timeout: 10000 }
+    );
+    const runs = JSON.parse(json);
+    return {
+      available: true,
+      runs: runs.map(r => ({
+        id: r.databaseId,
+        name: r.name,
+        status: r.status,
+        conclusion: r.conclusion,
+        branch: r.headBranch,
+        createdAt: r.createdAt,
+      })),
+      hasFailures: runs.some(r => r.conclusion === 'failure'),
+      lastRun: runs[0] || null,
+    };
+  } catch {
+    return { available: false, runs: [], hasFailures: false, lastRun: null };
+  }
+}
+
+/**
+ * Get failed CI run logs and classify the failure.
+ * @param {string|number} runId
+ * @param {string} [cwd]
+ * @returns {object}
+ */
+export function triageFailure(runId, cwd) {
+  try {
+    const logs = execSync(`gh run view ${runId} --log-failed 2>/dev/null | tail -100`, {
+      cwd, encoding: 'utf8', timeout: 15000,
+    });
+
+    const classification = classifyFailure(logs);
+    const fileHints = extractFileHints(logs, cwd);
+
+    return {
+      success: true,
+      runId,
+      logs: logs.slice(-3000), // last 3000 chars
+      classification,
+      fileHints,
+      suggestedAction: getSuggestedAction(classification),
+    };
+  } catch (err) {
+    return { success: false, runId, error: err.message };
+  }
+}
+
+/**
+ * Classify a CI failure from log output.
+ * @param {string} logs
+ * @returns {{ type: string, confidence: string }}
+ */
+function classifyFailure(logs) {
+  const lower = logs.toLowerCase();
+
+  if (lower.includes('syntaxerror') || lower.includes('parse error'))               return { type: 'syntax',          confidence: 'high' };
+  if (lower.includes('typeerror') || lower.includes('type error'))                  return { type: 'type-error',      confidence: 'high' };
+  if (lower.includes('referenceerror'))                                              return { type: 'reference-error', confidence: 'high' };
+  if (lower.includes('test fail') || lower.includes('tests failed') || lower.includes('assertion')) return { type: 'test-failure',    confidence: 'high' };
+  if (lower.includes('enoent') || lower.includes('no such file'))                   return { type: 'missing-file',    confidence: 'high' };
+  if (lower.includes('permission denied') || lower.includes('eacces'))             return { type: 'permissions',     confidence: 'high' };
+  if (lower.includes('timeout') || lower.includes('timed out'))                    return { type: 'timeout',         confidence: 'medium' };
+  if (lower.includes('out of memory') || lower.includes('heap'))                   return { type: 'oom',             confidence: 'medium' };
+  if (lower.includes('npm err') || lower.includes('yarn error') || lower.includes('dependency')) return { type: 'dependency',     confidence: 'medium' };
+  if (lower.includes('lint') || lower.includes('eslint'))                           return { type: 'lint',            confidence: 'high' };
+  if (lower.includes('build fail'))                                                  return { type: 'build',           confidence: 'medium' };
+  if (lower.includes('docker') || lower.includes('container'))                      return { type: 'container',       confidence: 'medium' };
+
+  return { type: 'unknown', confidence: 'low' };
+}
+
+/**
+ * Extract local file paths referenced in CI logs.
+ * @param {string} logs
+ * @param {string} [cwd]
+ * @returns {string[]}
+ */
+function extractFileHints(logs, cwd) {
+  const files = new Set();
+  const root = cwd || process.cwd();
+
+  const patterns = [
+    /(?:at\s+)?([a-zA-Z0-9_./\\-]+\.[a-zA-Z]+):(\d+)/g,
+    /(?:in\s+)?([a-zA-Z0-9_./\\-]+\.[a-zA-Z]+)\((\d+)\)/g,
+    /Error in ([a-zA-Z0-9_./\\-]+\.[a-zA-Z]+)/g,
+  ];
+
+  for (const pattern of patterns) {
+    for (const match of logs.matchAll(pattern)) {
+      const file = match[1];
+      if (file && !file.includes('node_modules') && existsSync(join(root, file))) {
+        files.add(file);
+      }
+    }
+  }
+
+  return [...files];
+}
+
+/**
+ * Get a human-readable suggested action for a failure classification.
+ * @param {{ type: string }} classification
+ * @returns {string}
+ */
+function getSuggestedAction(classification) {
+  const actions = {
+    'syntax':          'Fix syntax error in the identified file',
+    'type-error':      'Check type annotations and function signatures',
+    'reference-error': 'Check for undefined variables or missing imports',
+    'test-failure':    'Run tests locally and fix failing assertions',
+    'missing-file':    'Check if a required file was deleted or not committed',
+    'permissions':     'Check file permissions and access rights',
+    'timeout':         'Investigate slow operations or increase timeout',
+    'oom':             'Check for memory leaks or reduce batch size',
+    'dependency':      'Run npm install and check for version conflicts',
+    'lint':            'Run linter locally and fix violations',
+    'build':           'Check build configuration and dependencies',
+    'container':       'Check Dockerfile and container configuration',
+    'unknown':         'Review full CI logs for error details',
+  };
+  return actions[classification.type] || actions.unknown;
+}
+
+/**
+ * Full CI triage: detect CI, fetch status, classify failures, map to files.
+ * @param {string} [cwd]
+ * @returns {object}
+ */
+export function fullTriage(cwd) {
+  const ci = detectCI(cwd);
+  if (!ci.primary) return { available: false, reason: 'no-ci-detected' };
+
+  const status = getCIStatus(cwd);
+  if (!status.available) return { available: false, reason: 'gh-cli-unavailable' };
+  if (!status.hasFailures) return { available: true, healthy: true, message: 'All CI runs passing' };
+
+  const failedRuns = status.runs.filter(r => r.conclusion === 'failure');
+  const triages = failedRuns.slice(0, 3).map(r => triageFailure(r.id, cwd));
+
+  return {
+    available: true,
+    healthy: false,
+    failedRuns: failedRuns.length,
+    triages,
+    topIssue: triages[0]?.classification || null,
+  };
+}
+
+// ─── CLI (direct invocation) ──────────────────────────────────────────────────
+
+const isMain = process.argv[1]?.endsWith('ci-triage.mjs');
+if (isMain) {
+  const cwd = process.argv[2] || process.cwd();
+  const result = fullTriage(cwd);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}

package/src/continuity.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+// continuity.mjs — Session continuity for dual-brain.
+// Generates handoff receipts so the next session can pick up seamlessly
+// when a session hits context limits, crashes, or is manually ended.
+//
+// Exports: generateHandoff, saveHandoff, getLatestHandoff, getHandoffAge,
+//          buildCompactionSurvivalKit, buildResumeBrief, pruneHandoffs,
+//          extractRoutingPatterns
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ─── Session chaining ─────────────────────────────────────────────────────────
+
+/**
+ * Generate a compact handoff object from current session state.
+ * Designed to fit in ~500 tokens when serialized.
+ *
+ * @param {object} sessionState
+ * @param {string}   [sessionState.taskDescription]
+ * @param {string[]} [sessionState.filesChanged]
+ * @param {string[]} [sessionState.testsRun]
+ * @param {object[]} [sessionState.decisions]         Most recent routing decisions
+ * @param {string[]} [sessionState.unresolved]        Open questions / blockers
+ * @param {object}   [sessionState.routingHistory]
+ * @param {string}     [sessionState.routingHistory.lastProvider]
+ * @param {string}     [sessionState.routingHistory.lastModel]
+ * @param {string[]}   [sessionState.routingHistory.failedProviders]
+ * @param {string[]} [sessionState.activePreferences]
+ * @param {string}   [sessionState.resumeHint]        e.g. "continue implementing auth refactor"
+ * @returns {object}
+ */
+export function generateHandoff(sessionState) {
+  return {
+    version: 1,
+    timestamp: new Date().toISOString(),
+    task: sessionState.taskDescription || null,
+    progress: {
+      filesChanged: (sessionState.filesChanged || []).slice(0, 20),
+      testsRun: sessionState.testsRun || [],
+      decisions: (sessionState.decisions || []).slice(0, 5), // most recent routing decisions
+    },
+    unresolved: (sessionState.unresolved || []).slice(0, 5),
+    routing: {
+      lastProvider: sessionState.routingHistory?.lastProvider || null,
+      lastModel: sessionState.routingHistory?.lastModel || null,
+      failedProviders: sessionState.routingHistory?.failedProviders || [],
+    },
+    preferences: sessionState.activePreferences || [],
+    resumeHint: sessionState.resumeHint || null,
+  };
+}
+
+// ─── Handoff persistence ──────────────────────────────────────────────────────
+
+/**
+ * Persist a handoff object to .dual-brain/handoffs/.
+ * @param {object} handoff   Result of generateHandoff()
+ * @param {string} [cwd]     Project root (defaults to process.cwd())
+ * @returns {string}         Absolute path of the written file
+ */
+export function saveHandoff(handoff, cwd) {
+  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  mkdirSync(dir, { recursive: true });
+  const filename = `handoff-${Date.now()}.json`;
+  writeFileSync(join(dir, filename), JSON.stringify(handoff, null, 2));
+  return join(dir, filename);
+}
+
+/**
+ * Load the most recent handoff from .dual-brain/handoffs/.
+ * Returns null when no handoffs exist or all are unreadable.
+ * @param {string} [cwd]
+ * @returns {object|null}
+ */
+export function getLatestHandoff(cwd) {
+  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  if (!existsSync(dir)) return null;
+  const files = readdirSync(dir)
+    .filter(f => f.startsWith('handoff-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+  if (files.length === 0) return null;
+  try {
+    return JSON.parse(readFileSync(join(dir, files[0]), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Return the age of a handoff in hours.
+ * Returns Infinity when the handoff has no timestamp.
+ * @param {object|null} handoff
+ * @returns {number}  Hours since handoff was generated
+ */
+export function getHandoffAge(handoff) {
+  if (!handoff?.timestamp) return Infinity;
+  return (Date.now() - Date.parse(handoff.timestamp)) / 3600000;
+}
+
+// ─── Smart compaction ─────────────────────────────────────────────────────────
+
+/**
+ * Build a compaction-safe summary string to inject before context compression.
+ * The content must survive being summarised by a compression pass, so keep it
+ * terse, high-signal, and easy to re-state.
+ *
+ * @param {object} state
+ * @param {string}   [state.activeTask]
+ * @param {string[]} [state.routingRules]
+ * @param {string[]} [state.criticalDecisions]
+ * @param {string[]} [state.filesInProgress]
+ * @param {string[]} [state.preferences]
+ * @param {string[]} [state.warnings]
+ * @returns {string}
+ */
+export function buildCompactionSurvivalKit(state) {
+  const lines = [];
+  lines.push('[DUAL-BRAIN CONTINUITY]');
+
+  if (state.activeTask) {
+    lines.push(`TASK: ${state.activeTask}`);
+  }
+  if (state.routingRules?.length) {
+    lines.push(`ROUTING: ${state.routingRules.join('; ')}`);
+  }
+  if (state.criticalDecisions?.length) {
+    lines.push(`DECISIONS: ${state.criticalDecisions.join('; ')}`);
+  }
+  if (state.filesInProgress?.length) {
+    lines.push(`FILES: ${state.filesInProgress.join(', ')}`);
+  }
+  if (state.preferences?.length) {
+    lines.push(`PREFS: ${state.preferences.join('; ')}`);
+  }
+  if (state.warnings?.length) {
+    lines.push(`WARNINGS: ${state.warnings.join('; ')}`);
+  }
+
+  lines.push('[/DUAL-BRAIN CONTINUITY]');
+  return lines.join('\n');
+}
+
+// ─── Resume brief builder ─────────────────────────────────────────────────────
+
+/**
+ * Check for a recent handoff and build a resume context string for a new session.
+ * Returns null when no usable handoff exists (missing, too stale, or unreadable).
+ *
+ * @param {string} [cwd]
+ * @returns {string|null}
+ */
+export function buildResumeBrief(cwd) {
+  const handoff = getLatestHandoff(cwd);
+  if (!handoff) return null;
+
+  const ageHours = getHandoffAge(handoff);
+  if (ageHours > 48) return null; // too stale to be useful
+
+  const lines = [];
+  const ageLabel =
+    ageHours < 1
+      ? 'just now'
+      : ageHours < 24
+        ? `${Math.round(ageHours)}h ago`
+        : `${Math.round(ageHours / 24)}d ago`;
+
+  lines.push(`Resuming from previous session (${ageLabel}):`);
+
+  if (handoff.task) lines.push(`  Task: ${handoff.task}`);
+  if (handoff.resumeHint) lines.push(`  Next: ${handoff.resumeHint}`);
+  if (handoff.progress?.filesChanged?.length) {
+    const shown = handoff.progress.filesChanged.slice(0, 5);
+    const extra = handoff.progress.filesChanged.length > 5
+      ? ` (+${handoff.progress.filesChanged.length - 5} more)`
+      : '';
+    lines.push(`  Changed: ${shown.join(', ')}${extra}`);
+  }
+  if (handoff.unresolved?.length) {
+    lines.push(`  Unresolved: ${handoff.unresolved.join('; ')}`);
+  }
+  if (handoff.routing?.failedProviders?.length) {
+    lines.push(`  Note: ${handoff.routing.failedProviders.join(', ')} failed last session`);
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Handoff cleanup ──────────────────────────────────────────────────────────
+
+/**
+ * Remove old handoff files, keeping only the most recent `keep` entries.
+ * @param {string} [cwd]
+ * @param {number} [keep=10]
+ * @returns {number}  Count of files pruned
+ */
+export function pruneHandoffs(cwd, keep = 10) {
+  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  if (!existsSync(dir)) return 0;
+  const files = readdirSync(dir)
+    .filter(f => f.startsWith('handoff-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+  let pruned = 0;
+  for (const f of files.slice(keep)) {
+    try {
+      unlinkSync(join(dir, f));
+      pruned++;
+    } catch {
+      // Skip files that can't be removed — best-effort
+    }
+  }
+  return pruned;
+}
+
+// ─── Cross-session learning ───────────────────────────────────────────────────
+
+/**
+ * Extract routing patterns from handoff history to inform provider/model selection.
+ *
+ * @param {string} [cwd]
+ * @returns {{
+ *   patterns: Array<{ type: string, value: string, count: number }>,
+ *   confidence: number,
+ *   sampleSize: number
+ * }}
+ */
+export function extractRoutingPatterns(cwd) {
+  const dir = join(cwd || process.cwd(), '.dual-brain', 'handoffs');
+  if (!existsSync(dir)) return { patterns: [], confidence: 0, sampleSize: 0 };
+
+  const files = readdirSync(dir)
+    .filter(f => f.startsWith('handoff-') && f.endsWith('.json'))
+    .sort()
+    .reverse()
+    .slice(0, 20);
+
+  const handoffs = files
+    .map(f => {
+      try {
+        return JSON.parse(readFileSync(join(dir, f), 'utf8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  // Count provider/model usage patterns
+  const providerCounts = {};
+  const modelCounts = {};
+  const failureCounts = {};
+
+  for (const h of handoffs) {
+    if (h.routing?.lastProvider) {
+      providerCounts[h.routing.lastProvider] = (providerCounts[h.routing.lastProvider] || 0) + 1;
+    }
+    if (h.routing?.lastModel) {
+      modelCounts[h.routing.lastModel] = (modelCounts[h.routing.lastModel] || 0) + 1;
+    }
+    for (const fp of (h.routing?.failedProviders || [])) {
+      failureCounts[fp] = (failureCounts[fp] || 0) + 1;
+    }
+  }
+
+  const patterns = [];
+
+  // Most used provider
+  const topProvider = Object.entries(providerCounts).sort((a, b) => b[1] - a[1])[0];
+  if (topProvider) {
+    patterns.push({ type: 'preferred_provider', value: topProvider[0], count: topProvider[1] });
+  }
+
+  // Most used model
+  const topModel = Object.entries(modelCounts).sort((a, b) => b[1] - a[1])[0];
+  if (topModel) {
+    patterns.push({ type: 'preferred_model', value: topModel[0], count: topModel[1] });
+  }
+
+  // Frequently failing provider (threshold: 3+ failures)
+  const topFailure = Object.entries(failureCounts).sort((a, b) => b[1] - a[1])[0];
+  if (topFailure && topFailure[1] >= 3) {
+    patterns.push({ type: 'unreliable_provider', value: topFailure[0], count: topFailure[1] });
+  }
+
+  return {
+    patterns,
+    confidence: Math.min(1, handoffs.length / 10),
+    sampleSize: handoffs.length,
+  };
+}

package/src/detect.mjs

@@ -5,6 +5,7 @@
 import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
+import { execSync } from 'child_process';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -365,6 +366,39 @@ function detectSuggestedPlugins(prompt) {
   return [...matched];
 }
 
+// ─── CI risk check ────────────────────────────────────────────────────────────
+
+/**
+ * Lightweight CI risk check: returns true if the current branch has a recent
+ * CI failure, indicating the task may touch already-broken code.
+ * Intentionally best-effort — any error returns false (never blocks detection).
+ * @param {string} [cwd]
+ * @returns {{ hasCIFailure: boolean, failedBranch: string|null }}
+ */
+function checkCIRisk(cwd) {
+  try {
+    const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+      cwd, encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+
+    const json = execSync(
+      'gh run list --limit 5 --json conclusion,headBranch 2>/dev/null',
+      { cwd, encoding: 'utf8', timeout: 8000 }
+    );
+    const runs = JSON.parse(json);
+    const branchFailure = runs.find(
+      r => r.conclusion === 'failure' && r.headBranch === currentBranch
+    );
+
+    return {
+      hasCIFailure: Boolean(branchFailure),
+      failedBranch: branchFailure ? currentBranch : null,
+    };
+  } catch {
+    return { hasCIFailure: false, failedBranch: null };
+  }
+}
+
 /** Main detection function. Input: { prompt, files?, priorFailures?, sessionContext? } */
 function detectTask(input) {
   const { prompt = '', files = [], sessionContext = null } = input;
@@ -455,6 +489,9 @@ function detectTask(input) {
   // 10. Suggested Codex plugins (keyword-based, static map — no I/O)
   const suggestedPlugins = detectSuggestedPlugins(prompt);
 
+  // 11. CI risk — check if current branch has failing CI runs (best-effort, never throws)
+  const ciRiskResult = checkCIRisk(input.cwd || process.cwd());
+
   return {
     intent,
     risk,
@@ -470,6 +507,7 @@ function detectTask(input) {
     reasoningDepth,
     reasoningSignals,
     suggestedPlugins,
+    ciRisk: ciRiskResult,
     ...(repeatedFailure && { repeatedFailure: true }),
   };
 }

package/src/dispatch.mjs

@@ -675,6 +675,7 @@ async function dispatch(input = {}) {
   // ── 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');
@@ -683,6 +684,17 @@ async function dispatch(input = {}) {
         input = { ...input, situationBrief: brief };
       }
     } catch { /* non-blocking */ }
+
+    // Continuity fallback: check handoff from continuity.mjs if still no brief
+    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 ───────────────────────────────────────────────
 
@@ -848,6 +860,23 @@ async function dispatch(input = {}) {
     }
   }
 
+  // ── 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.
@@ -856,7 +885,7 @@ async function dispatch(input = {}) {
     const nativeDescriptor = buildNativeDispatch(
       effectiveDecision,
       prompt,
-      { worktree: input.worktree, maxTurns: input.maxTurns },
+      { worktree: useWorktree, maxTurns: input.maxTurns },
     );
 
     const command = buildCommand(effectiveDecision, prompt, files, cwd);
@@ -955,6 +984,23 @@ async function dispatch(input = {}) {
       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 ────────────────────────────────────────────
+
     return {
       status:        success ? 'completed' : 'failed',
       type:          'native-agent',
@@ -967,6 +1013,8 @@ async function dispatch(input = {}) {
       summary,
       durationMs,
       usage,
+      worktreeUsed:  useWorktree,
+      autoReview,
       error: success ? null : errorText.slice(0, 200),
     };
   }
@@ -1054,16 +1102,35 @@ async function dispatch(input = {}) {
     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 ──────────────────────────────────────────────
+
   return {
-    status:     success ? 'completed' : 'failed',
-    provider:   subProvider,
-    model:      subModel,
-    specialist: specialist ?? 'generic',
-    command:    subCommand,
+    status:      success ? 'completed' : 'failed',
+    provider:    subProvider,
+    model:       subModel,
+    specialist:  specialist ?? 'generic',
+    command:     subCommand,
     exitCode,
     summary,
     durationMs,
     usage,
+    worktreeUsed: useWorktree,
+    autoReview,
     error: success ? null : errorText.slice(0, 200),
   };
 }