@ekkos/cli 0.2.3 → 0.2.5

package/dist/commands/doctor.d.ts

@@ -0,0 +1,32 @@
+type GateStatus = 'PASS' | 'FAIL' | 'WARN';
+interface Check {
+    name: string;
+    passed: boolean;
+    detail?: string;
+}
+interface Gate {
+    id: string;
+    title: string;
+    status: GateStatus;
+    checks: Check[];
+    fix?: string;
+}
+interface DoctorReport {
+    platform: string;
+    gates: Gate[];
+    canProceed: boolean;
+    nodeVersion?: string;
+    claudeVersion?: string;
+}
+/**
+ * Run diagnostic checks and return report
+ */
+export declare function runDiagnostics(): DoctorReport;
+/**
+ * Main doctor command
+ */
+export declare function doctor(options?: {
+    fix?: boolean;
+    json?: boolean;
+}): Promise<void>;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,418 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDiagnostics = runDiagnostics;
+exports.doctor = doctor;
+const os_1 = require("os");
+const child_process_1 = require("child_process");
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Check if a command exists in PATH
+ */
+function commandExists(cmd) {
+    try {
+        const which = (0, os_1.platform)() === 'win32' ? 'where' : 'which';
+        (0, child_process_1.execSync)(`${which} ${cmd}`, { stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get command version safely
+ */
+function getVersion(cmd, versionFlag = '--version') {
+    try {
+        const output = (0, child_process_1.execSync)(`${cmd} ${versionFlag}`, {
+            encoding: 'utf-8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        return output.split('\n')[0];
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if node-pty can be loaded
+ */
+function checkPty() {
+    try {
+        // Try to require node-pty
+        require('node-pty');
+        return { available: true };
+    }
+    catch (error) {
+        // Check for prebuilt alternative
+        try {
+            require('node-pty-prebuilt-multiarch');
+            return { available: true };
+        }
+        catch {
+            return {
+                available: false,
+                error: error?.message || 'Cannot load node-pty'
+            };
+        }
+    }
+}
+/**
+ * Check MCP configuration via claude mcp list
+ */
+function checkMcpConfig() {
+    try {
+        const output = (0, child_process_1.execSync)('claude mcp list', {
+            encoding: 'utf-8',
+            timeout: 10000,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        // Parse server names from output
+        const servers = [];
+        const lines = output.split('\n');
+        for (const line of lines) {
+            // Look for server names (varies by Claude version)
+            if (line.includes('ekkos') || line.includes('memory')) {
+                servers.push(line.trim());
+            }
+        }
+        const hasEkkos = output.toLowerCase().includes('ekkos') ||
+            output.toLowerCase().includes('memory');
+        return { configured: hasEkkos, servers };
+    }
+    catch (error) {
+        return {
+            configured: false,
+            servers: [],
+            error: error?.message || 'Failed to check MCP config'
+        };
+    }
+}
+/**
+ * Check if bash is available (for hooks on Windows)
+ */
+function checkBash() {
+    if ((0, os_1.platform)() !== 'win32')
+        return true;
+    try {
+        (0, child_process_1.execSync)('bash --version', { stdio: 'ignore', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run diagnostic checks and return report
+ */
+function runDiagnostics() {
+    const isWindows = (0, os_1.platform)() === 'win32';
+    const gates = [];
+    // Get basic info
+    const nodeVersion = getVersion('node') || 'Not found';
+    const claudeVersion = getVersion('claude');
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GATE 1: Interactive Claude Works
+    // ═══════════════════════════════════════════════════════════════════════════
+    const claudeChecks = [];
+    let claudeGatePass = true;
+    // Check 1.1: claude command exists
+    const claudeExists = commandExists('claude');
+    claudeChecks.push({
+        name: 'Claude CLI installed',
+        passed: claudeExists,
+        detail: claudeExists ? claudeVersion || 'Found' : 'Not in PATH'
+    });
+    if (!claudeExists)
+        claudeGatePass = false;
+    // Check 1.2: claude --version works
+    if (claudeExists) {
+        const versionWorks = claudeVersion !== null;
+        claudeChecks.push({
+            name: 'Claude responds to --version',
+            passed: versionWorks,
+            detail: versionWorks ? claudeVersion : 'No response'
+        });
+        if (!versionWorks)
+            claudeGatePass = false;
+    }
+    // Check 1.3: On Windows, PTY is required for interactive mode
+    // This is checked in Gate 2, but we note it here
+    if (isWindows) {
+        claudeChecks.push({
+            name: 'Interactive mode (requires PTY)',
+            passed: true, // Will be validated in Gate 2
+            detail: 'See PTY gate below'
+        });
+    }
+    gates.push({
+        id: 'interactive-claude',
+        title: 'Interactive Claude',
+        status: claudeGatePass ? 'PASS' : 'FAIL',
+        checks: claudeChecks,
+        fix: claudeGatePass ? undefined : 'npm install -g @anthropic-ai/claude-code'
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GATE 2: PTY Works (Windows-critical)
+    // ═══════════════════════════════════════════════════════════════════════════
+    const ptyChecks = [];
+    let ptyGatePass = true;
+    // Check Node version (20.x or 22.x recommended)
+    const nodeMatch = nodeVersion.match(/v?(\d+)\./);
+    const nodeMajor = nodeMatch ? parseInt(nodeMatch[1], 10) : 0;
+    const nodeOk = nodeMajor >= 18 && nodeMajor <= 22;
+    ptyChecks.push({
+        name: 'Node.js version',
+        passed: nodeOk,
+        detail: nodeOk
+            ? `${nodeVersion} (OK)`
+            : `${nodeVersion} (Need 20.x or 22.x LTS for PTY support)`
+    });
+    if (!nodeOk && isWindows)
+        ptyGatePass = false;
+    // Check PTY availability
+    const ptyResult = checkPty();
+    ptyChecks.push({
+        name: 'node-pty loadable',
+        passed: ptyResult.available,
+        detail: ptyResult.available ? 'ConPTY available' : ptyResult.error
+    });
+    if (!ptyResult.available && isWindows)
+        ptyGatePass = false;
+    // On macOS/Linux, PTY is typically available, mark as PASS with note
+    if (!isWindows && !ptyResult.available) {
+        ptyChecks.push({
+            name: 'Fallback available',
+            passed: true,
+            detail: 'Unix script(1) fallback available'
+        });
+        ptyGatePass = true; // Unix has fallback
+    }
+    gates.push({
+        id: 'pty',
+        title: 'PTY (Terminal)',
+        status: ptyGatePass ? 'PASS' : (isWindows ? 'FAIL' : 'WARN'),
+        checks: ptyChecks,
+        fix: ptyGatePass ? undefined : isWindows
+            ? 'npm install node-pty-prebuilt-multiarch OR install VS Build Tools and run: npm rebuild node-pty'
+            : undefined
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // GATE 3: MCP Works
+    // ═══════════════════════════════════════════════════════════════════════════
+    const mcpChecks = [];
+    let mcpGatePass = true;
+    // Check MCP config
+    const mcpResult = checkMcpConfig();
+    if (mcpResult.error && mcpResult.error.includes('not found')) {
+        // Claude not installed, can't check MCP
+        mcpChecks.push({
+            name: 'MCP configuration',
+            passed: false,
+            detail: 'Claude CLI required to check MCP'
+        });
+        mcpGatePass = false;
+    }
+    else {
+        mcpChecks.push({
+            name: 'ekkOS MCP server configured',
+            passed: mcpResult.configured,
+            detail: mcpResult.configured
+                ? `Found: ${mcpResult.servers.join(', ') || 'ekkOS server'}`
+                : 'No ekkOS server in claude mcp list'
+        });
+        if (!mcpResult.configured)
+            mcpGatePass = false;
+    }
+    // Check bash on Windows (for hooks, WARN only)
+    if (isWindows) {
+        const bashOk = checkBash();
+        mcpChecks.push({
+            name: 'Bash available (for hooks)',
+            passed: bashOk,
+            detail: bashOk ? 'Git Bash/WSL detected' : 'PowerShell hooks will be used'
+        });
+        // Don't fail gate for missing bash, just note it
+    }
+    gates.push({
+        id: 'mcp',
+        title: 'MCP Configuration',
+        status: mcpGatePass ? 'PASS' : 'FAIL',
+        checks: mcpChecks,
+        fix: mcpGatePass ? undefined :
+            'claude mcp add ekkos-memory npx -y @ekkos/cli@latest mcp && claude mcp start ekkos-memory'
+    });
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Calculate overall status
+    // ═══════════════════════════════════════════════════════════════════════════
+    const allPass = gates.every(g => g.status === 'PASS');
+    const hasBlocker = gates.some(g => g.status === 'FAIL');
+    return {
+        platform: isWindows ? 'Windows' : (0, os_1.platform)() === 'darwin' ? 'macOS' : 'Linux',
+        gates,
+        canProceed: !hasBlocker,
+        nodeVersion,
+        claudeVersion: claudeVersion || undefined
+    };
+}
+/**
+ * Display the doctor report
+ */
+function displayReport(report) {
+    console.log('');
+    console.log(chalk_1.default.cyan.bold('🩺 ekkOS Doctor'));
+    console.log(chalk_1.default.gray('─'.repeat(60)));
+    console.log('');
+    // Platform info
+    console.log(chalk_1.default.gray(`Platform: ${report.platform}`));
+    console.log(chalk_1.default.gray(`Node: ${report.nodeVersion}`));
+    if (report.claudeVersion) {
+        console.log(chalk_1.default.gray(`Claude: ${report.claudeVersion}`));
+    }
+    console.log('');
+    // Display each gate
+    for (const gate of report.gates) {
+        const icon = gate.status === 'PASS' ? chalk_1.default.green('✓')
+            : gate.status === 'WARN' ? chalk_1.default.yellow('○')
+                : chalk_1.default.red('✗');
+        const color = gate.status === 'PASS' ? chalk_1.default.green
+            : gate.status === 'WARN' ? chalk_1.default.yellow
+                : chalk_1.default.red;
+        console.log(`${icon} ${color.bold(gate.title)}`);
+        for (const check of gate.checks) {
+            const checkIcon = check.passed ? chalk_1.default.green('  ✓') : chalk_1.default.red('  ✗');
+            console.log(`${checkIcon} ${check.name}`);
+            if (check.detail) {
+                console.log(chalk_1.default.gray(`      ${check.detail}`));
+            }
+        }
+        if (gate.fix && gate.status === 'FAIL') {
+            console.log(chalk_1.default.yellow(`  → Fix: ${gate.fix}`));
+        }
+        console.log('');
+    }
+    // Summary
+    console.log(chalk_1.default.gray('─'.repeat(60)));
+    const blockers = report.gates.filter(g => g.status === 'FAIL').length;
+    const warnings = report.gates.filter(g => g.status === 'WARN').length;
+    if (blockers > 0) {
+        console.log(chalk_1.default.red.bold(`BLOCKERS: ${blockers}`));
+        console.log(chalk_1.default.yellow('Run the fix commands above to resolve issues.'));
+    }
+    else if (warnings > 0) {
+        console.log(chalk_1.default.yellow.bold(`WARNINGS: ${warnings}`));
+        console.log(chalk_1.default.green('ekkOS can run, but some features may be limited.'));
+    }
+    else {
+        console.log(chalk_1.default.green.bold('✓ All systems operational'));
+        console.log(chalk_1.default.green('ekkOS is ready to use.'));
+    }
+    console.log('');
+}
+/**
+ * Attempt safe auto-fixes
+ */
+async function attemptAutoFixes(report) {
+    const fixed = [];
+    const manual = [];
+    for (const gate of report.gates) {
+        if (gate.status === 'PASS')
+            continue;
+        switch (gate.id) {
+            case 'interactive-claude':
+                // Try to install Claude Code (safe, non-admin)
+                console.log(chalk_1.default.yellow('\nAttempting to install Claude Code...'));
+                try {
+                    (0, child_process_1.execSync)('npm install -g @anthropic-ai/claude-code', {
+                        stdio: 'inherit',
+                        timeout: 120000
+                    });
+                    fixed.push('Claude Code installed');
+                }
+                catch {
+                    manual.push('npm install -g @anthropic-ai/claude-code');
+                }
+                break;
+            case 'pty':
+                // Try prebuilt PTY first (safe, non-admin)
+                console.log(chalk_1.default.yellow('\nAttempting to install prebuilt PTY...'));
+                try {
+                    // Try homebridge prebuilt first
+                    (0, child_process_1.execSync)('npm install -g @homebridge/node-pty-prebuilt-multiarch', {
+                        stdio: 'inherit',
+                        timeout: 60000
+                    });
+                    fixed.push('Prebuilt PTY installed');
+                }
+                catch {
+                    manual.push('npm install -g @homebridge/node-pty-prebuilt-multiarch');
+                    manual.push('If that fails: Install VS Build Tools, then: npm rebuild node-pty');
+                }
+                break;
+            case 'mcp':
+                // Try to configure MCP (safe)
+                console.log(chalk_1.default.yellow('\nAttempting to configure MCP...'));
+                try {
+                    (0, child_process_1.execSync)('claude mcp add ekkos-memory npx -y @ekkos/cli@latest mcp', {
+                        stdio: 'inherit',
+                        timeout: 30000
+                    });
+                    (0, child_process_1.execSync)('claude mcp start ekkos-memory', {
+                        stdio: 'inherit',
+                        timeout: 10000
+                    });
+                    fixed.push('MCP configured');
+                }
+                catch {
+                    manual.push('claude mcp add ekkos-memory npx -y @ekkos/cli@latest mcp');
+                    manual.push('claude mcp start ekkos-memory');
+                }
+                break;
+        }
+    }
+    return { fixed, manual };
+}
+/**
+ * Main doctor command
+ */
+async function doctor(options = {}) {
+    const report = runDiagnostics();
+    // JSON output mode
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        process.exit(report.canProceed ? 0 : 1);
+    }
+    displayReport(report);
+    // Fix mode - attempt safe auto-fixes
+    if (options.fix && !report.canProceed) {
+        console.log(chalk_1.default.cyan.bold('\n🔧 Attempting auto-fixes...\n'));
+        const { fixed, manual } = await attemptAutoFixes(report);
+        if (fixed.length > 0) {
+            console.log(chalk_1.default.green('\n✓ Auto-fixed:'));
+            for (const f of fixed) {
+                console.log(chalk_1.default.green(`  • ${f}`));
+            }
+        }
+        if (manual.length > 0) {
+            console.log(chalk_1.default.yellow('\n⚠ Manual steps required:'));
+            for (const m of manual) {
+                console.log(chalk_1.default.white(`  ${m}`));
+            }
+        }
+        // Re-run diagnostics to check if fixes worked
+        console.log(chalk_1.default.cyan('\n🔄 Re-checking...'));
+        const recheck = runDiagnostics();
+        displayReport(recheck);
+        if (recheck.canProceed) {
+            console.log(chalk_1.default.green.bold('✓ All issues resolved!'));
+        }
+        process.exit(recheck.canProceed ? 0 : 1);
+    }
+    // Exit with error code if blockers
+    if (!report.canProceed) {
+        process.exit(1);
+    }
+}

package/dist/commands/run.d.ts

@@ -2,6 +2,7 @@ interface RunOptions {
     session?: string;
     verbose?: boolean;
     bypass?: boolean;
+    doctor?: boolean;
     slashOpenDelayMs?: number;
     charDelayMs?: number;
     postEnterDelayMs?: number;

package/dist/commands/run.js

@@ -43,6 +43,7 @@ const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const child_process_1 = require("child_process");
 const state_1 = require("../utils/state");
+const doctor_1 = require("./doctor");
 // Try to load node-pty (may fail on Node 24+)
 let pty = null;
 try {
@@ -54,15 +55,15 @@ catch {
 function getConfig(options) {
     return {
         slashOpenDelayMs: options.slashOpenDelayMs ??
-            parseInt(process.env.EKKOS_SLASH_OPEN_DELAY_MS || '1000', 10),
+            parseInt(process.env.EKKOS_SLASH_OPEN_DELAY_MS || '500', 10), // was 1000
         charDelayMs: options.charDelayMs ??
             parseInt(process.env.EKKOS_CHAR_DELAY_MS || '25', 10),
         postEnterDelayMs: options.postEnterDelayMs ??
-            parseInt(process.env.EKKOS_POST_ENTER_DELAY_MS || '500', 10),
+            parseInt(process.env.EKKOS_POST_ENTER_DELAY_MS || '300', 10), // was 500
         clearWaitMs: options.clearWaitMs ??
-            parseInt(process.env.EKKOS_CLEAR_WAIT_MS || '5000', 10),
+            parseInt(process.env.EKKOS_CLEAR_WAIT_MS || '2500', 10), // was 5000
         idlePromptMs: parseInt(process.env.EKKOS_IDLE_PROMPT_MS || '250', 10),
-        paletteRetryMs: parseInt(process.env.EKKOS_PALETTE_RETRY_MS || '500', 10),
+        paletteRetryMs: parseInt(process.env.EKKOS_PALETTE_RETRY_MS || '400', 10), // was 500
         debugLogPath: options.debugLogPath ??
             process.env.EKKOS_DEBUG_LOG_PATH ??
             path.join(os.homedir(), '.ekkos', 'auto-continue.debug.log')
@@ -362,6 +363,26 @@ async function emergencyCapture(transcriptPath, sessionId) {
 async function run(options) {
     const verbose = options.verbose || false;
     const bypass = options.bypass || false;
+    // ══════════════════════════════════════════════════════════════════════════
+    // PRE-FLIGHT DIAGNOSTICS (--doctor flag)
+    // ══════════════════════════════════════════════════════════════════════════
+    if (options.doctor) {
+        console.log(chalk_1.default.cyan('\n🩺 Running pre-flight diagnostics...\n'));
+        const report = (0, doctor_1.runDiagnostics)();
+        // Display summary
+        for (const gate of report.gates) {
+            const icon = gate.status === 'PASS' ? chalk_1.default.green('✓')
+                : gate.status === 'WARN' ? chalk_1.default.yellow('○')
+                    : chalk_1.default.red('✗');
+            console.log(`${icon} ${gate.title}: ${gate.status}`);
+        }
+        console.log('');
+        if (!report.canProceed) {
+            console.log(chalk_1.default.red('Blockers detected. Run `ekkos doctor` for details.'));
+            process.exit(1);
+        }
+        console.log(chalk_1.default.green('✓ All checks passed. Starting Claude...\n'));
+    }
     // Get injection config (from options or env vars)
     const config = getConfig(options);
     setDebugLogPath(config.debugLogPath);
@@ -481,6 +502,9 @@ async function run(options) {
     let lastSeenSessionName = null;
     let lastSeenSessionAt = 0;
     const RECENCY_WINDOW_MS = 15000; // 15s - session name must be recent to trust
+    // Track if we've EVER observed a session in THIS process run
+    // This is the authoritative flag - if false, don't trust persisted state
+    let observedSessionThisRun = false;
     // Output buffer for pattern detection
     let outputBuffer = '';
     // Debounce tracking to prevent double triggers
@@ -513,6 +537,35 @@ async function run(options) {
     }
     // Determine which mode to use
     const usePty = pty !== null;
+    // ══════════════════════════════════════════════════════════════════════════
+    // WINDOWS: HARD FAIL WITHOUT PTY
+    // Without node-pty/ConPTY, auto-continue cannot work on Windows.
+    // Claude switches to --print mode without a real PTY, breaking the TUI.
+    // ══════════════════════════════════════════════════════════════════════════
+    if (isWindows && !usePty) {
+        console.log('');
+        console.log(chalk_1.default.red.bold('❌ ekkos run requires PTY support on Windows'));
+        console.log('');
+        console.log(chalk_1.default.yellow('Without node-pty (ConPTY), Claude Code runs in --print mode'));
+        console.log(chalk_1.default.yellow('which prevents auto-continue from working.'));
+        console.log('');
+        console.log(chalk_1.default.cyan('To fix:'));
+        console.log('');
+        console.log(chalk_1.default.white('  Option 1: Use Node 20 or 22 LTS (recommended)'));
+        console.log(chalk_1.default.gray('    winget install OpenJS.NodeJS.LTS'));
+        console.log(chalk_1.default.gray('    npm install -g @ekkos/cli'));
+        console.log('');
+        console.log(chalk_1.default.white('  Option 2: Install prebuilt PTY'));
+        console.log(chalk_1.default.gray('    npm install node-pty-prebuilt-multiarch'));
+        console.log('');
+        console.log(chalk_1.default.white('  Option 3: Build node-pty from source'));
+        console.log(chalk_1.default.gray('    1. Install VS Build Tools (Desktop C++ workload)'));
+        console.log(chalk_1.default.gray('    2. npm rebuild node-pty --build-from-source'));
+        console.log('');
+        console.log(chalk_1.default.gray('Run `ekkos doctor` for detailed diagnostics.'));
+        console.log('');
+        process.exit(1);
+    }
     if (verbose) {
         console.log(chalk_1.default.gray(`  💻 PTY mode: ${usePty ? 'node-pty' : 'spawn+script (fallback)'}`));
         console.log('');
@@ -589,23 +642,46 @@ async function run(options) {
             return;
         }
         // ════════════════════════════════════════════════════════════════════════
-        // SESSION SELECTION: Prefer most recently SEEN session from TUI output
-        // This fixes the "groovy-koala-saves" bug where stale persisted state was used
-        // Priority: lastSeenSessionName (if recent) > currentSession > persisted state
+        // SESSION SELECTION: observedSessionThisRun pattern
+        //
+        // The key insight: ONLY trust session names we've actually observed in THIS
+        // process run. On Windows (without PTY), Claude may exit immediately without
+        // emitting any session info, leaving persisted state stale.
+        //
+        // Priority:
+        // 1. lastSeenSessionName (if recent AND observed this run)
+        // 2. currentSession (if observed this run)
+        // 3. Most recent session from local cache (if NOT observed this run)
+        // 4. Persisted state (last resort)
         // ════════════════════════════════════════════════════════════════════════
         let sessionToRestore = null;
-        // PRIORITY 1: Most recently observed session name from TUI output
-        // Only trust if seen within RECENCY_WINDOW_MS (15 seconds)
-        if (lastSeenSessionName && (Date.now() - lastSeenSessionAt) < RECENCY_WINDOW_MS) {
-            sessionToRestore = lastSeenSessionName;
-            dlog(`Using lastSeenSessionName (${Date.now() - lastSeenSessionAt}ms ago): ${sessionToRestore}`);
-        }
-        // PRIORITY 2: currentSession (in-memory, may be stale)
-        if (!sessionToRestore && currentSession) {
-            sessionToRestore = currentSession;
-            dlog(`Using currentSession (in-memory): ${sessionToRestore}`);
-        }
-        // PRIORITY 3: Persisted state (fallback)
+        if (observedSessionThisRun) {
+            // We've seen a session in THIS process - trust in-memory state
+            dlog(`observedSessionThisRun=true - trusting in-memory state`);
+            // PRIORITY 1: Most recently observed session name from TUI output
+            // Only trust if seen within RECENCY_WINDOW_MS (15 seconds)
+            if (lastSeenSessionName && (Date.now() - lastSeenSessionAt) < RECENCY_WINDOW_MS) {
+                sessionToRestore = lastSeenSessionName;
+                dlog(`Using lastSeenSessionName (${Date.now() - lastSeenSessionAt}ms ago): ${sessionToRestore}`);
+            }
+            // PRIORITY 2: currentSession (in-memory, confirmed this run)
+            if (!sessionToRestore && currentSession) {
+                sessionToRestore = currentSession;
+                dlog(`Using currentSession (in-memory, observed this run): ${sessionToRestore}`);
+            }
+        }
+        else {
+            // We've NOT observed any session this run - don't trust persisted state
+            // This prevents the "groovy-koala-saves" bug on Windows
+            dlog(`observedSessionThisRun=false - using cache fallback`);
+            // PRIORITY 3: Most recent session from local cache index
+            const recentSession = (0, state_1.getMostRecentSession)();
+            if (recentSession) {
+                sessionToRestore = recentSession.sessionName;
+                dlog(`Using most recent session from cache: ${sessionToRestore} (${recentSession.lastActive})`);
+            }
+        }
+        // PRIORITY 4: Persisted state (last resort)
         if (!sessionToRestore) {
             const state = (0, state_1.getState)();
             sessionToRestore = state?.sessionName || null;
@@ -615,7 +691,7 @@ async function run(options) {
                 sessionToRestore = (0, state_1.uuidToWords)(sessionId);
             }
             if (sessionToRestore) {
-                dlog(`Using persisted state (fallback): ${sessionToRestore}`);
+                dlog(`Using persisted state (last resort): ${sessionToRestore}`);
             }
         }
         const sessionDisplay = sessionToRestore || 'unknown-session';
@@ -729,8 +805,9 @@ async function run(options) {
                 lastSeenSessionName = detectedSession;
                 lastSeenSessionAt = Date.now();
                 currentSession = lastSeenSessionName;
+                observedSessionThisRun = true; // Mark that we've seen a session in THIS process
                 (0, state_1.updateState)({ sessionName: currentSession });
-                dlog(`Session detected from status line: ${currentSession}`);
+                dlog(`Session detected from status line: ${currentSession} (observedSessionThisRun=true)`);
             }
             else {
                 // Same session, just update timestamp
@@ -746,8 +823,9 @@ async function run(options) {
                     lastSeenSessionName = detectedSession;
                     lastSeenSessionAt = Date.now();
                     currentSession = lastSeenSessionName;
+                    observedSessionThisRun = true; // Mark that we've seen a session in THIS process
                     (0, state_1.updateState)({ sessionName: currentSession });
-                    dlog(`Session detected from generic match: ${currentSession}`);
+                    dlog(`Session detected from generic match: ${currentSession} (observedSessionThisRun=true)`);
                 }
                 else {
                     lastSeenSessionAt = Date.now();

package/dist/index.js

@@ -9,6 +9,7 @@ const init_1 = require("./commands/init");
 const test_1 = require("./commands/test");
 const status_1 = require("./commands/status");
 const run_1 = require("./commands/run");
+const doctor_1 = require("./commands/doctor");
 const chalk_1 = __importDefault(require("chalk"));
 commander_1.program
     .name('ekkos')
@@ -42,13 +43,24 @@ commander_1.program
     .option('-s, --session <name>', 'Session name to restore on clear')
     .option('-b, --bypass', 'Enable bypass permissions mode (dangerously skip all permission checks)')
     .option('-v, --verbose', 'Show debug output')
+    .option('-d, --doctor', 'Run diagnostics before starting')
     .action((options) => {
     (0, run_1.run)({
         session: options.session,
         bypass: options.bypass,
-        verbose: options.verbose
+        verbose: options.verbose,
+        doctor: options.doctor
     });
 });
+// Doctor command - check system prerequisites
+commander_1.program
+    .command('doctor')
+    .description('Check system prerequisites for ekkOS (Node, PTY, Claude, MCP)')
+    .option('-f, --fix', 'Attempt safe auto-fixes and show commands for manual fixes')
+    .option('-j, --json', 'Output machine-readable JSON report')
+    .action((options) => {
+    (0, doctor_1.doctor)({ fix: options.fix, json: options.json });
+});
 // Deprecated setup command (redirects to init)
 commander_1.program
     .command('setup')

package/dist/utils/state.d.ts

@@ -55,3 +55,12 @@ export declare function parseAutoClearFlag(): {
     session: string;
     timestamp: number;
 } | null;
+/**
+ * Get the most recent session from the local cache index
+ * Used when no session was observed in the current process run
+ */
+export declare function getMostRecentSession(): {
+    sessionName: string;
+    sessionId: string;
+    lastActive: string;
+} | null;

package/dist/utils/state.js

@@ -46,6 +46,7 @@ exports.getConfig = getConfig;
 exports.getAuthToken = getAuthToken;
 exports.clearAutoClearFlag = clearAutoClearFlag;
 exports.parseAutoClearFlag = parseAutoClearFlag;
+exports.getMostRecentSession = getMostRecentSession;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -184,3 +185,38 @@ function parseAutoClearFlag() {
     }
     return null;
 }
+/**
+ * Get the most recent session from the local cache index
+ * Used when no session was observed in the current process run
+ */
+function getMostRecentSession() {
+    const indexPath = path.join(exports.EKKOS_DIR, 'cache', 'sessions', 'index.json');
+    try {
+        if (!fs.existsSync(indexPath)) {
+            return null;
+        }
+        const indexContent = fs.readFileSync(indexPath, 'utf-8');
+        const index = JSON.parse(indexContent);
+        // Find the most recently active session
+        let mostRecent = null;
+        let latestTime = 0;
+        for (const [sessionName, data] of Object.entries(index)) {
+            // Skip test sessions
+            if (sessionName.startsWith('test-'))
+                continue;
+            const activeTime = new Date(data.last_active_ts).getTime();
+            if (activeTime > latestTime) {
+                latestTime = activeTime;
+                mostRecent = {
+                    sessionName,
+                    sessionId: data.session_id,
+                    lastActive: data.last_active_ts
+                };
+            }
+        }
+        return mostRecent;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekkos/cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Setup ekkOS memory for AI coding assistants (Claude Code, Cursor, Windsurf)",
   "main": "dist/index.js",
   "bin": {