dual-brain 2.0.0

package/CLAUDE.md

@@ -0,0 +1,40 @@
+# Dual-Brain Orchestrator
+
+This project uses dual-provider orchestration. Config: `.claude/orchestrator.json`.
+
+## Tier Routing
+
+Route subagents by task complexity:
+
+- **Search** (`model: "haiku"`): Read-only lookups, grep, explore. Return: files found, line refs, confidence.
+- **Execute** (`model: "sonnet"`): Edits, tests, git ops. Return: files changed, tests run, edge cases.
+- **Think** (main session, Opus): Architecture, review, planning. Return: decision, alternatives, risks.
+
+## GPT Lane
+
+For isolated or parallel work, dispatch to GPT via Codex CLI:
+
+- `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --model gpt-5.4` — execution tasks
+- `node .claude/hooks/dual-brain-think.mjs --question "..."` — dual-perspective decisions
+
+## Routing Rules
+
+1. Tasks under 3 min → Claude (Codex startup overhead not worth it)
+2. Isolated tasks over 3 min → check balance: `node .claude/hooks/budget-balancer.mjs`
+3. High-risk decisions → dual-brain think
+4. When a task spans tiers: think > execute > search
+
+## Quality Gate
+
+Before ending a session with code changes:
+1. Run `node .claude/hooks/session-report.mjs`
+2. Run `node .claude/hooks/quality-gate.mjs`
+
+Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (GPT unavailable).
+
+## Available Tools
+
+- `node .claude/hooks/cost-report.mjs` — activity and cost estimates
+- `node .claude/hooks/health-check.mjs` — verify system health
+- `node .claude/hooks/budget-balancer.mjs` — provider balance status
+- `node .claude/hooks/test-orchestrator.mjs` — run self-tests

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1xmint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# Dual-Brain Orchestrator
+
+Dual-provider orchestration for Claude Code across Claude and OpenAI subscriptions. Routes search work to cheap models, execution to mid-tier, and reserves the most capable models for thinking. Dispatches isolated tasks to GPT via Codex CLI, with dual-brain analysis for high-risk decisions.
+
+## Install
+
+```bash
+npx dual-brain init
+```
+
+Then run the setup wizard:
+
+```bash
+node .claude/hooks/setup-wizard.mjs
+```
+
+Restart your Claude Code session. The wizard configures `orchestrator.json` with the right models and cost rates for your subscription tier.
+
+**What the installer does:**
+- Copies 13 hook scripts to `.claude/hooks/`
+- Copies orchestrator config and hookify rules to `.claude/`
+- Registers `enforce-tier.mjs` (PreToolUse) and `cost-logger.mjs` (PostToolUse) in `.claude/settings.json`
+- Creates a `review-rules.md` template for your project-specific GPT review rules
+- Updates `.gitignore` to exclude usage logs and review artifacts
+
+## How it works
+
+Two hooks are registered in `.claude/settings.json` and run automatically:
+
+- **enforce-tier.mjs** (PreToolUse on Agent): Classifies agent tasks by keyword, advises the correct model tier, detects duplicates, and suggests cross-provider routing
+- **cost-logger.mjs** (PostToolUse on all tools): Logs usage data to daily rotated files for cost tracking
+
+Three hookify rules in `.claude/hookify.orchestrator-*.local.md` provide session-level guidance:
+
+- **Route**: Reminds the session to delegate subagents at the right tier
+- **Gate**: Catches code changes that weren't reviewed before the session ends
+- **Cost**: Checks that dispatched subagents use the correct model tier
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `hooks/setup-wizard.mjs` | Interactive setup — configure your subscription and preferences |
+| `hooks/cost-report.mjs` | Activity & cost estimates by model tier |
+| `hooks/dual-brain-review.mjs` | Send current git diff to GPT for independent review |
+| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions |
+| `hooks/quality-gate.mjs` | Config-driven quality gate with sensitivity scoring |
+| `hooks/budget-balancer.mjs` | Show provider balance and routing recommendations |
+| `hooks/gpt-work-dispatcher.mjs` | Dispatch execution tasks to GPT via Codex CLI |
+| `hooks/session-report.mjs` | Session-end summary: activity, routing compliance, quality gate |
+| `hooks/health-check.mjs` | Verify all hooks and dependencies are configured |
+| `hooks/test-orchestrator.mjs` | Self-test harness — validates all hooks work correctly |
+| `hooks/install-git-hooks.mjs` | Install a git pre-commit hook for the quality gate |
+| `hooks/enforce-tier.mjs` | PreToolUse hook — enforces model tier routing (automatic) |
+| `hooks/cost-logger.mjs` | PostToolUse hook — logs usage data (automatic) |
+
+## Model Intelligence
+
+The `model_intelligence` section in `orchestrator.json` provides per-model metadata: strengths, weaknesses, best-for/avoid-for task guidance, context windows, and Codex compatibility. The `enforce-tier.mjs` hook reads this to give context-aware routing advice.
+
+## Customize
+
+- `orchestrator.json` — subscriptions, tiers, quality gate, routing rules, budgets
+- `.claude/review-rules.md` — project-specific rules injected into GPT review prompts
+- `.claude/settings.json` — hook registrations (auto-generated by installer)
+
+## Requirements
+
+- Node 20+
+- Codex CLI (optional) — for GPT-lane features: `npm i -g @openai/codex` then `codex login`. Falls back to `OPENAI_API_KEY` env var. Without Codex, Claude-lane features work normally.
+
+## Works with any subscription
+
+The setup wizard supports any combination:
+- Claude only ($20 Pro / $100 Max / $200 Max / API)
+- OpenAI only ($20 Plus / $100 Pro)
+- Both providers (recommended for dual-brain features)
+
+Without an OpenAI subscription, GPT-lane features gracefully degrade — all work routes through Claude.

