@aitherium/shell-cli 1.1.0 → 1.11.0

package/dist/renderer.js

@@ -6,13 +6,34 @@ import ora from 'ora';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
 import { homedir } from 'os';
+import { spawn } from 'child_process';
+import { getActiveConfig } from './config.js';
 // Configure marked for terminal rendering
 marked.use(markedTerminal({ reflowText: true, width: 80 }));
+/* ── Trace verbosity ─────────────────────────────────────────────
+ * FULL trace is ON by default: every pipeline stage (planning/MCTS,
+ * neurons, middleware, per-turn timings) prints a permanent line so the
+ * user can SEE what the system is doing on every turn without asking.
+ * Set AITHER_TRACE=quiet (or off/0/false) to collapse stages back into a
+ * single transient status line.
+ */
+export const TRACE_FULL = (() => {
+    const v = (process.env.AITHER_TRACE || '').toLowerCase().trim();
+    if (v === 'quiet' || v === 'off' || v === '0' || v === 'false' || v === 'none')
+        return false;
+    return true; // default: full trace
+})();
+/* ── OSC 8 terminal hyperlink ────────────────────────────────── */
+/** Wrap text in an OSC 8 clickable hyperlink for terminals that support it. */
+export function osc8Link(url, label) {
+    const text = label || url;
+    return `\x1b]8;;${url}\x1b\\${chalk.cyan.underline(text)}\x1b]8;;\x1b\\`;
+}
 /* ── Banner ─────────────────────────────────────────────────── */
 export function renderBanner(info) {
-    const version = 'v1.1.0';
+    const version = 'v1.11.0'; // keep in sync with package.json
     const title = `AitherShell ${version}`;
     let connected;
     if (info.genesisOnline === true) {
@@ -121,42 +142,136 @@ function stripWebCruft(text) {
  * and render as clickable OSC 8 terminal hyperlinks.
  */
 export function resolveImagePath(relativePath) {
-    const { homedir } = require('os');
-    const { resolve } = require('path');
+    // ESM module — use the top-level imports, NOT require() (which is undefined
+    // here and made renderMarkdown throw → raw ![](...) markdown leaked through).
     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;
+    const rel = relativePath.replace(/^\/api\/files\?path=/, '');
+    // If it's already an existing absolute path, keep it.
+    try {
+        if (/^([A-Za-z]:[/\\]|\/)/.test(rel) && existsSync(rel))
+            return rel;
+    }
+    catch { /* */ }
+    // Try known AitherOS roots (the Library is bind-mounted under <root>/AitherOS).
+    const roots = [
+        process.env.AITHER_ROOT,
+        'D:\\AitherOS-Fresh', // dev box repo root
+        resolve(home, 'AitherOS-Fresh'),
+        resolve(home, 'AitherOS'),
+    ].filter(Boolean);
+    for (const root of roots) {
+        for (const sub of ['AitherOS', '']) {
+            try {
+                const p = resolve(root, sub, rel);
+                if (existsSync(p))
+                    return p;
+            }
+            catch { /* */ }
         }
-        catch { }
     }
-    return resolve(relativePath);
+    return resolve(rel); // best-effort (may not exist) — caller can check
+}
+/** Strip OSC-8 hyperlink escapes (blessed/TUI can't render them → raw `]8;;`). */
+export function stripOsc8(text) {
+    // ESC ]8;;<url> ESC \  …label…  ESC ]8;; ESC \   →  keep just the label.
+    return text.replace(/\x1b\]8;;[^\x07\x1b]*(?:\x1b\\|\x07)/g, '');
+}
+/** The backend the shell is ACTUALLY connected to (local genesis, a remote
+ *  gateway/mcp, etc.) — image URLs must resolve against IT, not a hardcoded host. */
+function backendBase() {
+    const cfg = getActiveConfig();
+    const base = cfg?.genesisUrl
+        || process.env.AITHER_API_URL || process.env.AITHER_GENESIS_URL
+        || 'http://127.0.0.1:8001';
+    return String(base).replace(/\/+$/, '');
 }
 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)}`;
+        const base = backendBase();
+        const isLocalBackend = /(^|\/\/)(127\.0\.0\.1|localhost)\b/.test(base);
+        // If the raw path is already a full URL, keep it.
+        const isAbsUrl = /^https?:\/\//i.test(rawPath);
+        let url;
+        let shown;
+        // Only a LOCAL backend can have the file on THIS disk (bind-mounted
+        // Library). For a remote backend (gateway/mcp/…) the file lives there, so
+        // always link the backend's HTTP URL — never guess a local path.
+        const local = (!isAbsUrl && isLocalBackend) ? (() => {
+            try {
+                const c = resolveImagePath(rawPath);
+                return existsSync(c) ? c : null;
+            }
+            catch {
+                return null;
+            }
+        })() : null;
+        if (local) {
+            url = `file:///${local.replace(/\\/g, '/')}`;
+            shown = local;
+        }
+        else if (isAbsUrl) {
+            url = rawPath;
+            shown = rawPath;
+        }
+        else {
+            const p = rawPath.replace(/^\/api\/files\?path=/, '');
+            url = `${base}/api/files?path=${encodeURIComponent(p)}`;
+            shown = url;
+        }
+        const link = `\x1b]8;;${url}\x1b\\${chalk.cyan.underline(label)}\x1b]8;;\x1b\\`;
+        return `🖼 ${link}  ${chalk.dim(shown)}`;
     });
 }
