@haven_ai/connect 0.1.26-alpha.0 → 0.1.27-alpha.0

package/dist/cli.js

@@ -1,263 +1,26 @@
 #!/usr/bin/env node
-import { realpathSync } from 'fs';
-import { fileURLToPath, pathToFileURL } from 'url';
-import { HAVEN_MINIMUM_NODE_VERSION, isSupportedNodeVersion, unsupportedNodeVersionMessage, SKILL_FOLDER_NAME, resolveTokenFromAddress, HAVEN_SKILL_MD, HAVEN_SKILL_BODY_MD } from '@haven_ai/sdk';
-import crypto from 'crypto';
-import { Wallet } from 'ethers';
-import { mkdir, rm, chmod, access, writeFile, readFile, unlink } from 'fs/promises';
+import { ensureConsent, computeConsentHash, loadCredentials, consentInputFromClient, registeredToolNames, MCP_VERSION } from '@haven_ai/mcp';
+import { ensureSignerConsent, computeSignerConsentHash, loadSignerCredentials, createEdgeSigner, toolSchemas } from '@haven_ai/signer';
+import { isSupportedNodeVersion, unsupportedNodeVersionMessage, SKILL_FOLDER_NAME, resolveTokenFromAddress, HAVEN_SKILL_MD, HAVEN_SKILL_BODY_MD, HAVEN_MINIMUM_NODE_VERSION } from '@haven_ai/sdk';
+import { mkdir, rm, chmod, access, writeFile, readFile, unlink, readdir, stat } from 'fs/promises';
 import { homedir, platform } from 'os';
 import { join, resolve, dirname } from 'path';
+import { parseDocument, isMap, stringify } from 'yaml';
 import { execFile, spawn } from 'child_process';
 import { promisify } from 'util';
-import { parseDocument, isMap, stringify } from 'yaml';
-import { registeredToolNames, MCP_VERSION, ensureConsent, computeConsentHash, loadCredentials, consentInputFromClient } from '@haven_ai/mcp';
-import { ensureSignerConsent, computeSignerConsentHash, loadSignerCredentials, createEdgeSigner, toolSchemas } from '@haven_ai/signer';
+import { realpathSync } from 'fs';
+import { fileURLToPath, pathToFileURL } from 'url';
+import crypto from 'crypto';
+import { Wallet } from 'ethers';
 
