@aitherium/shell-cli 1.11.1 → 1.12.1

package/dist/repl.js

@@ -602,7 +602,7 @@ export async function startRepl(client, config) {
             }
             // ── /jobs — built-in job management ──
             if (cmdName === 'jobs') {
-                handleJobsCommand(cmdArgs);
+                await handleJobsCommand(cmdArgs);
                 return;
             }
             // ── /relay — native group chat (humans + agents) ──
@@ -1046,9 +1046,47 @@ export async function startRepl(client, config) {
         }
     }
     /* ── /jobs command handler ──────────────────────────────────── */
-    function handleJobsCommand(args) {
+    async function handleJobsCommand(args) {
         const parts = args.trim().split(/\s+/);
         const sub = parts[0] || '';
+        // ── Cloud expeditions ──
+        if (sub === 'cloud' || sub === 'cjobs') {
+            const expId = parts[1] || '';
+            if (expId) {
+                // /jobs cloud <id>
+                await handleExpeditionDetail(client, expId);
+            }
+            else {
+                // /jobs cloud
+                await handleExpeditionList(client);
+            }
+            return;
+        }
+        // ── Steer & hint ──
+        if (sub === 'steer' || sub === 'hint') {
+            const expId = parts[1];
+            if (!expId) {
+                console.log(chalk.yellow(`  Usage: /jobs ${sub} <expedition-id> <message...>`));
+                return;
+            }
+            const message = parts.slice(2).join(' ');
+            if (!message) {
+                console.log(chalk.yellow(`  Usage: /jobs ${sub} <expedition-id> <message...>`));
+                return;
+            }
+            await handleExpeditionSteer(client, expId, message, sub === 'hint' ? 'hint' : 'append');
+            return;
+        }
+        // ── Watch ──
+        if (sub === 'watch') {
+            const expId = parts[1];
+            if (!expId) {
+                console.log(chalk.yellow('  Usage: /jobs watch <expedition-id>'));
+                return;
+            }
+            await handleExpeditionWatch(client, expId);
+            return;
+        }
         // /jobs cancel <id>
         if (sub === 'cancel' || sub === 'kill') {
             const id = Number(parts[1]);
@@ -1076,19 +1114,175 @@ export async function startRepl(client, config) {
             console.log(formatJobOutput(job));
             return;
         }
-        // /jobs — list all
+        // /jobs — list all local + help
         const allJobs = listJobs();
         if (allJobs.length === 0) {
-            console.log(chalk.dim('  No background jobs.'));
-            return;
+            console.log(chalk.dim('  No local background jobs.'));
         }
-        console.log(chalk.bold('\n  Background Jobs\n'));
-        for (const job of allJobs) {
-            console.log(formatJobLine(job));
+        else {
+            console.log(chalk.bold('\n  Local Background Jobs\n'));
+            for (const job of allJobs) {
+                console.log(formatJobLine(job));
+            }
         }
-        console.log(chalk.dim(`\n  /jobs <id>         View output`));
-        console.log(chalk.dim(`  /jobs cancel <id>  Cancel a running job`));
         console.log();
+        console.log(chalk.bold('  Commands\n'));
+        console.log(chalk.dim('  Local jobs:'));
+        console.log(`    ${chalk.cyan('/jobs')}              List local background jobs`);
+        console.log(`    ${chalk.cyan('/jobs <id>')}         View job output`);
+        console.log(`    ${chalk.cyan('/jobs cancel <id>')}  Cancel a running job`);
+        console.log();
+        console.log(chalk.dim('  Cloud expeditions (durable):'));
+        console.log(`    ${chalk.cyan('/jobs cloud')}         List expeditions`);
+        console.log(`    ${chalk.cyan('/jobs cloud <id>')}    View expedition details`);
+        console.log(`    ${chalk.cyan('/jobs steer <id> msg')} Send message to expedition`);
+        console.log(`    ${chalk.cyan('/jobs hint <id> msg')}  Send invisible hint to expedition`);
+        console.log(`    ${chalk.cyan('/jobs watch <id>')}    Watch expedition stream live`);
+        console.log();
+    }
+    /* ── Expedition helpers ────────────────────────────────────── */
+    async function handleExpeditionList(client) {
+        try {
+            const result = await client.listExpeditions();
+            if (!result || result.error) {
+                console.log(chalk.red(`  Error: ${result?.error || 'Failed to list expeditions'}`));
+                return;
+            }
+            const expeditions = result.expeditions || [];
+            if (!expeditions.length) {
+                console.log(chalk.dim('  No expeditions.'));
+                return;
+            }
+            console.log(chalk.bold('\n  Cloud Expeditions (Durable Jobs)\n'));
+            // Format as a table: ID | Status | Title | Owner
+            const headers = ['ID', 'Status', 'Title', 'Owner'];
+            const rows = expeditions.map((exp) => [
+                exp.id.slice(0, 8),
+                formatExpeditionStatus(exp.status),
+                (exp.title || '').slice(0, 40),
+                exp.owner || 'unknown',
+            ]);
+            // Simple table format
+            const maxLens = [8, 12, 40, 15];
+            console.log(`  ${headers.map((h, i) => h.padEnd(maxLens[i])).join(' ')}`);
+            console.log(`  ${headers.map(() => '─'.repeat(10)).join(' ')}`);
+            for (const row of rows) {
+                console.log(`  ${row.map((c, i) => String(c).padEnd(maxLens[i])).join(' ')}`);
+            }
+            console.log(chalk.dim(`\n  /jobs cloud <id>  View expedition details`));
+            console.log();
+        }
+        catch (err) {
+            console.log(chalk.red(`  Error: ${err.message}`));
+        }
+    }
+    async function handleExpeditionDetail(client, expId) {
+        try {
+            const status = await client.getExpeditionStatus(expId);
+            if (!status || status.error) {
+                console.log(chalk.red(`  Expedition not found: ${expId}`));
+                return;
+            }
+            const tasks = await client.getExpeditionTasks(expId);
+            const taskList = tasks?.tasks || [];
+            console.log(chalk.bold(`\n  Expedition: ${expId}\n`));
+            console.log(`  Status: ${formatExpeditionStatus(status.status || 'unknown')}`);
+            if (status.title)
+                console.log(`  Title:  ${status.title}`);
+            if (status.owner)
+                console.log(`  Owner:  ${status.owner}`);
+            if (status.created_at)
+                console.log(`  Created: ${new Date(status.created_at).toLocaleString()}`);
+            if (taskList.length > 0) {
+                console.log(chalk.bold('\n  Tasks\n'));
+                for (const task of taskList) {
+                    const icon = task.status === 'completed' ? chalk.green('✓') : task.status === 'failed' ? chalk.red('✗') : chalk.blue('•');
+                    const title = task.title || task.id.slice(0, 8);
+                    console.log(`    ${icon} ${title.padEnd(30)} ${chalk.dim(task.status)}`);
+                    if (task.result_summary) {
+                        const summary = typeof task.result_summary === 'string'
+                            ? task.result_summary
+                            : JSON.stringify(task.result_summary, null, 2);
+                        const lines = summary.split('\n').slice(0, 5);
+                        for (const line of lines) {
+                            console.log(`      ${chalk.dim(line)}`);
+                        }
+                        if (summary.split('\n').length > 5) {
+                            console.log(`      ${chalk.dim('...')}`);
+                        }
+                    }
+                    if (task.error) {
+                        console.log(`      ${chalk.red(task.error)}`);
+                    }
+                }
+            }
+            console.log();
+        }
+        catch (err) {
+            console.log(chalk.red(`  Error: ${err.message}`));
+        }
+    }
+    async function handleExpeditionSteer(client, expId, message, action) {
+        try {
+            const result = await client.steerExpedition(expId, message, action);
+            if (!result || result.error) {
+                console.log(chalk.red(`  Error: ${result?.error || 'Failed to steer expedition'}`));
+                return;
+            }
+            const verb = action === 'hint' ? 'hint sent' : 'message sent';
+            console.log(chalk.green(`  ✓ ${verb} to expedition ${result.expedition_id}`));
+            refreshPrompt();
+        }
+        catch (err) {
+            console.log(chalk.red(`  Error: ${err.message}`));
+        }
+    }
+    async function handleExpeditionWatch(client, expId) {
+        try {
+            console.log(chalk.cyan(`  Watching expedition ${expId}... (Ctrl+C to stop)\n`));
+            let eventCount = 0;
+            for await (const event of client.streamExpeditionEvents(expId)) {
+                eventCount++;
+                if (event.type === 'error') {
+                    console.log(chalk.red(`  Error: ${event.data.error}`));
+                    break;
+                }
+                // Print event summaries
+                const ts = new Date().toLocaleTimeString();
+                const typeIcon = event.type === 'EXPEDITION_COMPLETED' ? chalk.green('✓')
+                    : event.type === 'EXPEDITION_FAILED' ? chalk.red('✗')
+                        : '•';
+                console.log(`  ${ts} ${typeIcon} ${event.type}`);
+                if (event.data.message) {
+                    console.log(`    ${chalk.dim(event.data.message)}`);
+                }
+                if (event.type === 'EXPEDITION_COMPLETED' || event.type === 'EXPEDITION_FAILED') {
+                    console.log(chalk.cyan(`\n  Expedition ${event.data.status || 'done'}`));
+                    break;
+                }
+            }
+            if (eventCount === 0) {
+                console.log(chalk.yellow('  No events received (expedition may not exist or is already done).'));
+            }
+        }
+        catch (err) {
+            if (err.name === 'AbortError' || err.message?.includes('abort')) {
+                console.log(chalk.yellow('\n  Watch cancelled.'));
+            }
+            else {
+                console.log(chalk.red(`  Error: ${err.message}`));
+            }
+        }
+    }
+    function formatExpeditionStatus(status) {
+        const normalized = (status || '').toLowerCase();
+        if (normalized === 'completed' || normalized === 'done')
+            return chalk.green(status);
+        if (normalized === 'failed' || normalized === 'error')
+            return chalk.red(status);
+        if (normalized === 'running' || normalized === 'active')
+            return chalk.blue(status);
+        return chalk.yellow(status);
     }
     /* ── Background forge launcher ──────────────────────────────── */
     function launchBgForge(client, args) {

package/dist/status-banner.js

@@ -13,14 +13,34 @@
  * connect banner and the TUI share one implementation.
  */
 import chalk from 'chalk';
+/** Loopback/private hosts serve the internal self-signed CA. Bun's `fetch`
+ *  ignores NODE_EXTRA_CA_CERTS (set in main.ts), so an https probe to an internal
+ *  service — notably Identity at :8115, which is https-ONLY (http → 400) — fails
+ *  cert validation and gets false-flagged DOWN even though it's up. Health probes
+ *  carry no secrets, so accept the internal cert for private hosts; PUBLIC remote
+ *  endpoints (idp/gateway, real valid certs) keep strict TLS validation. */
+function insecureTlsFor(url) {
+    try {
+        const h = new URL(url).hostname;
+        const isPrivate = h === 'localhost' || h === '127.0.0.1' || h === '::1' ||
+            /^10\./.test(h) || /^192\.168\./.test(h) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+            h.endsWith('.local') || h.endsWith('.internal');
+        // `tls` is Bun's per-request option (the shipped binary is Bun-compiled);
+        // Node's fetch ignores it harmlessly.
+        return isPrivate ? { tls: { rejectUnauthorized: false } } : {};
+    }
+    catch {
+        return {};
+    }
+}
 /** Probe a health endpoint, tolerating http↔https and a single cold-start miss. */
 export async function probeHealth(url, timeoutMs = 4000) {
     const tryFetch = async (u) => {
         try {
             const r = await fetch(u, {
                 signal: AbortSignal.timeout(timeoutMs),
-                // @ts-ignore — Node 18+ supports this for self-signed certs
-                ...(u.startsWith('https') ? { dispatcher: undefined } : {}),
+                ...insecureTlsFor(u),
             });
             return r.ok;
         }

package/dist/tui/controller.js

@@ -16,6 +16,7 @@ export function createTuiRenderer(surface, sessionId, prompt) {
     let completePrinted = false;
     let terminalSeen = false; // complete/error/timeout/interrupt reached us
     let answerCheckpoint = null; // OUTPUT offset where the answer text begins
+    let pendingFollowups = []; // stashed on suggested_followups; rendered AFTER complete
     const traceEvents = [];
     const toolCalls = [];
     const thinking = [];
@@ -145,6 +146,16 @@ export function createTuiRenderer(surface, sessionId, prompt) {
                         // (replaceOutputFrom) instead of leaving the weak first pass on screen.
                         // Matches renderer.ts (the plain REPL) which does `content = data.answer`.
                         content = String(text);
+                        // If this eager segment printed a header ("💬 Initial …") but never
+                        // streamed any tokens (the engine returned the answer as one event,
+                        // e.g. the search fastpath), show it NOW rather than waiting for
+                        // 'complete' — an interrupted/timed-out stream would otherwise leave
+                        // the user staring at just the preamble. 'complete' re-renders via
+                        // replaceOutputFrom(answerCheckpoint).
+                        if (!tokenStreamed && answerCheckpoint == null) {
+                            answerCheckpoint = surface.markCheckpoint();
+                            surface.appendOutput(String(text));
+                        }
                     }
                     break;
                 }
@@ -259,10 +270,36 @@ export function createTuiRenderer(surface, sessionId, prompt) {
                     }
                     const ms = d.duration_ms != null ? `${(Number(d.duration_ms) / 1000).toFixed(1)}s` : '';
                     surface.outputLine(chalk.dim(`── ${[agent, model, ms].filter(Boolean).join(' · ')}`));
+                    // Follow-up chips AFTER the answer (complete just rewrote the answer
+                    // region via replaceOutputFrom, so they couldn't be printed earlier).
+                    if (pendingFollowups.length) {
+                        surface.outputLine(chalk.dim('  Next →'));
+                        pendingFollowups.forEach((t, i) => surface.outputLine('  ' + chalk.cyan(`[${i + 1}]`) + ' ' + chalk.dim(String(t))));
+                        surface.setPendingFollowups(pendingFollowups); // enable digit-select for next input
+                    }
                     autoOpenImagesFromText(content); // pop generated images in the OS viewer
                     surface.finishTraceTurn('done');
                     break;
                 }
+                case 'suggested_followups': {
+                    // Stash now; render in 'complete' (after the answer is finalised).
+                    const items = Array.isArray(d.followups) ? d.followups.map((x) => String(x)) : [];
+                    if (items.length)
+                        pendingFollowups = items;
+                    break;
+                }
+                case 'notebook_ready': {
+                    // A clarified plan was turned into a notebook. formatTrace drops this
+                    // (no message/stage field), so surface the id or the user never knows.
+                    const id = String(d.notebook_id || d.plan_id || '').trim();
+                    surface.outputLine(chalk.cyan(`  📓 Notebook ready${id ? `: ${id}` : ''}`));
+                    break;
+                }
+                case 'stream_warning':
+                    // 60s+ of stream silence (e.g. reasoning model cold-start). Reassure
+                    // the user the turn isn't dead.
+                    surface.traceLine(chalk.yellow(`  ⏳ ${d.message || 'still working — model may be warming up…'}`));
+                    break;
                 case 'heartbeat':
                 case 'keepalive':
                 case 'debug':

package/dist/tui/repl-tui.js

@@ -10,7 +10,7 @@
  * for those; everything else runs in-pane.
  */
 import { execSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import chalk from 'chalk';
 import { setActiveConfig } from '../config.js';
@@ -21,6 +21,9 @@ import { collectArgs } from '../interactive.js';
 import { gatherStatus, formatStatusLines } from '../status-banner.js';
 import { setJobNotifier, listJobs, getJob, cancelJob, runningCount, launchChatJob, launchForgeJob, launchSwarmJob, launchCommandJob, formatJobLine, formatJobOutput, } from '../jobs.js';
 import { configureRemoteSync, recordTurn, loadSession, buildContextSummary } from '../session-store.js';
+import { openLocalImage } from '../renderer.js';
+import { loadDoc, renderDocLines, resolveDocPath } from '../doc-view.js';
+import { imageToAnsi, imageDimensions } from '../image-preview.js';
 import { createTuiScreen } from './screen.js';
 import { createTuiRenderer } from './controller.js';
 import { setTuiActive } from '../crash-reporter.js';
@@ -106,6 +109,11 @@ export async function startTuiRepl(client, config) {
     let histIdx = history.length;
     let activeAbort = null;
     let processing = false;
+    // Type-ahead queue: messages typed while a turn is streaming. Run as fresh
+    // turns the instant the current one finishes (Claude-Code style) instead of
+    // being dropped into a steer that oneshot/trivial turns silently discard.
+    let queuedInputs = [];
+    let draining = false;
     let sigintCount = 0;
     let sigintTimer = null;
     let gpuTag = '';
@@ -295,8 +303,13 @@ export async function startTuiRepl(client, config) {
         }
         sigintCount++;
         if (sigintCount >= 2) {
+            const q = queuedInputs.length;
             setTuiActive(null);
             surface.destroy();
+            // Write AFTER destroy so it lands in the restored terminal, not the
+            // torn-down blessed screen — otherwise the user never sees it.
+            if (q)
+                process.stderr.write(`\n⚠ Discarded ${q} queued message(s).\n`);
             process.exit(0);
         }
         surface.setStatus('Ctrl+C again to exit');
@@ -387,18 +400,54 @@ export async function startTuiRepl(client, config) {
                 relayStatus('sent · agents may reply…');
             return;
         }
-        // Steer an active stream.
+        // A turn is in flight. cancel/stop/abort interrupt it; anything else is
+        // queued and run as a fresh turn the moment this one finishes. (The old
+        // fire-and-forget steer was silently dropped on oneshot/trivial turns —
+        // which is every plain question — so the message just vanished.)
         if (activeAbort && processing) {
             const lower = clean.toLowerCase();
             if (lower === 'cancel' || lower === 'stop' || lower === '@abort') {
                 onInterrupt();
                 return;
             }
-            surface.traceLine(chalk.yellow(`  🔄 steer: ${clean}`));
-            client.steer(config.sessionId, clean, 'append').catch(() => { });
+            queuedInputs.push(clean);
+            surface.traceLine(chalk.cyan(`  ⏳ queued (${queuedInputs.length}) — sends after this turn`));
             return;
         }
-        await runChat(clean, explicitBg);
+        // Bare digit (1-9) → expand to the Nth follow-up suggestion from the last turn.
+        const _pick = clean.match(/^([1-9])$/);
+        if (_pick) {
+            const fups = surface.getPendingFollowups();
+            const idx = parseInt(_pick[1], 10) - 1;
+            if (idx >= 0 && idx < fups.length) {
+                const chosen = fups[idx];
+                surface.setPendingFollowups([]); // consume
+                surface.outputLine(chalk.dim(`  → ${chosen}`));
+                await runChatDraining(chosen, explicitBg);
+                return;
+            }
+        }
+        surface.setPendingFollowups([]); // any new message invalidates last turn's chips
+        await runChatDraining(clean, explicitBg);
+    }
+    /** Run a chat turn, then drain any messages the user typed while it streamed,
+     *  running each as its own turn in order. The `draining` guard keeps two
+     *  rapid submits from spinning up overlapping drain loops. */
+    async function runChatDraining(input, bg = false) {
+        await runChat(input, bg);
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (queuedInputs.length && !processing) {
+                const next = queuedInputs.shift();
+                surface.outputLine(chalk.green('› ') + chalk.dim('(queued) ') + next);
+                await runChat(next, false);
+            }
+        }
+        finally {
+            draining = false;
+        }
     }
     function showHelp() {
         surface.outputLine(chalk.bold('Keys: ') + chalk.dim('Edit: ←/→ move · Ctrl+A/E line start/end · Ctrl+W del word · Ctrl+U/K kill · Home/End (empty line=scroll) | Panes: wheel/PgUp scroll · Ctrl+←/→ resize split · Ctrl+T trace · Ctrl+E expand all · click thread | Ctrl+C abort/exit · Tab complete'));
@@ -424,9 +473,76 @@ export async function startTuiRepl(client, config) {
         }
         surface.focusInput();
     }
-    function handleJobs(args) {
+    async function handleJobs(args) {
         const parts = args.trim().split(/\s+/);
         const sub = parts[0] || '';
+        // ── Cloud (durable expedition) jobs — mirror the classic REPL surface ──
+        if (sub === 'cloud') {
+            const expId = parts[1];
+            if (!expId) {
+                const result = await client.listExpeditions();
+                if (!result || result.error) {
+                    surface.outputLine(chalk.red(`  Error: ${result?.error || 'Failed to list expeditions'}`));
+                    return;
+                }
+                const exps = result.expeditions || [];
+                if (!exps.length) {
+                    surface.outputLine(chalk.dim('  No cloud expeditions.'));
+                    return;
+                }
+                surface.outputLine(chalk.bold('  Cloud Expeditions (Durable Jobs)'));
+                for (const e of exps) {
+                    surface.outputLine(`  ${chalk.bold(String(e.id).slice(0, 8))}  ${e.status || '?'}  ${(e.title || '').slice(0, 44)}`);
+                }
+                surface.outputLine(chalk.dim('  /jobs cloud <id> · /jobs steer <id> <msg> · /jobs watch <id>'));
+                return;
+            }
+            const status = await client.getExpeditionStatus(expId);
+            if (!status || status.error) {
+                surface.outputLine(chalk.red(`  Expedition not found: ${expId}`));
+                return;
+            }
+            surface.outputLine(`  ${chalk.bold(expId)}  status: ${status.status || '?'}`);
+            const tasks = await client.getExpeditionTasks(expId);
+            for (const t of (tasks?.tasks || [])) {
+                const out = (t.result_summary || t.error || '').slice(0, 500);
+                surface.outputLine(`  • ${t.title || t.id}: ${t.status}${out ? `\n    ${out}` : ''}`);
+            }
+            return;
+        }
+        if (sub === 'steer' || sub === 'hint') {
+            const expId = parts[1];
+            const msg = parts.slice(2).join(' ');
+            if (!expId || !msg) {
+                surface.outputLine(chalk.yellow(`Usage: /jobs ${sub} <id> <message>`));
+                return;
+            }
+            const r = await client.steerExpedition(expId, msg, sub === 'hint' ? 'hint' : 'append');
+            surface.outputLine(r?.ok ? chalk.green(`  Steered ${expId} (${sub}).`) : chalk.red(`  Steer failed: ${r?.error || r?.detail || 'unknown'}`));
+            return;
+        }
+        if (sub === 'watch') {
+            const expId = parts[1];
+            if (!expId) {
+                surface.outputLine(chalk.yellow('Usage: /jobs watch <id>'));
+                return;
+            }
+            surface.outputLine(chalk.dim(`  Watching ${expId}…`));
+            try {
+                for await (const ev of client.streamExpeditionEvents(expId)) {
+                    const d = ev.data || {};
+                    const line = d.message || d.error || ev.type;
+                    if (line)
+                        surface.outputLine(`  [${ev.type}] ${line}`);
+                    if (ev.type === 'error' || d.status === 'completed' || d.status === 'failed')
+                        break;
+                }
+            }
+            catch (err) {
+                surface.outputLine(chalk.red(`  Watch error: ${err.message}`));
+            }
+            return;
+        }
         if (sub === 'cancel' || sub === 'kill') {
             const id = Number(parts[1]);
             if (!id) {
@@ -625,6 +741,89 @@ export async function startTuiRepl(client, config) {
         surface.outputLine(chalk.dim('  📡 Left relay — back to agent chat.'));
         idleStatus();
     }
+    /** `/view <path>` — open a file in the in-TUI document viewer. Markdown/code/
+     *  text render in a full-screen scrollable overlay; PNG images render inline as
+     *  half-blocks on the real terminal (via runDetached, for true 24-bit colour);
+     *  other image formats open in the OS viewer. */
+    async function handleView(args) {
+        const path = args.trim();
+        if (!path) {
+            surface.outputLine(chalk.yellow('Usage: /view <file>') + chalk.dim('  — markdown, code, text, or a PNG image'));
+            surface.focusInput();
+            return;
+        }
+        const doc = loadDoc(path);
+        if (doc.kind === 'missing' || doc.kind === 'binary') {
+            surface.outputLine(chalk.yellow(`  ${doc.note || doc.kind}: `) + chalk.dim(doc.absPath));
+            surface.focusInput();
+            return;
+        }
+        if (doc.kind === 'image') {
+            const cols = Math.max(20, (process.stdout.columns || 100) - 4);
+            const ansi = imageToAnsi(doc.absPath, Math.min(cols, 120), 50);
+            if (ansi) {
+                const dims = imageDimensions(doc.absPath);
+                await surface.runDetached(`view ${doc.title}`, () => {
+                    process.stdout.write(chalk.dim(`  ${doc.title}${dims ? `  ${dims.width}×${dims.height}` : ''}\n\n`));
+                    for (const l of ansi)
+                        process.stdout.write('  ' + l + '\n');
+                });
+                idleStatus();
+            }
+            else {
+                openLocalImage(doc.absPath);
+                surface.outputLine(chalk.dim(`  🖼  ${doc.ext.replace('.', '').toUpperCase()} opened in OS viewer (only PNG renders inline): `) + chalk.dim(doc.absPath));
+                surface.focusInput();
+            }
+            return;
+        }
+        const width = (process.stdout.columns || 100);
+        const { lines, fallbackOpenPath } = renderDocLines(doc, width);
+        if (fallbackOpenPath)
+            openLocalImage(fallbackOpenPath);
+        await surface.showViewer(doc.title, lines);
+        idleStatus();
+    }
+    /** `/edit <path>` — open a file in the in-TUI editor (notepad/vim-lite). Opens
+     *  an empty buffer for a non-existent path (create-on-save). Refuses image/
+     *  binary files. Ctrl+S writes the file; Esc/Ctrl+Q closes. */
+    async function handleEdit(args) {
+        const path = args.trim();
+        if (!path) {
+            surface.outputLine(chalk.yellow('Usage: /edit <file>') + chalk.dim('  — opens the in-shell editor (^S save · ^Q quit)'));
+            surface.focusInput();
+            return;
+        }
+        const absPath = resolveDocPath(path);
+        let initial = '';
+        if (existsSync(absPath)) {
+            const doc = loadDoc(path);
+            if (doc.kind === 'image' || doc.kind === 'binary') {
+                surface.outputLine(chalk.yellow(`  cannot edit a ${doc.kind} file: `) + chalk.dim(absPath));
+                surface.focusInput();
+                return;
+            }
+            initial = doc.text ?? '';
+        }
+        else {
+            surface.outputLine(chalk.dim(`  new file: ${absPath}`));
+        }
+        const title = absPath.split(/[/\\]/).pop() || path;
+        await surface.showEditor(title, initial, async (text) => {
+            try {
+                const dir = dirname(absPath);
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                writeFileSync(absPath, text, 'utf-8');
+                return null;
+            }
+            catch (e) {
+                return e?.message || 'write failed';
+            }
+        });
+        surface.outputLine(chalk.dim(`  edited ${absPath}`));
+        idleStatus();
+    }
     async function runCommand(input, bg = false) {
         const sp = input.indexOf(' ');
         const name = sp > 0 ? input.slice(1, sp) : input.slice(1);
@@ -643,8 +842,16 @@ export async function startTuiRepl(client, config) {
             showHelp();
             return;
         }
+        if (name === 'view' || name === 'open' || name === 'cat') {
+            await handleView(args);
+            return;
+        }
+        if (name === 'edit' || name === 'e' || name === 'nano') {
+            await handleEdit(args);
+            return;
+        }
         if (name === 'jobs') {
-            handleJobs(args);
+            await handleJobs(args);
             return;
         }
         if (name === 'relay') {
@@ -774,7 +981,9 @@ export async function startTuiRepl(client, config) {
                     surface.traceLine(chalk.yellow('  ⚠ LLM pool busy (0 slots) — sending anyway'));
             }
         }
-        catch { /* */ }
+        catch {
+            surface.traceLine(chalk.yellow('  ⚠ pre-flight check failed (backend slow or down) — sending anyway'));
+        }
         surface.outputLine(chalk.green('› ') + input);
         surface.setStatus('working…');
         // Open a fresh, collapsible trace thread for this turn (older turns collapse).
@@ -842,8 +1051,11 @@ export async function startTuiRepl(client, config) {
                         aborted = true;
                         surface.outputLine(chalk.dim('  (interrupted)'));
                     }
-                    else
-                        surface.outputLine(chalk.red(`  Error: ${err?.message || err}`));
+                    else {
+                        // First line only, bounded — never spray a raw stack/JSON at the user.
+                        const raw = typeof err?.message === 'string' ? err.message : String(err);
+                        surface.outputLine(chalk.red(`  Error: ${raw.split('\n')[0].slice(0, 200)}`));
+                    }
                     renderer.finish(aborted);
                     break;
                 }