dual-brain 6.1.1 → 7.0.1

package/AGENTS.md

@@ -0,0 +1,97 @@
+# Dual-Brain Orchestrator — Codex Agent Instructions
+
+You are a **work provider** in a dual-brain system. Claude Code is the orchestrator.
+You are dispatched by `src/dispatch.mjs` to handle execute-tier tasks. Do not orchestrate — implement.
+
+## Your Role
+
+- **Tier**: Execute (`gpt-4.1` default, `o4-mini` for search, `gpt-5.4`/`gpt-5.5` for think-heavy work)
+- **Dispatched by**: `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`
+- **You receive**: a scoped task, acceptance criteria, and file context
+- **You return**: structured output (files changed, tests run, edge cases found)
+
+You are NOT the orchestrator. Do not run `dual-brain go` or re-route tasks. Complete the work handed to you.
+
+## Core Architecture (v6)
+
+Four modules in `src/` form the decision pipeline:
+
+- **`profile.mjs`** — Active profile, provider availability, subscription plan
+- **`detect.mjs`** — Task intent, risk, complexity, tier classification
+- **`decide.mjs`** — Provider/model/tier routing; budget pressure and dual-brain threshold
+- **`dispatch.mjs`** — Executes decisions: Claude subagent, GPT via Codex, or dual-brain flow
+
+## Tier System
+
+| Tier | Model | Scope |
+|------|-------|-------|
+| Search | `o4-mini` | Read-only lookups, grep, explore |
+| Execute | `gpt-4.1` | Edits, tests, git ops |
+| Think | `gpt-5.4` / `gpt-5.5` | Architecture (usually Claude-side) |
+
+## Structured Output Format
+
+After completing any task, output a JSON block so the orchestrator can parse results:
+
+```json
+{
+  "status": "done",
+  "files_changed": ["src/foo.mjs", "src/bar.mjs"],
+  "tests_run": ["npm test -- --grep foo"],
+  "edge_cases": ["what happens when X is null"],
+  "notes": "optional freeform"
+}
+```
+
+For search-tier tasks, include `"files_found"` and `"line_refs"` instead of `files_changed`.
+
+## Security Rules (No Exceptions)
+
+- **Never** write secrets, tokens, or credentials to files
+- **Never** implement auth/credential changes without a task brief that includes dual-brain approval
+- If the task touches auth, credentials, billing, or migrations: stop, output `"status": "needs_approval"`, and explain why
+- Use `--sandbox` mode when available; prefer `--approval-mode suggest` for destructive operations
+
+## Quality Gate
+
+Before finishing a session with code changes, run:
+
+```bash
+node .claude/hooks/session-report.mjs
+node .claude/hooks/quality-gate.mjs
+```
+
+Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (escalate).
+
+## Codex CLI Flags
+
+```bash
+codex --approval-mode suggest          # Prompt before destructive shell ops
+codex --sandbox                        # Isolate filesystem writes
+codex exec --json "..."                # Programmatic output (used by dispatch.mjs)
+```
+
+When invoked by dispatch.mjs, `--json` output is expected. Always emit valid JSON in the structured output block.
+
+## Routing Rules (for context)
+
+1. Tasks under 3 min → Claude handles directly (Codex startup overhead not worth it)
+2. Isolated tasks over 3 min → routed here by budget-balancer
+3. High-risk decisions → dual-brain think (Claude + GPT deliberate before you implement)
+4. Tier priority: think > execute > search
+
+## Risk Classification
+
+| Risk | Examples | Action |
+|------|----------|--------|
+| Critical | auth, secrets, tokens | Requires dual-brain approval before you touch it |
+| High | billing, migrations | Confirm task brief includes approval |
+| Medium | tests, utilities | Implement, note edge cases |
+| Low | docs, comments | Implement freely |
+
+## Hardcoded Stops
+
+Do not proceed if:
+- No task brief provided (ask for one via `"status": "needs_brief"`)
+- Task scope exceeds 5 production files with no wave plan
+- Task involves routing/dispatcher/tier logic changes without dual-brain sign-off

