@oar-sh/oar 0.9.8 → 0.9.10

package/server/services/oar-cli-helpers.mjs

@@ -1,5 +1,5 @@
 /**
- * Pure helpers behind `oar setup` and `oar doctor` — everything here is
+ * Pure helpers behind the `oar` command line — everything here is
  * deterministic and unit-testable; the interactive glue stays in bin/oar.js.
  */
 
@@ -41,6 +41,135 @@ export function relayUrl({ config, lanAddress = null } = {}) {
   return `http://${host}:${config?.port || 3333}/?token=${encodeURIComponent(token)}`;
 }
 
+/**
+ * What `oar setup` and `oar url` print about the relay's address. `qrUrl` is
+ * set only for an address a phone can reach: the LAN address when LAN access
+ * is on, and never one that is internal to WSL. `tunnelUrl` is the address a
+ * running relay reports for its tunnel, with the token added.
+ */
+export function describeRelayAddress({ config, lanAddress = null, wslNat = false, tunnelBase = '' } = {}) {
+  const lan = config?.localhostOnly === false;
+  const url = relayUrl({ config: { ...config, localhostOnly: !lan }, lanAddress });
+  const lines = [`[oar] Relay URL: ${url}`];
+  let qrUrl = null;
+  if (!lan) {
+    lines.push('[oar] This machine only. For a phone, switch on LAN access (oar setup --lan) or use a tunnel (README: Remote access).');
+  } else if (!lanAddress) {
+    lines.push('[oar] LAN access is on, but this machine has no network address.');
+  } else if (wslNat) {
+    lines.push('[oar] That address is internal to WSL; other devices cannot reach it. Ways out: a tunnel (README: Remote access), or WSL\'s mirrored networking (networkingMode=mirrored in .wslconfig).');
+  } else {
+    qrUrl = url;
+  }
+  const base = String(tunnelBase || '').trim().replace(/\/+$/, '');
+  const tunnelUrl = base ? `${base}/?token=${encodeURIComponent(String(config?.authToken || '').trim())}` : null;
+  return { url, lines, qrUrl, tunnelUrl };
+}
+
+const VALUE_OPTIONS = ['--port', '--migrate-from', '--to'];
+const LAUNCHER_FLAGS = ['--install-extension', '--no-install-extension', '--migrate-from'];
+const COMMAND_OPTIONS = { '--setup': 'setup', '--start': 'start', '--stop': 'stop', '--status': 'status' };
+const CLI_COMMANDS = {
+  menu: {},
+  start: {},
+  stop: {},
+  restart: {},
+  status: {},
+  url: {},
+  doctor: {},
+  help: {},
+  version: {},
+  setup: { flags: ['--lan', '--local', '--new-token', '--defaults', '--start'], values: ['--port', '--migrate-from'] },
+  service: { words: ['install', 'remove', 'status'] },
+  update: { flags: ['--beta'], values: ['--to'] },
+  copilot: { flags: ['--install-extension', '--no-install-extension'], values: ['--port', '--migrate-from'], forwards: true },
+};
+
+export function usageText() {
+  return [
+    'Usage: oar [command] [options]',
+    '',
+    '  oar                    Menu in a terminal; status and this text elsewhere',
+    '  oar start              Start the relay in the background',
+    '  oar stop               Stop the relay (waits for running turns)',
+    '  oar restart            Restart the relay (waits for running turns)',
+    '  oar status             Is the relay running, on which port, as a service',
+    '  oar url                Relay URL, with a QR code when a phone can reach it',
+    '  oar setup              Auth token, access and port; asks, or takes',
+    '                         [--port <port>] [--lan | --local] [--new-token] [--defaults] [--start]',
+    '  oar service install | remove | status',
+    '                         Start the relay at login',
+    '  oar copilot [--port <port>] [--install-extension] [--no-install-extension] [-- gh copilot args...]',
+    '                         Relay plus a Copilot terminal session',
+    '  oar doctor             Check the install and the provider CLIs',
+    '  oar update [--beta] [--to <version>]',
+    '  oar help               This text',
+    '  oar --version',
+  ].join('\n');
+}
+
+/**
+ * Reads the command line into `{ command, args }`, or `{ error }` for anything
+ * `oar` does not know, so nothing starts by accident. The command may follow
+ * options (`oar --port 3339 setup`), and `--setup`, `--start`, `--stop` and
+ * `--status` name it too. Without a command the launcher's own flags (or a
+ * `--` part) mean the Copilot session, and nothing at all means the menu.
+ */
+export function parseCliArgs(argv = []) {
+  const all = (Array.isArray(argv) ? argv : []).map((arg) => String(arg));
+  const separator = all.indexOf('--');
+  const head = separator === -1 ? all : all.slice(0, separator);
+  const forwarded = separator === -1 ? [] : all.slice(separator);
+  if (head.includes('--help') || head.includes('-h')) return { command: 'help', args: [] };
+
+  let command = null;
+  let args = [];
+  for (let index = 0; index < head.length; index += 1) {
+    const arg = head[index];
+    if (VALUE_OPTIONS.includes(arg)) {
+      if (index + 1 >= head.length) return { error: `${arg} needs a value.` };
+      args.push(arg, head[index += 1]);
+    } else if (arg.startsWith('-') || command) {
+      args.push(arg);
+    } else {
+      command = arg;
+    }
+  }
+  if (!command) {
+    const named = args.includes('--setup') ? '--setup' : args.find((arg) => COMMAND_OPTIONS[arg]);
+    if (args.includes('--version') || args.includes('-v')) return { command: 'version', args: [] };
+    if (named) {
+      command = COMMAND_OPTIONS[named];
+      args.splice(args.indexOf(named), 1);
+    } else if (forwarded.length || args.some((arg) => LAUNCHER_FLAGS.includes(arg))) {
+      command = 'copilot';
+    } else if (!args.length) {
+      command = 'menu';
+    } else {
+      // An option this command line knows needs its command; any other is unknown.
+      const known = [...VALUE_OPTIONS, '--lan', '--local', '--new-token', '--defaults', '--beta'];
+      return { error: known.includes(args[0]) ? `${args[0]} needs a command.` : `Unknown option: ${args[0]}` };
+    }
+  }
+
+  const spec = Object.hasOwn(CLI_COMMANDS, command) ? CLI_COMMANDS[command] : null;
+  if (!spec) return { error: `Unknown command: ${command}` };
+  if (forwarded.length && !spec.forwards) return { error: `oar ${command} takes no "--" part.` };
+  let words = 0;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const name = arg.startsWith('--') ? arg.split('=')[0] : arg;
+    if (spec.values?.includes(name)) {
+      if (arg === name) index += 1;
+    } else if (spec.words?.includes(arg) && words === 0) {
+      words += 1;
+    } else if (!spec.flags?.includes(arg)) {
+      return { error: arg.startsWith('-') ? `Unknown option for oar ${command}: ${arg}` : `Unexpected argument: ${arg}` };
+    }
+  }
+  return { command, args: [...args, ...forwarded] };
+}
+
 /**
  * A systemd *user* unit for the relay server. The launcher is not used here —
  * the service runs server.js directly with the same env the launcher would set,
@@ -102,7 +231,7 @@ export function buildServicePath({ nodeBin, envPath = '', homeDir = '' } = {}) {
  * accept the flag and run the scripts as before. `npm-install-scripts.test.mjs`
  * holds this list to the lockfile.
  */
