@tonyclaw/agent-inspector 4.0.1 → 4.0.2

package/src/cli.ts

@@ -1,1433 +0,0 @@
-#!/usr/bin/env node
-import { Buffer } from "node:buffer";
-import { spawn, type ChildProcess } from "node:child_process";
-import { createConnection } from "node:net";
-import { fileURLToPath } from "node:url";
-import { dirname, join, resolve as resolvePath } from "node:path";
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
-import type { Readable, Writable } from "node:stream";
-import packageJson from "../package.json";
-import {
-  AGENT_INSPECTOR_BACKEND_ENV,
-  AGENT_INSPECTOR_BACKEND_HEADER,
-  BackendImplementationSchema,
-  parseBackendImplementation,
-  type BackendImplementation,
-} from "./lib/backendImplementation.js";
-import {
-  AGENT_INSPECTOR_BASE_PATH_ENV,
-  AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV,
-  appendBasePathToOrigin,
-  getConfiguredBasePath,
-  normalizePublicBasePath,
-} from "./lib/basePath.js";
-import {
-  AGENT_INSPECTOR_CLI_ENTRY_ENV,
-  managedInstanceShutdownMessage,
-  readManagedInstanceLaunch,
-  type ManagedInstanceLaunch,
-} from "./lib/managedInstance.js";
-import {
-  formatAccessHintLines,
-  isLoopbackHost,
-  isValidBindHost,
-  localUrlForPort,
-  networkUrlsForBindHost,
-  probeHostForBindHost,
-  urlForHost,
-} from "./cli/networkHints.js";
-import {
-  shouldSuppressServerOutputLine,
-  type ServerOutputFilterContext,
-} from "./cli/startupOutput.js";
-import {
-  resolvePreferredBackendImplementation,
-  resolveRustBackendPackage,
-} from "./cli/rustBackendPackage.js";
-import { handleNamedInstanceApi } from "./cli/instanceApi.js";
-import {
-  closeIdentityProxyGracefully,
-  forceCloseIdentityProxy,
-  parseUiOriginAllowlist,
-  startIdentityProxy,
-  stopIdentityProxyAdmission,
-  type ManagedInstanceControlOptions,
-} from "./proxy/identityProxy.js";
-import { findPidsByPort, killPid, openUrlCommand } from "./proxy/platformCommands.js";
-import { resolveDataDir } from "./proxy/dataDir.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-// v3 defaults the public entrypoint to 9527. The legacy 9527 alias can be
-// enabled explicitly for older AI-tool and MCP configs. The TanStack Start
-// runtime stays on a private upstream port and public ports reverse-proxy to
-// that same runtime, so logs, sessions, and MCP state remain unified.
-const DEFAULT_PORT = 9527;
-const LEGACY_ALIAS_PORT = 9527;
-const DEFAULT_UPSTREAM_PORT = 9529;
-const DEFAULT_BIND_HOST = "127.0.0.1";
-const LOCAL_PROBE_TIMEOUT_MS = 5000;
-const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
-const DEFAULT_CAPTURE_MODE = "simple";
-const DEFAULT_SHUTDOWN_DEADLINE_MS = 15_000;
-const SUPERVISOR_SHUTDOWN_GRACE_MS = 2_000;
-const FORCE_RESTART_PORT_RELEASE_TIMEOUT_MS = 10_000;
-const FORCE_RESTART_PORT_RELEASE_POLL_MS = 100;
-const TYPESCRIPT_STARTUP_READY_TIMEOUT_MS = 10_000;
-const RUST_STARTUP_READY_TIMEOUT_MS = 60_000;
-const AGENT_INSPECTOR_BACKGROUND_SUPERVISOR_ENV = "AGENT_INSPECTOR_BACKGROUND_SUPERVISOR";
-
-type CaptureMode = "simple" | "full";
-
-process.title = "Agent Inspector";
-
-/**
- * Subcommand router. The legacy one-liner UX (`agent-inspector` with no args,
- * or `agent-inspector start`) starts the proxy. `agent-inspector onboard` runs
- * the guided skill install. Unknown subcommands fall back to the legacy
- * behavior so a stray positional arg doesn't break an old invocation.
- */
-const subcommand = process.argv[2];
-
-function printGlobalHelp(): void {
-  console.log(`agent-inspector ${packageJson.version} - Agent observability and knowledge capture
-
-Usage:
-  agent-inspector [start] [options]
-  agent-inspector instance <start|list|status|connect|stop|restart> ...
-  agent-inspector alias <list|add|remove> ...
-  agent-inspector onboard [options]
-  agent-inspector doctor [options]
-
-Global options:
-  -h, --help      Show this help without starting a runtime
-  -v, --version   Print the package version
-
-Start options:
-  --backend <typescript|rust> Select the backend implementation (default: rust when native package is available)
-  --backend-only, --headless  Start the API, proxy, and MCP runtime without serving the UI
-  --with-ui                  Serve the independently built UI through the protected ingress
-  --port, -p <port>          Public ingress port (default: 9527)
-  --host, -H <host>          Bind host (default: 127.0.0.1)
-  --background               Start a hidden supervisor and return after readiness
-  --no-open                  Do not open the UI after startup
-
-Run \`agent-inspector instance --help\`, \`agent-inspector onboard --help\`, or
-\`agent-inspector doctor --help\` for command-specific options.`);
-}
-
-switch (subcommand) {
-  case "--help":
-  case "-h":
-    printGlobalHelp();
-    process.exitCode = 0;
-    break;
-  case "--version":
-  case "-v":
-    console.log(packageJson.version);
-    process.exitCode = 0;
-    break;
-  case "onboard": {
-    const { runOnboard } = await import("./cli/onboard.js");
-    const code = await runOnboard(process.argv.slice(3));
-    process.exit(code);
-  }
-  case "doctor": {
-    const { runDoctor } = await import("./cli/doctor.js");
-    const code = await runDoctor(process.argv.slice(3));
-    process.exit(code);
-  }
-  case "alias": {
-    const { runAlias } = await import("./cli/alias.js");
-    const code = await runAlias(process.argv.slice(3));
-    process.exit(code);
-  }
-  case "instance": {
-    const { runInstance } = await import("./cli/instance.js");
-    const code = await runInstance(process.argv.slice(3));
-    process.exitCode = code;
-    break;
-  }
-  case undefined:
-    await runStart(process.argv.slice(2));
-    break;
-  case "start":
-    await runStart(process.argv.slice(3));
-    break;
-  default:
-    if (subcommand.startsWith("-")) {
-      await runStart(process.argv.slice(2));
-    } else {
-      console.error(`agent-inspector: unknown command ${subcommand}`);
-      console.error("Run `agent-inspector --help` for supported commands.");
-      process.exitCode = 2;
-    }
-}
-
-// -----------------------------------------------------------------------------
-// Legacy `start` behavior — start the proxy on the configured port. Extracted
-// into a function so the router above can keep the top-level flow readable.
-// -----------------------------------------------------------------------------
-async function isInspectorHealthy(port: number, host?: string, basePath = ""): Promise<boolean> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
-  try {
-    const response = await fetch(
-      appendBasePathToOrigin(urlForHost(port, probeHostForBindHost(host)), "/api/health", basePath),
-      {
-        cache: "no-store",
-        signal: controller.signal,
-      },
-    );
-    return response.ok;
-  } catch {
-    return false;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function getRunningCaptureMode(
-  port: number,
-  host?: string,
-  basePath = "",
-): Promise<CaptureMode | null> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
-  try {
-    const response = await fetch(
-      appendBasePathToOrigin(urlForHost(port, probeHostForBindHost(host)), "/api/config", basePath),
-      {
-        cache: "no-store",
-        signal: controller.signal,
-      },
-    );
-    if (!response.ok) return null;
-    const raw: unknown = await response.json();
-    return readCaptureMode(raw);
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-async function getRunningBackend(
-  port: number,
-  host?: string,
-  basePath = "",
-): Promise<BackendImplementation | null> {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
-  try {
-    const response = await fetch(
-      appendBasePathToOrigin(urlForHost(port, probeHostForBindHost(host)), "/api/health", basePath),
-      {
-        cache: "no-store",
-        signal: controller.signal,
-      },
-    );
-    if (!response.ok) return null;
-    const header = response.headers.get(AGENT_INSPECTOR_BACKEND_HEADER);
-    if (header === null) return "typescript";
-    const parsed = BackendImplementationSchema.safeParse(header.trim().toLowerCase());
-    return parsed.success ? parsed.data : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timeout);
-  }
-}
-
-function isPortAcceptingConnections(port: number, host?: string): Promise<boolean> {
-  return new Promise((resolve) => {
-    const socket = createConnection({ host: probeHostForBindHost(host), port });
-    const finish = (value: boolean): void => {
-      socket.removeAllListeners();
-      socket.destroy();
-      resolve(value);
-    };
-
-    socket.setTimeout(LOCAL_PROBE_TIMEOUT_MS);
-    socket.once("connect", () => finish(true));
-    socket.once("timeout", () => finish(false));
-    socket.once("error", () => finish(false));
-  });
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-async function waitForPortToRelease(port: number, host?: string): Promise<boolean> {
-  const deadline = Date.now() + FORCE_RESTART_PORT_RELEASE_TIMEOUT_MS;
-  while (Date.now() < deadline) {
-    if (!(await isPortAcceptingConnections(port, host))) return true;
-    await sleep(FORCE_RESTART_PORT_RELEASE_POLL_MS);
-  }
-  return !(await isPortAcceptingConnections(port, host));
-}
-
-async function waitForPortsToRelease(ports: Iterable<number>, host?: string): Promise<boolean> {
-  let released = true;
-  for (const port of ports) {
-    if (!(await waitForPortToRelease(port, host))) {
-      const remaining = findPidsByPort(port);
-      const suffix =
-        remaining.length === 0 ? "" : ` Remaining listener PID(s): ${remaining.join(", ")}.`;
-      console.error(
-        `Port ${String(port)} did not release after ${String(
-          FORCE_RESTART_PORT_RELEASE_TIMEOUT_MS,
-        )}ms.${suffix}`,
-      );
-      released = false;
-    }
-  }
-  return released;
-}
-
-function startupReadyTimeoutMs(backend: BackendImplementation): number {
-  const configured = Number(process.env["AGENT_INSPECTOR_STARTUP_READY_TIMEOUT_MS"] ?? "");
-  if (Number.isInteger(configured) && configured > 0) return configured;
-  return backend === "rust" ? RUST_STARTUP_READY_TIMEOUT_MS : TYPESCRIPT_STARTUP_READY_TIMEOUT_MS;
-}
-
-async function waitForInspectorHealthy(
-  port: number,
-  timeoutMs: number,
-  host?: string,
-  basePath = "",
-): Promise<boolean> {
-  const start = Date.now();
-  while (Date.now() - start < timeoutMs) {
-    if (await isInspectorHealthy(port, host, basePath)) return true;
-    await sleep(250);
-  }
-  return false;
-}
-
-function openBrowser(targetUrl: string): void {
-  const command = openUrlCommand(targetUrl);
-  if (command === null) return;
-  const browserProcess = spawn(command.command, command.args, {
-    stdio: "ignore",
-    detached: true,
-    windowsHide: true,
-  });
-  browserProcess.once("error", () => {
-    // Opening a browser is best-effort. Minimal Linux/container images may not
-    // include xdg-open, and that should not make the CLI look unhealthy.
-  });
-  browserProcess.unref();
-}
-
-function waitForProcessExit(child: ChildProcess): Promise<number> {
-  return new Promise((resolve) => {
-    child.once("exit", (code) => {
-      resolve(code ?? 1);
-    });
-    child.once("error", () => {
-      resolve(1);
-    });
-  });
-}
-
-function pipeServerOutput(child: ChildProcess, context: ServerOutputFilterContext): void {
-  pipeServerOutputStream(child.stdout, process.stdout, context);
-  pipeServerOutputStream(child.stderr, process.stderr, context);
-}
-
-type BackgroundSupervisorLogs = {
-  stdoutPath: string;
-  stderrPath: string;
-};
-
-function createBackgroundSupervisorLogs(
-  env: Readonly<Record<string, string | undefined>>,
-): BackgroundSupervisorLogs | null {
-  try {
-    const logsDir = join(resolveDataDir(existsSync, env), "logs");
-    mkdirSync(logsDir, { recursive: true });
-    const stdoutPath = join(logsDir, "backend.stdout.log");
-    const stderrPath = join(logsDir, "backend.stderr.log");
-    const header = `\n[${new Date().toISOString()}] Agent Inspector backend process started\n`;
-    appendFileSync(stdoutPath, header, { encoding: "utf8" });
-    appendFileSync(stderrPath, header, { encoding: "utf8" });
-    return { stdoutPath, stderrPath };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`Failed to open Agent Inspector background logs: ${message}\n`);
-    return null;
-  }
-}
-
-function pipeServerOutputStream(
-  stream: Readable | null,
-  target: Writable,
-  context: ServerOutputFilterContext,
-): void {
-  if (stream === null) return;
-
-  let buffered = "";
-  stream.on("data", (chunk: unknown) => {
-    const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
-    const lines = `${buffered}${text}`.split(/\r?\n/);
-    buffered = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!shouldSuppressServerOutputLine(line, context)) {
-        target.write(`${line}\n`);
-      }
-    }
-  });
-  stream.on("end", () => {
-    if (buffered.length === 0) return;
-    if (!shouldSuppressServerOutputLine(buffered, context)) {
-      target.write(buffered);
-    }
-    buffered = "";
-  });
-}
-
-function appendBackgroundLog(path: string, text: string): void {
-  try {
-    appendFileSync(path, text, { encoding: "utf8" });
-  } catch {
-    // Background supervisor output is best-effort: startup must not fail just
-    // because a diagnostic log file is temporarily unavailable.
-  }
-}
-
-function pipeServerOutputStreamToFile(
-  stream: Readable | null,
-  targetPath: string,
-  context: ServerOutputFilterContext,
-): void {
-  if (stream === null) return;
-
-  let buffered = "";
-  stream.on("data", (chunk: unknown) => {
-    const text = Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk);
-    const lines = `${buffered}${text}`.split(/\r?\n/);
-    buffered = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!shouldSuppressServerOutputLine(line, context)) {
-        appendBackgroundLog(targetPath, `${line}\n`);
-      }
-    }
-  });
-  stream.on("end", () => {
-    if (buffered.length === 0) return;
-    if (!shouldSuppressServerOutputLine(buffered, context)) {
-      appendBackgroundLog(targetPath, buffered);
-    }
-    buffered = "";
-  });
-}
-
-type ServerCommand = {
-  command: string;
-  args: string[];
-};
-
-type ServerCommandResolution =
-  | { kind: "success"; command: ServerCommand }
-  | { kind: "error"; message: string };
-
-function resolveServerCommand(
-  outputDir: string,
-  serverPath: string,
-  backend: BackendImplementation,
-): ServerCommandResolution {
-  if (backend === "rust") {
-    const resolved = resolveRustBackendPackage({ rootVersion: packageJson.version });
-    return resolved.kind === "error"
-      ? {
-          kind: "error",
-          message: `Cannot start the Rust backend (${resolved.error.code}): ${resolved.error.message}`,
-        }
-      : {
-          kind: "success",
-          command: { command: resolved.value.command, args: [...resolved.value.args] },
-        };
-  }
-  const brandedRuntime = join(outputDir, BRANDED_WINDOWS_RUNTIME_EXE);
-  return {
-    kind: "success",
-    command:
-      process.platform === "win32" && existsSync(brandedRuntime)
-        ? { command: brandedRuntime, args: [serverPath] }
-        : { command: process.execPath, args: [serverPath] },
-  };
-}
-
-function parseCaptureMode(value: string | undefined): CaptureMode | null {
-  switch (value) {
-    case undefined:
-      return null;
-    case "simple":
-      return "simple";
-    case "full":
-      return "full";
-    default:
-      return null;
-  }
-}
-
-function readCaptureMode(raw: unknown): CaptureMode | null {
-  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;
-  const descriptor = Object.getOwnPropertyDescriptor(raw, "captureMode");
-  const value: unknown = descriptor?.value;
-  return typeof value === "string" ? parseCaptureMode(value) : null;
-}
-
-function printAccessHints(
-  port: number,
-  host: string | undefined,
-  basePath: string,
-  serveUi: boolean,
-  publicOrigin: string | undefined,
-): void {
-  const networkUrls = networkUrlsForBindHost(port, host);
-  for (const line of formatAccessHintLines(port, networkUrls, host, basePath, serveUi)) {
-    console.log(line);
-  }
-  if (publicOrigin !== undefined) {
-    const publicBaseUrl = appendBasePathToOrigin(publicOrigin, "/", basePath);
-    if (serveUi) console.log(`   Public UI:      ${publicBaseUrl}`);
-    console.log(`   Public control Base: ${publicBaseUrl}`);
-    console.log(`   Public agent Base:   ${publicBaseUrl}`);
-    console.log(`   Public REST API: ${appendBasePathToOrigin(publicOrigin, "/api", basePath)}`);
-    console.log(`   Public proxy:    ${appendBasePathToOrigin(publicOrigin, "/proxy", basePath)}`);
-    console.log(`   Public MCP:     ${appendBasePathToOrigin(publicOrigin, "/api/mcp", basePath)}`);
-  }
-  if (!isLoopbackHost(host)) {
-    const proxyTokenConfigured = (process.env["AGENT_INSPECTOR_PROXY_TOKEN"] ?? "") !== "";
-    const legacyProxyEnabled =
-      process.env["AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY"] === "1";
-    if (proxyTokenConfigured) {
-      console.log("   Remote proxy:   dedicated token authentication enabled");
-    } else if (legacyProxyEnabled) {
-      console.warn("   Remote proxy:   UNAUTHENTICATED compatibility mode enabled");
-    } else {
-      console.warn("   Remote proxy:   blocked until AGENT_INSPECTOR_PROXY_TOKEN is configured");
-    }
-    if (process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] === "1") {
-      console.warn("   Control plane:  REMOTE ACCESS ENABLED by administrator override");
-    } else {
-      console.log("   Control plane:  local only by default");
-      if ((process.env["AGENT_INSPECTOR_CONTROL_TOKEN"] ?? "") !== "") {
-        console.log("   Remote API:     Bearer token authentication enabled");
-      }
-    }
-  }
-}
-
-function readPositiveIntegerEnv(name: string): number | undefined {
-  const raw = process.env[name];
-  if (raw === undefined || raw.trim().length === 0) return undefined;
-  const parsed = Number(raw);
-  if (Number.isSafeInteger(parsed) && parsed > 0) return parsed;
-  console.warn(`Ignoring invalid ${name}=${raw}; expected a positive integer.`);
-  return undefined;
-}
-
-function normalizeExplicitPublicOrigin(value: string | undefined): string | null | undefined {
-  if (value === undefined || value.trim().length === 0) return undefined;
-  try {
-    const parsed = new URL(value.trim());
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
-    if (parsed.username.length > 0 || parsed.password.length > 0) return null;
-    if (parsed.pathname !== "/" || parsed.search.length > 0 || parsed.hash.length > 0) return null;
-    return parsed.origin;
-  } catch {
-    return null;
-  }
-}
-
-type BackgroundSupervisorOptions = {
-  backend: BackendImplementation;
-  port: number;
-  host: string | undefined;
-  configDir: string | undefined;
-  providersJson: string | undefined;
-  captureMode: CaptureMode;
-  enableIdentityProxy: boolean;
-  legacyAliasEnabled: boolean;
-  serveUi: boolean;
-};
-
-function buildBackgroundSupervisorArgs(options: BackgroundSupervisorOptions): string[] {
-  const args = [
-    "--no-open",
-    "--backend",
-    options.backend,
-    "--port",
-    String(options.port),
-    "--mode",
-    options.captureMode,
-  ];
-  if (options.host !== undefined) {
-    args.push("--host", options.host);
-  }
-  if (options.configDir !== undefined) {
-    args.push("--config-dir", options.configDir);
-  }
-  if (options.providersJson !== undefined) {
-    args.push("--providers", options.providersJson);
-  }
-  if (!options.enableIdentityProxy) {
-    args.push("--no-identity-proxy");
-  }
-  if (options.legacyAliasEnabled) {
-    args.push("--legacy-port");
-  }
-  if (!options.serveUi) {
-    args.push("--backend-only");
-  }
-  return args;
-}
-
-function pickUpstreamPort(publicPort: number, legacyAliasPort: number | null): number {
-  const nearbyPort = publicPort + 2 <= 65535 ? publicPort + 2 : publicPort - 2;
-  const candidates =
-    publicPort === DEFAULT_PORT
-      ? [DEFAULT_UPSTREAM_PORT, nearbyPort, LEGACY_ALIAS_PORT + 2]
-      : [nearbyPort, DEFAULT_UPSTREAM_PORT, LEGACY_ALIAS_PORT + 2];
-  for (const candidate of candidates) {
-    if (
-      Number.isInteger(candidate) &&
-      candidate > 0 &&
-      candidate <= 65535 &&
-      candidate !== publicPort &&
-      candidate !== legacyAliasPort
-    ) {
-      return candidate;
-    }
-  }
-  return DEFAULT_UPSTREAM_PORT;
-}
-
-/** Try to start an identity-proxy ingress. The primary caller treats a
- *  `null` result as fatal; only an optional compatibility alias may degrade. */
-async function tryStartIdentityProxy(
-  identityPort: number,
-  upstreamPort: number,
-  listenHost: string,
-  upstreamHost: string,
-  managedInstance: ManagedInstanceControlOptions | undefined,
-  allowedUiOrigins: readonly string[],
-  uiDirectory: string | undefined,
-  publicOrigin: string | undefined,
-  backend: BackendImplementation,
-): Promise<import("node:http").Server | null> {
-  try {
-    const server = await startIdentityProxy({
-      listenPort: identityPort,
-      listenHost,
-      upstreamHost,
-      upstreamPort,
-      backendImplementation: backend,
-      restrictRemoteControl: !isLoopbackHost(listenHost),
-      allowRemoteControl: process.env["AGENT_INSPECTOR_ALLOW_REMOTE_CONTROL"] === "1",
-      controlToken: process.env["AGENT_INSPECTOR_CONTROL_TOKEN"],
-      proxyToken: process.env["AGENT_INSPECTOR_PROXY_TOKEN"],
-      allowUnauthenticatedRemoteProxy:
-        process.env["AGENT_INSPECTOR_ALLOW_UNAUTHENTICATED_REMOTE_PROXY"] === "1",
-      trustedHosts: (process.env["AGENT_INSPECTOR_TRUSTED_HOSTS"] ?? "")
-        .split(",")
-        .map((host) => host.trim())
-        .filter((host) => host.length > 0),
-      allowedUiOrigins,
-      uiDirectory,
-      publicOrigin,
-      maxRequestBytes: readPositiveIntegerEnv("AGENT_INSPECTOR_MAX_REQUEST_BYTES"),
-      requestTimeoutMs: readPositiveIntegerEnv("AGENT_INSPECTOR_REQUEST_TIMEOUT_MS"),
-      managedInstance,
-      instanceApiHandler: backend === "rust" ? handleNamedInstanceApi : undefined,
-    });
-    return server;
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    console.warn(`[identity-proxy] Could not listen on port ${identityPort}: ${message}.`);
-    return null;
-  }
-}
-
-async function runStart(args: string[]): Promise<void> {
-  const managedLaunchResult = readManagedInstanceLaunch(process.env);
-  if (managedLaunchResult.kind === "invalid") {
-    console.error(managedLaunchResult.message);
-    process.exitCode = 1;
-    return;
-  }
-  const managedLaunch: ManagedInstanceLaunch | null =
-    managedLaunchResult.kind === "managed" ? managedLaunchResult.launch : null;
-  const envPort = process.env["AGENT_INSPECTOR_PORT"] ?? process.env["PORT"];
-  const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
-  const envHost = process.env["NITRO_HOST"] ?? process.env["HOST"];
-  const envMode =
-    process.env["AGENT_INSPECTOR_CAPTURE_MODE"] ?? process.env["AGENT_INSPECTOR_MODE"];
-  const rawEnvBackend = process.env[AGENT_INSPECTOR_BACKEND_ENV];
-  const envBackend =
-    rawEnvBackend === undefined ? undefined : parseBackendImplementation(rawEnvBackend);
-  if (envBackend === null) {
-    console.error(
-      `Invalid ${AGENT_INSPECTOR_BACKEND_ENV}. Use typescript or rust; no backend was started.`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  let port = portDefault;
-  let host =
-    envHost !== undefined && envHost.trim().length > 0 ? envHost.trim() : DEFAULT_BIND_HOST;
-  let open = true;
-  let openWasSpecified = false;
-  let background = false;
-  let forceRestart = false;
-  let configDir: string | undefined;
-  let providersJson: string | undefined;
-  let captureMode: CaptureMode = DEFAULT_CAPTURE_MODE;
-  let captureModeWasSpecified = false;
-  let enableIdentityProxy = true;
-  let legacyAliasEnabled = false;
-  let serveUi = process.env["AGENT_INSPECTOR_BACKEND_ONLY"] !== "1";
-  let backend: BackendImplementation = envBackend ?? "typescript";
-  let backendWasSpecified = envBackend !== undefined;
-
-  if (envMode !== undefined && envMode !== "") {
-    const parsedMode = parseCaptureMode(envMode);
-    if (parsedMode === null) {
-      console.error(`Invalid capture mode: ${envMode}. Use simple or full.`);
-      process.exitCode = 1;
-      return;
-    }
-    captureMode = parsedMode;
-    captureModeWasSpecified = true;
-  }
-
-  if (host !== undefined && !isValidBindHost(host)) {
-    console.error(`Invalid host: ${host}. Use an IP or hostname without protocol/path.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i] ?? "";
-    if (arg.startsWith("--port=")) {
-      port = Number(arg.slice(arg.indexOf("=") + 1));
-      continue;
-    }
-    if (arg.startsWith("--host=")) {
-      const value = arg.slice(arg.indexOf("=") + 1).trim();
-      if (!isValidBindHost(value)) {
-        console.error(`Invalid host: ${value}. Use an IP or hostname without protocol/path.`);
-        process.exitCode = 1;
-        return;
-      }
-      host = value;
-      continue;
-    }
-    if (arg.startsWith("--mode=") || arg.startsWith("--capture-mode=")) {
-      const value = arg.slice(arg.indexOf("=") + 1);
-      const parsedMode = parseCaptureMode(value);
-      if (parsedMode === null) {
-        console.error(`Invalid capture mode: ${value}. Use simple or full.`);
-        process.exitCode = 1;
-        return;
-      }
-      captureMode = parsedMode;
-      captureModeWasSpecified = true;
-      continue;
-    }
-    if (arg.startsWith("--backend=")) {
-      const parsedBackend = BackendImplementationSchema.safeParse(
-        arg
-          .slice(arg.indexOf("=") + 1)
-          .trim()
-          .toLowerCase(),
-      );
-      if (!parsedBackend.success) {
-        console.error("Invalid backend implementation. Use typescript or rust.");
-        process.exitCode = 1;
-        return;
-      }
-      backend = parsedBackend.data;
-      backendWasSpecified = true;
-      continue;
-    }
-    switch (arg) {
-      case "--port":
-      case "-p":
-        port = Number(args[i + 1]);
-        i++;
-        break;
-      case "--host":
-      case "-H": {
-        const value = args[i + 1]?.trim() ?? "";
-        if (!isValidBindHost(value)) {
-          console.error(`Invalid host: ${value}. Use an IP or hostname without protocol/path.`);
-          process.exitCode = 1;
-          return;
-        }
-        host = value;
-        i++;
-        break;
-      }
-      case "--backend": {
-        const parsedBackend = BackendImplementationSchema.safeParse(
-          args[i + 1]?.trim().toLowerCase(),
-        );
-        if (!parsedBackend.success) {
-          console.error("Invalid backend implementation. Use typescript or rust.");
-          process.exitCode = 1;
-          return;
-        }
-        backend = parsedBackend.data;
-        backendWasSpecified = true;
-        i++;
-        break;
-      }
-      case "--no-open":
-        open = false;
-        openWasSpecified = true;
-        break;
-      case "--open":
-        open = true;
-        openWasSpecified = true;
-        break;
-      case "--force-restart":
-      case "--restart":
-        forceRestart = true;
-        break;
-      case "--background":
-        background = true;
-        break;
-      case "--backend-only":
-      case "--headless":
-        serveUi = false;
-        open = false;
-        break;
-      case "--with-ui":
-        serveUi = true;
-        break;
-      case "--config-dir":
-        configDir = args[i + 1];
-        i++;
-        break;
-      case "--providers":
-        providersJson = args[i + 1];
-        i++;
-        break;
-      case "--mode":
-      case "--capture-mode": {
-        const value = args[i + 1];
-        const parsedMode = parseCaptureMode(value);
-        if (parsedMode === null) {
-          console.error(`Invalid capture mode: ${String(value)}. Use simple or full.`);
-          process.exitCode = 1;
-          return;
-        }
-        captureMode = parsedMode;
-        captureModeWasSpecified = true;
-        i++;
-        break;
-      }
-      case "--no-identity-proxy":
-        enableIdentityProxy = false;
-        break;
-      case "--identity-proxy-port": {
-        const value = args[i + 1];
-        const parsed = Number(value);
-        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
-          console.error(`Invalid identity-proxy port: ${String(value)}.`);
-          process.exitCode = 1;
-          return;
-        }
-        port = parsed;
-        i++;
-        break;
-      }
-      case "--no-legacy-port":
-        legacyAliasEnabled = false;
-        break;
-      case "--legacy-port":
-        legacyAliasEnabled = true;
-        break;
-      case "--help":
-      case "-h":
-        printGlobalHelp();
-        return;
-      case "--version":
-      case "-v":
-        console.log(packageJson.version);
-        return;
-      default:
-        console.error(`agent-inspector start: unknown option ${arg}`);
-        console.error("Run `agent-inspector --help` for supported options.");
-        process.exitCode = 2;
-        return;
-    }
-  }
-
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    console.error(`Invalid port: ${String(port)}. Use --port <1-65535>.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (!backendWasSpecified) {
-    backend =
-      managedLaunch?.backend ??
-      resolvePreferredBackendImplementation({ rootVersion: packageJson.version });
-  }
-
-  if (managedLaunch !== null && managedLaunch.backend !== backend) {
-    console.error(
-      `Managed instance backend mismatch: launch identity requires ${managedLaunch.backend}, but ${backend} was selected.`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  if (!enableIdentityProxy && process.env["AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS"] !== "1") {
-    console.error(
-      "Refusing --no-identity-proxy because it also disables Host, CSRF, credential-scope, and first-hop budget enforcement. Keep the protected ingress enabled or set AGENT_INSPECTOR_ALLOW_UNPROTECTED_INGRESS=1 explicitly for temporary diagnostics.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-  if (!serveUi) open = false;
-  if (!enableIdentityProxy && serveUi) {
-    console.error(
-      "The decoupled UI is composed only by the protected ingress. Use --backend-only with --no-identity-proxy, or keep the identity proxy enabled.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const uiOriginAllowlist = parseUiOriginAllowlist(process.env["AGENT_INSPECTOR_UI_ORIGINS"]);
-  if (uiOriginAllowlist.rejected.length > 0) {
-    console.error(
-      `Invalid AGENT_INSPECTOR_UI_ORIGINS entries: ${uiOriginAllowlist.rejected.join(", ")}. Only exact loopback http(s) origins are accepted; use a same-origin authenticated gateway for remote UI hosting.`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const publicOrigin = normalizeExplicitPublicOrigin(process.env["AGENT_INSPECTOR_PUBLIC_ORIGIN"]);
-  if (publicOrigin === null) {
-    console.error(
-      "Invalid AGENT_INSPECTOR_PUBLIC_ORIGIN. Use an exact http(s) origin without credentials, path, query, or fragment.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const uiDirectoryCandidate = join(__dirname, "../.output/ui");
-  const uiIndexPath = join(uiDirectoryCandidate, "index.html");
-  const uiDirectory = serveUi && existsSync(uiIndexPath) ? uiDirectoryCandidate : undefined;
-  if (serveUi && uiDirectory === undefined) {
-    console.error(
-      `Agent Inspector UI artifact is missing at ${uiIndexPath}. Run the composed build or use --backend-only.`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-
-  const outputDir = __dirname;
-  const serverPath = join(outputDir, "../.output/server/index.mjs");
-  const serverCommandResolution = resolveServerCommand(outputDir, serverPath, backend);
-  if (serverCommandResolution.kind === "error") {
-    console.error(serverCommandResolution.message);
-    process.exitCode = 1;
-    return;
-  }
-  const serverCommand = serverCommandResolution.command;
-
-  /**
-   * Check if a port is in use and kill the process using it
-   */
-  function killProcessOnPort(targetPort: number): void {
-    const pids = findPidsByPort(targetPort);
-    for (const pid of pids) {
-      console.log(`Killing process ${pid} on port ${targetPort}...`);
-      if (!killPid(pid)) {
-        console.error(`Failed to kill process ${pid} on port ${targetPort}.`);
-      }
-    }
-  }
-
-  const legacyAliasPort =
-    enableIdentityProxy && legacyAliasEnabled && port === DEFAULT_PORT ? LEGACY_ALIAS_PORT : null;
-
-  // TanStack Start listens on the private upstream port; identity proxies own
-  // the public-facing port(s). When the identity proxy is disabled we fall
-  // back to TanStack listening on the public port directly.
-  const upstreamPort =
-    managedLaunch === null
-      ? enableIdentityProxy
-        ? pickUpstreamPort(port, legacyAliasPort)
-        : port
-      : managedLaunch.upstreamPort;
-  if (
-    upstreamPort < 1 ||
-    upstreamPort > 65_535 ||
-    (enableIdentityProxy && upstreamPort === port) ||
-    upstreamPort === legacyAliasPort
-  ) {
-    console.error(`Invalid managed upstream port: ${String(upstreamPort)}.`);
-    process.exitCode = 1;
-    return;
-  }
-  const upstreamHost = enableIdentityProxy ? DEFAULT_BIND_HOST : host;
-  process.env["PORT"] = String(upstreamPort);
-
-  const configuredBasePath = process.env[AGENT_INSPECTOR_BASE_PATH_ENV];
-  if (configuredBasePath !== undefined && normalizePublicBasePath(configuredBasePath) === null) {
-    console.error(
-      `Invalid ${AGENT_INSPECTOR_BASE_PATH_ENV}. Use / for root or URL-safe path segments such as /inspector or /foo-bar/v1.`,
-    );
-    process.exitCode = 1;
-    return;
-  }
-  const basePath = getConfiguredBasePath(process.env);
-  const bindOrigin = urlForHost(port, host);
-  const outwardOrigin = publicOrigin ?? bindOrigin;
-  const surfaceBaseUrl = appendBasePathToOrigin(outwardOrigin, "/", basePath);
-  const uiUrl = serveUi ? surfaceBaseUrl : null;
-  const proxyUrl = appendBasePathToOrigin(outwardOrigin, "/proxy", basePath);
-  const openAiProxyUrl = appendBasePathToOrigin(outwardOrigin, "/proxy/v1", basePath);
-  const proxyMessagesUrl = appendBasePathToOrigin(outwardOrigin, "/proxy/v1/messages", basePath);
-  const legacyUrl =
-    legacyAliasPort === null
-      ? null
-      : appendBasePathToOrigin(localUrlForPort(legacyAliasPort), "/", basePath);
-  const legacyProxyUrl =
-    legacyAliasPort === null
-      ? null
-      : appendBasePathToOrigin(localUrlForPort(legacyAliasPort), "/proxy", basePath);
-  const legacyMcpUrl =
-    legacyAliasPort === null
-      ? null
-      : appendBasePathToOrigin(localUrlForPort(legacyAliasPort), "/api/mcp", basePath);
-
-  if (!forceRestart && (await isInspectorHealthy(port, host, basePath))) {
-    const runningBackend = await getRunningBackend(port, host, basePath);
-    if (runningBackend !== backend) {
-      console.error(
-        runningBackend === null
-          ? `A healthy Agent Inspector is already running at ${surfaceBaseUrl}, but its backend implementation cannot be verified. Use --force-restart to replace it safely.`
-          : `Agent Inspector at ${surfaceBaseUrl} uses ${runningBackend}, but ${backend} was requested. Use --force-restart to switch implementations.`,
-      );
-      process.exitCode = 1;
-      return;
-    }
-    console.log(
-      `agent-inspector ${serveUi ? "is already running" : "backend is already running"} at ${surfaceBaseUrl}`,
-    );
-    printAccessHints(port, host, basePath, serveUi, publicOrigin);
-    if (captureModeWasSpecified) {
-      const runningMode = await getRunningCaptureMode(port, host, basePath);
-      if (runningMode !== null && runningMode !== captureMode) {
-        console.log(`Existing instance capture mode is ${runningMode}; requested ${captureMode}.`);
-        console.log(`Use --force-restart to restart with ${captureMode} mode.`);
-      }
-    }
-    console.log(`Use --force-restart to restart the existing instance.`);
-    if (open && openWasSpecified && uiUrl !== null) {
-      openBrowser(uiUrl);
-    }
-    return;
-  }
-
-  if (!forceRestart && (await isPortAcceptingConnections(port, host))) {
-    console.error(`Port ${port} is already in use, but it is not a healthy agent-inspector.`);
-    console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (forceRestart) {
-    const restartPorts = new Set<number>();
-    restartPorts.add(port);
-    if (enableIdentityProxy) {
-      restartPorts.add(upstreamPort);
-      if (legacyAliasPort !== null) restartPorts.add(legacyAliasPort);
-    }
-    for (const targetPort of restartPorts) {
-      killProcessOnPort(targetPort);
-    }
-    if (!(await waitForPortsToRelease(restartPorts, host))) {
-      console.error("Agent Inspector could not restart because one or more ports are still busy.");
-      process.exitCode = 1;
-      return;
-    }
-  }
-
-  if (background && enableIdentityProxy) {
-    const cliEntry = process.argv[1];
-    if (cliEntry === undefined || cliEntry.length === 0) {
-      console.error("Cannot resolve agent-inspector CLI entry for background supervisor.");
-      process.exitCode = 1;
-      return;
-    }
-
-    const supervisorArgs = buildBackgroundSupervisorArgs({
-      backend,
-      port,
-      host,
-      configDir,
-      providersJson,
-      captureMode,
-      enableIdentityProxy,
-      legacyAliasEnabled,
-      serveUi,
-    });
-    const supervisorProcess = spawn(process.execPath, [cliEntry, ...supervisorArgs], {
-      stdio: "ignore",
-      detached: true,
-      env: {
-        ...process.env,
-        [AGENT_INSPECTOR_CLI_ENTRY_ENV]: cliEntry,
-        [AGENT_INSPECTOR_BACKGROUND_SUPERVISOR_ENV]: "1",
-      },
-      windowsHide: true,
-    });
-    supervisorProcess.once("error", (err) => {
-      console.error(`Failed to start Agent Inspector background supervisor: ${err.message}`);
-    });
-    supervisorProcess.unref();
-
-    if (await waitForInspectorHealthy(port, startupReadyTimeoutMs(backend), host, basePath)) {
-      console.log(
-        `agent-inspector background ${serveUi ? "server" : "backend"} is ready at ${surfaceBaseUrl}`,
-      );
-      printAccessHints(port, host, basePath, serveUi, publicOrigin);
-      if (legacyProxyUrl !== null && legacyMcpUrl !== null) {
-        console.log(`   Legacy proxy:  ${legacyProxyUrl}`);
-        console.log(`   Legacy MCP:    ${legacyMcpUrl}`);
-      }
-      console.log(``);
-      console.log(`Route AI coding tools through the identity proxy for accurate PID attribution:`);
-      console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`);
-      console.log(`   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`);
-      console.log(`   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`);
-      if (open && openWasSpecified && uiUrl !== null) {
-        openBrowser(uiUrl);
-      }
-      return;
-    }
-
-    console.error(`agent-inspector background server did not become ready at ${surfaceBaseUrl}.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  // Start the server with the branded Windows runtime when postinstall created it.
-  const serverEnv = { ...process.env };
-  const currentCliEntry = process.env[AGENT_INSPECTOR_CLI_ENTRY_ENV] ?? process.argv[1];
-  if (currentCliEntry !== undefined && currentCliEntry.length > 0) {
-    serverEnv[AGENT_INSPECTOR_CLI_ENTRY_ENV] = currentCliEntry;
-  }
-  if (configDir !== undefined) {
-    // Normalize MSYS / Git Bash paths to Windows native form.
-    // On Windows, `path.join('/c/Users/foo')` becomes `\c\Users\foo`
-    // (leading slash converted to backslash).
-    // Child processes spawned by `spawn()` won't follow that style, so
-    // rewrite `\c\...` (or any `\x\...` drive) to `C:\...` before
-    // handing the path to the proxy server. No-op on already-native
-    // Windows paths and on non-Windows platforms.
-    let resolvedPath = join(configDir);
-    const msysMatch = /^\\([a-z])\\(.*)$/i.exec(resolvedPath);
-    if (msysMatch !== null) {
-      const drive = (msysMatch[1] ?? "").toUpperCase();
-      const rest = msysMatch[2] ?? "";
-      resolvedPath = `${drive}:\\${rest}`;
-    } else {
-      resolvedPath = resolvePath(resolvedPath);
-    }
-    serverEnv["AGENT_INSPECTOR_CONFIG_DIR"] = resolvedPath;
-  }
-  if (providersJson !== undefined) {
-    serverEnv["AGENT_INSPECTOR_PROVIDERS_JSON"] = providersJson;
-  }
-  serverEnv["HOST"] = upstreamHost;
-  serverEnv["NITRO_HOST"] = upstreamHost;
-  serverEnv["PORT"] = String(upstreamPort);
-  serverEnv["NITRO_PORT"] = String(upstreamPort);
-  if (enableIdentityProxy && basePath.length > 0) {
-    serverEnv[AGENT_INSPECTOR_INTERNAL_STRIPPED_BASE_PATH_ENV] = "1";
-  }
-  serverEnv["AGENT_INSPECTOR_PUBLIC_PORT"] = String(port);
-  serverEnv["PROXY_PORT"] = String(upstreamPort);
-  serverEnv["AGENT_INSPECTOR_CAPTURE_MODE"] = captureMode;
-  serverEnv[AGENT_INSPECTOR_BACKEND_ENV] = backend;
-  serverEnv["AGENT_INSPECTOR_BACKEND_ONLY"] = serveUi ? "0" : "1";
-  const workerDir = join(__dirname, "workers");
-  if (existsSync(workerDir)) {
-    serverEnv["AGENT_INSPECTOR_WORKER_DIR"] = workerDir;
-  }
-  const runningInBackgroundSupervisor =
-    process.env[AGENT_INSPECTOR_BACKGROUND_SUPERVISOR_ENV] === "1";
-  const backgroundSupervisorLogs = runningInBackgroundSupervisor
-    ? createBackgroundSupervisorLogs(serverEnv)
-    : null;
-  const shouldPipeBackgroundRuntimeLogs = backgroundSupervisorLogs !== null;
-  const serverProcess = spawn(serverCommand.command, serverCommand.args, {
-    stdio:
-      managedLaunch === null
-        ? background && !shouldPipeBackgroundRuntimeLogs
-          ? ["ignore", "ignore", "ignore"]
-          : ["ignore", "pipe", "pipe"]
-        : backend === "typescript"
-          ? background && !shouldPipeBackgroundRuntimeLogs
-            ? ["ignore", "ignore", "ignore", "ipc"]
-            : ["ignore", "pipe", "pipe", "ipc"]
-          : background
-            ? shouldPipeBackgroundRuntimeLogs
-              ? ["ignore", "pipe", "pipe"]
-              : ["ignore", "ignore", "ignore"]
-            : ["ignore", "pipe", "pipe"],
-    detached: background,
-    env: serverEnv,
-    windowsHide: background || runningInBackgroundSupervisor,
-  });
-  serverProcess.once("error", (err) => {
-    console.error(`Failed to start Agent Inspector runtime: ${err.message}`);
-  });
-  const serverExit = waitForProcessExit(serverProcess);
-  if (!background || backgroundSupervisorLogs !== null) {
-    const outputContext = {
-      enableIdentityProxy,
-      publicPort: port,
-      upstreamPort,
-    };
-    if (backgroundSupervisorLogs === null) {
-      pipeServerOutput(serverProcess, outputContext);
-    } else {
-      pipeServerOutputStreamToFile(
-        serverProcess.stdout,
-        backgroundSupervisorLogs.stdoutPath,
-        outputContext,
-      );
-      pipeServerOutputStreamToFile(
-        serverProcess.stderr,
-        backgroundSupervisorLogs.stderrPath,
-        outputContext,
-      );
-    }
-  }
-
-  // Identity proxy — a native Node HTTP server that sits in front of
-  // TanStack Start and looks up each client's PID via the OS connection
-  // table, injecting the result as `X-Agent-Inspector-Client-*` headers.
-  // This lets AI tools (which can't easily set those headers themselves)
-  // still get accurate session attribution. Started only after TanStack
-  // Start is healthy, so the upstream is ready by the time clients connect.
-  const identityProxies: Array<{
-    label: "primary" | "legacy";
-    port: number;
-    server: import("node:http").Server;
-  }> = [];
-  let supervisorShutdownPromise: Promise<void> | null = null;
-  const requestSupervisorShutdown = (signal: "SIGINT" | "SIGTERM"): void => {
-    if (supervisorShutdownPromise !== null) return;
-    for (const proxy of identityProxies) stopIdentityProxyAdmission(proxy.server);
-    if (managedLaunch !== null && backend === "typescript" && serverProcess.connected) {
-      serverProcess.send(managedInstanceShutdownMessage(managedLaunch.controlToken), (error) => {
-        if (error !== null && serverProcess.exitCode === null) serverProcess.kill(signal);
-      });
-    } else {
-      serverProcess.kill(signal);
-    }
-
-    const childDeadline =
-      readPositiveIntegerEnv("AGENT_INSPECTOR_SHUTDOWN_TIMEOUT_MS") ?? DEFAULT_SHUTDOWN_DEADLINE_MS;
-    let deadline: ReturnType<typeof setTimeout> | null = null;
-    let forced = false;
-    const graceful = Promise.all([
-      serverExit.then(() => undefined),
-      ...identityProxies.map(async (proxy) => await closeIdentityProxyGracefully(proxy.server)),
-    ]).then(() => undefined);
-    const timedOut = new Promise<void>((resolve) => {
-      deadline = setTimeout(() => {
-        forced = true;
-        for (const proxy of identityProxies) forceCloseIdentityProxy(proxy.server);
-        if (serverProcess.exitCode === null) serverProcess.kill("SIGKILL");
-        resolve();
-      }, childDeadline + SUPERVISOR_SHUTDOWN_GRACE_MS);
-    });
-    supervisorShutdownPromise = Promise.race([graceful, timedOut])
-      .finally(() => {
-        if (deadline !== null) clearTimeout(deadline);
-      })
-      .then(() => {
-        if (forced) process.exitCode = 1;
-      });
-  };
-  const handleSigint = (): void => requestSupervisorShutdown("SIGINT");
-  const handleSigterm = (): void => requestSupervisorShutdown("SIGTERM");
-  const currentSupervisorShutdown = (): Promise<void> | null => supervisorShutdownPromise;
-  process.on("SIGINT", handleSigint);
-  process.on("SIGTERM", handleSigterm);
-  const managedInstanceControl: ManagedInstanceControlOptions | undefined =
-    managedLaunch === null
-      ? undefined
-      : {
-          name: managedLaunch.name,
-          instanceId: managedLaunch.instanceId,
-          launchId: managedLaunch.launchId,
-          controlToken: managedLaunch.controlToken,
-          supervisorPid: process.pid,
-          startedAt: managedLaunch.startedAt,
-          backend,
-          publicPort: port,
-          upstreamPort,
-          requestShutdown: () => requestSupervisorShutdown("SIGTERM"),
-        };
-  if (enableIdentityProxy) {
-    const primaryProxy = await tryStartIdentityProxy(
-      port,
-      upstreamPort,
-      host,
-      upstreamHost,
-      managedInstanceControl,
-      uiOriginAllowlist.origins,
-      uiDirectory,
-      publicOrigin,
-      backend,
-    );
-    if (primaryProxy === null) {
-      console.error(
-        `Agent Inspector could not bind its protected public ingress at ${bindOrigin}; stopping the private backend.`,
-      );
-      requestSupervisorShutdown("SIGTERM");
-      const failedStartupShutdown = currentSupervisorShutdown();
-      if (failedStartupShutdown !== null) await failedStartupShutdown;
-      process.off("SIGINT", handleSigint);
-      process.off("SIGTERM", handleSigterm);
-      process.exitCode = 1;
-      return;
-    }
-    identityProxies.push({ label: "primary", port, server: primaryProxy });
-    if (legacyAliasPort !== null) {
-      const legacyProxy = await tryStartIdentityProxy(
-        legacyAliasPort,
-        upstreamPort,
-        host,
-        upstreamHost,
-        managedInstanceControl,
-        uiOriginAllowlist.origins,
-        uiDirectory,
-        publicOrigin,
-        backend,
-      );
-      if (legacyProxy !== null) {
-        identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });
-      }
-    }
-  }
-
-  if (background) {
-    serverProcess.unref();
-    // Probe the upstream TanStack port directly — the identity proxy is
-    // not started yet so the public port is not yet accepting traffic.
-    const upstreamProbeBasePath = enableIdentityProxy ? "" : basePath;
-    if (
-      await waitForInspectorHealthy(
-        upstreamPort,
-        startupReadyTimeoutMs(backend),
-        host,
-        upstreamProbeBasePath,
-      )
-    ) {
-      console.log(
-        `agent-inspector background ${serveUi ? "server" : "backend"} is ready at ${surfaceBaseUrl}`,
-      );
-      if (identityProxies.length > 0) {
-        console.log(`Identity proxy ready on port ${port} (PID-attributing proxy).`);
-      }
-      printAccessHints(port, host, basePath, serveUi, publicOrigin);
-      if (legacyProxyUrl !== null && legacyMcpUrl !== null) {
-        console.log(`   Legacy proxy:  ${legacyProxyUrl}`);
-        console.log(`   Legacy MCP:    ${legacyMcpUrl}`);
-      }
-      if (identityProxies.length > 0) {
-        console.log(
-          ``,
-          `Route AI coding tools through the identity proxy for accurate PID attribution:`,
-          `   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`,
-          `   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`,
-          `   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`,
-          legacyProxyUrl === null
-            ? `   Override the port with --port <n> when needed.`
-            : `   Legacy configs using ${legacyProxyUrl} still work.`,
-        );
-      }
-      return;
-    }
-    console.error(`agent-inspector background server did not become ready at ${surfaceBaseUrl}.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (!(await waitForInspectorHealthy(port, startupReadyTimeoutMs(backend), host, basePath))) {
-    console.error(`Agent Inspector did not become ready at ${surfaceBaseUrl}; stopping startup.`);
-    requestSupervisorShutdown("SIGTERM");
-    const failedStartupShutdown = currentSupervisorShutdown();
-    if (failedStartupShutdown !== null) await failedStartupShutdown;
-    process.off("SIGINT", handleSigint);
-    process.off("SIGTERM", handleSigterm);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (identityProxies.length > 0) {
-    console.log(``);
-    console.log(`Identity proxy ready at ${bindOrigin} (PID-attributing ingress).`);
-    if (legacyAliasPort !== null) {
-      const legacyReady = identityProxies.some((proxy) => proxy.label === "legacy");
-      if (legacyReady) {
-        console.log(`   Legacy alias ready at http://localhost:${legacyAliasPort}.`);
-      }
-    }
-    if (upstreamPort !== port) {
-      console.log(`   Internal runtime port ${upstreamPort} is hidden behind the public proxy.`);
-    }
-  }
-
-  console.log(
-    `${serveUi ? "UI and backend" : "Backend control and agent runtime"} running at ${surfaceBaseUrl}`,
-  );
-  console.log(`   Capture mode: ${captureMode}`);
-  console.log(`   Backend: ${backend}`);
-  console.log(`   Proxy: ${proxyUrl}`);
-  printAccessHints(port, host, basePath, serveUi, publicOrigin);
-  if (legacyUrl !== null && legacyProxyUrl !== null && legacyMcpUrl !== null) {
-    console.log(`   Legacy UI:      ${legacyUrl}`);
-    console.log(`   Legacy proxy:   ${legacyProxyUrl}`);
-    console.log(`   Legacy MCP:     ${legacyMcpUrl}`);
-  }
-  console.log(``);
-  console.log(`Route AI coding tools through the proxy:`);
-  console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${proxyUrl} claude`);
-  console.log(`   OpenCode:     LLM_BASE_URL=${proxyUrl} opencode`);
-  console.log(`   MiMo Code:    OPENAI_BASE_URL=${openAiProxyUrl} mimo`);
-  console.log(`   Direct HTTP:  curl ${proxyMessagesUrl} -d '{"model":"...","messages":[...]}'`);
-  console.log(
-    `   Remote/container tools: use the Network proxy URL above when shown; otherwise restart with --host 0.0.0.0 or a reachable IP.`,
-  );
-  if (open && uiUrl !== null) openBrowser(uiUrl);
-
-  process.exitCode = await serverExit;
-
-  const activeSupervisorShutdown = currentSupervisorShutdown();
-  if (activeSupervisorShutdown !== null) {
-    await activeSupervisorShutdown;
-  } else {
-    await Promise.all(identityProxies.map((proxy) => closeIdentityProxyGracefully(proxy.server)));
-  }
-  process.off("SIGINT", handleSigint);
-  process.off("SIGTERM", handleSigterm);
-}