package/agents/implementer.md

@@ -0,0 +1,22 @@
+# Implementer Agent
+
+You are a write-capable execution agent. Your role is to implement changes per a provided brief — no more, no less.
+
+## Role
+Execute changes exactly as specified in the brief. Run tests after every edit. Report what changed, what was tested, and any edge cases encountered.
+
+## Allowed Tools
+All tools are available: Read, Edit, Write, NotebookEdit, Bash, Agent, WebSearch, WebFetch.
+
+## Rules
+- Implement only what the brief specifies — do not expand scope
+- Run tests after completing edits (`node --test src/test.mjs` or the project test command)
+- Never modify auth, credentials, or secrets without a dual-brain think decision on record
+- If scope is unclear, stop and report — do not guess
+
+## Output Format
+Return:
+- Files changed (absolute paths)
+- Tests run and result (pass / fail / skipped)
+- Edge cases encountered
+- Any deviations from the brief (with reason)

package/agents/researcher.md

@@ -0,0 +1,25 @@
+# Researcher Agent
+
+You are a read-only research agent. Your role is to investigate, find code, and explore architecture — never to modify files.
+
+## Role
+Investigate the codebase, find relevant files, explore architecture, and report findings clearly with file paths and line references.
+
+## Allowed Tools
+- Read
+- Bash (grep, find, cat — read-only commands only)
+- WebSearch
+- WebFetch
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Output Format
+Return:
+- Files found (absolute paths)
+- Line references for key code
+- Confidence level (high / medium / low)
+- Summary of findings

package/agents/verifier.md

@@ -0,0 +1,30 @@
+# Verifier Agent
+
+You are a read-only verification agent. Your role is to run tests, lint, and type-check — never to modify files.
+
+## Role
+Verify correctness of the codebase after changes. Run all available test suites, report pass/fail, coverage delta, and any regressions.
+
+## Allowed Tools
+- Read
+- Bash (test runners, lint, type-check — no file modifications)
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Verification Steps
+1. Run core tests: `node --test src/test.mjs`
+2. Run hook tests if available: `node hooks/test-orchestrator.mjs`
+3. Check for lint errors if a linter is configured
+4. Report coverage delta if measurable
+
+## Output Format
+Return:
+- Test result: pass / fail
+- Tests run count and breakdown
+- Regressions found (test name, failure message)
+- Coverage delta (if available)
+- Recommendation: safe to merge / needs fixes

package/bin/dual-brain.mjs

@@ -10,6 +10,7 @@ import {
   ensureProfile, loadProfile, saveProfile, runOnboarding,
   rememberPreference, forgetPreference, getActivePreferences,
   getAvailableProviders, isSoloBrain, getHeadModel,
+  detectAuth, detectEnvironment,
 } from '../src/profile.mjs';
 
 import { detectTask } from '../src/detect.mjs';
@@ -45,6 +46,7 @@ dual-brain <command> [options]
 
 Commands:
   init                      First-time setup (providers, plans, optimization)
+  auth                      Show authentication status for all providers
   install                   Install Claude Code hooks into the current project
   go "task description"     Detect → decide → dispatch a task
     --dry-run               Show routing decision without executing
