@ekkos/cli 1.3.6 → 1.3.8

package/dist/deploy/instructions.js

@@ -6,25 +6,52 @@ exports.getInstructionsContent = getInstructionsContent;
 const fs_1 = require("fs");
 const platform_1 = require("../utils/platform");
 const templates_1 = require("../utils/templates");
+const BEGIN_MARKER = '<!-- ekkOS:begin — managed by ekkos init, do not remove this marker -->';
+const END_MARKER = '<!-- ekkOS:end -->';
 /**
- * Deploy CLAUDE.md to ~/.claude/CLAUDE.md
+ * Deploy ekkOS block into ~/.claude/CLAUDE.md.
+ *
+ * Strategy:
+ *  - If file doesn't exist → create it with just the ekkOS block.
+ *  - If file exists and already has markers → replace the block between markers.
+ *  - If file exists with no markers → prepend ekkOS block above existing content.
+ *
+ * Never destroys user content outside the markers.
  */
 function deployInstructions() {
-    // Ensure .claude directory exists
     if (!(0, fs_1.existsSync)(platform_1.CLAUDE_DIR)) {
         (0, fs_1.mkdirSync)(platform_1.CLAUDE_DIR, { recursive: true });
     }
-    // Copy CLAUDE.md template
-    (0, templates_1.copyTemplateFile)('CLAUDE.md', platform_1.CLAUDE_MD);
+    const ekkosBlock = (0, templates_1.readTemplate)('CLAUDE.md');
+    if (!(0, fs_1.existsSync)(platform_1.CLAUDE_MD)) {
+        // No file — create fresh
+        (0, fs_1.writeFileSync)(platform_1.CLAUDE_MD, ekkosBlock);
+        return;
+    }
+    const existing = (0, fs_1.readFileSync)(platform_1.CLAUDE_MD, 'utf-8');
+    const beginIdx = existing.indexOf(BEGIN_MARKER);
+    const endIdx = existing.indexOf(END_MARKER);
+    if (beginIdx !== -1 && endIdx !== -1 && endIdx > beginIdx) {
+        // Markers found — replace in-place
+        const before = existing.slice(0, beginIdx);
+        const after = existing.slice(endIdx + END_MARKER.length);
+        (0, fs_1.writeFileSync)(platform_1.CLAUDE_MD, before + ekkosBlock + after);
+        return;
+    }
+    // No markers — prepend ekkOS block, preserve everything below
+    (0, fs_1.writeFileSync)(platform_1.CLAUDE_MD, ekkosBlock + '\n\n' + existing);
 }
 /**
- * Check if CLAUDE.md is deployed
+ * Check if CLAUDE.md has the ekkOS block
  */
 function isInstructionsDeployed() {
-    return (0, fs_1.existsSync)(platform_1.CLAUDE_MD);
+    if (!(0, fs_1.existsSync)(platform_1.CLAUDE_MD))
+        return false;
+    const content = (0, fs_1.readFileSync)(platform_1.CLAUDE_MD, 'utf-8');
+    return content.includes(BEGIN_MARKER) && content.includes(END_MARKER);
 }
 /**
- * Get the CLAUDE.md content (for preview)
+ * Get the ekkOS CLAUDE.md template content
  */
 function getInstructionsContent() {
     try {

package/dist/index.js

@@ -38,27 +38,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const commander_1 = require("commander");
-const init_1 = require("./commands/init");
-const test_1 = require("./commands/test");
-const status_1 = require("./commands/status");
+// The `run` command is the default (bare `ekkos`), so it stays eager.
+// `dashboardCommand` is eager because `run --dashboard` spawns `ekkos dashboard` in tmux.
+// All other command modules are loaded lazily inside .action() callbacks.
 const run_1 = require("./commands/run");
-const gemini_1 = require("./commands/gemini");
-const test_claude_1 = require("./commands/test-claude");
-const doctor_1 = require("./commands/doctor");
-const stream_1 = require("./commands/stream");
-const claw_1 = require("./commands/claw");
-// DEPRECATED: Hooks removed in hookless architecture migration
-// hooksInstall, hooksVerify, hooksStatus no longer called — `hooks` command prints a deprecation notice.
-const state_1 = require("./utils/state");
-const index_1 = require("./commands/usage/index");
 const dashboard_1 = require("./commands/dashboard");
-const swarm_1 = require("./commands/swarm");
-const swarm_dashboard_1 = require("./commands/swarm-dashboard");
-const swarm_setup_1 = require("./commands/swarm-setup");
-const scan_1 = require("./commands/scan");
 const chalk_1 = __importDefault(require("chalk"));
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
 // Get version from package.json (CommonJS compatible)
 const pkgPath = path.resolve(__dirname, '../package.json');
 const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
@@ -75,16 +63,13 @@ commander_1.program
     .addHelpText('after', [
     '',
     chalk_1.default.cyan.bold('Examples:'),
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Start Claude Code with ekkOS memory (default: run)')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos init')}                         ${chalk_1.default.gray('First-time setup — authenticate + configure your IDE')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos scan')}                         ${chalk_1.default.gray('Scan repo structure and seed system registry')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos scan --compile')}               ${chalk_1.default.gray('Scan, seed, and trigger compile pass')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch with live usage dashboard (tmux split)')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run -b')}                       ${chalk_1.default.gray('Launch with bypass permissions mode')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos doctor --fix')}                 ${chalk_1.default.gray('Check and auto-fix system prerequisites')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos usage daily')}                  ${chalk_1.default.gray("View today's token usage and costs")}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos gemini')}                       ${chalk_1.default.gray('Launch Gemini CLI with ekkOS memory proxy')}`,
-    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos swarm launch -t "build X"')}    ${chalk_1.default.gray('Launch parallel workers on a task')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos')}                              ${chalk_1.default.gray('Start Claude Code with ekkOS memory (default)')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos codex')}                        ${chalk_1.default.gray('Start Codex (OpenAI) mode')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos daemon start')}                 ${chalk_1.default.gray('Start the background mobile sync service')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos docs watch')}                   ${chalk_1.default.gray('Keep local ekkOS_CONTEXT.md files updated on disk')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos connect gemini')}               ${chalk_1.default.gray('Securely store your Gemini API key in the cloud')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos agent create --path ./repo')}   ${chalk_1.default.gray('Spawn a headless remote agent in a directory')}`,
+    `  ${chalk_1.default.gray('$')} ${chalk_1.default.white('ekkos run --dashboard')}              ${chalk_1.default.gray('Launch Claude with live usage dashboard')}`,
     '',
     chalk_1.default.gray('  Run ') + chalk_1.default.white('ekkos <command> --help') + chalk_1.default.gray(' for detailed options on any command.'),
     '',
@@ -152,38 +137,49 @@ commander_1.program
                 title: 'Getting Started',
                 icon: '▸',
                 commands: [
-                    { name: 'init', desc: 'Authenticate and configure your IDE (Claude, Cursor, Windsurf)' },
+                    { name: 'init', desc: 'First-time setup — authenticate and configure IDEs' },
                     { name: 'scan', desc: 'Scan repo structure and seed ekkOS system registry' },
-                    { name: 'status', desc: 'Show memory status and installation info' },
-                    { name: 'test', desc: 'Test connection to ekkOS memory API' },
-                    { name: 'doctor', desc: 'Check system prerequisites (Node, PTY, Claude, MCP)' },
+                    { name: 'docs', desc: 'Watch and regenerate local ekkOS_CONTEXT.md files' },
+                    { name: 'status', desc: 'Show overall system status (Memory, Sync Daemon, Auth)' },
+                    { name: 'doctor', desc: 'Check system prerequisites and fix runaway processes' },
                 ],
             },
             {
-                title: 'Running',
+                title: 'Launch Agents (Local + Mobile Synced)',
                 icon: '▸',
                 commands: [
-                    { name: 'run', desc: 'Launch Claude Code with ekkOS memory', note: 'default' },
-                    { name: 'test-claude', desc: 'Launch Claude with proxy only (no PTY) for debugging' },
-                    { name: 'sessions', desc: 'List active Claude Code sessions' },
-                    { name: 'claw', desc: 'OpenClaw integration status and upgrade controls' },
+                    { name: 'run', desc: 'Launch Claude Code with memory and mobile control', note: 'default' },
+                    { name: 'codex', desc: 'Launch Codex (OpenAI) with mobile control' },
+                    { name: 'gemini', desc: 'Launch Gemini mode (ACP) with mobile control' },
+                    { name: 'acp', desc: 'Launch a generic ACP-compatible agent' },
                 ],
             },
             {
-                title: 'Monitoring & Usage',
+                title: 'Mobile Sync & Cloud (Synk)',
                 icon: '▸',
                 commands: [
-                    { name: 'usage', desc: 'Token usage and cost tracking (daily, weekly, monthly, session)' },
-                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
-                    { name: 'stream', desc: 'Stream capture status and management' },
-                    { name: 'hooks', desc: '[DEPRECATED] Hooks no longer needed — use `ekkos run`' },
+                    { name: 'daemon', desc: 'Manage background mobile sync service (start, stop, status)' },
+                    { name: 'connect', desc: 'Securely store AI vendor API keys in the cloud' },
+                    { name: 'sandbox', desc: 'Configure OS-level sandboxing for agent execution' },
+                    { name: 'notify', desc: 'Send push notifications to your Synk mobile app' },
                 ],
             },
             {
-                title: 'Swarm (Multi-Agent)',
+                title: 'Headless Agents (Remote Control)',
                 icon: '▸',
                 commands: [
-                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, swarm dashboard' },
+                    { name: 'agent', desc: 'Manage remote headless agents (create, list, stop)' },
+                    { name: 'swarm', desc: 'Parallel workers, Q-learning routing, and swarm dashboard' },
+                ],
+            },
+            {
+                title: 'Monitoring & Usage',
+                icon: '▸',
+                commands: [
+                    { name: 'auth', desc: 'Manage authentication for Memory, Agents, and Mobile App' },
+                    { name: 'usage', desc: 'Token usage and cost tracking (daily, weekly, monthly, session)' },
+                    { name: 'dashboard', desc: 'Live TUI dashboard for session monitoring' },
+                    { name: 'sessions', desc: 'List active local CLI sessions' },
                 ],
             },
         ];
