@ekkos/cli 1.3.9 → 1.4.0

package/dist/commands/gemini.d.ts

@@ -12,6 +12,7 @@ export interface GeminiOptions {
     verbose?: boolean;
     noProxy?: boolean;
     session?: string;
+    dashboard?: boolean;
 }
 /**
  * Launch Gemini CLI with ekkOS proxy integration.

package/dist/commands/gemini.js

@@ -62,6 +62,8 @@ const isWindows = process.platform === 'win32';
 const PULSE_LOADED_TEXT = '  🧠 ekkOS_Pulse  Loaded!';
 const PULSE_SHINE_FRAME_MS = 50;
 const PULSE_SHINE_SWEEPS = 2;
+const GEMINI_DEFAULT_MODEL = 'gemini-3.1-flash-lite-preview';
+const GEMINI_MAX_OUTPUT_TOKENS = 65536;
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -121,6 +123,159 @@ function resolveGeminiPath() {
     // 3. Ultimate fallback — let spawn resolve it (will error with helpful message)
     return 'gemini';
 }
+function extractGeminiCliArgs() {
+    const geminiIdx = process.argv.indexOf('gemini');
+    if (geminiIdx === -1)
+        return [];
+    const rawArgs = process.argv.slice(geminiIdx + 1);
+    const filtered = [];
+    for (let i = 0; i < rawArgs.length; i += 1) {
+        const arg = rawArgs[i];
+        if (!arg)
+            continue;
+        if (arg === '--skip-proxy' || arg === '-v' || arg === '--verbose' || arg === '--dashboard') {
+            continue;
+        }
+        if (arg === '-s' || arg === '--session') {
+            i += 1;
+            continue;
+        }
+        filtered.push(arg);
+    }
+    return filtered;
+}
+function resolveGeminiLaunchModel(args) {
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (!arg)
+            continue;
+        if ((arg === '-m' || arg === '--model') && typeof args[i + 1] === 'string') {
+            return args[i + 1];
+        }
+        if (arg.startsWith('--model=')) {
+            const value = arg.slice('--model='.length).trim();
+            if (value)
+                return value;
+        }
+    }
+    const envModel = (process.env.GEMINI_MODEL || process.env.GOOGLE_GEMINI_MODEL || '').trim();
+    return envModel || GEMINI_DEFAULT_MODEL;
+}
+function resolveGeminiContextSize(model) {
+    const normalized = (model || '').trim().toLowerCase();
+    if (normalized.startsWith('gemini-3.1-pro') || normalized.startsWith('gemini-3-pro')) {
+        return 2097152;
+    }
+    return 1048576;
+}
+function resolveGeminiProjectId(projectPath) {
+    try {
+        const projectsPath = path.join(os.homedir(), '.gemini', 'projects.json');
+        if (!fs.existsSync(projectsPath))
+            return undefined;
+        const parsed = JSON.parse(fs.readFileSync(projectsPath, 'utf-8'));
+        const projectId = parsed?.projects?.[projectPath];
+        return typeof projectId === 'string' && projectId.length > 0 ? projectId : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function getGeminiSessionMetadata(options, args) {
+    const model = resolveGeminiLaunchModel(args);
+    return {
+        provider: 'gemini',
+        claudeModel: model,
+        claudeLaunchModel: model,
+        claudeContextWindow: '1m',
+        claudeContextSize: resolveGeminiContextSize(model),
+        claudeMaxOutputTokens: GEMINI_MAX_OUTPUT_TOKENS,
+        geminiProjectId: resolveGeminiProjectId(process.cwd()),
+        dashboardEnabled: options.dashboard === true,
+    };
+}
+function writeGeminiSessionFiles(sessionId, sessionName, metadata) {
+    try {
+        const ekkosDir = path.join(os.homedir(), '.ekkos');
+        if (!fs.existsSync(ekkosDir))
+            fs.mkdirSync(ekkosDir, { recursive: true });
+        const now = new Date().toISOString();
+        fs.writeFileSync(path.join(ekkosDir, 'current-session.json'), JSON.stringify({ session_id: sessionId, session_name: sessionName, timestamp: now, ...metadata }, null, 2));
+        fs.writeFileSync(path.join(ekkosDir, 'session-hint.json'), JSON.stringify({
+            session_id: sessionId,
+            session_name: sessionName,
+            project_path: process.cwd(),
+            timestamp: now,
+            pid: process.pid,
+            ...metadata,
+        }, null, 2));
+    }
+    catch {
+        // Non-fatal
+    }
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\"'\"'`)}'`;
+}
+function launchGeminiWithDashboard(options, extraArgs) {
+    (0, state_1.getActiveSessions)();
+    const tmuxSession = `ekkos-gemini-${Date.now().toString(36)}`;
+    const sessionName = options.session || (0, state_1.uuidToWords)(crypto.randomUUID());
+    const sessionId = crypto.randomUUID();
+    options.session = sessionName;
+    cliSessionName = sessionName;
+    cliSessionId = sessionId;
+    const metadata = getGeminiSessionMetadata({ ...options, session: sessionName, dashboard: true }, extraArgs);
+    const ekkosCmd = process.argv[1];
+    const cwd = process.cwd();
+    const termCols = process.stdout.columns ?? 160;
+    const termRows = process.stdout.rows ?? 48;
+    writeGeminiSessionFiles(sessionId, sessionName, metadata);
+    const geminiArgs = ['gemini', '-s', sessionName];
+    if (options.verbose)
+        geminiArgs.push('-v');
+    if (options.noProxy)
+        geminiArgs.push('--skip-proxy');
+    geminiArgs.push(...extraArgs);
+    const runCommand = `EKKOS_NO_SPLASH=1 node ${shellQuote(ekkosCmd)} ${geminiArgs.map(shellQuote).join(' ')}`;
+    const dashCommand = `node ${shellQuote(ekkosCmd)} dashboard ${shellQuote(sessionName)} --provider gemini --refresh 2000`;
+    try {
+        (0, child_process_1.execSync)(`tmux new-session -d -s "${tmuxSession}" -x ${termCols} -y ${termRows} -n "gemini" 'sleep 86400'`, { stdio: 'pipe' });
+        const applyTmuxOpt = (cmd) => {
+            try {
+                (0, child_process_1.execSync)(`tmux ${cmd}`, { stdio: 'pipe' });
+            }
+            catch (err) {
+                if (options.verbose) {
+                    console.log(chalk_1.default.gray(`  tmux option skipped: ${cmd} (${err.message})`));
+                }
+            }
+        };
+        applyTmuxOpt(`set-option -t "${tmuxSession}" default-terminal "xterm-256color"`);
+        applyTmuxOpt(`set-option -sa -t "${tmuxSession}" terminal-overrides ",xterm-256color:Tc:smcup@:rmcup@"`);
+        applyTmuxOpt(`set-option -t "${tmuxSession}" mouse on`);
+        const detachCleanupHook = `if-shell -F '#{==:#{session_attached},0}' 'kill-session -t ${tmuxSession}'`;
+        applyTmuxOpt(`set-hook -t "${tmuxSession}" client-detached "${detachCleanupHook}"`);
+        applyTmuxOpt(`set-window-option -t "${tmuxSession}" history-limit 100000`);
+        applyTmuxOpt(`set-window-option -t "${tmuxSession}" mode-keys vi`);
+        applyTmuxOpt(`set-window-option -t "${tmuxSession}:gemini" synchronize-panes off`);
+        applyTmuxOpt(`set-window-option -t "${tmuxSession}:gemini" window-size latest`);
+        applyTmuxOpt(`set-window-option -t "${tmuxSession}:gemini" aggressive-resize on`);
+        applyTmuxOpt(`set-option -t "${tmuxSession}" remain-on-exit off`);
+        applyTmuxOpt(`set-option -t "${tmuxSession}" escape-time 0`);
+        (0, child_process_1.execSync)(`tmux split-window -t "${tmuxSession}:gemini" -h -p 40 -c "${cwd}" ${shellQuote(dashCommand)}`, { stdio: 'pipe' });
+        (0, child_process_1.execSync)(`tmux respawn-pane -k -t "${tmuxSession}:gemini.0" ${shellQuote(runCommand)}`, { stdio: 'pipe' });
+        (0, child_process_1.execSync)(`tmux select-pane -t "${tmuxSession}:gemini.0"`, { stdio: 'pipe' });
+        (0, child_process_1.execSync)(`tmux attach -t "${tmuxSession}"`, { stdio: 'inherit' });
+        return true;
+    }
+    catch (err) {
+        console.error(chalk_1.default.red(`\n  ✘ Failed to launch Gemini dashboard split: ${err.message}\n`));
+        console.log(chalk_1.default.gray('  Falling back to normal Gemini mode.'));
+        console.log(chalk_1.default.gray('  Run "ekkos dashboard --latest --provider gemini" in another terminal.\n'));
+        return false;
+    }
+}
 /**
  * Build environment for Gemini CLI with proxy routing.
  */
