@tonyclaw/agent-inspector 3.0.45 → 3.0.47

package/src/lib/instanceContract.ts

@@ -1,7 +1,14 @@
 import { z } from "zod";
+import { BackendImplementationSchema } from "./backendImplementation";
+import { normalizePublicBasePath } from "./basePath";
 
 export const INSTANCE_API_SCHEMA_VERSION = 1;
 
+function isCanonicalPublicBasePath(value: string): boolean {
+  const normalized = normalizePublicBasePath(value);
+  return normalized !== null && (normalized.length === 0 ? "/" : normalized) === value;
+}
+
 export const InstanceStateSchema = z.enum(["running", "stopped", "conflict"]);
 export const InstanceStateReasonSchema = z.enum(["identity_mismatch", "port_conflict"]);
 
@@ -35,18 +42,36 @@ export const InstanceStatusOutputSchema = z
     host: z.string().min(1),
     publicPort: z.number().int().min(1).max(65_535),
     upstreamPort: z.number().int().min(1).max(65_535),
-    basePath: z.string().startsWith("/"),
+    basePath: z.string().refine(isCanonicalPublicBasePath, "Invalid public Base Path"),
     captureMode: z.enum(["simple", "full"]),
+    backend: BackendImplementationSchema.default("typescript"),
+    uiEnabled: z.boolean(),
     dataDir: z.string().min(1),
     supervisorPid: z.number().int().positive().nullable(),
     urls: InstanceUrlsSchema,
   })
   .strict();
 
+export const InstanceConnectionSurfacesSchema = z
+  .object({
+    ui: z
+      .object({
+        enabled: z.boolean(),
+        baseUrl: z.url().nullable(),
+      })
+      .strict(),
+    control: z.object({ baseUrl: z.url() }).strict(),
+    agent: z.object({ baseUrl: z.url() }).strict(),
+  })
+  .strict();
+
 export const InstanceConnectionOutputSchema = z
   .object({
     schemaVersion: z.literal(INSTANCE_API_SCHEMA_VERSION),
+    uiEnabled: z.boolean(),
     instance: InstanceStatusOutputSchema,
+    surfaces: InstanceConnectionSurfacesSchema,
+    /** @deprecated Use surfaces.control.baseUrl or surfaces.agent.baseUrl. */
     baseUrl: z.url(),
     endpoints: InstanceUrlsSchema,
     environment: z
@@ -82,12 +107,8 @@ export const InstanceStartRequestSchema = z
       .min(1)
       .max(2_048)
       .refine(
-        (value) =>
-          value.startsWith("/") &&
-          !value.includes("?") &&
-          !value.includes("#") &&
-          !value.includes("\\"),
-        "Base Path must be an absolute URL path without query, hash, or backslash",
+        (value) => normalizePublicBasePath(value) !== null,
+        "Base Path must use URL-safe path segments without traversal, encoded separators, or markup characters",
       )
       .optional(),
     host: z
@@ -105,6 +126,8 @@ export const InstanceStartRequestSchema = z
       )
       .optional(),
     captureMode: z.enum(["simple", "full"]).optional(),
+    backend: BackendImplementationSchema.optional(),
+    uiEnabled: z.boolean().optional(),
     dataDir: z.string().trim().min(1).max(32_767).optional(),
   })
   .strict();
@@ -175,15 +198,11 @@ export const InstanceErrorOutputSchema = z
   })
   .strict();
 
-export type InstanceState = z.infer<typeof InstanceStateSchema>;
-export type InstanceStateReason = z.infer<typeof InstanceStateReasonSchema>;
 export type InstanceStatusOutput = z.infer<typeof InstanceStatusOutputSchema>;
 export type InstanceConnectionOutput = z.infer<typeof InstanceConnectionOutputSchema>;
 export type InstanceStartRequest = z.infer<typeof InstanceStartRequestSchema>;
