@haven_ai/connect 0.0.0-dev.202609190647.18526db → 0.0.0-dev.202609190936.6937e31

package/README.md

@@ -109,7 +109,7 @@ report stays `version: 1`; `level` is additive.
 | Level | Meaning | Example |
 | --- | --- | --- |
 | `ok` | Nothing to say. | The installed signer matches the connector's pin. |
-| `advisory` | Worth reading; nothing is broken. Exit 0. | `signer_runtime`: the install is intact but behind the pinned version ("intact, but outdated" — both versions named, `--repair` offered); `signer_runtime_unused` (#3123): runtime directories nothing references. `superseded_agents` on a recognised runtime with no config file the connector can read (Claude Code, `other`): a second live key is reported, and the check says why "wired" cannot be verified from this machine. |
+| `advisory` | Worth reading; nothing is broken. Exit 0. | `signer_runtime`: the install is intact but behind the pinned version ("intact, but outdated" — both versions named, `--repair` offered); `signer_runtime_unused` (#3123): runtime directories nothing references; `mcp_server_name_rebound` (#3122): two local binding records claim one server name. `superseded_agents` on a recognised runtime with no config file the connector can read (Claude Code, `other`): a second live key is reported, and the check says why "wired" cannot be verified from this machine. |
 | `failed` | A real failure with one repair action. Exit 1. | A stale or empty runtime directory; a live key in a directory the runtime's config demonstrably does not use. |
 
 What stays blocking is live spend authority: a directory whose stored key
@@ -191,7 +191,9 @@ npx @haven_ai/connect@<channel> --unwire --name research [--reason "..."]
 touches local files only, so any published connector does the same job.
 
 It tombstone-first (so a stale long-lived host still hears `HAVEN-TOMBSTONE`,
-never a masked `ENOENT`), then removes THAT agent's hosted + signer pair from
+never a masked `ENOENT`), releases the directory's local server-name binding
+record (#3122, whatever the key-material decision below), then removes THAT
+agent's hosted + signer pair from
 every runtime config it appears in (Hermes YAML, Codex TOML, the Cursor / VS
 Code / Insiders / Claude Desktop JSON configs), plus the Hermes dotenv API-key
 line — bare `MCP_HAVEN_API_KEY` or named `MCP_HAVEN_<SLUG>_API_KEY`. Then it
@@ -224,7 +226,8 @@ revoked or destroyed — that is the honest state. **`--destroy-key-material`**
 proceeds on every answer, states what it destroyed and that local recovery
 of a stranded balance ends with it. In `--json` the record carries an
 additive `teardown: { status: destroyed | retained | forced, probe, detail,
-remedy? }`.
+remedy? }` and, since #3122, `binding_released` (whether a local
+`mcp-server-binding.json` was removed).
 
 The `claude-code` copy of the key (written by `claude mcp add`, into a config
 the connector does not own) is out of scope for `--unwire`, as it always was:
@@ -271,6 +274,67 @@ revoked on the backend; `connect reports, the user decides` (#1688) survives,
 and revocation stays an owner action on the Haven agent page. Restart every
 long-lived host afterwards, as with any retirement.
 
+### The wallet warning arrives before the write; names are bound locally (#3122)
+
+Setup guards the **name slot** (a taken `--name`, the bare pair already wired
+— #2551 refuses or asks) but never the **wallet**: a machine can carry several
+agents with live keys, and until #3122 the "your previous agent(s) still exist
+with their own keys" heads-up was printed only after the credentials were
+written (that completion heads-up, #1688, is unchanged — this slice ADDS an
+earlier notice). Two things changed, both from local files only (no network call is
+added; the backend is not asked whether any key still authenticates):
+
+- **Before the key is minted or anything is written**, setup names every
+  other credential directory that still holds a stored key, with the account
+  it can spend from — `Heads-up (before anything is written): this machine
+  already carries N agent director(y/ies) with stored keys — <id> (spends
+  from 0x…)`. It **warns, it does not refuse** (owner decision on #3119): a
+  refusal would change behaviour for every non-interactive caller, including
+  the dashboard's connect flow. `--json` carries the same list as
+  `existing_agents_before_write: [{ agent_id, account_address }]`, always
+  present on a completed run (`[]` on a clean machine) — a subset of
+  `superseded_agent_ids`, which names every other directory that has an
+  `identity.json` at all, key-less and tombstoned ones included.
+  "Holds a stored key" is the whole test: a tombstoned directory whose key
+  files were never deleted is counted (it can still spend), which is the
+  opposite side of the doctor's rule that ignores a retired directory's
+  binding record (it launches nothing). The scan covers exactly the credential
+  root this run writes into — `~/.haven/agents`, or the root given by
+  `--credentials-dir` — and never unions the two (#2551's collision check uses
+  the same root; `--doctor` shares the no-union rule but reads its
+  `--credentials-dir` as the agent directory itself, so its root is that
+  directory's parent; #3123's union was for the one shared `signer-runtime`
+  root).
+- **Each setup records what it bound** in a non-secret
+  `mcp-server-binding.json` beside `last-connect-outcome.json`: `{ version:
+  1, server_name, signer_name, agent_id, api_url, hosted_mcp_url?, bound_at }`
+  — no key material, by construction (pinned by test). Per credential
+  directory, not machine-wide: two concurrent setups never write the same
+  file, and "who else claims this name" is answered by scanning the root,
+  which setup and the doctor already do. When a setup is about to bind a
+  server name another directory's record holds, it says so before the write —
+  previous agent (the NEWEST holder when several records claim the name),
+  previous backend URL, when — and flags a **DIFFERENT backend** explicitly, because that is the case the backend cannot see and
+  the one that silently repoints a saved session; `--json` carries it as
+  `server_name_rebound_from: { server_name, agent_id, api_url, bound_at,
+  backend_changed }`. `--unwire` releases the record (its `--json` gains
+  `binding_released`), and so does a `--replace` retirement, so a legitimately
+  free name does not warn forever; `--tombstone` leaves it, and `--doctor`
+  ignores a retired directory's record. `--doctor` reports two records
+  claiming one name — excluding tombstoned (retired) directories — as the
+  `mcp_server_name_rebound` advisory (oldest → newest, backend change
+  flagged). The record is written
+  after the credentials, best-effort: a directory with credentials and no
+  record (a crash in between, or one retired by hand) is not proof the name
+  is free — the absence of a warning is not a guarantee, as with
+  `superseded_agent_ids`.
+
+**What wins when the local record disagrees with the backend.** The backend's
+`agents.mcp_server_name` is the authority for the same backend; the local
+record is a reporting aid that covers the two cases the backend cannot —
+another backend, or offline — and it never asserts itself as the backend's
+current truth. Every message that reads it says "locally recorded".
+
 ### Structured output for automation
 
 Pass `--json` when a launcher needs a machine-readable completion record. Connect
@@ -282,9 +346,12 @@ 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) and `approval.url`, the two
-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
+read-only verification tools, `hosted_mcp_url`, `superseded_agent_ids`,
+`existing_agents_before_write` (#3122 — the other live-keyed directories named
+before the first write, each with the account it spends from), and — on a run
+that replaced existing wiring — `superseded_agents_retired_locally` with
+`retired_agent_ids`; `server_name_rebound_from` (#3122) appears only when the
+run took a server name over from another directory's local binding record. 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

package/dist/cli.cjs

@@ -172,6 +172,16 @@ function redactSecrets(value) {
 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 withoutUserinfo(url) {
+  try {
+    const parsed = new URL(url);
+    parsed.username = "";
+    parsed.password = "";
+    return parsed.toString().replace(/\/+$/, "");
+  } catch {
+    return url;
+  }
+}
 function shortAddress(address) {
   if (!/^0x[0-9a-fA-F]{40}$/.test(address)) return address;
   return `${address.slice(0, 6)}...${address.slice(-4)}`;
@@ -543,12 +553,54 @@ async function readConnectOutcomeRuntime(directory) {
     return null;
   }
 }
-var REKEY_PENDING_FILENAME, REKEY_PENDING_TTL_MS, CONNECT_OUTCOME_FILENAME;
+async function writeMcpServerBinding(directory, binding) {
+  const path$1 = path.join(directory, MCP_SERVER_BINDING_FILENAME);
+  await promises.writeFile(path$1, `${JSON.stringify(binding, null, 2)}
+`, { mode: 384 });
+  return path$1;
+}
+async function readMcpServerBinding(directory) {
+  try {
+    const parsed = JSON.parse(await promises.readFile(path.join(directory, MCP_SERVER_BINDING_FILENAME), "utf8"));
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const record = parsed;
+    if (record.version !== 1 || typeof record.server_name !== "string" || typeof record.agent_id !== "string" || typeof record.api_url !== "string" || typeof record.bound_at !== "string") return null;
+    return record;
+  } catch {
+    return null;
+  }
+}
+async function clearMcpServerBinding(directory) {
+  try {
+    await promises.rm(path.join(directory, MCP_SERVER_BINDING_FILENAME));
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function listMcpServerBindings(baseDir, excludeDirectory) {
+  const root = defaultCredentialRoot(baseDir);
+  let entries = [];
+  try {
+    entries = await promises.readdir(root);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const directory = path.join(root, entry);
+    const binding = await readMcpServerBinding(directory);
+    if (binding) out.push({ directory, binding });
+  }
+  return out;
+}
+var REKEY_PENDING_FILENAME, REKEY_PENDING_TTL_MS, CONNECT_OUTCOME_FILENAME, MCP_SERVER_BINDING_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";
+    MCP_SERVER_BINDING_FILENAME = "mcp-server-binding.json";
   }
 });
 function mcpPackageSpec() {
@@ -567,9 +619,9 @@ var init_runtime_manifest = __esm({
       mcpPackage: "@haven_ai/mcp",
       mcpVersion: mcp.MCP_VERSION,
       sdkPackage: "@haven_ai/sdk",
-      sdkVersion: "0.0.0-dev.202609190647.18526db",
+      sdkVersion: "0.0.0-dev.202609190936.6937e31",
       signerPackage: "@haven_ai/signer",
-      signerVersion: "0.0.0-dev.202609190647.18526db",
+      signerVersion: "0.0.0-dev.202609190936.6937e31",
       // 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
@@ -3195,9 +3247,10 @@ async function unwireAgent(input) {
       }
     }
   }
+  const bindingReleased = await clearMcpServerBinding(input.directory);
   const teardown = await decideTeardown(identity, input);
   if (teardown.status !== "retained") await teardownLocalKeyMaterial(input.directory, identity);
-  return { directory: input.directory, agentId, slug, tombstoned, runtimes, teardown };
+  return { directory: input.directory, agentId, slug, tombstoned, runtimes, teardown, bindingReleased };
 }
 async function decideTeardown(identity, input) {
   const ended = "Local recovery of a stranded delegate balance ends with it: the sweep-recovery routes accept only this agent's API key and delegate signature, and neither exists on this machine any more.";
@@ -4296,6 +4349,30 @@ async function runDoctor(input, deps = {}) {
       } : {}
     });
   }
+  const bindings = (await Promise.all(
+    inventory.filter((entry) => entry.classification !== "retired").map(async (entry) => ({ entry, binding: await readMcpServerBinding(entry.directory) }))
+  )).filter((item) => item.binding !== null);
+  const byName = /* @__PURE__ */ new Map();
+  for (const item of bindings) {
+    const list = byName.get(item.binding.server_name) ?? [];
+    list.push(item);
+    byName.set(item.binding.server_name, list);
+  }
+  const rebound = [...byName.entries()].filter(([, items]) => items.length > 1);
+  if (rebound.length > 0) {
+    const parts = rebound.map(([name, items]) => {
+      const ordered = [...items].sort((a, b) => a.binding.bound_at < b.binding.bound_at ? -1 : a.binding.bound_at > b.binding.bound_at ? 1 : 0);
+      const backends = new Set(ordered.map((i) => withoutUserinfo(i.binding.api_url)));
+      return `'${name}': ` + ordered.map((i) => `${i.binding.agent_id} on ${withoutUserinfo(i.binding.api_url)} at ${i.binding.bound_at} [${i.entry.classification}]`).join(" \u2192 ") + (backends.size > 1 ? " (BACKEND CHANGED)" : "");
+    });
+    checks.push({
+      id: "mcp_server_name_rebound",
+      label: "MCP server names bound more than once",
+      level: "advisory",
+      detail: `${rebound.length} MCP server name${rebound.length === 1 ? "" : "s"} changed hands on this machine (locally recorded bindings; the backend's own record is the authority for the same backend): ${parts.join("; ")}. A saved session, script or document naming the server may still mean the earlier agent.`,
+      repair: `Retire the earlier director(y/ies) with ${RERUN} --unwire <dir> to release the name, or keep both and address them by --name.`
+    });
+  }
   const parkedElsewhere = inventory.filter((entry) => entry.directory !== primaryDirectory && entry.rekeyPending).map((entry) => ({ entry, pending: entry.rekeyPending }));
   if (parkedElsewhere.length > 0) {
     const abandoned = parkedElsewhere.filter((item) => item.pending.state !== "pending");
@@ -4743,7 +4820,7 @@ async function pathExists2(path) {
 init_unwire();
 init_local_mcp_runtime();
 init_runtime_manifest();
-var CONNECTOR_VERSION = "0.0.0-dev.202609190647.18526db";
+var CONNECTOR_VERSION = "0.0.0-dev.202609190936.6937e31";
 var CONNECT_OUTCOME_SCHEMA_VERSION = 1;
 var failureOutcomesByError = /* @__PURE__ */ new WeakMap();
 function failureOutcomeFor(runtimeHint, error) {
@@ -4870,6 +4947,27 @@ async function executeConnect(options, deps, trace) {
       }
     }
   }
+  const existingAgents = await listExistingKeyedAgents(options.credentialsDir);
+  if (existingAgents.length > 0) {
+    log("");
+    log(
+      `Heads-up (before anything is written to this machine): it already carries ${existingAgents.length} agent director${existingAgents.length === 1 ? "y" : "ies"} with stored keys \u2014 ` + existingAgents.map((a) => `${a.agentId}${a.accountAddress ? ` (spends from ${shortAddress(a.accountAddress)})` : ""}`).join(", ") + ". This setup creates a NEW agent alongside them and revokes nothing."
+    );
+  }
+  const hostedNameForRun = serverNamesFor(serverName).hosted;
+  let reboundFrom;
+  const holders = (await listMcpServerBindings(options.credentialsDir)).filter(({ binding }) => binding.server_name === hostedNameForRun).sort((a, b) => a.binding.bound_at < b.binding.bound_at ? 1 : a.binding.bound_at > b.binding.bound_at ? -1 : 0);
+  const newest = holders[0];
+  if (newest) {
+    const { binding, directory } = newest;
+    const backendChanged = withoutUserinfo(binding.api_url) !== withoutUserinfo(options.apiBaseUrl);
+    const previousApiUrl = withoutUserinfo(binding.api_url);
+    reboundFrom = { server_name: binding.server_name, agent_id: binding.agent_id, api_url: previousApiUrl, bound_at: binding.bound_at, backend_changed: backendChanged };
+    const beingReplaced = replacing?.superseded.some((entry) => entry.directory === directory) ?? false;
+    log(
+      `Heads-up: the MCP server name '${binding.server_name}' was bound to agent ${binding.agent_id} on ${previousApiUrl} at ${binding.bound_at} (locally recorded${holders.length > 1 ? `; ${holders.length - 1} older record${holders.length > 2 ? "s" : ""} also claim${holders.length > 2 ? "" : "s"} it` : ""}). ` + (beingReplaced ? `This run replaces that wiring, as you chose, with a new agent on ${withoutUserinfo(options.apiBaseUrl)}` : `This run rebinds it to a new agent on ${withoutUserinfo(options.apiBaseUrl)}`) + (backendChanged ? " \u2014 a DIFFERENT backend: any saved session, script or document naming this MCP server now resolves to a different backend and agent." : ".")
+    );
+  }
   const localKey = generateKey();
   const localApiKey = generateLocalApiKey();
   log("Minting a fresh signing key and API key \u2014 both stay on this machine.");
@@ -4933,6 +5031,21 @@ async function executeConnect(options, deps, trace) {
     warn: log
   });
   trace.directory = credentialPaths.directory;
