mixdog 0.7.17 → 0.8.0

package/setup/launch-core.mjs

@@ -1,617 +0,0 @@
-// launch-core.mjs — importable config-UI launch core.
-//
-// Extracted from launch.mjs so the same alive-probe → stale-server
-// detection → spawn → requestOpen sequence can run BOTH from the CLI
-// shim (launch.mjs, which keeps the Windows console-hide / self-respawn
-// mitigations for direct `bun launch.mjs` invocation) AND from inside the
-// resident MCP server (the `open_config` tool). When the MCP server — a
-// long-lived background process — spawns setup-server with windowsHide:true,
-// no console window is created at all, so the conhost flash the CLI path
-// fights with FFI/wscript shims simply never happens.
-//
-// Import-safe: no top-level side effects, no env mutation at module load.
-// All paths/ports are module constants; per-call state (plugin root/data)
-// is derived inside launchConfigUi().
-
-import { spawn, execSync } from 'child_process';
-import { openSync, closeSync, readFileSync, writeSync, writeFileSync, appendFileSync, statSync, unlinkSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import http from 'http';
-import net from 'net';
-import { tmpdir } from 'os';
-import { resolvePluginData } from '../src/shared/plugin-paths.mjs';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const server = join(__dirname, 'setup-server.mjs');
-// Reuse the launcher's own runtime (bun.exe from the CLI shebang, or the
-// bun that runs the MCP server). Spawning setup-server by absolute path lets
-// us drop shell:true on Windows; the cmd.exe wrapper was swallowing the
-// child's stderr and turning real bun startup errors into an empty log.
-const CHILD_INTERPRETER = process.execPath;
-export const PORT = 3458;
-export const CONFIG_UI_URL = `http://localhost:${PORT}`;
-
-function ping(timeoutMs = 1500) {
-  return new Promise(resolve => {
-    // setup-server listens on 127.0.0.1 only. agent:false disables Node's
-    // default keepAlive socket pool; Connection: close prevents any keepalive
-    // negotiation that could leave half-open sockets between probes.
-    const req = http.get({
-      host: '127.0.0.1', port: PORT, path: '/',
-      agent: false, headers: { Connection: 'close' },
-    }, res => { res.resume(); resolve(true); });
-    req.on('error', () => resolve(false));
-    req.setTimeout(timeoutMs, () => { req.destroy(); resolve(false); });
-  });
-}
-
-// TCP-level liveness probe used as a fallback when HTTP ping times out but
-// the server is actually accepting connections. Distinguishes "server is
-// listening but its handler is momentarily slow" from "server is dead" so
-// the launcher doesn't false-trigger spawnServerWithLog and crash on the
-// port collision.
-function tcpOpen(timeoutMs = 300) {
-  return new Promise(resolve => {
-    const s = net.connect({ host: '127.0.0.1', port: PORT });
-    s.setTimeout(timeoutMs);
-    s.once('connect', () => { s.destroy(); resolve(true); });
-    s.once('timeout', () => { s.destroy(); resolve(false); });
-    s.once('error', () => resolve(false));
-  });
-}
-
-// GET /api/plugin-path. Returns the absolute plugin root the running
-// setup-server identifies as, or null on any failure. Used to detect a
-// stale or wrong-plugin server still bound to PORT before we hand it the
-// /open call — otherwise a different version's setup window can pop up.
-function fetchPluginPath(timeoutMs = 1500) {
-  return new Promise(resolve => {
-    const req = http.get(`http://127.0.0.1:${PORT}/api/plugin-path`, res => {
-      let body = '';
-      res.setEncoding('utf8');
-      res.on('data', chunk => { body += chunk; });
-      res.on('end', () => {
-        try {
-          const json = JSON.parse(body);
-          resolve(typeof json?.path === 'string' ? json.path : null);
-        } catch {
-          resolve(null);
-        }
-      });
-    });
-    req.on('error', () => resolve(null));
-    req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
-  });
-}
-
-// Watchdog disabled — returning 0 keeps setup-server alive after the MCP
-// host exits (until the user closes the chrome window). The previous
-// execSync('powershell …') ancestor walk was a major conhost-flash source
-// on every /mixdog:config invocation; removing it eliminated that flash.
-function findAncestorPid() {
-  return 0;
-}
-
-function requestOpen() {
-  return new Promise(resolve => {
-    const req = http.get(`http://127.0.0.1:${PORT}/open`, res => {
-      let body = '';
-      res.setEncoding('utf8');
-      res.on('data', chunk => { body += chunk; });
-      res.on('end', () => {
-        try {
-          const json = JSON.parse(body);
-          resolve(json.ok === true);
-        } catch {
-          resolve(res.statusCode >= 200 && res.statusCode < 300);
-        }
-      });
-    });
-    req.on('error', () => resolve(false));
-    // /open now holds the in-process open mutex until the spawned browser is
-    // discoverable or its wscript launcher's bounded focus loop (~6s) exits,
-    // so the response can legitimately take several seconds. Allow headroom
-    // above that bound so a slow-but-successful open is not reported as a
-    // failure (which would throw a spurious LaunchError).
-    req.setTimeout(12000, () => { req.destroy(); resolve(false); });
-  });
-}
-
-function sleep(ms) {
-  return new Promise(resolve => setTimeout(resolve, ms));
-}
-
-// Cross-process launch mutex. Only ONE launcher runs the version-check →
-// reclaim critical section at a time. Now that prewarm takes over every
-// session, two concurrent session starts can both observe the same stale
-// server; without serialization the slower one kills the faster one's
-// freshly-spawned correct server. Exclusive-create lock file + stale-takeover
-// (a holder that crashed mid-launch leaves a lock no older than STALE_MS).
-// Best-effort: on timeout or an unexpected fs error we proceed lock-free
-// rather than deadlock the launcher.
-const LAUNCH_LOCK_PATH = join(tmpdir(), `mixdog-setup-launch-${PORT}.lock`);
-const LAUNCH_LOCK_STALE_MS = 30000;
-
-async function acquireLaunchLock(trace, timeoutMs = 20000) {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() <= deadline) {
-    try {
-      const fd = openSync(LAUNCH_LOCK_PATH, 'wx'); // exclusive create — EEXIST if held
-      writeSync(fd, `${process.pid} ${new Date().toISOString()}\n`);
-      closeSync(fd);
-      return true;
-    } catch (e) {
-      if (e?.code !== 'EEXIST') { trace(`launch-lock: unexpected ${e?.code || e} → proceeding lock-free`); return false; }
-      let stale = false;
-      try { stale = (Date.now() - statSync(LAUNCH_LOCK_PATH).mtimeMs) > LAUNCH_LOCK_STALE_MS; } catch {}
-      if (stale) { trace(`launch-lock: stale lock → reclaiming`); try { unlinkSync(LAUNCH_LOCK_PATH); } catch {} continue; }
-      await sleep(200);
-    }
-  }
-  trace(`launch-lock: wait timeout → proceeding lock-free`);
-  return false;
-}
-
-function releaseLaunchLock() {
-  try { unlinkSync(LAUNCH_LOCK_PATH); } catch {}
-}
-
-// POSIX listener-pid resolution with graceful degradation across minimal
-// images. Tries lsof → ss → fuser; returns the first listener pid found, or
-// null if none of the tools exist / none report a listener. A missing tool
-// throws ENOENT from execSync, which we swallow and move to the next probe so
-// a bare container without lsof does not wedge port reclaim.
-function resolveListenerPidPosix(trace) {
-  // lsof: -ti prints bare pids, -sTCP:LISTEN restricts to the listening socket.
-  try {
-    const out = execSync(`lsof -ti :${PORT} -sTCP:LISTEN`, { encoding: 'utf8', timeout: 3000 }).trim();
-    const n = parseInt(out.split('\n')[0], 10);
-    if (Number.isFinite(n) && n > 0) return n;
-  } catch (e) {
-    if (trace) trace(`reclaimPort: lsof unavailable/failed (${e?.code || e?.message || e}) → trying ss`);
-  }
-  // ss (iproute2): -H no header, -l listening, -t tcp, -n numeric, -p process.
-  // The pid lives in the trailing `users:(("name",pid=1234,fd=7))` field.
-  try {
-    const out = execSync(`ss -Hltnp 'sport = :${PORT}'`, { encoding: 'utf8', timeout: 3000 }).trim();
-    const m = out.match(/pid=(\d+)/);
-    if (m) {
-      const n = parseInt(m[1], 10);
-      if (Number.isFinite(n) && n > 0) return n;
-    }
-  } catch (e) {
-    if (trace) trace(`reclaimPort: ss unavailable/failed (${e?.code || e?.message || e}) → trying fuser`);
-  }
-  // fuser: prints the pids holding the tcp port to stdout (diagnostics on
-  // stderr). Take the first numeric token.
-  try {
-    const out = execSync(`fuser ${PORT}/tcp 2>/dev/null`, { encoding: 'utf8', timeout: 3000 }).trim();
-    const m = out.match(/\d+/);
-    if (m) {
-      const n = parseInt(m[0], 10);
-      if (Number.isFinite(n) && n > 0) return n;
-    }
-  } catch (e) {
-    if (trace) trace(`reclaimPort: fuser unavailable/failed (${e?.code || e?.message || e}) → no listener pid resolved`);
-  }
-  return null;
-}
-
-// Reclaim PORT from a version-mismatched setup-server: resolve the LISTENER
-// pid, kill it (tree on win32, process-group on unix), wait for the port to
-// free, then spawn the current-version server window-free. Throws LaunchError
-// if the port cannot be reclaimed. Caller MUST hold the launch lock so two
-// launchers never race the kill+respawn.
-async function reclaimPort(pluginRoot, pluginData, remoteRoot, trace) {
-  let stalePid = null;
-  let pidResolveError = null;
-  let killError = null;
-  try {
-    if (process.platform === 'win32') {
-      // -State Listen is REQUIRED: Get-NetTCPConnection -LocalPort returns the
-      // LISTENING socket AND every ESTABLISHED/TIME_WAIT connection to it, so a
-      // bare `-First 1` can resolve a client/proxy PID (or 0) instead of the
-      // server — taskkill then misses the real owner and the port never frees.
-      const out = execSync(
-        `powershell -NoProfile -Command "(Get-NetTCPConnection -LocalPort ${PORT} -State Listen -ErrorAction SilentlyContinue | Select-Object -First 1).OwningProcess"`,
-        { encoding: 'utf8', timeout: 3000, windowsHide: true },
-      ).trim();
-      const n = parseInt(out, 10);
-      if (Number.isFinite(n) && n > 0) stalePid = n;
-    } else {
-      // Resolve the LISTENER pid. lsof is the primary tool, but minimal
-      // Linux/WSL/container images often ship without it — falling back to
-      // ss (iproute2) then fuser keeps port reclaim working there instead
-      // of wedging on a missing-binary ENOENT. Each probe is independent and
-      // best-effort; the first that yields a pid wins.
-      stalePid = resolveListenerPidPosix(trace);
-    }
-  } catch (e) { pidResolveError = e; }
-  if (stalePid !== null) {
-    try {
-      if (process.platform === 'win32') {
-        // /T kills the whole process tree — the setup-server spawns child
-        // browser/server descendants that survive a PID-only Stop-Process.
-        execSync(`taskkill /T /F /PID ${stalePid}`, { timeout: 3000, windowsHide: true });
-      } else {
-        // Detached setup-server is its own process-group leader; the negative
-        // PID signals the group, reaping descendants a bare kill would orphan.
-        try { execSync(`kill -KILL -${stalePid}`, { timeout: 3000 }); }
-        catch { execSync(`kill -KILL ${stalePid}`, { timeout: 3000 }); }
-      }
-    } catch (e) { killError = e; }
-  }
-  // Poll until the port stops answering (250ms ticks, 5000ms deadline — a hair
-  // longer than the kill's own 3000ms timeout so a slow OS port release is not
-  // misread as a kill failure).
-  const killDeadline = Date.now() + 5000;
-  let portFree = false;
-  while (Date.now() < killDeadline) {
-    await sleep(250);
-    portFree = !(await ping(300));
-    if (portFree) break;
-  }
-  if (!portFree) {
-    const errorDetails = [
-      pidResolveError && `  PID resolution failure: ${pidResolveError?.message || String(pidResolveError)}`,
-      killError && `  kill failure: ${killError?.message || String(killError)}`,
-    ].filter(Boolean).join('\n');
-    throw new LaunchError(
-      `Port ${PORT} is in use by a different mixdog plugin instance and could not be reclaimed (kill of PID ${stalePid ?? 'unknown'} failed or timed out).\n` +
-      `  expected plugin root: ${pluginRoot}\n` +
-      `  actual plugin root:   ${remoteRoot}\n` +
-      (errorDetails ? errorDetails + '\n' : '') +
-      `Stop the other setup-server (or change PORT) and retry.\n`,
-    );
-  }
-  trace(`reclaimPort: killed stalePid=${stalePid}, port freed, spawning current server`);
-  await spawnServerWithLog(pluginRoot, pluginData, { openOnStart: false });
-  trace(`reclaimPort: spawnServerWithLog completed`);
-}
-
-async function waitForServer(timeoutMs = 4000, shouldStop = () => false) {
-  const deadline = Date.now() + timeoutMs;
-  let ready = false;
-  while (Date.now() < deadline) {
-    ready = await ping(500);
-    if (ready) break;
-    if (shouldStop()) break;
-    await sleep(250);
-  }
-  return ready && !shouldStop();
-}
-
-function openLaunchLog() {
-  const path = join(tmpdir(), `mixdog-setup-launch-${process.pid}.log`);
-  const fd = openSync(path, 'a');
-  writeSync(fd, [
-    '',
-    `[${new Date().toISOString()}] setup-server launch`,
-    `launcherPid=${process.pid}`,
-    `execPath=${process.execPath}`,
-    `interpreter=${CHILD_INTERPRETER}`,
-    `server=${server}`,
-    `cwd=${dirname(__dirname)}`,
-    '--- child stdout/stderr ---',
-  ].join('\n') + '\n');
-  return { path, fd };
-}
-
-function writeLog(fd, message) {
-  try {
-    if (typeof fd === 'number') writeSync(fd, message);
-  } catch {}
-}
-
-function closeLog(fd) {
-  try {
-    if (typeof fd === 'number') closeSync(fd);
-  } catch {}
-}
-
-function readLog(path) {
-  try { return readFileSync(path, 'utf8').trim(); } catch { return ''; }
-}
-
-// In the importable core a launch failure THROWS (with the same diagnostic
-// text the CLI used to print to stderr). The CLI shim catches and converts
-// it back to a stderr write + process.exit(1); the MCP tool surfaces it as
-// an error result.
-class LaunchError extends Error {}
-
-function cmdSetLine(name, value) {
-  return `set "${name}=${String(value ?? '').replace(/"/g, '')}"`;
-}
-
-function cmdQuote(value) {
-  return `"${String(value).replace(/"/g, '""')}"`;
-}
-
-function spawnWscriptHidden(vbsPath) {
-  return new Promise(resolve => {
-    let child;
-    try {
-      child = spawn('wscript.exe', ['//B', '//NoLogo', vbsPath], {
-        stdio: 'ignore',
-        windowsHide: true,
-      });
-    } catch (error) {
-      resolve({ ok: false, error: error?.message || String(error) });
-      return;
-    }
-    child.once('error', error => resolve({ ok: false, error: error?.message || String(error) }));
-    child.once('exit', code => resolve({ ok: code === 0, code }));
-  });
-}
-
-// Spawn setup-server with a launch log, wait for readiness, and throw a
-// LaunchError on failure. Shared by the cold-start (!alive) path and the
-// stale-server takeover path so both use one implementation.
-async function spawnServerWithLog(pluginRoot, pluginData, { openOnStart = true } = {}) {
-  const launchLog = openLaunchLog();
-  let spawnError = null;
-  let childExit = null;
-  let child;
-
-  if (process.platform === 'win32') {
-    closeLog(launchLog.fd);
-    const stamp = `${process.pid}-${Date.now()}`;
-    const cmdPath = join(tmpdir(), `mixdog-setup-server-${stamp}.cmd`);
-    const vbsPath = join(tmpdir(), `mixdog-setup-server-${stamp}.vbs`);
-    const batchLines = [
-      '@echo off',
-      'setlocal',
-      cmdSetLine('CLAUDE_PLUGIN_ROOT', pluginRoot),
-      cmdSetLine('CLAUDE_PLUGIN_DATA', pluginData),
-      cmdSetLine('MIXDOG_SETUP_OPEN_ON_START', openOnStart ? '1' : '0'),
-      cmdSetLine('MIXDOG_SETUP_PARENT_PID', String(findAncestorPid() || '')),
-      process.env.USERPROFILE ? cmdSetLine('USERPROFILE', process.env.USERPROFILE) : '',
-      process.env.APPDATA ? cmdSetLine('APPDATA', process.env.APPDATA) : '',
-      process.env.LOCALAPPDATA ? cmdSetLine('LOCALAPPDATA', process.env.LOCALAPPDATA) : '',
-      process.env.PATH ? cmdSetLine('PATH', process.env.PATH) : '',
-      `cd /d ${cmdQuote(pluginRoot)}`,
-      `echo [${new Date().toISOString()}] hidden setup-server cmd start>>${cmdQuote(launchLog.path)}`,
-      `${cmdQuote(CHILD_INTERPRETER)} ${cmdQuote(server)}>>${cmdQuote(launchLog.path)} 2>&1`,
-      'set "mixdogExit=%ERRORLEVEL%"',
-      'del "%~f0" >NUL 2>&1',
-      'exit /b %mixdogExit%',
-    ].filter(Boolean);
-    writeFileSync(cmdPath, batchLines.join('\r\n'), 'utf8');
-
-    const escVbs = s => String(s).replace(/"/g, '""');
-    const cmdLine = `cmd.exe /d /c ""${cmdPath}""`;
-    const vbsLines = [
-      'Option Explicit',
-      'Const HIDDEN_WINDOW = 0',
-      'Dim Wmi, Startup, cmdLine, cwd, pid, rc',
-      'Set Wmi = GetObject("winmgmts:{impersonationLevel=impersonate}!\\\\.\\root\\cimv2")',
-      'Set Startup = Wmi.Get("Win32_ProcessStartup").SpawnInstance_',
-      'Startup.ShowWindow = HIDDEN_WINDOW',
-      `cmdLine = "${escVbs(cmdLine)}"`,
-      `cwd = "${escVbs(pluginRoot)}"`,
-      'rc = Wmi.Get("Win32_Process").Create(cmdLine, cwd, Startup, pid)',
-      'If rc <> 0 Then WScript.Quit rc',
-    ];
-    writeFileSync(vbsPath, vbsLines.join('\r\n'), 'utf8');
-
-    const launched = await spawnWscriptHidden(vbsPath);
-    if (!launched.ok) {
-      throw new LaunchError(
-        `Failed to spawn hidden setup-server for ${CONFIG_UI_URL}\n` +
-        `Launch log: ${launchLog.path}\n` +
-        `wscript result: ${launched.error || `exit ${launched.code}`}\n`,
-      );
-    }
-    if (!await waitForServer(15000)) {
-      const captured = readLog(launchLog.path);
-      throw new LaunchError(
-        `setup-server did not become ready at ${CONFIG_UI_URL}/ within 15000ms (hidden WMI launch).\n` +
-        `Launch log: ${launchLog.path}\n` +
-        (captured ? `--- setup-server launch log ---\n${captured}\n--- end setup-server launch log ---\n` : 'No setup-server output was captured.\n'),
-      );
-    }
-    return;
-  }
-
-  try {
-    child = spawn(CHILD_INTERPRETER, [server], {
-      detached: true,
-      // Console-less parents (hidden wscript/PowerShell chain) would
-      // otherwise hand the detached console child a fresh visible window.
-      windowsHide: true,
-      // Use a real file descriptor, not parent pipes/stdio. This keeps the
-      // detached child independent after unref() while preserving first-start
-      // stdout/stderr for diagnostics. shell:false (default) on every
-      // platform — cmd.exe wrapping was eating the child's stderr.
-      stdio: ['ignore', launchLog.fd, launchLog.fd],
-      cwd: pluginRoot,
-      env: {
-        ...process.env,
-        CLAUDE_PLUGIN_ROOT: pluginRoot,
-        CLAUDE_PLUGIN_DATA: pluginData,
-        MIXDOG_SETUP_OPEN_ON_START: openOnStart ? '1' : '0',
-        MIXDOG_SETUP_PARENT_PID: String(findAncestorPid() || ''),
-      },
-    });
-  } catch (error) {
-    closeLog(launchLog.fd);
-    throw new LaunchError(
-      `Failed to spawn setup-server for ${CONFIG_UI_URL}\n` +
-      `Launch log: ${launchLog.path}\n` +
-      `${error?.stack || error?.message || String(error)}\n`,
-    );
-  }
-
-  child.once('error', error => {
-    spawnError = error;
-    writeLog(launchLog.fd, `\n[${new Date().toISOString()}] child error: ${error?.stack || error?.message || String(error)}\n`);
-  });
-  child.once('exit', (code, signal) => {
-    childExit = { code, signal };
-    writeLog(launchLog.fd, `\n[${new Date().toISOString()}] child exit: code=${code} signal=${signal}\n`);
-  });
-  child.unref();
-
-  if (!await waitForServer(15000, () => Boolean(spawnError || childExit))) {
-    closeLog(launchLog.fd);
-    const captured = readLog(launchLog.path);
-    const status = spawnError
-      ? `spawn error: ${spawnError?.stack || spawnError?.message || String(spawnError)}`
-      : childExit
-        ? `child exit: code=${childExit.code} signal=${childExit.signal}`
-        : 'child did not report an error or exit before readiness timeout';
-    throw new LaunchError(
-      `setup-server did not become ready at ${CONFIG_UI_URL}/ within 15000ms (${status}).\n` +
-      `Launch log: ${launchLog.path}\n` +
-      (captured ? `--- setup-server launch log ---\n${captured}\n--- end setup-server launch log ---\n` : 'No setup-server output was captured.\n'),
-    );
-  }
-
-  closeLog(launchLog.fd);
-}
-
-// Probe for an already-running setup-server. A live server answers the HTTP
-// ping immediately; if its event loop is momentarily blocked inside a sync
-// spawn (chrome /open path), the kernel still completes the TCP accept, so the
-// tcpOpen fallback detects it. A short window therefore suffices.
-function probeOnce() {
-  return new Promise(resolve => {
-    const req = http.get({
-      host: '127.0.0.1', port: PORT, path: '/',
-      agent: false, headers: { Connection: 'close' },
-    }, res => { res.resume(); resolve('up'); });
-    req.on('error', e => resolve(e?.code === 'ECONNREFUSED' ? 'refused' : 'timeout'));
-    req.setTimeout(800, () => { req.destroy(); resolve('timeout'); });
-  });
-}
-
-async function aliveProbe() {
-  const deadline = Date.now() + 1500;
-  while (Date.now() < deadline) {
-    const state = await probeOnce();
-    if (state === 'up') return true;
-    if (state === 'refused') return false;
-    await sleep(150);
-  }
-  return false;
-}
-
-// Resolve / start the resident setup-server and open (or re-open) the config
-// UI window, returning the UI URL on success. Throws LaunchError with a
-// diagnostic message on failure.
-//
-// Options:
-//   pluginRoot — override the plugin root (defaults to CLAUDE_PLUGIN_ROOT or
-//                the directory above setup/).
-//   trace      — optional (msg:string)=>void hook for diagnostics; defaults
-//                to a tmp trace-log writer (matches the CLI's behaviour).
-//   prewarm    — when true, only ensure the server is alive (spawned
-//                window-free, MIXDOG_SETUP_OPEN_ON_START unset). Never opens
-//                or re-focuses a window; a no-op when the server already runs.
-export async function launchConfigUi(options = {}) {
-  const pluginRoot = options.pluginRoot || process.env.CLAUDE_PLUGIN_ROOT || dirname(__dirname);
-  const prewarm = options.prewarm === true;
-  // Slash-command shells expand ${CLAUDE_PLUGIN_ROOT} into argv but do not
-  // export it, so the spawned setup-server inherits a stripped env. Re-derive
-  // both ROOT and DATA so plugin-paths and the stricter channels-lib guard
-  // (which checks CLAUDE_PLUGIN_DATA directly) both succeed in the child.
-  process.env.CLAUDE_PLUGIN_ROOT = pluginRoot;
-  const pluginData = process.env.CLAUDE_PLUGIN_DATA || resolvePluginData();
-  process.env.CLAUDE_PLUGIN_DATA = pluginData;
-
-  const traceFn = typeof options.trace === 'function'
-    ? options.trace
-    : (() => {
-        const traceLogPath = join(tmpdir(), `mixdog-launch-trace-${process.pid}.log`);
-        return msg => {
-          try { appendFileSync(traceLogPath, `[${new Date().toISOString()}] ${msg}\n`); } catch {}
-        };
-      })();
-  const __trace = msg => { try { traceFn(msg); } catch {} };
-  __trace(`launchConfigUi entry parentPid=${process.ppid} pluginRoot=${pluginRoot}`);
-
-  const alive = await aliveProbe();
-  __trace(`aliveProbe result alive=${alive}`);
-
-  // Singleton / current-version invariant is enforced below for BOTH prewarm
-  // and interactive launches: prewarm no longer early-returns on a live
-  // server, so a stale old-version setup-server left running across a plugin
-  // update is taken over and replaced window-free at session start — instead
-  // of lingering until a manual /mixdog:config (the recurrence we hit). PORT
-  // is a fixed constant, so exactly one setup-server can own it; reclaiming a
-  // version-mismatched owner is the correct singleton behaviour even here.
-  if (!alive) {
-    // Boot window-free; the unconditional requestOpen below owns opening the
-    // window. Spawning with openOnStart:1 here would double-open and races a
-    // concurrent every-session prewarm that may bind the port first (in which
-    // case our own openOnStart child never gets to open anything).
-    __trace(`branch: !alive → spawnServerWithLog (window-free)`);
-    await spawnServerWithLog(pluginRoot, pluginData, { openOnStart: false });
-    __trace(`spawnServerWithLog completed`);
-  }
-
-  // Confirm the live server belongs to THIS plugin install before reusing it
-  // (a stale or different-version setup-server would otherwise own the
-  // window). After a !alive spawn above this simply re-confirms our own server.
-  const remoteRoot = await fetchPluginPath();
-  __trace(`fetchPluginPath returned remoteRoot=${remoteRoot}`);
-  if (remoteRoot) {
-    // Normalize: trailing slash strip + backslash → forward slash + lowercase
-    // so `C:/x` and `C:\x` compare equal (lowercase only on Windows).
-    const normalize = p => { const s = p.replace(/[\\/]+$/, '').replace(/\\/g, '/'); return process.platform === 'win32' ? s.toLowerCase() : s; };
-    const expected = normalize(pluginRoot);
-    const actual = normalize(remoteRoot);
-    __trace(`compare expected=${expected} actual=${actual} mismatch=${expected !== actual}`);
-    if (expected !== actual) {
-      // Serialize the reclaim across processes: prewarm now takes over every
-      // session, so two concurrent launchers can both observe this stale
-      // server. Under the lock the recheck is authoritative — whoever acquires
-      // first reclaims, and the next acquirer re-reads a now-current server and
-      // skips, so a freshly-spawned correct server is never killed.
-      const locked = await acquireLaunchLock(__trace);
-      try {
-        const recheckRoot = await fetchPluginPath();
-        if (recheckRoot && normalize(recheckRoot) !== expected) {
-          await reclaimPort(pluginRoot, pluginData, recheckRoot, __trace);
-        } else {
-          __trace(`takeover: server current under lock (recheckRoot=${recheckRoot}) → skip`);
-        }
-      } finally {
-        if (locked) releaseLaunchLock();
-      }
-    }
-  }
-
-  // Ensure the server (just spawned, taken over, or concurrently swapped by
-  // another launcher) is actually answering before we report success or open a
-  // window — absorbs the brief port-down window during a concurrent reclaim so
-  // requestOpen never hits a refused port and prewarm never returns early.
-  if (!await waitForServer(15000)) {
-    throw new LaunchError(`setup-server did not become ready at ${CONFIG_UI_URL}/ before launch.\n`);
-  }
-
-  // Prewarm stops here: the current-version server is up (spawned or taken
-  // over above) and must NOT open a browser window.
-  if (prewarm) {
-    __trace(`prewarm: current-version server ensured → return`);
-    return CONFIG_UI_URL;
-  }
-
-  // Invariant: a non-prewarm launch ALWAYS opens the window through the
-  // idempotent /open endpoint once the server is ready — regardless of which
-  // process (this launcher, a concurrent every-session prewarm, or a
-  // pre-existing server) actually booted it. Relying on the spawned child's
-  // MIXDOG_SETUP_OPEN_ON_START would silently no-op whenever a window-free
-  // prewarm server bound the port first.
-  __trace(`branch: requestOpen`);
-  const opened = await requestOpen();
-  __trace(`requestOpen returned ${opened}`);
-  if (!opened) {
-    throw new LaunchError(`Failed to open config UI window for ${CONFIG_UI_URL}\n`);
-  }
-  __trace(`launchConfigUi success`);
-  return CONFIG_UI_URL;
-}
-
-export { LaunchError, tcpOpen };