@@ -225,7 +221,7 @@ commander_1.program
     .option('-q, --quick', 'Quick setup: auto-detect IDE, use defaults, only prompt for API key if missing')
     .option('--skip-hooks', '[DEPRECATED] Hooks are no longer deployed; this flag is a no-op')
     .option('--skip-skills', 'Skip skills deployment')
-    .action(init_1.init);
+    .action(async (options) => { const { init } = await Promise.resolve().then(() => __importStar(require('./commands/init'))); await init(options); });
 // Scan command — discover repo systems and seed registry
 commander_1.program
     .command('scan')
@@ -233,21 +229,45 @@ commander_1.program
     .option('-c, --compile', 'Trigger a compile pass after seeding')
     .option('-n, --dry-run', 'Show discovered systems without seeding')
     .option('-p, --path <path>', 'Path to scan (default: current directory)')
-    .action((options) => {
-    (0, scan_1.scan)({
+    .action(async (options) => {
+    const { scan } = await Promise.resolve().then(() => __importStar(require('./commands/scan')));
+    scan({
         compile: options.compile,
         dryRun: options.dryRun,
         path: options.path,
     });
 });
+// Local living docs command
+const docsCmd = commander_1.program
+    .command('docs')
+    .description('Manage local ekkOS_CONTEXT.md living docs');
+docsCmd
+    .command('watch')
+    .description('Watch the local workspace and keep ekkOS_CONTEXT.md files current on disk')
+    .option('-p, --path <path>', 'Path to watch (default: current directory)')
+    .option('--timezone <iana-tz>', 'IANA timezone for timestamps (default: local machine timezone)')
+    .option('--poll-interval-ms <ms>', 'Polling interval fallback in milliseconds', (value) => parseInt(value, 10))
+    .option('--debounce-ms <ms>', 'Debounce window before recompiling in milliseconds', (value) => parseInt(value, 10))
+    .option('--no-seed', 'Do not seed the platform registry while watching')
+    .action(async (options) => {
+    const { watchLivingDocs } = await Promise.resolve().then(() => __importStar(require('./commands/living-docs')));
+    watchLivingDocs({
+        path: options.path,
+        timeZone: options.timezone,
+        pollIntervalMs: options.pollIntervalMs,
+        debounceMs: options.debounceMs,
+        noSeed: options.seed === false,
+    });
+});
 // Status command
 commander_1.program
     .command('status')
     .description('Show live session metrics and memory status')
     .option('-w, --watch', 'Watch mode — refresh session panel every 2s')
     .option('--json', 'Output raw metrics JSON (no memory API call)')
-    .action((options) => {
-    (0, status_1.status)({ watch: options.watch, json: options.json });
+    .action(async (options) => {
+    const { status } = await Promise.resolve().then(() => __importStar(require('./commands/status')));
+    status({ watch: options.watch, json: options.json });
 });
 // OpenClaw integration commands
 const clawCmd = commander_1.program
@@ -260,8 +280,9 @@ clawCmd
     .option('--proxy-url <url>', 'Expected ekkOS proxy URL (default: https://proxy.ekkos.dev)')
     .option('--model <model>', 'Expected primary OpenClaw model (default: ekkos-proxy/claude-sonnet-4-6)')
     .option('--workspace <path>', 'Expected OpenClaw workspace path')
-    .action((options) => {
-    (0, claw_1.clawStatus)({
+    .action(async (options) => {
+    const { clawStatus } = await Promise.resolve().then(() => __importStar(require('./commands/claw')));
+    clawStatus({
         json: options.json,
         proxyUrl: options.proxyUrl,
         model: options.model,
@@ -277,8 +298,9 @@ clawCmd
     .option('--proxy-url <url>', 'Target ekkOS proxy URL')
     .option('--model <model>', 'Target primary OpenClaw model')
     .option('--workspace <path>', 'Expected OpenClaw workspace path for status verification')
-    .action((options) => {
-    (0, claw_1.clawUpgrade)({
+    .action(async (options) => {
+    const { clawUpgrade } = await Promise.resolve().then(() => __importStar(require('./commands/claw')));
+    clawUpgrade({
         apply: options.apply,
         force: options.force,
         json: options.json,
@@ -291,7 +313,7 @@ clawCmd
 commander_1.program
     .command('test')
     .description('Test connection to ekkOS memory')
-    .action(test_1.test);
+    .action(async () => { const { test } = await Promise.resolve().then(() => __importStar(require('./commands/test'))); await test(); });
 // Run command - launches Claude Code with ekkOS proxy
 commander_1.program
     .command('run')
@@ -325,8 +347,9 @@ commander_1.program
     .option('-s, --session <name>', 'Session name')
     .option('-v, --verbose', 'Show debug output')
     .option('--skip-proxy', 'Skip API proxy (use direct Gemini API)')
-    .action((options) => {
-    (0, gemini_1.gemini)({
+    .action(async (options) => {
+    const { gemini } = await Promise.resolve().then(() => __importStar(require('./commands/gemini')));
+    gemini({
         session: options.session,
         verbose: options.verbose,
         noProxy: options.skipProxy,
@@ -339,8 +362,9 @@ commander_1.program
     .option('--no-proxy', 'Skip proxy too (completely vanilla Claude)')
     .option('--no-hooks', 'Temporarily disable all hooks during test')
     .option('-v, --verbose', 'Show debug output')
-    .action((options) => {
-    (0, test_claude_1.testClaude)({
+    .action(async (options) => {
+    const { testClaude } = await Promise.resolve().then(() => __importStar(require('./commands/test-claude')));
+    testClaude({
         noProxy: options.proxy === false,
         noHooks: options.hooks === false,
         verbose: options.verbose,
@@ -352,8 +376,9 @@ commander_1.program
     .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 });
+    .action(async (options) => {
+    const { doctor } = await Promise.resolve().then(() => __importStar(require('./commands/doctor')));
+    doctor({ fix: options.fix, json: options.json });
 });
 // Stream command - stream capture status and management
 const streamCmd = commander_1.program
@@ -365,8 +390,9 @@ streamCmd
     .option('-s, --session <id>', 'Session ID to check')
     .option('-w, --watch', 'Watch mode - refresh every second')
     .option('-j, --json', 'Output machine-readable JSON')
-    .action((options) => {
-    (0, stream_1.streamStatus)({
+    .action(async (options) => {
+    const { streamStatus } = await Promise.resolve().then(() => __importStar(require('./commands/stream')));
+    streamStatus({
         session: options.session,
         watch: options.watch,
         json: options.json
@@ -375,8 +401,9 @@ streamCmd
 streamCmd
     .command('list')
     .description('List all sessions with stream data')
-    .action(() => {
-    (0, stream_1.streamList)();
+    .action(async () => {
+    const { streamList } = await Promise.resolve().then(() => __importStar(require('./commands/stream')));
+    streamList();
 });
 // DEPRECATED: Hooks removed in hookless architecture migration
 // The `hooks` command prints a deprecation notice directing users to `ekkos run`.
@@ -393,17 +420,28 @@ commander_1.program
     console.log(chalk_1.default.gray('  the ekkOS proxy — no shell hooks required.'));
     console.log('');
 });
-// Usage command - track Claude Code token usage and costs (powered by ccusage)
-(0, index_1.registerUsageCommand)(commander_1.program);
-// Dashboard command - live TUI for monitoring session usage
+// Usage command — lightweight stub, heavy handler loaded lazily
+commander_1.program
+    .command('usage')
+    .description('Token usage and cost tracking (daily, weekly, monthly, session)')
+    .allowUnknownOption()
+    .action(async () => {
+    const { registerUsageCommand } = await Promise.resolve().then(() => __importStar(require('./commands/usage/index')));
+    const { Command } = await Promise.resolve().then(() => __importStar(require('commander')));
+    const usageProgram = new Command('ekkos');
+    registerUsageCommand(usageProgram);
+    usageProgram.parse(['node', 'ekkos', 'usage', ...process.argv.slice(3)]);
+});
+// Dashboard command — eager because `run --dashboard` spawns `ekkos dashboard` in tmux
 commander_1.program.addCommand(dashboard_1.dashboardCommand);
 // Sessions command - list active Claude Code sessions (swarm support)
 commander_1.program
     .command('sessions')
     .description('List active Claude Code sessions (for swarm/multi-session support)')
     .option('-j, --json', 'Output machine-readable JSON')
-    .action((options) => {
-    const sessions = (0, state_1.getActiveSessions)();
+    .action(async (options) => {
+    const { getActiveSessions } = await Promise.resolve().then(() => __importStar(require('./utils/state')));
+    const sessions = getActiveSessions();
     if (options.json) {
         console.log(JSON.stringify(sessions, null, 2));
         return;
@@ -443,7 +481,8 @@ commander_1.program
     console.log(chalk_1.default.gray('Running init with your options...'));
     console.log('');
     // Forward to init
-    await (0, init_1.init)({
+    const { init } = await Promise.resolve().then(() => __importStar(require('./commands/init')));
+    await init({
         ide: options.ide,
         key: options.key
     });
@@ -455,19 +494,19 @@ const swarmCmd = commander_1.program
 swarmCmd
     .command('status')
     .description('Show Q-table stats (states, visits, epsilon, top actions)')
-    .action(swarm_1.swarmStatus);
+    .action(async () => { const { swarmStatus } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmStatus(); });
 swarmCmd
     .command('reset')
     .description('Clear Q-table from Redis (routing reverts to static rules)')
-    .action(swarm_1.swarmReset);
+    .action(async () => { const { swarmReset } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmReset(); });
 swarmCmd
     .command('export')
     .description('Export Q-table to .swarm/q-learning-model.json')
-    .action(swarm_1.swarmExport);
+    .action(async () => { const { swarmExport } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmExport(); });
 swarmCmd
     .command('import')
     .description('Import Q-table from .swarm/q-learning-model.json into Redis')
-    .action(swarm_1.swarmImport);
+    .action(async () => { const { swarmImport } = await Promise.resolve().then(() => __importStar(require('./commands/swarm'))); swarmImport(); });
 swarmCmd
     .command('launch')
     .description('Launch parallel workers on a decomposed task (opens wizard if --task is omitted)')
@@ -478,13 +517,14 @@ swarmCmd
     .option('--no-queen', 'Skip launching the Python Queen coordinator')
     .option('--queen-strategy <strategy>', 'Queen strategy (adaptive-default, hierarchical-cascade, mesh-consensus)')
     .option('-v, --verbose', 'Show debug output')
-    .action((options) => {
-    // Auto-open wizard when --task is missing
+    .action(async (options) => {
     if (!options.task) {
-        (0, swarm_setup_1.swarmSetup)();
+        const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup')));
+        swarmSetup();
         return;
     }
-    (0, swarm_1.swarmLaunch)({
+    const { swarmLaunch } = await Promise.resolve().then(() => __importStar(require('./commands/swarm')));
+    swarmLaunch({
         workers: options.workers || 4,
         task: options.task,
         bypass: options.bypass !== false,
@@ -497,10 +537,83 @@ swarmCmd
 swarmCmd
     .command('setup')
     .description('Interactive TUI wizard for configuring and launching a swarm')
-    .action(() => {
-    (0, swarm_setup_1.swarmSetup)();
+    .action(async () => { const { swarmSetup } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-setup'))); swarmSetup(); });
+swarmCmd
+    .command('swarm-dashboard')
+    .description('Live swarm dashboard')
+    .allowUnknownOption()
+    .action(async () => {
+    const { swarmDashboardCommand } = await Promise.resolve().then(() => __importStar(require('./commands/swarm-dashboard')));
+    swarmDashboardCommand.parse(process.argv.slice(3));
 });
-swarmCmd.addCommand(swarm_dashboard_1.swarmDashboardCommand);
+// --- Remote & Agent Wrapper Helpers ---
+function runRemoteCommand(command, ...args) {
+    const isAgent = command === 'agent';
+    const pkgName = isAgent ? 'ekkos-agent' : 'ekkos-remote';
+    const binName = isAgent ? 'ekkos-agent.mjs' : 'ekkos-synk.mjs';
+    // Try resolving local monorepo first
+    let binPath = path.resolve(__dirname, '../../' + pkgName + '/bin/' + binName);
+    // If we are installed globally (dist folder structure), resolve relatively
+    if (!fs.existsSync(binPath)) {
+        try {
+            const globalPath = require.resolve('@ekkos/' + (isAgent ? 'agent' : 'remote') + '/package.json');
+            binPath = path.join(path.dirname(globalPath), 'bin', binName);
+        }
+        catch (e) {
+            // Fallback relative to current dist
+            binPath = path.resolve(__dirname, '../../' + pkgName + '/bin/' + binName);
+        }
+    }
+    const p = (0, child_process_1.spawn)('node', [binPath, ...args], {
+        stdio: 'inherit',
+        env: process.env
+    });
+    p.on('exit', (code) => {
+        process.exit(code || 0);
+    });
+}
+// Mobile Sync & Cloud (Synk) Commands
+commander_1.program
+    .command('auth')
+    .description('Manage authentication for Memory, Agents, and Mobile App')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'auth', ...process.argv.slice(3)));
+commander_1.program
+    .command('codex')
+    .description('Launch Codex (OpenAI) with mobile control')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'codex', ...process.argv.slice(3)));
+commander_1.program
+    .command('acp')
+    .description('Launch a generic ACP-compatible agent')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'acp', ...process.argv.slice(3)));
+commander_1.program
+    .command('daemon')
+    .description('Manage background mobile sync service (start, stop, status)')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'daemon', ...process.argv.slice(3)));
+commander_1.program
+    .command('connect')
+    .description('Securely store AI vendor API keys in the cloud')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'connect', ...process.argv.slice(3)));
+commander_1.program
+    .command('sandbox')
+    .description('Configure OS-level sandboxing for agent execution')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'sandbox', ...process.argv.slice(3)));
+commander_1.program
+    .command('notify')
+    .description('Send push notifications to your Synk mobile app')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('synk', 'notify', ...process.argv.slice(3)));
+// Headless Agents (Remote Control)
+commander_1.program
+    .command('agent')
+    .description('Manage remote headless agents (create, list, stop)')
+    .allowUnknownOption()
+    .action(() => runRemoteCommand('agent', ...process.argv.slice(3)));
 // Handle `-help` (single dash) — rewrite to `--help` for Commander compatibility
 const helpIdx = process.argv.indexOf('-help');
 if (helpIdx !== -1) {

package/dist/lib/usage-parser.js

@@ -91,8 +91,24 @@ function resolveSessionName(name) {
     if (fs.existsSync(activeSessionsPath)) {
         try {
             const sessions = JSON.parse(fs.readFileSync(activeSessionsPath, 'utf-8'));
-            // Find first entry with a valid UUID sessionId (skip "unknown" or empty)
-            const match = sessions.find(s => s.sessionName === name && s.sessionId && s.sessionId !== 'unknown' && s.sessionId.length > 8);
+            // Find first entry with a valid UUID sessionId (skip "unknown" or empty).
+            // Also skip entries whose PID is dead (stale from prior runs / restarts).
+            const match = sessions.find(s => {
+                if (s.sessionName !== name)
+                    return false;
+                if (!s.sessionId || s.sessionId === 'unknown' || s.sessionId.length <= 8)
+                    return false;
+                // Prune dead PIDs — prevents stale cross-binding after restart
+                if (s.pid > 1) {
+                    try {
+                        process.kill(s.pid, 0);
+                    }
+                    catch {
+                        return false;
+                    }
+                }
+                return true;
+            });
             if (match) {
                 return {
                     uuid: match.sessionId,

package/dist/local/index.d.ts

@@ -12,3 +12,7 @@ export { SyncEngine, createSyncEngine, } from './sync-engine';
 export type { SyncResult, } from './sync-engine';
 export { generateLocalEmbedding, cosineSimilarity, searchByEmbedding, isEmbeddingAvailable, } from './local-embeddings';
 export type { SimilarityResult, } from './local-embeddings';
+export { detectStack, } from './stack-detection';
+export type { StackInfo, } from './stack-detection';
+export { LANGUAGE_CONFIGS, BASE_KEY_FILES, BASE_EXCLUDED_DIRS, getKeyFilesForStack, getExcludedDirsForStack, getPromptHintsForStack, getSourceExtensionsForStack, getSystemBoundaryMarkersForStack, } from './language-config';
+export type { LanguageConfig, } from './language-config';

package/dist/local/index.js

@@ -6,7 +6,7 @@
  * Provides offline-capable memory, fallback logic, sync, and local embeddings.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEmbeddingAvailable = exports.searchByEmbedding = exports.cosineSimilarity = exports.generateLocalEmbedding = exports.createSyncEngine = exports.SyncEngine = exports.OFFLINE_CAPABLE_TOOLS = exports.isOfflineFallbackReady = exports.callWithFallback = exports.localStore = exports.LocalMemoryStore = void 0;
+exports.getSystemBoundaryMarkersForStack = exports.getSourceExtensionsForStack = exports.getPromptHintsForStack = exports.getExcludedDirsForStack = exports.getKeyFilesForStack = exports.BASE_EXCLUDED_DIRS = exports.BASE_KEY_FILES = exports.LANGUAGE_CONFIGS = exports.detectStack = exports.isEmbeddingAvailable = exports.searchByEmbedding = exports.cosineSimilarity = exports.generateLocalEmbedding = exports.createSyncEngine = exports.SyncEngine = exports.OFFLINE_CAPABLE_TOOLS = exports.isOfflineFallbackReady = exports.callWithFallback = exports.localStore = exports.LocalMemoryStore = void 0;
 // SQLite memory store (Phase 6A)
 var sqlite_store_1 = require("./sqlite-store");
 Object.defineProperty(exports, "LocalMemoryStore", { enumerable: true, get: function () { return sqlite_store_1.LocalMemoryStore; } });
@@ -26,3 +26,16 @@ Object.defineProperty(exports, "generateLocalEmbedding", { enumerable: true, get
 Object.defineProperty(exports, "cosineSimilarity", { enumerable: true, get: function () { return local_embeddings_1.cosineSimilarity; } });
 Object.defineProperty(exports, "searchByEmbedding", { enumerable: true, get: function () { return local_embeddings_1.searchByEmbedding; } });
 Object.defineProperty(exports, "isEmbeddingAvailable", { enumerable: true, get: function () { return local_embeddings_1.isEmbeddingAvailable; } });
+// Stack detection (Living Docs V4 — Phase 4)
+var stack_detection_1 = require("./stack-detection");
+Object.defineProperty(exports, "detectStack", { enumerable: true, get: function () { return stack_detection_1.detectStack; } });
+// Language configuration (Living Docs V4 — Phase 4)
+var language_config_1 = require("./language-config");
+Object.defineProperty(exports, "LANGUAGE_CONFIGS", { enumerable: true, get: function () { return language_config_1.LANGUAGE_CONFIGS; } });
+Object.defineProperty(exports, "BASE_KEY_FILES", { enumerable: true, get: function () { return language_config_1.BASE_KEY_FILES; } });
+Object.defineProperty(exports, "BASE_EXCLUDED_DIRS", { enumerable: true, get: function () { return language_config_1.BASE_EXCLUDED_DIRS; } });
+Object.defineProperty(exports, "getKeyFilesForStack", { enumerable: true, get: function () { return language_config_1.getKeyFilesForStack; } });
+Object.defineProperty(exports, "getExcludedDirsForStack", { enumerable: true, get: function () { return language_config_1.getExcludedDirsForStack; } });
+Object.defineProperty(exports, "getPromptHintsForStack", { enumerable: true, get: function () { return language_config_1.getPromptHintsForStack; } });
+Object.defineProperty(exports, "getSourceExtensionsForStack", { enumerable: true, get: function () { return language_config_1.getSourceExtensionsForStack; } });
+Object.defineProperty(exports, "getSystemBoundaryMarkersForStack", { enumerable: true, get: function () { return language_config_1.getSystemBoundaryMarkersForStack; } });

package/dist/local/language-config.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Language Configuration — data-driven config for each language ecosystem
+ *
+ * Pure functions with zero dependencies. Provides key files, excluded dirs,
+ * source extensions, system boundary markers, and Gemini prompt hints
+ * for each supported language.
+ *
+ * Living Docs V4 — Phase 4: Language-Adapted Discovery
+ */
+import type { StackInfo } from './stack-detection.js';
+export interface LanguageConfig {
+    /** Key file names to prioritize reading (for both CLI and server compiler) */
+    keyFiles: string[];
+    /** Directories to exclude from scanning */
+    excludedDirs: string[];
+    /** File extensions that count as source files */
+    sourceExtensions: string[];
+    /** Files that mark a system boundary */
+    systemBoundaryMarkers: string[];
+    /** Prompt hints for Gemini (what to ask about) */
+    promptHints: {
+        architecture: string[];
+        buildSystem: string[];
+        deployTarget: string[];
+        testFramework: string[];
+        conventions: string[];
+    };
+}
+export declare const BASE_KEY_FILES: string[];
+export declare const BASE_EXCLUDED_DIRS: string[];
+export declare const LANGUAGE_CONFIGS: Record<string, LanguageConfig>;
+/**
+ * Get the merged key files list for a detected stack.
+ * Returns BASE_KEY_FILES + language-specific files (deduplicated).
+ */
+export declare function getKeyFilesForStack(stack: StackInfo): string[];
+/**
+ * Get the merged excluded dirs for a detected stack.
+ * Returns BASE_EXCLUDED_DIRS + language-specific dirs.
+ */
+export declare function getExcludedDirsForStack(stack: StackInfo): Set<string>;
+/**
+ * Get prompt hints for the Gemini compiler.
+ * Falls back to TypeScript hints for unknown languages.
+ */
+export declare function getPromptHintsForStack(stack: StackInfo): LanguageConfig['promptHints'];
+/**
+ * Get the source extensions for a detected stack.
+ */
+export declare function getSourceExtensionsForStack(stack: StackInfo): Set<string>;
+/**
+ * Get system boundary markers for a detected stack.
+ * These are files that indicate a "system root" directory.
+ */
+export declare function getSystemBoundaryMarkersForStack(stack: StackInfo): string[];