@aitherium/shell-cli 1.12.0 → 1.12.1

package/dist/client.d.ts

@@ -96,6 +96,16 @@ export declare class GenesisClient {
         effort?: number;
     }): Promise<any>;
     getLogs(limit?: number, level?: string, service?: string): Promise<any>;
+    /** List all expeditions (unified chat jobs, promoted jobs, real expeditions). */
+    listExpeditions(): Promise<any>;
+    /** Get expedition status summary. */
+    getExpeditionStatus(id: string): Promise<any>;
+    /** Get expedition tasks. */
+    getExpeditionTasks(id: string): Promise<any>;
+    /** Steer an expedition with a message (append or hint). */
+    steerExpedition(id: string, message: string, action?: 'append' | 'hint'): Promise<any>;
+    /** Stream SSE events from an expedition. */
+    streamExpeditionEvents(id: string): AsyncGenerator<SSEEvent>;
     getLLMStatus(): Promise<any>;
     /** Resolve the MicroScheduler base URL the same way getLLMStatus does. */
     private _msCandidates;

package/dist/client.js

@@ -305,6 +305,49 @@ export class GenesisClient {
             params.set('service', service);
         return this.get(`/chronicle/logs?${params}`);
     }
+    /* ── Cloud Expeditions (durable jobs) ─────────────────────── */
+    // NOTE: use getDetailed (NOT get) — get() collapses any error to `null`, which
+    // is indistinguishable from "no expeditions". getDetailed preserves {error} so
+    // the REPL can show a real diagnostic (genesis down / 404) vs an empty list.
+    /** List all expeditions (unified chat jobs, promoted jobs, real expeditions). */
+    async listExpeditions() {
+        return this.getDetailed('/expedition/list');
+    }
+    /** Get expedition status summary. */
+    async getExpeditionStatus(id) {
+        return this.getDetailed(`/expedition/${id}/status`);
+    }
+    /** Get expedition tasks. */
+    async getExpeditionTasks(id) {
+        return this.getDetailed(`/expedition/${id}/tasks`);
+    }
+    /** Steer an expedition with a message (append or hint). */
+    async steerExpedition(id, message, action = 'append') {
+        return this.post(`/expedition/${id}/steer`, { message, action });
+    }
+    /** Stream SSE events from an expedition. */
+    async *streamExpeditionEvents(id) {
+        try {
+            const r = await fetch(`${this.baseUrl}/expedition/${id}/stream`, {
+                headers: { 'X-Caller-Type': 'PLATFORM', ...this.authHeaders() },
+                signal: AbortSignal.timeout(600_000), // 10 min timeout for watching
+            });
+            if (!r.ok) {
+                yield {
+                    type: 'error',
+                    data: { type: 'error', error: `HTTP ${r.status}` },
+                };
+                return;
+            }
+            yield* this.readSSE(r);
+        }
+        catch (err) {
+            yield {
+                type: 'error',
+                data: { type: 'error', error: err?.message || 'Stream failed' },
+            };
+        }
+    }
     async getLLMStatus() {
         try {
             const candidates = [process.env.AITHER_LLM_URL, 'https://localhost:8150', 'http://localhost:8150'].filter(Boolean);
@@ -541,11 +584,15 @@ export class GenesisClient {
         const WARN_TIMEOUT_MS = 60_000; // warn after 60s of silence
         let lastChunkAt = Date.now();
         let warningSent = false;
+        // Retain the in-flight read across a warning-yield so reader.read() is
+        // never called twice concurrently (that throws on a locked reader).
+        let pendingRead = null;
         try {
             while (true) {
                 // Race reader.read() against a timeout so the client never hangs
                 // if the backend stalls (e.g. reasoning model cold-start, 404 retry loop).
-                const readPromise = reader.read();
+                const readPromise = pendingRead ?? reader.read();
+                pendingRead = readPromise;
                 // IMPORTANT: keep a handle to the timeout timer and clear it once the
                 // chunk arrives. Otherwise every chunk (hundreds per streamed turn) leaks
                 // a live 120s timer; the swarm of late, post-settle rejections keeps the
@@ -555,16 +602,18 @@ export class GenesisClient {
                 const timeoutPromise = new Promise((_, reject) => {
                     chunkTimer = setTimeout(() => reject(new Error('SSE chunk timeout')), CHUNK_TIMEOUT_MS);
                 });
-                // Intermediate warning if no data for 60s
+                // Warn after 60s of silence WITHOUT consuming the read: race a sentinel
+                // alongside it so we can surface "still working" and keep waiting.
                 let warnTimer = null;
+                const racers = [readPromise, timeoutPromise];
                 if (!warningSent) {
-                    warnTimer = setTimeout(() => {
-                        warningSent = true;
-                    }, WARN_TIMEOUT_MS);
+                    racers.push(new Promise((res) => {
+                        warnTimer = setTimeout(() => res({ __warn: true }), WARN_TIMEOUT_MS);
+                    }));
                 }
                 let result;
                 try {
-                    result = await Promise.race([readPromise, timeoutPromise]);
+                    result = await Promise.race(racers);
                     if (chunkTimer)
                         clearTimeout(chunkTimer);
                     if (warnTimer)
@@ -601,6 +650,13 @@ export class GenesisClient {
                     }
                     break;
                 }
+                // Silence warning fired — surface it and keep waiting on the SAME read.
+                if (result.__warn) {
+                    warningSent = true;
+                    yield { type: 'stream_warning', data: { type: 'stream_warning', silent_ms: Date.now() - lastChunkAt, message: 'Still working — model may be warming up…' } };
+                    continue; // pendingRead retained → no second reader.read()
+                }
+                pendingRead = null; // real chunk consumed
                 lastChunkAt = Date.now();
                 const { done, value } = result;
                 if (done)

package/dist/commands.js

@@ -14,6 +14,7 @@ import { getRemoteMcpClient } from './mcp-client.js';
 import { formatTable, getSessionArtifacts, clearSessionArtifacts, resolveImagePath, osc8Link, addSessionArtifact } from './renderer.js';
 import { loadSession, saveSession, listSessions, deleteSession, transcriptMarkdown, sessionTokens, } from './session-store.js';
 import { loginWithPassword, verify2FA, register, logoutSession, validateToken, buildProfile, setProfile, clearProfile, getActiveProfile, getActiveUser, getActiveToken, requestEmailOTP, verifyEmailOTP, requestDeviceCode, pollDeviceToken, } from './auth.js';
+import { runWizard } from './install-wizard.js';
 const ONBOARD_CODE_EXTENSIONS = new Set([
     '.py', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.java', '.go', '.rs', '.cs',
     '.cpp', '.cc', '.c', '.h', '.hpp', '.rb', '.php', '.swift', '.kt', '.kts', '.scala',
@@ -279,6 +280,13 @@ const COMMANDS = {
             console.log();
         },
     },
+    // ── Installation & onboarding ──
+    install: {
+        description: 'One-click installer wizard (non-technical setup)',
+        handler: async (client, _args, config) => {
+            await runWizard(client, config);
+        },
+    },
     // ── Conversation QoL (transcript-backed) ──
     chats: {
         description: 'List, resume, or delete saved chat conversations',

package/dist/install-wizard.d.ts

@@ -0,0 +1,94 @@
+/**
+ * AitherShell Installer Wizard
+ * ===========================
+ *
+ * Non-technical user flow: one-click installer via interactive prompts.
+ * Guides the user through device-flow login, license provisioning,
+ * endpoint registration, and adk quickstart bootstrap.
+ *
+ * Endpoints called:
+ *   POST /v1/licenses/issue       (Bearer token auth)
+ *   POST /v1/endpoints/register   (X-License-Key header)
+ *   POST /v1/workspace/sync       (X-License-Key header)
+ */
+import type { GenesisClient } from './client.js';
+import type { ShellConfig } from './config.js';
+interface SystemInfo {
+    cpu_count: number;
+    gpu_name?: string;
+    gpu_vram?: number;
+    models_present: string[];
+}
+interface LicenseIssueResponse {
+    license_key: string;
+    tier: string;
+    entitlements: Record<string, unknown>;
+    expires_at: number;
+    sync_interval: number;
+}
+interface EndpointRegisterResponse {
+    endpoint_id: string;
+    tenant_id: string;
+    workspace_id: string;
+    sync_interval: number;
+}
+interface WorkspaceSyncResponse {
+    agent_roster: Record<string, unknown>[];
+    provider_key_refs: string[];
+    settings: Record<string, unknown>;
+    cache_ttl: number;
+}
+export declare class OnboardingClient {
+    private portalUrl;
+    private authToken;
+    constructor(portalUrl?: string);
+    setAuthToken(token: string): void;
+    /**
+     * POST /v1/licenses/issue — Mint a license.
+     * Requires: Bearer token in Authorization header
+     * Returns: license_key, tier, entitlements, expires_at
+     */
+    issueLicense(tierRequest: string, hardwareId?: string): Promise<LicenseIssueResponse>;
+    /**
+     * POST /v1/endpoints/register — Register a compute endpoint.
+     * Requires: license_key in request body
+     * Returns: endpoint_id, tenant_id, workspace_id, sync_interval
+     */
+    registerEndpoint(licenseKey: string, nodeId: string, hostname: string, systemInfo: SystemInfo): Promise<EndpointRegisterResponse>;
+    /**
+     * POST /v1/workspace/sync — Sync workspace configuration.
+     * Requires: X-License-Key header
+     * Returns: agent_roster, provider_key_refs, settings, cache_ttl
+     */
+    syncWorkspace(licenseKey: string, workspaceId: string): Promise<WorkspaceSyncResponse>;
+}
+/**
+ * Collect basic system info for the portal.
+ */
+export declare function collectSystemInfo(): SystemInfo;
+/**
+ * Check if Docker is running (best-effort).
+ * Returns true if 'docker ps' succeeds, false otherwise.
+ */
+export declare function isDockerRunning(): boolean;
+/**
+ * Check if 'adk' command is on PATH.
+ */
+export declare function isAdkAvailable(): boolean;
+/**
+ * Run the interactive installation wizard.
+ *
+ * Flow:
+ *   1. Welcome banner
+ *   2. Check Docker (optional)
+ *   3. Device-flow portal login
+ *   4. Request license tier
+ *   5. Detect system info
+ *   6. Register endpoint
+ *   7. Sync workspace
+ *   8. Run 'adk quickstart-local' (bootstrap Ollama + model)
+ *   9. Persist workspace config
+ *   10. Print success message
+ */
+export declare function runWizard(client: GenesisClient, config: ShellConfig): Promise<void>;
+export {};

package/dist/install-wizard.js

@@ -0,0 +1,397 @@
+/**
+ * AitherShell Installer Wizard
+ * ===========================
+ *
+ * Non-technical user flow: one-click installer via interactive prompts.
+ * Guides the user through device-flow login, license provisioning,
+ * endpoint registration, and adk quickstart bootstrap.
+ *
+ * Endpoints called:
+ *   POST /v1/licenses/issue       (Bearer token auth)
+ *   POST /v1/endpoints/register   (X-License-Key header)
+ *   POST /v1/workspace/sync       (X-License-Key header)
+ */
+import { execSync } from 'node:child_process';
+import { writeFileSync, mkdirSync, chmodSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, cpus } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import chalk from 'chalk';
+import ora from 'ora';
+import { requestDeviceCode, pollDeviceToken, buildProfile, setProfile, } from './auth.js';
+/* ── Onboarding Client ───────────────────────────────────────── */
+export class OnboardingClient {
+    portalUrl;
+    authToken = null;
+    constructor(portalUrl = 'https://portal.aitherium.com') {
+        this.portalUrl = portalUrl.replace(/\/+$/, '');
+    }
+    setAuthToken(token) {
+        this.authToken = token;
+    }
+    /**
+     * POST /v1/licenses/issue — Mint a license.
+     * Requires: Bearer token in Authorization header
+     * Returns: license_key, tier, entitlements, expires_at
+     */
+    async issueLicense(tierRequest, hardwareId) {
+        if (!this.authToken) {
+            throw new Error('Not authenticated — run device-flow login first');
+        }
+        const body = { tier_request: tierRequest };
+        if (hardwareId)
+            body.hardware_id = hardwareId;
+        const resp = await fetch(`${this.portalUrl}/v1/licenses/issue`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${this.authToken}`,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`License issue failed (HTTP ${resp.status}): ${text}`);
+        }
+        return resp.json();
+    }
+    /**
+     * POST /v1/endpoints/register — Register a compute endpoint.
+     * Requires: license_key in request body
+     * Returns: endpoint_id, tenant_id, workspace_id, sync_interval
+     */
+    async registerEndpoint(licenseKey, nodeId, hostname, systemInfo) {
+        const body = {
+            node_id: nodeId,
+            hostname,
+            system_info: systemInfo,
+            license_key: licenseKey,
+        };
+        const resp = await fetch(`${this.portalUrl}/v1/endpoints/register`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Endpoint register failed (HTTP ${resp.status}): ${text}`);
+        }
+        return resp.json();
+    }
+    /**
+     * POST /v1/workspace/sync — Sync workspace configuration.
+     * Requires: X-License-Key header
+     * Returns: agent_roster, provider_key_refs, settings, cache_ttl
+     */
+    async syncWorkspace(licenseKey, workspaceId) {
+        const body = {
+            workspace_id: workspaceId,
+            heartbeat: false,
+        };
+        const resp = await fetch(`${this.portalUrl}/v1/workspace/sync`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-License-Key': licenseKey,
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!resp.ok) {
+            const text = await resp.text().catch(() => '');
+            throw new Error(`Workspace sync failed (HTTP ${resp.status}): ${text}`);
+        }
+        return resp.json();
+    }
+}
+/* ── System Detection ────────────────────────────────────────── */
+/**
+ * Detect CPU count (always available).
+ */
+function detectCpuCount() {
+    return cpus().length;
+}
+/**
+ * Best-effort GPU detection via nvidia-smi (NVIDIA only).
+ * Returns { name, vram } or null if not found.
+ */
+function detectGpu() {
+    try {
+        const out = execSync('nvidia-smi --query-gpu=name,memory.total --format=csv,noheader', {
+            encoding: 'utf-8',
+            timeout: 5000,
+        }).trim();
+        const parts = out.split(',').map((s) => s.trim());
+        if (parts.length >= 2) {
+            const name = parts[0];
+            const vramMb = parseInt(parts[1].replace(/[^0-9]/g, ''), 10);
+            return { name, vram: vramMb };
+        }
+    }
+    catch {
+        // nvidia-smi not found or failed — skip
+    }
+    return null;
+}
+/**
+ * Collect basic system info for the portal.
+ */
+export function collectSystemInfo() {
+    const info = {
+        cpu_count: detectCpuCount(),
+        models_present: [],
+    };
+    const gpu = detectGpu();
+    if (gpu) {
+        info.gpu_name = gpu.name;
+        info.gpu_vram = gpu.vram;
+    }
+    return info;
+}
+/**
+ * Check if Docker is running (best-effort).
+ * Returns true if 'docker ps' succeeds, false otherwise.
+ */
+export function isDockerRunning() {
+    try {
+        execSync('docker ps', { stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if 'adk' command is on PATH.
+ */
+export function isAdkAvailable() {
+    try {
+        execSync('adk --version', { stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/* ── Installation Flow ───────────────────────────────────────── */
+/**
+ * Run the interactive installation wizard.
+ *
+ * Flow:
+ *   1. Welcome banner
+ *   2. Check Docker (optional)
+ *   3. Device-flow portal login
+ *   4. Request license tier
+ *   5. Detect system info
+ *   6. Register endpoint
+ *   7. Sync workspace
+ *   8. Run 'adk quickstart-local' (bootstrap Ollama + model)
+ *   9. Persist workspace config
+ *   10. Print success message
+ */
+export async function runWizard(client, config) {
+    console.log();
+    console.log(chalk.bold(chalk.cyan('╔════════════════════════════════════════╗')));
+    console.log(chalk.bold(chalk.cyan('║   AitherOS Installer Wizard             ║')));
+    console.log(chalk.bold(chalk.cyan('╚════════════════════════════════════════╝')));
+    console.log();
+    // ── Step 1: Check Docker ──────────────────────────────────────────
+    console.log(chalk.bold('Step 1: Pre-flight checks'));
+    const spinner = ora({ prefixText: '  ' });
+    spinner.start('Checking Docker...');
+    const dockerRunning = isDockerRunning();
+    if (dockerRunning) {
+        spinner.succeed('Docker is running');
+    }
+    else {
+        spinner.warn('Docker not running');
+        console.log();
+        console.log(chalk.yellow('  ⚠ Docker is recommended for full AitherOS features.'));
+        console.log(chalk.dim('    Install: https://docker.com'));
+        console.log(chalk.dim('    Or use standalone ADK: pip install aither-adk'));
+        console.log();
+    }
+    // ── Step 2: Device-flow login ────────────────────────────────────
+    console.log();
+    console.log(chalk.bold('Step 2: Sign in to your account'));
+    console.log();
+    let authToken = null;
+    try {
+        const dc = await requestDeviceCode(config.identityUrl, 'AitherShell-Installer');
+        console.log('  Open this URL in your browser:');
+        console.log('  ' + chalk.cyan.underline(dc.verification_uri_complete || dc.verification_uri));
+        if (dc.user_code) {
+            console.log();
+            console.log('  Code: ' + chalk.bold.yellow(dc.user_code));
+        }
+        console.log();
+        spinner.start('Waiting for authorization');
+        const deadline = Date.now() + (dc.expires_in || 900) * 1000;
+        const interval = Math.max(2, dc.interval || 5) * 1000;
+        while (Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, interval));
+            try {
+                const result = await pollDeviceToken(config.identityUrl, dc.device_code);
+                if ((result.status === 'complete' || result.status === 'authorized') &&
+                    result.access_token) {
+                    authToken = result.access_token;
+                    const profile = buildProfile(config.identityUrl, config.genesisUrl, result);
+                    setProfile('local', profile);
+                    config.authToken = authToken;
+                    config.authUser = profile.user;
+                    spinner.succeed(chalk.green(`Signed in as ${profile.user.display_name || profile.user.username}`));
+                    break;
+                }
+            }
+            catch (err) {
+                if (String(err?.message || '').includes('expired')) {
+                    spinner.fail('Device code expired');
+                    throw err;
+                }
+            }
+        }
+        if (!authToken) {
+            spinner.fail('Sign-in timed out');
+            throw new Error('Authorization timeout');
+        }
+    }
+    catch (err) {
+        console.log();
+        console.error(chalk.red(`  Error during sign-in: ${err.message}`));
+        process.exit(1);
+    }
+    console.log();
+    // ── Step 3: Issue license ────────────────────────────────────────
+    console.log(chalk.bold('Step 3: Provision license'));
+    const onboarding = new OnboardingClient(process.env.AITHER_PORTAL_URL || 'https://portal.aitherium.com');
+    onboarding.setAuthToken(authToken);
+    let licenseKey;
+    let workspaceId;
+    spinner.start('Requesting license...');
+    try {
+        const licenseResp = await onboarding.issueLicense('developer');
+        licenseKey = licenseResp.license_key;
+        spinner.succeed(`License issued: ${licenseResp.tier} (expires ${new Date(licenseResp.expires_at * 1000).toLocaleDateString()})`);
+    }
+    catch (err) {
+        spinner.fail(`License request failed: ${err.message}`);
+        console.error(chalk.red(`  ${err.message}`));
+        process.exit(1);
+    }
+    console.log();
+    // ── Step 4: Collect system info ──────────────────────────────────
+    console.log(chalk.bold('Step 4: Detect system hardware'));
+    spinner.start('Collecting system info...');
+    const systemInfo = collectSystemInfo();
+    spinner.succeed(`CPU: ${systemInfo.cpu_count} cores${systemInfo.gpu_name ? `, GPU: ${systemInfo.gpu_name}` : ''}`);
+    console.log();
+    // ── Step 5: Register endpoint ────────────────────────────────────
+    console.log(chalk.bold('Step 5: Register endpoint'));
+    const nodeId = process.env.HOSTNAME || randomUUID().slice(0, 12);
+    const hostname = nodeId;
+    spinner.start('Registering endpoint...');
+    try {
+        const regResp = await onboarding.registerEndpoint(licenseKey, nodeId, hostname, systemInfo);
+        workspaceId = regResp.workspace_id;
+        spinner.succeed(`Endpoint registered: ${regResp.endpoint_id}`);
+    }
+    catch (err) {
+        spinner.fail(`Endpoint registration failed: ${err.message}`);
+        console.error(chalk.red(`  ${err.message}`));
+        process.exit(1);
+    }
+    console.log();
+    // ── Step 6: Sync workspace ───────────────────────────────────────
+    console.log(chalk.bold('Step 6: Sync workspace'));
+    spinner.start('Syncing workspace configuration...');
+    try {
+        await onboarding.syncWorkspace(licenseKey, workspaceId);
+        spinner.succeed('Workspace synced');
+    }
+    catch (err) {
+        spinner.warn(`Workspace sync failed (non-fatal): ${err.message}`);
+    }
+    console.log();
+    // ── Step 7: ADK Quickstart ───────────────────────────────────────
+    console.log(chalk.bold('Step 7: Bootstrap ADK and models'));
+    console.log();
+    let adkAvailable = isAdkAvailable();
+    if (!adkAvailable) {
+        spinner.start('Installing aither-adk...');
+        try {
+            execSync('pip install aither-adk', { stdio: 'inherit', timeout: 60000 });
+            spinner.succeed('aither-adk installed');
+            adkAvailable = true;
+        }
+        catch (err) {
+            spinner.warn('Could not auto-install aither-adk. Please run: pip install aither-adk');
+        }
+    }
+    if (adkAvailable) {
+        console.log();
+        console.log(chalk.dim('  Running: adk quickstart-local'));
+        console.log(chalk.dim('  (This bootstraps Ollama and downloads a model — may take a few minutes)'));
+        console.log();
+        try {
+            execSync('adk quickstart-local', { stdio: 'inherit' });
+        }
+        catch (err) {
+            console.error(chalk.yellow('\n  ⚠ ADK quickstart encountered an error'));
+            console.error(chalk.dim(`  Error: ${err.message}`));
+            console.log();
+            console.log(chalk.dim('  You can retry manually: adk quickstart-local'));
+        }
+    }
+    console.log();
+    // ── Step 8: Persist workspace config ─────────────────────────────
+    console.log(chalk.bold('Step 8: Save configuration'));
+    const configDir = join(homedir(), '.aither');
+    const workspaceConfPath = join(configDir, 'workspace.conf');
+    const workspaceConf = {
+        workspace_id: workspaceId,
+        license_key: licenseKey,
+        node_id: nodeId,
+        endpoint_id: nodeId,
+        registered_at: new Date().toISOString(),
+    };
+    try {
+        if (!existsSync(configDir)) {
+            mkdirSync(configDir, { recursive: true });
+        }
+        writeFileSync(workspaceConfPath, JSON.stringify(workspaceConf, null, 2), 'utf-8');
+        try {
+            chmodSync(workspaceConfPath, 0o600);
+        }
+        catch {
+            // Windows — ignore chmod errors
+        }
+        spinner.succeed(`Workspace config saved to ${workspaceConfPath}`);
+    }
+    catch (err) {
+        spinner.warn(`Could not save workspace config: ${err.message}`);
+    }
+    console.log();
+    // ── Success banner ───────────────────────────────────────────────
+    console.log(chalk.green(chalk.bold('✓ Installation complete!')));
+    console.log();
+    console.log('  Next steps:');
+    console.log();
+    console.log(chalk.cyan('  1. Start the shell:'));
+    console.log(chalk.dim('     aither'));
+    console.log();
+    console.log(chalk.cyan('  2. View dashboard (if Docker is running):'));
+    console.log(chalk.dim('     http://localhost:3000'));
+    console.log();
+    console.log(chalk.cyan('  3. Try a quick command:'));
+    console.log(chalk.dim('     aither "What services are running?"'));
+    console.log();
+    if (!dockerRunning) {
+        console.log(chalk.yellow('  ℹ Docker is not running.'));
+        console.log(chalk.dim('    Start Docker Desktop to unlock the full dashboard and GPU inference.'));
+        console.log();
+    }
+}

package/dist/main.js

@@ -251,7 +251,7 @@ async function main() {
     // ── Explicit one-shot subcommands that must NOT fall through to chat ──
     // e.g. `aither node ls`, `aither node enroll --tenant acme`. Without this,
     // "node ls" became a positional chat prompt → intent-classified as a query.
-    const ONESHOT_CMDS = new Set(['node', 'nodes']);
+    const ONESHOT_CMDS = new Set(['node', 'nodes', 'install']);
     if (args[0] && ONESHOT_CMDS.has(args[0].toLowerCase())) {
         const { getCommand } = await import('./commands.js');
         const cmd = getCommand(args[0].toLowerCase());

package/dist/renderer.js

@@ -379,6 +379,11 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
     let lastStage = ''; // Current pipeline stage — shown in heartbeat spinner
     let eagerActive = false; // Eager streaming: multiple answer_segments this turn
     let eagerSegments = 0; // Count of segments rendered
+    let segmentTokenStreamed = false; // Did THIS segment receive token events? If a
+    // segment header printed but no tokens arrived
+    // (engine sent the answer as one 'answer' event),
+    // we must print the answer ourselves or the user
+    // is left staring at just the preamble line.
     // ── Session trace collection ──
     const traceEvents = [];
     const traceToolCalls = [];
@@ -592,6 +597,7 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         log(chalk.cyan('  💬 Initial') + segReason);
                     }
                     tokensStarted = false; // re-enter first-token path for this segment
+                    segmentTokenStreamed = false; // reset per-segment token tracking
                     content = ''; // per-segment accumulator (final captured at complete)
                     break;
                 }
@@ -614,6 +620,7 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     process.stdout.write(t);
                     hasOutput = true;
                     tokenStreamed = true;
+                    segmentTokenStreamed = true;
                     contentDisplayed = true;
                     break;
                 }
@@ -622,10 +629,21 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                 case 'final_answer': {
                     stopSpinner();
                     // Eager streaming already rendered the answer as live segments —
-                    // the terminal `answer` event is just the canonical copy for
-                    // trace/getContent. Capture it, don't re-print.
+                    // the terminal `answer` event is normally just the canonical copy
+                    // for trace/getContent. BUT if the current segment printed a header
+                    // ("💬 Initial …") yet no token events streamed (the engine returned
+                    // the answer as a single 'answer' event, e.g. the search fastpath),
+                    // the user would see only the preamble. In that case print it now.
                     if (eagerActive) {
-                        content = event.data.answer || event.data.content || content;
+                        const eagerAnswer = event.data.answer || event.data.content || content;
+                        if (!segmentTokenStreamed && eagerAnswer && eagerAnswer.trim()) {
+                            process.stdout.write('\r\x1b[2K');
+                            process.stdout.write(renderMarkdown(wrapBareCode(eagerAnswer)));
+                            if (!eagerAnswer.endsWith('\n'))
+                                process.stdout.write('\n');
+                            segmentTokenStreamed = true; // guard against double-print at complete
+                        }
+                        content = eagerAnswer;
                         contentDisplayed = true;
                         hasOutput = true;
                         break;
@@ -686,6 +704,25 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                     }
                     break;
                 }
+                case 'tool_decision': {
+                    // Pre-execution preamble: names the chosen tools the instant they're
+                    // parsed, before the (silent) tool execution wait.
+                    stopSpinner();
+                    const preamble = event.data.preamble
+                        || `Calling tools: ${(event.data.tools || []).join(', ')}`;
+                    log('  ' + chalk.yellow(`⚡ ${preamble}`));
+                    break;
+                }
+                case 'tool_call_preview': {
+                    // Trace-only: the model committed to a tool NAME mid-stream. Shown the
+                    // instant it's known; execution still happens from the done chunk.
+                    stopSpinner();
+                    const argHint = event.data.arguments_preview
+                        ? chalk.gray(` ${String(event.data.arguments_preview).slice(0, 80)}`)
+                        : '';
+                    log('  ' + chalk.yellow(`🔧 Calling ${event.data.name || 'tool'}…`) + argHint);
+                    break;
+                }
                 case 'tool_call': {
                     stopSpinner();
                     const turnLabel2 = event.data.turn != null ? chalk.cyan(`[Turn ${event.data.turn}] `) : '';
@@ -778,6 +815,17 @@ export function createStreamRenderer(sessionId, prompt, steeringBar) {
                         hasOutput = true;
                     break;
                 }
+                case 'suggested_followups': {
+                    // Proactive next-steps. Plain REPL is append-only (no digit-select);
+                    // the eager answer already streamed above, so these land beneath it.
+                    const fups = Array.isArray(event.data.followups) ? event.data.followups : [];
+                    if (fups.length) {
+                        process.stdout.write('\n' + chalk.dim('  Next →') + '\n');
+                        fups.forEach((t, i) => process.stdout.write('  ' + chalk.cyan(`[${i + 1}]`) + ' ' + chalk.dim(String(t)) + '\n'));
+                        hasOutput = true;
+                    }
+                    break;
+                }
                 case 'done':
                 case 'complete': {
                     stopSpinner();

package/dist/repl.js

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

package/dist/tui/controller.js

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

package/dist/tui/repl-tui.js

@@ -109,6 +109,11 @@ export async function startTuiRepl(client, config) {
     let histIdx = history.length;
     let activeAbort = null;
     let processing = false;
+    // Type-ahead queue: messages typed while a turn is streaming. Run as fresh
+    // turns the instant the current one finishes (Claude-Code style) instead of
+    // being dropped into a steer that oneshot/trivial turns silently discard.
+    let queuedInputs = [];
+    let draining = false;
     let sigintCount = 0;
     let sigintTimer = null;
     let gpuTag = '';
@@ -298,8 +303,13 @@ export async function startTuiRepl(client, config) {
         }
         sigintCount++;
         if (sigintCount >= 2) {
+            const q = queuedInputs.length;
             setTuiActive(null);
             surface.destroy();
+            // Write AFTER destroy so it lands in the restored terminal, not the
+            // torn-down blessed screen — otherwise the user never sees it.
+            if (q)
+                process.stderr.write(`\n⚠ Discarded ${q} queued message(s).\n`);
             process.exit(0);
         }
         surface.setStatus('Ctrl+C again to exit');
@@ -390,18 +400,54 @@ export async function startTuiRepl(client, config) {
                 relayStatus('sent · agents may reply…');
             return;
         }
-        // Steer an active stream.
+        // A turn is in flight. cancel/stop/abort interrupt it; anything else is
+        // queued and run as a fresh turn the moment this one finishes. (The old
+        // fire-and-forget steer was silently dropped on oneshot/trivial turns —
+        // which is every plain question — so the message just vanished.)
         if (activeAbort && processing) {
             const lower = clean.toLowerCase();
             if (lower === 'cancel' || lower === 'stop' || lower === '@abort') {
                 onInterrupt();
                 return;
             }
-            surface.traceLine(chalk.yellow(`  🔄 steer: ${clean}`));
-            client.steer(config.sessionId, clean, 'append').catch(() => { });
+            queuedInputs.push(clean);
+            surface.traceLine(chalk.cyan(`  ⏳ queued (${queuedInputs.length}) — sends after this turn`));
             return;
         }
-        await runChat(clean, explicitBg);
+        // Bare digit (1-9) → expand to the Nth follow-up suggestion from the last turn.
+        const _pick = clean.match(/^([1-9])$/);
+        if (_pick) {
+            const fups = surface.getPendingFollowups();
+            const idx = parseInt(_pick[1], 10) - 1;
+            if (idx >= 0 && idx < fups.length) {
+                const chosen = fups[idx];
+                surface.setPendingFollowups([]); // consume
+                surface.outputLine(chalk.dim(`  → ${chosen}`));
+                await runChatDraining(chosen, explicitBg);
+                return;
+            }
+        }
+        surface.setPendingFollowups([]); // any new message invalidates last turn's chips
+        await runChatDraining(clean, explicitBg);
+    }
+    /** Run a chat turn, then drain any messages the user typed while it streamed,
+     *  running each as its own turn in order. The `draining` guard keeps two
+     *  rapid submits from spinning up overlapping drain loops. */
+    async function runChatDraining(input, bg = false) {
+        await runChat(input, bg);
+        if (draining)
+            return;
+        draining = true;
+        try {
+            while (queuedInputs.length && !processing) {
+                const next = queuedInputs.shift();
+                surface.outputLine(chalk.green('› ') + chalk.dim('(queued) ') + next);
+                await runChat(next, false);
+            }
+        }
+        finally {
+            draining = false;
+        }
     }
     function showHelp() {
         surface.outputLine(chalk.bold('Keys: ') + chalk.dim('Edit: ←/→ move · Ctrl+A/E line start/end · Ctrl+W del word · Ctrl+U/K kill · Home/End (empty line=scroll) | Panes: wheel/PgUp scroll · Ctrl+←/→ resize split · Ctrl+T trace · Ctrl+E expand all · click thread | Ctrl+C abort/exit · Tab complete'));
@@ -427,9 +473,76 @@ export async function startTuiRepl(client, config) {
         }
         surface.focusInput();
     }
-    function handleJobs(args) {
+    async function handleJobs(args) {
         const parts = args.trim().split(/\s+/);
         const sub = parts[0] || '';
+        // ── Cloud (durable expedition) jobs — mirror the classic REPL surface ──
+        if (sub === 'cloud') {
+            const expId = parts[1];
+            if (!expId) {
+                const result = await client.listExpeditions();
+                if (!result || result.error) {
+                    surface.outputLine(chalk.red(`  Error: ${result?.error || 'Failed to list expeditions'}`));
+                    return;
+                }
+                const exps = result.expeditions || [];
+                if (!exps.length) {
+                    surface.outputLine(chalk.dim('  No cloud expeditions.'));
+                    return;
+                }
+                surface.outputLine(chalk.bold('  Cloud Expeditions (Durable Jobs)'));
+                for (const e of exps) {
+                    surface.outputLine(`  ${chalk.bold(String(e.id).slice(0, 8))}  ${e.status || '?'}  ${(e.title || '').slice(0, 44)}`);
+                }
+                surface.outputLine(chalk.dim('  /jobs cloud <id> · /jobs steer <id> <msg> · /jobs watch <id>'));
+                return;
+            }
+            const status = await client.getExpeditionStatus(expId);
+            if (!status || status.error) {
+                surface.outputLine(chalk.red(`  Expedition not found: ${expId}`));
+                return;
+            }
+            surface.outputLine(`  ${chalk.bold(expId)}  status: ${status.status || '?'}`);
+            const tasks = await client.getExpeditionTasks(expId);
+            for (const t of (tasks?.tasks || [])) {
+                const out = (t.result_summary || t.error || '').slice(0, 500);
+                surface.outputLine(`  • ${t.title || t.id}: ${t.status}${out ? `\n    ${out}` : ''}`);
+            }
+            return;
+        }
+        if (sub === 'steer' || sub === 'hint') {
+            const expId = parts[1];
+            const msg = parts.slice(2).join(' ');
+            if (!expId || !msg) {
+                surface.outputLine(chalk.yellow(`Usage: /jobs ${sub} <id> <message>`));
+                return;
+            }
+            const r = await client.steerExpedition(expId, msg, sub === 'hint' ? 'hint' : 'append');
+            surface.outputLine(r?.ok ? chalk.green(`  Steered ${expId} (${sub}).`) : chalk.red(`  Steer failed: ${r?.error || r?.detail || 'unknown'}`));
+            return;
+        }
+        if (sub === 'watch') {
+            const expId = parts[1];
+            if (!expId) {
+                surface.outputLine(chalk.yellow('Usage: /jobs watch <id>'));
+                return;
+            }
+            surface.outputLine(chalk.dim(`  Watching ${expId}…`));
+            try {
+                for await (const ev of client.streamExpeditionEvents(expId)) {
+                    const d = ev.data || {};
+                    const line = d.message || d.error || ev.type;
+                    if (line)
+                        surface.outputLine(`  [${ev.type}] ${line}`);
+                    if (ev.type === 'error' || d.status === 'completed' || d.status === 'failed')
+                        break;
+                }
+            }
+            catch (err) {
+                surface.outputLine(chalk.red(`  Watch error: ${err.message}`));
+            }
+            return;
+        }
         if (sub === 'cancel' || sub === 'kill') {
             const id = Number(parts[1]);
             if (!id) {
@@ -738,7 +851,7 @@ export async function startTuiRepl(client, config) {
             return;
         }
         if (name === 'jobs') {
-            handleJobs(args);
+            await handleJobs(args);
             return;
         }
         if (name === 'relay') {
@@ -868,7 +981,9 @@ export async function startTuiRepl(client, config) {
                     surface.traceLine(chalk.yellow('  ⚠ LLM pool busy (0 slots) — sending anyway'));
             }
         }
-        catch { /* */ }
+        catch {
+            surface.traceLine(chalk.yellow('  ⚠ pre-flight check failed (backend slow or down) — sending anyway'));
+        }
         surface.outputLine(chalk.green('› ') + input);
         surface.setStatus('working…');
         // Open a fresh, collapsible trace thread for this turn (older turns collapse).
@@ -936,8 +1051,11 @@ export async function startTuiRepl(client, config) {
                         aborted = true;
                         surface.outputLine(chalk.dim('  (interrupted)'));
                     }
-                    else
-                        surface.outputLine(chalk.red(`  Error: ${err?.message || err}`));
+                    else {
+                        // First line only, bounded — never spray a raw stack/JSON at the user.
+                        const raw = typeof err?.message === 'string' ? err.message : String(err);
+                        surface.outputLine(chalk.red(`  Error: ${raw.split('\n')[0].slice(0, 200)}`));
+                    }
                     renderer.finish(aborted);
                     break;
                 }

package/dist/tui/screen.d.ts

@@ -33,6 +33,11 @@ export interface TuiSurface {
     clearPanes(): void;
     /** Show/hide the TRACE pane (OUTPUT widens to fill). */
     toggleTrace(): void;
+    /** Stash the suggested follow-ups from the last turn so a bare digit in the
+     *  input box can expand to "send the Nth follow-up". Cleared when consumed. */
+    setPendingFollowups(items: string[]): void;
+    /** The currently-stashed follow-ups (empty if none / already consumed). */
+    getPendingFollowups(): string[];
     /** Coalesced repaint. */
     render(): void;
     /** Focus the input box for typing. */

package/dist/tui/screen.js

@@ -155,6 +155,9 @@ export function createTuiScreen(opts) {
         scheduleRender();
     }
     function markCheckpoint() { return outputBuf.length; }
+    let pendingFollowups = [];
+    function setPendingFollowups(items) { pendingFollowups = Array.isArray(items) ? items.slice(0, 9) : []; }
+    function getPendingFollowups() { return pendingFollowups; }
     function replaceOutputFrom(offset, text) {
         if (offset < 0 || offset > outputBuf.length)
             return;
@@ -199,6 +202,18 @@ export function createTuiScreen(opts) {
                 for (const l of t.lines)
                     out.push(l);
         });
+        // Belt-and-suspenders against blessed "character bleed": when the trace
+        // SHRINKS (a long turn collapses into a short new one) blessed's wide-char
+        // (emoji) miscount in wrapped lines leaves stale glyphs in the now-uncovered
+        // rows. clearRegion alone proved unreliable for this, so when the content is
+        // shorter than the pane, pad with blank lines so setContent paints over every
+        // visible row. Skip when the user has scrolled up (don't perturb their view)
+        // or when content already fills/overflows the pane (no uncovered rows).
+        if (!userPinnedTrace) {
+            const innerH = (typeof trace.height === 'number' ? trace.height : 0) - 2;
+            while (innerH > out.length)
+                out.push('');
+        }
         const base = trace.childBase || 0;
         try {
             trace.setContent(out.join('\n'));
@@ -1040,6 +1055,7 @@ export function createTuiScreen(opts) {
     return {
         screen, input, appendOutput, outputLine, markCheckpoint, replaceOutputFrom, prependOutput,
         traceLine, startTraceTurn, finishTraceTurn, setStatus, setTracePanel, setOutputLabel, clearPanes, toggleTrace, render, focusInput, destroy,
+        setPendingFollowups, getPendingFollowups,
         pickerOpen, showPicker, showViewer, showEditor, runDetached,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitherium/shell-cli",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "description": "Interactive terminal for AitherOS and ADK agents",
   "license": "BUSL-1.1",
   "type": "module",