dual-brain 0.2.21 → 0.2.23

package/bin/dual-brain.mjs

@@ -68,6 +68,7 @@ import { loadRepoCache } from '../src/repo.mjs';
 import { loadSession, saveSession, formatSessionCard, importReplitSessions, getSessionMeta, saveSessionMeta, renameSession, pinSession, unpinSession, categorizeSession, enrichSessions, archiveSession, getArchivedSessions } from '../src/session.mjs';
 
 import { box, bar, badge, menu, separator, panel, divider, statusChip, headerBar, prompt as tuiPrompt, signalLine } from '../src/tui.mjs';
+import { checkBudget } from '../src/governance.mjs';
 
 // ─── Dynamic imports for receipts + failure memory ───────────────────────────
 
@@ -2884,66 +2885,157 @@ async function mainScreen(rl, ask) {
   if (_spinnerTimeout) clearTimeout(_spinnerTimeout);
   if (dashSpinner) dashSpinner.succeed('Dashboard ready');
 
-  // ── Stale hint ────────────────────────────────────────────────────────────
-  if (staleCount >= 3) {
-    process.stdout.write(`${DIM}${staleCount} stale sessions (>7d) — type "sessions" to manage${RST}\n`);
-  }
-
   // ── Render Studio Console (paneled layout) ────────────────────────────────
   const CYAN = '\x1b[36m';
   const panelW = Math.min(sepW + 2, 72);
 
-  // Header panel — project, branch, providers, version
-  const headerLeft  = `${DIM}${projectName}${RST}  ${BOLD}${branchStr}${RST}  ${DIM}Claude${RST} ${claudeDot}  ${DIM}GPT${RST} ${openaiDot}`;
-  const headerRight = `${DIM}v${version}${RST}`;
-  const headerContent = [headerBar(headerLeft, headerRight, panelW - 4)];
-  process.stdout.write('\n' + panel('dual-brain', headerContent, { width: panelW, titleColor: CYAN }) + '\n\n');
+  // ── Budget / governance data ──────────────────────────────────────────────
+  let budgetInfo = null;
+  try {
+    const orchestratorCfg = JSON.parse(readFileSync(join(cwd, '.claude', 'orchestrator.json'), 'utf8'));
+    budgetInfo = checkBudget(cwd, orchestratorCfg);
+  } catch {
+    // No orchestrator config or no state — use a fresh read with defaults
+    try { budgetInfo = checkBudget(cwd, {}); } catch {}
+  }
+
+  // ── Panel 1: Providers + Budget (top priority — always render) ───────────
+  {
+    const providerLines = [];
+
+    // Provider health rows
+    const claudeLabel = claudeAvail ? `${GRN}✓${RST} Claude` : `${RED}✗${RST} ${DIM}Claude${RST}`;
+    const openaiLabel = openaiAvail ? `${GRN}✓${RST} GPT-4`  : `${RED}✗${RST} ${DIM}GPT-4${RST}`;
+
+    // Detect subscription expiry warnings
+    const claudeWarnStr = (claudeSub?.expiresAt && Date.parse(claudeSub.expiresAt) < Date.now())
+      ? `  ${YLW}⚠ expired${RST}` : '';
+    const openaiWarnStr = (openaiSub?.expiresAt && Date.parse(openaiSub.expiresAt) < Date.now())
+      ? `  ${YLW}⚠ expired${RST}` : '';
+
+    const providerCols = `${claudeLabel}${claudeWarnStr}   ${openaiLabel}${openaiWarnStr}`;
+
+    // Budget row
+    let budgetRow = null;
+    if (budgetInfo) {
+      const spent     = budgetInfo.spent.toFixed(2);
+      const remaining = budgetInfo.remaining.toFixed(2);
+      const limit     = budgetInfo.limit.toFixed(2);
+      const tc        = budgetInfo.tierCounts || {};
+      const tierStr   = `${DIM}t1:${tc[1] || 0}  t2:${tc[2] || 0}  t3:${tc[3] || 0}${RST}`;
+
+      if (budgetInfo.blocked) {
+        budgetRow = `${RED}✗${RST} Budget exhausted  $${spent}/$${limit}   ${tierStr}`;
+      } else if (budgetInfo.warning) {
+        budgetRow = `${YLW}⚠${RST} Budget low  ${YLW}$${remaining} remaining${RST}  of $${limit}   ${tierStr}`;
+      } else if (budgetInfo.spent > 0) {
+        budgetRow = `${GRN}✓${RST} Budget  ${DIM}$${spent} spent · $${remaining} remaining${RST}   ${tierStr}`;
+      } else {
+        budgetRow = `${DIM}· Budget  $0 spent · $${remaining} remaining   t1:0  t2:0  t3:0${RST}`;
+      }
+    }
+
+    providerLines.push(providerCols);
+    if (budgetRow) providerLines.push(budgetRow);
+
+    process.stdout.write('\n' + panel('dual-brain', providerLines, { width: panelW, titleColor: CYAN }) + '\n\n');
+  }
+
+  // ── Panel 2: Workspace signals (contextual, semantic icons) ──────────────
+  {
+    const signalLines = [];
+
+    // Git workspace status
+    if (gitBranch !== 'unknown') {
+      const dirtyStr = gitUncommitted > 0
+        ? `${YLW}⚠${RST} ${gitUncommitted} uncommitted file${gitUncommitted !== 1 ? 's' : ''}`
+        : `${GRN}✓${RST} ${DIM}clean${RST}`;
+      const aheadStr = gitAheadCount > 0 ? `  ${YLW}⚠${RST} ${gitAheadCount} ahead of remote` : '';
+      signalLines.push(`${DIM}${gitBranch}${RST}   ${dirtyStr}${aheadStr}`);
+    }
+
+    // Last commit
+    if (gitLastMsg) {
+      const isStale = /\d{2,}d ago/.test(gitLastAgo);
+      const icon = isStale ? `${YLW}⚠${RST}` : `${DIM}·${RST}`;
+      signalLines.push(`${icon} ${DIM}${gitLastMsg}  ${gitLastAgo}${RST}`);
+    }
+
+    // Open PRs
+    if (openPRs.length > 0) {
+      const prSummary = openPRs.slice(0, 2).map(pr => `#${pr.number}`).join(', ');
+      const trunc = openPRs.length > 2 ? ` +${openPRs.length - 2}` : '';
+      signalLines.push(`${DIM}·${RST} ${openPRs.length} open PR${openPRs.length !== 1 ? 's' : ''}${DIM}: ${prSummary}${trunc}${RST}`);
+    }
+
+    // Observer / awareness signals (high-priority only)
+    for (const obs of quickObservations) {
+      if (obs.priority === 'high') {
+        signalLines.push(`${RED}✗${RST} ${obs.message}`);
+      } else if (obs.priority === 'medium') {
+        signalLines.push(`${YLW}⚠${RST} ${obs.message}`);
+      }
+    }
+
+    // Risk / model registry
+    if (awarenessLine3 && !/No risk flags/.test(awarenessLine3)) {
+      const clean3 = awarenessLine3.replace(/\x1b\[[0-9;]*m/g, '').replace(/^[⚠✓]\s*/, '').trim();
+      if (clean3) signalLines.push(`${YLW}⚠${RST} ${clean3}`);
+    }
+
+    // Stale sessions hint
+    if (staleCount >= 3) {
+      signalLines.push(`${DIM}· ${staleCount} stale sessions (>7d) — type "sessions" to manage${RST}`);
+    }
+
+    // Resume / continuation hint
+    if (isReturning) {
+      const labelTrunc = (resumeState.label || 'last session').slice(0, 40);
+      const agePart    = resumeState.ageLabel ? `  ${DIM}${resumeState.ageLabel}${RST}` : '';
+      const nextPart   = resumeState.nextAction ? `  ${DIM}→ ${resumeState.nextAction}${RST}` : '';
+      signalLines.push(`${CYAN}↩${RST} Resume: ${BOLD}${labelTrunc}${RST}${agePart}${nextPart}`);
+    }
 
-  // Resume / prompt panel (only when there is something to show)
-  if (isReturning || !anyProviderAvail) {
-    const resumeContent = [];
     if (!anyProviderAvail) {
-      resumeContent.push(`${BOLD}Connect a provider to start working${RST}`);
-    } else {
-      const labelTrunc = (resumeState.label || 'last session').slice(0, 45);
-      const agePart    = resumeState.ageLabel ? ` · ${resumeState.ageLabel}` : '';
-      const nextPart   = resumeState.nextAction ? ` · next: ${resumeState.nextAction}` : '';
-      resumeContent.push(`${DIM}Last task${RST}   ${BOLD}${labelTrunc}${RST}${DIM}${agePart}${RST}`);
-      if (nextPart) resumeContent.push(`${DIM}Next step${RST}   ${nextPart.replace(/^ · /, '')}`);
-    }
-    resumeContent.push('');
-    resumeContent.push(`  ${CYAN}›${RST} ${BOLD}${suggestions[0]}${RST}    ${DIM}${suggestions[1] || ''}${RST}    ${DIM}${suggestions[2] || ''}${RST}`);
-    process.stdout.write(panel(isReturning ? 'Resume work' : 'Get started', resumeContent, { width: panelW }) + '\n\n');
-  } else {
-    // Fresh / no-resume state — just show suggestions inline
-    const suggestContent = [`  ${CYAN}›${RST} ${BOLD}${suggestions[0]}${RST}    ${DIM}${suggestions[1] || ''}${RST}    ${DIM}${suggestions[2] || ''}${RST}`];
-    process.stdout.write(panel('Get started', suggestContent, { width: panelW }) + '\n\n');
+      signalLines.push(`${RED}✗${RST} ${BOLD}No provider connected${RST}  — run: dual-brain login`);
+    }
+
+    if (signalLines.length > 0) {
+      process.stdout.write(panel('Workspace', signalLines, { width: panelW }) + '\n\n');
+    }
   }
 
-  // Signals panel — recent work items (only when there are items)
-  if (recentLines.length > 0) {
-    process.stdout.write(panel('Signals', recentLines, { width: panelW }) + '\n\n');
+  // ── Panel 3: What do you want to do? (suggestions) ───────────────────────
+  {
+    const promptTitle = !anyProviderAvail ? 'Get started' : isReturning ? 'Continue' : 'Start';
+    const suggestContent = suggestions.map((s, i) => {
+      return i === 0
+        ? `  ${CYAN}›${RST} ${BOLD}${s}${RST}`
+        : `    ${DIM}${s}${RST}`;
+    });
+    process.stdout.write(panel(promptTitle, suggestContent, { width: panelW }) + '\n\n');
   }
 
-  // Shortcut bar — always visible so the user never has to guess
+  // ── Shortcuts (vertical layout, one per line) ────────────────────────────
   const shortcuts = [
-    [`Enter`, isReturning ? 'resume last session' : 'start working'],
-    [`n`, 'new session'],
-    [`/`, 'search sessions'],
-    [`s`, 'settings & profiles'],
-    [`d`, 'doctor (diagnose issues)'],
-    [`a`, profile.automode ? 'auto mode ⚡ on' : 'auto mode'],
-    [`q`, 'quit'],
+    [`Enter`, isReturning ? 'resume last session' : 'start working  (or type a task)'],
+    [`n`,     'new session'],
+    [`/`,     'search sessions'],
+    [`s`,     'settings & profiles'],
+    [`d`,     'doctor — diagnose issues'],
+    [`a`,     profile.automode ? 'auto mode  (on)' : 'auto mode  (off)'],
+    [`q`,     'quit'],
   ];
-  process.stdout.write('\n');
   for (const [key, label] of shortcuts) {
-    const keyStr = key === 'Enter' ? `${CYAN}Enter${RST}` : `  ${CYAN}${key}${RST}  `;
-    const padded = key === 'Enter' ? ' ' : '  ';
-    process.stdout.write(`   ${keyStr}${padded}${DIM}${label}${RST}\n`);
+    const keyStr = key === 'Enter'
+      ? `${CYAN}Enter${RST}`
+      : `${CYAN}${key}${RST}    `;
+    const padder = key === 'Enter' ? '    ' : '';
+    process.stdout.write(`   ${keyStr}${padder}${DIM}${label}${RST}\n`);
   }
   process.stdout.write('\n');
 
-  // Input bar — rendered below shortcut bar
+  // Input bar — rendered below shortcuts
   const inputLeft = tuiPrompt('task or command...');
   process.stdout.write(` ${inputLeft}\n`);
 

package/hooks/enforce-tier.mjs

@@ -192,6 +192,96 @@ function quickPressureCheck(tier) {
   }
 }
 
+// ─── Governance Check (inlined for standalone hook execution) ─────────────────
+
+const GOVERNANCE_MODEL_TIERS = {
+  1: ['claude-haiku-4-5-20251001', 'haiku', 'gpt-4o-mini', 'o4-mini'],
+  2: ['claude-sonnet-4-6', 'sonnet', 'gpt-4o', 'gpt-4.1'],
+  3: ['claude-opus-4-6', 'claude-opus-4-7', 'opus', 'o3'],
+};
+
+function getGovernanceTier(modelId) {
+  if (!modelId) return 2;
+  const normalized = String(modelId).toLowerCase();
+  for (const [tier, models] of Object.entries(GOVERNANCE_MODEL_TIERS)) {
+    if (models.some(m => normalized.includes(m))) return Number(tier);
+  }
+  return 2;
+}
+
+function loadWorkStyle() {
+  try {
+    const data = JSON.parse(readFileSync(PROFILE_FILE, 'utf8'));
+    return data.workStyle || data.active || 'auto';
+  } catch { return 'auto'; }
+}
+
+function loadGovernanceBudget() {
+  const statePath = resolve(__dirname, '..', '..', '.dualbrain', 'governance-state.json');
+  try {
+    const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+    // Check staleness (30 min gap = new session)
+    const lastDispatch = raw.dispatches?.[raw.dispatches.length - 1];
+    if (lastDispatch && (Date.now() - Date.parse(lastDispatch.ts)) > 30 * 60 * 1000) {
+      return { totalEstimatedCost: 0 };
+    }
+    return raw;
+  } catch {
+    return { totalEstimatedCost: 0 };
+  }
+}
+
+function governanceCheck(input) {
+  const ti = input.tool_input || {};
+  const model = ti.model || '';
+  const tier = getGovernanceTier(model);
+
+  // Only apply governance enforcement to tier 3 models
+  if (tier < 3) return null;
+
+  const workStyle = loadWorkStyle();
+
+  // cost-saver profile: DENY tier 3
+  if (workStyle === 'cost-saver') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason:
+          '[governance] Tier 3 (heavy) model denied — profile is cost-saver. Use tier 1-2 models or switch profile.',
+      },
+    };
+  }
+
+  // Budget check
+  try {
+    const configPath = resolve(__dirname, '..', 'orchestrator.json');
+    const config = JSON.parse(readFileSync(configPath, 'utf8'));
+    const sessionLimit = config?.budgets?.session_limit_usd || 10;
+    const state = loadGovernanceBudget();
+    const remaining = sessionLimit - (state.totalEstimatedCost || 0);
+    if (remaining <= 0) {
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason:
+            `[governance] Session budget exhausted ($${state.totalEstimatedCost.toFixed(2)} / $${sessionLimit}). Wait for session reset or increase budget.`,
+        },
+      };
+    }
+  } catch {}
+
+  // auto/balanced profile: emit warning for tier 3 (pipeline handles consent)
+  if (workStyle === 'auto' || workStyle === 'balanced') {
+    return {
+      systemMessage: `[governance] Tier 3 (heavy) model requested: ${model || 'opus'}. Profile "${workStyle}" requires consent for heavy models. Proceeding — pipeline will handle approval.`,
+    };
+  }
+
+  return null;
+}
+
 const SEARCH_WORDS = /\b(explore|search|find|grep|locate|where\s+is|list\s+files|read[-\s]?only|lookup|scan)\b/i;
 const THINK_WORDS = /\b(plan|design|architect|review|audit|security|code[-\s]?review|threat[-\s]?model|complex[-\s]?debug)\b/i;
 
