@haven_ai/connect 0.1.28-alpha.0 → 0.1.29-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
@@ -150,6 +201,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.