🌱 narrow the reviewer token back to pull_requests: read now that the audited relay works

[clubanderson]

Summary

#7472 gave the reviewer token tier pull_requests: write so an advisory reviewer could post its verdict. It merged before we established that hive already had a sanctioned route for this. Now that #7486 makes that route usable, the token grant should be narrowed back to pull_requests: read.

Why

Hive's pattern everywhere else is that the governor performs the write, not the agent: issue_request_watcher.go, pr_request_watcher.go, merge_request_watcher.go all take a request file from an agent and execute it with the App token. review_request_watcher.go is the review analogue, and its doc comment is explicit that this is the intended route:

An agent that wants to review a PR writes a request file here INSTEAD of running gh pr review from its own shell. The hive's watcher submits the review with the App token, so the review is authored by the App bot AND — unlike a direct agent-CLI review, which the hive never observes — it is recorded on the audit/activity trail.

With #7486 merged, an ADVISORY + converse: true reviewer can use that relay. The direct-token grant from #7472 is then redundant — and not neutral:

• Attribution. A relay review is authored by the App bot. A direct-token review is authored by the agent's own identity, outside the App's activity trail.
• Observability. The hive never sees a direct gh pr review. It is not on the audit trail, so it does not appear in activity counts or SLA accounting.
• Canary / exfiltration. The relay runs review bodies through scanCanaryText with the fail-closed contract added in kubestellar/hive#4960. The direct path skips it.
• Incentive. Leaving both routes open means the easier one wins, and the easier one is the one we cannot see.

Proposed change

• Revert the pull_requests: write grant in the reviewer case of pkg/github/app.go back to read.
• Keep the reviewer tier itself — it is still the right tier, and contents: read / metadata: read are correct.
• Keep pkg/agentmode.TokenTierForRole and its tests; the role plumbing is independent of the permission level.
• Confirm the reviewer's config carries converse: true before landing, so the relay route is live when the direct route closes.

Sequencing

Do not land this until a reviewer has actually posted through the relay on the projectbluefin spoke and it is observed on the audit trail. Narrowing the token first would leave the reviewer with no working route at all — which is the state #7485 described.

Verification note

The permission assertions from #7472 already exist in pkg/github/reviewer_tier_permissions_test.go and pin pull_requests presence, so this change is a one-line flip plus updating those expectations.

[Danathar]

Picked this up and stopped at the sequencing gate rather than opening a PR — recording the state so the next pass can act the moment the gate clears.

Gate status (2026-09-17):

• ✨ Let an advisory reviewer post the verdict it computes #7472 is merged (cf57dd3d3, now on v4): pkg/github/app.go case "reviewer" grants PullRequests: write (lines 324–361 on v4).
• 🐛 fix(agent): let converse-capable advisory agents review through the audited relay #7486 — the relay authorizer fix that makes the sanctioned route usable for ADVISORY + converse: true — is still open, no review yet.
• No relay-authored review has been observed on the projectbluefin spoke's audit trail, and cannot be until 🐛 fix(agent): let converse-capable advisory agents review through the audited relay #7486 ships there.

So narrowing now would close the direct route before the relay route exists, which is the #7485 state this issue says not to recreate.

When the gate clears, the change is exactly what the issue says: flip PullRequests: gh.Ptr("write") → gh.Ptr("read") in the reviewer case, rewrite the tier's doc comment (it currently argues for write), update the pull_requests expectation in pkg/github/reviewer_tier_permissions_test.go, and add a changelog fragment under changed-. pkg/agentmode.TokenTierForRole and its tests stay as they are.

Not opening a PR until #7486 is merged and a relay review is on the spoke's audit trail.

— hive: backend=claude model=claude-opus-5

[clubanderson]

Status check: still valid, and the case is now stronger.

Current state on v4: src/pkg/github/app.go:358 still grants the reviewer tier PullRequests: write. Not yet narrowed.

The relay is confirmed working end-to-end. Two reviews posted on projectbluefin, both authored by the App bot, both on the audit trail:

• fix: redirect Bazaar Zed installs projectbluefin/common#1011 -> pullrequestreview-5243703265
• docs(skills): add GPU vendor toolkit interface spec projectbluefin/common#971 -> pullrequestreview-5243735981

And pkg/review/prompts.go:83 instructs the relay exclusively:

Use hive-review, never gh pr review - it is submitted with the App token and recorded on the audit trail.

So the direct grant is unused on the posting path. Narrowing it should be behaviour-neutral.

One justification in the code comment has since expired. app.go defends PullRequests: write partly on routing:

It also allows requesting reviewers, so the reviewer can route a PR to the person who should look at it.

That is no longer how routing works. #7527 routes by writing a **HUMAN DECISION NEEDED** marker and mentioning a human in the review body, and #7536 adds an optional existing-label mark (review.human_decision_label) applied by the governor with the App token, not by the agent. Neither path needs the reviewer tier to hold PullRequests: write. When this is narrowed, that paragraph should be removed rather than carried forward.

Sequencing. The only reason not to do it immediately is blast radius: if any reviewer path still falls back to its own token, narrowing silently stops all review posting - which is currently the active lever for draining the projectbluefin queue. Suggest landing it once the current coverage work (#7533, #7536) has run a full cycle and the outcome ledger confirms reviews are still posting.