@synap-core/cli 1.11.0 → 1.13.0

package/dist/lib/targets.js

@@ -11,13 +11,126 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { exec, execFileSync } from "node:child_process";
+import { execFileSync } from "node:child_process";
+import { openExternalUrl } from "./safe-open.js";
 import chalk from "chalk";
 import ora from "ora";
 import prompts from "prompts";
 import { log } from "../utils/logger.js";
+import { writeSecretFile, copySecretBackup, ensureSecretDir } from "./atomic-file.js";
+import { redactKey } from "./mcp-snippets.js";
 import { installSkills, getDeliverableSkills } from "./skills-installer.js";
-import { resolveUserId, hubPatch, } from "./hub-client.js";
+import { TARGET_KEY_MINT, takePreApprovedKey } from "./batch-approval.js";
+import { agentTypeOfSurface, machineInstanceId, machineInstanceLabel } from "./machine-instance.js";
+import { resolveUserId, hubGet, hubPatch, HubError, } from "./hub-client.js";
+/**
+ * Verify that a pod's `/mcp` endpoint actually serves Synap tools for THIS key.
+ *
+ * Two JSON-RPC calls: `initialize` (confirms the endpoint is a Synap MCP server,
+ * not a proxy default page — it checks `serverInfo.name === "synap-mcp-server"`)
+ * and `tools/list` (confirms the key authenticates and sees tools).
+ *
+ * This is the post-install gate `synap connect` runs after writing a client
+ * config. Without it, a wrong key, a workspace the agent isn't enrolled in, or
+ * a pod that is up but not serving MCP all surface three steps later when the
+ * user reports "it says it works but it doesn't" — which is exactly the failure
+ * that motivated this. `synap mcp verify` is the manual version of the same
+ * check.
+ */
+export async function verifyMcpConnection(podUrl, apiKey, opts) {
+    const podBase = podUrl.replace(/\/$/, "");
+    const url = `${podBase}/mcp`;
+    const timeout = opts?.timeoutMs ?? 20_000;
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+        Authorization: `Bearer ${apiKey}`,
+    };
+    // 1. initialize — is this a Synap MCP server?
+    let initRes;
+    try {
+        initRes = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {
+                    protocolVersion: "2024-11-05",
+                    capabilities: {},
+                    clientInfo: { name: "synap-cli", version: "1.0.0" },
+                },
+            }),
+            signal: AbortSignal.timeout(timeout),
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `Could not reach pod /mcp: ${err.message}` };
+    }
+    if (!initRes.ok) {
+        return { ok: false, error: `Pod /mcp returned HTTP ${initRes.status}` };
+    }
+    let initBody;
+    try {
+        initBody = (await initRes.json());
+    }
+    catch {
+        return { ok: false, error: "Pod /mcp returned a non-JSON body — is this a Synap pod?" };
+    }
+    if (initBody.error) {
+        return { ok: false, error: `MCP initialize rejected: ${initBody.error.message ?? "unknown error"}` };
+    }
+    const serverName = initBody.result?.serverInfo?.name;
+    if (serverName !== "synap-mcp-server") {
+        return {
+            ok: false,
+            error: `Pod /mcp is not a Synap MCP server (serverInfo.name = ${JSON.stringify(serverName)}) — the URL may point at a proxy or a non-Synap service.`,
+        };
+    }
+    // 2. tools/list — does this key authenticate and see tools?
+    let listRes;
+    try {
+        listRes = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} }),
+            signal: AbortSignal.timeout(timeout),
+        });
+    }
+    catch (err) {
+        return { ok: false, error: `Could not reach pod /mcp for tools/list: ${err.message}` };
+    }
+    if (!listRes.ok) {
+        return { ok: false, error: `Pod /mcp tools/list returned HTTP ${listRes.status}` };
+    }
+    let listBody;
+    try {
+        listBody = (await listRes.json());
+    }
+    catch {
+        return { ok: false, error: "Pod /mcp tools/list returned a non-JSON body." };
+    }
+    if (listBody.error) {
+        return { ok: false, error: `MCP tools/list rejected: ${listBody.error.message ?? "unknown error"}` };
+    }
+    const tools = Array.isArray(listBody.result?.tools) ? listBody.result.tools : [];
+    const toolCount = tools.length;
+    if (toolCount === 0) {
+        return {
+            ok: false,
+            error: `Pod /mcp authenticated this key but exposed ZERO tools — the key may be scoped ` +
+                `to a workspace the agent isn't enrolled in, or the pod is misconfigured.`,
+        };
+    }
+    if (opts?.expectToolCount && toolCount < opts.expectToolCount) {
+        return {
+            ok: false,
+            error: `Pod /mcp exposed only ${toolCount} tool(s), expected at least ${opts.expectToolCount}. The connection is degraded — re-run 'synap connect'.`,
+        };
+    }
+    return { ok: true, toolCount };
+}
 const CLAUDE_DESKTOP_MACOS = path.join(os.homedir(), "Library", "Application Support", "Claude");
 const CLAUDE_DESKTOP_WINDOWS = path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "Claude");
 const CLAUDE_DESKTOP_LINUX = path.join(os.homedir(), ".config", "Claude");
@@ -31,41 +144,10 @@ function claudeDesktopBaseDir() {
             return CLAUDE_DESKTOP_LINUX;
     }
 }
