@tonyclaw/agent-inspector 2.1.10 → 2.1.12

package/.output/server/index.mjs

@@ -38,100 +38,100 @@ const assets = {
   "/assets/alibaba-TTwafVwX.svg": {
     "type": "image/svg+xml",
     "etag": '"171b-6dyV5K8QjiaY35sN9qNprh9zDIs"',
-    "mtime": "2026-07-04T02:02:10.927Z",
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 5915,
     "path": "../public/assets/alibaba-TTwafVwX.svg"
   },
-  "/assets/CompareDrawer-BaGKK2R7.js": {
+  "/assets/CompareDrawer-XTdSOto9.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"49e8-G1wNmDGmbVxNPpz1a8oaOgtZzos"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "etag": '"49e8-bu14iyddw7i6hLggEbQwIlgQT/g"',
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 18920,
-    "path": "../public/assets/CompareDrawer-BaGKK2R7.js"
-  },
-  "/assets/index-B3EOwfg7.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"74-+kptPbQ2kpjXzSI1SU6SHbX2+SQ"',
-    "mtime": "2026-07-04T02:02:10.929Z",
-    "size": 116,
-    "path": "../public/assets/index-B3EOwfg7.js"
+    "path": "../public/assets/CompareDrawer-XTdSOto9.js"
   },
   "/assets/index-CmtfjQPv.css": {
     "type": "text/css; charset=utf-8",
     "etag": '"1e968-15dLAIs72Zhi4Qe/CRWBTVZ7MtI"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 125288,
     "path": "../public/assets/index-CmtfjQPv.css"
   },
-  "/assets/main-JvXpk_ov.js": {
+  "/assets/main-B_EcGyf-.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"512fd-ayrpztHB+N7SGRB3bs6EZN4hnBo"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "etag": '"512fd-vx5h/KMQz3ePll6B2LBWhS5rz1E"',
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 332541,
-    "path": "../public/assets/main-JvXpk_ov.js"
+    "path": "../public/assets/main-B_EcGyf-.js"
   },
   "/assets/minimax-BPMzvuL-.jpeg": {
     "type": "image/jpeg",
     "etag": '"1b06-IwivU89ko5UTMUM1/t7hn4sQK9A"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 6918,
     "path": "../public/assets/minimax-BPMzvuL-.jpeg"
   },
-  "/assets/RequestAnatomy-CiZE_fKZ.js": {
+  "/assets/ReplayDialog-Cd1VsfRe.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"43f2-pcT1lJeQNTmnbmOFKpaANfuLxXQ"',
-    "mtime": "2026-07-04T02:02:10.929Z",
-    "size": 17394,
-    "path": "../public/assets/RequestAnatomy-CiZE_fKZ.js"
+    "etag": '"318c-spkeYXrEB4wG/uX3hf+85eWDNJk"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 12684,
+    "path": "../public/assets/ReplayDialog-Cd1VsfRe.js"
   },
-  "/assets/ReplayDialog-Io8Ufsif.js": {
+  "/assets/index-BsFdgXac.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"318c-OhkrsLfrsml3ZquW9kjlH6TiWK0"',
-    "mtime": "2026-07-04T02:02:10.929Z",
-    "size": 12684,
-    "path": "../public/assets/ReplayDialog-Io8Ufsif.js"
+    "etag": '"74-db3//XcXc3MHuPF0eOLgXsErJTY"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 116,
+    "path": "../public/assets/index-BsFdgXac.js"
   },
-  "/assets/ResponseView-TJwxn-lh.js": {
+  "/assets/ResponseView-8GivXCzp.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"30d2-zO82t52tyuafUQNMKhsmem+8W9c"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "etag": '"30d2-iJTTpaNykHiLvmnmUvp+FrIs6ks"',
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 12498,
-    "path": "../public/assets/ResponseView-TJwxn-lh.js"
+    "path": "../public/assets/ResponseView-8GivXCzp.js"
+  },
+  "/assets/RequestAnatomy-QxSpbmsj.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"43f2-xjujMxYvXtaY+PgPnEev1/QeFAI"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 17394,
+    "path": "../public/assets/RequestAnatomy-QxSpbmsj.js"
+  },
+  "/assets/qwen-CONDcHqt.png": {
+    "type": "image/png",
+    "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 357059,
+    "path": "../public/assets/qwen-CONDcHqt.png"
   },
   "/assets/zhipuai-BPNAnxo-.svg": {
     "type": "image/svg+xml",
     "etag": '"2bf8-hNaLCTi89nOFCsIIfWpP/jrfo0s"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 11256,
     "path": "../public/assets/zhipuai-BPNAnxo-.svg"
   },
