@ekkos/cli 0.2.18 → 1.0.0

package/dist/capture/transcript-repair.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Transcript Repair - Handles orphan tool_result recovery
+ *
+ * When ccDNA's validate mode detects orphan tool_results (tool_result without
+ * matching tool_use), this module repairs the transcript:
+ *
+ * 1. ROLLBACK (preferred): Restore from backup if valid
+ * 2. SURGICAL REPAIR (fallback): Remove orphan tool_result lines
+ *
+ * This closes the loop: ccDNA detects → ekkos-cli repairs → /clear + /continue
+ */
+type RepairAction = 'none' | 'rollback' | 'surgical_repair' | 'failed';
+export interface RepairResult {
+    action: RepairAction;
+    orphansFound: number;
+    removedLines?: number;
+    backupUsed?: string;
+    reason?: string;
+}
+/**
+ * Minimal validator: tool_result.tool_use_id must reference a tool_use.id that
+ * appears earlier in the transcript (in-order).
+ */
+export declare function countOrphansInJsonl(jsonlPath: string): {
+    orphans: number;
+    orphanIds: string[];
+    lineCount: number;
+};
+/**
+ * Main entry point: repair or rollback a transcript with orphan tool_results.
+ *
+ * Strategy:
+ * 1. Check if there are orphans (exit early if none)
+ * 2. Try rollback to newest valid backup
+ * 3. If no valid backup, surgically remove orphan lines
+ */
+export declare function repairOrRollbackTranscript(jsonlPath: string): RepairResult;
+/**
+ * Quick validation check - can be called before operations to verify health.
+ */
+export declare function isTranscriptHealthy(jsonlPath: string): boolean;
+/**
+ * Get detailed transcript health info.
+ */
+export declare function getTranscriptHealth(jsonlPath: string): {
+    exists: boolean;
+    healthy: boolean;
+    orphans: number;
+    orphanIds: string[];
+};
+export {};

package/dist/capture/transcript-repair.js

