@aitherium/shell-cli 1.1.0

package/dist/repl.js

@@ -0,0 +1,1190 @@
+/**
+ * Interactive REPL — readline, streaming, history, Ctrl+C,
+ * shell escape (!), interactive slash-command picker (/), agent routing (@).
+ *
+ * NON-BLOCKING: Long-running tasks (forge, swarm, agent chat with &) run
+ * as background jobs. The REPL stays interactive — you can chat, queue more
+ * tasks, or check job status while agents work.
+ *
+ * "/" on an empty line immediately launches a searchable command picker
+ * (via @inquirer/prompts) WITHOUT pressing Enter. This is achieved by
+ * monkey-patching readline's _ttyWrite to intercept before the character
+ * is added to the line buffer.
+ */
+import * as readline from 'node:readline';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import chalk from 'chalk';
+import { search, Separator } from '@inquirer/prompts';
+import { createStreamRenderer, SteeringBar } from './renderer.js';
+import { getCommand, getCommandNames } from './commands.js';
+import { getCommandRegistry } from './command-registry.js';
+import { loadAgentNames, resolveAgentMention, completer, refreshCommandCompletions, SUBCOMMAND_DEFS } from './completions.js';
+import { setJobNotifier, listJobs, getJob, cancelJob, runningCount, launchChatJob, launchForgeJob, launchSwarmJob, formatJobLine, formatJobOutput, } from './jobs.js';
+import { configureRemoteSync, syncSessionToRemote } from './session-store.js';
+/** Commands that are long-running and auto-background. */
+const AUTO_BG_COMMANDS = new Set(['forge', 'swarm']);
+/** Post session profile to Strata for observability (best-effort). */
+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 startRepl(client, config) {
+    // Enable cross-client session sync (local CLI ↔ tunnel.aitherium.com)
+    configureRemoteSync(config.genesisUrl, config.authToken);
+    const agents = await loadAgentNames(client);
+    // Auto-discover commands from Genesis (MCP tools, ADK groups, tagged endpoints)
+    const registry = getCommandRegistry();
+    const dynamicCount = await registry.loadDynamicCommands(client);
+    if (dynamicCount > 0) {
+        refreshCommandCompletions();
+    }
+    const history = loadHistory(config.historyFile);
+    /** GPU status tag — updated by background poller. */
+    let gpuTag = '';
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        prompt: buildPrompt(),
+        completer: completer(agents),
+        history,
+        historySize: 500,
+        terminal: true,
+    });
+    // ── Keep event loop alive ──
+    // inquirer and AbortSignal.timeout can drop stdin refs.
+    // This interval prevents premature exit in TTY mode.
+    process.stdin.ref();
+    let keepAlive = null;
+    if (process.stdin.isTTY) {
+        keepAlive = setInterval(() => { }, 2_147_483_647);
+    }
+    let gpuPollTimer = null;
+    function cleanExit(code = 0) {
+        if (keepAlive)
+            clearInterval(keepAlive);
+        if (gpuPollTimer)
+            clearInterval(gpuPollTimer);
+        process.exit(code);
+    }
+    // Catch unhandled rejections (orphan AbortSignal.timeout)
+    process.on('unhandledRejection', (err) => {
+        if (err?.name === 'AbortError' || err?.code === 'ABORT_ERR')
+            return;
+        console.error(chalk.red(`  Unhandled error: ${err?.message || err}`));
+    });
+    let activeAbort = null;
+    const steeringBar = new SteeringBar();
+    let sigintCount = 0;
+    let pendingClose = false;
+    let closed = false;
+    let lastShellCmd = '';
+    let menuActive = false;
+    /** Pending clarification gate from the last plan response. */
+    let pendingGate = null;
+    /** Last session profile for RLM context injection across turns. */
+    let lastSessionProfile = null;
+    /** Build prompt with running job count and GPU status. */
+    function buildPrompt() {
+        const running = runningCount();
+        const parts = [];
+        if (running > 0)
+            parts.push(String(running));
+        if (gpuTag)
+            parts.push(gpuTag);
+        const suffix = parts.length > 0
+            ? chalk.dim(`[${parts.join('|')}]`)
+            : '';
+        return chalk.green('aither') + suffix + chalk.green('> ');
+    }
+    /** Update the prompt to reflect current job count / GPU state. */
+    function refreshPrompt() {
+        rl.setPrompt(buildPrompt());
+    }
+    /** Poll MicroScheduler GPU zone every 10s and update prompt tag. */
+    gpuPollTimer = setInterval(async () => {
+        try {
+            const st = await client.getGpuStatus();
+            const zone = st?.zone || '';
+            const prev = gpuTag;
+            if (zone.includes('image')) {
+                gpuTag = chalk.yellow('GPU:3D');
+            }
+            else if (st?.active) {
+                gpuTag = chalk.cyan('GPU:R');
+            }
+            else {
+                gpuTag = '';
+            }
+            if (gpuTag !== prev)
+                refreshPrompt();
+        }
+        catch { }
+    }, 10_000);
+    /** Restore readline + stdin after inquirer or any handler that disturbs them. */
+    function restoreReadline() {
+        process.stdin.ref();
+        process.stdin.resume();
+        rl.resume();
+        // inquirer turns off raw mode; readline needs it on for _ttyWrite to fire
+        if (process.stdin.isTTY && typeof process.stdin.setRawMode === 'function') {
+            process.stdin.setRawMode(true);
+        }
+    }
+    /**
+     * Print a notification above the current prompt line without disrupting
+     * what the user is typing. Clears the line, prints, then re-renders prompt.
+     * If a foreground task is active (readline paused), just print inline.
+     */
+    function notifyAbovePrompt(text) {
+        if (closed)
+            return;
+        if (activeAbort || processing) {
+            // Foreground task active — just print, don't touch readline
+            console.log(text);
+            return;
+        }
+        // Save current line content
+        const currentLine = rl.line || '';
+        // Move to start, clear line, print notification
+        process.stdout.write('\r\x1B[2K');
+        console.log(text);
+        // Re-render prompt + whatever the user was typing
+        refreshPrompt();
+        rl.prompt(true);
+        // Restore the user's in-progress input
+        if (currentLine) {
+            rl.line = currentLine;
+            rl.cursor = currentLine.length;
+            process.stdout.write(currentLine);
+        }
+    }
+    // ── Background job notifications ──
+    setJobNotifier((job) => {
+        const icon = job.status === 'completed' ? chalk.green('\u2713')
+            : job.status === 'failed' ? chalk.red('\u2717')
+                : chalk.yellow('\u2015');
+        const statusColor = job.status === 'completed' ? chalk.green
+            : job.status === 'failed' ? chalk.red
+                : chalk.yellow;
+        const header = `  ${icon} Job ${chalk.bold('#' + job.id)} ${statusColor(job.status)}: ${job.label}`;
+        // Show content preview for completed jobs so user doesn't need /jobs <id> for short responses
+        let preview = '';
+        if (job.status === 'completed' && job.output.length > 0) {
+            // Find the actual content (after the --- separator, or last non-trace line)
+            const sepIdx = job.output.indexOf('---');
+            const contentLines = sepIdx >= 0
+                ? job.output.slice(sepIdx + 1)
+                : job.output.filter(l => !l.startsWith('['));
+            const content = contentLines.join('\n').trim();
+            if (content.length > 0 && content.length <= 500) {
+                // Short enough to show inline
+                preview = '\n' + content.split('\n').map(l => `  ${l}`).join('\n');
+            }
+            else if (content.length > 500) {
+                // Show first few lines + hint
+                const firstLines = content.split('\n').slice(0, 4).join('\n');
+                preview = '\n' + firstLines.split('\n').map(l => `  ${l}`).join('\n')
+                    + chalk.dim(`\n  ... (${content.length} chars — /jobs ${job.id} for full output)`);
+            }
+        }
+        else if (job.status === 'failed' && job.error) {
+            preview = '\n' + chalk.red(`  ${job.error}`);
+        }
+        if (preview) {
+            notifyAbovePrompt(header + preview);
+        }
+        else {
+            notifyAbovePrompt(header + chalk.dim(`  (/jobs ${job.id} for output)`));
+        }
+    });
+    // ── Auth status in banner ──
+    if (config.authUser) {
+        console.log(chalk.green(`  Logged in as ${config.authUser.display_name || config.authUser.username}`));
+    }
+    else {
+        console.log(chalk.dim('  Not logged in. Use /login to authenticate.'));
+    }
+    console.log(chalk.dim('  /  commands   !  shell   @  directives/agents   &  background   ?  help'));
+    console.log();
+    // ── Register shell session with Genesis (best effort) ──
+    const _sessionRegistered = client.post('/shell/session/start', {
+        client_type: 'ts-shell',
+        session_id: config.sessionId,
+        username: config.authUser?.username,
+        user_id: config.authUser?.id,
+    }).catch(() => { });
+    // ── Build command choices for the interactive picker ──
+    const cmdChoices = buildCommandChoices();
+    // ── Monkey-patch _ttyWrite: "/" on empty line opens picker instantly ──
+    // Also: update SteeringBar display with current input when active.
+    if (process.stdin.isTTY) {
+        const origTtyWrite = rl._ttyWrite;
+        rl._ttyWrite = function (s, key) {
+            if (menuActive)
+                return; // Block ALL keystrokes while picker is active
+            if (s === '/' && this.line.length === 0 && !closed) {
+                // ALWAYS open picker for / on empty line — even during steering.
+                // Slash commands must never be sent as chat/steer input.
+                menuActive = true;
+                setImmediate(() => launchCommandPicker());
+                return;
+            }
+            origTtyWrite.call(this, s, key);
+            // Keep steering bar in sync with readline's internal buffer
+            if (steeringBar.active) {
+                steeringBar.setInput(this.line || '');
+            }
+        };
+    }
+    // ── Interactive command picker ──
+    async function launchCommandPicker() {
+        let selected;
+        // Track what the user typed so we can extract trailing args
+        let lastSearchInput = '';
+        try {
+            // Erase the prompt line and pause readline
+            process.stdout.write('\r\x1B[2K');
+            rl.pause();
+            selected = await search({
+                message: chalk.green('/'),
+                source: (input) => {
+                    lastSearchInput = input || '';
+                    // Match on the FIRST word only — rest is args
+                    const term = lastSearchInput.split(/\s/)[0].toLowerCase();
+                    if (!term)
+                        return cmdChoices;
+                    return cmdChoices.filter((c) => {
+                        if (c.type === 'separator')
+                            return false;
+                        return c.value.includes(term)
+                            || c.name.toLowerCase().includes(term)
+                            || (c.description || '').toLowerCase().includes(term);
+                    });
+                },
+                theme: {
+                    prefix: ' ',
+                    style: {
+                        highlight: (text) => chalk.cyan.bold(text),
+                    },
+                },
+            });
+        }
+        catch {
+            // Ctrl+C / Escape — go back to prompt
+        }
+        menuActive = false;
+        // Belt-and-suspenders: clear anything that got through
+        rl.line = '';
+        rl.cursor = 0;
+        restoreReadline();
+        if (selected) {
+            // Check if the user typed args after the command in the picker
+            // e.g. typed "nb list" — selected="nb", trailing args="list"
+            const pickerParts = (lastSearchInput || '').trim().split(/\s+/);
+            const trailingArgs = pickerParts.length > 1 ? pickerParts.slice(1).join(' ') : '';
+            if (trailingArgs) {
+                // User typed command + args in picker — execute immediately
+                lineQueue.push('/' + selected + ' ' + trailingArgs);
+                drainQueue();
+                return;
+            }
+            // If the command has subcommands, show a second picker
+            const subDefs = SUBCOMMAND_DEFS['/' + selected];
+            if (subDefs && subDefs.length > 0) {
+                let subSelected;
+                let subSearchInput = '';
+                try {
+                    process.stdout.write('\r\x1B[2K');
+                    rl.pause();
+                    const subChoices = subDefs.map(([name, argHint]) => ({
+                        name: argHint
+                            ? `${chalk.cyan(name)} ${chalk.dim(argHint)}`
+                            : chalk.cyan(name),
+                        value: name,
+                        description: '',
+                    }));
+                    subSelected = await search({
+                        message: chalk.green(`/${selected} `),
+                        source: (input) => {
+                            subSearchInput = input || '';
+                            const term = subSearchInput.split(/\s/)[0].toLowerCase();
+                            if (!term)
+                                return subChoices;
+                            return subChoices.filter((c) => c.value.includes(term));
+                        },
+                        theme: {
+                            prefix: ' ',
+                            style: { highlight: (text) => chalk.cyan.bold(text) },
+                        },
+                    });
+                }
+                catch {
+                    // Ctrl+C / Escape
+                }
+                menuActive = false;
+                rl.line = '';
+                rl.cursor = 0;
+                restoreReadline();
+                if (subSelected) {
+                    // Check for trailing args typed in sub-picker
+                    const subParts = (subSearchInput || '').trim().split(/\s+/);
+                    const subArgs = subParts.length > 1 ? subParts.slice(1).join(' ') : '';
+                    if (subArgs) {
+                        // User typed args in picker — execute immediately
+                        lineQueue.push(`/${selected} ${subSelected} ${subArgs}`);
+                        drainQueue();
+                        return;
+                    }
+                    // Check if this subcommand needs args
+                    const subDef = subDefs.find(([n]) => n === subSelected);
+                    const needsSubArgs = subDef && subDef[1] !== '';
+                    if (needsSubArgs) {
+                        // Prefill so user can type the arg, e.g. "/nb create "
+                        rl.prompt();
+                        rl.write(`/${selected} ${subSelected} `);
+                        return;
+                    }
+                    // No args needed — execute immediately
+                    lineQueue.push(`/${selected} ${subSelected}`);
+                    drainQueue();
+                    return;
+                }
+                rl.prompt();
+                return;
+            }
+            // No subcommands — execute immediately
+            // Handle MCP tool selections from the picker
+            if (selected.startsWith('mcp:')) {
+                const toolName = selected.slice(4);
+                lineQueue.push('/' + toolName);
+            }
+            else {
+                lineQueue.push('/' + selected);
+            }
+            drainQueue();
+            return;
+        }
+        rl.prompt();
+    }
+    // ── Line queue — serialize processing but DON'T block on bg tasks ──
+    const lineQueue = [];
+    let processing = false;
+    async function drainQueue() {
+        if (processing)
+            return;
+        processing = true;
+        try {
+            while (lineQueue.length > 0) {
+                const input = lineQueue.shift();
+                await processLine(input);
+            }
+        }
+        catch (err) {
+            console.error(chalk.red(`  Internal error: ${err.message}`));
+        }
+        processing = false;
+        menuActive = false;
+        if (pendingClose) {
+            cleanExit(0);
+            return;
+        }
+        if (!closed) {
+            refreshPrompt();
+            restoreReadline();
+            rl.prompt();
+        }
+    }
+    async function processLine(input) {
+        if (!input)
+            return;
+        saveHistory(config.historyFile, input);
+        // Exit
+        if (input === 'exit' || input === 'quit') {
+            const running = runningCount();
+            if (running > 0) {
+                console.log(chalk.yellow(`  ${running} background job(s) still running. They will be cancelled.`));
+            }
+            console.log(chalk.dim('  Goodbye.'));
+            rl.close();
+            return;
+        }
+        // ── ? — quick help ──
+        if (input === '?') {
+            printHelp(config);
+            return;
+        }
+        // ── ! — shell escape (execute in pwsh 7) ──
+        if (input.startsWith('!')) {
+            let shellCmd = input.slice(1).trim();
+            if (shellCmd === '!' || !shellCmd) {
+                if (input === '!!' && lastShellCmd) {
+                    shellCmd = lastShellCmd;
+                    console.log(chalk.dim(`  > ${shellCmd}`));
+                }
+                else if (!shellCmd) {
+                    console.log(chalk.yellow('  Usage: !command  (run in PowerShell 7)'));
+                    console.log(chalk.dim('  !!  repeats last shell command'));
+                    return;
+                }
+            }
+            lastShellCmd = shellCmd;
+            console.log();
+            try {
+                execSync(`pwsh -NoProfile -c "${shellCmd.replace(/"/g, '\\"')}"`, {
+                    stdio: 'inherit',
+                    timeout: 300000,
+                });
+            }
+            catch (err) {
+                if (err.status) {
+                    console.log(chalk.yellow(`  exit ${err.status}`));
+                }
+                else {
+                    console.log(chalk.red(`  Error: ${err.message}`));
+                }
+            }
+            console.log();
+            return;
+        }
+        // ── Check for trailing & — explicit background request ──
+        const explicitBg = input.endsWith(' &') || input.endsWith('\t&');
+        const cleanInput = explicitBg ? input.slice(0, -2).trimEnd() : input;
+        // ── / — slash commands (via Enter, if user typed /command directly) ──
+        if (cleanInput.startsWith('/')) {
+            const spaceIdx = cleanInput.indexOf(' ');
+            const cmdName = spaceIdx > 0 ? cleanInput.slice(1, spaceIdx) : cleanInput.slice(1);
+            const cmdArgs = spaceIdx > 0 ? cleanInput.slice(spaceIdx + 1) : '';
+            if (cmdName === 'exit' || cmdName === 'quit') {
+                console.log(chalk.dim('  Goodbye.'));
+                rl.close();
+                return;
+            }
+            // ── /jobs — built-in job management ──
+            if (cmdName === 'jobs') {
+                handleJobsCommand(cmdArgs);
+                return;
+            }
+            // Bare "/" via Enter — launch picker as fallback
+            if (!cmdName) {
+                if (process.stdin.isTTY && !menuActive) {
+                    menuActive = true;
+                    rl.pause();
+                    await launchCommandPicker();
+                }
+                else {
+                    showCommandList();
+                }
+                return;
+            }
+            const cmd = getCommand(cmdName);
+            if (cmd) {
+                // Auto-background for forge/swarm, or explicit & for any command
+                const shouldBg = explicitBg || AUTO_BG_COMMANDS.has(cmdName);
+                if (shouldBg && cmdName === 'forge') {
+                    // Parse forge args and launch as background job
+                    launchBgForge(client, cmdArgs);
+                    return;
+                }
+                if (shouldBg && cmdName === 'swarm') {
+                    launchBgSwarm(client, cmdArgs);
+                    return;
+                }
+                // Other commands with & — wrap in background job
+                if (explicitBg) {
+                    const { launchCommandJob } = await import('./jobs.js');
+                    const job = launchCommandJob(`/${cmdName} ${cmdArgs}`.trim(), () => cmd.handler(client, cmdArgs, config));
+                    console.log(chalk.dim(`  Background job ${chalk.bold('#' + job.id)} started: /${cmdName}`));
+                    refreshPrompt();
+                    return;
+                }
+                try {
+                    // Fully detach readline from stdin so command handlers that read
+                    // stdin directly (e.g. /login) get exclusive access to keystrokes.
+                    // rl.pause() alone doesn't work — readline's internal 'data'/'keypress'
+                    // listeners still intercept and buffer input.
+                    rl.pause();
+                    const stdinListeners = process.stdin.rawListeners('data').slice();
+                    const keypressListeners = process.stdin.rawListeners('keypress').slice();
+                    process.stdin.removeAllListeners('data');
+                    process.stdin.removeAllListeners('keypress');
+                    if (process.stdin.isTTY)
+                        process.stdin.setRawMode(false);
+                    process.stdin.resume();
+                    await cmd.handler(client, cmdArgs, config);
+                    // Reattach readline's listeners
+                    process.stdin.removeAllListeners('data');
+                    process.stdin.removeAllListeners('keypress');
+                    for (const fn of stdinListeners)
+                        process.stdin.on('data', fn);
+                    for (const fn of keypressListeners)
+                        process.stdin.on('keypress', fn);
+                }
+                catch (err) {
+                    console.log(chalk.red(`  Error: ${err.message}`));
+                }
+                finally {
+                    restoreReadline();
+                }
+            }
+            else {
+                // Try MCP tool fallback — auto-discovered tools are callable as slash commands
+                const mcpTool = registry.getMcpTool(cmdName);
+                if (mcpTool) {
+                    try {
+                        // Parse args as JSON params or key=value pairs
+                        let params = {};
+                        const trimmed = cmdArgs.trim();
+                        if (trimmed.startsWith('{')) {
+                            try {
+                                params = JSON.parse(trimmed);
+                            }
+                            catch { /* not JSON */ }
+                        }
+                        else if (trimmed) {
+                            for (const pair of trimmed.split(/\s+/)) {
+                                const eq = pair.indexOf('=');
+                                if (eq > 0) {
+                                    params[pair.slice(0, eq)] = pair.slice(eq + 1);
+                                }
+                                else {
+                                    params['input'] = pair;
+                                }
+                            }
+                        }
+                        const spinner = (await import('ora')).default(`Calling ${cmdName}...`).start();
+                        const result = await client.post('/tools/call', {
+                            tool: cmdName,
+                            params,
+                        });
+                        spinner.stop();
+                        const output = result?.result || result?.output || result;
+                        console.log(chalk.cyan(`  [MCP: ${cmdName}]`));
+                        console.log(typeof output === 'string' ? output : JSON.stringify(output, null, 2));
+                    }
+                    catch (err) {
+                        console.log(chalk.red(`  MCP tool error: ${err.message}`));
+                    }
+                }
+                else {
+                    const names = getCommandNames();
+                    const close = names.filter(n => n.startsWith(cmdName.toLowerCase().slice(0, 2)));
+                    const hint = close.length
+                        ? `  Did you mean: ${close.map(n => chalk.cyan('/' + n)).join(', ')}?`
+                        : `  Type ${chalk.cyan('/')} to open the command picker.`;
+                    console.log(chalk.yellow(`  Unknown command: /${cmdName}`));
+                    console.log(hint);
+                }
+            }
+            return;
+        }
+        // ── HARD GUARD: special prefixes NEVER become chat messages ──
+        // If we reach this point with a "/" prefix, something went wrong above
+        // (picker edge case, unknown command, etc). Catch it — never send to LLM.
+        if (cleanInput.startsWith('/')) {
+            const attempted = cleanInput.split(/\s+/)[0];
+            console.log(chalk.yellow(`  Unknown command: ${attempted}`));
+            console.log(chalk.dim(`  Type / to open the command picker, or /help for a list.`));
+            return;
+        }
+        // "!" prefix should have been caught above — guard just in case
+        if (cleanInput.startsWith('!')) {
+            console.log(chalk.yellow('  Usage: !command  (run in PowerShell 7)'));
+            return;
+        }
+        // @agent routing vs @strategy triggers
+        // Strategy triggers (@think, @research, @debug, etc.) should be passed
+        // through to Genesis as-is — the StrategyResolver detects them there.
+        // Agent routes (@demiurge, @lyra, @atlas, etc.) set the persona.
+        const STRATEGY_TRIGGERS = new Set([
+            'think', 'reason', 'research', 'council', 'deliberate',
+            'swarm', 'plan', 'agentic', 'compete', 'debug',
+            'troubleshoot', 'investigate', 'quick',
+            // Context-mode directives (ScopeContext)
+            'code', 'internal',
+            // Personal assistant mode
+            'personal',
+            // Companion / conversational mode
+            'chat', 'companion', 'talk',
+            // Creative / story mode
+            'story', 'saga', 'narrative',
+            // AppForge
+            'appforge', 'build',
+            // Security testing strategies
+            'redteam', 'pentest', 'security', 'hack',
+        ]);
+        let agent = config.defaultAgent;
+        let message = cleanInput;
+        // Extract ALL leading @mentions (handles "@aither @demi hi" → agents=["aither","demiurge"])
+        // Each mention is resolved against the AitherDirectory. Unknown mentions
+        // produce a warning and are dropped. Short aliases (e.g., "demi" → "demiurge")
+        // are resolved automatically.
+        const allMentions = cleanInput.match(/^(?:@(\S+)\s+)+/);
+        const resolvedAgents = [];
+        if (allMentions) {
+            const mentionParts = cleanInput.match(/@(\S+)/g) || [];
+            for (const m of mentionParts) {
+                const raw = m.slice(1); // strip '@'
+                if (STRATEGY_TRIGGERS.has(raw.toLowerCase()))
+                    continue;
+                const { resolved, unknown } = resolveAgentMention(raw);
+                if (resolved) {
+                    if (!resolvedAgents.includes(resolved))
+                        resolvedAgents.push(resolved);
+                }
+                else if (unknown) {
+                    console.log(chalk.yellow(`  ⚠ Unknown agent: @${unknown} — not in directory, skipped`));
+                }
+            }
+            if (resolvedAgents.length > 0) {
+                agent = resolvedAgents[0];
+                // Keep the FULL message (with all @mentions) so the backend
+                // IntentClassifier sees them and prevents trivial classification.
+                // The backend strips @mentions internally when building the LLM prompt.
+                message = cleanInput;
+            }
+        }
+        // Strategy triggers: keep the full "@think ..." in message for Genesis
+        // Detect deep strategy triggers that should remove the effort cap
+        const DEEP_TRIGGERS = new Set([
+            'think', 'reason', 'research', 'council', 'agentic',
+            'deliberate', 'debug', 'investigate', 'swarm',
+        ]);
+        const triggerParts = cleanInput.match(/@(\S+)/g) || [];
+        const hasDeepTrigger = triggerParts.some(m => DEEP_TRIGGERS.has(m.slice(1).toLowerCase()));
+        // ── Background chat (explicit & suffix) ──
+        if (explicitBg) {
+            const label = agent !== config.defaultAgent
+                ? `@${agent}: ${message.slice(0, 40)}...`
+                : `Chat: ${message.slice(0, 50)}...`;
+            const job = launchChatJob(client, message, {
+                agent,
+                sessionId: config.sessionId,
+                model: config.model,
+                label,
+            });
+            console.log(chalk.dim(`  Background job ${chalk.bold('#' + job.id)} started: ${label}`));
+            refreshPrompt();
+            return;
+        }
+        // ── Foreground stream chat ──
+        // Pre-flight readiness check — warn before wasting time on a stalled backend
+        try {
+            const healthResp = await fetch(`${config.genesisUrl}/health`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            if (healthResp.ok) {
+                const hData = await healthResp.json();
+                if (hData.generation_ready === false) {
+                    console.log(chalk.yellow('  System busy — LLM pool exhausted (0 slots available).'));
+                    console.log(chalk.dim('  Sending anyway — pool auto-recovers. Use /pool reset to force.'));
+                }
+            }
+        }
+        catch { /* don't block on health check failure */ }
+        // Do NOT pause readline — user can type to steer the active session.
+        // Lines entered during generation are routed to /chat/steer.
+        // The SteeringBar reserves the bottom terminal row for user input.
+        activeAbort = new AbortController();
+        steeringBar.activate();
+        const renderer = createStreamRenderer(config.sessionId, message);
+        // Build session context from previous turn for RLM continuity
+        const prevCtx = lastSessionProfile ? {
+            summary: `Previous prompt: "${lastSessionProfile.prompt.slice(0, 200)}" → ${lastSessionProfile.model}, ${lastSessionProfile.tool_calls.length} tools, ${lastSessionProfile.errors.length} errors`,
+            tools_used: lastSessionProfile.tool_calls.map(t => t.name),
+            model: lastSessionProfile.model,
+            errors: lastSessionProfile.errors,
+        } : undefined;
+        // If there's a pending clarification gate, auto-attach it so the
+        // backend resolves the gate and refines the plan instead of starting
+        // a brand new pipeline. The gate is consumed on use.
+        let clarificationResponse;
+        if (pendingGate) {
+            clarificationResponse = {
+                plan_id: pendingGate.planId,
+                gate_id: pendingGate.gateId,
+                answers: message, // user's natural-language answer
+            };
+            pendingGate = null; // consume — don't re-send on next message
+        }
+        try {
+            const stream = client.streamChat(message, {
+                agent,
+                mentions: resolvedAgents.length > 1 ? resolvedAgents : undefined,
+                sessionId: config.sessionId,
+                model: config.model,
+                signal: activeAbort.signal,
+                clarificationResponse,
+                sessionContext: prevCtx,
+                effort: config.effort,
+                safetyLevel: config.safetyLevel,
+                privateMode: config.privateMode,
+                attachments: config.imageAttachments,
+                maxEffort: hasDeepTrigger ? undefined : (config.effort || 5),
+            });
+            // Clear image attachments after including them — they're one-shot
+            if (config.imageAttachments?.length) {
+                config.imageAttachments = undefined;
+            }
+            let streamTimedOut = false;
+            for await (const event of stream) {
+                renderer.onEvent(event);
+                if (event.type === 'stream_timeout') {
+                    streamTimedOut = true;
+                }
+                // Track clarification_needed events so the NEXT message
+                // auto-resolves the gate without user having to do anything special.
+                if (event.type === 'clarification_needed' && event.data.plan_id) {
+                    pendingGate = {
+                        planId: event.data.plan_id,
+                        gateId: event.data.gate_id || '',
+                        questions: event.data.questions || [],
+                    };
+                }
+            }
+            // Stream ended with timeout — check if forge agent is still running
+            if (streamTimedOut) {
+                console.log(chalk.yellow('\n  ⏱ Stream timed out — no data received for 2 minutes.'));
+                console.log(chalk.dim('  Checking if the agent is still working...'));
+                try {
+                    // Check both forge sessions and Genesis status in parallel
+                    const [forgeData, statusData] = await Promise.all([
+                        Promise.race([
+                            client.get('/forge/sessions'),
+                            new Promise((resolve) => setTimeout(() => resolve(null), 5000)),
+                        ]),
+                        Promise.race([
+                            client.getStatus(),
+                            new Promise((resolve) => setTimeout(() => resolve(null), 5000)),
+                        ]),
+                    ]);
+                    const sessions = forgeData?.sessions || forgeData?.active || [];
+                    const active = Array.isArray(sessions) ? sessions.filter((s) => s.status === 'running' || s.status === 'active') : [];
+                    if (active.length > 0) {
+                        const agentDetails = active.map((s) => {
+                            const name = s.agent || s.agent_id || 'agent';
+                            const elapsed = s.elapsed_ms ? ` (${Math.round(s.elapsed_ms / 1000)}s)` : '';
+                            return `${name}${elapsed}`;
+                        }).join(', ');
+                        console.log(chalk.cyan(`  ✓ Agent still processing: ${agentDetails}`));
+                        console.log(chalk.dim('  The work continues in background — send a follow-up or check /forge.'));
+                    }
+                    else if (statusData) {
+                        const llm = statusData.llm_status || statusData.llm || 'unknown';
+                        console.log(chalk.dim(`  Genesis: ${statusData.status || 'unknown'} | LLM: ${typeof llm === 'object' ? llm.status || 'unknown' : llm}`));
+                        console.log(chalk.dim('  No active forge sessions found. The request may have failed server-side.'));
+                        console.log(chalk.dim('  Try again, or use & suffix to run in background: your message &'));
+                    }
+                    else {
+                        console.log(chalk.red('  Could not reach Genesis — services may be down.'));
+                        console.log(chalk.dim('  Check: /status or docker ps'));
+                    }
+                }
+                catch {
+                    console.log(chalk.dim('  Could not check forge status. The agent may still be processing.'));
+                    console.log(chalk.dim('  Try sending a follow-up message or check /status.'));
+                }
+            }
+        }
+        catch (err) {
+            if (err.name === 'AbortError') {
+                process.stdout.write(chalk.dim('\n  (interrupted)\n'));
+                // Clear any pending gate — the user intentionally aborted
+                pendingGate = null;
+            }
+            else {
+                const msg = err.message || 'unknown error';
+                if (msg.includes('took too long')) {
+                    console.log(chalk.yellow(`\n  ${msg}`));
+                    console.log(chalk.dim('  Checking which services are down...'));
+                    try {
+                        const svcData = await client.getServices();
+                        const services = svcData?.services || [];
+                        const down = services.filter((s) => s.status !== 'healthy' && !s.healthy);
+                        if (down.length) {
+                            console.log(chalk.dim(`  ${down.length} service(s) unreachable:`));
+                            for (const s of down.slice(0, 8)) {
+                                console.log(chalk.red(`    ${s.name}:${s.port || '?'} — ${s.status || 'down'}`));
+                            }
+                            if (down.length > 8)
+                                console.log(chalk.dim(`    ... and ${down.length - 8} more`));
+                            console.log(chalk.dim('\n  Tip: Start more services with:'));
+                            console.log(chalk.cyan('    docker compose -f docker-compose.aitheros.yml --profile chat-full up -d'));
+                        }
+                        else {
+                            console.log(chalk.dim('  All registered services appear healthy. LLM may be overloaded.'));
+                        }
+                    }
+                    catch {
+                        console.log(chalk.dim('  Could not fetch service status.'));
+                    }
+                }
+                else if (msg.includes('Cannot connect') || msg.includes('ECONNREFUSED') || msg.includes('fetch failed')) {
+                    console.log(chalk.red(`  Genesis is not reachable at ${config.genesisUrl}`));
+                    console.log(chalk.dim('  Start it with: docker compose -f docker-compose.aitheros.yml --profile chat-minimal up -d'));
+                }
+                else {
+                    console.log(chalk.red(`  Error: ${msg}`));
+                }
+            }
+        }
+        finally {
+            steeringBar.deactivate();
+            renderer.finish();
+            // Capture session profile for RLM and Strata
+            lastSessionProfile = renderer.getSessionProfile();
+            // Post to Strata (best-effort, non-blocking)
+            postToStrata(client, lastSessionProfile).catch(() => { });
+            // Sync session to remote for cross-client resume
+            syncSessionToRemote({
+                sessionId: config.sessionId,
+                agent: lastSessionProfile.agent || 'aither',
+                messages: [{ role: 'user', content: lastSessionProfile.prompt, timestamp: new Date().toISOString() }],
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            }).catch(() => { });
+            activeAbort = null;
+            if (!closed)
+                restoreReadline();
+        }
+    }
+    /* ── /jobs command handler ──────────────────────────────────── */
+    function handleJobsCommand(args) {
+        const parts = args.trim().split(/\s+/);
+        const sub = parts[0] || '';
+        // /jobs cancel <id>
+        if (sub === 'cancel' || sub === 'kill') {
+            const id = Number(parts[1]);
+            if (!id) {
+                console.log(chalk.yellow('  Usage: /jobs cancel <id>'));
+                return;
+            }
+            if (cancelJob(id)) {
+                console.log(chalk.green(`  Job #${id} cancelled.`));
+                refreshPrompt();
+            }
+            else {
+                console.log(chalk.yellow(`  Job #${id} is not running or doesn't exist.`));
+            }
+            return;
+        }
+        // /jobs <id> — show output
+        const id = Number(sub);
+        if (id > 0) {
+            const job = getJob(id);
+            if (!job) {
+                console.log(chalk.yellow(`  Job #${id} not found.`));
+                return;
+            }
+            console.log(formatJobOutput(job));
+            return;
+        }
+        // /jobs — list all
+        const allJobs = listJobs();
+        if (allJobs.length === 0) {
+            console.log(chalk.dim('  No background jobs.'));
+            return;
+        }
+        console.log(chalk.bold('\n  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();
+    }
+    /* ── Background forge launcher ──────────────────────────────── */
+    function launchBgForge(client, args) {
+        let task = args;
+        let agent;
+        let effort;
+        const agentMatch = args.match(/--agent\s+(\S+)/);
+        if (agentMatch) {
+            agent = agentMatch[1];
+            task = task.replace(agentMatch[0], '');
+        }
+        const effortMatch = args.match(/--effort\s+(\d+)/);
+        if (effortMatch) {
+            effort = Number(effortMatch[1]);
+            task = task.replace(effortMatch[0], '');
+        }
+        task = task.replace(/^["']|["']$/g, '').trim();
+        if (!task) {
+            console.log(chalk.yellow('  Usage: /forge "task description" [--agent name] [--effort N]'));
+            return;
+        }
+        const job = launchForgeJob(client, task, { agent, effort });
+        const who = agent ? `@${agent}` : 'Forge';
+        console.log(chalk.dim(`  ${who} dispatched as background job ${chalk.bold('#' + job.id)}`)
+            + chalk.dim(` (effort ${effort ?? 5})`));
+        refreshPrompt();
+    }
+    /* ── Background swarm launcher ──────────────────────────────── */
+    function launchBgSwarm(client, args) {
+        let task = args;
+        let mode = 'llm';
+        const modeMatch = args.match(/--mode\s+(\S+)/);
+        if (modeMatch) {
+            mode = modeMatch[1];
+            task = task.replace(modeMatch[0], '');
+        }
+        task = task.replace(/^["']|["']$/g, '').trim();
+        if (!task) {
+            console.log(chalk.dim('  Usage: /swarm <task> [--mode forge|llm|plan_only]'));
+            return;
+        }
+        const job = launchSwarmJob(client, task, mode);
+        console.log(chalk.dim(`  Swarm (${mode}) dispatched as background job ${chalk.bold('#' + job.id)}`));
+        refreshPrompt();
+    }
+    // ── Ctrl+C handling ──
+    rl.on('SIGINT', () => {
+        if (activeAbort) {
+            steeringBar.deactivate();
+            activeAbort.abort();
+            activeAbort = null;
+        }
+        else {
+            sigintCount++;
+            if (sigintCount >= 2) {
+                console.log(chalk.dim('\n  Goodbye.'));
+                cleanExit(0);
+            }
+            const running = runningCount();
+            const jobHint = running > 0 ? chalk.dim(` (${running} background job${running > 1 ? 's' : ''} running)`) : '';
+            console.log(chalk.dim('\n  Press Ctrl+C again to exit, or type a message.') + jobHint);
+            rl.prompt();
+            setTimeout(() => { sigintCount = 0; }, 2000);
+        }
+    });
+    // ── Line handler ──
+    function onLine(line) {
+        sigintCount = 0;
+        const input = line.trim();
+        if (!input) {
+            refreshPrompt();
+            rl.prompt();
+            return;
+        }
+        // Slash commands and shell escapes are ALWAYS dispatched locally,
+        // even during active generation — never send them as steering input.
+        if (input.startsWith('/') || input.startsWith('!')) {
+            lineQueue.push(input);
+            drainQueue();
+            return;
+        }
+        // If a foreground generation is active, steer instead of queue
+        if (activeAbort && !closed) {
+            // Special: "cancel" / "stop" / Ctrl+C text → cancel the session
+            const lower = input.toLowerCase();
+            if (lower === 'cancel' || lower === 'stop' || lower === '@abort') {
+                activeAbort.abort();
+                return;
+            }
+            // Steer the active session — inject this input
+            steeringBar.clearInput();
+            client.steer(config.sessionId, input, 'append').catch(() => { });
+            return;
+        }
+        lineQueue.push(input);
+        drainQueue();
+    }
+    rl.on('line', onLine);
+    // ── EOF (Ctrl+D) / stdin close ──
+    rl.on('close', () => {
+        closed = true;
+        // Deregister shell session (best effort, don't block exit)
+        client.post('/shell/session/end', { session_id: config.sessionId }).catch(() => { });
+        if (processing) {
+            pendingClose = true;
+        }
+        else if (!process.stdin.isTTY) {
+            setTimeout(() => cleanExit(0), 10);
+        }
+        else {
+            console.log(chalk.dim('\n  Goodbye.'));
+            cleanExit(0);
+        }
+    });
+    rl.prompt();
+}
+/* ── Help text ─────────────────────────────────────────────── */
+function printHelp(config) {
+    console.log(chalk.bold('\n  AitherShell Quick Reference\n'));
+    console.log(`  ${chalk.cyan('/')}               Interactive command picker (instant)`);
+    console.log(`  ${chalk.cyan('/command')}        Run a command directly`);
+    console.log(`  ${chalk.cyan('@agent message')} Route message to specific agent`);
+    console.log(`  ${chalk.cyan('@mode message')}  Set processing mode (see below)`);
+    console.log(`  ${chalk.cyan('!command')}        Run shell command in PowerShell 7`);
+    console.log(`  ${chalk.cyan('!!')}              Repeat last shell command`);
+    console.log(`  ${chalk.cyan('message')}         Chat with default agent (${config.defaultAgent})`);
+    console.log(`  ${chalk.cyan('exit')} / ${chalk.cyan('Ctrl+D')} Quit`);
+    console.log(`  ${chalk.cyan('Ctrl+C')}          Cancel current request / double-tap to quit`);
+    console.log();
+    console.log(chalk.bold('  @ Directives\n'));
+    console.log(chalk.dim('  Context modes — change what gets loaded:'));
+    console.log(`  ${chalk.cyan('@code')}           Force code context — codegraph + architecture + tools`);
+    console.log(`  ${chalk.cyan('@research')}       Deep web research + synthesis pipeline`);
+    console.log(`  ${chalk.cyan('@internal')}       Full AitherOS internal context (platform only)`);
+    console.log(chalk.dim('  Processing modes — change how the model thinks:'));
+    console.log(`  ${chalk.cyan('@chat')}           Companion mode — fast, natural conversation (persists)`);
+    console.log(`  ${chalk.cyan('@quick')}          Fast response, no deliberation (effort 1–3)`);
+    console.log(`  ${chalk.cyan('@think')}          Deep reasoning with extended deliberation`);
+    console.log(`  ${chalk.cyan('@reason')}         Full reasoning model + structured analysis`);
+    console.log(`  ${chalk.cyan('@agentic')}        Force agentic ReAct loop with tools`);
+    console.log(chalk.dim('  Multi-agent:'));
+    console.log(`  ${chalk.cyan('@debug')}          PRISM-powered debugging — 6 expert personas`);
+    console.log(`  ${chalk.cyan('@troubleshoot')}   Systematic service troubleshooting`);
+    console.log(`  ${chalk.cyan('@investigate')}    Deep exploratory investigation`);
+    console.log(`  ${chalk.cyan('@council')}        6-specialist council review`);
+    console.log(`  ${chalk.cyan('@deliberate')}     Parallel thought streams + convergence`);
+    console.log(`  ${chalk.cyan('@swarm')}          Full 11-agent swarm coding`);
+    console.log(`  ${chalk.cyan('@compete')}        Multiple strategies in parallel — best judged`);
+    console.log();
+    console.log(chalk.bold('  Background Jobs\n'));
+    console.log(`  ${chalk.cyan('message &')}       Run chat in background`);
+    console.log(`  ${chalk.cyan('@agent task &')}   Run agent task in background`);
+    console.log(`  ${chalk.cyan('/forge task')}     Auto-backgrounds (long-running)`);
+    console.log(`  ${chalk.cyan('/swarm task')}     Auto-backgrounds (long-running)`);
+    console.log(`  ${chalk.cyan('/command &')}      Background any slash command`);
+    console.log(`  ${chalk.cyan('/jobs')}            List all background jobs`);
+    console.log(`  ${chalk.cyan('/jobs <id>')}       View job output`);
+    console.log(`  ${chalk.cyan('/jobs cancel <id>')} Cancel a running job`);
+    console.log();
+}
+/* ── Build choices for the interactive command picker ──────── */
+function buildCommandChoices() {
+    const commands = getCommandNames();
+    const registry = getCommandRegistry();
+    const dynamicCmds = registry.allCommands();
+    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 choices = [];
+    const used = new Set();
+    // Merge static + dynamically discovered command names
+    const allCommands = [...new Set([...commands, ...dynamicCmds.map((c) => c.name), 'jobs'])];
+    for (const [cat, names] of categories) {
+        const available = names.filter(n => allCommands.includes(n));
+        if (!available.length)
+            continue;
+        choices.push(new Separator(chalk.bold.dim(` ── ${cat} ──`)));
+        for (const name of available) {
+            if (name === 'jobs') {
+                choices.push({
+                    name: '/jobs',
+                    value: 'jobs',
+                    description: 'List and manage background jobs',
+                });
+                used.add(name);
+                continue;
+            }
+            const cmd = getCommand(name);
+            choices.push({
+                name: `/${name}`,
+                value: name,
+                description: cmd?.description || '',
+            });
+            used.add(name);
+        }
+    }
+    const extra = allCommands.filter(n => !used.has(n) && n !== 'exit' && n !== 'quit');
+    if (extra.length) {
+        choices.push(new Separator(chalk.bold.dim(' ── Other ──')));
+        for (const name of extra) {
+            const cmd = getCommand(name);
+            const dynCmd = !cmd ? registry.resolve(name) : undefined;
+            choices.push({
+                name: `/${name}`,
+                value: name,
+                description: cmd?.description || dynCmd?.description || '',
+            });
+        }
+    }
+    // Add discovered MCP tools as a separate section
+    const mcpTools = registry.getMcpTools();
+    if (mcpTools.length) {
+        choices.push(new Separator(chalk.bold.dim(' ── MCP Tools ──')));
+        for (const tool of mcpTools.slice(0, 15)) {
+            choices.push({
+                name: `/${tool.name}`,
+                value: `mcp:${tool.name}`,
+                description: tool.description || 'MCP tool',
+            });
+        }
+        if (mcpTools.length > 15) {
+            choices.push({
+                name: chalk.dim(`  ... and ${mcpTools.length - 15} more (/tools to see all)`),
+                value: 'tools',
+                description: '',
+            });
+        }
+    }
+    return choices;
+}
+/* ── Fallback static command list (non-TTY) ───────────────── */
+function showCommandList() {
+    const registry = getCommandRegistry();
+    const commands = getCommandNames();
+    console.log(chalk.bold('\n  Commands\n'));
+    for (const name of commands) {
+        if (name === 'exit' || name === 'quit')
+            continue;
+        const cmd = getCommand(name);
+        const dynCmd = !cmd ? registry.resolve(name) : undefined;
+        const desc = (cmd?.description || dynCmd?.description)
+            ? chalk.dim(` — ${cmd?.description || dynCmd?.description}`)
+            : '';
+        console.log(`    ${chalk.cyan('/' + name)}${desc}`);
+    }
+    console.log(`    ${chalk.cyan('/jobs')}${chalk.dim(' — List and manage background jobs')}`);
+    console.log();
+}
+/* ── History persistence ──────────────────────────────────── */
+function loadHistory(file) {
+    try {
+        if (existsSync(file)) {
+            return readFileSync(file, 'utf-8')
+                .split('\n')
+                .filter(Boolean)
+                .slice(-500);
+        }
+    }
+    catch { /* ignore */ }
+    return [];
+}
+function saveHistory(file, line) {
+    try {
+        const dir = dirname(file);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(file, line + '\n');
+    }
+    catch { /* ignore */ }
+}