@aitherium/shell-cli 1.1.0

package/dist/renderer.js

@@ -0,0 +1,1812 @@
+/**
+ * Terminal renderer — banners, streaming tokens, markdown, tables.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import { marked } from 'marked';
+import { markedTerminal } from 'marked-terminal';
+import { writeFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+// Configure marked for terminal rendering
+marked.use(markedTerminal({ reflowText: true, width: 80 }));
+/* ── Banner ─────────────────────────────────────────────────── */
+export function renderBanner(info) {
+    const version = 'v1.1.0';
+    const title = `AitherShell ${version}`;
+    let connected;
+    if (info.genesisOnline === true) {
+        const label = info.backendName || (info.backendType === 'adk' ? 'agent' : 'Genesis');
+        connected = `Connected to ${label} (${info.genesis})`;
+    }
+    else {
+        connected = `Offline (${info.genesis})`;
+    }
+    // Build service status line from direct probes
+    const probed = info.serviceLines || [];
+    const upNames = probed.filter(s => s.up).map(s => s.name);
+    const downNames = probed.filter(s => !s.up).map(s => s.name);
+    const upCount = upNames.length;
+    const parts = [
+        info.services != null ? `${info.services} services` : (upCount > 0 ? `${upCount} services` : null),
+        info.agents != null ? `${info.agents} agents` : null,
+        info.llm ? info.llm : null,
+    ].filter(Boolean);
+    const stats = parts.join(' \u00b7 ') || 'no services detected';
+    const userLine = info.user ? `Logged in as ${info.user}` : '';
+    // Build the service detail lines: "up: vLLM, ComfyUI, ..."  "down: Watch, ..."
+    const detailLines = [];
+    if (upNames.length > 0)
+        detailLines.push(`UP: ${upNames.join(', ')}`);
+    if (downNames.length > 0)
+        detailLines.push(`DN: ${downNames.join(', ')}`);
+    const allLines = [connected, stats, ...detailLines, userLine].filter(Boolean);
+    const contentWidth = Math.max(...allLines.map(l => l.length));
+    const inner = contentWidth + 2; // 1 space padding each side
+    const titleBar = `\u2500 ${title} `;
+    const topPad = Math.max(0, inner - titleBar.length);
+    const border = chalk.cyan;
+    const pad = (raw, colored) => {
+        const display = colored || raw;
+        const gap = Math.max(0, contentWidth - raw.length);
+        return border(`  \u2502`) + ` ${display}${' '.repeat(gap)} ` + border(`\u2502`);
+    };
+    console.log();
+    console.log(border(`  \u256d${titleBar}${'\u2500'.repeat(topPad)}\u256e`));
+    const connColored = info.genesisOnline === true ? chalk.green(connected) : chalk.red(connected);
+    console.log(pad(connected, connColored));
+    console.log(pad(stats));
+    if (upNames.length > 0) {
+        const upLine = `UP: ${upNames.join(', ')}`;
+        console.log(pad(upLine, chalk.green(upLine)));
+    }
+    if (downNames.length > 0) {
+        const dnLine = `DN: ${downNames.join(', ')}`;
+        console.log(pad(dnLine, chalk.red(dnLine)));
+    }
+    if (userLine) {
+        console.log(pad(userLine, chalk.green(userLine)));
+    }
+    console.log(border(`  \u2570${'\u2500'.repeat(inner)}\u256f`));
+    console.log();
+}
+/* ── Output cleanup ────────────────────────────────────────── */
+/** Decode HTML entities that LLMs dump from scraped web content. */
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/&#(\d+);/g, (_m, code) => String.fromCharCode(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_m, hex) => String.fromCharCode(parseInt(hex, 16)))
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#8211;/g, '–')
+        .replace(/&#8212;/g, '—')
+        .replace(/&#8216;/g, '\u2018')
+        .replace(/&#8217;/g, '\u2019')
+        .replace(/&#8220;/g, '\u201C')
+        .replace(/&#8221;/g, '\u201D')
+        .replace(/&#038;/g, '&')
+        .replace(/&#039;/g, "'");
+}
+/**
+ * Strip website navigation chrome, cookie banners, menu dumps, and other
+ * non-content noise that LLMs paste verbatim from scraped pages.
+ */
+function stripWebCruft(text) {
+    const lines = text.split('\n');
+    const cleaned = [];
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Skip lines that are mostly bullet-separated nav items (5+ bullets)
+        if ((trimmed.match(/ • /g) || []).length >= 4)
+            continue;
+        // Skip lines that are just "Primary Menu Sections" / nav headers
+        if (/^(Primary|Main|Footer|Secondary)\s+Menu/i.test(trimmed))
+            continue;
+        // Skip cookie/consent boilerplate
+        if (/^(We use cookies|Accept all|Cookie settings|Privacy Policy$)/i.test(trimmed))
+            continue;
+        // Skip lines that are just a chain of pipe-separated short items (nav)
+        if (/^(\s*\|?\s*\w[\w\s]{1,20}\s*\|){4,}/.test(trimmed))
+            continue;
+        cleaned.push(line);
+    }
+    return cleaned.join('\n');
+}
+/* ── Markdown ───────────────────────────────────────────────── */
+/**
+ * Resolve `/api/files?path=...` image references to real file paths
+ * and render as clickable OSC 8 terminal hyperlinks.
+ */
+export function resolveImagePath(relativePath) {
+    const { homedir } = require('os');
+    const { resolve } = require('path');
+    const home = homedir();
+    // Try common AitherOS paths
+    const candidates = [
+        resolve(home, 'AitherOS', relativePath),
+        resolve(home, 'AitherOS-Fresh', 'AitherOS', relativePath),
+        resolve('D:', 'AitherOS-Fresh', 'AitherOS', relativePath),
+        resolve('/app', 'AitherOS', relativePath),
+    ];
+    for (const p of candidates) {
+        try {
+            if (require('fs').existsSync(p))
+                return p;
+        }
+        catch { }
+    }
+    return resolve(relativePath);
+}
+function resolveImagePaths(text) {
+    // Match ![alt](/api/files?path=...) or ![alt](Library/...)
+    return text.replace(/!\[([^\]]*)\]\((?:\/api\/files\?path=)?([^)]+)\)/g, (_match, alt, rawPath) => {
+        // Resolve to absolute path — Library is under AitherOS/
+        let absPath = rawPath;
+        if (!rawPath.match(/^[A-Za-z]:[/\\]/) && !rawPath.startsWith('/')) {
+            // Relative path — resolve from repo root
+            const repoRoot = process.env.AITHER_ROOT || process.cwd();
+            absPath = `${repoRoot}/AitherOS/${rawPath}`.replace(/\//g, '\\');
+        }
+        const label = alt || rawPath.split(/[/\\]/).pop() || 'image';
+        const fileUrl = `file:///${absPath.replace(/\\/g, '/')}`;
+        // OSC 8 terminal hyperlink: \e]8;;url\e\\ text \e]8;;\e\\
+        const link = `\x1b]8;;${fileUrl}\x1b\\${chalk.cyan.underline(label)}\x1b]8;;\x1b\\`;
+        return `${link} ${chalk.dim(absPath)}`;
+    });
+}
+export function renderMarkdown(text) {
+    try {
+        let clean = text;
+        clean = decodeHtmlEntities(clean);
+        clean = stripWebCruft(clean);
+        clean = resolveImagePaths(clean);
+        return marked.parse(clean);
+    }
+    catch {
+        return text;
+    }
+}
+/* ── Bare Code Wrapping ────────────────────────────────────── */
+/**
+ * Detect unformatted code in text and wrap it in markdown fences.
+ * Safety net for when the LLM ignores the prompt and dumps bare code.
+ */
+function wrapBareCode(text) {
+    const lines = text.split('\n');
+    const result = [];
+    let codeBlock = [];
+    let inCode = false;
+    let inFence = false; // Track existing fenced regions to skip them
+    const CODE_PATTERNS = /^(def |class |import |from |async def |export |const |let |var |function |if __name__|@\w+|  {2,}\S)/;
+    function flushCode() {
+        if (codeBlock.length >= 3) {
+            // Guess language from content
+            const joined = codeBlock.join('\n');
+            const lang = /\b(def |import |from |async def |if __name__)/.test(joined) ? 'python'
+                : /\b(const |let |var |function |export |=>)/.test(joined) ? 'javascript'
+                    : 'text';
+            result.push('```' + lang);
+            result.push(...codeBlock);
+            result.push('```');
+        }
+        else {
+            result.push(...codeBlock);
+        }
+        codeBlock = [];
+        inCode = false;
+    }
+    for (const line of lines) {
+        const trimmed = line.trimEnd();
+        // Track fenced code blocks — pass them through untouched
+        if (trimmed.startsWith('```')) {
+            if (inCode)
+                flushCode();
+            inFence = !inFence;
+            result.push(line);
+            continue;
+        }
+        if (inFence) {
+            result.push(line);
+            continue;
+        }
+        const looksLikeCode = CODE_PATTERNS.test(trimmed) || (inCode && (trimmed === '' || /^\s{2,}\S/.test(trimmed)));
+        if (looksLikeCode) {
+            inCode = true;
+            codeBlock.push(line);
+        }
+        else {
+            if (inCode)
+                flushCode();
+            result.push(line);
+        }
+    }
+    if (inCode)
+        flushCode();
+    return result.join('\n');
+}
+/** Module-level artifact store — accumulates across prompts in one shell session. */
+let _sessionArtifacts = [];
+export function getSessionArtifacts() {
+    return [..._sessionArtifacts];
+}
+export function clearSessionArtifacts() {
+    _sessionArtifacts = [];
+}
+export function createStreamRenderer(sessionId, prompt, steeringBar) {
+    let spinner = null;
+    let content = '';
+    let hasOutput = false;
+    let isGroupChat = false; // Set when session_start has multiple agents
+    let lastThinkingContent = ''; // Track to dedup with answer event
+    let completePrinted = false; // Prevent duplicate timing lines
+    const seenToolResults = new Set(); // Dedup tool_result entries
+    let tokenStreamed = false; // Track if answer was delivered via token events
+    let tokensStarted = false; // Once true, spinner is permanently disabled for this session
+    let lastStage = ''; // Current pipeline stage — shown in heartbeat spinner
+    // ── Session trace collection ──
+    const traceEvents = [];
+    const traceToolCalls = [];
+    const traceThinking = [];
+    const traceErrors = [];
+    let traceContextSources = {};
+    let traceModel = '';
+    let traceAgent = '';
+    let traceTurns = 0;
+    let lastKnownMaxTurns = '?'; // Populated by turn_progress
+    const startedAt = new Date().toISOString();
+    const startTime = Date.now();
+    function stopSpinner() {
+        if (steeringBar?.active) {
+            steeringBar.clearStatus();
+        }
+        if (spinner) {
+            spinner.stop();
+            spinner = null;
+        }
+    }
+    /**
+     * Start or update the spinner with new text.
+     *
+     * When SteeringBar is active, status is shown INSIDE the bar (no ora).
+     * This prevents stderr (ora) from fighting stdout (bar) for cursor control.
+     *
+     * Once token streaming begins, the spinner is permanently disabled.
+     */
+    function startSpinner(text) {
+        if (tokensStarted)
+            return;
+        // When SteeringBar is active, show status in the bar — no ora
+        if (steeringBar?.active) {
+            // Kill any lingering ora instance
+            if (spinner) {
+                spinner.stop();
+                spinner = null;
+            }
+            steeringBar.setStatus(text.replace(/\x1b\[[0-9;]*m/g, '')); // strip ANSI colors
+            return;
+        }
+        if (spinner) {
+            spinner.text = text;
+            if (!spinner.isSpinning)
+                spinner.start();
+        }
+        else {
+            spinner = ora({ text, spinner: 'dots', discardStdin: false }).start();
+        }
+    }
+    function printIndentedBlock(text, indent = '     ', color = chalk.dim) {
+        stopSpinner();
+        const lines = String(text)
+            .replace(/\r\n/g, '\n')
+            .split('\n');
+        for (const line of lines) {
+            console.log(color(`${indent}${line}`));
+        }
+    }
+    /** console.log wrapper that auto-clears the spinner before writing.
+     *  Prevents spinner ANSI escape codes from mixing with event output. */
+    function log(...args) {
+        stopSpinner();
+        console.log(...args);
+    }
+    return {
+        onEvent(event) {
+            // ── Collect every event for session trace ──
+            traceEvents.push({ ...event, data: { ...event.data, _ts: Date.now() } });
+            switch (event.type) {
+                case 'session_start':
+                    if (event.data.group && Array.isArray(event.data.group) && event.data.group.length > 1) {
+                        isGroupChat = true;
+                    }
+                    if (event.data.agent)
+                        traceAgent = event.data.agent;
+                    if (event.data.model)
+                        traceModel = event.data.model;
+                    startSpinner(chalk.dim(`${event.data.agent || 'thinking'}...`));
+                    break;
+                case 'thinking': {
+                    const rawThought = event.data.thought || event.data.content || '';
+                    const turnNum = event.data.turn;
+                    const phase = event.data.phase || '';
+                    // Clean up <think> tags
+                    const clean = rawThought.replace(/<\/?think(?:ing)?>/g, '').trim();
+                    if (phase === 'streaming' && clean) {
+                        // ── LIVE chain-of-thought streaming ──
+                        // Stream reasoning tokens as they arrive, like AitherChat does
+                        stopSpinner();
+                        // Use carriage return to overwrite previous streaming line
+                        const preview = clean.split('\n').filter((l) => l.trim()).slice(-3).join(' ').slice(-200);
+                        process.stdout.write(`\r${chalk.magenta('  💭 ')}${chalk.dim(preview)}${' '.repeat(20)}`);
+                    }
+                    else if (phase === 'complete' && clean) {
+                        // ── Full reasoning block complete ──
+                        // Clear the streaming line, then print the full thought
+                        process.stdout.write('\r\x1b[2K');
+                        log(chalk.magenta('  💭 Reasoning complete:'));
+                        // Show full reasoning, wrapped nicely
+                        const lines = clean.split('\n').filter((l) => l.trim());
+                        for (const line of lines) {
+                            log(chalk.dim(`     ${line}`));
+                        }
+                        lastThinkingContent = clean;
+                        traceThinking.push(clean);
+                    }
+                    else if (turnNum != null && clean && clean !== 'thinking...' && clean.length > 5) {
+                        // ── Agentic turn thought ──
+                        stopSpinner();
+                        lastThinkingContent = clean;
+                        const turnLabel = chalk.cyan(`  [Turn ${turnNum}]`);
+                        // Show full reasoning trace, not just first line
+                        const lines = clean.split('\n').filter((l) => l.trim());
+                        for (const line of lines) {
+                            log(`${turnLabel} ${chalk.dim(line)}`);
+                        }
+                    }
+                    else if (clean.length > 10) {
+                        // Post-completion thinking block — show full chain of thought
+                        stopSpinner();
+                        lastStage = 'reasoning';
+                        const thinkLines = clean.split('\n').filter((l) => l.trim());
+                        if (thinkLines.length > 8) {
+                            log(chalk.magenta('  💭 Chain of thought:'));
+                            for (const line of thinkLines) {
+                                log(chalk.dim(`     ${line}`));
+                            }
+                        }
+                        else {
+                            for (const line of thinkLines) {
+                                log(chalk.dim(`  💭 ${line}`));
+                            }
+                        }
+                        traceThinking.push(clean);
+                    }
+                    else if (spinner) {
+                        spinner.text = chalk.dim(clean || 'thinking...');
+                    }
+                    else if (!hasOutput) {
+                        startSpinner(chalk.dim(clean || 'thinking...'));
+                    }
+                    break;
+                }
+                case 'thinking_end': {
+                    // Clear any streaming line remnant
+                    process.stdout.write('\r\x1b[2K');
+                    break;
+                }
+                case 'progress':
+                case 'status': {
+                    const msg = event.data.message || event.data.phase || event.data.status || '';
+                    const phase = event.data.phase || '';
+                    // Print ALL meaningful pipeline stages as visible lines
+                    const _printablePhases = new Set([
+                        'tool_reg_start', 'tool_reg_done', 'discovery_start',
+                        'notebook_start', 'orchestrator_start', 'runtime_start',
+                        'affect_start', 'prefire_start', 'facet_plan_start',
+                        'plan_start', 'planner_start', 'planner_done',
+                        'research_start',
+                        // IntentPlanner sub-phases
+                        'decompose_start', 'tool_match', 'critique_start',
+                        // Context assembly sub-phases
+                        'context_neurons', 'context_memory', 'context_graph',
+                        'context_affect', 'context_flux',
+                        // Tool execution phases
+                        'tool_executing',
+                    ]);
+                    if (_printablePhases.has(phase) && msg) {
+                        stopSpinner();
+                        log(chalk.dim(`  ⚙ ${msg}`));
+                        startSpinner(chalk.dim(msg));
+                    }
+                    else if (msg) {
+                        if (steeringBar?.active) {
+                            steeringBar.setStatus(msg);
+                        }
+                        else if (spinner) {
+                            spinner.text = chalk.dim(msg);
+                        }
+                    }
+                    break;
+                }
+                case 'token': {
+                    stopSpinner();
+                    tokensStarted = true; // Permanently disable spinner for this response
+                    const t = decodeHtmlEntities(event.data.t || '');
+                    content += t;
+                    process.stdout.write(t);
+                    hasOutput = true;
+                    tokenStreamed = true;
+                    break;
+                }
+                case 'message':
+                case 'answer':
+                case 'final_answer': {
+                    stopSpinner();
+                    const answer = event.data.response || event.data.answer || event.data.content || '';
+                    if (answer) {
+                        // Dedup: skip if already printed (AgentRuntime emits final_answer,
+                        // then the router emits answer with the same content)
+                        if (content && answer.trim() === content.trim()) {
+                            break;
+                        }
+                        if (!hasOutput)
+                            process.stdout.write('\n');
+                        // Group-chat: label each agent's response when multiple agents respond
+                        const answerAgent = event.data.agent || '';
+                        if (isGroupChat && answerAgent) {
+                            process.stdout.write(chalk.bold.cyan(`\n  [${answerAgent}]\n`));
+                        }
+                        content = answer;
+                        // Write answer text immediately — don't block on heavy markdown
+                        // rendering. Markdown is deferred to the 'complete' handler for
+                        // responses that contain code blocks.
+                        process.stdout.write(answer);
+                        if (!answer.endsWith('\n'))
+                            process.stdout.write('\n');
+                        hasOutput = true;
+                    }
+                    // Render interactive/display blocks in terminal
+                    const blocks = event.data.render_blocks;
+                    if (blocks && Array.isArray(blocks) && blocks.length > 0) {
+                        process.stdout.write('\n');
+                        renderTerminalBlocks(blocks);
+                    }
+                    break;
+                }
+                case 'render_blocks':
+                case 'await_input': {
+                    stopSpinner();
+                    const rblocks = event.data.render_blocks || event.data.blocks || [];
+                    if (rblocks.length > 0) {
+                        renderTerminalBlocks(rblocks);
+                    }
+                    if (event.data.prompt) {
+                        log(chalk.yellow(`\n  ⏳ ${event.data.prompt}`));
+                    }
+                    break;
+                }
+                case 'partial': {
+                    stopSpinner();
+                    const partial = event.data.content || event.data.text || '';
+                    if (partial && !hasOutput) {
+                        content = partial;
+                        process.stdout.write(partial);
+                        hasOutput = true;
+                    }
+                    break;
+                }
+                case 'tool_call': {
+                    stopSpinner();
+                    const turnLabel2 = event.data.turn != null ? chalk.cyan(`[Turn ${event.data.turn}] `) : '';
+                    const tools = event.data.tools || event.data.tool_calls || [];
+                    for (const tool of tools) {
+                        const name = tool.name || tool.function?.name || 'tool';
+                        const args = tool.args || tool.arguments;
+                        traceToolCalls.push({ name, args, timestamp: Date.now() });
+                        // Show the most useful argument (query, url, task, prompt, etc.)
+                        let argDisplay = '';
+                        if (args) {
+                            const key = args.query || args.url || args.task || args.prompt || args.path || args.code;
+                            if (key) {
+                                argDisplay = chalk.dim(` → ${String(key)}`);
+                            }
+                            else {
+                                argDisplay = chalk.dim(` ${JSON.stringify(args)}`);
+                            }
+                        }
+                        log(`  ${turnLabel2}` + chalk.yellow(`⚡ ${name}`) + argDisplay);
+                    }
+                    break;
+                }
+                case 'tool_result': {
+                    const results = event.data.results || [];
+                    let anySuccessfulOutput = false;
+                    for (const result of results) {
+                        // Dedup: skip identical tool+output combos (LLM may call the
+                        // same tool twice across follow-up turns)
+                        const dedupKey = `${result.tool || 'tool'}::${(result.output || '').slice(0, 200)}`;
+                        if (seenToolResults.has(dedupKey))
+                            continue;
+                        seenToolResults.add(dedupKey);
+                        const icon = result.success !== false ? chalk.green('\u2713') : chalk.red('\u2717');
+                        const name = result.tool || 'tool';
+                        if (result.success !== false && result.output)
+                            anySuccessfulOutput = true;
+                        if (result.output && result.success !== false) {
+                            try {
+                                const parsed = JSON.parse(result.output);
+                                // ── Search results: expand each result ──
+                                if (parsed.results && Array.isArray(parsed.results) && parsed.results.length > 0) {
+                                    log(`  ${icon} ${chalk.bold(name)} — ${parsed.results.length} results:`);
+                                    if (parsed.answer && parsed.answer.length > 0) {
+                                        printIndentedBlock(`📝 ${decodeHtmlEntities(parsed.answer)}`);
+                                    }
+                                    for (const [idx, r] of parsed.results.entries()) {
+                                        const title = decodeHtmlEntities(r.title || 'Untitled');
+                                        const snippet = decodeHtmlEntities(r.snippet || r.body || '');
+                                        log(chalk.white(`     ${idx + 1}. ${title}`));
+                                        if (snippet) {
+                                            printIndentedBlock(snippet, '        ');
+                                        }
+                                    }
+                                }
+                                // ── Webpage fetch: show title + clean content preview ──
+                                else if (parsed.content) {
+                                    const title = parsed.title ? decodeHtmlEntities(parsed.title) + ' — ' : '';
+                                    const cleanContent = stripWebCruft(decodeHtmlEntities(parsed.content));
+                                    log(`  ${icon} ${chalk.bold(name)}`);
+                                    printIndentedBlock(`${title}${cleanContent}`);
+                                }
+                                // ── Generic JSON ──
+                                else {
+                                    log(`  ${icon} ${chalk.bold(name)}:`);
+                                    printIndentedBlock(JSON.stringify(parsed, null, 2));
+                                }
+                            }
+                            catch {
+                                // Non-JSON output
+                                const lines = String(result.output).split('\n').filter((l) => l.trim());
+                                log(`  ${icon} ${chalk.bold(name)}:`);
+                                for (const line of lines) {
+                                    printIndentedBlock(line);
+                                }
+                            }
+                        }
+                        else if (result.success === false) {
+                            const err = result.output || result.error || 'unknown error';
+                            log(`  ${icon} ${chalk.bold(name)}:`);
+                            printIndentedBlock(String(err), '     ', chalk.red);
+                        }
+                        else {
+                            log(`  ${icon} ${name}`);
+                        }
+                    }
+                    // Mark that we showed tool output — prevents '(no response)'
+                    // when the LLM's text answer is empty but tools returned data
+                    if (anySuccessfulOutput)
+                        hasOutput = true;
+                    break;
+                }
+                case 'done':
+                case 'complete': {
+                    stopSpinner();
+                    // Only render content + timing once (engine + router can both emit 'complete')
+                    if (completePrinted)
+                        break;
+                    completePrinted = true;
+                    if (!hasOutput && event.data.content) {
+                        content = event.data.content;
+                        process.stdout.write(renderMarkdown(wrapBareCode(content)));
+                        hasOutput = true;
+                    }
+                    else if (tokenStreamed) {
+                        // Content was streamed raw via token events — re-render with
+                        // markdown so code blocks display properly. wrapBareCode catches
+                        // bare code even when no fences are present.
+                        const wrapped = wrapBareCode(content);
+                        if (wrapped !== content || content.includes('```')) {
+                            process.stdout.write('\n');
+                            process.stdout.write(renderMarkdown(wrapped));
+                        }
+                    }
+                    if (hasOutput)
+                        process.stdout.write('\n');
+                    const meta = [];
+                    if (event.data.model || event.data.model_used)
+                        meta.push(event.data.model || event.data.model_used);
+                    if (event.data.duration_ms || event.data.elapsed_ms) {
+                        meta.push(`${Math.round(event.data.duration_ms || event.data.elapsed_ms)}ms`);
+                    }
+                    if (event.data.turns_completed)
+                        meta.push(`${event.data.turns_completed} turns`);
+                    if (event.data.agent)
+                        meta.push(event.data.agent);
+                    if (meta.length) {
+                        log(chalk.dim(`  [${meta.join(' \u00b7 ')}]`));
+                    }
+                    break;
+                }
+                case 'error':
+                    stopSpinner();
+                    log(chalk.red(`\n  Error: ${event.data.error || 'unknown error'}`));
+                    traceErrors.push(String(event.data.error || 'unknown error'));
+                    break;
+                case 'stream_timeout':
+                    // Soft timeout — stream went quiet but agent may still be running.
+                    // Don't show a hard error; the REPL will check forge status.
+                    stopSpinner();
+                    hasOutput = true; // Prevent "(no response)" — we already showed trace output
+                    break;
+                case 'heartbeat':
+                case 'keepalive': {
+                    const elapsedMs = event.data.elapsed_ms || event.data.elapsed;
+                    if (elapsedMs != null) {
+                        const secs = Math.round(elapsedMs / 1000);
+                        const elapsed = secs >= 60 ? `${Math.floor(secs / 60)}m ${secs % 60}s` : `${secs}s`;
+                        const stageHint = lastStage ? ` · ${lastStage}` : '';
+                        const statusMsg = `Working... ${elapsed} elapsed${stageHint}`;
+                        if (steeringBar?.active) {
+                            steeringBar.setStatus(statusMsg);
+                        }
+                        else if (spinner) {
+                            spinner.text = chalk.dim(statusMsg);
+                        }
+                        if (secs > 0 && secs % 30 === 0) {
+                            stopSpinner();
+                            log(chalk.dim(`  ⏱ Still working... ${elapsed}${stageHint}`));
+                            startSpinner(chalk.dim(statusMsg));
+                        }
+                    }
+                    else {
+                        const stageHint = lastStage ? ` · ${lastStage}` : '';
+                        if (steeringBar?.active) {
+                            steeringBar.setStatus(`Working...${stageHint}`);
+                        }
+                        else if (spinner) {
+                            spinner.text = chalk.dim(`Working...${stageHint}`);
+                        }
+                        else if (!hasOutput) {
+                            startSpinner(chalk.dim('Working...'));
+                        }
+                    }
+                    break;
+                }
+                case 'debug':
+                    break; // silent
+                // ── LLM lifecycle events — show what the model is doing ──
+                case 'llm_start': {
+                    const llmModel = event.data.model || 'auto';
+                    const llmTurn = event.data.turn;
+                    const turnHint = llmTurn != null ? ` (turn ${llmTurn})` : '';
+                    lastStage = `inference: ${llmModel}`;
+                    startSpinner(chalk.dim(`🧠 LLM inference: ${llmModel}${turnHint}`));
+                    break;
+                }
+                case 'llm_done': {
+                    const llmMs = event.data.llm_time_ms || event.data.elapsed_ms || event.data.duration_ms || 0;
+                    const llmTokens = event.data.tokens_used || event.data.tokens || event.data.completion_tokens || 0;
+                    const llmMod = event.data.model_used || event.data.model || '';
+                    const hasTools = event.data.has_tool_calls;
+                    stopSpinner();
+                    const parts = [];
+                    if (llmMs > 0)
+                        parts.push(`${Math.round(llmMs)}ms`);
+                    if (llmTokens > 0)
+                        parts.push(`${llmTokens} tokens`);
+                    if (llmMod)
+                        parts.push(llmMod);
+                    if (hasTools)
+                        parts.push('+ tool calls');
+                    if (parts.length > 0) {
+                        log(chalk.dim(`  ⚡ LLM: ${parts.join(' · ')}`));
+                    }
+                    lastStage = '';
+                    break;
+                }
+                case 'llm_error': {
+                    stopSpinner();
+                    const llmErr = event.data.error || 'inference failed';
+                    log(chalk.red(`  ⚡ LLM error: ${llmErr}`));
+                    traceErrors.push(`LLM: ${llmErr}`);
+                    lastStage = '';
+                    break;
+                }
+                // ── Pipeline trace events — show in spinner ──
+                case 'classify': {
+                    const intent = event.data.intent?.type || '?';
+                    const effort = event.data.effort?.level || '?';
+                    const tier = event.data.effort?.tier || '';
+                    const followupBoost = event.data.effort?.followup_boost || 0;
+                    const oneshot = event.data.effort?.oneshot || false;
+                    const depth = event.data.depth_label || '';
+                    let effortLine = `  📋 Intent: ${intent} | Effort: ${effort}`;
+                    if (tier)
+                        effortLine += ` | Tier: ${tier}`;
+                    if (depth)
+                        effortLine += ` | Depth: ${depth}`;
+                    if (followupBoost > 0)
+                        effortLine += ` (+${followupBoost} follow-up)`;
+                    if (oneshot)
+                        effortLine += ` ⚡ one-shot`;
+                    log(chalk.dim(effortLine));
+                    break;
+                }
+                // promotion_suggested handled below (near line 1050+)
+                case 'classify_update': {
+                    const updatedIntent = event.data.intent?.type || '?';
+                    const updatedEffort = event.data.effort?.level || '?';
+                    const reason = event.data.reason || 'context';
+                    log(chalk.dim(`  📋 Intent: ${updatedIntent} | Effort: ${updatedEffort} (${reason})`));
+                    break;
+                }
+                case 'model_select': {
+                    const model = event.data.model_selection?.recommended_model || 'auto';
+                    const tier = event.data.model_selection?.tier || 'auto';
+                    log(chalk.dim(`  🎯 Model: ${model} (${tier})`));
+                    break;
+                }
+                case 'context_assembly': {
+                    const tokens = event.data.total_tokens || 0;
+                    const gatherMs = event.data.gather_time_ms || 0;
+                    const sources = event.data.sources || {};
+                    traceContextSources = sources;
+                    const sourceEntries = Object.entries(sources);
+                    if (sourceEntries.length > 0) {
+                        stopSpinner();
+                        log(chalk.dim(`  📦 Context assembled: ${tokens} tokens (${gatherMs}ms)`));
+                        for (const [name, info] of sourceEntries) {
+                            const si = info;
+                            const toks = si.tokens || 0;
+                            const extra = si.fired ? ` (${si.fired} fired)` : '';
+                            const bar = toks > 0 ? chalk.green('█'.repeat(Math.min(Math.ceil(toks / 50), 20))) : chalk.red('—');
+                            log(chalk.dim(`     ${bar} ${name}: ${toks} tokens${extra}`));
+                        }
+                        startSpinner(chalk.dim('Building prompt...'));
+                    }
+                    else {
+                        log(chalk.dim(`  📦 Context: ${tokens} tokens`));
+                    }
+                    break;
+                }
+                case 'context_xray': {
+                    // Rich context introspection — show what made it into the prompt
+                    const snapshot = event.data.snapshot_id || '';
+                    const totalCtx = event.data.total_context_tokens || 0;
+                    const breakdown = event.data.breakdown || {};
+                    if (Object.keys(breakdown).length > 0) {
+                        log(chalk.dim(`  🔬 Context X-Ray: ${totalCtx} tokens ${snapshot ? `(${snapshot})` : ''}`));
+                        for (const [k, v] of Object.entries(breakdown)) {
+                            log(chalk.dim(`     ${k}: ${v}`));
+                        }
+                    }
+                    break;
+                }
+                case 'context_summary': {
+                    const origTokens = event.data.original_tokens || 0;
+                    const summTokens = event.data.summary_tokens || 0;
+                    if (origTokens > 0) {
+                        const pct = summTokens > 0 ? Math.round((1 - summTokens / origTokens) * 100) : 0;
+                        log(chalk.dim(`  📝 Context compressed: ${origTokens} → ${summTokens} tokens (${pct}% reduction)`));
+                    }
+                    break;
+                }
+                case 'clarification_needed': {
+                    stopSpinner();
+                    const questions = event.data.questions || [];
+                    const planSummary = event.data.plan_summary || '';
+                    if (planSummary) {
+                        log(chalk.cyan(`\n  📋 Plan: `) + chalk.dim(planSummary));
+                    }
+                    if (questions.length > 0) {
+                        log(chalk.yellow(`\n  ⏸ Clarification needed:`));
+                        for (const [i, q] of questions.entries()) {
+                            const qText = typeof q === 'string' ? q : (q.question || q.text || '?');
+                            const opts = (typeof q === 'object' && q.suggested_options) ? chalk.dim(`  Options: ${q.suggested_options.join(', ')}`) : '';
+                            log(chalk.white(`     ${i + 1}. ${qText}`) + opts);
+                        }
+                        log(chalk.dim('\n  💡 Just type your answer — it will continue the plan automatically.'));
+                    }
+                    hasOutput = true;
+                    break;
+                }
+                case 'plan_refined': {
+                    stopSpinner();
+                    const refined = event.data.plan_summary || '';
+                    const executable = event.data.is_executable ? chalk.green(' [ready]') : '';
+                    if (refined) {
+                        log(chalk.cyan(`\n  📋 Plan refined: `) + chalk.dim(refined) + executable);
+                    }
+                    // Restart spinner so heartbeats keep showing liveness
+                    startSpinner(chalk.dim('Executing plan...'));
+                    break;
+                }
+                case 'plan_ready': {
+                    stopSpinner();
+                    // Backend sends summary string, not steps array
+                    const summary = event.data.summary || '';
+                    const steps = event.data.steps || [];
+                    if (summary) {
+                        const agentic = event.data.agentic ? chalk.cyan(' [agentic]') : '';
+                        log(chalk.cyan(`\n  📋 Plan: `) + chalk.dim(summary) + agentic);
+                    }
+                    else if (steps.length > 0) {
+                        log(chalk.cyan(`\n  📋 Plan: ${steps.length} steps`));
+                        for (const [i, step] of steps.entries()) {
+                            const task = typeof step === 'string' ? step : (step.task || step.description || '?');
+                            log(chalk.dim(`     ${i + 1}. ${task}`));
+                        }
+                    }
+                    // Restart spinner so heartbeats keep showing liveness
+                    startSpinner(chalk.dim('Executing plan...'));
+                    break;
+                }
+                case 'plan_step': {
+                    const icon = event.data.status === 'complete' ? chalk.green('✓') : chalk.yellow('→');
+                    log(chalk.dim(`  ${icon} ${event.data.step || '?'}`));
+                    break;
+                }
+                case 'approval_required': {
+                    stopSpinner();
+                    log(chalk.yellow(`\n  ⏸ Approval required: ${event.data.action || event.data.reason || 'plan review'}`));
+                    log(chalk.dim('    (use web UI to respond, or /approve to continue)'));
+                    break;
+                }
+                case 'tool_selection': {
+                    const tools = (event.data.tool_names || event.data.detected_categories || []).join(', ') || 'none';
+                    const strategy = event.data.strategy || '';
+                    log(chalk.dim(`  🔧 Tools: [${tools}]${strategy ? ` strategy=${strategy}` : ''}`));
+                    break;
+                }
+                case 'tool_loop_step': {
+                    // Individual tool completion within the multi-turn tool loop
+                    const stepName = event.data.tool_name || 'tool';
+                    const stepOk = event.data.success !== false;
+                    const stepMs = event.data.elapsed_ms || 0;
+                    const stepIcon = stepOk ? chalk.green('\u2713') : chalk.red('\u2717');
+                    const msHint = stepMs > 0 ? chalk.dim(` (${stepMs}ms)`) : '';
+                    log(`  ${stepIcon} ${chalk.bold(stepName)}${msHint}`);
+                    break;
+                }
+                case 'checkpoint': {
+                    const turn = event.data.turn || '?';
+                    const maxTurns = event.data.max_turns || lastKnownMaxTurns || '?';
+                    if (event.data.max_turns)
+                        lastKnownMaxTurns = event.data.max_turns;
+                    const ok = event.data.ok || 0;
+                    const errors = event.data.errors || 0;
+                    const totalCalls = event.data.total_tool_calls || 0;
+                    const budgetPct = event.data.budget_pct || 0;
+                    const elapsed = event.data.elapsed_ms ? `${event.data.elapsed_ms}ms` : '';
+                    // Show progress bar
+                    const filled = Math.round(budgetPct / 10);
+                    const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+                    const errStr = errors > 0 ? chalk.red(` ${errors} err`) : '';
+                    log(chalk.dim(`  ── Turn ${turn}/${maxTurns} [${bar}] ${ok} ok${errStr} · ${totalCalls} total calls · ${elapsed}`));
+                    break;
+                }
+                case 'ooda_observe': {
+                    stopSpinner();
+                    const calls = event.data.tool_calls || 0;
+                    const ok = event.data.successes || 0;
+                    const turn3 = event.data.turn || '?';
+                    const maxT = event.data.max_turns || lastKnownMaxTurns || '?';
+                    log(chalk.dim(`  🔍 observe: Turn ${turn3}/${maxT} — ${ok}/${calls} tools ok`));
+                    break;
+                }
+                case 'ooda_decide': {
+                    const phase = event.data.phase || 'decide';
+                    const reason = event.data.reason || '';
+                    // Always show OODA decisions — they explain what the agent is doing
+                    if (reason) {
+                        stopSpinner();
+                        log(chalk.dim(`  🔄 ${phase}: ${reason}`));
+                    }
+                    else if (spinner) {
+                        spinner.text = chalk.dim(`OODA ${phase}`);
+                    }
+                    if (event.data.strip_tools) {
+                        log(chalk.dim('  🔄 Synthesizing from gathered data...'));
+                    }
+                    break;
+                }
+                case 'ooda_delegate': {
+                    stopSpinner();
+                    const target = event.data.delegate_to || '?';
+                    const reason = event.data.reason || '';
+                    log(chalk.yellow(`  🤝 Delegation → ${target}: ${reason}`));
+                    break;
+                }
+                case 'loop_guard': {
+                    log(chalk.red(`  ⛔ Loop guard: ${event.data.tool} — ${event.data.reason || 'blocked'}`));
+                    break;
+                }
+                case 'speculative_fire': {
+                    stopSpinner();
+                    const specTools = (event.data.tools || []).join(', ');
+                    log(chalk.cyan(`  🚀 Pre-firing: [${specTools}] (parallel speculative execution)`));
+                    break;
+                }
+                case 'speculative_result': {
+                    stopSpinner();
+                    const fired = event.data.tools_fired?.length || 0;
+                    const succeeded = event.data.tools_succeeded?.length || 0;
+                    const chars = event.data.total_chars || 0;
+                    log(chalk.green(`  ✓ Pre-fetched: ${succeeded}/${fired} tools returned data (${chars} chars)`));
+                    break;
+                }
+                case 'turn_start': {
+                    // Start spinner for new agent turn
+                    startSpinner(chalk.dim(`Turn ${event.data.turn || '?'}...`));
+                    break;
+                }
+                case 'escalation': {
+                    stopSpinner();
+                    log(chalk.yellow(`  ⬆ Escalation #${event.data.attempt || 1}: ${event.data.reason || 'quality'}`));
+                    break;
+                }
+                case 'reasoning_start':
+                case 'reasoning_engage': {
+                    const rawDepth = event.data.depth || 'deep';
+                    // Map internal labels to user-friendly display
+                    const depth = rawDepth === 'skip' ? 'light' : rawDepth === 'none' ? 'light' : rawDepth;
+                    const reason = event.data.reason || event.data.content || '';
+                    if (spinner) {
+                        spinner.text = chalk.dim(`Reasoning (${depth}): ${reason || '...'}`);
+                    }
+                    // Show reasoning trace content when available
+                    if (reason.length > 30) {
+                        log(chalk.dim(`  🧠 Reasoning (${depth}): ${reason}`));
+                    }
+                    break;
+                }
+                case 'reasoning_strategy': {
+                    stopSpinner();
+                    const index = event.data.strategy != null ? `#${event.data.strategy}` : '';
+                    const name = event.data.name || event.data.strategy_name || 'strategy';
+                    const detail = event.data.detail || event.data.content || '';
+                    log(chalk.dim(`  🧠 Strategy ${index} ${name}`.trimEnd()));
+                    if (detail) {
+                        printIndentedBlock(detail);
+                    }
+                    break;
+                }
+                case 'reasoning_trace':
+                case 'reasoning_step': {
+                    const step = event.data.content || event.data.step || event.data.trace || '';
+                    if (step) {
+                        stopSpinner();
+                        log(chalk.dim('  🧠 Reasoning step:'));
+                        printIndentedBlock(step);
+                    }
+                    break;
+                }
+                case 'agentic_upgrade': {
+                    stopSpinner();
+                    const reason = event.data.reason || 'auto';
+                    log(chalk.cyan(`  🔀 Agentic mode: ${reason}`));
+                    break;
+                }
+                case 'promotion_suggested': {
+                    stopSpinner();
+                    const sugEffort = event.data.suggested_effort || '?';
+                    const sugReason = event.data.reason || '';
+                    const sugMsg = event.data.message || '';
+                    log(chalk.yellow(`\n  ⬆ ${sugMsg || `Suggest escalation to effort ${sugEffort}: ${sugReason}`}`));
+                    break;
+                }
+                case 'council':
+                case 'council_perspective': {
+                    const agent = event.data.agent || 'council';
+                    const content = event.data.perspective || event.data.consensus || '';
+                    if (content) {
+                        log(chalk.magenta(`  👥 ${agent}: `) + chalk.dim(content));
+                    }
+                    break;
+                }
+                case 'agent_message': {
+                    const agentName = event.data.agent || 'agent';
+                    log(chalk.blue(`  🤖 ${agentName}: `) + chalk.dim(event.data.content || ''));
+                    break;
+                }
+                case 'steering_guide': {
+                    log(chalk.yellow(`  🔄 Steering: ${event.data.hook || '?'} → ${event.data.reason || 'guided'}`));
+                    if (event.data.suggestion) {
+                        log(chalk.dim(`     💡 ${event.data.suggestion}`));
+                    }
+                    break;
+                }
+                case 'think_start': {
+                    // Show think configuration as a visible pipeline trace
+                    const model = event.data.model || 'auto';
+                    const effort = event.data.effort_level || '?';
+                    const reasoning = event.data.use_reasoning ? 'reasoning' : 'standard';
+                    const elapsed = event.data.elapsed_ms ? `${event.data.elapsed_ms}ms` : '';
+                    log(chalk.dim(`  ⚙ Think: E${effort} ${reasoning} model=${model} ${elapsed}`));
+                    break;
+                }
+                // ── UCB pipeline stages — context gathering + LLM call ──
+                case 'context_start': {
+                    const sources = (event.data.sources || []).join(', ') || 'none';
+                    startSpinner(chalk.dim(`Gathering context: ${sources}`));
+                    break;
+                }
+                case 'context_done': {
+                    const gatherMs2 = event.data.gather_time_ms || 0;
+                    const sourceResults = event.data.sources || {};
+                    const sourceNames = Object.keys(sourceResults);
+                    const neuronsFired = event.data.neurons_fired || 0;
+                    const cacheHits = event.data.cache_hits || 0;
+                    const ctxTokens = event.data.context_tokens || event.data.system_prompt_tokens || 0;
+                    if (sourceNames.length > 0) {
+                        stopSpinner();
+                        const extras = [];
+                        if (neuronsFired > 0)
+                            extras.push(`${neuronsFired} neurons`);
+                        if (cacheHits > 0)
+                            extras.push(`${cacheHits} cache hits`);
+                        if (ctxTokens > 0)
+                            extras.push(`${ctxTokens} tokens`);
+                        const extStr = extras.length > 0 ? ` · ${extras.join(', ')}` : '';
+                        log(chalk.dim(`  📦 Context gathered: ${sourceNames.join(', ')} (${gatherMs2}ms${extStr})`));
+                        // Show token breakdown per source
+                        for (const [name, info] of Object.entries(sourceResults)) {
+                            const si = info;
+                            const toks = si.tokens || 0;
+                            if (toks > 0) {
+                                const bar = chalk.green('█'.repeat(Math.min(Math.ceil(toks / 100), 20)));
+                                const extra = si.fired ? ` (${si.fired} fired)` : si.count ? ` (${si.count} entries)` : '';
+                                log(chalk.dim(`     ${bar} ${name}: ${toks} tokens${extra}`));
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'llm_start': {
+                    // From UCB: has model, prompt_tokens_est, has_tools
+                    // From AgentRuntime: has turn, timestamp (minimal)
+                    const llmModel = event.data.model || 'auto';
+                    traceModel = llmModel;
+                    const promptTokens = event.data.prompt_tokens_est || 0;
+                    const hasTools2 = event.data.has_tools ? ' + tools' : '';
+                    const turnInfo = event.data.turn ? `Turn ${event.data.turn} · ` : '';
+                    const tokenInfo = promptTokens > 0 ? ` (${promptTokens} tokens${hasTools2})` : '';
+                    const spinText = `${turnInfo}LLM inference: ${llmModel}${tokenInfo}`;
+                    lastStage = `LLM: ${llmModel}`;
+                    // Always print a visible line so the user knows what's happening
+                    stopSpinner();
+                    log(chalk.dim(`  🧠 ${spinText}`));
+                    startSpinner(chalk.dim(spinText));
+                    break;
+                }
+                case 'llm_done':
+                case 'llm_end': {
+                    stopSpinner();
+                    const llmMs = event.data.llm_time_ms || event.data.duration_ms || 0;
+                    const tokensUsed = event.data.tokens_used || event.data.tokens || 0;
+                    const llmModelUsed = event.data.model_used || event.data.model || 'default';
+                    const hasThinking = event.data.has_thinking ? ' + reasoning' : '';
+                    const hasToolCalls = event.data.has_tool_calls ? ' + tool_calls' : '';
+                    log(chalk.dim(`  ⚡ LLM: ${llmModelUsed} → ${tokensUsed} tokens (${Math.round(llmMs)}ms)${hasThinking}${hasToolCalls}`));
+                    break;
+                }
+                case 'middleware_progress': {
+                    const mwName = event.data.middleware || event.data.stage || 'middleware';
+                    const mwStatus = event.data.status || 'running';
+                    const mwDetail = event.data.detail || '';
+                    lastStage = mwName;
+                    const mwIcon = mwStatus === 'complete' ? chalk.green('✓') : chalk.yellow('→');
+                    const detailStr = mwDetail ? chalk.dim(` (${mwDetail})`) : '';
+                    if (steeringBar?.active) {
+                        // Log line goes through interceptor (one bar redraw).
+                        // Status updates without extra redraws.
+                        console.log(chalk.dim(`  ${mwIcon} ${mwName}: ${mwStatus}${detailStr}`));
+                        steeringBar.setStatus(`${mwName}...`);
+                    }
+                    else {
+                        stopSpinner();
+                        log(chalk.dim(`  ${mwIcon} ${mwName}: ${mwStatus}${detailStr}`));
+                        startSpinner(chalk.dim(`${mwName}...`));
+                    }
+                    break;
+                }
+                case 'mcts_plan': {
+                    stopSpinner();
+                    const mSteps = event.data.steps || [];
+                    const mMethodRaw = event.data.method || 'MCTS';
+                    const mMethodLabels = {
+                        'direct': 'direct',
+                        'mcts_heuristic': 'mcts_heuristic',
+                        'mcts': 'mcts',
+                    };
+                    const mMethod = mMethodLabels[mMethodRaw] || mMethodRaw;
+                    log(chalk.cyan(`  🌲 ${mMethod} plan: ${mSteps.length} steps`));
+                    for (const [i, step] of mSteps.entries()) {
+                        const desc = typeof step === 'string' ? step : (step.task || step.description || step.type || '?');
+                        const tool = (typeof step === 'object' && step.tool) ? chalk.yellow(` [${step.tool}]`) : '';
+                        log(chalk.dim(`     ${i + 1}. ${desc}`) + tool);
+                    }
+                    break;
+                }
+                // ── Context Facets — multi-phase agentic execution ──
+                case 'facet_start': {
+                    stopSpinner();
+                    const chType = (event.data.facet_type || 'unknown').toUpperCase();
+                    const chIdx = event.data.facet_index ?? '?';
+                    const chTurns = event.data.max_turns || '?';
+                    const chTools = Array.isArray(event.data.tools) ? event.data.tools.length + ' tools' : 'all tools';
+                    log(chalk.cyan(`\n  ── Facet ${chIdx}: ${chType} (${chTurns} turns, ${chTools}) ──`));
+                    startSpinner(chalk.dim(`${chType} phase...`));
+                    break;
+                }
+                case 'facet_end': {
+                    stopSpinner();
+                    const endType = (event.data.facet_type || '').toUpperCase();
+                    const endTurns = event.data.turns_completed || 0;
+                    const endTokens = event.data.tokens_used || 0;
+                    const endRemaining = event.data.tokens_remaining || 0;
+                    const crystalPreview = event.data.crystal_summary || '';
+                    log(chalk.green(`  ✓ ${endType} complete: ${endTurns} turns, ${endTokens} tokens${endRemaining > 0 ? ` (+${endRemaining} unspent)` : ''}`));
+                    if (crystalPreview) {
+                        log(chalk.dim('    Crystal:'));
+                        printIndentedBlock(crystalPreview, '      ');
+                    }
+                    break;
+                }
+                case 'facet_crystallize': {
+                    const crIdx = event.data.facet_index ?? '?';
+                    const findings = event.data.key_findings || [];
+                    if (findings.length > 0) {
+                        log(chalk.yellow(`  💎 Crystallized ${findings.length} findings from facet ${crIdx}:`));
+                        for (const f of findings) {
+                            printIndentedBlock(`• ${f}`);
+                        }
+                    }
+                    break;
+                }
+                case 'budget_cascade': {
+                    const fromCh = event.data.from_facet || event.data.from_chapter || '?';
+                    const toCh = event.data.to_facet || event.data.to_chapter || 'pool (reusable for later facets)';
+                    const transferred = event.data.tokens_transferred || 0;
+                    if (transferred > 0) {
+                        log(chalk.dim(`  ↪ Budget cascade: ${transferred} turns from ${fromCh} → ${toCh}`));
+                    }
+                    break;
+                }
+                case 'artifact_delivered': {
+                    stopSpinner();
+                    const artFile = event.data.filename || event.data.path || 'file';
+                    const artSize = event.data.size || 0;
+                    const artCmd = event.data.retrieve_cmd || '';
+                    const artLang = event.data.language || '';
+                    const artPath = event.data.path || '';
+                    // Track artifact in session store
+                    _sessionArtifacts.push({
+                        filename: artFile,
+                        path: artPath,
+                        size: artSize,
+                        language: artLang,
+                        retrieve_cmd: artCmd,
+                        timestamp: new Date().toISOString(),
+                    });
+                    const artIdx = _sessionArtifacts.length;
+                    log(chalk.green.bold(`\n  📦 Artifact #${artIdx}: ${artFile} (${artSize} bytes)`));
+                    if (artCmd) {
+                        log(chalk.dim(`     Retrieve: ${artCmd}`));
+                        log(chalk.cyan(`     Run /artifacts to list all, /get ${artIdx} to download`));
+                    }
+                    break;
+                }
+                // Pipeline stages that update spinner
+                case 'pipeline':
+                case 'session_learn':
+                case 'search_fire':
+                case 'judge':
+                case 'delegation_decide':
+                case 'fast_path':
+                case 'security_gate':
+                case 'memory_recall':
+                case 'guardrail_check': {
+                    if (spinner) {
+                        const msg = event.data.message || event.data.stage || event.data.phase
+                            || event.data.status || event.type;
+                        spinner.text = chalk.dim(msg);
+                    }
+                    break;
+                }
+                // ── Missing event handlers — full observability ──
+                case 'turn_end': {
+                    const teTurn = event.data.turn || '?';
+                    const teDuration = event.data.duration_ms ? `${Math.round(event.data.duration_ms)}ms` : '';
+                    const teOutcome = event.data.outcome || '';
+                    log(chalk.dim(`  ── Turn ${teTurn} end${teOutcome ? `: ${teOutcome}` : ''}${teDuration ? ` (${teDuration})` : ''}`));
+                    break;
+                }
+                case 'tool_denied': {
+                    const denied = event.data.denied || [];
+                    if (denied.length > 0) {
+                        log(chalk.red(`  ⛔ Tools denied: ${denied.join(', ')}`));
+                    }
+                    break;
+                }
+                case 'tool_selected': {
+                    const selToolsArr = event.data.tools || [];
+                    const selTool = selToolsArr.length > 0
+                        ? `[${selToolsArr.slice(0, 4).join(', ')}${selToolsArr.length > 4 ? `, +${selToolsArr.length - 4}` : ''}]`
+                        : (event.data.tool || event.data.name || '?');
+                    const selTotal = event.data.total_available || 0;
+                    const selReason = selTotal > 0 ? `${selToolsArr.length}/${selTotal} tools` : (event.data.reason || '');
+                    log(chalk.dim(`  🔧 Tool selected: ${selTool}${selReason ? ` — ${selReason}` : ''}`));
+                    break;
+                }
+                case 'llm_error': {
+                    stopSpinner();
+                    const llmErr = event.data.error || event.data.message || 'unknown';
+                    const llmErrModel = event.data.model || '?';
+                    log(chalk.red(`  ✗ LLM error (${llmErrModel}): ${String(llmErr)}`));
+                    traceErrors.push(`LLM error (${llmErrModel}): ${String(llmErr)}`);
+                    break;
+                }
+                case 'reasoning_depth': {
+                    const rdDepth = event.data.depth || event.data.level || '?';
+                    const rdReason = event.data.reason || '';
+                    log(chalk.dim(`  🧠 Reasoning depth: ${rdDepth}${rdReason ? ` — ${rdReason}` : ''}`));
+                    break;
+                }
+                case 'agentic_promotion': {
+                    stopSpinner();
+                    const apReason = event.data.reason || 'auto';
+                    const apEffort = event.data.effort || '?';
+                    log(chalk.cyan(`  🔀 Agentic promotion: effort=${apEffort} — ${apReason}`));
+                    break;
+                }
+                case 'steering': {
+                    const stHook = event.data.hook || event.data.type || '?';
+                    const stReason = event.data.reason || '';
+                    log(chalk.yellow(`  🔄 Steering: ${stHook}${stReason ? ` — ${stReason}` : ''}`));
+                    break;
+                }
+                case 'strategy_subsystem': {
+                    const ssName = event.data.subsystem || event.data.name || '?';
+                    const ssStatus = event.data.status || event.data.decision || '';
+                    log(chalk.dim(`  ⚙ Strategy: ${ssName} → ${ssStatus}`));
+                    break;
+                }
+                case 'plan_approved': {
+                    log(chalk.green(`  ✓ Plan approved${event.data.plan_id ? ` (${event.data.plan_id})` : ''}`));
+                    break;
+                }
+                case 'verification': {
+                    const vResults = event.data.results || [];
+                    if (Array.isArray(vResults) && vResults.length > 0) {
+                        for (const v of vResults) {
+                            const icon = v.success ? chalk.green('✓') : chalk.red('✗');
+                            const path = v.path || '';
+                            const kind = v.kind || '';
+                            const reason = v.reason || '';
+                            const kindLabel = kind ? ` (${kind.replace(/_/g, ' ')})` : '';
+                            log(chalk.dim(`  🔍 ${icon} ${path}${kindLabel}${reason ? ` — ${reason}` : ''}`));
+                        }
+                    }
+                    else {
+                        const vResult = event.data.passed ? chalk.green('✓ passed') : chalk.red('✗ failed');
+                        const vDetail = event.data.detail || event.data.reason || '';
+                        log(chalk.dim(`  🔍 Verification: ${vResult}${vDetail ? ` — ${vDetail}` : ''}`));
+                    }
+                    break;
+                }
+                case 'image_gen_start': {
+                    stopSpinner();
+                    const igPrompt = event.data.prompt || event.data.description || '';
+                    log(chalk.cyan(`  🎨 Generating image: ${igPrompt}`));
+                    startSpinner(chalk.dim('Generating image...'));
+                    break;
+                }
+                case 'image_gen_complete': {
+                    stopSpinner();
+                    const igUrl = event.data.url || '';
+                    log(chalk.green(`  ✓ Image generated${igUrl ? `: ${igUrl}` : ''}`));
+                    break;
+                }
+                case 'image_gen_failed': {
+                    stopSpinner();
+                    const igErr = event.data.error || 'unknown';
+                    log(chalk.red(`  ✗ Image generation failed: ${igErr}`));
+                    break;
+                }
+                case 'session_context': {
+                    const scTopic = event.data.topic || event.data.summary || '';
+                    if (scTopic) {
+                        log(chalk.dim(`  📝 Session context: ${scTopic}`));
+                    }
+                    break;
+                }
+                case 'reasoning_backend_health': {
+                    const backends = event.data.backends || {};
+                    const entries = Object.entries(backends);
+                    // Friendly display names for backend IDs
+                    const friendlyNames = {
+                        'vllm': 'orchestrator vLLM',
+                        'vllm_swap': 'local swap (on-demand)',
+                        'vllm_orchestrator': 'orchestrator (fallback)',
+                        'vllm_reasoning': 'local reasoning (on-demand)',
+                        'vllm_coding': 'coding vLLM',
+                        'vllm_qwen': 'Qwen vLLM',
+                        'vllm_cloud_reasoning': 'cloud reasoning',
+                        'vllm_gemma4_reasoning': 'Gemma4 (cloud)',
+                        'vllm_gemma4_flagship': 'Gemma4 flagship (cloud)',
+                        'vllm_dgx': 'DGX Spark',
+                        'vllm_dgx_swap': 'DGX Spark (swap)',
+                        'vllm_dgx_embed': 'DGX Spark (embeddings)',
+                        'vllm_dgx_orch': 'DGX Spark (orchestrator)',
+                        'deepseek_api': 'DeepSeek API',
+                        'comfyui': 'ComfyUI',
+                    };
+                    // On-demand backends are expected to be offline — hide when down, show when up
+                    const onDemandBackends = new Set([
+                        'vllm_swap', 'vllm_reasoning', 'vllm_dgx_swap',
+                        'vllm_gemma4_reasoning', 'vllm_gemma4_flagship', 'vllm_cloud_reasoning',
+                    ]);
+                    if (entries.length > 0) {
+                        const online = entries.filter(([, alive]) => alive);
+                        // Only show offline backends that aren't on-demand (expected off)
+                        const offline = entries.filter(([name, alive]) => !alive && !onDemandBackends.has(name));
+                        for (const [name, alive] of [...online, ...offline]) {
+                            const label = friendlyNames[name] || name.replace(/^vllm_/, '').replace(/_/g, ' ');
+                            const status = alive ? chalk.green('online') : chalk.red('offline');
+                            log(chalk.dim(`  🔧 ${label}: ${status}`));
+                        }
+                    }
+                    break;
+                }
+                case 'autonomous_start':
+                case 'autonomous_task': {
+                    stopSpinner();
+                    const atTask = event.data.task || event.data.description || '';
+                    log(chalk.cyan(`  🤖 Autonomous task: ${atTask}`));
+                    break;
+                }
+                case 'expedition_created': {
+                    const expId = event.data.expedition_id || event.data.id || '?';
+                    log(chalk.cyan(`  🗺 Expedition created: ${expId}`));
+                    break;
+                }
+                case 'checkpoint_resumed': {
+                    const crTurn = event.data.turn || '?';
+                    log(chalk.dim(`  ↩ Checkpoint resumed at turn ${crTurn}`));
+                    break;
+                }
+                case 'council_review': {
+                    const crVerdict = event.data.verdict || event.data.decision || '';
+                    const crReason = event.data.reason || '';
+                    log(chalk.magenta(`  👥 Council review: ${crVerdict}${crReason ? ` — ${crReason}` : ''}`));
+                    break;
+                }
+                case 'cuga_available': {
+                    break; // Internal signal, no display needed
+                }
+                case 'context_stage': {
+                    const csStage = event.data.substage || event.data.stage || 'context';
+                    const csStatus = event.data.status || event.data.detail || '';
+                    const csLabel = csStatus ? `${csStage}: ${csStatus}` : csStage;
+                    lastStage = csLabel;
+                    stopSpinner();
+                    log(chalk.dim(`  [context_stage] ${csLabel}`));
+                    startSpinner(chalk.dim(csLabel));
+                    break;
+                }
+                case 'pipeline': {
+                    const plStage = event.data.stage || event.data.phase || '';
+                    const plStrategy = event.data.strategy || '';
+                    const plEffort = event.data.effort;
+                    // Show effort/strategy info inline
+                    if (plEffort && typeof plEffort === 'object') {
+                        const efLvl = plEffort.level || '?';
+                        const efLabel = plEffort.label || plEffort.tier || '';
+                        stopSpinner();
+                        log(chalk.dim(`  [pipeline] effort=${efLvl}${efLabel ? ` (${efLabel})` : ''}${plStrategy ? ` strategy=${plStrategy}` : ''}`));
+                    }
+                    else if (plStage) {
+                        lastStage = plStage;
+                        if (spinner) {
+                            spinner.text = chalk.dim(plStage);
+                        }
+                    }
+                    break;
+                }
+                case 'plan_complete':
+                case 'plan_status': {
+                    const pcStatus = event.data.status || event.data.outcome || 'done';
+                    lastStage = `plan: ${pcStatus}`;
+                    log(chalk.dim(`  [plan_complete] ${pcStatus}`));
+                    break;
+                }
+                case 'turn_progress': {
+                    const tpTurn = event.data.turn || '?';
+                    const tpMax = event.data.max_turns || '?';
+                    if (event.data.max_turns)
+                        lastKnownMaxTurns = event.data.max_turns;
+                    lastStage = `turn ${tpTurn}/${tpMax}`;
+                    if (spinner) {
+                        spinner.text = chalk.dim(`Turn ${tpTurn}/${tpMax}...`);
+                    }
+                    break;
+                }
+                default: {
+                    // Show content from unexpected events as fallback
+                    if (event.data.content && !hasOutput) {
+                        stopSpinner();
+                        process.stdout.write(event.data.content);
+                        content += event.data.content;
+                        hasOutput = true;
+                    }
+                    // Show meaningful unknown events so nothing is silently swallowed
+                    const msg = event.data.message || event.data.reason || event.data.status || '';
+                    if (msg && event.type !== 'debug') {
+                        log(chalk.dim(`  [${event.type}] ${String(msg).slice(0, 120)}`));
+                    }
+                    break;
+                }
+            }
+        },
+        getContent() {
+            return content;
+        },
+        finish() {
+            stopSpinner();
+            if (!hasOutput) {
+                console.log(chalk.dim('  (no response)'));
+            }
+            // ── Status bar — compact summary after each response ──
+            const elapsed = Date.now() - startTime;
+            const parts = [];
+            if (traceAgent)
+                parts.push(`agent: ${traceAgent}`);
+            if (traceModel)
+                parts.push(`model: ${traceModel}`);
+            if (traceTurns > 0)
+                parts.push(`turns: ${traceTurns}/${lastKnownMaxTurns}`);
+            if (traceToolCalls.length > 0)
+                parts.push(`tools: ${traceToolCalls.length}`);
+            parts.push(`${(elapsed / 1000).toFixed(1)}s`);
+            console.log(chalk.dim(`  [${parts.join(' | ')}]`));
+            // ── Persist session trace to disk ──
+            if (sessionId) {
+                try {
+                    const sessDir = join(homedir(), '.aither', 'sessions', sessionId);
+                    if (!existsSync(sessDir))
+                        mkdirSync(sessDir, { recursive: true });
+                    const profile = this.getSessionProfile();
+                    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+                    const filePath = join(sessDir, `${ts}.json`);
+                    writeFileSync(filePath, JSON.stringify(profile, null, 2));
+                }
+                catch (_e) {
+                    // best-effort — don't crash on trace write failure
+                }
+            }
+        },
+        getTrace() {
+            return traceEvents;
+        },
+        getSessionProfile() {
+            return {
+                session_id: sessionId || 'anonymous',
+                prompt: prompt || '',
+                started_at: startedAt,
+                duration_ms: Date.now() - startTime,
+                event_count: traceEvents.length,
+                tool_calls: traceToolCalls,
+                thinking_traces: traceThinking,
+                context_sources: traceContextSources,
+                model: traceModel,
+                agent: traceAgent,
+                errors: traceErrors,
+                events: traceEvents,
+            };
+        },
+    };
+}
+/* ── Terminal Block Renderer ────────────────────────────────── */
+function renderTerminalBlocks(blocks) {
+    for (const block of blocks) {
+        switch (block.type) {
+            case 'header':
+                console.log(chalk.bold.cyan(`\n  ${block.text}`) + (block.subtitle ? chalk.dim(` — ${block.subtitle}`) : ''));
+                break;
+            case 'kv': {
+                const pairs = block.pairs || {};
+                for (const [k, v] of Object.entries(pairs)) {
+                    console.log(chalk.dim(`    ${k}: `) + chalk.white(String(v)));
+                }
+                break;
+            }
+            case 'table': {
+                const cols = (block.columns || []).map((c) => typeof c === 'string' ? c : c.label);
+                const rows = (block.rows || []).map((r) => r.map(String));
+                if (cols.length > 0) {
+                    console.log('  ' + formatTable(cols, rows).split('\n').join('\n  '));
+                }
+                break;
+            }
+            case 'callout': {
+                const icons = { info: 'ℹ', success: '✓', warning: '⚠', error: '✗', tip: '💡' };
+                const colors = {
+                    info: chalk.blue, success: chalk.green, warning: chalk.yellow,
+                    error: chalk.red, tip: chalk.magenta,
+                };
+                const color = colors[block.variant || 'info'] || chalk.blue;
+                const icon = icons[block.variant || 'info'] || 'ℹ';
+                console.log(color(`  ${icon} ${block.title || ''} ${block.text}`));
+                break;
+            }
+            case 'progress': {
+                if (block.steps) {
+                    const icons = { done: '✓', active: '⟳', pending: '○', error: '✗' };
+                    for (const step of block.steps) {
+                        const icon = icons[step.status] || '○';
+                        const color = step.status === 'done' ? chalk.green : step.status === 'active' ? chalk.blue : step.status === 'error' ? chalk.red : chalk.dim;
+                        console.log(color(`    ${icon} ${step.name}`) + (step.detail ? chalk.dim(` (${step.detail})`) : ''));
+                    }
+                }
+                else if (block.value != null) {
+                    const pct = Math.round(block.value * 100);
+                    const filled = Math.round(pct / 5);
+                    const bar = '█'.repeat(filled) + '░'.repeat(20 - filled);
+                    console.log(chalk.blue(`  [${bar}] ${pct}%`) + (block.label ? chalk.dim(` ${block.label}`) : ''));
+                }
+                break;
+            }
+            case 'scores': {
+                for (const [name, val] of Object.entries(block.scores || {})) {
+                    const v = val;
+                    const pct = Math.round(v * 100);
+                    const color = pct >= 80 ? chalk.green : pct >= 50 ? chalk.yellow : chalk.red;
+                    console.log(`    ${chalk.dim(name.padEnd(20))} ${color(`${pct}%`)}`);
+                }
+                break;
+            }
+            case 'code': {
+                const label = block.filename || block.language || 'code';
+                console.log(chalk.dim(`\n  ─── ${label} ───`));
+                const codeLines = (block.content || '').split('\n');
+                for (const codeLine of codeLines) {
+                    console.log(chalk.white(`  ${codeLine}`));
+                }
+                console.log(chalk.dim(`  ─── end ───`));
+                if (block.filename && block.filename !== 'code' && !block.filename.startsWith('code.')) {
+                    console.log(chalk.dim(`  Saved to: ${block.filename}`));
+                }
+                break;
+            }
+            case 'list': {
+                const items = block.items || [];
+                for (const item of items) {
+                    const text = typeof item === 'string' ? item : item.text;
+                    console.log(chalk.dim('  • ') + text);
+                }
+                break;
+            }
+            case 'approve':
+                console.log(chalk.yellow.bold(`\n  ⚠ ${block.title}`));
+                if (block.detail)
+                    console.log(chalk.dim(`    ${block.detail}`));
+                console.log(chalk.dim(`    [${block.approve_label || 'Approve'}] / [${block.reject_label || 'Reject'}]`));
+                console.log(chalk.dim(`    (interactive approval — use web UI to respond)`));
+                break;
+            case 'form':
+                if (block.title)
+                    console.log(chalk.cyan.bold(`\n  📋 ${block.title}`));
+                if (block.description)
+                    console.log(chalk.dim(`    ${block.description}`));
+                for (const f of block.fields || []) {
+                    const def = f.default != null ? chalk.dim(` [${f.default}]`) : '';
+                    console.log(chalk.dim(`    ${f.label}:`) + def);
+                }
+                console.log(chalk.dim(`    (interactive form — use web UI to submit)`));
+                break;
+            case 'select':
+                if (block.label)
+                    console.log(chalk.cyan(`  ${block.label}`));
+                for (const opt of block.options || []) {
+                    const label = typeof opt === 'string' ? opt : opt.label;
+                    const desc = typeof opt === 'object' && opt.description ? chalk.dim(` — ${opt.description}`) : '';
+                    console.log(chalk.dim('    ○ ') + label + desc);
+                }
+                console.log(chalk.dim(`    (interactive selection — use web UI to choose)`));
+                break;
+            case 'markdown':
+                if (block.text)
+                    console.log('  ' + renderMarkdown(block.text).trim().split('\n').join('\n  '));
+                break;
+            default:
+                // Unknown block — show type + any text content
+                if (block.text || block.content) {
+                    console.log(chalk.dim(`  [${block.type}] `) + (block.text || block.content));
+                }
+                break;
+        }
+    }
+}
+/* ── Table Formatter ────────────────────────────────────────── */
+export function formatTable(headers, rows) {
+    // Strip ANSI for width calculation
+    const strip = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+    const widths = headers.map((h, i) => Math.max(strip(h).length, ...rows.map(r => strip(r[i] || '').length)));
+    const pad = (s, w) => s + ''.padEnd(Math.max(0, w - strip(s).length));
+    const header = headers.map((h, i) => pad(h, widths[i])).join('  ');
+    const sep = widths.map(w => '\u2500'.repeat(w)).join('\u2500\u2500');
+    const body = rows.map(row => row.map((cell, i) => pad(cell || '', widths[i])).join('  ')).join('\n');
+    return `${chalk.bold(header)}\n${chalk.dim(sep)}\n${body}`;
+}
+/* ── Steering Bar — dedicated input line during streaming ─────── */
+/**
+ * Keeps a visible input line at the bottom of the terminal while
+ * stream output prints above.  Works on Windows Terminal (no ANSI
+ * scroll regions).
+ *
+ * How it works:
+ *   1. Intercepts process.stdout.write
+ *   2. Before each write: erase the bar line so output doesn't collide
+ *   3. After each write: redraw the bar on a fresh line below output
+ *   4. User keystrokes update the bar's displayed text in real time
+ *   5. On Enter, the bar clears and the repl routes to /chat/steer
+ *
+ * The bar line looks like:
+ *   ── [steer] > what the user is typing_
+ */
+export class SteeringBar {
+    _active = false;
+    _inputText = '';
+    _statusText = '';
+    _origWrite = null;
+    _barDrawn = false;
+    _debounceTimer = null;
+    _spinFrame = 0;
+    _spinTimer = null;
+    static _SPIN_CHARS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    get active() { return this._active; }
+    get inputText() { return this._inputText; }
+    activate() {
+        if (this._active)
+            return;
+        this._active = true;
+        this._inputText = '';
+        this._statusText = '';
+        this._barDrawn = false;
+        if (!process.stdout.isTTY)
+            return;
+        const self = this;
+        this._origWrite = process.stdout.write.bind(process.stdout);
+        const origWrite = this._origWrite;
+        process.stdout.write = function (chunk, encodingOrCb, cb) {
+            if (!self._active) {
+                return origWrite(chunk, encodingOrCb, cb);
+            }
+            // Erase bar before writing output
+            if (self._barDrawn) {
+                origWrite('\x1b8\x1b[J');
+                self._barDrawn = false;
+            }
+            // Write the actual output
+            const result = origWrite(chunk, encodingOrCb, cb);
+            // Schedule bar redraw (debounced — token bursts produce many writes)
+            if (self._debounceTimer)
+                clearTimeout(self._debounceTimer);
+            self._debounceTimer = setTimeout(() => {
+                self._debounceTimer = null;
+                if (self._active)
+                    self._drawBar(origWrite);
+            }, 30);
+            return result;
+        };
+        // Draw initial bar
+        this._drawBar(origWrite);
+    }
+    deactivate() {
+        if (!this._active)
+            return;
+        this._active = false;
+        this._statusText = '';
+        if (this._debounceTimer) {
+            clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+        }
+        if (this._spinTimer) {
+            clearInterval(this._spinTimer);
+            this._spinTimer = null;
+        }
+        // Erase bar if drawn
+        if (this._barDrawn && this._origWrite) {
+            this._origWrite('\x1b8\x1b[J');
+            this._barDrawn = false;
+        }
+        // Restore stdout.write
+        if (this._origWrite) {
+            process.stdout.write = this._origWrite;
+            this._origWrite = null;
+        }
+    }
+    /** Schedule a single debounced redraw. All state changes route here. */
+    _scheduleRedraw() {
+        if (!this._active || !this._origWrite)
+            return;
+        if (this._debounceTimer)
+            clearTimeout(this._debounceTimer);
+        const w = this._origWrite;
+        this._debounceTimer = setTimeout(() => {
+            this._debounceTimer = null;
+            if (!this._active)
+                return;
+            if (this._barDrawn) {
+                w('\x1b8\x1b[J');
+                this._barDrawn = false;
+            }
+            this._drawBar(w);
+        }, 16);
+    }
+    /** Show spinner + status text in the bar (replaces ora when bar is active). */
+    setStatus(text) {
+        this._statusText = text;
+        if (!this._spinTimer && this._active && this._origWrite) {
+            const origWrite = this._origWrite;
+            this._spinTimer = setInterval(() => {
+                this._spinFrame = (this._spinFrame + 1) % SteeringBar._SPIN_CHARS.length;
+                if (this._active)
+                    this._scheduleRedraw();
+            }, 80);
+        }
+        // Don't redraw immediately — the interceptor or spin timer will do it
+    }
+    /** Clear status text. */
+    clearStatus() {
+        this._statusText = '';
+        if (this._spinTimer) {
+            clearInterval(this._spinTimer);
+            this._spinTimer = null;
+        }
+        // Don't redraw — next stdout write or setStatus will handle it
+    }
+    /** Update displayed input text (called from readline _ttyWrite hook). */
+    setInput(text) {
+        this._inputText = text;
+        if (this._active && this._origWrite) {
+            // Keystroke — redraw immediately (no debounce for input responsiveness)
+            if (this._debounceTimer)
+                clearTimeout(this._debounceTimer);
+            this._debounceTimer = null;
+            if (this._barDrawn) {
+                this._origWrite('\x1b8\x1b[J');
+                this._barDrawn = false;
+            }
+            this._drawBar(this._origWrite);
+        }
+    }
+    /** Clear input after steer send. */
+    clearInput() {
+        this._inputText = '';
+        this._scheduleRedraw();
+    }
+    _drawBar(write) {
+        const cols = process.stdout.columns || 80;
+        const barWidth = Math.min(cols, 60);
+        const sep = chalk.dim('─'.repeat(barWidth));
+        // Status line (spinner + status text)
+        let statusLine = '';
+        if (this._statusText) {
+            const frame = SteeringBar._SPIN_CHARS[this._spinFrame];
+            statusLine = `\n${chalk.cyan(frame)} ${chalk.dim(this._statusText)}\x1b[K`;
+        }
+        // Input prompt
+        const prefix = chalk.dim(' [steer]') + chalk.yellow(' > ');
+        const prefixLen = 11;
+        const maxInput = cols - prefixLen - 1;
+        const display = this._inputText.length > maxInput
+            ? this._inputText.slice(-maxInput)
+            : this._inputText;
+        write('\x1b7'); // Save cursor position (end of content)
+        write(`${statusLine}\n${sep}\n${prefix}${display}\x1b[K`);
+        this._barDrawn = true;
+    }
+}