-export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['better-sqlite3', 'cloudflared', 'koffi']);
+export const NPM_INSTALL_SCRIPT_PACKAGES = Object.freeze(['better-sqlite3', 'koffi']);
 export const NPM_ALLOW_SCRIPTS_ARG = `--allow-scripts=${NPM_INSTALL_SCRIPT_PACKAGES.join(',')}`;
 
 /**
@@ -155,6 +284,8 @@ export function renderDoctorReport({
   dbPath,
   dbSizeBytes,
   probes = [],
+  warnings = [],
+  tunnel = '',
 }) {
   const yesNo = (v) => (v ? 'yes' : 'no');
   const lines = [
@@ -167,13 +298,17 @@ export function renderDoctorReport({
   if (config) {
     lines.push(`  port          : ${config.port ?? 3333} (localhostOnly: ${yesNo(config.localhostOnly !== false)})`);
     lines.push(`  auth token    : ${String(config.authToken || '').trim() ? 'set' : 'MISSING'}`);
-    const tunnel = config.cloudflaredTunnel || {};
-    lines.push(`  tunnel        : ${tunnel.enabled === true || tunnel.mode === 'managed' ? 'managed' : 'disabled'}`);
+    // `tunnel` is the caller's finding (describeConfiguredTunnel: is the tunnel
+    // on, and is there a cloudflared to run it); without one, the config's word.
+    const tunnelConfig = config.cloudflaredTunnel || {};
+    const configured = tunnelConfig.enabled === true || tunnelConfig.mode === 'managed' ? 'managed' : 'disabled';
+    lines.push(`  tunnel        : ${tunnel || configured}`);
   }
   lines.push(`  database      : ${dbSizeBytes !== null ? `${dbPath} (${(dbSizeBytes / 1048576).toFixed(1)} MB)` : `${dbPath} (not created yet)`}`);
   lines.push('  provider CLIs :');
   for (const probe of probes) {
     lines.push(`    ${probe.id.padEnd(14)}: ${probe.ok ? probe.version || 'installed' : 'not found'}`);
   }
+  for (const warning of warnings) lines.push(`  warning       : ${warning}`);
   return lines.join('\n');
 }

package/server/services/oar-cli-menu.mjs

@@ -0,0 +1,240 @@
+/**
+ * The terminal side of `oar`: line prompts and the menu. Everything reads
+ * from and writes to the stream pair it is given, so tests drive it with
+ * fake streams.
+ */
+
+import readline from 'node:readline';
+
+/** Ctrl+C (or a closed input) in a prompt or in the menu; `oar` exits 130 on it, without a message. */
+export class PromptAborted extends Error {
+  constructor() {
+    super('Aborted');
+    this.code = 'OAR_PROMPT_ABORTED';
+  }
+}
+
+export function askLine(question, { input = process.stdin, output = process.stdout } = {}) {
+  return new Promise((resolve, reject) => {
+    let rl;
+    try {
+      rl = readline.createInterface({ input, output, terminal: Boolean(input.isTTY) });
+    } catch {
+      // A terminal that refuses raw mode still reads whole lines.
+      rl = readline.createInterface({ input, output, terminal: false });
+    }
+    let settled = false;
+    const abort = () => {
+      if (settled) return;
+      settled = true;
+      rl.close();
+      output.write('\n');
+      reject(new PromptAborted());
+    };
+    rl.once('SIGINT', abort);
+    rl.once('close', abort);
+    rl.question(question, (answer) => {
+      settled = true;
+      rl.close();
+      resolve(String(answer).trim());
+    });
+  });
+}
+
+export async function askYesNo(question, { defaultYes = false, input, output } = {}) {
+  const answer = (await askLine(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'} `, { input, output })).toLowerCase();
+  return answer ? answer === 'y' || answer === 'yes' : defaultYes;
+}
+
+export function createPrompter({ input = process.stdin, output = process.stdout } = {}) {
+  return {
+    line: (question) => askLine(question, { input, output }),
+    yesNo: (question, options = {}) => askYesNo(question, { ...options, input, output }),
+  };
+}
+
+export const MENU_ENTRIES = Object.freeze([
+  { id: 'start', label: 'Start' },
+  { id: 'stop', label: 'Stop' },
+  { id: 'restart', label: 'Restart' },
+  { id: 'url', label: 'Show URL and QR code' },
+  { id: 'setup', label: 'Settings' },
+  { id: 'service', label: 'Install or remove the service' },
+  { id: 'update', label: 'Update' },
+  { id: 'doctor', label: 'Doctor' },
+  { id: 'copilot', label: 'Copilot session' },
+  { id: 'quit', label: 'Quit' },
+]);
+
+const RELAY_TEXT = {
+  running: 'relay running',
+  stopped: 'relay stopped',
+  taken: 'relay not reachable (its port is held by another program, or by a relay with other settings)',
+  unconfigured: 'not set up yet (choose Settings)',
+};
+const SERVICE_TEXT = {
+  active: 'installed, running',
+  installed: 'installed',
+  none: 'not installed',
+  unavailable: 'not available here',
+};
+
+export function menuUsesColor({ env = process.env, output = process.stdout } = {}) {
+  return Boolean(output?.isTTY) && !String(env?.NO_COLOR || '');
+}
+
+/** The menu as lines of text: the status header, then the entries, the selected one marked. */
+export function renderMenu({ status = {}, selected = 0, color = false } = {}) {
+  const paint = (code, text) => (color ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const relay = RELAY_TEXT[status.relay] || RELAY_TEXT.stopped;
+  const lines = [
+    `${paint(1, `OAR ${status.version || ''}`.trim())} · ${paint(status.relay === 'running' ? 32 : 31, relay)}`,
+  ];
+  if (status.url) lines.push(`  URL      ${status.url}`);
+  if (status.port) lines.push(`  Port     ${status.port}`);
+  if (status.access) lines.push(`  Access   ${status.access === 'lan' ? 'LAN' : 'this machine only'}`);
+  if (SERVICE_TEXT[status.service]) lines.push(`  Service  ${SERVICE_TEXT[status.service]}`);
+  for (const warning of status.warnings || []) lines.push(paint(33, `  ! ${warning}`));
+  lines.push('');
+  MENU_ENTRIES.forEach((entry, index) => {
+    const key = entry.id === 'quit' ? 'q' : String(index + 1);
+    const text = `${index === selected ? '>' : ' '} ${key}  ${entry.label}`;
+    lines.push(index === selected ? paint(7, text) : text);
+  });
+  lines.push('', 'Arrow keys and Enter, or a digit, to choose; q to quit.');
+  return lines;
+}
+
+/** One chunk of raw input as a menu key: 'up', 'down', 'enter', 'quit', 'interrupt', an entry index, or null. */
+export function readMenuKey(chunk) {
+  const key = String(chunk);
+  if (key === '\x03' || key === '\x04') return 'interrupt';
+  if (key === '\x1b[A' || key === '\x1bOA' || key === 'k') return 'up';
+  if (key === '\x1b[B' || key === '\x1bOB' || key === 'j') return 'down';
+  if (key === '\r' || key === '\n') return 'enter';
+  if (key === 'q' || key === 'Q') return 'quit';
+  if (/^[1-9]$/.test(key)) return Number(key) - 1;
+  return null;
+}
+
+/** Reads raw key presses until `onKey` returns a value; the terminal is back in line mode on every way out. */
+function readKeys({ input, onKey }) {
+  return new Promise((resolve, reject) => {
+    const finish = (settle, value) => {
+      input.removeListener('data', onData);
+      input.removeListener('end', onEnd);
+      try { input.setRawMode(false); } catch {}
+      input.pause();
+      settle(value);
+    };
+    const onEnd = () => finish(reject, new PromptAborted());
+    const onData = (chunk) => {
+      let result;
+      try { result = onKey(readMenuKey(chunk)); } catch (error) { finish(reject, error); return; }
+      if (result !== undefined) finish(resolve, result);
+    };
+    input.on('data', onData);
+    input.once('end', onEnd);
+    try {
+      input.setRawMode(true);
+      input.resume();
+    } catch (error) {
+      finish(reject, error);
+    }
+  });
+}
+
+/**
+ * Runs the menu until Quit or Ctrl+C. `loadStatus()` returns the header's
+ * status before each drawing; `actions[id](status)` runs an entry and may
+ * return `{ exit: true }` to leave the menu. An input without raw mode gets
+ * the same list with a numbered prompt.
+ */
+export async function runMenu({
+  input = process.stdin,
+  output = process.stdout,
+  env = process.env,
+  loadStatus = async () => ({}),
+  actions = {},
+} = {}) {
+  const color = menuUsesColor({ env, output });
+  let rawMode = typeof input.setRawMode === 'function';
+  let selected = 0;
+  const draw = (status) => {
+    output.write(`${output.isTTY ? '\x1b[2J\x1b[H' : ''}${renderMenu({ status, selected, color }).join('\n')}\n`);
+  };
+  const pickByKey = (status) => readKeys({
+    input,
+    onKey: (key) => {
+      if (key === 'interrupt') throw new PromptAborted();
+      if (key === 'quit') return MENU_ENTRIES.length - 1;
+      if (key === 'enter') return selected;
+      if (typeof key === 'number') {
+        selected = key;
+        return selected;
+      }
+      if (key === 'up' || key === 'down') {
+        selected = (selected + (key === 'up' ? MENU_ENTRIES.length - 1 : 1)) % MENU_ENTRIES.length;
+        draw(status);
+      }
+      return undefined;
+    },
+  });
+  const pickByNumber = async () => {
+    for (;;) {
+      const answer = (await askLine('Choose (1-9, q): ', { input, output })).toLowerCase();
+      if (answer === 'q') return MENU_ENTRIES.length - 1;
+      if (/^[1-9]$/.test(answer)) return Number(answer) - 1;
+    }
+  };
+
+  try {
+    for (;;) {
+      const status = await loadStatus();
+      draw(status);
+      let choice;
+      try {
+        choice = rawMode ? await pickByKey(status) : await pickByNumber();
+      } catch (error) {
+        if (error instanceof PromptAborted || !rawMode) throw error;
+        // The terminal refused raw mode.
+        rawMode = false;
+        choice = await pickByNumber();
+      }
+      selected = choice;
+      const entry = MENU_ENTRIES[choice];
+      if (entry.id === 'quit') return { code: 0, reason: 'menu-quit' };
+      output.write('\n');
+      let result = null;
+      try {
+        result = await actions[entry.id]?.(status);
+      } catch (error) {
+        // Ctrl+C inside an entry (a setup question) leaves that entry, not
+        // the menu.
+        if (error instanceof PromptAborted) {
+          output.write('\n');
+          continue;
+        }
+        output.write(`[oar] ${error?.message || error}\n`);
+      }
+      if (result?.exit) return { code: result.code ?? 0, reason: 'menu-exit' };
+      output.write('\n');
+      if (rawMode) {
+        output.write('Press a key to go back to the menu. ');
+        await readKeys({
+          input,
+          onKey: (key) => {
+            if (key === 'interrupt') throw new PromptAborted();
+            return true;
+          },
+        });
+      } else {
+        await askLine('Press Enter to go back to the menu. ', { input, output });
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof PromptAborted)) throw error;
+    output.write('\n');
+    return { code: 130, reason: 'interrupted' };
+  }
+}

package/server/services/oar-cli-wsl.mjs

@@ -0,0 +1,129 @@
+/**
+ * What `oar` needs to know about WSL. A distro in WSL's default (NAT)
+ * networking has its own network namespace: a port a Windows program listens
+ * on looks free inside the distro, and a Windows browser's `localhost:<port>`
+ * then reaches the Windows program, not the relay in the distro. Windows is
+ * asked through interop; every failure means "unknown" and is treated like a
+ * plain Linux host.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const INTEROP_TIMEOUT_MS = 4000;
+// WSL's own localhost forwarders listen on Windows for every port a distro
+// listens on, so they stand for the distro's program, not for a Windows one.
+const WSL_FORWARDER_RE = /^wsl(relay|host)\.exe$/i;
+
+export function isWsl({ env = process.env, platform = process.platform, readFileImpl = fs.readFileSync } = {}) {
+  if (platform !== 'linux') return false;
+  if (String(env?.WSL_DISTRO_NAME || env?.WSL_INTEROP || '').trim()) return true;
+  try {
+    return /microsoft|wsl/i.test(String(readFileImpl('/proc/sys/kernel/osrelease', 'utf8')));
+  } catch {
+    return false;
+  }
+}
+
+/** The Windows system folder as the distro sees it: `[automount] root` of /etc/wsl.conf, else /mnt/. */
+export function windowsSystemDir({ readFileImpl = fs.readFileSync } = {}) {
+  let root = '/mnt/';
+  try {
+    let section = '';
+    for (const raw of String(readFileImpl('/etc/wsl.conf', 'utf8')).split(/\r?\n/)) {
+      const line = raw.trim();
+      const header = line.match(/^\[(.+)\]$/);
+      if (header) section = header[1].trim().toLowerCase();
+      const pair = section === 'automount' && line.match(/^root\s*=\s*(.+)$/i);
+      if (pair) root = pair[1].trim().replace(/^["']|["']$/g, '') || root;
+    }
+  } catch {
+    // No wsl.conf: the default mount root.
+  }
+  return path.posix.join(root, 'c', 'Windows', 'System32');
+}
+
+function runWindowsTool(name, args, { spawnSyncImpl = spawnSync, readFileImpl = fs.readFileSync } = {}) {
+  try {
+    const result = spawnSyncImpl(path.posix.join(windowsSystemDir({ readFileImpl }), name), args, {
+      encoding: 'utf8',
+      timeout: INTEROP_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return result && !result.error && result.status === 0 ? String(result.stdout || '') : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Listening TCP ports in `netstat -ano` output, each with the process ids
+ * that hold it. Windows prints the state word in the system language, so a
+ * listener is recognised by its shape instead: a TCP row whose remote address
+ * is the all-zero one (`0.0.0.0:0` or `[::]:0`). Only listeners a browser's
+ * `localhost` reaches count: the loopback and the any-address ones.
+ */
+export function parseNetstatListeners(text) {
+  const listeners = new Map();
+  for (const line of String(text || '').split(/\r?\n/)) {
+    const row = line.match(/^\s*TCP\s+(\S+):(\d+)\s+(?:0\.0\.0\.0|\[::\]):0\s+.*?(\d+)\s*$/);
+    if (!row || !['0.0.0.0', '127.0.0.1', '[::]', '[::1]'].includes(row[1])) continue;
+    const port = Number(row[2]);
+    const pids = listeners.get(port) || [];
+    if (!pids.includes(Number(row[3]))) pids.push(Number(row[3]));
+    listeners.set(port, pids);
+  }
+  return listeners;
+}
+
+/** Port → process ids of the Windows listeners, or null when Windows cannot be asked. */
+export function windowsListeningPorts(options = {}) {
+  const output = runWindowsTool('netstat.exe', ['-ano'], options);
+  return output === null ? null : parseNetstatListeners(output);
+}
+
+function windowsProcessName(pid, options) {
+  const output = runWindowsTool('tasklist.exe', ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'], options);
+  return output?.match(/^"([^"]+)"/m)?.[1] || '';
+}
+
+/**
+ * A function `(port) => name | null`: the Windows program that holds the port,
+ * or null when none does, when this is not WSL, or when Windows cannot be
+ * asked. The listener list is read once, on the first call.
+ */
+export function createWindowsPortCheck(options = {}) {
+  if (!isWsl(options)) return () => null;
+  let listeners;
+  return (port) => {
+    if (listeners === undefined) listeners = windowsListeningPorts(options);
+    for (const pid of listeners?.get(Number(port)) || []) {
+      const name = windowsProcessName(pid, options);
+      if (!WSL_FORWARDER_RE.test(name)) return name || 'a Windows program';
+    }
+    return null;
+  };
+}
+
+/**
+ * True in a WSL distro whose network is its own (NAT): its LAN address is
+ * internal to WSL. Mirrored networking shares the addresses of Windows.
+ */
+export function isWslNat(options = {}) {
+  if (!isWsl(options)) return false;
+  try {
+    const result = (options.spawnSyncImpl || spawnSync)('wslinfo', ['--networking-mode'], {
+      encoding: 'utf8',
+      timeout: INTEROP_TIMEOUT_MS,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return String(result?.stdout || '').trim().toLowerCase() !== 'mirrored';
+  } catch {
+    return true;
+  }
+}
+
+export function windowsPortWarning(port, holder) {
+  return `Windows holds port ${port} (${holder}): a browser on Windows reaches that program, not this relay. Pick another port: oar setup --port N`;
+}

package/server/services/preview-proxy-server.mjs

@@ -399,13 +399,33 @@ export function createPreviewProxyServer({
 
   // WebSocket upgrades (Vite HMR, an app's own socket) ride the same prefix.
   function handleUpgrade(req, socket, head) {
+    // Node removes its own error listener from a socket the moment it emits
+    // 'upgrade', and the upstream socket handed to 'upgrade' comes bare too. A
+    // browser that drops the connection while the dev server is still
+    // answering would otherwise raise an uncaught ECONNRESET and end the
+    // whole relay. Whatever fails on either side takes both down.
+    let upstreamReq = null;
+    let upstreamSocket = null;
+    const teardown = () => {
+      try { socket.destroy(); } catch {}
+      try { upstreamSocket?.destroy(); } catch {}
+      try { upstreamReq?.destroy(); } catch {}
+    };
+    socket.on('error', teardown);
+    // A client that leaves before the dev server answers abandons the
+    // handshake. Once both sides are piped, an orderly close travels through
+    // the pipes, so the pending writes still reach the other side.
+    socket.once('close', teardown);
+    const reply = (text) => {
+      if (socket.destroyed) return;
+      try { socket.write(text); } catch {}
+    };
+
     const resolved = resolveRequest(req);
     // Static previews have nothing to upgrade to; refuse like an unknown token.
     if (resolved.kind !== 'proxy' || resolved.entry?.mode === 'static') {
-      try {
-        socket.write('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
-      } catch {}
-      try { socket.destroy(); } catch {}
+      reply('HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n');
+      teardown();
       return;
     }
 
@@ -426,7 +446,7 @@ export function createPreviewProxyServer({
     headers.connection = 'Upgrade';
     headers.upgrade = String(req.headers.upgrade || 'websocket');
 
-    const upstreamReq = httpImpl.request({
+    upstreamReq = httpImpl.request({
       host: entry.targetHost,
       port: entry.targetPort,
       method: req.method,
@@ -436,25 +456,26 @@ export function createPreviewProxyServer({
     });
     guardConnectTimeout(upstreamReq, connectTimeoutMs, () => {});
 
-    upstreamReq.on('upgrade', (upstreamRes, upstreamSocket, upstreamHead) => {
+    upstreamReq.on('upgrade', (upstreamRes, answeredSocket, upstreamHead) => {
+      upstreamSocket = answeredSocket;
+      upstreamSocket.on('error', teardown);
+      // The client left while the dev server was answering.
+      if (socket.destroyed) {
+        teardown();
+        return;
+      }
       const lines = [`HTTP/1.1 ${upstreamRes.statusCode} ${upstreamRes.statusMessage}`];
       for (const [name, value] of Object.entries(upstreamRes.headers)) {
         for (const entryValue of Array.isArray(value) ? value : [value]) {
           lines.push(`${name}: ${entryValue}`);
         }
       }
-      try {
-        socket.write(`${lines.join('\r\n')}\r\n\r\n`);
-      } catch {
-        try { upstreamSocket.destroy(); } catch {}
-        return;
-      }
-      if (upstreamHead?.length) socket.write(upstreamHead);
+      reply(`${lines.join('\r\n')}\r\n\r\n`);
+      if (upstreamHead?.length) reply(upstreamHead);
       if (head?.length) upstreamSocket.write(head);
+      socket.removeListener('close', teardown);
       trackUpgradedSocket(socket);
       trackUpgradedSocket(upstreamSocket);
-      upstreamSocket.on('error', () => { try { socket.destroy(); } catch {} });
-      socket.on('error', () => { try { upstreamSocket.destroy(); } catch {} });
       upstreamSocket.pipe(socket);
       socket.pipe(upstreamSocket);
     });
@@ -462,18 +483,15 @@ export function createPreviewProxyServer({
     // A dev server that answers an upgrade with a plain response (404 on an
     // unknown HMR path) must not leave the client hanging.
     upstreamReq.on('response', (upstreamRes) => {
-      try {
-        socket.write(`HTTP/1.1 ${upstreamRes.statusCode} ${upstreamRes.statusMessage}\r\nConnection: close\r\n\r\n`);
-      } catch {}
+      reply(`HTTP/1.1 ${upstreamRes.statusCode} ${upstreamRes.statusMessage}\r\nConnection: close\r\n\r\n`);
+      upstreamRes.on('error', () => {});
       upstreamRes.resume();
-      try { socket.destroy(); } catch {}
+      teardown();
     });
 
     upstreamReq.on('error', () => {
-      try {
-        socket.write('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n');
-      } catch {}
-      try { socket.destroy(); } catch {}
+      reply('HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n');
+      teardown();
     });
 
     upstreamReq.end();