@@ -64,6 +66,44 @@ Options:
 `.trim());
 }
 
+// ─── Auth helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Print a compact auth status table to stdout.
+ * @param {{ claude: object, openai: object }} auth  Result from detectAuth()
+ */
+function printAuthTable(auth) {
+  const W = 55; // inner width (wide enough for source labels)
+  const bar = '═'.repeat(W);
+  const pad = (s) => {
+    const visible = s.replace(/[̀-ͯ]/g, ''); // strip combining chars for length
+    return s + ' '.repeat(Math.max(0, W - visible.length));
+  };
+
+  const claudeLine1 = auth.claude.found
+    ? `  Claude:  ✓ found via ${auth.claude.source}`
+    : `  Claude:  ✗ not found`;
+  const claudeLine2 = auth.claude.found
+    ? `           ${auth.claude.masked}`
+    : `           run: claude auth login`;
+
+  const openaiLine1 = auth.openai.found
+    ? `  OpenAI:  ✓ found via ${auth.openai.source}`
+    : `  OpenAI:  ✗ not found`;
+  const openaiLine2 = auth.openai.found
+    ? `           ${auth.openai.masked}`
+    : `           run: codex auth  OR  export OPENAI_API_KEY=sk-...`;
+
+  console.log(`╔${bar}╗`);
+  console.log(`║${pad('  Auth Status')}║`);
+  console.log(`╠${bar}╣`);
+  console.log(`║${pad(claudeLine1)}║`);
+  console.log(`║${pad(claudeLine2)}║`);
+  console.log(`║${pad(openaiLine1)}║`);
+  console.log(`║${pad(openaiLine2)}║`);
+  console.log(`╚${bar}╝`);
+}
+
 // ─── Card command (default) ──────────────────────────────────────────────────
 
 async function cmdCard() {
@@ -83,19 +123,70 @@ async function cmdCard() {
   const health  = getHealth(cwd);
   const card    = formatSessionCard(session, repo, health);
   console.log(card);
+
+  // Auth status warnings (non-blocking)
+  const auth = await detectAuth();
+  const warnings = [];
+  if (!auth.claude.found) warnings.push('Claude auth not found — run: claude auth login');
+  if (!auth.openai.found) warnings.push('OpenAI auth not found — run: codex auth  OR  export OPENAI_API_KEY=sk-...');
+  if (warnings.length > 0) {
+    console.log('\nAuth warnings:');
+    for (const w of warnings) console.log(`  ⚠  ${w}`);
+  }
+
+  // Environment info
+  const env = detectEnvironment();
+  if (env.isReplit || env.hasReplitTools) {
+    const envLabel = env.hasReplitTools ? 'Replit + replit-tools' : 'Replit';
+    console.log(`\nRuntime: ${envLabel}`);
+  }
 }
 
 // ─── Commands ─────────────────────────────────────────────────────────────────
 
 async function cmdInit() {
-  const profile = await runOnboarding({ interactive: true });
-  saveProfile(profile, { cwd: process.cwd() });
-  const rt = await detectRuntime();
-  const providers = getAvailableProviders(profile);
-  const providerSummary = providers.length
-    ? providers.map(p => `${p.name === 'claude' ? 'Claude' : 'OpenAI'} (${p.plan})`).join(', ')
-    : 'none';
-  console.log(`Profile saved. Providers: ${providerSummary}. Mode: ${profile.mode}. Runtime: ${rt.runtime}`);
+  const cwd = process.cwd();
+
+  // --- Step 1: Auth preflight ---
+  const auth = await detectAuth();
+  printAuthTable(auth);
+
+  const noneFound = !auth.claude.found && !auth.openai.found;
+  if (noneFound) {
+    console.log('\nNo AI provider credentials found. Set up at least one before continuing:\n');
+    console.log('  Claude : claude auth login');
+    console.log('  OpenAI : codex auth   OR   export OPENAI_API_KEY=sk-...\n');
+    console.log('Re-run "dual-brain init" after authenticating.');
+    return;
+  }
+
+  // --- Step 2: Run onboarding wizard, skipping tiers for auto-detected plans ---
+  const profile = await runOnboarding({ interactive: true, detectedAuth: auth });
+  saveProfile(profile, { cwd });
+
+  // --- Step 3: Show dashboard + next step ---
+  console.log('');
+  const repo    = loadRepoCache(cwd);
+  const session = loadSession(cwd);
+  const health  = getHealth(cwd);
+  const card    = formatSessionCard(session, repo, health);
+  console.log(card);
+  console.log('\nReady! Try: dual-brain go "your task here"\n');
+}
+
+async function cmdAuth() {
+  const auth = await detectAuth();
+  printAuthTable(auth);
+
+  // If anything is missing, print setup commands
+  if (!auth.claude.found) {
+    console.log('\nTo set up Claude:');
+    console.log('  claude auth login');
+  }
+  if (!auth.openai.found) {
+    console.log('\nTo set up OpenAI:');
+    console.log('  codex auth   OR   export OPENAI_API_KEY=sk-...');
+  }
 }
 
 async function cmdGo(args) {
@@ -410,6 +501,7 @@ async function main() {
 
   if (cmd === 'init')     { await cmdInit(); return; }
   if (cmd === 'install')  { await cmdInstall(); return; }
+  if (cmd === 'auth')     { await cmdAuth(); return; }
   if (cmd === 'go')       { await cmdGo(args.slice(1)); return; }
   if (cmd === 'status')   { await cmdStatus(args.slice(1)); return; }
   if (cmd === 'hot')      { cmdHot(args[1]); return; }

package/hooks/enforce-tier.mjs

@@ -195,6 +195,20 @@ function quickPressureCheck(tier) {
 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;
 
+// ─── Write-intent enforcement ─────────────────────────────────────────────────
+// Keywords that indicate an agent will mutate files or system state.
+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;
+
+/**
+ * Determine whether a prompt is purely read-only (no write keywords at all).
+ */
+function isReadOnly(prompt) {
+  return !WRITE_INTENT_WORDS.test(prompt);
+}
+
 function preferredModel(config, tier) {
   const models = config?.subscriptions?.claude?.models ?? {};
   for (const [name, meta] of Object.entries(models)) {
@@ -212,10 +226,37 @@ try {
   }
 
   const ti = input.tool_input || {};
-  const text = `${ti.description || ''} ${ti.prompt || ''}`.toLowerCase();
+  // Use the raw prompt for dispatch-marker and write-intent checks (before lowercasing).
+  const rawPrompt = `${ti.description || ''} ${ti.prompt || ''}`;
+  const text = rawPrompt.toLowerCase();
   const subType = (ti.subagent_type || '').toLowerCase();
   const currentModel = (ti.model || '').toLowerCase();
 
+  // ── Dispatch pipeline gate ─────────────────────────────────────────────────
+  // Block write-capable agents that did NOT come through src/dispatch.mjs.
+  // Legitimate dispatches have a <!-- dual-brain-dispatch: <runId> --> marker
+  // prepended to the prompt by dispatch() / dispatchDualBrain().
+  //
+  // Skip enforcement when already inside a subagent (agent_id present) —
+  // nested agent spawns from within a work agent are fine.
+  const hasMarker = DISPATCH_MARKER_RE.test(rawPrompt);
+  const inSubagent = Boolean(input.agent_id);
+
+  if (!inSubagent && !hasMarker && !isReadOnly(rawPrompt)) {
+    // Write-intent detected in HEAD session without the dispatch marker → block.
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason:
+          '[dual-brain] Write-capable agents must go through dispatch. Use: dual-brain go "task"',
+      },
+    }));
+    process.exit(2);
+  }
+  // (If hasMarker is true OR the prompt is read-only we fall through to normal
+  //  tier-routing logic below.)
+
   // Compute prompt hash early for duplicate detection and logging
   const promptHash = computePromptHash(ti);
 

package/hooks/head-guard.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// head-guard.mjs — Blocks HEAD from using mutation tools.
+// Reads Claude Code hook stdin JSON protocol (PreToolUse event).
+//
+// Protocol (Claude Code sends this on stdin):
+//   { session_id, hook_event_name, tool_name, tool_input,
+//     tool_use_id, agent_id?, agent_type? }
+//
+// Exit behaviour:
+//   exit 0                     → allow
+//   exit 2 + stdout JSON       → block (permissionDecision: "deny")
+//
+// Key insight: `agent_id` is present when the hook fires inside a spawned
+// subagent (work agent). If absent we are in the HEAD session.
+
+import { readFileSync } from 'fs';
+
+const BLOCKED_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'Bash']);
+
+// Read stdin JSON payload
+let input;
+try {
+  const raw = readFileSync('/dev/stdin', 'utf8');
+  input = JSON.parse(raw);
+} catch {
+  // If we can't read / parse input, fail open — don't break sessions
+  // that aren't using dual-brain at all.
+  process.exit(0);
+}
+
+const toolName = input.tool_name || '';
+
+// If this hook is firing inside a subagent, ALLOW — subagents are work agents
+// and are permitted to edit/write/bash.
+if (input.agent_id) {
+  process.exit(0);
+}
+
+// HEAD session: block direct mutation tools
+if (BLOCKED_TOOLS.has(toolName)) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        `[dual-brain] HEAD cannot use ${toolName} directly. Dispatch via: dual-brain go "task description"`,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(2);
+}
+
+// Also block MCP filesystem write tools (any mcp__ tool with write/create/
+// delete/remove/move/rename in the name).
+if (toolName.startsWith('mcp__') && /write|create|delete|remove|move|rename/i.test(toolName)) {
+  const output = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        '[dual-brain] HEAD cannot use MCP write tools. Dispatch via: dual-brain go "task description"',
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+  process.exit(2);
+}
+
+// Allow everything else (Read, Agent handled by enforce-tier, etc.)
+process.exit(0);

package/hooks/head-guard.sh

@@ -1,12 +1,14 @@
 #!/usr/bin/env bash
-# head-guard.sh — PreToolUse hook that blocks the HEAD agent from directly implementing code.
+# head-guard.sh — DEPRECATED. Replaced by head-guard.mjs.
 #
-# Claude Code calls this before every tool invocation:
-#   - CLAUDE_TOOL_NAME  = name of the tool being called (e.g. "Edit", "Bash")
-#   - stdin             = tool input as JSON
+# This file is kept for reference only. It never worked correctly because it
+# reads CLAUDE_TOOL_NAME from the environment, but Claude Code delivers tool
+# info via stdin JSON, not environment variables.
 #
-# Exit 0  → allow
-# Exit 2  → block  (stderr message is shown to Claude)
+# The replacement (head-guard.mjs) reads stdin JSON, detects HEAD vs subagent
+# via `agent_id`, and returns the correct permissionDecision block format.
+#
+# Do not use this file. See hooks/head-guard.mjs instead.
 
 BLOCK_MSG='[dual-brain] HEAD cannot use this tool directly. Dispatch via: dual-brain go "task description"'
 

package/mcp-server/README.md

@@ -0,0 +1,81 @@
+# dual-brain MCP Server
+
+Exposes dual-brain's routing engine as MCP tools so any MCP-compatible client (VS Code, Cursor, Windsurf, etc.) can use smart provider/model routing.
+
+## Usage
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "dual-brain": {
+      "command": "node",
+      "args": ["node_modules/dual-brain/mcp-server/index.mjs"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "dual-brain": {
+      "command": "node",
+      "args": ["/path/to/dual-brain/mcp-server/index.mjs"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `dual_brain_detect`
+Classify a task into intent, risk, complexity, and tier.
+
+```json
+{ "prompt": "refactor the auth module", "files": ["src/auth.mjs"] }
+```
+
+Returns: `{ intent, risk, complexity, effort, tier, requiresWrite, explanation }`
+
+### `dual_brain_decide`
+Full routing decision — detect + route to provider and model.
+
+```json
+{ "prompt": "fix the login bug", "files": ["src/auth.mjs"], "profile": "quality-first" }
+```
+
+Returns: `{ provider, model, effort, tier, dualBrain, explanation, detection }`
+
+### `dual_brain_status`
+Provider health, routing scores, and session stats.
+
+```json
+{}
+```
+
+Returns: `{ providers: { claude: {...}, openai: {...} }, session, profile }`
+
+### `dual_brain_remember`
+Save a routing preference that persists across sessions.
+
+```json
+{ "preference": "prefer claude for architecture tasks" }
+```
+
+Returns: `{ saved: true, preference, preferences: string[] }`
+
+## Standalone test
+
+```bash
+node mcp-server/index.mjs
+```
+
+Then send JSON-RPC over stdin:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node mcp-server/index.mjs
+```