fix(review-pr): schema mismatch, chunk size, and timeout diagnostics

[derekmisler]

Summary

Three targeted fixes for the runaway-drafter timeout seen in docker/sailor PR #754.

Failing run: https://github.com/docker/sailor/actions/runs/25577728034/job/75088929732

The root cause: the drafter sub-agent looped for 1799 s re-reading the same 4 files ~140× each because its enforced structured_output schema rejected every emit attempt, causing the model to keep doing more file reads instead of returning results.

---

Fix 1 — Schema mismatch in review-pr/agents/pr-review.yaml

Root cause of the infinite loop. The root agent's transfer_task delegation message did not explicitly document the drafter's enforced structured_output schema field names. When the LLM generated the task string it used title/body (natural GitHub review terminology) instead of the schema-required category/issue/details/in_diff. Every emit attempt was rejected by schema validation, causing the drafter to loop indefinitely reading the same source files ~140× each until SIGKILL at 1800 s.

Changes:

• Add a CRITICAL block in the ## CRITICAL: How to delegate to the drafter section documenting the exact drafter response schema, with an explicit warning never to use title/body
• Update step 4d (aggregate findings) to reference the correct field names
• Update step 5 (parse drafter response) to explicitly name issue and details
• Update step 9 (build inline comments) to list all correct finding fields

The drafter's structured_output schema itself is unchanged — it is the contract.

---

Fix 2 — Lower soft chunk target 1000 → 600 lines (review-pr/action.yml)

Chunk 1 of sailor PR #754 was 1229 lines of dense Rust snapshot/restore code — at the edge of what a drafter can process in one turn, amplifying the schema-loop impact. Lowering the soft target produces smaller, more manageable chunks.

• Soft target: 1000 → 600 lines (split triggers when this is exceeded and directory changes)
• Hard cap: 2000 lines (unchanged)
• Updated the nearby comment and log echo to stay accurate

---

Fix 3 — Better exit-124 diagnostics (review-pr/action.yml)

When the agent timed out, the PR received a generic "PR Review Failed" comment and an unhelpful step summary. Users had no idea why it failed or what to do.

Changes:

• Add a dedicated elif [ "$EXIT_CODE" = "124" ] branch before the generic non-zero exit handler
• Post an actionable PR comment explaining the timeout and suggesting /review retry or splitting the PR
• Add a TIMEOUT_NOTE (exit code 124, 1800 s limit, verbose log artifact reference) printed in the step summary
• All other non-zero exit code behaviour is unchanged

---

Testing

• pnpm build ✅ (all bundles compiled successfully)
• pnpm lint — Biome and tsc pass; one pre-existing actionlint warning about node24 runner in test-e2e.yml (existed on main before this PR)
• pnpm test — pre-existing DNS sandbox failure (unrelated to these changes, also reproducible on main)

[docker-agent]

Assessment: 🟢 APPROVE

All three fixes look correct and address the described root causes. The schema documentation addition in pr-review.yaml is accurate and will prevent the drafter loop. The 1000→600 line chunk-size reduction is straightforward. The timeout branch logic is sound. One minor cosmetic issue noted inline.

[docker-agent]

Assessment: 🟢 APPROVE

All three fixes in this PR are correct:

1. Schema mismatch documentation (): The added block correctly documents the drafter's enforced schema fields (, , , ) and explicitly warns against using /. The field names in steps 4d, 5, and 9 are consistently updated to match.

2. Chunk soft-target reduction (, 1000→600 lines): The logic change is applied consistently across the condition check and both log messages. No off-by-one issues; the hard cap (2000 lines) and chunk boundary logic are unchanged.

3. Timeout diagnostics (, exit code 124): The new elif [ "$EXIT_CODE" = "124" ] branch is correctly positioned before the generic non-zero handler. The gh api call uses -f body="..." which automatically triggers POST per gh api's documented behaviour (no explicit -X POST needed — identical pattern to the pre-existing non-zero-exit error comment at line 838). The TIMEOUT_NOTE multiline string, printf '%s\n' usage, and if [ -n "$TIMEOUT_NOTE" ] guard are all correct.