ai-control-center 1.15.2

package/lib/utils/spinner.js

@@ -0,0 +1,132 @@
+/**
+ * Global spinner singleton — single-width braille frames work everywhere.
+ * Usage:
+ *   spinner.start('Gemini  ·  Analyzing code...');
+ *   spinner.update('Gemini  ·  Writing review...');
+ *   spinner.succeed('Review complete');   // stops + prints ✓
+ *   spinner.fail('Review failed');        // stops + prints ✗
+ *
+ * Automatically pauses before console.log() calls (via pause/resume) so
+ * spinner line never mixes with log output.
+ */
+import chalk from 'chalk';
+
+// Braille spinner — each char is 1 terminal column wide (safe in all terminals)
+const FRAMES   = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const INTERVAL = 80;
+
+let _timer   = null;
+let _label   = '';
+let _color   = 'cyan';
+let _frame   = 0;
+let _active  = false;
+
+function draw() {
+  if (!_active) return;
+  const f = chalk[_color](FRAMES[_frame % FRAMES.length]);
+  process.stdout.write(`\r  ${f}  ${_label}  `); // trailing spaces overwrite old content
+  _frame++;
+}
+
+function clearLine() {
+  process.stdout.write('\r\x1b[K'); // carriage-return + erase to end-of-line
+}
+
+function stopTimer() {
+  if (_timer) { clearInterval(_timer); _timer = null; }
+}
+
+export const spinner = {
+
+  get active() { return _active; },
+
+  /** Start spinning with a label. */
+  start(label, color = 'cyan') {
+    _label  = label;
+    _color  = color;
+    _frame  = 0;
+    _active = true;
+    stopTimer();
+    _timer = setInterval(draw, INTERVAL);
+    draw();
+    return this;
+  },
+
+  /** Change the label while spinning — takes effect on next frame. */
+  update(label) {
+    _label = label;
+    return this;
+  },
+
+  /**
+   * Pause the spinner and clear the line (before printing a log line).
+   * Call resume() after the line is printed.
+   */
+  pause() {
+    stopTimer();
+    clearLine();
+  },
+
+  /** Resume spinning after a log line was printed. */
+  resume() {
+    if (!_active) return;
+    if (_timer) return;
+    _timer = setInterval(draw, INTERVAL);
+    draw();
+  },
+
+  /** Stop spinning silently (no output). */
+  stop() {
+    stopTimer();
+    clearLine();
+    _active = false;
+  },
+
+  /** Stop and print a green success line. */
+  succeed(msg) {
+    stopTimer();
+    clearLine();
+    _active = false;
+    if (msg) process.stdout.write(chalk.green(`  ✓  ${msg}\n`));
+  },
+
+  /** Stop and print a red failure line. */
+  fail(msg) {
+    stopTimer();
+    clearLine();
+    _active = false;
+    if (msg) process.stdout.write(chalk.red(`  ✗  ${msg}\n`));
+  },
+
+  /** Stop and print a yellow warning line. */
+  warn(msg) {
+    stopTimer();
+    clearLine();
+    _active = false;
+    if (msg) process.stdout.write(chalk.yellow(`  ~  ${msg}\n`));
+  },
+};
+
+/**
+ * Cycle through a list of progress messages on the spinner while an async
+ * task runs.  Returns a cleanup function — call it after await completes.
+ *
+ * Example:
+ *   const stopCycle = spinCycle('GEMINI', [
+ *     'Reading feature request...',
+ *     'Writing user stories...',
+ *     'Identifying risks...',
+ *   ]);
+ *   await runGemini(...);
+ *   stopCycle();
+ *   spinner.succeed('PM spec written');
+ */
+export function spinCycle(aiLabel, messages, intervalMs = 4000, color = 'cyan') {
+  let i = 0;
+  spinner.start(`${aiLabel}  ·  ${messages[0]}`, color);
+  const t = setInterval(() => {
+    i = (i + 1) % messages.length;
+    spinner.update(`${aiLabel}  ·  ${messages[i]}`);
+  }, intervalMs);
+  return () => clearInterval(t);
+}

package/lib/utils/stage-queue.js