@@ -0,0 +1,319 @@
+"use strict";
+/**
+ * Transcript Repair - Handles orphan tool_result recovery
+ *
+ * When ccDNA's validate mode detects orphan tool_results (tool_result without
+ * matching tool_use), this module repairs the transcript:
+ *
+ * 1. ROLLBACK (preferred): Restore from backup if valid
+ * 2. SURGICAL REPAIR (fallback): Remove orphan tool_result lines
+ *
+ * This closes the loop: ccDNA detects → ekkos-cli repairs → /clear + /continue
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countOrphansInJsonl = countOrphansInJsonl;
+exports.repairOrRollbackTranscript = repairOrRollbackTranscript;
+exports.isTranscriptHealthy = isTranscriptHealthy;
+exports.getTranscriptHealth = getTranscriptHealth;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+// Debug logging to the same file as eviction
+function debugLog(category, msg, data) {
+    try {
+        const logDir = path.join(os.homedir(), '.ekkos', 'logs');
+        if (!fs.existsSync(logDir))
+            fs.mkdirSync(logDir, { recursive: true });
+        const logPath = path.join(logDir, 'eviction-debug.log');
+        const ts = new Date().toISOString();
+        const line = `[${ts}] [REPAIR:${category}] ${msg}${data ? '\n  ' + JSON.stringify(data, null, 2).replace(/\n/g, '\n  ') : ''}`;
+        fs.appendFileSync(logPath, line + '\n');
+    }
+    catch {
+        // Silent fail
+    }
+}
+/**
+ * Minimal validator: tool_result.tool_use_id must reference a tool_use.id that
+ * appears earlier in the transcript (in-order).
+ */
+function countOrphansInJsonl(jsonlPath) {
+    const content = fs.readFileSync(jsonlPath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    const seenToolUses = new Set();
+    const orphanIds = [];
+    for (const line of lines) {
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const blocks = obj?.message?.content;
+        if (!Array.isArray(blocks))
+            continue;
+        for (const b of blocks) {
+            const block = b;
+            if (block?.type === 'tool_use' && typeof block?.id === 'string') {
+                seenToolUses.add(block.id);
+            }
+            else if (block?.type === 'tool_result' && typeof block?.tool_use_id === 'string') {
+                if (!seenToolUses.has(block.tool_use_id)) {
+                    orphanIds.push(block.tool_use_id);
+                }
+            }
+        }
+    }
+    return { orphans: orphanIds.length, orphanIds, lineCount: lines.length };
+}
+/**
+ * Find plausible backups for a jsonl file.
+ * Our jsonl-rewriter uses: ${filePath}.backup (single backup)
+ */
+function findBackups(jsonlPath) {
+    const dir = path.dirname(jsonlPath);
+    const base = path.basename(jsonlPath);
+    if (!fs.existsSync(dir))
+        return [];
+    const candidates = [];
+    // Primary backup: exact .backup suffix (from jsonl-rewriter.ts)
+    const primaryBackup = `${jsonlPath}.backup`;
+    if (fs.existsSync(primaryBackup)) {
+        candidates.push(primaryBackup);
+    }
+    // Also check for other backup patterns in case user has manual backups
+    const files = fs.readdirSync(dir);
+    const additionalBackups = files
+        .filter(f => f.startsWith(base) &&
+        f !== base &&
+        (f.includes('.bak') || f.includes('.backup') || f.includes('.old') || f.includes('.prev')))
+        .map(f => path.join(dir, f))
+        .filter(f => !candidates.includes(f)) // Don't duplicate
+        .sort((a, b) => {
+        // Sort by mtime, newest first
+        const am = fs.statSync(a).mtimeMs;
+        const bm = fs.statSync(b).mtimeMs;
+        return bm - am;
+    });
+    return [...candidates, ...additionalBackups];
+}
+/**
+ * Atomically replace target file with source file.
+ * Keeps the corrupted version for forensics.
+ */
+function atomicReplace(target, source) {
+    const dir = path.dirname(target);
+    const tmp = path.join(dir, `${path.basename(target)}.tmp-repair-${Date.now()}`);
+    fs.copyFileSync(source, tmp);
+    const corrupt = path.join(dir, `${path.basename(target)}.corrupt-${Date.now()}`);
+    fs.renameSync(target, corrupt);
+    fs.renameSync(tmp, target);
+    debugLog('ATOMIC_REPLACE', 'Replaced corrupt file', {
+        target,
+        source,
+        corruptBackup: corrupt,
+    });
+}
+/**
+ * Surgical repair: drop any line that contains a tool_result whose tool_use_id
+ * has not appeared earlier in the file. This unbricks at the cost of losing those results.
+ */
+function surgicalRepair(jsonlPath) {
+    const content = fs.readFileSync(jsonlPath, 'utf-8');
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    const seenToolUses = new Set();
+    const kept = [];
+    let removed = 0;
+    for (const line of lines) {
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            // Keep non-JSON lines (shouldn't happen, but safe)
+            kept.push(line);
+            continue;
+        }
+        const blocks = obj?.message?.content;
+        if (!Array.isArray(blocks)) {
+            kept.push(line);
+            continue;
+        }
+        // First pass: collect tool_use IDs from this line
+        const lineToolUseIds = [];
+        for (const b of blocks) {
+            const block = b;
+            if (block?.type === 'tool_use' && typeof block?.id === 'string') {
+                lineToolUseIds.push(block.id);
+            }
+        }
+        // Second pass: check for orphan tool_results
+        let hasOrphanResult = false;
+        for (const b of blocks) {
+            const block = b;
+            if (block?.type === 'tool_result' && typeof block?.tool_use_id === 'string') {
+                if (!seenToolUses.has(block.tool_use_id)) {
+                    hasOrphanResult = true;
+                    debugLog('SURGICAL_DROP', 'Dropping line with orphan tool_result', {
+                        tool_use_id: block.tool_use_id,
+                        linePreview: line.slice(0, 200),
+                    });
+                }
+            }
+        }
+        if (hasOrphanResult) {
+            removed++;
+            continue;
+        }
+        // If kept, update seen tool uses AFTER keeping (order matters)
+        for (const id of lineToolUseIds) {
+            seenToolUses.add(id);
+        }
+        kept.push(line);
+    }
+    // Write atomically
+    const dir = path.dirname(jsonlPath);
+    const tmp = path.join(dir, `${path.basename(jsonlPath)}.tmp-surgical-${Date.now()}`);
+    fs.writeFileSync(tmp, kept.join('\n') + '\n', 'utf-8');
+    const corrupt = path.join(dir, `${path.basename(jsonlPath)}.corrupt-${Date.now()}`);
+    fs.renameSync(jsonlPath, corrupt);
+    fs.renameSync(tmp, jsonlPath);
+    const { orphans: orphansAfter } = countOrphansInJsonl(jsonlPath);
+    debugLog('SURGICAL_COMPLETE', 'Surgical repair finished', {
+        removed,
+        orphansAfter,
+        corruptBackup: corrupt,
+    });
+    return { removed, orphansAfter };
+}
+/**
+ * Main entry point: repair or rollback a transcript with orphan tool_results.
+ *
+ * Strategy:
+ * 1. Check if there are orphans (exit early if none)
+ * 2. Try rollback to newest valid backup
+ * 3. If no valid backup, surgically remove orphan lines
+ */
+function repairOrRollbackTranscript(jsonlPath) {
+    debugLog('REPAIR_START', '═══════════════════════════════════════════════════════════', {
+        action: 'TRANSCRIPT_REPAIR_INITIATED',
+        jsonlPath,
+        timestamp: new Date().toISOString(),
+    });
+    if (!fs.existsSync(jsonlPath)) {
+        debugLog('REPAIR_ABORT', 'JSONL file not found', { jsonlPath });
+        return { action: 'failed', orphansFound: 0, reason: 'jsonl_not_found' };
+    }
+    const initial = countOrphansInJsonl(jsonlPath);
+    debugLog('REPAIR_SCAN', 'Initial orphan count', {
+        orphans: initial.orphans,
+        orphanIds: initial.orphanIds,
+    });
+    if (initial.orphans === 0) {
+        debugLog('REPAIR_CLEAN', 'No orphans found - transcript is healthy');
+        return { action: 'none', orphansFound: 0 };
+    }
+    // 1) Try rollback to newest valid backup
+    const backups = findBackups(jsonlPath);
+    debugLog('REPAIR_BACKUPS', `Found ${backups.length} backup candidates`, { backups });
+    for (const backup of backups) {
+        try {
+            const v = countOrphansInJsonl(backup);
+            debugLog('REPAIR_CHECK_BACKUP', 'Validating backup', {
+                backup,
+                orphans: v.orphans,
+            });
+            if (v.orphans === 0) {
+                // SAFETY CHECK: Prevent session amnesia (rollback > 20 lines)
+                const lostLines = (initial.lineCount || 0) - (v.lineCount || 0);
+                if (lostLines > 20) {
+                    debugLog('REPAIR_BACKUP_SKIPPED', 'Backup too old - skipping to prevent data loss', {
+                        backup,
+                        currentLines: initial.lineCount,
+                        backupLines: v.lineCount,
+                        lostLines
+                    });
+                    continue;
+                }
+                atomicReplace(jsonlPath, backup);
+                debugLog('REPAIR_ROLLBACK_SUCCESS', 'Rolled back to valid backup', { backup });
+                return { action: 'rollback', orphansFound: initial.orphans, backupUsed: backup };
+            }
+        }
+        catch (err) {
+            debugLog('REPAIR_BACKUP_ERROR', 'Failed to check backup', {
+                backup,
+                error: err.message,
+            });
+        }
+    }
+    // 2) Surgical repair fallback
+    debugLog('REPAIR_SURGICAL', 'No valid backup found - attempting surgical repair');
+    const { removed, orphansAfter } = surgicalRepair(jsonlPath);
+    if (orphansAfter === 0) {
+        return { action: 'surgical_repair', orphansFound: initial.orphans, removedLines: removed };
+    }
+    debugLog('REPAIR_FAILED', 'Surgical repair incomplete - orphans remain', {
+        orphansAfter,
+        removed,
+    });
+    return {
+        action: 'failed',
+        orphansFound: initial.orphans,
+        removedLines: removed,
+        reason: 'orphans_remain_after_surgical',
+    };
+}
+/**
+ * Quick validation check - can be called before operations to verify health.
+ */
+function isTranscriptHealthy(jsonlPath) {
+    if (!fs.existsSync(jsonlPath))
+        return true; // Non-existent is not unhealthy
+    const { orphans } = countOrphansInJsonl(jsonlPath);
+    return orphans === 0;
+}
+/**
+ * Get detailed transcript health info.
+ */
+function getTranscriptHealth(jsonlPath) {
+    if (!fs.existsSync(jsonlPath)) {
+        return { exists: false, healthy: true, orphans: 0, orphanIds: [] };
+    }
+    const { orphans, orphanIds } = countOrphansInJsonl(jsonlPath);
+    return { exists: true, healthy: orphans === 0, orphans, orphanIds };
+}

