neoagent 2.3.1-beta.11 → 2.3.1-beta.111

package/lib/manager.js

@@ -18,6 +18,7 @@ const {
   LOG_DIR,
   ENV_FILE,
   PID_FILE,
+  getDefaultVmBaseImageUrl,
   ensureRuntimeDirs,
   migrateLegacyRuntime
 } = require('../runtime/paths');
@@ -118,28 +119,45 @@ function readEnvFileRaw() {
   return fs.readFileSync(ENV_FILE, 'utf8');
 }
 
+function sanitizeEnvKey(key) {
+  return String(key).replace(/[\r\n]/g, '');
+}
+
+function sanitizeEnvValue(value) {
+  return String(value).replace(/[\r\n]/g, '');
+}
+
+function validateEnvKey(key) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
+    throw new Error(`Invalid env key "${key}". Keys must be uppercase letters, digits, and underscores (e.g. PORT, ANTHROPIC_API_KEY).`);
+  }
+}
+
 function upsertEnvValue(key, value) {
+  const safeKey = sanitizeEnvKey(key);
+  const safeValue = sanitizeEnvValue(value);
   const raw = readEnvFileRaw();
   const lines = raw ? raw.split('\n') : [];
   let replaced = false;
 
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i].startsWith(`${key}=`)) {
-      lines[i] = `${key}=${value}`;
+    if (lines[i].startsWith(`${safeKey}=`)) {
+      lines[i] = `${safeKey}=${safeValue}`;
       replaced = true;
       break;
     }
   }
 
