@haven_ai/connect 0.0.0-dev.202609040858.f4467bb → 0.0.0-dev.202609041540.2214a02

package/README.md

@@ -92,7 +92,8 @@ already-running host, which is why the restart guidance below matters.
 
 ## Retiring an old agent directory
 
-Re-running setup creates a NEW agent and retires nothing. Long-lived MCP hosts
+Re-running setup without `--replace` creates a NEW agent and retires nothing
+(with `--replace`, see [Running setup again](#running-setup-again)). Long-lived MCP hosts
 (gateways, TUI workers, editors, desktop apps) load their MCP wiring once, at
 process start — a host started before your latest setup keeps spawning the OLD
 agent's signer path forever, and when that directory is later removed the spawn
@@ -173,7 +174,9 @@ dashboard whenever ready and verify later with the read-only `haven_get_agent`
 tool. The object includes runtime/topology status,
 probe result, activation and next-action guidance, approval state/expiry (null
 when the backend does not provide an approval expiry), the two
-read-only verification tools, `hosted_mcp_url`, and `superseded_agent_ids`. It
+read-only verification tools, `hosted_mcp_url`, `superseded_agent_ids`, and —
+on a run that replaced existing wiring — `superseded_agents_retired_locally`
+with `retired_agent_ids`. It
 contains no API key, private key, credential
 contents, full credential paths, or full delegate address. The same redacted
 object is available to library callers as `runConnect(...).outcome`; the older
@@ -186,11 +189,26 @@ mismatch. It is non-secret: the same string goes into your own MCP config file,
 and the API key travels beside it in a header.
 
 `superseded_agent_ids` lists the other agent directories on this machine. A
-re-run mints a NEW agent and retires nothing, so those older agents still hold
-live API and signing keys — revoke them on the Haven agent page if you meant to
-replace them. Empty on a clean first run; an empty list is not a guarantee,
-since a scan that cannot read the credential root also yields one rather than
-failing a completed setup.
+re-run mints a NEW agent, and without `--replace` retires nothing, so those
+older agents still hold live API and signing keys — revoke them on the Haven
+agent page if you meant to replace them. Empty on a clean first run; an empty
+list is not a guarantee, since a scan that cannot read the credential root also
+yields one rather than failing a completed setup. On a `--replace` run, `retired_agent_ids` names the
+directories that were actually tombstoned and had their local key files removed
+— **the collision set only**, never the whole `superseded_agent_ids` list, which
+also names named agents that coexist with the replaced bare pair and are
+untouched — and `superseded_agents_retired_locally` is `true` when that
+retirement covered every collision entry (`false`: the install ended with an
+error code and the retirement was skipped, or one entry failed). Both fields
+are absent on any other run and say nothing about the backend, where nothing is
+revoked.
+
+A `wiring_collision` refusal (a non-interactive bare setup over a live
+previous agent, #2551) carries `error.superseded_agent_ids` and
+`error.suggested_name` — the ids the human needs in order to decide, and a
+valid `--name` the run can be re-issued with — with `next_action:
+relay_wiring_collision_to_user`. It is a relay, not a retry hint: do not append
+`--replace` or `--name` on the agent's own initiative.
 
 For a recoverable install, configuration, probe, consent, or manual-runtime
 condition, inspect `error.code` and `error.next_action`, then follow the safe
@@ -247,6 +265,17 @@ adding a security boundary. (The local-signer tool-exposure
 acknowledgement is a separate, machine-checkable consent about what the local
 MCP tools expose, not a registration gate.)
 
+The one question Connect does put before registration is not about the
+agent being created but about the one already here: a **wiring collision**
+([#2551](https://github.com/d-hinders/Haven-AI/issues/2551)). When the bare
+`haven` / `haven-signer` pair on this machine already belongs to a different
+agent whose directory still holds a live key, proceeding would silently
+re-point that pair — the state `--doctor` reports as a still-spend-capable
+`superseded` directory. That choice (replace it, or install alongside under a
+name) belongs to the user, and it is asked *before* the key is minted or the
+agent registered so that declining leaves no orphaned `pending_approval` agent
+behind. See [Running setup again](#running-setup-again).
+
 ## Running setup again
 
 Each setup prompt is one-time and each successful run creates a **new** agent
@@ -264,17 +293,44 @@ already-configured machine behaves as follows (characterized in
   credentials into its own directory under `~/.haven/agents/<agent-id>/`,
   alongside the previous agent's directory, which stays byte-identical.
   Nothing is rotated, revoked, or deleted locally.
-- **Runtime MCP entries are replaced, not duplicated**: Connect owns the
-  `haven` and `haven-signer` entries (and the managed Codex/Hermes
-  equivalents) and re-points them at the newest agent's credentials.
-  Unrelated MCP servers and configuration are preserved. Without `--name`, one
-  runtime is therefore wired to one Haven agent — the newest one. With
+- **A bare re-run over a live previous agent is a decision, not a default
+  ([#2551](https://github.com/d-hinders/Haven-AI/issues/2551)).** Before
+  minting a key or registering, Connect scans the credential root for a
+  bare-pair directory that still holds a usable key — the same reading
+  `--doctor` classifies as `wired` or `superseded`; `retired`, `orphaned`,
+  `parked` and **named** directories never count. If it finds one:
+  - an **interactive terminal** is asked to choose — **replace** (below) or
+    **install alongside** under a name Connect proposes from the agent's
+    display name (e.g. `payment-agent`), collision-checked against the
+    directories already there;
+  - a **non-interactive run** (`--json`, CI, an agent tool call, a pipe)
+    refuses with `wiring_collision` — nothing written, token still unused —
+    naming the superseded agent ids and the two flags that resolve it. The
+    refusal is written as a **relay instruction**: an agent running the
+    dashboard's command may append only `--json` (and `--runtime` after a
+    runtime refusal), so it must hand the choice to its user rather than add
+    a flag itself, and re-run only with the flag the user picks.
+  - **`--replace`** is the unattended answer "yes, replace". `--name <slug>`
+    installs alongside. Passing both is a usage error — they contradict.
+- **Replacing re-points the bare pair, then retires the previous directory
+  locally.** Connect owns the `haven` and `haven-signer` entries (and the
+  managed Codex/Hermes equivalents) and re-points them at the new agent's
+  credentials; unrelated MCP servers and configuration are preserved. Once
+  the runtime install has actually completed, each superseded directory is
+  tombstoned and its local key files removed — the same teardown `--unwire`
+  performs — so `--doctor` reads it as `retired` rather than still
+  spend-capable. If the install ends with an error code the retirement is
+  **skipped**, because the old wiring may still be the only working one; the
+  outcome's `superseded_agents_retired_locally` says which happened and
+  `retired_agent_ids` names exactly the directories it reached. With
   `--name`, each agent owns its own suffixed pair and they coexist; see
   [Running several agents in one runtime](#running-several-agents-in-one-runtime).
-- **The previous agent is not revoked by a re-run.** Its credentials remain on
-  disk and its authority remains whatever its on-chain rules say. Revoke
-  agents you no longer use from the Haven dashboard, then delete their
-  credential directories.
+- **The previous agent is not revoked by a re-run — with or without
+  `--replace`.** Local retirement is local: its authority remains whatever
+  its on-chain rules and the Haven agent page say. Revoke agents you no
+  longer use from the Haven dashboard. Connect never calls revoke — that
+  route is owner-authenticated, and an agent credential revoking a sibling
+  agent would be an agent editing its own authority.
 - **A re-run never overwrites an existing credential file.** A write that would
   collide with an existing `identity.json`/`signer.json`/`agent.json` is
   refused outright (and a partially failed write rolls itself back), so a
@@ -401,10 +457,14 @@ Add `--json` for a machine-readable report. No secret material is ever
 printed.
 
 `--doctor` also probes every OTHER agent credential directory it did not
-select (#1688). A re-run of setup mints a NEW agent and retires nothing, so
-a directory from a previous setup can hold an API key that still
-authenticates — meaning any host that started before the re-run keeps
-spending as the agent you believe you replaced. A superseded directory
+select (#1688). A re-run of setup mints a NEW agent and, unless it ran with
+`--replace` (#2551), retires nothing, so a directory from a previous setup
+can hold an API key that still authenticates — meaning any host that started
+before the re-run keeps spending as the agent you believe you replaced. Since
+#2551 a bare setup no longer reaches that state silently: it asks at a
+terminal and refuses everywhere else, so a `superseded` directory now means
+someone chose it — a `--replace` whose install failed, an older connector, or
+a directory this scan could not classify. A superseded directory
 whose key is still live is a FAILING check naming the agent id, with the
 repair spelled out: revoke it on the Haven agent page, then remove the
 directory. An already-revoked one reports as informational; an unreachable

package/dist/cli.cjs

@@ -535,9 +535,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: mcp.MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.0.0-dev.202609040858.f4467bb",
+      sdkVersion: "0.0.0-dev.202609041540.2214a02",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.0.0-dev.202609040858.f4467bb",
+      signerVersion: "0.0.0-dev.202609041540.2214a02",
       // 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
@@ -2913,14 +2913,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, {
@@ -3038,6 +3030,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) {
@@ -3077,18 +3072,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;
@@ -3173,16 +3163,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({
@@ -3203,6 +3204,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, {
@@ -4267,10 +4276,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.0.0-dev.202609040858.f4467bb";
+var CONNECTOR_VERSION = "0.0.0-dev.202609041540.2214a02";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
 function failureOutcomeFor(runtimeHint, error) {
@@ -4375,6 +4493,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.");
@@ -4395,7 +4535,7 @@ 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,
       connectorContext: {
         environment_label: options.environmentLabel ?? "Local workspace",
         config_target: installCapabilities.canWriteRuntimeConfig ? "agent runtime MCP config" : "local credential files"
@@ -4417,7 +4557,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,
@@ -4456,7 +4596,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,
@@ -4495,10 +4635,43 @@ 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 supersededAgentIds = [];
   try {
     supersededAgentIds = await listOtherAgentIds(options.credentialsDir, credentialPaths.directory);
-    if (supersededAgentIds.length > 0) {
+    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.`
@@ -4542,6 +4715,8 @@ async function executeConnect(options, deps, trace) {
     delegateAddress: registration.delegate_address,
     hostedMcpUrl: registration.hosted_mcp_url,
     supersededAgentIds,
+    supersededAgentsRetiredLocally,
+    ...replacing ? { retiredAgentIds } : {},
     setupChallengeExpiresAt: setup.challenge.expires_at,
     approvalRequired: registration.agent_status === "pending_approval"
   });
@@ -4594,6 +4769,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 } } : {}
   };
@@ -4615,10 +4792,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 setup 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";
@@ -4649,7 +4854,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 } : {}
     }
   };
 }
@@ -4886,6 +5093,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") {
@@ -4925,6 +5133,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);
@@ -4950,6 +5160,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.");
@@ -5028,6 +5249,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,",
@@ -5131,13 +5358,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 {
@@ -5176,10 +5403,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,