agileflow 3.4.3 → 4.0.0-alpha.1

package/scripts/spawn-audit-sessions.js

@@ -1,877 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * spawn-audit-sessions.js - Spawn ULTRADEEP audit analyzer sessions in tmux
- *
- * Spawns each analyzer as a separate Claude Code session in tmux,
- * with sentinel files for coordination and tab grouping for visual organization.
- *
- * Key differences from spawn-parallel.js:
- *   - No worktrees: audits are read-only, all sessions share the same repo
- *   - Piped prompts: each session gets analyzer-specific prompt via echo | claude
- *   - Sentinel files: each writes findings to docs/09-agents/ultradeep/{trace_id}/
- *   - Tab grouping: applies colors from tmux-group-colors.js
- *
- * Usage:
- *   node scripts/spawn-audit-sessions.js --audit=security --target=src/ --focus=all --trace-id=abc123
- *   node scripts/spawn-audit-sessions.js --audit=logic --target=. --depth=ultradeep
- *
- * Options:
- *   --audit=TYPE       Audit type: logic|security|performance|test|completeness|legal
- *   --target=PATH      Target file or directory to analyze
- *   --focus=AREAS      Comma-separated focus areas, or 'all'
- *   --trace-id=ID      Unique trace ID (auto-generated if not provided)
- *   --timeout=MINUTES  Completion timeout (default: 30)
- *   --dry-run          Show what would be spawned without executing
- */
-
-const { execFileSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const crypto = require('crypto');
-
-const { getAuditType, getAnalyzersForAudit } = require('./lib/audit-registry');
-const { getColorForAudit } = require('./lib/tmux-group-colors');
-const { resolveModel, estimateCost } = require('./lib/model-profiles');
-
-const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
-
-/**
- * Read ultradeep config from agileflow-metadata.json.
- * @returns {{ stagger_seconds: number, max_concurrent: number }}
- */
-function getUltradeepConfig() {
-  const defaults = { stagger_seconds: 3, max_concurrent: 0 };
-  try {
-    const metaPath = path.join(process.cwd(), 'docs', '00-meta', 'agileflow-metadata.json');
-    if (fs.existsSync(metaPath)) {
-      const meta = JSON.parse(fs.readFileSync(metaPath, 'utf8'));
-      const ud = meta.ultradeep || {};
-      if (typeof ud.stagger_seconds === 'number') defaults.stagger_seconds = ud.stagger_seconds;
-      if (typeof ud.max_concurrent === 'number') defaults.max_concurrent = ud.max_concurrent;
-    }
-  } catch (_) {
-    /* use defaults */
-  }
-  return defaults;
-}
-
-/**
- * Parse CLI arguments.
- * @returns {object} Parsed options
- */
-function parseArgs() {
-  const args = process.argv.slice(2);
-  const options = {
-    audit: null,
-    target: '.',
-    focus: ['all'],
-    model: null,
-    traceId: null,
-    timeout: 30,
-    dryRun: false,
-    json: false,
-    stagger: null,
-    concurrency: null,
-    depth: null,
-    partitions: null,
-  };
-
-  for (const arg of args) {
-    if (arg.startsWith('--audit=')) options.audit = arg.split('=')[1];
-    else if (arg.startsWith('--target=')) options.target = arg.split('=')[1];
-    else if (arg.startsWith('--focus=')) options.focus = arg.split('=')[1].split(',');
-    else if (arg.startsWith('--model=')) options.model = arg.split('=')[1];
-    else if (arg.startsWith('--trace-id=')) options.traceId = arg.split('=')[1];
-    else if (arg.startsWith('--timeout=')) {
-      const parsed = parseInt(arg.split('=')[1], 10);
-      options.timeout = isNaN(parsed) ? 30 : parsed;
-    } else if (arg.startsWith('--stagger=')) {
-      const parsed = parseFloat(arg.split('=')[1]);
-      options.stagger = isNaN(parsed) ? null : parsed;
-    } else if (arg.startsWith('--concurrency=')) {
-      const parsed = parseInt(arg.split('=')[1], 10);
-      options.concurrency = isNaN(parsed) ? null : parsed;
-    } else if (arg.startsWith('--depth=')) options.depth = arg.split('=')[1];
-    else if (arg.startsWith('--partitions='))
-      options.partitions = arg.split('=')[1].split(',').filter(Boolean);
-    else if (arg === '--dry-run') options.dryRun = true;
-    else if (arg === '--json') options.json = true;
-  }
-
-  if (!options.traceId) {
-    options.traceId = crypto.randomBytes(6).toString('hex');
-  }
-
-  return options;
-}
-
-/**
- * Check if tmux is available and we're in a tmux session.
- * @returns {{ available: boolean, inSession: boolean }}
- */
-function checkTmux() {
-  try {
-    execFileSync('which', ['tmux'], { stdio: 'pipe' });
-    const inSession = !!process.env.TMUX;
-    return { available: true, inSession };
-  } catch (_) {
-    return { available: false, inSession: false };
-  }
-}
-
-/**
- * Create the sentinel directory for a trace.
- * @param {string} rootDir - Project root
- * @param {string} traceId - Unique trace ID
- * @returns {string} Path to sentinel directory
- */
-function createSentinelDir(rootDir, traceId) {
-  const sentinelDir = path.join(rootDir, 'docs', '09-agents', 'ultradeep', traceId);
-  fs.mkdirSync(sentinelDir, { recursive: true });
-  return sentinelDir;
-}
-
-/**
- * Write initial status file for the trace.
- * @param {string} sentinelDir - Sentinel directory path
- * @param {string} auditType - Audit type key
- * @param {Array} analyzers - Array of analyzer configs
- * @param {number} [staggerMs] - Stagger delay in milliseconds
- * @param {number} [maxConcurrent] - Max concurrent sessions (0 = unlimited)
- */
-function writeStatusFile(sentinelDir, auditType, analyzers, staggerMs, maxConcurrent, extra) {
-  const status = {
-    started_at: new Date().toISOString(),
-    audit_type: auditType,
-    analyzers: analyzers.map(a => a.key),
-    completed: [],
-    failed: [],
-    stagger_ms: staggerMs != null ? staggerMs : null,
-    max_concurrent: maxConcurrent || null,
-  };
-  // Store extra fields for retry support
-  if (extra) {
-    if (extra.target != null) status.target = extra.target;
-    if (extra.model != null) status.model = extra.model;
-    if (extra.timeout_minutes != null) status.timeout_minutes = extra.timeout_minutes;
-  }
-  fs.writeFileSync(path.join(sentinelDir, '_status.json'), JSON.stringify(status, null, 2) + '\n');
-}
-
-/**
- * Build the prompt for an individual analyzer session.
- * @param {object} analyzer - Analyzer config { key, subagent_type, label }
- * @param {string} target - Target path to analyze
- * @param {string} traceId - Trace ID
- * @param {string} sentinelDir - Sentinel directory for output
- * @param {string} auditType - Audit type key
- * @param {string} [model] - Resolved model name for sub-agent
- * @returns {string} Prompt text
- */
-function buildAnalyzerPrompt(analyzer, target, traceId, sentinelDir, auditType, model) {
-  const findingsFile = path.join(sentinelDir, `${analyzer.key}.findings.json`);
-
-  // Sanitize fields that get interpolated into double-quoted prompt sections
-  const safeLabel = String(analyzer.label || '').replace(/["\\]/g, '');
-  const safeTarget = String(target || '').replace(/["\\]/g, '');
-  const safeSubagentType = String(analyzer.subagent_type || '').replace(/["\\]/g, '');
-
-  return `You are an ULTRADEEP audit session coordinator.
-
-## Task
-
-1. Use the Agent tool to spawn a sub-agent for analysis
-2. After the sub-agent completes, parse its output and write findings as JSON to the sentinel file
-
-## Agent Configuration
-
-Use the Agent tool with these parameters:
-- subagent_type: "${safeSubagentType}"
-- description: "${safeLabel} analysis of ${safeTarget}"${model ? `\n- model: "${model}"` : ''}
-- prompt: |
-    Analyze the target path ${safeTarget} thoroughly for ${safeLabel}-related issues.
-    Search all relevant files recursively. Be thorough.
-    Return a JSON object with this structure:
-    {"findings": [{"id": "${analyzer.key}-NNN", "severity": "P0|P1|P2|P3", "title": "Short description", "file": "path/to/file.js", "line": 42, "description": "Detailed explanation", "evidence": "Code snippet or reasoning", "recommendation": "How to fix"}], "summary": {"files_scanned": 0, "total_findings": 0, "by_severity": {"P0": 0, "P1": 0, "P2": 0, "P3": 0}}}
-    TRACE_ID: ${traceId}
-    ANALYZER: ${analyzer.key}
-
-## Output
-
-After the Agent tool returns its analysis, write a JSON file to: ${findingsFile}
-
-Use this structure:
-{
-  "analyzer": "${analyzer.key}",
-  "audit_type": "${auditType}",
-  "trace_id": "${traceId}",
-  "target": "${safeTarget}",
-  "completed_at": "<ISO timestamp>",
-  "findings": [
-    {
-      "id": "${analyzer.key}-001",
-      "severity": "P0|P1|P2|P3",
-      "title": "Short description",
-      "file": "path/to/file.js",
-      "line": 42,
-      "description": "Detailed explanation",
-      "evidence": "Code snippet or reasoning",
-      "recommendation": "How to fix"
-    }
-  ],
-  "summary": {
-    "files_scanned": 0,
-    "total_findings": 0,
-    "by_severity": { "P0": 0, "P1": 0, "P2": 0, "P3": 0 }
-  }
-}
-
-IMPORTANT: You MUST write the findings JSON file when complete. This is how the orchestrator knows you're done.
-If the Agent tool is unavailable or returns an error, perform the analysis directly using Read, Glob, and Grep tools.
-Start by spawning the Agent now.`;
-}
-
-/**
- * Create a slug from a partition path for use in window names and filenames.
- * Only allows alphanumeric, hyphens, and underscores — safe for tmux window
- * names, shell interpolation, and filesystem paths.
- * @param {string} partition - Partition path (e.g. 'src/auth')
- * @returns {string} Slug (e.g. 'src-auth')
- */
-function partitionSlug(partition) {
-  return (
-    partition
-      .replace(/^\.?\/?/, '')
-      .replace(/\/+$/g, '')
-      .replace(/[/\\]/g, '-')
-      .replace(/[^a-zA-Z0-9_-]/g, '_') || 'root'
-  );
-}
-
-/**
- * Build the prompt for an extreme-mode partition coordinator session.
- * This coordinator runs ALL analyzers on a single partition using the Agent tool.
- * @param {string} partition - Partition path to analyze
- * @param {Array<{ key: string, subagent_type: string, label: string }>} analyzers - All analyzers to run
- * @param {string} traceId - Trace ID
- * @param {string} sentinelDir - Sentinel directory for output
- * @param {string} auditType - Audit type key
- * @param {string} [model] - Resolved model name for sub-agents
- * @returns {string} Prompt text
- */
-function buildExtremePrompt(partition, analyzers, traceId, sentinelDir, auditType, model) {
-  const slug = partitionSlug(partition);
-  const findingsFile = path.join(sentinelDir, `${slug}.findings.json`);
-
-  const safePartition = String(partition || '').replace(/["\\]/g, '');
-
-  const analyzerList = analyzers
-    .map((a, i) => `${i + 1}. subagent_type: "${a.subagent_type}" — ${a.label} (key: ${a.key})`)
-    .join('\n');
-
-  const modelLine = model ? `\n- model: "${model}"` : '';
-
-  return `You are an EXTREME audit session coordinator for partition: ${safePartition}
-
-## Task
-
-Run ALL of the following analyzers on your partition using the Agent tool.
-Deploy them in parallel (multiple Agent calls in one message) where possible.
-
-## Analyzers to Run
-${analyzerList}
-
-## Agent Configuration for Each Analyzer
-
-Use the Agent tool with these parameters for each analyzer:
-- subagent_type: (from the list above)
-- description: "[Analyzer label] analysis of ${safePartition}"${modelLine}
-- prompt: |
-    Analyze the target path ${safePartition} thoroughly for issues relevant to your analyzer domain.
-    Search all relevant files recursively. Be thorough.
-    Use the analyzer key from your subagent_type as the ID prefix (e.g., for "security-analyzer-injection" use "injection").
-    Return a JSON object with this structure:
-    {"findings": [{"id": "<analyzer-key>-NNN", "severity": "P0|P1|P2|P3", "title": "Short description", "file": "path/to/file.js", "line": 42, "description": "Detailed explanation", "evidence": "Code snippet or reasoning", "recommendation": "How to fix"}], "summary": {"files_scanned": 0, "total_findings": 0, "by_severity": {"P0": 0, "P1": 0, "P2": 0, "P3": 0}}}
-    TRACE_ID: ${traceId}
-
-## After All Analyzers Complete
-
-Combine ALL findings from ALL analyzers into a single JSON file: ${findingsFile}
-
-Use this structure:
-{
-  "partition": "${safePartition}",
-  "audit_type": "${auditType}",
-  "trace_id": "${traceId}",
-  "completed_at": "<ISO timestamp>",
-  "analyzer_count": ${analyzers.length},
-  "analyzers_run": [${analyzers.map(a => `"${a.key}"`).join(', ')}],
-  "findings": [
-    {
-      "id": "<analyzer_key>-001",
-      "analyzer": "<analyzer_key>",
-      "severity": "P0|P1|P2|P3",
-      "title": "Short description",
-      "file": "path/to/file.js",
-      "line": 42,
-      "description": "Detailed explanation",
-      "evidence": "Code snippet or reasoning",
-      "recommendation": "How to fix"
-    }
-  ],
-  "summary": {
-    "files_scanned": 0,
-    "total_findings": 0,
-    "by_severity": { "P0": 0, "P1": 0, "P2": 0, "P3": 0 }
-  }
-}
-
-IMPORTANT: You MUST write the findings JSON file when complete. This is how the orchestrator knows you're done.
-Start by spawning ALL ${analyzers.length} analyzers now, in parallel.`;
-}
-
-/**
- * Spawn a single analyzer session in tmux.
- * @param {object} params - Session parameters
- * @returns {string|null} Window name if successful, null on failure
- */
-function spawnOneSession({
-  analyzer,
-  index,
-  sessionName,
-  rootDir,
-  options,
-  sentinelDir,
-  auditType,
-  groupColor,
-}) {
-  const windowName = `${auditType.prefix}:${analyzer.key}`;
-  const model = resolveModel(options.model, 'haiku');
-  const prompt = buildAnalyzerPrompt(
-    analyzer,
-    options.target,
-    options.traceId,
-    sentinelDir,
-    options.audit,
-    model
-  );
-  const escapedPrompt = prompt.replace(/'/g, "'\\''");
-
-  try {
-    if (index === 0) {
-      execFileSync(
-        'tmux',
-        ['new-session', '-d', '-s', sessionName, '-n', windowName, '-c', rootDir],
-        { stdio: 'pipe' }
-      );
-    } else {
-      execFileSync('tmux', ['new-window', '-t', sessionName, '-n', windowName, '-c', rootDir], {
-        stdio: 'pipe',
-      });
-    }
-
-    execFileSync(
-      'tmux',
-      ['set-option', '-w', '-t', `${sessionName}:${windowName}`, '@group_color', groupColor],
-      { stdio: 'pipe' }
-    );
-
-    const claudeCmd = `echo '${escapedPrompt}' | claude --model ${model} --allowedTools 'Read Glob Grep Write Agent' 2>&1; echo "AUDIT_COMPLETE: ${analyzer.key}"`;
-    execFileSync('tmux', ['send-keys', '-t', `${sessionName}:${windowName}`, claudeCmd, 'Enter'], {
-      stdio: 'pipe',
-    });
-
-    return windowName;
-  } catch (err) {
-    console.error(`Failed to spawn ${windowName}: ${err.message}`);
-    return null;
-  }
-}
-
-/**
- * Poll sentinel directory for wave completion.
- * @param {string} sentinelDir - Sentinel directory path
- * @param {string[]} keys - Analyzer keys to wait for
- * @param {number} timeoutMinutes - Timeout in minutes
- * @returns {Promise<boolean>} true if all completed, false on timeout
- */
-async function pollWaveCompletion(sentinelDir, keys, timeoutMinutes) {
-  const timeoutMs = (timeoutMinutes || 30) * 60 * 1000;
-  const startTime = Date.now();
-  while (Date.now() - startTime < timeoutMs) {
-    const allDone = keys.every(key =>
-      fs.existsSync(path.join(sentinelDir, `${key}.findings.json`))
-    );
-    if (allDone) return true;
-    await sleep(3000);
-  }
-  return false;
-}
-
-/**
- * Spawn audit analyzer sessions in tmux with staggered launching.
- * @param {object} options - Parsed CLI options
- * @returns {Promise<{ ok: boolean, traceId: string, sentinelDir: string, sessions: string[] }>}
- */
-async function spawnAuditInTmux(options) {
-  const rootDir = process.cwd();
-  const auditType = getAuditType(options.audit);
-
-  if (!auditType) {
-    console.error(`Unknown audit type: ${options.audit}`);
-    console.error(`Valid types: logic, security, performance, test, completeness, legal, seo, ads`);
-    process.exit(1);
-  }
-
-  const isExtreme = options.depth === 'extreme';
-  const depthForRegistry = isExtreme ? 'extreme' : 'ultradeep';
-  const result = getAnalyzersForAudit(options.audit, depthForRegistry, options.focus);
-  if (!result || result.analyzers.length === 0) {
-    console.error(`No analyzers found for ${options.audit} with focus: ${options.focus.join(',')}`);
-    process.exit(1);
-  }
-
-  const sentinelDir = createSentinelDir(rootDir, options.traceId);
-
-  // Use stderr for human output when --json mode is active
-  const log = options.json ? console.error : console.log;
-
-  // --- EXTREME MODE: partition-based multi-agent ---
-  if (isExtreme) {
-    if (!options.partitions || options.partitions.length === 0) {
-      console.error('EXTREME mode requires --partitions=dir1,dir2,...');
-      process.exit(1);
-    }
-
-    const partitions = options.partitions;
-    const partitionSlugs = partitions.map(p => partitionSlug(p));
-
-    // Write status file with partition info
-    const statusData = {
-      started_at: new Date().toISOString(),
-      audit_type: options.audit,
-      mode: 'extreme',
-      partitions: partitions,
-      analyzers: partitionSlugs,
-      analyzers_per_partition: result.analyzers.map(a => a.key),
-      completed: [],
-      failed: [],
-      target: options.target,
-      model: options.model,
-      timeout_minutes: options.timeout,
-    };
-    fs.writeFileSync(
-      path.join(sentinelDir, '_status.json'),
-      JSON.stringify(statusData, null, 2) + '\n'
-    );
-
-    const groupColor = getColorForAudit(options.audit);
-    const totalSessions = partitions.length * result.analyzers.length;
-
-    if (options.dryRun) {
-      log(`\nDry run - EXTREME mode would spawn ${partitions.length} partition coordinators:`);
-      log(`  Partitions: ${partitions.join(', ')}`);
-      log(`  Analyzers per partition: ${result.analyzers.length}`);
-      log(`  Total agent sessions: ${totalSessions}`);
-      const model = resolveModel(options.model, 'haiku');
-      for (const p of partitions) {
-        const slug = partitionSlug(p);
-        log(
-          `  ${auditType.prefix}:${slug} (${model}) → ALL ${result.analyzers.length} analyzers on ${p}`
-        );
-      }
-      log(`\nSentinel dir: ${sentinelDir}`);
-      log(`Group color: ${groupColor}`);
-      return {
-        ok: true,
-        traceId: options.traceId,
-        sentinelDir,
-        sessions: [],
-        dryRun: true,
-        mode: 'extreme',
-        partitions,
-      };
-    }
-
-    const tmux = checkTmux();
-    if (!tmux.available) {
-      console.error('tmux is not available. EXTREME mode requires tmux.');
-      console.error('Falling back to DEPTH=deep mode.');
-      return { ok: false, traceId: options.traceId, sentinelDir, sessions: [], fallback: 'deep' };
-    }
-
-    const sessionName = `audit-${options.audit}-${options.traceId.slice(0, 8)}`;
-    const sessions = [];
-    const config = getUltradeepConfig();
-    const staggerMs =
-      ((options.stagger != null ? options.stagger : config.stagger_seconds) || 0) * 1000;
-
-    for (let i = 0; i < partitions.length; i++) {
-      if (i > 0 && staggerMs > 0) await sleep(staggerMs);
-
-      const partition = partitions[i];
-      const slug = partitionSlug(partition);
-      const windowName = `${auditType.prefix}:${slug}`;
-      const model = resolveModel(options.model, 'haiku');
-      const prompt = buildExtremePrompt(
-        partition,
-        result.analyzers,
-        options.traceId,
-        sentinelDir,
-        options.audit,
-        model
-      );
-      const escapedPrompt = prompt.replace(/'/g, "'\\''");
-
-      try {
-        if (i === 0) {
-          execFileSync(
-            'tmux',
-            ['new-session', '-d', '-s', sessionName, '-n', windowName, '-c', rootDir],
-            { stdio: 'pipe' }
-          );
-        } else {
-          execFileSync('tmux', ['new-window', '-t', sessionName, '-n', windowName, '-c', rootDir], {
-            stdio: 'pipe',
-          });
-        }
-
-        execFileSync(
-          'tmux',
-          ['set-option', '-w', '-t', `${sessionName}:${windowName}`, '@group_color', groupColor],
-          { stdio: 'pipe' }
-        );
-
-        const claudeCmd = `echo '${escapedPrompt}' | claude --model ${model} --allowedTools 'Read Glob Grep Write Agent' 2>&1; echo "AUDIT_COMPLETE: ${slug}"`;
-        execFileSync(
-          'tmux',
-          ['send-keys', '-t', `${sessionName}:${windowName}`, claudeCmd, 'Enter'],
-          {
-            stdio: 'pipe',
-          }
-        );
-
-        sessions.push(windowName);
-      } catch (err) {
-        console.error(`Failed to spawn ${windowName}: ${err.message}`);
-      }
-    }
-
-    // Apply status bar theme
-    try {
-      const tmuxScript = path.join(__dirname, 'claude-tmux.sh');
-      execFileSync(tmuxScript, [`--configure-session=${sessionName}`], { stdio: 'pipe' });
-    } catch (_) {
-      // Non-critical
-    }
-
-    log(`\nSpawned ${sessions.length} partition coordinators in tmux session: ${sessionName}`);
-    log(`  Partitions: ${partitions.join(', ')}`);
-    log(`  Analyzers per partition: ${result.analyzers.length}`);
-    log(`  Total agent sessions: ${totalSessions}`);
-    log(`Sentinel dir: ${sentinelDir}`);
-    log(`Attach with: tmux attach -t ${sessionName}`);
-
-    return {
-      ok: true,
-      traceId: options.traceId,
-      sentinelDir,
-      sessions,
-      sessionName,
-      mode: 'extreme',
-      partitions,
-    };
-  }
-
-  // --- ULTRADEEP MODE (existing behavior) ---
-
-  // Enforce session limit
-  if (result.analyzers.length > 20) {
-    console.error(`Too many analyzers (${result.analyzers.length}). Maximum is 20.`);
-    process.exit(1);
-  }
-
-  // Resolve stagger and concurrency from CLI flags or config
-  const config = getUltradeepConfig();
-  const staggerMs =
-    ((options.stagger != null ? options.stagger : config.stagger_seconds) || 0) * 1000;
-  const maxConcurrent = options.concurrency != null ? options.concurrency : config.max_concurrent;
-
-  writeStatusFile(sentinelDir, options.audit, result.analyzers, staggerMs, maxConcurrent, {
-    target: options.target,
-    model: options.model,
-    timeout_minutes: options.timeout,
-  });
-
-  const groupColor = getColorForAudit(options.audit);
-  const sessions = [];
-
-  if (options.dryRun) {
-    log(`\nDry run - would spawn ${result.analyzers.length} sessions:`);
-    log(`  Stagger: ${staggerMs / 1000}s between launches`);
-    if (maxConcurrent > 0) {
-      const waveCount = Math.ceil(result.analyzers.length / maxConcurrent);
-      log(`  Concurrency: ${maxConcurrent}/wave (${waveCount} waves)`);
-    }
-    for (const analyzer of result.analyzers) {
-      const model = resolveModel(options.model, 'haiku');
-      log(`  ${auditType.prefix}:${analyzer.key} (${model}) → ${analyzer.label}`);
-    }
-    log(`\nSentinel dir: ${sentinelDir}`);
-    log(`Group color: ${groupColor}`);
-    return { ok: true, traceId: options.traceId, sentinelDir, sessions: [], dryRun: true };
-  }
-
-  const tmux = checkTmux();
-  if (!tmux.available) {
-    console.error('tmux is not available. ULTRADEEP mode requires tmux.');
-    console.error('Falling back to DEPTH=deep mode.');
-    return { ok: false, traceId: options.traceId, sentinelDir, sessions: [], fallback: 'deep' };
-  }
-
-  // Create dedicated tmux session for this audit
-  const sessionName = `audit-${options.audit}-${options.traceId.slice(0, 8)}`;
-  let sessionIndex = 0;
-
-  if (maxConcurrent > 0 && result.analyzers.length > maxConcurrent) {
-    // Wave-based spawning
-    const waves = [];
-    for (let i = 0; i < result.analyzers.length; i += maxConcurrent) {
-      waves.push(result.analyzers.slice(i, i + maxConcurrent));
-    }
-    for (let w = 0; w < waves.length; w++) {
-      if (w > 0) {
-        const prevKeys = waves[w - 1].map(a => a.key);
-        await pollWaveCompletion(sentinelDir, prevKeys, options.timeout);
-      }
-      for (let i = 0; i < waves[w].length; i++) {
-        if (sessionIndex > 0 && staggerMs > 0) await sleep(staggerMs);
-        const name = spawnOneSession({
-          analyzer: waves[w][i],
-          index: sessionIndex,
-          sessionName,
-          rootDir,
-          options,
-          sentinelDir,
-          auditType,
-          groupColor,
-        });
-        if (name) sessions.push(name);
-        sessionIndex++;
-      }
-    }
-  } else {
-    // Simple staggered spawning (no wave limit)
-    for (let i = 0; i < result.analyzers.length; i++) {
-      if (i > 0 && staggerMs > 0) await sleep(staggerMs);
-      const name = spawnOneSession({
-        analyzer: result.analyzers[i],
-        index: i,
-        sessionName,
-        rootDir,
-        options,
-        sentinelDir,
-        auditType,
-        groupColor,
-      });
-      if (name) sessions.push(name);
-    }
-  }
-
-  // Apply the same status bar theme as normal Claude sessions
-  try {
-    const tmuxScript = path.join(__dirname, 'claude-tmux.sh');
-    execFileSync(tmuxScript, [`--configure-session=${sessionName}`], { stdio: 'pipe' });
-  } catch (_) {
-    // Non-critical styling failure — audit session still works with default theme
-  }
-
-  log(`\nSpawned ${sessions.length} analyzer sessions in tmux session: ${sessionName}`);
-  log(`Sentinel dir: ${sentinelDir}`);
-  log(`Attach with: tmux attach -t ${sessionName}`);
-
-  return { ok: true, traceId: options.traceId, sentinelDir, sessions, sessionName };
-}
-
-/**
- * Poll sentinel directory for completion.
- * @param {string} sentinelDir - Sentinel directory path
- * @param {string[]} expected - Expected analyzer keys
- * @param {number} timeoutMinutes - Timeout in minutes
- * @returns {Promise<{ complete: boolean, results: object[], missing: string[] }>}
- */
-async function pollForCompletion(sentinelDir, expected, timeoutMinutes) {
-  const timeoutMs = timeoutMinutes * 60 * 1000;
-  const startTime = Date.now();
-  const pollIntervalMs = 5000;
-
-  while (Date.now() - startTime < timeoutMs) {
-    const completed = [];
-    const missing = [];
-
-    for (const key of expected) {
-      const findingsFile = path.join(sentinelDir, `${key}.findings.json`);
-      if (fs.existsSync(findingsFile)) {
-        completed.push(key);
-      } else {
-        missing.push(key);
-      }
-    }
-
-    // Update status file
-    try {
-      const statusPath = path.join(sentinelDir, '_status.json');
-      const status = JSON.parse(fs.readFileSync(statusPath, 'utf8'));
-      status.completed = completed;
-      status.last_checked = new Date().toISOString();
-      fs.writeFileSync(statusPath, JSON.stringify(status, null, 2) + '\n');
-    } catch (_) {
-      // Non-critical
-    }
-
-    if (missing.length === 0) {
-      return { complete: true, results: collectResults(sentinelDir, expected), missing: [] };
-    }
-
-    await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
-  }
-
-  // Timeout
-  const results = collectResults(sentinelDir, expected);
-  const completedKeys = results.map(r => r.analyzer);
-  const missing = expected.filter(k => !completedKeys.includes(k));
-  return { complete: false, results, missing };
-}
-
-/**
- * Collect all findings from sentinel directory.
- * @param {string} sentinelDir - Sentinel directory path
- * @param {string[]} expected - Expected keys. In ultradeep mode these are analyzer keys
- *   (e.g. 'injection', 'auth'). In extreme mode these are partition slugs
- *   (e.g. 'src-auth', 'src-api') — matches the `analyzers` array in `_status.json`.
- * @returns {object[]} Array of parsed findings
- */
-function collectResults(sentinelDir, expected) {
-  const results = [];
-
-  for (const key of expected) {
-    const findingsFile = path.join(sentinelDir, `${key}.findings.json`);
-    try {
-      if (fs.existsSync(findingsFile)) {
-        const data = JSON.parse(fs.readFileSync(findingsFile, 'utf8'));
-        results.push(data);
-      }
-    } catch (err) {
-      results.push({
-        analyzer: key,
-        error: `Failed to parse findings: ${err.message}`,
-        findings: [],
-      });
-    }
-  }
-
-  return results;
-}
-
-/**
- * Show cost estimation before launching.
- * @param {string} auditType - Audit type key
- * @param {number} analyzerCount - Number of analyzers to spawn
- * @param {string} [model] - Explicit model override
- * @param {object} [opts] - Options
- * @param {boolean} [opts.json] - If true, route output to stderr to keep stdout clean for JSON
- * @param {number} [opts.partitions] - Number of partitions (extreme mode)
- */
-function showCostEstimate(auditType, analyzerCount, model, opts) {
-  const resolved = resolveModel(model, 'haiku');
-  const partCount =
-    opts && typeof opts.partitions === 'number' && opts.partitions > 1 ? opts.partitions : 1;
-  const estimate = estimateCost(resolved, analyzerCount, partCount);
-  const log = opts && opts.json ? console.error : console.log;
-
-  if (partCount > 1) {
-    log(`\nCost estimate for EXTREME ${auditType} audit:`);
-    log(`  Model: ${estimate.model}`);
-    log(`  Partitions: ${partCount}`);
-    log(`  Analyzers per partition: ${analyzerCount}`);
-    log(`  Total agent sessions: ${estimate.totalSessions}`);
-    log(`  Per-agent estimate: ${estimate.perAnalyzerCost}`);
-    log(`  Total estimate: ${estimate.totalEstimate}`);
-  } else {
-    log(`\nCost estimate for ULTRADEEP ${auditType} audit:`);
-    log(`  Model: ${estimate.model}`);
-    log(`  Analyzers: ${analyzerCount}`);
-    log(`  Cost multiplier vs haiku: ${estimate.multiplier}x`);
-    log(`  Per-analyzer estimate: ${estimate.perAnalyzerCost}`);
-    log(`  Total estimate: ${estimate.totalEstimate}`);
-    log(`  Each analyzer runs as a full Claude Code session`);
-  }
-}
-
-// Main
-if (require.main === module) {
-  (async () => {
-    const options = parseArgs();
-
-    if (!options.audit) {
-      console.error(
-        'Usage: node spawn-audit-sessions.js --audit=TYPE --target=PATH [--focus=AREAS] [--model=MODEL] [--trace-id=ID] [--stagger=SECONDS] [--concurrency=N]'
-      );
-      console.error('Types: logic, security, performance, test, completeness, legal');
-      process.exit(1);
-    }
-
-    const isExtreme = options.depth === 'extreme';
-    const depthForCost = isExtreme ? 'extreme' : 'ultradeep';
-    const result = getAnalyzersForAudit(options.audit, depthForCost, options.focus);
-    if (result) {
-      showCostEstimate(options.audit, result.analyzers.length, options.model, {
-        json: options.json,
-        partitions: isExtreme && options.partitions ? options.partitions.length : 1,
-      });
-    }
-
-    const spawnResult = await spawnAuditInTmux(options);
-
-    if (options.json) {
-      const jsonOut = {
-        ok: spawnResult.ok,
-        traceId: spawnResult.traceId,
-        sentinelDir: spawnResult.sentinelDir,
-        sessionName: spawnResult.sessionName || null,
-        sessions: spawnResult.sessions,
-        dryRun: spawnResult.dryRun || false,
-        fallback: spawnResult.fallback || null,
-        mode: spawnResult.mode || 'ultradeep',
-        partitions: spawnResult.partitions || null,
-      };
-      console.log(JSON.stringify(jsonOut));
-    }
-
-    if (!spawnResult.ok && spawnResult.fallback) {
-      process.exit(2); // Signal fallback to caller
-    }
-  })().catch(err => {
-    console.error(err.message);
-    process.exit(1);
-  });
-}
-
-module.exports = {
-  parseArgs,
-  checkTmux,
-  createSentinelDir,
-  writeStatusFile,
-  buildAnalyzerPrompt,
-  buildExtremePrompt,
-  partitionSlug,
-  spawnOneSession,
-  spawnAuditInTmux,
-  pollForCompletion,
-  pollWaveCompletion,
-  collectResults,
-  showCostEstimate,
-  getUltradeepConfig,
-  sleep,
-};