-// src/api.ts
-function createConnectApiClient(baseUrl, fetchImpl = fetch) {
-  const root = baseUrl.replace(/\/+$/, "");
-  return {
-    resolveSetup: (input) => request(fetchImpl, `${root}/agent-connection-setups/resolve`, {
-      method: "POST",
-      body: JSON.stringify({
-        setup_token: input.setupToken,
-        connector_version: input.connectorVersion,
-        runtime: input.runtime
-      })
-    }),
-    registerSetup: (input) => request(fetchImpl, `${root}/agent-connection-setups/register`, {
-      method: "POST",
-      body: JSON.stringify({
-        setup_token: input.setupToken,
-        challenge_id: input.challengeId,
-        delegate_address: input.delegateAddress,
-        proof_signature: input.proofSignature,
-        api_key_hash: input.apiKeyHash,
-        api_key_prefix: input.apiKeyPrefix,
-        runtime: input.runtime,
-        connector_version: input.connectorVersion,
-        connector_context: input.connectorContext,
-        install_capabilities: input.installCapabilities && {
-          can_write_runtime_config: input.installCapabilities.canWriteRuntimeConfig,
-          restart_required: input.installCapabilities.restartRequired
-        }
-      })
-    }),
-    getConnectorStatus: (setupId, apiKey) => request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/connector-status`, {
-      method: "GET",
-      headers: { Authorization: `Bearer ${apiKey}` }
-    }),
-    updateInstallStatus: async (setupId, apiKey, input) => {
-      await request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/install-status`, {
-        method: "POST",
-        headers: { Authorization: `Bearer ${apiKey}` },
-        body: JSON.stringify({
-          runtime: input.runtime,
-          connector_version: input.connectorVersion,
-          runtime_mcp_mode: input.runtimeMcpMode,
-          hosted_mcp_configured: input.hostedMcpConfigured,
-          local_signer_configured: input.localSignerConfigured,
-          local_mcp_configured: input.localMcpConfigured,
-          credential_files_written: input.credentialFilesWritten,
-          signer_acknowledged: input.signerAcknowledged,
-          local_mcp_acknowledged: input.localMcpAcknowledged,
-          activation_command_available: input.activationCommandAvailable,
-          skill_installed: input.skillInstalled,
-          probe_result: input.probeResult,
-          restart_required: input.restartRequired,
-          next_user_action: input.nextUserAction,
-          error_code: input.errorCode ?? null,
-          environment_label: input.environmentLabel
-        })
-      });
-    }
-  };
-}
-var ConnectRequestError = class extends Error {
-  constructor(message, status) {
-    super(message);
-    this.status = status;
-    this.name = "ConnectRequestError";
-  }
-  status;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
-async function request(fetchImpl, url, init) {
-  const response = await fetchImpl(url, {
-    ...init,
-    headers: {
-      "Content-Type": "application/json",
-      ...init.headers ?? {}
-    }
-  });
-  const text = await response.text();
-  const body = text ? JSON.parse(text) : null;
-  if (!response.ok) {
-    const message = body?.error ?? body?.message ?? `${response.status} ${response.statusText}`;
-    throw new ConnectRequestError(`Haven setup request failed: ${message}`, response.status);
-  }
-  return body;
-}
-function generateDelegateKey() {
-  return delegateKeyFromPrivateKey(Wallet.createRandom().privateKey);
-}
-function delegateKeyFromPrivateKey(privateKey) {
-  const wallet = new Wallet(privateKey);
-  return {
-    privateKey: wallet.privateKey,
-    address: wallet.address,
-    signChallenge: (message) => wallet.signMessage(message)
-  };
-}
-function generateAgentApiKey() {
-  return `sk_agent_${crypto.randomBytes(24).toString("hex")}`;
-}
-function hashAgentApiKey(apiKey) {
-  return crypto.createHash("sha256").update(apiKey).digest("hex");
-}
-function agentApiKeyPrefix(apiKey) {
-  return apiKey.slice(0, 12);
-}
-
-// src/redact.ts
-var API_KEY_RE = /sk_agent_[A-Za-z0-9]+/g;
-var PRIVATE_KEY_RE = /0x[0-9a-fA-F]{64}/g;
-function redactSecrets(value) {
-  return value.replace(API_KEY_RE, "sk_agent_[redacted]").replace(PRIVATE_KEY_RE, "0x[redacted-private-key]");
-}
-function shortAddress(address) {
-  if (!/^0x[0-9a-fA-F]{40}$/.test(address)) return address;
-  return `${address.slice(0, 6)}...${address.slice(-4)}`;
-}
-async function preflightCredentialStorage(input = {}) {
-  const directory = defaultCredentialRoot(input.baseDir);
-  await mkdir(directory, { recursive: true, mode: 448 });
-  await restrictPermissions(directory, 448, input.warn);
-  const probePath = join(directory, `.haven-connect-preflight-${crypto.randomBytes(8).toString("hex")}`);
-  try {
-    await writeOwnerOnlyJson(probePath, { ok: true }, input.warn);
-  } finally {
-    await rm(probePath, { force: true }).catch(() => void 0);
-  }
-  return directory;
-}
-async function writeCredentialFiles(input) {
-  const directory = defaultAgentDirectory(input.agentId, input.baseDir);
-  await mkdir(directory, { recursive: true, mode: 448 });
-  await restrictPermissions(directory, 448, input.warn);
-  const identityPath = join(directory, "identity.json");
-  const signerPath = join(directory, "signer.json");
-  const agentPath = join(directory, "agent.json");
-  await assertDoesNotExist(identityPath);
-  await assertDoesNotExist(signerPath);
-  await assertDoesNotExist(agentPath);
-  await writeOwnerOnlyJson(
-    signerPath,
-    {
-      delegate_key: input.delegateKey,
-      delegate_address: input.delegateAddress,
-      agent_id: input.agentId,
-      safe_address: input.safeAddress,
-      chain_id: input.chainId,
-      network: input.network,
-      x402_binding_signer: input.x402BindingSigner,
-      note: "Local signer credential. Haven backend never receives this private key."
-    },
-    input.warn
-  );
-  try {
-    await writeOwnerOnlyJson(
-      identityPath,
-      {
-        api_key: input.apiKey,
-        agent_id: input.agentId,
-        safe_address: input.safeAddress,
-        chain_id: input.chainId,
-        network: input.network,
-        api_url: input.apiUrl,
-        hosted_mcp_url: input.hostedMcpUrl,
-        agent_budget: input.agentBudget,
-        note: "Haven API key identifies the agent only. It cannot spend without the local signer key and on-chain Haven wallet rules."
-      },
-      input.warn
-    );
-  } catch (err) {
-    await rm(signerPath, { force: true }).catch(() => void 0);
-    throw err;
-  }
-  try {
-    await writeOwnerOnlyJson(
-      agentPath,
-      {
-        agent_id: input.agentId,
-        delegate_address: input.delegateAddress,
-        safe_address: input.safeAddress,
-        chain_id: input.chainId,
-        network: input.network,
-        agent_budget: input.agentBudget,
-        note: "Non-secret orientation for the agent: public delegate/Haven wallet identity + configured budget. Contains no API key or signing key. For the live remaining budget, call haven_get_allowances."
-      },
-      input.warn
-    );
-  } catch (err) {
-    await rm(signerPath, { force: true }).catch(() => void 0);
-    await rm(identityPath, { force: true }).catch(() => void 0);
-    await rm(agentPath, { force: true }).catch(() => void 0);
-    throw err;
-  }
-  return { directory, identityPath, signerPath, agentPath };
-}
-function defaultAgentDirectory(agentId, baseDir = join(homedir(), ".haven", "agents")) {
-  return resolve(defaultCredentialRoot(baseDir), safePathPart(agentId));
-}
-function defaultCredentialRoot(baseDir = join(homedir(), ".haven", "agents")) {
-  return resolve(baseDir);
-}
-async function writeOwnerOnlyJson(path, value, warn) {
-  const json = JSON.stringify(dropUndefined(value), null, 2);
-  await writeFile(path, `${json}
-`, { mode: 384, flag: "wx" });
-  await restrictPermissions(path, 384, warn);
-}
-function safePathPart(value) {
-  return value.replace(/[^A-Za-z0-9_.-]/g, "_");
-}
-function dropUndefined(value) {
-  return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
-}
-async function assertDoesNotExist(path) {
-  try {
-    await access(path);
-  } catch (err) {
-    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return;
-    throw err;
-  }
-  throw new Error(`Refusing to overwrite existing Haven credential file: ${path}`);
-}
-async function restrictPermissions(path, mode, warn) {
-  try {
-    await chmod(path, mode);
-  } catch (err) {
-    warn?.(
-      `Warning: could not restrict permissions on ${path} to ${mode.toString(8)}. Move this credential to a private location or run chmod ${mode.toString(8)} ${path}. ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-}
-var MCP_RUNTIME_MANIFEST = {
-  mcpPackage: "@haven_ai/mcp",
-  mcpVersion: MCP_VERSION,
-  sdkPackage: "@haven_ai/sdk",
-  sdkVersion: "0.1.26-alpha.0",
-  signerPackage: "@haven_ai/signer",
-  signerVersion: "0.1.26-alpha.0",
-  // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
-  // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
-  // so the guard that was supposed to enforce the floor waved Node v23 through
-  // — including on the `--local` path where it does run. A hand-maintained
-  // second copy of a number is a drift waiting to happen; a guard test pins
-  // this against `package.json`'s `engines.node`.
-  minimumNodeVersion: HAVEN_MINIMUM_NODE_VERSION,
-  supportedClients: ["codex-cli", "codex-desktop", "claude-code"],
-  requiredTools: registeredToolNames()
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
 };
 function mcpPackageSpec() {
   return `${MCP_RUNTIME_MANIFEST.mcpPackage}@${MCP_RUNTIME_MANIFEST.mcpVersion}`;
@@ -268,21 +31,35 @@ function sdkPackageSpec() {
 function signerPackageSpec() {
   return `${MCP_RUNTIME_MANIFEST.signerPackage}@${MCP_RUNTIME_MANIFEST.signerVersion}`;
 }
-
-// src/config-writers.ts
-var HERMES_API_KEY_ENV = "MCP_HAVEN_API_KEY";
-var HermesConfigRecoveryError = class extends Error {
-  constructor() {
-    super("Hermes configuration recovery did not complete");
-    this.name = "HermesConfigRecoveryError";
-  }
-};
-var InvalidCodexTomlError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "InvalidCodexTomlError";
+var MCP_RUNTIME_MANIFEST;
+var init_runtime_manifest = __esm({
+  "src/runtime-manifest.ts"() {
+    MCP_RUNTIME_MANIFEST = {
+      mcpPackage: "@haven_ai/mcp",
+      mcpVersion: MCP_VERSION,
+      sdkPackage: "@haven_ai/sdk",
+      sdkVersion: "0.1.27-alpha.0",
+      signerPackage: "@haven_ai/signer",
+      signerVersion: "0.1.27-alpha.0",
+      // Sourced from the SDK, never a literal (#1161). This field read '20.0.0'
+      // while every package's `engines` said `>=24` and the docs said `>=24.0.0`,
+      // so the guard that was supposed to enforce the floor waved Node v23 through
+      // — including on the `--local` path where it does run. A hand-maintained
+      // second copy of a number is a drift waiting to happen; a guard test pins
+      // this against `package.json`'s `engines.node`.
+      minimumNodeVersion: HAVEN_MINIMUM_NODE_VERSION,
+      supportedClients: ["codex-cli", "codex-desktop", "claude-code"],
+      requiredTools: registeredToolNames(),
+      /**
+       * The signer MCP's tool surface, DERIVED from the pinned @haven_ai/signer
+       * package (#1587) — same anti-drift rule as `requiredTools` above: a
+       * literal list here would rot the first time the signer gains a tool.
+       * The handshake probe requires all of them.
+       */
+      requiredSignerTools: Object.keys(toolSchemas)
+    };
   }
-};
+});
 async function writeRuntimeConfig(input, deps = {}) {
   switch (input.runtime) {
     case "codex-cli":
@@ -867,16 +644,35 @@ function hasBalancedTomlContainers(value) {
 function tomlString(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
 }
-function cursorConfigPath(homeDir = homedir()) {
-  return resolve(homeDir, ".cursor", "mcp.json");
-}
-function codexConfigPath(homeDir = homedir()) {
-  return resolve(homeDir, ".codex", "config.toml");
-}
-function vscodeConfigPath(homeDir = homedir()) {
-  if (platform() === "darwin") return resolve(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
-  if (platform() === "win32") {
-    return resolve(process.env.APPDATA ?? join(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
+function runtimeConfigPathFor(runtime, homeDir = homedir()) {
+  switch (runtime) {
+    case "cursor":
+      return cursorConfigPath(homeDir);
+    case "codex-cli":
+    case "codex-desktop":
+      return codexConfigPath(homeDir);
+    case "vscode":
+      return vscodeConfigPath(homeDir);
+    case "vscode-insiders":
+      return vscodeInsidersConfigPath(homeDir);
+    case "claude-desktop":
+      return claudeDesktopConfigPath(homeDir);
+    case "hermes":
+      return hermesConfigPath(homeDir);
+    default:
+      return null;
+  }
+}
+function cursorConfigPath(homeDir = homedir()) {
+  return resolve(homeDir, ".cursor", "mcp.json");
+}
+function codexConfigPath(homeDir = homedir()) {
+  return resolve(homeDir, ".codex", "config.toml");
+}
+function vscodeConfigPath(homeDir = homedir()) {
+  if (platform() === "darwin") return resolve(homeDir, "Library", "Application Support", "Code", "User", "mcp.json");
+  if (platform() === "win32") {
+    return resolve(process.env.APPDATA ?? join(homeDir, "AppData", "Roaming"), "Code", "User", "mcp.json");
   }
   return resolve(homeDir, ".config", "Code", "User", "mcp.json");
 }
@@ -923,82 +719,25 @@ function configTargetLabel(runtime) {
       return "runtime MCP config";
   }
 }
-async function acknowledgeLocalMcpConsent(identityPath, signerPath, log) {
-  try {
-    const input = await buildLocalMcpConsentInput(identityPath, signerPath);
-    const decision = await ensureConsent(input, {
-      credentialsPath: identityPath,
-      writeAck: true,
-      out: log ? { write: (chunk) => writeLogChunk(log, chunk) } : void 0
-    });
-    return {
-      acknowledged: decision.ok,
-      hash: decision.hash,
-      reason: decision.reason
-    };
-  } catch (err) {
-    return {
-      acknowledged: false,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-async function getLocalMcpConsentStatus(identityPath, signerPath) {
-  try {
-    const input = await buildLocalMcpConsentInput(identityPath, signerPath);
-    const hash = computeConsentHash(input);
-    const stored = await readLocalMcpAckFile(localMcpAckPath(identityPath));
-    if (stored === hash) {
-      return { acknowledged: true, hash, reason: "ack_file_match" };
-    }
-    return {
-      acknowledged: false,
-      hash,
-      reason: stored ? "ack_file_mismatch" : "ack_file_missing"
+var HERMES_API_KEY_ENV, HermesConfigRecoveryError, InvalidCodexTomlError;
+var init_config_writers = __esm({
+  "src/config-writers.ts"() {
+    init_runtime_manifest();
+    HERMES_API_KEY_ENV = "MCP_HAVEN_API_KEY";
+    HermesConfigRecoveryError = class extends Error {
+      constructor() {
+        super("Hermes configuration recovery did not complete");
+        this.name = "HermesConfigRecoveryError";
+      }
     };
-  } catch (err) {
-    return {
-      acknowledged: false,
-      error: err instanceof Error ? err.message : String(err)
+    InvalidCodexTomlError = class extends Error {
+      constructor(message) {
+        super(message);
+        this.name = "InvalidCodexTomlError";
+      }
     };
   }
-}
-function localMcpAckPath(identityPath) {
-  return resolve(`${identityPath}.ack.json`);
-}
-async function buildLocalMcpConsentInput(identityPath, signerPath) {
-  const credentials = await loadCredentials({ identityPath, signerPath });
-  const unavailableDuringSetup = {
-    getAllowances: async () => {
-      throw new Error("Haven approval is not complete yet.");
-    }
-  };
-  return consentInputFromClient(
-    unavailableDuringSetup,
-    {
-      apiKey: credentials.apiKey,
-      apiUrl: credentials.apiUrl,
-      agentId: credentials.agentId,
-      safeAddress: credentials.safeAddress,
-      delegateAddress: credentials.delegateAddress,
-      chainId: credentials.chainId,
-      allowanceSummary: credentials.allowanceSummary
-    },
-    registeredToolNames()
-  );
-}
-async function readLocalMcpAckFile(path) {
-  try {
-    const parsed = JSON.parse(await readFile(path, "utf8"));
-    return typeof parsed.ack === "string" ? parsed.ack : null;
-  } catch {
-    return null;
-  }
-}
-function writeLogChunk(log, chunk) {
-  const message = String(chunk).trimEnd();
-  if (message) log(message);
-}
+});
 async function probeHostedMcpTools(apiKey, hostedMcpUrl, fetchImpl = fetch) {
   let response;
   try {
@@ -1041,6 +780,8 @@ async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4)
     let stdout = "";
     let settled = false;
     let sawInitialize = false;
+    let serverInfo;
+    let capabilities;
     const finish = (result) => {
       if (settled) return;
       settled = true;
@@ -1072,6 +813,9 @@ async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4)
         }
         if (payload.id === 1 && !sawInitialize) {
           sawInitialize = true;
+          const init = payload.result;
+          serverInfo = init?.serverInfo;
+          capabilities = init?.capabilities;
           writeJsonRpc(child, { jsonrpc: "2.0", method: "notifications/initialized", params: {} });
           writeJsonRpc(child, { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
           continue;
@@ -1080,7 +824,7 @@ async function probeLocalMcpTools(command, args, requiredTools, timeoutMs = 1e4)
           const tools = payload.result?.tools;
           const toolNames = Array.isArray(tools) ? tools.map((tool) => tool && typeof tool === "object" && "name" in tool ? tool.name : void 0).filter((name) => typeof name === "string") : [];
           const missing = requiredTools.filter((name) => !toolNames.includes(name));
-          finish({ status: missing.length === 0 ? "ok" : "missing_tools", toolNames });
+          finish({ status: missing.length === 0 ? "ok" : "missing_tools", toolNames, serverInfo, capabilities });
           return;
         }
       }
@@ -1129,51 +873,37 @@ async function fetchWithTimeout(fetchImpl, url, init) {
     clearTimeout(timeout);
   }
 }
-var execFileAsync = promisify(execFile);
-var UnsupportedNodeVersionError = class extends Error {
-  code = "local_mcp_unsupported_node_version";
-  nodeVersion;
-  minimumNodeVersion;
-  constructor(nodeVersion, minimumNodeVersion, subject = "Haven setup") {
-    super(unsupportedNodeVersionMessage({ subject, nodeVersion, minimumNodeVersion }));
-    this.name = "UnsupportedNodeVersionError";
-    this.nodeVersion = nodeVersion;
-    this.minimumNodeVersion = minimumNodeVersion;
+var init_probes = __esm({
+  "src/probes.ts"() {
   }
-};
-async function prepareLocalMcpRuntime(input, deps = {}) {
-  assertSupportedNodeVersion(input.nodeVersion);
+});
+async function prepareSignerRuntime(input, deps = {}) {
   const homeDir = input.homeDir ?? homedir();
-  const runtimeDirectory = resolve(homeDir, ".haven", "mcp-runtime", MCP_RUNTIME_MANIFEST.mcpVersion);
+  const runtimeDirectory = resolve(homeDir, ".haven", "signer-runtime", MCP_RUNTIME_MANIFEST.signerVersion);
   const npmCacheDirectory = resolve(homeDir, ".haven", "npm-cache");
-  const cliPath = join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "dist", "cli.js");
+  const cliPath = join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "dist", "cli.js");
   const messages = [];
   await mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await chmod(runtimeDirectory, 448).catch(() => void 0);
   await mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await chmod(npmCacheDirectory, 448).catch(() => void 0);
   if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
-    messages.push(`Using existing local Haven MCP runtime ${mcpPackageSpec()}.`);
+    messages.push(`Using existing local Haven signer runtime ${signerPackageSpec()}.`);
   } else {
-    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps.runCommand);
-    messages.push(`Installed local Haven MCP runtime ${mcpPackageSpec()}.`);
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps);
+    messages.push(`Installed local Haven signer runtime ${signerPackageSpec()}.`);
   }
-  await assertFileExists(cliPath, "local Haven MCP CLI");
-  const wrapperPath = join(input.credentialDirectory, "bin", "haven-mcp");
-  await writeWrapper({
-    wrapperPath,
-    cliPath,
-    identityPath: input.identityPath,
-    signerPath: input.signerPath
-  });
+  await assertFileExists(cliPath, "local Haven signer CLI");
+  const wrapperPath = join(input.credentialDirectory, "bin", "haven-signer.mjs");
+  await writeWrapper({ wrapperPath, cliPath, signerPath: input.signerPath });
   await writeRuntimeSidecar({
-    path: join(input.credentialDirectory, "mcp-runtime.json"),
+    path: join(input.credentialDirectory, "signer-runtime.json"),
     wrapperPath,
     runtimeDirectory,
     npmCacheDirectory,
     cliPath
   });
-  messages.push(`Prepared stable local Haven MCP wrapper: ${wrapperPath}`);
+  messages.push(`Prepared stable local Haven signer wrapper: ${wrapperPath}`);
   return {
     command: wrapperPath,
     args: [],
@@ -1184,12 +914,8 @@ async function prepareLocalMcpRuntime(input, deps = {}) {
     messages
   };
 }
-function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = MCP_RUNTIME_MANIFEST.minimumNodeVersion, subject = "Haven setup") {
-  if (!isSupportedNodeVersion(nodeVersion, minimumNodeVersion)) {
-    throw new UnsupportedNodeVersionError(nodeVersion, minimumNodeVersion, subject);
-  }
-}
-async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, runCommand) {
+async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps) {
+  const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
     "--prefix",
@@ -1198,12 +924,22 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, runCo
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    mcpPackageSpec(),
+    signerPackageSpec(),
     sdkPackageSpec()
   ];
   const run = async (args) => {
-    if (runCommand) await runCommand("npm", args);
-    else await execFileAsync("npm", args, { timeout: 12e4, maxBuffer: 1024 * 1024 });
+    const startedAt = Date.now();
+    const heartbeat = setInterval(() => {
+      const seconds = Math.round((Date.now() - startedAt) / 1e3);
+      onProgress?.(`Still installing the local Haven signer runtime\u2026 (${seconds}s \u2014 a cold cache can take several minutes)`);
+    }, SIGNER_INSTALL_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    try {
+      if (runCommand) await runCommand("npm", args);
+      else await execFileAsync("npm", args, { timeout: SIGNER_INSTALL_TIMEOUT_MS, maxBuffer: 1024 * 1024 });
+    } finally {
+      clearInterval(heartbeat);
+    }
   };
   try {
     await run(baseArgs);
@@ -1211,18 +947,20 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, runCo
     try {
       await run([...baseArgs, "--cache", npmCacheDirectory]);
     } catch (err) {
-      throw new Error(`Could not install local Haven MCP runtime ${mcpPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`);
+      throw new Error(
+        `Could not install local Haven signer runtime ${signerPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`
+      );
     }
   }
 }
 async function installedRuntimeMatches(runtimeDirectory, cliPath) {
   try {
-    await assertFileExists(cliPath, "local Haven MCP CLI");
-    const [mcpPackage, sdkPackage] = await Promise.all([
-      readPackageJson(join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
+    await assertFileExists(cliPath, "local Haven signer CLI");
+    const [signerPackage, sdkPackage] = await Promise.all([
+      readPackageJson(join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
       readPackageJson(join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
     ]);
-    return mcpPackage.version === MCP_RUNTIME_MANIFEST.mcpVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    return signerPackage.version === MCP_RUNTIME_MANIFEST.signerVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
   } catch {
     return false;
   }
@@ -1238,10 +976,9 @@ async function writeWrapper(input) {
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
-    `const identityPath = ${JSON.stringify(input.identityPath)}`,
     `const signerPath = ${JSON.stringify(input.signerPath)}`,
     "",
-    "const child = spawn(process.execPath, [cliPath, '--identity', identityPath, '--signer', signerPath, ...process.argv.slice(2)], {",
+    "const child = spawn(process.execPath, [cliPath, '--credentials', signerPath, ...process.argv.slice(2)], {",
     "  stdio: 'inherit',",
     "})",
     "",
@@ -1254,57 +991,889 @@ async function writeWrapper(input) {
   await writeFile(input.wrapperPath, source, { mode: 448 });
   await chmod(input.wrapperPath, 448).catch(() => void 0);
 }
-async function writeRuntimeSidecar(input) {
-  const value = {
-    mcp_package: MCP_RUNTIME_MANIFEST.mcpPackage,
-    mcp_version: MCP_RUNTIME_MANIFEST.mcpVersion,
-    sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
-    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
-    minimum_node_version: MCP_RUNTIME_MANIFEST.minimumNodeVersion,
-    wrapper_path: input.wrapperPath,
-    runtime_directory: input.runtimeDirectory,
-    npm_cache_directory: input.npmCacheDirectory,
-    cli_path: input.cliPath
+async function readRuntimeSidecar(credentialDirectory) {
+  try {
+    return JSON.parse(
+      await readFile(join(credentialDirectory, "signer-runtime.json"), "utf8")
+    );
+  } catch {
+    return null;
+  }
+}
+async function writeRuntimeSidecar(input) {
+  const value = {
+    signer_package: MCP_RUNTIME_MANIFEST.signerPackage,
+    signer_version: MCP_RUNTIME_MANIFEST.signerVersion,
+    sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
+    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    wrapper_path: input.wrapperPath,
+    runtime_directory: input.runtimeDirectory,
+    npm_cache_directory: input.npmCacheDirectory,
+    cli_path: input.cliPath
+  };
+  await writeFile(input.path, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  await chmod(input.path, 384).catch(() => void 0);
+}
+async function assertFileExists(path, label) {
+  try {
+    await access(path);
+  } catch {
+    throw new Error(`Missing ${label}: ${path}`);
+  }
+}
+var execFileAsync, SIGNER_INSTALL_TIMEOUT_MS, SIGNER_INSTALL_HEARTBEAT_MS;
+var init_signer_runtime = __esm({
+  "src/signer-runtime.ts"() {
+    init_runtime_manifest();
+    execFileAsync = promisify(execFile);
+    SIGNER_INSTALL_TIMEOUT_MS = 6e5;
+    SIGNER_INSTALL_HEARTBEAT_MS = 15e3;
+  }
+});
+
+// src/runtime-registry.ts
+function runtimeProfile(runtime, env = process.env) {
+  return RUNTIME_PROFILES[normalizeRuntime(runtime, env)];
+}
+function normalizeRuntime(runtime, env = process.env) {
+  const explicit = normalizeRuntimeName(runtime);
+  if (explicit) return explicit;
+  return detectRuntime(env) ?? "other";
+}
+function restartRequiredForRuntime(runtime, env = process.env) {
+  const mode = runtimeProfile(runtime, env).restartMode;
+  return mode === "restart-session" || mode === "restart-app";
+}
+function runtimeVerificationInstruction(runtime) {
+  const label = RUNTIME_PROFILES[runtime].label;
+  return `In ${label}, run the read-only \`haven_get_agent\` and \`haven_get_allowances\` tools to confirm the Haven wallet and live budget. Do not sign, fund, or create a payment to verify setup.`;
+}
+function normalizeRuntimeName(runtime) {
+  const key = runtime?.trim().toLowerCase();
+  if (!key) return null;
+  return RUNTIME_ALIASES[key.replace(/\s+/g, "-")] ?? null;
+}
+function detectRuntime(env) {
+  if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDECODE_CWD) return "claude-code";
+  if (env.CODEX_SANDBOX || env.CODEX_HOME || env.CODEX_CWD) return "codex-cli";
+  if (env.VSCODE_CWD || env.VSCODE_IPC_HOOK_CLI || env.TERM_PROGRAM === "vscode") return "vscode";
+  if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
+  return null;
+}
+var RUNTIME_PROFILES, RUNTIME_ALIASES;
+var init_runtime_registry = __esm({
+  "src/runtime-registry.ts"() {
+    RUNTIME_PROFILES = {
+      "claude-code": {
+        id: "claude-code",
+        label: "Claude Code",
+        restartMode: "restart-session",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Start a new Claude Code session so it loads the Haven MCP entries."
+      },
+      "codex-cli": {
+        id: "codex-cli",
+        label: "Codex CLI",
+        restartMode: "restart-session",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Start a fresh Codex CLI session (for example, run `codex resume --last`)."
+      },
+      "codex-desktop": {
+        id: "codex-desktop",
+        label: "Codex Desktop",
+        restartMode: "restart-session",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Quit and reopen Codex Desktop so it loads the Haven MCP entries."
+      },
+      cursor: {
+        id: "cursor",
+        label: "Cursor",
+        restartMode: "hot-reload",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Wait for Cursor to hot-reload the Haven MCP entries; no app restart is required."
+      },
+      vscode: {
+        id: "vscode",
+        label: "VS Code",
+        restartMode: "hot-reload",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Wait for VS Code to hot-reload the Haven MCP entries; no app restart is required."
+      },
+      "vscode-insiders": {
+        id: "vscode-insiders",
+        label: "VS Code Insiders",
+        restartMode: "hot-reload",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Wait for VS Code Insiders to hot-reload the Haven MCP entries; no app restart is required."
+      },
+      "claude-desktop": {
+        id: "claude-desktop",
+        label: "Claude Desktop",
+        restartMode: "restart-app",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Quit and reopen Claude Desktop so it loads the Haven MCP entries."
+      },
+      hermes: {
+        id: "hermes",
+        label: "Hermes Agent",
+        restartMode: "restart-session",
+        canWriteRuntimeConfig: true,
+        activationInstruction: "Start a new Hermes session; in Hermes Gateway, run `/restart` instead."
+      },
+      other: {
+        id: "other",
+        label: "Other agent runtime",
+        restartMode: "manual",
+        canWriteRuntimeConfig: false,
+        activationInstruction: "Finish the manual MCP setup shown above, then start a fresh session in that runtime."
+      }
+    };
+    RUNTIME_ALIASES = {
+      claude: "claude-code",
+      "claude-code": "claude-code",
+      claudecode: "claude-code",
+      "claude_code": "claude-code",
+      codex: "codex-cli",
+      "codex-cli": "codex-cli",
+      codexcli: "codex-cli",
+      "codex_cli": "codex-cli",
+      "codex-desktop": "codex-desktop",
+      "codex_desktop": "codex-desktop",
+      codexdesktop: "codex-desktop",
+      "codex-app": "codex-desktop",
+      "codex_app": "codex-desktop",
+      codexapp: "codex-desktop",
+      cursor: "cursor",
+      vscode: "vscode",
+      "vs-code": "vscode",
+      "vs_code": "vscode",
+      code: "vscode",
+      "vscode-insiders": "vscode-insiders",
+      "vscode_insiders": "vscode-insiders",
+      vscodeinsiders: "vscode-insiders",
+      "vs-code-insiders": "vscode-insiders",
+      "code-insiders": "vscode-insiders",
+      insiders: "vscode-insiders",
+      "claude-desktop": "claude-desktop",
+      "claude_desktop": "claude-desktop",
+      claudesktop: "claude-desktop",
+      desktop: "claude-desktop",
+      hermes: "hermes",
+      "hermes-agent": "hermes",
+      hermes_agent: "hermes",
+      hermesagent: "hermes",
+      other: "other",
+      manual: "other"
+    };
+  }
+});
+async function acknowledgeLocalSignerConsent(signerPath, log) {
+  try {
+    const input = await buildSignerConsentInput(signerPath);
+    const decision = await ensureSignerConsent(input, {
+      credentialsPath: signerPath,
+      writeAck: true,
+      out: log ? { write: (chunk) => writeLogChunk2(log, chunk) } : void 0
+    });
+    return {
+      acknowledged: decision.ok,
+      hash: decision.hash,
+      reason: decision.reason
+    };
+  } catch (err) {
+    return {
+      acknowledged: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function getLocalSignerConsentStatus(signerPath) {
+  try {
+    const input = await buildSignerConsentInput(signerPath);
+    const hash = computeSignerConsentHash(input);
+    const stored = await readSignerAckFile(signerAckPath(signerPath));
+    if (stored === hash) {
+      return { acknowledged: true, hash, reason: "ack_file_match" };
+    }
+    return {
+      acknowledged: false,
+      hash,
+      reason: stored ? "ack_file_mismatch" : "ack_file_missing"
+    };
+  } catch (err) {
+    return {
+      acknowledged: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function signerAckPath(signerPath) {
+  return resolve(`${signerPath}.signer-ack.json`);
+}
+async function buildSignerConsentInput(signerPath) {
+  const credentials = await loadSignerCredentials(signerPath);
+  const signer = createEdgeSigner(credentials.delegateKey, {
+    x402BindingSigner: credentials.x402BindingSigner
+  });
+  return {
+    delegateAddress: signer.delegateAddress,
+    safeAddress: credentials.safeAddress,
+    agentId: credentials.agentId,
+    chainId: credentials.chainId,
+    network: credentials.network,
+    toolNames: Object.keys(toolSchemas)
+  };
+}
+async function readSignerAckFile(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return typeof parsed.ack === "string" ? parsed.ack : null;
+  } catch {
+    return null;
+  }
+}
+function writeLogChunk2(log, chunk) {
+  const message = String(chunk).trimEnd();
+  if (message) log(message);
+}
+var init_signer_consent = __esm({
+  "src/signer-consent.ts"() {
+  }
+});
+
+// src/doctor.ts
+var doctor_exports = {};
+__export(doctor_exports, {
+  runDoctor: () => runDoctor,
+  runRepair: () => runRepair
+});
+async function discoverCredentialDirectory(homeDir, explicit) {
+  if (explicit) return { directory: explicit };
+  const root = join(homeDir, ".haven", "agents");
+  let entries = [];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return {};
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    const directory = join(root, entry);
+    try {
+      const s = await stat(join(directory, "identity.json"));
+      candidates.push({ directory, mtimeMs: s.mtimeMs });
+    } catch {
+    }
+  }
+  if (candidates.length === 0) return {};
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return {
+    directory: candidates[0].directory,
+    note: candidates.length > 1 ? `${candidates.length} agent credential dirs found; examining the newest.` : void 0
+  };
+}
+async function runDoctor(input, deps = {}) {
+  const homeDir = deps.homeDir ?? homedir();
+  const checks = [];
+  let signerCapabilities;
+  const { directory, note } = await discoverCredentialDirectory(homeDir, input.credentialsDir);
+  let identity;
+  let signerParses = false;
+  if (!directory) {
+    checks.push({
+      id: "credentials",
+      label: "Agent credentials",
+      ok: false,
+      detail: "No agent credential directory with an identity.json under ~/.haven/agents.",
+      repair: `Run the full setup once: ${RERUN} --setup <token from the Haven dashboard>.`
+    });
+  } else {
+    try {
+      identity = JSON.parse(await readFile(join(directory, "identity.json"), "utf8"));
+    } catch {
+      identity = void 0;
+    }
+    try {
+      const signer = JSON.parse(await readFile(join(directory, "signer.json"), "utf8"));
+      signerParses = typeof signer === "object" && signer !== null;
+    } catch {
+      signerParses = false;
+    }
+    const ok = Boolean(identity?.api_key) && signerParses;
+    checks.push({
+      id: "credentials",
+      label: "Agent credentials",
+      ok,
+      detail: ok ? `identity.json and signer.json parse (agent ${identity?.agent_id ?? "unknown"})${note ? ` \u2014 ${note}` : ""}` : "identity.json or signer.json is missing or unparseable.",
+      ...ok ? {} : { repair: `Re-run the full setup with a fresh token: ${RERUN} --setup <token>.` }
+    });
+  }
+  let sidecar = null;
+  if (directory) {
+    sidecar = await readRuntimeSidecar(directory);
+    if (!sidecar) {
+      checks.push({
+        id: "signer_runtime",
+        label: "Signer runtime (preinstalled wrapper)",
+        ok: false,
+        detail: "No signer-runtime.json sidecar \u2014 the pinned signer runtime was never prepared (or a pre-#1586 npx config).",
+        repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}`
+      });
+    } else {
+      const matches = await installedRuntimeMatches(sidecar.runtime_directory, sidecar.cli_path);
+      const versionOk = sidecar.signer_version === MCP_RUNTIME_MANIFEST.signerVersion;
+      const ok = matches && versionOk;
+      checks.push({
+        id: "signer_runtime",
+        label: "Signer runtime (preinstalled wrapper)",
+        ok,
+        detail: ok ? `Installed ${sidecar.signer_package}@${sidecar.signer_version} at ${sidecar.runtime_directory}` : matches ? `Installed version ${sidecar.signer_version} does not match the connector's pinned ${MCP_RUNTIME_MANIFEST.signerVersion}.` : `Runtime directory is stale or empty (${sidecar.runtime_directory}) \u2014 the CLI or package versions are missing.`,
+        ...ok ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}` }
+      });
+    }
+  }
+  const configPath = runtimeConfigPathFor(input.runtime, homeDir);
+  if (configPath === null) {
+    checks.push({
+      id: "runtime_config",
+      label: "Runtime MCP config",
+      ok: true,
+      detail: `Runtime '${input.runtime}' has no file-based config the connector owns (CLI-managed) \u2014 skipping the file check.`
+    });
+  } else {
+    let configText = null;
+    try {
+      configText = await readFile(configPath, "utf8");
+    } catch {
+      configText = null;
+    }
+    if (configText === null) {
+      checks.push({
+        id: "runtime_config",
+        label: "Runtime MCP config",
+        ok: false,
+        detail: `No runtime config at ${configPath}.`,
+        repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}`
+      });
+    } else {
+      const hasHaven = identity?.hosted_mcp_url ? configText.includes(identity.hosted_mcp_url) : configText.includes("haven");
+      const signerViaNpx = configText.includes("@haven_ai/signer");
+      const wrapperReferenced = sidecar ? configText.includes(sidecar.wrapper_path) : false;
+      const ok = hasHaven && !signerViaNpx && (sidecar ? wrapperReferenced : true);
+      checks.push({
+        id: "runtime_config",
+        label: "Runtime MCP config",
+        ok,
+        detail: ok ? `Config at ${configPath} references the hosted server and the prepared signer wrapper.` : signerViaNpx ? `Config at ${configPath} still launches the signer via npx \u2014 the pre-#1586 shape that cannot start under a 120s startup timeout.` : `Config at ${configPath} is missing the Haven entries${sidecar && !wrapperReferenced ? " (or references a different signer wrapper)" : ""}.`,
+        ...ok ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}` }
+      });
+    }
+  }
+  if (identity?.api_key && (identity.hosted_mcp_url || identity.api_url)) {
+    const hostedUrl = identity.hosted_mcp_url ?? `${identity.api_url}/mcp`;
+    const probe = await (deps.probeHosted ?? probeHostedMcpTools)(identity.api_key, hostedUrl, deps.fetch);
+    checks.push({
+      id: "hosted_mcp",
+      label: "Hosted Haven MCP",
+      ok: probe.status === "ok",
+      detail: probe.status === "ok" ? `Reachable and authorized (${hostedUrl}).` : `Probe failed: ${probe.status} (${hostedUrl}).`,
+      ...probe.status === "ok" ? {} : {
+        repair: probe.status === "unauthorized" ? `The stored API key was rejected \u2014 re-run the full setup with a fresh token: ${RERUN} --setup <token>.` : "Check network access to the hosted MCP URL, then re-run --doctor."
+      }
+    });
+  } else {
+    checks.push({
+      id: "hosted_mcp",
+      label: "Hosted Haven MCP",
+      ok: false,
+      detail: "No stored API key / hosted MCP URL to probe with.",
+      repair: `Re-run the full setup: ${RERUN} --setup <token>.`
+    });
+  }
+  if (sidecar && directory) {
+    const consent = await getLocalSignerConsentStatus(join(directory, "signer.json"));
+    if (!consent.acknowledged) {
+      checks.push({
+        id: "signer_process",
+        label: "Signer stdio handshake",
+        ok: false,
+        detail: "The local-tools consent is not acknowledged, so the signer refuses to start (by design).",
+        repair: `Run: ${RERUN} --ack-local-tools --setup <token>  (or re-run your original setup command with --ack-local-tools).`
+      });
+    } else {
+      const probe = await (deps.probeSignerTools ?? probeLocalMcpTools)(
+        sidecar.wrapper_path,
+        [],
+        MCP_RUNTIME_MANIFEST.requiredSignerTools
+      );
+      const experimental = probe.capabilities?.experimental ?? probe.capabilities;
+      const compat = experimental?.["haven/signer-compatibility"];
+      signerCapabilities = compat ? { "haven/signer-compatibility": compat } : void 0;
+      const compatDetail = compat ? ` Compat: x402 expected-context v${JSON.stringify(compat.x402_expected_context_versions ?? "?")}.` : "";
+      checks.push({
+        id: "signer_process",
+        label: "Signer stdio handshake",
+        ok: probe.status === "ok",
+        detail: probe.status === "ok" ? `Signer started, listed ${probe.toolNames?.length ?? 0} tools${probe.serverInfo?.version ? ` (v${probe.serverInfo.version})` : ""}.${compatDetail}` : `Handshake failed: ${probe.status}.`,
+        ...probe.status === "ok" ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}` }
+      });
+    }
+  } else if (directory) {
+    checks.push({
+      id: "signer_process",
+      label: "Signer stdio handshake",
+      ok: false,
+      detail: "Skipped \u2014 no prepared signer runtime to probe.",
+      repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}`
+    });
+  }
+  const restart = restartRequiredForRuntime(input.runtime, deps.env);
+  checks.push({
+    id: "restart",
+    label: "Runtime restart",
+    ok: true,
+    detail: restart ? "This runtime loads MCP config at startup \u2014 restart it after any repair before expecting the tools to appear." : "No restart requirement known for this runtime."
+  });
+  return {
+    version: 1,
+    ok: checks.every((check) => check.ok),
+    runtime: input.runtime,
+    credentialDirectory: directory,
+    checks,
+    ...signerCapabilities ? { signerCapabilities } : {}
+  };
+}
+async function runRepair(input, deps = {}) {
+  const homeDir = deps.homeDir ?? homedir();
+  const messages = [];
+  const { directory, note } = await discoverCredentialDirectory(homeDir, input.credentialsDir);
+  if (note) messages.push(`Note: ${note}`);
+  if (!directory) {
+    return {
+      ok: false,
+      messages: [`No agent credentials found to repair \u2014 run the full setup: ${RERUN} --setup <token>.`]
+    };
+  }
+  let identity;
+  try {
+    identity = JSON.parse(await readFile(join(directory, "identity.json"), "utf8"));
+  } catch {
+    return { ok: false, messages: ["identity.json is unreadable \u2014 re-run the full setup with a fresh token."] };
+  }
+  if (!identity.api_key || !(identity.hosted_mcp_url || identity.api_url)) {
+    return { ok: false, messages: ["identity.json lacks the stored API key / hosted URL \u2014 re-run the full setup."] };
+  }
+  const configPath = runtimeConfigPathFor(input.runtime, homeDir);
+  if (configPath) {
+    try {
+      const existing = await readFile(configPath, "utf8");
+      if (existing.includes("bin/haven-mcp") || existing.includes(".haven/mcp-runtime")) {
+        return {
+          ok: false,
+          messages: [
+            `The config at ${configPath} is the LOCAL-stdio topology (--local). Repair currently rewrites only the hosted+signer shape and will not touch it.`,
+            "Re-run your original setup command (with --local) to repair a local-stdio install."
+          ]
+        };
+      }
+    } catch {
+    }
+  }
+  const signerPath = join(directory, "signer.json");
+  const prepared = await prepareSignerRuntime(
+    { credentialDirectory: directory, signerPath, homeDir },
+    { runCommand: deps.runCommand }
+  );
+  messages.push(...prepared.messages);
+  const configResult = await writeRuntimeConfig({
+    runtime: input.runtime,
+    hostedMcpUrl: identity.hosted_mcp_url ?? `${identity.api_url}/mcp`,
+    apiKey: identity.api_key,
+    identityPath: join(directory, "identity.json"),
+    signerPath,
+    credentialDirectory: directory,
+    signerCommand: { command: prepared.command, args: prepared.args },
+    homeDir,
+    mode: "hosted"
+  });
+  messages.push(...configResult.messages);
+  messages.push("Repair complete \u2014 restart the runtime, then verify with --doctor.");
+  return { ok: true, messages };
+}
+var RERUN;
+var init_doctor = __esm({
+  "src/doctor.ts"() {
+    init_runtime_manifest();
+    init_probes();
+    init_signer_runtime();
+    init_config_writers();
+    init_runtime_registry();
+    init_signer_consent();
+    RERUN = "npx @haven_ai/connect@alpha";
+  }
+});
+
+// src/api.ts
+function createConnectApiClient(baseUrl, fetchImpl = fetch) {
+  const root = baseUrl.replace(/\/+$/, "");
+  return {
+    resolveSetup: (input) => request(fetchImpl, `${root}/agent-connection-setups/resolve`, {
+      method: "POST",
+      body: JSON.stringify({
+        setup_token: input.setupToken,
+        connector_version: input.connectorVersion,
+        runtime: input.runtime
+      })
+    }),
+    registerSetup: (input) => request(fetchImpl, `${root}/agent-connection-setups/register`, {
+      method: "POST",
+      body: JSON.stringify({
+        setup_token: input.setupToken,
+        challenge_id: input.challengeId,
+        delegate_address: input.delegateAddress,
+        proof_signature: input.proofSignature,
+        api_key_hash: input.apiKeyHash,
+        api_key_prefix: input.apiKeyPrefix,
+        runtime: input.runtime,
+        connector_version: input.connectorVersion,
+        connector_context: input.connectorContext,
+        install_capabilities: input.installCapabilities && {
+          can_write_runtime_config: input.installCapabilities.canWriteRuntimeConfig,
+          restart_required: input.installCapabilities.restartRequired
+        }
+      })
+    }),
+    getConnectorStatus: (setupId, apiKey) => request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/connector-status`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${apiKey}` }
+    }),
+    updateInstallStatus: async (setupId, apiKey, input) => {
+      await request(fetchImpl, `${root}/agent-connection-setups/${encodeURIComponent(setupId)}/install-status`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify({
+          runtime: input.runtime,
+          connector_version: input.connectorVersion,
+          runtime_mcp_mode: input.runtimeMcpMode,
+          hosted_mcp_configured: input.hostedMcpConfigured,
+          local_signer_configured: input.localSignerConfigured,
+          local_mcp_configured: input.localMcpConfigured,
+          credential_files_written: input.credentialFilesWritten,
+          signer_acknowledged: input.signerAcknowledged,
+          local_mcp_acknowledged: input.localMcpAcknowledged,
+          activation_command_available: input.activationCommandAvailable,
+          skill_installed: input.skillInstalled,
+          probe_result: input.probeResult,
+          restart_required: input.restartRequired,
+          next_user_action: input.nextUserAction,
+          error_code: input.errorCode ?? null,
+          environment_label: input.environmentLabel
+        })
+      });
+    }
+  };
+}
+var ConnectRequestError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "ConnectRequestError";
+  }
+  status;
+};
+async function request(fetchImpl, url, init) {
+  const response = await fetchImpl(url, {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...init.headers ?? {}
+    }
+  });
+  const text = await response.text();
+  const body = text ? JSON.parse(text) : null;
+  if (!response.ok) {
+    const message = body?.error ?? body?.message ?? `${response.status} ${response.statusText}`;
+    throw new ConnectRequestError(`Haven setup request failed: ${message}`, response.status);
+  }
+  return body;
+}
+function generateDelegateKey() {
+  return delegateKeyFromPrivateKey(Wallet.createRandom().privateKey);
+}
+function delegateKeyFromPrivateKey(privateKey) {
+  const wallet = new Wallet(privateKey);
+  return {
+    privateKey: wallet.privateKey,
+    address: wallet.address,
+    signChallenge: (message) => wallet.signMessage(message)
+  };
+}
+function generateAgentApiKey() {
+  return `sk_agent_${crypto.randomBytes(24).toString("hex")}`;
+}
+function hashAgentApiKey(apiKey) {
+  return crypto.createHash("sha256").update(apiKey).digest("hex");
+}
+function agentApiKeyPrefix(apiKey) {
+  return apiKey.slice(0, 12);
+}
+
+// src/redact.ts
+var API_KEY_RE = /sk_agent_[A-Za-z0-9]+/g;
+var PRIVATE_KEY_RE = /0x[0-9a-fA-F]{64}/g;
+function redactSecrets(value) {
+  return value.replace(API_KEY_RE, "sk_agent_[redacted]").replace(PRIVATE_KEY_RE, "0x[redacted-private-key]");
+}
+function shortAddress(address) {
+  if (!/^0x[0-9a-fA-F]{40}$/.test(address)) return address;
+  return `${address.slice(0, 6)}...${address.slice(-4)}`;
+}
+async function preflightCredentialStorage(input = {}) {
+  const directory = defaultCredentialRoot(input.baseDir);
+  await mkdir(directory, { recursive: true, mode: 448 });
+  await restrictPermissions(directory, 448, input.warn);
+  const probePath = join(directory, `.haven-connect-preflight-${crypto.randomBytes(8).toString("hex")}`);
+  try {
+    await writeOwnerOnlyJson(probePath, { ok: true }, input.warn);
+  } finally {
+    await rm(probePath, { force: true }).catch(() => void 0);
+  }
+  return directory;
+}
+async function writeCredentialFiles(input) {
+  const directory = defaultAgentDirectory(input.agentId, input.baseDir);
+  await mkdir(directory, { recursive: true, mode: 448 });
+  await restrictPermissions(directory, 448, input.warn);
+  const identityPath = join(directory, "identity.json");
+  const signerPath = join(directory, "signer.json");
+  const agentPath = join(directory, "agent.json");
+  await assertDoesNotExist(identityPath);
+  await assertDoesNotExist(signerPath);
+  await assertDoesNotExist(agentPath);
+  await writeOwnerOnlyJson(
+    signerPath,
+    {
+      delegate_key: input.delegateKey,
+      delegate_address: input.delegateAddress,
+      agent_id: input.agentId,
+      safe_address: input.safeAddress,
+      chain_id: input.chainId,
+      network: input.network,
+      x402_binding_signer: input.x402BindingSigner,
+      note: "Local signer credential. Haven backend never receives this private key."
+    },
+    input.warn
+  );
+  try {
+    await writeOwnerOnlyJson(
+      identityPath,
+      {
+        api_key: input.apiKey,
+        agent_id: input.agentId,
+        safe_address: input.safeAddress,
+        chain_id: input.chainId,
+        network: input.network,
+        api_url: input.apiUrl,
+        hosted_mcp_url: input.hostedMcpUrl,
+        agent_budget: input.agentBudget,
+        note: "Haven API key identifies the agent only. It cannot spend without the local signer key and on-chain Haven wallet rules."
+      },
+      input.warn
+    );
+  } catch (err) {
+    await rm(signerPath, { force: true }).catch(() => void 0);
+    throw err;
+  }
+  try {
+    await writeOwnerOnlyJson(
+      agentPath,
+      {
+        agent_id: input.agentId,
+        delegate_address: input.delegateAddress,
+        safe_address: input.safeAddress,
+        chain_id: input.chainId,
+        network: input.network,
+        agent_budget: input.agentBudget,
+        note: "Non-secret orientation for the agent: public delegate/Haven wallet identity + configured budget. Contains no API key or signing key. For the live remaining budget, call haven_get_allowances."
+      },
+      input.warn
+    );
+  } catch (err) {
+    await rm(signerPath, { force: true }).catch(() => void 0);
+    await rm(identityPath, { force: true }).catch(() => void 0);
+    await rm(agentPath, { force: true }).catch(() => void 0);
+    throw err;
+  }
+  return { directory, identityPath, signerPath, agentPath };
+}
+function defaultAgentDirectory(agentId, baseDir = join(homedir(), ".haven", "agents")) {
+  return resolve(defaultCredentialRoot(baseDir), safePathPart(agentId));
+}
+function defaultCredentialRoot(baseDir = join(homedir(), ".haven", "agents")) {
+  return resolve(baseDir);
+}
+async function writeOwnerOnlyJson(path, value, warn) {
+  const json = JSON.stringify(dropUndefined(value), null, 2);
+  await writeFile(path, `${json}
+`, { mode: 384, flag: "wx" });
+  await restrictPermissions(path, 384, warn);
+}
+function safePathPart(value) {
+  return value.replace(/[^A-Za-z0-9_.-]/g, "_");
+}
+function dropUndefined(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, field]) => field !== void 0));
+}
+async function assertDoesNotExist(path) {
+  try {
+    await access(path);
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") return;
+    throw err;
+  }
+  throw new Error(`Refusing to overwrite existing Haven credential file: ${path}`);
+}
+async function restrictPermissions(path, mode, warn) {
+  try {
+    await chmod(path, mode);
+  } catch (err) {
+    warn?.(
+      `Warning: could not restrict permissions on ${path} to ${mode.toString(8)}. Move this credential to a private location or run chmod ${mode.toString(8)} ${path}. ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+// src/runtime-install.ts
+init_config_writers();
+async function acknowledgeLocalMcpConsent(identityPath, signerPath, log) {
+  try {
+    const input = await buildLocalMcpConsentInput(identityPath, signerPath);
+    const decision = await ensureConsent(input, {
+      credentialsPath: identityPath,
+      writeAck: true,
+      out: log ? { write: (chunk) => writeLogChunk(log, chunk) } : void 0
+    });
+    return {
+      acknowledged: decision.ok,
+      hash: decision.hash,
+      reason: decision.reason
+    };
+  } catch (err) {
+    return {
+      acknowledged: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+async function getLocalMcpConsentStatus(identityPath, signerPath) {
+  try {
+    const input = await buildLocalMcpConsentInput(identityPath, signerPath);
+    const hash = computeConsentHash(input);
+    const stored = await readLocalMcpAckFile(localMcpAckPath(identityPath));
+    if (stored === hash) {
+      return { acknowledged: true, hash, reason: "ack_file_match" };
+    }
+    return {
+      acknowledged: false,
+      hash,
+      reason: stored ? "ack_file_mismatch" : "ack_file_missing"
+    };
+  } catch (err) {
+    return {
+      acknowledged: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+function localMcpAckPath(identityPath) {
+  return resolve(`${identityPath}.ack.json`);
+}
+async function buildLocalMcpConsentInput(identityPath, signerPath) {
+  const credentials = await loadCredentials({ identityPath, signerPath });
+  const unavailableDuringSetup = {
+    getAllowances: async () => {
+      throw new Error("Haven approval is not complete yet.");
+    }
   };
-  await writeFile(input.path, `${JSON.stringify(value, null, 2)}
-`, { mode: 384 });
-  await chmod(input.path, 384).catch(() => void 0);
+  return consentInputFromClient(
+    unavailableDuringSetup,
+    {
+      apiKey: credentials.apiKey,
+      apiUrl: credentials.apiUrl,
+      agentId: credentials.agentId,
+      safeAddress: credentials.safeAddress,
+      delegateAddress: credentials.delegateAddress,
+      chainId: credentials.chainId,
+      allowanceSummary: credentials.allowanceSummary
+    },
+    registeredToolNames()
+  );
 }
-async function assertFileExists(path, label) {
+async function readLocalMcpAckFile(path) {
   try {
-    await access(path);
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return typeof parsed.ack === "string" ? parsed.ack : null;
   } catch {
-    throw new Error(`Missing ${label}: ${path}`);
+    return null;
   }
 }
+function writeLogChunk(log, chunk) {
+  const message = String(chunk).trimEnd();
+  if (message) log(message);
+}
+
+// src/runtime-install.ts
+init_probes();
+
+// src/local-mcp-runtime.ts
+init_signer_runtime();
+init_runtime_manifest();
 var execFileAsync2 = promisify(execFile);
-async function prepareSignerRuntime(input, deps = {}) {
+var UnsupportedNodeVersionError = class extends Error {
+  code = "local_mcp_unsupported_node_version";
+  nodeVersion;
+  minimumNodeVersion;
+  constructor(nodeVersion, minimumNodeVersion, subject = "Haven setup") {
+    super(unsupportedNodeVersionMessage({ subject, nodeVersion, minimumNodeVersion }));
+    this.name = "UnsupportedNodeVersionError";
+    this.nodeVersion = nodeVersion;
+    this.minimumNodeVersion = minimumNodeVersion;
+  }
+};
+async function prepareLocalMcpRuntime(input, deps = {}) {
+  assertSupportedNodeVersion(input.nodeVersion);
   const homeDir = input.homeDir ?? homedir();
-  const runtimeDirectory = resolve(homeDir, ".haven", "signer-runtime", MCP_RUNTIME_MANIFEST.signerVersion);
+  const runtimeDirectory = resolve(homeDir, ".haven", "mcp-runtime", MCP_RUNTIME_MANIFEST.mcpVersion);
   const npmCacheDirectory = resolve(homeDir, ".haven", "npm-cache");
-  const cliPath = join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "dist", "cli.js");
+  const cliPath = join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "dist", "cli.js");
   const messages = [];
   await mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await chmod(runtimeDirectory, 448).catch(() => void 0);
   await mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await chmod(npmCacheDirectory, 448).catch(() => void 0);
   if (await installedRuntimeMatches2(runtimeDirectory, cliPath)) {
-    messages.push(`Using existing local Haven signer runtime ${signerPackageSpec()}.`);
+    messages.push(`Using existing local Haven MCP runtime ${mcpPackageSpec()}.`);
   } else {
-    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps.runCommand);
-    messages.push(`Installed local Haven signer runtime ${signerPackageSpec()}.`);
+    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps);
+    messages.push(`Installed local Haven MCP runtime ${mcpPackageSpec()}.`);
   }
-  await assertFileExists2(cliPath, "local Haven signer CLI");
-  const wrapperPath = join(input.credentialDirectory, "bin", "haven-signer.mjs");
-  await writeWrapper2({ wrapperPath, cliPath, signerPath: input.signerPath });
+  await assertFileExists2(cliPath, "local Haven MCP CLI");
+  const wrapperPath = join(input.credentialDirectory, "bin", "haven-mcp");
+  await writeWrapper2({
+    wrapperPath,
+    cliPath,
+    identityPath: input.identityPath,
+    signerPath: input.signerPath
+  });
   await writeRuntimeSidecar2({
-    path: join(input.credentialDirectory, "signer-runtime.json"),
+    path: join(input.credentialDirectory, "mcp-runtime.json"),
     wrapperPath,
     runtimeDirectory,
     npmCacheDirectory,
     cliPath
   });
-  messages.push(`Prepared stable local Haven signer wrapper: ${wrapperPath}`);
+  messages.push(`Prepared stable local Haven MCP wrapper: ${wrapperPath}`);
   return {
     command: wrapperPath,
     args: [],
@@ -1315,7 +1884,13 @@ async function prepareSignerRuntime(input, deps = {}) {
     messages
   };
 }
-async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, runCommand) {
+function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = MCP_RUNTIME_MANIFEST.minimumNodeVersion, subject = "Haven setup") {
+  if (!isSupportedNodeVersion(nodeVersion, minimumNodeVersion)) {
+    throw new UnsupportedNodeVersionError(nodeVersion, minimumNodeVersion, subject);
+  }
+}
+async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps) {
+  const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
     "--prefix",
@@ -1324,12 +1899,22 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, runC
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    signerPackageSpec(),
+    mcpPackageSpec(),
     sdkPackageSpec()
   ];
   const run = async (args) => {
-    if (runCommand) await runCommand("npm", args);
-    else await execFileAsync2("npm", args, { timeout: 12e4, maxBuffer: 1024 * 1024 });
+    const startedAt = Date.now();
+    const heartbeat = setInterval(() => {
+      const seconds = Math.round((Date.now() - startedAt) / 1e3);
+      onProgress?.(`Still installing the local Haven MCP runtime\u2026 (${seconds}s \u2014 a cold cache can take several minutes)`);
+    }, SIGNER_INSTALL_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    try {
+      if (runCommand) await runCommand("npm", args);
+      else await execFileAsync2("npm", args, { timeout: SIGNER_INSTALL_TIMEOUT_MS, maxBuffer: 1024 * 1024 });
+    } finally {
+      clearInterval(heartbeat);
+    }
   };
   try {
     await run(baseArgs);
@@ -1337,20 +1922,18 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, runC
     try {
       await run([...baseArgs, "--cache", npmCacheDirectory]);
     } catch (err) {
-      throw new Error(
-        `Could not install local Haven signer runtime ${signerPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`
-      );
+      throw new Error(`Could not install local Haven MCP runtime ${mcpPackageSpec()}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 }
 async function installedRuntimeMatches2(runtimeDirectory, cliPath) {
   try {
-    await assertFileExists2(cliPath, "local Haven signer CLI");
-    const [signerPackage, sdkPackage] = await Promise.all([
-      readPackageJson2(join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
+    await assertFileExists2(cliPath, "local Haven MCP CLI");
+    const [mcpPackage, sdkPackage] = await Promise.all([
+      readPackageJson2(join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
       readPackageJson2(join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
     ]);
-    return signerPackage.version === MCP_RUNTIME_MANIFEST.signerVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    return mcpPackage.version === MCP_RUNTIME_MANIFEST.mcpVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
   } catch {
     return false;
   }
@@ -1366,9 +1949,10 @@ async function writeWrapper2(input) {
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
+    `const identityPath = ${JSON.stringify(input.identityPath)}`,
     `const signerPath = ${JSON.stringify(input.signerPath)}`,
     "",
-    "const child = spawn(process.execPath, [cliPath, '--credentials', signerPath, ...process.argv.slice(2)], {",
+    "const child = spawn(process.execPath, [cliPath, '--identity', identityPath, '--signer', signerPath, ...process.argv.slice(2)], {",
     "  stdio: 'inherit',",
     "})",
     "",
@@ -1383,10 +1967,11 @@ async function writeWrapper2(input) {
 }
 async function writeRuntimeSidecar2(input) {
   const value = {
-    signer_package: MCP_RUNTIME_MANIFEST.signerPackage,
-    signer_version: MCP_RUNTIME_MANIFEST.signerVersion,
+    mcp_package: MCP_RUNTIME_MANIFEST.mcpPackage,
+    mcp_version: MCP_RUNTIME_MANIFEST.mcpVersion,
     sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
     sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    minimum_node_version: MCP_RUNTIME_MANIFEST.minimumNodeVersion,
     wrapper_path: input.wrapperPath,
     runtime_directory: input.runtimeDirectory,
     npm_cache_directory: input.npmCacheDirectory,
@@ -1403,6 +1988,10 @@ async function assertFileExists2(path, label) {
     throw new Error(`Missing ${label}: ${path}`);
   }
 }
+
+// src/runtime-install.ts
+init_signer_runtime();
+init_runtime_manifest();
 var CODEX_AGENTS_BEGIN_MARKER = "<!-- BEGIN haven-pay (managed by @haven_ai/connect; edits inside this section are overwritten on re-setup) -->";
 var CODEX_AGENTS_END_MARKER = "<!-- END haven-pay -->";
 async function installSkillForRuntime(runtime, deps = {}) {
@@ -1507,208 +2096,9 @@ function hermesHome(deps) {
   return env.HERMES_HOME ?? join(deps.homeDir ?? homedir(), ".hermes");
 }
 
-// src/runtime-registry.ts
-var RUNTIME_PROFILES = {
-  "claude-code": {
-    id: "claude-code",
-    label: "Claude Code",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Start a new Claude Code session so it loads the Haven MCP entries."
-  },
-  "codex-cli": {
-    id: "codex-cli",
-    label: "Codex CLI",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Start a fresh Codex CLI session (for example, run `codex resume --last`)."
-  },
-  "codex-desktop": {
-    id: "codex-desktop",
-    label: "Codex Desktop",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Quit and reopen Codex Desktop so it loads the Haven MCP entries."
-  },
-  cursor: {
-    id: "cursor",
-    label: "Cursor",
-    restartMode: "hot-reload",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Wait for Cursor to hot-reload the Haven MCP entries; no app restart is required."
-  },
-  vscode: {
-    id: "vscode",
-    label: "VS Code",
-    restartMode: "hot-reload",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Wait for VS Code to hot-reload the Haven MCP entries; no app restart is required."
-  },
-  "vscode-insiders": {
-    id: "vscode-insiders",
-    label: "VS Code Insiders",
-    restartMode: "hot-reload",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Wait for VS Code Insiders to hot-reload the Haven MCP entries; no app restart is required."
-  },
-  "claude-desktop": {
-    id: "claude-desktop",
-    label: "Claude Desktop",
-    restartMode: "restart-app",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Quit and reopen Claude Desktop so it loads the Haven MCP entries."
-  },
-  hermes: {
-    id: "hermes",
-    label: "Hermes Agent",
-    restartMode: "restart-session",
-    canWriteRuntimeConfig: true,
-    activationInstruction: "Start a new Hermes session; in Hermes Gateway, run `/restart` instead."
-  },
-  other: {
-    id: "other",
-    label: "Other agent runtime",
-    restartMode: "manual",
-    canWriteRuntimeConfig: false,
-    activationInstruction: "Finish the manual MCP setup shown above, then start a fresh session in that runtime."
-  }
-};
-var RUNTIME_ALIASES = {
-  claude: "claude-code",
-  "claude-code": "claude-code",
-  claudecode: "claude-code",
-  "claude_code": "claude-code",
-  codex: "codex-cli",
-  "codex-cli": "codex-cli",
-  codexcli: "codex-cli",
-  "codex_cli": "codex-cli",
-  "codex-desktop": "codex-desktop",
-  "codex_desktop": "codex-desktop",
-  codexdesktop: "codex-desktop",
-  "codex-app": "codex-desktop",
-  "codex_app": "codex-desktop",
-  codexapp: "codex-desktop",
-  cursor: "cursor",
-  vscode: "vscode",
-  "vs-code": "vscode",
-  "vs_code": "vscode",
-  code: "vscode",
-  "vscode-insiders": "vscode-insiders",
-  "vscode_insiders": "vscode-insiders",
-  vscodeinsiders: "vscode-insiders",
-  "vs-code-insiders": "vscode-insiders",
-  "code-insiders": "vscode-insiders",
-  insiders: "vscode-insiders",
-  "claude-desktop": "claude-desktop",
-  "claude_desktop": "claude-desktop",
-  claudesktop: "claude-desktop",
-  desktop: "claude-desktop",
-  hermes: "hermes",
-  "hermes-agent": "hermes",
-  hermes_agent: "hermes",
-  hermesagent: "hermes",
-  other: "other",
-  manual: "other"
-};
-function runtimeProfile(runtime, env = process.env) {
-  return RUNTIME_PROFILES[normalizeRuntime(runtime, env)];
-}
-function normalizeRuntime(runtime, env = process.env) {
-  const explicit = normalizeRuntimeName(runtime);
-  if (explicit) return explicit;
-  return detectRuntime(env) ?? "other";
-}
-function restartRequiredForRuntime(runtime, env = process.env) {
-  const mode = runtimeProfile(runtime, env).restartMode;
-  return mode === "restart-session" || mode === "restart-app";
-}
-function runtimeVerificationInstruction(runtime) {
-  const label = RUNTIME_PROFILES[runtime].label;
-  return `In ${label}, run the read-only \`haven_get_agent\` and \`haven_get_allowances\` tools to confirm the Haven wallet and live budget. Do not sign, fund, or create a payment to verify setup.`;
-}
-function normalizeRuntimeName(runtime) {
-  const key = runtime?.trim().toLowerCase();
-  if (!key) return null;
-  return RUNTIME_ALIASES[key.replace(/\s+/g, "-")] ?? null;
-}
-function detectRuntime(env) {
-  if (env.CLAUDECODE || env.CLAUDE_CODE || env.CLAUDECODE_CWD) return "claude-code";
-  if (env.CODEX_SANDBOX || env.CODEX_HOME || env.CODEX_CWD) return "codex-cli";
-  if (env.VSCODE_CWD || env.VSCODE_IPC_HOOK_CLI || env.TERM_PROGRAM === "vscode") return "vscode";
-  if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
-  return null;
-}
-async function acknowledgeLocalSignerConsent(signerPath, log) {
-  try {
-    const input = await buildSignerConsentInput(signerPath);
-    const decision = await ensureSignerConsent(input, {
-      credentialsPath: signerPath,
-      writeAck: true,
-      out: log ? { write: (chunk) => writeLogChunk2(log, chunk) } : void 0
-    });
-    return {
-      acknowledged: decision.ok,
-      hash: decision.hash,
-      reason: decision.reason
-    };
-  } catch (err) {
-    return {
-      acknowledged: false,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-async function getLocalSignerConsentStatus(signerPath) {
-  try {
-    const input = await buildSignerConsentInput(signerPath);
-    const hash = computeSignerConsentHash(input);
-    const stored = await readSignerAckFile(signerAckPath(signerPath));
-    if (stored === hash) {
-      return { acknowledged: true, hash, reason: "ack_file_match" };
-    }
-    return {
-      acknowledged: false,
-      hash,
-      reason: stored ? "ack_file_mismatch" : "ack_file_missing"
-    };
-  } catch (err) {
-    return {
-      acknowledged: false,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-function signerAckPath(signerPath) {
-  return resolve(`${signerPath}.signer-ack.json`);
-}
-async function buildSignerConsentInput(signerPath) {
-  const credentials = await loadSignerCredentials(signerPath);
-  const signer = createEdgeSigner(credentials.delegateKey, {
-    x402BindingSigner: credentials.x402BindingSigner
-  });
-  return {
-    delegateAddress: signer.delegateAddress,
-    safeAddress: credentials.safeAddress,
-    agentId: credentials.agentId,
-    chainId: credentials.chainId,
-    network: credentials.network,
-    toolNames: Object.keys(toolSchemas)
-  };
-}
-async function readSignerAckFile(path) {
-  try {
-    const parsed = JSON.parse(await readFile(path, "utf8"));
-    return typeof parsed.ack === "string" ? parsed.ack : null;
-  } catch {
-    return null;
-  }
-}
-function writeLogChunk2(log, chunk) {
-  const message = String(chunk).trimEnd();
-  if (message) log(message);
-}
-
 // src/runtime-install.ts
+init_runtime_registry();
+init_signer_consent();
 var execFileAsync3 = promisify(execFile);
 async function installRuntime(input, deps = {}) {
   const runtime = normalizeRuntime(input.runtime, deps.env);
@@ -1784,9 +2174,28 @@ async function installRuntime(input, deps = {}) {
       signerCommand = { command: signerRuntime.command, args: signerRuntime.args };
       consentMessages.push(...signerRuntime.messages);
     } catch (err) {
-      consentMessages.push(
-        `Could not pre-install the local Haven signer; falling back to npx launch: ${err instanceof Error ? err.message : String(err)}`
-      );
+      return {
+        runtime,
+        runtimeMcpMode: "hosted_plus_signer",
+        hostedMcpConfigured: false,
+        localSignerConfigured: false,
+        localMcpConfigured: false,
+        probeResult: "signer_runtime_install_failed",
+        restartRequired: false,
+        nextUserAction: "The local Haven signer runtime could not be installed, so no configuration was written. Check your network (a cold install downloads the signer package set) and re-run: npx @haven_ai/connect@alpha",
+        errorCode: "signer_runtime_install_failed",
+        configTarget: profile.label,
+        signerAcknowledged: signerConsent?.acknowledged,
+        localMcpAcknowledged: localMcpConsent?.acknowledged,
+        activationCommand: void 0,
+        signerRuntimePrepared: false,
+        messages: [
+          ...consentMessages,
+          `Could not pre-install the local Haven signer: ${err instanceof Error ? err.message : String(err)}`,
+          "No runtime configuration was written (fail-closed): a config pointing at an uninstalled signer looks wired but cannot start.",
+          "Re-run `npx @haven_ai/connect@alpha` to retry the setup."
+        ]
+      };
     }
   }
   const signerRuntimePrepared = localRuntime ? void 0 : signerCommand !== void 0;
@@ -1803,19 +2212,51 @@ async function installRuntime(input, deps = {}) {
     homeDir: deps.homeDir,
     mode: localRuntime ? "local" : "hosted"
   });
+  if (deps.onRuntimeConfigured) {
+    const signerCredentialOnDisk = await probeLocalSignerCredential(input.signerPath);
+    const earlyLocalMcpOk = configResult.runtimeMcpMode === "local_stdio" && configResult.localMcpConfigured && signerCredentialOnDisk && Boolean(localMcpConsent?.acknowledged);
+    const earlySignerOk = configResult.runtimeMcpMode === "local_stdio" ? earlyLocalMcpOk : configResult.signerConfigured && signerCredentialOnDisk && Boolean(signerConsent?.acknowledged);
+    try {
+      await deps.onRuntimeConfigured({
+        runtime,
+        runtimeMcpMode: configResult.runtimeMcpMode,
+        hostedMcpConfigured: configResult.hostedConfigured,
+        localSignerConfigured: earlySignerOk,
+        localMcpConfigured: earlyLocalMcpOk,
+        signerAcknowledged: signerConsent?.acknowledged,
+        localMcpAcknowledged: localMcpConsent?.acknowledged,
+        restartRequired: configResult.restartRequired || restartRequiredForRuntime(runtime, deps.env),
+        nextUserAction: nextAction(runtime, profile.restartMode, configResult.errorCode),
+        errorCode: configResult.errorCode
+      });
+    } catch {
+    }
+  }
   progress("Almost there \u2014 just confirming everything connects\u2026");
   const localProbePromise = configResult.runtimeMcpMode === "local_stdio" && localRuntimeInstall ? runLocalMcpProbe(localRuntimeInstall, deps) : Promise.resolve(void 0);
-  const [hostedProbe, signerCredentialReady, localMcpProbe] = await Promise.all([
+  const signerProbePromise = configResult.runtimeMcpMode !== "local_stdio" && signerCommand ? (deps.probeSignerTools ?? probeLocalMcpTools)(
+    signerCommand.command,
+    signerCommand.args,
+    MCP_RUNTIME_MANIFEST.requiredSignerTools
+  ) : Promise.resolve(void 0);
+  const [hostedProbe, signerCredentialReady, localMcpProbe, signerProbe] = await Promise.all([
     configResult.hostedConfigured ? probeHostedMcpTools(input.apiKey, input.hostedMcpUrl, deps.fetch) : Promise.resolve({ status: "bad_response" }),
     probeLocalSignerCredential(input.signerPath),
-    localProbePromise
+    localProbePromise,
+    signerProbePromise
   ]);
   const hostedOk = configResult.hostedConfigured && hostedProbe.status === "ok";
   const localMcpOk = configResult.runtimeMcpMode === "local_stdio" && configResult.localMcpConfigured && signerCredentialReady && Boolean(localMcpConsent?.acknowledged) && localMcpProbe?.status === "ok";
-  const signerOk = configResult.runtimeMcpMode === "local_stdio" ? localMcpOk : configResult.signerConfigured && signerCredentialReady && Boolean(signerConsent?.acknowledged);
+  const signerOk = configResult.runtimeMcpMode === "local_stdio" ? localMcpOk : configResult.signerConfigured && signerCredentialReady && Boolean(signerConsent?.acknowledged) && // #1587: no handshake, no green. A signer command that was registered
+  // but not probed (manual topology) keeps the old semantics.
+  (signerProbe === void 0 || signerProbe.status === "ok");
   const restartRequired = configResult.restartRequired || restartRequiredForRuntime(runtime, deps.env);
-  const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : hostedMcpErrorCode(configResult.hostedConfigured, hostedProbe.status) ?? signerConsentErrorCode(signerCredentialReady, signerConsent));
+  const errorCode = configResult.errorCode ?? (configResult.runtimeMcpMode === "local_stdio" ? localMcpErrorCode(signerCredentialReady, localMcpConsent, localMcpProbe?.status) : hostedMcpErrorCode(configResult.hostedConfigured, hostedProbe.status) ?? signerConsentErrorCode(signerCredentialReady, signerConsent) ?? signerProbeErrorCode(signerProbe));
   const hostedProbeMessages = configResult.hostedConfigured && hostedProbe.status !== "ok" ? [`Hosted Haven MCP probe failed: ${hostedProbe.status}.`] : configResult.hostedConfigured ? ["Verified hosted Haven MCP tools with a read-only handshake."] : [];
+  const signerProbeMessages = signerProbe ? signerProbe.status === "ok" ? ["Verified local Haven signer with a stdio handshake."] : [
+    `Local Haven signer handshake failed: ${signerProbe.status}.`,
+    "Re-run `npx @haven_ai/connect@alpha` to repair the signer setup."
+  ] : [];
   const localProbeMessages = localMcpProbe && localMcpProbe.status !== "ok" ? [`Local Haven MCP handshake failed: ${localMcpProbe.status}.`] : localMcpProbe?.status === "ok" ? ["Verified local Haven MCP tools with a stdio handshake."] : [];
   const skillInstall = !configResult.errorCode ? await installSkillForRuntime(runtime, { homeDir: deps.homeDir, env: deps.env }) : void 0;
   return {
@@ -1834,7 +2275,7 @@ async function installRuntime(input, deps = {}) {
     activationCommand: configResult.activationCommand,
     skillInstalled: skillInstall?.installed,
     signerRuntimePrepared,
-    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...hostedProbeMessages, ...localProbeMessages, ...skillInstall?.messages ?? []]
+    messages: [...consentMessages, ...localRuntimeInstall?.messages ?? [], ...configResult.messages, ...hostedProbeMessages, ...signerProbeMessages, ...localProbeMessages, ...skillInstall?.messages ?? []]
   };
 }
 function runtimeInstallCapabilities(runtime, env = process.env) {
@@ -1854,10 +2295,11 @@ async function configureClaudeCode(deps, localMcpCommand) {
   });
   try {
     if (!localMcpCommand) throw new Error("local MCP wrapper command is required");
+    await runCommand("claude", ["mcp", "remove", "haven"]).catch(() => void 0);
+    await runCommand("claude", ["mcp", "remove", "haven-signer"]).catch(() => void 0);
     await runCommand("claude", ["mcp", "add-json", "haven", serverJson, "--scope", "user"]).catch(async () => {
       await runCommand("claude", ["mcp", "add", "haven", "--scope", "user", "--", localMcpCommand]);
     });
-    await runCommand("claude", ["mcp", "remove", "haven-signer"]).catch(() => void 0);
     const verified = await runCommand("claude", ["mcp", "get", "haven"]).then(() => true).catch(() => false);
     return {
       hostedConfigured: false,
@@ -1979,6 +2421,10 @@ function signerConsentErrorCode(signerCredentialReady, signerConsent) {
   if (!signerConsent?.acknowledged) return "local_signer_ack_required";
   return void 0;
 }
+function signerProbeErrorCode(probe) {
+  if (!probe || probe.status === "ok") return void 0;
+  return `local_signer_probe_${probe.status}`;
+}
 function hostedMcpErrorCode(hostedConfigured, hostedProbeStatus) {
   if (!hostedConfigured || hostedProbeStatus === "ok") return void 0;
   return `hosted_mcp_probe_${hostedProbeStatus}`;
@@ -2002,7 +2448,7 @@ function supportsLocalMcp(runtime) {
   return runtime === "codex-cli" || runtime === "codex-desktop" || runtime === "claude-code";
 }
 async function prepareRuntimeForLocalMcp(input, deps) {
-  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand }));
+  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress }));
   return prepare({
     credentialDirectory: input.credentialDirectory,
     identityPath: input.identityPath,
@@ -2011,7 +2457,13 @@ async function prepareRuntimeForLocalMcp(input, deps) {
   });
 }
 async function prepareSignerForRuntime(input, deps) {
-  const prepare = deps.prepareSignerRuntime ?? ((runtimeInput) => prepareSignerRuntime(runtimeInput, { runCommand: deps.runCommand }));
+  const prepare = deps.prepareSignerRuntime ?? ((runtimeInput) => (
+    // onProgress threaded through on purpose (#1586 review): without it the
+    // install heartbeat was dead code in production and the console still
+    // went silent for the whole cold install — the exact symptom the issue
+    // set out to remove, at a longer timeout.
+    prepareSignerRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress })
+  ));
   return prepare({
     credentialDirectory: input.credentialDirectory,
     signerPath: input.signerPath,
@@ -2034,7 +2486,9 @@ function localRuntimePrepareErrorCode(err) {
 }
 
 // src/runtime.ts
-var CONNECTOR_VERSION = "0.1.26-alpha.0";
+init_runtime_registry();
+init_runtime_manifest();
+var CONNECTOR_VERSION = "0.1.27-alpha.0";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 async function runConnect(options, deps = {}) {
   assertSupportedNodeVersion(deps.nodeVersion, MCP_RUNTIME_MANIFEST.minimumNodeVersion);
@@ -2141,7 +2595,35 @@ async function runConnect(options, deps = {}) {
     ackSigner: options.ackSigner,
     ackLocalTools: options.ackLocalTools,
     localMcp: options.localMcp
-  }, { onProgress: log });
+  }, {
+    onProgress: log,
+    // #1543: report "runtime configured" the moment the config write settles,
+    // so the dashboard can expose its budget-approval controls without
+    // waiting on the probes and skill install — a tail that approval does not
+    // depend on. Silent and best-effort: the complete report below remains
+    // authoritative (it overwrites these keys, adding the probe verdicts and
+    // skill state), so an early failure costs nothing but the head start.
+    onRuntimeConfigured: async (early) => {
+      try {
+        await api.updateInstallStatus(registration.setup_id, localApiKey, {
+          runtime: early.runtime,
+          connectorVersion,
+          runtimeMcpMode: early.runtimeMcpMode,
+          hostedMcpConfigured: early.hostedMcpConfigured,
+          localSignerConfigured: early.localSignerConfigured,
+          localMcpConfigured: early.localMcpConfigured,
+          credentialFilesWritten: true,
+          signerAcknowledged: early.signerAcknowledged,
+          localMcpAcknowledged: early.localMcpAcknowledged,
+          restartRequired: early.restartRequired,
+          nextUserAction: early.nextUserAction,
+          errorCode: early.errorCode ?? null,
+          environmentLabel: options.environmentLabel ?? "Local workspace"
+        });
+      } catch {
+      }
+    }
+  });
   printRuntimeInstall(runtimeInstall, log);
   if (runtimeInstall.errorCode) {
     log("Haven setup needs a couple more steps on this machine \u2014 see the notes above.");
@@ -2170,10 +2652,11 @@ async function runConnect(options, deps = {}) {
   } catch (err) {
     log(`Could not report install status to Haven: ${err instanceof Error ? err.message : String(err)}`);
   }
+  let approval;
   if (options.waitForApproval !== false && !runtimeInstall.errorCode) {
-    await waitForBudgetApproval(api, registration.setup_id, localApiKey, log, options.approvalWait);
+    approval = await waitForBudgetApproval(api, registration.setup_id, localApiKey, log, options.approvalWait);
   }
-  printNextSteps(runtimeInstall, log);
+  printNextSteps(runtimeInstall, log, approval);
   return {
     setupId: registration.setup_id,
     agentId: registration.agent_id,
@@ -2314,9 +2797,14 @@ async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
   const sleep = options.sleep ?? ((ms) => new Promise((resolve8) => setTimeout(resolve8, ms)));
   const maxPolls = Math.max(1, Math.floor(timeoutMs / intervalMs));
   const remindEvery = Math.max(1, Math.floor(3e4 / intervalMs));
-  log("Registered with Haven \u2014 waiting for you to approve the budget in the dashboard\u2026");
+  let waitingAnnounced = false;
+  const announceWaiting = () => {
+    if (waitingAnnounced) return;
+    waitingAnnounced = true;
+    log("Registered with Haven \u2014 waiting for you to approve the budget in the dashboard\u2026");
+  };
   for (let i = 0; i < maxPolls; i++) {
-    await sleep(intervalMs);
+    if (i > 0) await sleep(intervalMs);
     let status;
     try {
       status = await api.getConnectorStatus(setupId, apiKey);
@@ -2325,6 +2813,7 @@ async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
         log("This setup ended in Haven \u2014 start a fresh connection from the dashboard when ready.");
         return "ended";
       }
+      announceWaiting();
       continue;
     }
     if (status.status === "active") {
@@ -2337,7 +2826,8 @@ async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
       log(`This setup ended in Haven (${status.status}) \u2014 start a fresh connection from the dashboard when ready.`);
       return "ended";
     }
-    if ((i + 1) % remindEvery === 0) {
+    announceWaiting();
+    if (i > 0 && i % remindEvery === 0) {
       log("Still waiting for budget approval in Haven\u2026");
     }
   }
@@ -2346,11 +2836,11 @@ async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
   );
   return "pending";
 }
-function completionHandoffLines(result) {
+function completionHandoffLines(result, approval) {
   if (result.errorCode === "manual_runtime_setup_required") {
     return [
       "Next steps:",
-      "1. Return to Haven and approve the agent rules. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+      "1. Return to Haven and approve the budget. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
       "2. Finish the manual MCP setup using the secret-free file references printed above, then start a fresh session in your runtime.",
       `3. ${runtimeVerificationInstruction(result.runtime)}`
     ];
@@ -2360,16 +2850,38 @@ function completionHandoffLines(result) {
       "Recovery: runtime setup is not complete. Resolve the reported problem, then return to Haven for a fresh connection and run its new Connect command. Do not manually edit runtime config or paste credentials into prompts, logs, or config."
     ];
   }
+  if (approval === "ended") {
+    return [
+      "Next step: this setup ended in Haven before the budget was approved, so there is nothing left to approve on it \u2014 start a fresh connection from the dashboard when ready."
+    ];
+  }
   const profile = runtimeProfile(result.runtime);
+  const activation = activationInstructionWithWhy(profile);
+  if (approval === "approved") {
+    return [
+      "Next steps \u2014 the budget is already approved, so there is nothing more to do in Haven:",
+      `1. ${activation}`,
+      `2. ${runtimeVerificationInstruction(result.runtime)}`
+    ];
+  }
   return [
     "Next steps:",
-    "1. Return to Haven and approve the agent rules. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
-    `2. ${profile.activationInstruction}`,
+    "1. Return to Haven and approve the budget. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+    `2. ${activation}`,
     `3. ${runtimeVerificationInstruction(result.runtime)}`
   ];
 }
-function printNextSteps(result, log) {
-  for (const line of completionHandoffLines(result)) log(line);
+function activationInstructionWithWhy(profile) {
+  if (profile.restartMode === "restart-session") {
+    return `${profile.activationInstruction} (The entries are already written and verified \u2014 ${profile.label} only reads MCP config when a session starts, which is why this step is still needed.)`;
+  }
+  if (profile.restartMode === "restart-app") {
+    return `${profile.activationInstruction} (The entries are already written and verified \u2014 ${profile.label} only reads MCP config at app launch, which is why this step is still needed.)`;
+  }
+  return profile.activationInstruction;
+}
+function printNextSteps(result, log, approval) {
+  for (const line of completionHandoffLines(result, approval)) log(line);
 }
 
 // src/args.ts
@@ -2380,12 +2892,18 @@ function parseArgs(argv, env = process.env) {
   };
   let help = false;
   let json = false;
+  let doctor = false;
+  let repair = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
       help = true;
     } else if (arg === "--json") {
       json = true;
+    } else if (arg === "--doctor") {
+      doctor = true;
+    } else if (arg === "--repair") {
+      repair = true;
     } else if (arg === "--setup" || arg === "--setup-token") {
       options.setupToken = requireValue(argv, ++i, arg);
     } else if (arg === "--api" || arg === "--api-url") {
@@ -2412,7 +2930,13 @@ function parseArgs(argv, env = process.env) {
     }
   }
   if (help) {
-    return { options, help, json };
+    return { options, help, json, doctor, repair };
+  }
+  if (doctor || repair) {
+    if (!options.runtime) {
+      throw new Error("--doctor/--repair need --runtime <runtime> (which config to examine).");
+    }
+    return { options, help, json, doctor, repair };
   }
   if (!options.setupToken) {
     throw new Error("Missing --setup <hv_setup_...> setup token.");
@@ -2421,7 +2945,7 @@ function parseArgs(argv, env = process.env) {
     throw new Error("Missing --api <Haven API URL>.");
   }
   options.apiBaseUrl = options.apiBaseUrl.replace(/\/+$/, "");
-  return { options, help, json };
+  return { options, help, json, doctor, repair };
 }
 function helpText() {
   return [
@@ -2444,6 +2968,11 @@ function helpText() {
     "  --local                    Advanced: install the fully-local Haven MCP (no hosted dependency).",
     "                             Only available for Claude Code and Codex. Default is hosted MCP + local signer.",
     "  --json                     Emit one versioned, secret-free result object on stdout; progress stays on stderr.",
+    "  --doctor                   Diagnose an existing setup (read-only, no token): config, credentials,",
+    "                             signer runtime, hosted MCP, and a live signer handshake. Exits non-zero on any failure.",
+    "  --repair                   Repair, then re-diagnose (implies --doctor): reinstall the pinned signer",
+    "                             runtime, rewrite the wrapper and runtime config from stored credentials.",
+    "                             Hosted topology only (refuses to touch a --local config). No keys, no token.",
     "  --help                     Show this help.",
     "",
     "The connector never prints the private key and never sends it to Haven. JSON output never includes credential contents or full credential paths."
@@ -2481,6 +3010,37 @@ async function runCli(argv, io = {
 `);
     return 0;
   }
+  if (parsed.doctor || parsed.repair) {
+    const { runDoctor: runDoctor2, runRepair: runRepair2 } = await Promise.resolve().then(() => (init_doctor(), doctor_exports));
+    const runtime = parsed.options.runtime ?? "";
+    const credentialsDir = parsed.options.credentialsDir;
+    try {
+      if (parsed.repair) {
+        const repair = await runRepair2({ runtime, credentialsDir });
+        for (const message of repair.messages) io.stderr(`${redactSecrets(message)}
+`);
+        if (!repair.ok) return 1;
+      }
+      const report = await runDoctor2({ runtime, credentialsDir });
+      if (parsed.json) {
+        io.stdout(`${redactSecrets(JSON.stringify(report))}
+`);
+      } else {
+        for (const check of report.checks) {
+          io.stdout(redactSecrets(`${check.ok ? "\u2713" : "\u2717"} ${check.label}: ${check.detail}
+`));
+          if (check.repair) io.stdout(redactSecrets(`    \u21B3 repair: ${check.repair}
+`));
+        }
+        io.stdout(report.ok ? "All checks passed.\n" : "One or more checks FAILED \u2014 see repairs above.\n");
+      }
+      return report.ok ? 0 : 1;
+    } catch (err) {
+      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
+`);
+      return 1;
+    }
+  }
   try {
     const result = await runConnect(
       { ...parsed.options, waitForApproval: !parsed.json },