fix(github-webhook): route PR reviews through invokability (BLO-21582)

[kkroo]

Thinking Path

• Paperclip is the control plane that invokes and coordinates AI-agent work.
• GitHub webhooks are the event-driven bridge that wakes agents immediately for PR review work.
• PR reviewer selection previously used a narrower idle/running status query, while ordinary heartbeat dispatch uses the canonical invokability and reporting-chain rules.
• When the sole reviewer was in recoverable error status, or was paused during a restart, sanctioned review requests were skipped before a durable wake existed.
• This pull request routes reviewer selection through evaluateAgentInvokability, distinguishes transient healthy-chain pauses from terminal invalid configuration, and persists bounded availability retries.
• The benefit is that recoverable reviewer outages no longer silently lose review requests, while terminated, pending-approval, unknown, and invalid-org-chain reviewers remain excluded.

Linked Issues or Issue Description

• Refs BLO-21995 - follow-up to the durable PR-review retry path, fixing the reviewer-availability selection gap found during its production verification.
• Refs BLO-21582 - root-cause issue documenting the status: error reviewer blackhole.
• Related BLO-20491 - review-pipeline observability and residual wake/output attribution.

What Changed

• Use the shared agent invokability contract for reviewer affinity and least-load selection; healthy active, idle, running, and error reviewers are eligible.
• Keep paused reviewers with a healthy reporting chain distinct from terminal invalid-org-chain or lifecycle states.
• Persist an initially unavailable reviewer wake in the existing durable retry row with a separate availability backoff ladder and six-hour wall-clock bound.
• Retire terminal no-reviewer outcomes as superseded, while re-arming explicit transient-unavailability failures.
• Harden replay parsing and preserve duplicate-delivery/advisory-lock coalescing behavior.
• Add regression coverage for error-status selection, paused recovery, concurrent duplicate marker requests, invalid paused chains, and the shared invokability contract.

Verification

• pnpm install --prod=false
• pnpm --filter @paperclipai/server typecheck
• git diff --check
• pnpm exec vitest run server/src/__tests__/agent-invokability.test.ts server/src/__tests__/github-webhook.test.ts --reporter=dot
• Result: 215/215 tests passed across both files.
• No UI changes; no screenshots required.
• Checked ROADMAP.md; this is a bug fix and does not duplicate roadmap work.
• Searched GitHub for related/duplicate PRs; the prior BLO-21995 implementation is merged as fix(github-webhook): durably retry PR-review wakes lost to lock contention (BLO-21995) #1155, with no open duplicate for this invokability follow-up.

Risks

• Reviewer routing now intentionally accepts error status when the shared invokability contract says the agent and reporting chain remain callable; adapter recovery behavior remains owned by heartbeat dispatch.
• Healthy paused reviewers may leave a durable retry row for up to six hours; the bounded ladder prevents unbounded polling and emits an alertable exhausted state.
• No schema migration is added; existing agent_wakeup_requests rows and statuses are reused.
• The production deployment must be verified before relying on this path for a fresh review request.

ROADMAP.md was checked; this is a narrowly scoped bug fix and does not overlap planned core work.

Model Used

• OpenAI GPT-5 coding agent (exact runtime model: GPT-5; tool use, shell execution, code review, and test execution).

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either linked existing issues with Fixes/Closes/Refs OR described the issue in-PR following the relevant issue template
• I have run tests locally and they pass
• I have added or updated tests where applicable
• If this change affects the UI, I have included before/after screenshots
• I have updated relevant documentation to reflect this change (behavior is documented in code; no external documentation applies)
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[allyblockcast]

🔗 Paperclip issue: BLO-21582
🔗 Paperclip issue: BLO-21995
🔗 Paperclip issue: BLO-20491

[allyblockcast]

🔗 Paperclip issue: BLO-21582
🔗 Paperclip issue: BLO-21995
🔗 Paperclip issue: BLO-20491

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: 9978664

Critical Issues (0)

Important Issues (0)

Suggestions (0)

Strengths

• Reviewer selection now uses the shared invokability contract while retaining explicit treatment for healthy paused reviewers versus invalid organization state.
• The availability retry is durable, bounded, and independently covered for recovery, long outages, malformed records, and duplicate marker deliveries.
• The PR-scoped advisory lock and enqueue coalescing path remain the single dispatch decision point.

Recommended Action

1. Merge when the remaining CI gates pass.