dual-brain 0.2.30 → 0.3.1

package/.dual-brain/docs/claude-code-extension-points.md

@@ -0,0 +1,32 @@
+# Claude Code Extension Points (Verified May 2026)
+
+**NOTE**: Claude Code does NOT have a plugin system. No manifest, no marketplace, no `.claude-plugin/` format.
+
+## Actual Extension Points
+
+| Mechanism | Location | What It Does |
+|-----------|----------|-------------|
+| Hooks | `.claude/settings.json` → hooks | Shell commands at lifecycle events (PreToolUse, PostToolUse, Stop, SessionStart, etc.) |
+| Skills | `.claude/skills/*.md` | Instruction injection when skill is matched |
+| Custom commands | `.claude/commands/*.md` | Become `/project:command-name` slash commands |
+| MCP servers | `.claude/settings.json` → mcpServers | External tool servers |
+| Custom agents | `.claude/agents/*.md` | Subagent definitions |
+| CLAUDE.md | `.claude/CLAUDE.md` | Project instructions loaded every session |
+
+## Distribution Pattern
+
+No higher-level abstraction exists. The proven pattern:
+
+1. **npm package** with hook scripts + install CLI
+2. `npx dual-brain install` merges hooks into settings.json, copies skills/commands/agents
+3. `npx dual-brain uninstall` reverses the above
+4. Version the settings merge to avoid clobbering user config
+
+Our existing `dual-brain install --global` is already the right approach.
+
+## What We Ship
+
+- `~/.claude/hooks/` — 30+ hook scripts (head-guard, enforce-tier, cost-logger, etc.)
+- `~/.claude/settings.json` — hook event bindings
+- `~/.claude/CLAUDE.md` — global instructions
+- npm postinstall wires everything up

package/.dual-brain/docs/data-tools-capabilities.md

