echelon-dev 1.0.0

package/lib/echelon-local-agent.js

@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+
+/**
+ * Echelon Local Agent - Zero Dependencies
+ *
+ * Runs on the user's local machine. Receives pair programming commands
+ * from the backend via HTTP or WebSocket relay (for mobile/remote trigger).
+ *
+ * Port: 3457 (different from knoxis at 3456)
+ * Config: ~/.echelon/
+ *
+ * ZERO EXTERNAL DEPENDENCIES - uses only Node.js built-in modules
+ */
+
+const http = require('http');
+const https = require('https');
+const { exec, spawn, spawnSync } = require('child_process');
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+const url = require('url');
+
+const DEFAULT_PORT = parseInt(process.env.ECHELON_AGENT_PORT || '3457', 10);
+const ECHELON_DIR = path.join(os.homedir(), '.echelon');
+const CERT_DIR = process.env.ECHELON_CERT_DIR || path.join(ECHELON_DIR, 'certs');
+const CERT_FILE = path.join(CERT_DIR, 'localhost.pem');
+const KEY_FILE = path.join(CERT_DIR, 'localhost-key.pem');
+const WORKSPACES_FILE = path.join(ECHELON_DIR, 'workspaces.json');
+
+const TRUSTED_ORIGINS = [
+  'https://qig.ai', 'https://www.qig.ai', 'https://app.qig.ai',
+  'http://localhost:3000', 'http://localhost:5173',
+  'http://127.0.0.1:3000', 'http://127.0.0.1:5173'
+];
+const ALLOWED_ORIGINS = (process.env.ECHELON_ALLOWED_ORIGINS || '')
+  .split(',').map(o => o.trim()).filter(Boolean);
+const ALL_ALLOWED_ORIGINS = [...new Set([...TRUSTED_ORIGINS, ...ALLOWED_ORIGINS])];
+
+const serverMeta = { secure: false, port: DEFAULT_PORT };
+const HEADLESS_TIMEOUT_MS = parseInt(process.env.ECHELON_HEADLESS_TIMEOUT_MS || '1200000', 10);
+const HEADLESS_MAX_OUTPUT = parseInt(process.env.ECHELON_HEADLESS_MAX_OUTPUT_CHARS || '50000', 10);
+
+// ===== UTILITY =====
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function safeBasename(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9._-]+/g, '_').slice(0, 80) || 'session';
+}
+
+function commandExists(cmd) {
+  const detector = os.platform() === 'win32' ? 'where' : 'which';
+  return spawnSync(detector, [cmd], { stdio: 'ignore' }).status === 0;
+}
+
+function buildShellCommand(command) {
+  if (os.platform() === 'win32') return { cmd: 'cmd.exe', args: ['/c', command] };
+  return { cmd: 'bash', args: ['-lc', command] };
+}
+
+function escapeForShell(value) {
+  return String(value || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$').replace(/`/g, '\\`').replace(/!/g, '\\!');
+}
+
+// ===== CERT GENERATION =====
+
+function generateSelfSignedCert() {
+  ensureDir(CERT_DIR);
+  const result = spawnSync('openssl', [
+    'req', '-x509', '-newkey', 'rsa:2048',
+    '-keyout', KEY_FILE, '-out', CERT_FILE,
+    '-days', '365', '-nodes', '-subj', '/CN=localhost',
+    '-addext', 'subjectAltName=DNS:localhost,IP:127.0.0.1'
+  ], { stdio: 'pipe' });
+  return result.status === 0;
+}
+
+// ===== CORS =====
+
+function getCorsHeaders(origin) {
+  const headers = {
+    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS, PATCH',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With, Accept, Origin',
+    'Access-Control-Max-Age': '86400'
+  };
+  if (origin) {
+    const isAllowed = ALL_ALLOWED_ORIGINS.some(a => a === '*' || origin === a || origin.endsWith(a.replace('https://', '.')));
+    if (isAllowed) {
+      headers['Access-Control-Allow-Origin'] = origin;
+      headers['Access-Control-Allow-Credentials'] = 'true';
+    } else {
+      headers['Access-Control-Allow-Origin'] = '*';
+    }
+  } else {
+    headers['Access-Control-Allow-Origin'] = '*';
+  }
+  return headers;
+}
+
+// ===== WORKSPACE MANAGEMENT =====
+
+function loadWorkspaces() {
+  ensureDir(ECHELON_DIR);
+  try {
+    if (fs.existsSync(WORKSPACES_FILE)) return JSON.parse(fs.readFileSync(WORKSPACES_FILE, 'utf8'));
+  } catch (e) {}
+  return {};
+}
+
+function saveWorkspaces(ws) {
+  ensureDir(ECHELON_DIR);
+  fs.writeFileSync(WORKSPACES_FILE, JSON.stringify(ws, null, 2));
+}
+
+function resolveWorkspacePath(nameOrPath) {
+  if (fs.existsSync(nameOrPath)) return path.resolve(nameOrPath);
+  const workspaces = loadWorkspaces();
+  if (workspaces[nameOrPath]) return workspaces[nameOrPath];
+  const lower = nameOrPath.toLowerCase();
+  for (const [name, wsPath] of Object.entries(workspaces)) {
+    if (name.toLowerCase().includes(lower)) return wsPath;
+  }
+  // Also check knoxis registry as fallback
+  const knoxisFile = path.join(os.homedir(), '.knoxis', 'workspaces.json');
+  if (fs.existsSync(knoxisFile)) {
+    try {
+      const kws = JSON.parse(fs.readFileSync(knoxisFile, 'utf8'));
+      if (kws[nameOrPath]) return kws[nameOrPath];
+      for (const [name, wsPath] of Object.entries(kws)) {
+        if (name.toLowerCase().includes(lower)) return wsPath;
+      }
+    } catch (e) {}
+  }
+  return null;
+}
+
+function discoverProjects() {
+  const discovered = {};
+  const searchDirs = ['Projects', 'IdeaProjects', 'Developer', 'Code', 'dev', 'src', 'work', 'Desktop']
+    .map(d => path.join(os.homedir(), d));
+
+  for (const dir of searchDirs) {
+    if (!fs.existsSync(dir)) continue;
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        const p = path.join(dir, entry.name);
+        const hasProject = ['.git', 'package.json', 'pom.xml', 'src', 'Cargo.toml', 'go.mod']
+          .some(f => fs.existsSync(path.join(p, f)));
+        if (hasProject) discovered[entry.name] = p;
+      }
+    } catch (e) {}
+  }
+  return discovered;
+}
+
+// ===== HEADLESS EXECUTION =====
+
+function runHeadlessProcess({ workspace, command, prompt, sessionLabel }) {
+  return new Promise((resolve) => {
+    const startedAt = Date.now();
+    const workspaceDir = workspace || process.cwd();
+    const logDir = path.join(workspaceDir, '.echelon', 'headless');
+    ensureDir(logDir);
+    const logFile = path.join(logDir, `${Date.now()}-${safeBasename(sessionLabel)}.log`);
+    const logStream = fs.createWriteStream(logFile, { encoding: 'utf8' });
+
+    const trimmedCommand = String(command || '').trim();
+    const hasPrompt = typeof prompt === 'string' && prompt.trim().length > 0;
+    const looksLikePairProgram = trimmedCommand.toLowerCase().includes('echelon-pair-program') || trimmedCommand.toLowerCase().includes('knoxis-pair-program');
+
+    let proc;
+    let stdout = '';
+    let stderr = '';
+    let truncated = false;
+    let timedOut = false;
+
+    const capture = (chunk, isStdErr) => {
+      const text = chunk.toString();
+      logStream.write(text);
+      if (isStdErr) { stderr += text; return; }
+      if (stdout.length < HEADLESS_MAX_OUTPUT) { stdout += text; }
+      else { truncated = true; }
+    };
+
+    const finish = (exitCode) => {
+      try { logStream.end(); } catch (e) {}
+      resolve({
+        success: exitCode === 0 && !timedOut, exitCode, timedOut, truncated,
+        durationMs: Date.now() - startedAt, workspace: workspaceDir, logFile,
+        stdout: stdout.trim(), stderr: stderr.trim()
+      });
+    };
+
+    const timeout = setTimeout(() => { timedOut = true; try { proc.kill('SIGKILL'); } catch (e) {} }, HEADLESS_TIMEOUT_MS);
+
+    if (!looksLikePairProgram && hasPrompt && (!trimmedCommand || trimmedCommand.toLowerCase().startsWith('claude'))) {
+      if (!commandExists('claude')) { clearTimeout(timeout); finish(127); return; }
+      proc = spawn('claude', ['--dangerously-skip-permissions'], { cwd: workspaceDir, env: process.env, stdio: ['pipe', 'pipe', 'pipe'] });
+      proc.stdout.on('data', chunk => capture(chunk, false));
+      proc.stderr.on('data', chunk => capture(chunk, true));
+      proc.on('close', code => { clearTimeout(timeout); finish(code == null ? 1 : code); });
+      proc.stdin.write(prompt);
+      proc.stdin.end();
+      return;
+    }
+
+    if (trimmedCommand) {
+      const spec = buildShellCommand(trimmedCommand);
+      proc = spawn(spec.cmd, spec.args, { cwd: workspaceDir, env: process.env });
+      proc.stdout.on('data', chunk => capture(chunk, false));
+      proc.stderr.on('data', chunk => capture(chunk, true));
+      proc.on('close', code => { clearTimeout(timeout); finish(code == null ? 1 : code); });
+      return;
+    }
+
+    clearTimeout(timeout);
+    finish(1);
+  });
+}
+
+// ===== TERMINAL OPENING =====
+
+function openMacTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    ensureDir(workspaceDir);
+    const escapedDir = workspaceDir.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    let finalCommand = command;
+    if (command.includes('claude') && !command.includes('--dangerously-skip-permissions')) {
+      finalCommand = command.replace(/^claude\s+/, 'claude --dangerously-skip-permissions ');
+    }
+    const escapedCommand = finalCommand.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    const appleScript = `tell application "Terminal"\n    activate\n    set newTab to do script "cd \\"${escapedDir}\\""\n    delay 0.5\n    do script "${escapedCommand}" in newTab\nend tell`;
+    const tempScript = `/tmp/echelon-terminal-${Date.now()}.scpt`;
+    fs.writeFileSync(tempScript, appleScript);
+    exec(`osascript "${tempScript}"`, (error) => {
+      try { fs.unlinkSync(tempScript); } catch (e) {}
+      if (error) reject(error); else resolve();
+    });
+  });
+}
+
+function openWindowsTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    ensureDir(workspaceDir);
+    exec(`start cmd /K "cd /d "${workspaceDir}" && ${command}"`, (error) => {
+      if (error) reject(error); else resolve();
+    });
+  });
+}
+
+function openLinuxTerminal(workspaceDir, command) {
+  return new Promise((resolve, reject) => {
+    ensureDir(workspaceDir);
+    exec(`gnome-terminal --working-directory="${workspaceDir}" -- bash -c "${command}; exec bash"`, (error) => {
+      if (error) {
+        exec(`xterm -e "cd '${workspaceDir}' && ${command}; bash"`, (e2) => {
+          if (e2) reject(e2); else resolve();
+        });
+      } else resolve();
+    });
+  });
+}
+
+function openTerminal(workspaceDir, command) {
+  const platform = os.platform();
+  if (platform === 'darwin') return openMacTerminal(workspaceDir, command);
+  if (platform === 'win32') return openWindowsTerminal(workspaceDir, command);
+  return openLinuxTerminal(workspaceDir, command);
+}
+
+// ===== HTTP HELPERS =====
+
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    let body = '';
+    req.on('data', chunk => { body += chunk.toString(); });
+    req.on('end', () => { try { resolve(body ? JSON.parse(body) : {}); } catch (e) { reject(e); } });
+    req.on('error', reject);
+  });
+}
+
+function sendJSON(res, statusCode, data, origin) {
+  res.writeHead(statusCode, { 'Content-Type': 'application/json', ...getCorsHeaders(origin) });
+  res.end(JSON.stringify(data));
+}
+
+// ===== REQUEST HANDLER =====
+
+async function handleRequest(req, res) {
+  const parsedUrl = url.parse(req.url, true);
+  const pathname = parsedUrl.pathname;
+  const method = req.method;
+  const origin = req.headers.origin || '';
+
+  if (method === 'OPTIONS') {
+    res.writeHead(204, getCorsHeaders(origin));
+    return res.end();
+  }
+
+  // Health check
+  if (pathname === '/health' && method === 'GET') {
+    return sendJSON(res, 200, {
+      status: 'healthy', agent: 'echelon-local-agent', version: '1.0.0',
+      platform: os.platform(), secure: serverMeta.secure, port: serverMeta.port,
+      dependencies: 'none', team: ['knoxis', 'solan', 'astrahelm']
+    }, origin);
+  }
+
+  // Execute terminal command (main endpoint for remote trigger)
+  if (pathname === '/terminal/execute' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      const { workspaceDirectory, workingDirectory, command, prompt, headless, sessionId } = body;
+      const workspace = workspaceDirectory || workingDirectory;
+
+      console.log(`[execute] workspace=${workspace} headless=${!!headless}`);
+      if (command) console.log(`[execute] command=${command.substring(0, 100)}`);
+
+      if (headless) {
+        const result = await runHeadlessProcess({ workspace, command, prompt, sessionLabel: sessionId || 'remote' });
+        return sendJSON(res, result.success ? 200 : 500, result, origin);
+      }
+
+      await openTerminal(workspace, command);
+      return sendJSON(res, 200, { success: true, message: 'Terminal opened', platform: os.platform() }, origin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, origin);
+    }
+  }
+
+  // Start multi-agent pair programming session
+  if (pathname === '/pair/start' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      const { workspace, task, agents, provider, headless, sessionId, contextFile } = body;
+
+      if (!task) return sendJSON(res, 400, { success: false, error: 'Task description required' }, origin);
+
+      let workspaceDir = process.cwd();
+      if (workspace) {
+        const wsPath = resolveWorkspacePath(workspace);
+        if (wsPath) workspaceDir = wsPath;
+        else return sendJSON(res, 404, { success: false, error: `Workspace not found: ${workspace}` }, origin);
+      }
+
+      // Build the echelon-pair-program command
+      const scriptPath = path.join(__dirname, 'echelon-pair-program.js');
+      const promptB64 = Buffer.from(task).toString('base64');
+      let cmd = `node "${scriptPath}" --workspace "${workspaceDir}" --prompt-base64 "${promptB64}"`;
+      if (agents) cmd += ` --agents "${agents}"`;
+      if (provider) cmd += ` --ai-provider "${provider}"`;
+      if (contextFile) cmd += ` --context-file "${contextFile}"`;
+
+      if (headless) {
+        const result = await runHeadlessProcess({ workspace: workspaceDir, command: cmd, sessionLabel: sessionId || 'pair' });
+        return sendJSON(res, result.success ? 200 : 500, result, origin);
+      }
+
+      await openTerminal(workspaceDir, cmd);
+      return sendJSON(res, 200, {
+        success: true, message: 'Echelon dev team session started',
+        workspace: workspaceDir, task, agents: agents || 'knoxis,solan,astrahelm'
+      }, origin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, origin);
+    }
+  }
+
+  // Workspace endpoints
+  if (pathname === '/workspace/list' && method === 'GET') {
+    const ws = loadWorkspaces();
+    const list = Object.entries(ws).map(([name, p]) => ({ name, path: p, exists: fs.existsSync(p) }));
+    return sendJSON(res, 200, { success: true, workspaces: list }, origin);
+  }
+
+  if (pathname === '/workspace/get' && method === 'GET') {
+    const name = parsedUrl.query.name;
+    if (!name) return sendJSON(res, 400, { success: false, error: 'Name required' }, origin);
+    const wsPath = resolveWorkspacePath(name);
+    if (wsPath) return sendJSON(res, 200, { success: true, name, path: wsPath }, origin);
+    return sendJSON(res, 404, { success: false, error: `Not found: ${name}` }, origin);
+  }
+
+  if (pathname === '/workspace/save' && method === 'POST') {
+    try {
+      const body = await parseBody(req);
+      if (!body.name) return sendJSON(res, 400, { success: false, error: 'Name required' }, origin);
+      const resolved = path.resolve(body.path || process.cwd());
+      if (!fs.existsSync(resolved)) return sendJSON(res, 400, { success: false, error: `Path does not exist: ${resolved}` }, origin);
+      const ws = loadWorkspaces();
+      ws[body.name] = resolved;
+      saveWorkspaces(ws);
+      return sendJSON(res, 200, { success: true, name: body.name, path: resolved }, origin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, origin);
+    }
+  }
+
+  if (pathname === '/workspace/discover' && method === 'POST') {
+    const discovered = discoverProjects();
+    const ws = loadWorkspaces();
+    let added = 0;
+    for (const [name, p] of Object.entries(discovered)) {
+      if (!ws[name]) { ws[name] = p; added++; }
+    }
+    saveWorkspaces(ws);
+    return sendJSON(res, 200, {
+      success: true, discovered: Object.keys(discovered).length, added,
+      workspaces: Object.entries(ws).map(([name, p]) => ({ name, path: p }))
+    }, origin);
+  }
+
+  // Sessions endpoints
+  if (pathname === '/sessions/list' && method === 'GET') {
+    try {
+      const { listSessions } = require('./session-recorder');
+      const limit = parseInt(parsedUrl.query.limit || '20');
+      return sendJSON(res, 200, { success: true, sessions: listSessions(limit) }, origin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, origin);
+    }
+  }
+
+  if (pathname === '/sessions/get' && method === 'GET') {
+    try {
+      const { loadSession } = require('./session-recorder');
+      const id = parsedUrl.query.id;
+      if (!id) return sendJSON(res, 400, { success: false, error: 'Session ID required' }, origin);
+      const session = loadSession(id);
+      if (!session) return sendJSON(res, 404, { success: false, error: 'Session not found' }, origin);
+      return sendJSON(res, 200, { success: true, session }, origin);
+    } catch (error) {
+      return sendJSON(res, 500, { success: false, error: error.message }, origin);
+    }
+  }
+
+  sendJSON(res, 404, { error: 'Not found' }, origin);
+}
+
+// ===== WEBSOCKET RELAY =====
+// Connects to backend so your phone/webapp can trigger terminal actions on this machine
+
+// Read config files as fallback for env vars (needed when launched via LaunchAgent)
+function loadConfigFallback() {
+  const files = [
+    path.join(os.homedir(), '.echelon', 'config.json'),
+    path.join(os.homedir(), '.knoxis', 'config.json')
+  ];
+  for (const f of files) {
+    try { if (fs.existsSync(f)) return JSON.parse(fs.readFileSync(f, 'utf8')); } catch (e) {}
+  }
+  return {};
+}
+const _config = loadConfigFallback();
+
+const BACKEND_WS_URL = process.env.ECHELON_BACKEND_WS_URL || process.env.KNOXIS_BACKEND_WS_URL || _config.backendWsUrl || null;
+const RELAY_USER_ID = process.env.ECHELON_USER_ID || process.env.KNOXIS_USER_ID || _config.userId || null;
+const RECONNECT_MS = parseInt(process.env.ECHELON_RECONNECT_MS || '2000', 10);
+
+let relaySocket = null;
+let reconnectTimer = null;
+
+function connectRelay() {
+  if (!BACKEND_WS_URL || !RELAY_USER_ID) return;
+
+  const wsUrl = `${BACKEND_WS_URL}/ws/echelon-terminal?userId=${encodeURIComponent(RELAY_USER_ID)}`;
+  console.log(`[relay] Connecting to: ${wsUrl}`);
+
+  let WebSocketImpl;
+  try {
+    WebSocketImpl = globalThis.WebSocket || require('ws');
+  } catch (e) {
+    // Fallback: try knoxis terminal endpoint
+    try { WebSocketImpl = require('ws'); } catch (e2) {
+      console.warn('[relay] WebSocket requires Node 22+ or "ws" package. Relay disabled.');
+      return;
+    }
+  }
+
+  try { relaySocket = new WebSocketImpl(wsUrl); } catch (e) {
+    console.warn('[relay] Connection failed:', e.message);
+    scheduleReconnect();
+    return;
+  }
+
+  relaySocket.onopen = () => {
+    console.log('[relay] Connected to backend');
+    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+  };
+
+  relaySocket.onmessage = async (event) => {
+    try {
+      const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());
+
+      if (msg.type === 'execute_command') {
+        console.log(`[relay] Command received: ${msg.requestId}`);
+        const workspace = msg.workingDir || process.cwd();
+
+        let result;
+        try {
+          if (msg.headless) {
+            result = await runHeadlessProcess({ workspace, command: msg.command, prompt: msg.prompt, sessionLabel: msg.requestId || 'relay' });
+          } else {
+            await openTerminal(workspace, msg.command);
+            result = { success: true, message: 'Terminal opened via relay' };
+          }
+        } catch (err) {
+          result = { success: false, error: err.message };
+        }
+
+        if (relaySocket && relaySocket.readyState === 1) {
+          relaySocket.send(JSON.stringify({ type: 'command_result', requestId: msg.requestId, ...result, timestamp: Date.now() }));
+        }
+      } else if (msg.type === 'connected') {
+        console.log(`[relay] Backend says: ${msg.message}`);
+      }
+    } catch (e) {
+      console.error('[relay] Error:', e.message);
+    }
+  };
+
+  relaySocket.onclose = (event) => {
+    const code = event && event.code ? event.code : 'unknown';
+    console.log(`[relay] Disconnected (code: ${code})`);
+    relaySocket = null;
+    if (code === 1006 || code === 1001) {
+      console.log('[relay] Unexpected close — reconnecting immediately...');
+      setTimeout(() => connectRelay(), 500);
+    } else {
+      scheduleReconnect();
+    }
+  };
+
+  relaySocket.onerror = (err) => {
+    console.error('[relay] Error:', err.message || 'connection failed');
+  };
+}
+
+function scheduleReconnect() {
+  if (reconnectTimer || !BACKEND_WS_URL || !RELAY_USER_ID) return;
+  reconnectTimer = setTimeout(() => { reconnectTimer = null; connectRelay(); }, RECONNECT_MS);
+}
+
+function startHeartbeat() {
+  if (!BACKEND_WS_URL || !RELAY_USER_ID) return;
+  setInterval(() => {
+    if (relaySocket && relaySocket.readyState === 1) {
+      try { relaySocket.send(JSON.stringify({ type: 'heartbeat', timestamp: Date.now() })); } catch (e) {}
+    }
+  }, 30000);
+}
+
+// ===== LAUNCH AGENT (macOS auto-start) =====
+
+function ensureLaunchAgent() {
+  if (process.platform !== 'darwin') return;
+  if (process.env.ECHELON_SKIP_LAUNCH_AGENT === '1') return;
+
+  try {
+    const agentsDir = path.join(os.homedir(), 'Library', 'LaunchAgents');
+    ensureDir(agentsDir);
+    const plistPath = path.join(agentsDir, 'com.echelon.dev.plist');
+    const logPath = path.join(os.homedir(), 'Library', 'Logs', 'EchelonDev.log');
+
+    const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>com.echelon.dev</string>
+    <key>ProgramArguments</key>
+    <array>
+      <string>${process.execPath}</string>
+      <string>${__filename}</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>${logPath}</string>
+    <key>StandardErrorPath</key>
+    <string>${logPath}</string>
+  </dict>
+</plist>`;
+
+    let needsWrite = true;
+    if (fs.existsSync(plistPath)) {
+      if (fs.readFileSync(plistPath, 'utf8') === plist) needsWrite = false;
+    }
+
+    if (needsWrite) {
+      fs.writeFileSync(plistPath, plist, 'utf8');
+      spawnSync('launchctl', ['unload', plistPath]);
+      const load = spawnSync('launchctl', ['load', '-w', plistPath]);
+      if (load.status === 0) console.log('[startup] Installed launch agent for auto-start');
+    }
+  } catch (err) {
+    console.warn('[startup] Could not configure auto-start:', err.message);
+  }
+}
+
+// ===== SERVER CREATION =====
+
+function createServer() {
+  // Try existing certs
+  try {
+    if (fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+      serverMeta.secure = true;
+      return https.createServer({ key: fs.readFileSync(KEY_FILE), cert: fs.readFileSync(CERT_FILE) }, handleRequest);
+    }
+  } catch (err) {}
+
+  // Try generating certs
+  if (generateSelfSignedCert() && fs.existsSync(KEY_FILE) && fs.existsSync(CERT_FILE)) {
+    try {
+      serverMeta.secure = true;
+      return https.createServer({ key: fs.readFileSync(KEY_FILE), cert: fs.readFileSync(CERT_FILE) }, handleRequest);
+    } catch (err) {}
+  }
+
+  serverMeta.secure = false;
+  console.warn('[warn] Running in HTTP mode - HTTPS frontends may have CORS issues');
+  return http.createServer(handleRequest);
+}
+
+// ===== GRACEFUL SHUTDOWN =====
+
+process.on('SIGINT', () => {
+  console.log('\nShutting down Echelon Local Agent...');
+  if (relaySocket) try { relaySocket.close(); } catch (e) {}
+  process.exit(0);
+});
+process.on('SIGTERM', () => process.exit(0));
+
+// ===== START =====
+
+ensureLaunchAgent();
+const server = createServer();
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.log(`\nEchelon Local Agent is already running on port ${serverMeta.port}.`);
+    console.log('No action needed — your existing agent is handling requests.\n');
+    process.exit(0);
+    return;
+  }
+  console.error('Server error:', err);
+  process.exit(1);
+});
+
+connectRelay();
+startHeartbeat();
+
+server.listen(serverMeta.port, () => {
+  const scheme = serverMeta.secure ? 'https' : 'http';
+  console.log('');
+  console.log('==============================================');
+  console.log('  Echelon Local Agent v1.0.0');
+  console.log('==============================================');
+  console.log(`  Mode:      ${serverMeta.secure ? 'HTTPS' : 'HTTP'}`);
+  console.log(`  Listening: ${scheme}://localhost:${serverMeta.port}`);
+  console.log(`  Team:      Knoxis, Solan, Astrahelm`);
+  console.log('');
+  console.log('  Endpoints:');
+  console.log('  POST /terminal/execute    - Execute command (remote trigger)');
+  console.log('  POST /pair/start          - Start multi-agent session');
+  console.log('  GET  /workspace/list      - List workspaces');
+  console.log('  POST /workspace/discover  - Auto-discover projects');
+  console.log('  GET  /sessions/list       - List recorded sessions');
+  console.log('  GET  /health              - Health check');
+  console.log('');
+  if (BACKEND_WS_URL && RELAY_USER_ID) {
+    console.log(`  Relay: ${BACKEND_WS_URL} (user: ${RELAY_USER_ID})`);
+  } else {
+    console.log('  Relay: Not configured (set ECHELON_BACKEND_WS_URL + ECHELON_USER_ID)');
+  }
+  console.log('');
+});