Surveyor counts unresolved review threads inline, so a failed or partial read reports zero

[devantler]

🤖 Generated by the Agentic Engineer

Evidence

The surveyor counts pentad field (b), unresolved review threads, by running a paginated GraphQL query inline for each PR. That count fails silently. On 2026-08-04 a survey reported unresolved=0 for devantler-tech/monorepo#2436 while a Major CodeRabbit thread was open, and the PR was promoted and armed for auto-merge on that number (devantler-tech/monorepo#2670). A failed read, a first-page-only read and a genuine zero all print the same 0.

The consumer now has a tested helper for its own merge preflight (devantler-tech/monorepo#3474). It paginates, counts every author, checks fetched == totalCount, and prints UNKNOWN with exit 2 on any incomplete read. The surveyor cannot use it. The read-only command guard (forge-readonly-guard.sh) allows only forge commands and scripts shipped in the plugin's own scripts/ directory, so a consumer-repository script is refused:

deny: a read must begin with a forge command, not '.claude/scripts/pr-unresolved-threads.sh'

Audience and problem

This affects every deployment of the surveyor. Field (b) gates promotion and merge, and the one wrong value it can report is the dangerous one.

Expected behaviour

Field (b) comes from a deterministic, tested script shipped with the plugin, like classify-default-branch-ci-runs.sh, and the guard allows exactly that script.

Acceptance criteria

• A plugin-shipped script (for example scripts/count-unresolved-review-threads.sh <owner>/<repo> <pr>) prints unresolved=<n> total=<t> only on a complete read, and UNKNOWN <reason> with exit 2 on a failed, truncated or malformed one.
• Hermetic tests cover zero, unresolved, resolved-only and >100-thread pagination, plus ablations: without --paginate the result is caught as truncated, and without the truncation guard it reads zero.
• forge-readonly-guard.sh allows that script by its plugin path, the same way it allows the default-branch classifier, and still denies other local scripts.
• The surveyor agent requires the script for field (b), and reports unresolved=unknown on exit 2, never 0.

Rough size: S. The consumer-side reference implementation is .claude/scripts/pr-unresolved-threads.sh in devantler-tech/monorepo#3474.