@aitherium/shell-cli 1.1.0 → 1.11.0

package/dist/tui/repl-tui.js

@@ -0,0 +1,898 @@
+/**
+ * Full-featured interactive REPL on the blessed 3-pane surface.
+ *
+ * Feature parity with the readline REPL (repl.ts): chat streaming + steering,
+ * @agent routing, background jobs (`&`, /jobs, auto-bg forge/swarm), a native
+ * command picker (`/`), Tab completion, clarification-gate auto-resolve,
+ * !shell, history, Strata posting, remote session sync + RLM continuity,
+ * GPU status tag and a pre-flight readiness check. Interactive @inquirer
+ * pickers inside command handlers don't work under blessed — use AITHER_TUI=0
+ * for those; everything else runs in-pane.
+ */
+import { execSync } from 'node:child_process';
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import chalk from 'chalk';
+import { setActiveConfig } from '../config.js';
+import { getCommand, getCommandNames } from '../commands.js';
+import { getCommandRegistry } from '../command-registry.js';
+import { loadAgentNames, resolveAgentMention, completer, refreshCommandCompletions, SUBCOMMAND_DEFS, } from '../completions.js';
+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 { createTuiScreen } from './screen.js';
+import { createTuiRenderer } from './controller.js';
+import { setTuiActive } from '../crash-reporter.js';
+import { RelayClient, resolveRelayUrl } from '../relay.js';
+const AUTO_BG_COMMANDS = new Set(['forge', 'swarm']);
+const STRATEGY_TRIGGERS = new Set([
+    'think', 'reason', 'research', 'council', 'deliberate', 'swarm', 'plan',
+    'agentic', 'compete', 'debug', 'troubleshoot', 'investigate', 'quick',
+    'code', 'internal', 'personal', 'chat', 'companion', 'talk', 'story', 'saga',
+    'narrative', 'appforge', 'build', 'redteam', 'pentest', 'security', 'hack',
+]);
+const DEEP_TRIGGERS = new Set([
+    'think', 'reason', 'research', 'council', 'agentic', 'deliberate', 'debug',
+    'investigate', 'swarm',
+]);
+function loadHistory(file) {
+    if (!file || !existsSync(file))
+        return [];
+    try {
+        return readFileSync(file, 'utf8').split('\n').map(l => l.trim()).filter(Boolean).slice(-500);
+    }
+    catch {
+        return [];
+    }
+}
+function saveHistory(file, line) {
+    if (!file)
+        return;
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, line + '\n');
+    }
+    catch { /* */ }
+}
+function stringify(a) {
+    if (typeof a === 'string')
+        return a;
+    if (a instanceof Error)
+        return a.message;
+    try {
+        return JSON.stringify(a);
+    }
+    catch {
+        return String(a);
+    }
+}
+function sumTokens(events) {
+    let n = 0;
+    for (const e of events)
+        if (e.type === 'llm_done' || e.type === 'llm_end')
+            n += Number(e.data?.tokens_used || e.data?.tokens || 0);
+    return n;
+}
+async function postToStrata(client, profile) {
+    const strataUrl = client.baseUrl.replace(/:\d+$/, ':8136');
+    await fetch(`${strataUrl}/api/v1/ingest/ide-session`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            source: 'aither-shell', session_id: profile.session_id, prompt: profile.prompt,
+            model: profile.model, agent: profile.agent, event_count: profile.event_count,
+            tool_calls: profile.tool_calls.map(t => t.name), errors: profile.errors,
+            duration_ms: profile.duration_ms, thinking_traces: profile.thinking_traces.length,
+        }),
+        signal: AbortSignal.timeout(5000),
+    });
+}
+export async function startTuiRepl(client, config) {
+    setActiveConfig(config);
+    configureRemoteSync(config.genesisUrl, config.authToken);
+    let agents = [];
+    try {
+        agents = await loadAgentNames(client);
+    }
+    catch { /* */ }
+    const registry = getCommandRegistry();
+    try {
+        if (await registry.loadDynamicCommands(client, config))
+            refreshCommandCompletions();
+    }
+    catch { /* */ }
+    const complete = completer(agents);
+    const history = loadHistory(config.historyFile);
+    let histIdx = history.length;
+    let activeAbort = null;
+    let processing = false;
+    let sigintCount = 0;
+    let sigintTimer = null;
+    let gpuTag = '';
+    let pendingGate = null;
+    let lastProfile = null;
+    // ── Relay (native group chat) state ──
+    let relay = null;
+    let rosterUsers = [];
+    let relayUnread = new Map(); // other channels' unread counts
+    let relayKnownChannels = []; // for tab-completion
+    let relayOldestTs = null; // oldest shown msg ts (scrollback)
+    let relayLoadingOlder = false;
+    let relayTypingThrottle = null;
+    /** Scrollback: fetch + prepend older history when the output is scrolled to top. */
+    async function relayLoadOlder() {
+        if (!relay || relayLoadingOlder || !relayOldestTs)
+            return;
+        relayLoadingOlder = true;
+        try {
+            const older = await relay.loadOlder(relayOldestTs, 50);
+            if (older.length) {
+                relayOldestTs = String(older[0].timestamp || relayOldestTs);
+                surface.prependOutput(older.map(formatRelayMsg).join('\n'));
+            }
+            else {
+                surface.prependOutput(chalk.dim('  ── beginning of channel ──'));
+                relayOldestTs = null; // nothing older — stop further loads
+            }
+        }
+        finally {
+            relayLoadingOlder = false;
+        }
+    }
+    /** Tab-complete a relay channel (#…) or roster nick from the last token. */
+    function relayComplete(value) {
+        if (!relay)
+            return null;
+        const idx = value.lastIndexOf(' ');
+        const head = idx >= 0 ? value.slice(0, idx + 1) : '';
+        const tok = value.slice(head.length);
+        if (!tok)
+            return null;
+        if (tok.startsWith('#')) {
+            const hits = relayKnownChannels.filter(c => c.toLowerCase().startsWith(tok.toLowerCase()));
+            return hits.length === 1 ? head + hits[0] + ' ' : null;
+        }
+        const bare = tok.replace(/^@/, '');
+        if (bare) {
+            const hits = rosterUsers.map(u => u.nick).filter(n => n.toLowerCase().startsWith(bare.toLowerCase()));
+            if (hits.length === 1)
+                return head + '@' + hits[0] + ' ';
+        }
+        return null;
+    }
+    function relayOnType() {
+        if (!relay || relayTypingThrottle)
+            return; // throttle to ≤1 typing ping / 2s
+        relay.typing();
+        relayTypingThrottle = setTimeout(() => { relayTypingThrottle = null; }, 2000);
+    }
+    function idleStatus() {
+        const running = runningCount();
+        const bits = ['ready', gpuTag, running > 0 ? `${running} job${running > 1 ? 's' : ''}` : '']
+            .filter(Boolean).join(' · ');
+        surface.setStatus(bits);
+    }
+    const surface = createTuiScreen({
+        title: 'AitherShell',
+        onSubmit: (line) => { void onSubmit(line); },
+        onInterrupt: () => onInterrupt(),
+        onHistory: (dir) => {
+            if (!history.length)
+                return null;
+            if (dir === 'up')
+                histIdx = Math.max(0, histIdx - 1);
+            else
+                histIdx = Math.min(history.length, histIdx + 1);
+            return histIdx >= history.length ? '' : history[histIdx];
+        },
+        onTab: (value) => {
+            if (!value)
+                return null;
+            if (relay) {
+                const r = relayComplete(value);
+                if (r != null)
+                    return r;
+            }
+            const [hits] = complete(value);
+            if (!hits || !hits.length)
+                return null;
+            if (hits.length === 1)
+                return hits[0];
+            // Multiple: show options, complete to longest common prefix.
+            surface.traceLine(chalk.dim('  ⇥ ' + hits.slice(0, 12).join('  ')));
+            let lcp = hits[0];
+            for (const h of hits) {
+                while (!h.startsWith(lcp))
+                    lcp = lcp.slice(0, -1);
+            }
+            return lcp || null;
+        },
+        onSlash: () => { void openPicker(); },
+        onType: () => relayOnType(),
+        onScrollTop: () => { void relayLoadOlder(); },
+    });
+    // Tell the global crash reporter the TUI owns the terminal: stray async
+    // rejections become non-fatal + silent, and a real uncaught crash restores
+    // the terminal (surface.destroy) before printing the report.
+    setTuiActive(() => { try {
+        surface.destroy();
+    }
+    catch { /* */ } });
+    // ── Background-job completion notifications → OUTPUT pane ──
+    setJobNotifier((job) => {
+        const icon = job.status === 'completed' ? chalk.green('✓') : job.status === 'failed' ? chalk.red('✗') : chalk.yellow('—');
+        const color = job.status === 'completed' ? chalk.green : job.status === 'failed' ? chalk.red : chalk.yellow;
+        surface.outputLine(`${icon} Job ${chalk.bold('#' + job.id)} ${color(job.status)}: ${job.label}`);
+        if (job.status === 'completed' && job.output.length) {
+            const sepIdx = job.output.indexOf('---');
+            const lines = sepIdx >= 0 ? job.output.slice(sepIdx + 1) : job.output.filter(l => !l.startsWith('['));
+            const text = lines.join('\n').trim();
+            if (text) {
+                if (text.length <= 800)
+                    surface.outputLine(chalk.dim(text));
+                else
+                    surface.outputLine(chalk.dim(text.split('\n').slice(0, 6).join('\n') + `\n  … (/jobs ${job.id} for full)`));
+            }
+        }
+        else if (job.status === 'failed' && job.error) {
+            surface.outputLine(chalk.red('  ' + job.error));
+        }
+        idleStatus();
+    });
+    // ── GPU status poll (10s) ──
+    const gpuTimer = setInterval(async () => {
+        try {
+            const st = await client.getGpuStatus();
+            const zone = st?.zone || '';
+            gpuTag = zone.includes('image') ? chalk.yellow('GPU:3D') : st?.active ? chalk.cyan('GPU:R') : '';
+            if (!processing)
+                idleStatus();
+        }
+        catch { /* */ }
+    }, 10_000);
+    void gpuTimer;
+    // ── Register shell session (best-effort) ──
+    client.post('/shell/session/start', {
+        client_type: 'ts-shell', session_id: config.sessionId,
+        username: config.authUser?.username, user_id: config.authUser?.id,
+    }).catch(() => { });
+    // ── Resume previous conversation (--continue/--resume) ──
+    let seededContext = null;
+    if (config.resumed) {
+        const entry = loadSession(config.sessionId);
+        if (entry?.messages.length)
+            seededContext = buildContextSummary(entry.messages);
+    }
+    // ── Welcome ──
+    surface.outputLine(chalk.cyan.bold('AitherShell') + chalk.dim(`  ·  ${config.genesisUrl}`));
+    if (config.authUser)
+        surface.outputLine(chalk.dim(`Logged in as ${config.authUser.display_name || config.authUser.username}`));
+    if (config.resumed) {
+        const n = loadSession(config.sessionId)?.messages.length || 0;
+        surface.outputLine(chalk.green(`↩ Resumed session ${config.sessionId.slice(0, 8)} (${n} messages)`));
+    }
+    surface.outputLine(chalk.dim('/ commands · @ agents · ! shell · Tab complete · mouse-wheel/PgUp scroll · Ctrl+G release mouse (copy/paste) · End=live · Ctrl+T trace · Ctrl+E expand · Ctrl+C abort/exit'));
+    idleStatus();
+    surface.focusInput();
+    // Live fleet/backend status — services up, local-vs-Genesis backend, and the
+    // orchestrator + reasoning models loaded. Fetched async so the prompt is usable
+    // immediately; the block fills in under the welcome a moment later. `/status`
+    // refreshes it on demand.
+    void gatherStatus(client, config).then((info) => {
+        surface.outputLine('');
+        for (const line of formatStatusLines(info))
+            surface.outputLine(line);
+        surface.outputLine('');
+        surface.focusInput();
+    }).catch(() => { });
+    function onInterrupt() {
+        if (activeAbort) {
+            activeAbort.abort();
+            activeAbort = null;
+            surface.setStatus('aborted');
+            surface.focusInput();
+            return;
+        }
+        sigintCount++;
+        if (sigintCount >= 2) {
+            setTuiActive(null);
+            surface.destroy();
+            process.exit(0);
+        }
+        surface.setStatus('Ctrl+C again to exit');
+        if (sigintTimer)
+            clearTimeout(sigintTimer);
+        sigintTimer = setTimeout(() => { sigintCount = 0; idleStatus(); }, 2000);
+    }
+    // ── Command picker (native blessed list) ──
+    function buildPickerItems() {
+        const names = getCommandNames();
+        const dyn = registry.allCommands().map((c) => c.name);
+        const all = [...new Set([...names, ...dyn, 'jobs'])];
+        const categories = [
+            ['System', ['status', 'services', 'agents', 'logs', 'model', 'metrics']],
+            ['Agents', ['forge', 'sessions', 'resume', 'swarm', 'inbox', 'compose', 'monitor', 'notebook']],
+            ['Jobs', ['jobs']],
+            ['Search', ['search', 'codegraph', 'scope', 'onboard', 'obsidian', 'tools', 'context']],
+            ['AI', ['think', 'research', 'memory', 'soul']],
+            ['Ops', ['deploy', 'fleet', 'workflow', 'backup', 'benchmark', 'products', 'docker']],
+            ['Security', ['security', 'review', 'train', 'tool-scope', 'rbac']],
+            ['Automation', ['run', 'script', 'apps', 'gaming', 'routines']],
+            ['Auth', ['login', 'register', 'logout', 'whoami']],
+            ['Shell', ['help', 'clear', 'config']],
+        ];
+        const items = [];
+        const used = new Set();
+        for (const [cat, list] of categories) {
+            const avail = list.filter(n => all.includes(n));
+            if (!avail.length)
+                continue;
+            items.push({ label: `── ${cat} ──`, value: '', separator: true });
+            for (const n of avail) {
+                used.add(n);
+                items.push({ label: `/${n}`, value: n, description: getCommand(n)?.description || '' });
+            }
+        }
+        const extra = all.filter(n => !used.has(n) && n !== 'exit' && n !== 'quit');
+        if (extra.length) {
+            items.push({ label: '── Other ──', value: '', separator: true });
+            for (const n of extra)
+                items.push({ label: `/${n}`, value: n, description: getCommand(n)?.description || registry.resolve(n)?.description || '' });
+        }
+        return items;
+    }
+    async function openPicker() {
+        const choice = await surface.showPicker('/ commands', buildPickerItems());
+        if (!choice)
+            return;
+        // Defer to runCommand: when the command has a subcommand table, runCommand's
+        // interactive path picks the subcommand AND prompts for its arguments (the
+        // blessed overlay can't do text/enum arg entry). Bare invocation and the
+        // picker thus share one fully-interactive flow.
+        await runCommand('/' + choice);
+    }
+    async function onSubmit(input) {
+        sigintCount = 0;
+        if (!input)
+            return;
+        if (surface.pickerOpen())
+            return;
+        saveHistory(config.historyFile, input);
+        history.push(input);
+        histIdx = history.length;
+        if (input === 'exit' || input === 'quit' || input === '/exit' || input === '/quit') {
+            setTuiActive(null);
+            surface.destroy();
+            process.exit(0);
+        }
+        if (input === '?') {
+            showHelp();
+            return;
+        }
+        if (input.startsWith('!')) {
+            runShell(input.slice(1).trim());
+            return;
+        }
+        const explicitBg = input.endsWith(' &');
+        const clean = explicitBg ? input.slice(0, -2).trimEnd() : input;
+        if (clean.startsWith('/')) {
+            await runCommand(clean, explicitBg);
+            return;
+        }
+        // Relay mode: plain input is a message to the channel (humans + agents see it).
+        if (relay) {
+            relay.send(clean);
+            // Agents don't emit typing while generating, so hint that a reply is coming.
+            if (rosterUsers.some(u => u.is_agent))
+                relayStatus('sent · agents may reply…');
+            return;
+        }
+        // Steer an active stream.
+        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(() => { });
+            return;
+        }
+        await runChat(clean, explicitBg);
+    }
+    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'));
+        surface.outputLine(chalk.dim('/ picker · /cmd · @agent route · @think/@research deep · ! shell · cmd & background · /jobs · exit'));
+        surface.outputLine(chalk.dim('/relay [#channel]  native group chat (humans + agents) · /relay join #x · /relay channels [scope] · scroll up = older · /relay more · /leave'));
+        surface.focusInput();
+    }
+    function runShell(cmd) {
+        if (!cmd) {
+            surface.outputLine(chalk.yellow('Usage: !<command> (PowerShell 7)'));
+            return;
+        }
+        surface.outputLine(chalk.dim('$ ' + cmd));
+        try {
+            const out = execSync(`pwsh -NoProfile -c "${cmd.replace(/"/g, '\\"')}"`, { encoding: 'utf8', timeout: 300_000 });
+            if (out)
+                surface.outputLine(out.replace(/\n$/, ''));
+        }
+        catch (err) {
+            if (err.stdout)
+                surface.outputLine(String(err.stdout).replace(/\n$/, ''));
+            surface.outputLine(chalk.red(err.status ? `exit ${err.status}` : `Error: ${err.message}`));
+        }
+        surface.focusInput();
+    }
+    function handleJobs(args) {
+        const parts = args.trim().split(/\s+/);
+        const sub = parts[0] || '';
+        if (sub === 'cancel' || sub === 'kill') {
+            const id = Number(parts[1]);
+            if (!id) {
+                surface.outputLine(chalk.yellow('Usage: /jobs cancel <id>'));
+                return;
+            }
+            surface.outputLine(cancelJob(id) ? chalk.green(`Job #${id} cancelled.`) : chalk.yellow(`Job #${id} not running.`));
+            idleStatus();
+            return;
+        }
+        const id = Number(sub);
+        if (id > 0) {
+            const job = getJob(id);
+            surface.outputLine(job ? formatJobOutput(job) : chalk.yellow(`Job #${id} not found.`));
+            return;
+        }
+        const all = listJobs();
+        if (!all.length) {
+            surface.outputLine(chalk.dim('No background jobs.'));
+            return;
+        }
+        surface.outputLine(chalk.bold('Background Jobs'));
+        for (const j of all)
+            surface.outputLine(formatJobLine(j));
+        surface.outputLine(chalk.dim('/jobs <id> view · /jobs cancel <id>'));
+    }
+    // ── Relay (native AitherRelay group chat — humans + agents in a channel) ──
+    function relayMentionsMe(content) {
+        if (!relay)
+            return false;
+        const n = relay.nick.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return new RegExp(`(^|[^\\w])@?${n}\\b`, 'i').test(content || '');
+    }
+    function formatRelayMsg(m) {
+        let time = '';
+        try {
+            const t = typeof m.timestamp === 'number'
+                ? new Date(m.timestamp > 1e12 ? m.timestamp : m.timestamp * 1000)
+                : (m.timestamp ? new Date(m.timestamp) : null);
+            if (t && !isNaN(t.getTime()))
+                time = chalk.dim(t.toTimeString().slice(0, 5) + ' ');
+        }
+        catch { /* */ }
+        const self = !!relay && m.nick === relay.nick;
+        const who = m.agent ? chalk.magenta(`@${m.nick}`) : (self ? chalk.green(m.nick) : chalk.cyan(m.nick));
+        const line = `${time}${who}: ${m.content}`;
+        // Highlight messages that mention you (not your own).
+        return (!self && relayMentionsMe(m.content)) ? chalk.yellow('★ ') + line : line;
+    }
+    function renderRoster(channel) {
+        const humans = rosterUsers.filter(u => !u.is_agent).map(u => `  ${chalk.cyan(u.nick)}`);
+        const agents = rosterUsers.filter(u => u.is_agent).map(u => `  ${chalk.magenta('@' + u.nick)}`);
+        const lines = [];
+        if (agents.length) {
+            lines.push(chalk.bold('Agents'));
+            lines.push(...agents, '');
+        }
+        lines.push(chalk.bold(`People (${humans.length})`));
+        lines.push(...(humans.length ? humans : [chalk.dim('  (just you)')]));
+        surface.setTracePanel(`${channel} · ${rosterUsers.length}`, lines);
+    }
+    function relayStatus(extra) {
+        if (!relay)
+            return;
+        const unread = [...relayUnread.entries()].filter(([, n]) => n > 0)
+            .map(([c, n]) => `${c}(${n})`).join(' ');
+        surface.setStatus(['📡 relay', relay.currentChannel, unread ? `unread ${unread}` : '', extra].filter(Boolean).join(' · '));
+    }
+    async function startRelay(initialChannel) {
+        if (relay) {
+            surface.outputLine(chalk.yellow('Already in relay — /leave first.'));
+            return;
+        }
+        const nick = config.authUser?.username || config.authUser?.display_name || `dev_${Math.floor(Math.random() * 9000 + 1000)}`;
+        const client = new RelayClient({
+            url: resolveRelayUrl(), token: config.authToken || undefined, nick,
+            handlers: {
+                onStatus: (s) => relayStatus(s === 'open' ? undefined : s),
+                onHistory: (ch, msgs) => {
+                    relayUnread.delete(ch);
+                    relayOldestTs = msgs.length
+                        ? msgs.reduce((min, m) => (String(m.timestamp) < min ? String(m.timestamp) : min), String(msgs[0].timestamp))
+                        : null;
+                    surface.clearPanes();
+                    surface.setOutputLabel(`relay ${ch}`);
+                    surface.outputLine(chalk.dim(`── ${ch} — last ${msgs.length} message(s) · scroll up for more ──`));
+                    for (const m of msgs)
+                        surface.outputLine(formatRelayMsg(m));
+                    renderRoster(ch);
+                    relayStatus();
+                },
+                onMessage: (m) => {
+                    // Messages for OTHER joined channels become unread badges, not noise.
+                    if (relay && m.channel && m.channel !== relay.currentChannel) {
+                        relayUnread.set(m.channel, (relayUnread.get(m.channel) || 0) + 1);
+                        relayStatus();
+                        return;
+                    }
+                    surface.outputLine(formatRelayMsg(m));
+                    relayStatus(); // clears any "agents may reply…" hint once a reply lands
+                },
+                onJoin: (n, ch, isAgent) => { if (!rosterUsers.some(u => u.nick === n))
+                    rosterUsers.push({ nick: n, is_agent: isAgent }); renderRoster(ch); },
+                onPart: (n, ch) => { rosterUsers = rosterUsers.filter(u => u.nick !== n); renderRoster(ch); },
+                onUserlist: (ch, users) => { rosterUsers = users; renderRoster(ch); },
+                onTyping: (n) => relayStatus(`${n} typing…`),
+                onError: (msg) => surface.outputLine(chalk.red(`  relay: ${msg}`)),
+            },
+        });
+        let channel = initialChannel;
+        if (!channel) {
+            surface.setStatus('📡 relay · loading channels…');
+            const channels = await client.listChannels();
+            relayKnownChannels = channels.map(c => c.name);
+            if (channels.length) {
+                const items = channels.map(c => ({ label: c.name + (c.topic ? `  —  ${c.topic}` : ''), value: c.name }));
+                const picked = await surface.showPicker('Join a relay channel', items);
+                if (!picked) {
+                    idleStatus();
+                    return;
+                }
+                channel = picked;
+            }
+            else {
+                channel = '#general';
+                surface.outputLine(chalk.dim('  (no channel list returned — defaulting to #general)'));
+            }
+        }
+        relay = client;
+        rosterUsers = [];
+        // Best-effort channel list for tab-completion (covers the /relay #x path).
+        if (!relayKnownChannels.length)
+            client.listChannels().then(cs => { relayKnownChannels = cs.map(c => c.name); }).catch(() => { });
+        surface.outputLine(chalk.green(`  📡 Joining ${channel} as ${nick}…  (type to chat · /relay join #x · /leave)`));
+        client.connect(channel);
+        relayStatus('connecting');
+    }
+    async function handleRelay(args) {
+        const a = args.trim();
+        const parts = a.split(/\s+/);
+        const sub = (parts[0] || '').toLowerCase();
+        if (relay) {
+            if (sub === 'leave' || sub === 'exit' || sub === 'quit') {
+                leaveRelay();
+                return;
+            }
+            if (sub === 'join') {
+                if (parts[1]) {
+                    rosterUsers = [];
+                    relay.join(parts[1]);
+                }
+                else
+                    surface.outputLine(chalk.yellow('Usage: /relay join #channel'));
+                return;
+            }
+            if (sub === 'channels') {
+                const scope = parts[1] || 'platform'; // platform | community | workspace:<slug>
+                const cs = await relay.listChannels(scope);
+                relayKnownChannels = cs.map(c => c.name);
+                surface.outputLine(chalk.bold(`Channels (${scope}): `) + chalk.dim(relayKnownChannels.join('  ') || '(none)'));
+                return;
+            }
+            if (sub === 'more' || sub === 'history') {
+                await relayLoadOlder();
+                return;
+            }
+            if (a.startsWith('#')) {
+                rosterUsers = [];
+                relay.join(a);
+                return;
+            }
+            surface.outputLine(chalk.dim('In relay: type to chat · /relay join #x · /relay channels [scope] · /relay more · /leave'));
+            return;
+        }
+        await startRelay(a.startsWith('#') ? a : undefined);
+    }
+    function leaveRelay() {
+        if (!relay)
+            return;
+        try {
+            relay.part();
+        }
+        catch { /* */ } // tell the channel before closing
+        relay.disconnect();
+        relay = null;
+        rosterUsers = [];
+        relayUnread = new Map();
+        relayOldestTs = null;
+        relayLoadingOlder = false;
+        if (relayTypingThrottle) {
+            clearTimeout(relayTypingThrottle);
+            relayTypingThrottle = null;
+        }
+        surface.setOutputLabel('output');
+        surface.setTracePanel('trace', []);
+        surface.outputLine(chalk.dim('  📡 Left relay — back to agent chat.'));
+        idleStatus();
+    }
+    async function runCommand(input, bg = false) {
+        const sp = input.indexOf(' ');
+        const name = sp > 0 ? input.slice(1, sp) : input.slice(1);
+        const args = sp > 0 ? input.slice(sp + 1).trim() : '';
+        if (!name) {
+            await openPicker();
+            return;
+        }
+        if (name === 'clear' || name === 'cls') {
+            surface.clearPanes();
+            idleStatus();
+            surface.focusInput();
+            return;
+        }
+        if (name === 'help') {
+            showHelp();
+            return;
+        }
+        if (name === 'jobs') {
+            handleJobs(args);
+            return;
+        }
+        if (name === 'relay') {
+            await handleRelay(args);
+            return;
+        }
+        if ((name === 'leave' || name === 'unrelay') && relay) {
+            leaveRelay();
+            return;
+        }
+        const cmd = getCommand(name);
+        if (!cmd) {
+            surface.outputLine(chalk.yellow(`Unknown command: ${name}`) + chalk.dim('  (/ picker, or AITHER_TUI=0 for full UX)'));
+            surface.focusInput();
+            return;
+        }
+        // Background variants.
+        if ((bg || AUTO_BG_COMMANDS.has(name))) {
+            if (name === 'forge') {
+                bgForge(args);
+                return;
+            }
+            if (name === 'swarm') {
+                bgSwarm(args);
+                return;
+            }
+            if (bg) {
+                const job = launchCommandJob(`/${name} ${args}`.trim(), () => cmd.handler(client, args, config));
+                surface.outputLine(chalk.dim(`Background job #${job.id}: /${name}`));
+                idleStatus();
+                return;
+            }
+        }
+        // Foreground: suspend the TUI and run the command on the REAL terminal, so
+        // its console.log / ora spinners / @inquirer prompts (e.g. /login) all work
+        // and can't corrupt or deadlock the blessed screen. Returns on a keypress.
+        // When invoked bare (no args) and the command has a subcommand table, collect
+        // its arguments interactively first — same detached session, so the prompts
+        // and the handler output share one suspend/restore cycle.
+        const subDefs = SUBCOMMAND_DEFS['/' + name];
+        const interactive = !args && !!subDefs?.length;
+        await surface.runDetached(name, async () => {
+            let finalArgs = args;
+            if (interactive) {
+                const collected = await collectArgs(name, subDefs);
+                if (collected === null) {
+                    console.log(chalk.dim('\n  (cancelled)\n'));
+                    return;
+                }
+                finalArgs = collected;
+            }
+            await cmd.handler(client, finalArgs, config);
+        });
+        idleStatus();
+    }
+    function bgForge(args) {
+        let task = args;
+        let agent;
+        let effort;
+        const am = args.match(/--agent\s+(\S+)/);
+        if (am) {
+            agent = am[1];
+            task = task.replace(am[0], '');
+        }
+        const em = args.match(/--effort\s+(\d+)/);
+        if (em) {
+            effort = Number(em[1]);
+            task = task.replace(em[0], '');
+        }
+        task = task.replace(/^["']|["']$/g, '').trim();
+        if (!task) {
+            surface.outputLine(chalk.yellow('Usage: /forge "task" [--agent name] [--effort N]'));
+            return;
+        }
+        const job = launchForgeJob(client, task, { agent, effort });
+        surface.outputLine(chalk.dim(`${agent ? '@' + agent : 'Forge'} → background job #${job.id} (effort ${effort ?? 5})`));
+        idleStatus();
+    }
+    function bgSwarm(args) {
+        let task = args;
+        let mode = 'llm';
+        const mm = args.match(/--mode\s+(\S+)/);
+        if (mm) {
+            mode = mm[1];
+            task = task.replace(mm[0], '');
+        }
+        task = task.replace(/^["']|["']$/g, '').trim();
+        if (!task) {
+            surface.outputLine(chalk.yellow('Usage: /swarm <task> [--mode forge|llm|plan_only]'));
+            return;
+        }
+        const job = launchSwarmJob(client, task, mode);
+        surface.outputLine(chalk.dim(`Swarm (${mode}) → background job #${job.id}`));
+        idleStatus();
+    }
+    async function runChat(input, bg = false) {
+        // Resolve @mentions (agent routes) vs @strategy triggers.
+        let agent = config.defaultAgent;
+        const resolved = [];
+        const mentions = input.match(/@(\S+)/g) || [];
+        for (const m of mentions) {
+            const raw = m.slice(1);
+            if (STRATEGY_TRIGGERS.has(raw.toLowerCase()))
+                continue;
+            const { resolved: r, unknown } = resolveAgentMention(raw);
+            if (r && !resolved.includes(r))
+                resolved.push(r);
+            else if (unknown)
+                surface.traceLine(chalk.yellow(`  ⚠ unknown agent @${unknown}`));
+        }
+        if (resolved.length)
+            agent = resolved[0];
+        const hasDeep = mentions.some(m => DEEP_TRIGGERS.has(m.slice(1).toLowerCase()));
+        if (bg) {
+            const label = agent !== config.defaultAgent ? `@${agent}: ${input.slice(0, 40)}` : `Chat: ${input.slice(0, 50)}`;
+            const job = launchChatJob(client, input, { agent, sessionId: config.sessionId, model: config.model, label });
+            surface.outputLine(chalk.dim(`Background job #${job.id}: ${label}`));
+            idleStatus();
+            return;
+        }
+        // Pre-flight readiness (non-blocking warning).
+        try {
+            const h = await fetch(`${config.genesisUrl}/health`, { signal: AbortSignal.timeout(2000) });
+            if (h.ok) {
+                const hd = await h.json();
+                if (hd.generation_ready === false)
+                    surface.traceLine(chalk.yellow('  ⚠ LLM pool busy (0 slots) — sending anyway'));
+            }
+        }
+        catch { /* */ }
+        surface.outputLine(chalk.green('› ') + input);
+        surface.setStatus('working…');
+        // Open a fresh, collapsible trace thread for this turn (older turns collapse).
+        surface.startTraceTurn(input.length > 32 ? input.slice(0, 32) + '…' : input);
+        // Clarification gate auto-resolve.
+        let clarification;
+        if (pendingGate) {
+            clarification = { plan_id: pendingGate.planId, gate_id: pendingGate.gateId, answers: input };
+            pendingGate = null;
+        }
+        // RLM continuity: prior turn this session, or the resumed transcript summary.
+        const prevCtx = lastProfile ? {
+            summary: `Previous: "${lastProfile.prompt.slice(0, 160)}" → ${lastProfile.model}, ${lastProfile.tool_calls.length} tools`,
+            tools_used: lastProfile.tool_calls.map(t => t.name), model: lastProfile.model, errors: lastProfile.errors,
+        } : seededContext ? {
+            summary: seededContext, tools_used: [], model: config.model || '', errors: [],
+        } : undefined;
+        seededContext = null; // consume once
+        activeAbort = new AbortController();
+        processing = true;
+        let aborted = false;
+        let renderer = createTuiRenderer(surface, config.sessionId, input);
+        // Auto-retry once when the connection is severed mid-turn (Genesis or the
+        // LB recreated under us — a deploy rolling the stack). Only when NO tools
+        // fired yet (no double side-effects) and only after the backend is
+        // reachable again. A soft stream_timeout (agent may still be working) is
+        // NOT retried — that path keeps its "check forge status" semantics.
+        const MAX_ATTEMPTS = 2;
+        try {
+            for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+                if (attempt > 0) {
+                    renderer = createTuiRenderer(surface, config.sessionId, input);
+                    surface.startTraceTurn((input.length > 32 ? input.slice(0, 32) + '…' : input) + ' (retry)');
+                }
+                let sawTerminal = false; // complete/done/error/timeout/interrupt arrived
+                let interrupted = false; // transport died mid-turn
+                let toolFired = false; // tools ran — retry could double side-effects
+                try {
+                    for await (const ev of client.streamChat(input, {
+                        agent, mentions: resolved.length > 1 ? resolved : undefined,
+                        sessionId: config.sessionId, model: config.model, signal: activeAbort.signal,
+                        clarificationResponse: clarification, sessionContext: prevCtx,
+                        effort: config.effort, safetyLevel: config.safetyLevel, privateMode: config.privateMode,
+                        attachments: config.imageAttachments, maxEffort: hasDeep ? undefined : (config.effort || 5),
+                    })) {
+                        renderer.onEvent(ev);
+                        if (ev.type === 'complete' || ev.type === 'done' || ev.type === 'error'
+                            || ev.type === 'llm_error' || ev.type === 'stream_timeout')
+                            sawTerminal = true;
+                        if (ev.type === 'stream_interrupted') {
+                            sawTerminal = true;
+                            interrupted = true;
+                        }
+                        if (ev.type === 'tool_call' || ev.type === 'tool_result')
+                            toolFired = true;
+                        if (ev.type === 'clarification_needed' && ev.data.plan_id) {
+                            pendingGate = { planId: ev.data.plan_id, gateId: ev.data.gate_id || '' };
+                        }
+                    }
+                    if (config.imageAttachments?.length)
+                        config.imageAttachments = undefined;
+                }
+                catch (err) {
+                    if (err?.name === 'AbortError') {
+                        aborted = true;
+                        surface.outputLine(chalk.dim('  (interrupted)'));
+                    }
+                    else
+                        surface.outputLine(chalk.red(`  Error: ${err?.message || err}`));
+                    renderer.finish(aborted);
+                    break;
+                }
+                renderer.finish(aborted);
+                const lostMidTurn = interrupted || !sawTerminal;
+                if (!lostMidTurn || aborted || toolFired || attempt === MAX_ATTEMPTS - 1)
+                    break;
+                surface.setStatus('connection lost — waiting for backend…');
+                const back = await waitForBackend(config.genesisUrl, 120_000, activeAbort.signal);
+                if (!back) {
+                    surface.outputLine(chalk.yellow('  Backend still unreachable after 2 minutes — resend when it returns.'));
+                    break;
+                }
+                surface.outputLine(chalk.cyan('↻ Backend is back — retrying the turn once…'));
+            }
+        }
+        finally {
+            activeAbort = null;
+            processing = false;
+            lastProfile = renderer.getSessionProfile();
+            postToStrata(client, lastProfile).catch(() => { });
+            // Persist the full turn (user + assistant) locally + remote → /export, --continue.
+            try {
+                recordTurn(config.sessionId, lastProfile.agent || agent, input, renderer.getContent(), {
+                    model: lastProfile.model, tools: lastProfile.tool_calls.map(t => t.name),
+                    tokens: sumTokens(lastProfile.events),
+                });
+            }
+            catch { /* */ }
+            idleStatus();
+            surface.focusInput();
+        }
+    }
+}
+/** Poll /health until the backend answers 200, the timeout elapses, or the
+ *  user aborts. Genesis cold-boots in ~110s after a recreate, so the budget
+ *  must cover a full container roll, not just a blip. */
+async function waitForBackend(baseUrl, timeoutMs, signal) {
+    const t0 = Date.now();
+    while (Date.now() - t0 < timeoutMs) {
+        if (signal?.aborted)
+            return false;
+        try {
+            const r = await fetch(`${baseUrl}/health`, { signal: AbortSignal.timeout(3000) });
+            if (r.ok)
+                return true;
+        }
+        catch { /* still down */ }
+        await new Promise(res => setTimeout(res, 2500));
+    }
+    return false;
+}