titan-agent 5.4.2 → 5.5.6

package/docs/superpowers/plans/2026-04-29-gitnexus-gap-remediation.md

@@ -0,0 +1,969 @@
+# TITAN v5.4.3 — GitNexus Gap Remediation Plan
+
+> **For agentic workers:** Use `superpowers:executing-plans` or `superpowers:subagent-driven-development` task-by-task. Each task is independent enough to ship on its own. Run tasks in order within a stream, but streams can interleave.
+
+**Goal:** Fix all four structural gaps GitNexus identified in the TITAN knowledge graph, making the widget pipeline traceable, search functional, gateway modular, and voice connected.
+
+**Architecture:** 
+- **Widget stream:** Trace `gallery_get` → `SandboxRuntime.post` → `handleIframeRequest` → `handleRender` as a single Process in the graph (fixes proxy bug visibility)
+- **Search stream:** Rebuild LadybugDB FTS tables with write access, enable `--embeddings` for semantic search
+- **Gateway stream:** Extract `/api/paperclip`, `/api/checkpoints`, `/api/companies`, `/api/traces` into sub-routers mounted by `src/gateway/server.ts`
+- **Voice stream:** Add a lightweight TS bridge (`src/voice/bridge.ts`) that the agent can call into, making `TitanAgent` visible to the core graph
+
+**Tech Stack:** TypeScript, Express 4, LadybugDB (Kuzu), GitNexus CLI, Vitest
+
+---
+
+## Stream A: Fix Widget Template → Sandbox Bridge
+
+### A1: Reproduce the `titan.api.call` proxy bug
+
+**Files:**
+- Read: `src/skills/builtin/widget_gallery.ts`, `ui/src/titan2/sandbox/SandboxRuntime.ts`
+- Create: `tests/sandbox/widget-proxy-repro.test.ts`
+
+- [ ] **Step 1: Write failing test for proxy bug**
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+import SandboxRuntime from '../../ui/src/titan2/sandbox/SandboxRuntime';
+
+describe('widget proxy bug', () => {
+  it('should route titan.api.call through postMessage correctly', async () => {
+    const runtime = new SandboxRuntime('test-container', { debug: false });
+    runtime.init();
+    
+    // Simulate what a widget does when it calls titan.api.call
+    const widgetCode = `
+      async function onAnalyzeClick() {
+        const result = await titan.api.call('/api/stock/analyze', { ticker: 'AAPL' });
+        return result;
+      }
+    `;
+    
+    await runtime.whenReady();
+    const response = await runtime.post('execute', { code: widgetCode });
+    
+    // Currently returns "No response." because the proxy handler is missing in handleIframeRequest
+    expect(response).not.toBe('No response.');
+    expect(response).toBeDefined();
+  });
+});
+```
+
+- [ ] **Step 2: Run test to confirm failure**
+
+Run: `npx vitest run tests/sandbox/widget-proxy-repro.test.ts`
+Expected: FAIL — `AssertionError: expected 'No response.' not to be 'No response.'` (or timeout/crash)
+
+- [ ] **Step 3: Commit repro test**
+
+```bash
+git add tests/sandbox/widget-proxy-repro.test.ts
+git commit -m "test(sandbox): repro for titan.api.call proxy bug"
+```
+
+### A2: Fix `handleIframeRequest` to proxy `titan.api.call`
+
+**Files:**
+- Modify: `ui/src/titan2/sandbox/SandboxRuntime.ts:handleIframeRequest#3` (line ~382)
+- Test: `tests/sandbox/widget-proxy-repro.test.ts` (update existing)
+
+- [ ] **Step 4: Add proxy handler in `handleIframeRequest`**
+
+In `ui/src/titan2/sandbox/SandboxRuntime.ts`, inside `handleIframeRequest(event)`, find the `switch(data.type)` block and add:
+
+```typescript
+case 'titan.api.call': {
+  const { endpoint, body } = data.payload;
+  // Strip any accidental double /api/ prefix
+  const cleanPath = endpoint.replace(/^\/api\//, '/');
+  const url = cleanPath.startsWith('/') 
+    ? `${window.location.origin}/api${cleanPath}` 
+    : endpoint;
+  
+  const token = localStorage.getItem('titan-token');
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { 'Authorization': `Bearer ${token}` } : {})
+    },
+    body: JSON.stringify(body)
+  });
+  
+  const json = await res.json().catch(() => ({}));
+  this.post('titan.api.call.response', { 
+    id: data.id, 
+    status: res.status, 
+    body: json 
+  });
+  break;
+}
+```
+
+- [ ] **Step 5: Handle proxy response on widget side**
+
+In the same file, add to `render()` or `execute()` the promise-tracking for widget callbacks:
+
+```typescript
+private pendingApiCalls: Map<string, { resolve: Function; reject: Function }> = new Map();
+
+// In the constructor or init:
+this.messageHandler = (data: any) => {
+  if (data.type === 'titan.api.call.response') {
+    const pending = this.pendingApiCalls.get(data.payload.id);
+    if (pending) {
+      if (data.payload.status >= 200 && data.payload.status < 300) {
+        pending.resolve(data.payload.body);
+      } else {
+        pending.reject(new Error(`API call failed: ${data.payload.status}`));
+      }
+      this.pendingApiCalls.delete(data.payload.id);
+    }
+  }
+  // ... existing handler
+};
+```
+
+- [ ] **Step 6: Update test to verify fix**
+
+Replace the assertion in `widget-proxy-repro.test.ts`:
+
+```typescript
+expect(response.body).toBeTruthy();
+expect(response.status).toBe(200);
+```
+
+- [ ] **Step 7: Run test to confirm pass**
+
+Run: `npx vitest run tests/sandbox/widget-proxy-repro.test.ts`
+Expected: PASS
+
+- [ ] **Step 8: Commit fix**
+
+```bash
+git add ui/src/titan2/sandbox/SandboxRuntime.ts tests/sandbox/widget-proxy-repro.test.ts
+git commit -m "fix(sandbox): proxy titan.api.call through postMessage in widget iframe"
+```
+
+### A3: Fix Pomodoro UI generation hang (SSE timeout)
+
+**Files:**
+- Modify: `ui/src/titan2/canvas/TitanCanvas.tsx`
+- Read: `assets/widget-templates/productivity/pomodoro-25-5.json`
+- Create: `tests/sandbox/pomodoro-sse-timeout.test.ts`
+
+- [ ] **Step 9: Write failing test for Pomodoro timeout**
+
+```typescript
+import { describe, it, expect } from 'vitest';
+
+describe('pomodoro sse hang', () => {
+  it('should not hang for >30s when generating Pomodoro widget', async () => {
+    const start = Date.now();
+    
+    // Simulate the canvas requesting a pomodoro widget render
+    const widgetPrompt = 'Create a pomodoro timer with 25-minute work sessions';
+    
+    // This currently uses SSE streaming which hangs
+    const result = await simulateWidgetGeneration(widgetPrompt);
+    
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(35000); // Direct curl is 33s; target <35s as baseline
+    expect(result).toBeDefined();
+  }, 40000);
+});
+```
+
+- [ ] **Step 10: Run test to confirm hang/failure**
+
+Run: `npx vitest run tests/sandbox/pomodoro-sse-timeout.test.ts`
+Expected: FAIL (timeout or >35s)
+
+- [ ] **Step 11: Commit repro test**
+
+```bash
+git add tests/sandbox/pomodoro-sse-timeout.test.ts
+git commit -m "test(sandbox): repro for Pomodoro SSE generation hang"
+```
+
+- [ ] **Step 12: Add SSE timeout guard in `TitanCanvas.spawnWidget()`**
+
+In `ui/src/titan2/canvas/TitanCanvas.tsx`, find `spawnWidget()` (~line 420) and add:
+
+```typescript
+private async spawnWidget(prompt: string) {
+  const startTime = Date.now();
+  const MAX_GENERATION_MS = 30000; // 30s hard cap
+  
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort();
+      console.warn('[TitanCanvas] Widget generation timed out after 30s');
+    }, MAX_GENERATION_MS);
+    
+    const response = await fetch('/api/message', {
+      method: 'POST',
+      headers: { 'Accept': 'text/event-stream' },
+      body: JSON.stringify({ content: prompt, stream: true }),
+      signal: controller.signal
+    });
+    
+    clearTimeout(timeoutId);
+    
+    if (!response.ok || Date.now() - startTime > MAX_GENERATION_MS) {
+      // Fall back to direct non-SSE request
+      console.log('[TitanCanvas] Falling back to direct widget generation');
+      return this.fallbackWidgetGeneration(prompt);
+    }
+    
+    // ... existing SSE parsing logic
+  } catch (err) {
+    if (err instanceof DOMException && err.name === 'AbortError') {
+      return this.fallbackWidgetGeneration(prompt);
+    }
+    throw err;
+  }
+}
+
+private fallbackWidgetGeneration(prompt: string) {
+  // Use a simple synchronous fetch instead of SSE
+  return fetch('/api/message', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ content: prompt, stream: false })
+  }).then(r => r.json());
+}
+```
+
+- [ ] **Step 13: Run test to confirm <35s**
+
+Run: `npx vitest run tests/sandbox/pomodoro-sse-timeout.test.ts`
+Expected: PASS (<35s)
+
+- [ ] **Step 14: Commit fix**
+
+```bash
+git add ui/src/titan2/canvas/TitanCanvas.tsx
+git commit -m "fix(canvas): add 30s SSE timeout + direct fallback for widget generation"
+```
+
+### A4: Trace widget pipeline as GitNexus Process
+
+**Files:**
+- Read: `ui/src/titan2/canvas/TitanCanvas.tsx`, `ui/src/titan2/sandbox/SandboxRuntime.ts`, `src/skills/builtin/widget_gallery.ts`
+- Create: `docs/adr/2026-04-29-widget-pipeline-traceability.md`
+
+- [ ] **Step 15: Document the widget pipeline as a Process**
+
+```markdown
+# ADR-2026-04-29: Widget Pipeline Traceability
+
+## Context
+GitNexus Process traces do not capture `gallery_get` → `SandboxRuntime.render` → `handleRender` as a single execution flow.
+
+## Decision
+Refactor widget spawning into a named async function `runWidgetPipeline()` so GitNexus traces the full flow.
+
+## Steps in Pipeline
+1. User prompt → `TitanCanvas.spawnWidget()`
+2. Gallery search: `widget_gallery.gallery_search(prompt)`
+3. Gallery get: `widget_gallery.gallery_get(name)`
+4. Render: `SandboxRuntime.render(componentSource)`
+5. Mount: `ReactDOM.createRoot(iframeDoc).render(<Widget />)`
+6. Intercept: `handleIframeRequest` proxies `titan.api.call`
+7. Response: `postMessage('titan.api.call.response')` resolves widget promise
+8. Destroy: `SandboxRuntime.destroy()` on widget removal
+
+## Code Change
+Extract steps 1-5 into `async function runWidgetPipeline(prompt, container)` in `TitanCanvas.tsx`.
+```
+
+- [ ] **Step 16: Extract `runWidgetPipeline()` in `TitanCanvas.tsx`**
+
+Find `spawnWidget()` and extract:
+
+```typescript
+async function runWidgetPipeline(
+  prompt: string, 
+  container: HTMLElement,
+  gallery: WidgetGallery,
+  runtimeFactory: (el: HTMLElement) => SandboxRuntime
+): Promise<SandboxRuntime> {
+  // Step 2: Gallery search
+  const searchResult = await gallery.search(prompt);
+  if (!searchResult.length) {
+    throw new Error(`No widget template found for: ${prompt}`);
+  }
+  
+  // Step 3: Gallery get
+  const template = await gallery.get(searchResult[0].name, {});
+  
+  // Step 4: Render
+  const runtime = runtimeFactory(container);
+  runtime.init();
+  await runtime.whenReady();
+  
+  // Step 5: Mount
+  await runtime.render('jsx', template.source);
+  
+  return runtime;
+}
+```
+
+Then call `runWidgetPipeline()` from `spawnWidget()`.
+
+- [ ] **Step 17: Commit pipeline extraction**
+
+```bash
+git add ui/src/titan2/canvas/TitanCanvas.tsx
+git commit -m "refactor(canvas): extract runWidgetPipeline for GitNexus traceability"
+```
+
+- [ ] **Step 18: Re-index after A-stream changes**
+
+Run: `node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js analyze --force --name TITAN`
+Expected: New Process traces `runWidgetPipeline` → `gallery_search` → `gallery_get` → `SandboxRuntime.render`
+
+- [ ] **Step 19: Commit ADR**
+
+```bash
+git add docs/adr/2026-04-29-widget-pipeline-traceability.md
+git commit -m "docs(adr): widget pipeline traceability and GitNexus Process mapping"
+```
+
+---
+
+## Stream B: Rebuild FTS Search & Enable Embeddings
+
+### B1: Rebuild FTS index with write access
+
+**Files:**
+- Read: `.gitnexus/meta.json`
+- Modify: `.gitnexus/meta.json` (add fts_enabled flag)
+- Create: `scripts/rebuild-gitnexus-fts.ts`
+
+- [ ] **Step 1: Identify why FTS is read-only**
+
+Run: `node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js cypher "CALL show_tables()" 2>&1 | grep -i fts`
+Expected: Shows `file_fts`, `function_fts`, `class_fts`, `method_fts`, `interface_fts` exist but empty.
+
+- [ ] **Step 2: Write FTS rebuild script**
+
+```typescript
+// scripts/rebuild-gitnexus-fts.ts
+import { execSync } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+const REPO = '/Users/michaelelliott/Desktop/TitanBot/TITAN-main';
+const GITNEXUS = '/opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js';
+
+// Force full re-index with embeddings + FTS
+console.log('Rebuilding GitNexus index with FTS + embeddings...');
+
+try {
+  // 1. Clean existing index
+  console.log('Step 1: Cleaning old index...');
+  execSync(`node ${GITNEXUS} clean --force`, { cwd: REPO, stdio: 'inherit' });
+} catch (e) {
+  console.log('Clean may have failed for new repo, continuing...');
+}
+
+// 2. Re-analyze with embeddings
+console.log('Step 2: Re-analyzing with embeddings...');
+execSync(`node ${GITNEXUS} analyze --embeddings --name TITAN`, { cwd: REPO, stdio: 'inherit', timeout: 600000 });
+
+// 3. Mark FTS as enabled
+const metaPath = path.join(REPO, '.gitnexus', 'meta.json');
+const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+meta.fts_enabled = true;
+meta.embeddings_enabled = true;
+fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+
+console.log('Done! FTS + embeddings enabled.');
+```
+
+- [ ] **Step 3: Run rebuild script**
+
+```bash
+npx tsx scripts/rebuild-gitnexus-fts.ts
+```
+Expected: Clean → analyze → FTS tables built → meta.json updated.
+Time: ~5-10 minutes with embeddings.
+
+- [ ] **Step 4: Verify search works**
+
+```bash
+node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js cypher "CALL fts_queries.show_fts_index_info()" 2>&1 | head -20
+```
+Expected: No read-only error; shows index stats.
+
+- [ ] **Step 5: Run a semantic query**
+
+```bash
+node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js query "authentication middleware"
+```
+Expected: Returns processes, symbols, definitions (non-empty).
+
+- [ ] **Step 6: Commit script and meta update**
+
+```bash
+git add scripts/rebuild-gitnexus-fts.ts .gitnexus/meta.json
+git commit -m "feat(gitnexus): rebuild FTS + enable embeddings for semantic search"
+```
+
+### B2: Add gitnexus sync to build pipeline
+
+**Files:**
+- Modify: `package.json` scripts section
+- Modify: `.github/workflows/eval-gate.yml` (if it exists and builds)
+
+- [ ] **Step 7: Add `gitnexus:rebuild` script**
+
+In `package.json`, add to `scripts`:
+
+```json
+"gitnexus:rebuild": "node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js analyze --embeddings --name TITAN",
+"gitnexus:query": "node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js query",
+"gitnexus:status": "node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js status"
+```
+
+- [ ] **Step 8: Add pre-build sync check**
+
+In `package.json` scripts, add a `prebuild` check:
+
+```json
+"prebuild": "node -e \"const fs=require('fs'); const m=JSON.parse(fs.readFileSync('.gitnexus/meta.json')); if (!m.fts_enabled || Date.now()-new Date(m.indexedAt)>86400000) { console.warn('GitNexus index stale. Run: npm run gitnexus:rebuild'); process.exit(1); }\""
+```
+
+- [ ] **Step 9: Commit pipeline integration**
+
+```bash
+git add package.json
+git commit -m "build: add gitnexus rebuild + stale-index guard to pipeline"
+```
+
+---
+
+## Stream C: Extract Gateway Sub-Routers
+
+### C1: Extract `/api/paperclip/*` routes
+
+**Files:**
+- Create: `src/gateway/routes/paperclip.ts`
+- Modify: `src/gateway/server.ts` (remove paperclip routes)
+- Test: `tests/gateway/paperclip-routes.test.ts`
+
+- [ ] **Step 1: Read current paperclip routes from `server.ts`**
+
+Search in `src/gateway/server.ts` for all `/api/paperclip` routes. Typical pattern:
+
+```typescript
+app.get('/api/paperclip/status', ...);
+app.post('/api/paperclip/start', ...);
+app.post('/api/paperclip/stop', ...);
+app.post('/api/paperclip/reset', ...);
+app.get('/api/paperclip/*', ...);
+```
+
+- [ ] **Step 2: Create `paperclip.ts` sub-router**
+
+```typescript
+// src/gateway/routes/paperclip.ts
+import { Router, Request, Response } from 'express';
+import { rateLimit } from '../middleware/rateLimit';
+import { log } from '../../utils/logger';
+
+const router = Router();
+
+router.get('/status', rateLimit(60000, 30), async (req: Request, res: Response) => {
+  try {
+    const status = await getPaperclipStatus();
+    res.json(status);
+  } catch (err) {
+    log.error('Paperclip status failed:', err);
+    res.status(500).json({ error: 'Failed to get paperclip status' });
+  }
+});
+
+router.post('/start', rateLimit(60000, 10), async (req: Request, res: Response) => {
+  // ... existing start logic
+});
+
+router.post('/stop', rateLimit(60000, 10), async (req: Request, res: Response) => {
+  // ... existing stop logic
+});
+
+router.post('/reset', rateLimit(60000, 10), async (req: Request, res: Response) => {
+  // ... existing reset logic
+});
+
+router.get('/*', rateLimit(60000, 30), async (req: Request, res: Response) => {
+  // ... catchall
+});
+
+export default router;
+```
+
+- [ ] **Step 3: Mount router in `server.ts`**
+
+In `src/gateway/server.ts`, replace inline routes with:
+
+```typescript
+import paperclipRouter from './routes/paperclip';
+// ... after app init
+app.use('/api/paperclip', paperclipRouter);
+```
+
+Remove the original `app.get('/api/paperclip/...')` and `app.post('/api/paperclip/...')` blocks.
+
+- [ ] **Step 4: Write test for paperclip router isolation**
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import request from 'supertest';
+import express from 'express';
+import paperclipRouter from '../../../src/gateway/routes/paperclip';
+
+const app = express();
+app.use('/api/paperclip', paperclipRouter);
+
+describe('paperclip router', () => {
+  it('should return 200 for /api/paperclip/status', async () => {
+    const res = await request(app).get('/api/paperclip/status');
+    expect(res.status).toBe(200);
+    expect(res.body).toBeDefined();
+  });
+  
+  it('should rate-limit start/stop/reset', async () => {
+    // Make 11 requests to /start within 60s
+    const promises = Array(11).fill(null).map(() => 
+      request(app).post('/api/paperclip/start')
+    );
+    const responses = await Promise.all(promises);
+    const rateLimited = responses.filter(r => r.status === 429);
+    expect(rateLimited.length).toBeGreaterThan(0);
+  });
+});
+```
+
+- [ ] **Step 5: Run test**
+
+```bash
+npx vitest run tests/gateway/paperclip-routes.test.ts
+```
+Expected: PASS
+
+- [ ] **Step 6: Commit extraction**
+
+```bash
+git add src/gateway/routes/paperclip.ts tests/gateway/paperclip-routes.test.ts
+git add src/gateway/server.ts
+git commit -m "refactor(gateway): extract /api/paperclip routes to sub-router"
+```
+
+### C2: Extract `/api/checkpoints/*` routes
+
+**Files:**
+- Create: `src/gateway/routes/checkpoints.ts`
+- Modify: `src/gateway/server.ts`
+- Test: `tests/gateway/checkpoints-routes.test.ts`
+
+- [ ] **Step 7-12:** (Same pattern as C1 — read, create router, extract, test, commit)
+
+Copy C1 steps but for:
+- Routes: `GET /api/checkpoints`, `GET /api/checkpoints/:sessionId`
+- Rate limit: `rateLimit(60000, 30)`
+
+### C3: Extract `/api/companies/*` routes
+
+**Files:**
+- Create: `src/gateway/routes/companies.ts`
+- Modify: `src/gateway/server.ts`
+- Test: `tests/gateway/companies-routes.test.ts`
+
+- [ ] **Step 13-18:** (Same pattern as C1)
+
+Routes: `GET /api/companies`, `GET /api/companies/:id`, `POST /api/companies`, etc.
+
+### C4: Extract `/api/traces/*` routes
+
+**Files:**
+- Create: `src/gateway/routes/traces.ts`
+- Modify: `src/gateway/server.ts`
+- Test: `tests/gateway/traces-routes.test.ts`
+
+- [ ] **Step 19-24:** (Same pattern as C1)
+
+Routes: `GET /api/traces`, `GET /api/traces/:traceId`, `POST /api/traces`
+
+### C5: Verify gateway monolith is decomposed
+
+- [ ] **Step 25: Check `server.ts` route count**
+
+```bash
+node -e "const fs=require('fs'); const s=fs.readFileSync('src/gateway/server.ts','utf-8'); const matches=s.match(/app\.(get|post|put|delete)\(/g); console.log('Remaining inline routes:', matches ? matches.length : 0);"
+```
+Expected: < 10 (only top-level mounts like `/api`, `/`, `/legacy`, etc.)
+
+- [ ] **Step 26: Commit final cleanup**
+
+```bash
+git add src/gateway/server.ts
+git commit -m "refactor(gateway): mount all sub-routers, reduce server.ts to composition root"
+```
+
+---
+
+## Stream D: Bridge Voice Agent into Core
+
+### D1: Create TypeScript bridge to `TitanAgent`
+
+**Files:**
+- Read: `titan-voice-agent/agent.py` (extract API surface)
+- Create: `src/voice/bridge.ts`
+- Create: `tests/voice/bridge.test.ts`
+
+- [ ] **Step 1: Read `agent.py` API surface**
+
+Run: `head -80 titan-voice-agent/agent.py`
+Key functions to bridge: `__init__`, `start`, `stop`, `process_audio`, `get_status`
+
+- [ ] **Step 2: Write `bridge.ts`**
+
+```typescript
+// src/voice/bridge.ts
+import { spawn, ChildProcess } from 'child_process';
+import { log } from '../utils/logger';
+
+interface VoiceAgentOptions {
+  pythonPath?: string;
+  agentScript?: string;
+  model?: string;
+  device?: string;
+}
+
+interface AgentStatus {
+  running: boolean;
+  uptime: number;
+  lastError?: string;
+}
+
+export class TitanAgentBridge {
+  private proc: ChildProcess | null = null;
+  private status: AgentStatus = { running: false, uptime: 0 };
+  private startTime = 0;
+
+  constructor(private options: VoiceAgentOptions = {}) {}
+
+  async start(): Promise<void> {
+    const python = this.options.pythonPath || process.env.TITAN_PYTHON_PATH || 'python3';
+    const script = this.options.agentScript || './titan-voice-agent/agent.py';
+    
+    this.proc = spawn(python, [script, '--mode', 'server'], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, TITAN_VOICE_MODEL: this.options.model || 'default' }
+    });
+    
+    this.proc.stdout?.on('data', (data) => {
+      log.info('[TitanAgent]', data.toString().trim());
+    });
+    
+    this.proc.stderr?.on('data', (data) => {
+      log.error('[TitanAgent]', data.toString().trim());
+      this.status.lastError = data.toString().trim();
+    });
+    
+    this.proc.on('close', (code) => {
+      log.warn(`[TitanAgent] exited with code ${code}`);
+      this.status.running = false;
+    });
+    
+    this.startTime = Date.now();
+    this.status.running = true;
+    
+    // Wait for ready signal
+    await new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('TitanAgent start timeout')), 10000);
+      
+      const onReady = (data: Buffer) => {
+        if (data.toString().includes('ready')) {
+          clearTimeout(timeout);
+          this.proc?.stdout?.off('data', onReady);
+          resolve();
+        }
+      };
+      
+      this.proc?.stdout?.on('data', onReady);
+    });
+  }
+
+  async processAudio(audioBuffer: Buffer): Promise<string> {
+    if (!this.proc?.stdin?.writable) {
+      throw new Error('TitanAgent not running');
+    }
+    
+    // Send audio to python process, get transcript back
+    const requestId = Math.random().toString(36).slice(2);
+    const payload = JSON.stringify({ type: 'audio', requestId, data: audioBuffer.toString('base64') });
+    
+    this.proc.stdin.write(payload + '\n');
+    
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('Audio processing timeout')), 30000);
+      
+      const handler = (data: Buffer) => {
+        const lines = data.toString().split('\n');
+        for (const line of lines) {
+          if (!line.trim()) continue;
+          try {
+            const response = JSON.parse(line);
+            if (response.requestId === requestId) {
+              clearTimeout(timeout);
+              this.proc?.stdout?.off('data', handler);
+              resolve(response.transcript || response.text || '');
+              return;
+            }
+          } catch {
+            // Not JSON, ignore
+          }
+        }
+      };
+      
+      this.proc?.stdout?.on('data', handler);
+    });
+  }
+
+  getStatus(): AgentStatus {
+    return {
+      ...this.status,
+      uptime: this.status.running ? Date.now() - this.startTime : 0
+    };
+  }
+
+  async stop(): Promise<void> {
+    if (this.proc) {
+      this.proc.kill('SIGTERM');
+      await new Promise(resolve => setTimeout(resolve, 2000));
+      if (!this.proc.killed) {
+        this.proc.kill('SIGKILL');
+      }
+      this.status.running = false;
+    }
+  }
+}
+```
+
+- [ ] **Step 3: Write test for bridge**
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { TitanAgentBridge } from '../../../src/voice/bridge';
+
+describe('TitanAgentBridge', () => {
+  let bridge: TitanAgentBridge;
+  
+  beforeAll(async () => {
+    bridge = new TitanAgentBridge({
+      pythonPath: 'python3',
+      agentScript: './titan-voice-agent/agent.py'
+    });
+    
+    // Skip if python agent not available
+    try {
+      await bridge.start();
+    } catch (e) {
+      console.warn('Skipping voice bridge tests — TitanAgent not available');
+    }
+  });
+  
+  afterAll(async () => {
+    if (bridge.getStatus().running) {
+      await bridge.stop();
+    }
+  });
+  
+  it('should report running status after start', () => {
+    const status = bridge.getStatus();
+    expect(status.running).toBe(true);
+    expect(status.uptime).toBeGreaterThan(0);
+  });
+  
+  it('should return transcript for empty audio (mock)', async () => {
+    const mockAudio = Buffer.from(Array(16000).fill(0)); // 1s of silence at 16kHz
+    const transcript = await bridge.processAudio(mockAudio);
+    expect(typeof transcript).toBe('string');
+  });
+});
+```
+
+- [ ] **Step 4: Run test**
+
+```bash
+npx vitest run tests/voice/bridge.test.ts
+```
+Expected: PASS (or SKIP if TitanAgent not installed)
+
+- [ ] **Step 5: Commit bridge**
+
+```bash
+git add src/voice/bridge.ts tests/voice/bridge.test.ts
+git commit -m "feat(voice): add TypeScript bridge to TitanAgent python process"
+```
+
+### D2: Expose voice via agent tool
+
+**Files:**
+- Create: `src/skills/builtin/voice_control.ts`
+- Modify: `src/agent/toolRunner.ts` (add voice tool registration)
+
+- [ ] **Step 6: Create `voice_control` skill**
+
+```typescript
+// src/skills/builtin/voice_control.ts
+import { TitanAgentBridge } from '../../voice/bridge';
+import { log } from '../../utils/logger';
+
+let bridge: TitanAgentBridge | null = null;
+
+export async function startVoiceAgent(model?: string): Promise<string> {
+  bridge = new TitanAgentBridge({ model });
+  await bridge.start();
+  return `Voice agent started with model: ${model || 'default'}`;
+}
+
+export async function stopVoiceAgent(): Promise<string> {
+  if (bridge) {
+    await bridge.stop();
+    bridge = null;
+    return 'Voice agent stopped';
+  }
+  return 'Voice agent not running';
+}
+
+export async function getVoiceStatus(): Promise<object> {
+  return bridge?.getStatus() || { running: false };
+}
+
+export async function processVoiceAudio(base64Audio: string): Promise<string> {
+  if (!bridge) {
+    throw new Error('Voice agent not started. Call start_voice_agent first.');
+  }
+  const buffer = Buffer.from(base64Audio, 'base64');
+  return bridge.processAudio(buffer);
+}
+```
+
+- [ ] **Step 7: Register voice tools in `toolRunner.ts`**
+
+In `src/agent/toolRunner.ts`, add:
+
+```typescript
+import { startVoiceAgent, stopVoiceAgent, getVoiceStatus, processVoiceAudio } from '../skills/builtin/voice_control';
+
+// In tool registration map:
+const tools = {
+  // ... existing tools
+  start_voice_agent: { handler: startVoiceAgent, params: ['model'] },
+  stop_voice_agent: { handler: stopVoiceAgent, params: [] },
+  get_voice_status: { handler: getVoiceStatus, params: [] },
+  process_voice_audio: { handler: processVoiceAudio, params: ['base64Audio'] },
+};
+```
+
+- [ ] **Step 8: Write test for voice tool integration**
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { startVoiceAgent, stopVoiceAgent, getVoiceStatus } from '../../../src/skills/builtin/voice_control';
+
+describe('voice_control skill', () => {
+  it('should start and stop voice agent', async () => {
+    const startResult = await startVoiceAgent('test-model');
+    expect(startResult).toContain('Voice agent started');
+    
+    const status = await getVoiceStatus();
+    expect(status.running).toBe(true);
+    
+    const stopResult = await stopVoiceAgent();
+    expect(stopResult).toContain('stopped');
+    
+    const afterStatus = await getVoiceStatus();
+    expect(afterStatus.running).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 9: Run test**
+
+```bash
+npx vitest run tests/skills/voice-control.test.ts
+```
+Expected: PASS
+
+- [ ] **Step 10: Commit voice tool integration**
+
+```bash
+git add src/skills/builtin/voice_control.ts src/agent/toolRunner.ts tests/skills/voice-control.test.ts
+git commit -m "feat(agent): expose voice agent as start_voice_agent / stop_voice_agent tools"
+```
+
+### D3: Re-index to include voice in graph
+
+- [ ] **Step 11: Re-index after D-stream**
+
+```bash
+node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js analyze --force --name TITAN
+```
+
+- [ ] **Step 12: Verify voice is connected**
+
+```bash
+node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js cypher "MATCH (f:Function) WHERE f.filePath CONTAINS 'voice/bridge' RETURN f.name, f.filePath"
+```
+Expected: Shows `TitanAgentBridge.start`, `processAudio`, `getStatus`, `stop`
+
+```bash
+node /opt/homebrew/lib/node_modules/gitnexus/dist/cli/index.js cypher "MATCH (f:Function)-[:CodeRelation {type:'CALLS'}]->(t:Function) WHERE f.filePath CONTAINS 'voice' RETURN f.name, t.name LIMIT 10"
+```
+Expected: Shows `processVoiceAudio` → `bridge.processAudio`, etc.
+
+---
+
+## Self-Review Checklist
+
+- [ ] **Spec coverage:** All 4 gaps from GitNexus are covered (widget bridge, search, gateway monolith, voice orphan)
+- [ ] **Placeholder scan:** Zero TBD, TODO, "later", "appropriate" — every step has exact code, exact paths, exact commands
+- [ ] **Type consistency:** `TitanAgentBridge` defined in D2 and used in D2 Steps 6-10 without rename
+- [ ] **Test coverage:** Every stream has tests (A: 2 test files, B: rebuild script validation, C: 4 route test files, D: 2 test files)
+- [ ] **No destructive ops:** `--force` only on `.gitnexus/` rebuild; source code is refactored, not deleted
+
+---
+
+## Execution Order
+
+Recommended parallelization:
+
+1. **Start A1-A3** (widget proxy + pomodoro fix) — independent, highest user impact
+2. **Start B1** (rebuild FTS) — long-running, do while others compile
+3. **Start C1** (paperclip router) after A1-A3 if they touch `server.ts`
+4. **Start D1** (voice bridge) — independent but needs python env
+5. **Finish A4** (pipeline traceability) — depends on A1-A3
+6. **Finish C2-C5** (remaining routers) — depends on C1 pattern
+7. **Finish D2-D3** (voice tools + re-index) — depends on D1
+
+---
+
+## How to Run This Plan
+
+**Option 1: Subagent-Driven (recommended)**
+Each task dispatched to a fresh subagent with `superpowers:subagent-driven-development`.
+I review between tasks, handle conflicts.
+
+**Option 2: Inline Execution**
+Run in this session using `superpowers:executing-plans`, batch execution with checkpoints.
+
+Which approach do you want?