@@ -0,0 +1,50 @@
+/**
+ * Stage Queue — buffers incoming requests when pipeline is busy.
+ *
+ * File: .ai-workflow/stage-queue.json
+ * Format: [{ type, data, queuedAt }]
+ * Max size: 10 (oldest dropped)
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { getWorkflowDir, atomicWriteSync } from './pipeline.js';
+
+const QUEUE_FILE = () => resolve(getWorkflowDir(), 'stage-queue.json');
+const MAX_QUEUE = 10;
+
+export function enqueue(item) {
+  const file = QUEUE_FILE();
+  let queue = [];
+  if (existsSync(file)) {
+    try { queue = JSON.parse(readFileSync(file, 'utf8')); } catch { queue = []; }
+  }
+
+  queue.push({ ...item, queuedAt: new Date().toISOString() });
+
+  // Drop oldest if over limit
+  if (queue.length > MAX_QUEUE) {
+    queue = queue.slice(queue.length - MAX_QUEUE);
+  }
+
+  atomicWriteSync(file, JSON.stringify(queue, null, 2));
+}
+
+export function dequeue() {
+  const file = QUEUE_FILE();
+  if (!existsSync(file)) return null;
+
+  let queue = [];
+  try { queue = JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
+  if (queue.length === 0) return null;
+
+  const item = queue.shift();
+  atomicWriteSync(file, JSON.stringify(queue, null, 2));
+  return item;
+}
+
+export function peekQueue() {
+  const file = QUEUE_FILE();
+  if (!existsSync(file)) return [];
+  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return []; }
+}

package/lib/utils/state-machine.js

@@ -0,0 +1,89 @@
+/**
+ * State Machine — enforces valid pipeline transitions.
+ * Every updateStatus() call MUST go through validateTransition().
+ *
+ * This is the single source of truth for all pipeline state transitions.
+ * No ad-hoc states allowed.
+ */
+
+import { getStatus, updateStatus } from './pipeline.js';
+import { logActivity } from './activity-log.js';
+
+export const VALID_TRANSITIONS = {
+  'idle':            ['assign', 'suggestion', 'browser-qa'],
+  'assign':          ['browser-qa', 'spec', 'arch'],
+  'browser-qa':      ['triage', 'spec', 'deploy-verify', 'idle'],
+  'triage':          ['bugfix', 'spec', 'escalate'],
+  'bugfix':          ['re-qa', 'escalate'],
+  're-qa':           ['spec', 'bugfix', 'escalate', 'idle', 'deploy-verify'],
+  'spec':            ['arch'],
+  'arch':            ['impl'],
+  'impl':            ['review', 'browser-qa'],
+  'review':          ['deploy', 'impl'],           // approved → deploy, rejected → impl
+  'deploy':          ['deploy-verify'],
+  'deploy-verify':   ['idle', 'bugfix'],            // post-deploy QA
+  'escalate':        ['manual_hold', 'bugfix', 'idle'],
+  'manual_hold':     ['bugfix', 'idle', 'spec'],    // CEO decides
+  'suggestion':      ['idle', 'spec'],              // CEO picks suggestion → spec
+};
+
+export const TERMINAL_STATES = ['idle', 'manual_hold'];
+
+/**
+ * Every status.json MUST conform to this shape.
+ * Validate on every read/write.
+ */
+export const STATUS_SCHEMA = {
+  stage:           'string',   // one of VALID_TRANSITIONS keys
+  previousStage:   'string',
+  featureId:       'string|null',
+  assignedUrl:     'string|null',    // target website URL (from /assign)
+  assignedGoal:    'string|null',    // project goal text
+  transitionedAt:  'string',         // ISO timestamp
+  pipelineStarted: 'string|null',    // ISO timestamp of pipeline start
+  currentCycle:    'number',         // bugfix cycle counter (0 = no bugfix)
+  maxCycles:       'number',         // from config, default 3
+  qa_pass_rate:    'number|null',    // last QA pass rate %
+  qa_last_run:     'string|null',    // ISO timestamp
+  error:           'string|null',    // last error message (cleared on success)
+  escalation:      'object|null',    // { reason, failedStage, cycles, timestamp }
+};
+
+/**
+ * Validate a state transition. Throws if invalid.
+ */
+export function validateTransition(currentState, nextState) {
+  const allowed = VALID_TRANSITIONS[currentState];
+  if (!allowed) {
+    throw new Error(`Unknown state: "${currentState}". Valid states: ${Object.keys(VALID_TRANSITIONS).join(', ')}`);
+  }
+  if (!allowed.includes(nextState)) {
+    throw new Error(
+      `Invalid transition: "${currentState}" → "${nextState}". ` +
+      `Allowed from "${currentState}": [${allowed.join(', ')}]`
+    );
+  }
+  return true;
+}
+
+/**
+ * Wrap updateStatus to enforce state machine.
+ * Replace direct updateStatus() calls with this.
+ */
+export function transitionTo(nextState, metadata = {}) {
+  const current = getStatus();
+  const currentStage = current.stage || 'idle';
+
+  validateTransition(currentStage, nextState);
+
+  updateStatus({
+    stage: nextState,
+    previousStage: currentStage,
+    transitionedAt: new Date().toISOString(),
+    ...metadata,
+  });
+
+  logActivity('PIPELINE', `${currentStage} → ${nextState}`, 'info');
+
+  return { from: currentStage, to: nextState };
+}