-export type InstanceOperation = z.infer<typeof InstanceOperationSchema>;
 export type InstanceOperationOutcome = z.infer<typeof InstanceOperationOutcomeSchema>;
 export type InstanceOperationOutput = z.infer<typeof InstanceOperationOutputSchema>;
-export type InstanceListOutput = z.infer<typeof InstanceListOutputSchema>;
 export type InstancePublicErrorCode = z.infer<typeof InstancePublicErrorCodeSchema>;
 export type InstancePublicError = z.infer<typeof InstancePublicErrorSchema>;
 export type InstanceErrorOutput = z.infer<typeof InstanceErrorOutputSchema>;

package/src/lib/managedInstance.ts

@@ -5,6 +5,7 @@ export const MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE = "agent-inspector:managed-s
 export const AGENT_INSPECTOR_CLI_ENTRY_ENV = "AGENT_INSPECTOR_CLI_ENTRY";
 
 export const MANAGED_INSTANCE_ENV = {
+  backend: "AGENT_INSPECTOR_INSTANCE_BACKEND",
   name: "AGENT_INSPECTOR_INSTANCE_NAME",
   instanceId: "AGENT_INSPECTOR_INSTANCE_ID",
   launchId: "AGENT_INSPECTOR_INSTANCE_LAUNCH_ID",
@@ -16,6 +17,7 @@ export const MANAGED_INSTANCE_ENV = {
 type ManagedInstanceEnv = Readonly<Record<string, string | undefined>>;
 
 export type ManagedInstanceLaunch = {
+  backend: BackendImplementation;
   name: string;
   instanceId: string;
   launchId: string;
@@ -47,6 +49,7 @@ export function readManagedInstanceLaunch(
   env: ManagedInstanceEnv = process.env,
 ): ManagedInstanceLaunchResult {
   const values = [
+    env[MANAGED_INSTANCE_ENV.backend],
     env[MANAGED_INSTANCE_ENV.name],
     env[MANAGED_INSTANCE_ENV.instanceId],
     env[MANAGED_INSTANCE_ENV.launchId],
@@ -59,6 +62,9 @@ export function readManagedInstanceLaunch(
   }
 
   const name = nonEmpty(env[MANAGED_INSTANCE_ENV.name]);
+  const backend = parseBackendImplementation(
+    nonEmpty(env[MANAGED_INSTANCE_ENV.backend]) ?? undefined,
+  );
   const instanceId = nonEmpty(env[MANAGED_INSTANCE_ENV.instanceId]);
   const launchId = nonEmpty(env[MANAGED_INSTANCE_ENV.launchId]);
   const controlToken = nonEmpty(env[MANAGED_INSTANCE_ENV.controlToken]);
@@ -66,6 +72,7 @@ export function readManagedInstanceLaunch(
   const upstreamPort = Number(env[MANAGED_INSTANCE_ENV.upstreamPort]);
   if (
     name === null ||
+    backend === null ||
     instanceId === null ||
     launchId === null ||
     controlToken === null ||
@@ -83,7 +90,7 @@ export function readManagedInstanceLaunch(
   }
   return {
     kind: "managed",
-    launch: { name, instanceId, launchId, controlToken, startedAt, upstreamPort },
+    launch: { backend, name, instanceId, launchId, controlToken, startedAt, upstreamPort },
   };
 }
 
@@ -102,3 +109,4 @@ export function parseManagedInstanceShutdownMessage(
     ? { type: MANAGED_INSTANCE_SHUTDOWN_MESSAGE_TYPE, controlToken: value["controlToken"] }
     : null;
 }
+import { parseBackendImplementation, type BackendImplementation } from "./backendImplementation";

package/src/lib/piAgentContract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { LogIdSchema } from "../contracts";
 
 export const PiAgentHistoryMessageSchema = z.object({
   role: z.enum(["user", "assistant"]),
@@ -55,9 +56,9 @@ export const PiAgentQueryStatsSchema = z.object({
 export const PiAgentEvidenceSchema = z.object({
   source: PiAgentEvidenceSourceSchema,
   id: z.string(),
-  logId: z.number().int().positive().optional(),
+  logId: LogIdSchema.optional(),
   knowledgeId: z.string().optional(),
-  logIds: z.array(z.number().int().positive()).optional(),
+  logIds: z.array(LogIdSchema).optional(),
   timestamp: z.string().optional(),
   sessionId: z.string().optional(),
   model: z.string().optional(),

package/src/lib/publicBasePathContext.ts

@@ -1,9 +1,10 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import {
   AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER,
+  AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER,
   AGENT_INSPECTOR_PUBLIC_PORT_HEADER,
   getConfiguredBasePath,
-  normalizeBasePath,
+  normalizePublicBasePath,
 } from "./basePath";
 import { getCurrentPort } from "./serverPort";
 
@@ -11,17 +12,12 @@ type BasePathEnv = Readonly<Record<string, string | undefined>>;
 
 type PublicRequestContext = {
   basePath: string;
+  publicOrigin: string | null;
   publicPort: number | null;
 };
 
 const publicRequestStorage = new AsyncLocalStorage<PublicRequestContext>();
 
-function isSafePublicBasePath(value: string): boolean {
-  if (value.length === 0) return true;
-  if (!/^\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*$/u.test(value)) return false;
-  return !value.split("/").some((segment) => segment === "." || segment === "..");
-}
-
 /**
  * Resolve the public Base Path attached by the trusted ingress. Invalid or
  * missing values fall back to the process's canonical Base Path.
@@ -29,8 +25,8 @@ function isSafePublicBasePath(value: string): boolean {
 export function resolveRequestPublicBasePath(request: Request, env?: BasePathEnv): string {
   const rawValue = request.headers.get(AGENT_INSPECTOR_PUBLIC_BASE_PATH_HEADER);
   if (rawValue !== null) {
-    const normalized = normalizeBasePath(rawValue);
-    if (isSafePublicBasePath(normalized)) return normalized;
+    const normalized = normalizePublicBasePath(rawValue);
+    if (normalized !== null) return normalized;
   }
   return getConfiguredBasePath(env ?? process.env);
 }
@@ -59,6 +55,29 @@ export function resolveRequestPublicPort(request: Request): number | null {
   }
 }
 
+function normalizedPublicOrigin(value: string): string | null {
+  try {
+    const parsed = new URL(value);
+    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;
+  }
+}
+
+/** Resolve the public origin set by trusted ingress without consulting forwarded headers. */
+export function resolveRequestPublicOrigin(request: Request): string | null {
+  const headerOrigin = request.headers.get(AGENT_INSPECTOR_PUBLIC_ORIGIN_HEADER);
+  if (headerOrigin !== null) return normalizedPublicOrigin(headerOrigin);
+  try {
+    return normalizedPublicOrigin(new URL(request.url).origin);
+  } catch {
+    return null;
+  }
+}
+
 /** Return the originating request's public Base Path, or the canonical path outside a request. */
 export function getPublicBasePath(env?: BasePathEnv): string {
   return publicRequestStorage.getStore()?.basePath ?? getConfiguredBasePath(env ?? process.env);
@@ -69,12 +88,21 @@ export function getPublicPort(): number {
   return publicRequestStorage.getStore()?.publicPort ?? getCurrentPort();
 }
 
+/** Return the trusted public origin, with a loopback fallback outside an ingress request. */
+export function getPublicOrigin(): string {
+  return (
+    publicRequestStorage.getStore()?.publicOrigin ?? `http://localhost:${String(getCurrentPort())}`
+  );
+}
+
 /** Run work with an explicitly selected public Base Path. Primarily useful for internal calls. */
 export function runWithPublicBasePath<T>(basePath: string, callback: () => T): T {
   const current = publicRequestStorage.getStore();
+  const normalized = normalizePublicBasePath(basePath) ?? getConfiguredBasePath(process.env);
   return publicRequestStorage.run(
     {
-      basePath: normalizeBasePath(basePath),
+      basePath: normalized,
+      publicOrigin: current?.publicOrigin ?? null,
       publicPort: current?.publicPort ?? null,
     },
     callback,
@@ -89,6 +117,7 @@ export function runWithPublicPort<T>(publicPort: number, callback: () => T): T {
   return publicRequestStorage.run(
     {
       basePath: current?.basePath ?? getConfiguredBasePath(process.env),
+      publicOrigin: current?.publicOrigin ?? null,
       publicPort: normalizedPort,
     },
     callback,
@@ -100,6 +129,7 @@ export function runWithRequestPublicBasePath<T>(request: Request, callback: () =
   return publicRequestStorage.run(
     {
       basePath: resolveRequestPublicBasePath(request),
+      publicOrigin: resolveRequestPublicOrigin(request),
       publicPort: resolveRequestPublicPort(request),
     },
     callback,

package/src/lib/resourceLimits.ts

@@ -9,6 +9,7 @@ export const MAX_PROVIDER_MODEL_METADATA = 64;
 export const MAX_SSE_CLIENTS = 32;
 export const MAX_ACTIVE_PROVIDER_TESTS = 2;
 export const MAX_PROVIDER_TEST_CONCURRENCY = 4;
+export const MAX_ACTIVE_PROXY_REQUESTS = 16;
 
 export const ResourceLimitErrorCodeSchema = z.enum([
   "invalid-page-request",
@@ -16,6 +17,7 @@ export const ResourceLimitErrorCodeSchema = z.enum([
   "provider-model-limit-exceeded",
   "sse-capacity-exceeded",
   "provider-test-capacity-exceeded",
+  "proxy-capacity-exceeded",
 ]);
 
 export const ResourceLimitStatusSchema = z.union([

package/src/lib/runContract.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JsonValueSchema } from "../contracts";
+import { JsonValueSchema, LogIdSchema } from "../contracts";
 import { SessionInfoSchema } from "./sessionInfoContract";
 
 export const InspectorRunStatusSchema = z.enum([
@@ -33,7 +33,7 @@ export const RunTimelineEventSchema = z.object({
   severity: RunTimelineEventSeveritySchema,
   title: z.string(),
   details: z.string(),
-  logId: z.number().int().positive().nullable(),
+  logId: LogIdSchema.nullable(),
   status: z.number().nullable(),
   model: z.string().nullable(),
   provider: z.string().nullable(),
@@ -62,7 +62,7 @@ export const FailureClassificationSchema = z.object({
   severity: z.enum(["none", "low", "medium", "high"]),
   category: FailureCategorySchema,
   summary: z.string(),
-  evidenceLogIds: z.array(z.number().int().positive()),
+  evidenceLogIds: z.array(LogIdSchema),
   hints: z.array(z.string()),
 });
 

package/src/lib/sessionInfoContract.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { LogIdSchema } from "../contracts";
 
 export const SessionTokenUsageSchema = z.object({
   input: z.number().int().nonnegative(),
@@ -9,7 +10,7 @@ export const SessionTokenUsageSchema = z.object({
 });
 
 export const SessionLogSummarySchema = z.object({
-  id: z.number().int().positive(),
+  id: LogIdSchema,
   sessionLogNumber: z.number().int().positive().optional(),
   timestamp: z.string(),
   provider: z.string().nullable(),
@@ -57,7 +58,7 @@ export const SessionInfoSchema = z.object({
   models: z.array(z.string()),
   providers: z.array(z.string()),
   tokenUsage: SessionTokenUsageSchema,
-  lastLogId: z.number().nullable(),
+  lastLogId: LogIdSchema.nullable(),
   lastModel: z.string().nullable(),
   clientUserAgent: z.string().nullable().optional(),
   clientPid: z.number().nullable(),

package/src/mcp/instanceHandlers.ts

@@ -90,6 +90,8 @@ function lifecycleRequest(input: InstanceLifecycleToolInput): InstanceStartReque
     basePath: input.basePath,
     host: input.host,
     captureMode: input.captureMode,
+    backend: input.backend,
+    uiEnabled: input.uiEnabled,
     dataDir: input.dataDir,
   };
 }

package/src/mcp/server.ts

@@ -36,10 +36,10 @@ import { InspectorRunStatusSchema, UpdateInspectorRunInputSchema } from "../lib/
 import { withBasePath } from "../lib/basePath";
 import {
   getPublicBasePath,
-  getPublicPort,
+  getPublicOrigin,
   runWithRequestPublicBasePath,
 } from "../lib/publicBasePathContext";
-import { JsonValueSchema } from "../contracts";
+import { JsonValueSchema, LogIdSchema, parseLogId } from "../contracts";
 import { InstanceListOutputSchema } from "../lib/instanceContract";
 import {
   MAX_PROVIDER_MODEL_NAME_CHARS,
@@ -335,7 +335,15 @@ const UpdateProviderInputSchema = z.object({
 });
 
 const LogResourceListResponseSchema = z.object({
-  logs: z.array(z.object({ id: z.number().int().positive() })),
+  logs: z.array(z.object({ id: LogIdSchema })),
+});
+
+export const McpLogIdInputSchema = z.object({
+  id: LogIdSchema.describe("The log id."),
+});
+
+export const McpOptionalLogIdInputSchema = z.object({
+  id: LogIdSchema.optional().describe("Optional log id to inspect."),
 });
 
 const ProcessResourceListResponseSchema = z.object({
@@ -361,10 +369,7 @@ function jsonResource(uri: URL, data: unknown): ReadResourceResult {
 }
 
 function mcpEndpointUrl(): string {
-  return `http://localhost:${String(getPublicPort())}${withBasePath(
-    "/api/mcp",
-    getPublicBasePath(),
-  )}`;
+  return `${getPublicOrigin()}${withBasePath("/api/mcp", getPublicBasePath())}`;
 }
 
 function mcpHealth(): Record<string, unknown> {
@@ -968,9 +973,7 @@ function registerTools(server: McpServer): void {
       title: "Get a single captured log by id",
       description:
         "Returns the full CapturedLog for the given id, including rawRequestBody and responseText with no truncation. SSE streaming chunks are NOT included — use inspector_get_log_chunks for those. Returns an error if the id does not exist.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogImpl(callApi, id)),
   );
@@ -981,9 +984,7 @@ function registerTools(server: McpServer): void {
       title: "Get SSE streaming chunks for a captured log",
       description:
         "Returns the SSE chunks array for a streaming log, in the order they were received. Returns an error if the log has no chunks (i.e. was non-streaming or the log id is unknown).",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogChunksImpl(callApi, id)),
   );
@@ -994,9 +995,7 @@ function registerTools(server: McpServer): void {
       title: "Get captured log headers",
       description:
         "Returns header-focused evidence for one log without large request/response bodies: raw headers, upstream headers, user-agent, origin, client PID/port, session id, model, and API path.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     ({ id }) => safeCall(() => getLogHeadersImpl(callApi, id)),
   );
@@ -1174,9 +1173,7 @@ function registerTools(server: McpServer): void {
       title: "Diagnose capture detail availability",
       description:
         "Explains why headers or bodies may be missing for the current runtime or a specific log, including captureMode, compact body mode, rawHeaders presence, and next-step recommendations.",
-      inputSchema: z.object({
-        id: z.number().int().positive().optional().describe("Optional log id to inspect."),
-      }),
+      inputSchema: McpOptionalLogIdInputSchema,
     },
     (args) => safeCall(() => diagnoseCaptureImpl(callApi, args)),
   );
@@ -1504,9 +1501,7 @@ function registerTools(server: McpServer): void {
       title: "Replay a captured log against its provider",
       description:
         "Re-sends the captured request body to the upstream LLM and returns the response summary: success flag, status, responseText, input/output token counts, elapsedMs, and whether the response was streaming. Useful for re-running a request after a fix or a transient failure. Returns an error if the log id is unknown or the upstream call fails.",
-      inputSchema: z.object({
-        id: z.number().int().positive().describe("The log id to replay."),
-      }),
+      inputSchema: McpLogIdInputSchema,
     },
     (args) => safeWriteCall("inspector_replay_log", () => replayLogImpl(callApi, args)),
   );
@@ -1815,8 +1810,8 @@ function registerResources(server: McpServer): void {
     },
     async (uri, variables) => {
       const id = variableString(variables, "id");
-      const parsed = id === null ? Number.NaN : Number(id);
-      if (!Number.isInteger(parsed) || parsed <= 0) {
+      const parsed = id === null ? null : parseLogId(id);
+      if (parsed === null) {
         return textResource(uri, "text/plain", "Invalid log id");
       }
       const result = await getLogImpl(callApi, parsed);

package/src/proxy/config.ts

@@ -1,11 +1,4 @@
-import {
-  writeFileSync,
-  readFileSync,
-  unlinkSync,
-  existsSync,
-  renameSync,
-  copyFileSync,
-} from "node:fs";
+import { writeFileSync, readFileSync, unlinkSync, existsSync, renameSync } from "node:fs";
 import { join } from "node:path";
 import { logger } from "./logger";
 import { getDataDir } from "./dataDir";
@@ -128,19 +121,19 @@ export function getConfig(): RuntimeConfig {
 }
 
 /**
- * Applies a partial update to the in-memory config and persists to disk.
- * Returns the updated full config. Persistence failures are logged but
- * do not throw — the in-memory value is always updated so the caller
- * sees a consistent response.
+ * Applies a partial update after atomically persisting it to disk.
+ * Returns the updated full config on success or null when persistence
+ * fails. A failed write leaves both the in-memory value and the existing
+ * on-disk value unchanged.
  */
-export function setConfig(patch: Partial<MutableRuntimeConfig>): RuntimeConfig {
+export function setConfig(patch: Partial<MutableRuntimeConfig>): RuntimeConfig | null {
   const next: RuntimeConfig = {
     ...currentConfig,
     ...patch,
     captureMode: currentConfig.captureMode,
   };
+  if (!persistConfig(next)) return null;
   currentConfig = next;
-  persistConfig(next);
   return next;
 }
 
@@ -164,8 +157,10 @@ export function _rebootForTests(): void {
 // --- Atomic write ---
 
 /**
- * Atomic write: temp file + rename. Mirrors the pattern in chunkStorage.ts.
- * Returns true on success, false on failure (logged but not thrown).
+ * Atomic write: secure temp file + rename in the same directory.
+ * Returns true on success, false on failure (logged but not thrown). There is
+ * deliberately no copy fallback because replacing the target through a copy
+ * could expose a partially written config after a crash.
  */
 function persistConfig(value: RuntimeConfig): boolean {
   const dir = getDataDir();
@@ -181,13 +176,15 @@ function persistConfig(value: RuntimeConfig): boolean {
     writeFileSync(tempPath, JSON.stringify(toPersistedConfig(value)), {
       encoding: "utf-8",
       mode: PRIVATE_FILE_MODE,
+      flush: true,
     });
     if (!securePrivateFileSync(tempPath)) {
-      unlinkSync(tempPath);
+      removeConfigTempFile(tempPath);
       logger.error(`[config] Failed to secure config temp file ${tempPath}`);
       return false;
     }
   } catch (err) {
+    removeConfigTempFile(tempPath);
     logger.error(`[config] Failed to write config temp file: ${String(err)}`);
     return false;
   }
@@ -196,19 +193,17 @@ function persistConfig(value: RuntimeConfig): boolean {
     renameSync(tempPath, targetPath);
     return true;
   } catch (err) {
-    logger.warn(`[config] Rename failed, falling back to copy+delete: ${String(err)}`);
-    try {
-      copyFileSync(tempPath, targetPath);
-      if (!securePrivateFileSync(targetPath)) {
-        logger.error(`[config] Failed to secure config file ${targetPath}`);
-        return false;
-      }
-      unlinkSync(tempPath);
-      return true;
-    } catch (copyErr) {
-      logger.error(`[config] Failed to copy config file: ${String(copyErr)}`);
-      return false;
-    }
+    removeConfigTempFile(tempPath);
+    logger.error(`[config] Failed to atomically replace config file: ${String(err)}`);
+    return false;
+  }
+}
+
+function removeConfigTempFile(tempPath: string): void {
+  try {
+    unlinkSync(tempPath);
+  } catch {
+    // Best effort. A stale temp path is never read as runtime configuration.
   }
 }
 

package/src/proxy/dataDir.ts

@@ -1,6 +1,10 @@
-import { cpSync, existsSync, rmSync } from "node:fs";
+import { cpSync, existsSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
-import { ensurePrivateDirectorySync, securePrivateTreeSync } from "./privateDataPath";
+import {
+  ensurePrivateDirectorySync,
+  isPathTreeFreeOfIndirectionSync,
+  securePrivateTreeSync,
+} from "./privateDataPath";
 
 const CURRENT_DATA_DIR_NAME = ".agent-inspector";
 const LEGACY_DATA_DIR_NAMES = [".llm-inspector", ".llm-agent"];
@@ -98,14 +102,46 @@ export function migrateLegacyDataDirs(): void {
     const legacyDir = join(base, legacyName);
     if (!existsSync(legacyDir)) continue;
 
+    const stagingDir = join(
+      base,
+      `${CURRENT_DATA_DIR_NAME}.migration-${String(process.pid)}-${String(Date.now())}`,
+    );
+
     try {
-      if (!ensurePrivateDirectorySync(currentDir)) return;
-      cpSync(legacyDir, currentDir, { recursive: true, force: true });
-      if (!securePrivateTreeSync(currentDir)) return;
+      // cpSync may dereference junctions on some Windows runtimes. Reject the source tree before
+      // copying and recheck it afterwards so migration never imports through an indirection.
+      if (!isPathTreeFreeOfIndirectionSync(legacyDir)) return;
+      if (existsSync(currentDir)) {
+        // Never merge legacy state into an unknown or partially initialized destination. A caller
+        // can inspect it and retry after resolving the conflict; the authoritative legacy source
+        // remains untouched.
+        if (readdirSync(currentDir).length > 0) return;
+        rmSync(currentDir, { recursive: true, force: false });
+      }
+      if (!ensurePrivateDirectorySync(stagingDir)) return;
+      for (const entry of readdirSync(legacyDir)) {
+        cpSync(join(legacyDir, entry), join(stagingDir, entry), {
+          recursive: true,
+          force: false,
+          errorOnExist: true,
+        });
+      }
+      if (!isPathTreeFreeOfIndirectionSync(legacyDir)) {
+        rmSync(stagingDir, { recursive: true, force: true });
+        return;
+      }
+      if (!securePrivateTreeSync(stagingDir)) {
+        rmSync(stagingDir, { recursive: true, force: true });
+        return;
+      }
+      renameSync(stagingDir, currentDir);
       rmSync(legacyDir, { recursive: true, force: true });
+      return;
     } catch {
-      // Best-effort migration: startup must continue even when the old
-      // directory is locked or partially unreadable. The next call can retry.
+      // A failed staged migration never deletes the legacy source. Remove only this attempt's
+      // private sibling and retry on a later startup.
+      if (existsSync(stagingDir)) rmSync(stagingDir, { recursive: true, force: true });
+      return;
     }
   }
 }