@haven_ai/connect 0.1.30-alpha.0 → 0.1.32-alpha.0

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import crypto from 'crypto';
 import { Wallet } from 'ethers';
-import { mkdir, rm, stat, readdir, readFile, chmod, access, writeFile, unlink, rename } from 'fs/promises';
+import { mkdir, rm, stat, readdir, readFile, writeFile, chmod, access, unlink, rename } from 'fs/promises';
 import { homedir, platform } from 'os';
 import { join, resolve, dirname, basename } from 'path';
 import { ensureConsent, computeConsentHash, loadCredentials, consentInputFromClient, registeredToolNames, MCP_VERSION } from '@haven_ai/mcp';
@@ -147,6 +147,9 @@ var init_key = __esm({
 function redactSecrets(value) {
   return value.replace(API_KEY_RE, "sk_agent_[redacted]").replace(PRIVATE_KEY_RE, "0x[redacted-private-key]");
 }
+function redactForAutomation(value) {
+  return redactSecrets(value).replace(/(?:~|\/)[^\s`"']*\/(?:identity|signer|agent)\.json\b/g, "[credential-file-redacted]").replace(/(?:~|\/)[^\s`"']*\/\.env\b/g, "[credential-env-redacted]");
+}
 function shortAddress(address) {
   if (!/^0x[0-9a-fA-F]{40}$/.test(address)) return address;
   return `${address.slice(0, 6)}...${address.slice(-4)}`;
@@ -494,11 +497,19 @@ async function restrictPermissions(path, mode, warn) {
     );
   }
 }
-var REKEY_PENDING_FILENAME, REKEY_PENDING_TTL_MS;
+async function writeConnectOutcomeRecord(directory, outcome, warn) {
+  const path = join(directory, CONNECT_OUTCOME_FILENAME);
+  await writeFile(path, `${JSON.stringify(outcome, null, 2)}
+`, { mode: 384 });
+  await restrictPermissions(path, 384, warn);
+  return path;
+}
+var REKEY_PENDING_FILENAME, REKEY_PENDING_TTL_MS, CONNECT_OUTCOME_FILENAME;
 var init_storage = __esm({
   "src/storage.ts"() {
     REKEY_PENDING_FILENAME = "rekey-pending.json";
     REKEY_PENDING_TTL_MS = 24 * 60 * 60 * 1e3;
+    CONNECT_OUTCOME_FILENAME = "last-connect-outcome.json";
   }
 });
 function mcpPackageSpec() {
@@ -517,9 +528,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.1.30-alpha.0",
+      sdkVersion: "0.1.32-alpha.0",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.1.30-alpha.0",
+      signerVersion: "0.1.32-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
@@ -661,6 +672,97 @@ function isHermesEnvAssignment(line, envKey) {
 function isAmbiguousHermesEnvLine(line, envKey) {
   return new RegExp(`^\\s*(?:export[ \\t]+)?${envKey}\\b`).test(line);
 }
+function removeHermesYaml(existingYaml, names, configPath) {
+  if (!existingYaml?.trim()) return existingYaml ?? "";
+  const doc = parseDocument(existingYaml, { keepSourceTokens: true });
+  if (doc.errors.length > 0 || !isMap(doc.contents)) {
+    throw new UnreadableRuntimeConfigError(configPath ?? "the Hermes config", "it is not a YAML object");
+  }
+  const mcpPair = doc.contents.items.find((item) => item.key?.toString() === "mcp_servers");
+  if (!mcpPair || !isMap(mcpPair.value)) return existingYaml;
+  const toRemove = mcpPair.value.items.filter((item) => {
+    const name = item.key?.toString();
+    return name === names.hosted || name === names.signer;
+  });
+  if (toRemove.length === 0) return existingYaml;
+  if (toRemove.length !== mcpPair.value.items.length && toRemove.some((item) => !item.key?.range || !item.value?.range)) {
+    throw new UnreadableRuntimeConfigError(configPath ?? "the Hermes config", "an MCP server entry cannot be safely removed");
+  }
+  let out = existingYaml;
+  const ranges = toRemove.map((item) => {
+    const keyStart = item.key.range[0];
+    const valueEnd = item.value.range[1];
+    const lineStart = existingYaml.lastIndexOf("\n", keyStart - 1) + 1;
+    let end = valueEnd;
+    if (existingYaml.slice(end).startsWith("\r\n")) end += 2;
+    else if (existingYaml[end] === "\n") end += 1;
+    return [lineStart, end];
+  });
+  ranges.sort((a, b) => b[0] - a[0]);
+  for (const [start, end] of ranges) out = out.slice(0, start) + out.slice(end);
+  if (toRemove.length === mcpPair.value.items.length) {
+    const reparsed = parseDocument(out, { keepSourceTokens: true });
+    if (!reparsed.errors.length && isMap(reparsed.contents)) {
+      const pair = reparsed.contents.items.find((item) => item.key?.toString() === "mcp_servers");
+      if (pair && pair.key?.range && pair.value?.range) {
+        const keyStart = pair.key.range[0];
+        const valueEnd = pair.value.range[1];
+        const lineStart = out.lastIndexOf("\n", keyStart - 1) + 1;
+        let end = valueEnd;
+        if (out.slice(end).startsWith("\r\n")) end += 2;
+        else if (out[end] === "\n") end += 1;
+        out = out.slice(0, lineStart) + out.slice(end);
+      }
+    }
+  }
+  return out;
+}
+function removeHermesEnv(existingEnv, envKey) {
+  if (!existingEnv) return "";
+  const lineEnding = existingEnv.includes("\r\n") ? "\r\n" : "\n";
+  const hasTrailingNewline = /\r?\n$/.test(existingEnv);
+  const lines = existingEnv.split(/\r?\n/);
+  if (hasTrailingNewline) lines.pop();
+  let removed = 0;
+  const kept = lines.filter((line) => {
+    if (isHermesEnvAssignment(line, envKey)) {
+      removed += 1;
+      return false;
+    }
+    if (isAmbiguousHermesEnvLine(line, envKey)) {
+      throw new Error("Hermes environment contains an ambiguous managed key");
+    }
+    return true;
+  });
+  if (removed === 0) return existingEnv;
+  const joined = kept.join(lineEnding);
+  return hasTrailingNewline ? `${joined}${lineEnding}` : joined;
+}
+function removeJsonMcpConfig(existingJson, serverRoot, names, configPath) {
+  if (!existingJson?.trim()) return existingJson ?? "";
+  const config = parseJsonObject(existingJson, configPath);
+  const root = config[serverRoot];
+  if (!root || typeof root !== "object" || Array.isArray(root)) return existingJson;
+  const servers = root;
+  let removed = false;
+  for (const name of [names.hosted, names.signer]) {
+    if (name in servers) {
+      delete servers[name];
+      removed = true;
+    }
+  }
+  if (!removed) return existingJson;
+  if (Object.keys(servers).length === 0) delete config[serverRoot];
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+function removeCodexToml(existingToml, names) {
+  let next = removeTomlTableTree(
+    removeTomlTableTree(existingToml, `mcp_servers.${names.codexHosted}`),
+    `mcp_servers.${names.codexSigner}`
+  );
+  return next;
+}
 function appendHermesMcpServers(source, servers) {
   const documentEnd = /(?:^|\n)[ \t]*\.\.\.[ \t]*(?:#[^\n]*)?\r?\n?$/.exec(source);
   if (documentEnd) {
@@ -1933,17 +2035,22 @@ var init_skill_install = __esm({
 });
 
 // src/connect-error.ts
+function isConnectError(err) {
+  return err instanceof ConnectError;
+}
 var ConnectError;
 var init_connect_error = __esm({
   "src/connect-error.ts"() {
     ConnectError = class extends Error {
       code;
       nextAction;
-      constructor(code, message, nextAction2) {
+      details;
+      constructor(code, message, nextAction2, details = {}) {
         super(message);
         this.name = "ConnectError";
         this.code = code;
         this.nextAction = nextAction2;
+        this.details = details;
       }
     };
   }
@@ -1966,7 +2073,8 @@ async function resolveRuntimeSelection(explicit, force, options = {}) {
       throw new ConnectError(
         "runtime_force_unrecognized",
         `Unknown --runtime-force value "${force}". Valid values: ${RUNTIME_FLAG_VALUES}.`,
-        "rerun_connect_with_a_valid_runtime_name"
+        "rerun_connect_with_a_valid_runtime_name",
+        { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST }
       );
     }
     return { runtime: forced, source: "force" };
@@ -1979,7 +2087,8 @@ async function resolveRuntimeSelection(explicit, force, options = {}) {
       throw new ConnectError(
         "runtime_unrecognized",
         `"${supplied}" is not an agent runtime Haven knows. Valid values: ${RUNTIME_FLAG_VALUES} (the aliases cowork, codex and openclaw are accepted too). Re-run with one of those, or --runtime other to store credentials and finish the MCP setup by hand. Nothing was written and the Haven setup token is still unused.`,
-        "rerun_connect_with_a_valid_runtime_name"
+        "rerun_connect_with_a_valid_runtime_name",
+        { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST }
       );
     }
     return { runtime: detected, source: "detected", discardedHint: supplied };
@@ -2014,7 +2123,7 @@ function detectRuntime(env) {
   if (env.HERMES_HOME || env.HERMES_AGENT) return "hermes";
   return null;
 }
-var RUNTIME_PROFILES, RUNTIME_ALIASES, RUNTIME_FLAG_VALUES;
+var RUNTIME_PROFILES, RUNTIME_ALIASES, RUNTIME_FLAG_VALUE_LIST, RUNTIME_FLAG_VALUES;
 var init_runtime_registry = __esm({
   "src/runtime-registry.ts"() {
     init_connect_error();
@@ -2133,7 +2242,18 @@ var init_runtime_registry = __esm({
       other: "other",
       manual: "other"
     };
-    RUNTIME_FLAG_VALUES = "claude-code, codex-cli, codex-desktop, cursor, vscode, vscode-insiders, claude-desktop, hermes, other";
+    RUNTIME_FLAG_VALUE_LIST = [
+      "claude-code",
+      "codex-cli",
+      "codex-desktop",
+      "cursor",
+      "vscode",
+      "vscode-insiders",
+      "claude-desktop",
+      "hermes",
+      "other"
+    ];
+    RUNTIME_FLAG_VALUES = RUNTIME_FLAG_VALUE_LIST.join(", ");
   }
 });
 async function acknowledgeLocalSignerConsent(signerPath, log) {
@@ -2632,14 +2752,49 @@ 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, {
   TOMBSTONE_FILENAME: () => TOMBSTONE_FILENAME,
   TOMBSTONE_MARKER: () => TOMBSTONE_MARKER,
+  defaultTombstonesDir: () => defaultTombstonesDir,
   readAgentTombstone: () => readAgentTombstone,
+  readTombstoneRecords: () => readTombstoneRecords,
   writeAgentTombstone: () => writeAgentTombstone
 });
+function defaultTombstonesDir(baseDir) {
+  return join(baseDir ?? join(homedir(), ".haven"), "tombstones");
+}
+async function readTombstoneRecords(tombstonesDir) {
+  const root = tombstonesDir ?? defaultTombstonesDir();
+  let entries = [];
+  try {
+    entries = await readdir(root);
+  } catch {
+    return [];
+  }
+  const records = [];
+  for (const entry of entries) {
+    if (!entry.endsWith(".json")) continue;
+    const recordPath = join(root, entry);
+    try {
+      const parsed = JSON.parse(await readFile(recordPath, "utf8"));
+      if (typeof parsed?.agent_id === "string") {
+        records.push({ ...parsed, recordPath });
+      }
+    } catch {
+    }
+  }
+  return records;
+}
 function tombstoneScript(info) {
   const lines = [
     `${TOMBSTONE_MARKER}: this Haven agent was retired.`,
@@ -2670,7 +2825,11 @@ function tombstoneScript(info) {
 async function writeAgentTombstone(input) {
   const dirStat = await stat(input.directory).catch(() => null);
   if (!dirStat?.isDirectory()) {
-    throw new Error(`Not a directory: ${input.directory} \u2014 nothing to tombstone.`);
+    throw new ConnectError(
+      "tombstone_directory_not_found",
+      `Not a directory: ${input.directory} \u2014 nothing to tombstone. Agent directories are named by their wiring SLUG when the agent has one, and by the agent id otherwise \u2014 so a path built from an agent id will not exist for a named agent. List ~/.haven/agents (or read the directories from --doctor --json) and pass one of those.`,
+      "retry_with_an_existing_agent_directory"
+    );
   }
   const info = {
     // reason / replaced_by are persisted to disk and re-emitted to the host's
@@ -2687,8 +2846,13 @@ async function writeAgentTombstone(input) {
   const wrapperPath = join(binDir, "haven-signer.mjs");
   await writeFile(wrapperPath, tombstoneScript(info), "utf8");
   await chmod(wrapperPath, 493);
-  await writeFile(join(input.directory, TOMBSTONE_FILENAME), JSON.stringify(info, null, 2) + "\n", "utf8");
-  return info;
+  const record = JSON.stringify(info, null, 2) + "\n";
+  await writeFile(join(input.directory, TOMBSTONE_FILENAME), record, "utf8");
+  const root = input.tombstonesDir ?? defaultTombstonesDir();
+  await mkdir(root, { recursive: true, mode: 448 });
+  const recordPath = join(root, `${info.agent_id}.json`);
+  await writeFile(recordPath, record, { mode: MIRROR_MODE });
+  return { ...info, recordPath };
 }
 async function readAgentTombstone(directory) {
   try {
@@ -2699,15 +2863,185 @@ async function readAgentTombstone(directory) {
     return null;
   }
 }
-var TOMBSTONE_FILENAME, TOMBSTONE_MARKER;
+var TOMBSTONE_FILENAME, MIRROR_MODE, TOMBSTONE_MARKER;
 var init_tombstone = __esm({
   "src/tombstone.ts"() {
     init_redact();
+    init_connect_error();
     TOMBSTONE_FILENAME = "TOMBSTONE.json";
+    MIRROR_MODE = 384;
     TOMBSTONE_MARKER = "HAVEN-TOMBSTONE";
   }
 });
 
+// src/unwire.ts
+var unwire_exports = {};
+__export(unwire_exports, {
+  unwireAgent: () => unwireAgent
+});
+function identityAt(directory) {
+  return readFile(join(directory, "identity.json"), "utf8").then((raw) => JSON.parse(raw)).catch(() => null);
+}
+function removeForModel(text, model, names, path) {
+  switch (model.kind) {
+    case "yaml":
+      return removeHermesYaml(text, names, path);
+    case "toml":
+      return removeCodexToml(text, names);
+    case "json":
+      return removeJsonMcpConfig(text, model.serverRoot ?? "mcpServers", names, path);
+  }
+}
+function envLineValue(envText, envKey) {
+  const line = envText.split(/\r?\n/).find((candidate) => new RegExp(`^\\s*(?:export[ \\t]+)?${envKey}[ \\t]*=`).test(candidate));
+  if (!line) return void 0;
+  let value = line.slice(line.indexOf("=") + 1);
+  value = value.trim();
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    value = value.slice(1, -1);
+  }
+  return value;
+}
+async function readOptionalText(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch {
+    return null;
+  }
+}
+async function unwireAgent(input) {
+  const homeDir = input.homeDir ?? homedir();
+  const [identity, sidecar] = await Promise.all([identityAt(input.directory), readRuntimeSidecar(input.directory)]);
+  const agentId = identity?.agent_id ?? "unknown";
+  const slug = input.slug ?? sidecar?.server_name;
+  const names = serverNamesFor(slug);
+  const runtimes = [];
+  let tombstoned = false;
+  const tombstonePath = 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;
+  }
+  for (const model of RUNTIMES) {
+    const path = runtimeConfigPathFor(model.runtime, homeDir);
+    if (path === null) continue;
+    const text = await readOptionalText(path);
+    if (text === null) continue;
+    try {
+      if (!slug) {
+        const owned = sidecar?.wrapper_path != null && text.includes(sidecar.wrapper_path);
+        if (!owned) {
+          const pairPresent = removeForModel(text, model, names, path) !== text;
+          if (!pairPresent) continue;
+          runtimes.push({
+            runtime: model.runtime,
+            label: model.label,
+            path,
+            status: "refused",
+            detail: "the bare haven / haven-signer pair in this config launches a different agent (no wrapper from this directory in the file); refusing to guess which one is yours"
+          });
+          continue;
+        }
+      }
+      const next = removeForModel(text, model, names, path);
+      if (next === text) continue;
+      await writeFile(path, next, "utf8");
+      runtimes.push({ runtime: model.runtime, label: model.label, path, status: "removed" });
+    } catch (err) {
+      if (err instanceof UnreadableRuntimeConfigError) {
+        runtimes.push({ runtime: model.runtime, label: model.label, path, status: "unreadable", detail: err.message });
+        continue;
+      }
+      throw err;
+    }
+  }
+  const envPath = hermesEnvPath(homeDir);
+  const envText = await readOptionalText(envPath);
+  if (envText !== null) {
+    try {
+      if (!slug) {
+        const value = envLineValue(envText, names.hermesEnvKey);
+        if (value === void 0) {
+        } else if (!identity?.api_key) {
+          runtimes.push({
+            runtime: "hermes",
+            label: "Hermes env",
+            path: envPath,
+            status: "refused",
+            detail: "MCP_HAVEN_API_KEY is shared by unnamed agents and this directory has no stored API key to compare against; refusing to remove another agent's credential"
+          });
+        } else if (value !== identity.api_key) {
+          runtimes.push({
+            runtime: "hermes",
+            label: "Hermes env",
+            path: envPath,
+            status: "refused",
+            detail: "MCP_HAVEN_API_KEY in the Hermes env holds a different agent's key; refusing to remove another agent's credential"
+          });
+        } else {
+          const next = removeHermesEnv(envText, names.hermesEnvKey);
+          if (next !== envText) {
+            await writeFile(envPath, next, "utf8");
+            runtimes.push({ runtime: "hermes", label: "Hermes env", path: envPath, status: "removed" });
+          }
+        }
+      } else {
+        const next = removeHermesEnv(envText, names.hermesEnvKey);
+        if (next !== envText) {
+          await writeFile(envPath, next, "utf8");
+          runtimes.push({ runtime: "hermes", label: "Hermes env", path: envPath, status: "removed" });
+        }
+      }
+    } catch (err) {
+      if (err instanceof Error && err.message.includes("ambiguous managed key")) {
+        runtimes.push({
+          runtime: "hermes",
+          label: "Hermes env",
+          path: envPath,
+          status: "refused",
+          detail: err.message
+        });
+      } else {
+        throw err;
+      }
+    }
+  }
+  await Promise.all([
+    rm(join(input.directory, "signer.json"), { force: true }),
+    rm(join(input.directory, REKEY_PENDING_FILENAME), { force: true })
+  ]);
+  if (identity && identity.api_key !== void 0) {
+    const { api_key: _dropped, ...rest } = identity;
+    await writeFile(join(input.directory, "identity.json"), `${JSON.stringify(rest, null, 2)}
+`, { mode: 384 });
+  }
+  return { directory: input.directory, agentId, slug, tombstoned, runtimes };
+}
+var RUNTIMES;
+var init_unwire = __esm({
+  "src/unwire.ts"() {
+    init_config_writers();
+    init_server_names();
+    init_signer_runtime();
+    init_tombstone();
+    init_storage();
+    RUNTIMES = [
+      { runtime: "hermes", label: "Hermes Agent config", kind: "yaml" },
+      { runtime: "codex-cli", label: "Codex config", kind: "toml" },
+      { runtime: "cursor", label: "Cursor MCP config", kind: "json", serverRoot: "mcpServers" },
+      { runtime: "vscode", label: "VS Code MCP config", kind: "json", serverRoot: "servers" },
+      { runtime: "vscode-insiders", label: "VS Code Insiders MCP config", kind: "json", serverRoot: "servers" },
+      { runtime: "claude-desktop", label: "Claude Desktop config", kind: "json", serverRoot: "mcpServers" }
+    ];
+  }
+});
+
 // src/rekey.ts
 var rekey_exports = {};
 __export(rekey_exports, {
@@ -2767,7 +3101,7 @@ async function startRekey(options, deps = {}) {
 async function finishRekey(options, deps = {}) {
   const now = deps.now ?? (() => Date.now());
   if (!options.newApiKey) {
-    throw new Error("--rekey-finish needs --api-key <key> \u2014 the one the Haven agent page showed once.");
+    throw new Error(REKEY_FINISH_NEEDS_API_KEY);
   }
   const stored = await readStoredCredentials(
     options.serverName,
@@ -2910,6 +3244,7 @@ var init_rekey = __esm({
     init_signer_runtime();
     init_key();
     init_redact();
+    init_rekey_messages();
     init_server_names();
     init_storage();
   }
@@ -3389,6 +3724,15 @@ async function runDoctor(input, deps = {}) {
     if (revoked.length > 0) parts.push(`already revoked: ${revoked.join(", ")}`);
     if (retired.length > 0) parts.push(`tombstoned (keys removed): ${retired.join(", ")}`);
     if (unverifiable.length > 0) parts.push(`could not verify: ${unverifiable.join(", ")}`);
+    const knownIds = new Set([...inventory].map((e) => e.agentId ?? basename(e.directory)));
+    const ghostRecords = (await readTombstoneRecords(join(homeDir, ".haven", "tombstones"))).filter(
+      (rec) => !knownIds.has(rec.agent_id)
+    );
+    if (ghostRecords.length > 0) {
+      parts.push(
+        `retired records (dir removed): ${ghostRecords.map((rec) => `${rec.agent_id} (${rec.reason})`).join(", ")}`
+      );
+    }
     const supersededLive = live.filter((item) => item.entry.classification !== "wired").map((item) => item.label);
     checks.push({
       id: "superseded_agents",
@@ -3623,6 +3967,14 @@ async function scanInstalledClients(options = {}) {
     return SCAN_ORDER.indexOf(a.runtime) - SCAN_ORDER.indexOf(b.runtime);
   });
 }
+function installedClientHint(candidates) {
+  const installedClients = candidates.map((candidate) => candidate.runtime);
+  if (candidates.length === 1) {
+    return { installedClients, suggestedRuntime: candidates[0].runtime };
+  }
+  const configured = candidates.filter((candidate) => candidate.evidence === "config-file");
+  return configured.length === 1 ? { installedClients, suggestedRuntime: configured[0].runtime } : { installedClients };
+}
 var MAX_PROMPT_ATTEMPTS = 3;
 async function promptForInstalledClient(candidates, io = defaultPromptIo()) {
   if (candidates.length === 0) throw noInstalledClientsError();
@@ -3696,9 +4048,35 @@ function defaultPromptIo() {
 // src/runtime.ts
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.1.30-alpha.0";
+var CONNECTOR_VERSION = "0.1.32-alpha.0";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
+var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
+function failureOutcomeFor(runtimeHint, error) {
+  if (error !== null && typeof error === "object") {
+    const recorded = failureOutcomesByError.get(error);
+    if (recorded) return recorded;
+  }
+  return failedConnectOutcome(runtimeHint, error);
+}
 async function runConnect(options, deps = {}) {
+  const trace = {};
+  try {
+    return await executeConnect(options, deps, trace);
+  } catch (err) {
+    const outcome = failedConnectOutcome(trace.runtime ?? options.runtime, err);
+    if (err !== null && typeof err === "object") failureOutcomesByError.set(err, outcome);
+    if (trace.directory) await recordConnectOutcome(deps, trace.directory, outcome);
+    throw err;
+  }
+}
+async function recordConnectOutcome(deps, directory, outcome) {
+  try {
+    return await (deps.writeOutcomeRecord ?? writeConnectOutcomeRecord)(directory, outcome);
+  } catch {
+    return void 0;
+  }
+}
+async function executeConnect(options, deps, trace) {
   assertSupportedNodeVersion(deps.nodeVersion, MCP_RUNTIME_MANIFEST.minimumNodeVersion);
   const connectorVersion = options.connectorVersion ?? CONNECTOR_VERSION;
   const api = deps.api ?? createConnectApiClient(options.apiBaseUrl);
@@ -3718,13 +4096,27 @@ async function runConnect(options, deps = {}) {
     promptForRuntime: runtimeSelectionPrompt(options, deps)
   });
   if (!selection.runtime) {
+    const hint = await installedClientHintFor(deps);
     throw new ConnectError(
       "runtime_undetermined",
-      `Could not determine the agent runtime: nothing was detected in this environment and no --runtime was given. If you are an AI agent running this command: re-run it once, unchanged except for adding --runtime <name>, naming the harness you are running in \u2014 one of: ${RUNTIME_FLAG_VALUES} (the aliases cowork, codex and openclaw are accepted too). Do not guess: if your harness is not one of those, use --runtime other, which stores the credentials and prints the manual MCP steps. Nothing was written and the Haven setup token is still unused.`,
-      "rerun_connect_with_explicit_runtime"
+      `Could not determine the agent runtime: nothing was detected in this environment and no --runtime was given. If you are an AI agent running this command: re-run it once, unchanged except for adding --runtime <name>, naming the harness you are running in \u2014 one of: ${RUNTIME_FLAG_VALUES} (the aliases cowork, codex and openclaw are accepted too). Do not guess: if your harness is not one of those, use --runtime other, which stores the credentials and prints the manual MCP steps. ` + installedClientProse(hint) + "Nothing was written and the Haven setup token is still unused.",
+      "rerun_connect_with_explicit_runtime",
+      // #2091: the values must ride structurally too. The backend's setup
+      // prompt permits a retry only with "one of the values that refusal
+      // lists" — and --json discards prose, so a prose-only list deadlocked
+      // every automation run in an undetected runtime (Codex in the field:
+      // npx needs network, Codex runs network commands unsandboxed, and the
+      // unsandboxed path carries none of the CODEX_* detection vars).
+      //
+      // #2174: the list alone still leaves the retry a nine-value guess. The
+      // scan below narrows it to what is actually on this machine — as a
+      // HINT. It does not select, and this stays a refusal: see
+      // `installedClientHint`.
+      { allowedRuntimes: RUNTIME_FLAG_VALUE_LIST, ...hint }
     );
   }
   const runtime = selection.runtime;
+  trace.runtime = runtime;
   const installCapabilities = runtimeInstallCapabilities(runtime);
   if (options.localMcp) {
     if (!supportsLocalMcp(runtime)) {
@@ -3743,11 +4135,16 @@ async function runConnect(options, deps = {}) {
     log(`runtime: ${runtime} (chosen at the prompt \u2014 nothing was detected in this environment)`);
   }
   log("Warming up your connection to Haven\u2026");
-  const setup = await api.resolveSetup({
-    setupToken: options.setupToken,
-    connectorVersion,
-    runtime
-  });
+  let setup;
+  try {
+    setup = await api.resolveSetup({
+      setupToken: options.setupToken,
+      connectorVersion,
+      runtime
+    });
+  } catch (err) {
+    throw deadSetupTokenError(err) ?? err;
+  }
   assertSetupChallengeIsUsable(setup.challenge.expires_at);
   printSetupSummary(setup, log);
   await preflightStorage({ baseDir: options.credentialsDir, warn: log });
@@ -3784,6 +4181,8 @@ async function runConnect(options, deps = {}) {
       installCapabilities
     });
   } catch (err) {
+    const dead = deadSetupTokenError(err);
+    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."
@@ -3813,6 +4212,7 @@ async function runConnect(options, deps = {}) {
     x402BindingSigner: setup.x402_binding_signer ?? void 0,
     warn: log
   });
+  trace.directory = credentialPaths.directory;
   log(`Stored Haven identity credential locally: ${credentialPaths.identityPath}`);
   log(`Stored local signer credential locally: ${credentialPaths.signerPath}`);
   log(`Stored non-secret agent orientation locally: ${credentialPaths.agentPath}`);
@@ -3870,12 +4270,13 @@ async function runConnect(options, deps = {}) {
   } else {
     log("Haven setup on this machine is complete.");
   }
+  let supersededAgentIds = [];
   try {
-    const supersededIds = await listOtherAgentIds(options.credentialsDir, credentialPaths.directory);
-    if (supersededIds.length > 0) {
+    supersededAgentIds = await listOtherAgentIds(options.credentialsDir, credentialPaths.directory);
+    if (supersededAgentIds.length > 0) {
       log("");
       log(
-        `Heads-up: this setup created a NEW agent. Your previous agent(s) \u2014 ${supersededIds.join(", ")} \u2014 still exist with their own keys, and any host that was already running keeps acting as them.`
+        `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.`
       );
       log(
         `If you meant to replace them: revoke them on the Haven agent page, then restart EVERY long-lived host (gateways, TUI workers, editors) \u2014 each holds the MCP wiring snapshot from its own start time, so after repeated setups each can be stuck on a DIFFERENT old agent. Then remove their directories under ~/.haven/agents (or ${RERUN_HINT} --tombstone <dir> to leave a diagnostic in their place). Run ${RERUN_HINT} --doctor to check whether their keys are still live.`
@@ -3910,17 +4311,23 @@ async function runConnect(options, deps = {}) {
     approval = await waitForBudgetApproval(api, registration.setup_id, localApiKey, log, options.approvalWait);
   }
   printNextSteps(runtimeInstall, log, approval);
+  const outcome = completionOutcome({
+    runtimeInstall,
+    delegateAddress: registration.delegate_address,
+    hostedMcpUrl: registration.hosted_mcp_url,
+    supersededAgentIds,
+    setupChallengeExpiresAt: setup.challenge.expires_at,
+    approvalRequired: registration.agent_status === "pending_approval"
+  });
+  if (await recordConnectOutcome(deps, credentialPaths.directory, outcome)) {
+    log(`Saved this run's outcome to ${CONNECT_OUTCOME_FILENAME} in the agent's credential directory.`);
+  }
   return {
     setupId: registration.setup_id,
     agentId: registration.agent_id,
     delegateAddress: registration.delegate_address,
     credentialPaths,
-    outcome: completionOutcome({
-      runtimeInstall,
-      delegateAddress: registration.delegate_address,
-      setupChallengeExpiresAt: setup.challenge.expires_at,
-      approvalRequired: registration.agent_status === "pending_approval"
-    })
+    outcome
   };
 }
 function completionOutcome(input) {
@@ -3952,11 +4359,35 @@ function completionOutcome(input) {
     // malformed value arrives, do not echo it into an automation-facing
     // record; the human log has already been redacted separately.
     delegate_address: /^0x[0-9a-fA-F]{40}$/.test(input.delegateAddress) ? shortAddress(input.delegateAddress) : "[delegate-address-redacted]",
+    // The endpoint Connect wrote into the runtime's MCP config, verbatim — the
+    // same string that already sits in the user's own config file. Passed
+    // through the secret filter anyway: this is the automation contract, the
+    // value is server-supplied, and belts are cheap (the #1589 stance).
+    ...input.hostedMcpUrl ? { hosted_mcp_url: redactSecrets(input.hostedMcpUrl) } : {},
+    // Always emitted on a completed run, empty list included: "no superseded
+    // 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.setupChallengeExpiresAt ? { setup_challenge_expires_at: input.setupChallengeExpiresAt } : {},
     ...runtimeInstall.errorCode ? { error: { code: runtimeInstall.errorCode, next_action: nextAction2 } } : {}
   };
   return outcome;
 }
+async function installedClientHintFor(deps) {
+  try {
+    const candidates = await (deps.scanInstalledClients ?? scanInstalledClients)({ env: deps.env });
+    const hint = installedClientHint(candidates);
+    return hint.installedClients.length > 0 ? hint : {};
+  } catch {
+    return {};
+  }
+}
+function installedClientProse(hint) {
+  const found = hint.installedClients ?? [];
+  if (found.length === 0) return "";
+  const suggestion = hint.suggestedRuntime ? ` The likeliest is ${hint.suggestedRuntime}, but Haven will not choose for you \u2014 pass it yourself if it is right.` : " Haven will not choose between them for you.";
+  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;
@@ -3981,7 +4412,19 @@ function failedConnectOutcome(runtimeHint, error) {
       tools: ["haven_get_agent", "haven_get_allowances"],
       instruction: "After a successful setup and activation, verify only with haven_get_agent and haven_get_allowances."
     },
-    error: { code, next_action: nextAction2 }
+    error: {
+      code,
+      next_action: nextAction2,
+      // Only a ConnectError's message enters the JSON record: the vocabulary's
+      // prose is connector-authored and safe to serialize, while a plain
+      // Error can carry arbitrary server or filesystem detail (that stance is
+      // pinned by test). Redaction stays on as belt-and-braces; plain-Error
+      // runs still get their redacted message on stderr via the CLI mirror.
+      ...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 } : {}
+    }
   };
 }
 function printSetupSummary(setup, log) {
@@ -4003,16 +4446,20 @@ function assertSetupChallengeIsUsable(expiresAt) {
     "This Haven setup challenge is expired or invalid. Return to Haven, start a fresh connection, and rerun Connect. No local credentials were written."
   );
 }
+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.",
+    "return_to_haven_for_fresh_setup"
+  );
+}
 function isExpiredSetupChallenge(err) {
   return err instanceof Error && /(?:setup )?challenge.*expir|expir.*(?:setup )?challenge/i.test(err.message);
 }
 function secureLogger(log, redactPaths = false) {
   return (message) => {
-    let safe = redactSecrets(message);
-    if (redactPaths) {
-      safe = safe.replace(/(?:~|\/)[^\s`"']*\/(?:identity|signer|agent)\.json\b/g, "[credential-file-redacted]").replace(/(?:~|\/)[^\s`"']*\/\.env\b/g, "[credential-env-redacted]");
-    }
-    log(safe);
+    log(redactPaths ? redactForAutomation(message) : redactSecrets(message));
   };
 }
 function printRuntimeInstall(result, log) {
@@ -4171,6 +4618,7 @@ function printNextSteps(result, log, approval) {
 
 // src/args.ts
 init_server_names();
+init_rekey_messages();
 function parseArgs(argv, env = process.env) {
   const options = {
     apiBaseUrl: env.HAVEN_API_URL ?? "http://localhost:3001",
@@ -4185,6 +4633,8 @@ function parseArgs(argv, env = process.env) {
   let tombstoneDir;
   let tombstoneReason;
   let tombstoneReplacedBy;
+  let unwire;
+  let unwireDir;
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") {
@@ -4203,6 +4653,13 @@ function parseArgs(argv, env = process.env) {
       newApiKey = requireValue(argv, ++i, arg);
     } else if (arg === "--tombstone") {
       tombstoneDir = requireValue(argv, ++i, arg);
+    } else if (arg === "--unwire") {
+      unwire = unwire ?? {};
+      const next = argv[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        unwireDir = next;
+        i += 1;
+      }
     } else if (arg === "--reason") {
       tombstoneReason = requireValue(argv, ++i, arg);
     } else if (arg === "--replaced-by") {
@@ -4252,18 +4709,37 @@ function parseArgs(argv, env = process.env) {
       );
     }
     if (rekey.phase === "finish" && !newApiKey) {
-      throw new Error("--rekey-finish needs --api-key <key> \u2014 the one the Haven agent page showed once.");
+      throw new Error(REKEY_FINISH_NEEDS_API_KEY);
     }
     return { options, help, json, doctor, repair, tombstone, rekey };
   }
   if (newApiKey !== void 0) {
     throw new Error("--api-key requires --rekey-finish.");
   }
-  if (!tombstoneDir && (tombstoneReason !== void 0 || tombstoneReplacedBy !== void 0)) {
-    throw new Error("--reason and --replaced-by require --tombstone <dir>.");
+  if (!tombstoneDir && !unwire && (tombstoneReason !== void 0 || tombstoneReplacedBy !== void 0)) {
+    throw new Error("--reason and --replaced-by require --tombstone <dir> or --unwire.");
+  }
+  if (unwire && (tombstoneReason !== void 0 || tombstoneReplacedBy !== void 0)) {
+    unwire = {
+      ...tombstoneReason !== void 0 ? { reason: tombstoneReason } : {},
+      ...tombstoneReplacedBy !== void 0 ? { replacedBy: tombstoneReplacedBy } : {},
+      ...unwire
+    };
   }
   if (tombstone) {
-    return { options, help, json, doctor, repair, tombstone, rekey };
+    if (unwire) {
+      throw new Error("--unwire and --tombstone are separate operations; run one per invocation.");
+    }
+    return { options, help, json, doctor, repair, tombstone, rekey, unwire, unwireDir };
+  }
+  if (unwire) {
+    if (options.setupToken) {
+      throw new Error("--unwire removes existing wiring; it does not take --setup. Drop --setup.");
+    }
+    if (!unwireDir && !options.serverName && !options.credentialsDir) {
+      throw new Error("--unwire needs a target: --unwire <dir>, --unwire --name <slug>, or --unwire --credentials-dir <path>.");
+    }
+    return { options, help, json, doctor, repair, tombstone, rekey, unwire, unwireDir };
   }
   if (doctor || repair) {
     if (!options.runtime) {
@@ -4326,8 +4802,20 @@ function helpText() {
     "  --tombstone <dir>          Retire an agent credential directory in place (no token): replaces its signer",
     "                             wrapper with a diagnostic that names the retirement in MCP stderr logs, and",
     "                             writes TOMBSTONE.json. Touches NO key material and revokes nothing.",
-    "  --reason <text>            Reason recorded in the tombstone (with --tombstone).",
-    "  --replaced-by <agent-id>   Successor agent recorded in the tombstone (with --tombstone).",
+    "  --unwire [<dir>]           Remove one agent\u2019s wiring from every runtime config it appears in (no token):",
+    "                             tombstone-first, then drops the hosted + signer MCP pair from Hermes YAML, Codex",
+    "                             TOML and the JSON configs (Cursor, VS Code, Insiders, Claude Desktop), plus the",
+    "                             Hermes dotenv API-key line (MCP_HAVEN_API_KEY / MCP_HAVEN_<SLUG>_API_KEY).",
+    "                             Target the directory directly, or add --name <slug> or --credentials-dir.",
+    "                             An UNNAMED pair is only removed when this directory\u2019s wrapper is the one the",
+    "                             config launches (or its key is the one the Hermes env holds); otherwise the",
+    "                             command refuses rather than unwire a different agent \u2014 it never touches a",
+    "                             pair another agent owns. Tears down the target directory: its signer key and",
+    "                             API key are removed locally (record kept via the #2155 tombstone mirror) and",
+    "                             nothing is ever revoked on the backend \u2014 that stays an owner action on the",
+    "                             Haven agent page.",
+    "  --reason <text>            Reason recorded in the tombstone (with --tombstone or --unwire).",
+    "  --replaced-by <agent-id>   Successor agent recorded in the tombstone (with --tombstone or --unwire).",
     "  --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."
@@ -4343,6 +4831,28 @@ function requireValue(argv, index, option) {
 
 // src/cli.ts
 init_redact();
+init_connect_error();
+function failSubcommand(io, json, err, envelope, fallback) {
+  const message = err instanceof Error ? err.message : String(err);
+  io.stderr(`${redactSecrets(message)}
+`);
+  if (json) {
+    io.stdout(
+      `${redactSecrets(
+        JSON.stringify({
+          ...envelope,
+          error: {
+            code: isConnectError(err) ? err.code : fallback.code,
+            next_action: isConnectError(err) ? err.nextAction : fallback.nextAction,
+            ...isConnectError(err) && message ? { message } : {}
+          }
+        })
+      )}
+`
+    );
+  }
+  return 1;
+}
 async function runCli(argv, io = {
   stdout: (message) => process.stdout.write(message),
   stderr: (message) => process.stderr.write(message)
@@ -4353,6 +4863,8 @@ async function runCli(argv, io = {
     parsed = parseArgs(argv);
   } catch (err) {
     if (wantsJson) {
+      io.stderr(`${redactForAutomation(err instanceof Error ? err.message : String(err))}
+`);
       io.stdout(`${JSON.stringify(failedConnectOutcome(void 0, err))}
 `);
     } else {
@@ -4368,13 +4880,13 @@ async function runCli(argv, io = {
   }
   if (parsed.tombstone) {
     const { writeAgentTombstone: writeAgentTombstone2 } = await Promise.resolve().then(() => (init_tombstone(), tombstone_exports));
-    const { readFile: readFile12 } = await import('fs/promises');
-    const { join: join10 } = await import('path');
+    const { readFile: readFile13 } = await import('fs/promises');
+    const { join: join11 } = await import('path');
     try {
       let agentId = "unknown";
       try {
         const identity = JSON.parse(
-          await readFile12(join10(parsed.tombstone.directory, "identity.json"), "utf8")
+          await readFile13(join11(parsed.tombstone.directory, "identity.json"), "utf8")
         );
         agentId = identity.agent_id ?? "unknown";
       } catch {
@@ -4395,14 +4907,80 @@ async function runCli(argv, io = {
           "Key files were NOT touched and nothing was revoked \u2014 revoke the agent on the Haven agent page if you have not already.\n"
         );
         io.stdout(
-          "Restart EVERY long-lived MCP host (gateway, TUI workers, editors): each holds the wiring snapshot from its own start time, and the tombstone only speaks when a stale host next probes the old path.\n"
+          `A surviving tombstone record was mirrored to ${redactSecrets(info.recordPath)}
+`
+        );
+        io.stdout(
+          "Restart EVERY long-lived MCP host (gateway, TUI workers, editors): each holds the wiring snapshot from its own start time, and the tombstone only speaks when a stale host next probes the old path. The mirrored record keeps this retirement observable even after the agent directory itself is deleted.\n"
         );
       }
       return 0;
     } catch (err) {
-      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
-`);
-      return 1;
+      return failSubcommand(io, parsed.json, err, { tombstoned: false }, {
+        code: "tombstone_failed",
+        nextAction: "review_the_error_and_retry_with_a_valid_agent_directory"
+      });
+    }
+  }
+  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 homeDir = homedir10();
+    const root = parsed.options.credentialsDir ?? join11(homeDir, ".haven", "agents");
+    const directory = parsed.unwireDir ?? (parsed.options.serverName ? join11(root, parsed.options.serverName) : root);
+    try {
+      const result = await unwireAgent2({
+        directory,
+        slug: parsed.options.serverName,
+        reason: parsed.unwire.reason,
+        replacedBy: parsed.unwire.replacedBy,
+        homeDir
+      });
+      const failures = result.runtimes.filter((r) => r.status === "refused" || r.status === "unreadable");
+      if (parsed.json) {
+        io.stdout(
+          `${redactSecrets(
+            JSON.stringify({
+              unwired: true,
+              agent_id: result.agentId,
+              slug: result.slug ?? null,
+              directory: result.directory,
+              tombstoned: result.tombstoned,
+              runtimes: result.runtimes.map((r) => ({
+                runtime: r.runtime,
+                label: r.label,
+                status: r.status,
+                ...r.detail ? { detail: r.detail } : {}
+              }))
+            })
+          )}
+`
+        );
+      } else {
+        io.stdout(redactSecrets(`Unwired agent ${result.agentId} at ${result.directory}.
+`));
+        io.stdout(
+          result.tombstoned ? "  \xB7 Tombstoned first: any long-lived host still resolving the old wrapper gets the HAVEN-TOMBSTONE diagnosis.\n" : "  \xB7 Directory was already tombstoned.\n"
+        );
+        for (const r of result.runtimes) {
+          const mark = r.status === "removed" ? "\u2713" : r.status === "clean" ? "\u2013" : "\u2717";
+          io.stdout(redactSecrets(`  ${mark} ${r.label}: ${r.status}${r.detail ? ` \u2014 ${r.detail}` : ""}
+`));
+        }
+        io.stdout(
+          failures.length > 0 ? "  Some entries were NOT removed (\u2717 above). Re-run `--unwire` after resolving each refusal \u2014\n  it is idempotent.\n" : "  Verify: `--doctor --runtime <runtime>` per host should report this agent as `retired` with a\n  clean runtime-config check.\n"
+        );
+        io.stdout(
+          "Restart EVERY long-lived MCP host (gateway, TUI workers, editors): each holds the wiring snapshot\nfrom its own start time. This directory\u2019s local key material was removed and the tombstone\nrecord + #2155 mirror survive \u2014 but nothing was REVOKED on the backend. If you have not\nalready, revoke the agent on the Haven agent page to stop it spending entirely.\n"
+        );
+      }
+      return failures.length > 0 ? 1 : 0;
+    } catch (err) {
+      return failSubcommand(io, parsed.json, err, { unwired: false }, {
+        code: "unwire_failed",
+        nextAction: "review_the_error_and_rerun_unwire_which_is_idempotent"
+      });
     }
   }
   if (parsed.rekey) {
@@ -4458,9 +5036,10 @@ async function runCli(argv, io = {
       }
       return 0;
     } catch (err) {
-      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
-`);
-      return 1;
+      return failSubcommand(io, parsed.json, err, { rekey: "failed" }, {
+        code: "rekey_failed",
+        nextAction: "review_the_error_and_rerun_the_rekey_phase"
+      });
     }
   }
   if (parsed.doctor || parsed.repair) {
@@ -4506,9 +5085,10 @@ async function runCli(argv, io = {
       }
       return report.ok ? 0 : 1;
     } catch (err) {
-      io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}
-`);
-      return 1;
+      return failSubcommand(io, parsed.json, err, { doctor: "failed" }, {
+        code: "doctor_failed",
+        nextAction: "review_the_error_and_rerun_doctor"
+      });
     }
   }
   try {
@@ -4533,7 +5113,9 @@ async function runCli(argv, io = {
     return 0;
   } catch (err) {
     if (parsed.json) {
-      io.stdout(`${JSON.stringify(failedConnectOutcome(parsed.options.runtime, err))}
+      io.stderr(`${redactForAutomation(err instanceof Error ? err.message : String(err))}
+`);
+      io.stdout(`${JSON.stringify(failureOutcomeFor(parsed.options.runtime, err))}
 `);
     } else {
       io.stderr(`${redactSecrets(err instanceof Error ? err.message : String(err))}