multicorn-shield 1.10.0 → 1.11.0

package/dist/multicorn-shield.js

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { readFileSync, existsSync, statSync } from 'fs';
-import { readFile, mkdir, writeFile, copyFile, chmod, unlink } from 'fs/promises';
+import { existsSync, readFileSync, mkdirSync, openSync, realpathSync, unlinkSync, writeFileSync, statSync, readdirSync } from 'fs';
+import { readFile, mkdir, writeFile, copyFile, chmod, rename, rm, unlink } from 'fs/promises';
 import { join, dirname, resolve, basename, sep } from 'path';
 import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 import { createRequire } from 'module';
 import { createInterface } from 'readline';
 import { parse, stringify } from 'yaml';
-import { spawn } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
 import 'stream';
+import { createConnection } from 'net';
 
 var MULTICORN_DIR = join(homedir(), ".multicorn");
 var SCOPES_PATH = join(MULTICORN_DIR, "scopes.json");
@@ -232,6 +233,7 @@ async function fetchGrantedScopes(agentId, apiKey, baseUrl) {
     if (perm.revoked_at !== null) continue;
     if (perm.read) scopes.push({ service: perm.service, permissionLevel: "read" });
     if (perm.write) scopes.push({ service: perm.service, permissionLevel: "write" });
+    if (perm.delete === true) scopes.push({ service: perm.service, permissionLevel: "delete" });
     if (perm.execute) scopes.push({ service: perm.service, permissionLevel: "execute" });
   }
   return scopes;
