feat: PR annotation — post agent session summary as a GitHub PR comment automatically

[Siddhant-K-code]

Problem

When an agent produces a PR, the reviewer gets the diff but not the story: what did the agent read first, how much did it cost, did it hit any lint violations, were there redundant tool calls? That context lives in .agent-traces/ but never surfaces where the reviewer actually looks.

The current workaround is to manually run agent-strace share and paste the link — which nobody does.

---

Proposed solution

agent-strace pr-comment — post a structured summary of the agent session to the PR it produced.

# Post comment to the current branch's open PR
agent-strace pr-comment

# Post comment for a specific session
agent-strace pr-comment SESSION_ID

# Dry run — print the comment without posting
agent-strace pr-comment --dry-run

Comment format

## agent-trace session summary

| | |
|---|---|
| **Session** | `abc123` · 2m 14s |
| **Cost** | $0.31 (142 tool calls) |
| **Model** | claude-opus-4-6 |
| **Status** | completed |

### What the agent did
- Read 8 files, modified 4
- Phases: explore → implement → verify (3 test runs)
- 1 context reset at 1m 02s

### Flags
- ⚠️ 2 redundant reads (`src/auth.py` read 3×)
- ✅ No lint violations
- ✅ No errors

<details>
<summary>Replay this session</summary>

```bash
agent-strace replay abc123
```

Or [view the HTML replay](link-to-share) (if hosted collector is configured).
</details>

GitHub Actions trigger

Auto-post on PR open/update when .agent-traces/ exists:

# .github/workflows/agent-trace-pr.yml
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  annotate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Siddhant-K-code/agent-trace@gha-v1
        with:
          post-pr-comment: true
          github-token: ${{ secrets.GITHUB_TOKEN }}

Implementation notes

• Uses gh CLI or GitHub API to post the comment — no new dependencies
• Session is identified by matching the latest session timestamp to the most recent commit in the branch
• If multiple sessions exist for the branch, posts a summary of all of them with individual cost/status rows
• Idempotent: updates the existing comment on re-run rather than posting a new one (identified by a hidden HTML comment marker)
• Works with GitLab MR comments via --platform gitlab flag

---

Acceptance criteria

• agent-strace pr-comment posts a structured comment to the open PR for the current branch
• Comment includes: cost, duration, tool call count, model, status, files modified, lint violations, redundant reads
• --dry-run prints the comment without posting
• Idempotent: re-running updates the existing comment
• GitHub Actions workflow example in docs
• --platform gitlab posts to GitLab MR instead
• Works without hosted collector (replay link is optional)