dual-brain 0.2.22 → 0.2.24

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

@@ -290,7 +290,19 @@ const THINK_WORDS = /\b(plan|design|architect|review|audit|security|code[-\s]?re
 const WRITE_INTENT_WORDS = /\b(edit|fix|change|update|create|write|modify|implement|refactor|add|remove|delete|build|install|configure|patch|apply|move|rename|migrate|replace|rewrite|generate|scaffold|init(?:ialize)?|setup|deploy|run\s+tests?|commit|push|install|uninstall)\b/i;
 
 // Dispatch marker prefix stamped by src/dispatch.mjs for all legitimate dispatches.
-const DISPATCH_MARKER_RE = /<!--\s*dual-brain-dispatch:\s*[a-z0-9]+\s*-->/i;
+const DISPATCH_MARKER_RE = /<!--\s*dual-brain-dispatch:[a-z0-9|:.\-]+\s*-->/i;
+
+function parseDispatchMarker(prompt) {
+  const match = prompt?.match(/<!-- dual-brain-dispatch:([^>]+) -->/);
+  if (!match) return null;
+  const parts = match[1].split('|');
+  const fields = { runId: parts[0] };
+  for (const part of parts.slice(1)) {
+    const [key, val] = part.split(':');
+    if (key && val) fields[key] = val;
+  }
+  return fields;
+}
 
 /**
  * Determine whether a prompt is purely read-only (no write keywords at all).
@@ -357,6 +369,22 @@ try {
     // Non-blocking governance warning — will be included in final output
   }
 
+  // ── Over-provisioning check via enriched dispatch marker ───────────────────
+  // If the marker carries governance scores, validate that the model tier isn't
+  // higher than the task actually requires (closes the brainstorm-opus loophole).
+  const markerFields = parseDispatchMarker(rawPrompt);
+  if (markerFields?.req && markerFields?.model) {
+    const reqTier = parseInt(markerFields.req, 10);
+    const modelTier = getGovernanceTier(markerFields.model);
+    if (!isNaN(reqTier) && modelTier > reqTier && reqTier <= 2) {
+      process.stdout.write(JSON.stringify({
+        systemMessage: `[governance] Over-provisioned: task requires tier ${reqTier} but using tier ${modelTier} model (${markerFields.model}). Consider downgrading.`,
+      }));
+      process.exit(0);
+    }
+  }
+  // ── End over-provisioning check ────────────────────────────────────────────
+
   // Compute prompt hash early for duplicate detection and logging
   const promptHash = computePromptHash(ti);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dual-brain",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration",
   "type": "module",
   "bin": {
@@ -46,7 +46,8 @@
     "./memory-tiers": "./src/memory-tiers.mjs",
     "./envelope": "./src/envelope.mjs",
     "./session-lock": "./src/session-lock.mjs",
-    "./governance": "./src/governance.mjs"
+    "./governance": "./src/governance.mjs",
+    "./context-intel": "./src/context-intel.mjs"
   },
   "keywords": [
     "claude-code",
@@ -132,6 +133,7 @@
     "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,9 @@ 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');
@@ -704,8 +707,8 @@ function _renderTemplatedPrompt(prompt, decision, context = {}) {
 // 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> -->
-// runId is a short timestamp-based ID that ties back to this dispatch session.
+// 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;
 
@@ -717,9 +720,14 @@ function _getDispatchRunId() {
   return _dispatchRunId;
 }
 
-function _prependDispatchMarker(prompt) {
+function _prependDispatchMarker(prompt, decision = {}) {
   const runId = _getDispatchRunId();
-  return `<!-- dual-brain-dispatch: ${runId} -->\n${prompt}`;
+  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 ────────────────────────────────────────────────
@@ -755,6 +763,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.
@@ -821,7 +851,12 @@ async function dispatch(input = {}) {
 
   // Stamp the prompt with the dispatch marker so enforce-tier.mjs can recognise
   // that this agent call came through the official pipeline.
-  prompt = _prependDispatchMarker(prompt);
+  // 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.
@@ -1125,7 +1160,7 @@ async function dispatch(input = {}) {
     }
     // ── End auto-review annotation ────────────────────────────────────────────
 
-    return {
+    const nativeResult = {
       status:        success ? 'completed' : 'failed',
       type:          'native-agent',
       provider:      currentProvider,
@@ -1142,6 +1177,11 @@ async function dispatch(input = {}) {
       authVerified:  true,
       error: success ? null : errorText.slice(0, 200),
     };
+    try {
+      const { recordDispatchOutcome } = await import('./outcome.mjs');
+      recordDispatchOutcome(input, nativeResult);
+    } catch { /* never block */ }
+    return nativeResult;
   }
 
   const command = buildCommand(effectiveDecision, prompt, files, cwd);