package/lib/utils/status-bar.js

@@ -0,0 +1,327 @@
+/**
+ * Persistent 2-line bottom status bar — inspired by Claude Code's UI.
+ *
+ * Row N-1  (agent row)  — active AI agent · current task · elapsed time · tokens
+ * Row N    (info row)   — pipeline stage · feature · session log path · model
+ *
+ * Uses ANSI scroll-region to reserve the last 2 terminal rows so normal
+ * console.log output scrolls without overwriting the bar.
+ *
+ * Usage:
+ *   statusBar.install(inquirer)    ← once at startup; patches inquirer to auto-pause
+ *   statusBar.reinstall()          ← call after console.clear() in printHeader()
+ *   statusBar.set('GEMINI', 'Analyzing errors...', estimatedTokens)
+ *   statusBar.setLastEvent('COPILOT', 'All fixes applied')
+ *   statusBar.clear()              ← task finished
+ */
+import chalk from 'chalk';
+import { getStatus } from './pipeline.js';
+
+// ─── Guard: no-op when stdout is not a real terminal ─────────────────────────
+
+const IS_TTY = !!process.stdout.isTTY;
+
+// ─── State ────────────────────────────────────────────────────────────────────
+
+let _installed     = false;
+let _paused        = false;
+let _timer         = null;
+let _agent         = null;    // 'GEMINI' | 'CLAUDE' | 'COPILOT' | null
+let _task          = '';
+let _startTime     = null;
+let _sessionTokens = 0;       // accumulated estimated input tokens this session
+let _lastEvent     = '';      // last milestone activity line (shown in info row)
+let _logFile       = null;    // current session log path (set from activity-log)
+let _model         = '';      // active model string (e.g. 'haiku-4.5')
+let _prevRows      = 0;       // last known terminal height — used to erase old bar on resize
+
+// ─── Terminal primitives ──────────────────────────────────────────────────────
+
+const write   = s  => IS_TTY && process.stdout.write(s);
+const rows    = () => (IS_TTY && process.stdout.rows)    || 24;
+const cols    = () => (IS_TTY && process.stdout.columns) || 80;
+const save    = () => write('\x1b7');
+const restore = () => write('\x1b8');
+const goTo    = (r, c) => write(`\x1b[${r};${c}H`);
+const clrLine = () => write('\x1b[2K');
+
+const BAR_ROWS = 2; // number of rows reserved at the bottom
+
+function setScrollRegion(top, bottom) {
+  write(`\x1b[${top};${bottom}r`);
+}
+
+// ─── Agent colour map ─────────────────────────────────────────────────────────
+
+const AGENT_COLOR = { GEMINI: 'cyan', CLAUDE: 'magenta', COPILOT: 'blue', PIPELINE: 'yellow' };
+
+// ─── Elapsed time formatter ───────────────────────────────────────────────────
+
+function fmtElapsed(startMs) {
+  const s = Math.floor((Date.now() - startMs) / 1000);
+  const m = Math.floor(s / 60);
+  return m > 0 ? `${m}m ${(s % 60).toString().padStart(2, '0')}s` : `${s}s`;
+}
+
+// ─── Truncate to fit within N visible chars ───────────────────────────────────
+
+function fit(str, maxLen) {
+  if (!str) return '';
+  return str.length > maxLen ? str.slice(0, maxLen - 1) + '…' : str;
+}
+
+// ─── Draw both rows ───────────────────────────────────────────────────────────
+
+function draw() {
+  if (!IS_TTY || !_installed || _paused) return;
+
+  const r = rows();
+  const c = cols();
+
+  save();
+
+  // ── Erase old bar rows when terminal is resized ───────────────────────────
+  // If rows() changed (terminal grew or shrank), the old bar content is still
+  // painted at the old physical rows. Erase those rows before drawing the new
+  // bar so no duplicate/ghost lines are left behind.
+  if (_prevRows > 0 && _prevRows !== r) {
+    goTo(_prevRows - 1, 1); clrLine();
+    goTo(_prevRows,     1); clrLine();
+  }
+  _prevRows = r;
+
+  // ── Row N-1: Agent activity row ───────────────────────────────────────────
+  const agentRow = r - 1;
+  goTo(agentRow, 1);
+  clrLine();
+
+  let agentLine;
+  if (_agent) {
+    const aColor  = AGENT_COLOR[_agent] || 'white';
+    const elapsed = _startTime ? fmtElapsed(_startTime) : '0s';
+
+    // Build right side first (fixed width) — elapsed + tokens + model
+    // Right side is always visible; task gets whatever space remains.
+    const tokPlain  = _sessionTokens > 0
+      ? `  ~${(_sessionTokens / 1000).toFixed(1)}k tok`
+      : '';
+    const modelPlain = _model ? `  [${_model}]` : '';
+    const rightPlain = `  ${elapsed}${tokPlain}${modelPlain} `;
+    const rightLen   = rightPlain.length;
+
+    // Left: " AGENT  ·  " prefix (fixed) + task (fills remaining space)
+    const prefixPlain = ` ${_agent}  ·  `;
+    const taskLen  = Math.max(6, c - prefixPlain.length - rightLen);
+    const task     = fit(_task, taskLen);
+
+    agentLine = chalk.bgBlack(
+      ` ${chalk[aColor].bold(_agent)}` +
+      chalk.dim('  ·  ') +
+      chalk.white(task) +
+      chalk.dim(`  ${elapsed}`) +
+      chalk.dim(tokPlain) +
+      chalk.dim(modelPlain) +
+      ' '
+    );
+  } else {
+    // Idle agent row: show "ready" hint + session token total
+    const tokPlain = _sessionTokens > 0
+      ? `  session ~${(_sessionTokens / 1000).toFixed(1)}k tok`
+      : '';
+    const idlePlain = ` ready  ·  select an action${tokPlain}`;
+    const pad = Math.max(0, c - idlePlain.length - 1);
+    agentLine = chalk.bgBlack(chalk.dim(idlePlain) + ' '.repeat(pad) + ' ');
+  }
+  process.stdout.write(agentLine);
+
+  // ── Row N: Info row — pipeline + feature + log file ───────────────────────
+  const infoRow = r;
+  goTo(infoRow, 1);
+  clrLine();
+
+  const st           = getStatus();
+  const stage        = st.stage            || 'idle';
+  const feature      = st.current_feature  || '—';
+  const pipelineMode = st.pipeline_mode;
+
+  // Left: stage + feature + mode badge
+  const stageColour = {
+    idle: 'dim', approved: 'green', review_complete: 'green',
+    rejected: 'red', arch_complete: 'blue', implementation_complete: 'magenta',
+  }[stage] || 'yellow';
+
+  const modeStr      = pipelineMode === 'auto' ? '  ·  auto' : '';
+  const modePlain    = modeStr.length;
+
+  const leftParts = [
+    chalk[stageColour](` ${stage}`),
+    chalk.dim('  ·  '),
+    chalk.dim(fit(feature, 28)),
+    pipelineMode === 'auto'
+      ? chalk.dim('  ·  ') + chalk.cyan('auto')
+      : '',
+  ];
+  const leftStr = leftParts.join('');
+
+  // Right: last event + log file shortname
+  const logShort = _logFile
+    ? chalk.dim('  log:' + _logFile.split('/').pop())
+    : '';
+  const lastEvt = _lastEvent
+    ? chalk.dim(`  ${fit(_lastEvent, 38)}`)
+    : '';
+
+  // Plain lengths for padding
+  const leftPlain  = ` ${stage}  ·  ${fit(feature, 28)}`.length + modePlain;
+  const rightPlain = (_lastEvent ? fit(_lastEvent, 38).length + 2 : 0) +
+                     (_logFile   ? _logFile.split('/').pop().length + 6 : 0);
+  const pad = Math.max(0, c - leftPlain - rightPlain - 1);
+
+  const infoLine = chalk.bgBlack(
+    leftStr +
+    ' '.repeat(pad) +
+    lastEvt +
+    logShort +
+    ' '
+  );
+  process.stdout.write(infoLine);
+
+  restore();
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export const statusBar = {
+
+  get installed()     { return _installed; },
+  get sessionTokens() { return _sessionTokens; },
+
+  /**
+   * Call once at startup.
+   * Pass the inquirer instance to auto-pause during every prompt.
+   */
+  install(inquirerInstance) {
+    if (!IS_TTY || _installed) return;
+    _installed = true;
+
+    setScrollRegion(1, rows() - BAR_ROWS);
+
+    // Re-apply scroll region + redraw on terminal resize.
+    // draw() erases old bar rows first (via _prevRows check) so no ghost lines remain.
+    process.stdout.on('resize', () => {
+      setScrollRegion(1, rows() - BAR_ROWS);
+      draw();
+    });
+
+    // 1-second redraw drives the elapsed timer
+    _timer = setInterval(draw, 1000);
+    draw();
+
+    // Restore terminal on exit
+    const cleanup = () => {
+      if (_timer) clearInterval(_timer);
+      setScrollRegion(1, rows());   // restore full scroll region
+      // Clear both bar rows
+      save();
+      goTo(rows() - 1, 1); clrLine();
+      goTo(rows(), 1);     clrLine();
+      restore();
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+
+    // Auto-pause during every inquirer.prompt() call
+    if (inquirerInstance) {
+      const _orig = inquirerInstance.prompt.bind(inquirerInstance);
+      inquirerInstance.prompt = async (...args) => {
+        statusBar.pause();
+        try {
+          return await _orig(...args);
+        } finally {
+          statusBar.resume();
+        }
+      };
+    }
+  },
+
+  /**
+   * Re-apply scroll region + redraw after console.clear() in printHeader().
+   */
+  reinstall() {
+    if (!IS_TTY || !_installed) return;
+    setScrollRegion(1, rows() - BAR_ROWS);
+    draw();
+  },
+
+  /**
+   * Set active AI agent.
+   * @param {string} agent            'GEMINI' | 'CLAUDE' | 'COPILOT'
+   * @param {string} task             Short description shown in agent row
+   * @param {number} estimatedTokens  Rough input token count (chars / 4)
+   */
+  set(agent, task, estimatedTokens = 0) {
+    _agent          = agent;
+    _task           = (task || '').replace(/\n/g, ' ').trim();
+    _startTime      = Date.now();
+    _sessionTokens += estimatedTokens;
+    // Derive model hint — respect GEMINI_MODEL env var when set
+    const geminiModel = process.env.GEMINI_MODEL || 'gemini-2.5-pro';
+    _model = agent === 'COPILOT' ? 'copilot'
+           : agent === 'GEMINI'  ? geminiModel
+           : agent === 'CLAUDE'  ? 'claude-sonnet-4-6'
+           : '';
+    draw();
+  },
+
+  /** Mark current task as done. Agent row returns to idle. */
+  clear() {
+    _agent     = null;
+    _task      = '';
+    _startTime = null;
+    _model     = '';
+    draw();
+  },
+
+  /**
+   * Update the last milestone event shown in the info row.
+   * Call from logActivity() so the bar always reflects the latest event.
+   */
+  setLastEvent(ai, message) {
+    const prefix = ai ? `${ai}: ` : '';
+    _lastEvent = prefix + message;
+    draw();
+  },
+
+  /** Set the session log file path for display in the info row. */
+  setLogFile(path) {
+    _logFile = path;
+    draw();
+  },
+
+  /** Reset the session token counter (e.g. start of a new feature). */
+  resetTokens() {
+    _sessionTokens = 0;
+    draw();
+  },
+
+  /**
+   * Pause the bar and clear both bar rows.
+   * Call before anything that writes to the terminal.
+   */
+  pause() {
+    if (!IS_TTY || !_installed) return;
+    _paused = true;
+    save();
+    goTo(rows() - 1, 1); clrLine();
+    goTo(rows(), 1);     clrLine();
+    restore();
+  },
+
+  /** Resume drawing after a pause. */
+  resume() {
+    if (!IS_TTY || !_installed) return;
+    _paused = false;
+    draw();
+  },
+};

package/lib/utils/token-estimator.js

@@ -0,0 +1,101 @@
+/**
+ * Pre-flight Token Estimation.
+ *
+ * Provides heuristic token counts, cost estimates, and budget checks
+ * before sending prompts to AI models.
+ */
+
+import { bus } from '../shared/event-bus.js';
+
+/** Per-1K-token pricing for supported models. */
+const PRICING = {
+  'gemini-2.5-pro':    { input: 0.00125, output: 0.005   },
+  'claude-sonnet-4.6': { input: 0.003,   output: 0.015   },
+  'claude-haiku-4.5':  { input: 0.0008,  output: 0.004   },
+  'copilot':           { input: 0,       output: 0       },
+};
+
+/**
+ * Estimate token count from raw text.
+ *
+ * Heuristics:
+ *   English prose  ≈ 1 token per 0.75 words
+ *   Code           ≈ 1 token per 0.50 words
+ *
+ * We detect code-heavy text by the ratio of non-alpha characters.
+ */
+export function estimateTokens(text) {
+  if (!text) return { tokens: 0, words: 0, chars: 0 };
+
+  const chars = text.length;
+  const words = text.split(/\s+/).filter(Boolean).length;
+
+  const nonAlpha = (text.match(/[^a-zA-Z\s]/g) || []).length;
+  const codeRatio = chars > 0 ? nonAlpha / chars : 0;
+  const wordsPerToken = codeRatio > 0.3 ? 0.5 : 0.75;
+
+  const tokens = Math.ceil(words / wordsPerToken);
+
+  return { tokens, words, chars };
+}
+
+/**
+ * Estimate cost for a given token count and model.
+ *
+ * @returns {{ inputCost: number, outputCost: number, totalCost: number, model: string }}
+ */
+export function estimateCost(tokens, model) {
+  const pricing = PRICING[model] || PRICING['copilot'];
+  const inputCost  = (tokens / 1000) * pricing.input;
+  const outputCost = (tokens / 1000) * pricing.output;
+
+  return {
+    inputCost:  Math.round(inputCost  * 1_000_000) / 1_000_000,
+    outputCost: Math.round(outputCost * 1_000_000) / 1_000_000,
+    totalCost:  Math.round((inputCost + outputCost) * 1_000_000) / 1_000_000,
+    model,
+  };
+}
+
+/**
+ * Check whether estimated tokens exceed a budget threshold.
+ * Emits a 'budget:warning' event via the shared bus when usage > 80 %.
+ *
+ * @param {string} prompt  – the text to estimate
+ * @param {string} stage   – pipeline stage name
+ * @param {number} budget  – maximum allowed tokens
+ * @returns {{ ok: boolean, estimated: number, budget: number, percentUsed: number, warning: string|null }}
+ */
+export function checkBudget(prompt, stage, budget) {
+  const { tokens: estimated } = estimateTokens(prompt);
+  const percentUsed = budget > 0 ? Math.round((estimated / budget) * 100) : 0;
+  let warning = null;
+
+  if (percentUsed > 100) {
+    warning = `Token budget exceeded for "${stage}": ${estimated}/${budget} (${percentUsed}%)`;
+  } else if (percentUsed > 80) {
+    warning = `Approaching token budget for "${stage}": ${estimated}/${budget} (${percentUsed}%)`;
+  }
+
+  if (warning) {
+    bus.emit('budget:warning', { stage, estimated, budget, percentUsed, warning });
+  }
+
+  return {
+    ok: percentUsed <= 100,
+    estimated,
+    budget,
+    percentUsed,
+    warning,
+  };
+}
+
+/**
+ * Format a token estimate as a human-readable string.
+ */
+export function formatEstimate(estimate) {
+  if (!estimate) return 'No estimate available';
+
+  const { tokens, words, chars } = estimate;
+  return `~${tokens.toLocaleString()} tokens (${words.toLocaleString()} words, ${chars.toLocaleString()} chars)`;
+}