+// Images already auto-opened this process, so we don't reopen on re-render.
+const _openedImages = new Set();
+/** Open a local image in the OS default viewer (detached). Best-effort. */
+export function openLocalImage(p) {
+    if (!p || _openedImages.has(p))
+        return;
+    try {
+        if (!existsSync(p))
+            return;
+    }
+    catch {
+        return;
+    }
+    _openedImages.add(p);
+    try {
+        const plat = process.platform;
+        if (plat === 'win32')
+            spawn('cmd', ['/c', 'start', '', p], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+        else if (plat === 'darwin')
+            spawn('open', [p], { detached: true, stdio: 'ignore' }).unref();
+        else
+            spawn('xdg-open', [p], { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch { /* viewer unavailable — the path is still shown */ }
+}
+/** Scan answer text for generated-image markdown and open any LOCAL ones in the
+ *  OS viewer (so the user actually SEES the image — the TUI can't render it
+ *  inline). Opt out with AITHER_AUTO_OPEN_IMAGES=0. */
+export function autoOpenImagesFromText(text) {
+    if (!text)
+        return;
+    const off = (process.env.AITHER_AUTO_OPEN_IMAGES || '').toLowerCase();
+    if (off === '0' || off === 'false' || off === 'off' || off === 'no')
+        return;
+    const re = /!\[[^\]]*\]\((?:\/api\/files\?path=)?([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const raw = m[1];
+        if (/^https?:\/\//i.test(raw))
+            continue; // remote — nothing local to open
+        try {
+            const c = resolveImagePath(raw);
+            if (existsSync(c))
+                openLocalImage(c);
+        }
+        catch { /* */ }
+    }
+}
 export function renderMarkdown(text) {
     try {
         let clean = text;
@@ -235,6 +350,20 @@ export function getSessionArtifacts() {
 export function clearSessionArtifacts() {
     _sessionArtifacts = [];
 }
+/** Register a locally-saved file as a session artifact (so /get + /artifacts find it). */
+export function addSessionArtifact(a) {
+    const filename = a.path.split(/[\\/]/).pop() || a.path;
+    _sessionArtifacts.push({
+        filename,
+        path: a.path,
+        size: a.size ?? 0,
+        language: a.language || 'image',
+        retrieve_cmd: `/get ${_sessionArtifacts.length + 1}`,
+        download_url: '',
+        timestamp: new Date().toISOString(),
+    });
+    return _sessionArtifacts.length;
+}
 export function createStreamRenderer(sessionId, prompt, steeringBar) {
     let spinner = null;
     let content = '';
@@ -244,8 +373,12 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
     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 contentDisplayed = false; // True when actual response text was written to stdout
     let tokensStarted = false; // Once true, spinner is permanently disabled for this session
+    let llmFired = false; // Set on llm_start — suppresses post-gen middleware even without token events
     let lastStage = ''; // Current pipeline stage — shown in heartbeat spinner
+    let eagerActive = false; // Eager streaming: multiple answer_segments this turn
+    let eagerSegments = 0; // Count of segments rendered
     // ── Session trace collection ──
     const traceEvents = [];
     const traceToolCalls = [];
@@ -323,8 +456,11 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     if (event.data.agent)
                         traceAgent = event.data.agent;
-                    if (event.data.model)
+                    // Skip the "auto"/"unknown" placeholder — the real model arrives in
+                    // llm_start / complete. Capturing it here is why the footer said "auto".
+                    if (event.data.model && event.data.model !== 'auto' && event.data.model !== 'unknown') {
                         traceModel = event.data.model;
+                    }
                     startSpinner(chalk.dim(`${event.data.agent || 'thinking'}...`));
                     break;
                 case 'thinking': {
@@ -392,8 +528,11 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     break;
                 }
                 case 'thinking_end': {
-                    // Clear any streaming line remnant
-                    process.stdout.write('\r\x1b[2K');
+                    // Only clear the streaming thinking line if we haven't started
+                    // writing answer tokens — otherwise we'd erase the answer.
+                    if (!tokensStarted && !contentDisplayed) {
+                        process.stdout.write('\r\x1b[2K');
+                    }
                     break;
                 }
                 case 'progress':
@@ -407,6 +546,8 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         'affect_start', 'prefire_start', 'facet_plan_start',
                         'plan_start', 'planner_start', 'planner_done',
                         'research_start',
+                        // Classification start
+                        'classify_start',
                         // IntentPlanner sub-phases
                         'decompose_start', 'tool_match', 'critique_start',
                         // Context assembly sub-phases
@@ -430,20 +571,67 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     break;
                 }
+                case 'answer_segment': {
+                    // Eager streaming: a new answer block (initial fast pass, or a
+                    // refinement once background enrichment lands). Print a header and
+                    // reset per-segment streaming state so tokens render cleanly.
+                    eagerActive = true;
+                    eagerSegments += 1;
+                    stopSpinner();
+                    const segKind = event.data.kind || 'initial';
+                    const segReason = event.data.reason ? chalk.dim(` (${event.data.reason})`) : '';
+                    if (hasOutput)
+                        process.stdout.write('\n');
+                    if (segKind === 'continuation') {
+                        log(chalk.cyan('  ↳ Continuing') + segReason);
+                    }
+                    else if (segKind === 'refinement') {
+                        log(chalk.cyan('  ↻ Refining') + segReason);
+                    }
+                    else {
+                        log(chalk.cyan('  💬 Initial') + segReason);
+                    }
+                    tokensStarted = false; // re-enter first-token path for this segment
+                    content = ''; // per-segment accumulator (final captured at complete)
+                    break;
+                }
+                case 'segment_end': {
+                    if (!content.endsWith('\n'))
+                        process.stdout.write('\n');
+                    break;
+                }
                 case 'token': {
                     stopSpinner();
-                    tokensStarted = true; // Permanently disable spinner for this response
+                    if (!tokensStarted) {
+                        tokensStarted = true; // Permanently disable spinner for this response
+                        // Clear any residual progress/thinking line before first token
+                        process.stdout.write('\r\x1b[2K');
+                        if (steeringBar?.active)
+                            steeringBar.enterTokenMode();
+                    }
                     const t = decodeHtmlEntities(event.data.t || '');
                     content += t;
                     process.stdout.write(t);
                     hasOutput = true;
                     tokenStreamed = true;
+                    contentDisplayed = true;
                     break;
                 }
                 case 'message':
                 case 'answer':
                 case 'final_answer': {
                     stopSpinner();
+                    // Eager streaming already rendered the answer as live segments —
+                    // the terminal `answer` event is just the canonical copy for
+                    // trace/getContent. Capture it, don't re-print.
+                    if (eagerActive) {
+                        content = event.data.answer || event.data.content || content;
+                        contentDisplayed = true;
+                        hasOutput = true;
+                        break;
+                    }
+                    // Clear any residual spinner/thinking line
+                    process.stdout.write('\r\x1b[2K');
                     const answer = event.data.response || event.data.answer || event.data.content || '';
                     if (answer) {
                         // Dedup: skip if already printed (AgentRuntime emits final_answer,
@@ -466,6 +654,7 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         if (!answer.endsWith('\n'))
                             process.stdout.write('\n');
                         hasOutput = true;
+                        contentDisplayed = true;
                     }
                     // Render interactive/display blocks in terminal
                     const blocks = event.data.render_blocks;
@@ -592,19 +781,26 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                 case 'done':
                 case 'complete': {
                     stopSpinner();
+                    if (steeringBar?.active)
+                        steeringBar.exitTokenMode();
                     // Only render content + timing once (engine + router can both emit 'complete')
                     if (completePrinted)
                         break;
                     completePrinted = true;
-                    if (!hasOutput && event.data.content) {
+                    if (!contentDisplayed && event.data.content) {
                         content = event.data.content;
+                        process.stdout.write('\r\x1b[2K');
                         process.stdout.write(renderMarkdown(wrapBareCode(content)));
                         hasOutput = true;
+                        contentDisplayed = true;
                     }
-                    else if (tokenStreamed) {
+                    else if (tokenStreamed && !eagerActive) {
                         // 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.
+                        // Skipped in eager mode: segments already streamed as plain text
+                        // and `content` only holds the last segment, so a markdown
+                        // re-render would duplicate / mangle the multi-segment output.
                         const wrapped = wrapBareCode(content);
                         if (wrapped !== content || content.includes('```')) {
                             process.stdout.write('\n');
@@ -613,19 +809,18 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     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`);
+                    autoOpenImagesFromText(content); // pop generated images in the OS viewer
+                    // Update trace vars from the authoritative complete event, then let
+                    // finish() print the SINGLE canonical footer. Printing a footer here
+                    // too caused the duplicate "[model \u00b7 ms \u00b7 agent]" + "[agent | model
+                    // | time]" lines the user saw.
+                    const _cm = event.data.model || event.data.model_used;
+                    if (_cm && _cm !== 'auto' && _cm !== 'unknown')
+                        traceModel = _cm;
                     if (event.data.agent)
-                        meta.push(event.data.agent);
-                    if (meta.length) {
-                        log(chalk.dim(`  [${meta.join(' \u00b7 ')}]`));
-                    }
+                        traceAgent = event.data.agent;
+                    if (event.data.turns_completed)
+                        traceTurns = event.data.turns_completed;
                     break;
                 }
                 case 'error':
@@ -639,6 +834,15 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     stopSpinner();
                     hasOutput = true; // Prevent "(no response)" — we already showed trace output
                     break;
+                case 'stream_interrupted':
+                    // Transport died mid-turn (backend/LB restart) — unlike a soft
+                    // timeout the connection is GONE, so say so instead of going silent.
+                    stopSpinner();
+                    log(chalk.yellow(`\n  ⚠ Stream interrupted — ${event.data.error || 'connection lost'}`));
+                    log(chalk.dim('  The backend connection dropped mid-turn; any answer above is partial. Resend to retry.'));
+                    traceErrors.push(`stream interrupted: ${event.data.error || 'connection lost'}`);
+                    hasOutput = true;
+                    break;
                 case 'heartbeat':
                 case 'keepalive': {
                     const elapsedMs = event.data.elapsed_ms || event.data.elapsed;
@@ -1066,8 +1270,11 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                 case 'llm_start': {
                     // From UCB: has model, prompt_tokens_est, has_tools
                     // From AgentRuntime: has turn, timestamp (minimal)
+                    llmFired = true;
                     const llmModel = event.data.model || 'auto';
-                    traceModel = llmModel;
+                    if (event.data.model && event.data.model !== 'auto' && event.data.model !== 'unknown') {
+                        traceModel = event.data.model;
+                    }
                     const promptTokens = event.data.prompt_tokens_est || 0;
                     const hasTools2 = event.data.has_tools ? ' + tools' : '';
                     const turnInfo = event.data.turn ? `Turn ${event.data.turn} · ` : '';
@@ -1083,6 +1290,8 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                 case 'llm_done':
                 case 'llm_end': {
                     stopSpinner();
+                    if (tokensStarted)
+                        break; // complete handler prints timing metadata
                     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';
@@ -1093,21 +1302,32 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                 }
                 case 'middleware_progress': {
                     const mwName = event.data.middleware || event.data.stage || 'middleware';
-                    const mwStatus = event.data.status || 'running';
                     const mwDetail = event.data.detail || '';
+                    const mwElapsed = event.data.elapsed_ms ? ` ${Math.round(event.data.elapsed_ms)}ms` : '';
                     lastStage = mwName;
-                    const mwIcon = mwStatus === 'complete' ? chalk.green('✓') : chalk.yellow('→');
-                    const detailStr = mwDetail ? chalk.dim(` (${mwDetail})`) : '';
+                    const mwLabel = `${mwName}${mwDetail ? ` (${mwDetail})` : ''}`;
+                    // FULL TRACE (default): print a permanent line for every pipeline
+                    // stage — even after the LLM fires — so the user sees exactly what
+                    // the system is doing and where the time goes, every turn.
+                    if (TRACE_FULL) {
+                        log(chalk.dim(`  ⚙ ${mwLabel}${mwElapsed}`));
+                        if (steeringBar?.active)
+                            steeringBar.setStatus(`${mwName}...`);
+                        break;
+                    }
+                    // QUIET mode: after LLM fires, suppress visible lines — bar status only.
+                    if (tokensStarted || llmFired) {
+                        if (steeringBar?.active)
+                            steeringBar.setStatus(`${mwName}...`);
+                        break;
+                    }
+                    // QUIET mode pre-generation: ONE transient status line instead of a
+                    // permanent line per middleware (avoids "→ planexecutor: running" spam).
                     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}...`);
+                        steeringBar.setStatus(`${mwLabel}...`);
                     }
                     else {
-                        stopSpinner();
-                        log(chalk.dim(`  ${mwIcon} ${mwName}: ${mwStatus}${detailStr}`));
-                        startSpinner(chalk.dim(`${mwName}...`));
+                        startSpinner(chalk.dim(`${mwLabel}...`));
                     }
                     break;
                 }
@@ -1181,6 +1401,7 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     const artCmd = event.data.retrieve_cmd || '';
                     const artLang = event.data.language || '';
                     const artPath = event.data.path || '';
+                    const artDownloadUrl = event.data.download_url || '';
                     // Track artifact in session store
                     _sessionArtifacts.push({
                         filename: artFile,
@@ -1188,14 +1409,15 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         size: artSize,
                         language: artLang,
                         retrieve_cmd: artCmd,
+                        download_url: artDownloadUrl,
                         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`));
-                    }
+                    const artSizeStr = artSize > 1024
+                        ? `${(artSize / 1024).toFixed(0)} KB`
+                        : `${artSize} bytes`;
+                    log(chalk.green.bold(`\n  📦 Artifact #${artIdx}: ${artFile} (${artSizeStr})`));
+                    log(chalk.cyan(`     /get ${artIdx}`) + chalk.dim(` to save to current directory`));
                     break;
                 }
                 // Pipeline stages that update spinner
@@ -1415,11 +1637,57 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     break;
                 }
+                case 'mcts_iteration': {
+                    // Live MCTS planning progress — shows the planner is actually
+                    // working instead of a silent "planexecutor" blackout.
+                    const mi = event.data.iteration ?? '?';
+                    const mt = event.data.total ?? '?';
+                    const mbv = typeof event.data.best_value === 'number' ? event.data.best_value.toFixed(3) : '?';
+                    const mms = event.data.elapsed_ms ? ` ${Math.round(event.data.elapsed_ms)}ms` : '';
+                    lastStage = `mcts ${mi}/${mt}`;
+                    if (TRACE_FULL) {
+                        log(chalk.dim(`  🌲 MCTS: iter ${mi}/${mt} · best=${mbv} · depth=${event.data.depth ?? '?'}${mms}`));
+                    }
+                    else if (steeringBar?.active) {
+                        steeringBar.setStatus(`mcts ${mi}/${mt}...`);
+                    }
+                    break;
+                }
+                case 'plan_phase': {
+                    const ppPhase = event.data.name || event.data.phase || 'phase';
+                    const ppMs = event.data.elapsed_ms ? ` ${Math.round(event.data.elapsed_ms)}ms` : '';
+                    const ppCand = event.data.candidates != null ? ` · ${event.data.candidates} candidate(s)` : '';
+                    const ppIter = event.data.iterations ? ` · ${event.data.iterations} iters` : '';
+                    lastStage = `plan: ${ppPhase}`;
+                    if (TRACE_FULL) {
+                        log(chalk.dim(`  📐 Plan phase: ${ppPhase}${ppMs}${ppCand}${ppIter}`));
+                    }
+                    else if (steeringBar?.active) {
+                        steeringBar.setStatus(`plan: ${ppPhase}...`);
+                    }
+                    break;
+                }
+                case 'plan_start': {
+                    const psTier = event.data.tier || '';
+                    const psTimeout = event.data.timeout_ms ? ` (budget ${Math.round(event.data.timeout_ms)}ms)` : '';
+                    lastStage = 'planning';
+                    if (TRACE_FULL) {
+                        log(chalk.dim(`  📐 Planning started${psTier ? `: ${psTier}` : ''}${psTimeout}`));
+                    }
+                    else if (steeringBar?.active) {
+                        steeringBar.setStatus('planning...');
+                    }
+                    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}`));
+                    // "timeout"/"no_plan" are normal — planning is optional enrichment,
+                    // the turn proceeds without a plan. Don't alarm the user.
+                    const pcBenign = pcStatus === 'timeout' || pcStatus === 'no_plan' || pcStatus === 'no_result';
+                    const pcIcon = pcBenign ? '○' : '✓';
+                    log(chalk.dim(`  ${pcIcon} Planning ${pcBenign ? `skipped (${pcStatus}) — proceeding without a plan` : pcStatus}`));
                     break;
                 }
                 case 'turn_progress': {
@@ -1433,6 +1701,48 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     break;
                 }
+                // ── Pipeline transparency events ──
+                case 'middleware_chain_complete': {
+                    const mwCount = event.data.count || 0;
+                    const mwMs = Math.round(event.data.total_ms || 0);
+                    log(chalk.dim(`  🔗 Pipeline: ${mwCount} stages, ${mwMs}ms`));
+                    break;
+                }
+                case 'context_flame_graph': {
+                    const neurons = event.data.neurons_fired || 0;
+                    const ctxTokens = event.data.total_tokens || 0;
+                    const quality = (event.data.quality_score || 0).toFixed(2);
+                    log(chalk.dim(`  🧠 Context: ${neurons} neurons, ${ctxTokens} tokens, quality=${quality}`));
+                    break;
+                }
+                case 'prefire_result': {
+                    if (event.data.tool) {
+                        log(chalk.dim(`  ⚡ Pre-fired: ${event.data.tool} (${event.data.chars || 0} chars)`));
+                    }
+                    else if (event.data.tools) {
+                        log(chalk.dim(`  ⚡ Pre-firing: ${event.data.tools.join(', ')}`));
+                    }
+                    break;
+                }
+                case 'context_eviction': {
+                    const evCount = event.data.evicted || 0;
+                    const evTokens = event.data.tokens_freed || 0;
+                    log(chalk.dim(`  🗑 Evicted: ${evCount} chunks, ${evTokens} tokens freed`));
+                    break;
+                }
+                case 'neuron_fire': {
+                    const nChunks = event.data.chunks_count || 0;
+                    const nTokens = event.data.total_tokens || 0;
+                    log(chalk.dim(`  🧬 Neurons: ${nChunks} chunks, ${nTokens} tokens`));
+                    break;
+                }
+                case 'notebook_export': {
+                    log(chalk.dim(`  📓 Notebook: ${event.data.notebook_id || ''}`));
+                    break;
+                }
+                case 'speculative_prefetch':
+                case 'outcome_recorded':
+                    break; // silent — internal bookkeeping
                 default: {
                     // Show content from unexpected events as fallback
                     if (event.data.content && !hasOutput) {
@@ -1441,10 +1751,24 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         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 || '';
+                    // Show meaningful unknown events so nothing is silently swallowed.
+                    // Pipeline substages are discriminated by `stage` (the wire type is
+                    // often 'pipeline'); label by stage and prefer a human field, else —
+                    // under full trace — show a compact scalar dump so telemetry like
+                    // llm_route / thinking_budget / reasoning_summary is never invisible.
+                    const d = event.data || {};
+                    const label = d.stage || event.type;
+                    let msg = d.message || d.reason || d.status || d.summary || d.detail || '';
+                    if (!msg && TRACE_FULL && (d.stage || event.type === 'pipeline')) {
+                        msg = Object.entries(d)
+                            .filter(([k, v]) => k !== 'type' && k !== 'stage' &&
+                            (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean'))
+                            .slice(0, 4)
+                            .map(([k, v]) => `${k}=${String(v).slice(0, 30)}`)
+                            .join(' ');
+                    }
                     if (msg && event.type !== 'debug') {
-                        log(chalk.dim(`  [${event.type}] ${String(msg).slice(0, 120)}`));
+                        log(chalk.dim(`  [${label}] ${String(msg).slice(0, 120)}`));
                     }
                     break;
                 }
@@ -1640,31 +1964,32 @@ export function formatTable(headers, rows) {
     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 ─────── */
+/* ── Steering Bar — fixed bottom bar via ANSI scroll regions ──── */
 /**
- * Keeps a visible input line at the bottom of the terminal while
- * stream output prints above.  Works on Windows Terminal (no ANSI
- * scroll regions).
+ * Keeps a fixed input bar at the bottom of the terminal while
+ * stream output scrolls above.  Uses DECSTBM (Set Scrolling Region)
+ * to physically separate the output area from the bar — no stdout
+ * monkey-patching, no erase/redraw races.
  *
- * 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
+ * Layout:
+ *   Rows 1 to (rows-3):  SCROLL REGION — all output, tokens, spinners
+ *   Row (rows-2):         Status spinner (e.g., "generation...")
+ *   Row (rows-1):         Separator line ────────
+ *   Row (rows):           [steer] > input
  *
- * The bar line looks like:
- *   ── [steer] > what the user is typing_
+ * Output cannot collide with the bar because they occupy different
+ * terminal regions.
  */
 export class SteeringBar {
     _active = false;
     _inputText = '';
     _statusText = '';
-    _origWrite = null;
-    _barDrawn = false;
-    _debounceTimer = null;
     _spinFrame = 0;
     _spinTimer = null;
+    _tokenMode = false;
+    _resizeHandler = null;
+    _resizeTimer = null;
+    _lastRows = 0; // Last geometry we drew the bar at (for resize cleanup)
     static _SPIN_CHARS = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
     get active() { return this._active; }
     get inputText() { return this._inputText; }
@@ -1674,90 +1999,90 @@ export class SteeringBar {
         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;
+        // Set up scroll region and draw initial bar
+        this._setupRegion();
+        // Handle terminal resize. Dragging a terminal edge fires many 'resize'
+        // events in a burst; redrawing the scroll-region bar on each one (against
+        // partially-reflowed geometry) is what left a stale duplicate green
+        // "aither >" prompt behind. Debounce, then do a CLEAN repaint that resets
+        // the scroll region and erases the OLD bar lines before redrawing.
+        this._resizeHandler = () => this._handleResize();
+        process.stdout.on('resize', this._resizeHandler);
+    }
+    /** Debounced, artifact-free resize repaint. */
+    _handleResize() {
+        if (!this._active || !process.stdout.isTTY)
+            return;
+        if (this._resizeTimer)
+            clearTimeout(this._resizeTimer);
+        this._resizeTimer = setTimeout(() => {
+            this._resizeTimer = null;
+            if (!this._active || !process.stdout.isTTY)
+                return;
+            // Clear the bar lines at their PREVIOUS positions (the source of the
+            // stale duplicate prompt) with the scroll region reset to full screen
+            // so we can address any row, then re-establish the region + redraw.
+            const oldRows = this._lastRows || (process.stdout.rows || 24);
+            let buf = '\x1b7\x1b[r'; // save cursor, reset scroll region to full
+            for (let r = Math.max(1, oldRows - 2); r <= oldRows; r++) {
+                buf += `\x1b[${r};1H\x1b[2K`; // clear each old bar line
             }
-            // 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);
+            buf += '\x1b8'; // restore cursor
+            process.stdout.write(buf);
+            this._setupRegion(); // recompute region for new geometry + redraw
+        }, 60);
     }
     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;
+        if (this._resizeTimer) {
+            clearTimeout(this._resizeTimer);
+            this._resizeTimer = null;
         }
-        // Restore stdout.write
-        if (this._origWrite) {
-            process.stdout.write = this._origWrite;
-            this._origWrite = null;
+        if (this._resizeHandler) {
+            process.stdout.removeListener('resize', this._resizeHandler);
+            this._resizeHandler = 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;
+        if (process.stdout.isTTY) {
+            const rows = process.stdout.rows || 24;
+            // Save cursor (in scroll region), clear the bottom 3 bar lines
+            let buf = '\x1b7';
+            for (let r = rows - 2; r <= rows; r++) {
+                buf += `\x1b[${r};1H\x1b[2K`;
             }
-            this._drawBar(w);
-        }, 16);
+            // Reset scroll region to full screen, restore cursor, move to new line
+            buf += '\x1b[r\x1b8\n';
+            process.stdout.write(buf);
+        }
+    }
+    /** Set scroll region and draw bar, preserving cursor position. */
+    _setupRegion() {
+        const rows = process.stdout.rows || 24;
+        const scrollEnd = Math.max(1, rows - 3);
+        // Save cursor, set scroll region, restore cursor — content stays put
+        process.stdout.write(`\x1b7\x1b[1;${scrollEnd}r\x1b8`);
+        this._lastRows = rows; // remember geometry for the next resize cleanup
+        this._drawBar();
     }
     /** 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;
+        if (!this._spinTimer && this._active) {
             this._spinTimer = setInterval(() => {
                 this._spinFrame = (this._spinFrame + 1) % SteeringBar._SPIN_CHARS.length;
                 if (this._active)
-                    this._scheduleRedraw();
+                    this._drawBar();
             }, 80);
         }
-        // Don't redraw immediately — the interceptor or spin timer will do it
+        this._drawBar();
     }
     /** Clear status text. */
     clearStatus() {
@@ -1766,47 +2091,64 @@ export class SteeringBar {
             clearInterval(this._spinTimer);
             this._spinTimer = null;
         }
-        // Don't redraw — next stdout write or setStatus will handle it
+        this._drawBar();
     }
     /** 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);
-        }
+        this._drawBar();
     }
     /** Clear input after steer send. */
     clearInput() {
         this._inputText = '';
-        this._scheduleRedraw();
+        this._drawBar();
+    }
+    enterTokenMode() {
+        this._tokenMode = true;
+        if (this._spinTimer) {
+            clearInterval(this._spinTimer);
+            this._spinTimer = null;
+        }
+    }
+    exitTokenMode() {
+        this._tokenMode = false;
     }
-    _drawBar(write) {
+    /**
+     * Draw the fixed bottom bar — single atomic write.
+     * Uses absolute positioning outside the scroll region, then restores
+     * cursor back into the scroll region.
+     */
+    _drawBar() {
+        if (!this._active || !process.stdout.isTTY)
+            return;
+        const rows = process.stdout.rows || 24;
         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 = '';
+        // Status line content
+        let statusContent = '';
         if (this._statusText) {
             const frame = SteeringBar._SPIN_CHARS[this._spinFrame];
-            statusLine = `\n${chalk.cyan(frame)} ${chalk.dim(this._statusText)}\x1b[K`;
+            statusContent = `${chalk.cyan(frame)} ${chalk.dim(this._statusText)}`;
         }
-        // Input prompt
-        const prefix = chalk.dim(' [steer]') + chalk.yellow(' > ');
-        const prefixLen = 11;
+        // Input line content
+        const prefix = chalk.dim(' aither') + chalk.yellow(' > ');
+        const prefixLen = 10;
         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;
+        const sep = chalk.dim('─'.repeat(barWidth));
+        // Build entire bar as one atomic buffer:
+        // Save cursor (in scroll region)
+        let buf = '\x1b7';
+        // Row rows-2: status line
+        buf += `\x1b[${rows - 2};1H\x1b[2K${statusContent}`;
+        // Row rows-1: separator
+        buf += `\x1b[${rows - 1};1H\x1b[2K${sep}`;
+        // Row rows: input prompt
+        buf += `\x1b[${rows};1H\x1b[2K${prefix}${display}`;
+        // Restore cursor (back to scroll region)
+        buf += '\x1b8';
+        process.stdout.write(buf);
     }
 }