-  if (!replaced) lines.push(`${key}=${value}`);
+  if (!replaced) lines.push(`${safeKey}=${safeValue}`);
   const output = lines.filter((_, idx, arr) => idx !== arr.length - 1 || arr[idx] !== '').join('\n') + '\n';
   fs.writeFileSync(ENV_FILE, output, { mode: 0o600 });
 }
 
 function removeEnvValue(key) {
+  const safeKey = sanitizeEnvKey(key);
   const raw = readEnvFileRaw();
   if (!raw) return false;
-  const lines = raw.split('\n').filter((line) => !line.startsWith(`${key}=`));
+  const lines = raw.split('\n').filter((line) => !line.startsWith(`${safeKey}=`));
   const output = lines.filter((_, idx, arr) => idx !== arr.length - 1 || arr[idx] !== '').join('\n') + '\n';
   fs.writeFileSync(ENV_FILE, output, { mode: 0o600 });
   return true;
@@ -287,6 +305,38 @@ function ensureLogDir() {
   ensureRuntimeDirs();
 }
 
+function pruneOldRuntimeBackups(backupsDir, keepLatest = 3) {
+  if (!fs.existsSync(backupsDir) || keepLatest < 0) return;
+
+  const backupDirs = fs
+    .readdirSync(backupsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('pre-update-'))
+    .map((entry) => {
+      const fullPath = path.join(backupsDir, entry.name);
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(fullPath).mtimeMs;
+      } catch {
+        // Skip entries that disappear or cannot be statted.
+        return null;
+      }
+      return { name: entry.name, fullPath, mtimeMs };
+    })
+    .filter(Boolean)
+    .sort((a, b) => {
+      if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+      return b.name.localeCompare(a.name);
+    });
+
+  for (const backup of backupDirs.slice(keepLatest)) {
+    try {
+      fs.rmSync(backup.fullPath, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+  }
+}
+
 function backupRuntimeData() {
   const backupsDir = path.join(RUNTIME_HOME, 'backups');
   fs.mkdirSync(backupsDir, { recursive: true });
@@ -296,6 +346,7 @@ function backupRuntimeData() {
 
   if (fs.existsSync(ENV_FILE)) fs.copyFileSync(ENV_FILE, path.join(target, '.env'));
   if (fs.existsSync(DATA_DIR)) fs.cpSync(DATA_DIR, path.join(target, 'data'), { recursive: true, force: false, errorOnExist: false });
+  pruneOldRuntimeBackups(backupsDir, 3);
 }
 
 function killByPort(port) {
@@ -347,15 +398,19 @@ function listNeoAgentServerProcesses() {
       };
     })
     .filter(Boolean)
-    .filter((entry) =>
-      entry.pid !== process.pid &&
-      /(^|\s)node(\s|$)/.test(entry.command) &&
-      (
-        appIndexPattern.test(String(entry.command || '').replace(/\\/g, '/')) ||
-        genericNeoAgentPattern.test(String(entry.command || '').replace(/\\/g, '/')) ||
-        repoNamePattern.test(String(entry.command || ''))
-      )
-    );
+    .filter((entry) => {
+      if (entry.pid === process.pid) return false;
+      const cmd = String(entry.command || '');
+      const cmdNormalized = cmd.replace(/\\/g, '/');
+      const executablePart = cmd.split(/\s+/)[0] || '';
+      const executableBase = path.basename(executablePart);
+      const isNode = /^node\d*$/.test(executableBase) || /(^|\s)node\d*(\s|$)/.test(cmd);
+      return isNode && (
+        appIndexPattern.test(cmdNormalized) ||
+        genericNeoAgentPattern.test(cmdNormalized) ||
+        repoNamePattern.test(cmd)
+      );
+    });
 }
 
 function killNeoAgentServerProcesses() {
@@ -425,18 +480,24 @@ async function cmdSetup() {
   ensureRuntimeDirs();
 
   const current = Object.fromEntries(parseEnv(readEnvFileRaw()).entries());
+  const defaultVmBaseImageUrl = getDefaultVmBaseImageUrl();
 
   logInfo('Press Enter to keep the current value shown in brackets.');
 
   heading('Core');
-  const port = await ask('Server port', current.PORT || '3333');
+  const portRaw = await ask('Server port', current.PORT || '3333');
+  const portNum = Number(portRaw);
+  if (!Number.isInteger(portNum) || portNum < 1 || portNum > 65535) {
+    throw new Error(`Invalid port "${portRaw}". Must be an integer between 1 and 65535.`);
+  }
+  const port = String(portNum);
   const publicUrl = await ask('Public base URL', current.PUBLIC_URL || '');
   const secureCookiesDefault = current.SECURE_COOKIES ||
     (String(publicUrl || '').trim().startsWith('https://') ? 'true' : 'false');
   const secureCookies = await ask('Secure cookies (true/false)', secureCookiesDefault);
   const trustProxyDefault = current.TRUST_PROXY || secureCookiesDefault;
   const trustProxy = await ask('Trust reverse proxy headers (true/false)', trustProxyDefault);
-  const sessionSecret = await askSecret('Session secret', current.SESSION_SECRET || randomSecret());
+  const sessionSecret = current.SESSION_SECRET || randomSecret();
   const deploymentMode = await ask(
     'Deployment mode (self_hosted/managed)',
     current.NEOAGENT_DEPLOYMENT_MODE || 'self_hosted'
@@ -446,6 +507,11 @@ async function cmdSetup() {
     current.NEOAGENT_RELEASE_CHANNEL || 'stable'
   );
   const origins = await ask('Allowed CORS origins', current.ALLOWED_ORIGINS || '');
+  const deploymentProfile = current.NEOAGENT_PROFILE || 'prod';
+  const vmBaseImageUrl = current.NEOAGENT_VM_BASE_IMAGE_URL || defaultVmBaseImageUrl;
+  const vmMemoryMb = current.NEOAGENT_VM_MEMORY_MB || '4096';
+  const vmCpus = current.NEOAGENT_VM_CPUS || '2';
+  const vmGuestToken = current.NEOAGENT_VM_GUEST_TOKEN || randomSecret();
 
   heading('AI Providers');
   const anthropic = await askSecret('Anthropic API key', current.ANTHROPIC_API_KEY || '');
@@ -542,6 +608,19 @@ async function cmdSetup() {
   const normalizedDeploymentMode = parseDeploymentMode(deploymentMode);
   const normalizedReleaseChannel = parseReleaseChannel(releaseChannel) || 'stable';
 
+  const githubOauthClientId = await askSecret(
+    'GitHub OAuth client ID',
+    current.GITHUB_OAUTH_CLIENT_ID || ''
+  );
+  const githubOauthClientSecret = await askSecret(
+    'GitHub OAuth client secret',
+    current.GITHUB_OAUTH_CLIENT_SECRET || ''
+  );
+  const githubOauthRedirectUri = await ask(
+    'GitHub OAuth redirect URI',
+    current.GITHUB_OAUTH_REDIRECT_URI || ''
+  );
+
   const lines = [
     `NODE_ENV=production`,
     `PORT=${port}`,
@@ -549,8 +628,13 @@ async function cmdSetup() {
     `SECURE_COOKIES=${normalizedSecureCookies}`,
     `TRUST_PROXY=${normalizedTrustProxy}`,
     `SESSION_SECRET=${sessionSecret}`,
+    `NEOAGENT_PROFILE=${deploymentProfile}`,
     `NEOAGENT_DEPLOYMENT_MODE=${normalizedDeploymentMode}`,
     `NEOAGENT_RELEASE_CHANNEL=${normalizedReleaseChannel}`,
+    `NEOAGENT_VM_BASE_IMAGE_URL=${vmBaseImageUrl}`,
+    `NEOAGENT_VM_MEMORY_MB=${vmMemoryMb}`,
+    `NEOAGENT_VM_CPUS=${vmCpus}`,
+    `NEOAGENT_VM_GUEST_TOKEN=${vmGuestToken}`,
     anthropic ? `ANTHROPIC_API_KEY=${anthropic}` : '',
     anthropicBaseUrl ? `ANTHROPIC_BASE_URL=${anthropicBaseUrl}` : '',
     openai ? `OPENAI_API_KEY=${openai}` : '',
@@ -576,6 +660,9 @@ async function cmdSetup() {
     figmaOauthClientId ? `FIGMA_OAUTH_CLIENT_ID=${figmaOauthClientId}` : '',
     figmaOauthClientSecret ? `FIGMA_OAUTH_CLIENT_SECRET=${figmaOauthClientSecret}` : '',
     figmaOauthRedirectUri ? `FIGMA_OAUTH_REDIRECT_URI=${figmaOauthRedirectUri}` : '',
+    githubOauthClientId ? `GITHUB_OAUTH_CLIENT_ID=${githubOauthClientId}` : '',
+    githubOauthClientSecret ? `GITHUB_OAUTH_CLIENT_SECRET=${githubOauthClientSecret}` : '',
+    githubOauthRedirectUri ? `GITHUB_OAUTH_REDIRECT_URI=${githubOauthRedirectUri}` : '',
     deepgramApiKey ? `DEEPGRAM_API_KEY=${deepgramApiKey}` : '',
     deepgramBaseUrl ? `DEEPGRAM_BASE_URL=${deepgramBaseUrl}` : '',
     deepgramModel ? `DEEPGRAM_MODEL=${deepgramModel}` : '',
@@ -674,10 +761,192 @@ async function cmdMigrate(args = []) {
   });
 }
 
+async function pollDeviceCode({ pollUrl, pollBody, pollHeaders = {}, intervalMs, timeoutMs, onToken }) {
+  const start = Date.now();
+  let currentInterval = intervalMs;
+  while (Date.now() - start < timeoutMs) {
+    await new Promise((r) => setTimeout(r, currentInterval));
+    const res = await fetch(pollUrl, {
+      method: 'POST',
+      headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', ...pollHeaders },
+      body: JSON.stringify(pollBody()),
+    });
+    if (res.status === 403 || res.status === 404) continue;
+    if (!res.ok) {
+      const text = await res.text().catch(() => 'Unknown error');
+      throw new Error(`Token poll failed: HTTP ${res.status} — ${text}`);
+    }
+    const data = await res.json();
+    const done = await onToken(data);
+    if (done) return;
+    if (data.error === 'authorization_pending') continue;
+    if (data.error === 'slow_down') { currentInterval += 5000; continue; }
+    if (data.error) throw new Error(`Authentication failed: ${data.error_description || data.error}`);
+  }
+  throw new Error('Authentication timed out after 15 minutes.');
+}
+
+async function cmdLoginClaudeCode() {
+  heading('Claude Code Login');
+
+  // Check for Claude CLI credential file first (set by `claude login`)
+  const cliCredsPath = path.join(os.homedir(), '.claude', '.credentials.json');
+  if (fs.existsSync(cliCredsPath)) {
+    try {
+      const raw = fs.readFileSync(cliCredsPath, 'utf8');
+      const data = JSON.parse(raw);
+      const token = data?.claudeAiOauthTokens?.accessToken;
+      if (token) {
+        upsertEnvValue('CLAUDE_CODE_OAUTH_TOKEN', token);
+        logOk('Imported access token from Claude CLI credentials store');
+        logInfo('Restarting NeoAgent to apply credentials...');
+        cmdRestart();
+        return;
+      }
+    } catch { }
+  }
+
+  // Browser-based PKCE OAuth flow.
+  // client_id is the metadata URL per claude.ai's dynamic client registration.
+  // Redirect URIs registered: http://localhost/callback and http://127.0.0.1/callback (port 80).
+  // Per RFC 8252 §7.3, servers SHOULD allow any loopback port — we try high ports first
+  // and fall back to 80 if everything else is occupied.
+  const http = require('http');
+  const { URL: NodeURL } = require('url');
+
+  const clientId = '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
+  const SCOPES = 'user:inference user:profile org:create_api_key user:sessions:claude_code user:mcp_servers';
+
+  // The registered redirect URIs are http://localhost/callback and http://127.0.0.1/callback
+  // (port 80). The OAuth server validates the URI exactly, so we must use port 80.
+  // Dynamic high port — the server accepts http://localhost:{any-port}/callback per RFC 8252.
+  const redirectPort = Math.floor(Math.random() * 10000) + 49152;
+  const redirectUri = `http://localhost:${redirectPort}/callback`;
+
+  // Generate PKCE verifier and challenge
+  const codeVerifier = crypto.randomBytes(48).toString('base64url');
+  const codeChallenge = crypto
+    .createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+
+  const state = crypto.randomBytes(16).toString('hex');
+
+  const authUrl = new URL('https://platform.claude.com/oauth/authorize');
+  authUrl.searchParams.set('response_type', 'code');
+  authUrl.searchParams.set('client_id', clientId);
+  authUrl.searchParams.set('redirect_uri', redirectUri);
+  authUrl.searchParams.set('scope', SCOPES);
+  authUrl.searchParams.set('code_challenge', codeChallenge);
+  authUrl.searchParams.set('code_challenge_method', 'S256');
+  authUrl.searchParams.set('state', state);
+
+  console.log(`\n  ${COLORS.cyan}Opening browser for Claude Code authorization...${COLORS.reset}`);
+  console.log(`  ${COLORS.dim}If the browser doesn't open, visit:${COLORS.reset}`);
+  console.log(`  ${authUrl.toString()}\n`);
+
+  // Open browser
+  const openCmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'start'
+    : 'xdg-open';
+  spawnSync(openCmd, [authUrl.toString()], { stdio: 'ignore' });
+
+  // Start local redirect server to capture authorization code
+  const authCode = await new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => {
+      server.close();
+      reject(new Error('Claude Code authorization timed out after 5 minutes.'));
+    }, 5 * 60 * 1000);
+
+    const server = http.createServer((req, res) => {
+      try {
+        const reqUrl = new NodeURL(req.url, redirectUri);
+        const code = reqUrl.searchParams.get('code');
+        const returnedState = reqUrl.searchParams.get('state');
+        const error = reqUrl.searchParams.get('error');
+
+        if (error) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>Authorization failed.</h2><p>You can close this tab.</p></body></html>');
+          clearTimeout(timeout);
+          server.close();
+          reject(new Error(`OAuth error: ${error}`));
+          return;
+        }
+
+        if (returnedState && returnedState !== state) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>Authorization failed.</h2><p>State mismatch. You can close this tab.</p></body></html>');
+          clearTimeout(timeout);
+          server.close();
+          reject(new Error('OAuth state mismatch — possible CSRF attempt.'));
+          return;
+        }
+
+        if (code) {
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h2>Authorization successful!</h2><p>You can close this tab and return to the terminal.</p></body></html>');
+          clearTimeout(timeout);
+          server.close();
+          resolve(code);
+        }
+      } catch (err) {
+        res.writeHead(500);
+        res.end('Internal error');
+      }
+    });
+
+    server.listen(redirectPort, 'localhost', () => {
+      logInfo(`Waiting for OAuth callback on ${redirectUri} ...`);
+    });
+    server.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(new Error(`Could not start OAuth callback server: ${err.message}`));
+    });
+  });
+
+  logInfo('Exchanging authorization code for access token...');
+  const tokenRes = await fetch('https://platform.claude.com/v1/oauth/token', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'anthropic-version': '2023-06-01',
+    },
+    body: JSON.stringify({
+      grant_type: 'authorization_code',
+      code: authCode,
+      redirect_uri: redirectUri,
+      client_id: clientId,
+      code_verifier: codeVerifier,
+      state,
+    }),
+  });
+
+  if (!tokenRes.ok) {
+    const text = await tokenRes.text().catch(() => 'Unknown error');
+    throw new Error(`Token exchange failed: HTTP ${tokenRes.status} — ${text}`);
+  }
+
+  const tokenData = await tokenRes.json();
+  const accessToken = tokenData.access_token;
+  if (!accessToken) {
+    throw new Error('Token exchange succeeded but no access_token was returned.');
+  }
+
+  upsertEnvValue('CLAUDE_CODE_OAUTH_TOKEN', accessToken);
+  if (tokenData.refresh_token) {
+    upsertEnvValue('CLAUDE_CODE_REFRESH_TOKEN', tokenData.refresh_token);
+  }
+  logOk('Saved Claude Code OAuth token to .env');
+  logInfo('Restarting NeoAgent to apply credentials...');
+  cmdRestart();
+}
+
 async function cmdLogin(args = []) {
   const provider = args[0];
-  if (provider !== 'github-copilot' && provider !== 'openai-codex') {
-    throw new Error(`Unsupported login provider: ${provider || 'none'}. Available: github-copilot, openai-codex`);
+  if (provider !== 'github-copilot' && provider !== 'openai-codex' && provider !== 'claude-code') {
+    throw new Error(`Unsupported login provider: ${provider || 'none'}. Available: github-copilot, openai-codex, claude-code`);
   }
 
   if (provider === 'github-copilot') {
@@ -690,52 +959,28 @@ async function cmdLogin(args = []) {
       headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
       body: JSON.stringify({ client_id: clientId, scope: 'user:email' })
     });
-
-    if (!reqRes.ok) {
-      throw new Error(`Failed to request device code: HTTP ${reqRes.status}`);
-    }
+    if (!reqRes.ok) throw new Error(`Failed to request device code: HTTP ${reqRes.status}`);
 
     const { device_code, user_code, verification_uri, interval } = await reqRes.json();
-
     console.log(`\n  ${COLORS.cyan}Please visit:${COLORS.reset} ${verification_uri}`);
-    console.log(`  ${COLORS.cyan}And enter the code:${COLORS.reset} ${COLORS.bold}${user_code}${COLORS.reset}\n`);
-    
+    console.log(`  ${COLORS.cyan}Enter code:${COLORS.reset}   ${COLORS.bold}${user_code}${COLORS.reset}\n`);
     logInfo('Waiting for authorization (timeout in 15m)...');
-    const startTime = Date.now();
-    const timeoutMs = 15 * 60 * 1000;
-    let currentPollInterval = (interval || 5) * 1000;
-
-    while (Date.now() - startTime < timeoutMs) {
-      await new Promise((r) => setTimeout(r, currentPollInterval));
-      const tokenRes = await fetch('https://github.com/login/oauth/access_token', {
-        method: 'POST',
-        headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          client_id: clientId,
-          device_code,
-          grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
-        })
-      });
-
-      if (!tokenRes.ok) {
-        const errorText = await tokenRes.text().catch(() => 'Unknown error');
-        throw new Error(`GitHub token request failed: HTTP ${tokenRes.status} - ${errorText}`);
-      }
 
-      const data = await tokenRes.json();
-      if (data.access_token) {
+    await pollDeviceCode({
+      pollUrl: 'https://github.com/login/oauth/access_token',
+      pollBody: () => ({ client_id: clientId, device_code, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }),
+      intervalMs: (interval || 5) * 1000,
+      timeoutMs: 15 * 60 * 1000,
+      onToken: async (data) => {
+        if (!data.access_token) return false;
         upsertEnvValue('GITHUB_COPILOT_ACCESS_TOKEN', data.access_token);
-        logOk('Successfully authenticated and saved GitHub Copilot access token to .env');
-        return;
-      } else if (data.error === 'authorization_pending') {
-        // Continue polling
-      } else if (data.error === 'slow_down') {
-        currentPollInterval += 5000;
-      } else if (data.error) {
-        throw new Error(`Authentication failed: ${data.error_description || data.error}`);
-      }
-    }
-    throw new Error('GitHub authentication timed out after 15 minutes.');
+        logOk('Saved GitHub Copilot access token to .env');
+        logInfo('Restarting NeoAgent to apply credentials...');
+        cmdRestart();
+        return true;
+      },
+    });
+    return;
   } else if (provider === 'openai-codex') {
     heading('OpenAI Codex Login');
     const clientId = 'app_EMoamEEZ73f0CkXaXp7hrann';
@@ -751,47 +996,62 @@ async function cmdLogin(args = []) {
       throw new Error(`Failed to request device code: HTTP ${reqRes.status}`);
     }
 
-    const { device_code, user_code, verification_uri, interval } = await reqRes.json();
+    const data = await reqRes.json();
+    const { device_auth_id, interval } = data;
+    const user_code = data.user_code || data.usercode;
+    const verification_uri = 'https://auth.openai.com/codex/device';
 
     console.log(`\n  ${COLORS.cyan}Please visit:${COLORS.reset} ${verification_uri}`);
-    console.log(`  ${COLORS.cyan}And enter the code:${COLORS.reset} ${COLORS.bold}${user_code}${COLORS.reset}\n`);
-    
+    console.log(`  ${COLORS.cyan}Enter code:${COLORS.reset}   ${COLORS.bold}${user_code}${COLORS.reset}\n`);
     logInfo('Waiting for authorization (timeout in 15m)...');
-    const startTime = Date.now();
-    const timeoutMs = 15 * 60 * 1000;
-    let currentPollInterval = (interval || 5) * 1000;
-
-    while (Date.now() - startTime < timeoutMs) {
-      await new Promise((r) => setTimeout(r, currentPollInterval));
-      const tokenRes = await fetch('https://auth.openai.com/api/accounts/deviceauth/token', {
-        method: 'POST',
-        headers: { 'Accept': 'application/json', 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          client_id: clientId,
-          device_code,
-          grant_type: 'urn:ietf:params:oauth:grant-type:device_code'
-        })
-      });
-
-      if (!tokenRes.ok) {
-        const errorText = await tokenRes.text().catch(() => 'Unknown error');
-        throw new Error(`OpenAI token request failed: HTTP ${tokenRes.status} - ${errorText}`);
-      }
 
-      const data = await tokenRes.json();
-      if (data.access_token) {
-        upsertEnvValue('OPENAI_CODEX_ACCESS_TOKEN', data.access_token);
-        logOk('Successfully authenticated and saved OpenAI Codex access token to .env');
-        return;
-      } else if (data.error === 'authorization_pending') {
-        // Continue polling
-      } else if (data.error === 'slow_down') {
-        currentPollInterval += 5000;
-      } else if (data.error) {
-        throw new Error(`Authentication failed: ${data.error_description || data.error}`);
-      }
+    let authorizationCode = null;
+    let codeVerifier = null;
+
+    await pollDeviceCode({
+      pollUrl: 'https://auth.openai.com/api/accounts/deviceauth/token',
+      pollBody: () => ({ device_auth_id, user_code }),
+      intervalMs: (interval || 5) * 1000,
+      timeoutMs: 15 * 60 * 1000,
+      onToken: async (data) => {
+        if (!data.authorization_code || !data.code_verifier) return false;
+        authorizationCode = data.authorization_code;
+        codeVerifier = data.code_verifier;
+        return true;
+      },
+    });
+
+    logInfo('Exchanging authorization code for access token...');
+    const exchangeRes = await fetch('https://auth.openai.com/oauth/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: authorizationCode,
+        redirect_uri: 'https://auth.openai.com/deviceauth/callback',
+        client_id: clientId,
+        code_verifier: codeVerifier,
+      }),
+    });
+
+    if (!exchangeRes.ok) {
+      const errorText = await exchangeRes.text().catch(() => 'Unknown error');
+      throw new Error(`OpenAI token exchange failed: HTTP ${exchangeRes.status} — ${errorText}`);
+    }
+
+    const exchangeData = await exchangeRes.json();
+    if (!exchangeData.access_token) {
+      throw new Error('OpenAI token exchange succeeded but did not return an access token.');
+    }
+    upsertEnvValue('OPENAI_CODEX_ACCESS_TOKEN', exchangeData.access_token);
+    if (exchangeData.refresh_token) {
+      upsertEnvValue('OPENAI_CODEX_REFRESH_TOKEN', exchangeData.refresh_token);
     }
