feat(mcp): expose policy-scoped bounded diagnostics #358

Problem

MCP clients can list and send but cannot request a bounded explanation of discovery, SSH-return-route or receiver readiness failures through a reviewed diagnostic contract. Raw doctor output may contain more route/environment information than a shared MCP caller needs.

Proposed scope

Expose a narrowly scoped diagnostic tool around supported CLI checks. Separate local metadata inspection from explicitly permitted active connection probes and return sanitized structured findings.

Acceptance criteria

• Require explicit operator policy for diagnostic actions, destinations and permitted agents. Do not derive diagnostic authority from list/send permission or expand old policies silently.
• Enumerate supported checks and their effects. Metadata-only inspection must not automatically invoke SSH/network/native/version probes; active probes require separately explicit permission.
• Enforce bounded execution time, output/byte budgets, per-call probe limits and cancellation cleanup. Do not add continuous health monitoring, unbounded watch or automatic retries.
• Preserve exact destination/SSH/home allowlists. No arbitrary command, host, path, trusted SSH config, bind address, firewall or credential overrides.
• Return only reviewed safe summary fields. Keep raw logs, native transcripts, message contents, keys, fingerprint material and private topology/path details out of model-visible output unless a separately reviewed policy explicitly permits a narrow field.
• Distinguish configuration/discovery readiness, TCP accept, TLS, peer authentication, native submission and ACK. Missing older-version fields mean unknown, not false or success.
• Diagnostic success is not send authorization, effective-storage attestation, guaranteed return path, native consumption or ACK.
• No install/update, service restart, pairing mutation, firewall/ACL change, policy rewrite or fallback route is performed.
• Add installed stdio, policy, malformed/partial-result, timeout/cancellation, non-reflection and zero-submission fixtures. Retain current POSIX versus Windows cleanup limits.

Related work

Depends on the destination/capability contract and coordinates safe refusal/explanation fields with MCP preflight. Reuse doctor/readiness semantics, including #341/#342 diagnostics; do not reopen those completed changes or infer live acceptance.

Source: MCP guide, doctor/readiness implementation.

Planning

Proposed v1.4.0 candidate, priority P2; no committed date. Registration does not authorize active live probes, implementation, merge, release or operational changes.

Tracking dependencies

Depends on #356; coordinate structured refusal/explanation output with #357. Active probes require explicit diagnostic policy, not authority inferred from either tool's successful output.