[P3] doctor prints JSON to stdout, human text to stderr, and always exits 0

[bigknoxy]

Audit ref: AUDIT-2026-08.md item B44 · Priority P3 (score 39) · Evidence: cli.ts:803-804

Context

doctor is the command a user runs when something is wrong. It currently makes that harder in two ways (cli.ts:803-804):

1. Streams are backwards. The JSON goes to stdout and the human-readable summary goes to stderr. So structured-edit doctor shows JSON to a human, and structured-edit doctor 2>/dev/null hides the readable part. Both audiences get the wrong thing.
2. It always exits 0, even when it reports an unhealthy installation. Nothing can gate on it — not CI, not the installer, not a setup script.

Required behavior

1. Adopt the global --format json|text rule: text to stdout on a TTY, JSON to stdout when piped. Diagnostics only on stderr. Never both payloads at once.
2. Exit non-zero when unhealthy. 0 healthy, 1 warnings only, 2 one or more failures. Document it — this is what makes doctor usable as a CI gate and as the installer's final verification step.
3. Make the output actionable: every failed check names the specific fix command, not just "missing". Since doctor is where the audit's silent-AST-fallback problem becomes visible, it must explicitly report whether the tree-sitter bindings actually loaded, per language — getParser() swallows init errors and returns null, so a broken native build currently manifests only as mysteriously-worse edits.
4. Report versions of everything relevant: HashPilot, Bun, each parser, LSP servers if present, config file locations actually in use.

Acceptance criteria

• Text output on stdout for TTY; JSON on stdout when piped; nothing on stderr but diagnostics.
• Exit codes 0/1/2 by health, documented.
• Per-language parser load status reported, including the failure reason when a parser is unavailable.
• Every failing check includes a concrete remediation command.
• install.sh runs doctor at the end and fails the install on exit 2.

[bigknoxy]

🎉 This issue has been resolved in version 4.5.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