@haven_ai/connect 0.1.34-alpha.0 → 0.1.36-alpha.0

package/dist/cli.cjs

@@ -55,6 +55,7 @@ function createConnectApiClient(baseUrl, fetchImpl = fetch) {
         runtime: input.runtime,
         connector_version: input.connectorVersion,
         mcp_server_name: input.mcpServerName,
+        run_mode: input.runMode,
         connector_context: input.connectorContext,
         install_capabilities: input.installCapabilities && {
           can_write_runtime_config: input.installCapabilities.canWriteRuntimeConfig,
@@ -90,7 +91,21 @@ function createConnectApiClient(baseUrl, fetchImpl = fetch) {
           restart_required: input.restartRequired,
           next_user_action: input.nextUserAction,
           error_code: input.errorCode ?? null,
-          environment_label: input.environmentLabel
+          environment_label: input.environmentLabel,
+          // Three states on the wire, and ABSENT is a fourth (#2561 review).
+          // `?? null` alone collapsed the fourth into the third: a report that
+          // simply had nothing to say — the early config-written ping, which
+          // fires before the scan has started — asserted "the scan could not
+          // run" instead of leaving the key alone. Inert today, because the
+          // complete report overwrites it seconds later and nothing reads the
+          // row in between; a landmine the moment any caller relies on
+          // "absent = unchanged", which is what the backend's jsonb merge
+          // means and what this field's own contract says.
+          //
+          // So: a caller that passes the field says something (`null` included,
+          // deliberately, since "could not run" is a claim worth making); a
+          // caller that omits it says nothing.
+          ...input.supersededAgentIds !== void 0 ? { superseded_agent_ids: input.supersededAgentIds } : {}
         })
       });
     }
@@ -535,9 +550,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: mcp.MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.1.34-alpha.0",
+      sdkVersion: "0.1.36-alpha.0",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.1.34-alpha.0",
+      signerVersion: "0.1.36-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
@@ -903,7 +918,7 @@ async function writeJsonRuntimeConfig(input, target, serverRoot) {
       restartRequired: true,
       messages: unreadable ? [
         `Could not update ${configTargetLabel(input.runtime)}: ${err.message}.`,
-        `Nothing was written to ${err.configPath}. Fix the JSON there (or move the file aside), then run \`${REPAIR_COMMAND_PREFIX} ${input.runtime}\` to write the Haven entries from the credentials already stored on this machine. Do not re-run the setup command: its token is already used.`
+        `Nothing was written to ${err.configPath}. Fix the JSON there (or move the file aside), then run \`${REPAIR_COMMAND_PREFIX} ${input.runtime}\` to write the Haven entries from the credentials already stored on this machine. Do not re-run the connector command: its setup token is already used.`
       ] : [`Could not update ${configTargetLabel(input.runtime)}: ${err instanceof Error ? err.message : String(err)}`],
       errorCode: unreadable ? "runtime_config_unreadable" : "runtime_config_write_failed"
     };
@@ -968,7 +983,7 @@ async function writeHermesConfig(input, deps) {
       restartRequired: true,
       messages: unreadable ? [
         `Could not update Hermes Agent config: ${err.message}.`,
-        `Nothing was written to ${err.configPath}. Fix the YAML there (or move the file aside), then run \`${REPAIR_COMMAND_PREFIX} hermes\` to write the Haven entries from the credentials already stored on this machine. Do not re-run the setup command: its token is already used.`
+        `Nothing was written to ${err.configPath}. Fix the YAML there (or move the file aside), then run \`${REPAIR_COMMAND_PREFIX} hermes\` to write the Haven entries from the credentials already stored on this machine. Do not re-run the connector command: its setup token is already used.`
       ] : [recoveryIncomplete ? "Could not update Hermes Agent config. Recovery did not complete; inspect the Hermes configuration before retrying." : "Could not update Hermes Agent config. Existing configuration was left unchanged."],
       errorCode: unreadable ? "runtime_config_unreadable" : "runtime_config_write_failed"
     };
@@ -1358,7 +1373,7 @@ var init_config_writers = __esm({
         this.name = "InvalidCodexTomlError";
       }
     };