-  "/assets/StreamingChunkSequence-D-9ysFSG.js": {
+  "/assets/_sessionId-D89uDTQs.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"d5c-Siu/PgtKfi5RvFy2DV5/y0lzSDU"',
-    "mtime": "2026-07-04T02:02:10.930Z",
-    "size": 3420,
-    "path": "../public/assets/StreamingChunkSequence-D-9ysFSG.js"
-  },
-  "/assets/_sessionId-3JCekYV3.js": {
-    "type": "text/javascript; charset=utf-8",
-    "etag": '"d2-Ck1cytNneSGYTerMobA/d7kU7E4"',
-    "mtime": "2026-07-04T02:02:10.929Z",
+    "etag": '"d2-63rh9pFgM3iAAYD/jdB7M0OPa1w"',
+    "mtime": "2026-07-04T05:26:41.755Z",
     "size": 210,
-    "path": "../public/assets/_sessionId-3JCekYV3.js"
+    "path": "../public/assets/_sessionId-D89uDTQs.js"
   },
-  "/assets/qwen-CONDcHqt.png": {
-    "type": "image/png",
-    "etag": '"572c3-cdJAPaHdOvFCGzuaQjagdgOu6XE"',
-    "mtime": "2026-07-04T02:02:10.929Z",
-    "size": 357059,
-    "path": "../public/assets/qwen-CONDcHqt.png"
+  "/assets/StreamingChunkSequence-CwNGqJ5n.js": {
+    "type": "text/javascript; charset=utf-8",
+    "etag": '"d5c-0RMlG+zdOOYhcXL94BP73yEZKCM"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 3420,
+    "path": "../public/assets/StreamingChunkSequence-CwNGqJ5n.js"
   },
-  "/assets/ProxyViewerContainer-Cxwizw8H.js": {
+  "/assets/ProxyViewerContainer-Cc944N8i.js": {
     "type": "text/javascript; charset=utf-8",
-    "etag": '"c1bf2-b7zp7bO7iKSX7NYjIYX/gBZE8b4"',
-    "mtime": "2026-07-04T02:02:10.929Z",
-    "size": 793586,
-    "path": "../public/assets/ProxyViewerContainer-Cxwizw8H.js"
+    "etag": '"c1d99-n90ipQQM8DOvJtMKVbz7nJrU49s"',
+    "mtime": "2026-07-04T05:26:41.755Z",
+    "size": 794009,
+    "path": "../public/assets/ProxyViewerContainer-Cc944N8i.js"
   }
 };
 function readAsset(id) {

package/package.json

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

package/src/cli.ts

@@ -12,11 +12,19 @@ import {
   probeHostForBindHost,
   urlForHost,
 } from "./cli/networkHints.js";
+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;
 const LOCAL_PROBE_TIMEOUT_MS = 2000;
 const BRANDED_WINDOWS_RUNTIME_EXE = "agent-inspector.exe";
 const DEFAULT_CAPTURE_MODE = "simple";
@@ -198,6 +206,34 @@ function printAccessHints(port: number, host?: string): void {
   }
 }
 
+/** 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
+ *  TanStack Start server keeps running either way; clients just lose the
+ *  per-PID attribution until they fall back to direct port `port` access. */
+async function tryStartIdentityProxy(
+  identityPort: number,
+  upstreamPort: number,
+  upstreamHost: string | undefined,
+): Promise<import("node:http").Server | null> {
+  try {
+    const server = await startIdentityProxy({
+      listenPort: identityPort,
+      upstreamHost: upstreamHost ?? "127.0.0.1",
+      upstreamPort,
+    });
+    return server;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `[identity-proxy] Could not listen on port ${identityPort}: ${message}. ` +
+        `Falling back to OS-scan heuristic on port ${upstreamPort}. ` +
+        `Pass --identity-proxy-port <n> to choose another port, or --no-identity-proxy to disable.`,
+    );
+    return null;
+  }
+}
+
 async function runStart(args: string[]): Promise<void> {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== undefined ? Number(envPort) : DEFAULT_PORT;
@@ -215,6 +251,11 @@ async function runStart(args: string[]): Promise<void> {
   let providersJson: string | undefined;
   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;
 
   if (envMode !== undefined && envMode !== "") {
     const parsedMode = parseCaptureMode(envMode);
@@ -312,6 +353,21 @@ async function runStart(args: string[]): Promise<void> {
         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;
+        }
+        identityProxyPort = parsed;
+        i++;
+        break;
+      }
       default:
         break;
     }
@@ -395,7 +451,12 @@ async function runStart(args: string[]): Promise<void> {
     }
   }
 
