multicorn-shield 1.11.0 → 1.12.0

package/dist/multicorn-shield.js

@@ -658,7 +658,35 @@ function isVersionAtLeast(version, minimum) {
   }
   return true;
 }
-async function updateOpenClawConfigIfPresent(apiKey, baseUrl, agentName) {
+var OPENCLAW_SHIELD_API_KEY_ENV_REF = "${MULTICORN_API_KEY}";
+function buildOpenClawShieldPluginConfig(params) {
+  return {
+    apiKey: OPENCLAW_SHIELD_API_KEY_ENV_REF,
+    baseUrl: params.baseUrl,
+    agentName: params.agentName,
+    failMode: "closed"
+  };
+}
+function detectStaleOpenClawHookIntegration(openclawConfig) {
+  const hooks = openclawConfig["hooks"];
+  if (typeof hooks !== "object" || hooks === null) return false;
+  const internal = hooks["internal"];
+  if (typeof internal !== "object" || internal === null) return false;
+  const entries = internal["entries"];
+  if (typeof entries !== "object" || entries === null) return false;
+  return Object.prototype.hasOwnProperty.call(entries, "multicorn-shield");
+}
+function staleOpenClawHookIntegrationMessage() {
+  return "Deprecated OpenClaw gateway hook config detected at hooks.internal.entries.multicorn-shield. Shield now uses the multicorn-shield plugin under plugins.entries. Disable the old hook manually (for example openclaw hooks disable multicorn-shield) and remove hooks.internal.entries.multicorn-shield when you are ready.";
+}
+function stripLegacyOpenClawShieldEntryFields(shield) {
+  delete shield["env"];
+  delete shield["apiKey"];
+  delete shield["baseUrl"];
+  delete shield["agentName"];
+  delete shield["failMode"];
+}
+async function updateOpenClawConfigIfPresent(_apiKey, baseUrl, agentName) {
   let raw;
   try {
     raw = await readFile(OPENCLAW_CONFIG_PATH, "utf8");
@@ -674,50 +702,67 @@ async function updateOpenClawConfigIfPresent(apiKey, baseUrl, agentName) {
   } catch {
     return "parse-error";
   }
-  let hooks = obj["hooks"];
-  if (hooks === void 0 || typeof hooks !== "object") {
-    hooks = {};
-    obj["hooks"] = hooks;
+  if (detectStaleOpenClawHookIntegration(obj)) {
+    process.stderr.write(
+      style.yellow("\u26A0") + " " + staleOpenClawHookIntegrationMessage() + "\n"
+    );
   }
-  let internal = hooks["internal"];
-  if (internal === void 0 || typeof internal !== "object") {
-    internal = { enabled: true, entries: {} };
-    hooks["internal"] = internal;
+  let plugins = obj["plugins"];
+  if (plugins === void 0 || typeof plugins !== "object") {
+    plugins = {};
+    obj["plugins"] = plugins;
   }
-  let entries = internal["entries"];
-  if (entries === void 0 || typeof entries !== "object") {
-    entries = {};
-    internal["entries"] = entries;
+  let pluginEntries = plugins["entries"];
+  if (pluginEntries === void 0 || typeof pluginEntries !== "object") {
+    pluginEntries = {};
+    plugins["entries"] = pluginEntries;
   }
-  let shield = entries["multicorn-shield"];
+  let shield = pluginEntries["multicorn-shield"];
   if (shield === void 0 || typeof shield !== "object") {
-    shield = { enabled: true, env: {} };
-    entries["multicorn-shield"] = shield;
-  }
-  let env = shield["env"];
-  if (env === void 0 || typeof env !== "object") {
-    env = {};
-    shield["env"] = env;
-  }
-  env["MULTICORN_API_KEY"] = apiKey;
-  env["MULTICORN_BASE_URL"] = baseUrl;
-  if (agentName !== void 0) {
-    env["MULTICORN_AGENT_NAME"] = agentName;
+    shield = { enabled: true };
+    pluginEntries["multicorn-shield"] = shield;
+  }
+  stripLegacyOpenClawShieldEntryFields(shield);
+  const resolvedAgentName = agentName ?? (typeof shield["config"] === "object" && shield["config"] !== null && typeof shield["config"]["agentName"] === "string" ? String(shield["config"]["agentName"]) : void 0);
+  if (resolvedAgentName !== void 0) {
+    shield["enabled"] = true;
+    shield["config"] = buildOpenClawShieldPluginConfig({
+      baseUrl,
+      agentName: resolvedAgentName
+    });
     const agentsList = obj["agents"];
     const list = agentsList?.["list"];
     if (Array.isArray(list) && list.length > 0) {
       const first = list[0];
-      if (first["id"] !== agentName) {
-        first["id"] = agentName;
-        first["name"] = agentName;
+      if (first["id"] !== resolvedAgentName) {
+        first["id"] = resolvedAgentName;
+        first["name"] = resolvedAgentName;
       }
     } else {
       if (agentsList !== void 0 && typeof agentsList === "object") {
-        agentsList["list"] = [{ id: agentName, name: agentName }];
+        agentsList["list"] = [{ id: resolvedAgentName, name: resolvedAgentName }];
       } else {
-        obj["agents"] = { list: [{ id: agentName, name: agentName }] };
+        obj["agents"] = { list: [{ id: resolvedAgentName, name: resolvedAgentName }] };
       }
     }
+  } else {
+    shield["enabled"] = true;
+    const existingConfig = shield["config"];
+    if (typeof existingConfig === "object" && existingConfig !== null) {
+      const cfg = { ...existingConfig };
+      cfg["apiKey"] = OPENCLAW_SHIELD_API_KEY_ENV_REF;
+      cfg["baseUrl"] = baseUrl;
+      if (cfg["failMode"] !== "open" && cfg["failMode"] !== "closed") {
+        cfg["failMode"] = "closed";
+      }
+      shield["config"] = cfg;
+    } else {
+      shield["config"] = {
+        apiKey: OPENCLAW_SHIELD_API_KEY_ENV_REF,
+        baseUrl,
+        failMode: "closed"
+      };
+    }
   }
   await writeFile(
     OPENCLAW_CONFIG_PATH,
@@ -726,6 +771,10 @@ async function updateOpenClawConfigIfPresent(apiKey, baseUrl, agentName) {
   );
   return "updated";
 }
+function isPastedShieldApiKeyInput(input) {
+  const trimmed = input.trim();
+  return trimmed.startsWith("mcs_") && trimmed.length >= 8;
+}
 async function validateApiKey(apiKey, baseUrl) {
   try {
     const response = await fetch(`${baseUrl}/api/v1/agents`, {
@@ -1095,40 +1144,6 @@ async function installCodexCliNativeHooks() {
   };
   await writeFile(getCodexHooksJsonPath(), JSON.stringify(hooksConfig, null, 2) + "\n", "utf8");
 }
-async function promptCodexCliIntegrationMode(ask) {
-  process.stderr.write("\n" + style.bold("Codex CLI integration") + "\n");
-  process.stderr.write(
-    "  " + style.violet("1") + ". Native plugin - Shield checks terminal (Bash) commands via Codex Hooks\n"
-  );
-  process.stderr.write(
-    "  " + style.violet("2") + ". Hosted proxy - govern MCP server traffic via config.toml\n"
-  );
-  let choice = 0;
-  while (choice === 0) {
-    const input = await ask("Choose integration (1-2): ");
-    const num = parseInt(input.trim(), 10);
-    if (num === 1) choice = 1;
-    if (num === 2) choice = 2;
-  }
-  return choice === 1 ? "native" : "hosted";
-}
-async function promptClineIntegrationMode(ask) {
-  process.stderr.write("\n" + style.bold("Cline integration") + "\n");
-  process.stderr.write(
-    "  " + style.violet("1") + ". Native plugin (recommended) - Cline Hooks see every file, terminal, browser, and MCP action\n"
-  );
-  process.stderr.write(
-    "  " + style.violet("2") + ". Hosted proxy - govern MCP traffic only (paste proxy URL into Cline MCP settings)\n"
-  );
-  let choice = 0;
-  while (choice === 0) {
-    const input = await ask("Choose integration (1-2): ");
-    const num = parseInt(input.trim(), 10);
-    if (num === 1) choice = 1;
-    if (num === 2) choice = 2;
-  }
-  return choice === 1 ? "native" : "hosted";
-}
 function getGeminiCliHooksInstallDir() {
   return join(homedir(), ".multicorn", "gemini-cli-hooks");
 }
@@ -1454,40 +1469,6 @@ async function installGeminiCliNativeHooks(ask) {
   await mkdir(dirname(settingsPath), { recursive: true });
   await writeFile(settingsPath, JSON.stringify(existing, null, 2) + "\n", SECRET_JSON_FILE_OPTIONS);
 }
-async function promptGeminiCliIntegrationMode(ask) {
-  process.stderr.write("\n" + style.bold("Gemini CLI integration") + "\n");
-  process.stderr.write(
-    "  " + style.violet("1") + ". Native plugin (recommended) - Gemini CLI Hooks see every file, terminal, web, and MCP action\n"
-  );
-  process.stderr.write(
-    "  " + style.violet("2") + ". Hosted proxy - govern MCP traffic only (paste proxy URL into Gemini CLI settings)\n"
-  );
-  let choice = 0;
-  while (choice === 0) {
-    const input = await ask("Choose integration (1-2): ");
-    const num = parseInt(input.trim(), 10);
-    if (num === 1) choice = 1;
-    if (num === 2) choice = 2;
-  }
-  return choice === 1 ? "native" : "hosted";
-}
-async function promptOpencodeIntegrationMode(ask) {
-  process.stderr.write("\n" + style.bold("OpenCode integration") + "\n");
-  process.stderr.write(
-    "  " + style.violet("1") + ". Native plugin (recommended) - Shield checks primary-agent tool execution via OpenCode Hooks\n"
-  );
-  process.stderr.write(
-    "  " + style.violet("2") + ". Hosted proxy - govern MCP server traffic via opencode.json (full subagent coverage when tools use MCP through Shield)\n"
-  );
-  let choice = 0;
-  while (choice === 0) {
-    const input = await ask("Choose integration (1-2): ");
-    const num = parseInt(input.trim(), 10);
-    if (num === 1) choice = 1;
-    if (num === 2) choice = 2;
-  }
-  return choice === 1 ? "native" : "hosted";
-}
 function getClaudeDesktopConfigPath() {
   switch (process.platform) {
     case "win32":
@@ -1607,27 +1588,22 @@ var INIT_WIZARD_PLATFORM_REGISTRY = [
   },
   { slug: "other-mcp", displayName: "Local MCP / Other", section: "hosted" }
 ];
-var INIT_WIZARD_MENU_SECTIONS = (() => {
-  const itemsFor = (section) => INIT_WIZARD_PLATFORM_REGISTRY.filter((e) => e.section === section).map((e) => ({
-    platform: e.slug,
-    label: e.displayName
-  }));
-  return [
-    { title: "Recommended (native plugin)", items: itemsFor("native") },
-    { title: "Hosted proxy (MCP only)", items: itemsFor("hosted") }
-  ];
-})();
-var INIT_WIZARD_SELECTION_MAX = INIT_WIZARD_PLATFORM_REGISTRY.length;
+var INIT_WIZARD_PICKER_NATIVE_SLUGS = INIT_WIZARD_PLATFORM_REGISTRY.filter((e) => e.section === "native").map((e) => e.slug);
+var INIT_WIZARD_DASHBOARD_AGENTS_URL = "https://app.multicorn.ai/agents/new";
+var INIT_WIZARD_PICKER_SELECTION_MAX = INIT_WIZARD_PICKER_NATIVE_SLUGS.length;
+var PICKER_SLUG_BY_SELECTION = Object.fromEntries(
+  INIT_WIZARD_PICKER_NATIVE_SLUGS.map((slug, i) => [i + 1, slug])
+);
 var INIT_EXISTING_AGENTS_PLATFORM_ACTIONS = [
   "Add a new agent alongside these",
   "Replace an existing agent",
   "Skip - choose a different platform"
 ];
-var PLATFORM_BY_SELECTION = Object.fromEntries(
-  INIT_WIZARD_PLATFORM_REGISTRY.map((e, i) => [i + 1, e.slug])
-);
-function platformMenuLabelForSelection(sel) {
-  const slug = PLATFORM_BY_SELECTION[sel];
+function resolveInitHybridIntegrationMode(explicit) {
+  return explicit ?? "native";
+}
+function platformMenuLabelForPickerSelection(sel) {
+  const slug = PICKER_SLUG_BY_SELECTION[sel];
   if (slug === void 0) return "Unknown";
   const entry = INIT_WIZARD_PLATFORM_REGISTRY.find((e) => e.slug === slug);
   return entry?.displayName ?? slug;
@@ -1645,48 +1621,31 @@ async function promptPlatformSelection(ask) {
   process.stderr.write(
     "\n" + style.bold(style.violet("Which platform are you connecting?")) + "\n\n"
   );
+  process.stderr.write("  " + style.dim("Native plugin (files, terminal, browser)") + "\n");
   let optionNum = 1;
-  for (const section of INIT_WIZARD_MENU_SECTIONS) {
-    process.stderr.write("  " + style.dim(section.title) + "\n");
-    for (const item of section.items) {
-      const indent = optionNum >= 10 ? "   " : "    ";
-      process.stderr.write(`${indent}${style.violet(String(optionNum))}. ${item.label}
+  for (const slug of INIT_WIZARD_PICKER_NATIVE_SLUGS) {
+    const entry = INIT_WIZARD_PLATFORM_REGISTRY.find((e) => e.slug === slug);
+    const label = entry?.displayName ?? slug;
+    const indent = optionNum >= 10 ? "   " : "    ";
+    process.stderr.write(`${indent}${style.violet(String(optionNum))}. ${label}
 `);
-      optionNum++;
-    }
+    optionNum++;
   }
-  process.stderr.write(
-    "\n" + style.dim(
-      `  Pick ${String(INIT_WIZARD_SELECTION_MAX)} to wrap a local MCP server with multicorn-shield --wrap.`
-    ) + "\n"
-  );
+  process.stderr.write("\n");
+  process.stderr.write("  MCP agents (Cursor, Copilot, others) are set up\n");
+  process.stderr.write(`  in the dashboard: ${INIT_WIZARD_DASHBOARD_AGENTS_URL}
+
+`);
   let selection = 0;
   while (selection === 0) {
-    const input = await ask(`Select (1-${String(INIT_WIZARD_SELECTION_MAX)}): `);
+    const input = await ask(`Select (1-${String(INIT_WIZARD_PICKER_SELECTION_MAX)}): `);
     const num = parseInt(input.trim(), 10);
-    if (num >= 1 && num <= INIT_WIZARD_SELECTION_MAX) {
+    if (num >= 1 && num <= INIT_WIZARD_PICKER_SELECTION_MAX) {
       selection = num;
     }
   }
   return selection;
 }
-async function promptWindsurfIntegrationMode(ask) {
-  process.stderr.write("\n" + style.bold("Windsurf integration") + "\n");
-  process.stderr.write(
-    "  " + style.violet("1") + ". Native plugin (recommended) - Cascade Hooks see every file, terminal, and MCP action\n"
-  );
-  process.stderr.write(
-    "  " + style.violet("2") + ". Hosted proxy - govern MCP traffic only (paste proxy URL into mcp_config)\n"
-  );
-  let choice = 0;
-  while (choice === 0) {
-    const input = await ask("Choose integration (1-2): ");
-    const num = parseInt(input.trim(), 10);
-    if (num === 1) choice = 1;
-    if (num === 2) choice = 2;
-  }
-  return choice === 1 ? "native" : "hosted";
-}
 async function arrowSelect(options, ask, fallbackLabel) {
   if (options.length === 1) {
     const only = options[0] ?? "";
@@ -1899,6 +1858,14 @@ var HOSTED_PROXY_PLATFORMS_WITH_URL_KEY = /* @__PURE__ */ new Set([
 function shouldEmbedKeyInHostedProxyUrl(platform) {
   return HOSTED_PROXY_PLATFORMS_WITH_URL_KEY.has(platform);
 }
+function buildClineHostedMcpEntry(url) {
+  return {
+    type: "streamableHttp",
+    url,
+    timeout: 60,
+    disabled: false
+  };
+}
 function hostedProxyUrlWithKeyParam(proxyUrl, apiKey) {
   if (apiKey.length === 0) {
     process.stderr.write(
@@ -2303,9 +2270,11 @@ async function applyHostedProxyMcpConfig(platform, proxyUrl, shortName, apiKey,
         printHostedProxyJsonParseWarning(getWindsurfMcpConfigPath());
       }
     } else if (platform === "cline") {
-      result = await mergeMcpServersObjectStyle(getClineMcpSettingsPath(), shortName, {
-        url: proxyUrlWithKeyWhenNeeded
-      });
+      result = await mergeMcpServersObjectStyle(
+        getClineMcpSettingsPath(),
+        shortName,
+        buildClineHostedMcpEntry(proxyUrlWithKeyWhenNeeded)
+      );
       if (result === "parse-error") {
         printHostedProxyJsonParseWarning(getClineMcpSettingsPath());
       }
@@ -2595,9 +2564,7 @@ Authorization = "Bearer ${bearerToken}"
     snippetText = platform === "cline" ? JSON.stringify(
       {
         mcpServers: {
-          [shortName]: {
-            [urlKey]: urlInSnippet
-          }
+          [shortName]: buildClineHostedMcpEntry(urlInSnippet)
         }
       },
       null,
@@ -2761,6 +2728,7 @@ function mergeAgentsForPlatform(localAgents, remoteAgents, selectedPlatform) {
 var DEFAULT_SHIELD_API_BASE_URL = "https://api.multicorn.ai";
 async function runInit(explicitBaseUrl, options) {
   const verbose = options?.verbose === true;
+  const hybridIntegration = resolveInitHybridIntegrationMode(options?.integration);
   if (!process.stdin.isTTY) {
     process.stderr.write(
       style.red("Error: interactive terminal required. Cannot run init with piped input.") + "\n"
@@ -2805,9 +2773,31 @@ async function runInit(explicitBaseUrl, options) {
   if (existing !== null && existing.apiKey.startsWith("mcs_") && existing.apiKey.length >= 8) {
     const masked = "mcs_..." + existing.apiKey.slice(-4);
     process.stderr.write("Found existing API key: " + style.cyan(masked) + "\n");
-    const answer = await ask("Use this key? (Y/n) ");
-    if (answer.trim().toLowerCase() !== "n") {
-      apiKey = existing.apiKey;
+    const answer = await ask("Use this key? (Y/n, or paste a new mcs_ key) ");
+    const trimmed = answer.trim();
+    if (trimmed.toLowerCase() !== "n") {
+      const candidate = isPastedShieldApiKeyInput(trimmed) ? trimmed : existing.apiKey;
+      const spinner = withSpinner("Validating key...");
+      let reuseResult;
+      try {
+        reuseResult = await validateApiKey(candidate, resolvedBaseUrl);
+      } catch (error) {
+        spinner.stop(false, "Validation failed");
+        throw error;
+      }
+      if (reuseResult.valid) {
+        spinner.stop(true, "Key validated");
+        apiKey = candidate;
+      } else {
+        spinner.stop(false, reuseResult.error ?? "Validation failed.");
+        if (isPastedShieldApiKeyInput(trimmed)) {
+          process.stderr.write(style.red("That key was rejected. Enter a new key below.") + "\n");
+        } else {
+          process.stderr.write(
+            style.yellow("Existing key is no longer valid. Enter a new key below.") + "\n"
+          );
+        }
+      }
     }
   }
   if (apiKey.length === 0) {
@@ -2859,8 +2849,8 @@ async function runInit(explicitBaseUrl, options) {
     let removeAgentNameBeforeSave = void 0;
     const initWorkspacePath = resolve(process.cwd());
     const selection = await promptPlatformSelection(ask);
-    const selectedPlatform = PLATFORM_BY_SELECTION[selection] ?? "cursor";
-    const selectedLabel = platformMenuLabelForSelection(selection);
+    const selectedPlatform = PICKER_SLUG_BY_SELECTION[selection] ?? "openclaw";
+    const selectedLabel = platformMenuLabelForPickerSelection(selection);
     if (selectedPlatform === "other-mcp") {
       const raw = existing !== null ? { ...existing } : {};
       raw["apiKey"] = apiKey;
@@ -2994,7 +2984,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
       }
       if (detection.status === "parse-error") {
         process.stderr.write(
-          style.red("\u2717") + " Could not update OpenClaw config. Set MULTICORN_API_KEY in ~/.openclaw/openclaw.json manually.\n"
+          style.red("\u2717") + " Could not update OpenClaw config. Set plugins.entries.multicorn-shield.config.apiKey in ~/.openclaw/openclaw.json, or run npx multicorn-shield init.\n"
         );
       }
       if (detection.status === "detected") {
@@ -3034,7 +3024,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
           if (result === "parse-error") {
             spinner.stop(
               false,
-              "Could not update OpenClaw config. Set MULTICORN_API_KEY in ~/.openclaw/openclaw.json manually."
+              "Could not update OpenClaw config. Set plugins.entries.multicorn-shield.config.apiKey in ~/.openclaw/openclaw.json, or run npx multicorn-shield init."
             );
           } else {
             spinner.stop(
@@ -3081,7 +3071,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
       });
       setupSucceeded = true;
     } else if (selectedPlatform === "windsurf") {
-      const windsurfMode = await promptWindsurfIntegrationMode(ask);
+      const windsurfMode = hybridIntegration;
       if (windsurfMode === "native") {
         try {
           await installWindsurfNativeHooks();
@@ -3180,7 +3170,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else if (selectedPlatform === "gemini-cli") {
-      const geminiMode = await promptGeminiCliIntegrationMode(ask);
+      const geminiMode = hybridIntegration;
       if (geminiMode === "native") {
         try {
           await installGeminiCliNativeHooks(ask);
@@ -3274,7 +3264,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else if (selectedPlatform === "opencode") {
-      const opencodeMode = await promptOpencodeIntegrationMode(ask);
+      const opencodeMode = hybridIntegration;
       if (opencodeMode === "native") {
         try {
           await installOpenCodeNativePlugin();
@@ -3363,7 +3353,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else if (selectedPlatform === "codex-cli") {
-      const codexMode = await promptCodexCliIntegrationMode(ask);
+      const codexMode = hybridIntegration;
       if (codexMode === "native") {
         try {
           await installCodexCliNativeHooks();
@@ -3452,7 +3442,7 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
         }
       }
     } else if (selectedPlatform === "cline") {
-      const clineMode = await promptClineIntegrationMode(ask);
+      const clineMode = hybridIntegration;
       if (clineMode === "native") {
         try {
           await installClineNativeHooks();
@@ -3935,9 +3925,7 @@ async function writeLocalMcpEntry(client, agentName, localProxyUrl, apiKey, work
       return await mergeMcpServersObjectStyle(
         filePath,
         entryKey,
-        {
-          url
-        },
+        buildClineHostedMcpEntry(url),
         legacyKeys
       ) === "ok" ? filePath : null;
     case "windsurf":
@@ -4985,10 +4973,95 @@ async function restoreClaudeDesktopMcpFromBackup() {
 
 // package.json
 var package_default = {
-  version: "1.11.0"};
+  version: "1.12.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;
+var LOCAL_PROXY_READY_POLL_MS = 500;
+var LOCAL_PROXY_READY_MAX_POLLS = 30;
+var NOT_FOUND_MESSAGE = "Local proxy server entry (dist/server.js) not found. Reinstall multicorn-shield or run pnpm build.";
+function findMulticornShieldPackageRoot(moduleDir = dirname(fileURLToPath(import.meta.url))) {
+  let current = moduleDir;
+  for (; ; ) {
+    const pkgPath = join(current, "package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.name === "multicorn-shield") {
+          return current;
+        }
+      } catch {
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  try {
+    const req = createRequire(import.meta.url);
+    return dirname(req.resolve("multicorn-shield/package.json"));
+  } catch {
+    throw new Error(NOT_FOUND_MESSAGE);
+  }
+}
+function resolveLocalProxyServerEntry(options) {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(findMulticornShieldPackageRoot(moduleDir), "dist", "server.js")
+  ];
+  try {
+    const req = createRequire(import.meta.url);
+    const proxyRoot = dirname(req.resolve("multicorn-proxy/package.json"));
+    candidates.unshift(join(proxyRoot, "dist", "server.js"));
+  } catch {
+  }
+  for (const path of candidates) {
+    if (existsSync(path)) return path;
+  }
+  throw new Error(NOT_FOUND_MESSAGE);
+}
+function buildLocalProxySpawnEnv(port, apiBaseUrl) {
+  return {
+    PORT: String(port),
+    HOST: "127.0.0.1",
+    SHIELD_API_BASE_URL: apiBaseUrl,
+    ALLOW_PRIVATE_TARGETS: "true"
+  };
+}
+function buildLocalProxySpawnCommand(port, apiBaseUrl, execPath = process.execPath, serverEntryPath = resolveLocalProxyServerEntry()) {
+  const env = buildLocalProxySpawnEnv(port, apiBaseUrl);
+  return {
+    executable: execPath,
+    args: [serverEntryPath],
+    env,
+    serverEntryPath
+  };
+}
+function readProxyLogTail(logPath, maxBytes = 8e3) {
+  try {
+    const content = readFileSync(logPath, "utf8");
+    if (content.length <= maxBytes) return content;
+    return content.slice(-maxBytes);
+  } catch {
+    return "";
+  }
+}
+function formatLocalProxyStartError(port, logPath, childExited, exitCode) {
+  const logTail = readProxyLogTail(logPath);
+  const reason = childExited ? `Proxy process exited early${exitCode === null ? "" : ` (code ${String(exitCode)})`}.` : `Proxy did not become ready on port ${String(port)} within the timeout.`;
+  let message = `Could not start the local proxy on port ${String(port)}. ${reason}`;
+  message += logTail.length > 0 ? `
+
+Output from ${logPath}:
+${logTail.trimEnd()}` : `
+
+See ${logPath} for details.`;
+  return message;
+}
+
+// src/commands/files.ts
 var DEFAULT_FS_PORT = 3005;
 var DEFAULT_PROXY_PORT = 3001;
 var PIDFILE_DIR = process.env["MULTICORN_HOME"] ?? join(homedir(), ".multicorn");
@@ -5023,6 +5096,16 @@ function readPidfile(agent) {
     return null;
   }
 }
+function supervisorPidFromSession(data) {
+  if (typeof data.supervisorPid === "number") return data.supervisorPid;
+  if (typeof data.pid === "number") return data.pid;
+  return void 0;
+}
+function isAgentSessionRunning(data) {
+  if (data === null) return false;
+  const pid = supervisorPidFromSession(data);
+  return typeof pid === "number" && isProcessAlive(pid);
+}
 function removePidfile(agent) {
   const p = pidfilePath(agent);
   try {
@@ -5063,7 +5146,7 @@ function runStatus() {
   const fsReg = readFsRegistry();
   process.stderr.write("Active sessions:\n\n");
   for (const s of sessions) {
-    const supervisorAlive = typeof s.supervisorPid === "number" && isProcessAlive(s.supervisorPid);
+    const supervisorAlive = isAgentSessionRunning(s);
     const fsEntry = fsReg[s.dir];
     const fsAlive = fsEntry !== void 0 && isProcessAlive(fsEntry.pid);
     const proxyAlive = proxyReg !== null && proxyReg.port === s.proxyPort && isProcessAlive(proxyReg.pid);
@@ -5210,9 +5293,7 @@ async function withResourceLock(fn) {
   }
 }
 function liveAgents() {
-  return listAllPidfiles().filter(
-    (p) => typeof p.supervisorPid === "number" && isProcessAlive(p.supervisorPid)
-  );
+  return listAllPidfiles().filter((p) => isAgentSessionRunning(p));
 }
 function agentsReferencingProxy(proxyPort, agents, excludeAgent) {
   return agents.filter((a) => a.agent !== excludeAgent && a.proxyPort === proxyPort);
@@ -5230,27 +5311,37 @@ async function nextFreePort(start, claimed, isBusy, range = FS_PORT_SCAN_RANGE)
     `No free port for the filesystem server in range ${String(start)}-${String(start + range)}.`
   );
 }
+async function resolveBaseUrl(explicitBaseUrl) {
+  if (explicitBaseUrl !== void 0 && explicitBaseUrl.trim().length > 0) {
+    return explicitBaseUrl.trim();
+  }
+  const envBaseUrl = process.env["MULTICORN_BASE_URL"];
+  if (typeof envBaseUrl === "string" && envBaseUrl.trim().length > 0) {
+    return envBaseUrl.trim();
+  }
+  const config = await loadConfig();
+  if (config !== null && config.baseUrl.length > 0) {
+    return config.baseUrl;
+  }
+  const fromFile = await readBaseUrlFromConfig();
+  if (fromFile !== void 0 && fromFile.length > 0) {
+    return fromFile;
+  }
+  return DEFAULT_SHIELD_API_BASE_URL;
+}
 async function resolveConfig(opts) {
+  const baseUrl = await resolveBaseUrl(opts.baseUrl);
   const fromFlag = opts.apiKey;
   if (fromFlag && fromFlag.length > 0) {
-    return {
-      apiKey: fromFlag,
-      baseUrl: opts.baseUrl ?? DEFAULT_SHIELD_API_BASE_URL
-    };
+    return { apiKey: fromFlag, baseUrl };
   }
   const envKey = process.env["MULTICORN_API_KEY"];
   if (typeof envKey === "string" && envKey.length > 0) {
-    return {
-      apiKey: envKey,
-      baseUrl: opts.baseUrl ?? DEFAULT_SHIELD_API_BASE_URL
-    };
+    return { apiKey: envKey, baseUrl };
   }
   const config = await loadConfig();
   if (config !== null) {
-    return {
-      apiKey: config.apiKey,
-      baseUrl: opts.baseUrl ?? config.baseUrl
-    };
+    return { apiKey: config.apiKey, baseUrl };
   }
   process.stderr.write(
     "No API key found. Pass --api-key <key> or add it to ~/.multicorn/config.json.\n"
@@ -5290,26 +5381,40 @@ function startLocalProxyDetached(port, apiBaseUrl) {
   const logFile = join(PIDFILE_DIR, "proxy.log");
   const out = openSync(logFile, "a");
   const err = openSync(logFile, "a");
-  const child = spawn("npx", ["multicorn-proxy"], {
+  const { executable, args, env: proxyEnv } = buildLocalProxySpawnCommand(port, apiBaseUrl);
+  const child = spawn(executable, [...args], {
     stdio: ["ignore", out, err],
     detached: true,
     env: {
       ...process.env,
-      PORT: String(port),
-      HOST: "127.0.0.1",
-      SHIELD_API_BASE_URL: apiBaseUrl,
+      ...proxyEnv
       // SAFETY: blanket-allow for private targets is acceptable ONLY because
       // this is a local single-user proxy. The only registered target is the
       // filesystem server on the same machine. Do NOT copy this pattern to a
       // multi-tenant or hosted proxy deployment.
-      ALLOW_PRIVATE_TARGETS: "true"
     }
   });
   child.unref();
   return child;
 }
-async function ensureProxy(proxyPort, apiBaseUrl) {
-  if (await probeProxyHealth(proxyPort)) {
+async function ensureProxy(proxyPort, apiBaseUrl, options) {
+  const forceRespawn = options?.forceRespawn === true;
+  if (forceRespawn) {
+    const reg2 = readProxyRegistry();
+    if (reg2 !== null && reg2.port === proxyPort && isProcessAlive(reg2.pid)) {
+      killWithEscalation(reg2.pid, true);
+    }
+    if (reg2 !== null && reg2.port === proxyPort) {
+      try {
+        unlinkSync(PROXY_REGISTRY);
+      } catch {
+      }
+    }
+    for (let i = 0; i < 20; i++) {
+      if (!await isPortListening(proxyPort)) break;
+      await sleep3(100);
+    }
+  } else if (await probeProxyHealth(proxyPort)) {
     const reg2 = readProxyRegistry();
     const managed = reg2 !== null && reg2.port === proxyPort && isProcessAlive(reg2.pid);
     return { reused: true, managed };
@@ -5326,9 +5431,11 @@ async function ensureProxy(proxyPort, apiBaseUrl) {
       `A server is already running on port ${String(proxyPort)} but it's not a healthy Shield proxy. Stop it or re-run with --proxy-port <n>.`
     );
   }
+  const logFile = join(PIDFILE_DIR, "proxy.log");
   const child = startLocalProxyDetached(proxyPort, apiBaseUrl);
-  for (let i = 0; i < 30; i++) {
-    await sleep3(500);
+  for (let i = 0; i < LOCAL_PROXY_READY_MAX_POLLS; i++) {
+    await sleep3(LOCAL_PROXY_READY_POLL_MS);
+    if (child.exitCode !== null || child.signalCode !== null) break;
     if (await probeProxyHealth(proxyPort)) {
       if (child.pid !== void 0) {
         writeJsonFile(PROXY_REGISTRY, { pid: child.pid, port: proxyPort });
@@ -5340,9 +5447,8 @@ async function ensureProxy(proxyPort, apiBaseUrl) {
     if (child.pid !== void 0) killWithEscalation(child.pid, true);
   } catch {
   }
-  throw new Error(
-    `Could not start the local proxy on port ${String(proxyPort)}. Check the log at ${join(PIDFILE_DIR, "proxy.log")}.`
-  );
+  const childExited = child.exitCode !== null || child.signalCode !== null;
+  throw new Error(formatLocalProxyStartError(proxyPort, logFile, childExited, child.exitCode));
 }
 async function ensureFsServer(realDir, requestedPort) {
   const reg = readFsRegistry();
@@ -5545,8 +5651,9 @@ async function runStop(agent) {
     process.exit(1);
   }
   await withResourceLock(() => {
-    if (typeof data.supervisorPid === "number" && isProcessAlive(data.supervisorPid)) {
-      killWithEscalation(data.supervisorPid);
+    const supervisorPid = supervisorPidFromSession(data);
+    if (typeof supervisorPid === "number" && isProcessAlive(supervisorPid)) {
+      killWithEscalation(supervisorPid);
     }
     removePidfile(agent);
     releaseFsServerIfUnused(data.dir, agent);
@@ -5576,7 +5683,8 @@ Run it once with the folder: npx multicorn-shield files restart <dir> --agent ${
   await runDetached({
     ...opts,
     dir,
-    proxyPort: opts.proxyPort ?? existing?.proxyPort});
+    proxyPort: opts.proxyPort ?? existing?.proxyPort,
+    respawnProxy: true});
 }
 async function runDetached(opts) {
   const absDir = resolve(opts.dir);
@@ -5587,8 +5695,7 @@ async function runDetached(opts) {
   }
   const existing = readPidfile(opts.agent);
   if (existing !== null) {
-    const alive = typeof existing.supervisorPid === "number" && isProcessAlive(existing.supervisorPid);
-    if (alive) {
+    if (isAgentSessionRunning(existing)) {
       process.stderr.write(
         `Already running for agent "${opts.agent}" (fs :${String(existing.fsPort)}, proxy :${String(existing.proxyPort)}).
 Stop with: npx multicorn-shield files stop --agent ${opts.agent}
@@ -5603,6 +5710,7 @@ Stop with: npx multicorn-shield files stop --agent ${opts.agent}
   if (opts.proxyPort !== void 0) args.push("--proxy-port", String(opts.proxyPort));
   if (opts.apiKey !== void 0) args.push("--api-key", opts.apiKey);
   if (opts.baseUrl !== void 0) args.push("--base-url", opts.baseUrl);
+  if (opts.respawnProxy) args.push("--respawn-proxy");
   if (opts.client !== void 0) args.push("--client", opts.client);
   const scriptPath = process.argv[1] ?? resolve("dist/multicorn-shield.js");
   const logFile = join(PIDFILE_DIR, `files-${opts.agent}.log`);
@@ -5686,8 +5794,7 @@ async function runFilesCommand(opts) {
   const proxyPort = opts.proxyPort ?? DEFAULT_PROXY_PORT;
   const existingPidfile = readPidfile(opts.agent);
   if (existingPidfile !== null) {
-    const supervisorAlive = typeof existingPidfile.supervisorPid === "number" && isProcessAlive(existingPidfile.supervisorPid);
-    if (supervisorAlive) {
+    if (isAgentSessionRunning(existingPidfile)) {
       process.stderr.write(
         `A session for agent "${opts.agent}" is already running. Run 'files stop --agent ${opts.agent}' first, or use a different --agent name.
 `
@@ -5701,7 +5808,9 @@ async function runFilesCommand(opts) {
   let fsReused;
   try {
     const ensured = await withResourceLock(async () => {
-      const proxyRes = await ensureProxy(proxyPort, config.baseUrl);
+      const proxyRes = await ensureProxy(proxyPort, config.baseUrl, {
+        forceRespawn: opts.respawnProxy
+      });
       const fsRes = await ensureFsServer(realDir, opts.port);
       writePidfile({
         agent: opts.agent,
@@ -5968,6 +6077,8 @@ function parseArgs(argv) {
   let filesForeground = false;
   let filesStatus = false;
   let filesRestart = false;
+  let filesRespawnProxy = false;
+  let initIntegration = void 0;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "init") {
@@ -6018,6 +6129,8 @@ function parseArgs(argv) {
           filesStop = true;
         } else if (token === "--foreground") {
           filesForeground = true;
+        } else if (token === "--respawn-proxy") {
+          filesRespawnProxy = true;
         } else if (token === "--detach") ; else if (token === "stop") {
           filesStop = true;
         } else if (token === "status") {
@@ -6126,6 +6239,12 @@ function parseArgs(argv) {
       }
     } else if (arg === "--verbose" || arg === "--debug") {
       verbose = true;
+    } else if (arg === "--integration") {
+      const next = args[i + 1];
+      if (next === "native" || next === "hosted") {
+        initIntegration = next;
+        i++;
+      }
     }
   }
   return {
@@ -6139,6 +6258,7 @@ function parseArgs(argv) {
     deleteAgentName,
     apiKey,
     verbose,
+    initIntegration,
     filesDir,
     filesPort,
     filesProxyPort,
@@ -6146,7 +6266,8 @@ function parseArgs(argv) {
     filesClient,
     filesForeground,
     filesStatus,
-    filesRestart
+    filesRestart,
+    filesRespawnProxy
   };
 }
 function printHelp() {
@@ -6156,7 +6277,12 @@ function printHelp() {
       "",
       "Usage:",
       "  npx multicorn-shield init",
-      "      Interactive setup. Saves API key to ~/.multicorn/config.json.",
+      "      Interactive setup for native plugins (files, terminal, browser).",
+      "      Native: OpenClaw, Claude Code, Windsurf, Cline, Gemini CLI, OpenCode, Codex CLI.",
+      "      MCP-only clients (Cursor, Copilot, etc.): https://app.multicorn.ai/agents/new",
+      "      Saves API key to ~/.multicorn/config.json.",
+      "      --integration hosted  Use hosted MCP proxy for Windsurf, Cline, Gemini CLI,",
+      "                            OpenCode, or Codex CLI (default: native).",
       "",
       "  npx multicorn-shield files <dir> --agent <name> [--client <client>]",
       "      Share a local folder with a coding agent. Starts a filesystem MCP server",
@@ -6237,7 +6363,10 @@ async function runCli() {
     process.exit(0);
   }
   if (cli.subcommand === "init") {
-    await runInit(cli.baseUrl, { verbose: cli.verbose });
+    await runInit(cli.baseUrl, {
+      verbose: cli.verbose,
+      ...cli.initIntegration !== void 0 ? { integration: cli.initIntegration } : {}
+    });
     return;
   }
   if (cli.subcommand === "files") {
@@ -6253,7 +6382,8 @@ async function runCli() {
         client: void 0,
         foreground: true,
         status: true,
-        restart: false
+        restart: false,
+        respawnProxy: false
       });
       return;
     }
@@ -6278,7 +6408,8 @@ async function runCli() {
       client: cli.filesClient,
       foreground: cli.filesForeground,
       status: false,
-      restart: cli.filesRestart
+      restart: cli.filesRestart,
+      respawnProxy: cli.filesRespawnProxy
     });
     return;
   }