package/hookify.orchestrator-cost.local.md

@@ -0,0 +1,16 @@
+---
+name: orchestrator-cost-check
+enabled: true
+event: all
+tool_matcher: Agent
+action: warn
+conditions:
+  - field: tool_name
+    operator: equals
+    pattern: Agent
+---
+
+**[Cost]** Subagent dispatched. Verify you selected the right tier:
+- `model: "haiku"` for search/exploration
+- `model: "sonnet"` for execution/implementation
+- No model param (inherit Opus) only for thinking tasks

package/hookify.orchestrator-gate.local.md

@@ -0,0 +1,19 @@
+---
+name: orchestrator-quality-gate
+enabled: true
+event: stop
+action: warn
+conditions:
+  - field: transcript
+    operator: regex_match
+    pattern: (Edit|Write|MultiEdit).+\.(ts|tsx|js|jsx|py|rs|go|java|rb|swift|kt)
+---
+
+**[Quality Gate]** Before ending this session:
+1. Run `node .claude/hooks/session-report.mjs` to see the session summary
+2. Run `node .claude/hooks/quality-gate.mjs` and check the output:
+   - `gate: "pass"` — safe to end
+   - `gate: "issues_found"` — address flagged issues first
+   - `gate: "needs_human_review"` — GPT unavailable, review diff manually
+   - `gate: "disabled"` — gate is off in config
+Do NOT skip these steps.

package/hookify.orchestrator-route.local.md

@@ -0,0 +1,23 @@
+---
+name: orchestrator-routing
+enabled: true
+event: prompt
+action: warn
+conditions:
+  - field: user_prompt
+    operator: regex_match
+    pattern: .+
+---
+
+**[Tier Router]** Route work across both providers (config: `.claude/orchestrator.json`):
+
+**Claude lane** (fast, interactive):
+- Search (`model: "haiku"`): Read-only lookups, grep, explore. Agent must return: files found, line refs, confidence.
+- Execute (`model: "sonnet"`): Edits, tests, git ops. Agent must return: files changed, tests run, edge cases.
+- Think (main session): Architecture, review, planning. Agent must return: decision, alternatives, risks.
+
+**GPT lane** (parallel, isolated work):
+- Use `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --model gpt-5.4` for isolated execution
+- Use `node .claude/hooks/dual-brain-think.mjs --question "..."` for dual-perspective decisions
+
+**Routing:** Tasks <3min → Claude. Isolated tasks >3min → check balance first (`node .claude/hooks/budget-balancer.mjs`). High-risk → dual-brain. Think > execute > search when task spans tiers.

package/hooks/budget-balancer.mjs