-    throw new Error('OpenAI authentication timed out after 15 minutes.');
+    logOk('Saved OpenAI Codex tokens to .env');
+    logInfo('Restarting NeoAgent to apply credentials...');
+    cmdRestart();
+  } else if (provider === 'claude-code') {
+    await cmdLoginClaudeCode();
   }
 }
 
@@ -891,6 +1151,109 @@ function startFallback() {
   logOk(`Started detached process (pid ${child.pid})`);
 }
 
+async function ensureQemuInstalled() {
+  heading('Ensure QEMU Installed');
+  const platform = detectPlatform();
+  
+  const hasSystem = commandExists('qemu-system-x86_64') || commandExists('qemu-system-aarch64');
+  const hasImg = commandExists('qemu-img');
+
+  if (hasSystem && hasImg) {
+    logOk('QEMU components are already installed');
+    return;
+  }
+
+  logInfo('QEMU components not found. Attempting to install...');
+
+  if (platform === 'macos') {
+    if (!commandExists('brew')) {
+      throw new Error('Homebrew is required to install QEMU on macOS. Please install it first: https://brew.sh/');
+    }
+    logInfo('Running "brew install qemu"...');
+    runOrThrow('brew', ['install', 'qemu']);
+  } else if (platform === 'linux') {
+    const isArm = process.arch === 'arm64' || process.arch === 'aarch64';
+    if (commandExists('apt-get')) {
+      const pkgs = ['qemu-utils'];
+      if (isArm) {
+        pkgs.push('qemu-system-arm');
+      } else {
+        pkgs.push('qemu-system-x86');
+      }
+      logInfo(`Running "sudo apt-get update && sudo apt-get install -y ${pkgs.join(' ')}"...`);
+      runOrThrow('sudo', ['apt-get', 'update']);
+      runOrThrow('sudo', ['apt-get', 'install', '-y', ...pkgs]);
+    } else if (commandExists('dnf')) {
+      logInfo('Running "sudo dnf install -y qemu-kvm qemu-img"...');
+      runOrThrow('sudo', ['dnf', 'install', '-y', 'qemu-kvm', 'qemu-img']);
+    } else if (commandExists('yum')) {
+      logInfo('Running "sudo yum install -y qemu-kvm qemu-img"...');
+      runOrThrow('sudo', ['yum', 'install', '-y', 'qemu-kvm', 'qemu-img']);
+    } else {
+      throw new Error('Unsupported Linux distribution. Please install qemu-system and qemu-utils manually.');
+    }
+  } else {
+    throw new Error('Unsupported platform for automatic QEMU installation. Please install QEMU manually.');
+  }
+
+  const verifiedSystem = commandExists('qemu-system-x86_64') || commandExists('qemu-system-aarch64');
+  const verifiedImg = commandExists('qemu-img');
+
+  if (verifiedSystem && verifiedImg) {
+    logOk('QEMU installed successfully');
+  } else {
+    throw new Error('QEMU installation failed or components not found in PATH after install.');
+  }
+}
+
+function ensureYtDlpInstalled() {
+  heading('Ensure yt-dlp Installed');
+  if (commandExists('yt-dlp')) {
+    const ver = runQuiet('yt-dlp', ['--version']);
+    logOk(`yt-dlp ${ver.status === 0 ? ver.stdout.trim() : '(version unknown)'}`);
+    return;
+  }
+
+  logInfo('yt-dlp not found. Attempting to install...');
+  const platform = detectPlatform();
+
+  if (platform === 'macos') {
+    if (!commandExists('brew')) {
+      logWarn('Homebrew not found — skipping yt-dlp install. Install manually: brew install yt-dlp');
+      return;
+    }
+    try {
+      runOrThrow('brew', ['install', 'yt-dlp']);
+      logOk('yt-dlp installed via Homebrew');
+    } catch {
+      logWarn('yt-dlp install failed. Install manually: brew install yt-dlp');
+    }
+    return;
+  }
+
+  if (platform === 'linux') {
+    if (commandExists('pipx')) {
+      try {
+        runOrThrow('pipx', ['install', 'yt-dlp']);
+        logOk('yt-dlp installed via pipx');
+        return;
+      } catch {
+        // fall through to pip3
+      }
+    }
+    if (commandExists('pip3')) {
+      try {
+        runOrThrow('pip3', ['install', '--user', 'yt-dlp']);
+        logOk('yt-dlp installed via pip3');
+        return;
+      } catch {
+        // fall through to warn
+      }
+    }
+    logWarn('Could not install yt-dlp automatically. Install manually: pipx install yt-dlp');
+  }
+}
+
 async function cmdInstall() {
   heading(`Install ${APP_NAME}`);
   if (!fs.existsSync(ENV_FILE)) {
@@ -899,6 +1262,8 @@ async function cmdInstall() {
   }
 
   installDependencies();
+  await ensureQemuInstalled();
+  ensureYtDlpInstalled();
   buildBundledWebClientIfPossible({ required: true });
 
   const platform = detectPlatform();
@@ -960,7 +1325,7 @@ function cmdStop() {
           logOk(`Stopped pid ${pid}`);
           stopped = true;
         } catch {
-          logWarn(`pid ${pid} not running`);
+          logWarn(`pid ${pid} was not running (stale PID file)`);
         }
       }
       fs.rmSync(pidPath, { force: true });
@@ -988,6 +1353,11 @@ function cmdRestart() {
   cmdStart();
 }
 
+async function cmdRebuildWeb() {
+  heading(`Rebuild Flutter Web Client`);
+  buildBundledWebClientIfPossible();
+}
+
 function cmdUninstall() {
   heading(`Uninstall ${APP_NAME}`);
   const platform = detectPlatform();
@@ -1016,22 +1386,52 @@ async function cmdStatus() {
   const port = loadEnvPort();
   const running = await isPortOpen(port);
   const releaseChannel = currentReleaseChannel();
+  const platform = detectPlatform();
 
   if (running) {
-    logOk(`running on http://localhost:${port}`);
+    logOk(`server   http://localhost:${port}`);
   } else {
-    logWarn(`not reachable on port ${port}`);
+    logWarn(`server   not reachable on port ${port}`);
   }
 
-  console.log(`  install root ${APP_DIR}`);
-  console.log(`  version ${currentInstalledVersionLabel()}`);
-  console.log(`  release channel ${releaseChannelSummary(releaseChannel)}`);
+  if (platform === 'macos' && fs.existsSync(PLIST_DST)) {
+    const svcRes = runQuiet('launchctl', ['list', SERVICE_LABEL]);
+    if (svcRes.status === 0 && svcRes.stdout.trim()) {
+      logOk(`service  launchd (${SERVICE_LABEL})`);
+    } else {
+      logWarn(`service  launchd unit not loaded — run: neoagent install`);
+    }
+  } else if (platform === 'linux' && fs.existsSync(SYSTEMD_UNIT)) {
+    const svcRes = runQuiet('systemctl', ['--user', 'is-active', 'neoagent']);
+    if (svcRes.status === 0 && svcRes.stdout.trim() === 'active') {
+      logOk('service  systemd (neoagent)');
+    } else {
+      logWarn('service  systemd unit not active — run: neoagent install');
+    }
+  }
+
+  if (fs.existsSync(ENV_FILE)) {
+    logOk(`config   ${ENV_FILE}`);
+  } else {
+    logWarn(`config   .env not found — run: neoagent setup`);
+  }
+
+  if (hasBundledWebClient(WEB_CLIENT_DIR)) {
+    logOk('web      bundled Flutter client present');
+  } else {
+    logWarn('web      no bundled client — run: neoagent rebuild-web');
+  }
+
+  console.log('');
+  console.log(`  install  ${APP_DIR}`);
+  console.log(`  version  ${currentInstalledVersionLabel()}`);
+  console.log(`  channel  ${releaseChannelSummary(releaseChannel)}`);
 
   const processes = listNeoAgentServerProcesses();
   if (processes.length > 0) {
-    console.log(`  neoagent pids ${processes.map((proc) => proc.pid).join(', ')}`);
+    console.log(`  pids     ${processes.map((proc) => proc.pid).join(', ')}`);
     if (processes.length > 1) {
-      logWarn(`multiple NeoAgent server processes detected (${processes.length})`);
+      logWarn(`multiple NeoAgent processes detected (${processes.length})`);
     }
   }
 }
@@ -1083,6 +1483,8 @@ function cmdUpdate(args = []) {
   }
   const versionBefore = currentInstalledVersionLabel();
   let versionAfter = versionBefore;
+  const githubInstallRef = releaseChannel === 'beta' ? '#beta' : '';
+  const githubInstallSpec = `git+https://github.com/NeoLabs-Systems/NeoAgent.git${githubInstallRef}`;
 
   if (fs.existsSync(path.join(APP_DIR, '.git')) && commandExists('git')) {
     const current = runQuiet('git', ['rev-parse', '--short', 'HEAD']);
@@ -1091,6 +1493,7 @@ function cmdUpdate(args = []) {
     const targetBranch = resolvePreferredGitBranch(releaseChannel);
     logInfo(`Using git branch ${targetBranch} for the ${releaseChannel} channel.`);
     ensureGitBranchForReleaseChannel(targetBranch);
+    backupRuntimeData();
     runOrThrow('git', ['pull', '--rebase', '--autostash', 'origin', targetBranch]);
 
     const next = runQuiet('git', ['rev-parse', '--short', 'HEAD']);
@@ -1103,17 +1506,16 @@ function cmdUpdate(args = []) {
       buildBundledWebClientIfPossible();
     }
   } else {
-    const npmTag = resolvePreferredNpmTag(releaseChannel);
-    logWarn(`No git repo detected; attempting npm global update from ${npmTag}.`);
+    logWarn(`No git repo detected; attempting npm global update from ${githubInstallSpec}.`);
     if (commandExists('npm')) {
       try {
         backupRuntimeData();
-        runOrThrow('npm', ['install', '-g', `neoagent@${npmTag}`, '--force'], {
+        runOrThrow('npm', ['install', '-g', githubInstallSpec, '--force'], {
           env: withInstallEnv()
         });
-        logOk('npm global update completed (forced reinstall)');
+        logOk('npm global update completed (forced reinstall from GitHub)');
       } catch {
-        logWarn(`npm global update failed. Run: npm install -g neoagent@${npmTag} --force`);
+        logWarn(`npm global update failed. Run: npm install -g ${githubInstallSpec} --force`);
       }
     } else {
       logWarn('npm not found. Cannot perform global update.');
@@ -1121,6 +1523,7 @@ function cmdUpdate(args = []) {
   }
 
   versionAfter = currentInstalledVersionLabel();
+  ensureYtDlpInstalled();
 
   if (!hasBundledWebClient(WEB_CLIENT_DIR)) {
     throw new Error('No bundled Flutter web client found after update.');
@@ -1132,11 +1535,16 @@ function cmdUpdate(args = []) {
 
 async function cmdEnv(args = []) {
   heading('Environment Variables');
-  let action = args[0];
+  const action = (args[0] || '').trim().toLowerCase();
 
   if (!action) {
-    const picked = await ask('Action (list/get/set/unset)', 'list');
-    action = (picked || 'list').trim().toLowerCase();
+    console.log('Usage: neoagent env <subcommand>');
+    console.log('');
+    console.log('  neoagent env list            List all variables (secrets masked)');
+    console.log('  neoagent env get KEY         Print a single variable');
+    console.log('  neoagent env set KEY VALUE   Set a variable');
+    console.log('  neoagent env unset KEY       Remove a variable');
+    return;
   }
 
   if (action === 'list') {
@@ -1161,16 +1569,17 @@ async function cmdEnv(args = []) {
   }
 
   if (action === 'set') {
-    const key = args[1] || await ask('Key', 'PORT');
-    const value = args.slice(2).join(' ') || await ask('Value', key === 'PORT' ? '3333' : '');
+    const key = args[1];
+    const value = args.slice(2).join(' ');
     if (!key || !value) throw new Error('Usage: neoagent env set <KEY> <VALUE>');
+    validateEnvKey(key);
     upsertEnvValue(key, value);
     logOk(`Set ${key} in ${ENV_FILE}`);
     return;
   }
 
   if (action === 'unset') {
-    const key = args[1] || await ask('Key', 'PORT');
+    const key = args[1];
     if (!key) throw new Error('Usage: neoagent env unset <KEY>');
     removeEnvValue(key);
     logOk(`Removed ${key} from ${ENV_FILE}`);
@@ -1180,16 +1589,56 @@ async function cmdEnv(args = []) {
   throw new Error('Usage: neoagent env [list|get|set|unset] ...');
 }
 
+function cmdVersion() {
+  console.log(currentInstalledVersionLabel());
+}
+
 function printHelp() {
-  console.log(`${APP_NAME} manager`);
-  console.log('Usage: neoagent <command>');
-  console.log('Commands: install | setup | env | channel | update | restart | start | stop | status | logs | uninstall | migrate | login');
-  console.log('Login usage: neoagent login github-copilot | neoagent login openai-codex');
-  console.log('Channel usage: neoagent channel | neoagent channel stable | neoagent channel beta');
-  console.log('Update usage: neoagent update | neoagent update stable | neoagent update beta');
-  console.log('Env usage: neoagent env list | neoagent env get PORT | neoagent env set PORT 3333 | neoagent env unset PORT');
-  console.log('Migrate usage: neoagent migrate | neoagent migrate dry-run | neoagent migrate status');
-  console.log('               neoagent migrate openclaw-only | neoagent migrate hermes-only');
+  const c = COLORS;
+  const W = 38;
+
+  function row(cmd, desc) {
+    const padded = `  neoagent ${cmd}`.padEnd(W);
+    console.log(`${padded}${c.dim}${desc}${c.reset}`);
+  }
+
+  console.log(`\n${c.bold}neoagent${c.reset}  —  manage your NeoAgent server\n`);
+  console.log(`${c.bold}Usage${c.reset}  neoagent <command> [args]\n`);
+
+  console.log(`${c.bold}Lifecycle${c.reset}`);
+  row('install',              'First-time install and service setup');
+  row('start',               'Start the server');
+  row('stop',                'Stop the server');
+  row('restart',             'Stop, then start');
+  row('status',              'Health overview (server, service, config)');
+  row('logs',                'Tail server logs');
+  row('uninstall',           'Remove the system service');
+  console.log('');
+
+  console.log(`${c.bold}Configuration${c.reset}`);
+  row('setup',               'Interactive configuration wizard');
+  row('env list',            'List all variables (secrets masked)');
+  row('env get KEY',         'Print a single variable');
+  row('env set KEY VALUE',   'Set a variable');
+  row('env unset KEY',       'Remove a variable');
+  row('channel',             'Show current release channel');
+  row('channel stable|beta', 'Switch release channel');
+  console.log('');
+
+  console.log(`${c.bold}Updates & Auth${c.reset}`);
+  row('update',              'Update to latest on current channel');
+  row('update stable|beta',  'Update and switch channel');
+  row('login github-copilot','Authenticate GitHub Copilot');
+  row('login openai-codex',  'Authenticate OpenAI Codex');
+  row('login claude-code',   'Authenticate Claude Code');
+  console.log('');
+
+  console.log(`${c.bold}Maintenance${c.reset}`);
+  row('migrate',             'Migrate from another agent installation');
+  row('migrate dry-run',     'Preview what would be migrated');
+  row('rebuild-web',         'Rebuild the bundled Flutter web client');
+  row('version',             'Print installed version');
+  console.log('');
 }
 
 async function runCLI(argv) {
@@ -1216,6 +1665,9 @@ async function runCLI(argv) {
     case 'restart':
       cmdRestart();
       break;
+    case 'rebuild-web':
+      await cmdRebuildWeb();
+      break;
     case 'start':
       cmdStart();
       break;
@@ -1237,13 +1689,18 @@ async function runCLI(argv) {
     case 'login':
       await cmdLogin(argv.slice(1));
       break;
+    case 'version':
+    case '--version':
+    case '-V':
+      cmdVersion();
+      break;
     case 'help':
     case '--help':
     case '-h':
       printHelp();
       break;
     default:
-      throw new Error(`Unknown command: ${command}`);
+      throw new Error(`Unknown command: ${command}. Run "neoagent --help" for usage.`);
   }
 }