Module mcp_health 

Agent MCP self-heal: notice when an agent’s agentmux MCP server did not connect, tell the operator and the agent, and repair it in bounded steps (docs/specs/SPEC_AGENT_MCP_SELF_HEAL_2026_10_10.md).

Claude Code lists each MCP server’s status in its system/init frame and answers mcp_status and mcp_reconnect control requests. This module reads those frames and decides each pane’s next step; the persistent controller carries the steps out (persistent/lifecycle.rs). The steps: reconnect, reconnect again after a pause, restart the CLI in the safe profile (no shell prefix, bash_prefix::apply_for_spawn), and otherwise give up and say so. The safe-profile restart happens once per pane unless the agent asks again (agentmux-mcp doctor --heal): a failure it didn’t fix, it won’t fix the second time.

Structs

Decision

Heal 🔒

Every pane’s state, and the panes in the safe profile.

Notice

The pane row’s content. One row per episode, updated in place.

Pane 🔒

Snapshot

What agentmux-mcp doctor is told.

Enums

Action

What the controller does next.

Phase

Where a pane is in the ladder.

Status

A server’s status, as the CLI names it.

Constants

MAX_ERROR_CHARS 🔒

The longest error text kept, shown or put in a note.

MAX_PENDING_CHECKS 🔒

MAX_RECONNECTS 🔒

Reconnects before the safe profile: one at once, one after RETRY_DELAY.

NOTICE_SUBTYPE

The pane row’s frame (frontend/app/view/agent/cli-notice.ts).

PENDING_RECHECK 🔒

A server still pending at init is asked about again after this, up to MAX_PENDING_CHECKS times; the CLI gives a server 30 s to connect.

RECONNECT_PREFIX 🔒

RETRY_DELAY 🔒

SERVER

The MCP server AgentMux puts in every agent’s config.

STALE_STEP_MS 🔒

A step with no answer for this long no longer holds the next one back.

STATUS_PREFIX 🔒

VERIFY_DELAY 🔒

A reconnect the CLI calls a success is checked this long after: Claude Code answers success for a server that still failed to start.

Statics

CONFIG 🔒

Functions

agentmux_entry 🔒

The agentmux entry in a list of {name, status, …} servers.

agentmux_status 🔒

auto_enabled

Whether the automatic repair is on (agent:mcpselfheal, default on). Noticing and telling stay on either way.

control_request 🔒

give_up_note

The [AgentMux] note an agent gets when AgentMux gives up. The error is the CLI’s text about a process, so it is quoted (sanitize::quote_in_system_note): it can’t open a line or a marker.

heal 🔒

heal_now

agentmux-mcp doctor --heal: start the ladder over now, allowing one more safe-profile restart. Err says why nothing started: connected, already_healing, or no_status_yet (the CLI hasn’t reported the server).

install

Give the module the settings (srv startup). Until then, and in tests, the automatic repair is on.

is_safe_profile

Whether the pane runs in the safe profile: its MCP server failed and reconnecting didn’t help, so its CLI starts without the shell prefix.

notice_frame

The pane row for notice.

on_reconnect

The answer to our mcp_reconnect, and the step that follows.

on_status

The server’s status from a frame of process (a system/init, or the answer to our mcp_status, which also says why it failed), and the step that follows. auto: the automatic repair is on (auto_enabled).

our_response 🔒

The response of a control_response answering one of our requests.

reconnect_request_line

Ask the CLI to start the agentmux server again.

reconnect_result

The answer to our mcp_reconnect: the CLI’s reason when it says it failed. Ok only means it didn’t: the server can still be down, so the outcome is checked with mcp_status (VERIFY_DELAY).

snapshot

What srv knows about the pane’s agentmux server, for doctor.

status_from_control_response

The server’s status in the answer to our mcp_status, with the error the CLI keeps for a server that failed (MCP error -32000: Connection closed).

status_from_init

The agentmux server’s status in a system/init frame; None for any other frame, or one that doesn’t list the server.

status_request_line

Ask the CLI for its servers’ status.

truncate 🔒