@tonyclaw/agent-inspector 2.1.23 → 3.0.0

package/.output/server/index.mjs

@@ -38,114 +38,114 @@ const assets = {
   "/assets/alibaba-TTwafVwX.svg": {
     "type": "image/svg+xml",
     "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
-    "mtime": "2026-07-06T23:30:24.816Z",
+    "mtime": "2026-07-07T00:31:07.940Z",
     "size": 5915,
     "path": "../public/assets/alibaba-TTwafVwX.svg"
   },
-  "/assets/index-B26q0-ch.js": {
+  "/assets/CompareDrawer-ZL1yvIH6.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"74-AZvnGEhntbiyIDS+wwwbTZjCuCw"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 116,
-    "path": "../public/assets/index-B26q0-ch.js"
+    "etag": '"4bbf-CIi9MFvNx5XBmXT0nU0DPL42gd8"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 19391,
+    "path": "../public/assets/CompareDrawer-ZL1yvIH6.js"
   },
-  "/assets/json-viewer-DERQNZRV.js": {
+  "/assets/json-viewer-B9gYSlz7.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"1ae6-A6B2jiKFX+jryATLfM15t7QIsvM"',
-    "mtime": "2026-07-06T23:30:24.817Z",
+    "etag": '"1ae6-eUFnKJytY27s8aDs8Lo5QbvfXRw"',
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 6886,
-    "path": "../public/assets/json-viewer-DERQNZRV.js"
+    "path": "../public/assets/json-viewer-B9gYSlz7.js"
   },
   "/assets/minimax-BPMzvuL-.jpeg": {
     "type": "image/jpeg",
     "etag": '"1b06-IwivU89ko5UTMUM1/t7hn4sQK9A"',
-    "mtime": "2026-07-06T23:30:24.816Z",
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 6918,
     "path": "../public/assets/minimax-BPMzvuL-.jpeg"
   },
-  "/assets/index-CxszCIFm.css": {
-    "type": "text/css; charset=utf-8",
-    "etag": '"219d3-hGkO4OXmpghyDnxd7KIL9unRxwQ"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 137683,
-    "path": "../public/assets/index-CxszCIFm.css"
-  },
-  "/assets/CompareDrawer-Cvgl_Jmi.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"4bbf-qdrjZBBOyzn/JHMYJ2UAiNDDbFQ"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 19391,
-    "path": "../public/assets/CompareDrawer-Cvgl_Jmi.js"
-  },
-  "/assets/index-BZxLBVYd.js": {
+  "/assets/index-_inxJ5Yi.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"1cd2c-eSvMM8zbdBG02FS4JJNg0vJ028w"',
-    "mtime": "2026-07-06T23:30:24.817Z",
+    "etag": '"1cd2c-oLlmpQRDfuZo5GBb+xP4a/4UY4g"',
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 118060,
-    "path": "../public/assets/index-BZxLBVYd.js"
+    "path": "../public/assets/index-_inxJ5Yi.js"
   },
-  "/assets/RequestAnatomy-CrLSqdiA.js": {
+  "/assets/index-BJvPLWvO.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"43f2-YwOCt5e63SibXMhWqzHRxd1nNC8"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 17394,
-    "path": "../public/assets/RequestAnatomy-CrLSqdiA.js"
+    "etag": '"74-BHSPo95dMXATS9vdlnudttsOua0"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 116,
+    "path": "../public/assets/index-BJvPLWvO.js"
   },
-  "/assets/ReplayDialog-DeEELx0X.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"31d6-hWOAjkfta2prr+9EmQOXzNOAzTU"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 12758,
-    "path": "../public/assets/ReplayDialog-DeEELx0X.js"
+  "/assets/index-Tq5s9NV0.css": {
+    "type": "text/css; charset=utf-8",
+    "etag": '"22408-MQKT02eqQudVEj/DozyiEJoTl6E"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 140296,
+    "path": "../public/assets/index-Tq5s9NV0.css"
   },