@@ -321,7 +323,7 @@ function detectScopeHints() {
   return [];
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function isApiSuccessResponse(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -1976,6 +1978,17 @@ async function warnIfApiKeyFileNotGitignored(workspaceRoot, relativePosixPath) {
     style.yellow("\u26A0") + " Config contains your API key. Add " + style.cyan(norm) + " to .gitignore to avoid committing credentials.\n"
   );
 }
+async function writeFileAtomic(filePath, body) {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${String(process.pid)}.${String(Date.now())}.tmp`;
+  try {
+    await writeFile(tmp, body, SECRET_JSON_FILE_OPTIONS);
+    await rename(tmp, filePath);
+  } catch (e) {
+    await rm(tmp, { force: true }).catch(() => void 0);
+    throw e;
+  }
+}
 async function mergeTopLevelKeyedJsonFile(filePath, topLevelKey, shortName, entry, options) {
   let root = {};
   try {
@@ -2000,21 +2013,25 @@ async function mergeTopLevelKeyedJsonFile(filePath, topLevelKey, shortName, entr
     }
   }
   const bucketRaw = root[topLevelKey];
-  const bucket = typeof bucketRaw === "object" && bucketRaw !== null && !Array.isArray(bucketRaw) ? { ...bucketRaw } : {};
-  if (options.onExisting === "skip" && bucket[shortName] !== void 0) {
+  const existingBucket = typeof bucketRaw === "object" && bucketRaw !== null && !Array.isArray(bucketRaw) ? bucketRaw : {};
+  if (options.onExisting === "skip" && existingBucket[shortName] !== void 0) {
     return "unchanged";
   }
+  const staleKeys = new Set((options.removeKeys ?? []).filter((k) => k !== shortName));
+  const bucket = Object.fromEntries(
+    Object.entries(existingBucket).filter(([k]) => !staleKeys.has(k))
+  );
   bucket[shortName] = entry;
   root[topLevelKey] = bucket;
-  await mkdir(dirname(filePath), { recursive: true });
-  await writeFile(filePath, JSON.stringify(root, null, 2) + "\n", SECRET_JSON_FILE_OPTIONS);
+  await writeFileAtomic(filePath, JSON.stringify(root, null, 2) + "\n");
   writeMcpAddedLine(shortName, filePath);
   return "ok";
 }
-async function mergeMcpServersObjectStyle(filePath, shortName, entry) {
+async function mergeMcpServersObjectStyle(filePath, shortName, entry, removeKeys) {
   const result = await mergeTopLevelKeyedJsonFile(filePath, "mcpServers", shortName, entry, {
     stripJsonComments: false,
-    onExisting: "overwrite"
+    onExisting: "overwrite",
+    removeKeys
   });
   return result === "parse-error" ? "parse-error" : "ok";
 }
@@ -2751,8 +2768,8 @@ async function runInit(explicitBaseUrl, options) {
     process.exit(1);
   }
   const rl = createInterface({ input: process.stdin, output: process.stderr });
-  const ask = (question) => new Promise((resolve2) => {
-    rl.question(question, resolve2);
+  const ask = (question) => new Promise((resolve3) => {
+    rl.question(question, resolve3);
   });
   process.stderr.write("\n" + BANNER + "\n");
   process.stderr.write(style.dim("Agent governance for the AI era") + "\n\n");
@@ -3782,11 +3799,311 @@ You have ${String(agentsForPlatform.length)} agent(s) connected for ${selectedLa
   }
   return lastConfig;
 }
+var CODING_CLIENTS = [
+  "cursor",
+  "cline",
+  "windsurf",
+  "claude",
+  "copilot",
+  "goose",
+  "gemini",
+  "codex",
+  "continue",
+  "kilo",
+  "opencode"
+];
+var CLIENT_DISPLAY_NAMES = {
+  cursor: "Cursor",
+  cline: "Cline",
+  windsurf: "Windsurf",
+  claude: "Claude Desktop",
+  copilot: "GitHub Copilot",
+  goose: "Goose",
+  gemini: "Gemini CLI",
+  codex: "Codex CLI",
+  continue: "Continue",
+  kilo: "Kilo Code",
+  opencode: "OpenCode"
+};
+var CLIENT_RELOAD_INSTRUCTIONS = {
+  cursor: "Restart Cursor or reload the window to pick up the new server.",
+  cline: "Cline picks up config changes automatically.",
+  windsurf: "Restart Windsurf to pick up the new server.",
+  claude: "Restart Claude Desktop to pick up the new server.",
+  copilot: "Reload the VS Code window (Cmd+Shift+P > Reload Window).",
+  goose: "Restart Goose to pick up the new extension.",
+  gemini: "Restart Gemini CLI to pick up the new server.",
+  codex: "Restart Codex CLI to pick up the new server.",
+  continue: "Continue picks up config changes automatically.",
+  kilo: "Kilo Code picks up config changes automatically.",
+  opencode: "Restart OpenCode to pick up the new server."
+};
+function clientDisplayName(client) {
+  return CLIENT_DISPLAY_NAMES[client];
+}
+function clientReloadInstruction(client) {
+  return CLIENT_RELOAD_INSTRUCTIONS[client];
+}
+function clientConfigPath(client, workspacePath) {
+  switch (client) {
+    case "cursor":
+      return getCursorMcpJsonPath();
+    case "cline":
+      return getClineMcpSettingsPath();
+    case "windsurf":
+      return getWindsurfMcpConfigPath();
+    case "claude":
+      return getClaudeDesktopConfigPath();
+    case "goose":
+      return join(homedir(), ".config", "goose", "config.yaml");
+    case "gemini":
+      return join(homedir(), ".gemini", "settings.json");
+    case "codex":
+      return join(homedir(), ".codex", "config.toml");
+    case "copilot":
+      return join(workspacePath ?? ".", ".vscode", "mcp.json");
+    case "continue":
+      return join(workspacePath ?? ".", ".continue", "mcpServers");
+    case "kilo":
+      return join(workspacePath ?? ".", ".kilo", "kilo.jsonc");
+    case "opencode":
+      return join(workspacePath ?? ".", "opencode.json");
+  }
+}
+function detectInstalledClients() {
+  const found = [];
+  const homeClients = [
+    "cursor",
+    "cline",
+    "windsurf",
+    "claude",
+    "goose",
+    "gemini",
+    "codex"
+  ];
+  for (const client of homeClients) {
+    const p = clientConfigPath(client);
+    if (existsSync(p)) {
+      found.push(client);
+    } else {
+      const dir = dirname(p);
+      if (existsSync(dir)) {
+        found.push(client);
+      }
+    }
+  }
+  return found;
+}
+var CODING_CLIENT_TO_PLATFORM = {
+  cursor: "cursor",
+  cline: "cline",
+  windsurf: "windsurf",
+  claude: "claude-desktop",
+  copilot: "github-copilot",
+  goose: "goose",
+  gemini: "gemini-cli",
+  codex: "codex-cli",
+  continue: "continue-dev",
+  kilo: "kilo-code",
+  opencode: "opencode"
+};
+async function writeLocalMcpEntry(client, agentName, localProxyUrl, apiKey, workspacePath) {
+  const filePath = clientConfigPath(client, workspacePath);
+  const entryKey = agentName;
+  const legacyKeys = [`${agentName}-files`];
+  if (apiKey.trim().length === 0) {
+    process.stderr.write(
+      style.yellow("\u26A0") + ` Refusing to write MCP config for "${agentName}": missing API key. Left the config file unchanged.
+`
+    );
+    return null;
+  }
+  const authHeader = `Bearer ${apiKey}`;
+  const url = shouldEmbedKeyInHostedProxyUrl(CODING_CLIENT_TO_PLATFORM[client]) ? hostedProxyUrlWithKeyParam(localProxyUrl, apiKey) : localProxyUrl;
+  switch (client) {
+    case "cursor":
+      return await mergeMcpServersObjectStyle(
+        filePath,
+        entryKey,
+        {
+          url,
+          headers: { Authorization: authHeader }
+        },
+        legacyKeys
+      ) === "ok" ? filePath : null;
+    case "cline":
+      return await mergeMcpServersObjectStyle(
+        filePath,
+        entryKey,
+        {
+          url
+        },
+        legacyKeys
+      ) === "ok" ? filePath : null;
+    case "windsurf":
+      return await mergeMcpServersObjectStyle(
+        filePath,
+        entryKey,
+        {
+          serverUrl: url,
+          headers: { Authorization: authHeader }
+        },
+        legacyKeys
+      ) === "ok" ? filePath : null;
+    case "claude":
+      return await mergeMcpServersObjectStyle(
+        filePath,
+        entryKey,
+        {
+          url,
+          headers: { Authorization: authHeader }
+        },
+        legacyKeys
+      ) === "ok" ? filePath : null;
+    case "gemini": {
+      return await mergeMcpServersObjectStyle(
+        filePath,
+        entryKey,
+        {
+          httpUrl: url,
+          headers: { Authorization: authHeader }
+        },
+        legacyKeys
+      ) === "ok" ? filePath : null;
+    }
+    case "copilot": {
+      const result = await mergeTopLevelKeyedJsonFile(
+        filePath,
+        "servers",
+        entryKey,
+        { type: "http", url, headers: { Authorization: authHeader } },
+        { stripJsonComments: false, onExisting: "overwrite", removeKeys: legacyKeys }
+      );
+      return result === "ok" ? filePath : null;
+    }
+    case "goose": {
+      const goosePath = filePath;
+      let content = "";
+      try {
+        content = await readFile(goosePath, "utf8");
+      } catch (e) {
+        if (isErrnoException(e) && e.code === "ENOENT") {
+          content = "";
+        } else {
+          return null;
+        }
+      }
+      let root;
+      try {
+        const data = content.trim().length === 0 ? {} : parse(content);
+        if (data === null || typeof data !== "object" || Array.isArray(data)) return null;
+        root = data;
+      } catch {
+        return null;
+      }
+      const extensionsRaw = root["extensions"];
+      let extensions;
+      if (isYamlPlainObject(extensionsRaw)) {
+        extensions = { ...extensionsRaw };
+      } else if (extensionsRaw === void 0) {
+        extensions = {};
+      } else {
+        return null;
+      }
+      extensions[entryKey] = {
+        enabled: true,
+        type: "streamable_http",
+        name: entryKey,
+        description: "",
+        uri: url,
+        envs: {},
+        env_keys: [],
+        headers: { Authorization: authHeader },
+        timeout: 300,
+        socket: null,
+        bundled: null,
+        available_tools: []
+      };
+      root["extensions"] = extensions;
+      const out = stringify(root, { indent: 2, lineWidth: 0 });
+      const body = out.endsWith("\n") ? out : `${out}
+`;
+      await mkdir(dirname(goosePath), { recursive: true });
+      await writeFile(goosePath, body, SECRET_JSON_FILE_OPTIONS);
+      return goosePath;
+    }
+    case "codex": {
+      const codexPath = filePath;
+      let existing = "";
+      try {
+        existing = await readFile(codexPath, "utf8");
+      } catch (e) {
+        if (isErrnoException(e) && e.code === "ENOENT") {
+          existing = "";
+        } else {
+          return null;
+        }
+      }
+      const sectionHeader = `[mcp_servers.${entryKey}]`;
+      const sectionBlock = `${sectionHeader}
+type = "http"
+url = "${url}"
+
+[mcp_servers.${entryKey}.http_headers]
+Authorization = "${authHeader}"
+`;
+      if (existing.includes(sectionHeader)) {
+        const idx = existing.indexOf(sectionHeader);
+        const nextSection = existing.indexOf("\n[", idx + sectionHeader.length);
+        const before = existing.slice(0, idx);
+        const after = nextSection >= 0 ? existing.slice(nextSection + 1) : "";
+        existing = before + sectionBlock + (after.length > 0 ? "\n" + after : "");
+      } else {
+        existing = existing.trimEnd() + "\n\n" + sectionBlock;
+      }
+      await mkdir(dirname(codexPath), { recursive: true });
+      await writeFile(codexPath, existing, SECRET_JSON_FILE_OPTIONS);
+      return codexPath;
+    }
+    case "continue": {
+      const dir = join(workspacePath ?? ".", ".continue", "mcpServers");
+      const continuePath = join(dir, `${entryKey}.yaml`);
+      const yamlContent = stringify(
+        { name: entryKey, type: "streamableHttp", url },
+        { indent: 2, lineWidth: 0 }
+      );
+      await mkdir(dir, { recursive: true });
+      await writeFile(continuePath, yamlContent, SECRET_JSON_FILE_OPTIONS);
+      return continuePath;
+    }
+    case "kilo": {
+      const result = await mergeTopLevelKeyedJsonFile(
+        filePath,
+        "mcp",
+        entryKey,
+        { url, headers: { Authorization: authHeader } },
+        { stripJsonComments: true, onExisting: "overwrite", removeKeys: legacyKeys }
+      );
+      return result === "ok" ? filePath : null;
+    }
+    case "opencode": {
+      const result = await mergeTopLevelKeyedJsonFile(
+        filePath,
+        "mcp",
+        entryKey,
+        { type: "streamablehttp", url, headers: { Authorization: authHeader } },
+        { stripJsonComments: false, onExisting: "overwrite", removeKeys: legacyKeys }
+      );
+      return result === "ok" ? filePath : null;
+    }
+  }
+}
 
 // src/types/index.ts
 var PERMISSION_LEVELS = {
   Read: "read",
   Write: "write",
+  Delete: "delete",
   Execute: "execute",
   Publish: "publish",
   Create: "create"
@@ -3996,7 +4313,7 @@ function createActionLogger(config) {
   };
 }
 function sleep2(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 
 // src/spending/spending-checker.ts
@@ -4554,9 +4871,9 @@ function createProxyServer(config) {
       timer.unref();
     }
     config.logger.info("Proxy ready.", { agent: config.agentName });
-    return new Promise((resolve2) => {
+    return new Promise((resolve3) => {
       childProcess.on("exit", () => {
-        resolve2();
+        resolve3();
       });
     });
   }
@@ -4668,195 +4985,1253 @@ async function restoreClaudeDesktopMcpFromBackup() {
 
 // package.json
 var package_default = {
-  version: "1.10.0"};
+  version: "1.11.0"};
 
 // src/package-meta.ts
 var PACKAGE_VERSION = package_default.version;
-
-// bin/multicorn-shield.ts
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  let subcommand = "help";
-  let wrapCommand = "";
-  let wrapArgs = [];
-  let logLevel = "info";
-  let baseUrl = void 0;
-  let dashboardUrl = "";
-  let agentName = "";
-  let deleteAgentName = "";
-  let apiKey = void 0;
-  let verbose = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "init") {
-      subcommand = "init";
-    } else if (arg === "agents") {
-      subcommand = "agents";
-    } else if (arg === "delete-agent") {
-      subcommand = "delete-agent";
-      const name = args[i + 1];
-      if (name === void 0 || name.startsWith("-")) {
-        process.stderr.write("Error: delete-agent requires an agent name.\n");
-        process.stderr.write("Example: npx multicorn-shield delete-agent my-agent\n");
-        process.exit(1);
-      }
-      deleteAgentName = name;
-      i++;
-    } else if (arg === "--wrap") {
-      subcommand = "wrap";
-      const tail = args.slice(i + 1);
-      const remaining = [];
-      for (let j = 0; j < tail.length; j++) {
-        const token = tail[j];
-        if (token === void 0) continue;
-        if (remaining.length > 0) {
-          remaining.push(token);
-          continue;
-        }
-        if (token === "--agent-name") {
-          const value = tail[j + 1];
-          if (value !== void 0) {
-            agentName = value;
-            j++;
-          }
-        } else if (token === "--log-level") {
-          const value = tail[j + 1];
-          if (value !== void 0 && isValidLogLevel(value)) {
-            logLevel = value;
-            j++;
-          }
-        } else if (token === "--base-url") {
-          const value = tail[j + 1];
-          if (value !== void 0) {
-            baseUrl = value;
-            j++;
-          }
-        } else if (token === "--dashboard-url") {
-          const value = tail[j + 1];
-          if (value !== void 0) {
-            dashboardUrl = value;
-            j++;
-          }
-        } else if (token === "--api-key") {
-          const value = tail[j + 1];
-          if (value !== void 0) {
-            apiKey = value;
-            j++;
-          }
-        } else {
-          remaining.push(token);
-        }
-      }
-      if (remaining.length === 0) {
-        process.stderr.write("Error: --wrap requires a command to run.\n");
-        process.stderr.write("Example: npx multicorn-shield --wrap my-mcp-server\n");
-        process.exit(1);
-      }
-      wrapCommand = remaining[0] ?? "";
-      wrapArgs = remaining.slice(1);
-      break;
-    } else if (arg === "--log-level") {
-      const next = args[i + 1];
-      if (next !== void 0 && isValidLogLevel(next)) {
-        logLevel = next;
-        i++;
-      }
-    } else if (arg === "--base-url") {
-      const next = args[i + 1];
-      if (next !== void 0) {
-        baseUrl = next;
-        i++;
-      }
-    } else if (arg === "--dashboard-url") {
-      const next = args[i + 1];
-      if (next !== void 0) {
-        dashboardUrl = next;
-        i++;
-      }
-    } else if (arg === "--agent-name") {
-      const next = args[i + 1];
-      if (next !== void 0) {
-        agentName = next;
-        i++;
-      }
-    } else if (arg === "--api-key") {
-      const next = args[i + 1];
-      if (next !== void 0) {
-        apiKey = next;
-        i++;
-      }
-    } else if (arg === "--verbose" || arg === "--debug") {
-      verbose = true;
-    }
-  }
-  return {
-    subcommand,
-    wrapCommand,
-    wrapArgs,
-    logLevel,
-    baseUrl,
-    dashboardUrl,
-    agentName,
-    deleteAgentName,
-    apiKey,
-    verbose
-  };
+var DEFAULT_FS_PORT = 3005;
+var DEFAULT_PROXY_PORT = 3001;
+var PIDFILE_DIR = process.env["MULTICORN_HOME"] ?? join(homedir(), ".multicorn");
+var PROXY_REGISTRY = join(PIDFILE_DIR, "proxy.json");
+var FS_REGISTRY = join(PIDFILE_DIR, "fs-servers.json");
+var LOCK_PATH = join(PIDFILE_DIR, ".resources.lock");
+var LOCK_WAIT_MS = 6e4;
+var LOCK_STALE_MS = 12e4;
+var FS_PORT_SCAN_RANGE = 200;
+var style2 = {
+  green: (s) => `\x1B[38;2;34;197;94m${s}\x1B[0m`,
+  cyan: (s) => `\x1B[38;2;6;182;212m${s}\x1B[0m`,
+  dim: (s) => `\x1B[2m${s}\x1B[0m`,
+  bold: (s) => `\x1B[1m${s}\x1B[0m`
+};
+function pidfilePath(agent) {
+  return join(PIDFILE_DIR, `files-${agent}.pid`);
 }
-function printHelp() {
-  process.stderr.write(
-    [
-      "multicorn-shield: MCP permission proxy and Shield setup",
-      "",
-      "Usage:",
-      "  npx multicorn-shield init",
-      "      Interactive setup. Saves API key to ~/.multicorn/config.json.",
-      "",
-      "  npx multicorn-shield restore",
-      "      Restore MCP servers in claude_desktop_config.json from the Shield extension backup.",
-      "",
-      "  npx multicorn-shield agents",
-      "      List configured agents and show which is the default.",
-      "",
-      "  npx multicorn-shield delete-agent <name>",
-      "      Remove a saved agent.",
-      "",
-      "  npx multicorn-shield --wrap <command> [args...]",
-      "      Start <command> as an MCP server and proxy all tool calls through",
-      "      Shield's permission layer.",
-      "",
-      "Options:",
-      "  --version, -v        Print version and exit",
-      "  --verbose, --debug   Print extra diagnostics during init (menu selection, agent counts)",
-      "  --api-key <key>       Multicorn API key (overrides MULTICORN_API_KEY env var and config file)",
-      "  --log-level <level>   Log level: debug | info | warn | error  (default: info)",
-      "  --base-url <url>      Multicorn API base URL  (default: https://api.multicorn.ai)",
-      "  --dashboard-url <url> Dashboard URL for consent page  (default: derived from --base-url)",
-      "  --agent-name <name>   Override agent name derived from the wrapped command",
-      "",
-      "Examples:",
-      "  npx multicorn-shield init",
-      "  npx multicorn-shield --wrap npx @modelcontextprotocol/server-filesystem /tmp",
-      "  npx multicorn-shield --wrap my-mcp-server --log-level debug",
-      ""
-    ].join("\n")
-  );
+function writePidfile(data) {
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  writeFileSync(pidfilePath(data.agent), JSON.stringify(data), {
+    encoding: "utf8",
+    mode: 384
+  });
 }
-async function runCli() {
-  const first = process.argv[2];
-  if (first === "restore") {
-    await restoreClaudeDesktopMcpFromBackup();
-    process.stderr.write(
-      "Restored MCP server entries from ~/.multicorn/extension-backup.json into Claude Desktop config.\nRestart Claude Desktop to apply changes.\n"
-    );
-    return;
+function readPidfile(agent) {
+  const p = pidfilePath(agent);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
   }
-  if (first === "--version" || first === "-v") {
-    process.stdout.write(`${PACKAGE_VERSION}
-`);
-    process.exit(0);
+}
+function removePidfile(agent) {
+  const p = pidfilePath(agent);
+  try {
+    unlinkSync(p);
+  } catch {
   }
-  const cli = parseArgs(process.argv);
-  const logger = createLogger(cli.logLevel);
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listAllPidfiles() {
+  if (!existsSync(PIDFILE_DIR)) return [];
+  const files = readdirSync(PIDFILE_DIR).filter(
+    (f) => f.startsWith("files-") && f.endsWith(".pid")
+  );
+  const results = [];
+  for (const f of files) {
+    try {
+      const data = JSON.parse(readFileSync(join(PIDFILE_DIR, f), "utf8"));
+      results.push(data);
+    } catch {
+    }
+  }
+  return results;
+}
+function runStatus() {
+  const sessions = listAllPidfiles();
+  if (sessions.length === 0) {
+    process.stderr.write("No active file-sharing sessions.\n");
+    return;
+  }
+  const proxyReg = readProxyRegistry();
+  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 fsEntry = fsReg[s.dir];
+    const fsAlive = fsEntry !== void 0 && isProcessAlive(fsEntry.pid);
+    const proxyAlive = proxyReg !== null && proxyReg.port === s.proxyPort && isProcessAlive(proxyReg.pid);
+    const agentStatus = supervisorAlive ? style2.green("running") : style2.dim("stopped");
+    process.stderr.write(`  ${style2.bold(s.agent)} ${agentStatus}
+`);
+    process.stderr.write(`    Folder: ${s.dir || "(unknown)"}
+`);
+    process.stderr.write(
+      `    FS server: :${String(s.fsPort)} ${fsAlive ? style2.green("running") : style2.dim("stopped")}
+`
+    );
+    process.stderr.write(
+      `    Proxy: :${String(s.proxyPort)} ${proxyAlive ? style2.green("running") : style2.dim("stopped")}
+`
+    );
+    process.stderr.write("\n");
+    if (!supervisorAlive) {
+      removePidfile(s.agent);
+      process.stderr.write(style2.dim(`    (cleaned up stale pidfile)
+
+`));
+    }
+  }
+}
+async function isPortListening(port) {
+  return new Promise((resolve3) => {
+    const sock = createConnection({ port, host: "127.0.0.1" });
+    sock.once("connect", () => {
+      sock.destroy();
+      resolve3(true);
+    });
+    sock.once("error", () => {
+      sock.destroy();
+      resolve3(false);
+    });
+  });
+}
+async function probeProxyHealth(port) {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${String(port)}/health`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+async function readProxyVersion(port) {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${String(port)}/health`, {
+      signal: AbortSignal.timeout(2e3)
+    });
+    if (!resp.ok) return null;
+    const body = await resp.json();
+    return typeof body.version === "string" && body.version.length > 0 ? body.version : null;
+  } catch {
+    return null;
+  }
+}
+function sleep3(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function readJsonFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeJsonFile(path, data) {
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(data), { encoding: "utf8", mode: 384 });
+}
+function readProxyRegistry() {
+  return readJsonFile(PROXY_REGISTRY);
+}
+function readFsRegistry() {
+  return readJsonFile(FS_REGISTRY) ?? {};
+}
+function canonicalFolder(dir) {
+  const abs = resolve(dir);
+  try {
+    return realpathSync(abs);
+  } catch {
+    return abs;
+  }
+}
+function readLock() {
+  return readJsonFile(LOCK_PATH);
+}
+function isLockStale(holder, now = Date.now()) {
+  if (holder === null) return true;
+  if (!isProcessAlive(holder.pid)) return true;
+  return now - holder.ts > LOCK_STALE_MS;
+}
+async function acquireResourceLock() {
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (; ; ) {
+    try {
+      writeFileSync(LOCK_PATH, JSON.stringify({ pid: process.pid, ts: Date.now() }), {
+        encoding: "utf8",
+        mode: 384,
+        flag: "wx"
+      });
+      return;
+    } catch {
+      const holder = readLock();
+      if (isLockStale(holder)) {
+        try {
+          unlinkSync(LOCK_PATH);
+        } catch {
+        }
+        continue;
+      }
+      if (Date.now() > deadline) {
+        try {
+          unlinkSync(LOCK_PATH);
+        } catch {
+        }
+        continue;
+      }
+      await sleep3(100);
+    }
+  }
+}
+function releaseResourceLock() {
+  const holder = readLock();
+  if (holder !== null && holder.pid === process.pid) {
+    try {
+      unlinkSync(LOCK_PATH);
+    } catch {
+    }
+  }
+}
+async function withResourceLock(fn) {
+  await acquireResourceLock();
+  try {
+    return await fn();
+  } finally {
+    releaseResourceLock();
+  }
+}
+function liveAgents() {
+  return listAllPidfiles().filter(
+    (p) => typeof p.supervisorPid === "number" && isProcessAlive(p.supervisorPid)
+  );
+}
+function agentsReferencingProxy(proxyPort, agents, excludeAgent) {
+  return agents.filter((a) => a.agent !== excludeAgent && a.proxyPort === proxyPort);
+}
+function agentsReferencingFolder(folder, agents, excludeAgent) {
+  return agents.filter((a) => a.agent !== excludeAgent && a.dir === folder);
+}
+async function nextFreePort(start, claimed, isBusy, range = FS_PORT_SCAN_RANGE) {
+  for (let port = start; port < start + range; port++) {
+    if (claimed.has(port)) continue;
+    if (await isBusy(port)) continue;
+    return port;
+  }
+  throw new Error(
+    `No free port for the filesystem server in range ${String(start)}-${String(start + range)}.`
+  );
+}
+async function resolveConfig(opts) {
+  const fromFlag = opts.apiKey;
+  if (fromFlag && fromFlag.length > 0) {
+    return {
+      apiKey: fromFlag,
+      baseUrl: opts.baseUrl ?? DEFAULT_SHIELD_API_BASE_URL
+    };
+  }
+  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
+    };
+  }
+  const config = await loadConfig();
+  if (config !== null) {
+    return {
+      apiKey: config.apiKey,
+      baseUrl: opts.baseUrl ?? config.baseUrl
+    };
+  }
+  process.stderr.write(
+    "No API key found. Pass --api-key <key> or add it to ~/.multicorn/config.json.\n"
+  );
+  process.exit(1);
+}
+function startFsServerDetached(realDir, port) {
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  const logFile = join(PIDFILE_DIR, `fs-${String(port)}.log`);
+  const out = openSync(logFile, "a");
+  const err = openSync(logFile, "a");
+  const child = spawn(
+    "npx",
+    [
+      "supergateway",
+      // Serve the child over streamable HTTP at /mcp. Without this, supergateway
+      // defaults to SSE (/sse + /message), but the proxy registers the target as
+      // /mcp - the mismatch makes every request 404 with "Cannot POST /mcp".
+      "--outputTransport",
+      "streamableHttp",
+      "--stdio",
+      `npx @modelcontextprotocol/server-filesystem ${realDir}`,
+      "--port",
+      String(port)
+    ],
+    {
+      stdio: ["ignore", out, err],
+      detached: true,
+      env: { ...process.env }
+    }
+  );
+  child.unref();
+  return child;
+}
+function startLocalProxyDetached(port, apiBaseUrl) {
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  const logFile = join(PIDFILE_DIR, "proxy.log");
+  const out = openSync(logFile, "a");
+  const err = openSync(logFile, "a");
+  const child = spawn("npx", ["multicorn-proxy"], {
+    stdio: ["ignore", out, err],
+    detached: true,
+    env: {
+      ...process.env,
+      PORT: String(port),
+      HOST: "127.0.0.1",
+      SHIELD_API_BASE_URL: apiBaseUrl,
+      // 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)) {
+    const reg2 = readProxyRegistry();
+    const managed = reg2 !== null && reg2.port === proxyPort && isProcessAlive(reg2.pid);
+    return { reused: true, managed };
+  }
+  const reg = readProxyRegistry();
+  if (reg !== null && !isProcessAlive(reg.pid)) {
+    try {
+      unlinkSync(PROXY_REGISTRY);
+    } catch {
+    }
+  }
+  if (await isPortListening(proxyPort)) {
+    throw new Error(
+      `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 child = startLocalProxyDetached(proxyPort, apiBaseUrl);
+  for (let i = 0; i < 30; i++) {
+    await sleep3(500);
+    if (await probeProxyHealth(proxyPort)) {
+      if (child.pid !== void 0) {
+        writeJsonFile(PROXY_REGISTRY, { pid: child.pid, port: proxyPort });
+      }
+      return { reused: false, managed: true };
+    }
+  }
+  try {
+    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")}.`
+  );
+}
+async function ensureFsServer(realDir, requestedPort) {
+  const reg = readFsRegistry();
+  const existing = reg[realDir];
+  if (existing !== void 0 && isProcessAlive(existing.pid) && await isPortListening(existing.port)) {
+    return { port: existing.port, reused: true };
+  }
+  if (existing !== void 0) {
+    const rest = Object.fromEntries(Object.entries(reg).filter(([k]) => k !== realDir));
+    writeJsonFile(FS_REGISTRY, rest);
+  }
+  let port;
+  if (requestedPort !== void 0) {
+    if (await isPortListening(requestedPort)) {
+      throw new Error(
+        `A server is already running on port ${String(requestedPort)}. Re-run without --port to auto-pick a free port, or choose another.`
+      );
+    }
+    port = requestedPort;
+  } else {
+    const claimed = new Set(Object.values(readFsRegistry()).map((e) => e.port));
+    port = await nextFreePort(DEFAULT_FS_PORT, claimed, isPortListening);
+  }
+  const child = startFsServerDetached(realDir, port);
+  let ready = false;
+  for (let i = 0; i < 20; i++) {
+    await sleep3(500);
+    if (await isPortListening(port)) {
+      ready = true;
+      break;
+    }
+  }
+  if (!ready) {
+    try {
+      if (child.pid !== void 0) killWithEscalation(child.pid, true);
+    } catch {
+    }
+    throw new Error(
+      `Filesystem server failed to start on port ${String(port)}. Check the directory path and the log at ${join(PIDFILE_DIR, `fs-${String(port)}.log`)}.`
+    );
+  }
+  if (child.pid !== void 0) {
+    const next = readFsRegistry();
+    next[realDir] = { pid: child.pid, port };
+    writeJsonFile(FS_REGISTRY, next);
+  }
+  return { port, reused: false };
+}
+function releaseProxyIfUnused(proxyPort, stoppingAgent) {
+  const remaining = agentsReferencingProxy(proxyPort, liveAgents(), stoppingAgent);
+  if (remaining.length > 0) return;
+  const reg = readProxyRegistry();
+  if (reg !== null && reg.port === proxyPort && isProcessAlive(reg.pid)) {
+    killWithEscalation(reg.pid, true);
+  }
+  if (reg !== null && reg.port === proxyPort) {
+    try {
+      unlinkSync(PROXY_REGISTRY);
+    } catch {
+    }
+  }
+}
+function releaseFsServerIfUnused(folder, stoppingAgent) {
+  const remaining = agentsReferencingFolder(folder, liveAgents(), stoppingAgent);
+  if (remaining.length > 0) return;
+  const reg = readFsRegistry();
+  const entry = reg[folder];
+  if (entry === void 0) return;
+  if (isProcessAlive(entry.pid)) {
+    killWithEscalation(entry.pid, true);
+  }
+  const rest = Object.fromEntries(Object.entries(reg).filter(([k]) => k !== folder));
+  writeJsonFile(FS_REGISTRY, rest);
+}
+function proxyServerSlug(agentLabel) {
+  const t = agentLabel.trim().toLowerCase();
+  const slug = t.replace(/[^a-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+  if (slug === "") return "shield-handoff-agent";
+  if (!/^[a-z0-9]/i.test(slug)) return `a-${slug}`;
+  return slug.slice(0, 180);
+}
+async function registerAgentAndConfig(apiKey, baseUrl, agentName, fsPort, localDir) {
+  const targetUrl = `http://127.0.0.1:${String(fsPort)}/mcp`;
+  const serverName = proxyServerSlug(agentName);
+  const response = await fetch(`${baseUrl}/api/v1/proxy/config`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Multicorn-Key": apiKey
+    },
+    body: JSON.stringify({
+      server_name: serverName,
+      target_url: targetUrl,
+      platform: "other-mcp",
+      agent_name: agentName,
+      local_dir: localDir
+    }),
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!response.ok) {
+    let detail = `HTTP ${String(response.status)}`;
+    try {
+      const body = await response.json();
+      const errObj = body["error"];
+      if (typeof errObj?.["message"] === "string") detail = errObj["message"];
+      else if (typeof body["message"] === "string") detail = body["message"];
+    } catch {
+    }
+    throw new Error(`Failed to register agent: ${detail}`);
+  }
+  const envelope = await response.json();
+  const data = envelope["data"];
+  const proxyUrl = typeof data?.["proxy_url"] === "string" ? data["proxy_url"] : "";
+  if (proxyUrl.length === 0) {
+    throw new Error("Registration succeeded but no proxy URL was returned.");
+  }
+  let pathSegment = "";
+  try {
+    const parsed = new URL(proxyUrl);
+    pathSegment = parsed.pathname + parsed.search;
+  } catch {
+    pathSegment = proxyUrl;
+  }
+  await grantScope(apiKey, baseUrl, agentName, "filesystem", "read");
+  return { proxyUrl, pathSegment };
+}
+var HEARTBEAT_INTERVAL_MS = 3e4;
+async function sendHeartbeat(apiKey, baseUrl, serverName, proxyVersion) {
+  try {
+    await fetch(`${baseUrl}/api/v1/proxy/heartbeat`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Multicorn-Key": apiKey
+      },
+      // proxy_version lets the backend stamp the agent's last-seen version + timestamp
+      // from the heartbeat, so the dashboard can flag an out-of-date proxy that needs a
+      // restart even if the editor never connects through it.
+      body: JSON.stringify(
+        proxyVersion !== null ? { server_name: serverName, proxy_version: proxyVersion } : { server_name: serverName }
+      ),
+      signal: AbortSignal.timeout(8e3)
+    });
+  } catch {
+  }
+}
+async function grantScope(apiKey, baseUrl, agentName, service, level) {
+  const agentsResp = await fetch(`${baseUrl}/api/v1/agents`, {
+    headers: { "X-Multicorn-Key": apiKey },
+    signal: AbortSignal.timeout(8e3)
+  });
+  if (!agentsResp.ok) return;
+  const agentsBody = await agentsResp.json();
+  const agentsList = agentsBody["data"];
+  if (!Array.isArray(agentsList)) return;
+  const agent = agentsList.find((a) => a["name"] === agentName);
+  if (!agent || typeof agent["id"] !== "string") return;
+  const agentId = agent["id"];
+  await fetch(`${baseUrl}/api/v1/agents/${agentId}/scopes`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Multicorn-Key": apiKey
+    },
+    body: JSON.stringify({ service, permission_level: level }),
+    signal: AbortSignal.timeout(8e3)
+  });
+}
+function killWithEscalation(pid, group = false) {
+  const signal = (sig) => {
+    if (group) {
+      try {
+        process.kill(-pid, sig);
+        return;
+      } catch {
+      }
+    }
+    process.kill(pid, sig);
+  };
+  try {
+    signal("SIGTERM");
+  } catch {
+    return;
+  }
+  const deadline = Date.now() + 3e3;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return;
+    spawnSync("sleep", ["0.1"], { stdio: "ignore" });
+  }
+  try {
+    signal("SIGKILL");
+  } catch {
+  }
+}
+async function runStop(agent) {
+  const data = readPidfile(agent);
+  if (data === null) {
+    process.stderr.write(`No running session found for agent "${agent}".
+`);
+    process.exit(1);
+  }
+  await withResourceLock(() => {
+    if (typeof data.supervisorPid === "number" && isProcessAlive(data.supervisorPid)) {
+      killWithEscalation(data.supervisorPid);
+    }
+    removePidfile(agent);
+    releaseFsServerIfUnused(data.dir, agent);
+    releaseProxyIfUnused(data.proxyPort, agent);
+  });
+  process.stderr.write(`Stopped agent "${agent}".
+`);
+}
+async function runRestart(opts) {
+  if (opts.agent.length === 0) {
+    process.stderr.write("Error: --agent <name> is required for restart.\n");
+    process.exit(1);
+  }
+  const existing = readPidfile(opts.agent);
+  const dir = opts.dir.length > 0 ? opts.dir : existing?.dir ?? "";
+  if (dir.length === 0) {
+    process.stderr.write(
+      `Don't know which folder to restart agent "${opts.agent}" with.
+Run it once with the folder: npx multicorn-shield files restart <dir> --agent ${opts.agent}
+`
+    );
+    process.exit(1);
+  }
+  if (existing !== null) {
+    await runStop(opts.agent);
+  }
+  await runDetached({
+    ...opts,
+    dir,
+    proxyPort: opts.proxyPort ?? existing?.proxyPort});
+}
+async function runDetached(opts) {
+  const absDir = resolve(opts.dir);
+  if (!existsSync(absDir)) {
+    process.stderr.write(`Directory not found: ${opts.dir}. Check the path and try again.
+`);
+    process.exit(1);
+  }
+  const existing = readPidfile(opts.agent);
+  if (existing !== null) {
+    const alive = typeof existing.supervisorPid === "number" && isProcessAlive(existing.supervisorPid);
+    if (alive) {
+      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}
+`
+      );
+      return;
+    }
+    removePidfile(opts.agent);
+  }
+  const args = ["files", absDir, "--agent", opts.agent, "--foreground"];
+  if (opts.port !== void 0) args.push("--port", String(opts.port));
+  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.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`);
+  mkdirSync(PIDFILE_DIR, { recursive: true, mode: 448 });
+  const out = openSync(logFile, "a");
+  const err = openSync(logFile, "a");
+  const child = spawn(process.execPath, [scriptPath, ...args], {
+    detached: true,
+    stdio: ["ignore", out, err],
+    env: { ...process.env }
+  });
+  child.unref();
+  let pidData = null;
+  for (let i = 0; i < 60; i++) {
+    await sleep3(500);
+    pidData = readPidfile(opts.agent);
+    if (pidData !== null) break;
+    if (child.pid !== void 0 && !isProcessAlive(child.pid)) break;
+  }
+  if (pidData === null) {
+    process.stderr.write(`Failed to start in background. Check logs: ${logFile}
+`);
+    process.exit(1);
+  }
+  process.stderr.write("\n");
+  process.stderr.write(
+    `  ${style2.green("\u2713")} Setup complete. Shield is running in the background.
+`
+  );
+  process.stderr.write(`  ${style2.green("\u2713")} Folder: ${absDir}
+`);
+  process.stderr.write(
+    `  ${style2.green("\u2713")} FS server :${String(pidData.fsPort)}, Proxy :${String(pidData.proxyPort)}
+`
+  );
+  process.stderr.write("\n");
+  process.stderr.write(`  Stop it any time with:
+`);
+  process.stderr.write(
+    `    ${style2.cyan(`npx multicorn-shield files stop --agent ${opts.agent}`)}
+`
+  );
+  process.stderr.write("\n");
+  process.stderr.write(style2.dim(`  Status: npx multicorn-shield files status
+`));
+  process.stderr.write(style2.dim(`  Logs:   ${logFile}
+`));
+  process.stderr.write("\n");
+}
+async function runFilesCommand(opts) {
+  if (opts.status) {
+    runStatus();
+    return;
+  }
+  if (opts.restart) {
+    await runRestart(opts);
+    return;
+  }
+  if (opts.stop) {
+    await runStop(opts.agent);
+    return;
+  }
+  if (!opts.foreground) {
+    await runDetached(opts);
+    return;
+  }
+  const absDir = resolve(opts.dir);
+  if (!existsSync(absDir)) {
+    process.stderr.write(`Directory not found: ${opts.dir}. Check the path and try again.
+`);
+    process.exit(1);
+  }
+  if (opts.baseUrl && !isAllowedShieldApiBaseUrl(opts.baseUrl)) {
+    process.stderr.write(
+      "Error: --base-url must use HTTPS or http://localhost for local development.\n"
+    );
+    process.exit(1);
+  }
+  const config = await resolveConfig(opts);
+  const realDir = canonicalFolder(absDir);
+  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) {
+      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.
+`
+      );
+      process.exit(1);
+    }
+    removePidfile(opts.agent);
+  }
+  let fsPort;
+  let proxyReused;
+  let fsReused;
+  try {
+    const ensured = await withResourceLock(async () => {
+      const proxyRes = await ensureProxy(proxyPort, config.baseUrl);
+      const fsRes = await ensureFsServer(realDir, opts.port);
+      writePidfile({
+        agent: opts.agent,
+        dir: realDir,
+        supervisorPid: process.pid,
+        fsPort: fsRes.port,
+        proxyPort
+      });
+      return { proxyRes, fsRes };
+    });
+    fsPort = ensured.fsRes.port;
+    proxyReused = ensured.proxyRes.reused;
+    fsReused = ensured.fsRes.reused;
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${msg}
+`);
+    process.exit(1);
+  }
+  let registration;
+  try {
+    registration = await registerAgentAndConfig(
+      config.apiKey,
+      config.baseUrl,
+      opts.agent,
+      fsPort,
+      realDir
+    );
+  } catch (error) {
+    await withResourceLock(() => {
+      removePidfile(opts.agent);
+      releaseFsServerIfUnused(realDir, opts.agent);
+      releaseProxyIfUnused(proxyPort, opts.agent);
+    });
+    const msg = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Registration failed: ${msg}
+`);
+    process.exit(1);
+  }
+  const heartbeatServerName = proxyServerSlug(opts.agent);
+  const heartbeatTick = async () => {
+    const proxyVersion = await readProxyVersion(proxyPort);
+    const proxyOk = proxyVersion !== null || await probeProxyHealth(proxyPort);
+    const fsOk = await isPortListening(fsPort);
+    if (proxyOk && fsOk) {
+      await sendHeartbeat(config.apiKey, config.baseUrl, heartbeatServerName, proxyVersion);
+    }
+  };
+  void heartbeatTick();
+  const heartbeatTimer = setInterval(() => {
+    void heartbeatTick();
+  }, HEARTBEAT_INTERVAL_MS);
+  let cleaningUp = false;
+  process.on("SIGINT", () => {
+    if (cleaningUp) return;
+    cleaningUp = true;
+    void (async () => {
+      clearInterval(heartbeatTimer);
+      await withResourceLock(() => {
+        removePidfile(opts.agent);
+        releaseFsServerIfUnused(realDir, opts.agent);
+        releaseProxyIfUnused(proxyPort, opts.agent);
+      });
+      process.exit(0);
+    })();
+  });
+  process.on("SIGTERM", () => {
+    clearInterval(heartbeatTimer);
+    removePidfile(opts.agent);
+    process.exit(0);
+  });
+  const dirLabel = `./${basename(absDir)}`;
+  const localProxyUrl = `http://127.0.0.1:${String(proxyPort)}${registration.pathSegment}`;
+  process.stderr.write("\n");
+  process.stderr.write(
+    `  ${style2.green("\u2713")} ${proxyReused ? "Reusing shared proxy" : "Local proxy running"} (:${String(proxyPort)})
+`
+  );
+  process.stderr.write(
+    `  ${style2.green("\u2713")} ${fsReused ? "Reusing filesystem server for" : "Filesystem server on"} ${dirLabel} (:${String(fsPort)})
+`
+  );
+  process.stderr.write(`  ${style2.green("\u2713")} Agent '${opts.agent}' registered with Shield
+`);
+  const writeResult = await autoWriteClientConfig(
+    opts.client,
+    opts.agent,
+    localProxyUrl,
+    config.apiKey,
+    absDir
+  );
+  const firstWritten = writeResult.written[0];
+  if (firstWritten !== void 0) {
+    for (const w of writeResult.written) {
+      process.stderr.write(`  ${style2.green("\u2713")} Config written to ${style2.cyan(w.path)}
+`);
+    }
+    process.stderr.write("\n");
+    process.stderr.write(style2.dim(`  ${firstWritten.reload}
+`));
+  } else if (!writeResult.prompted) {
+    process.stderr.write("\n");
+    process.stderr.write(
+      "  Add this to your coding agent's MCP config so it routes through Shield:\n\n"
+    );
+    const configBlock = JSON.stringify(
+      {
+        mcpServers: {
+          [opts.agent]: {
+            url: hostedProxyUrlWithKeyParam(localProxyUrl, config.apiKey),
+            headers: { Authorization: `Bearer ${config.apiKey}` }
+          }
+        }
+      },
+      null,
+      2
+    );
+    process.stderr.write(style2.cyan(configBlock) + "\n\n");
+  }
+  process.stderr.write(style2.dim("  Write and delete will ask for approval the first time.\n"));
+  process.stderr.write("\n");
+  process.stderr.write(
+    `  ${style2.green("\u2713")} Shield is running (foreground mode). Press Ctrl-C to stop.
+`
+  );
+  process.stderr.write("\n");
+}
+async function autoWriteClientConfig(clientFlag, agentName, localProxyUrl, apiKey, workspacePath) {
+  if (clientFlag !== void 0 && clientFlag.length > 0) {
+    if (clientFlag === "all") {
+      const detected2 = detectInstalledClients();
+      if (detected2.length === 0) return { written: [], prompted: false };
+      const results = [];
+      for (const c of detected2) {
+        const path2 = await writeLocalMcpEntry(c, agentName, localProxyUrl, apiKey, workspacePath);
+        if (path2 !== null) {
+          results.push({ client: c, path: path2, reload: clientReloadInstruction(c) });
+        }
+      }
+      return { written: results, prompted: false };
+    }
+    const client2 = clientFlag;
+    if (!CODING_CLIENTS.includes(client2)) {
+      process.stderr.write(
+        `
+  Unknown --client "${clientFlag}". Valid options: ${CODING_CLIENTS.join(", ")}, all
+`
+      );
+      return { written: [], prompted: false };
+    }
+    const path = await writeLocalMcpEntry(client2, agentName, localProxyUrl, apiKey, workspacePath);
+    if (path !== null) {
+      return {
+        written: [{ client: client2, path, reload: clientReloadInstruction(client2) }],
+        prompted: false
+      };
+    }
+    process.stderr.write(
+      `
+  Could not write to ${clientDisplayName(client2)} config (parse error or permissions).
+`
+    );
+    return { written: [], prompted: false };
+  }
+  const detected = detectInstalledClients();
+  if (detected.length === 0) {
+    return { written: [], prompted: false };
+  }
+  if (detected.length === 1) {
+    const client2 = detected[0];
+    if (client2 === void 0) {
+      return { written: [], prompted: false };
+    }
+    const path = await writeLocalMcpEntry(client2, agentName, localProxyUrl, apiKey, workspacePath);
+    if (path !== null) {
+      return {
+        written: [{ client: client2, path, reload: clientReloadInstruction(client2) }],
+        prompted: false
+      };
+    }
+    process.stderr.write(
+      `
+  Could not safely update ${clientDisplayName(client2)} config (parse error or permissions). Left it unchanged.
+`
+    );
+    return { written: [], prompted: false };
+  }
+  if (!process.stdin.isTTY) {
+    process.stderr.write("\n");
+    process.stderr.write("  Multiple coding agents detected:\n");
+    for (const c of detected) {
+      process.stderr.write(`    - ${clientDisplayName(c)} (--client ${c})
+`);
+    }
+    process.stderr.write(
+      "\n  Re-run with --client <name> to write config, or --client all for all.\n"
+    );
+    return { written: [], prompted: true };
+  }
+  process.stderr.write("\n");
+  process.stderr.write("  Multiple coding agents detected. Which should route through Shield?\n\n");
+  for (const [i, c] of detected.entries()) {
+    process.stderr.write(`    ${String(i + 1)}) ${clientDisplayName(c)}
+`);
+  }
+  process.stderr.write(`    a) All of them
+`);
+  process.stderr.write("\n");
+  const choice = await promptLine("  Enter number (or 'a' for all): ");
+  const trimmed = choice.trim().toLowerCase();
+  if (trimmed === "a" || trimmed === "all") {
+    const results = [];
+    for (const c of detected) {
+      const path = await writeLocalMcpEntry(c, agentName, localProxyUrl, apiKey, workspacePath);
+      if (path !== null) {
+        results.push({ client: c, path, reload: clientReloadInstruction(c) });
+      }
+    }
+    return { written: results, prompted: false };
+  }
+  const num = Number.parseInt(trimmed, 10);
+  const client = num >= 1 && num <= detected.length ? detected[num - 1] : void 0;
+  if (client !== void 0) {
+    const path = await writeLocalMcpEntry(client, agentName, localProxyUrl, apiKey, workspacePath);
+    if (path !== null) {
+      return {
+        written: [{ client, path, reload: clientReloadInstruction(client) }],
+        prompted: false
+      };
+    }
+  }
+  process.stderr.write(`  Invalid choice. Use --client <name> next time.
+`);
+  return { written: [], prompted: true };
+}
+function promptLine(question) {
+  return new Promise((resolve3) => {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve3(answer);
+    });
+  });
+}
+
+// bin/multicorn-shield.ts
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let subcommand = "help";
+  let wrapCommand = "";
+  let wrapArgs = [];
+  let logLevel = "info";
+  let baseUrl = void 0;
+  let dashboardUrl = "";
+  let agentName = "";
+  let deleteAgentName = "";
+  let apiKey = void 0;
+  let verbose = false;
+  let filesDir = "";
+  let filesPort = void 0;
+  let filesProxyPort = void 0;
+  let filesStop = false;
+  let filesClient = void 0;
+  let filesForeground = false;
+  let filesStatus = false;
+  let filesRestart = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "init") {
+      subcommand = "init";
+    } else if (arg === "files") {
+      subcommand = "files";
+      const tail = args.slice(i + 1);
+      for (let j = 0; j < tail.length; j++) {
+        const token = tail[j];
+        if (token === void 0) continue;
+        if (token === "--agent") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            agentName = value;
+            j++;
+          }
+        } else if (token === "--port") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            filesPort = Number.parseInt(value, 10);
+            j++;
+          }
+        } else if (token === "--proxy-port") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            filesProxyPort = Number.parseInt(value, 10);
+            j++;
+          }
+        } else if (token === "--api-key") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            apiKey = value;
+            j++;
+          }
+        } else if (token === "--base-url") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            baseUrl = value;
+            j++;
+          }
+        } else if (token === "--client") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            filesClient = value;
+            j++;
+          }
+        } else if (token === "--stop") {
+          filesStop = true;
+        } else if (token === "--foreground") {
+          filesForeground = true;
+        } else if (token === "--detach") ; else if (token === "stop") {
+          filesStop = true;
+        } else if (token === "status") {
+          filesStatus = true;
+        } else if (token === "restart") {
+          filesRestart = true;
+        } else if (!token.startsWith("-") && filesDir === "") {
+          filesDir = token;
+        }
+      }
+      break;
+    } else if (arg === "agents") {
+      subcommand = "agents";
+    } else if (arg === "delete-agent") {
+      subcommand = "delete-agent";
+      const name = args[i + 1];
+      if (name === void 0 || name.startsWith("-")) {
+        process.stderr.write("Error: delete-agent requires an agent name.\n");
+        process.stderr.write("Example: npx multicorn-shield delete-agent my-agent\n");
+        process.exit(1);
+      }
+      deleteAgentName = name;
+      i++;
+    } else if (arg === "--wrap") {
+      subcommand = "wrap";
+      const tail = args.slice(i + 1);
+      const remaining = [];
+      for (let j = 0; j < tail.length; j++) {
+        const token = tail[j];
+        if (token === void 0) continue;
+        if (remaining.length > 0) {
+          remaining.push(token);
+          continue;
+        }
+        if (token === "--agent-name") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            agentName = value;
+            j++;
+          }
+        } else if (token === "--log-level") {
+          const value = tail[j + 1];
+          if (value !== void 0 && isValidLogLevel(value)) {
+            logLevel = value;
+            j++;
+          }
+        } else if (token === "--base-url") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            baseUrl = value;
+            j++;
+          }
+        } else if (token === "--dashboard-url") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            dashboardUrl = value;
+            j++;
+          }
+        } else if (token === "--api-key") {
+          const value = tail[j + 1];
+          if (value !== void 0) {
+            apiKey = value;
+            j++;
+          }
+        } else {
+          remaining.push(token);
+        }
+      }
+      if (remaining.length === 0) {
+        process.stderr.write("Error: --wrap requires a command to run.\n");
+        process.stderr.write("Example: npx multicorn-shield --wrap my-mcp-server\n");
+        process.exit(1);
+      }
+      wrapCommand = remaining[0] ?? "";
+      wrapArgs = remaining.slice(1);
+      break;
+    } else if (arg === "--log-level") {
+      const next = args[i + 1];
+      if (next !== void 0 && isValidLogLevel(next)) {
+        logLevel = next;
+        i++;
+      }
+    } else if (arg === "--base-url") {
+      const next = args[i + 1];
+      if (next !== void 0) {
+        baseUrl = next;
+        i++;
+      }
+    } else if (arg === "--dashboard-url") {
+      const next = args[i + 1];
+      if (next !== void 0) {
+        dashboardUrl = next;
+        i++;
+      }
+    } else if (arg === "--agent-name") {
+      const next = args[i + 1];
+      if (next !== void 0) {
+        agentName = next;
+        i++;
+      }
+    } else if (arg === "--api-key") {
+      const next = args[i + 1];
+      if (next !== void 0) {
+        apiKey = next;
+        i++;
+      }
+    } else if (arg === "--verbose" || arg === "--debug") {
+      verbose = true;
+    }
+  }
+  return {
+    subcommand,
+    wrapCommand,
+    wrapArgs,
+    logLevel,
+    baseUrl,
+    dashboardUrl,
+    agentName,
+    deleteAgentName,
+    apiKey,
+    verbose,
+    filesDir,
+    filesPort,
+    filesProxyPort,
+    filesStop,
+    filesClient,
+    filesForeground,
+    filesStatus,
+    filesRestart
+  };
+}
+function printHelp() {
+  process.stderr.write(
+    [
+      "multicorn-shield: MCP permission proxy and Shield setup",
+      "",
+      "Usage:",
+      "  npx multicorn-shield init",
+      "      Interactive setup. Saves API key to ~/.multicorn/config.json.",
+      "",
+      "  npx multicorn-shield files <dir> --agent <name> [--client <client>]",
+      "      Share a local folder with a coding agent. Starts a filesystem MCP server",
+      "      scoped to <dir>, registers the agent, writes your coding agent's MCP config,",
+      "      then exits. The service runs in the background until stopped.",
+      "",
+      "      --client <name>  Target client: cursor, cline, windsurf, claude, copilot,",
+      "                       goose, gemini, codex, continue, kilo, opencode",
+      "                       Auto-detected if omitted. Use --client all to write to every",
+      "                       detected client.",
+      "      --foreground     Keep the terminal open (for debugging). Default is background.",
+      "      --stop           Tear down the servers started by a previous `files` invocation.",
+      "",
+      "  npx multicorn-shield files stop --agent <name>",
+      "      Stop background processes for the named agent.",
+      "",
+      "  npx multicorn-shield files restart --agent <name>",
+      "      Stop then start the named agent, reusing the folder from its last run.",
+      "      Rewrites the coding agent's MCP config entry, so this repairs a stale",
+      "      entry that a plain stop/start would leave in place.",
+      "",
+      "  npx multicorn-shield files status",
+      "      Show all running file-sharing sessions.",
+      "",
+      "  npx multicorn-shield restore",
+      "      Restore MCP servers in claude_desktop_config.json from the Shield extension backup.",
+      "",
+      "  npx multicorn-shield agents",
+      "      List configured agents and show which is the default.",
+      "",
+      "  npx multicorn-shield delete-agent <name>",
+      "      Remove a saved agent.",
+      "",
+      "  npx multicorn-shield --wrap <command> [args...]",
+      "      Start <command> as an MCP server and proxy all tool calls through",
+      "      Shield's permission layer.",
+      "",
+      "Options:",
+      "  --version, -v        Print version and exit",
+      "  --verbose, --debug   Print extra diagnostics during init (menu selection, agent counts)",
+      "  --api-key <key>       Multicorn API key (overrides MULTICORN_API_KEY env var and config file)",
+      "  --log-level <level>   Log level: debug | info | warn | error  (default: info)",
+      "  --base-url <url>      Multicorn API base URL  (default: https://api.multicorn.ai)",
+      "  --dashboard-url <url> Dashboard URL for consent page  (default: derived from --base-url)",
+      "  --agent-name <name>   Override agent name derived from the wrapped command",
+      "",
+      "Examples:",
+      "  npx multicorn-shield init",
+      "  npx multicorn-shield files ./my-repo --agent my-agent",
+      "  npx multicorn-shield files ./my-repo --agent my-agent --foreground",
+      "  npx multicorn-shield files status",
+      "  npx multicorn-shield files stop --agent my-agent",
+      "  npx multicorn-shield files restart --agent my-agent",
+      "  npx multicorn-shield --wrap npx @modelcontextprotocol/server-filesystem /tmp",
+      "  npx multicorn-shield --wrap my-mcp-server --log-level debug",
+      ""
+    ].join("\n")
+  );
+}
+async function runCli() {
+  const first = process.argv[2];
+  if (first === "restore") {
+    await restoreClaudeDesktopMcpFromBackup();
+    process.stderr.write(
+      "Restored MCP server entries from ~/.multicorn/extension-backup.json into Claude Desktop config.\nRestart Claude Desktop to apply changes.\n"
+    );
+    return;
+  }
+  if (first === "--version" || first === "-v") {
+    process.stdout.write(`${PACKAGE_VERSION}
+`);
+    process.exit(0);
+  }
+  const cli = parseArgs(process.argv);
+  const logger = createLogger(cli.logLevel);
   if (cli.subcommand === "help") {
     printHelp();
     process.exit(0);
@@ -4865,6 +6240,48 @@ async function runCli() {
     await runInit(cli.baseUrl, { verbose: cli.verbose });
     return;
   }
+  if (cli.subcommand === "files") {
+    if (cli.filesStatus) {
+      await runFilesCommand({
+        dir: "",
+        agent: "",
+        port: void 0,
+        proxyPort: void 0,
+        apiKey: void 0,
+        baseUrl: void 0,
+        stop: false,
+        client: void 0,
+        foreground: true,
+        status: true,
+        restart: false
+      });
+      return;
+    }
+    if (!cli.filesStop && cli.agentName.length === 0) {
+      process.stderr.write("Error: --agent <name> is required for the files command.\n");
+      process.stderr.write("Example: npx multicorn-shield files ./my-repo --agent my-agent\n");
+      process.exit(1);
+    }
+    if (!cli.filesStop && !cli.filesRestart && cli.filesDir.length === 0) {
+      process.stderr.write("Error: a directory path is required.\n");
+      process.stderr.write("Example: npx multicorn-shield files ./my-repo --agent my-agent\n");
+      process.exit(1);
+    }
+    await runFilesCommand({
+      dir: cli.filesDir,
+      agent: cli.agentName,
+      port: cli.filesPort,
+      proxyPort: cli.filesProxyPort,
+      apiKey: cli.apiKey,
+      baseUrl: cli.baseUrl,
+      stop: cli.filesStop,
+      client: cli.filesClient,
+      foreground: cli.filesForeground,
+      status: false,
+      restart: cli.filesRestart
+    });
+    return;
+  }
   if (cli.subcommand === "agents") {
     const config2 = await loadConfig();
     if (config2 === null) {