package/dist/commands/agent.d.ts

@@ -42,3 +42,9 @@ export declare function agentUninstall(options?: AgentOptions): Promise<void>;
 export declare function agentLogs(options?: {
     follow?: boolean;
 }): Promise<void>;
+/**
+ * Check agent daemon health and diagnose connection issues
+ */
+export declare function agentHealth(options?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/commands/agent.js

@@ -54,6 +54,7 @@ exports.agentRestart = agentRestart;
 exports.agentStatus = agentStatus;
 exports.agentUninstall = agentUninstall;
 exports.agentLogs = agentLogs;
+exports.agentHealth = agentHealth;
 const chalk_1 = __importDefault(require("chalk"));
 const os = __importStar(require("os"));
 const fs = __importStar(require("fs"));
@@ -298,3 +299,246 @@ async function agentLogs(options = {}) {
         console.log(lines.join('\n'));
     }
 }
+/**
+ * Check agent daemon health and diagnose connection issues
+ */
+async function agentHealth(options = {}) {
+    const platform = os.platform();
+    const deviceFilePath = path.join(state_1.EKKOS_DIR, 'device.json');
+    const logPath = path.join(state_1.EKKOS_DIR, 'agent.out.log');
+    const pidFilePath = path.join(state_1.EKKOS_DIR, 'agent.pid');
+    const health = {
+        timestamp: new Date().toISOString(),
+        status: 'unknown',
+        checks: {
+            configured: false,
+            paired: false,
+            serviceRunning: false,
+            processRunning: false,
+            logsWriting: false,
+            cloudConnected: false,
+            networkHealthy: false,
+        },
+        issues: [],
+        suggestions: [],
+    };
+    // Check 1: Device configured
+    if (fs.existsSync(deviceFilePath)) {
+        const deviceData = JSON.parse(fs.readFileSync(deviceFilePath, 'utf-8'));
+        health.checks.configured = true;
+        health.device = {
+            name: deviceData.deviceName,
+            id: deviceData.deviceId.slice(0, 8) + '...',
+            platform: deviceData.platform,
+            arch: deviceData.arch,
+        };
+        // Check 2: Device paired
+        if (deviceData.deviceToken) {
+            health.checks.paired = true;
+            health.pairedAt = deviceData.pairedAt;
+        }
+        else {
+            health.checks.paired = false;
+            health.issues.push('Device not paired');
+            health.suggestions.push('Run `ekkos setup-remote` to pair device');
+        }
+        // Check 3: Service running
+        try {
+            if (platform === 'darwin') {
+                const output = (0, child_process_1.execSync)('launchctl list | grep dev.ekkos.agent || true', { encoding: 'utf-8' });
+                health.checks.serviceRunning = output.includes('dev.ekkos.agent');
+            }
+            else if (platform === 'win32') {
+                const output = (0, child_process_1.execSync)('schtasks /query /tn "ekkOS Agent" 2>nul || true', { encoding: 'utf-8' });
+                health.checks.serviceRunning = output.includes('Running');
+            }
+            else if (platform === 'linux') {
+                const output = (0, child_process_1.execSync)('systemctl --user is-active ekkos-agent 2>/dev/null || true', { encoding: 'utf-8' });
+                health.checks.serviceRunning = output.trim() === 'active';
+            }
+        }
+        catch {
+            health.checks.serviceRunning = false;
+        }
+        if (!health.checks.serviceRunning) {
+            health.issues.push('Service not running');
+            health.suggestions.push('Run `ekkos agent start` to start the service');
+        }
+        // Check 4: Process running
+        if (fs.existsSync(pidFilePath)) {
+            const pid = parseInt(fs.readFileSync(pidFilePath, 'utf-8').trim());
+            try {
+                // Check if process exists
+                (0, child_process_1.execSync)(`kill -0 ${pid} 2>/dev/null`, { stdio: 'pipe' });
+                health.checks.processRunning = true;
+            }
+            catch {
+                health.checks.processRunning = false;
+                health.issues.push(`Agent process (PID ${pid}) not running`);
+                health.suggestions.push('Run `ekkos agent restart` to restart');
+            }
+        }
+        else {
+            health.checks.processRunning = false;
+            health.issues.push('No PID file found');
+        }
+        // Check 5: Logs writing
+        if (fs.existsSync(logPath)) {
+            const stats = fs.statSync(logPath);
+            const lastModified = Date.now() - stats.mtime.getTime();
+            const fifteenMinutes = 15 * 60 * 1000;
+            health.checks.logsWriting = lastModified < fifteenMinutes;
+            health.lastLogWrite = {
+                timestamp: stats.mtime.toISOString(),
+                minutesAgo: Math.round(lastModified / 1000 / 60),
+            };
+            if (!health.checks.logsWriting) {
+                health.issues.push(`No logs written for ${Math.round(lastModified / 1000 / 60)} minutes`);
+                health.suggestions.push('Check if daemon crashed - run `ekkos agent logs -f` to monitor');
+            }
+            // Parse recent errors from logs
+            const content = fs.readFileSync(logPath, 'utf-8');
+            const lines = content.split('\n').slice(-100);
+            const errors = lines.filter(l => l.includes('ERROR') || l.includes('error') || l.includes('Connection failed'));
+            if (errors.length > 0) {
+                health.recentErrors = errors.slice(-5);
+            }
+        }
+        else {
+            health.checks.logsWriting = false;
+            health.issues.push('Log file not found');
+        }
+        // Check 6: Cloud connectivity
+        if (health.checks.paired) {
+            try {
+                const authToken = (0, state_1.getAuthToken)();
+                const state = (0, state_1.getState)();
+                if (authToken && state?.userId) {
+                    const MEMORY_API_URL = process.env.MEMORY_API_URL || 'https://api.ekkos.dev';
+                    const controller = new AbortController();
+                    const timeout = setTimeout(() => controller.abort(), 5000);
+                    try {
+                        const response = await fetch(`${MEMORY_API_URL}/api/v1/relay/devices/${state.userId}`, {
+                            headers: { 'Authorization': `Bearer ${authToken}` },
+                            signal: controller.signal,
+                        });
+                        clearTimeout(timeout);
+                        if (response.ok) {
+                            const data = await response.json();
+                            const device = data.devices?.find((d) => d.deviceId === deviceData.deviceId);
+                            health.checks.cloudConnected = device?.online === true;
+                            if (!health.checks.cloudConnected) {
+                                health.issues.push('Device shows offline in cloud');
+                                health.suggestions.push('Check network connection and agent logs');
+                            }
+                        }
+                        else {
+                            health.checks.cloudConnected = false;
+                            health.issues.push(`Cloud API returned ${response.status}`);
+                        }
+                    }
+                    catch (err) {
+                        clearTimeout(timeout);
+                        health.checks.cloudConnected = false;
+                        if (err.name === 'AbortError') {
+                            health.issues.push('Cloud connection timeout (>5s)');
+                        }
+                        else {
+                            health.issues.push(`Cloud connection error: ${err.message}`);
+                        }
+                        health.suggestions.push('Check internet connection');
+                    }
+                }
+                else {
+                    health.issues.push('Not logged in to ekkOS');
+                    health.suggestions.push('Run `ekkos init` to set up authentication');
+                }
+            }
+            catch {
+                health.checks.cloudConnected = false;
+                health.issues.push('Unable to check cloud connectivity');
+            }
+        }
+        // Check 7: Network health
+        if (health.checks.logsWriting && health.checks.cloudConnected) {
+            health.checks.networkHealthy = true;
+        }
+    }
+    else {
+        health.checks.configured = false;
+        health.issues.push('Device not configured');
+        health.suggestions.push('Run `ekkos setup-remote` to configure device');
+    }
+    // Determine overall status
+    if (health.issues.length === 0) {
+        health.status = 'healthy';
+    }
+    else if (health.checks.serviceRunning &&
+        health.checks.processRunning &&
+        health.checks.logsWriting) {
+        health.status = 'degraded';
+    }
+    else {
+        health.status = 'unhealthy';
+    }
+    if (options.json) {
+        console.log(JSON.stringify(health, null, 2));
+    }
+    else {
+        // Pretty print
+        console.log('');
+        console.log(chalk_1.default.cyan.bold('  ekkOS Agent Health Check'));
+        console.log('');
+        const statusColor = health.status === 'healthy' ? chalk_1.default.green :
+            health.status === 'degraded' ? chalk_1.default.yellow :
+                chalk_1.default.red;
+        console.log(`  Status: ${statusColor.bold(health.status.toUpperCase())}`);
+        console.log('');
+        // Device info
+        if (health.device) {
+            console.log(chalk_1.default.gray('  Device:'));
+            console.log(`    ${chalk_1.default.gray('Name:')} ${health.device.name}`);
+            console.log(`    ${chalk_1.default.gray('ID:')} ${health.device.id}`);
+            console.log(`    ${chalk_1.default.gray('Platform:')} ${health.device.platform}/${health.device.arch}`);
+            console.log('');
+        }
+        // Checks
+        console.log(chalk_1.default.gray('  Checks:'));
+        for (const [key, value] of Object.entries(health.checks)) {
+            const icon = value ? chalk_1.default.green('✓') : chalk_1.default.red('✗');
+            const label = key.replace(/([A-Z])/g, ' $1').trim();
+            console.log(`    ${icon} ${label}`);
+        }
+        console.log('');
+        // Issues
+        if (health.issues.length > 0) {
+            console.log(chalk_1.default.yellow('  Issues:'));
+            for (const issue of health.issues) {
+                console.log(`    ${chalk_1.default.yellow('⚠')} ${issue}`);
+            }
+            console.log('');
+        }
+        // Suggestions
+        if (health.suggestions.length > 0) {
+            console.log(chalk_1.default.cyan('  Suggestions:'));
+            for (const suggestion of health.suggestions) {
+                console.log(`    ${chalk_1.default.cyan('→')} ${suggestion}`);
+            }
+            console.log('');
+        }
+        // Recent errors
+        if (health.recentErrors && health.recentErrors.length > 0) {
+            console.log(chalk_1.default.red('  Recent Errors:'));
+            for (const err of health.recentErrors.slice(0, 3)) {
+                const preview = err.substring(0, 100) + (err.length > 100 ? '...' : '');
+                console.log(`    ${chalk_1.default.red('!')} ${preview}`);
+            }
+            console.log('');
+        }
+        // Logs info
+        if (health.lastLogWrite) {
+            console.log(chalk_1.default.gray(`  Last activity: ${health.lastLogWrite.minutesAgo} minutes ago`));
+            console.log('');
+        }
+    }
+}

package/dist/commands/dashboard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ekkos dashboard [session-name]
+ *
+ * Live TUI dashboard for monitoring Claude Code session usage in real-time.
+ * Uses blessed-contrib for rich terminal widgets (gauges, charts, tables).
+ *
+ * Usage:
+ *   ekkos dashboard <session-name>   Watch specific session
+ *   ekkos dashboard --latest         Auto-detect latest active session
+ *   ekkos dashboard --wait-for-new   Wait for a brand-new session to appear
+ *   ekkos dashboard                  Interactive session picker
+ *
+ * Text Selection:
+ *   To select text separately from Claude Code, run the dashboard in a different
+ *   terminal window/pane. This prevents the blessed screen from interfering with
+ *   Claude Code's text selection. Use iTerm2 split panes or tmux windows.
+ *
+ * Scrolling:
+ *   Up/Down arrows or j/k    Scroll one line
+ *   PageUp/PageDown or u/d   Scroll one page
+ *   Home/End or g/G          Jump to top/bottom
+ *   Mouse wheel              Scroll with mouse
+ */
+import { Command } from 'commander';
+export declare const dashboardCommand: Command;