feat(headroom): proxy lifecycle management + dashboard UI (Docker sidecar supported)

[diegosouzapw]

Summary

Ports upstream decolua/9router@b55cf36d + pair commit 50ed79fe to OmniRoute, adapted JS→TS.

Adds local-only headroom token-saver proxy lifecycle management with:

• /api/headroom/status — read-only probe: detects headroom CLI + python>=3.10, hits /health, reports installed/running/canStart/localUrl.
• /api/headroom/start — spawns headroom proxy --port <port> as a detached, pid-tracked process (only if URL is loopback + CLI installed).
• /api/headroom/stop — sends SIGTERM (then SIGKILL after 2s grace) to the managed PID.

External Docker sidecars (non-loopback HEADROOM_URL) are recognized as running=true but canStart=false — start/stop is refused so the dashboard never tries to spawn against a remote URL.

Security

• /api/headroom/start and /api/headroom/stop are added to both LOCAL_ONLY_API_PREFIXES and SPAWN_CAPABLE_PREFIXES in src/server/authz/routeGuard.ts (Hard Rules feat(npm): add npm package publishing with CLI entry point #15 + fix(ci): explicit .npmrc auth for npm publish #17). Loopback enforcement happens unconditionally before any auth check — a leaked JWT via tunnel cannot trigger process spawning.
• All probe helpers use execFileSync / spawn with array arguments — no shell interpolation (Hard Rule deps: bump qs from 6.14.1 to 6.14.2 #13).
• Error responses route through createErrorResponse() + sanitizeErrorMessage() — no raw stack traces leaked (Hard Rule fix(ui): fix Select dropdown dark theme inconsistency #12).
• status is intentionally NOT loopback-only (matches upstream): it's a read-only probe with no spawn side-effect.

Test plan

• TDD red→green: tests/unit/headroom-proxy-lifecycle.test.ts (7 cases) drives every pure helper + the route-guard wiring.
• npm run typecheck:core — clean.
• tests/unit/authz/routeGuard.test.ts — 29/29 still pass with the new prefixes added.
• npx eslint src/lib/headroom src/app/api/headroom src/server/authz/routeGuard.ts tests/unit/headroom-proxy-lifecycle.test.ts — 0 warnings.
• Live VPS test (Hard Rule fix(ci): add environment for npm token access #18): install the headroom-ai python CLI, hit POST /api/headroom/start from loopback, verify PID written to <DATA_DIR>/headroom/proxy.pid and /health reachable, then POST /api/headroom/stop and verify PID gone. Pair test: set HEADROOM_URL=http://headroom:8787 (Docker sidecar), confirm GET /api/headroom/status returns {running:true, canStart:false, localUrl:false} and POST /api/headroom/start returns 400 with EXTERNAL_PROXY-class refusal.

Pure-helper unit tests cover the routing/decision logic; the spawn pathway requires the third-party headroom-ai python package installed and is gated behind the VPS validation step above.

Co-authored

• @decolua (upstream lifecycle commit b55cf36d)
• @carmelogunsroses (Docker sidecar pair commit 50ed79fe)

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[gemini-code-assist]

Code Review

This pull request introduces local headroom-proxy lifecycle management, adding API endpoints to start, stop, and query the status of the headroom proxy, along with corresponding unit tests and route-guard restrictions to enforce local-only access. The code reviewer provided several valuable recommendations to enhance robustness, including closing the log file descriptor immediately after spawning to prevent resource leaks, making the proxy stop process asynchronous to avoid port collision race conditions, supporting Windows environments by conditionally using the 'where' command, and reading only the end of the log file to prevent out-of-memory issues.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The file descriptor outFd is opened and passed to spawn, but it is kept open in the parent process during the entire startup timeout period. In Node.js, spawn duplicates the file descriptors passed in stdio immediately. To prevent resource leaks, we can close outFd in the parent process immediately after spawning the child process. This also simplifies the cleanup logic as we don't need to close it in the exit handler or at the end of the function.

  const outFd = fs.openSync(LOG_FILE, "a");
  let child;
  try {
    child = spawn(binary, ["proxy", "--port", String(safePort(opts.port))], {
      stdio: ["ignore", outFd, outFd],
      detached: true,
      windowsHide: true,
      env: { ...process.env },
    });
  } finally {
    try {
      fs.closeSync(outFd);
    } catch {
      // ignore
    }
  }

  if (!child.pid) {
    throw new HeadroomError("Failed to spawn headroom proxy", "SPAWN_FAILED");
  }

[gemini-code-assist]

stopHeadroomProxy is currently synchronous and returns immediately after sending SIGTERM, while using a deferred setTimeout to send SIGKILL if the process is still alive after 2 seconds. Because it immediately deletes the PID file via clearPid(), a subsequent startHeadroomProxy call (e.g., if the user restarts the proxy from the dashboard) will immediately attempt to spawn a new process on the same port before the old one has actually terminated. This will cause a port collision (EADDRINUSE) and fail. Making stopHeadroomProxy asynchronous and waiting for the process to terminate before returning prevents this race condition.

export async function stopHeadroomProxy(): Promise<StopResult> {
  const pid = getManagedPid();
  if (!pid) return { stopped: false, reason: "not_running" };
  try {
    process.kill(pid, "SIGTERM");
    const start = Date.now();
    let alive = true;
    while (Date.now() - start < STOP_GRACE_MS) {
      if (!isPidAlive(pid)) {
        alive = false;
        break;
      }
      await new Promise((resolve) => setTimeout(resolve, 100));
    }
    if (alive) {
      try {
        process.kill(pid, "SIGKILL");
        await new Promise((resolve) => setTimeout(resolve, 50));
      } catch {
        // already gone
      }
    }
    clearPid();
    return { stopped: true, pid };
  } catch (e) {
    clearPid();
    const msg = e instanceof Error ? e.message : String(e);
    throw new HeadroomError(`Failed to stop headroom proxy: ${msg}`, "STOP_FAILED");
  }
}

[gemini-code-assist]

Since stopHeadroomProxy should be asynchronous to prevent port collision race conditions, we need to await its result here.

Suggested change

	const result = stopHeadroomProxy();
	const result = await stopHeadroomProxy();

[gemini-code-assist]

The which command is not available by default on Windows environments. Since OmniRoute includes an Electron application that can run on Windows, using which directly will fail to detect the headroom binary even if it is installed. We should check the platform and use where on Windows.

export function findHeadroomBinary(): string | null {
  try {
    const cmd = process.platform === "win32" ? "where" : "which";
    const out = execFileSync(cmd, ["headroom"], {
      stdio: ["ignore", "pipe", "ignore"],
      windowsHide: true,
      env: { ...process.env, PATH: EXTENDED_PATH },
    })
      .toString()
      .trim();
    return out.split(/\r?\n/)[0] || null;
  } catch {
    return null;
  }
}

[gemini-code-assist]

fs.readFileSync reads the entire log file into memory. If the headroom proxy runs for a long time and produces a large log file, this can cause a significant memory spike or an Out-Of-Memory (OOM) crash. We should read only the end of the file (e.g., the last 64KB) to retrieve the log tail efficiently.

export function getHeadroomLogTail(maxLines = 200): string {
  try {
    if (!fs.existsSync(LOG_FILE)) return "";
    const stat = fs.statSync(LOG_FILE);
    const size = stat.size;
    if (size === 0) return "";

    const bufferSize = Math.min(size, 64 * 1024);
    const fd = fs.openSync(LOG_FILE, "r");
    const buffer = Buffer.alloc(bufferSize);
    try {
      fs.readSync(fd, buffer, 0, bufferSize, size - bufferSize);
    } finally {
      fs.closeSync(fd);
    }

    const content = buffer.toString("utf8");
    const lines = content.split(/\r?\n/);
    const activeLines = size > bufferSize ? lines.slice(1) : lines;
    return activeLines.filter(Boolean).slice(-maxLines).join("\n");
  } catch {
    return "";
  }
}