-  "/assets/ResponseView-CFIqDL5E.js": {
+  "/assets/RequestAnatomy-CVt2vHih.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"47fa-+VN13C6cvB2BYNKPjLEy9ibIswM"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 18426,
-    "path": "../public/assets/ResponseView-CFIqDL5E.js"
+    "etag": '"43f2-Pb1rRv8VdlgdFtX52V4rCBrFcCo"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 17394,
+    "path": "../public/assets/RequestAnatomy-CVt2vHih.js"
   },
-  "/assets/main-BoshTI0W.js": {
+  "/assets/StreamingChunkSequence-DQFhpV_4.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"512fd-NlLbmALn+PuYHWA4Dj6BVyzFIuM"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 332541,
-    "path": "../public/assets/main-BoshTI0W.js"
+    "etag": '"dd6-SMIn60D5iwf77dJ0W8fWzwFQ+y4"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 3542,
+    "path": "../public/assets/StreamingChunkSequence-DQFhpV_4.js"
   },
   "/assets/zhipuai-BPNAnxo-.svg": {
     "type": "image/svg+xml",
     "etag": '"2bf8-hNaLCTi89nOFCsIIfWpP/jrfo0s"',
-    "mtime": "2026-07-06T23:30:24.816Z",
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 11256,
     "path": "../public/assets/zhipuai-BPNAnxo-.svg"
   },
-  "/assets/_sessionId-ZuH6-ZX5.js": {
+  "/assets/_sessionId-DeeeQcS9.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"36c-yfRDDJm0mM1r+nbDh5oXBDpciWQ"',
-    "mtime": "2026-07-06T23:30:24.817Z",
+    "etag": '"36c-9kxd4A0O2DRX90CFKTSW0gvJg7A"',
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 876,
-    "path": "../public/assets/_sessionId-ZuH6-ZX5.js"
+    "path": "../public/assets/_sessionId-DeeeQcS9.js"
   },
-  "/assets/StreamingChunkSequence-DSRjbgqb.js": {
+  "/assets/ReplayDialog-D-gDSuhe.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"dd6-phWzlhQq/JJk54G5Z2rU0kzp2as"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 3542,
-    "path": "../public/assets/StreamingChunkSequence-DSRjbgqb.js"
+    "etag": '"31d6-7nPX+7CzElY2l3LTEI8tdhGnb9g"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 12758,
+    "path": "../public/assets/ReplayDialog-D-gDSuhe.js"
+  },
+  "/assets/ResponseView-zVdHc0mv.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"47fa-My/gIfJNAY80sXwdo3igU0H0hlA"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 18426,
+    "path": "../public/assets/ResponseView-zVdHc0mv.js"
+  },
+  "/assets/main-Do_fjInc.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"512fd-fApJrxOu5dijJDTxHvG75pv2C6s"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 332541,
+    "path": "../public/assets/main-Do_fjInc.js"
   },
   "/assets/qwen-CONDcHqt.png": {
     "type": "image/png",
     "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
-    "mtime": "2026-07-06T23:30:24.816Z",
+    "mtime": "2026-07-07T00:31:07.942Z",
     "size": 357059,
     "path": "../public/assets/qwen-CONDcHqt.png"
   },