-  process.env["PORT"] = String(port);
+  // 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;
+  process.env["PORT"] = String(upstreamPort);
 
   const url = urlForHost(port, host);
 
@@ -425,6 +486,10 @@ async function runStart(args: string[]): Promise<void> {
 
   if (forceRestart) {
     killProcessOnPort(port);
+    if (enableIdentityProxy) {
+      killProcessOnPort(identityProxyPort);
+      killProcessOnPort(upstreamPort);
+    }
   }
 
   console.log(`Server running at ${url}`);
@@ -495,11 +560,36 @@ async function runStart(args: string[]): Promise<void> {
     windowsHide: background,
   });
 
+  // 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 identityProxy = enableIdentityProxy
+    ? await tryStartIdentityProxy(identityProxyPort, upstreamPort, host)
+    : null;
+
   if (background) {
     serverProcess.unref();
-    if (await waitForInspectorHealthy(port, 5000, host)) {
+    // Probe the upstream TanStack port directly — the identity proxy is
+    // 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).`);
+      }
       printAccessHints(port, host);
+      if (identityProxy !== null) {
+        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.)`,
+        );
+      }
       return;
     }
     console.error(`agent-inspector background server did not become ready at ${url}.`);
@@ -508,4 +598,19 @@ async function runStart(args: string[]): Promise<void> {
   }
 
   process.exitCode = await waitForProcessExit(serverProcess);
+
+  // Foreground path: print the smart-port hint now that the proxy is up,
+  // then keep the proxy alive until the server exits.
+  if (identityProxy !== null) {
+    console.log(
+      ``,
+      `Identity proxy is listening on port ${identityProxyPort}:`,
+      `   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 ${port} still works (falls back to OS-scan heuristic).`,
+    );
+    await new Promise<void>((resolve) => identityProxy.close(() => resolve()));
+  }
 }

package/src/components/proxy-viewer/ConversationGroup.tsx

@@ -77,6 +77,24 @@ function collectProviders(logs: CapturedLog[]): {
   }));
 }
 
+export function getFirstClientPid(logs: readonly CapturedLog[]): number | null {
+  for (const log of logs) {
+    const pid = log.clientPid;
+    if (pid !== null && pid !== undefined) return pid;
+  }
+  return null;
+}
+
+export function getFirstClientProjectFolder(logs: readonly CapturedLog[]): string | null {
+  for (const log of logs) {
+    const projectFolder = log.clientProjectFolder;
+    if (projectFolder !== null && projectFolder !== undefined && projectFolder !== "") {
+      return projectFolder;
+    }
+  }
+  return null;
+}
+
 export const ConversationGroup = memo(function ({
   group,
   viewMode = "simple",
@@ -110,6 +128,8 @@ export const ConversationGroup = memo(function ({
   const endTime = group.logs[group.logs.length - 1]?.timestamp ?? new Date().toISOString();
   const isLoading = group.logs.some((log) => log.responseStatus === null);
   const showTraceRollupMetrics = standalone && !hasPinnedSessionContext;
+  const clientPid = useMemo(() => getFirstClientPid(group.logs), [group.logs]);
+  const clientProjectFolder = useMemo(() => getFirstClientProjectFolder(group.logs), [group.logs]);
 
   // Pre-compute stop reasons for each log — used by turnIndices
   const turnGroups = useMemo(() => buildTurnGroups(group.logs), [group.logs]);
@@ -144,8 +164,8 @@ export const ConversationGroup = memo(function ({
           providers={providers}
           isLoading={isLoading}
           userAgent={group.logs[0]?.userAgent ?? null}
-          clientPid={group.logs[0]?.clientPid ?? null}
-          clientProjectFolder={group.logs[0]?.clientProjectFolder ?? null}
+          clientPid={clientPid}
+          clientProjectFolder={clientProjectFolder}
           timeDisplayFormat={timeDisplayFormat}
           onClear={() => onClearGroup(group.logs.map((l) => l.id))}
         />

package/src/components/proxy-viewer/LogEntryHeader.tsx

@@ -162,6 +162,13 @@ export const LogEntryHeader = memo(function ({
   const tokenRateLabel =
     tokensPerSecond === null || tokensPerSecond <= 0 ? null : formatTokenRate(tokensPerSecond);
   const warningCount = log.warnings?.length ?? 0;
+  const hasClientPid = log.clientPid !== null && log.clientPid !== undefined;
+  const hasClientProjectFolder =
+    log.clientProjectFolder !== null &&
+    log.clientProjectFolder !== undefined &&
+    log.clientProjectFolder !== "";
+  const hasClientCwd =
+    log.clientCwd !== null && log.clientCwd !== undefined && log.clientCwd !== "";
 
   return (
     <TooltipProvider>
@@ -243,32 +250,31 @@ export const LogEntryHeader = memo(function ({
           </Tooltip>
         )}
 
-        {/* Elapsed time */}
-        {log.elapsedMs !== null && (
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <span
-                className={cn(
-                  "flex items-center gap-1 text-xs shrink-0",
-                  isSlowResponse ? "text-amber-400" : "text-muted-foreground",
-                )}
-              >
-                <Clock className="size-3" />
-                <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
-                {isSlowResponse && <AlertTriangle className="size-3" aria-label="Slow response" />}
-              </span>
-            </TooltipTrigger>
-            <TooltipContent>
-              {isSlowResponse
-                ? `Slow response: ${formatElapsed(log.elapsedMs)} exceeds ${formatElapsed(
-                    slowResponseThresholdSeconds * 1000,
-                  )}`
-                : log.streaming
-                  ? "Total streaming response time"
-                  : "Elapsed response time"}
-            </TooltipContent>
-          </Tooltip>
-        )}
+        {/* Elapsed time. Tooltip is only shown when this log exceeded the slow-
+            response threshold — for normal-speed logs the elapsed value is
+            self-explanatory, so we skip the tooltip wrapper to keep the row
+            quiet. */}
+        {log.elapsedMs !== null &&
+          (isSlowResponse ? (
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <span className="flex items-center gap-1 text-xs text-amber-400 shrink-0">
+                  <Clock className="size-3" />
+                  <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
+                  <AlertTriangle className="size-3" aria-label="Slow response" />
+                </span>
+              </TooltipTrigger>
+              <TooltipContent>
+                Slow response: {formatElapsed(log.elapsedMs)} exceeds{" "}
+                {formatElapsed(slowResponseThresholdSeconds * 1000)}
+              </TooltipContent>
+            </Tooltip>
+          ) : (
+            <span className="flex items-center gap-1 text-xs text-muted-foreground shrink-0">
+              <Clock className="size-3" />
+              <span className="font-mono tabular-nums">{formatElapsed(log.elapsedMs)}</span>
+            </span>
+          ))}
 
         {/* Streaming timing */}
         {log.streaming && firstChunkLabel !== null && (
@@ -367,12 +373,12 @@ export const LogEntryHeader = memo(function ({
         )}
 
         {/* Client info (PID + project folder) */}
-        {(log.clientPid !== null || log.clientProjectFolder !== null) && (
+        {(hasClientPid || hasClientProjectFolder) && (
           <Tooltip>
             <TooltipTrigger asChild>
               <span className="hidden xl:flex items-center gap-1 text-purple-400/80 text-xs shrink-0">
                 <FileTerminal className="size-3" />
-                {log.clientProjectFolder !== null ? (
+                {hasClientProjectFolder ? (
                   <span className="font-mono tabular-nums">{log.clientProjectFolder}</span>
                 ) : (
                   <span className="font-mono tabular-nums">PID {log.clientPid}</span>
@@ -380,7 +386,7 @@ export const LogEntryHeader = memo(function ({
               </span>
             </TooltipTrigger>
             <TooltipContent>
-              {log.clientCwd !== null
+              {hasClientCwd
                 ? `PID: ${log.clientPid ?? "?"}  CWD: ${log.clientCwd}`
                 : `Process ID: ${log.clientPid ?? "?"}`}
             </TooltipContent>

package/src/proxy/identityProxy.ts

@@ -0,0 +1,192 @@
+import http from "node:http";
+import { Buffer } from "node:buffer";
+import { lookupClientByPort } from "./socketTracker";
+
+const IDENTITY_HEADERS = {
+  pid: "x-agent-inspector-client-pid",
+  port: "x-agent-inspector-client-port",
+  cwd: "x-agent-inspector-client-cwd",
+  projectFolder: "x-agent-inspector-client-project-folder",
+} as const;
+
+const REQUEST_HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+  "content-length",
+]);
+
+const RESPONSE_HOP_BY_HOP = new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailers",
+  "transfer-encoding",
+  "upgrade",
+]);
+
+export type IdentityProxyOptions = {
+  /** Public port to listen on. Clients point at this. */
+  listenPort: number;
+  /** Host the upstream TanStack Start server listens on. */
+  upstreamHost: string;
+  /** Port the upstream TanStack Start server listens on. */
+  upstreamPort: number;
+};
+
+/**
+ * Start a tiny native Node HTTP server that:
+ *   1. Reads the client connection's source port (`req.socket.remotePort`).
+ *   2. Resolves that port to a PID via the OS connection table
+ *      (`Get-NetTCPConnection -LocalPort <port>` on Windows,
+ *       `ss -tanp state established` on Linux/macOS).
+ *   3. Resolves the PID's cwd / project folder.
+ *   4. Injects everything as `X-Agent-Inspector-Client-*` headers.
+ *   5. Reverse-proxies the request to the upstream inspector (TanStack
+ *      Start, which already reads those headers via `getClientInfo`).
+ *
+ * Why this exists: TanStack Start strips the underlying TCP socket from
+ * the fetch-API `Request` before it reaches the proxy handler, so the
+ * handler cannot read `socket.remotePort`. Sitting in front of TanStack
+ * Start as a native Node server restores the ability to look up the
+ * client PID at the socket level — no wrapper script, no client-side
+ * changes, no header configuration by the AI tool author.
+ *
+ * The proxy degrades gracefully when the OS lookup fails (missing
+ * permissions, port not found): the request is still forwarded, just
+ * without identity headers, so it falls back to the existing
+ * best-effort scan inside TanStack Start.
+ */
+export function startIdentityProxy(options: IdentityProxyOptions): Promise<http.Server> {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer();
+    // Eagerly resolve client identity on `connection` — at that point the
+    // socket is fresh and the OS connection table still lists it as
+    // ESTABLISHED. By the time `request` fires (let alone after we finish
+    // reading the body) HTTP/1.0 clients have already closed their side
+    // and the row is in TIME_WAIT with PID 0.
+    server.on("connection", (socket: import("node:net").Socket) => {
+      const remotePort = socket.remotePort;
+      if (remotePort !== undefined && remotePort > 0) {
+        void lookupClientByPort(remotePort).catch(() => null);
+      }
+    });
+    server.on("request", (req, res) => {
+      void handleRequest(req, res, options).catch((err: unknown) => {
+        const message = err instanceof Error ? err.message : String(err);
+        if (!res.headersSent) {
+          res.writeHead(502, { "content-type": "text/plain" });
+        }
+        res.end(`Identity proxy error: ${message}`);
+      });
+    });
+    server.once("error", reject);
+    server.listen(options.listenPort, () => {
+      server.removeListener("error", reject);
+      resolve(server);
+    });
+  });
+}
+
+async function handleRequest(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  options: IdentityProxyOptions,
+): Promise<void> {
+  // The connection-time lookup already populated the per-port cache; this
+  // call now hits the cache and returns the result synchronously.
+  const remotePort = req.socket.remotePort;
+  let identity: Awaited<ReturnType<typeof lookupClientByPort>> | null = null;
+  if (remotePort !== undefined && remotePort > 0) {
+    try {
+      identity = await lookupClientByPort(remotePort);
+    } catch {
+      identity = null;
+    }
+  }
+
+  // Buffer the request body — TanStack Start needs the raw bytes intact
+  // for SSE/streaming endpoints, so we can't decode-and-re-encode.
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) {
+    chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : toBuffer(chunk));
+  }
+  const body = Buffer.concat(chunks);
+
+  const upstreamHeaders: Record<string, string | string[]> = {};
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (REQUEST_HOP_BY_HOP.has(name.toLowerCase())) continue;
+    if (value === undefined) continue;
+    upstreamHeaders[name] = value;
+  }
+  if (identity !== null && identity.pid !== null) {
+    upstreamHeaders[IDENTITY_HEADERS.pid] = String(identity.pid);
+    if (identity.port !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.port] = String(identity.port);
+    }
+    if (identity.cwd !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.cwd] = identity.cwd;
+    }
+    if (identity.projectFolder !== null) {
+      upstreamHeaders[IDENTITY_HEADERS.projectFolder] = identity.projectFolder;
+    }
+  }
+
+  process.stderr.write(
+    `[identity-proxy] req ${req.method} ${req.url} remotePort=${remotePort} pid=${identity?.pid ?? "?"}\n`,
+  );
+  process.stderr.write(
+    `[identity-proxy] forwarding headers: pid=${upstreamHeaders[IDENTITY_HEADERS.pid] ?? "?"} cwd=${upstreamHeaders[IDENTITY_HEADERS.cwd] ?? "?"}\n`,
+  );
+
+  const proxyReq = http.request(
+    {
+      hostname: options.upstreamHost,
+      port: options.upstreamPort,
+      path: req.url ?? "/",
+      method: req.method,
+      headers: upstreamHeaders,
+    },
+    (proxyRes) => {
+      const outHeaders: Record<string, string | string[]> = {};
+      for (const [name, value] of Object.entries(proxyRes.headers)) {
+        if (RESPONSE_HOP_BY_HOP.has(name.toLowerCase())) continue;
+        if (value === undefined) continue;
+        outHeaders[name] = value;
+      }
+      res.writeHead(proxyRes.statusCode ?? 502, outHeaders);
+      proxyRes.pipe(res);
+    },
+  );
+  proxyReq.on("error", (err) => {
+    if (!res.headersSent) {
+      res.writeHead(502, { "content-type": "text/plain" });
+    }
+    res.end(`Upstream error: ${err.message}`);
+  });
+  if (body.length > 0) proxyReq.write(body);
+  proxyReq.end();
+}
+
+// `Readable` chunks in Node are typed as `any` (they can be Buffer | string
+// depending on the encoding setting). We narrow them via runtime checks.
+function toBuffer(chunk: unknown): Buffer {
+  if (Buffer.isBuffer(chunk)) return chunk;
+  if (typeof chunk === "string") return Buffer.from(chunk);
+  // `for await` over a Node Readable always yields Buffer | string; this
+  // branch is only reachable if a custom stream returns something else
+  // (Uint8Array / ArrayBuffer / etc.). The Buffer constructor accepts an
+  // ArrayBuffer directly; we attempt that first, then fall back to a
+  // best-effort empty buffer so we never throw on an unexpected chunk.
+  if (chunk instanceof ArrayBuffer) return Buffer.from(chunk);
+  if (chunk instanceof Uint8Array)
+    return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);
+  return Buffer.alloc(0);
+}