fix: report agent explain file errors as json

[akbash-bot]

Issue

A missing file passed to herdr agent explain --file prints a Rust I/O error instead of structured JSON. Shell wrappers cannot read an error code from that output.

Problem

The local fixture read returned its operating-system error directly. The CLI's top-level error handling then printed the Rust debug representation.

How did we fix it?

Herdr now converts local fixture read failures into an ErrorResponse. It writes one agent_explain_file_read_failed JSON response to stderr and exits with code 1. Successful fixture and live-pane explanations are unchanged.

Verification

The process test failed before because stderr could not be parsed as JSON. It now verifies the exact command, response ID and code, path context, output streams, and exit status. Formatting, clippy, Windows lint, 3,488 other Rust tests, integration assets, and maintenance checks passed. live_server_holds_one_pty_master_fd_per_pane still fails on clean master because its replacement server does not appear.

refs #3022

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7dd34810-5944-4621-9b50-1cd6ca0fb653

📥 Commits

Reviewing files that changed from the base of the PR and between 2c438d4 and 565a2fb.

📒 Files selected for processing (1)

• docs/next/CHANGELOG.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

herdr agent explain --file now reports file-read failures as structured JSON on stderr with exit code 1. The change adds schema imports, regression coverage, and Unreleased changelog entries.

Changes

Agent explain error handling

Layer / File(s)	Summary
Structured file-read error path src/cli/agent.rs, tests/cli/agents.rs	File-read failures now produce serialized ErrorResponse output with an error ID, error code, path-specific message, and exit code 1. The CLI test covers a missing file.
Release note updates docs/next/CHANGELOG.md	The Unreleased changelog records separate light and dark theme overrides and fixes for agent, Windows, input, rendering, workspace, and structured fixture-read behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 565a2

This localized change makes missing-file errors return structured JSON while preserving successful explanations, and no actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: reporting agent explain file errors as JSON.
Description check	✅ Passed	The description directly explains the file error handling change, its behavior, and verification results.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch akbash/3022-agent-explain-file-error

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ogulcancelik]

@akbash-bot fix conflicts pls

[greptile-apps]

Greptile Summary

The PR converts herdr agent explain --file read failures into a structured JSON error on stderr with exit code 1.

• Adds an agent_explain_file_read_failed error response containing the requested path and underlying I/O error.
• Adds a CLI process test covering output streams, response fields, and exit status.
• Documents the behavior change in the next release changelog.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/cli/agent.rs	Converts fixture read errors into the CLI's structured ErrorResponse format and returns exit code 1.
tests/cli/agents.rs	Verifies missing fixture files produce parseable JSON on stderr, no stdout, and the expected failure status.
docs/next/CHANGELOG.md	Records the new structured error behavior for agent explanation fixture reads.

_{Reviews (2): Last reviewed commit: "fix: report agent explain file errors as..." | Re-trigger Greptile}

[akbash-bot]

Done — rebased onto current master, resolved the changelog conflict, and all PR checks plus CodeRabbit and Greptile are green at 2c438d4.

[MaxAsif]

@akbash-bot fix conflict

[ogulcancelik]

@akbash-bot the implementation review is clean. please rebase onto current master, resolve the changelog conflict, and rerun checks and both review bots.

[akbash-bot]

I rebased and resolved the changelog conflict locally, but I cannot update this PR head: akbash-bot currently has triage access and no push permission on herdrdev/herdr, while this PR points to the canonical repository branch. The rebased commit is aa9a10f6 on akbash-bot:akbash/3022-agent-explain-file-error. Please restore canonical push access or update that canonical branch, then tag me and I’ll rerun CI and both review bots.