-/** Raycast app-support root (macOS only — Raycast is macOS-only). */
-function raycastSupportDir() {
-    return path.join(os.homedir(), "Library", "Application Support", "com.raycast.macos");
-}
-/**
- * Locate Raycast's EXISTING `mcp-config.json`. Raycast stores all non-dev MCP
- * servers in ONE file inside the "Manage MCP Servers" extension's support
- * directory — an opaque UUID folder under `…/com.raycast.macos/extensions/`.
- * The folder name is only known to Raycast and the file is created lazily the
- * first time the user opens "Manage MCP Servers".
- *
- * We therefore scan the support dirs for an EXISTING `mcp-config.json` and
- * return its path (so we can merge into it). Returns `null` when none exists —
- * the caller then prints the block for the user to paste via Raycast's
- * "Show Config File in Finder" action (the only reliable first-time path).
- */
-function raycastMcpConfigPath() {
-    const extensionsDir = path.join(raycastSupportDir(), "extensions");
-    try {
-        for (const entry of fs.readdirSync(extensionsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const candidate = path.join(extensionsDir, entry.name, "mcp-config.json");
-            if (fs.existsSync(candidate))
-                return candidate;
-        }
-    }
-    catch {
-        /* extensions dir missing — Raycast not installed or never opened */
-    }
-    return null;
-}
 export const TARGETS = {
     "claude-code": {
         name: "claude-code",
+        keyStore: { format: "claude-code", path: () => path.join(os.homedir(), ".claude", "settings.json") },
         label: "Claude Code",
         supports: { skills: true, mcp: true },
         skillsDir: () => path.join(os.homedir(), ".claude", "skills"),
@@ -73,6 +155,7 @@ export const TARGETS = {
     },
     "claude-desktop": {
         name: "claude-desktop",
+        keyStore: { format: "json", path: () => path.join(claudeDesktopBaseDir(), "claude_desktop_config.json") },
         label: "Claude Desktop",
         // Claude Desktop reads Agent Skills from its app-support skills/ dir
         // (alongside claude_desktop_config.json). The "upload via claude.ai" path
@@ -85,49 +168,67 @@ export const TARGETS = {
     },
     cursor: {
         name: "cursor",
+        keyStore: { format: "json", path: () => path.join(os.homedir(), ".cursor", "mcp.json") },
         label: "Cursor",
         supports: { skills: false, mcp: true },
         mcpConfigPath: () => path.join(os.homedir(), ".cursor", "mcp.json"),
     },
     raycast: {
         name: "raycast",
+        keyStore: {
+            none: "Raycast keeps its MCP sign-in in its own store; the commands' key is in ~/.synap/config.json",
+        },
         label: "Raycast",
-        description: "Native MCP server (via mcp-remote bridge) — all Synap tools in Raycast AI",
+        description: "Synap extension commands + the pod's MCP server in Raycast AI (HTTP, OAuth)",
         supports: { skills: false, mcp: true },
     },
-    openclaw: {
-        name: "openclaw",
-        label: "OpenClaw",
-        supports: { skills: true, mcp: false },
-    },
     openwebui: {
         name: "openwebui",
+        keyStore: { none: "registered in Open WebUI through its API — no local file" },
         label: "Open WebUI",
         description: "Register Synap as a model source and tool server in Open WebUI",
         supports: { skills: false, mcp: true },
     },
     codex: {
         name: "codex",
+        keyStore: { format: "toml", path: () => path.join(os.homedir(), ".codex", "config.toml") },
         label: "OpenAI Codex",
         description: "OpenAI Codex CLI — MCP server + instructions",
         supports: { skills: true, mcp: true },
-        mcpConfigPath: () => path.join(os.homedir(), ".codex", "config.yaml"),
+        mcpConfigPath: () => path.join(os.homedir(), ".codex", "config.toml"),
         skillsDir: () => path.join(os.homedir(), ".codex"),
     },
+    chatgpt: {
+        name: "chatgpt",
+        keyStore: { none: "pasted into ChatGPT on the web — no local file" },
+        label: "ChatGPT (API key)",
+        description: "ChatGPT connector (web) — API-key auth to your pod's /mcp (provisions under generic surface)",
+        supports: { skills: false, mcp: true },
+    },
+    "chatgpt-oauth": {
+        name: "chatgpt-oauth",
+        keyStore: { none: "OAuth through the control plane — no key" },
+        label: "ChatGPT (OAuth, via Control Plane)",
+        description: "ChatGPT connector via Synap Control Plane OAuth — multi-pod, no key to paste",
+        supports: { skills: false, mcp: true },
+    },
     opencode: {
         name: "opencode",
+        keyStore: { format: "json", path: () => path.join(os.homedir(), ".config", "opencode", "opencode.json") },
         label: "opencode",
         description: "Synap IS as AI provider + Synap pod as MCP tools in ~/.config/opencode/opencode.json",
         supports: { skills: false, mcp: true },
     },
     aider: {
         name: "aider",
+        keyStore: { none: "aider gets the Intelligence Service provider, not a pod MCP key" },
         label: "aider",
         description: "Write Synap IS as the OpenAI-compatible provider in ~/.aider.conf.yml",
         supports: { skills: false, mcp: false },
     },
     windsurf: {
         name: "windsurf",
+        keyStore: { format: "json", path: () => path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json") },
         label: "Windsurf",
         description: "Codeium Windsurf editor — MCP config at ~/.codeium/windsurf/mcp_config.json",
         supports: { skills: false, mcp: true },
@@ -135,29 +236,57 @@ export const TARGETS = {
     },
     goose: {
         name: "goose",
+        keyStore: { format: "yaml-goose", path: () => path.join(os.homedir(), ".config", "goose", "config.yaml") },
         label: "Goose",
         description: "Block's AI agent — MCP extension in ~/.config/goose/config.yaml",
         supports: { skills: false, mcp: true },
     },
     zed: {
         name: "zed",
+        keyStore: { format: "jsonc", path: () => zedSettingsPath() },
         label: "Zed",
         description: "Zed editor — context_servers entry in Zed settings.json (via mcp-remote)",
         supports: { skills: false, mcp: true },
     },
     vscode: {
         name: "vscode",
+        keyStore: { format: "json", path: () => path.join(vsCodeUserDataDir(), "mcp.json") },
         label: "VS Code (Kilo Code / Cline / Continue / Copilot)",
         description: "VS Code native MCP — one config read by Kilo Code, Cline, Continue, and Copilot",
         supports: { skills: false, mcp: true },
     },
+    grok: {
+        name: "grok",
+        keyStore: { format: "toml", path: () => path.join(os.homedir(), ".grok", "config.toml") },
+        label: "Grok (Grok Build TUI)",
+        description: "xAI Grok Build — provisions an agent key and writes [mcp_servers.*] into ~/.grok/config.toml",
+        supports: { skills: false, mcp: true },
+        mcpConfigPath: () => path.join(os.homedir(), ".grok", "config.toml"),
+    },
     generic: {
         name: "generic",
+        keyStore: { none: "printed for you to paste — no file the CLI writes" },
         label: "Generic MCP Client",
         description: "Output MCP connection config for any MCP-compatible client",
         supports: { skills: false, mcp: true },
     },
 };
+/**
+ * Every client file that may hold a key, for `synap doctor` — DERIVED from
+ * `TARGETS[*].keyStore`, never a second hand list. The surface is the CLI's
+ * key slot name (`agentKeysByPod.<surface>`), which is the target name.
+ */
+export function clientKeyFiles() {
+    const out = [];
+    for (const t of Object.values(TARGETS)) {
+        if ("none" in t.keyStore)
+            continue;
+        const file = t.keyStore.path();
+        if (file)
+            out.push({ surface: t.name, tool: t.label, file, format: t.keyStore.format });
+    }
+    return out;
+}
 export function isTargetName(value) {
     return value in TARGETS;
 }
@@ -181,13 +310,19 @@ export function buildMcpUrl(podUrl, workspaceId, projectId) {
  * Shared preamble for MCP surface installers: provision a dedicated agent key,
  * enroll the agent into the caller's workspaces, and resolve the scoped MCP URL.
  */
-async function prepareMcpSurface(cfg, agentType) {
-    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentType);
+async function prepareMcpSurface(cfg, agentType, opts) {
+    // Idempotent by default: `synap connect` is re-runnable. Without it, every
+    // connect mints a NEW inactive key + a fresh approval request on the pod,
+    // even for a surface that is already connected — which is why the pod admin
+    // site keeps showing "validate this proposal" on every reconnect. The pod
+    // returns `alreadyValid` for an existing key; we recover the plaintext from
+    // local storage and reuse it, rotating only on positive invalidation.
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentType, { idempotent: opts?.idempotent ?? true, toolProfile: opts?.toolProfile });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     return { effectiveApiKey, agentUserId, mcpUrl: buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId) };
 }
 // ─── Agent context configuration ──────────────────────────────────────────────
-export async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, info) {
+export async function configureAgentContext(podUrl, apiKey, agentType, agentUserId, info, opts) {
     const { AGENT_TEMPLATES, getTemplate } = await import("./agent-templates.js");
     log.blank();
     log.heading("Configure your agent");
@@ -209,7 +344,7 @@ export async function configureAgentContext(podUrl, apiKey, agentType, agentUser
     // create`) still get a routing file — just with the MINIMAL default template,
     // since there's no TTY to prompt on.
     let templateId;
-    if (process.stdin.isTTY) {
+    if (process.stdin.isTTY && opts?.prompt !== false) {
         ({ templateId } = await prompts({
             type: "select",
             name: "templateId",
@@ -235,17 +370,16 @@ export async function configureAgentContext(podUrl, apiKey, agentType, agentUser
     setAgentWorkspaceRouting({ memoryWorkspaceId: undefined, productWorkspaceIds: [] });
     // Always write to ~/.synap/contexts/<surface>.md
     const contextDir = path.join(os.homedir(), ".synap", "contexts");
-    if (!fs.existsSync(contextDir))
-        fs.mkdirSync(contextDir, { recursive: true });
+    ensureSecretDir(contextDir);
     const globalContextPath = path.join(contextDir, `${agentType}.md`);
-    fs.writeFileSync(globalContextPath, content, { mode: 0o600 });
+    writeSecretFile(globalContextPath, content, { mode: 0o600 });
     // For skills-capable surfaces, also write alongside SKILL.md
     const skillsDir = info?.skillsDir?.();
     if (skillsDir) {
         const synapSkillDir = path.join(skillsDir, "synap");
         if (!fs.existsSync(synapSkillDir))
             fs.mkdirSync(synapSkillDir, { recursive: true });
-        fs.writeFileSync(path.join(synapSkillDir, "CONTEXT.md"), content, { mode: 0o600 });
+        writeSecretFile(path.join(synapSkillDir, "CONTEXT.md"), content, { mode: 0o600 });
         log.success(`Agent context written to ${synapSkillDir}/CONTEXT.md`);
     }
     else {
@@ -273,7 +407,7 @@ export function listTargets() {
  * Run the install flow for a target. Returns true on success.
  * Throws only on unexpected errors — recoverable failures are logged + return false.
  */
-export async function installForTarget(target, cfg) {
+export async function installForTarget(target, cfg, opts) {
     const info = TARGETS[target];
     if (!info) {
         log.error(`Unknown target: ${target}`);
@@ -294,15 +428,18 @@ export async function installForTarget(target, cfg) {
         case "raycast":
             result = await installRaycast(cfg);
             break;
-        case "openclaw":
-            result = await installOpenclaw(cfg);
-            break;
         case "openwebui":
             result = await installOpenWebUI(cfg);
             break;
         case "codex":
             result = await installCodex(info, cfg);
             break;
+        case "chatgpt":
+            result = await installChatGpt(cfg);
+            break;
+        case "chatgpt-oauth":
+            result = await installChatGptOAuth(cfg);
+            break;
         case "opencode":
             result = await installOpencode(cfg);
             break;
@@ -321,22 +458,58 @@ export async function installForTarget(target, cfg) {
         case "vscode":
             result = await installVSCode(cfg);
             break;
+        case "grok":
+            result = await installGrok(info, cfg);
+            break;
         case "generic":
             result = await installGeneric(cfg);
             break;
     }
-    // Post-install: configure agent workspace context for all successful MCP installs.
-    if (result && info.supports.mcp && target !== "generic") {
+    // Post-install: agent context wizard for MCP targets. Skip Raycast — its AI
+    // reads the pod's MCP instructions; CONTEXT.md has no Raycast consumer.
+    if (result && info.supports.mcp && target !== "generic" && target !== "raycast") {
         const { getSurfaceAgentKey } = await import("./pod.js");
         const saved = getSurfaceAgentKey(target);
         const agentUserId = saved?.agentUserId ?? "";
         try {
-            await configureAgentContext(cfg.podUrl, cfg.apiKey, target, agentUserId, info);
+            await configureAgentContext(cfg.podUrl, cfg.apiKey, target, agentUserId, info, {
+                prompt: !cfg.unattended,
+            });
         }
         catch (err) {
             log.warn(`Agent context wizard failed: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // ── Post-install verify (the missing gate) ────────────────────────────────
+    // The config is written and the agent key is stored — but until this point
+    // nothing has checked that the client will actually load Synap tools. A key
+    // scoped to a workspace the agent isn't enrolled in, a pod that is up but not
+    // serving MCP, or a config the client ignores all surface three steps later
+    // when the user reports "it says it works but it doesn't". Verify against the
+    // pod's /mcp with the AGENT key (the one the client will use), not the human
+    // profile key — those are different identities and only one is in the config.
+    if (result && info.supports.mcp && opts?.verify !== false) {
+        const { getSurfaceAgentKey } = await import("./pod.js");
+        const saved = getSurfaceAgentKey(target, cfg.podUrl);
+        const verifyKey = saved?.hubApiKey ?? cfg.apiKey;
+        const verifySpinner = ora(`Verifying ${info.label} can reach Synap…`).start();
+        try {
+            const v = await verifyMcpConnection(cfg.podUrl, verifyKey, { timeoutMs: 20_000 });
+            if (v.ok) {
+                verifySpinner.succeed(`${info.label} verified — ${v.toolCount} Synap tool(s) reachable at ${cfg.podUrl}/mcp`);
+            }
+            else {
+                verifySpinner.warn(`${info.label} install completed but verification FAILED.`);
+                log.warn(`  ${v.error}`);
+                log.dim(`  The client config was written, but the agent key couldn't reach Synap. ` +
+                    `Re-run 'synap connect --target=${target}' after fixing it.`);
+            }
+        }
+        catch (err) {
+            verifySpinner.warn(`${info.label} verification errored.`);
+            log.warn(`  ${err.message}`);
+        }
+    }
     return result;
 }
 // ─── Claude Code ─────────────────────────────────────────────────────────────
@@ -346,7 +519,7 @@ async function installClaudeCode(info, cfg) {
     // commands (capture, recall, search, create, etc.) — not via MCP tool calls.
     // Skills give it Synap knowledge; the agent key lets it call the CLI directly.
     // MCP is available as an opt-in for users who prefer the tool-call interface.
-    const { mode } = await prompts({
+    const { mode } = cfg.unattended ? { mode: "both" } : await prompts({
         type: "select",
         name: "mode",
         message: "What do you want to install?",
@@ -489,74 +662,23 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     const me = await meRes.json();
     if (!me.id)
         throw new Error("/api/hub/users/me returned no user ID — is the pod running?");
-    const agentSetupRes = await fetch(`${podBase}/api/hub/setup/agent`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
-        body: JSON.stringify({ agentType: "claude-code", idempotent: true }),
-        signal: AbortSignal.timeout(30000),
+    // ONE door for the key: `provisionAgentKey` takes a key approved with this
+    // computer (device flow), resumes a request already filed from here, reuses
+    // the stored live key, or files a new request — with this computer's
+    // instance label — and WAITS for its approval. It never returns a pending
+    // key. (This function used to POST /setup/agent itself and wrote the still-
+    // pending key into every config — the 2026-10-12 incident.)
+    const provisioned = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "claude-code", {
+        idempotent: true,
+        surfaceName: "claude-code",
+        fallbackCandidate: settings.env?.["SYNAP_HUB_API_KEY"],
     });
-    if (!agentSetupRes.ok) {
-        const text = await agentSetupRes.text().catch(() => agentSetupRes.statusText);
-        throw new Error(credentialError("claude-code", agentSetupRes.status, text));
-    }
-    const agentSetup = await agentSetupRes.json();
-    if (agentSetup.alreadyValid) {
-        // Idempotent path — pod says the agent key is still valid but doesn't re-transmit it.
-        // Resolution priority: stored agentKey config > settings.json env var.
-        // Self-heal: verify the candidate resolves to the expected agent user, not the human user.
-        const { getSurfaceAgentKey: readSurfaceKey } = await import("./pod.js");
-        const storedKey = readSurfaceKey("claude-code");
-        const candidate = storedKey?.hubApiKey ??
-            settings.env?.["SYNAP_HUB_API_KEY"] ??
-            null;
-        const expectedAgentUserId = agentSetup.agentUserId ?? storedKey?.agentUserId;
-        let candidateIsValid = false;
-        if (candidate && expectedAgentUserId) {
-            try {
-                // Use auth/status — it returns the key's actual owner userId.
-                // For agent keys this is the agent userId, not the human userId.
-                // users/me always returns the human owner regardless of key type.
-                const verifyRes = await fetch(`${podBase}/api/hub/auth/status`, {
-                    headers: { Authorization: `Bearer ${candidate}` },
-                    signal: AbortSignal.timeout(30000),
-                });
-                if (verifyRes.ok) {
-                    const verifyStatus = await verifyRes.json();
-                    candidateIsValid = verifyStatus.userId === expectedAgentUserId;
-                }
-            }
-            catch { /* reprovision below */ }
-        }
-        if (candidateIsValid && candidate) {
-            effectiveApiKey = candidate;
-        }
-        else {
-            // Self-heal: stored key is stale, wrong identity, or never persisted.
-            // Reprovision without idempotent flag to get a fresh agent key.
-            const reproRes = await fetch(`${podBase}/api/hub/setup/agent`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json", Authorization: `Bearer ${cfg.apiKey}` },
-                body: JSON.stringify({ agentType: "claude-code" }),
-                signal: AbortSignal.timeout(30000),
-            });
-            if (reproRes.ok) {
-                const repro = await reproRes.json();
-                effectiveApiKey = repro.hubApiKey ?? candidate ?? cfg.apiKey;
-                if (repro.agentUserId)
-                    agentSetup.agentUserId = repro.agentUserId;
-            }
-            else {
-                // Reprovision failed — fall back to whatever we have, warn clearly
-                effectiveApiKey = candidate ?? cfg.apiKey;
-                log.warn("Could not reprovision agent key — using fallback. Run `synap connect --target=claude-code` to fix.");
-            }
-        }
-    }
-    else {
-        if (!agentSetup.hubApiKey)
-            throw new Error("setup/agent succeeded but returned no hubApiKey — check pod logs.");
-        effectiveApiKey = agentSetup.hubApiKey;
-    }
+    effectiveApiKey = provisioned.hubApiKey;
+    const agentSetup = { agentUserId: provisioned.agentUserId, alreadyValid: provisioned.reused };
+    // The last gate before ANY file is written: the pod must not say this key is
+    // pending, revoked, expired or unknown. A refused key changes nothing here.
+    const { assertKeyWritable } = await import("./key-state.js");
+    await assertKeyWritable(cfg.podUrl, effectiveApiKey);
     // Persist the provisioned key to agentKeys["claude-code"] so SYNAP_AGENT=claude-code
     // works in CLI sessions outside of this env (e.g. terminal, not just inside Claude Code).
     const { setSurfaceAgentKey: saveSurfaceKey } = await import("./pod.js");
@@ -564,9 +686,16 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     // Enroll the new agent user into the caller's workspaces using the HUMAN key
     // (before switching to the agent key). Scoped to one workspace when chosen.
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentSetup.agentUserId ?? "", cfg.workspaceId);
-    // Set per-agent governance — prompt once per agent, idempotent.
-    if (agentSetup.agentUserId) {
-        await ensureAgentGovernance(cfg, agentSetup.agentUserId);
+    // Set per-agent governance — read before write, so it never overwrites a
+    // choice. Unattended (`synap init`) writes NOTHING: a new agent follows the
+    // POD default ("reversible writes act", founder 2026-09-28). Interactive
+    // `synap connect` still offers the presets, and only for an agent nobody
+    // configured.
+    if (agentSetup.agentUserId && !cfg.unattended) {
+        await ensureAgentGovernance(cfg, agentSetup.agentUserId, undefined, {
+            onlyIfUnset: true,
+            knownAgent: !!agentSetup.alreadyValid,
+        });
     }
     const env = (settings.env ?? {});
     env["SYNAP_POD_URL"] = cfg.podUrl;
@@ -597,7 +726,7 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     if (!fs.existsSync(settingsDir)) {
         fs.mkdirSync(settingsDir, { recursive: true });
     }
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
     // ── Register the MCP server where Claude Code actually reads it ───────────
     // The official `claude mcp add` writes to the user-scope registry that
     // `claude mcp list` + the runtime consult — unlike settings.json mcpServers,
@@ -605,31 +734,128 @@ export async function writeClaudeCodeEnv(cfg, { writeMcp = true } = {}) {
     // synap tools.
     if (writeMcp) {
         const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
-        registerClaudeCodeMcp(mcpUrl, effectiveApiKey);
+        const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
+        registerClaudeCodeMcp(mcpUrl, effectiveApiKey, serverName);
     }
 }
 /**
  * Register the Synap MCP server with Claude Code via the official CLI, into the
  * user-scope registry (`claude mcp list` truth). Idempotent: drops any prior
- * entry first. Best-effort: if the `claude` binary isn't on PATH, prints the
- * exact command to run by hand rather than failing the whole connect.
+ * entry first (legacy `"synap"` and the pod-derived name). Best-effort: if the
+ * `claude` binary isn't on PATH, prints the exact command to run by hand
+ * rather than failing the whole connect.
+ *
+ * Server name is pod-derived (`mcpServerNameFromPodUrl`) so multi-pod setups
+ * (perso + team) do not overwrite each other — same pattern as Grok/Cursor.
  */
-function registerClaudeCodeMcp(mcpUrl, apiKey) {
+export function registerClaudeCodeMcp(mcpUrl, apiKey, serverName) {
     const header = `Authorization: Bearer ${apiKey}`;
+    const bridge = claudeCodeMcpTransport() === "bridge";
     try {
+        // Remove legacy single-name entry and any prior pod-derived name.
+        for (const name of new Set(["synap", serverName])) {
+            try {
+                execFileSync("claude", ["mcp", "remove", name], { stdio: "ignore" });
+            }
+            catch {
+                /* no prior entry — fine */
+            }
+        }
+        execFileSync("claude", bridge
+            ? // Stdio: Claude Code hands a stdio server its own session id, which
+                // the bridge forwards — see lib/mcp-bridge.ts. The key rides in the
+                // server's env, as the header does for http.
+                // `-e` is variadic in Claude Code's CLI: the server name must come
+                // BEFORE it, or `-e` swallows it as an env var.
+                ["mcp", "add", "--scope", "user", serverName, "-e", `SYNAP_MCP_API_KEY=${apiKey}`, "--", ...synapBridgeCommand(mcpUrl)]
+            : ["mcp", "add", "--transport", "http", serverName, mcpUrl, "--header", header, "--scope", "user"], { stdio: "ignore" });
+        log.success(`MCP server '${serverName}' registered with Claude Code (\`claude mcp add\`, user scope${bridge ? ", via the synap stdio bridge" : ""}). Relaunch Claude Code to load the tools.`);
+        if (serverName !== "synap") {
+            log.dim("Multi-pod: connect each profile separately — server names are derived from the pod host so they don't overwrite:");
+            log.dim("  synap connect --target=claude-code --name=perso");
+            log.dim("  synap connect --target=claude-code --name=team");
+        }
+    }
+    catch {
+        // Never print the key (terminal scrollback / shell history). Claude Code
+        // expands ${VAR} in an http header at launch, so the printed command names
+        // an env var; the key itself goes to a 0600 file the user sources.
+        const keyFile = path.join(os.homedir(), ".synap", "mcp-keys", `${serverName.replace(/[^A-Za-z0-9_-]/g, "_")}.env`);
         try {
-            execFileSync("claude", ["mcp", "remove", "synap"], { stdio: "ignore" });
+            ensureSecretDir(path.dirname(keyFile));
+            writeSecretFile(keyFile, `export SYNAP_MCP_KEY='${apiKey}'\n`);
+            log.dim(`Could not run \`claude mcp add\` (is the claude CLI on PATH?). The '${serverName}' MCP server may now be UNREGISTERED in Claude Code. Register it by hand (the key is in a 0600 file, not on this screen):`);
+            log.dim(`  source ${keyFile}`);
+            log.dim(bridge
+                ? `  claude mcp add --scope user ${serverName} -e SYNAP_MCP_API_KEY="$SYNAP_MCP_KEY" -- ${synapBridgeCommand(mcpUrl).map(shellQuote).join(" ")}`
+                : `  claude mcp add --transport http ${serverName} ${mcpUrl} --header 'Authorization: Bearer \${SYNAP_MCP_KEY}' --scope user`);
         }
         catch {
-            /* no prior entry — fine */
+            log.dim("Could not run `claude mcp add` (is the claude CLI on PATH?) and could not save the key file — run `synap mcp url` instead.");
         }
-        execFileSync("claude", ["mcp", "add", "--transport", "http", "synap", mcpUrl, "--header", header, "--scope", "user"], { stdio: "ignore" });
-        log.success("MCP server registered with Claude Code (`claude mcp add`, user scope). Relaunch Claude Code to load the synap tools.");
+    }
+}
+function shellQuote(arg) {
+    return /^[A-Za-z0-9_\-./:=@]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * How Claude Code reaches the pod's MCP: `"http"` (direct) or `"bridge"` (the
+ * synap stdio bridge, which tells the pod which Claude Code conversation each
+ * call comes from, so work can be reopened in it). Stored in Claude Code's own
+ * settings env (`SYNAP_MCP_TRANSPORT`), which `writeClaudeCodeEnv` merges, so a
+ * re-connect or `synap pods use` keeps the choice. Default: http.
+ */
+export function claudeCodeMcpTransport() {
+    try {
+        const settings = JSON.parse(fs.readFileSync(path.join(os.homedir(), ".claude", "settings.json"), "utf-8"));
+        return settings.env?.["SYNAP_MCP_TRANSPORT"] === "bridge" ? "bridge" : "http";
+    }
+    catch {
+        return "http";
+    }
+}
+/**
+ * Switch Claude Code's MCP transport and re-register the server with the key
+ * and pod `writeClaudeCodeEnv` already stored. Returns the server name, or
+ * null when Claude Code was never connected (nothing to switch).
+ */
+export function setClaudeCodeMcpTransport(transport) {
+    const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf-8"));
     }
     catch {
-        log.dim("Could not run `claude mcp add` (is the claude CLI on PATH?). Register it by hand:");
-        log.dim(`  claude mcp add --transport http synap ${mcpUrl} --header "${header}" --scope user`);
+        return null;
     }
+    const env = (settings.env ?? {});
+    const podUrl = env["SYNAP_POD_URL"];
+    const apiKey = env["SYNAP_HUB_API_KEY"];
+    if (!podUrl || !apiKey)
+        return null;
+    if (transport === "bridge")
+        env["SYNAP_MCP_TRANSPORT"] = "bridge";
+    else
+        delete env["SYNAP_MCP_TRANSPORT"];
+    settings.env = env;
+    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    const serverName = mcpServerNameFromPodUrl(podUrl);
+    registerClaudeCodeMcp(buildMcpUrl(podUrl, env["SYNAP_WORKSPACE_ID"], env["SYNAP_PROJECT_ID"]), apiKey, serverName);
+    return serverName;
+}
+/**
+ * The command Claude Code spawns for the bridge: THIS CLI by absolute path (the
+ * one running `use-bridge` is the one known to have the bridge — a `synap` on
+ * PATH may be an older install without it), unless this run is a throwaway
+ * `npx` copy, whose cache path can vanish; then the `synap` on PATH.
+ */
+function synapBridgeCommand(mcpUrl) {
+    const args = ["mcp", "bridge", "--url", mcpUrl];
+    const self = process.argv[1];
+    if (self && !self.includes(`${path.sep}_npx${path.sep}`)) {
+        return [process.execPath, fs.realpathSync(self), ...args];
+    }
+    return ["synap", ...args];
 }
 // ─── Agent key provisioning helper ──────────────────────────────────────────
 /**
@@ -649,40 +875,80 @@ function credentialError(agentType, status, body) {
     return (`Failed to provision agent key for ${agentType} (HTTP ${status}): ${body}\n` +
         `If this persists, re-authenticate with \`synap login --reconnect\`.`);
 }
-function openBrowserUrl(url) {
-    const safe = url.replace(/"/g, "%22");
-    const cmd = process.platform === "darwin" ? `open "${safe}"` :
-        process.platform === "win32" ? `start "" "${safe}"` :
-            `xdg-open "${safe}"`;
-    exec(cmd, () => { });
+/** Open an http(s) URL in the browser — argv only, never a shell (`safe-open.ts`). */
+export function openBrowserUrl(url) {
+    openExternalUrl(url);
 }
-async function waitForKeyApproval(podBase, humanApiKey, pendingToken, agentType) {
-    // Shared poll loop (also backs CP `synap login`) — see lib/approval-poll.ts.
-    const { pollForApproval } = await import("./approval-poll.js");
-    await pollForApproval({
-        url: `${podBase}/api/hub/setup/agent/pending/${pendingToken}`,
-        headers: { Authorization: `Bearer ${humanApiKey}` },
-        isApproved: (d) => d.status === "active",
-        isRejected: (d) => d.status === "rejected",
-        onApproved: () => undefined,
-        rejectedError: `Agent key for ${agentType} was rejected in the browser. Run connect again to re-request.`,
-        timeoutError: `Timed out waiting for approval of ${agentType} agent key (120s). ` +
-            `Open the review URL manually or run connect again.`,
-    });
+/** The pod answered a key mint with something unusable (e.g. no agent id). */
+export class AgentKeyMintError extends Error {
+    agentType;
+    constructor(agentType, message) {
+        super(message);
+        this.agentType = agentType;
+        this.name = "AgentKeyMintError";
+    }
 }
 /**
  * Provision an agent-owned API key for the given surface via POST /api/hub/setup/agent.
  * When requireApproval is true the key is created inactive; the user must approve in the
  * browser before this function returns.
  * Throws on failure — callers must not silently fall back to a human key.
+ *
+ * @param surfaceName  The CLI surface name (e.g. "chatgpt", "codex") — used for
+ *                     idempotent key lookup in local storage. If omitted, `agentType`
+ *                     is used. This handles the case where the pod's agentType
+ *                     differs from the CLI surface (e.g. ChatGPT provisions under
+ *                     "generic" but the CLI surface is "chatgpt").
  */
-export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true, idempotent = false, } = {}) {
+export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requireApproval = true, idempotent = false, surfaceName, deferApproval = false, instanceId, fallbackCandidate, toolProfile, } = {}) {
+    // `synap init` already minted — and the person approved — this key in one
+    // step with the others (`approveAgentKeysAtOnce`): hand it over, mint nothing.
+    if (!deferApproval) {
+        const pre = takePreApprovedKey(agentType);
+        if (pre)
+            return { ...pre, reused: false };
+    }
+    const surface = surfaceName ?? agentType;
+    const instance = instanceId ?? machineInstanceId(surface);
+    const podBase = podUrl.replace(/\/$/, "");
+    const pod = await import("./pod.js");
+    // A request already filed from this computer is RESUMED, never filed again:
+    // one approval, one key (2026-10-12: three orphaned requests in one evening).
+    const recorded = pod.getPendingAgentKey(surface, podUrl);
+    if (recorded) {
+        const { classifyRecordedPending } = await import("./key-approval.js");
+        const now = await classifyRecordedPending(recorded);
+        if (now.kind === "active") {
+            pod.clearPendingAgentKey(surface, podUrl);
+            return { hubApiKey: recorded.hubApiKey, agentUserId: recorded.agentUserId, reused: true };
+        }
+        if (now.kind === "pending" || now.kind === "unknown") {
+            if (deferApproval) {
+                return {
+                    hubApiKey: recorded.hubApiKey,
+                    agentUserId: recorded.agentUserId,
+                    reused: true,
+                    pending: { pendingToken: recorded.keyId, reviewUrl: now.state.approvalUrl ?? recorded.approvalUrl },
+                };
+            }
+            await awaitApprovalOrThrow({
+                podUrl,
+                humanApiKey,
+                agentType,
+                surface,
+                hubApiKey: recorded.hubApiKey,
+                pendingToken: recorded.keyId,
+                approvalUrl: now.state.approvalUrl ?? recorded.approvalUrl,
+            });
+            return { hubApiKey: recorded.hubApiKey, agentUserId: recorded.agentUserId, reused: true };
+        }
+        pod.clearPendingAgentKey(surface, podUrl); // dead: file a fresh request below
+    }
     // `idempotent: true` reuses the pod's existing valid key for this agentType
     // instead of minting a fresh one + revoking the old — required by callers whose
     // running process holds a long-lived key (e.g. `bridge-setup`), so re-running
     // setup doesn't break a live bridge. Default false preserves the mint-fresh
     // behavior every other caller (connect / pods / init) already relied on.
-    const podBase = podUrl.replace(/\/$/, "");
     let res;
     try {
         res = await fetch(`${podBase}/api/hub/setup/agent`, {
@@ -691,7 +957,16 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
                 "Content-Type": "application/json",
                 Authorization: `Bearer ${humanApiKey}`,
             },
-            body: JSON.stringify({ agentType, idempotent, requireApproval }),
+            // instanceLabel: this computer's name, so the connection reads
+            // "Claude Code on <computer>" wherever the person decides about it.
+            body: JSON.stringify({
+                agentType,
+                idempotent,
+                requireApproval,
+                instanceId: instance,
+                instanceLabel: machineInstanceLabel(),
+                ...(toolProfile ? { toolProfile } : {}),
+            }),
             signal: AbortSignal.timeout(30000),
         });
     }
@@ -716,9 +991,11 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
     // no rotation, no redeploy. We mint fresh ONLY when no valid local key exists
     // (e.g. a brand-new machine). This generalizes the claude-code self-heal.
     if (!body.hubApiKey && body.alreadyValid && idempotent) {
-        const { getSurfaceAgentKey } = await import("./pod.js");
-        const stored = getSurfaceAgentKey(agentType);
-        const candidate = stored?.hubApiKey;
+        // Use surfaceName for local storage lookup if provided; otherwise agentType.
+        // This handles cases where pod agentType ≠ CLI surface (e.g. ChatGPT uses
+        // "generic" but CLI surface is "chatgpt").
+        const stored = pod.getSurfaceAgentKey(surface);
+        const candidate = stored?.hubApiKey ?? fallbackCandidate;
         const expectedAgentUserId = body.agentUserId ?? stored?.agentUserId;
         if (candidate && expectedAgentUserId) {
             // auth/status returns the KEY's owner userId (the agent's, for agent keys).
@@ -757,6 +1034,10 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
         return provisionAgentKey(podUrl, humanApiKey, agentType, {
             requireApproval,
             idempotent: false,
+            surfaceName,
+            deferApproval,
+            instanceId: instance,
+            toolProfile,
         });
     }
     if (!body.hubApiKey) {
@@ -764,22 +1045,75 @@ export async function provisionAgentKey(podUrl, humanApiKey, agentType, { requir
             `This is a server-side bug — check the pod logs.`);
     }
     if (body.requiresApproval && body.pendingToken && body.reviewUrl) {
-        log.info(`\n  Opening your pod to review this agent key request…`);
-        log.dim(`  ${body.reviewUrl}`);
-        openBrowserUrl(body.reviewUrl);
-        process.stdout.write(chalk.dim("  Waiting for approval"));
-        const ticker = setInterval(() => process.stdout.write(chalk.dim(".")), 2000);
-        try {
-            await waitForKeyApproval(podBase, humanApiKey, body.pendingToken, agentType);
+        // The pre-approved key is handed to an installer that enrolls and scopes
+        // by this id: an empty one would connect an agent the pod cannot name.
+        if (!body.agentUserId) {
+            throw new AgentKeyMintError(agentType, `The pod minted a ${agentType} key but named no agent for it.`);
         }
-        finally {
-            clearInterval(ticker);
-            process.stdout.write("\n");
+        // Recorded BEFORE any wait: an interrupted or timed-out wait resumes this
+        // same request next time instead of filing another.
+        pod.setPendingAgentKey(surface, {
+            hubApiKey: body.hubApiKey,
+            agentUserId: body.agentUserId,
+            podUrl,
+            keyId: body.pendingToken,
+            approvalUrl: body.reviewUrl,
+            instanceId: instance,
+            createdAt: new Date().toISOString(),
+        });
+        if (deferApproval) {
+            return {
+                hubApiKey: body.hubApiKey,
+                agentUserId: body.agentUserId,
+                reused: false,
+                pending: { pendingToken: body.pendingToken, reviewUrl: body.reviewUrl },
+            };
         }
+        await awaitApprovalOrThrow({
+            podUrl,
+            humanApiKey,
+            agentType,
+            surface,
+            hubApiKey: body.hubApiKey,
+            pendingToken: body.pendingToken,
+            approvalUrl: body.reviewUrl,
+        });
         log.success(`  Approved! Writing ${agentType} agent key.`);
+        return { hubApiKey: body.hubApiKey, agentUserId: body.agentUserId, reused: false };
+    }
+    // Minted live (no approval asked). Still never hand out a key the pod says
+    // is unusable — callers write what this returns into configs.
+    if (!deferApproval) {
+        const { assertKeyWritable } = await import("./key-state.js");
+        await assertKeyWritable(podUrl, body.hubApiKey);
     }
     return { hubApiKey: body.hubApiKey, agentUserId: body.agentUserId ?? "", reused: false };
 }
+/**
+ * Open the approval page and wait for THIS pending key to go live. Approved →
+ * the recorded request is cleared. Rejected → cleared, and a plain error.
+ * Timed out → the request stays recorded and `AgentKeyAwaitingApprovalError`
+ * names the link and the resume command: nothing is written anywhere.
+ */
+async function awaitApprovalOrThrow(args) {
+    const { waitForKeyLive, openAndWait, AgentKeyAwaitingApprovalError } = await import("./key-approval.js");
+    const pod = await import("./pod.js");
+    const outcome = await openAndWait(args.agentType, args.approvalUrl, args.podUrl, () => waitForKeyLive({
+        podUrl: args.podUrl,
+        pendingKey: args.hubApiKey,
+        pendingToken: args.pendingToken,
+        humanApiKey: args.humanApiKey,
+    }), openBrowserUrl);
+    if (outcome === "approved") {
+        pod.clearPendingAgentKey(args.surface, args.podUrl);
+        return;
+    }
+    if (outcome === "rejected") {
+        pod.clearPendingAgentKey(args.surface, args.podUrl);
+        throw new Error(`The ${args.agentType} connection was declined on the pod. Run connect again to ask again.`);
+    }
+    throw new AgentKeyAwaitingApprovalError(args.agentType, args.approvalUrl);
+}
 /**
  * Enroll an agent user into the caller's workspaces via POST /api/hub/workspaces/enroll-agent.
  * Non-fatal — logs on failure so connect flow is never blocked by enrollment errors.
@@ -837,15 +1171,23 @@ async function installClaudeDesktop(info, cfg) {
     // stdio MCP messages into HTTPS calls against the pod's /mcp endpoint.
     //
     // Reference: https://www.npmjs.com/package/mcp-remote
-    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "claude-desktop");
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "claude-desktop", { idempotent: true });
     const { setSurfaceAgentKey: saveDesktopKey } = await import("./pod.js");
     saveDesktopKey("claude-desktop", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     const desktopMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
-    writeMcpServerEntry(mcpPath, "synap", {
+    // Pod-derived name so connecting a SECOND pod adds an entry instead of
+    // overwriting the first (same rule as Claude Code / Cursor / Grok).
+    const desktopServerName = mcpServerNameFromPodUrl(cfg.podUrl);
+    writeMcpServerEntry(mcpPath, desktopServerName, {
         command: "npx",
-        args: ["-y", "mcp-remote", desktopMcpUrl, "--header", `Authorization: Bearer ${effectiveApiKey}`],
+        // The header value rides in env (this file is 0600), never in the
+        // mcp-remote process's argv where any local `ps` can read it.
+        args: ["-y", "mcp-remote", desktopMcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+        env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
     });
+    if (desktopServerName !== "synap")
+        removeMcpServerEntry(mcpPath, "synap");
     log.blank();
     log.success(`MCP server 'synap' added to ${path.relative(os.homedir(), mcpPath)}`);
     log.dim("The entry uses 'npx mcp-remote' as a stdio bridge — Claude Desktop spawns it.");
@@ -880,19 +1222,32 @@ async function installCursor(info, cfg) {
     const mcpPath = info.mcpConfigPath?.();
     if (!mcpPath)
         return false;
-    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "cursor");
+    const mint = TARGET_KEY_MINT.cursor;
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, mint.agentType, { idempotent: mint.idempotent });
     const { setSurfaceAgentKey: saveCursorKey } = await import("./pod.js");
     saveCursorKey("cursor", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     const cursorMcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
-    writeMcpServerEntry(mcpPath, "synap", {
+    // Pod-derived name so multi-pod connects don't overwrite each other (peer of Grok).
+    const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
+    writeMcpServerEntry(mcpPath, serverName, {
         url: cursorMcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
     });
+    // Drop legacy single-name entry when we wrote a pod-qualified name, so reconnects
+    // don't leave a stale "synap" next to "synap-thearch".
+    if (serverName !== "synap") {
+        removeMcpServerEntry(mcpPath, "synap");
+    }
     log.blank();
-    log.success(`MCP server 'synap' added to ${path.relative(os.homedir(), mcpPath)}`);
+    log.success(`MCP server '${serverName}' added to ${path.relative(os.homedir(), mcpPath)}`);
     if (cfg.workspaceId)
         log.dim(`Scoped to workspace: ${cfg.workspaceId}`);
+    if (serverName !== "synap") {
+        log.dim("Multi-pod: connect each profile separately — server names are derived from the pod host so they don't overwrite:");
+        log.dim("  synap connect --target=cursor --name=perso");
+        log.dim("  synap connect --target=cursor --name=team");
+    }
     log.dim("Restart Cursor. The synap tool set will appear in agent mode.");
     log.blank();
     log.info("Cursor reads Claude-format skills from ~/.claude/skills/ too.");
@@ -900,10 +1255,20 @@ async function installCursor(info, cfg) {
     return true;
 }
 // ─── Raycast ─────────────────────────────────────────────────────────────────
+/**
+ * Raycast has two halves (decision B1, 2026-10-21):
+ *   - the Synap extension's native COMMANDS (search, capture, review…) call Hub
+ *     REST with a dedicated `raycast` agent key, read from ~/.synap/config.json;
+ *   - Raycast AI talks to the pod's own MCP server over HTTP (Streamable HTTP),
+ *     signed in with OAuth, or with that same agent key in a header as the
+ *     fallback. The extension ships no AI tools of its own any more.
+ *
+ * Raycast keeps its MCP servers in its own store, filled through its "Install
+ * MCP Server" form; its file format for an HTTP server is not documented, so we
+ * print the form's fields rather than write a guessed shape into Raycast's
+ * config. The key is never printed: the fallback header lives in a 0600 file.
+ */
 async function installRaycast(cfg) {
-    // Raycast reads credentials from ~/.synap/config.json (Tier 0) for its native
-    // extension commands, AND from mcp-config.json for the MCP server. Persist the
-    // workspace choice so both paths see the right scope.
     const { setActiveWorkspaceId, clearActiveWorkspaceId } = await import("./pod.js");
     if (cfg.workspaceId) {
         setActiveWorkspaceId(cfg.workspaceId);
@@ -911,94 +1276,29 @@ async function installRaycast(cfg) {
     else {
         clearActiveWorkspaceId();
     }
-    // Provision a dedicated "raycast" agent identity + resolve the scoped MCP URL.
-    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "raycast");
+    // A key minted here lists the 9-tool starter set on /mcp and loads more on
+    // demand (`entry`); an existing live key is reused as it is.
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "raycast", {
+        toolProfile: "entry",
+    });
     const { setSurfaceAgentKey } = await import("./pod.js");
     setSurfaceAgentKey("raycast", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
-    // ── Write the Raycast MCP server config (merge, never clobber) ─────────────
-    // Raycast's native MCP is stdio-only — bridge the HTTP /mcp endpoint with the
-    // `mcp-remote` npm package (npx spawns it). Same bridge as Claude Desktop/Zed.
-    const synapServerEntry = {
-        command: "npx",
-        args: [
-            "-y",
-            "mcp-remote",
-            mcpUrl,
-            "--header",
-            `Authorization: Bearer ${effectiveApiKey}`,
-        ],
-    };
-    // The mcp-config.json lives in an opaque UUID folder Raycast creates the first
-    // time "Manage MCP Servers" is opened. If it already exists we merge into it;
-    // otherwise we can't know the folder, so we print the block to paste.
-    const existingPath = raycastMcpConfigPath();
-    let wrote = false;
-    if (existingPath) {
-        try {
-            let mcpConfig = {};
-            try {
-                mcpConfig = JSON.parse(fs.readFileSync(existingPath, "utf-8"));
-            }
-            catch {
-                try {
-                    fs.copyFileSync(existingPath, `${existingPath}.bak`);
-                }
-                catch { /* best-effort */ }
-            }
-            mcpConfig.mcpServers = mcpConfig.mcpServers ?? {};
-            mcpConfig.mcpServers["synap"] = synapServerEntry;
-            fs.writeFileSync(existingPath, JSON.stringify(mcpConfig, null, 2) + "\n", { mode: 0o600 });
-            wrote = true;
-            log.success(`Synap MCP server added to Raycast: ${existingPath}`);
-            log.dim("Reopen Raycast → 'Manage MCP Servers' → 'synap' is connected with all tools.");
-            log.dim("First call spawns 'npx mcp-remote' (needs Node on PATH).");
-        }
-        catch (err) {
-            log.warn(`Could not write Raycast MCP config: ${err.message}`);
-        }
-    }
-    if (!wrote) {
-        log.info("To add Synap to Raycast as an MCP server:");
-        log.dim("  1. Open Raycast → run 'Manage MCP Servers'");
-        log.dim("  2. Action 'Show Config File in Finder' → open mcp-config.json");
-        log.dim("  3. Paste the 'synap' entry below into \"mcpServers\", then save:");
-        log.blank();
-        log.dim(JSON.stringify({ mcpServers: { synap: synapServerEntry } }, null, 2));
-        log.blank();
-        log.dim("  (Re-running `synap connect --target=raycast` after step 2 writes it for you.)");
-    }
-    log.blank();
+    const { writeMcpSnippetFiles } = await import("./mcp-snippets.js");
+    const files = writeMcpSnippetFiles(mcpUrl, effectiveApiKey, agentUserId);
+    log.success("Raycast agent key stored for the Synap extension's commands.");
     log.dim(`   Pod: ${cfg.podUrl}`);
     log.dim(`   Scope: ${cfg.workspaceId ? `workspace ${cfg.workspaceId}` : "all workspaces (pod-wide)"}`);
-    return true;
-}
-// ─── OpenClaw (wraps existing flow with saved pod config) ───────────────────
-async function installOpenclaw(cfg) {
-    const { detectOpenClaw, readOpenClawConfig, writeOpenClawConfig, setConfigValue } = await import("./openclaw.js");
-    const oc = detectOpenClaw();
-    if (!oc.found) {
-        log.warn("OpenClaw not detected on this machine.");
-        log.dim("  Install it first: https://openclaw.dev");
-        log.dim("  Or run `synap init` to set up from scratch.");
-        return false;
-    }
-    const ocConfig = readOpenClawConfig() ?? {};
-    setConfigValue(ocConfig, "synap.podUrl", cfg.podUrl);
-    setConfigValue(ocConfig, "synap.hubApiKey", cfg.apiKey);
-    if (cfg.workspaceId)
-        setConfigValue(ocConfig, "synap.workspaceId", cfg.workspaceId);
-    if (cfg.agentUserId)
-        setConfigValue(ocConfig, "synap.agentUserId", cfg.agentUserId);
-    writeOpenClawConfig(ocConfig);
-    if (cfg.agentUserId) {
-        await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, cfg.agentUserId, cfg.workspaceId);
-    }
-    log.success("Wrote OpenClaw config");
     log.blank();
-    log.info("Install the skills:");
-    for (const name of cfg.skills ?? getDeliverableSkills()) {
-        log.dim(`  openclaw skills install ${name}`);
-    }
+    const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
+    log.info("Add Synap to Raycast AI (one time, Raycast Pro):");
+    log.dim("  1. In Raycast, run “Install MCP Server”.");
+    log.dim(`  2. Name: ${serverName}   Transport: HTTP   URL: ${mcpUrl}`);
+    log.dim("  3. Authentication: OAuth → Dynamic → Sign In, then approve on your pod's consent page.");
+    log.dim("     Fallback, if Sign In fails: no OAuth; add the HTTP header");
+    log.dim(`     Authorization: Bearer ${redactKey(effectiveApiKey)}   (full value: ${files.jsonFile}, 0600)`);
+    log.dim("  4. Press “Install MCP Server” (⌘↵). In Raycast AI, mention the server and ask anything.");
+    log.blank();
+    log.dim("Raycast AI starts with the 9 essential Synap tools; it loads more when a task needs them.");
     return true;
 }
 // ─── Open WebUI ──────────────────────────────────────────────────────────────
@@ -1013,12 +1313,10 @@ async function installOpenWebUI(cfg) {
     log.info("2. MCP tool server:");
     log.dim("   Admin → Tools → Add Tool Server");
     log.dim(`   URL:     ${mcpUrl}`);
-    log.dim(`   Header:  Authorization: Bearer ${cfg.apiKey}`);
+    log.dim(`   Header:  Authorization: Bearer <key — saved in ~/.synap/openwebui-mcp.json (0600)>`);
     log.blank();
     const synapDir = path.join(os.homedir(), ".synap");
-    if (!fs.existsSync(synapDir)) {
-        fs.mkdirSync(synapDir, { recursive: true });
-    }
+    ensureSecretDir(synapDir);
     const refFile = path.join(synapDir, "openwebui-mcp.json");
     const refData = {
         modelSource: { baseUrl: `http://${podHost}/v1` },
@@ -1027,15 +1325,139 @@ async function installOpenWebUI(cfg) {
             headers: { Authorization: `Bearer ${cfg.apiKey}` },
         },
     };
-    fs.writeFileSync(refFile, JSON.stringify(refData, null, 2) + "\n", { mode: 0o600 });
+    writeSecretFile(refFile, JSON.stringify(refData, null, 2) + "\n", { mode: 0o600 });
     log.success(`Connection details saved to ~/.synap/openwebui-mcp.json`);
     return true;
 }
+// ─── ChatGPT (web) ───────────────────────────────────────────────────────────
+/**
+ * ChatGPT connects to Synap in TWO ways. This target wires the API-key path
+ * (the one the CLI can automate) and documents the OAuth path.
+ *
+ * API key: ChatGPT's "Add custom connector" accepts a URL + an
+ * `Authorization: Bearer <key>` header. That is the pod's standard MCP form,
+ * so the connection is the same one every other target uses — just pointed at
+ * the pod directly.
+ *
+ * OAuth: ChatGPT also supports OAuth (no header field). The pod's /mcp is
+ * Bearer-only, so OAuth for a SINGLE pod isn't available — it lives on the
+ * Control Plane (`https://api.synap.live/mcp`), which is an OAuth MCP server
+ * exposing `list_pods` / `connect_pod` / 14 proxied `pod__*` tools. That path
+ * is multi-pod and managed; `synap mcp connect-claude` prints it for
+ * claude.ai, and the same URL works for ChatGPT's OAuth connector.
+ *
+ * Agent type: the pod only mints keys for known surface agent types
+ * (`SURFACE_AGENT_TYPE_REQUIRED`), so a ChatGpt agent provisions under
+ * "generic" — a dedicated identity, never the human profile key.
+ */
+async function installChatGpt(cfg) {
+    // ChatGPT provisions under agentType "generic" (not a known surface type),
+    // so we store under surface name "chatgpt" for the user-facing CLI.
+    // The pod's SURFACE_AGENT_TYPE_REQUIRED guard allows "generic" but not "chatgpt".
+    // For idempotent reuse: pass surfaceName="chatgpt" so the local lookup finds
+    // the stored key, while the pod call uses agentType="generic".
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, agentTypeOfSurface("chatgpt"), { idempotent: true, surfaceName: "chatgpt" });
+    const { setSurfaceAgentKey } = await import("./pod.js");
+    setSurfaceAgentKey("chatgpt", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
+    await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
+    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
+    const synapDir = path.join(os.homedir(), ".synap");
+    ensureSecretDir(synapDir);
+    const refFile = path.join(synapDir, "chatgpt-mcp.json");
+    const refData = {
+        mcpToolServer: {
+            url: mcpUrl,
+            headers: { Authorization: `Bearer ${effectiveApiKey}` },
+        },
+        oauthAlternative: {
+            url: "https://api.synap.live/mcp",
+            note: "ChatGPT OAuth connector (no header field). Multi-pod: list_pods, " +
+                "connect_pod, then proxied pod__* tools. Same URL as claude.ai.",
+        },
+    };
+    writeSecretFile(refFile, JSON.stringify(refData, null, 2) + "\n", { mode: 0o600 });
+    log.heading("Connecting ChatGPT → " + cfg.podUrl);
+    log.blank();
+    log.info("Path 1 — API key (this CLI can wire it):");
+    log.blank();
+    log.info("  ChatGPT → Settings → Connectors → Add custom connector");
+    log.info(`  Name:     Synap`);
+    log.info(`  URL:      ${mcpUrl}`);
+    log.info(`  Auth:     API key`);
+    log.info(`  API key:  ${redactKey(effectiveApiKey)}  (full key: ~/.synap/chatgpt-mcp.json, 0600)`);
+    log.blank();
+    log.dim("  ChatGPT shows the key field inline — paste it there. If your build only " +
+        "shows URL + a header, set Authorization: Bearer <key>.");
+    log.blank();
+    log.info("Path 2 — OAuth (multi-pod, no key to paste):");
+    log.blank();
+    log.info("  ChatGPT → Settings → Connectors → Add custom connector");
+    log.info("  URL:     https://api.synap.live/mcp");
+    log.info("  Auth:    OAuth (leave API key blank)");
+    log.blank();
+    log.dim("  After OAuth, ask ChatGPT to 'list my Synap pods' (list_pods) and connect " +
+        "one (connect_pod). Same flow as claude.ai — see `synap mcp connect-claude`.");
+    log.blank();
+    log.success(`Connection details saved to ~/.synap/chatgpt-mcp.json`);
+    log.dim("ChatGPT caches connectors per workspace — remove and re-add if you switch pods.");
+    return true;
+}
+// ─── ChatGPT (web) — OAuth via Control Plane ──────────────────────────────────
+/**
+ * ChatGPT OAuth via the Control Plane — same URL as claude.ai.
+ *
+ * The CP's `/mcp` endpoint is OAuth-only (ES256 access tokens, RFC 9728
+ * `WWW-Authenticate` discovery). This path is MULTI-POD: after OAuth, the
+ * user sees `list_pods` → `connect_pod` to pick a pod, then gets 14 proxied
+ * `pod__*` tools. No API key is pasted; the CP stores an encrypted grant.
+ *
+ * Use this when:
+ *   - You have multiple pods and want to switch between them in ChatGPT
+ *   - You prefer OAuth over API-key auth
+ *   - You want the managed CP proxy (revoke in one place, no pod restarts)
+ */
+async function installChatGptOAuth(cfg) {
+    // Use the CP origin from the pod (or managed fallback)
+    const { deriveCpOrigin } = await import("../commands/mcp.js");
+    const { cpOrigin } = deriveCpOrigin(cfg.podUrl);
+    const url = `${cpOrigin.replace(/\/$/, "")}/mcp`;
+    log.heading("Connecting ChatGPT (OAuth) via Control Plane");
+    log.blank();
+    log.info("This uses the SAME OAuth URL as claude.ai — the CP is the single broker.");
+    log.blank();
+    log.info("ChatGPT → Settings → Connectors → Add custom connector");
+    log.info(`  Name:  Synap (Control Plane)`);
+    log.info(`  URL:   ${url}`);
+    log.info(`  Auth:  OAuth (leave API key blank)`);
+    log.blank();
+    log.info("After connecting, ask ChatGPT to:");
+    log.info("  1. 'list my Synap pods' (list_pods)");
+    log.info("  2. 'connect pod <your-pod>' (connect_pod)");
+    log.blank();
+    log.dim("The CP stores an encrypted grant. Revoke in pod-admin → My Connections.");
+    log.blank();
+    log.dim("See `synap mcp connect-claude` for the identical claude.ai flow.");
+    // Save a reference file for the user
+    const synapDir = path.join(os.homedir(), ".synap");
+    ensureSecretDir(synapDir);
+    const refFile = path.join(synapDir, "chatgpt-oauth.json");
+    const refData = {
+        oauthUrl: url,
+        note: "ChatGPT OAuth connector via Synap Control Plane. Multi-pod: list_pods, connect_pod, then proxied pod__* tools.",
+    };
+    writeSecretFile(refFile, JSON.stringify(refData, null, 2) + "\n", { mode: 0o600 });
+    log.success(`Connection details saved to ~/.synap/chatgpt-oauth.json`);
+    return true;
+}
 // ─── Windsurf ────────────────────────────────────────────────────────────────
 async function installWindsurf(info, cfg) {
     const configPath = info.mcpConfigPath?.() ?? path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
     const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "windsurf");
-    writeMcpServerEntry(configPath, "synap", { url: mcpUrl, headers: { Authorization: `Bearer ${effectiveApiKey}` } });
+    // Pod-derived name — a second pod must not overwrite the first.
+    const windsurfServerName = mcpServerNameFromPodUrl(cfg.podUrl);
+    writeMcpServerEntry(configPath, windsurfServerName, { url: mcpUrl, headers: { Authorization: `Bearer ${effectiveApiKey}` } });
+    if (windsurfServerName !== "synap")
+        removeMcpServerEntry(configPath, "synap");
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("windsurf", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`Windsurf MCP config updated: ${configPath}`);
@@ -1077,7 +1499,7 @@ async function installGoose(cfg) {
     else {
         updated = (existing ? existing.trimEnd() + "\n\n" : "") + "extensions:\n" + block + "\n";
     }
-    fs.writeFileSync(configPath, updated, { mode: 0o600 });
+    writeSecretFile(configPath, updated, { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("goose", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`Goose config updated: ${configPath}`);
@@ -1112,16 +1534,21 @@ async function installZed(cfg) {
         catch { /* malformed — start from scratch */ }
     }
     const contextServers = (settings.context_servers ?? {});
-    contextServers["synap"] = {
+    // Pod-derived name — a second pod must not overwrite the first.
+    const zedServerName = mcpServerNameFromPodUrl(cfg.podUrl);
+    if (zedServerName !== "synap")
+        delete contextServers["synap"];
+    contextServers[zedServerName] = {
         source: "custom",
         command: {
             path: "npx",
-            args: ["-y", "mcp-remote@latest", mcpUrl, "--header", `Authorization: Bearer ${effectiveApiKey}`],
+            args: ["-y", "mcp-remote@latest", mcpUrl, "--header", "Authorization:${SYNAP_AUTH}"],
+            env: { SYNAP_AUTH: `Bearer ${effectiveApiKey}` },
         },
         settings: {},
     };
     settings.context_servers = contextServers;
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    writeSecretFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("zed", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`Zed settings updated: ${settingsPath}`);
@@ -1152,12 +1579,16 @@ async function installVSCode(cfg) {
         catch { /* ignore */ }
     }
     existing.servers = existing.servers ?? {};
-    existing.servers["synap"] = {
+    // Pod-derived name — a second pod must not overwrite the first.
+    const vscodeServerName = mcpServerNameFromPodUrl(cfg.podUrl);
+    if (vscodeServerName !== "synap")
+        delete existing.servers["synap"];
+    existing.servers[vscodeServerName] = {
         type: "http",
         url: mcpUrl,
         headers: { Authorization: `Bearer ${effectiveApiKey}` },
     };
-    fs.writeFileSync(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
+    writeSecretFile(mcpJsonPath, JSON.stringify(existing, null, 2) + "\n", { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("vscode", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`VS Code MCP config updated: ${mcpJsonPath}`);
@@ -1165,39 +1596,149 @@ async function installVSCode(cfg) {
     log.dim("Reload VS Code (or open the MCP panel) to activate.");
     return true;
 }
+/**
+ * Derive a stable MCP server name from the pod URL so multi-pod setups
+ * (perso + team) don't overwrite each other. e.g. pod.thearch.synap.live → synap-thearch
+ */
+function mcpServerNameFromPodUrl(podUrl, fallback = "synap") {
+    try {
+        const host = new URL(podUrl).hostname; // pod.thearch.synap.live
+        const parts = host.split(".").filter(Boolean);
+        if (parts[0] === "pod" && parts[1])
+            return `synap-${parts[1]}`;
+        if (parts[0])
+            return `synap-${parts[0]}`;
+    }
+    catch {
+        /* ignore */
+    }
+    return fallback;
+}
+/** Merge/replace [mcp_servers.<name>] in a Grok config.toml without a TOML dep. */
+function writeGrokTomlMcpServer(configPath, serverName, opts) {
+    const dir = path.dirname(configPath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+    let existing = "";
+    if (fs.existsSync(configPath)) {
+        try {
+            existing = fs.readFileSync(configPath, "utf-8");
+        }
+        catch {
+            /* start fresh */
+        }
+    }
+    // Strip any previous section for this server (header through next top-level section)
+    const sectionHeader = `[mcp_servers.${serverName}]`;
+    const sectionRe = new RegExp(
+    // eslint-disable-next-line no-useless-escape
+    `\\n?\\[mcp_servers\\.${serverName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\][\\s\\S]*?(?=\\n\\[|$)`, "g");
+    let next = existing.replace(sectionRe, "").replace(/\n{3,}/g, "\n\n").trimEnd();
+    const block = [
+        "",
+        sectionHeader,
+        `url = "${opts.url}"`,
+        `headers = { Authorization = "Bearer ${opts.bearer}" }`,
+        `enabled = true`,
+        `startup_timeout_sec = 30`,
+        "",
+    ].join("\n");
+    next = (next ? next + "\n" : "") + block;
+    writeSecretFile(configPath, next.endsWith("\n") ? next : next + "\n", {
+        mode: 0o600,
+    });
+}
+// ─── Grok (Grok Build TUI) ───────────────────────────────────────────────────
+async function installGrok(info, cfg) {
+    const configPath = info.mcpConfigPath?.() ?? path.join(os.homedir(), ".grok", "config.toml");
+    const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "grok");
+    writeGrokTomlMcpServer(configPath, serverName, {
+        url: mcpUrl,
+        bearer: effectiveApiKey,
+    });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("grok", {
+        hubApiKey: effectiveApiKey,
+        agentUserId,
+        podUrl: cfg.podUrl,
+    });
+    log.success(`Grok MCP config updated: ${configPath}`);
+    log.info(`  Server table: [mcp_servers.${serverName}]`);
+    log.info(`  URL:          ${mcpUrl}`);
+    log.dim("  Agent key provisioned (not the human profile key).");
+    log.blank();
+    if (serverName !== "synap") {
+        log.dim("Multi-pod: connect each profile separately — server names are derived from the pod host so they don't overwrite:");
+        log.dim("  synap connect --target=grok --name=perso");
+        log.dim("  synap connect --target=grok --name=team");
+    }
+    log.dim("Restart Grok (or open a new session) and run: grok mcp doctor");
+    return true;
+}
 async function installGeneric(cfg) {
-    const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
+    // Provision a real agent key (same as other MCP surfaces) — never paste the
+    // human profile key into MCP configs (agents can't approve; human keys on MCP
+    // write path are rejected by the pod).
+    const { effectiveApiKey, agentUserId, mcpUrl } = await prepareMcpSurface(cfg, "generic");
+    const serverName = mcpServerNameFromPodUrl(cfg.podUrl);
     const httpConfig = {
-        synap: {
+        [serverName]: {
             url: mcpUrl,
             transport: "http",
-            headers: { Authorization: `Bearer ${cfg.apiKey}` },
+            headers: { Authorization: `Bearer ${effectiveApiKey}` },
         },
     };
-    log.info("Universal MCP connection config:");
+    log.info("Universal MCP connection config (agent key):");
     log.blank();
     log.info("HTTP direct:");
-    log.dim(JSON.stringify(httpConfig, null, 2));
+    // Redacted on screen; the real key is in ~/.synap/mcp-config.json (0600).
+    const shown = redactKey(effectiveApiKey);
+    log.dim(JSON.stringify({ [serverName]: { ...httpConfig[serverName], headers: { Authorization: `Bearer ${shown}` } } }, null, 2));
     log.blank();
-    log.info("stdio bridge (mcp-remote):");
-    log.dim(`  command: npx -y mcp-remote ${mcpUrl} --header "Authorization: Bearer ${cfg.apiKey}"`);
+    log.info("Grok Build (~/.grok/config.toml):");
+    log.dim(`[mcp_servers.${serverName}]`);
+    log.dim(`url = "${mcpUrl}"`);
+    log.dim(`headers = { Authorization = "Bearer ${shown}" }`);
     log.blank();
-    log.info("Environment variable form:");
-    log.dim(`  MCP_SERVER_URL=${mcpUrl}`);
-    log.dim(`  MCP_API_KEY=${cfg.apiKey}`);
+    log.info("stdio bridge (mcp-remote) — key via env, not argv:");
+    log.dim(`  command: npx -y mcp-remote ${mcpUrl} --header "Authorization:\${SYNAP_AUTH}"`);
+    log.dim(`  env:     SYNAP_AUTH="Bearer ${shown}"`);
+    log.dim("  Real key: ~/.synap/mcp-config.json (0600).");
     log.blank();
     const synapDir = path.join(os.homedir(), ".synap");
-    if (!fs.existsSync(synapDir)) {
-        fs.mkdirSync(synapDir, { recursive: true });
-    }
+    ensureSecretDir(synapDir);
     const configFile = path.join(synapDir, "mcp-config.json");
-    fs.writeFileSync(configFile, JSON.stringify(httpConfig, null, 2) + "\n", { mode: 0o600 });
-    log.success(`MCP config written to ~/.synap/mcp-config.json`);
+    // Merge with existing so dual-pod generic installs don't clobber each other
+    let existing = {};
+    if (fs.existsSync(configFile)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+        }
+        catch {
+            /* replace */
+        }
+    }
+    const merged = { ...existing, ...httpConfig };
+    writeSecretFile(configFile, JSON.stringify(merged, null, 2) + "\n", {
+        mode: 0o600,
+    });
+    const { setSurfaceAgentKey: save } = await import("./pod.js");
+    save("generic", {
+        hubApiKey: effectiveApiKey,
+        agentUserId,
+        podUrl: cfg.podUrl,
+    });
+    log.success(`MCP config written to ~/.synap/mcp-config.json (server: ${serverName})`);
+    log.dim("Prefer: synap connect --target=grok  to auto-write ~/.grok/config.toml");
     return true;
 }
 // ─── Codex ───────────────────────────────────────────────────────────────────
 async function installCodex(info, cfg) {
-    const configPath = info.mcpConfigPath?.() ?? path.join(os.homedir(), ".codex", "config.yaml");
+    // Codex reads MCP servers from ~/.codex/config.toml (not config.yaml).
+    // HTTP MCP format: [mcp_servers.synap] with url, headers, type="http"
+    const configPath = info.mcpConfigPath?.() ?? path.join(os.homedir(), ".codex", "config.toml");
     const configDir = path.dirname(configPath);
     if (!fs.existsSync(configDir)) {
         fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
@@ -1211,27 +1752,36 @@ async function installCodex(info, cfg) {
         catch { /* ignore */ }
     }
     // Build MCP server entry
-    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "codex");
+    const mint = TARGET_KEY_MINT.codex;
+    const { hubApiKey: effectiveApiKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, mint.agentType, { idempotent: mint.idempotent });
+    const { setSurfaceAgentKey } = await import("./pod.js");
+    setSurfaceAgentKey("codex", { hubApiKey: effectiveApiKey, agentUserId, podUrl: cfg.podUrl });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
-    // Inject/replace the synap mcpServers block using simple string manipulation
-    // (avoid requiring a YAML parser dependency)
+    // Build TOML block for HTTP MCP server
     const mcpBlock = [
-        "mcpServers:",
-        `  - name: synap`,
-        `    url: "${mcpUrl}"`,
-        `    headers:`,
-        `      Authorization: "Bearer ${effectiveApiKey}"`,
+        "",
+        "[mcp_servers.synap]",
+        `url = "${mcpUrl}"`,
+        `http_headers = { Authorization = "Bearer ${effectiveApiKey}" }`,
+        `startup_timeout_sec = 30`,
+        `enabled = true`,
+        "",
     ].join("\n");
+    // Replace existing synap entry or append
     let updated;
-    if (/^mcpServers:/m.test(existing)) {
-        // Replace existing mcpServers block (everything from mcpServers: to the next top-level key or EOF)
-        updated = existing.replace(/^mcpServers:[\s\S]*?(?=\n[a-zA-Z]|\s*$)/m, mcpBlock);
+    const sectionHeader = "[mcp_servers.synap]";
+    const sectionRe = new RegExp(`\\n?\\[mcp_servers\\.synap\\][\\s\\S]*?(?=\\n\\[|$)`, "g");
+    if (existing.includes(sectionHeader)) {
+        updated = existing.replace(sectionRe, "").replace(/\n{3,}/g, "\n\n").trimEnd();
+        updated = (updated ? updated + "\n" : "") + mcpBlock;
     }
     else {
-        updated = existing ? `${existing.trimEnd()}\n\n${mcpBlock}\n` : `${mcpBlock}\n`;
+        updated = existing ? `${existing.trimEnd()}\n${mcpBlock}\n` : mcpBlock;
     }
-    fs.writeFileSync(configPath, updated, { mode: 0o600 });
+    if (!updated.endsWith("\n"))
+        updated += "\n";
+    writeSecretFile(configPath, updated, { mode: 0o600 });
     // Skills → append synap context to ~/.codex/instructions.md
     const instructionsPath = path.join(configDir, "instructions.md");
     const marker = "<!-- synap-skill -->";
@@ -1254,7 +1804,7 @@ async function installCodex(info, cfg) {
             "Always call orient (or list workspaces) first to discover workspace IDs.",
             "",
         ].join("\n");
-        fs.writeFileSync(instructionsPath, (instructions.trimEnd() + snippet).trimStart() + "\n", { mode: 0o600 });
+        writeSecretFile(instructionsPath, (instructions.trimEnd() + snippet).trimStart() + "\n", { mode: 0o600 });
     }
     log.success(`Codex config updated: ${configPath}`);
     if (cfg.workspaceId) {
@@ -1333,7 +1883,7 @@ export async function installOpencode(cfg) {
             existing = JSON.parse(fs.readFileSync(configPath, "utf-8"));
         }
         catch {
-            fs.copyFileSync(configPath, `${configPath}.bak`);
+            copySecretBackup(configPath, `${configPath}.bak`);
             log.warn("Existing opencode.json unreadable — backed up to opencode.json.bak");
         }
     }
@@ -1345,12 +1895,16 @@ export async function installOpencode(cfg) {
         models,
     };
     // Provision an agent key so the MCP server runs under its own identity
-    const { hubApiKey: agentKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "opencode");
+    const { hubApiKey: agentKey, agentUserId } = await provisionAgentKey(cfg.podUrl, cfg.apiKey, "opencode", { idempotent: true });
     await enrollAgentIfNeeded(cfg.podUrl, cfg.apiKey, agentUserId, cfg.workspaceId);
     const podBase = cfg.podUrl.replace(/\/$/, "");
     const mcpUrl = buildMcpUrl(cfg.podUrl, cfg.workspaceId, cfg.projectId);
     const mcpBlock = (existing.mcp ?? {});
-    mcpBlock["synap"] = { type: "remote", url: mcpUrl, headers: { Authorization: `Bearer ${agentKey}` } };
+    // Pod-derived name — a second pod must not overwrite the first.
+    const opencodeServerName = mcpServerNameFromPodUrl(cfg.podUrl);
+    if (opencodeServerName !== "synap")
+        delete mcpBlock["synap"];
+    mcpBlock[opencodeServerName] = { type: "remote", url: mcpUrl, headers: { Authorization: `Bearer ${agentKey}` } };
     const updated = {
         $schema: "https://opencode.ai/config.json",
         ...existing,
@@ -1358,7 +1912,7 @@ export async function installOpencode(cfg) {
         mcp: mcpBlock,
         ...(existing.model ? {} : { model: defaultModel }),
     };
-    fs.writeFileSync(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
+    writeSecretFile(configPath, JSON.stringify(updated, null, 2) + "\n", { mode: 0o600 });
     const { setSurfaceAgentKey: save } = await import("./pod.js");
     save("opencode", { hubApiKey: agentKey, agentUserId, podUrl: cfg.podUrl });
     log.success(`opencode configured: ~/.config/opencode/opencode.json`);
@@ -1393,7 +1947,7 @@ export async function installAider(cfg) {
     const updated = existing.includes(marker)
         ? existing.replace(/# synap-provider[\s\S]*?(?=\n[a-zA-Z#]|\s*$)/, block.trimEnd())
         : existing ? `${existing.trimEnd()}\n\n${block}` : block;
-    fs.writeFileSync(confPath, updated.trimEnd() + "\n", { mode: 0o600 });
+    writeSecretFile(confPath, updated.trimEnd() + "\n", { mode: 0o600 });
     log.success(`${provider.name} configured in ~/.aider.conf.yml`);
     log.dim(`  Base URL: ${provider.baseUrl}`);
     log.dim(`  Model:    openai/${defaultModel}`);
@@ -1415,16 +1969,55 @@ export function writeMcpServerEntry(configPath, serverName, server) {
         catch {
             // corrupt or unreadable — back up and start fresh
             const backup = `${configPath}.bak-${Date.now()}`;
-            fs.copyFileSync(configPath, backup);
+            copySecretBackup(configPath, backup);
             log.warn(`Existing config unreadable; backed up to ${path.basename(backup)}`);
         }
     }
     config.mcpServers = config.mcpServers ?? {};
     config.mcpServers[serverName] = server;
-    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", {
+    writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
         mode: 0o600,
     });
 }
+/** Best-effort remove of a named MCP server entry (e.g. legacy `"synap"`). */
+function removeMcpServerEntry(configPath, serverName) {
+    if (!fs.existsSync(configPath))
+        return;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+        if (!config.mcpServers?.[serverName])
+            return;
+        delete config.mcpServers[serverName];
+        if (Object.keys(config.mcpServers).length === 0)
+            delete config.mcpServers;
+        writeSecretFile(configPath, JSON.stringify(config, null, 2) + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        /* leave config alone if unreadable */
+    }
+}
+/** The prompt's first choice: write nothing, follow the pod default. */
+const POD_DEFAULT_CHOICE = "pod-default";
+/** The pod posture name each named preset maps to. */
+const PRESET_POSTURE = {
+    creates: "create-with-undo",
+};
+/**
+ * Read an agent's governance, or `null` when the pod has no such read door
+ * (a pod older than it: 404/405) — "unknown", never "unset".
+ */
+async function readAgentGovernance(agentUserId, hubCfg) {
+    try {
+        return (await hubGet(`/agent-users/${agentUserId}/governance`, {}, hubCfg));
+    }
+    catch (err) {
+        if (err instanceof HubError && (err.status === 404 || err.status === 405))
+            return null;
+        throw err;
+    }
+}
 // Governance presets — MUST stay in sync with GOVERNANCE_MODES in the backend
 // `@synap/governance-policy`. (Single-source TODO: have the backend resolve a
 // mode NAME so the CLI never re-states the autoApproveFor list — until then,
@@ -1465,11 +2058,37 @@ const GOVERNANCE_PRESETS = {
         writesRequireProposal: false,
     },
 };
-export async function ensureAgentGovernance(cfg, agentUserId, presetMode) {
+export async function ensureAgentGovernance(cfg, agentUserId, presetMode, opts = {}) {
     const userId = await resolveUserId(cfg);
     const hubCfg = { ...cfg, userId };
-    // Non-interactive when a preset is passed (e.g. `--governance normal`);
-    // otherwise prompt (Normal pre-selected, Enter = <1s).
+    let current = null;
+    // A failed read (vs a pod that has no read door) is its own fact: the
+    // strict fallback below is the same, but the message must not claim the
+    // pod is old.
+    let readFailed = false;
+    try {
+        current = await readAgentGovernance(agentUserId, hubCfg);
+    }
+    catch (err) {
+        readFailed = true;
+        log.warn(`Could not read agent approval: ${err.message}`);
+        if (opts.onlyIfUnset)
+            return; // unknown ⇒ never overwrite
+    }
+    if (opts.onlyIfUnset && current === null && opts.knownAgent) {
+        log.dim("Kept this agent's approval settings.");
+        return;
+    }
+    if (opts.onlyIfUnset && current?.configured) {
+        log.dim(current.posture === "create-with-undo"
+            ? 'Agent approval: "creates" — creating happens at once with Undo; changes and deletes wait for you.'
+            : "Kept this agent's approval settings.");
+        return;
+    }
+    // Non-interactive when a preset is passed (e.g. `--governance creates`);
+    // otherwise prompt. "Follow the pod default" is pre-selected and writes
+    // nothing: a new agent's trust is the pod's rule, a preset is only ever a
+    // stricter (or looser) explicit choice.
     let mode = presetMode;
     if (!mode) {
         const res = await prompts({
@@ -1477,13 +2096,23 @@ export async function ensureAgentGovernance(cfg, agentUserId, presetMode) {
             name: "mode",
             message: "Governance — how should this agent's actions be gated?",
             choices: [
+                {
+                    title: "Follow the pod default (recommended)",
+                    description: "Uses your pod's trust setting (Settings › Approvals); change it there anytime.",
+                    value: POD_DEFAULT_CHOICE,
+                },
                 {
                     title: "Safe — every change requires your approval in Synap Studio",
                     description: "Creates, updates, and deletes all go through proposals. Maximum control.",
                     value: "safe",
                 },
                 {
-                    title: "Normal — creating & editing are instant, deletes need approval (recommended)",
+                    title: "Creates — creating is instant with Undo; changes and deletes need approval",
+                    description: "Agents add new things at once and you can undo each one; edits, new fields, automations and deletes go through proposals.",
+                    value: "creates",
+                },
+                {
+                    title: "Normal — creating & editing are instant, deletes need approval",
                     description: "Agents create and edit data immediately (edits merge, never wipe fields); deletes and full-content rewrites go through proposals.",
                     value: "normal",
                 },
@@ -1493,19 +2122,39 @@ export async function ensureAgentGovernance(cfg, agentUserId, presetMode) {
                     value: "crazy",
                 },
             ],
-            initial: 1,
+            initial: 0,
         });
         if (!res.mode)
             return;
+        if (res.mode === POD_DEFAULT_CHOICE) {
+            log.dim("Agent approval: follows the pod default.");
+            return;
+        }
         mode = res.mode;
     }
-    const profile = GOVERNANCE_PRESETS[mode] ?? GOVERNANCE_PRESETS.normal;
+    const posture = PRESET_POSTURE[mode];
+    // A pod without the read door (`current === null` after a clean read) also
+    // predates named postures: it would ignore `posture` and loosen the agent.
+    // Fall back to the strictest legacy list rather than guess.
+    const podKnowsPostures = current !== null;
+    const legacyMode = mode === "creates" ? "safe" : mode;
+    const profile = GOVERNANCE_PRESETS[legacyMode] ?? GOVERNANCE_PRESETS.safe;
     try {
-        await hubPatch(`/agent-users/${agentUserId}/governance`, {
-            autoApproveFor: profile.autoApproveFor,
-            writesRequireProposal: profile.writesRequireProposal,
-        }, hubCfg);
-        log.success(`Agent governance set to "${mode}"`);
+        await hubPatch(`/agent-users/${agentUserId}/governance`, posture && podKnowsPostures
+            ? { posture }
+            : {
+                autoApproveFor: profile.autoApproveFor,
+                writesRequireProposal: profile.writesRequireProposal,
+            }, hubCfg);
+        log.success(posture && podKnowsPostures
+            ? 'Agent approval: "creates". Creating happens at once with Undo; changes, new fields, automations and deletes wait for you.'
+            : mode === "creates"
+                ? readFailed
+                    ? 'Agent approval: "safe" — could not read this pod\'s approval settings, so every change waits for you.'
+                    : 'Agent approval: "safe" — this pod predates "creates", so every change waits for you.'
+                : legacyMode === "normal"
+                    ? 'Agent approval: "normal". Creating and editing (including profile and property changes and new automations) happen at once; deletes wait for you.'
+                    : `Agent approval: "${legacyMode}".`);
     }
     catch (err) {
         log.warn(`Could not apply agent governance: ${err.message}`);