fix(mcp): review round 2 — busy-skip the refresh pass, fail-fast list pairs, health-tick refresh retry

- _refresh_server never parks on a held connect lock: the holder is
  itself a catalog publisher whose publish supersedes the pass, and
  parking burned refresh_sync's whole 30s budget on ONE busy server (a
  reconnect attempt holds the lock up to 45s), failing the operator
  pass for every healthy server queued behind it. Busy → skip (None),
  no publish, no status writes; the identity/state recheck stays as
  belt-and-braces for the one-tick check→acquire race.
- _list_resource_pair: the ONE copy of the paired resources/templates
  list protocol (both twins). Fail-fast — a fast real error (auth /
  method rejection) surfaces as ITSELF instead of being masked behind
  a hung sibling's eventual 30s TimeoutError — with the survivor
  CANCELLED and REAPED inside the timeout scope, never left detached
  on the shared session.
- Health-tick refresh retry: there is NO periodic refresh pass
  (removed in eb2a119d; the docs still claimed the 4h tier — fixed),
  so a push refresh that failed while the transport stayed up had no
  automatic recovery and the shared catalog stayed stale for every
  user until an operator intervened. Failures and busy-skips arm
  _static_refresh_retry via the shared recorder; the health tick
  drains it with one bounded, lock-serialized full pass per tick;
  success, session drops, removal, and the post-reconnect spawns
  clear it. This also un-latches the error pill: the retry's
  completion clears it within a tick.
- _record_refresh_failure: the bearer-redaction policy (type +
  message, never exc_info) lives exactly once; all three
  refresh-failure sites route through it.
- Static runner discards its coalesce marker only AFTER the
  lock-identity check: on the superseded path a marker present in the
  set belongs to the re-added generation's parked runner, and
  discarding it would mint duplicates past the one-parked-runner
  bound (the pool runner deliberately differs — nothing else clears
  pool markers, so its marker is its own to release).
- _clear_static_push_state: the ONE (server, kind) keyspace walk for
  stamps + retry flag (+ markers on removal).
- Tests: busy-skip, superseded-no-status, fail-fast + reap (<5s
  bound), retry arm/drain/re-arm/clear quartet, logged-wrapper
  contract updated to the shared recorder's arg shape; vacuous
  stamp-math test deleted (behavioral per-kind coverage retained);
  _free_port/_wait_tcp_ready/_wait_session_live hoisted to conftest
  for both live tests.

Refs #839

docs/tools.md

@@ -779,7 +779,10 @@ MCP tool lists stay up-to-date without restart through two mechanisms:
 1. **Push notifications** -- MCP servers that declare `tools.listChanged: true` in
    their capabilities send `notifications/tools/list_changed` when their tool list
    changes. `MCPClientManager` registers a `message_handler` on each `ClientSession`
-   that triggers an immediate refresh for that server.
+   that triggers an immediate refresh for that server (debounced per server and
+   notification kind, and run off the receive loop). A refresh that fails while
+   the connection stays up is retried automatically on the next health-loop tick
+   until one completes.
 
 2. **Manual** -- `/mcp refresh` re-fetches tools from all servers immediately.
    `/mcp refresh <server>` targets a single server. If a server has disconnected,
@@ -787,6 +790,10 @@ MCP tool lists stay up-to-date without restart through two mechanisms:
    same controls (refresh / reconnect buttons per server) for cluster-wide
    fan-out.
 
+Reconnects (health-loop, dispatch-driven, or operator-forced) always end in a
+full catalog rediscovery, so a server that changed its tools while disconnected
+comes back current.
+
 When tools change, `MCPClientManager` rebuilds its merged tool list using copy-on-write
 (new list/dict objects assigned atomically) and notifies all active `ChatSession`
 instances via registered listener callbacks. Each session rebuilds its `_tools`,
@@ -857,13 +864,16 @@ catalog.
 
 ### Refresh
 
-Resource lists stay current through the same three-tier mechanism as tool lists:
+Resource lists stay current through the same mechanisms as tool lists:
 
 1. **Push** -- Servers declaring `resources.listChanged: true` send
-   `notifications/resources/list_changed`, triggering an immediate refresh.
-2. **Periodic** -- Servers without push are polled on the configured refresh
-   interval (default 4 hours, same timer as tools).
-3. **Manual** -- `/mcp refresh` re-fetches resources alongside tools.
+   `notifications/resources/list_changed`, triggering an immediate refresh
+   (with the same failed-refresh retry on the health-loop tick).
+2. **Manual** -- `/mcp refresh` re-fetches resources alongside tools.
+
+Servers without push support are refreshed whenever they reconnect (every
+reconnect ends in full rediscovery) or when an operator refreshes manually;
+there is no periodic polling.
 
 ---