@tonyclaw/llm-inspector 1.19.0 → 1.19.2

package/.output/cli.js

@@ -20,6 +20,7 @@ function which(bin) {
       const out2 = execFileSync("where", [bin], {
         encoding: "utf8",
         timeout: 3e3,
+        windowsHide: true,
         stdio: ["ignore", "pipe", "ignore"]
       });
       const first = out2.split(/\r?\n/).find((line) => line.trim().length > 0);
@@ -133,29 +134,117 @@ ${detectedSummary || "  (no known AI tool detected \u2014 the user can still use
 
 Default proxy port: \`${port}\` (override with \`PORT=<n> llm-inspector\` or \`--port <n>\`).
 
+> **PAUSE protocol.** Every \`**PAUSE**\` marker in this skill is a real stop.
+> Use the \`AskUserQuestion\` tool to actually wait for the user before
+> continuing. Do not stream past a PAUSE based on context \u2014 the user has
+> not seen your output yet. Each PAUSE in the body below includes a sample
+> question you can adapt.
+
 ---
 
-## Preflight
+## Phase 0: Idempotency check
+
+**EXPLAIN:** "Before we do anything, let me see what's already set up. If some of the steps are already done, we can skip them."
+
+**DO:** Probe the three pieces of state this skill touches. Use targeted checks \u2014 do **not** read large JSON files into the conversation.
 
-Before starting, verify the environment.
+\`\`\`bash
+# 1. Is the proxy already up?
+curl -fsS "http://localhost:${port}/api/health" 2>/dev/null && echo "PROXY: up" || echo "PROXY: down"
+
+# 2. Does the config have a real provider key?
+CFG="$HOME/.llm-inspector/config.json"
+if [ -f "$CFG" ]; then
+  if grep -qE '"apiKey"[[:space:]]*:[[:space:]]*"(sk-[^"]+|REPLACE|REPLACE_)' "$CFG" 2>/dev/null; then
+    echo "CONFIG: has key (no REPLACE placeholder)"
+  else
+    echo "CONFIG: missing or has placeholder key"
+  fi
+else
+  echo "CONFIG: file does not exist"
+fi
+
+# 3. Is the MCP server already wired? (project .mcp.json wins)
+PROJ_MCP=".mcp.json"
+HOME_MCP="$HOME/.claude.json"
+if [ -f "$PROJ_MCP" ] && grep -q '"llm-inspector"' "$PROJ_MCP"; then
+  echo "MCP: wired in $PROJ_MCP"
+elif [ -f "$HOME_MCP" ] && grep -q '"llm-inspector"' "$HOME_MCP"; then
+  echo "MCP: wired in $HOME_MCP"
+else
+  echo "MCP: not wired"
+fi
+\`\`\`
+
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+$port = ${port}
+$cfg  = Join-Path $env:USERPROFILE '.llm-inspector/config.json'
+
+# 1. Is the proxy already up?
+try {
+  $null = Invoke-RestMethod -Uri "http://localhost:$port/api/health" -TimeoutSec 2 -ErrorAction Stop
+  Write-Host 'PROXY: up'
+} catch {
+  Write-Host 'PROXY: down'
+}
+
+# 2. Does the config have a real provider key?
+if (Test-Path $cfg) {
+  $content = Get-Content $cfg -Raw
+  if ($content -match '"apiKey"[[:space:]]*:[[:space:]]*"(sk-[^"]+)"') {
+    Write-Host 'CONFIG: has key'
+  } elseif ($content -match 'REPLACE') {
+    Write-Host 'CONFIG: has placeholder key'
+  } else {
+    Write-Host 'CONFIG: missing key'
+  }
+} else {
+  Write-Host 'CONFIG: file does not exist'
+}
+
+# 3. Is the MCP server already wired? (project .mcp.json wins)
+$projMcp = Join-Path (Get-Location) '.mcp.json'
+$homeMcp = Join-Path $env:USERPROFILE '.claude.json'
+if ((Test-Path $projMcp) -and (Select-String -Path $projMcp -Pattern 'llm-inspector' -Quiet)) {
+  Write-Host "MCP: wired in $projMcp"
+} elseif ((Test-Path $homeMcp) -and (Select-String -Path $homeMcp -Pattern 'llm-inspector' -Quiet)) {
+  Write-Host "MCP: wired in $homeMcp"
+} else {
+  Write-Host 'MCP: not wired'
+}
+\`\`\`
+
+**DO:** Summarize the three checks in one line, then use \`AskUserQuestion\` to ask whether to skip the corresponding phases.
+
+> **PAUSE** \u2014 call \`AskUserQuestion\` with:
+> - header: \`Skip done\`
+> - question: \`Proxy/CONFIG/MCP state: <summary>. Skip the phases that are already done?\`
+> - options: \`["Yes, skip what's done", "No, walk me through everything again"]\`
+> Wait for the answer before moving to Preflight.
+
+---
+
+## Preflight
 
-**EXPLAIN:** "Let's make sure everything we need is in place. Two quick checks."
+**EXPLAIN:** "Quick env sanity check \u2014 make sure Node and Claude Code are present."
 
-**DO:** Run the platform-appropriate commands below. The user can copy-paste, or you can run them yourself if you have shell access.
+**DO:** Run the platform-appropriate commands below.
 
 \`\`\`bash
 # Unix / macOS / WSL
-node --version                  # expect >= 18
-test -d "$HOME/.claude" && echo "claude-code: present" || echo "claude-code: not detected"
+node --version                                       # expect >= 18
+command -v claude >/dev/null && echo "claude-code: present" || echo "claude-code: not detected"
 \`\`\`
 
 \`\`\`powershell
-# Windows PowerShell
-node --version                  # expect >= 18
-if (Test-Path "$env:USERPROFILE\\.claude") { Write-Host "claude-code: present" } else { Write-Host "claude-code: not detected" }
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+node --version                                       # expect >= 18
+$null = Get-Command claude -ErrorAction SilentlyContinue
+if ($null) { Write-Host 'claude-code: present' } else { Write-Host 'claude-code: not detected' }
 \`\`\`
 
-**PAUSE** \u2014 if Node is older than 18, ask the user to install a newer version (https://nodejs.org) before continuing.
+> **PAUSE** \u2014 if Node is older than 18, ask the user to install a newer version (https://nodejs.org) before continuing. Use \`AskUserQuestion\` with header \`Node version\`.
 
 ---
 
@@ -178,7 +267,7 @@ llm-inspector is a transparent HTTP proxy + Web UI for AI coding tools. Point yo
 Ready? Let's start with the provider.
 \`\`\`
 
-**PAUSE** \u2014 wait for the user to confirm.
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Ready?\` and options \`["Yes, let's go", "Wait, I have a question"]\`. Wait for the user before continuing.
 
 ---
 
@@ -186,47 +275,94 @@ Ready? Let's start with the provider.
 
 **EXPLAIN:** "A 'provider' is an upstream LLM endpoint \u2014 Anthropic, OpenAI, MiniMax, etc. llm-inspector routes each request to the right upstream based on the model name. You need at least one provider configured for the proxy to forward traffic."
 
-**DO:** Open (or create) \`~/.llm-inspector/config.json\` in the user's editor. If the file doesn't exist, create it with the structure below. Walk the user through filling in their API key for their provider of choice.
+**DO:** First, re-check whether the config already has a real key (Phase 0 may have raced with a manual edit). Use the same \`grep -qE '"apiKey":"sk-' "$HOME/.llm-inspector/config.json"\` (bash) or \`Select-String\` (PowerShell) check from Phase 0. If a real key is present, skip the rest of this phase.
 
-\`\`\`json
+**DO:** If no real key, ask the user for the provider type and API key via \`AskUserQuestion\`. The question should be a free-form text field (no fixed options) \u2014 the API key is a secret, so don't echo it back in the question UI.
+
+\`\`\`bash
+# After collecting the key, write the config
+mkdir -p "$HOME/.llm-inspector"
+cat > "$HOME/.llm-inspector/config.json" <<'JSON'
 {
   "providers": [
     {
       "id": "anthropic",
       "type": "anthropic",
-      "apiKey": "sk-ant-...",
+      "apiKey": "REPLACE_ME_BEFORE_WRITING",
       "baseUrl": "https://api.anthropic.com"
     }
   ]
 }
+JSON
+# Then patch the apiKey with the user-provided value (use jq if available)
 \`\`\`
 
-Alternative (avoid touching the config file): point the user at the Web UI \u2192 top-right Settings button \u2192 Providers tab, which has a form-driven flow.
+\`\`\`powershell
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly
+$dir  = Join-Path $env:USERPROFILE '.llm-inspector'
+$file = Join-Path $dir 'config.json'
+New-Item -ItemType Directory -Force -Path $dir | Out-Null
+@'
+{
+  "providers": [
+    {
+      "id": "anthropic",
+      "type": "anthropic",
+      "apiKey": "REPLACE_ME_BEFORE_WRITING",
+      "baseUrl": "https://api.anthropic.com"
+    }
+  ]
+}
+'@ | Set-Content -Path $file -Encoding UTF8
+# Then patch the apiKey with the user-provided value
+\`\`\`
+
+**DO:** Patch the placeholder with the actual key using \`jq\` (preferred) or a simple \`sed\`. Then read the file back to confirm the key is no longer \`REPLACE_ME_BEFORE_WRITING\`.
+
+**DO:** If the user declines to provide a key in the AskUserQuestion (selects "Skip for now"), do **not** write a placeholder config. Tell the user that Phase 5 (First capture) will be skipped, and that they can re-run the skill after adding a key.
 
-**PAUSE** \u2014 wait for the user to confirm they have at least one provider with a key.
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Provider key\` and options \`["Key is in, continue", "Skip for now, I'll add it later"]\`. Wait for the answer.
 
 ---
 
 ## Phase 3: Start proxy
 
-**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, kills any process already on that port, and prints the URL."
+**EXPLAIN:** "Time to start the proxy. It binds to port ${port} by default, reuses an already-running healthy llm-inspector, and prints the URL. Use \`--force-restart\` only when you intentionally want to replace the existing process."
 
-**DO:** Start the proxy in the background so you can keep working.
+**DO:** Skip this phase entirely if the Phase 0 health check already reported \`PROXY: up\` and the user opted to skip done phases.
+
+**DO:** Otherwise, start the proxy with the explicit \`--background --no-open\` flags. On Windows, resolve the npm shim first and launch it through \`Start-Process -WindowStyle Hidden\` so setup does not flash a command window.
 
 \`\`\`bash
 # Unix / macOS / WSL
-nohup llm-inspector --no-open > /tmp/llm-inspector.log 2>&1 &
+llm-inspector --background --no-open > /tmp/llm-inspector.log 2>&1
 \`\`\`
 
 \`\`\`powershell
-# Windows PowerShell
-Start-Process -FilePath "llm-inspector" -ArgumentList "--no-open" -RedirectStandardOutput "$env:TEMP\\llm-inspector.log" -RedirectStandardError "$env:TEMP\\llm-inspector.err.log" -WindowStyle Hidden
+# Windows PowerShell \u2014 single-quoted so $env: expands correctly.
+# Locate the binary on PATH first (works for npm, pnpm, yarn, volta, fnm).
+# If not on PATH, fall back to the common npm global shim at $env:APPDATA.
+# As a last resort, let cmd /c resolve it through PATHEXT.
+$log = Join-Path $env:TEMP 'llm-inspector.log'
+$err = Join-Path $env:TEMP 'llm-inspector.err.log'
+$found = Get-Command llm-inspector -ErrorAction SilentlyContinue
+if ($found) {
+  $shim = $found.Source
+  $args = '--background','--no-open'
+} elseif (Test-Path (Join-Path $env:APPDATA 'npm/llm-inspector.cmd')) {
+  $shim = Join-Path $env:APPDATA 'npm/llm-inspector.cmd'
+  $args = '--background','--no-open'
+} else {
+  # bin not on PATH and not at the default npm prefix \u2014 let cmd resolve it
+  $shim = 'cmd.exe'
+  $args = '/c','llm-inspector','--background','--no-open'
+}
+Start-Process -FilePath $shim -ArgumentList $args -RedirectStandardOutput $log -RedirectStandardError $err -WindowStyle Hidden
 \`\`\`
 
 Then wait for the port to be ready:
 
 \`\`\`bash
-# Wait up to 10s for the port to come up
 for i in $(seq 1 20); do
   curl -fsS "http://localhost:${port}/api/health" >/dev/null 2>&1 && echo "ready" && break
   sleep 0.5
@@ -239,7 +375,7 @@ done
 curl -sS "http://localhost:${port}/api/health"
 \`\`\`
 
-**PAUSE** \u2014 if the health check fails, show the user the log file (\`/tmp/llm-inspector.log\` or \`%TEMP%\\\\llm-inspector.log\`) and diagnose. Common issues: another process on the port, firewall, missing providers.
+> **PAUSE** \u2014 if the health check fails, show the user the log file (\`/tmp/llm-inspector.log\` or \`%TEMP%\\llm-inspector.log\`) and diagnose. Common issues: another process on the port, firewall, missing providers. Use \`AskUserQuestion\` with header \`Proxy up?\` and options \`["Yes, proxy is up", "No, I see an error in the log"]\`. Wait for the answer.
 
 ---
 
@@ -267,18 +403,22 @@ mimo
 
 For a tool that wasn't auto-detected, fall through to the generic curl test in the next phase \u2014 the user can wire their tool later.
 
-**PAUSE** \u2014 wait for the user to confirm they've set the env var (or that they're going to use the curl test instead).
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Tool wired?\` and options \`["Yes, env var is set, claude is running", "No, I'm going to use the curl test instead"]\`. Wait for the answer.
 
 ---
 
 ## Phase 4.5: Wire MCP server
 
-**EXPLAIN:** "The proxy also exposes an MCP server at \`http://localhost:${port}/api/mcp\`. Your AI agent can query logs, replay requests, and test providers through it \u2014 no need to leave the editor. We'll add an \`mcpServers\` entry so your agent picks it up automatically."
+**EXPLAIN:** "The proxy also exposes an MCP server at \`http://localhost:${port}/api/mcp\`. Your AI agent can query logs, replay requests, and test providers through it \u2014 no need to leave the editor."
 
-**DO:** Add (or merge) an \`mcpServers\` entry in the user's Claude Code config. The file is \`~/.claude.json\` on all platforms; the MCP spec entry uses HTTP Streamable transport:
+**DO:** Skip this phase if Phase 0 reported \`MCP: wired in <path>\` and the user opted to skip done phases.
+
+**DO:** Otherwise, check the project-level \`.mcp.json\` first (preferred \u2014 modern Claude Code convention), then fall back to \`~/.claude.json\`. Use the \`Read\` tool to inspect; do **not** \`cat\` a 40 KB file into the conversation.
+
+If neither has an \`llm-inspector\` entry, add one. The simplest path is to write to project \`.mcp.json\` (create it if missing):
 
 \`\`\`json
-// ~/.claude.json  (merge into existing mcpServers)
+// .mcp.json  (project root)
 {
   "mcpServers": {
     "llm-inspector": {
@@ -289,26 +429,7 @@ For a tool that wasn't auto-detected, fall through to the generic curl test in t
 }
 \`\`\`
 
-If \`mcpServers\` already exists, add \`llm-inspector\` as a new key \u2014 don't clobber existing entries.
-
-PowerShell one-liner that creates the file if missing, or merges if present:
-
-\`\`\`powershell
-$cfg = Join-Path $env:USERPROFILE ".claude.json"
-if (Test-Path $cfg) {
-  $doc = Get-Content $cfg -Raw | ConvertFrom-Json
-} else {
-  $doc = [pscustomobject]@{ mcpServers = [pscustomobject]@{} }
-}
-if (-not ($doc.PSObject.Properties.Name -contains "mcpServers")) {
-  $doc | Add-Member -NotePropertyName mcpServers -NotePropertyValue ([pscustomobject]@{})
-}
-$doc.mcpServers | Add-Member -NotePropertyName "llm-inspector" -NotePropertyValue ([pscustomobject]@{
-  type = "http"
-  url  = "http://localhost:${port}/api/mcp"
-}) -Force
-$doc | ConvertTo-Json -Depth 10 | Set-Content $cfg -Encoding UTF8
-\`\`\`
+If \`mcpServers\` already exists in \`.mcp.json\`, merge the \`llm-inspector\` key into it via the \`Edit\` tool \u2014 do not overwrite other entries. If you can't create a project \`.mcp.json\` (no project root, permission, etc.), fall back to merging into \`~/.claude.json\` using the same \`Read\`/\`Edit\` pattern.
 
 **DO:** Verify the handshake. The MCP \`initialize\` request should return 200 with a \`serverInfo\` payload \u2014 that proves the server is mounted and reachable:
 
@@ -325,41 +446,33 @@ curl -sS -X POST "http://localhost:${port}/api/mcp" \\
       "capabilities": {},
       "clientInfo": { "name": "onboard-check", "version": "0" }
     }
-  }'
-# expect: HTTP 200, body contains "result" with serverInfo.name = "llm-inspector"
+  }' | grep -o '"name":"llm-inspector"' && echo "handshake OK"
 \`\`\`
 
-After the handshake, issue a \`tools/list\` to confirm the tool catalog is reachable:
+The \`grep -o '"name":"llm-inspector"'\` extracts only the serverInfo name \u2014 do not dump the full response. If the server returns session IDs, store the \`mcp-session-id\` header from the first response and use it for the follow-up \`tools/list\` call.
 
-\`\`\`bash
-SESSION=<session-id-from-initialize-response>
-curl -sS -X POST "http://localhost:${port}/api/mcp" \\
-  -H "Content-Type: application/json" \\
-  -H "Accept: application/json, text/event-stream" \\
-  -H "mcp-session-id: $SESSION" \\
-  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
-# expect: a result.tools array with at least 1 entry
-\`\`\`
-
-**PAUSE** \u2014 if \`initialize\` returns non-200, show the user the proxy log and re-check the JSON syntax. If it returns 200 but \`tools/list\` fails, the server is up but the session wasn't carried over \u2014 re-use the \`mcp-session-id\` header from the first response.
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`MCP OK?\` and options \`["Yes, handshake returned 200", "No, the call failed"]\`. Wait for the answer.
 
 ---
 
 ## Phase 5: First capture
 
-**EXPLAIN:** "Let's prove the proxy works end-to-end. We'll send one real request through it and confirm the log shows up in the API. A 401/403 from the upstream is fine \u2014 the point is that the *request* reaches the proxy."
+**EXPLAIN:** "Let's prove the proxy works end-to-end. We'll send one real request through it and confirm the log shows up in the API."
 
-**DO:** Fire a minimal Anthropic-format request through the proxy. This works regardless of which tool the user wired up:
+**DO:** First, re-check the config. If the \`apiKey\` is still a \`REPLACE_ME_BEFORE_WRITING\` placeholder (user opted out in Phase 2), **skip the capture test** and tell the user to fill in their key and re-run the skill. A 401 from the upstream is fine if they did provide a real key \u2014 the proxy will still log the request.
+
+Fire a minimal Anthropic-format request through the proxy:
 
 \`\`\`bash
 curl -sS -X POST "http://localhost:${port}/proxy/v1/messages" \\
   -H "Content-Type: application/json" \\
   -H "anthropic-version: 2023-06-01" \\
   -H "x-api-key: \${LLM_INSPECTOR_API_KEY:-sk-no-key-needed-for-routing}" \\
-  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}'
+  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":1,"messages":[{"role":"user","content":"ping"}]}' \\
+  -o /tmp/llm-inspector-capture.json -w 'STATUS:%{http_code}\\n'
 \`\`\`
 
-**DO:** Poll the logs API for up to 5 seconds. A 200 with at least one entry means success:
+**DO:** Poll the logs API for up to 5 seconds. A 200 with at least one entry means the request reached the proxy:
 
 \`\`\`bash
 for i in $(seq 1 10); do
@@ -367,13 +480,24 @@ for i in $(seq 1 10); do
   count=$(echo "$resp" | grep -o '"total":[0-9]*' | head -1 | grep -o '[0-9]*$')
   if [ "\${count:-0}" -ge 1 ]; then
     echo "captured"
+    echo "$resp" | head -c 400
     break
   fi
   sleep 0.5
 done
 \`\`\`
 
-**PAUSE** \u2014 show the user the captured log entry (id, status, model, elapsed). If the count never reached 1, the proxy didn't see the request \u2014 re-check the env var and the proxy log.
+**DO:** Diagnose the response based on the actual status and body. **Do not** default to "auth failure" for every 4xx.
+
+| Status | Body hint | Meaning |
+|--------|-----------|---------|
+| 200 | normal | Real success \u2014 the upstream returned data |
+| 401 | \`"unauthorized"\` or similar | Upstream rejected the key (expected with a test key) |
+| 403 | \`"Request not allowed"\` | **Proxy's allowlist** \u2014 not an auth failure, the proxy rejected the model/config. Show the user the proxy log. |
+| 403 | other text | Could be upstream ACL \u2014 different problem |
+| 5xx | anything | Upstream network error |
+
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`Captured?\` and options matching the diagnosis above. Wait for the answer.
 
 ---
 
@@ -390,14 +514,14 @@ done
   # Unix / macOS
   lsof -ti:${port} | xargs -r kill -9
 
-  # Windows PowerShell
-  Get-NetTCPConnection -LocalPort ${port} | ForEach-Object { Stop-Process -Id \\$_.OwningProcess -Force }
+  # Windows PowerShell \u2014 single-quoted so $env: expands correctly
+  Get-NetTCPConnection -LocalPort $port | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
   \`\`\`
 
 - **Re-run onboard**: \`llm-inspector onboard --force\` refreshes this skill.
 - **Full docs**: see the project README (linked from the Web UI footer).
 
-**PAUSE** \u2014 let the user know they can come back to this skill at any time via \`/llm-inspector:onboard\` if they want a refresher, and call out that \`/llm-inspector:onboard --skip-tool-wire\` is the way to re-run later phases without re-detecting the tool.
+> **PAUSE** \u2014 use \`AskUserQuestion\` with header \`All set?\` and options \`["All set, I'm done", "Wait, I want to revisit a phase"]\`. Wait for the answer.
 
 You're done. Happy inspecting.
 `;
@@ -407,6 +531,7 @@ var init_skill_onboard = __esm({
   "src/cli/templates/skill-onboard.ts"() {
     "use strict";
     REQUIRED_PHASE_HEADINGS = [
+      "Phase 0: Idempotency check",
       "Preflight",
       "Phase 1: Welcome",
       "Phase 2: Provider setup",
@@ -629,23 +754,105 @@ var init_onboard = __esm({
 
 // src/cli.ts
 import { spawn, execSync } from "node:child_process";
+import { createConnection } from "node:net";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { dirname as dirname2, join as join3 } from "node:path";
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname2(__filename2);
 var DEFAULT_PORT2 = 25947;
+var LOCAL_PROBE_TIMEOUT_MS = 2e3;
 var subcommand = process.argv[2];
 if (subcommand === "onboard") {
   const { runOnboard: runOnboard2 } = await Promise.resolve().then(() => (init_onboard(), onboard_exports));
   const code = await runOnboard2(process.argv.slice(3));
   process.exit(code);
 }
-runStart(process.argv.slice(2));
-function runStart(args) {
+await runStart(process.argv.slice(2));
+async function isInspectorHealthy(port) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), LOCAL_PROBE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/api/health`, {
+      cache: "no-store",
+      signal: controller.signal
+    });
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+function isPortAcceptingConnections(port) {
+  return new Promise((resolve) => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (value) => {
+      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) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+async function waitForInspectorHealthy(port, timeoutMs) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (await isInspectorHealthy(port)) return true;
+    await sleep(250);
+  }
+  return false;
+}
+function openBrowser(targetUrl) {
+  let command;
+  switch (process.platform) {
+    case "darwin":
+      command = ["open", targetUrl];
+      break;
+    case "linux":
+      command = ["xdg-open", targetUrl];
+      break;
+    case "win32":
+      command = ["cmd", "/c", "start", "", targetUrl];
+      break;
+    default:
+      break;
+  }
+  if (command === void 0) return;
+  const [bin, ...cmdArgs] = command;
+  if (bin === void 0) return;
+  const browserProcess = spawn(bin, cmdArgs, {
+    stdio: "ignore",
+    detached: true,
+    windowsHide: true
+  });
+  browserProcess.unref();
+}
+function waitForProcessExit(child) {
+  return new Promise((resolve) => {
+    child.once("exit", (code) => {
+      resolve(code ?? 1);
+    });
+    child.once("error", () => {
+      resolve(1);
+    });
+  });
+}
+async function runStart(args) {
   const envPort = process.env["PORT"];
   const portDefault = envPort !== void 0 ? Number(envPort) : DEFAULT_PORT2;
   let port = portDefault;
   let open = true;
+  let openWasSpecified = false;
+  let background = false;
+  let forceRestart = false;
   let configDir;
   let providersJson;
   for (let i = 0; i < args.length; i++) {
@@ -658,9 +865,18 @@ function runStart(args) {
         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 "--config-dir":
         configDir = args[i + 1];
@@ -674,6 +890,11 @@ function runStart(args) {
         break;
     }
   }
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+    console.error(`Invalid port: ${String(port)}. Use --port <1-65535>.`);
+    process.exitCode = 1;
+    return;
+  }
   function killProcessOnPort(targetPort) {
     const platform = process.platform;
     try {
@@ -681,7 +902,8 @@ function runStart(args) {
       if (platform === "win32") {
         const output = execSync(`netstat -ano | findstr :${targetPort}`, {
           encoding: "utf8",
-          timeout: 5e3
+          timeout: 5e3,
+          windowsHide: true
         });
         const lines = output.trim().split("\n");
         for (const line of lines) {
@@ -700,8 +922,12 @@ function runStart(args) {
         pids = [...new Set(pids)];
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
-            execSync(`taskkill /PID ${pid} /F`, { encoding: "utf8", timeout: 5e3 });
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
+            execSync(`taskkill /PID ${pid} /F`, {
+              encoding: "utf8",
+              timeout: 5e3,
+              windowsHide: true
+            });
           } catch {
           }
         }
@@ -717,7 +943,7 @@ function runStart(args) {
         pids = [...new Set(pids)];
         for (const pid of pids) {
           try {
-            console.log(`Killing process ${pid} on port ${port}...`);
+            console.log(`Killing process ${pid} on port ${targetPort}...`);
             execSync(`kill -9 ${pid}`, { encoding: "utf8", timeout: 5e3 });
           } catch {
           }
@@ -727,8 +953,24 @@ function runStart(args) {
     }
   }
   process.env["PORT"] = String(port);
-  killProcessOnPort(port);
   const url = `http://localhost:${port}`;
+  if (!forceRestart && await isInspectorHealthy(port)) {
+    console.log(`llm-inspector is already running at ${url}`);
+    console.log(`Use --force-restart to restart the existing instance.`);
+    if (open && openWasSpecified) {
+      openBrowser(url);
+    }
+    return;
+  }
+  if (!forceRestart && await isPortAcceptingConnections(port)) {
+    console.error(`Port ${port} is already in use, but it is not a healthy llm-inspector.`);
+    console.error(`Stop that process, choose --port <n>, or re-run with --force-restart.`);
+    process.exitCode = 1;
+    return;
+  }
+  if (forceRestart) {
+    killProcessOnPort(port);
+  }
   console.log(`Server running at ${url}`);
   console.log(`   Proxy: ${url}/proxy`);
   console.log(``);
@@ -746,26 +988,6 @@ function runStart(args) {
   console.log(
     `   Example: ROUTES='{"claude-":"https://api.anthropic.com","MiniMax":"https://api.minimaxi.com/anthropic"}'`
   );
-  const openBrowser = (targetUrl) => {
-    let command;
-    switch (process.platform) {
-      case "darwin":
-        command = ["open", targetUrl];
-        break;
-      case "linux":
-        command = ["xdg-open", targetUrl];
-        break;
-      case "win32":
-        command = ["cmd", "/c", "start", targetUrl];
-        break;
-      default:
-        break;
-    }
-    if (command === void 0) return;
-    const [bin, ...cmdArgs] = command;
-    if (bin === void 0) return;
-    spawn(bin, cmdArgs, { stdio: "ignore", detached: true });
-  };
   if (open) {
     openBrowser(url);
   }
@@ -774,8 +996,11 @@ function runStart(args) {
   const serverEnv = { ...process.env };
   if (configDir !== void 0) {
     let resolvedPath = join3(configDir, "config.json");
-    if (resolvedPath.startsWith("\\c\\")) {
-      resolvedPath = "C:" + resolvedPath;
+    const msysMatch = /^\\([a-z])\\(.*)$/i.exec(resolvedPath);
+    if (msysMatch !== null) {
+      const drive = (msysMatch[1] ?? "").toUpperCase();
+      const rest = msysMatch[2] ?? "";
+      resolvedPath = `${drive}:\\${rest}`;
     }
     serverEnv["LLM_INSPECTOR_CONFIG_PATH"] = resolvedPath;
   }
@@ -783,9 +1008,20 @@ function runStart(args) {
     serverEnv["LLM_INSPECTOR_PROVIDERS_JSON"] = providersJson;
   }
   const serverProcess = spawn(process.execPath, [serverPath], {
-    stdio: ["ignore", "inherit", "inherit"],
-    detached: true,
-    env: serverEnv
+    stdio: background ? ["ignore", "ignore", "ignore"] : "inherit",
+    detached: background,
+    env: serverEnv,
+    windowsHide: background
   });
-  serverProcess.unref();
+  if (background) {
+    serverProcess.unref();
+    if (await waitForInspectorHealthy(port, 5e3)) {
+      console.log(`llm-inspector background server is ready at ${url}`);
+      return;
+    }
+    console.error(`llm-inspector background server did not become ready at ${url}.`);
+    process.exitCode = 1;
+    return;
+  }
+  process.exitCode = await waitForProcessExit(serverProcess);
 }