mobygate 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,82 @@ All notable changes to mobygate are documented here. Format loosely follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); version numbers are
 [Semantic Versioning](https://semver.org/).
 
+## [0.5.1] — 2026-04-19
+
+### Fixed
+
+- **Dashboard 404** on `/` after `npm install -g mobygate@latest` on
+  some fnm / npm-global setups. Root cause: Express 5's
+  `res.sendFile(absolutePath)` + `send` middleware was throwing a
+  spurious `NotFoundError` even when `index.html` was present on
+  disk. Replaced with `fs.readFile` + `res.send(html)` — more direct,
+  no middleware in between, and surfaces any real file-missing
+  problem as a readable HTML error page pointing at the fix.
+
+## [0.5.0] — 2026-04-19
+
+The "upgrade should just work" release. Closes an entire class of
+user-reported friction where a fresh `npm install -g mobygate@latest`
+would seemingly succeed but leave the dashboard showing the old
+version, the wrong server on :3456, or the browser serving stale HTML.
+
+### Added
+
+- **`Cache-Control: no-cache` headers on `/`** — browsers now always
+  re-fetch `index.html`, so a dashboard hard-reload is no longer
+  required after an upgrade. Fixes the most common "I see the old
+  dashboard after upgrade" report.
+- **`postinstall` npm hook** — on `npm install -g mobygate[@…]`, if a
+  mobygate service (launchd / systemd / Task Scheduler) is already
+  installed on the box, it gets auto-restarted so the new code is
+  the one running on :3456. Users no longer need to remember
+  `mobygate restart` or `mobygate update` after an `npm install`.
+  Silent on first install and in dev-clone `npm install` (doesn't
+  bounce your live server while you're editing).
+- **`mobygate doctor`** — diagnostic that reports:
+  - service-reported version vs CLI version (mismatch warning)
+  - port 3456 owner (flags non-mobygate processes holding the port)
+  - legacy launchd / systemd / Task Scheduler entries from prior
+    project names (claude-gate, claude-max-sdk-proxy) still present
+  - CLI-install path vs service-install path mismatch
+    (multi-node-version / fnm / nvm splits)
+  - auth state (logged-in, plan)
+  Prints a Recommended fix section with copy-pasteable commands.
+- **`mobygate init --yes` / `-y`** — non-interactive mode. Accepts
+  all prompts using existing config values or built-in defaults.
+  Makes the tool scriptable: you can now write a one-liner recovery
+  command for anyone stuck on an old install.
+- **Legacy service auto-cleanup in `mobygate init`** — before
+  installing new services, detects and removes launchd plists /
+  systemd units / Task Scheduler tasks under prior project names
+  (`ai.claude-gate.*`, `ai.claude-max-sdk-proxy.*`, etc.). Fixes the
+  "zombie old proxy still holding :3456" case that had friends
+  seeing the pre-v0.1.0 stub dashboard long after upgrading.
+- **Port auto-kill in `mobygate init`** — if anything is bound to
+  the target port when init runs, it's killed (LISTEN sockets
+  only — won't kill active clients). Guarantees the new service
+  can bind :3456 cleanly.
+
+### Fixed
+
+- `doctor` / `killPort` filter `lsof -sTCP:LISTEN` so a browser tab
+  or `curl` connection *to* the port is no longer misidentified as
+  the owner of the port.
+
+### Recovery flow
+
+A user on any prior generation (including the pre-rename
+claude-max-sdk-proxy) can now catch up with a single command:
+
+```
+npm install -g mobygate@latest && mobygate init --yes
+```
+
+The postinstall hook restarts any existing mobygate service, and
+`init --yes` cleans up legacy services, frees the port, re-writes
+the service definition for this machine's paths, and restarts.
+No manual `lsof | xargs kill`, no browser hard-reload required.
+
 ## [0.4.0] — 2026-04-19
 
 ### Added

package/bin/mobygate.js

@@ -35,6 +35,7 @@ import {
   installLinuxServices, uninstallLinuxServices,
   queryLinuxUnit, startLinuxUnit, stopLinuxUnit, LINUX_UNITS,
   nonMacInstallInstructions,
+  cleanupLegacyServices, killPort,
 } from '../lib/platform.js';
 import { getAuthStatus, forceRefresh } from '../scripts/auth-helper.js';
 import { banner, compactBanner } from '../lib/ascii.js';
@@ -96,8 +97,12 @@ async function confirm(q, def = true) {
 
 async function cmdInit() {
   const pkg = readPackage();
+  // --yes / -y skips prompts (uses defaults or existing config values),
+  // makes `mobygate init` scriptable for unattended upgrades.
+  const nonInteractive = process.argv.includes('--yes') || process.argv.includes('-y');
   print(banner({ version: pkg.version }));
   section('mobygate init');
+  if (nonInteractive) print(c.dim('(non-interactive — using existing config and defaults)'));
   print(c.dim(`Platform: ${PLATFORM}  Install path: ${REPO_ROOT}`));
   print(c.dim(`Config:   ${CONFIG_PATH}`));
   print('');
@@ -113,8 +118,10 @@ async function cmdInit() {
     warn('`claude` CLI not found on PATH.');
     print(c.dim('  The proxy uses Claude Code\'s CLI to resolve OAuth credentials.'));
     print(c.dim('  Install: https://docs.claude.com/en/docs/claude-code'));
-    const proceed = await confirm('Continue anyway? (you can set CLAUDE_BIN in config.yaml later)', false);
-    if (!proceed) die('Aborted.');
+    if (!nonInteractive) {
+      const proceed = await confirm('Continue anyway? (you can set CLAUDE_BIN in config.yaml later)', false);
+      if (!proceed) die('Aborted.');
+    }
   } else {
     ok(`claude CLI at ${claudeProbe.stdout.trim().split('\n')[0]}`);
   }
@@ -127,22 +134,47 @@ async function cmdInit() {
     } else {
       warn('Not logged into Claude Max.');
       print(c.dim('  Run `claude auth login` in another terminal, then re-run `mobygate init`.'));
-      const proceed = await confirm('Continue without login?', false);
-      if (!proceed) die('Aborted.');
+      if (!nonInteractive) {
+        const proceed = await confirm('Continue without login?', false);
+        if (!proceed) die('Aborted.');
+      }
     }
   } catch (e) {
     warn(`Couldn't check auth status: ${e.message}`);
   }
 
+  // ---- Clean up any legacy service / zombie process on our port ----
+  // Idempotent — runs every init. Removes launchd/systemd/Task Scheduler
+  // entries left behind by claude-max-sdk-proxy / claude-gate / any prior
+  // generation, and kills anything currently bound to :3456 so the new
+  // service can claim it without collision.
+  section('Cleanup');
+  const cleaned = cleanupLegacyServices();
+  const removed = cleaned.filter((r) => r.removed);
+  if (removed.length) {
+    for (const r of removed) ok(`Removed legacy ${r.label}`);
+  } else {
+    print(c.dim('  No legacy services found.'));
+  }
+  const targetPort = parseInt(process.env.PORT || String(loadConfig().port), 10) || 3456;
+  const killed = killPort(targetPort);
+  if (killed.length) ok(`Freed port ${targetPort} (killed pid${killed.length > 1 ? 's' : ''} ${killed.join(', ')})`);
+  else print(c.dim(`  Port ${targetPort} is free.`));
+
   // ---- Config ----
   section('Configuration');
   const existing = loadConfig();
-  const port = await prompt('HTTP port', String(existing.port));
-  const defaultModel = await prompt('Default model', existing.default_model);
-  const sessionTtl = await prompt('Session TTL (minutes)', String(existing.session_ttl_minutes));
-  const claudeBin = claudeProbe.status === 0
-    ? (await prompt('CLAUDE_BIN override (blank = PATH)', existing.claude_bin || ''))
-    : (await prompt('CLAUDE_BIN (absolute path to claude binary)', existing.claude_bin || ''));
+  // With --yes, inherit existing values / defaults without prompting
+  const port = nonInteractive ? String(existing.port)
+    : await prompt('HTTP port', String(existing.port));
+  const defaultModel = nonInteractive ? existing.default_model
+    : await prompt('Default model', existing.default_model);
+  const sessionTtl = nonInteractive ? String(existing.session_ttl_minutes)
+    : await prompt('Session TTL (minutes)', String(existing.session_ttl_minutes));
+  const claudeBin = nonInteractive ? (existing.claude_bin || '')
+    : (claudeProbe.status === 0
+        ? (await prompt('CLAUDE_BIN override (blank = PATH)', existing.claude_bin || ''))
+        : (await prompt('CLAUDE_BIN (absolute path to claude binary)', existing.claude_bin || '')));
 
   const configPath = writeConfig({
     port: parseInt(port, 10) || 3456,
@@ -408,6 +440,105 @@ function cmdVersion() {
   print(`mobygate v${pkg.version} · ${detectInstallMode()} install at ${REPO_ROOT}`);
 }
 
+/**
+ * Diagnostic command — identifies the classes of problem users have hit
+ * during upgrades (CLI vs service version mismatch, zombie old services,
+ * port-3456 owned by something else, node-version split). Prints one
+ * line per finding + a recommended fix at the end.
+ */
+async function cmdDoctor() {
+  const pkg = readPackage();
+  const mode = detectInstallMode();
+  section('mobygate doctor');
+  print(c.dim(`CLI: v${pkg.version} · ${mode} install at ${REPO_ROOT}`));
+  const issues = [];
+  const fixes = [];
+
+  // 1. Version reported by the running service (via /dashboard/recent)
+  let serviceVersion = null;
+  try {
+    const port = loadConfig().port;
+    const r = await fetch(`http://localhost:${port}/dashboard/recent`, { signal: AbortSignal.timeout(2000) });
+    const j = await r.json();
+    serviceVersion = j.build?.version || null;
+  } catch (e) { /* server down or pre-v0.2.0 */ }
+  if (!serviceVersion) {
+    warn('Service on :3456 is not responding / older than v0.2.0');
+    issues.push('service-down-or-ancient');
+  } else {
+    const match = serviceVersion === pkg.version;
+    (match ? ok : warn)(`Service on :3456 reports v${serviceVersion}${match ? '' : ` (CLI is v${pkg.version} — mismatch)`}`);
+    if (!match) {
+      issues.push('version-mismatch');
+      fixes.push('mobygate restart');
+    }
+  }
+
+  // 2. Port owner — filter to LISTEN state so we don't flag clients that
+  // happen to be *connected to* :3456 (browser tabs, curl) as owners.
+  if (IS_MAC || IS_LINUX) {
+    const r = spawnSync('sh', ['-c', `lsof -ti :${loadConfig().port} -sTCP:LISTEN 2>/dev/null`], { encoding: 'utf8' });
+    const pid = (r.stdout || '').trim().split('\n').filter(Boolean)[0];
+    if (pid) {
+      const ps = spawnSync('ps', ['-p', pid, '-o', 'command='], { encoding: 'utf8' });
+      const cmdline = (ps.stdout || '').trim();
+      if (cmdline && !cmdline.includes('mobygate')) {
+        warn(`:${loadConfig().port} is owned by NON-mobygate pid ${pid}: ${cmdline.slice(0, 80)}`);
+        issues.push('port-owned-by-foreign-process');
+        fixes.push(`lsof -ti :${loadConfig().port} -sTCP:LISTEN | xargs kill && mobygate init --yes`);
+      } else {
+        print(c.dim(`  port ${loadConfig().port} held by mobygate pid ${pid}.`));
+      }
+    }
+  }
+
+  // 3. Legacy service entries we haven't cleaned yet
+  if (IS_MAC) {
+    const legacyFound = [];
+    for (const lbl of ['ai.claude-gate.server','ai.claude-gate.auth-refresh','ai.claude-max-sdk-proxy.server','ai.claude-max-sdk-proxy.auth-refresh']) {
+      const p = join(process.env.HOME, 'Library', 'LaunchAgents', `${lbl}.plist`);
+      if (existsSync(p)) legacyFound.push(lbl);
+    }
+    if (legacyFound.length) {
+      warn(`Legacy launchd plists found: ${legacyFound.join(', ')}`);
+      issues.push('legacy-services');
+      fixes.push('mobygate init --yes   # cleans up legacy entries');
+    }
+  }
+
+  // 4. CLI mobygate vs service install path (multi-node-version detection)
+  const state = readState();
+  if (state && state.install_path && state.install_path !== REPO_ROOT) {
+    warn(`CLI install (${REPO_ROOT}) differs from service install (${state.install_path})`);
+    issues.push('install-path-split');
+    fixes.push('mobygate init --yes   # rebinds service to the current CLI location');
+  }
+
+  // 5. /auth/status
+  try {
+    const r = await fetch(`http://localhost:${loadConfig().port}/auth/status?quick=1`, { signal: AbortSignal.timeout(2000) });
+    const j = await r.json();
+    if (!j.loggedIn) {
+      warn('Not logged in to Claude — run `claude auth login`');
+      issues.push('not-logged-in');
+      fixes.push('claude auth login');
+    } else {
+      ok(`Auth: ${j.email || 'logged in'} (${j.subscriptionType || j.authMethod})`);
+    }
+  } catch { /* already reported via service-down */ }
+
+  // Summary
+  print('');
+  if (!issues.length) {
+    ok('No problems detected. Everything looks healthy.');
+  } else {
+    section('Recommended fix');
+    for (const f of fixes) print(`  ${c.cyan(f)}`);
+    print('');
+    print(c.dim(`${issues.length} issue${issues.length > 1 ? 's' : ''} found: ${issues.join(', ')}`));
+  }
+}
+
 /**
  * Upgrade mobygate to the latest version from its source of truth:
  *   - `npm` mode → `npm install -g mobygate@latest`
@@ -474,8 +605,9 @@ function usage() {
   print(`mobygate — OpenAI → Claude Max local gateway
 
 Usage:
-  mobygate init       Interactive setup: config, services, smoke test
+  mobygate init       Interactive setup (add --yes to skip prompts)
   mobygate update     Upgrade to the latest version + restart service
+  mobygate doctor     Diagnose version mismatches, zombie services, port conflicts
   mobygate start      Start the proxy service
   mobygate stop       Stop the proxy service
   mobygate restart    Stop + start
@@ -497,6 +629,7 @@ const COMMANDS = {
   init: cmdInit,
   update: cmdUpdate,
   upgrade: cmdUpdate,
+  doctor: cmdDoctor,
   start: cmdStart,
   stop: cmdStop,
   restart: cmdRestart,

package/lib/platform.js

@@ -328,6 +328,110 @@ export const WIN_LABELS = {
   auth: WIN_AUTH_TASK,
 };
 
+// ---------------------------------------------------------------------------
+// Legacy / zombie service cleanup — invoked by `mobygate init` so upgrades
+// from any prior generation (claude-max-sdk-proxy / claude-gate / brother's
+// forks) never leave an old process competing with the new one on :3456.
+// ---------------------------------------------------------------------------
+
+const LEGACY_MAC_LABELS = [
+  'ai.claude-max-sdk-proxy.server',
+  'ai.claude-max-sdk-proxy.auth-refresh',
+  'ai.claude-gate.server',
+  'ai.claude-gate.auth-refresh',
+];
+const LEGACY_LINUX_UNITS = [
+  'claude-max-sdk-proxy.service',
+  'claude-gate-server.service',
+  'claude-gate-auth.service',
+  'claude-gate-auth.timer',
+];
+const LEGACY_WIN_TASKS = [
+  'claude-max-sdk-proxy-server',
+  'claude-max-sdk-proxy-auth-refresh',
+  'claude-gate-server',
+  'claude-gate-auth-refresh',
+];
+
+/**
+ * Remove all known legacy service entries. Returns a list of
+ * { platform, label, removed } for each attempt so callers can log.
+ * Safe to run every `mobygate init` — no-op if nothing matches.
+ */
+export function cleanupLegacyServices() {
+  const results = [];
+  if (IS_MAC) {
+    for (const label of LEGACY_MAC_LABELS) {
+      const p = join(LAUNCH_AGENTS_DIR, `${label}.plist`);
+      if (!existsSync(p)) { results.push({ label, removed: false, reason: 'absent' }); continue; }
+      try { execSync(`launchctl unload "${p}" 2>/dev/null`, { stdio: 'ignore' }); } catch {}
+      try { unlinkSync(p); results.push({ label, removed: true }); }
+      catch (e) { results.push({ label, removed: false, error: e.message }); }
+    }
+  } else if (IS_LINUX) {
+    for (const unit of LEGACY_LINUX_UNITS) {
+      const r = systemctlUser(['disable', '--now', unit]);
+      const p = join(SYSTEMD_USER_DIR, unit);
+      if (existsSync(p)) {
+        try { unlinkSync(p); results.push({ label: unit, removed: true }); }
+        catch (e) { results.push({ label: unit, removed: false, error: e.message }); }
+      } else {
+        results.push({ label: unit, removed: false, reason: 'absent' });
+      }
+    }
+    systemctlUser(['daemon-reload']);
+  } else if (IS_WIN) {
+    for (const task of LEGACY_WIN_TASKS) {
+      const r = runPowershell(`
+        $t = Get-ScheduledTask -TaskName '${task}' -ErrorAction SilentlyContinue
+        if ($t) {
+          Stop-ScheduledTask -TaskName '${task}' -ErrorAction SilentlyContinue
+          Unregister-ScheduledTask -TaskName '${task}' -Confirm:$false
+          Write-Output 'removed'
+        } else { Write-Output 'absent' }
+      `);
+      if (r.ok) results.push({ label: task, removed: r.stdout === 'removed', reason: r.stdout });
+      else results.push({ label: task, removed: false, error: r.stderr });
+    }
+  }
+  return results;
+}
+
+/**
+ * Kill whatever currently owns the given port. Best-effort across platforms.
+ * Returns the list of PIDs killed (empty if nothing was bound).
+ */
+export function killPort(port) {
+  const killed = [];
+  if (IS_MAC || IS_LINUX) {
+    try {
+      // Filter to LISTEN state so we don't kill clients connected to :port
+      const r = spawnSync('sh', ['-c', `lsof -ti :${port} -sTCP:LISTEN 2>/dev/null || true`], { encoding: 'utf8' });
+      const pids = (r.stdout || '').trim().split('\n').filter(Boolean);
+      for (const pid of pids) {
+        try { process.kill(parseInt(pid, 10), 'SIGTERM'); killed.push(pid); } catch {}
+      }
+      if (pids.length) {
+        // Give graceful shutdown a moment, then force
+        setTimeout(() => {
+          for (const pid of pids) { try { process.kill(parseInt(pid, 10), 'SIGKILL'); } catch {} }
+        }, 500);
+      }
+    } catch {}
+  } else if (IS_WIN) {
+    const r = runPowershell(`
+      $c = Get-NetTCPConnection -LocalPort ${port} -ErrorAction SilentlyContinue
+      if ($c) {
+        $c | ForEach-Object {
+          try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue; Write-Output $_.OwningProcess } catch {}
+        }
+      }
+    `);
+    if (r.ok && r.stdout) killed.push(...r.stdout.split(/\r?\n/).filter(Boolean));
+  }
+  return killed;
+}
+
 // ---------------------------------------------------------------------------
 // Linux — systemd user units
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mobygate",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "OpenAI-compatible local proxy for Claude Max. The Möbius-strip gateway: OpenAI shape in, Claude Max out.",
   "type": "module",
   "main": "server.js",
   "bin": {
-    "mobygate": "./bin/mobygate.js"
+    "mobygate": "bin/mobygate.js"
   },
   "scripts": {
     "start": "node server.js",
@@ -13,7 +13,8 @@
     "up": "npm install && node server.js",
     "auth:status": "node scripts/auth-status.js",
     "auth:status:quick": "node scripts/auth-status.js --quick",
-    "auth:refresh": "node scripts/auth-refresh.js"
+    "auth:refresh": "node scripts/auth-refresh.js",
+    "postinstall": "node scripts/postinstall.js || true"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.112",

package/scripts/postinstall.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * mobygate postinstall hook.
+ *
+ * Runs automatically after `npm install -g mobygate` (and any fresh
+ * `npm install` in a dev clone). Its job: if a previous mobygate
+ * service is already registered on this box (launchd / systemd /
+ * Task Scheduler), restart it so the newly-updated code is what's
+ * actually running on :3456.
+ *
+ * Without this, `npm install -g mobygate@latest` updates files on
+ * disk but leaves the old process running — users have to remember
+ * to also run `mobygate restart` or `mobygate update`. This hook
+ * makes upgrades one-command.
+ *
+ * Silent on first install (no service exists yet → nothing to
+ * restart). Silent on CI / npm install in odd contexts (no
+ * permission, no launchctl available, etc.) — never fails the
+ * install. Worst case: prints a line saying it couldn't auto-
+ * restart, user runs `mobygate restart` themselves.
+ */
+
+import { existsSync } from 'fs';
+import { homedir, platform } from 'os';
+import { join } from 'path';
+import { execSync, spawnSync } from 'child_process';
+
+// Skip during `npm install` inside this package's own dev clone —
+// you don't want `npm install` as a developer to restart your live
+// service every save. Skip when npm's lifecycle event is "install"
+// and the cwd isn't a global install.
+const isGlobalInstall = (process.env.npm_config_global === 'true')
+  || !!process.env.npm_lifecycle_event && process.env.npm_config_prefix;
+if (!isGlobalInstall && process.env.npm_package_name === 'mobygate') {
+  // Developer install — skip, don't surprise them by bouncing their server
+  process.exit(0);
+}
+
+const plat = platform();
+const log = (...args) => process.stderr.write('[mobygate postinstall] ' + args.join(' ') + '\n');
+
+try {
+  if (plat === 'darwin') {
+    const plist = join(homedir(), 'Library', 'LaunchAgents', 'ai.mobygate.server.plist');
+    if (!existsSync(plist)) process.exit(0);          // first install, no service yet
+    try { execSync(`launchctl unload "${plist}"`, { stdio: 'ignore' }); } catch {}
+    try { execSync(`launchctl load "${plist}"`, { stdio: 'ignore' }); } catch (e) {
+      log(`couldn't reload ai.mobygate.server — run \`mobygate restart\` manually`);
+      process.exit(0);
+    }
+    log('auto-restarted ai.mobygate.server (launchd)');
+  } else if (plat === 'linux') {
+    const r = spawnSync('systemctl', ['--user', 'is-active', 'mobygate-server.service'], { encoding: 'utf8' });
+    if (r.stdout?.trim() !== 'active') process.exit(0); // not running → first install or disabled
+    const restart = spawnSync('systemctl', ['--user', 'restart', 'mobygate-server.service'], { encoding: 'utf8' });
+    if (restart.status !== 0) {
+      log('couldn\'t restart mobygate-server.service — run `mobygate restart` manually');
+      process.exit(0);
+    }
+    log('auto-restarted mobygate-server (systemd user)');
+  } else if (plat === 'win32') {
+    // Detect task presence, then restart via PowerShell
+    const ps = spawnSync('powershell', [
+      '-NoProfile', '-Command',
+      `$t = Get-ScheduledTask -TaskName 'mobygate-server' -ErrorAction SilentlyContinue
+       if (-not $t) { exit 0 }
+       Stop-ScheduledTask -TaskName 'mobygate-server' -ErrorAction SilentlyContinue
+       Start-Sleep -Milliseconds 500
+       Start-ScheduledTask -TaskName 'mobygate-server'
+       Write-Output 'ok'`,
+    ], { encoding: 'utf8', windowsHide: true });
+    if (ps.status === 0 && ps.stdout?.includes('ok')) {
+      log('auto-restarted mobygate-server (Task Scheduler)');
+    } else if (ps.status === 0) {
+      // Task didn't exist — first install, silent
+    } else {
+      log("couldn't restart mobygate-server — run `mobygate restart` manually");
+    }
+  }
+} catch (e) {
+  // Never fail the npm install for any reason
+  log(`postinstall skipped: ${e.message}`);
+  process.exit(0);
+}

package/server.js

@@ -785,9 +785,36 @@ async function handleNonStreaming(res, body, requestId, sessionKey) {
 const app = express();
 app.use(express.json({ limit: '10mb' }));
 
-// GET / — serve dashboard
-app.get('/', (_req, res) => {
-  res.sendFile(join(__dirname, 'index.html'));
+// GET / — serve dashboard. No-cache headers so browsers always re-fetch
+// after a mobygate upgrade; otherwise they keep serving the old index.html
+// from cache and users see a stale dashboard long after the service updated.
+//
+// We use fs.readFile + res.send instead of res.sendFile because Express 5's
+// sendFile + send middleware has produced spurious 404s in npm-global fnm
+// installs even when the file definitely exists — likely an interaction
+// between ESM __dirname resolution and send's internal path checks.
+// readFile is straightforward and gives us a real error to log if the
+// file genuinely is missing.
+app.get('/', async (_req, res) => {
+  res.setHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
+  res.setHeader('Pragma', 'no-cache');
+  res.setHeader('Expires', '0');
+  try {
+    const { readFile } = await import('fs/promises');
+    const html = await readFile(join(__dirname, 'index.html'), 'utf8');
+    res.type('html').send(html);
+  } catch (e) {
+    res.status(500).type('html').send(
+      `<!doctype html><meta charset=utf-8><title>mobygate — dashboard unavailable</title>
+       <body style="background:#0B0B09;color:#F3EFE4;font-family:ui-monospace,monospace;padding:2rem">
+       <h1>Dashboard failed to load</h1>
+       <p>Server is running fine — the dashboard HTML is just missing from the install.</p>
+       <pre>Path tried:   ${join(__dirname, 'index.html')}</pre>
+       <pre>Error:        ${e.code || ''} ${e.message}</pre>
+       <p>Fix: <code>npm install -g mobygate@latest --force</code></p>
+       </body>`
+    );
+  }
 });
 
 // POST /v1/chat/completions