@@ -0,0 +1,463 @@
+#!/usr/bin/env node
+/**
+ * budget-balancer.mjs — Core budget balancing module for the Dual-Brain Orchestrator.
+ *
+ * Tracks rolling usage pressure across Claude and OpenAI providers and recommends
+ * which provider should handle incoming work.
+ *
+ * Exported API:
+ *   getProviderStatus()          → current pressure per provider/tier
+ *   chooseProvider(taskProfile)  → recommended provider + model + rationale
+ *   recordUsageEvent(event)      → append a usage event to today's log
+ *
+ * Also works as a standalone CLI: node .claude/hooks/budget-balancer.mjs
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ORCHESTRATOR_CONFIG = join(__dirname, "..", "orchestrator.json");
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Rolling window for pressure calculation (milliseconds) */
+const WINDOW_MS = 5 * 60 * 60 * 1000; // 5 hours
+
+/**
+ * Rough per-tier token budgets per 5-hour window.
+ * Based on $100/month Claude Max 5x and OpenAI Pro subscription estimates.
+ * These are approximations — the real limit is monthly, distributed evenly.
+ */
+const WINDOW_BUDGETS = {
+  claude: {
+    think:   500_000,   // Opus — costly, use sparingly
+    execute: 2_000_000, // Sonnet — primary workhorse
+    search:  5_000_000, // Haiku — cheap, generous budget
+  },
+  openai: {
+    think:   500_000,   // gpt-5.5
+    execute: 2_000_000, // gpt-5.4
+    search:  5_000_000, // gpt-4.1-mini
+  },
+};
+
+/** Estimated tokens consumed per call, by tier */
+const TOKENS_PER_CALL = {
+  search:  2_500,
+  execute: 5_500,
+  think:  11_000,
+};
+
+/** Default pressure thresholds (fraction 0–1) */
+const DEFAULT_THRESHOLDS = {
+  warm:      0.65,
+  hot:       0.82,
+  throttled: 0.95,
+};
+
+/** Default model mapping when orchestrator.json is missing provider config */
+const DEFAULT_MODELS = {
+  claude: { think: "opus", execute: "sonnet", search: "haiku" },
+  openai: { think: "gpt-5.5", execute: "gpt-5.4", search: "gpt-4.1-mini" },
+};
+
+// ---------------------------------------------------------------------------
+// Config helpers
+// ---------------------------------------------------------------------------
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(ORCHESTRATOR_CONFIG, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function getThresholds(config, provider) {
+  return (
+    config?.providers?.[provider]?.pressure_thresholds || DEFAULT_THRESHOLDS
+  );
+}
+
+function getProviderModels(config, provider) {
+  return config?.providers?.[provider]?.models || DEFAULT_MODELS[provider];
+}
+
+// ---------------------------------------------------------------------------
+// Provider / tier detection from model name
+// ---------------------------------------------------------------------------
+
+/**
+ * Given a model string, return { provider, tier } or null if unrecognised.
+ */
+function classifyModel(model) {
+  if (!model) return null;
+  const m = String(model).toLowerCase();
+
+  if (m.includes("opus"))         return { provider: "claude", tier: "think" };
+  if (m.includes("sonnet"))       return { provider: "claude", tier: "execute" };
+  if (m.includes("haiku"))        return { provider: "claude", tier: "search" };
+  if (m.includes("gpt-5.5") || m.includes("gpt4.5")) return { provider: "openai", tier: "think" };
+  if (m.includes("gpt-5.4") || (m.includes("gpt-4.1") && !m.includes("mini"))) return { provider: "openai", tier: "execute" };
+  if (m.includes("mini"))         return { provider: "openai", tier: "search" };
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Usage log helpers
+// ---------------------------------------------------------------------------
+
+function usageFilePath(date) {
+  const d = date || new Date().toISOString().slice(0, 10);
+  return join(__dirname, `usage-${d}.jsonl`);
+}
+
+/**
+ * Read all usage entries from the last `WINDOW_MS` milliseconds.
+ * Scans today's (and optionally yesterday's) log file.
+ */
+function readRecentEntries() {
+  const now = Date.now();
+  const cutoff = now - WINDOW_MS;
+
+  const entries = [];
+
+  // Check today's and yesterday's files to cover the rolling window boundary
+  const today = new Date().toISOString().slice(0, 10);
+  const yesterday = new Date(now - 86_400_000).toISOString().slice(0, 10);
+
+  for (const date of [yesterday, today]) {
+    const file = usageFilePath(date);
+    if (!existsSync(file)) continue;
+    let raw;
+    try {
+      raw = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    for (const line of raw.split("\n")) {
+      if (!line.trim()) continue;
+      let record;
+      try {
+        record = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const ts = Date.parse(record.timestamp);
+      if (!isNaN(ts) && ts >= cutoff) {
+        entries.push(record);
+      }
+    }
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// Exported: getProviderStatus()
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute rolling 5-hour pressure for each provider/tier combination.
+ *
+ * @returns {object} Status keyed by provider → tier → { pressure, state, calls, estTokens }
+ */
+function getProviderStatus() {
+  const config = loadConfig();
+
+  const entries = readRecentEntries();
+
+  // Accumulate call counts per provider/tier
+  const counts = {
+    claude: { think: 0, execute: 0, search: 0 },
+    openai: { think: 0, execute: 0, search: 0 },
+  };
+
+  for (const entry of entries) {
+    // Determine provider/tier either from stored `provider` field or by classifying model
+    let provider = entry.provider;
+    let tier = entry.tier;
+
+    if (!provider && entry.model) {
+      const classified = classifyModel(entry.model);
+      if (classified) {
+        provider = classified.provider;
+        tier = classified.tier;
+      }
+    }
+
+    if (provider && tier && counts[provider] && counts[provider][tier] !== undefined) {
+      counts[provider][tier]++;
+    }
+  }
+
+  // Build status object
+  const status = {};
+
+  for (const provider of ["claude", "openai"]) {
+    const thresholds = getThresholds(config, provider);
+    status[provider] = {};
+
+    for (const tier of ["think", "execute", "search"]) {
+      const calls = counts[provider][tier];
+      const estTokens = calls * TOKENS_PER_CALL[tier];
+      const budget = WINDOW_BUDGETS[provider][tier];
+      const pressure = budget > 0 ? estTokens / budget : 0;
+
+      let state;
+      if (pressure >= (thresholds.throttled ?? DEFAULT_THRESHOLDS.throttled)) {
+        state = "throttled";
+      } else if (pressure >= (thresholds.hot ?? DEFAULT_THRESHOLDS.hot)) {
+        state = "hot";
+      } else if (pressure >= (thresholds.warm ?? DEFAULT_THRESHOLDS.warm)) {
+        state = "warm";
+      } else {
+        state = "healthy";
+      }
+
+      status[provider][tier] = { pressure, state, calls, estTokens };
+    }
+  }
+
+  return status;
+}
+
+// ---------------------------------------------------------------------------
+// Exported: chooseProvider(taskProfile)
+// ---------------------------------------------------------------------------
+
+/**
+ * Recommend a provider for an incoming task.
+ *
+ * @param {object} taskProfile
+ * @param {string} taskProfile.tier                  - search | execute | think
+ * @param {number} [taskProfile.estimatedDurationMs] - expected task duration
+ * @param {string} [taskProfile.contextCoupling]     - low | medium | high
+ * @param {string} [taskProfile.isolation]           - low | medium | high
+ * @returns {{ provider, model, reason, scores }}
+ */
+function chooseProvider(taskProfile = {}) {
+  const {
+    tier = "execute",
+    estimatedDurationMs = 0,
+    contextCoupling = "low",
+    isolation = "low",
+  } = taskProfile;
+
+  const config = loadConfig();
+  const status = getProviderStatus();
+
+  const PRESSURE_PENALTY = {
+    healthy:   0,
+    warm:     15,
+    hot:      40,
+    throttled: 100,
+  };
+
+  const scores = {};
+
+  for (const provider of ["claude", "openai"]) {
+    const tierStatus = status[provider]?.[tier] || { pressure: 0, state: "healthy" };
+    const otherProvider = provider === "claude" ? "openai" : "claude";
+    const otherTierStatus = status[otherProvider]?.[tier] || { pressure: 0, state: "healthy" };
+
+    // Base score
+    let score = 50;
+
+    // Task-fit score
+    if (provider === "claude") {
+      if (contextCoupling === "high")   score += 20;
+      else if (contextCoupling === "medium") score += 10;
+    } else {
+      // openai
+      if (isolation === "high")   score += 20;
+      else if (isolation === "medium") score += 10;
+    }
+
+    // Pressure penalty
+    score -= PRESSURE_PENALTY[tierStatus.state] ?? 0;
+
+    // Latency penalty (OpenAI only — Codex has higher startup overhead)
+    if (provider === "openai") {
+      if (estimatedDurationMs < 180_000) {
+        score -= 25; // < 3 min: overhead not worth it
+      } else if (estimatedDurationMs < 600_000) {
+        score -= 10; // < 10 min: minor penalty
+      }
+      // >= 10 min: no penalty
+    }
+
+    // Underused bonus
+    if (
+      tierStatus.pressure < 0.3 &&
+      otherTierStatus.pressure > 0.5
+    ) {
+      score += 20;
+    }
+
+    scores[provider] = Math.round(score);
+  }
+
+  const winner = scores.claude >= scores.openai ? "claude" : "openai";
+  const loser  = winner === "claude" ? "openai" : "claude";
+
+  // Resolve model name
+  const models = getProviderModels(config, winner);
+  const model = models?.[tier] || DEFAULT_MODELS[winner][tier];
+
+  // Build human reason string
+  const winnerPressure = (status[winner]?.[tier]?.pressure ?? 0).toFixed(2);
+  const loserPressure  = (status[loser]?.[tier]?.pressure ?? 0).toFixed(2);
+
+  let reasonParts = [];
+  if (winner === "claude" && contextCoupling !== "low") {
+    reasonParts.push(`high session context coupling`);
+  }
+  if (winner === "openai" && isolation !== "low") {
+    reasonParts.push(`isolated task`);
+  }
+  if (parseFloat(winnerPressure) < parseFloat(loserPressure)) {
+    reasonParts.push(`${winner} pressure lower (${winnerPressure} vs ${loserPressure})`);
+  }
+  if (!reasonParts.length) {
+    reasonParts.push(`${winner} scored higher (${scores[winner]} vs ${scores[loser]})`);
+  }
+
+  return {
+    provider: winner,
+    model,
+    reason: reasonParts.join(", "),
+    scores,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Exported: recordUsageEvent(event)
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a usage event to today's daily log file.
+ * Automatically adds `provider` field if not present.
+ *
+ * @param {object} event - Usage event (see cost-logger.mjs schema)
+ */
+function recordUsageEvent(event = {}) {
+  // Infer provider from model name if not supplied
+  let provider = event.provider;
+  if (!provider && event.model) {
+    const classified = classifyModel(event.model);
+    provider = classified?.provider || "claude";
+  }
+  if (!provider) provider = "claude";
+
+  const entry = JSON.stringify({
+    schema_version: 2,
+    timestamp: event.timestamp || new Date().toISOString(),
+    provider,
+    ...event,
+  });
+
+  const file = usageFilePath();
+  mkdirSync(dirname(file), { recursive: true });
+
+  try {
+    appendFileSync(file, entry + "\n", { encoding: "utf8", flag: "a" });
+  } catch (err) {
+    // Non-fatal — log to stderr but don't crash callers
+    process.stderr.write(`[budget-balancer] Failed to write usage event: ${err.message}\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CLI rendering helpers
+// ---------------------------------------------------------------------------
+
+function pressureBar(pressure, width = 10) {
+  const filled = Math.min(width, Math.round(pressure * width));
+  return "█".repeat(filled) + "░".repeat(width - filled);
+}
+
+function stateLabel(state) {
+  return state.padEnd(8);
+}
+
+function formatPercent(pressure) {
+  return String(Math.round(pressure * 100)).padStart(3) + "%";
+}
+
+function printStatusTable(status) {
+  const LINE_WIDTH = 50;
+  const border = "═".repeat(LINE_WIDTH - 2);
+  const blank  = " ".repeat(LINE_WIDTH - 4);
+
+  const h = (text) => {
+    const padded = ` ${text}`.padEnd(LINE_WIDTH - 4);
+    return `║ ${padded} ║`;
+  };
+  const row = (label, tier) => {
+    const s = status[label]?.[tier] || { pressure: 0, state: "healthy" };
+    const bar = pressureBar(s.pressure);
+    const pct = formatPercent(s.pressure);
+    const lbl = stateLabel(s.state);
+    const line = `  ${tier.charAt(0).toUpperCase() + tier.slice(1).padEnd(7)}: ${bar}  ${pct} ${lbl}`;
+    return h(line);
+  };
+
+  const config = loadConfig();
+  const claudePlan  = config?.subscriptions?.claude?.plan  ? `Claude Max ${config.subscriptions.claude.plan}` : "Claude Max $100";
+  const openaiPlan  = config?.subscriptions?.openai?.plan  ? `OpenAI Pro ${config.subscriptions.openai.plan}` : "OpenAI Pro $100";
+
+  // Recommendation
+  const rec = chooseProvider({ tier: "execute", estimatedDurationMs: 300_000, isolation: "high", contextCoupling: "low" });
+  const recText = `Route execution to ${rec.provider === "openai" ? "OpenAI" : "Claude"}`;
+
+  const lines = [
+    `╔${border}╗`,
+    h("         Provider Balance Status                "),
+    `╠${border}╣`,
+    h(claudePlan),
+    row("claude", "think"),
+    row("claude", "execute"),
+    row("claude", "search"),
+    h(blank),
+    h(openaiPlan),
+    row("openai", "think"),
+    row("openai", "execute"),
+    row("openai", "search"),
+    `╠${border}╣`,
+    h(`Recommendation: ${recText}`),
+    `╚${border}╝`,
+  ];
+
+  console.log(lines.join("\n"));
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const status = getProviderStatus();
+  printStatusTable(status);
+}
+
+// Run as CLI only when invoked directly
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main().catch((err) => {
+    process.stderr.write(`[budget-balancer] ${err.message}\n`);
+    process.exit(1);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+export { getProviderStatus, chooseProvider, recordUsageEvent };