Preserve structured child errors and retry guidance in batch JSON summaries

[Widthdom]

Problem and priority

P2 — second in this audit batch. Batch summaries replace an actionable structured child error with a generic exit-code-derived error. Automation cannot distinguish an output-budget failure from invalid arguments or reuse the child's retry advice.

Reproduction

Observed with a locally built cdidx from origin/main at b52ac0fc372a22eb9667ba409d3d204c153d3188, on macOS, during the 2026-09-05–06 JST dogfood audit. dotnet build passed with zero warnings/errors. Commands below run from the repository root; CLI shorthand means dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll.

Run directly:

dotnet ./src/CodeIndex/bin/Debug/net8.0/cdidx.dll status --explain index_complete --json --max-json-bytes 1024 --db .cdidx/codeindex.db

Observed: E028_RESPONSE_BUDGET_TOO_SMALL, category:response_budget, minimum_required_bytes:1472, and retry.recommended_bytes:2496 (sizes can vary with runtime metadata).

Place this line in a JSONL input file:

["status","--explain","index_complete","--json","--max-json-bytes","1024"]

Feed it to cdidx batch --db .cdidx/codeindex.db --json-summary --parallel 4. The child record instead contains E010_USAGE_ERROR, category:batch_child_usage, and generic help, with no structured minimum-size/retry fields.

A second observed input reproduces the same loss:

["search","File.Delete","--json=array","--max-json-bytes","512","--limit","2"]

Direct search returns E028 and its measured output-size/retry fields. Batch loses them. Both cases belong in this one PR.

Prior issues and recurrence classification

Follow-up to closed #4871, which standardized typed batch failures and required actionable context and sequential/parallel envelope parity. The current envelope is typed, but structured child semantics are still lost. Related foundation: #4582, #4723 and #4142. We have not bisected an introduced regression; do not claim the old malformed-input bug itself recurred.

Implementation guide / one-PR scope

• Limit changes to batch child-error capture, parsing and serialization; do not change individual query budget policies.
• Inspect src/CodeIndex/Cli/QueryCommandRunner.Batch.cs:299–335: the null-error fallback derives a generic category from the exit code.
• Retain a bounded, sanitized structured error object from valid child JSON; preserve stable error_code, category, message/hint, and documented budget/retry fields.
• Safe structured errors should be available without opting into raw streams. Preserve --include-raw-streams as an explicit separate diagnostic facility.
• Treat child output as untrusted: enforce byte/depth limits, avoid arbitrary stderr splicing and sensitive-data exposure, and retain a safe fallback for non-JSON/malformed output.
• Preserve one record per input, stable order, aggregate exit status and parent output budgets.

Acceptance and validation

• Direct versus batch errors retain equivalent machine classification and retry data for both reproductions.
• Sequential and parallel batch modes agree.
• Cover malformed child JSON, text failures, cancellation, mixed successful/failed commands and tiny parent budgets.
• Keep existing raw-output compatibility documented; current help describes raw failed output, so clearly document this additive structured-error improvement.
• Follow AGENT_GUIDE.md and the relevant test/workflow guidance. Keep the implementation scoped to this issue. Add focused behavioral/contract tests where behavior changes, run the relevant net8.0/net9.0 checks, update affected CLI/help/README/developer documentation, and add a bilingual changelog.d/unreleased/ fragment for user-visible behavior. Preserve cross-platform behavior and backward compatibility.

[Widthdom]

Work started on branch fix-issue5259 from the latest fetched origin/main. I will address structured child error preservation and retry guidance in batch JSON summaries, with focused validation, bilingual documentation/changelog updates, and Codex adversarial review.