amalgm 0.0.0 → 0.0.32

package/lib/cli.js

@@ -0,0 +1,1132 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const http = require('http');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+const readline = require('readline');
+const { spawn, spawnSync } = require('child_process');
+
+const {
+  AMALGM_DIR,
+  DEFAULT_APP_URL,
+  DEVICE_FILE,
+  LOG_DIR,
+  PID_FILE,
+  RUNTIME_DIR,
+  RUNTIME_STATE_FILE,
+  RUNTIME_TOKEN_FILE,
+} = require('./paths');
+const { startSupervisor } = require('./supervisor');
+const {
+  deleteComputerAuth,
+  loadComputerRecord,
+  proxyTokenFromRecord,
+  proxyTokenNeedsRefresh,
+  saveComputerRecord,
+} = require('./auth-store');
+const {
+  agentCommandShimStatus,
+  binaryStatus,
+  ensureAgentCommandShims,
+  ensureNativeBinaries,
+} = require('../runtime/scripts/chat-core/tooling/native-binaries');
+
+const PACKAGE_VERSION = require('../package.json').version;
+const SETUP_CODE_LENGTH = 16;
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args.shift() || 'help';
+  const options = {};
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const eq = arg.indexOf('=');
+    if (eq !== -1) {
+      options[arg.slice(2, eq)] = arg.slice(eq + 1);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    const next = args[i + 1];
+    if (next && !next.startsWith('--')) {
+      options[key] = next;
+      i += 1;
+    } else {
+      options[key] = true;
+    }
+  }
+
+  return { command, options, positionals };
+}
+
+function usage() {
+  return [
+    'amalgm - local computer runtime',
+    '',
+    'Usage:',
+    '  amalgm login [--app-url https://amalgm.ai] [--name "My Mac"] [--setup-code ABCD-EFGH-JKLM-NPQR] [--no-open] [--no-poll]',
+    '  amalgm start [--foreground] [--local-only]',
+    '  amalgm stop',
+    '  amalgm status',
+    '  amalgm doctor',
+    '  amalgm update [--tag latest|canary]',
+    '  amalgm logs [service]',
+    '  amalgm logout',
+    '',
+    'Environment:',
+    '  AMALGM_APP_URL        Web app base URL for login/register',
+    '  AMALGM_AUTO_UPDATE    Set to 1 to update before start when a newer dist-tag exists',
+    '  AMALGM_DIR            Runtime state dir (default ~/.amalgm)',
+    '  AMALGM_PROXY_TOKEN    Optional short-lived proxy token override',
+  ].join('\n');
+}
+
+function ensureDir(dir, mode = 0o700) {
+  fs.mkdirSync(dir, { recursive: true, mode });
+  try {
+    fs.chmodSync(dir, mode);
+  } catch {
+    // chmod is best-effort on non-POSIX filesystems.
+  }
+}
+
+function ensureBaseDirs() {
+  ensureDir(AMALGM_DIR, 0o700);
+  ensureDir(LOG_DIR, 0o700);
+}
+
+function readJson(file, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJsonSecret(file, data) {
+  ensureDir(path.dirname(file), 0o700);
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temp, file);
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // chmod is best-effort on non-POSIX filesystems.
+  }
+}
+
+function runtimeEntry(relativePath) {
+  return path.join(RUNTIME_DIR, relativePath);
+}
+
+function runtimeMissingFiles() {
+  const required = [
+    runtimeEntry('scripts/amalgm-mcp/index.js'),
+    runtimeEntry('scripts/chat-server.js'),
+    runtimeEntry('scripts/fs-watcher.js'),
+    runtimeEntry('scripts/local-gateway.js'),
+    runtimeEntry('scripts/port-monitor.js'),
+  ];
+  return required.filter((file) => !fs.existsSync(file));
+}
+
+function servicePorts() {
+  const state = readJson(RUNTIME_STATE_FILE, null);
+  const statePorts = state?.ports || {};
+  if (Number.isInteger(state?.gateway_port)) {
+    return [
+      ['local-gateway', Number(state.gateway_port)],
+      ['port-monitor', Number(statePorts.port_monitor || 0)],
+      ['fs-watcher', Number(statePorts.fs_watcher || 0)],
+      ['amalgm-mcp', Number(statePorts.amalgm_mcp || 0)],
+      ['chat-server', Number(statePorts.chat_server || 0)],
+    ].filter(([, port]) => Number.isInteger(port) && port > 0);
+  }
+
+  return [
+    ['local-gateway', Number(process.env.AMALGM_GATEWAY_PORT || 28781)],
+    ['port-monitor', Number(process.env.PORT_MONITOR_PORT || 8081)],
+    ['fs-watcher', Number(process.env.FS_WATCHER_PORT || 8082)],
+    ['amalgm-mcp', Number(process.env.AMALGM_MCP_PORT || 8083)],
+    ['chat-server', Number(process.env.CHAT_SERVER_PORT || 8084)],
+  ];
+}
+
+function hasRequiredComputerFields(record) {
+  return !!(
+    record
+    && record.computer_id
+    && record.webhook_url
+    && record.tunnel_url
+    && record.tunnel_token
+  );
+}
+
+const SAFE_DAEMON_ENV_KEYS = [
+  'AMALGM_BIND_HOST',
+  'AMALGM_DEFAULT_CWD',
+  'AMALGM_GATEWAY_PORT',
+  'AMALGM_MCP_PORT',
+  'AMALGM_NATIVE_NODE_MODULES',
+  'AMALGM_SKIP_NATIVE_INSTALL',
+  'CHAT_SERVER_PORT',
+  'ELECTRON_RUN_AS_NODE',
+  'FS_WATCHER_PORT',
+  'FS_WATCHER_ROOT',
+  'HOME',
+  'LANG',
+  'LC_ALL',
+  'LOGNAME',
+  'NODE_PATH',
+  'PATH',
+  'PORT_MONITOR_PORT',
+  'SHELL',
+  'SSH_AUTH_SOCK',
+  'TERM',
+  'TMP',
+  'TMPDIR',
+  'TEMP',
+  'USER',
+  'XDG_CACHE_HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_DATA_HOME',
+];
+
+function daemonEnv(localOnly) {
+  const env = {};
+  for (const key of SAFE_DAEMON_ENV_KEYS) {
+    if (process.env[key]) env[key] = process.env[key];
+  }
+  env.AMALGM_DIR = AMALGM_DIR;
+  if (localOnly) env.AMALGM_LOCAL_ONLY = 'true';
+  return env;
+}
+
+function normalizeBaseUrl(value) {
+  const url = new URL(String(value || DEFAULT_APP_URL));
+  url.pathname = url.pathname.replace(/\/+$/, '');
+  url.search = '';
+  url.hash = '';
+  return url.toString().replace(/\/$/, '');
+}
+
+function machineName() {
+  return process.env.AMALGM_COMPUTER_NAME || os.hostname() || 'Amalgm computer';
+}
+
+function platformName() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function normalizeSetupCode(value) {
+  return String(value || '').toUpperCase().replace(/[^A-Z0-9]/g, '').slice(0, SETUP_CODE_LENGTH);
+}
+
+function formatSetupCode(value) {
+  const normalized = normalizeSetupCode(value);
+  return normalized.match(/.{1,4}/g)?.join('-') || '';
+}
+
+async function ensureDevice() {
+  const existing = readJson(DEVICE_FILE, null);
+  if (existing && typeof existing.device_id === 'string' && existing.device_id.length >= 8) {
+    return existing;
+  }
+
+  const device = {
+    device_id: `npm-${crypto.randomUUID()}`,
+    created_at: new Date().toISOString(),
+  };
+  writeJsonSecret(DEVICE_FILE, device);
+  return device;
+}
+
+async function requestJson(url, options = {}) {
+  let res;
+  try {
+    res = await fetch(url, {
+      ...options,
+      headers: {
+        accept: 'application/json',
+        ...(options.body ? { 'content-type': 'application/json' } : {}),
+        ...(options.headers || {}),
+      },
+    });
+  } catch (error) {
+    const method = String(options.method || 'GET').toUpperCase();
+    const cause = error?.cause || {};
+    const causeDetail = [
+      cause.code,
+      cause.errno,
+      cause.syscall,
+      cause.hostname,
+      cause.address,
+      cause.port,
+    ].filter(Boolean).join(' ');
+    const lines = [
+      `Could not reach the Amalgm web app (${method} ${url}).`,
+      `Cause: ${causeDetail || error.message || 'network request failed'}`,
+      'Check network, DNS, TLS certificates, or pass --app-url to target a different deployment.',
+    ];
+    if (String(url).includes('/api/auth/computer-setup/cli/start')) {
+      lines.push('For headless machines, create a setup code in the web app and run `amalgm login --setup-code <code>`.');
+    }
+    const wrapped = new Error(lines.join('\n'));
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  const text = await res.text();
+  let payload = {};
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = { text };
+    }
+  }
+
+  if (!res.ok) {
+    const detail = payload && payload.error ? payload.error : text || res.statusText;
+    const error = new Error(`${res.status} ${detail}`);
+    error.status = res.status;
+    error.payload = payload;
+    throw error;
+  }
+
+  return payload;
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function assertRuntimePresent() {
+  const missing = runtimeMissingFiles();
+  if (missing.length > 0) {
+    throw new Error(
+      [
+        'The Amalgm runtime is missing from this package.',
+        'If you are developing locally, run `npm run npm:sync` from amalgm-engine.',
+        'If this came from npm, reinstall the package.',
+        `Missing: ${missing[0]}`,
+      ].join('\n'),
+    );
+  }
+}
+
+function isPortFree(port, host = '127.0.0.1') {
+  return new Promise((resolve) => {
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+      resolve(false);
+      return;
+    }
+
+    const server = net.createServer();
+    server.unref();
+    server.on('error', () => resolve(false));
+    server.listen({ port, host }, () => {
+      server.close(() => resolve(true));
+    });
+  });
+}
+
+async function unavailableServicePorts() {
+  const results = [];
+  const explicitEnvByService = new Map([
+    ['local-gateway', 'AMALGM_GATEWAY_PORT'],
+    ['port-monitor', 'PORT_MONITOR_PORT'],
+    ['fs-watcher', 'FS_WATCHER_PORT'],
+    ['amalgm-mcp', 'AMALGM_MCP_PORT'],
+    ['chat-server', 'CHAT_SERVER_PORT'],
+  ]);
+  for (const [name, port] of servicePorts()) {
+    const envName = explicitEnvByService.get(name);
+    if (!envName || !process.env[envName]) continue;
+    if (!(await isPortFree(port))) results.push([name, port]);
+  }
+  return results;
+}
+
+function commandExists(command) {
+  if (!command || process.platform === 'win32') return true;
+  const paths = String(process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  return paths.some((dir) => {
+    try {
+      fs.accessSync(path.join(dir, command), fs.constants.X_OK);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function parseSemver(value) {
+  const [core, prerelease = ''] = String(value || '').trim().replace(/^v/, '').split('-', 2);
+  const parts = core.split('.').map((part) => Number.parseInt(part, 10));
+  return {
+    major: Number.isFinite(parts[0]) ? parts[0] : 0,
+    minor: Number.isFinite(parts[1]) ? parts[1] : 0,
+    patch: Number.isFinite(parts[2]) ? parts[2] : 0,
+    prerelease: prerelease ? prerelease.split('.') : [],
+  };
+}
+
+function comparePrerelease(left, right) {
+  if (left.length === 0 && right.length === 0) return 0;
+  if (left.length === 0) return 1;
+  if (right.length === 0) return -1;
+
+  const length = Math.max(left.length, right.length);
+  for (let i = 0; i < length; i += 1) {
+    const a = left[i];
+    const b = right[i];
+    if (a === undefined) return -1;
+    if (b === undefined) return 1;
+    const aNum = /^\d+$/.test(a) ? Number.parseInt(a, 10) : null;
+    const bNum = /^\d+$/.test(b) ? Number.parseInt(b, 10) : null;
+    if (aNum !== null && bNum !== null && aNum !== bNum) return aNum > bNum ? 1 : -1;
+    if (aNum !== null && bNum === null) return -1;
+    if (aNum === null && bNum !== null) return 1;
+    if (a !== b) return a > b ? 1 : -1;
+  }
+  return 0;
+}
+
+function compareVersions(left, right) {
+  const a = parseSemver(left);
+  const b = parseSemver(right);
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] > b[key] ? 1 : -1;
+  }
+  return comparePrerelease(a.prerelease, b.prerelease);
+}
+
+function npmCommand() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function npmInstallTag(options = {}) {
+  const explicit = options.tag || options.channel;
+  if (explicit && explicit !== true) return String(explicit).replace(/^@/, '');
+  return PACKAGE_VERSION.includes('-canary.') ? 'canary' : 'latest';
+}
+
+function npmPackageVersionForTag(tag) {
+  const result = spawnSync(npmCommand(), ['view', `amalgm@${tag}`, 'version', '--json'], {
+    encoding: 'utf8',
+    timeout: 15000,
+    env: {
+      ...process.env,
+      npm_config_audit: 'false',
+      npm_config_fund: 'false',
+    },
+  });
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || '').trim();
+    throw new Error(`Could not check npm dist-tag "${tag}". ${detail}`);
+  }
+
+  const raw = String(result.stdout || '').trim();
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw.replace(/^"|"$/g, '');
+  }
+}
+
+function installNpmPackageTag(tag) {
+  return spawnSync(npmCommand(), ['install', '-g', `amalgm@${tag}`], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      npm_config_audit: 'false',
+      npm_config_fund: 'false',
+    },
+  });
+}
+
+function openBrowser(url) {
+  const command =
+    process.platform === 'darwin'
+      ? 'open'
+      : process.platform === 'win32'
+        ? 'cmd'
+        : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+
+  try {
+    if (!commandExists(command)) return false;
+    const child = spawn(command, args, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+    });
+    child.once('error', () => {
+      // Browser opening is opportunistic. The login URL is always printed.
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function registerComputer(appUrl, registrationToken, device, name) {
+  const registered = await requestJson(`${appUrl}/api/computers/register`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${registrationToken}`,
+    },
+    body: JSON.stringify({
+      device_id: device.device_id,
+      name,
+      platform: platformName(),
+      app_version: PACKAGE_VERSION,
+    }),
+  });
+
+  const record = {
+    ...registered,
+    app_url: appUrl,
+    name,
+    platform: platformName(),
+    app_version: PACKAGE_VERSION,
+    registered_at: new Date().toISOString(),
+  };
+  saveComputerRecord(record);
+
+  console.log(`Registered computer: ${record.computer_id}`);
+  console.log(`Events URL: ${record.webhook_url}`);
+  if (!proxyTokenFromRecord(record)) {
+    console.log('HMAC proxy: not minted yet; Amalgm-managed egress will refresh after registration is complete.');
+  }
+  console.log('Run `amalgm start` to connect this machine.');
+  return record;
+}
+
+async function refreshStoredProxyToken(record) {
+  const refreshToken = record?.computer_auth_token || record?.tunnel_token;
+  if (!refreshToken || !record?.computer_id || !record?.app_url) return record;
+  if (!proxyTokenNeedsRefresh(record)) return record;
+
+  const refreshed = await requestJson(`${record.app_url}/api/computers/proxy-token`, {
+    method: 'POST',
+    headers: {
+      authorization: `Bearer ${refreshToken}`,
+    },
+    body: JSON.stringify({
+      computer_id: record.computer_id,
+      device_id: record.device_id || '',
+    }),
+  });
+
+  const next = {
+    ...record,
+    proxy_token: refreshed.proxy_token || record.proxy_token,
+    proxy_token_expires_in: refreshed.proxy_token_expires_in || record.proxy_token_expires_in,
+    proxy_token_expires_at: refreshed.proxy_token_expires_at || record.proxy_token_expires_at,
+    proxy_token_refreshed_at: new Date().toISOString(),
+  };
+  return saveComputerRecord(next);
+}
+
+async function loginWithSetupCode(appUrl, setupCode, device, name) {
+  const normalizedCode = normalizeSetupCode(setupCode);
+  if (normalizedCode.length !== SETUP_CODE_LENGTH) {
+    throw new Error('Invalid setup code. It should look like ABCD-EFGH-JKLM-NPQR.');
+  }
+
+  console.log(`Connecting this computer to Amalgm as ${name}`);
+  const redeemed = await requestJson(`${appUrl}/api/auth/computer-setup/redeem`, {
+    method: 'POST',
+    body: JSON.stringify({
+      setup_code: normalizedCode,
+      device_id: device.device_id,
+      name,
+      platform: platformName(),
+      app_version: PACKAGE_VERSION,
+    }),
+  });
+
+  if (!redeemed.computer_registration_token) {
+    throw new Error('Setup code was accepted, but no registration token was returned.');
+  }
+
+  return registerComputer(appUrl, redeemed.computer_registration_token, device, name);
+}
+
+function appUrlFlag(appUrl) {
+  return appUrl === normalizeBaseUrl(DEFAULT_APP_URL) ? '' : ` --app-url ${JSON.stringify(appUrl)}`;
+}
+
+async function promptYesNo(question, defaultYes = true) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+
+  const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    const answer = await new Promise((resolve) => {
+      rl.question(`${question}${suffix}`, resolve);
+    });
+    const normalized = String(answer || '').trim().toLowerCase();
+    if (!normalized) return defaultYes;
+    return normalized === 'y' || normalized === 'yes';
+  } finally {
+    rl.close();
+  }
+}
+
+async function promptForFreshLogin(appUrl, device, name, options, reason) {
+  if (!(await promptYesNo(`${reason} Create a new setup code?`))) {
+    throw new Error('Login was not completed. Run `amalgm login` again to create a fresh setup code.');
+  }
+  return startCliLogin(appUrl, device, name, options);
+}
+
+async function startCliLogin(appUrl, device, name, options) {
+  console.log(`Starting Amalgm login for ${name}`);
+  const started = await requestJson(`${appUrl}/api/auth/computer-setup/cli/start`, {
+    method: 'POST',
+    body: JSON.stringify({
+      device_id: device.device_id,
+      name,
+      platform: platformName(),
+      app_version: PACKAGE_VERSION,
+    }),
+  });
+
+  if (!started.device_code || !started.setup_code || !started.verification_url) {
+    throw new Error('Login started, but the server did not return a setup URL.');
+  }
+
+  const setupCode = formatSetupCode(started.setup_code);
+  const verificationUrl = String(started.verification_url);
+  const manualCommand = `amalgm login --setup-code ${setupCode}${appUrlFlag(appUrl)}`;
+
+  console.log('');
+  if (!options['no-open'] && openBrowser(verificationUrl)) {
+    console.log('Opened your browser to finish login.');
+  } else {
+    console.log('Open this URL in any browser to finish login:');
+  }
+  console.log(verificationUrl);
+  console.log('');
+  console.log(`Setup code: ${setupCode}`);
+  console.log('');
+  console.log('Headless/SSH/container flow: approve the code in your browser, then paste this command back here if polling is unavailable:');
+  console.log(`  ${manualCommand}`);
+
+  if (options['no-poll']) {
+    console.log('');
+    console.log('Polling disabled. Run the command above after approving the setup code.');
+    return null;
+  }
+
+  const intervalMs = Math.max(1, Number(started.interval || 2)) * 1000;
+  const deadline = Date.now() + Math.max(60, Number(started.expires_in || 180)) * 1000;
+  let lastWaitingLog = 0;
+
+  console.log('');
+  console.log('Waiting for browser approval...');
+
+  while (Date.now() < deadline) {
+    let polled;
+    try {
+      polled = await requestJson(`${appUrl}/api/auth/computer-setup/cli/poll`, {
+        method: 'POST',
+        body: JSON.stringify({
+          device_code: started.device_code,
+          device_id: device.device_id,
+          name,
+          platform: platformName(),
+          app_version: PACKAGE_VERSION,
+        }),
+      });
+    } catch (error) {
+      if (error.status === 410) {
+        return promptForFreshLogin(appUrl, device, name, options, 'Setup code expired.');
+      }
+      throw error;
+    }
+
+    if (polled.status === 'approved' && polled.computer_registration_token) {
+      if (polled.approved_by?.label) {
+        console.log(`Approved by: ${polled.approved_by.label}`);
+      }
+      console.log('Browser approved. Registering this computer...');
+      return registerComputer(appUrl, polled.computer_registration_token, device, name);
+    }
+
+    if (polled.status === 'registered') {
+      console.log('This setup code is already registered. Run `amalgm status` to inspect local state.');
+      return null;
+    }
+
+    const now = Date.now();
+    if (now - lastWaitingLog > 15000) {
+      lastWaitingLog = now;
+      console.log('Still waiting for approval...');
+    }
+    await sleep(intervalMs);
+  }
+
+  return promptForFreshLogin(appUrl, device, name, options, 'Login timed out.');
+}
+
+async function login(options) {
+  ensureBaseDirs();
+  const appUrl = normalizeBaseUrl(options['app-url'] || DEFAULT_APP_URL);
+  const device = await ensureDevice();
+  const name = String(options.name || machineName()).slice(0, 120);
+  const setupCode = options['setup-code'] || options.code;
+
+  if (setupCode) {
+    return loginWithSetupCode(appUrl, setupCode, device, name);
+  }
+
+  return startCliLogin(appUrl, device, name, options);
+}
+
+function isPidRunning(pid) {
+  if (!pid || !Number.isInteger(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readPid() {
+  const raw = readJson(PID_FILE, null);
+  if (raw && Number.isInteger(raw.pid)) return raw.pid;
+  try {
+    const parsed = Number(fs.readFileSync(PID_FILE, 'utf8').trim());
+    return Number.isInteger(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function runningDaemonRestartReason(pid, record, localOnly) {
+  const state = readJson(RUNTIME_STATE_FILE, null);
+  const supervisorPid = Number(state?.supervisor_pid || state?.pid || 0);
+  if (!state || supervisorPid !== pid) return 'runtime ownership state is missing';
+  if (state.source && state.source !== 'npm') return `it is owned by ${state.source}`;
+  if (state.package_version && state.package_version !== PACKAGE_VERSION) {
+    return `it is running package ${state.package_version}, not ${PACKAGE_VERSION}`;
+  }
+  if (state.runtime_dir && state.runtime_dir !== RUNTIME_DIR) {
+    return 'it is running a different package install';
+  }
+  if (!!state.local_only !== !!localOnly) {
+    return localOnly ? 'it is running in registered mode' : 'it is running in local-only mode';
+  }
+  if (!localOnly && (state.computer_id || '') !== (record?.computer_id || '')) {
+    return `it is connected as ${state.computer_id || 'another computer'}`;
+  }
+  return '';
+}
+
+function ensureAgentRuntimeCommands(options = {}) {
+  const logger = options.logger || console;
+  const nativeResult = ensureNativeBinaries({ logger, quiet: !!options.quiet });
+  if (!nativeResult.ok) {
+    logger.warn?.(`Could not install all agent binaries: ${nativeResult.error?.message || 'unknown error'}`);
+    const missing = nativeResult.after.filter((item) => !item.ok).map((item) => item.name);
+    if (missing.length > 0) logger.warn?.(`Missing agents: ${missing.join(', ')}`);
+  } else if (nativeResult.installed && !options.quiet) {
+    logger.log?.('Agent binaries are ready.');
+  }
+
+  const shimResult = ensureAgentCommandShims({ logger, quiet: !!options.quiet });
+  if (!shimResult.ok) {
+    logger.warn?.(`Could not expose all agent commands: ${shimResult.error?.message || 'unknown error'}`);
+  }
+}
+
+async function update(options = {}) {
+  const tag = npmInstallTag(options);
+  const targetVersion = npmPackageVersionForTag(tag);
+  if (!targetVersion) throw new Error(`npm did not return a version for amalgm@${tag}`);
+
+  if (compareVersions(targetVersion, PACKAGE_VERSION) <= 0) {
+    console.log(`Amalgm is already current for ${tag}: ${PACKAGE_VERSION}`);
+    return false;
+  }
+
+  console.log(`Updating Amalgm from ${PACKAGE_VERSION} to ${targetVersion} (${tag}).`);
+  const result = installNpmPackageTag(tag);
+  if (result.status !== 0) {
+    throw new Error(`npm install -g amalgm@${tag} failed with status ${result.status ?? result.signal ?? 'unknown'}`);
+  }
+
+  console.log(`Amalgm updated to ${targetVersion}.`);
+  const pid = readPid();
+  if (isPidRunning(pid)) {
+    console.log('A previous Amalgm daemon is still running. Run `amalgm stop && amalgm start` to restart it with the new package.');
+  }
+  return true;
+}
+
+async function updateBeforeStartIfRequested(options = {}) {
+  const requested = options['auto-update'] || process.env.AMALGM_AUTO_UPDATE === '1';
+  if (!requested) return false;
+
+  try {
+    return await update(options);
+  } catch (error) {
+    console.warn(`Auto-update skipped: ${error.message}`);
+    return false;
+  }
+}
+
+async function start(options) {
+  ensureBaseDirs();
+
+  if (await updateBeforeStartIfRequested(options)) {
+    console.log('Run `amalgm start` again to launch the updated package.');
+    return;
+  }
+
+  assertRuntimePresent();
+
+  let record = loadComputerRecord({ migrate: true });
+  const localOnly = !!options['local-only'];
+  if (!localOnly && !hasRequiredComputerFields(record)) {
+    throw new Error('This machine is not logged in. Run `amalgm login` to authorize it in your browser, or use `amalgm start --local-only` for local-only development.');
+  }
+  if (!localOnly) {
+    try {
+      record = await refreshStoredProxyToken(record);
+    } catch (error) {
+      console.warn(`Could not refresh proxy token before start: ${error.message}`);
+    }
+  }
+
+  ensureAgentRuntimeCommands({ logger: console });
+
+  const pid = readPid();
+  if (isPidRunning(pid)) {
+    const restartReason = runningDaemonRestartReason(pid, record, localOnly);
+    if (!restartReason) {
+      console.log(`Amalgm is already running (pid ${pid}).`);
+      return;
+    }
+    console.log(`Amalgm is already running (pid ${pid}), but ${restartReason}. Restarting.`);
+    await stop();
+  }
+
+  const blockedPorts = await unavailableServicePorts();
+  if (blockedPorts.length > 0) {
+    const detail = blockedPorts.map(([name, port]) => `${name} (${port})`).join(', ');
+    throw new Error(`Cannot start Amalgm because explicitly configured port(s) are already in use: ${detail}`);
+  }
+
+  if (options.foreground) {
+    await startSupervisor({ foreground: true, localOnly });
+    return;
+  }
+
+  ensureDir(LOG_DIR);
+  const logPath = path.join(LOG_DIR, 'daemon.log');
+  const logFd = fs.openSync(logPath, 'a');
+  const child = spawn(process.execPath, [path.join(__dirname, '..', 'bin', 'amalgm.js'), 'run'], {
+    detached: true,
+    env: daemonEnv(localOnly),
+    stdio: ['ignore', logFd, logFd],
+    windowsHide: true,
+  });
+
+  child.unref();
+  fs.closeSync(logFd);
+  writeJsonSecret(PID_FILE, { pid: child.pid, started_at: new Date().toISOString() });
+  console.log(`Amalgm started (pid ${child.pid}).`);
+  console.log(`Logs: ${logPath}`);
+
+  const ready = await waitForServices(8000);
+  const pending = ready.filter(([, ok]) => !ok).map(([name]) => name);
+  if (pending.length === 0) {
+    console.log('Services: all local essentials are up.');
+  } else {
+    console.log(`Services still warming up: ${pending.join(', ')}. Run \`amalgm status\` or \`amalgm logs\` if they stay down.`);
+  }
+}
+
+async function stop() {
+  const pid = readPid();
+  if (!isPidRunning(pid)) {
+    try {
+      fs.unlinkSync(PID_FILE);
+    } catch {
+      // noop
+    }
+    console.log('Amalgm is not running.');
+    return;
+  }
+
+  process.kill(pid, 'SIGTERM');
+  for (let i = 0; i < 25; i += 1) {
+    await sleep(200);
+    if (!isPidRunning(pid)) break;
+  }
+
+  if (isPidRunning(pid)) {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch {
+      // noop
+    }
+  }
+
+  try {
+    fs.unlinkSync(PID_FILE);
+  } catch {
+    // noop
+  }
+  console.log('Amalgm stopped.');
+}
+
+async function checkHttp(port, pathName = '/healthz') {
+  return new Promise((resolve) => {
+    const req = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        path: pathName,
+        method: 'GET',
+        timeout: 1000,
+      },
+      (res) => {
+        res.resume();
+        res.on('end', () => resolve(res.statusCode >= 200 && res.statusCode < 500));
+      },
+    );
+    req.on('timeout', () => {
+      req.destroy();
+      resolve(false);
+    });
+    req.on('error', () => resolve(false));
+    req.end();
+  });
+}
+
+async function waitForServices(timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  let latest = [];
+  while (Date.now() < deadline) {
+    latest = [];
+    for (const [name, port] of servicePorts()) {
+      latest.push([name, await checkHttp(port)]);
+    }
+    if (latest.every(([, ok]) => ok)) return latest;
+    await sleep(300);
+  }
+  return latest;
+}
+
+async function status() {
+  const pid = readPid();
+  const record = loadComputerRecord({ migrate: true });
+  const runtimeState = readJson(RUNTIME_STATE_FILE, null);
+
+  console.log(`Daemon: ${isPidRunning(pid) ? `running (pid ${pid})` : 'stopped'}`);
+  console.log(`State: ${AMALGM_DIR}`);
+  if (runtimeState?.gateway_url) console.log(`Gateway: ${runtimeState.gateway_url}`);
+  console.log(
+    `Computer: ${
+      record?.computer_id
+        ? `${record.computer_id} (${record.name || record.device_id || 'unnamed'})`
+        : 'not logged in'
+    }`,
+  );
+  if (record?.webhook_url) console.log(`Events: ${record.webhook_url}`);
+  if (record?.tunnel_url) console.log(`Tunnel: ${record.tunnel_url}`);
+  if (record?.tunnel_token) {
+    console.log(`Chat tunnel: ${record.chat_tunnel_url || 'wss://amalgm-chat-gateway.fly.dev/wire'}`);
+  }
+  console.log(`HMAC proxy: ${proxyTokenFromRecord(record) ? 'configured' : 'not configured'}`);
+
+  for (const [name, port] of servicePorts()) {
+    const ok = await checkHttp(port);
+    console.log(`${name.padEnd(13)} ${ok ? 'up' : 'down'}  http://127.0.0.1:${port}`);
+  }
+}
+
+async function doctor() {
+  ensureBaseDirs();
+
+  const checks = [];
+  const add = (name, ok, detail = '', level = ok ? 'ok' : 'err') => {
+    checks.push({ name, ok, detail, level });
+  };
+
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  add('node', nodeMajor >= 20, process.version);
+
+  const missing = runtimeMissingFiles();
+  add('runtime', missing.length === 0, missing.length === 0 ? RUNTIME_DIR : `missing ${missing[0]}`);
+
+  const record = loadComputerRecord({ migrate: true });
+  add(
+    'login',
+    hasRequiredComputerFields(record),
+    record?.computer_id ? `computer ${record.computer_id}` : 'not logged in',
+  );
+  add(
+    'hmac proxy',
+    !!proxyTokenFromRecord(record),
+    proxyTokenFromRecord(record)
+      ? 'configured'
+      : 'pending server mint/refresh endpoint; BYOK/provider-auth can still run locally',
+    proxyTokenFromRecord(record) ? 'ok' : 'warn',
+  );
+
+  for (const agent of binaryStatus()) {
+    add(
+      `${agent.name} binary`,
+      agent.ok,
+      agent.ok ? agent.path : 'missing; `amalgm start` will try to install it',
+      agent.ok ? 'ok' : 'warn',
+    );
+  }
+  for (const shim of agentCommandShimStatus()) {
+    add(
+      `${shim.command} command`,
+      shim.ok,
+      shim.ok ? `${shim.path} (${shim.status})` : shim.status,
+      shim.ok ? 'ok' : 'warn',
+    );
+  }
+
+  const pid = readPid();
+  const daemonRunning = isPidRunning(pid);
+  add('daemon', daemonRunning, daemonRunning ? `pid ${pid}` : 'stopped', daemonRunning ? 'ok' : 'warn');
+
+  for (const [name, port] of servicePorts()) {
+    const envName = {
+      'local-gateway': 'AMALGM_GATEWAY_PORT',
+      'port-monitor': 'PORT_MONITOR_PORT',
+      'fs-watcher': 'FS_WATCHER_PORT',
+      'amalgm-mcp': 'AMALGM_MCP_PORT',
+      'chat-server': 'CHAT_SERVER_PORT',
+    }[name];
+    const ok = daemonRunning ? await checkHttp(port) : (!process.env[envName] || await isPortFree(port));
+    add(
+      `${name} port`,
+      ok,
+      daemonRunning
+        ? `http://127.0.0.1:${port}`
+        : (ok ? `available ${port}` : `configured port in use ${port}`),
+      ok ? 'ok' : (daemonRunning ? 'err' : 'warn'),
+    );
+  }
+
+  console.log('Amalgm doctor');
+  console.log(`State: ${AMALGM_DIR}`);
+  for (const check of checks) {
+    console.log(`${check.level.padEnd(4)} ${check.name.padEnd(18)} ${check.detail}`);
+  }
+
+  const failedBlocking = checks.filter((check) => check.level === 'err');
+  if (failedBlocking.length > 0) process.exitCode = 1;
+}
+
+function readLastLines(file, maxLines = 120) {
+  const stat = fs.statSync(file);
+  const bytes = Math.min(stat.size, 128 * 1024);
+  const fd = fs.openSync(file, 'r');
+  const buffer = Buffer.alloc(bytes);
+  fs.readSync(fd, buffer, 0, bytes, stat.size - bytes);
+  fs.closeSync(fd);
+  return buffer.toString('utf8').trimEnd().split('\n').slice(-maxLines).join('\n');
+}
+
+async function logs(options, positionals) {
+  const service = String(options.service || positionals[0] || 'daemon').replace(/[^a-z0-9_-]/gi, '');
+  const logPath = path.join(LOG_DIR, `${service}.log`);
+  if (!fs.existsSync(logPath)) {
+    throw new Error(`No log file found for "${service}" at ${logPath}`);
+  }
+  console.log(readLastLines(logPath, Number(options.lines || 120)));
+}
+
+async function logout() {
+  const record = loadComputerRecord({ migrate: true });
+  await stop();
+  if (record?.computer_auth_token && record?.app_url && record?.computer_id) {
+    try {
+      await requestJson(`${record.app_url}/api/computers/revoke`, {
+        method: 'POST',
+        headers: {
+          authorization: `Bearer ${record.computer_auth_token}`,
+        },
+        body: JSON.stringify({
+          computer_id: record.computer_id,
+          device_id: record.device_id || '',
+        }),
+      });
+      console.log('Revoked computer tokens on Amalgm.');
+    } catch (error) {
+      console.warn(`Remote revoke failed: ${error.message}`);
+    }
+  }
+  deleteComputerAuth();
+  try {
+    fs.unlinkSync(RUNTIME_TOKEN_FILE);
+  } catch {
+    // noop
+  }
+  console.log('Logged out locally. The device id remains so re-login updates the same computer.');
+}
+
+async function main(argv) {
+  const { command, options, positionals } = parseArgs(argv);
+
+  if (command === 'help' || command === '--help' || command === '-h') {
+    console.log(usage());
+    return;
+  }
+
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(PACKAGE_VERSION);
+    return;
+  }
+
+  if (command === 'login') return login(options);
+  if (command === 'start') return start(options);
+  if (command === 'run') {
+    return startSupervisor({
+      foreground: true,
+      localOnly: process.env.AMALGM_LOCAL_ONLY === 'true',
+    });
+  }
+  if (command === 'stop') return stop();
+  if (command === 'status') return status();
+  if (command === 'doctor') return doctor();
+  if (command === 'update') return update(options);
+  if (command === 'logs') return logs(options, positionals);
+  if (command === 'logout') return logout();
+
+  console.error(`Unknown command: ${command}`);
+  console.error('');
+  console.error(usage());
+  process.exitCode = 1;
+}
+
+module.exports = { main };