@@ -257,6 +347,16 @@ try {
   // (If hasMarker is true OR the prompt is read-only we fall through to normal
   //  tier-routing logic below.)
 
+  // ── Governance enforcement (tier 3 gating + budget) ──────────────────────────
+  const govResult = governanceCheck(input);
+  if (govResult) {
+    if (govResult.hookSpecificOutput?.permissionDecision === 'deny') {
+      process.stdout.write(JSON.stringify(govResult));
+      process.exit(2);
+    }
+    // Non-blocking governance warning — will be included in final output
+  }
+
   // Compute prompt hash early for duplicate detection and logging
   const promptHash = computePromptHash(ti);
 
@@ -303,8 +403,9 @@ try {
   let autoStatus = null;
 
   // Helper to prepend optional warnings (duplicate + drift + balance + auto) before a message
+  const govWarning = govResult?.systemMessage || null;
   const prependWarnings = (msg) => {
-    const parts = [duplicateWarning, driftWarning, failureMessage, msg, autoStatus, balanceHint].filter(Boolean);
+    const parts = [govWarning, duplicateWarning, driftWarning, failureMessage, msg, autoStatus, balanceHint].filter(Boolean);
     return parts.join('\n\n');
   };
 
@@ -408,7 +509,7 @@ try {
         followed: true,
         profile: profileName,
       });
-      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
+      const onlyWarnings = [govWarning, duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
       if (onlyWarnings) {
         process.stdout.write(JSON.stringify({ systemMessage: onlyWarnings }));
       } else {
@@ -439,7 +540,7 @@ try {
         followed: true,
         profile: profileName,
       });
-      const onlyWarnings = [duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
+      const onlyWarnings = [govWarning, duplicateWarning, driftWarning, failureMessage, autoStatus, balanceHint].filter(Boolean).join('\n\n');
       if (onlyWarnings) {
         process.stdout.write(JSON.stringify({ systemMessage: onlyWarnings }));
       } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -45,7 +45,9 @@
     "./simmer": "./src/simmer.mjs",
     "./memory-tiers": "./src/memory-tiers.mjs",
     "./envelope": "./src/envelope.mjs",
-    "./session-lock": "./src/session-lock.mjs"
+    "./session-lock": "./src/session-lock.mjs",
+    "./governance": "./src/governance.mjs",
+    "./context-intel": "./src/context-intel.mjs"
   },
   "keywords": [
     "claude-code",
@@ -130,6 +132,8 @@
     "src/memory-tiers.mjs",
     "src/envelope.mjs",
     "src/session-lock.mjs",
+    "src/governance.mjs",
+    "src/context-intel.mjs",
     "bin/*.mjs",
     "hooks/enforce-tier.mjs",
     "hooks/cost-logger.mjs",

package/src/context-intel.mjs

@@ -0,0 +1,156 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export const MODEL_FORMAT = {
+  claude: 'xml', sonnet: 'xml', haiku: 'xml', opus: 'xml',
+  gpt: 'markdown', o3: 'markdown', 'o4-mini': 'markdown',
+};
+
+function detectFormat(targetModel, role) {
+  const m = targetModel.toLowerCase();
+  if (m.includes('o3') || (m.includes('opus') && role === 'thinker')) return 'prose';
+  if (m.includes('gpt') || m.includes('o3') || m.includes('o4')) return 'markdown';
+  return 'xml';
+}
+
+export function selectRelevant(pack, role) {
+  const { intent, constraints, priorAttempts, repoState, fileSummaries,
+          acceptanceCriteria, files } = pack;
+  if (role === 'thinker') {
+    return { intent, constraints, priorAttempts, repoState,
+             fileSummaries, acceptanceCriteria };
+  }
+  if (role === 'worker') {
+    const inScope = [...(files?.explicit || []), ...(files?.gitChanged || [])];
+    return { intent, acceptanceCriteria, constraints, inScope };
+  }
+  // reviewer
+  return { intent, acceptanceCriteria, constraints, fileSummaries, repoState };
+}
+
+function readFiles(paths, cwd) {
+  const base = cwd || process.cwd();
+  const out = {};
+  for (const p of paths) {
+    const abs = resolve(base, p);
+    if (existsSync(abs)) {
+      try { out[p] = readFileSync(abs, 'utf8'); } catch { out[p] = '(unreadable)'; }
+    }
+  }
+  return out;
+}
+
+export function renderForModel(sections, targetModel, role) {
+  const fmt = detectFormat(targetModel, role);
+
+  if (fmt === 'prose') {
+    const parts = [];
+    if (sections.intent) parts.push(`Task: ${sections.intent}`);
+    if (sections.acceptanceCriteria?.length)
+      parts.push(`Success looks like: ${sections.acceptanceCriteria.join('; ')}`);
+    if (sections.constraints?.length)
+      parts.push(`Constraints: ${sections.constraints.join('; ')}`);
+    if (sections.repoState) parts.push(`Repo: ${JSON.stringify(sections.repoState)}`);
+    if (sections.fileSummaries) parts.push(`Files: ${JSON.stringify(sections.fileSummaries)}`);
+    if (sections.priorAttempts?.length)
+      parts.push(`Prior attempts: ${JSON.stringify(sections.priorAttempts)}`);
+    return parts.join('\n\n');
+  }
+
+  if (fmt === 'markdown') {
+    const lines = [];
+    if (sections.intent) lines.push(`## Objective\n${sections.intent}`);
+    if (sections.constraints?.length)
+      lines.push(`## Constraints\n${sections.constraints.map(c => `- ${c}`).join('\n')}`);
+    if (sections.acceptanceCriteria?.length)
+      lines.push(`## Acceptance Criteria\n${sections.acceptanceCriteria.map(c => `- ${c}`).join('\n')}`);
+    if (sections.repoState) lines.push(`## Repo State\n\`\`\`json\n${JSON.stringify(sections.repoState, null, 2)}\n\`\`\``);
+    if (sections.fileSummaries) lines.push(`## Files\n\`\`\`json\n${JSON.stringify(sections.fileSummaries, null, 2)}\n\`\`\``);
+    if (sections.fileContents) {
+      lines.push('## File Contents');
+      for (const [p, content] of Object.entries(sections.fileContents))
+        lines.push(`### ${p}\n\`\`\`\n${content}\n\`\`\``);
+    }
+    if (sections.inScope?.length)
+      lines.push(`## In-Scope Files\n${sections.inScope.map(f => `- ${f}`).join('\n')}`);
+    if (sections.priorAttempts?.length)
+      lines.push(`## Prior Attempts\n${JSON.stringify(sections.priorAttempts, null, 2)}`);
+    return lines.join('\n\n');
+  }
+
+  // xml (Claude models)
+  const tags = [];
+  if (sections.intent) tags.push(`<objective>${sections.intent}</objective>`);
+  if (sections.constraints?.length)
+    tags.push(`<constraints>\n${sections.constraints.map(c => `  <constraint>${c}</constraint>`).join('\n')}\n</constraints>`);
+  if (sections.acceptanceCriteria?.length)
+    tags.push(`<criteria>\n${sections.acceptanceCriteria.map(c => `  <criterion>${c}</criterion>`).join('\n')}\n</criteria>`);
+  if (sections.repoState)
+    tags.push(`<repo_state>${JSON.stringify(sections.repoState)}</repo_state>`);
+  if (sections.fileSummaries)
+    tags.push(`<files>${JSON.stringify(sections.fileSummaries)}</files>`);
+  if (sections.fileContents) {
+    const fc = Object.entries(sections.fileContents)
+      .map(([p, c]) => `  <file path="${p}">\n${c}\n  </file>`).join('\n');
+    tags.push(`<file_contents>\n${fc}\n</file_contents>`);
+  }
+  if (sections.inScope?.length)
+    tags.push(`<in_scope_files>\n${sections.inScope.map(f => `  <file>${f}</file>`).join('\n')}\n</in_scope_files>`);
+  if (sections.priorAttempts?.length)
+    tags.push(`<prior_attempts>${JSON.stringify(sections.priorAttempts)}</prior_attempts>`);
+  return `<context>\n${tags.join('\n')}\n</context>`;
+}
+
+export function enforceTokenBudget(rendered, budget) {
+  const chars = budget * 4;
+  const originalTokens = Math.ceil(rendered.length / 4);
+  if (rendered.length <= chars) return { text: rendered, truncated: false, originalTokens, finalTokens: originalTokens };
+
+  // Try dropping prior_attempts / prior attempts block
+  let text = rendered
+    .replace(/<prior_attempts>[\s\S]*?<\/prior_attempts>/g, '')
+    .replace(/## Prior Attempts[\s\S]*?(?=\n## |$)/, '')
+    .replace(/Prior attempts:.*?(?=\n\n|$)/s, '');
+
+  if (text.length <= chars) return { text: text.trim(), truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+
+  // Summarize git/repo state
+  text = text
+    .replace(/<repo_state>[\s\S]*?<\/repo_state>/g, '<repo_state>(truncated)</repo_state>')
+    .replace(/## Repo State[\s\S]*?(?=\n## |$)/, '## Repo State\n(truncated)');
+
+  if (text.length <= chars) return { text: text.trim(), truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+
+  // Hard truncate
+  text = text.slice(0, chars) + '\n...(truncated)';
+  return { text, truncated: true, originalTokens, finalTokens: Math.ceil(text.length / 4) };
+}
+
+export function attachOutputSchema(role) {
+  if (role === 'thinker')
+    return 'Return JSON: { decision: string, confidence: 0-1, reasoning: string, workSpec: { objective, files, criteria } }';
+  if (role === 'worker')
+    return 'Return JSON: { filesChanged: string[], testsRun: boolean, issues: string[] }';
+  return 'Return JSON: { pass: boolean, findings: [{ severity, file, line, issue, fix }] }';
+}
+
+export function shapeForRole(pack, role, targetModel, tokenBudget) {
+  const sections = selectRelevant(pack, role);
+
+  if (role === 'worker' && sections.inScope?.length) {
+    const cwd = pack.repoState?.cwd;
+    sections.fileContents = readFiles(sections.inScope, cwd);
+  }
+
+  const rendered = renderForModel(sections, targetModel, role);
+  const { text, truncated, originalTokens, finalTokens } = enforceTokenBudget(rendered, tokenBudget);
+  const sectionKeys = Object.keys(sections);
+
+  return { shaped: text, role, model: targetModel, tokenEstimate: finalTokens, sections: sectionKeys };
+}
+
+export function compilePacket(pack, role, targetModel, tokenBudget) {
+  const { shaped } = shapeForRole(pack, role, targetModel, tokenBudget);
+  const schema = attachOutputSchema(role);
+  return `${shaped}\n\n${schema}`;
+}

package/src/dispatch.mjs

@@ -16,6 +16,8 @@ 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';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const USAGE_DIR = join(__dirname, '..', '.dualbrain', 'usage');
@@ -755,6 +757,28 @@ async function dispatch(input = {}) {
   // 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.

package/src/governance.mjs

@@ -0,0 +1,279 @@
+// governance.mjs — Model tier enforcement + multi-model collaboration
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+// ─── Tier Definitions ────────────────────────────────────────────────────────
+
+export const MODEL_TIERS = Object.freeze({
+  1: {
+    label: 'lightweight',
+    models: ['claude-haiku-4-5-20251001', 'haiku', 'gpt-4o-mini', 'o4-mini'],
+    autoApprove: true,
+  },
+  2: {
+    label: 'standard',
+    models: ['claude-sonnet-4-6', 'sonnet', 'gpt-4o', 'gpt-4.1'],
+    autoApprove: true,
+  },
+  3: {
+    label: 'heavy',
+    models: ['claude-opus-4-6', 'claude-opus-4-7', 'opus', 'o3'],
+    autoApprove: false, // requires consent check per profile
+  },
+});
+
+// Reverse lookup: model ID → tier number
+export function getModelTier(modelId) {
+  if (!modelId) return 2; // default to standard
+  const normalized = String(modelId).toLowerCase();
+  for (const [tier, def] of Object.entries(MODEL_TIERS)) {
+    if (def.models.some(m => normalized.includes(m))) return Number(tier);
+  }
+  return 2; // unknown models default to standard
+}
+
+// ─── Task Scoring ────────────────────────────────────────────────────────────
+
+export function scoreTask(detection) {
+  // detection comes from detect.mjs — has intent, risk, scope, files, etc.
+  const scores = {
+    complexity: 0,  // 0-3
+    risk: 0,        // 0-3
+    creativity: 0,  // 0-2
+    precision: 0,   // 0-2
+    contextVolume: 0, // 0-3
+  };
+
+  // Complexity from file count / scope
+  const fileCount = detection?.files?.length || detection?.scope?.fileCount || 0;
+  if (fileCount >= 6) scores.complexity = 3;
+  else if (fileCount >= 3) scores.complexity = 2;
+  else if (fileCount >= 1) scores.complexity = 1;
+
+  // Risk from explicit risk field or keywords
+  const risk = detection?.risk || detection?.riskLevel || 'low';
+  const riskMap = { low: 0, medium: 1, high: 2, critical: 3 };
+  scores.risk = riskMap[risk] ?? 0;
+
+  // Boost risk for security/auth/billing keywords
+  const text = (detection?.objective || detection?.intent || '').toLowerCase();
+  if (/\b(auth|security|credential|secret|billing|payment|migration|delete|drop)\b/.test(text)) {
+    scores.risk = Math.max(scores.risk, 2);
+  }
+
+  // Creativity from intent type
+  const intent = (detection?.intent || detection?.type || '').toLowerCase();
+  if (/\b(architect|design|brainstorm|explore|research)\b/.test(intent)) scores.creativity = 2;
+  else if (/\b(refactor|plan|decide)\b/.test(intent)) scores.creativity = 1;
+
+  // Precision — one-shot tasks need higher precision
+  if (/\b(security|deploy|publish|migration)\b/.test(text)) scores.precision = 2;
+  else if (/\b(implement|build|create)\b/.test(text)) scores.precision = 1;
+
+  // Context volume
+  const contextSize = detection?.contextTokens || detection?.estimatedContext || 0;
+  if (contextSize > 200000) scores.contextVolume = 3;
+  else if (contextSize > 50000) scores.contextVolume = 2;
+  else if (contextSize > 10000) scores.contextVolume = 1;
+
+  return scores;
+}
+
+export function computeRequiredTier(scores) {
+  const total = Object.values(scores).reduce((a, b) => a + b, 0);
+  if (total <= 2) return 1;
+  if (total <= 6) return 2;
+  return 3;
+}
+
+// ─── Governance Assessment ───────────────────────────────────────────────────
+
+// Profile governance defaults
+const GOVERNANCE_PERMISSIONS = {
+  'auto':          { 1: 'auto', 2: 'auto', 3: 'ask' },
+  'balanced':      { 1: 'auto', 2: 'auto', 3: 'ask' },
+  'cost-saver':    { 1: 'auto', 2: 'auto', 3: 'deny' },
+  'quality-first': { 1: 'auto', 2: 'auto', 3: 'auto' },
+};
+
+// Pricing per million tokens (input/output) for cost estimation
+const MODEL_PRICING = {
+  'haiku':  { input: 1.00, output: 5.00 },
+  'sonnet': { input: 3.00, output: 15.00 },
+  'opus':   { input: 5.00, output: 25.00 },
+  'gpt-4o-mini': { input: 0.15, output: 0.60 },
+  'gpt-4o': { input: 2.50, output: 10.00 },
+  'gpt-4.1': { input: 2.00, output: 8.00 },
+  'o3': { input: 2.00, output: 8.00 },
+  'o4-mini': { input: 1.10, output: 4.40 },
+};
+
+function estimateCost(modelId, estimatedTokens = 8000) {
+  const normalized = String(modelId).toLowerCase();
+  let pricing = MODEL_PRICING['sonnet']; // default
+  for (const [key, p] of Object.entries(MODEL_PRICING)) {
+    if (normalized.includes(key)) { pricing = p; break; }
+  }
+  // Assume 20% input, 80% output for agent tasks
+  const inputTokens = estimatedTokens * 0.2;
+  const outputTokens = estimatedTokens * 0.8;
+  return (inputTokens * pricing.input + outputTokens * pricing.output) / 1_000_000;
+}
+
+export function assessGovernance(model, detection, profile) {
+  const tier = getModelTier(model);
+  const scores = scoreTask(detection);
+  const requiredTier = computeRequiredTier(scores);
+  const workStyle = profile?.workStyle || profile?.name || 'auto';
+  const permissions = GOVERNANCE_PERMISSIONS[workStyle] || GOVERNANCE_PERMISSIONS['auto'];
+  const permission = permissions[tier] || 'ask';
+  const estimatedCost = estimateCost(model);
+
+  return {
+    requestedTier: tier,
+    requiredTier,
+    overProvisioned: tier > requiredTier,
+    underProvisioned: tier < requiredTier,
+    permission, // 'auto' | 'ask' | 'deny'
+    estimatedCost,
+    scores,
+    justification: buildJustification(scores, tier, requiredTier),
+  };
+}
+
+function buildJustification(scores, requestedTier, requiredTier) {
+  const parts = [];
+  if (scores.risk >= 2) parts.push('high-risk');
+  if (scores.complexity >= 2) parts.push('complex');
+  if (scores.creativity >= 2) parts.push('creative/architectural');
+  if (scores.contextVolume >= 2) parts.push('large-context');
+  if (requestedTier > requiredTier) parts.push('over-provisioned');
+  if (requestedTier < requiredTier) parts.push('under-provisioned');
+  return parts.join(', ') || 'standard task';
+}
+
+// ─── Collaboration Assessment ────────────────────────────────────────────────
+
+export function shouldCollaborate(detection, governance, profile) {
+  // Never collaborate on tier-1 tasks
+  if (governance.requiredTier <= 1) return { collaborate: false };
+
+  // Never collaborate in cost-saver mode unless explicitly requested
+  const workStyle = profile?.workStyle || profile?.name || 'auto';
+  if (workStyle === 'cost-saver') return { collaborate: false };
+
+  // Check collaboration triggers (need ANY two)
+  const triggers = [];
+  const text = (detection?.objective || detection?.intent || '').toLowerCase();
+
+  if (/\b(auth|security|credential|billing|migration)\b/.test(text)) triggers.push('irreversibility');
+  if (detection?.ambiguity === 'high' || /\b(should we|how to|best approach|tradeoff)\b/.test(text)) triggers.push('ambiguity');
+  if (detection?.novelty === 'high' || /\b(new|first time|never done|greenfield)\b/.test(text)) triggers.push('novelty');
+  if ((detection?.files?.length || 0) >= 4 && /\b(security|performance|ux)\b/.test(text)) triggers.push('cross-domain');
+  if (governance.requestedTier >= 3 && detection?.confidence && detection.confidence < 0.8) triggers.push('low-confidence');
+
+  const shouldDo = triggers.length >= 2;
+
+  return {
+    collaborate: shouldDo,
+    triggers,
+    pattern: shouldDo ? selectPattern(triggers, detection) : null,
+    estimatedOverhead: shouldDo ? estimateCost('gpt-4.1') : 0, // secondary model cost
+  };
+}
+
+function selectPattern(triggers, detection) {
+  const text = (detection?.objective || detection?.intent || '').toLowerCase();
+
+  // Security → adversarial review
+  if (triggers.includes('irreversibility') && /\b(auth|security|credential)\b/.test(text)) {
+    return 'adversarial-review';
+  }
+
+  // Architecture/greenfield → second opinion (perspective rotation reserved for Phase 4)
+  if (triggers.includes('novelty') || triggers.includes('ambiguity')) {
+    return 'second-opinion';
+  }
+
+  // Default
+  return 'second-opinion';
+}
+
+// ─── Governance State (Session Budget Tracking) ──────────────────────────────
+
+const STATE_FILE = '.dualbrain/governance-state.json';
+const SESSION_GAP_MS = 30 * 60 * 1000; // 30 min gap = new session
+
+export function loadGovernanceState(cwd) {
+  const statePath = join(cwd, STATE_FILE);
+  try {
+    const raw = JSON.parse(readFileSync(statePath, 'utf8'));
+    // Check if session is stale
+    const lastDispatch = raw.dispatches?.[raw.dispatches.length - 1];
+    if (lastDispatch && (Date.now() - Date.parse(lastDispatch.ts)) > SESSION_GAP_MS) {
+      // Stale session — reset
+      return freshState();
+    }
+    return raw;
+  } catch {
+    return freshState();
+  }
+}
+
+function freshState() {
+  return {
+    sessionStartedAt: new Date().toISOString(),
+    dispatches: [],
+    totalEstimatedCost: 0,
+    tierCounts: { 1: 0, 2: 0, 3: 0 },
+  };
+}
+
+export function recordDispatch(cwd, tier, model, estimatedCost, approved = true) {
+  const state = loadGovernanceState(cwd);
+  state.dispatches.push({
+    tier,
+    model: String(model),
+    estimatedCost,
+    approved,
+    ts: new Date().toISOString(),
+  });
+  state.totalEstimatedCost += estimatedCost;
+  state.tierCounts[tier] = (state.tierCounts[tier] || 0) + 1;
+
+  const dir = join(cwd, '.dualbrain');
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(cwd, STATE_FILE), JSON.stringify(state, null, 2) + '\n');
+  return state;
+}
+
+export function checkBudget(cwd, orchestratorConfig) {
+  const state = loadGovernanceState(cwd);
+  const sessionLimit = orchestratorConfig?.budgets?.session_limit_usd || 10;
+  const remaining = sessionLimit - state.totalEstimatedCost;
+
+  return {
+    spent: state.totalEstimatedCost,
+    remaining,
+    limit: sessionLimit,
+    warning: remaining < sessionLimit * 0.2, // <20% remaining
+    blocked: remaining <= 0,
+    tierCounts: state.tierCounts,
+  };
+}
+
+// ─── Format for User Display ─────────────────────────────────────────────────
+
+export function formatGovernancePrompt(governance, collaboration) {
+  const tierLabel = MODEL_TIERS[governance.requestedTier]?.label || 'unknown';
+  const lines = [];
+
+  lines.push(`[governance] Task requires ${tierLabel} model (tier ${governance.requestedTier}, ~$${governance.estimatedCost.toFixed(2)})`);
+  if (governance.justification) lines.push(`  Reason: ${governance.justification}`);
+  if (collaboration?.collaborate) {
+    lines.push(`  + ${collaboration.pattern} with secondary model (+$${collaboration.estimatedOverhead.toFixed(2)})`);
+  }
+
+  return lines.join('\n');
+}

package/src/templates.mjs

@@ -142,8 +142,44 @@ const TEMPLATES = {
   },
 };
 
+// ── Output schemas ───────────────────────────────────────────────────────────
+
+const OUTPUT_SCHEMAS = {
+  think: '{ "decision": "string", "confidence": 0.0-1.0, "reasoning": "string", "workSpec": { "objective": "string", "files": ["path"], "criteria": ["string"] } }',
+  execute: '{ "filesChanged": ["path"], "testsRun": boolean, "issues": ["string"] }',
+  review: '{ "pass": boolean, "findings": [{ "severity": "critical|high|medium|low", "file": "path", "line": number, "issue": "string", "fix": "string" }] }',
+  search: '{ "found": [{ "file": "path", "line": number, "snippet": "string" }], "confidence": 0.0-1.0 }',
+};
+
+// ── Model render hints ────────────────────────────────────────────────────────
+
+const MODEL_RENDER_HINTS = {
+  xml: ['claude', 'sonnet', 'haiku', 'opus'],
+  markdown: ['gpt', 'gpt-4', 'gpt-4.1', 'gpt-4o'],
+  prose: ['o3', 'o4-mini'],
+};
+
 // ── Template API ─────────────────────────────────────────────────────────────
 
+/**
+ * Get the structured output schema for a tier.
+ */
+export function getOutputSchema(tier) {
+  return OUTPUT_SCHEMAS[tier] || null;
+}
+
+/**
+ * Get the preferred prompt rendering format for a given model ID.
+ */
+export function getRenderHint(modelId) {
+  if (!modelId) return 'markdown';
+  const normalized = String(modelId).toLowerCase();
+  for (const [format, patterns] of Object.entries(MODEL_RENDER_HINTS)) {
+    if (patterns.some(p => normalized.includes(p))) return format;
+  }
+  return 'markdown';
+}
+
 /**
  * Get a template by tier name.
  */
@@ -193,6 +229,7 @@ export function renderPrompt(tier, contract, context = {}) {
     errors: [],
     template: { id: template.id, version: template.version },
     contract: { ...contract, id: contract.id || Date.now().toString(36) },
+    outputSchema: OUTPUT_SCHEMAS[tier] || null,
     stats: {
       words: prompt.split(/\s+/).length,
       chars: prompt.length,