@@ -138,14 +293,20 @@ function buildGeminiEnv(options) {
     // Resolve userId from config or auth token
     const ekkosConfig = (0, state_1.getConfig)();
     let userId = ekkosConfig?.userId || 'anonymous';
+    const authToken = (0, state_1.getAuthToken)();
     if (userId === 'anonymous') {
-        const authToken = (0, state_1.getAuthToken)();
         if (authToken?.startsWith('ekk_')) {
             const parts = authToken.split('_');
             if (parts.length >= 2 && parts[1])
                 userId = parts[1];
         }
     }
+    // Gemini CLI strictly requires an API key to exist in the environment,
+    // even when routing to a proxy. If they don't have GEMINI_API_KEY set, 
+    // provide their GOOGLE_AI_API_KEY, ekkOS auth token, or a placeholder so the CLI boots up.
+    if (!env.GEMINI_API_KEY) {
+        env.GEMINI_API_KEY = env.GOOGLE_AI_API_KEY || authToken || 'ekk_guest_token_for_proxy';
+    }
     // Build proxy URL — no query params (SDK concatenates baseUrl + path as strings).
     // Format: /gproxy/{userId}/{session}/{sid}/{project64}
     // Proxy extracts params from path, then routes /v1beta or /v1beta1 to googleRouter.
@@ -164,6 +325,11 @@ function buildGeminiEnv(options) {
  */
 async function gemini(options = {}) {
     (0, state_1.ensureEkkosDir)();
+    const extraArgs = extractGeminiCliArgs();
+    if (options.dashboard) {
+        if (launchGeminiWithDashboard(options, extraArgs))
+            return;
+    }
     console.log('');
     console.log(chalk_1.default.cyan('  🧠 ekkOS_') + chalk_1.default.gray(' + ') + chalk_1.default.blue('Gemini CLI'));
     // Resolve binary
@@ -176,7 +342,9 @@ async function gemini(options = {}) {
     // Register session for multi-session awareness
     const sessionId = cliSessionId || crypto.randomUUID();
     const sessionName = cliSessionName || 'gemini-session';
-    (0, state_1.registerActiveSession)(sessionId, sessionName, process.cwd());
+    const metadata = getGeminiSessionMetadata(options, extraArgs);
+    (0, state_1.registerActiveSession)(sessionId, sessionName, process.cwd(), metadata);
+    writeGeminiSessionFiles(sessionId, sessionName, metadata);
     if (!options.noProxy) {
         await showPulseLoadedBanner();
     }
@@ -184,14 +352,6 @@ async function gemini(options = {}) {
     // Extract any trailing arguments meant for the inner CLI
     // We look for 'gemini' in process.argv and pass everything after it.
     // If the user did `ekkos gemini -m gemini-3.1-pro-preview`, we want to pass `-m gemini-3.1-pro-preview`
-    let extraArgs = [];
-    const geminiIdx = process.argv.indexOf('gemini');
-    if (geminiIdx !== -1) {
-        extraArgs = process.argv.slice(geminiIdx + 1).filter(a => {
-            // Filter out ekkos wrapper options
-            return !['--skip-proxy', '-v', '--verbose'].includes(a) && !(a === '-s' || a === '--session' || process.argv[process.argv.indexOf(a) - 1] === '-s' || process.argv[process.argv.indexOf(a) - 1] === '--session');
-        });
-    }
     // Spawn Gemini CLI — stdio: inherit for full terminal passthrough
     const child = (0, child_process_1.spawn)(geminiPath, extraArgs, {
         stdio: 'inherit',

package/dist/commands/init-living-docs.d.ts

@@ -0,0 +1,6 @@
+export interface InitLivingDocsOptions {
+    path?: string;
+    timeZone?: string;
+    noSeed?: boolean;
+}
+export declare function initLivingDocs(options: InitLivingDocsOptions): Promise<void>;

package/dist/commands/init-living-docs.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initLivingDocs = initLivingDocs;
+const chalk_1 = __importDefault(require("chalk"));
+const path_1 = require("path");
+const living_docs_manager_js_1 = require("../local/living-docs-manager.js");
+const state_1 = require("../utils/state");
+const platform_js_1 = require("../utils/platform.js");
+async function initLivingDocs(options) {
+    const targetPath = (0, path_1.resolve)(options.path || process.cwd());
+    const timeZone = options.timeZone || process.env.EKKOS_USER_TIMEZONE || Intl.DateTimeFormat().resolvedOptions().timeZone;
+    const apiKey = options.noSeed ? null : (0, state_1.getAuthToken)();
+    const apiUrl = options.noSeed ? undefined : (process.env.EKKOS_API_URL || platform_js_1.MCP_API_URL);
+    console.log('\n  ' + chalk_1.default.cyan.bold('Initialize ekkOS Cortex'));
+    console.log(chalk_1.default.gray('  ─────────────────────────────────'));
+    console.log(chalk_1.default.gray(`  Path: ${targetPath}`));
+    const manager = new living_docs_manager_js_1.LocalLivingDocsManager({
+        targetPath,
+        apiUrl,
+        apiKey,
+        timeZone,
+        onLog: message => console.log(chalk_1.default.gray(`  ${message}`)),
+    });
+    // Force a full scan and compile by ignoring the cooldown
+    // We'll use a slightly different flow than .start() to make it one-shot
+    console.log(chalk_1.default.gray('  Scanning repository structure...'));
+    // We hack the cooldown by temporarily setting the env var if we could, 
+    // but better to just call the internal methods if they were public.
+    // Since they are private, we'll use a small trick: 
+    // The start() method is what we want, but we want it to exit after the first pass.
+    // Actually, let's just use start() and wait for the initialCompilePromise
+    manager.start();
+    // Give it a moment to start the initial pass
+    const checkInterval = setInterval(() => {
+        // @ts-ignore - reaching into private for the promise
+        if (manager.initialCompilePromise) {
+            // @ts-ignore
+            manager.initialCompilePromise.then(() => {
+                clearInterval(checkInterval);
+                manager.stop();
+                console.log('\n' + chalk_1.default.green('  ✓ ekkOS Cortex initialized successfully!'));
+                console.log(chalk_1.default.gray('  Your project now has ekkOS_CONTEXT.md files for every discovered system.'));
+                console.log(chalk_1.default.gray('  Run `ekkos cortex watch` to keep them updated while you work.'));
+                console.log('');
+                process.exit(0);
+            });
+        }
+    }, 100);
+    // Safety timeout
+    setTimeout(() => {
+        console.log(chalk_1.default.red('\n  Initialization timed out.'));
+        process.exit(1);
+    }, 60000);
+}

package/dist/commands/living-docs.js

@@ -11,13 +11,13 @@ const state_1 = require("../utils/state");
 const platform_js_1 = require("../utils/platform.js");
 function printStartupSummary(options) {
     console.log('');
-    console.log(chalk_1.default.cyan.bold('  ekkOS Living Docs Watch'));
-    console.log(chalk_1.default.gray('  ─────────────────────────'));
+    console.log(chalk_1.default.cyan.bold('  ekkOS Cortex Watcher'));
+    console.log(chalk_1.default.gray('  ──────────────────────'));
     console.log(chalk_1.default.gray(`  Path: ${options.targetPath}`));
     console.log(chalk_1.default.gray(`  Timezone: ${options.timeZone}`));
     console.log(chalk_1.default.gray(`  Registry seed: ${options.seedingEnabled ? 'enabled' : 'disabled'}`));
     console.log('');
-    console.log(chalk_1.default.gray('  Watching local files and rewriting ekkOS_CONTEXT.md on change.'));
+    console.log(chalk_1.default.gray('  Watching local files and updating Cortex docs (ekkOS_CONTEXT.md) on change.'));
     console.log(chalk_1.default.gray('  Press Ctrl+C to stop.'));
     console.log('');
 }

package/dist/commands/run.js

@@ -86,7 +86,7 @@ function getConfig(options) {
     };
     /* eslint-enable no-restricted-syntax */
 }
-const MAX_OUTPUT_1M_MODELS = '128000';
+const MAX_OUTPUT_1M_MODELS = '64000';
 const MAX_OUTPUT_200K_OPUS_SONNET = '32768';
 let runtimeClaudeCodeVersion = null;
 let runtimeClaudeContextWindow = 'auto';
@@ -149,6 +149,62 @@ function buildClaudeLaunchModelArg(model, contextWindow) {
     }
     return normalized;
 }
+function buildClaudeLaunchProfileId(model, contextWindow) {
+    const normalized = normalizeRequestedLaunchModel(model).model;
+    if (!normalized)
+        return undefined;
+    const lower = normalized.toLowerCase();
+    if (/^claude-opus-4-6(?:$|-)/.test(lower)) {
+        if (contextWindow === '200k')
+            return 'claude-opus-4-6-200k';
+        if (contextWindow === '1m')
+            return 'claude-opus-4-6-1m';
+        return undefined;
+    }
+    if (/^claude-sonnet-4-6(?:$|-)/.test(lower)) {
+        if (contextWindow === '200k')
+            return 'claude-sonnet-4-6-200k';
+        if (contextWindow === '1m')
+            return 'claude-sonnet-4-6-1m';
+        return undefined;
+    }
+    if (/^claude-opus-4-5(?:$|-)/.test(lower))
+        return 'claude-opus-4-5';
+    if (/^claude-sonnet-4-5(?:$|-)/.test(lower))
+        return 'claude-sonnet-4-5';
+    if (/^claude-haiku-4-5(?:$|-)/.test(lower))
+        return 'claude-haiku-4-5';
+    return normalized;
+}
+function resolveClaudeContextWindowSize(model, contextWindow) {
+    if (contextWindow === '200k')
+        return 200000;
+    if (contextWindow === '1m' && modelSupportsOneMillionContext(model))
+        return 1000000;
+    if (model && !modelSupportsOneMillionContext(model))
+        return 200000;
+    return undefined;
+}
+function getClaudeSessionMetadata(options) {
+    const normalizedContextWindow = normalizeContextWindowOption(options.contextWindow);
+    const selectedModel = typeof options.model === 'string' ? options.model : undefined;
+    const launchModel = buildClaudeLaunchModelArg(selectedModel, normalizedContextWindow);
+    const profileId = buildClaudeLaunchProfileId(selectedModel, normalizedContextWindow);
+    const contextSize = resolveClaudeContextWindowSize(selectedModel, normalizedContextWindow);
+    const maxOutputTokens = Number.parseInt(resolveClaudeMaxOutputTokens(selectedModel, normalizedContextWindow), 10);
+    return {
+        provider: 'claude',
+        claudeModel: normalizeRequestedLaunchModel(selectedModel).model,
+        claudeLaunchModel: launchModel,
+        claudeProfile: profileId,
+        claudeContextWindow: normalizedContextWindow,
+        claudeContextSize: contextSize,
+        claudeMaxOutputTokens: Number.isFinite(maxOutputTokens) ? maxOutputTokens : undefined,
+        claudeCodeVersion: runtimeClaudeCodeVersion || undefined,
+        dashboardEnabled: options.dashboard === true,
+        bypassEnabled: options.bypass === true,
+    };
+}
 function isTwoHundredKFixedOutputModel(model) {
     const normalized = (model || '').trim().toLowerCase();
     if (!normalized)
@@ -184,7 +240,7 @@ function renderClaudeLaunchSelectorIntro() {
     console.log(line(chalk_1.default.white.bold('ekkOS.dev // PULSE')));
     console.log(neonCyan('╠══════════════════════════════════════════════════════════════════════╣'));
     console.log(line(`${acidGreen('200K')} ${steel('compat lane')} ${chalk_1.default.white('// Opus/Sonnet 4.5/4.6 => 32,768 output')}`));
-    console.log(line(`${signalAmber(' 1M')} ${steel('wide lane')}   ${chalk_1.default.white('// Opus/Sonnet 4.6 => 128,000 output')}`));
+    console.log(line(`${signalAmber(' 1M')} ${steel('wide lane')}   ${chalk_1.default.white('// Opus/Sonnet 4.6 => 64,000 output')}`));
     console.log(line(steel('Pick a launch vector, then a fixed runtime profile. No hidden context prompt.')));
     console.log(neonCyan('╚══════════════════════════════════════════════════════════════════════╝'));
     console.log('');
@@ -223,7 +279,7 @@ function buildLaunchModelChoices() {
             value: 'claude-opus-4-6-200k',
         },
         {
-            name: `${cyan.bold('Claude Opus 4.6')} ${amber('[1M]')} ${chalk_1.default.gray('// out 128,000')}`,
+            name: `${cyan.bold('Claude Opus 4.6')} ${amber('[1M]')} ${chalk_1.default.gray('// out 64,000')}`,
             value: 'claude-opus-4-6-1m',
         },
         {
@@ -235,7 +291,7 @@ function buildLaunchModelChoices() {
             value: 'claude-sonnet-4-6-200k',
         },
         {
-            name: `${cyan.bold('Claude Sonnet 4.6')} ${amber('[1M]')} ${chalk_1.default.gray('// out 128,000')}`,
+            name: `${cyan.bold('Claude Sonnet 4.6')} ${amber('[1M]')} ${chalk_1.default.gray('// out 64,000')}`,
             value: 'claude-sonnet-4-6-1m',
         },
         {
@@ -615,6 +671,7 @@ function getEkkosEnv() {
         // Gateway extracts from URL: /proxy/{userId}/{sessionName}/v1/messages
         const proxyUrl = (0, proxy_url_1.buildProxyUrl)(userId, cliSessionName, process.cwd(), cliSessionId, {
             claudeCodeVersion: runtimeClaudeCodeVersion || undefined,
+            claudeProfile: buildClaudeLaunchProfileId(runtimeClaudeLaunchModel, runtimeClaudeContextWindow),
             claudeContextWindow: runtimeClaudeContextWindow,
         });
         env.ANTHROPIC_BASE_URL = proxyUrl;
@@ -859,7 +916,7 @@ function formatPulseContextLine(contextWindow) {
         return '200K // 200,000 token window // forced 32,768 output';
     }
     if (contextWindow === '1m') {
-        return '1M // 1,000,000 token window // unlocked 128,000 output';
+        return '1M // 1,000,000 token window // safe 64,000 output cap';
     }
     return 'AUTO // ekkOS resolves 200K vs 1M from the selected profile';
 }
@@ -906,7 +963,7 @@ async function showPulseLaunchLoader(options) {
     console.log(buildPanelLine(steel, 'PATH', 'selector -> dashboard -> claude -> proxy'));
     console.log(cyan('  ╚══════════════════════════════════════════════════════════════════════════════╝'));
     console.log(`  ${green('200K')} ${steel('// Opus/Sonnet 4.5/4.6 => 32,768 output')}`);
-    console.log(`  ${amber('1M  ')} ${steel('// Opus/Sonnet 4.6 => 128,000 output')}`);
+    console.log(`  ${amber('1M  ')} ${steel('// Opus/Sonnet 4.6 => 64,000 output')}`);
     console.log('');
     for (const stage of stages) {
         for (let filled = 0; filled <= barWidth; filled += 1) {
@@ -1131,10 +1188,16 @@ function cleanupInstanceFile(instanceId) {
  * Keeps ~/.ekkos/current-session.json, ~/.claude/state/current-session.json,
  * and ~/.ekkos/session-hint.json in sync whenever the session is known.
  */
-function writeSessionFiles(sessionId, sessionName) {
+function writeSessionFiles(sessionId, sessionName, metadata) {
     try {
         const ekkosDir = path.join(os.homedir(), '.ekkos');
         const claudeStateDir = path.join(os.homedir(), '.claude', 'state');
+        const launchMetadata = metadata || getClaudeSessionMetadata({
+            model: runtimeClaudeLaunchModel,
+            contextWindow: runtimeClaudeContextWindow,
+            dashboard: false,
+            bypass: false,
+        });
         // Ensure directories exist
         if (!fs.existsSync(ekkosDir))
             fs.mkdirSync(ekkosDir, { recursive: true });
@@ -1142,16 +1205,17 @@ function writeSessionFiles(sessionId, sessionName) {
             fs.mkdirSync(claudeStateDir, { recursive: true });
         const now = new Date().toISOString();
         // 1. ~/.ekkos/current-session.json
-        fs.writeFileSync(path.join(ekkosDir, 'current-session.json'), JSON.stringify({ session_id: sessionId, session_name: sessionName, timestamp: now }, null, 2));
+        fs.writeFileSync(path.join(ekkosDir, 'current-session.json'), JSON.stringify({ session_id: sessionId, session_name: sessionName, timestamp: now, ...launchMetadata }, null, 2));
         // 2. ~/.claude/state/current-session.json
-        fs.writeFileSync(path.join(claudeStateDir, 'current-session.json'), JSON.stringify({ session_id: sessionId, session_name: sessionName, timestamp: now }, null, 2));
+        fs.writeFileSync(path.join(claudeStateDir, 'current-session.json'), JSON.stringify({ session_id: sessionId, session_name: sessionName, timestamp: now, ...launchMetadata }, null, 2));
         // 3. ~/.ekkos/session-hint.json (dashboard discovery)
         fs.writeFileSync(path.join(ekkosDir, 'session-hint.json'), JSON.stringify({
             session_name: sessionName,
             session_id: sessionId,
             project_path: process.cwd(),
             timestamp: now,
-            pid: process.pid
+            pid: process.pid,
+            ...launchMetadata,
         }, null, 2));
     }
     catch {
@@ -1199,7 +1263,7 @@ function launchWithDashboard(options) {
     const termCols = process.stdout.columns ?? 160;
     const termRows = process.stdout.rows ?? 48;
     // Write session hint immediately so dashboard can find JSONL as it appears
-    writeSessionFiles(crypto.randomUUID(), sessionName);
+    writeSessionFiles(crypto.randomUUID(), sessionName, getClaudeSessionMetadata(options));
     const runCommand = `EKKOS_NO_SPLASH=1 node "${ekkosCmd}" ${runArgs.join(' ')}`;
     // Pass session name directly — dashboard starts rendering immediately (lazy JSONL resolution)
     const dashCommand = `node "${ekkosCmd}" dashboard "${sessionName}" --refresh 2000`;
@@ -1263,7 +1327,7 @@ function launchWithWindowsTerminal(options) {
     // Pre-generate session name so dashboard can start immediately
     const sessionName = options.session || (0, state_1.uuidToWords)(crypto.randomUUID());
     // Write session hint immediately
-    writeSessionFiles(crypto.randomUUID(), sessionName);
+    writeSessionFiles(crypto.randomUUID(), sessionName, getClaudeSessionMetadata(options));
     // Build ekkos run args WITHOUT --dashboard (prevent recursion)
     // Always pass -s so run reuses the same session name we gave the dashboard
     const runArgs = ['run', '-s', sessionName];
@@ -1778,8 +1842,8 @@ async function run(options) {
     // ════════════════════════════════════════════════════════════════════════════
     const initialSessionId = cliSessionId || 'pending';
     const initialSessionName = currentSession || 'initializing';
-    (0, state_1.registerActiveSession)(initialSessionId, initialSessionName, process.cwd());
-    writeSessionFiles(initialSessionId, initialSessionName);
+    (0, state_1.registerActiveSession)(initialSessionId, initialSessionName, process.cwd(), getClaudeSessionMetadata(options));
+    writeSessionFiles(initialSessionId, initialSessionName, getClaudeSessionMetadata(options));
     dlog(`Registered active session (PID ${process.pid})`);
     // Show active sessions count if verbose
     if (verbose) {
@@ -1946,9 +2010,9 @@ async function run(options) {
                     // and shown in "Continuum Loaded". Re-deriving from JSONL UUID produces a
                     // different name since Claude Code's UUID ≠ the CLI-generated UUID.
                     currentSession = cliSessionName || (0, state_1.uuidToWords)(sessionId);
-                    (0, state_1.updateCurrentProcessSession)(currentSessionId, currentSession);
+                    (0, state_1.updateCurrentProcessSession)(currentSessionId, currentSession, getClaudeSessionMetadata(options));
                     (0, state_1.updateState)({ sessionId: currentSessionId, sessionName: currentSession });
-                    writeSessionFiles(currentSessionId, currentSession);
+                    writeSessionFiles(currentSessionId, currentSession, getClaudeSessionMetadata(options));
                     bindRealSessionToProxy(currentSession, 'fast-transcript', currentSessionId);
                     dlog(`[TRANSCRIPT] FAST DETECT: New transcript found! ${fullPath}`);
                     evictionDebugLog('TRANSCRIPT_SET', 'Fast poll detected new file', {
@@ -2842,10 +2906,10 @@ async function run(options) {
             // Keep cliSessionName if set (proxy mode) — JSONL UUID differs from CLI UUID
             currentSession = cliSessionName || (0, state_1.uuidToWords)(currentSessionId);
             // Update THIS process's session entry (not global state.json)
-            (0, state_1.updateCurrentProcessSession)(currentSessionId, currentSession);
+            (0, state_1.updateCurrentProcessSession)(currentSessionId, currentSession, getClaudeSessionMetadata(options));
             // Also update global state for backwards compatibility
             (0, state_1.updateState)({ sessionId: currentSessionId, sessionName: currentSession });
-            writeSessionFiles(currentSessionId, currentSession);
+            writeSessionFiles(currentSessionId, currentSession, getClaudeSessionMetadata(options));
             dlog(`Session detected from UUID: ${currentSession}`);
             resolveTranscriptFromSessionId('session-id-from-output');
             bindRealSessionToProxy(currentSession, 'session-id-from-output', currentSessionId || undefined);
@@ -2878,10 +2942,10 @@ async function run(options) {
                     currentSession = lastSeenSessionName;
                     observedSessionThisRun = true; // Mark that we've seen a session in THIS process
                     // Update THIS process's session entry (not global state.json)
-                    (0, state_1.updateCurrentProcessSession)(currentSessionId || 'unknown', currentSession);
+                    (0, state_1.updateCurrentProcessSession)(currentSessionId || 'unknown', currentSession, getClaudeSessionMetadata(options));
                     // Also update global state for backwards compatibility
                     (0, state_1.updateState)({ sessionName: currentSession });
-                    writeSessionFiles(currentSessionId || 'unknown', currentSession);
+                    writeSessionFiles(currentSessionId || 'unknown', currentSession, getClaudeSessionMetadata(options));
                     dlog(`Session detected from status line: ${currentSession} (observedSessionThisRun=true)`);
                     bindRealSessionToProxy(currentSession, 'status-line', currentSessionId || undefined);
                     resolveTranscriptFromSessionId('status-line');

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

@@ -0,0 +1,3 @@
+export declare function setupCiCommand(options: {
+    repoRoot?: string;
+}): Promise<number>;

package/dist/commands/setup-ci.js

@@ -0,0 +1,107 @@
+"use strict";
+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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupCiCommand = setupCiCommand;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const WORKFLOW_CONTENT = `name: ekkOS Cortex Validation
+
+on:
+  push:
+    branches: [main, master]
+    paths:
+      - '**/ekkOS_CONTEXT.md'
+  pull_request:
+    branches: [main, master]
+    paths:
+      - '**/ekkOS_CONTEXT.md'
+
+jobs:
+  validate-cortex:
+    name: Validate Cortex Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Validate Cortex docs
+        run: npx @google/gemini-cli docs validate
+        
+      - name: Add validation summary
+        if: always()
+        run: |
+          echo "### ekkOS Cortex Validation" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "Validated \`ekkOS_CONTEXT.md\` files across the repository." >> "$GITHUB_STEP_SUMMARY"
+          if [ "\${{ job.status }}" = "success" ]; then
+            echo "**Result:** All Cortex checks passed." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "**Result:** Some Cortex checks failed. See logs for details." >> "$GITHUB_STEP_SUMMARY"
+          fi
+`;
+async function setupCiCommand(options) {
+    const repoRoot = options.repoRoot || process.cwd();
+    const workflowsDir = path.join(repoRoot, '.github', 'workflows');
+    const workflowFile = path.join(workflowsDir, 'ekkos-cortex-validation.yml');
+    console.log(chalk_1.default.cyan.bold('\n  ekkOS Cortex CI/CD Setup'));
+    console.log(chalk_1.default.gray('  ─────────────────────────'));
+    if (!fs.existsSync(workflowsDir)) {
+        fs.mkdirSync(workflowsDir, { recursive: true });
+        console.log(chalk_1.default.gray(`  Created directory: .github/workflows`));
+    }
+    if (fs.existsSync(workflowFile)) {
+        console.log(chalk_1.default.yellow(`  ⚠️  Workflow file already exists at: .github/workflows/ekkos-cortex-validation.yml`));
+        console.log(chalk_1.default.gray(`  Skipping creation to avoid overwriting.`));
+        return 0;
+    }
+    fs.writeFileSync(workflowFile, WORKFLOW_CONTENT, 'utf-8');
+    console.log(chalk_1.default.green(`  ✓ Created GitHub Actions workflow: .github/workflows/ekkos-cortex-validation.yml`));
+    console.log('');
+    console.log(chalk_1.default.gray('  This workflow will automatically run `ekkos docs validate` on pull requests'));
+    console.log(chalk_1.default.gray('  and pushes that modify any ekkOS_CONTEXT.md (Cortex) file in your repository.'));
+    console.log('');
+    return 0;
+}