@@ -1244,7 +1284,7 @@ async function dispatch(input = {}) {
   }
   // ── End auto-review annotation ──────────────────────────────────────────────
 
-  return {
+  const subResult = {
     status:      success ? 'completed' : 'failed',
     provider:    subProvider,
     model:       subModel,
@@ -1259,6 +1299,11 @@ async function dispatch(input = {}) {
     authVerified: true,
     error: success ? null : errorText.slice(0, 200),
   };
+  try {
+    const { recordDispatchOutcome } = await import('./outcome.mjs');
+    recordDispatchOutcome(input, subResult);
+  } catch { /* never block */ }
+  return subResult;
 }
 
 // ─── Dual-brain dispatch (parallel) ───────────────────────────────────────────
@@ -1271,7 +1316,12 @@ async function dispatchDualBrain(input = {}) {
   prompt = redact(prompt);
 
   // Stamp with dispatch marker so enforce-tier.mjs allows this Agent call
-  prompt = _prependDispatchMarker(prompt);
+  // 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()

package/src/outcome.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, appendFileSync, readFileSync, existsSync } from 'fs';
+import { mkdirSync, appendFileSync, writeFileSync, readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { randomUUID } from 'crypto';
 
@@ -44,6 +44,36 @@ function last7DaysFiles(cwd) {
   return files;
 }
 
+export function recordDispatchOutcome(dispatchInput, result) {
+  try {
+    const cwd = dispatchInput.cwd ?? process.cwd();
+    const decision = dispatchInput.decision ?? {};
+    ensureDir(cwd);
+
+    const id = `out_${Date.now().toString(36)}`;
+    const record = {
+      id,
+      timestamp: new Date().toISOString(),
+      prompt: (dispatchInput.prompt ?? '').slice(0, 200),
+      tier: decision.tier ?? result.tier ?? 'execute',
+      model: decision.model ?? result.model ?? 'unknown',
+      provider: decision.provider ?? result.provider ?? 'unknown',
+      success: result.status === 'success' || result.status === 'completed',
+      status: result.status ?? 'unknown',
+      durationMs: result.durationMs ?? 0,
+      filesChanged: result.filesChanged?.length ?? 0,
+      errors: (result.errors ?? (result.error ? [result.error] : [])).slice(0, 3),
+      lesson: '',
+    };
+
+    const filePath = join(outcomesDir(cwd), `outcome_${id}.json`);
+    writeFileSync(filePath, JSON.stringify(record, null, 2), 'utf8');
+    return record;
+  } catch {
+    return null;
+  }
+}
+
 export function computeRoutingScore(plan, result, verification) {
   let score = 3;
   if (result.success && result.duration < 60_000) score += 1;

package/src/pipeline.mjs

@@ -12,6 +12,8 @@ import { dispatch } from './dispatch.mjs';
 import { loadProfile } from './profile.mjs';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { buildContextPack as buildContextPackIntel } from './context.mjs';
+import { compilePacket } from './context-intel.mjs';
 
 // Lazy-load collaboration module
 let _collab = null;
@@ -648,6 +650,143 @@ function runGate(run, gateName, gateFn) {
   return result.passed;
 }
 
+// ─── Pre-dispatch think (Position 1: context intelligence) ───────────────────
+
+/**
+ * Optionally spawn a cheap think agent to produce a refined work spec before
+ * the real dispatch. Non-blocking on any failure.
+ *
+ * @param {string}   prompt
+ * @param {string[]} files
+ * @param {object}   decision   — from plan._decision
+ * @param {string}   cwd
+ * @param {object}   profile
+ * @param {object}   [opts]
+ * @param {boolean}  [opts._skipPreDispatchThink]  — set true on recursive calls
+ * @param {object}   [opts.log]                    — logging function
+ * @returns {Promise<{ refined: boolean, prompt?, files?, decision? }>}
+ */
+async function preDispatchThink(prompt, files, decision, cwd, profile, opts = {}) {
+  const log = opts.log ?? (() => {});
+
+  // Guard: never recurse
+  if (opts._skipPreDispatchThink) {
+    log('[dual-brain] pre-dispatch think: skipped (recursive call)');
+    return { refined: false };
+  }
+
+  // Guard: only execute/think tiers
+  const tier = decision?.tier ?? 'execute';
+  if (tier === 'search') {
+    log('[dual-brain] pre-dispatch think: skipped (search tier)');
+    return { refined: false };
+  }
+
+  // Guard: governance tier >= 2 (map tier names to numeric levels)
+  const TIER_LEVEL = { search: 1, execute: 2, think: 3 };
+  const tierLevel = TIER_LEVEL[tier] ?? 2;
+  if (tierLevel < 2) {
+    log('[dual-brain] pre-dispatch think: skipped (tier < 2)');
+    return { refined: false };
+  }
+
+  // Guard: decision confidence must be < 0.9
+  const confidence = decision?.confidence ?? 0.5;
+  if (confidence >= 0.9) {
+    log('[dual-brain] pre-dispatch think: skipped (confidence >= 0.9)');
+    return { refined: false };
+  }
+
+  // Guard: not cost-saver work style
+  try {
+    const style = getWorkStyle(profile);
+    if (style.key === 'cost-saver') {
+      log('[dual-brain] pre-dispatch think: skipped (cost-saver profile)');
+      return { refined: false };
+    }
+  } catch {
+    // profile unavailable — proceed
+  }
+
+  try {
+    log('[dual-brain] pre-dispatch think: refining work spec...');
+
+    // Build the thinker context pack
+    const pack = await buildContextPackIntel(prompt, files, cwd);
+
+    // Compile to a thinker-shaped prompt (sonnet, 3000 token budget)
+    const thinkerPrompt = compilePacket(pack, 'thinker', 'sonnet', 3000);
+
+    // Dispatch to a think agent — use sonnet, tier=think, skip all extras
+    const thinkDecision = {
+      provider: 'claude',
+      model: 'sonnet',
+      tier: 'think',
+      confidence: 1,   // internal call — fully confident
+    };
+
+    const thinkResult = await dispatch({
+      decision: thinkDecision,
+      prompt: thinkerPrompt,
+      files: [],
+      cwd,
+      dryRun: false,
+      verbose: false,
+      profile,
+      _skipPreDispatchThink: true,
+      _skipRelatedContext: true,
+    });
+
+    // Parse the think result — expect JSON with { decision, confidence, workSpec }
+    let parsed = null;
+    try {
+      const raw = typeof thinkResult === 'string'
+        ? thinkResult
+        : (thinkResult?.output ?? thinkResult?.result ?? thinkResult?.text ?? JSON.stringify(thinkResult));
+
+      // Extract JSON from possible prose wrapping
+      const jsonMatch = raw.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        parsed = JSON.parse(jsonMatch[0]);
+      }
+    } catch {
+      // JSON parse failed — proceed unchanged
+    }
+
+    if (!parsed || typeof parsed.confidence !== 'number' || parsed.confidence <= 0.7) {
+      const reason = !parsed ? 'unparseable response' : `confidence ${parsed.confidence} <= 0.7`;
+      log(`[dual-brain] pre-dispatch think: skipped (${reason})`);
+      return { refined: false };
+    }
+
+    const ws = parsed.workSpec;
+    if (!ws || !ws.objective) {
+      log('[dual-brain] pre-dispatch think: skipped (no workSpec.objective)');
+      return { refined: false };
+    }
+
+    // Apply refinements
+    const newObjective = ws.objective;
+    const newFiles     = [...new Set([...files, ...(ws.files ?? [])])];
+    const newDecision  = ws.criteria?.length
+      ? { ...decision, acceptanceCriteria: [...(decision.acceptanceCriteria ?? []), ...ws.criteria] }
+      : decision;
+
+    log(`[dual-brain] think refined: "${newObjective.slice(0, 60)}..." (confidence: ${parsed.confidence})`);
+
+    return {
+      refined:  true,
+      prompt:   newObjective,
+      files:    newFiles,
+      decision: newDecision,
+    };
+  } catch (err) {
+    // Non-blocking on any failure
+    log(`[dual-brain] pre-dispatch think: skipped (error: ${err.message})`);
+    return { refined: false };
+  }
+}
+
 // ─── Main entry point ─────────────────────────────────────────────────────────
 
 /**
@@ -1070,7 +1209,33 @@ export async function runPipeline(trigger, prompt, options = {}) {
       }
     }
 
-    const decision = { ...run.plan._decision };
+    let decision = { ...run.plan._decision };
+
+    // ── Pre-dispatch think (Position 1: context intelligence) ────────────────
+    // For tier-2+ non-trivial tasks with decision confidence < 0.9, spawn a
+    // cheap sonnet think agent to produce a refined work spec before the real
+    // dispatch. Non-blocking — if it fails or confidence is low, proceed as-is.
+    {
+      const thinkRefinement = await preDispatchThink(
+        effectivePrompt,
+        files,
+        decision,
+        cwd,
+        run.context?.profile ?? {},
+        { log, _skipPreDispatchThink: options._skipPreDispatchThink }
+      );
+      if (thinkRefinement.refined) {
+        // Mutate locals so both collab and direct paths use the refined inputs
+        // (effectivePrompt is const — store refinement in a mutable local)
+        run._thinkRefinedPrompt  = thinkRefinement.prompt;
+        run._thinkRefinedFiles   = thinkRefinement.files;
+        decision                 = thinkRefinement.decision;
+      }
+    }
+
+    // Resolve the (possibly refined) prompt and file list for dispatch
+    const dispatchPrompt = run._thinkRefinedPrompt ?? effectivePrompt;
+    const dispatchFiles  = run._thinkRefinedFiles  ?? files;
 
     // ── HEAD judgment injection into agent prompts ─────────────────────────────
     // HEAD's obligations, noticings, and uncertainties flow to the work agent
@@ -1130,13 +1295,13 @@ export async function runPipeline(trigger, prompt, options = {}) {
 
       // Inject collaboration context + HEAD judgment into prompt
       const collabContext = collab.buildAgentContext(session, primaryId);
-      const promptParts = [collabContext, headJudgmentBlock, effectivePrompt].filter(Boolean);
+      const promptParts = [collabContext, headJudgmentBlock, dispatchPrompt].filter(Boolean);
       const collabPrompt = promptParts.join('\n\n');
 
       run.result = await dispatch({
         decision,
         prompt: collabPrompt,
-        files,
+        files: dispatchFiles,
         cwd,
         dryRun: false,
         verbose,
@@ -1192,13 +1357,13 @@ export async function runPipeline(trigger, prompt, options = {}) {
       try { collab.persistEvents(session, cwd); } catch {}
     } else {
       const directPrompt = headJudgmentBlock
-        ? `${headJudgmentBlock}\n\n${effectivePrompt}`
-        : effectivePrompt;
+        ? `${headJudgmentBlock}\n\n${dispatchPrompt}`
+        : dispatchPrompt;
 
       run.result = await dispatch({
         decision,
         prompt: directPrompt,
-        files,
+        files: dispatchFiles,
         cwd,
         dryRun: false,
         verbose,

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,