+  try {
+    const bindingRecord = {
+      version: 1,
+      server_name: hostedNameForRun,
+      signer_name: serverNamesFor(serverName).signer,
+      agent_id: registration.agent_id,
+      api_url: withoutUserinfo(options.apiBaseUrl),
+      // never persist `user:pass@` (#3154 doc review r2)
+      ...registration.hosted_mcp_url ? { hosted_mcp_url: registration.hosted_mcp_url } : {},
+      bound_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeMcpServerBinding(credentialPaths.directory, bindingRecord);
+  } catch {
+    log("Could not record the MCP server-name binding locally (non-fatal; the next setup cannot see this binding).");
+  }
   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}`);
@@ -5012,6 +5125,7 @@ async function executeConnect(options, deps, trace) {
             replacedBy: registration.agent_id
           });
           await teardownLocalKeyMaterial(entry.directory, await readIdentityFile(entry.directory));
+          await clearMcpServerBinding(entry.directory);
           retiredAgentIds.push(entry.agentId);
           log(`Retired previous agent ${entry.agentId} locally: tombstoned, local key files removed.`);
         } catch (err) {
@@ -5081,6 +5195,8 @@ async function executeConnect(options, deps, trace) {
     supersededAgentIds,
     supersededAgentsRetiredLocally,
     ...replacing ? { retiredAgentIds } : {},
+    existingAgentsBeforeWrite: existingAgents.map((a) => ({ agent_id: a.agentId, account_address: a.accountAddress })),
+    ...reboundFrom ? { serverNameReboundFrom: reboundFrom } : {},
     setupChallengeExpiresAt: setup.challenge.expires_at,
     approvalRequired: registration.agent_status === "pending_approval",
     approvalUrl: registration.approval_url
@@ -5145,6 +5261,10 @@ function completionOutcome(input) {
     superseded_agent_ids: input.supersededAgentIds ?? [],
     ...input.supersededAgentsRetiredLocally !== void 0 ? { superseded_agents_retired_locally: input.supersededAgentsRetiredLocally } : {},
     ...input.retiredAgentIds ? { retired_agent_ids: input.retiredAgentIds } : {},
+    // #3122: always emitted on a completed run (empty list included), for the
+    // same reason as superseded_agent_ids above.
+    existing_agents_before_write: input.existingAgentsBeforeWrite ?? [],
+    ...input.serverNameReboundFrom ? { server_name_rebound_from: input.serverNameReboundFrom } : {},
     ...input.setupChallengeExpiresAt ? { setup_challenge_expires_at: input.setupChallengeExpiresAt } : {},
     ...runtimeInstall.errorCode ? { error: { code: runtimeInstall.errorCode, next_action: nextAction2 } } : {}
   };
@@ -5420,6 +5540,32 @@ function activationInstructionWithWhy(profile) {
   return profile.activationInstruction;
 }
 var RERUN_HINT = sdk.connectorRerunCommand();
+async function listExistingKeyedAgents(baseDir) {
+  const root = defaultCredentialRoot(baseDir);
+  let entries = [];
+  try {
+    entries = await promises.readdir(root);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const directory = path.join(root, entry);
+    try {
+      const identity = JSON.parse(await promises.readFile(path.join(directory, "identity.json"), "utf8"));
+      if (typeof identity.api_key !== "string" || identity.api_key.length === 0) continue;
+      let agent = {};
+      try {
+        agent = JSON.parse(await promises.readFile(path.join(directory, "agent.json"), "utf8"));
+      } catch {
+      }
+      const { accountAddress } = readStoredAccountAddress(identity, agent);
+      out.push({ agentId: typeof identity.agent_id === "string" ? identity.agent_id : entry, directory, accountAddress: accountAddress ?? null });
+    } catch {
+    }
+  }
+  return out;
+}
 async function listOtherAgentIds(baseDir, currentDirectory) {
   const root = defaultCredentialRoot(baseDir);
   let entries = [];
@@ -5847,6 +5993,8 @@ async function runCli(argv, io = {
                 status: r.status,
                 ...r.detail ? { detail: r.detail } : {}
               })),
+              // #3122: additive — whether the local server-name binding record was released.
+              binding_released: result.bindingReleased,
               // #3123: additive — what happened to the key material and why.
               teardown: {
                 status: result.teardown.status,
@@ -5869,6 +6017,7 @@ async function runCli(argv, io = {
           io.stdout(redactSecrets(`  ${mark} ${r.label}: ${r.status}${r.detail ? ` \u2014 ${r.detail}` : ""}
 `));
         }
+        io.stdout(result.bindingReleased ? "  \u2713 MCP server-name binding: released (the name is free for the next setup).\n" : "  \u2013 MCP server-name binding: none recorded for this directory.\n");
         const t = result.teardown;
         io.stdout(redactSecrets(`  ${t.status === "retained" ? "\u2717" : t.status === "forced" ? "!" : "\u2713"} Key material: ${t.status} (probe: ${t.probe}) \u2014 ${t.detail}
 `));