fix(agent): explain abnormal turn endings instead of blank/partial reply

[Bartok9]

Summary

• When a turn ends abnormally after tools (empty content after retries, a partial/truncated stream, exhausted retries, or an iteration/budget limit), surface a single user-visible explanation of why the reply stopped instead of leaving a blank or fragmentary response box.
• Normal successful short replies (e.g. Done.) stay completely quiet.

Motivation

Closes #34452.

After substantive tool calls (read_file, patch, …) the turn could end with no usable assistant reply or only a fragment (e.g. The). The internal turn_exit_reason values (empty_response_exhausted, partial_stream_recovery, all_retries_exhausted_no_response, max_iterations_reached, …) already exist but were never explained to the user at end of turn — the failure was silent from the UI's perspective, and the user couldn't tell whether to send continue, switch model/provider, or inspect tool output.

The issue explicitly asks for behavior "similar in spirit to the file-mutation verifier footer, but for turn-completion failures." This PR follows that existing pattern exactly:

• New _format_turn_completion_explanation(turn_exit_reason) maps an abnormal reason to a short, actionable message. It returns "" for normal text_response(...) exits and for diagnostic-only reasons (unknown, guardrail_halt — which already surfaces its own message), so healthy turns are never annotated.
• At turn end in agent/conversation_loop.py, right after the file-mutation verifier footer, when there is no genuinely usable reply this turn — an empty response, the (empty) terminal sentinel, or a suspiciously short partial fragment (≤24 chars without sentence-ending punctuation, and not a text_response exit) — the explanation either replaces the bare (empty) sentinel or is appended after a partial fragment so the user sees both what arrived and why it stopped.
• Gated by display.turn_completion_explainer (default True) with HERMES_TURN_COMPLETION_EXPLAINER env override, mirroring _file_mutation_verifier_enabled so gateway and CLI share one setting.

Verification

• python3 -m pytest tests/run_agent/test_turn_completion_explainer.py — 11 passed (formatter map, enable/disable seam, end-to-end empty-exhausted surfaces the explanation, normal Done. stays quiet).
• python3 -m pytest tests/run_agent/test_run_agent.py tests/run_agent/test_tool_call_guardrail_runtime.py — 362 passed. Five pre-existing tests that asserted the bare final_response == "(empty)" sentinel were updated to assert the new user-visible explanation (the (empty) sentinel was precisely the silent-failure symptom this issue reports); all other assertions in those tests (api-call counts, status emissions, completed) are unchanged.
• Did NOT change: streaming/recovery paths, the empty-response retry/fallback machinery, or the turn_exit_reason values themselves — only their end-of-turn presentation when no usable reply exists.

Differential value (related, not duplicate)

Existing open PRs address adjacent but different failure modes:

• fix(gateway): close silent response loss after agent tool calls (#29346) #34336 — gateway drops a correct, non-empty answer (a delivery bug).
• [codex] fix(gateway): surface empty agent responses #32456 — empty response specifically after /stop.
• fix(agent): emit recovered/fallback text to stream clients before close (#31449) #31539 — streams recovered partial text to clients.

None of them produce the consolidated end-of-turn explanation for the empty/exhausted/iteration-limit cases that #34452 asks for. This PR is complementary: it explains the genuinely-no-reply outcome rather than recovering or delivering content.

[teknium1]

Merged via PR #34848 — your commits were cherry-picked onto current main with your authorship preserved in git log (59b0ea9, de6d602). Thanks for the clean implementation following the file-mutation-verifier pattern; we added the DEFAULT_CONFIG key registration and shortened the footer prefix on top. #34848