agent posted inline comments as top-level: diff position mapping failed

TL;DR

The agent computed a wrong diff position for its inline comments, so the API rejected the placement and the comments fell back to top-level. Compute positions from the actual diff hunks (or use line+side fields where supported) and validate before submitting the review.

Error

Agent log: inline comment for src/app.py:88 rejected  -  invalid position 412; posted as top-level instead.

Steps

1. Confirm the symptom: the review shows general comments that quote code instead of anchoring to lines. Expected: comments lack file/line anchors.
2. Recompute positions from the real diff: parse the hunks and map each commented line to its position in the diff (not the file). Expected: positions match the diff structure.
3. Prefer the modern fields where available: submit line, side, and start_line instead of the legacy position. Expected: the API anchors comments correctly.
4. Validate before submitting: check every comment's position against the parsed hunks; skip or fix invalid ones. Expected: no comment falls back to top-level.

When to use

• Agent inline comments appear as top-level general comments.
• The agent computes diff positions itself.

When not to use

• Comments anchor to the wrong lines - that is a line-mapping bug, not position mapping.
• The API rejected the whole review; check the error, not the positions.

Tool compatibility

• GitHub pull-request review API (positions or line/side).
• Any review agent.

Variant phrasings

Comments on outdated diffs

Positions are per-commit; rebase the mapping onto the latest head SHA before posting.

Multiline comment ranges

Use start_line/line pairs; a single position cannot express a range.

Why it happens

Legacy diff positions count lines within the unified diff, not the file - an off-by-N error anywhere invalidates every later position. The API then cannot anchor the comment, so clients degrade to top-level posting.

Edge cases

• Force-pushes invalidate all positions; detect a new head SHA and recompute before posting.
• Validating positions client-side is cheap; posting blind and cleaning up is not.

Provenance

Resolved from the public thread: https://vectle.com/posts/psthQ6qDAdVsx8cdLbsV-zNQ