@ekkos/cli 0.2.9 → 0.2.11

package/dist/commands/run.js

@@ -62,9 +62,10 @@ function getConfig(options) {
         postEnterDelayMs: options.postEnterDelayMs ??
             parseInt(process.env.EKKOS_POST_ENTER_DELAY_MS || '300', 10), // was 500
         clearWaitMs: options.clearWaitMs ??
-            parseInt(process.env.EKKOS_CLEAR_WAIT_MS || '2500', 10), // was 5000
+            parseInt(process.env.EKKOS_CLEAR_WAIT_MS || '1111', 10), // 1111 = symbolic ✨
         idlePromptMs: parseInt(process.env.EKKOS_IDLE_PROMPT_MS || '250', 10),
         paletteRetryMs: parseInt(process.env.EKKOS_PALETTE_RETRY_MS || '400', 10), // was 500
+        maxIdleWaitMs: parseInt(process.env.EKKOS_MAX_IDLE_WAIT_MS || '2000', 10), // was 10000
         debugLogPath: options.debugLogPath ??
             process.env.EKKOS_DEBUG_LOG_PATH ??
             path.join(os.homedir(), '.ekkos', 'auto-continue.debug.log')
@@ -167,7 +168,8 @@ async function typeSlowly(shell, text, charDelayMs) {
  * that hasn't changed for idlePromptMs. This prevents injecting while Claude
  * is busy generating ("Channelling...").
  */
-async function waitForIdlePrompt(getOutputBuffer, config, maxWaitMs = 10000) {
+async function waitForIdlePrompt(getOutputBuffer, config) {
+    const maxWaitMs = config.maxIdleWaitMs;
     const startTime = Date.now();
     let lastOutput = '';
     let stableTime = 0;
@@ -380,9 +382,45 @@ async function emergencyCapture(transcriptPath, sessionId) {
         dlog('Warning: Could not capture context');
     }
 }
+/**
+ * Generate a unique instance ID for this run
+ * Used for namespacing storage paths
+ */
+function generateInstanceId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+/**
+ * Write/update instance file
+ */
+function writeInstanceFile(instanceId, data) {
+    const instancesDir = path.join(state_1.EKKOS_DIR, 'instances');
+    if (!fs.existsSync(instancesDir)) {
+        fs.mkdirSync(instancesDir, { recursive: true });
+    }
+    const instanceFile = path.join(instancesDir, `${instanceId}.json`);
+    fs.writeFileSync(instanceFile, JSON.stringify(data, null, 2));
+}
+/**
+ * Clean up instance file on exit
+ */
+function cleanupInstanceFile(instanceId) {
+    try {
+        const instanceFile = path.join(state_1.EKKOS_DIR, 'instances', `${instanceId}.json`);
+        if (fs.existsSync(instanceFile)) {
+            fs.unlinkSync(instanceFile);
+        }
+    }
+    catch {
+        // Ignore cleanup errors
+    }
+}
 async function run(options) {
     const verbose = options.verbose || false;
     const bypass = options.bypass || false;
+    const noInject = options.noInject || false;
+    // Generate instance ID for this run
+    const instanceId = generateInstanceId();
+    process.env.EKKOS_INSTANCE_ID = instanceId;
     // ══════════════════════════════════════════════════════════════════════════
     // PRE-FLIGHT DIAGNOSTICS (--doctor flag)
     // ══════════════════════════════════════════════════════════════════════════
@@ -407,6 +445,72 @@ async function run(options) {
     const config = getConfig(options);
     setDebugLogPath(config.debugLogPath);
     // ══════════════════════════════════════════════════════════════════════════
+    // EARLY SETUP: Resolve paths and prepare spawn BEFORE animation
+    // This lets us start Claude while animations run (perceived performance)
+    // ══════════════════════════════════════════════════════════════════════════
+    (0, state_1.ensureEkkosDir)();
+    (0, state_1.clearAutoClearFlag)();
+    const rawClaudePath = resolveClaudePath();
+    const isNpxMode = rawClaudePath.startsWith('npx:');
+    const pinnedVersion = isNpxMode ? rawClaudePath.split(':')[1] : null;
+    const claudePath = isNpxMode ? 'npx' : rawClaudePath;
+    // Build args early
+    const earlyArgs = [];
+    if (isNpxMode) {
+        earlyArgs.push(`@anthropic-ai/claude-code@${pinnedVersion}`);
+    }
+    if (bypass) {
+        earlyArgs.push('--dangerously-skip-permissions');
+    }
+    // Check PTY availability early
+    const usePty = pty !== null;
+    const monitorOnlyMode = noInject || (isWindows && !usePty);
+    // ══════════════════════════════════════════════════════════════════════════
+    // CONCURRENT STARTUP: Spawn Claude while animation runs
+    // Buffer output until animation completes, then flush
+    // ══════════════════════════════════════════════════════════════════════════
+    let earlySpawnedShell = null;
+    let bufferedOutput = [];
+    let animationComplete = false;
+    let shellReady = false;
+    let shellError = null;
+    // Handler reference for early spawn (allows replacing buffer handler with real handler)
+    let earlyDataHandler = null;
+    // Start spawning Claude NOW (before animation) if PTY available
+    if (usePty && pty && !isWindows) {
+        try {
+            earlySpawnedShell = pty.spawn(claudePath, earlyArgs, {
+                name: 'xterm-256color',
+                cols: process.stdout.columns || 80,
+                rows: process.stdout.rows || 24,
+                cwd: process.cwd(),
+                env: process.env
+            });
+            // Buffer output until animation completes using delegating handler
+            earlyDataHandler = (data) => {
+                bufferedOutput.push(data);
+            };
+            earlySpawnedShell.onData((data) => {
+                // Delegate to current handler (buffer during animation, real handler after)
+                if (earlyDataHandler) {
+                    earlyDataHandler(data);
+                }
+            });
+            earlySpawnedShell.onExit(() => {
+                if (!animationComplete) {
+                    // Claude exited during animation - will handle after
+                    shellError = new Error('Claude exited during startup');
+                }
+            });
+            shellReady = true;
+            dlog('Claude spawned early (buffering output during animation)');
+        }
+        catch (err) {
+            dlog(`Early spawn failed: ${err.message}, will retry after animation`);
+            shellError = err;
+        }
+    }
+    // ══════════════════════════════════════════════════════════════════════════
     // STARTUP BANNER WITH COLOR PULSE ANIMATION
     // ══════════════════════════════════════════════════════════════════════════
     const logoLines = [
@@ -494,23 +598,121 @@ async function run(options) {
     process.stdout.write('\x1B[6A');
     logoLines.forEach(line => console.log(chalk_1.default.magenta(line)));
     console.log('');
-    console.log(chalk_1.default.cyan.bold('  Auto-Continue Wrapper'));
-    console.log(chalk_1.default.gray('  Monitors for context limit and auto-restores sessions'));
-    console.log(chalk_1.default.gray('  Uses full 200K context window - triggers on actual limit'));
+    // ══════════════════════════════════════════════════════════════════════════
+    // ANIMATED TITLE: "Cognitive Continuity Engine" with orange/white shine
+    // ══════════════════════════════════════════════════════════════════════════
+    const titleText = 'Cognitive Continuity Engine';
+    const taglineText = 'Context is finite. Intelligence isn\'t.';
+    // Color palette for shine effect
+    const whiteShine = chalk_1.default.whiteBright;
+    // Phase 1: Typewriter effect for title
+    process.stdout.write('  ');
+    for (let i = 0; i < titleText.length; i++) {
+        const char = titleText[i];
+        // Flash white then settle to orange
+        process.stdout.write(whiteShine(char));
+        await sleep(25);
+        process.stdout.write('\b' + chalk_1.default.hex('#FF6B35').bold(char));
+    }
+    console.log('');
+    // Phase 2: Shine sweep across title (3 passes)
+    const SHINE_PASSES = 3;
+    const SHINE_WIDTH = 4;
+    for (let pass = 0; pass < SHINE_PASSES; pass++) {
+        for (let shinePos = -SHINE_WIDTH; shinePos <= titleText.length + SHINE_WIDTH; shinePos++) {
+            process.stdout.write('\x1B[1A'); // Move up one line
+            process.stdout.write('\r  '); // Return to start
+            let output = '';
+            for (let i = 0; i < titleText.length; i++) {
+                const distFromShine = Math.abs(i - shinePos);
+                if (distFromShine === 0) {
+                    output += whiteShine.bold(titleText[i]);
+                }
+                else if (distFromShine === 1) {
+                    output += chalk_1.default.hex('#FFFFFF')(titleText[i]);
+                }
+                else if (distFromShine === 2) {
+                    output += chalk_1.default.hex('#FFD700')(titleText[i]);
+                }
+                else if (distFromShine === 3) {
+                    output += chalk_1.default.hex('#FFA500')(titleText[i]);
+                }
+                else {
+                    output += chalk_1.default.hex('#FF6B35').bold(titleText[i]);
+                }
+            }
+            process.stdout.write(output + '\n'); // Write and move down for next frame
+            await sleep(15);
+        }
+    }
+    // Final title state
+    process.stdout.write('\x1B[1A\r');
+    console.log('  ' + chalk_1.default.hex('#FF6B35').bold(titleText));
+    // Phase 3: Tagline fade-in with shimmer
+    await sleep(100);
+    // Build up tagline with wave effect
+    const taglineColors = [
+        chalk_1.default.hex('#444444'),
+        chalk_1.default.hex('#666666'),
+        chalk_1.default.hex('#888888'),
+        chalk_1.default.hex('#AAAAAA'),
+        chalk_1.default.hex('#CCCCCC'),
+        chalk_1.default.hex('#EEEEEE'),
+        chalk_1.default.gray,
+    ];
+    for (let wave = 0; wave < taglineColors.length; wave++) {
+        process.stdout.write('\r  ');
+        process.stdout.write(taglineColors[wave](taglineText));
+        await sleep(40);
+    }
+    console.log('');
+    // Phase 4: Quick orange accent pulse on tagline
+    for (let pulse = 0; pulse < 2; pulse++) {
+        await sleep(80);
+        process.stdout.write('\x1B[1A\r');
+        console.log('  ' + chalk_1.default.hex('#FF8C00')(taglineText));
+        await sleep(80);
+        process.stdout.write('\x1B[1A\r');
+        console.log('  ' + chalk_1.default.gray(taglineText));
+    }
+    // Final tagline state with subtle orange tint
+    process.stdout.write('\x1B[1A\r');
+    console.log('  ' + chalk_1.default.hex('#B8860B')(taglineText));
+    console.log('');
     if (bypass) {
         console.log(chalk_1.default.yellow('  ⚡ Bypass permissions mode enabled'));
     }
     if (verbose) {
         console.log(chalk_1.default.gray(`  📁 Debug log: ${config.debugLogPath}`));
-        console.log(chalk_1.default.gray(`  ⏱  Timing: slash=${config.slashOpenDelayMs}ms, char=${config.charDelayMs}ms, clear=${config.clearWaitMs}ms`));
+        console.log(chalk_1.default.gray(`  ⏱  Timing: clear=${config.clearWaitMs}ms, idleMax=${config.maxIdleWaitMs}ms (~${Math.round((config.clearWaitMs + config.maxIdleWaitMs * 2 + 1700) / 1000)}s total)`));
     }
     console.log('');
-    // Ensure .ekkos directory exists
-    (0, state_1.ensureEkkosDir)();
-    // Clear any stale flags
-    (0, state_1.clearAutoClearFlag)();
+    // ══════════════════════════════════════════════════════════════════════════
+    // ANIMATION COMPLETE: Mark ready and flush buffered Claude output
+    // ══════════════════════════════════════════════════════════════════════════
+    animationComplete = true;
+    dlog(`Animation complete. shellReady=${shellReady}, buffered=${bufferedOutput.length} chunks`);
+    // Show loading indicator if Claude is still initializing
+    if (shellReady && bufferedOutput.length === 0) {
+        process.stdout.write(chalk_1.default.gray('  Connecting to Claude...'));
+        // Brief wait for any buffered output
+        await sleep(100);
+        process.stdout.write('\r' + ' '.repeat(30) + '\r'); // Clear the line
+    }
     // Track state
     let currentSession = options.session || (0, state_1.getCurrentSessionName)();
+    // Write initial instance file
+    const startedAt = new Date().toISOString();
+    writeInstanceFile(instanceId, {
+        pid: process.pid,
+        projectPath: process.cwd(),
+        startedAt,
+        lastHeartbeat: startedAt,
+        sessionName: currentSession || undefined
+    });
+    if (verbose) {
+        console.log(chalk_1.default.gray(`  🆔 Instance: ${instanceId}`));
+    }
     // ════════════════════════════════════════════════════════════════════════════
     // MULTI-SESSION SUPPORT: Register this process as an active session
     // This prevents state collision when multiple Claude Code instances run
@@ -530,7 +732,8 @@ async function run(options) {
     let currentSessionId = null;
     // Stream tailer for mid-turn context capture
     let streamTailer = null;
-    const streamCacheDir = path.join(os.homedir(), '.ekkos', 'cache', 'sessions');
+    // Instance-namespaced cache directory per spec v1.2
+    const streamCacheDir = path.join(os.homedir(), '.ekkos', 'cache', 'sessions', instanceId);
     // Helper to start stream tailer when we have transcript path
     function startStreamTailer(tPath, sId, sName) {
         if (streamTailer)
@@ -576,103 +779,110 @@ async function run(options) {
     // Debounce tracking to prevent double triggers
     let lastDetectionTime = 0;
     const DETECTION_COOLDOWN = 30000; // 30 seconds cooldown
-    // Resolve claude path
-    const rawClaudePath = resolveClaudePath();
-    // Handle npx:VERSION format for pinned version
-    const isNpxMode = rawClaudePath.startsWith('npx:');
-    const pinnedVersion = isNpxMode ? rawClaudePath.split(':')[1] : null;
-    const claudePath = isNpxMode ? 'npx' : rawClaudePath;
-    if (verbose) {
-        if (isNpxMode) {
-            console.log(chalk_1.default.gray(`  🤖 Using claude-code@${pinnedVersion} via npx (pinned for better context)`));
-        }
-        else {
-            console.log(chalk_1.default.gray(`  🤖 Using claude at: ${claudePath}`));
-        }
-        if (currentSession) {
-            console.log(chalk_1.default.green(`  📍 Session: ${currentSession}`));
-        }
-    }
-    // Build args - prepend package name if using npx
-    const args = [];
-    if (isNpxMode) {
-        args.push(`@anthropic-ai/claude-code@${pinnedVersion}`);
-    }
-    if (bypass) {
-        args.push('--dangerously-skip-permissions');
-    }
-    // Determine which mode to use
-    const usePty = pty !== null;
+    // Use args from early setup
+    const args = earlyArgs;
     // ══════════════════════════════════════════════════════════════════════════
-    // WINDOWS: HARD FAIL WITHOUT PTY
+    // WINDOWS: MONITOR-ONLY MODE WITHOUT PTY (Per Spec v1.2 Addendum)
     // Without node-pty/ConPTY, auto-continue cannot work on Windows.
-    // Claude switches to --print mode without a real PTY, breaking the TUI.
+    // Instead of hard-failing, we enter monitor-only mode.
     // ══════════════════════════════════════════════════════════════════════════
     if (isWindows && !usePty) {
         console.log('');
-        console.log(chalk_1.default.red.bold('❌ ekkos run requires PTY support on Windows'));
+        console.log(chalk_1.default.yellow.bold('⚠️  Monitor-only mode (PTY not available)'));
         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(chalk_1.default.gray('Without node-pty (ConPTY), auto-continue cannot inject commands.'));
+        console.log(chalk_1.default.gray('ekkOS will monitor context usage and provide instructions when needed.'));
         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.cyan('To enable auto-continue:'));
+        console.log(chalk_1.default.white('  Option 1: Use Node 20 or 22 LTS'));
         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(chalk_1.default.white('  Option 2: npm install node-pty-prebuilt-multiarch'));
         console.log('');
         console.log(chalk_1.default.gray('Run `ekkos doctor` for detailed diagnostics.'));
         console.log('');
-        process.exit(1);
+    }
+    else if (noInject) {
+        console.log(chalk_1.default.yellow('  Monitor-only mode (--no-inject)'));
     }
     if (verbose) {
+        if (isNpxMode) {
+            console.log(chalk_1.default.gray(`  🤖 Using claude-code@${pinnedVersion} via npx (pinned for better context)`));
+        }
+        else {
+            console.log(chalk_1.default.gray(`  🤖 Using claude at: ${claudePath}`));
+        }
+        if (currentSession) {
+            console.log(chalk_1.default.green(`  📍 Session: ${currentSession}`));
+        }
         console.log(chalk_1.default.gray(`  💻 PTY mode: ${usePty ? 'node-pty' : 'spawn+script (fallback)'}`));
         console.log('');
     }
     let shell;
+    // ══════════════════════════════════════════════════════════════════════════
+    // USE EARLY-SPAWNED SHELL OR CREATE NEW ONE
+    // If we spawned Claude during animation, reuse it. Otherwise spawn now.
+    // ══════════════════════════════════════════════════════════════════════════
     if (usePty && pty) {
-        // Use node-pty for proper PTY control
-        try {
-            const ptyShell = pty.spawn(claudePath, args, {
-                name: 'xterm-256color',
-                cols: process.stdout.columns || 80,
-                rows: process.stdout.rows || 24,
-                cwd: process.cwd(),
-                env: process.env
-            });
+        if (earlySpawnedShell && shellReady && !shellError) {
+            // REUSE early-spawned shell - Claude loaded during animation!
+            dlog('Reusing early-spawned shell (Claude loaded during animation)');
             shell = {
-                write: (data) => ptyShell.write(data),
-                kill: () => ptyShell.kill(),
-                resize: (cols, rows) => ptyShell.resize(cols, rows),
-                onData: (callback) => ptyShell.onData(callback),
-                onExit: (callback) => ptyShell.onExit(callback)
+                write: (data) => earlySpawnedShell.write(data),
+                kill: () => earlySpawnedShell.kill(),
+                resize: (cols, rows) => earlySpawnedShell.resize(cols, rows),
+                onData: (callback) => {
+                    // Switch the delegating handler from buffer mode to real handler
+                    // This replaces buffering with actual output processing
+                    earlyDataHandler = callback;
+                },
+                onExit: (callback) => earlySpawnedShell.onExit(callback)
             };
-            // Handle terminal resize
-            process.stdout.on('resize', () => {
-                shell.resize?.(process.stdout.columns || 80, process.stdout.rows || 24);
-            });
+            // Flush buffered output NOW (before switching handler)
+            if (bufferedOutput.length > 0) {
+                dlog(`Flushing ${bufferedOutput.length} buffered output chunks`);
+                for (const chunk of bufferedOutput) {
+                    process.stdout.write(chunk);
+                    // Also populate output buffer for pattern detection
+                    outputBuffer += chunk;
+                }
+                bufferedOutput = [];
+            }
         }
-        catch (err) {
-            console.log(chalk_1.default.yellow(`node-pty failed, falling back to spawn+script mode`));
-            if (verbose) {
-                console.log(chalk_1.default.gray(`Error: ${err.message}`));
+        else {
+            // Spawn fresh (early spawn failed or wasn't attempted)
+            dlog('Spawning Claude fresh (early spawn not available)');
+            try {
+                const ptyShell = pty.spawn(claudePath, args, {
+                    name: 'xterm-256color',
+                    cols: process.stdout.columns || 80,
+                    rows: process.stdout.rows || 24,
+                    cwd: process.cwd(),
+                    env: process.env
+                });
+                shell = {
+                    write: (data) => ptyShell.write(data),
+                    kill: () => ptyShell.kill(),
+                    resize: (cols, rows) => ptyShell.resize(cols, rows),
+                    onData: (callback) => ptyShell.onData(callback),
+                    onExit: (callback) => ptyShell.onExit(callback)
+                };
+            }
+            catch (err) {
+                dlog(`node-pty spawn failed: ${err.message}`);
+                // Fall through to spawn mode
+                return runWithSpawn(claudePath, args, options, {
+                    currentSession,
+                    isAutoClearInProgress,
+                    transcriptPath,
+                    currentSessionId,
+                    outputBuffer
+                });
             }
-            // Fall through to spawn mode
-            return runWithSpawn(claudePath, args, options, {
-                currentSession,
-                isAutoClearInProgress,
-                transcriptPath,
-                currentSessionId,
-                outputBuffer
-            });
         }
+        // Handle terminal resize
+        process.stdout.on('resize', () => {
+            shell.resize?.(process.stdout.columns || 80, process.stdout.rows || 24);
+        });
     }
     else {
         // Fallback: use spawn+script for PTY emulation
@@ -977,11 +1187,72 @@ async function run(options) {
             }
         }
     });
+    // ══════════════════════════════════════════════════════════════════════════
+    // RESEARCH MODE: Auto-type research prompt after Claude is ready
+    // Triggers: `ekkos run -r` or `ekkos run --research`
+    // Works like /clear continue - waits for idle prompt, then injects text
+    // ══════════════════════════════════════════════════════════════════════════
+    if (options.research) {
+        dlog('Research mode enabled - will auto-inject research prompt');
+        // Research prompt - comprehensive autonomous research scanning
+        const researchPrompt = `You are the ekkOS Research Scout agent. Your task:
+
+1. **Scan arXiv** (cs.AI, cs.LG, cs.CL) for papers from the last 7 days
+2. **Filter for relevance** to ekkOS memory systems:
+   - Memory-augmented neural networks
+   - Retrieval-augmented generation (RAG)
+   - Long-term memory for LLMs
+   - Pattern learning and extraction
+   - Cognitive architectures
+   - Knowledge graphs
+   - Episodic/semantic memory systems
+3. **Analyze each relevant paper**:
+   - Core technique and novelty
+   - Applicability to ekkOS 11-layer architecture
+   - Implementation complexity (low/medium/high)
+   - Potential impact (1-5 scale)
+4. **Update docs/EKKOS_RESEARCH_ROADMAP.md** with findings
+5. **Forge high-value insights as patterns** using ekkOS_Forge
+
+Use Perplexity for deep research. Be thorough but efficient. Start now.`;
+        // Start research injection after a delay to let Claude initialize
+        setTimeout(async () => {
+            dlog('Starting research prompt injection...');
+            // Wait for idle prompt (same gate as /clear continue uses)
+            const readiness = await waitForIdlePrompt(getOutputBuffer, config);
+            if (!readiness.ready || readiness.interrupted) {
+                dlog('Claude not ready for research prompt - aborting');
+                return;
+            }
+            // PAUSE STDIN during injection to prevent user interference
+            process.stdin.off('data', onStdinData);
+            dlog('Stdin paused during research injection');
+            try {
+                // Clear any existing input
+                shell.write('\x15'); // Ctrl+U
+                await sleep(60);
+                // Type the research prompt character by character (faster for long prompts)
+                dlog('Typing research prompt...');
+                const fastCharDelay = Math.min(config.charDelayMs, 10); // Faster typing for long prompt
+                await typeSlowly(shell, researchPrompt, fastCharDelay);
+                // Send Enter to execute
+                await sleep(100);
+                shell.write('\r');
+                dlog('Research prompt sent');
+            }
+            finally {
+                // RESUME STDIN
+                process.stdin.on('data', onStdinData);
+                dlog('Stdin resumed after research injection');
+            }
+        }, 4000); // Wait 4 seconds for Claude to fully initialize
+    }
     // Handle PTY exit
     shell.onExit(({ exitCode }) => {
         (0, state_1.clearAutoClearFlag)();
         stopStreamTailer(); // Stop stream capture
         (0, state_1.unregisterActiveSession)(); // Remove from active sessions registry
+        cleanupInstanceFile(instanceId); // Clean up instance file
         // Restore terminal
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(false);
@@ -996,6 +1267,7 @@ async function run(options) {
         (0, state_1.clearAutoClearFlag)();
         stopStreamTailer(); // Stop stream capture
         (0, state_1.unregisterActiveSession)(); // Remove from active sessions registry
+        cleanupInstanceFile(instanceId); // Clean up instance file
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(false);
         }

package/dist/commands/setup-remote.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ekkos setup-remote - One-command setup for remote terminal access
+ *
+ * This command does everything automatically:
+ * 1. Checks if user is logged in (prompts login if not)
+ * 2. Generates unique device ID and fingerprint
+ * 3. Opens browser for device pairing approval
+ * 4. Installs background agent as system service
+ * 5. Starts agent immediately
+ * 6. Verifies connection to cloud relay
+ */
+export interface SetupRemoteOptions {
+    force?: boolean;
+    skipService?: boolean;
+    verbose?: boolean;
+}
+/**
+ * Main setup command
+ */
+export declare function setupRemote(options?: SetupRemoteOptions): Promise<void>;