pm health telemetry warning should expose flush/probe diagnostics for fetch-failed queues #205

Summary

During a 2026-06-12 3d-bots PM ecosystem audit, pm health repeatedly reported a degraded telemetry queue with fetch failed, but the remediation was too thin to tell whether the endpoint, network, auth/config, or local queue state was the problem.

No exact upstream duplicate was found from these searches: telemetry queue pending fetch failed, pm health telemetry queue, telemetry queue, and telemetry health. The only adjacent issue found was closed #138 for telemetry subcommand aliases.

Evidence

From /home/steve/GITHUB_RELEASE/3d-bots:

pm health --json
pm telemetry status --json

Observed status included:

{
  "enabled": true,
  "endpoint": "https://pm-cli.unbrained.dev/v1/events",
  "queue_entries": 243,
  "last_successful_flush_at": "2026-06-12T16:17:05.535Z",
  "last_failed_flush_at": "2026-06-12T16:21:47.830Z",
  "last_failed_flush_error": "fetch failed"
}

A later specialist pass saw the same class of warning with a larger pending queue and no endpoint probe attempted.

Observed

pm health reports telemetry_queue_pending:<n> and a generic fetch failed, but it does not provide enough next-step diagnostics to distinguish:

• endpoint unreachable vs. DNS/TLS failure
• payload rejected by endpoint
• queue too large or malformed
• local network/offline state
• disabled/proxy/env configuration problems

Expected

pm health or pm telemetry status should expose one or more of:

• explicit endpoint probe status when telemetry is enabled
• last HTTP status / transport error category
• suggested next commands such as pm telemetry flush --verbose or pm health --check-telemetry --probe-endpoint
• queue age/oldest event timestamp and retry summary
• guidance for safely clearing or preserving queues

Why it matters

The project philosophy is project management = context management, and PM telemetry is part of operational confidence. When health reports degraded telemetry, agents need enough detail to make a reliable closeout call without guessing.