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: ced7048d-24d2-45bf-b781-a887071b9c27

📥 Commits

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

📒 Files selected for processing (1)

• docs/next/CHANGELOG.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/next/CHANGELOG.md

Included review availability: Your plan provides up to 10 included reviews per hour; 4 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 an Unreleased changelog entry.

Changes

Agent explain error handling

Layer / File(s)	Summary
Structured file-read error path src/cli/agent.rs, tests/cli/agents.rs, docs/next/CHANGELOG.md	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, and the changelog records the behavior.

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

Merge Risk: ⚪ Minimal · up to 2c438

The change makes missing-file failures return structured JSON while preserving successful behavior. No actionable merge-blocking risk remains; the noted clean-master test failure is not attributed to this change.

Possibly related issues

• herdrdev/herdr#3022 — Covers the missing agent explain --file error behavior addressed by this change.

🚥 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 structured JSON errors on stderr with exit code 1.

• Adds an ErrorResponse with the agent_explain_file_read_failed code and path context.
• Adds a process-level regression test covering JSON structure, streams, and exit status.
• Documents the corrected behavior in the changelog.

Confidence Score: 5/5

The PR appears safe to merge with no actionable defects identified.

The new failure branch follows existing CLI error conventions, emits one serializable error response to stderr, and returns the intended nonzero exit code without duplicate reporting.

Important Files Changed

Filename	Overview
src/cli/agent.rs	Converts local fixture read errors into the established structured CLI error format without affecting successful file or live-pane explanations.
tests/cli/agents.rs	Adds focused process-level coverage for the missing-file response, stderr JSON, empty stdout, and exit code.
docs/next/CHANGELOG.md	Accurately records the user-visible structured-error fix.

_{Reviews (1): 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.