fix: explain unknown agent discovery failures

Supersedes #1511.

This is the maintainer takeover of the draft unknown-agent diagnostics fix. It preserves the contributor work, adds changelog credit, and reconciles diagnostics with symlinked agent directory discovery.