-    REPAIR_COMMAND_PREFIX = "npx @haven_ai/connect@alpha --doctor --repair --runtime";
+    REPAIR_COMMAND_PREFIX = sdk.connectorRerunCommand("--doctor --repair --runtime");
     UnreadableRuntimeConfigError = class extends Error {
       configPath;
       constructor(configPath, detail) {
@@ -1608,32 +1623,129 @@ var init_probes = __esm({
   "src/probes.ts"() {
   }
 });
+function resolveRuntimeSpecOverride(env) {
+  const override = {};
+  for (const pkg of Object.keys(RUNTIME_SPEC_ENV)) {
+    const variable = RUNTIME_SPEC_ENV[pkg];
+    const raw = env[variable];
+    if (raw === void 0) continue;
+    override[pkg] = validateSpec(variable, raw);
+  }
+  return Object.keys(override).length > 0 ? override : void 0;
+}
+function validateSpec(variable, raw) {
+  if (raw.length === 0 || raw.trim().length === 0) {
+    throw new RuntimeSpecOverrideError(variable, "it is empty");
+  }
+  if (/\s/.test(raw)) {
+    throw new RuntimeSpecOverrideError(variable, "it contains whitespace");
+  }
+  if (/[\u0000-\u001f\u007f]/.test(raw)) {
+    throw new RuntimeSpecOverrideError(variable, "it contains a control character");
+  }
+  const meta = SHELL_METACHARACTERS.exec(raw);
+  if (meta) {
+    throw new RuntimeSpecOverrideError(variable, `it contains the shell metacharacter ${JSON.stringify(meta[0])}`);
+  }
+  return raw;
+}
+function runtimeSpecOverrideDirectoryKey(resolvedSpecs) {
+  const digest = crypto.createHash("sha256").update(resolvedSpecs.join("\n")).digest("hex");
+  return `override-${digest.slice(0, 12)}`;
+}
+function overrideApplies(override, packages) {
+  return override !== void 0 && packages.some((pkg) => override[pkg] !== void 0);
+}
+function runtimeSpecOverrideNotice(runtimeLabel, override, pinned, runtimeDirectory) {
+  const lines = [`RUNTIME SPEC OVERRIDE ACTIVE for the local Haven ${runtimeLabel} \u2014 this is NOT the pinned manifest.`];
+  for (const pkg of Object.keys(RUNTIME_SPEC_ENV)) {
+    const spec = override[pkg];
+    if (spec === void 0) continue;
+    const pin = pinned[pkg];
+    lines.push(`  ${RUNTIME_SPEC_ENV[pkg]}=${spec}${pin ? ` (instead of ${pin})` : ""}`);
+  }
+  lines.push(`  Installing into ${runtimeDirectory} \u2014 the pinned runtime directory is untouched.`);
+  lines.push("  Unset the variable(s) and re-run to return to the pinned manifest.");
+  return lines;
+}
+function describeRuntimeSpecOverride(override) {
+  return Object.keys(RUNTIME_SPEC_ENV).filter((pkg) => override[pkg] !== void 0).map((pkg) => `${RUNTIME_SPEC_ENV[pkg]}=${override[pkg]}`).join(" ");
+}
+var RUNTIME_SPEC_ENV, SHELL_METACHARACTERS, RuntimeSpecOverrideError;
+var init_runtime_spec_override = __esm({
+  "src/runtime-spec-override.ts"() {
+    RUNTIME_SPEC_ENV = {
+      signer: "HAVEN_SIGNER_SPEC",
+      sdk: "HAVEN_SDK_SPEC",
+      mcp: "HAVEN_MCP_SPEC"
+    };
+    SHELL_METACHARACTERS = /[;&|<>$`'"()!#*?[\]{}\\]/;
+    RuntimeSpecOverrideError = class extends Error {
+      code = "runtime_spec_override_invalid";
+      variable;
+      constructor(variable, reason) {
+        super(`${variable} is set but not usable as an npm package spec: ${reason}. Unset it, or set it to a spec npm install accepts (file:/abs/path, a .tgz, or @haven_ai/<pkg>@<version>).`);
+        this.name = "RuntimeSpecOverrideError";
+        this.variable = variable;
+      }
+    };
+  }
+});
 async function prepareSignerRuntime(input, deps = {}) {
   const homeDir = input.homeDir ?? os.homedir();
-  const runtimeDirectory = path.resolve(homeDir, ".haven", "signer-runtime", MCP_RUNTIME_MANIFEST.signerVersion);
+  const override = resolveSignerRuntimeOverride(deps.env ?? process.env);
+  const signerSpec = override?.signer ?? signerPackageSpec();
+  const sdkSpec = override?.sdk ?? sdkPackageSpec();
+  const resolvedSpecs = [signerSpec, sdkSpec];
+  const overrideRecord = override ? { specs: override, resolved_specs: resolvedSpecs, directory_key: runtimeSpecOverrideDirectoryKey(resolvedSpecs) } : void 0;
+  const runtimeDirectory = path.resolve(
+    homeDir,
+    ".haven",
+    "signer-runtime",
+    overrideRecord ? overrideRecord.directory_key : MCP_RUNTIME_MANIFEST.signerVersion
+  );
   const npmCacheDirectory = path.resolve(homeDir, ".haven", "npm-cache");
   const cliPath = path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "dist", "cli.js");
   const messages = [];
+  if (override) {
+    messages.push(...runtimeSpecOverrideNotice(
+      "signer runtime",
+      override,
+      { signer: signerPackageSpec(), sdk: sdkPackageSpec() },
+      runtimeDirectory
+    ));
+  }
   await promises.mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await promises.chmod(runtimeDirectory, 448).catch(() => void 0);
   await promises.mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await promises.chmod(npmCacheDirectory, 448).catch(() => void 0);
-  if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
+  if (override) {
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
+    messages.push(`Installed local Haven signer runtime from override (${resolvedSpecs.join(" ")}).`);
+  } else if (await installedRuntimeMatches(runtimeDirectory, cliPath)) {
     messages.push(`Using existing local Haven signer runtime ${signerPackageSpec()}.`);
   } else {
-    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps);
+    await installRuntimePackages(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
     messages.push(`Installed local Haven signer runtime ${signerPackageSpec()}.`);
   }
   await assertFileExists(cliPath, "local Haven signer CLI");
+  const installedVersions = override ? await readInstalledVersions(runtimeDirectory) : void 0;
   const wrapperPath = path.join(input.credentialDirectory, "bin", "haven-signer.mjs");
-  await writeWrapper({ wrapperPath, cliPath, signerPath: input.signerPath });
+  await writeWrapper({
+    wrapperPath,
+    cliPath,
+    signerPath: input.signerPath,
+    overrideComment: override ? describeRuntimeSpecOverride(override) : void 0
+  });
   await writeRuntimeSidecar({
     path: path.join(input.credentialDirectory, "signer-runtime.json"),
     wrapperPath,
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    serverName: input.serverName
+    serverName: input.serverName,
+    override: overrideRecord,
+    installedVersions
   });
   messages.push(`Prepared stable local Haven signer wrapper: ${wrapperPath}`);
   return {
@@ -1643,10 +1755,17 @@ async function prepareSignerRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    messages
+    messages,
+    ...overrideRecord ? { runtimeSpecOverride: overrideRecord } : {}
   };
 }
-async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps) {
+function resolveSignerRuntimeOverride(env) {
+  const override = resolveRuntimeSpecOverride(env);
+  if (!overrideApplies(override, ["signer", "sdk"])) return void 0;
+  const { signer, sdk } = override;
+  return { ...signer !== void 0 ? { signer } : {}, ...sdk !== void 0 ? { sdk } : {} };
+}
+async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, packageSpecs, deps) {
   const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
@@ -1656,8 +1775,7 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps)
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    signerPackageSpec(),
-    sdkPackageSpec()
+    ...packageSpecs
   ];
   const run = async (args) => {
     const startedAt = Date.now();
@@ -1680,23 +1798,33 @@ async function installRuntimePackages(runtimeDirectory, npmCacheDirectory, deps)
       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)}`
+        `Could not install local Haven signer runtime ${packageSpecs.join(" ")}: ${err instanceof Error ? err.message : String(err)}`
       );
     }
   }
 }
 async function installedRuntimeMatches(runtimeDirectory, cliPath) {
+  return installedRuntimeMatchesVersions(runtimeDirectory, cliPath, {
+    signerVersion: MCP_RUNTIME_MANIFEST.signerVersion,
+    sdkVersion: MCP_RUNTIME_MANIFEST.sdkVersion
+  });
+}
+async function installedRuntimeMatchesVersions(runtimeDirectory, cliPath, expected) {
   try {
     await assertFileExists(cliPath, "local Haven signer CLI");
-    const [signerPackage, sdkPackage] = await Promise.all([
-      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
-      readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
-    ]);
-    return signerPackage.version === MCP_RUNTIME_MANIFEST.signerVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    const installed = await readInstalledVersions(runtimeDirectory);
+    return installed.signerVersion === expected.signerVersion && installed.sdkVersion === expected.sdkVersion;
   } catch {
     return false;
   }
 }
+async function readInstalledVersions(runtimeDirectory) {
+  const [signerPackage, sdkPackage] = await Promise.all([
+    readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "signer", "package.json")),
+    readPackageJson(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
+  ]);
+  return { signerVersion: signerPackage.version ?? "", sdkVersion: sdkPackage.version ?? "" };
+}
 async function readPackageJson(path) {
   return JSON.parse(await promises.readFile(path, "utf8"));
 }
@@ -1705,6 +1833,7 @@ async function writeWrapper(input) {
   await promises.chmod(path.dirname(input.wrapperPath), 448).catch(() => void 0);
   const source = [
     "#!/usr/bin/env node",
+    ...input.overrideComment ? [`// HAVEN RUNTIME SPEC OVERRIDE (#2424): ${input.overrideComment} \u2014 this wrapper launches a NON-pinned signer build.`] : [],
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
@@ -1736,13 +1865,14 @@ async function writeRuntimeSidecar(input) {
   const value = {
     ...input.serverName ? { server_name: input.serverName } : {},
     signer_package: MCP_RUNTIME_MANIFEST.signerPackage,
-    signer_version: MCP_RUNTIME_MANIFEST.signerVersion,
+    signer_version: input.installedVersions?.signerVersion ?? MCP_RUNTIME_MANIFEST.signerVersion,
     sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
-    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    sdk_version: input.installedVersions?.sdkVersion ?? MCP_RUNTIME_MANIFEST.sdkVersion,
     wrapper_path: input.wrapperPath,
     runtime_directory: input.runtimeDirectory,
     npm_cache_directory: input.npmCacheDirectory,
-    cli_path: input.cliPath
+    cli_path: input.cliPath,
+    ...input.override ? { runtime_spec_override: input.override } : {}
   };
   await promises.writeFile(input.path, `${JSON.stringify(value, null, 2)}
 `, { mode: 384 });
@@ -1759,6 +1889,7 @@ var execFileAsync, SIGNER_INSTALL_TIMEOUT_MS, SIGNER_INSTALL_HEARTBEAT_MS;
 var init_signer_runtime = __esm({
   "src/signer-runtime.ts"() {
     init_runtime_manifest();
+    init_runtime_spec_override();
     execFileAsync = util.promisify(child_process.execFile);
     SIGNER_INSTALL_TIMEOUT_MS = 6e5;
     SIGNER_INSTALL_HEARTBEAT_MS = 15e3;
@@ -1767,27 +1898,50 @@ var init_signer_runtime = __esm({
 async function prepareLocalMcpRuntime(input, deps = {}) {
   assertSupportedNodeVersion(input.nodeVersion);
   const homeDir = input.homeDir ?? os.homedir();
-  const runtimeDirectory = path.resolve(homeDir, ".haven", "mcp-runtime", MCP_RUNTIME_MANIFEST.mcpVersion);
+  const override = resolveLocalMcpRuntimeOverride(deps.env ?? process.env);
+  const mcpSpec = override?.mcp ?? mcpPackageSpec();
+  const sdkSpec = override?.sdk ?? sdkPackageSpec();
+  const resolvedSpecs = [mcpSpec, sdkSpec];
+  const overrideRecord = override ? { specs: override, resolved_specs: resolvedSpecs, directory_key: runtimeSpecOverrideDirectoryKey(resolvedSpecs) } : void 0;
+  const runtimeDirectory = path.resolve(
+    homeDir,
+    ".haven",
+    "mcp-runtime",
+    overrideRecord ? overrideRecord.directory_key : MCP_RUNTIME_MANIFEST.mcpVersion
+  );
   const npmCacheDirectory = path.resolve(homeDir, ".haven", "npm-cache");
   const cliPath = path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "dist", "cli.js");
   const messages = [];
+  if (override) {
+    messages.push(...runtimeSpecOverrideNotice(
+      "MCP runtime",
+      override,
+      { mcp: mcpPackageSpec(), sdk: sdkPackageSpec() },
+      runtimeDirectory
+    ));
+  }
   await promises.mkdir(runtimeDirectory, { recursive: true, mode: 448 });
   await promises.chmod(runtimeDirectory, 448).catch(() => void 0);
   await promises.mkdir(npmCacheDirectory, { recursive: true, mode: 448 });
   await promises.chmod(npmCacheDirectory, 448).catch(() => void 0);
-  if (await installedRuntimeMatches2(runtimeDirectory, cliPath)) {
+  if (override) {
+    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
+    messages.push(`Installed local Haven MCP runtime from override (${resolvedSpecs.join(" ")}).`);
+  } else if (await installedRuntimeMatches2(runtimeDirectory, cliPath)) {
     messages.push(`Using existing local Haven MCP runtime ${mcpPackageSpec()}.`);
   } else {
-    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps);
+    await installRuntimePackages2(runtimeDirectory, npmCacheDirectory, resolvedSpecs, deps);
     messages.push(`Installed local Haven MCP runtime ${mcpPackageSpec()}.`);
   }
   await assertFileExists2(cliPath, "local Haven MCP CLI");
+  const installedVersions = override ? await readInstalledVersions2(runtimeDirectory) : void 0;
   const wrapperPath = path.join(input.credentialDirectory, "bin", "haven-mcp");
   await writeWrapper2({
     wrapperPath,
     cliPath,
     identityPath: input.identityPath,
-    signerPath: input.signerPath
+    signerPath: input.signerPath,
+    overrideComment: override ? describeRuntimeSpecOverride(override) : void 0
   });
   await writeRuntimeSidecar2({
     path: path.join(input.credentialDirectory, "mcp-runtime.json"),
@@ -1795,7 +1949,9 @@ async function prepareLocalMcpRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    serverName: input.serverName
+    serverName: input.serverName,
+    override: overrideRecord,
+    installedVersions
   });
   messages.push(`Prepared stable local Haven MCP wrapper: ${wrapperPath}`);
   return {
@@ -1805,7 +1961,8 @@ async function prepareLocalMcpRuntime(input, deps = {}) {
     runtimeDirectory,
     npmCacheDirectory,
     cliPath,
-    messages
+    messages,
+    ...overrideRecord ? { runtimeSpecOverride: overrideRecord } : {}
   };
 }
 function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimumNodeVersion = MCP_RUNTIME_MANIFEST.minimumNodeVersion, subject = "Haven setup") {
@@ -1813,7 +1970,13 @@ function assertSupportedNodeVersion(nodeVersion = process.versions.node, minimum
     throw new UnsupportedNodeVersionError(nodeVersion, minimumNodeVersion, subject);
   }
 }
-async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps) {
+function resolveLocalMcpRuntimeOverride(env) {
+  const override = resolveRuntimeSpecOverride(env);
+  if (!overrideApplies(override, ["mcp", "sdk"])) return void 0;
+  const { mcp, sdk } = override;
+  return { ...mcp !== void 0 ? { mcp } : {}, ...sdk !== void 0 ? { sdk } : {} };
+}
+async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, packageSpecs, deps) {
   const { runCommand, onProgress } = deps;
   const baseArgs = [
     "install",
@@ -1823,8 +1986,7 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps
     "--no-fund",
     "--omit=dev",
     "--prefer-offline",
-    mcpPackageSpec(),
-    sdkPackageSpec()
+    ...packageSpecs
   ];
   const run = async (args) => {
     const startedAt = Date.now();
@@ -1846,22 +2008,26 @@ async function installRuntimePackages2(runtimeDirectory, npmCacheDirectory, deps
     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 MCP runtime ${packageSpecs.join(" ")}: ${err instanceof Error ? err.message : String(err)}`);
     }
   }
 }
 async function installedRuntimeMatches2(runtimeDirectory, cliPath) {
   try {
     await assertFileExists2(cliPath, "local Haven MCP CLI");
-    const [mcpPackage, sdkPackage] = await Promise.all([
-      readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
-      readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
-    ]);
-    return mcpPackage.version === MCP_RUNTIME_MANIFEST.mcpVersion && sdkPackage.version === MCP_RUNTIME_MANIFEST.sdkVersion;
+    const installed = await readInstalledVersions2(runtimeDirectory);
+    return installed.mcpVersion === MCP_RUNTIME_MANIFEST.mcpVersion && installed.sdkVersion === MCP_RUNTIME_MANIFEST.sdkVersion;
   } catch {
     return false;
   }
 }
+async function readInstalledVersions2(runtimeDirectory) {
+  const [mcpPackage, sdkPackage] = await Promise.all([
+    readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "mcp", "package.json")),
+    readPackageJson2(path.join(runtimeDirectory, "node_modules", "@haven_ai", "sdk", "package.json"))
+  ]);
+  return { mcpVersion: mcpPackage.version ?? "", sdkVersion: sdkPackage.version ?? "" };
+}
 async function readPackageJson2(path) {
   return JSON.parse(await promises.readFile(path, "utf8"));
 }
@@ -1870,6 +2036,7 @@ async function writeWrapper2(input) {
   await promises.chmod(path.dirname(input.wrapperPath), 448).catch(() => void 0);
   const source = [
     "#!/usr/bin/env node",
+    ...input.overrideComment ? [`// HAVEN RUNTIME SPEC OVERRIDE (#2424): ${input.overrideComment} \u2014 this wrapper launches a NON-pinned MCP build.`] : [],
     "import { spawn } from 'node:child_process'",
     "",
     `const cliPath = ${JSON.stringify(input.cliPath)}`,
@@ -1893,14 +2060,15 @@ async function writeRuntimeSidecar2(input) {
   const value = {
     ...input.serverName ? { server_name: input.serverName } : {},
     mcp_package: MCP_RUNTIME_MANIFEST.mcpPackage,
-    mcp_version: MCP_RUNTIME_MANIFEST.mcpVersion,
+    mcp_version: input.installedVersions?.mcpVersion ?? MCP_RUNTIME_MANIFEST.mcpVersion,
     sdk_package: MCP_RUNTIME_MANIFEST.sdkPackage,
-    sdk_version: MCP_RUNTIME_MANIFEST.sdkVersion,
+    sdk_version: input.installedVersions?.sdkVersion ?? 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
+    cli_path: input.cliPath,
+    ...input.override ? { runtime_spec_override: input.override } : {}
   };
   await promises.writeFile(input.path, `${JSON.stringify(value, null, 2)}
 `, { mode: 384 });
@@ -1918,6 +2086,7 @@ var init_local_mcp_runtime = __esm({
   "src/local-mcp-runtime.ts"() {
     init_signer_runtime();
     init_runtime_manifest();
+    init_runtime_spec_override();
     execFileAsync2 = util.promisify(child_process.execFile);
     UnsupportedNodeVersionError = class extends Error {
       code = "local_mcp_unsupported_node_version";
@@ -2418,7 +2587,7 @@ async function installRuntime(input, deps = {}) {
         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",
+        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: ${sdk.connectorRerunCommand()}`,
         errorCode: "signer_runtime_install_failed",
         configTarget: profile.label,
         signerAcknowledged: signerConsent?.acknowledged,
@@ -2429,7 +2598,7 @@ async function installRuntime(input, deps = {}) {
           ...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."
+          `Re-run \`${sdk.connectorRerunCommand()}\` to retry the setup.`
         ]
       };
     }
@@ -2492,7 +2661,7 @@ async function installRuntime(input, deps = {}) {
   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."
+    `Re-run \`${sdk.connectorRerunCommand()}\` 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;
@@ -2563,7 +2732,7 @@ async function configureClaudeCode(deps, localMcpCommand, serverName) {
       restartRequired: true,
       messages: [
         `Could not update Claude Code MCP config: ${err instanceof Error ? err.message : String(err)}`,
-        "Install Claude Code or rerun the Haven setup command inside a Claude Code terminal."
+        "Install Claude Code or rerun the Haven connector command inside a Claude Code terminal."
       ],
       errorCode: "claude_code_config_failed"
     };
@@ -2630,7 +2799,7 @@ async function configureClaudeCodeHosted(deps, input, signerCommand) {
       restartRequired: true,
       messages: [
         `Could not update Claude Code MCP config: ${err instanceof Error ? err.message : String(err)}`,
-        "Install Claude Code or rerun the Haven setup command inside a Claude Code terminal."
+        "Install Claude Code or rerun the Haven connector command inside a Claude Code terminal."
       ],
       errorCode: "claude_code_config_failed"
     };
@@ -2704,7 +2873,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, onProgress: deps.onProgress }));
+  const prepare = deps.prepareLocalMcpRuntime ?? ((runtimeInput) => prepareLocalMcpRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress, env: deps.env }));
   return prepare({
     credentialDirectory: input.credentialDirectory,
     identityPath: input.identityPath,
@@ -2719,7 +2888,7 @@ async function prepareSignerForRuntime(input, deps) {
     // 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 })
+    prepareSignerRuntime(runtimeInput, { runCommand: deps.runCommand, onProgress: deps.onProgress, env: deps.env })
   ));
   return prepare({
     credentialDirectory: input.credentialDirectory,
@@ -2759,14 +2928,6 @@ var init_runtime_install = __esm({
   }
 });
 
-// src/rekey-messages.ts
-var REKEY_FINISH_NEEDS_API_KEY;
-var init_rekey_messages = __esm({
-  "src/rekey-messages.ts"() {
-    REKEY_FINISH_NEEDS_API_KEY = "--rekey-finish needs --api-key <key> \u2014 the one the Haven agent page showed once.";
-  }
-});
-
 // src/tombstone.ts
 var tombstone_exports = {};
 __export(tombstone_exports, {
@@ -2818,7 +2979,7 @@ function tombstoneScript(info) {
     "one of them: each holds the snapshot from its own start time, so after",
     "a chain of recreations each can be parked on a DIFFERENT old agent.",
     "",
-    "Then verify with: npx @haven_ai/connect@alpha --doctor --runtime <runtime>"
+    `Then verify with: ${sdk.connectorRerunCommand("--doctor --runtime <runtime>")}`
   ];
   return [
     "#!/usr/bin/env node",
@@ -2884,6 +3045,9 @@ var init_tombstone = __esm({
 // src/unwire.ts
 var unwire_exports = {};
 __export(unwire_exports, {
+  readIdentityFile: () => readIdentityFile,
+  teardownLocalKeyMaterial: () => teardownLocalKeyMaterial,
+  tombstoneDirectoryIfAbsent: () => tombstoneDirectoryIfAbsent,
   unwireAgent: () => unwireAgent
 });
 function identityAt(directory) {
@@ -2923,18 +3087,13 @@ async function unwireAgent(input) {
   const slug = input.slug ?? sidecar?.server_name;
   const names = serverNamesFor(slug);
   const runtimes = [];
-  let tombstoned = false;
-  const tombstonePath = path.join(input.directory, TOMBSTONE_FILENAME);
-  if (await readOptionalText(tombstonePath) === null) {
-    await writeAgentTombstone({
-      directory: input.directory,
-      agentId,
-      reason: input.reason ?? "unwired via --unwire",
-      replacedBy: input.replacedBy,
-      tombstonesDir: input.tombstonesDir
-    });
-    tombstoned = true;
-  }
+  const tombstoned = await tombstoneDirectoryIfAbsent({
+    directory: input.directory,
+    agentId,
+    reason: input.reason ?? "unwired via --unwire",
+    replacedBy: input.replacedBy,
+    tombstonesDir: input.tombstonesDir
+  });
   for (const model of RUNTIMES) {
     const path = runtimeConfigPathFor(model.runtime, homeDir);
     if (path === null) continue;
@@ -3019,16 +3178,27 @@ async function unwireAgent(input) {
       }
     }
   }
+  await teardownLocalKeyMaterial(input.directory, identity);
+  return { directory: input.directory, agentId, slug, tombstoned, runtimes };
+}
+async function tombstoneDirectoryIfAbsent(input) {
+  if (await readOptionalText(path.join(input.directory, TOMBSTONE_FILENAME)) !== null) return false;
+  await writeAgentTombstone(input);
+  return true;
+}
+async function teardownLocalKeyMaterial(directory, identity) {
   await Promise.all([
-    promises.rm(path.join(input.directory, "signer.json"), { force: true }),
-    promises.rm(path.join(input.directory, REKEY_PENDING_FILENAME), { force: true })
+    promises.rm(path.join(directory, "signer.json"), { force: true }),
+    promises.rm(path.join(directory, REKEY_PENDING_FILENAME), { force: true })
   ]);
   if (identity && identity.api_key !== void 0) {
     const { api_key: _dropped, ...rest } = identity;
-    await promises.writeFile(path.join(input.directory, "identity.json"), `${JSON.stringify(rest, null, 2)}
+    await promises.writeFile(path.join(directory, "identity.json"), `${JSON.stringify(rest, null, 2)}
 `, { mode: 384 });
   }
-  return { directory: input.directory, agentId, slug, tombstoned, runtimes };
+}
+async function readIdentityFile(directory) {
+  return identityAt(directory);
 }
 var RUNTIMES;
 var init_unwire = __esm({
@@ -3049,6 +3219,14 @@ var init_unwire = __esm({
   }
 });
 
+// src/rekey-messages.ts
+var REKEY_FINISH_NEEDS_API_KEY;
+var init_rekey_messages = __esm({
+  "src/rekey-messages.ts"() {
+    REKEY_FINISH_NEEDS_API_KEY = "--rekey-finish needs --api-key <key> \u2014 the one the Haven agent page showed once.";
+  }
+});
+
 // src/rekey.ts
 var rekey_exports = {};
 __export(rekey_exports, {
@@ -3076,7 +3254,7 @@ async function startRekey(options, deps = {}) {
     expires_at: expiresAt
   });
   const finishCommand = [
-    "npx @haven_ai/connect@alpha --rekey-finish",
+    sdk.connectorRerunCommand("--rekey-finish"),
     options.serverName ? `--name ${options.serverName}` : void 0,
     "--api-key <the key the dashboard showed you>",
     options.runtime ? `--runtime ${options.runtime}` : "--runtime <your runtime>"
@@ -3167,7 +3345,7 @@ async function finishRekey(options, deps = {}) {
         signerPath: `${stored.directory}/signer.json`,
         homeDir: options.homeDir
       },
-      { runCommand: deps.runCommand }
+      { runCommand: deps.runCommand, env: deps.env }
     );
     const result = await (deps.writeConfig ?? writeHostedRuntimeConfig)(
       { runCommand: deps.runCommand, homeDir: options.homeDir },
@@ -3183,6 +3361,11 @@ async function finishRekey(options, deps = {}) {
       { command: prepared.command, args: prepared.args }
     );
     configRewritten = result.hostedConfigured;
+    if (prepared.runtimeSpecOverride) {
+      messages.push(
+        `  Signer runtime:   RUNTIME SPEC OVERRIDE ACTIVE \u2014 ${describeRuntimeSpecOverride(prepared.runtimeSpecOverride.specs)} (NOT the pinned manifest; installed into ${prepared.runtimeDirectory})`
+      );
+    }
     messages.push(`  Config:           ${result.target}`);
     messages.push(...result.messages.map((line) => `  ${line}`));
     if (!configRewritten) {
@@ -3249,6 +3432,7 @@ var init_rekey = __esm({
     init_api();
     init_runtime_install();
     init_signer_runtime();
+    init_runtime_spec_override();
     init_key();
     init_redact();
     init_rekey_messages();
@@ -3425,6 +3609,46 @@ function rekeyPendingCheck(status, hostedDelegateAddress, runtime, slug) {
     detail: `A re-key started ${started} is still open (expires ${status.expiresAt ?? "unknown"}). Paste this address into "Replace signing key" on the Haven agent page: ${address}. Parked at ${status.path}. ` + wedgeNote
   };
 }
+async function runtimeSpecOverrideCheck(directory, sidecar, env) {
+  const facts = [];
+  const installed = sidecar?.runtime_spec_override;
+  if (installed) {
+    facts.push(
+      `signer runtime installed under ${describeRuntimeSpecOverride(installed.specs)} (resolved: ${installed.resolved_specs.join(" ")}; directory key ${installed.directory_key})`
+    );
+  }
+  const mcpInstalled = await readMcpSidecarOverride(directory);
+  if (mcpInstalled) {
+    facts.push(
+      `local MCP runtime installed under ${describeRuntimeSpecOverride(mcpInstalled.specs)} (resolved: ${mcpInstalled.resolved_specs.join(" ")}; directory key ${mcpInstalled.directory_key})`
+    );
+  }
+  let shell;
+  try {
+    const active = resolveRuntimeSpecOverride(env);
+    if (active) shell = `set in this shell: ${describeRuntimeSpecOverride(active)} \u2014 a --repair from here installs these, not the pin`;
+  } catch (err) {
+    shell = err instanceof RuntimeSpecOverrideError ? `set in this shell but REFUSED: ${err.message}` : `set in this shell but unreadable: ${err instanceof Error ? err.message : String(err)}`;
+  }
+  if (shell) facts.push(shell);
+  if (facts.length === 0) return void 0;
+  const variables = Object.values(RUNTIME_SPEC_ENV).join(" / ");
+  return {
+    id: "runtime_spec_override",
+    label: "Runtime spec override",
+    ok: false,
+    detail: `runtime spec overridden \u2014 not the pinned manifest (${MCP_RUNTIME_MANIFEST.signerPackage}@${MCP_RUNTIME_MANIFEST.signerVersion}, ${MCP_RUNTIME_MANIFEST.sdkPackage}@${MCP_RUNTIME_MANIFEST.sdkVersion}). ${facts.join(". ")}.`,
+    repair: `Developer override (#2424). To return to the pinned manifest: unset ${variables}, then run ${RERUN} --doctor --repair --runtime <runtime>. If the override is intentional, this finding is the record of it.`
+  };
+}
+async function readMcpSidecarOverride(directory) {
+  try {
+    const parsed = JSON.parse(await promises.readFile(path.join(directory, "mcp-runtime.json"), "utf8"));
+    return parsed.runtime_spec_override;
+  } catch {
+    return void 0;
+  }
+}
 async function readIdentity(directory) {
   try {
     return JSON.parse(await promises.readFile(path.join(directory, "identity.json"), "utf8"));
@@ -3459,6 +3683,18 @@ async function checksForAgent(entry, input, deps) {
       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 if (sidecar.runtime_spec_override) {
+    const matches = await installedRuntimeMatchesVersions(sidecar.runtime_directory, sidecar.cli_path, {
+      signerVersion: sidecar.signer_version,
+      sdkVersion: sidecar.sdk_version
+    });
+    checks.push({
+      id: "signer_runtime",
+      label: "Signer runtime (preinstalled wrapper)",
+      ok: matches,
+      detail: matches ? `Installed ${sidecar.signer_package}@${sidecar.signer_version} at ${sidecar.runtime_directory} (override install \u2014 see runtime_spec_override)` : `Override runtime directory is stale or empty (${sidecar.runtime_directory}) \u2014 the CLI or package versions are missing.`,
+      ...matches ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime} with the same HAVEN_*_SPEC variables set.` }
+    });
   } else {
     const matches = await installedRuntimeMatches(sidecar.runtime_directory, sidecar.cli_path);
     const versionOk = sidecar.signer_version === MCP_RUNTIME_MANIFEST.signerVersion;
@@ -3471,6 +3707,8 @@ async function checksForAgent(entry, input, deps) {
       ...ok ? {} : { repair: `Run: ${RERUN} --doctor --repair --runtime ${input.runtime}` }
     });
   }
+  const overrideCheck = await runtimeSpecOverrideCheck(directory, sidecar, deps.env ?? process.env);
+  if (overrideCheck) checks.push(overrideCheck);
   const hostedUrl = identity?.hosted_mcp_url ?? (identity?.api_url ? `${identity.api_url}/mcp` : void 0);
   if (identity?.api_key && hostedUrl) {
     const probe = await (deps.probeHosted ?? probeHostedMcpTools)(identity.api_key, hostedUrl, deps.fetch);
@@ -3542,7 +3780,7 @@ async function checksForAgent(entry, input, deps) {
         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).`
+        repair: `Run: ${RERUN} --ack-local-tools --setup <token>  (or re-run your original connector command with --ack-local-tools).`
       });
     } else {
       const probe = await (deps.probeSignerTools ?? probeLocalMcpTools)(
@@ -3665,7 +3903,7 @@ async function runDoctor(input, deps = {}) {
       signerCapabilities = result.signerCapabilities;
       for (const check of result.checks) primaryChecksById.set(check.id, check);
     }
-    for (const id of ["credentials", "signer_runtime"]) {
+    for (const id of ["credentials", "signer_runtime", "runtime_spec_override"]) {
       const check = primaryChecksById.get(id);
       if (check) checks.push(check);
     }
@@ -3816,7 +4054,7 @@ async function runRepair(input, deps = {}) {
           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."
+            "Re-run your original connector command (with --local) to repair a local-stdio install."
           ]
         };
       }
@@ -3828,7 +4066,7 @@ async function runRepair(input, deps = {}) {
   const signerPath = path.join(directory, "signer.json");
   const prepared = await prepareSignerRuntime(
     { credentialDirectory: directory, signerPath, homeDir, serverName },
-    { runCommand: deps.runCommand }
+    { runCommand: deps.runCommand, env: deps.env }
   );
   messages.push(...prepared.messages);
   const names = serverNamesFor(serverName);
@@ -3855,6 +4093,7 @@ var init_doctor = __esm({
     init_runtime_manifest();
     init_probes();
     init_signer_runtime();
+    init_runtime_spec_override();
     init_config_writers();
     init_runtime_registry();
     init_signer_consent();
@@ -3862,7 +4101,7 @@ var init_doctor = __esm({
     init_server_names();
     init_storage();
     init_redact();
-    RERUN = "npx @haven_ai/connect@alpha";
+    RERUN = sdk.connectorRerunCommand();
   }
 });
 
@@ -4021,7 +4260,7 @@ function noInstalledClientsError() {
 function promptAbortedError(reason) {
   return new ConnectError(
     "runtime_prompt_aborted",
-    `Runtime not chosen (${reason}). Nothing was written: no agent was created, no credentials were stored, and the Haven setup token is still unused. Run the setup command again, or pass --runtime <name> to skip the prompt.`,
+    `Runtime not chosen (${reason}). Nothing was written: no agent was created, no credentials were stored, and the Haven setup token is still unused. Run the connector command again, or pass --runtime <name> to skip the prompt.`,
     "rerun_connect_and_choose_a_runtime"
   );
 }
@@ -4052,10 +4291,119 @@ function defaultPromptIo() {
   };
 }
 
+// src/wiring-collision.ts
+init_server_names();
+init_signer_runtime();
+init_storage();
+init_tombstone();
+async function detectWiringCollision(input) {
+  const root = defaultCredentialRoot(input.credentialsDir);
+  let entries = [];
+  try {
+    entries = await promises.readdir(root);
+  } catch {
+    return null;
+  }
+  const superseded = [];
+  const taken = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const directory = path.join(root, entry);
+    let identityRaw;
+    try {
+      identityRaw = await promises.readFile(path.join(directory, "identity.json"), "utf8");
+    } catch {
+      continue;
+    }
+    taken.add(entry);
+    let identity;
+    try {
+      identity = JSON.parse(identityRaw);
+    } catch {
+      identity = void 0;
+    }
+    if (!identity?.api_key) continue;
+    if (await pathExists2(path.join(directory, TOMBSTONE_FILENAME))) continue;
+    const sidecar = await readRuntimeSidecar(directory);
+    if (sidecar?.server_name) continue;
+    superseded.push({ directory, agentId: identity.agent_id ?? entry });
+  }
+  if (superseded.length === 0) return null;
+  return {
+    superseded,
+    suggestedServerName: proposeServerSlug(input.agentName, taken)
+  };
+}
+function proposeServerSlug(agentName, taken) {
+  let base = agentName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-").slice(0, 32).replace(/-+$/g, "");
+  if (!slugIsValid(base)) base = "agent";
+  if (!taken.has(base)) return base;
+  for (let n = 2; n < 1e3; n += 1) {
+    const suffix = `-${n}`;
+    const candidate = `${base.slice(0, 32 - suffix.length).replace(/-+$/g, "")}${suffix}`;
+    if (slugIsValid(candidate) && !taken.has(candidate)) return candidate;
+  }
+  throw new Error(`Could not propose an unused server name for ${JSON.stringify(agentName)}.`);
+}
+function slugIsValid(slug) {
+  try {
+    assertValidServerSlug(slug);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var MAX_PROMPT_ATTEMPTS2 = 3;
+async function promptWiringCollisionResolution(collision, agentName, io) {
+  const ids = collision.superseded.map((entry) => entry.agentId).join(", ");
+  io.write(`This machine is already wired to a Haven agent with a live key: ${ids}.
+`);
+  io.write(`Setting up "${agentName}" on the bare haven / haven-signer pair would replace that wiring.
+`);
+  io.write("  r) replace \u2014 re-point haven / haven-signer at the new agent and retire the previous directory locally\n");
+  io.write("     (tombstoned, local key files removed; you still revoke it on the Haven agent page)\n");
+  io.write(`  a) alongside \u2014 install as a named agent (suggested: ${collision.suggestedServerName}) with its own
+`);
+  io.write(`     haven-<name> / haven-signer-<name> pair, leaving the current wiring untouched
+`);
+  io.write("  q) quit \u2014 nothing is written and the setup token stays unused\n");
+  for (let attempt = 0; attempt < MAX_PROMPT_ATTEMPTS2; attempt += 1) {
+    const answer = await io.question("Replace, install alongside, or quit? [r/a/q]: ");
+    if (answer === null) return { action: "abort" };
+    const trimmed = answer.trim().toLowerCase();
+    if (trimmed === "r" || trimmed === "replace") return { action: "replace" };
+    if (trimmed === "q" || trimmed === "quit") return { action: "abort" };
+    if (trimmed === "a" || trimmed === "alongside") {
+      const typed = await io.question(`Server name [${collision.suggestedServerName}]: `);
+      if (typed === null) return { action: "abort" };
+      const serverName = typed.trim() === "" ? collision.suggestedServerName : typed.trim();
+      try {
+        assertValidServerSlug(serverName);
+      } catch (err) {
+        io.write(`${err instanceof Error ? err.message : String(err)}
+`);
+        continue;
+      }
+      return { action: "alongside", serverName };
+    }
+    io.write(`"${trimmed}" is not one of r, a, q.
+`);
+  }
+  return { action: "abort" };
+}
+async function pathExists2(path) {
+  try {
+    await promises.stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/runtime.ts
+init_unwire();
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.1.34-alpha.0";
+var CONNECTOR_VERSION = "0.1.36-alpha.0";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
 function failureOutcomeFor(runtimeHint, error) {
@@ -4160,6 +4508,28 @@ async function executeConnect(options, deps, trace) {
     await assertServerSlugAvailable(options.serverName, options.credentialsDir);
   }
   log("Checked local credential storage \u2014 all clear.");
+  let serverName = options.serverName;
+  let replacing;
+  if (!serverName) {
+    const collision = await detectWiringCollision({
+      credentialsDir: options.credentialsDir,
+      agentName: setup.agent.name
+    });
+    if (collision) {
+      const resolution = await resolveWiringCollision(collision, setup.agent.name, options, deps);
+      if (resolution.action === "replace") {
+        replacing = collision;
+        log(
+          `Replacing the existing haven / haven-signer wiring (previous agent(s): ${supersededIds(collision)}). The previous directory is retired locally once the new wiring is written; nothing is revoked.`
+        );
+      } else {
+        serverName = resolution.serverName;
+        assertValidServerSlug(serverName);
+        await assertServerSlugAvailable(serverName, options.credentialsDir);
+        log(`Installing alongside the existing wiring as a named agent: ${serverNamesFor(serverName).hosted} / ${serverNamesFor(serverName).signer}.`);
+      }
+    }
+  }
   const localKey = generateKey();
   const localApiKey = generateLocalApiKey();
   log("Minting a fresh signing key and API key \u2014 both stay on this machine.");
@@ -4180,7 +4550,10 @@ async function executeConnect(options, deps, trace) {
       // the dashboard can name it. Derived here rather than sent as the raw
       // slug — `serverNamesFor` is the one place the naming rule lives, and
       // the hosted name is what a user pastes into an MCP config.
-      mcpServerName: serverNamesFor(options.serverName).hosted,
+      mcpServerName: serverNamesFor(serverName).hosted,
+      // #2528: 'prose' is the default because it is what a caller who says
+      // nothing is doing — the library entry point is not a --json run.
+      runMode: options.runMode ?? "prose",
       connectorContext: {
         environment_label: options.environmentLabel ?? "Local workspace",
         config_target: installCapabilities.canWriteRuntimeConfig ? "agent runtime MCP config" : "local credential files"
@@ -4192,7 +4565,7 @@ async function executeConnect(options, deps, trace) {
     if (dead) throw dead;
     if (isExpiredSetupChallenge(err)) {
       throw new Error(
-        "The Haven setup challenge expired while connecting. Return to Haven, start a fresh connection, and run its new Connect command. Do not reuse or paste credentials."
+        "The Haven setup challenge expired while connecting. Return to Haven, start a fresh connection, and run its new connector command. Do not reuse or paste credentials."
       );
     }
     throw err;
@@ -4202,7 +4575,7 @@ async function executeConnect(options, deps, trace) {
   const credentialPaths = await writeCredentials({
     baseDir: options.credentialsDir,
     agentId: registration.agent_id,
-    serverName: options.serverName,
+    serverName,
     apiKey: localApiKey,
     delegateKey: localKey.privateKey,
     delegateAddress: localKey.address,
@@ -4241,7 +4614,7 @@ async function executeConnect(options, deps, trace) {
     ackSigner: options.ackSigner,
     ackLocalTools: options.ackLocalTools,
     localMcp: options.localMcp,
-    serverName: options.serverName
+    serverName
   }, {
     onProgress: log,
     // #1543: report "runtime configured" the moment the config write settles,
@@ -4268,7 +4641,7 @@ async function executeConnect(options, deps, trace) {
           environmentLabel: options.environmentLabel ?? "Local workspace"
         });
         if (!early.errorCode || early.errorCode === "manual_runtime_setup_required") {
-          log("\u2192 Action needed: approve this agent's budget in the Haven dashboard \u2014 the approval button is live now. Setup continues here in the meantime.");
+          log(approveBudgetCta(setup, registration.approval_url));
         }
       } catch {
       }
@@ -4280,10 +4653,45 @@ async function executeConnect(options, deps, trace) {
   } else {
     log("Haven setup on this machine is complete.");
   }
+  let supersededAgentsRetiredLocally;
+  const retiredAgentIds = [];
+  if (replacing) {
+    if (runtimeInstall.errorCode) {
+      supersededAgentsRetiredLocally = false;
+      log(
+        `Previous agent(s) ${supersededIds(replacing)} were NOT retired: the runtime install did not complete, so their wiring may still be the only working one. Resolve the install, then retire them with ${RERUN_HINT} --unwire <dir>.`
+      );
+    } else {
+      supersededAgentsRetiredLocally = true;
+      for (const entry of replacing.superseded) {
+        try {
+          await tombstoneDirectoryIfAbsent({
+            directory: entry.directory,
+            agentId: entry.agentId,
+            reason: "replaced by a new setup (--replace)",
+            replacedBy: registration.agent_id
+          });
+          await teardownLocalKeyMaterial(entry.directory, await readIdentityFile(entry.directory));
+          retiredAgentIds.push(entry.agentId);
+          log(`Retired previous agent ${entry.agentId} locally: tombstoned, local key files removed.`);
+        } catch (err) {
+          supersededAgentsRetiredLocally = false;
+          log(`Could not retire previous agent ${entry.agentId} locally: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+    }
+  }
+  let supersededScan = null;
   let supersededAgentIds = [];
   try {
-    supersededAgentIds = await listOtherAgentIds(options.credentialsDir, credentialPaths.directory);
-    if (supersededAgentIds.length > 0) {
+    supersededScan = await listOtherAgentIds(options.credentialsDir, credentialPaths.directory);
+    supersededAgentIds = supersededScan ?? [];
+    if (supersededAgentsRetiredLocally === true) {
+      log("");
+      log(
+        `Replaced: previous agent(s) ${supersededIds(replacing)} are retired on this machine but NOT revoked \u2014 revoke them on the Haven agent page, then restart EVERY long-lived host (gateways, TUI workers, editors): each holds the MCP wiring snapshot from its own start time, and the tombstone speaks only when a stale host next probes the old path.`
+      );
+    } else if (supersededAgentIds.length > 0) {
       log("");
       log(
         `Heads-up: this setup created a NEW agent. Your previous agent(s) \u2014 ${supersededAgentIds.join(", ")} \u2014 still exist with their own keys, and any host that was already running keeps acting as them.`
@@ -4311,23 +4719,31 @@ async function executeConnect(options, deps, trace) {
       restartRequired: runtimeInstall.restartRequired,
       nextUserAction: runtimeInstall.nextUserAction,
       errorCode: runtimeInstall.errorCode,
-      environmentLabel: options.environmentLabel ?? "Local workspace"
+      environmentLabel: options.environmentLabel ?? "Local workspace",
+      // The raw scan result, `null` and all — NOT the flattened
+      // `supersededAgentIds` the outcome carries. Flattening here would hand
+      // the dashboard the same ambiguity this field exists to remove (#2561).
+      supersededAgentIds: supersededScan
     });
   } 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) {
+  const narrateApprovalWait = options.waitForApproval === true || options.waitForApproval === void 0 && (deps.isStdoutTty ?? Boolean(process.stdout.isTTY));
+  if (narrateApprovalWait && !runtimeInstall.errorCode) {
     approval = await waitForBudgetApproval(api, registration.setup_id, localApiKey, log, options.approvalWait);
   }
-  printNextSteps(runtimeInstall, log, approval);
+  printNextSteps(runtimeInstall, log, approval, registration.approval_url);
   const outcome = completionOutcome({
     runtimeInstall,
     delegateAddress: registration.delegate_address,
     hostedMcpUrl: registration.hosted_mcp_url,
     supersededAgentIds,
+    supersededAgentsRetiredLocally,
+    ...replacing ? { retiredAgentIds } : {},
     setupChallengeExpiresAt: setup.challenge.expires_at,
-    approvalRequired: registration.agent_status === "pending_approval"
+    approvalRequired: registration.agent_status === "pending_approval",
+    approvalUrl: registration.approval_url
   });
   if (await recordConnectOutcome(deps, credentialPaths.directory, outcome)) {
     log(`Saved this run's outcome to ${CONNECT_OUTCOME_FILENAME} in the agent's credential directory.`);
@@ -4360,7 +4776,16 @@ function completionOutcome(input) {
       instruction: manualSetup ? "Finish the manual MCP setup using the secret-free references shown in normal Connect output, then start a fresh session." : runtimeProfile(runtimeInstall.runtime).activationInstruction
     },
     next_action: nextAction2,
-    approval: { required: input.approvalRequired, expires_at: null },
+    approval: {
+      required: input.approvalRequired,
+      expires_at: null,
+      // Only when there is something to approve AND the backend supplied a
+      // link. Never synthesised here: the connector does not know the
+      // dashboard's origin, and a guessed URL is worse than none — it is the
+      // "do not invent one" rule the agent runbook states, applied to the
+      // tool rather than the agent.
+      ...input.approvalRequired && input.approvalUrl ? { url: input.approvalUrl } : {}
+    },
     verification: {
       tools: ["haven_get_agent", "haven_get_allowances"],
       instruction: runtimeVerificationInstruction(runtimeInstall.runtime)
@@ -4378,6 +4803,8 @@ function completionOutcome(input) {
     // agents" is a fact a caller needs, and an omitted key would be
     // indistinguishable from an older connector that never reported it.
     superseded_agent_ids: input.supersededAgentIds ?? [],
+    ...input.supersededAgentsRetiredLocally !== void 0 ? { superseded_agents_retired_locally: input.supersededAgentsRetiredLocally } : {},
+    ...input.retiredAgentIds ? { retired_agent_ids: input.retiredAgentIds } : {},
     ...input.setupChallengeExpiresAt ? { setup_challenge_expires_at: input.setupChallengeExpiresAt } : {},
     ...runtimeInstall.errorCode ? { error: { code: runtimeInstall.errorCode, next_action: nextAction2 } } : {}
   };
@@ -4399,10 +4826,38 @@ function installedClientProse(hint) {
   return `Haven can see these agent clients installed here, likeliest first: ${found.join(", ")}.${suggestion} `;
 }
 function runtimeSelectionPrompt(options, deps) {
-  if (options.interactive !== true) return void 0;
-  if (!(deps.isTty ?? Boolean(process.stdin.isTTY))) return void 0;
+  if (!interactivePromptAllowed(options, deps)) return void 0;
   return deps.promptRuntime ?? (() => resolveRuntimeByInstalledClientPrompt());
 }
+function interactivePromptAllowed(options, deps) {
+  if (options.interactive !== true) return false;
+  return deps.isTty ?? Boolean(process.stdin.isTTY);
+}
+function supersededIds(collision) {
+  return collision.superseded.map((entry) => entry.agentId).join(", ");
+}
+async function resolveWiringCollision(collision, agentName, options, deps) {
+  if (options.replaceExistingWiring) return { action: "replace" };
+  if (interactivePromptAllowed(options, deps)) {
+    const prompt = deps.promptWiringCollision ?? ((c, name) => promptWiringCollisionResolution(c, name, defaultPromptIo()));
+    const resolution = await prompt(collision, agentName);
+    if (resolution.action === "abort") {
+      throw new ConnectError(
+        "wiring_collision_declined",
+        `Setup stopped at your request: this machine is already wired to ${supersededIds(collision)} and you chose neither to replace that wiring nor to install alongside it. Nothing was written: no agent was created, no credentials were stored, and the Haven setup token is still unused. Run the connector command again with --replace to re-point haven / haven-signer at the new agent, or with --name <slug> (e.g. --name ${collision.suggestedServerName}) to install alongside.`,
+        "rerun_connect_with_replace_or_name",
+        { supersededAgentIds: collision.superseded.map((e) => e.agentId), suggestedServerName: collision.suggestedServerName }
+      );
+    }
+    return resolution;
+  }
+  throw new ConnectError(
+    "wiring_collision",
+    `This machine is already wired to a Haven agent with a live key (${supersededIds(collision)}), and setting up "${agentName}" on the bare haven / haven-signer pair would replace that wiring. Nothing was written and the Haven setup token is still unused. If you are an AI agent running this command: do NOT add a flag yourself \u2014 relay this to your user and stop. Your user decides: REPLACE the existing wiring (re-run the same command with --replace added, which re-points the pair at the new agent and retires the previous directory locally \u2014 they still revoke the old agent on the Haven agent page), or install ALONGSIDE it (re-run with --name <slug> added, e.g. --name ${collision.suggestedServerName}, which gives the new agent its own haven-<slug> / haven-signer-<slug> pair). Re-run only with the flag your user chooses.`,
+    "relay_wiring_collision_to_user",
+    { supersededAgentIds: collision.superseded.map((e) => e.agentId), suggestedServerName: collision.suggestedServerName }
+  );
+}
 function failedConnectOutcome(runtimeHint, error) {
   const message = error instanceof Error ? error.message : "";
   const code = error instanceof ConnectError ? error.code : /Node\.js >=/i.test(message) ? "unsupported_node_version" : /setup challenge.*expired|expired or invalid/i.test(message) ? "setup_challenge_expired_or_invalid" : /only available for Claude Code and Codex/i.test(message) ? "local_mcp_unsupported_runtime" : "connect_failed";
@@ -4433,7 +4888,9 @@ function failedConnectOutcome(runtimeHint, error) {
       ...error instanceof ConnectError && message ? { message: redactForAutomation(message) } : {},
       ...error instanceof ConnectError && error.details.allowedRuntimes ? { allowed_runtimes: error.details.allowedRuntimes } : {},
       ...error instanceof ConnectError && error.details.installedClients?.length ? { installed_clients: error.details.installedClients } : {},
-      ...error instanceof ConnectError && error.details.suggestedRuntime ? { suggested_runtime: error.details.suggestedRuntime } : {}
+      ...error instanceof ConnectError && error.details.suggestedRuntime ? { suggested_runtime: error.details.suggestedRuntime } : {},
+      ...error instanceof ConnectError && error.details.supersededAgentIds ? { superseded_agent_ids: error.details.supersededAgentIds } : {},
+      ...error instanceof ConnectError && error.details.suggestedServerName ? { suggested_name: error.details.suggestedServerName } : {}
     }
   };
 }
@@ -4449,6 +4906,22 @@ function printSetupSummary(setup, log) {
   }
   log(`Setup challenge expires at ${setup.challenge.expires_at}. If it expires, return to Haven for a fresh setup and rerun Connect \u2014 do not reuse or paste credentials.`);
 }
+function approveBudgetCta(setup, approvalUrl) {
+  const where = approvalUrl ? `at ${approvalUrl}` : "in the Haven dashboard";
+  const budgetPhrase = setup.agent_budget.length > 0 ? setup.agent_budget.map((budget) => `up to ${describeSetupBudget(budget)}`).join(", ") : void 0;
+  if (budgetPhrase) {
+    return `\u2192 Action needed: approve this agent's budget \u2014 ${budgetPhrase} from ${setup.haven_wallet.name} on ${setup.haven_wallet.network} \u2014 ${where}. The approval button is live now; setup continues here in the meantime.`;
+  }
+  return `\u2192 Action needed: approve this agent's budget ${where} \u2014 the approval button is live now. Setup continues here in the meantime.`;
+}
+function describeSetupBudget(budget) {
+  return describeApprovedBudget({
+    token_symbol: budget.token_symbol,
+    token_address: budget.token_address,
+    amount: budget.allowance_amount,
+    reset_period_min: budget.reset_period_min
+  });
+}
 function assertSetupChallengeIsUsable(expiresAt) {
   const expiresAtMs = Date.parse(expiresAt);
   if (!Number.isNaN(expiresAtMs) && expiresAtMs > Date.now()) return;
@@ -4460,7 +4933,7 @@ function deadSetupTokenError(err) {
   if (!(err instanceof ConnectRequestError) || err.status !== 410 && err.status !== 401) return null;
   return new ConnectError(
     "setup_challenge_expired_or_invalid",
-    "This Haven setup token is expired or invalid \u2014 tokens are single-use and expire 30 minutes after the dashboard issues them, and a mistyped token reads the same way. Return to Haven, start a fresh connection, and run its new Connect command. No local credentials were written.",
+    "This Haven setup token is expired or invalid \u2014 tokens are single-use and expire 30 minutes after the dashboard issues them, and a mistyped token reads the same way. Return to Haven, start a fresh connection, and run its new connector command. No local credentials were written.",
     "return_to_haven_for_fresh_setup"
   );
 }
@@ -4561,18 +5034,19 @@ async function waitForBudgetApproval(api, setupId, apiKey, log, options = {}) {
   );
   return "pending";
 }
-function completionHandoffLines(result, approval) {
+function completionHandoffLines(result, approval, approvalUrl) {
+  const approveStep = approvalUrl ? `Approve the budget at ${approvalUrl}. Approval \u2014 not restarting \u2014 unlocks Haven tools.` : "Return to Haven and approve the budget. Approval \u2014 not restarting \u2014 unlocks Haven tools.";
   if (result.errorCode === "manual_runtime_setup_required") {
     return [
       "Next steps:",
-      "1. Return to Haven and approve the budget. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+      `1. ${approveStep}`,
       "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)}`
     ];
   }
   if (result.errorCode) {
     return [
-      "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."
+      "Recovery: runtime setup is not complete. Resolve the reported problem, then return to Haven for a fresh connection and run its new connector command. Do not manually edit runtime config or paste credentials into prompts, logs, or config."
     ];
   }
   if (approval === "ended") {
@@ -4591,7 +5065,7 @@ function completionHandoffLines(result, approval) {
   }
   return [
     "Next steps:",
-    "1. Return to Haven and approve the budget. Approval \u2014 not restarting \u2014 unlocks Haven tools.",
+    `1. ${approveStep}`,
     `2. ${activation}`,
     `3. ${runtimeVerificationInstruction(result.runtime)}`
   ];
@@ -4605,14 +5079,14 @@ function activationInstructionWithWhy(profile) {
   }
   return profile.activationInstruction;
 }
-var RERUN_HINT = "npx @haven_ai/connect@alpha";
+var RERUN_HINT = sdk.connectorRerunCommand();
 async function listOtherAgentIds(baseDir, currentDirectory) {
   const root = defaultCredentialRoot(baseDir);
   let entries = [];
   try {
     entries = await promises.readdir(root);
   } catch {
-    return [];
+    return null;
   }
   const ids = [];
   for (const entry of entries) {
@@ -4632,8 +5106,8 @@ async function listOtherAgentIds(baseDir, currentDirectory) {
   }
   return ids;
 }
-function printNextSteps(result, log, approval) {
-  for (const line of completionHandoffLines(result, approval)) log(line);
+function printNextSteps(result, log, approval, approvalUrl) {
+  for (const line of completionHandoffLines(result, approval, approvalUrl)) log(line);
 }
 
 // src/args.ts
@@ -4655,6 +5129,7 @@ function parseArgs(argv, env = process.env) {
   let tombstoneReplacedBy;
   let unwire;
   let unwireDir;
+  let replace = false;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -4694,6 +5169,8 @@ function parseArgs(argv, env = process.env) {
       options.runtimeForce = requireValue(argv, ++i, arg);
     } else if (arg === "--credentials-dir") {
       options.credentialsDir = requireValue(argv, ++i, arg);
+    } else if (arg === "--replace") {
+      replace = true;
     } else if (arg === "--name") {
       options.serverName = requireValue(argv, ++i, arg);
       assertValidServerSlug(options.serverName);
@@ -4719,6 +5196,17 @@ function parseArgs(argv, env = process.env) {
   if (help) {
     return { options, help, json, doctor, repair, tombstone, rekey };
   }
+  if (replace) {
+    if (rekeyPhase || tombstoneDir || unwire || doctor || repair) {
+      throw new Error("--replace belongs to a --setup run: it says what to do when the bare haven / haven-signer pair is already wired to another agent.");
+    }
+    if (options.serverName) {
+      throw new Error(
+        "--replace and --name contradict each other: --replace overwrites the bare haven / haven-signer wiring, --name installs alongside it under its own pair. Pass one of them."
+      );
+    }
+    options.replaceExistingWiring = true;
+  }
   if (rekey) {
     if (options.setupToken) {
       throw new Error("--rekey replaces an existing agent's key; it does not take --setup. Drop one of them.");
@@ -4797,6 +5285,12 @@ function helpText() {
     "  --runtime-force <name>     Escape hatch: use exactly this runtime, ignoring environment detection.",
     "  --credentials-dir <path>   Credential directory fallback. Defaults to ~/.haven/agents.",
     "  --environment-label <text> Non-sensitive label shown in Haven setup review.",
+    "  --replace                  When this machine is already wired to a different Haven agent on the bare",
+    "                             haven / haven-signer pair, re-point that pair at the new agent and retire the",
+    "                             previous agent directory locally (tombstoned, local key files removed).",
+    "                             Nothing is revoked \u2014 revoke the old agent on the Haven agent page. Without",
+    "                             this flag a non-interactive run REFUSES such a collision (wiring_collision)",
+    "                             and an interactive terminal is asked; --name installs alongside instead.",
     "  --name <slug>              Wiring slug for a NAMED agent: writes haven-<slug> / haven-signer-<slug>",
     "                             MCP entries and stores credentials at ~/.haven/agents/<slug>/, so several",
     "                             agents can run side by side in one runtime. 1-32 lowercase letters, digits,",
@@ -4900,13 +5394,13 @@ async function runCli(argv, io = {
   }
   if (parsed.tombstone) {
     const { writeAgentTombstone: writeAgentTombstone2 } = await Promise.resolve().then(() => (init_tombstone(), tombstone_exports));
-    const { readFile: readFile13 } = await import('fs/promises');
-    const { join: join11 } = await import('path');
+    const { readFile: readFile14 } = await import('fs/promises');
+    const { join: join12 } = await import('path');
     try {
       let agentId = "unknown";
       try {
         const identity = JSON.parse(
-          await readFile13(join11(parsed.tombstone.directory, "identity.json"), "utf8")
+          await readFile14(join12(parsed.tombstone.directory, "identity.json"), "utf8")
         );
         agentId = identity.agent_id ?? "unknown";
       } catch {
@@ -4945,10 +5439,10 @@ async function runCli(argv, io = {
   if (parsed.unwire) {
     const { unwireAgent: unwireAgent2 } = await Promise.resolve().then(() => (init_unwire(), unwire_exports));
     const { homedir: homedir10 } = await import('os');
-    const { join: join11 } = await import('path');
+    const { join: join12 } = await import('path');
     const homeDir = homedir10();
-    const root = parsed.options.credentialsDir ?? join11(homeDir, ".haven", "agents");
-    const directory = parsed.unwireDir ?? (parsed.options.serverName ? join11(root, parsed.options.serverName) : root);
+    const root = parsed.options.credentialsDir ?? join12(homeDir, ".haven", "agents");
+    const directory = parsed.unwireDir ?? (parsed.options.serverName ? join12(root, parsed.options.serverName) : root);
     try {
       const result = await unwireAgent2({
         directory,
@@ -5115,12 +5609,23 @@ async function runCli(argv, io = {
     const result = await runConnect(
       {
         ...parsed.options,
-        waitForApproval: !parsed.json,
+        // #1377 D / #2484: leave prose runs UNSPECIFIED (undefined) so
+        // runConnect's stdout-TTY narration gate decides whether there is a
+        // watching human to narrate to — an agent invoking prose as a tool
+        // call has none and must not sit opaque in the wait. --json stays an
+        // explicit false (skip, emit promptly).
+        waitForApproval: parsed.json ? false : void 0,
         // #1719: only a human-facing run may be asked which installed client to
         // configure. --json is the automation contract — it must fail with a
         // machine-readable code, never block on stdin. runConnect additionally
         // requires a real TTY before it prompts.
-        interactive: !parsed.json
+        interactive: !parsed.json,
+        // #2528: reported to the backend at register, so the funnel can tell a
+        // machine-readable run from a narrated one. Read from the SAME
+        // `parsed.json` the three flags above use, rather than inferred later
+        // from `waitForApproval` — that flag is already false for a prose run
+        // with no TTY (#2484), so inferring would mislabel real prose runs.
+        runMode: parsed.json ? "json" : "prose"
       },
       {
         log: (message) => (parsed.json ? io.stderr : io.stdout)(`${message}