-  "/assets/ProxyViewerContainer-CNLLZq37.js": {
+  "/assets/ProxyViewerContainer-vhfV449d.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"aece0-rsojOMYS6lexxfh1G0dXZ/InUpE"',
-    "mtime": "2026-07-06T23:30:24.817Z",
-    "size": 716e3,
-    "path": "../public/assets/ProxyViewerContainer-CNLLZq37.js"
+    "etag": '"aef11-EMJh1fZUCmNDbpYKv5051UbD1KI"',
+    "mtime": "2026-07-07T00:31:07.942Z",
+    "size": 716561,
+    "path": "../public/assets/ProxyViewerContainer-vhfV449d.js"
   }
 };
 function readAsset(id) {

package/README.md

@@ -62,13 +62,13 @@ The onboarding command installs guided setup skills for local agents:
 
 - Claude Code: `~/.claude/skills/agent-inspector-onboard/SKILL.md` plus a slash command.
 - Codex: `~/.codex/skills/agent-inspector-onboard/SKILL.md`, focused on connecting
-  `http://localhost:25947/api/mcp` through Codex `mcp_servers.agent-inspector`.
+  `http://localhost:9527/api/mcp` through Codex `mcp_servers.agent-inspector`.
 - OpenCode: run `agent-inspector onboard --opencode-only` to merge
   `mcp.agent-inspector` into `~/.config/opencode/opencode.json` or `opencode.jsonc`, then verify
   with `opencode mcp list`.
 - MiMo Code: run `agent-inspector onboard --mimo-only` to merge `mcp.agent-inspector` into
   `~/.config/mimocode/mimocode.jsonc` or `mimocode.json`, then route MiMo through the proxy with
-  `OPENAI_BASE_URL=http://localhost:25947/proxy`.
+  `OPENAI_BASE_URL=http://localhost:9527/proxy`.
 
 During npm global install, Agent Inspector also makes a best-effort onboarding skill install for
 detected local agents. If `~/.claude` exists, it installs the Claude Code skill and slash command.
@@ -123,20 +123,39 @@ agent-inspector doctor --chrome-extension
 Then point an AI coding tool at the proxy:
 
 ```bash
-ANTHROPIC_BASE_URL=http://localhost:25947/proxy <tool>
+ANTHROPIC_BASE_URL=http://localhost:9527/proxy <tool>
 ```
 
-The web UI runs at http://localhost:25947. The public proxy endpoint is also
-`http://localhost:25947/proxy`; internally Agent Inspector may run the app on a private helper port,
+The web UI runs at http://localhost:9527. The public proxy endpoint is also
+`http://localhost:9527/proxy`; internally Agent Inspector may run the app on a private helper port,
 but AI tools should use the public URL printed by the CLI.
 
+For v3 compatibility, the packaged CLI also keeps `http://localhost:25947` open as a legacy alias
+when it starts on the default port. Existing AI tool and MCP configs that still point at `25947`
+continue to work for now, but new configs should use `9527`.
+
+## v3.0 Port Migration
+
+Agent Inspector v3.0 changes the default public port from `25947` to `9527`. The packaged CLI keeps
+`25947` as a legacy alias when you run the default `agent-inspector` command, so existing AI coding
+tool and MCP configs do not need to be edited immediately.
+
+Use these endpoints for new configs:
+
+- Web UI: `http://localhost:9527`
+- Proxy: `http://localhost:9527/proxy`
+- OpenAI-compatible `/v1` proxy: `http://localhost:9527/proxy/v1`
+- MCP: `http://localhost:9527/api/mcp`
+
+If you intentionally want only the new port, start with `agent-inspector --no-legacy-port`.
+
 For Codex-style OpenAI Responses clients, configure the proxy as an OpenAI-compatible `/v1` base:
 
 ```toml
 model_provider = "agent-inspector"
 
 [model_providers."agent-inspector"]
-base_url = "http://127.0.0.1:25947/proxy/v1"
+base_url = "http://127.0.0.1:9527/proxy/v1"
 wire_api = "responses"
 ```
 
@@ -226,7 +245,7 @@ upstream URL failed.
 Agent Inspector exposes MCP at:
 
 ```text
-http://localhost:25947/api/mcp
+http://localhost:9527/api/mcp
 ```
 
 Coding agents can connect to this MCP surface directly over Streamable HTTP, or through the
@@ -244,10 +263,13 @@ The MCP HTTP surface is also documented as OpenAPI YAML in
 [`docs/mcp-openapi.yaml`](docs/mcp-openapi.yaml).
 
 Use only one transport for the same Inspector instance. If the MCP client supports Streamable HTTP,
-configure `http://localhost:25947/api/mcp` directly. If it only supports stdio, configure
+configure `http://localhost:9527/api/mcp` directly. If it only supports stdio, configure
 `agent-inspector-mcp stdio`; that command is only a bridge to `/api/mcp`, not a second Inspector
 server.
 
+Legacy MCP configs that still use `http://localhost:25947/api/mcp` are accepted by the default v3
+CLI alias during the compatibility window.
+
 Coding agents can use the MCP surface in three ways:
 
 - Tools: perform actions such as listing logs, reading bounded log details, testing providers,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonyclaw/agent-inspector",
-  "version": "2.1.23",
+  "version": "3.0.0",
   "type": "module",
   "description": "Agent observability and knowledge capture layer for AI coding tools.",
   "license": "MIT",

package/src/cli/doctor.ts

@@ -3,7 +3,7 @@ import { isAbsolute, join, resolve } from "node:path";
 import { createConnection } from "node:net";
 import { migrateLegacyDataDirs, resolveDataDir } from "../proxy/dataDir";
 
-const DEFAULT_PORT = 25947;
+const DEFAULT_PORT = 9527;
 const PROBE_TIMEOUT_MS = 2000;
 const EXTENSION_REQUIRED_FILES = [
   "manifest.json",

package/src/cli/onboard.ts

@@ -35,8 +35,9 @@ import { renderSkillOnboard, REQUIRED_PHASE_HEADINGS } from "./templates/skill-o
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-const DEFAULT_PORT = 25947;
+const DEFAULT_PORT = 9527;
 const DEFAULT_MCP_URL = `http://localhost:${DEFAULT_PORT}/api/mcp`;
+const LEGACY_MCP_URL = "http://localhost:25947/api/mcp";
 const SKILL_DIR_NAME = "agent-inspector-onboard";
 const SKILL_FILE_NAME = "SKILL.md";
 // Windows reserves `:` for NTFS alternate data streams, so a file named
@@ -630,6 +631,10 @@ function stringArrayEquals(value: unknown, expected: readonly string[]): boolean
   return value.every((item, index) => item === expected[index]);
 }
 
+function knownMcpEndpoints(endpoint: string): readonly string[] {
+  return endpoint === DEFAULT_MCP_URL ? [DEFAULT_MCP_URL, LEGACY_MCP_URL] : [endpoint];
+}
+
 function isAgentLocalEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {
   if (!isObject(value)) {
     return false;
@@ -641,16 +646,14 @@ function isAgentLocalEntry(value: unknown, endpoint: string, ignoreEnabled: bool
   }
 
   const env = value["environment"];
-  const usesUrlArg = stringArrayEquals(value["command"], [
-    "agent-inspector-mcp",
-    "stdio",
-    "--url",
-    endpoint,
-  ]);
+  const endpoints = knownMcpEndpoints(endpoint);
+  const usesUrlArg = endpoints.some((candidate) =>
+    stringArrayEquals(value["command"], ["agent-inspector-mcp", "stdio", "--url", candidate]),
+  );
   const usesEnv =
     stringArrayEquals(value["command"], ["agent-inspector-mcp", "stdio"]) &&
     isObject(env) &&
-    env["AGENT_INSPECTOR_MCP_URL"] === endpoint;
+    endpoints.some((candidate) => env["AGENT_INSPECTOR_MCP_URL"] === candidate);
 
   return value["type"] === "local" && (usesUrlArg || usesEnv);
 }
@@ -665,7 +668,10 @@ function isAgentRemoteEntry(value: unknown, endpoint: string, ignoreEnabled: boo
     return false;
   }
 
-  return value["type"] === "remote" && value["url"] === endpoint;
+  return (
+    value["type"] === "remote" &&
+    knownMcpEndpoints(endpoint).some((candidate) => value["url"] === candidate)
+  );
 }
 
 function isKnownAgentEntry(value: unknown, endpoint: string, ignoreEnabled: boolean): boolean {

package/src/cli.ts

@@ -23,14 +23,13 @@ import { startIdentityProxy } from "./proxy/identityProxy.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// External-facing port stays at 25947 so existing tooling / AI clients
-// (Claude Code, OpenCode, MiMo Code, etc.) keep working with the
-// unchanged `ANTHROPIC_BASE_URL=http://localhost:25947/proxy`. The
-// identity-injecting proxy listens on that port; the TanStack Start
-// upstream is moved to a private port (25949 by default) and reverse-
-// proxied through.
-const DEFAULT_PORT = 25947;
-const DEFAULT_UPSTREAM_PORT = 25949;
+// v3 defaults the public entrypoint to 9527 while keeping 25947 as a
+// compatibility alias for older AI-tool and MCP configs. The TanStack Start
+// runtime stays on a private upstream port and both public ports reverse-proxy
+// to that same runtime, so logs, sessions, and MCP state remain unified.
+const DEFAULT_PORT = 9527;
+const LEGACY_ALIAS_PORT = 25947;
+const DEFAULT_UPSTREAM_PORT = 9529;
 const LOCAL_PROBE_TIMEOUT_MS = 2000;
 const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
 const DEFAULT_CAPTURE_MODE = "simple";
@@ -244,6 +243,26 @@ function printAccessHints(port: number, host?: string): void {
   }
 }
 
+function pickUpstreamPort(publicPort: number, legacyAliasPort: number | null): number {
+  const candidates = [
+    DEFAULT_UPSTREAM_PORT,
+    publicPort + 2 <= 65535 ? publicPort + 2 : publicPort - 2,
+    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 the identity proxy. Returns `null` (and prints a warning)
  *  if the listen port is already in use by another process — e.g. when
  *  restarting a previous instance that didn't shut down cleanly. The
@@ -273,7 +292,7 @@ async function tryStartIdentityProxy(
 }
 
 async function runStart(args: string[]): Promise<void> {
-  const envPort = process.env["PORT"];
+  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 =
@@ -290,10 +309,7 @@ async function runStart(args: string[]): Promise<void> {
   let captureMode = DEFAULT_CAPTURE_MODE;
   let captureModeWasSpecified = false;
   let enableIdentityProxy = true;
-  let identityProxyPort =
-    process.env["AGENT_INSPECTOR_PORT"] !== undefined
-      ? Number(process.env["AGENT_INSPECTOR_PORT"])
-      : DEFAULT_PORT;
+  let legacyAliasEnabled = true;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -402,10 +418,13 @@ async function runStart(args: string[]): Promise<void> {
           process.exitCode = 1;
           return;
         }
-        identityProxyPort = parsed;
+        port = parsed;
         i++;
         break;
       }
+      case "--no-legacy-port":
+        legacyAliasEnabled = false;
+        break;
       default:
         break;
     }
@@ -489,11 +508,13 @@ async function runStart(args: string[]): Promise<void> {
     }
   }
 
-  // TanStack Start listens on the private upstream port; the identity
-  // proxy owns the public-facing `port`. When the identity proxy is
-  // disabled (or not yet running) we fall back to TanStack listening on
-  // the public port directly.
-  const upstreamPort = enableIdentityProxy ? DEFAULT_UPSTREAM_PORT : port;
+  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 = enableIdentityProxy ? pickUpstreamPort(port, legacyAliasPort) : port;
   process.env["PORT"] = String(upstreamPort);
 
   const url = urlForHost(port, host);
@@ -526,8 +547,8 @@ async function runStart(args: string[]): Promise<void> {
     const restartPorts = new Set<number>();
     restartPorts.add(port);
     if (enableIdentityProxy) {
-      restartPorts.add(identityProxyPort);
       restartPorts.add(upstreamPort);
+      if (legacyAliasPort !== null) restartPorts.add(legacyAliasPort);
     }
     for (const targetPort of restartPorts) {
       killProcessOnPort(targetPort);
@@ -538,6 +559,11 @@ async function runStart(args: string[]): Promise<void> {
   console.log(`   Capture mode: ${captureMode}`);
   console.log(`   Proxy: ${url}/proxy`);
   printAccessHints(port, host);
+  if (legacyAliasPort !== null) {
+    console.log(`   Legacy UI:      http://localhost:${legacyAliasPort}`);
+    console.log(`   Legacy proxy:   http://localhost:${legacyAliasPort}/proxy`);
+    console.log(`   Legacy MCP:     http://localhost:${legacyAliasPort}/api/mcp`);
+  }
   console.log(``);
   console.log(`Route AI coding tools through the proxy:`);
   console.log(`   Claude Code:  ANTHROPIC_BASE_URL=${url}/proxy claude`);
@@ -594,6 +620,8 @@ async function runStart(args: string[]): Promise<void> {
     serverEnv["HOST"] = host;
     serverEnv["NITRO_HOST"] = host;
   }
+  serverEnv["AGENT_INSPECTOR_PUBLIC_PORT"] = String(port);
+  serverEnv["PROXY_PORT"] = String(port);
   serverEnv["AGENT_INSPECTOR_CAPTURE_MODE"] = captureMode;
   const serverProcess = spawn(serverCommand.command, serverCommand.args, {
     stdio: background ? ["ignore", "ignore", "ignore"] : ["ignore", "pipe", "pipe"],
@@ -615,9 +643,23 @@ async function runStart(args: string[]): Promise<void> {
   // 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 identityProxy = enableIdentityProxy
-    ? await tryStartIdentityProxy(identityProxyPort, upstreamPort, host)
-    : null;
+  const identityProxies: Array<{
+    label: "primary" | "legacy";
+    port: number;
+    server: import("node:http").Server;
+  }> = [];
+  if (enableIdentityProxy) {
+    const primaryProxy = await tryStartIdentityProxy(port, upstreamPort, host);
+    if (primaryProxy !== null) {
+      identityProxies.push({ label: "primary", port, server: primaryProxy });
+    }
+    if (legacyAliasPort !== null) {
+      const legacyProxy = await tryStartIdentityProxy(legacyAliasPort, upstreamPort, host);
+      if (legacyProxy !== null) {
+        identityProxies.push({ label: "legacy", port: legacyAliasPort, server: legacyProxy });
+      }
+    }
+  }
 
   if (background) {
     serverProcess.unref();
@@ -625,18 +667,24 @@ async function runStart(args: string[]): Promise<void> {
     // not started yet so the public port is not yet accepting traffic.
     if (await waitForInspectorHealthy(upstreamPort, 5000, host)) {
       console.log(`agent-inspector background server is ready at ${url}`);
-      if (identityProxy !== null) {
-        console.log(`Identity proxy ready on port ${identityProxyPort} (PID-attributing proxy).`);
+      if (identityProxies.length > 0) {
+        console.log(`Identity proxy ready on port ${port} (PID-attributing proxy).`);
       }
       printAccessHints(port, host);
-      if (identityProxy !== null) {
+      if (legacyAliasPort !== null) {
+        console.log(`   Legacy proxy:  http://localhost:${legacyAliasPort}/proxy`);
+        console.log(`   Legacy MCP:    http://localhost:${legacyAliasPort}/api/mcp`);
+      }
+      if (identityProxies.length > 0) {
         console.log(
           ``,
           `Route AI coding tools through the identity proxy for accurate PID attribution:`,
-          `   Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${identityProxyPort}/proxy claude`,
-          `   OpenCode:     LLM_BASE_URL=http://localhost:${identityProxyPort}/proxy opencode`,
-          `   MiMo Code:    OPENAI_BASE_URL=http://localhost:${identityProxyPort}/proxy mimo`,
-          `   (Direct ${port} still works; it falls back to OS-scan heuristic.)`,
+          `   Claude Code:  ANTHROPIC_BASE_URL=http://localhost:${port}/proxy claude`,
+          `   OpenCode:     LLM_BASE_URL=http://localhost:${port}/proxy opencode`,
+          `   MiMo Code:    OPENAI_BASE_URL=http://localhost:${port}/proxy mimo`,
+          legacyAliasPort === null
+            ? `   Override the port with --port <n> when needed.`
+            : `   Legacy configs using http://localhost:${legacyAliasPort}/proxy still work.`,
         );
       }
       return;
@@ -646,9 +694,15 @@ async function runStart(args: string[]): Promise<void> {
     return;
   }
 
-  if (identityProxy !== null) {
+  if (identityProxies.length > 0) {
     console.log(``);
     console.log(`Identity proxy ready at ${url} (PID-attributing public entrypoint).`);
+    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.`);
     }
@@ -656,7 +710,7 @@ async function runStart(args: string[]): Promise<void> {
 
   process.exitCode = await waitForProcessExit(serverProcess);
 
-  if (identityProxy !== null) {
-    await new Promise<void>((resolve) => identityProxy.close(() => resolve()));
+  for (const proxy of identityProxies) {
+    await new Promise<void>((resolve) => proxy.server.close(() => resolve()));
   }
 }