Parent

Part of #3000 and follows #4179.

Goal

Upgrade /doctor memory from a raw metric dump into a small triage report that highlights memory pressure and likely next actions.

Motivation

Users can paste RSS/heap numbers today, but reviewers still have to interpret whether the process is near the V8 heap limit, whether RSS is suspiciously higher than V8 heap, or whether active handles/requests suggest runtime retention. A first-pass interpretation layer makes OOM reports more actionable without adding heavy heap snapshots yet.

Scope

• Compute lightweight derived metrics from the existing memory diagnostics object:
  • heap used ratio versus V8 heap size limit
  • heap used ratio versus heap total
  • RSS minus V8 heap total gap
  • external + arrayBuffer pressure
• Add a compact Interpretation section to /doctor memory output.
• Classify pressure as low, medium, or high using conservative thresholds.
• Include safe suggestions, for example:
  • run /compact or restart for high heap pressure
  • attach a heap snapshot only if requested by maintainers
  • suspect large tool results/history when heap pressure is high in long sessions
• Keep the output deterministic and paste-safe.

Non-goals

• No heap snapshot generation.
• No session history or tool-result inventory yet.
• No automated memory-pressure guard in the main loop.

Acceptance criteria

• Unit tests cover low/medium/high pressure formatting.
• Existing /doctor memory fields remain present.
• The interpretation does not expose private prompt/session contents.
• Non-interactive output remains plain text and easy to paste into GitHub issues.