@@ -0,0 +1,181 @@
+# DATA Tools (data-remote) — Complete Capability Reference
+
+**Package**: data-remote on npm  
+**Author**: Steve Moraco (stevemoraco/DATAtools)  
+**Version**: 1.2.42  
+**Location**: `/home/runner/workspace/.replit-tools/`  
+**Last audited**: 2026-05-17
+
+---
+
+## Core Scripts
+
+### 1. setup-claude-code.sh (522 lines)
+Master initialization — runs on every container startup.
+
+| Capability | Detail |
+|------------|--------|
+| Auto-update | Checks npm for newer data-remote, self-updates |
+| Symlink management | ~/.claude, ~/.codex, ~/.ssh, ~/.local/share/claude/versions |
+| Binary management | Finds/caches/symlinks Claude Code binary |
+| Persistence sync | Applies config.json to Claude cleanupPeriodDays + Codex max_bytes |
+| Mirror sync | Appends sessions to .session-archive/ (append-only) |
+| OAuth refresh | Proactively refreshes tokens < 2h from expiry |
+| Install fallback | Runs official install.sh if Claude not found |
+| Env exports | CLAUDE_PERSISTENT, CODEX_PERSISTENT, REPLIT_TOOLS, PATH |
+
+### 2. claude-session-manager.sh (792 lines)
+Interactive multi-terminal session picker + state tracker.
+
+| Capability | Detail |
+|------------|--------|
+| Terminal ID | Gets TTY/PID to track per-terminal state |
+| Session enumeration | Reads history.jsonl + project JSONL + Codex hierarchy |
+| Recent filtering | configurable window (default 48h), skips system/agent prompts |
+| Terminal state | Per-terminal JSON: last session ID + tool used |
+| Interactive menu | [1-9] quick-pick, [r] full list, [n] new, [c] resume |
+| Running instance count | Counts active claude/codex processes |
+| Aliases | cr, claude-resume, claude-pick, j, k, cm, claude-menu |
+
+### 3. claude-auth-refresh.sh (231 lines)
+OAuth token lifecycle management.
+
+| Capability | Detail |
+|------------|--------|
+| Token status | Reads .credentials.json, returns hours remaining |
+| Proactive refresh | Threshold: 2h, calls Anthropic OAuth endpoint |
+| Failure handling | Backup before update, retry cooldown (.auth-refresh-failed marker) |
+| API key support | Detects permanent keys, skips refresh |
+| Commands | --status, --force, --auto |
+| Client ID | 9d1c250a-e61b-44d9-88ed-5944d1962f5e |
+
+---
+
+## Persistence Directories
+
+### .claude-persistent/
+| Path | Contents |
+|------|----------|
+| settings.json | Model config, hooks, cleanup period |
+| .claude.json | OAuth account, telemetry, feature flags, session tracking |
+| .credentials.json | OAuth tokens (access, refresh, expiresAt) |
+| history.jsonl | Global session history (539 events) |
+| sessions/ | Per-process state (PID.json: sessionId, cwd, status) |
+| projects/ | Workspace-specific session JSONL + memory system |
+| file-history/ | Per-session edit snapshots (790 files across 12+ sessions) |
+| tasks/ | Per-session task queue |
+| paste-cache/ | Clipboard cache (88 files, session-scoped) |
+| shell-snapshots/ | Bash state captures (740 files) |
+| session-env/ | Per-session env var snapshots (216 files) |
+| plugins/marketplaces/ | MCP plugins (discord, telegram, github, etc.) |
+| cache/ | Changelog (310KB), GitHub issues metadata |
+| backups/ | Rolling .claude.json backups (5 recent, timestamped) |
+| mcp-needs-auth-cache.json | MCP server auth status (Gmail, Calendar, Drive) |
+
+### .codex-persistent/
+| Path | Contents |
+|------|----------|
+| auth.json | OpenAI/ChatGPT OAuth (Google-based) |
+| config.toml | Trust levels, history persistence, max_bytes |
+| models_cache.json | Cached model list from OpenAI API |
+| sessions/YYYY/MM/DD/ | Hierarchical session JSONL |
+| skills/.system/ | Built-in: imagegen, openai-docs, plugin-creator, skill-creator, skill-installer |
+| cache/codex_apps_tools/ | Plugin ecosystem cache |
+| shell_snapshots/ | Context captures |
+| memories/ | Per-session memory |
+
+### .gh-persistent/
+| Path | Contents |
+|------|----------|
+| config.yml | Protocol: https, aliases: co=pr checkout |
+| hosts.yml | OAuth token for 1xmint, repo+user scoped |
+
+### .npm-persistent/
+| Path | Contents |
+|------|----------|
+| .npmrc | Auth token for npmjs.org (enables publish) |
+
+### .ssh-persistent/
+SSH keys + config, permissions maintained (700/600/644).
+
+### .session-archive/ (Append-Only Mirror)
+```
+claude/history.jsonl
+claude/projects/-home-runner-workspace/{sessionId}.jsonl
+claude/projects/memory/*.md
+codex/(similar)
+```
+Files ONLY GROW. Preserves deleted sessions. Synced on every startup.
+
+### .claude-sessions/
+Per-terminal state files ({TERMINAL_ID}.json) for session manager.
+
+### .logs/
+auth-refresh.log (174KB) — timestamped token checks on every startup.
+
+### .claude-versions/
+Binary copies of Claude Code versions. Only latest symlinked.
+
+---
+
+## Configuration
+
+### config.json
+```json
+{
+  "recentWindowHours": 48,
+  "persistenceDays": 365250,
+  "mirror": { "enabled": true }
+}
+```
+
+### Hooks Defined (in settings.json)
+| Event | Matcher | Script |
+|-------|---------|--------|
+| PreToolUse | Edit/Write/NotebookEdit/Bash | head-guard.mjs |
+| PreToolUse | Agent | enforce-tier.mjs |
+| PostToolUse | * | cost-logger.mjs |
+| PostToolUse | * | auto-update-wrapper.mjs |
+
+---
+
+## What Dual-Brain Currently Uses
+
+| Capability | How |
+|------------|-----|
+| Session persistence | .claude-sessions/*.json tracks active sessions |
+| OAuth auto-refresh | Keeps tokens alive across long agent runs |
+| Multi-terminal sessions | Independent Claude instances per TTY |
+| Credential persistence | Survives container restarts |
+| Auto-update | Self-updates from npm on shell startup |
+| Binary management | Handles Claude symlinks/install/versioning |
+| Codex integration | .codex-persistent/ for GPT-side auth |
+| Mirror config | Append-only session backup |
+| Memory persistence | .claude-persistent/projects/ memory system |
+| Session archiving | .session-archive/ long-term history |
+
+## What Dual-Brain Should Leverage More
+
+| Opportunity | Rationale |
+|-------------|-----------|
+| Session manager for Manager agents | Steve's per-terminal tracking → register persistent managers |
+| Mirror for dual-brain debate | mirror.enabled syncs between Claude+Codex → route debate through it |
+| Auth refresh → Provider Manager | Integrate token expiry into health/failover |
+| Terminal tracking → agent hierarchy | HEAD on pts-0, Manager on pts-1 |
+| Shell snapshots → context loading | 740 snapshots = rich context for new agents |
+| File history → undo/revert | 790 edit snapshots = built-in time travel |
+| Append-only archive → audit trail | Compliance/debugging across sessions |
+| Codex skills system | Plugin architecture we could mirror |
+
+## What Dual-Brain Built (Not In DATA Tools)
+
+| Module | Why |
+|--------|-----|
+| Room system (room.ts) | File-based inter-agent messaging |
+| Provider Manager (provider-manager.ts) | Cross-provider failover + rate limit tracking |
+| Agent Protocol (agent-protocol.ts) | Typed hierarchy contracts |
+| Model Profiles (model-profiles.ts) | Capability taxonomy for routing |
+| Signal Scoring (signal.ts) | Outcome quality measurement |
+| Routing Advisor (routing-advisor.ts) | EMA-based learned routing |
+| Pipeline (pipeline.ts) | Gated execution with principle checks |
+| Cognitive Loop (cognitive-loop.ts) | Multi-wave parallel agent orchestration |

package/.dual-brain/docs/ecosystem-tools.md

@@ -0,0 +1,91 @@
+# AI Orchestration Ecosystem — Tool Audit
+
+**Audited**: 2026-05-17  
+**Purpose**: Tools/packages relevant to dual-brain's multi-provider orchestration
+
+---
+
+## Direct Competitors / Analogs
+
+### Ruflo (formerly claude-flow)
+- **npm**: claude-flow | **GitHub**: ruvnet/ruflo
+- 100+ specialized agents, multi-provider routing (Claude, GPT, Gemini, Cohere, Ollama)
+- SQLite-backed shared memory, swarm coordination
+- 27-hook lifecycle system, MCP server layer
+- **Maturity**: v3.5+, actively developed
+- **Borrow**: Router architecture, hook taxonomy (27 hooks covering full agent lifecycle)
+- **Difference from us**: Heavily opinionated, monolithic. We're lighter, file-based, subscription-only.
+
+### claude-code-flow (INTGworld)
+- Lighter swarm orchestration for Claude Code
+- Code-first, recursive agent cycles
+- Less mature than Ruflo, simpler
+- **Borrow**: Pattern study only
+
+---
+
+## Cost Tracking Tools
+
+### ai-cost-tracker
+- TypeScript/Node.js, SQLite-backed
+- Per-user/per-feature token costs across models
+- Production-ready
+- **Borrow**: SQLite cost schema with per-model pricing tables
+
+### CodeBurn
+- `npm i -g codeburn`
+- Terminal dashboard for Claude Code / Codex cost monitoring
+- **Borrow**: TUI/UX reference for our frontend overhaul
+
+### Tokscale (junhoyeo)
+- Tracks token usage across Claude Code, Codex, Gemini
+- Global leaderboard, contribution graphs
+- **Borrow**: Multi-provider cost comparison patterns
+
+---
+
+## Claude Code Plugin System
+
+Claude Code has a formal plugin system:
+- `.claude-plugin/plugin.json` manifests
+- Skills, agents, hooks, MCP servers
+- Curated: awesome-claude-code-plugins (ccplugins)
+- **Action**: Package dual-brain hooks as a `.claude-plugin` for distribution
+
+---
+
+## Multi-Agent Frameworks (learn-from)
+
+### CrewAI
+- Role-based DSL, enterprise observability (2026)
+- Our HEAD/Manager/Supervisor/Worker maps to CrewAI's role model
+- **Borrow**: Role hierarchy patterns, observability approach
+
+### AutoGen/AG2
+- Event-driven, async-first since v1.0 GA
+- Microsoft shifting to maintenance mode — caution
+- **Borrow**: Event-driven patterns only
+
+### LangGraph v0.4
+- State persistence and checkpointing
+- State machine approach mirrors our head.ts
+- **Borrow**: State machine persistence patterns for HEAD brain
+
+---
+
+## Replit-Specific
+
+### @replit/database
+- Official KV store for Replit
+- Simple persistence, no relational queries
+- **Note**: data-remote may be unpublished/internal npm package
+
+---
+
+## Priority Actions
+
+1. Study Ruflo's 27-hook taxonomy — see if we're missing lifecycle hooks
+2. Look at ai-cost-tracker's SQLite schema — could replace our JSON cost tracking
+3. Package as Claude Code plugin — distribution path for non-Replit users
+4. Study CodeBurn's TUI — UX reference for our frontend overhaul
+5. LangGraph state persistence — validate our HEAD state machine approach

package/.dual-brain/docs/panel-handoff.md

@@ -0,0 +1,124 @@
+# Dual-Brain Panel Handoff — For HeyVera Session
+
+## What This Is
+
+Dual-brain is an AI orchestration CLI that routes between Claude and GPT. It writes its state to JSON files that an external web panel can consume. This doc tells you how to build that panel.
+
+## Your Task
+
+1. Find the existing "Pulse" panel (X.com marketing agent dashboard)
+2. Make TWO copies:
+   - **Copy A**: Social marketing panel → integrate into heyvera.org (DO LATER, just copy it clean for now)
+   - **Copy B**: Strip all X.com/marketing code → rebuild as dual-brain orchestration portal
+3. Copy B becomes a page on heyvera.org
+
+## Data Contract
+
+Dual-brain writes JSON files to `.dual-brain/state/`. The panel reads these.
+
+### File: `providers.json`
+```typescript
+interface ProvidersState {
+  timestamp: string;
+  providers: Record<string, {
+    score: number;          // 0-1 health score
+    cooldownUntil?: number; // unix ms, if rate-limited
+    lastError?: string;
+    degraded?: boolean;
+    dispatchCount: number;
+  }>;
+}
+```
+
+### File: `routing.json`
+```typescript
+interface RoutingState {
+  timestamp: string;
+  totalObservations: number;
+  cells: Record<string, Record<string, {
+    ema: number;           // 0-1 performance score
+    observations: number;
+  }>>;
+  topPerformers: Array<{ cell: string; model: string; ema: number; observations: number }>;
+  worstPerformers: Array<{ cell: string; model: string; ema: number; observations: number }>;
+}
+```
+
+### File: `rooms.json`
+```typescript
+interface RoomsState {
+  timestamp: string;
+  rooms: Array<{
+    id: string;
+    project: string;
+    status: 'active' | 'closed';
+    createdAt: string;
+    workerCount: number;
+  }>;
+}
+```
+
+### File: `decisions.json` (ring buffer, max 50)
+```typescript
+interface Decision {
+  timestamp: string;
+  promptSummary: string;   // first 100 chars
+  provider: string;
+  model: string;
+  tier: string;
+  reason: string;
+  explored: boolean;       // was this an exploration pick?
+}
+```
+
+### File: `outcomes.json` (ring buffer, max 200)
+```typescript
+interface Outcome {
+  timestamp: string;
+  roomId: string;
+  success: boolean;
+  score: number;           // 0-1 composite quality
+  durationMs: number;
+  provider: string;
+  model: string;
+}
+```
+
+### File: `costs.json`
+```typescript
+interface CostsState {
+  timestamp: string;
+  session: {
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCostUsd: number;
+  };
+  byProvider: Record<string, {
+    tokens: number;
+    estimatedCostUsd: number;
+  }>;
+}
+```
+
+## What the Panel Should Show
+
+### Dashboard View (Copy B — Orchestration Portal)
+1. **Provider Health** — two cards (Claude / GPT), each showing health score, cooldown status, dispatch count
+2. **Routing Intelligence** — which model is winning for which task type (EMA scores), exploration rate
+3. **Live Feed** — scrolling list of recent decisions and outcomes
+4. **Cost Gauge** — session cost, per-provider breakdown
+5. **Active Rooms** — current agent tasks in flight
+6. **Performance Chart** — outcome scores over time
+
+### Future: Voice Input
+The panel will eventually accept voice input (browser Speech API), transcribe it, and send it to dual-brain's HEAD. For now, just build the read-only dashboard.
+
+### Future: Multi-Repo View
+The panel will show multiple repos with a manager-per-repo. Each repo card shows its active manager, workers, and costs.
+
+## Tech Notes
+- Poll the JSON files every 2-5 seconds (they're small)
+- Or use `fs.watch` if same machine
+- All files use atomic writes (write .tmp then rename) so reads never get partial data
+- The `getExportedState()` function in dual-brain returns all state as one object if you want an API instead of file polling

package/.dual-brain/docs/ruflo-analysis.md

@@ -0,0 +1,48 @@
+# Ruflo (claude-flow) — Competitive Analysis
+
+**Audited**: 2026-05-17  
+**Package**: claude-flow on npm, ruvnet/ruflo on GitHub  
+**Version**: v3.5+
+
+---
+
+## Reality vs Marketing
+
+| Claim | Reality |
+|-------|---------|
+| "27 hooks" | 8 Claude Code lifecycle events with multiple matchers. All exit 0, never block. |
+| "210 MCP tools" | Real MCP layer, but tool count inflated. Express proxy to stdio backends. |
+| "Vector DB / HNSW" | JSON files with a Map. Vector features may be in npm binary, not open source. |
+| "Intelligent routing" | Regex pattern matcher. Static confidence (0.8 match, 0.5 default). No learning. |
+
+## Where We're Ahead
+
+| Area | Ruflo | Dual-Brain |
+|------|-------|------------|
+| Routing | Static regex → hardcoded agent maps | EMA-based learned routing with exploration |
+| Hook enforcement | All `|| true`, never block | head-guard blocks HEAD from implementing |
+| Type safety | Markdown agents, no runtime validation | TypeScript contracts, typed protocols |
+| Architecture honesty | Marketing > codebase | What we claim = what we ship |
+
+## Where Ruflo's Ahead
+
+| Area | What They Have | What We Should Build |
+|------|---------------|---------------------|
+| MCP server | Orchestration exposed as MCP tools — any Claude Code session can use it | Yes — expose routing/dispatch/status as MCP tools |
+| Plugin format | `.claude-plugin/plugin.json` manifest with agents/commands/skills/scripts | Study as model for future extension system |
+| Session lifecycle | Automatic save/restore with clean start/end | Improve our session.ts persistence |
+
+## Their Architecture
+
+- **Router**: `router.cjs` — regex keyword-to-agent maps ("implement|create|build" → coder)
+- **Agent comms**: File-based mailbox via bash scripts (`.claude-flow/swarm/queue/`, `.claude-flow/swarm/mailbox/{agent}/`)
+- **Memory**: Flat JSON files (memory.json, auto-memory-store.json, ranked-context.json)
+- **MCP bridge**: Express server proxying to stdio backends
+- **Plugins**: 32 plugins in `plugins/ruflo-*`, each with manifest + agents + commands
+
+## Action Items
+
+1. **Build MCP server layer** — expose dual-brain orchestration as MCP tools (highest value)
+2. **Study their plugin manifest** — good pattern for extension packaging
+3. **Don't copy their routing** — ours is fundamentally better (learned vs static)
+4. **Don't copy their hooks** — ours actually enforce boundaries, theirs are cosmetic