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

package/README.md

@@ -52,6 +52,57 @@ spending authority.
    `haven_get_allowances` tools to confirm the Haven wallet and live budget.
    Do not sign, fund, or create a payment to verify setup.
 
+### `--doctor` reports every agent, not just one (#1697)
+
+With several agents wired into one runtime (`--name`), the doctor enumerates
+every credential directory on the machine and classifies each one:
+
+| Classification | Meaning |
+| --- | --- |
+| `wired` | Its MCP pair is present in this runtime's config. Fully checked. |
+| `superseded` | It holds credentials, but no config entry points at it. Reported, never silently skipped — its API key may still spend. |
+| `retired` | Tombstoned (see below); key material removed. |
+| `orphaned` | No usable identity and no tombstone. |
+
+The exit code is non-zero if **any** wired agent fails **any** check — not
+only the one the report's main section describes. In `--json`, the same
+information is on `agents[]`, each entry carrying `slug`, `agentId`,
+`directory`, `classification` and its own `checks[]`; the flat `checks` array
+is retained and still describes one agent, so a single-agent install reads as
+it always did.
+
+One check is worth calling out: **`identity_match`** compares the agent the
+stored API key actually authenticates as against the `delegate_address` in
+that directory's `signer.json`. A mismatch means the runtime would quote as
+one agent and sign as another, and it fails hard. This is the half of that
+hazard a local tool can know — the doctor still cannot see inside an
+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
+(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
+failure surfaces only as a masked "Connection closed" retried every few
+minutes. Two rules follow:
+
+1. **Restart EVERY long-lived host after a setup or retirement, not just one.**
+   Each process holds the snapshot from its own start time, so after a chain of
+   re-setups each host can be parked on a *different* old agent.
+2. **Tombstone a directory before (or instead of) deleting it:**
+
+   ```
+   npx @haven_ai/connect@alpha --tombstone ~/.haven/agents/<id> --reason "superseded"
+   ```
+
+   This replaces the directory's signer wrapper with a diagnostic that logs the
+   retirement (agent id, date, reason, restart guidance) to the host's MCP
+   stderr log on every probe, and records it in `TOMBSTONE.json` for
+   `--doctor`. It touches no key material and revokes nothing — revoke the
+   agent on the Haven agent page yourself. Delete the tombstone only once every
+   long-lived host has been restarted.
+
 ### Structured output for automation
 
 Pass `--json` when a launcher needs a machine-readable completion record. Connect
@@ -124,16 +175,104 @@ already-configured machine behaves as follows (characterized in
 - **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. One runtime is
-  therefore wired to one Haven agent — the newest one.
+  Unrelated MCP servers and configuration are preserved. Without `--name`, one
+  runtime is therefore wired to one Haven agent — the newest one. 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.
-- **Connect never overwrites an existing credential file.** A write that would
+- **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
-  re-run cannot corrupt stored key material.
+  re-run cannot corrupt stored key material. **`--rekey` is the one exception,
+  and it is a different operation** — it deliberately replaces a credential set
+  in place, at an unchanged path, and is the supported way to replace a key
+  rather than accumulate agents. See
+  [Replacing an agent's signing key](#replacing-an-agents-signing-key-rekey).
+
+## Running several agents in one runtime
+
+`--name <slug>` gives an agent its own MCP server pair and its own credential
+directory, so several agents coexist in one runtime instead of replacing each
+other:
+
+```sh
+npx -y @haven_ai/connect@alpha --setup hv_setup_... --api https://api.haven.example \
+  --name research --runtime claude-code
+```
+
+| | Without `--name` | With `--name research` |
+|---|---|---|
+| MCP entries | `haven`, `haven-signer` | `haven-research`, `haven-signer-research` |
+| Credentials | `~/.haven/agents/<agent-id>/` | `~/.haven/agents/research/` |
+
+A writer only ever touches the pair it owns, so adding a named agent cannot
+disturb the bare pair or another named one. Omitting `--name` is byte-identical
+to how the connector behaved before named pairs existed, so nothing already
+wired needs changing.
+
+The slug is **1–32 lowercase letters, digits and single hyphens**, validated
+before anything is written, and **immutable once wired** — it is the server name
+and tool prefix every host depends on. `haven`, `signer` and `signer-*` are
+refused, because their derived names would collide with another pair's.
+
+> A current connector reports the resolved server name (`haven`, or
+> `haven-<slug>`) to Haven at registration, and the dashboard shows it on each
+> agent, so you can match an agent to its config entry without leaving the
+> browser ([#1878](https://github.com/d-hinders/Haven-AI/issues/1878)). It is a
+> label, not authority — nothing keys off it.
+>
+> Agents connected before that shipped read **"MCP name not recorded"**: Haven
+> genuinely does not know, and guessing would name the wrong pair for anyone who
+> used `--name`. They keep working exactly as they are; `--doctor` on the machine
+> still maps them, and reconnecting records the name.
+
+## Replacing an agent's signing key (`--rekey`)
+
+If an agent's signing key is lost or exposed, replace it: same agent, same name,
+same history, new key. This does **not** create a new agent, and it is not the
+same as running setup again.
+
+Re-key is authorised by the **account owner in the dashboard** — the connector
+never calls Haven's re-key endpoints, which refuse an agent credential by
+design. So it runs in two phases with the dashboard between them:
+
+```sh
+# 1. On this machine: generate the new key, print its public address.
+npx -y @haven_ai/connect@alpha --rekey [--name research]
+
+# 2. In the dashboard: agent → Replace signing key → paste that address.
+#    Sign the steps. It shows a new API key ONCE.
+
+# 3. Back here: write the new credentials and rewire this agent's MCP pair.
+npx -y @haven_ai/connect@alpha --rekey-finish --api-key sk_agent_... \
+  --runtime claude-code [--name research]
+```
+
+Between the two phases nothing has changed: the agent keeps working on its old
+key until you finish. Phase one refuses up front what the backend would refuse
+anyway — a legacy-rail account, a revoked agent — so you find out before signing
+anything. Phase two refuses to write unless the pasted key authenticates,
+belongs to **this** agent, and Haven's recorded signing address matches the one
+this machine generated.
+
+**Pass `--runtime` on the finish step.** Your API key lives inside the MCP config
+as well as in the credential files, so without it the credentials are correct and
+every wired host still presents the retired key and fails with 401.
+
+**Then restart every long-lived host** — not just the one in front of you. Each
+long-running process loaded its wiring at startup and is still holding the old
+key. The connector prints the exact restart command for your runtime; the sweep
+across the rest is yours.
+
+> **If the key is lost, check for a balance on it first.** An agent's delegate
+> address can hold a small amount from x402 settlement, and sweeping it needs a
+> signature from that key. After a re-key it is unrecoverable — by you and by
+> Haven. Haven's preflight reads the balance and refuses until you say what
+> happened to it. Full detail:
+> [Replacing an agent's signing key](../../docs/product/agent-key-rotation.md).
 
 ## Diagnosing a stuck setup: `--doctor` / `--repair` (#1589)
 
@@ -150,6 +289,23 @@ prints one concrete repair action; the exit code is non-zero on any failure.
 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
+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
+probe is a note, never a verdict. Connect never revokes or deletes
+credentials itself — it reports, you decide. The setup completion output
+names superseded agents the moment they are created, for the same reason.
+One honest limit: "newest" is decided by file mtime, so a restored backup or
+a sync tool that rewrites timestamps can make doctor examine the wrong
+directory as current — before revoking anything, confirm the agent id
+against the Haven agent page, which is the authority on which agent is
+which.
+
 `--repair` re-runs what setup already owns — reinstall the pinned signer
 runtime, rewrite the wrapper + sidecar, and re-write the runtime config from
 the STORED credentials. It never touches keys and never needs a new token.