Skip to content

[RFC] [v6] Contributor relays as reviewers: let a trusted contributor's agent take a review perspective #18068

Closed as not planned

Description

@Danathar

Hold - design discussion, not a task. This is a proposal for maintainer discussion. Please do not implement it, decompose it into sub-issues, or relay it to contributors until the design is settled.

Status: Proposal
Target: Hive v6
Scope: Contributor relay (a new review task), review dispatch, verdict delivery, the reviewer grant, dashboard and MCP controls, docs
Initially out of scope: a contributor review standing as the only review of a pull request while a resident reviewer is available (stand-in mode, below, covers the case where none is); contributor_first on the reviewer lane; a reviewer-specific model floor; sharing tokens or credentials in any form; changes to GitHub branch protection or required approvals; repairing pull requests after a review (that agent stays resident)
Related design: RFC #7629: Standby contributors, behind a model floor (implemented; its capability tiers and per-lane floor exist today) · RFC #6825: Capability-aware contributor task assignment (closed) · PR #16518 (contributor-first lanes) · #18069 (contributor-only lanes) · #18238 (contributor agents can read the contributor's personal token)


This is a feature proposal, not a bug report. Intended outcome: a hive owner can let a trusted contributor's agent review pull requests alongside the hive's own reviewer, so review stops being the bottleneck, and can also stand in for the hive's reviewer when none is available. A contributor review becomes the whole review only when the owner has turned stand-in mode on and no resident reviewer is available.

The hive-specific terms used below (hub, resident agent, relay, perspective, verdict, and so on) are defined in the glossary at the end. All code references are to v6 at 15a6de7fc (v6.30.1) and are collected in the appendix.

What an operator sees today

On the projectbluefin hive, one reviewer replica served 20 repositories. Between 11:36 AM and 12:36 PM EST on 2026-11-12, 25 different pull requests were logged waiting for review with the reason no-free-reviewer, 24 of them in a single dispatch cycle. Scaling the reviewer up means more replicas, and each replica spends the hive's model tokens.

Contributors already add authoring capacity, but every pull request they open joins the same review queue. Adding contributors adds review work without adding review capacity.

The one role a contributor cannot usefully take is reviewer. This is not a deliberate ban. The only role the code refuses by name is supervisor; other roles are refused only when they are unknown, disabled or not allow-listed. It is a gap: the review pipeline was built around resident agents end to end, so there is no path for a contributor to receive a review or hand a verdict back. Three things stand in the way:

  1. Contributors are never offered anyone else's pull request. The hub hands contributors two kinds of task: issue, offered when the issue matches the relay's role (the issue's lane, the role's keywords, or the role name; scanner matches every issue), and fix-pr, which returns a contributor's own pull request to them for fixing. If an operator allow-listed reviewer today, a relay acting as reviewer would be offered matching issues and never a pull request to review. (The relay also runs a local review cycle, but it only answers review comments on the pull requests that contributor filed. The hub never assigns it.)
  2. The review dispatcher only knows resident agents. The planner that decides which agent reviews which pull request builds its list of reviewers from the enabled lanes in hive.yaml. A connected relay is not in that list.
  3. The verdict travels through a path inside the hive. A resident reviewer delivers its verdict with the hive-review command, which writes a request file into the review-request watcher's directory inside the hive's container. A relay runs on another machine and has no such path. The relay protocol has a task-outcome verdict field (for example, "no work needed" or "blocked"), but no message for a review verdict.

A related bug can be fixed independently. The owner's Acting as menu lists only the three default roles plus the privileged roles that need a grant, and the owner's assign action refuses any other role with HTTP 400. A role an operator allow-lists outside those sets therefore cannot be assigned from the contributor card, even though the hub accepts it from a trusted relay that asks for it by name. The Settings check-box list for delegatable roles is hard-coded the same way.

Proposal

A contributor relay may take one review perspective on a pull request, exactly as a resident reviewer replica would, under the owner's rules about who may do it. The hive keeps posting every review itself, so attribution, audit and routing do not change.

Where this leads. This is the first step of a longer sequence set out in #18069 (contributor-only lanes): a hive in which every role, review included, is performed by contributors and no resident agent runs. The defaults below (one contributor perspective per pull request, at least one resident perspective) are the right ones while a resident reviewer exists. They are the defaults #18069 revisits, deliberately, when it does not. Stand-in mode (below) is the narrow version of that step: contributors carry review only while the hive's own reviewer is unavailable.

The mechanics:

  1. A review task for relays. A new task kind, review-pr, carrying the repository, pull request number, head commit, the perspective to take and the review guidance. A relay says in its handshake whether it can run review tasks, the same way it already advertises fix_pr_interrupt_v1; the hub never sends a review task to a relay that cannot run one.
  2. Relays as review capacity. A connected relay acting as reviewer appears in the dispatcher's reviewer list next to the resident replicas and is counted the same way: one review in flight at a time, and a pending review that produces no verdict within review.pending_ttl (45 minutes by default) expires and is re-dispatched.
  3. The verdict comes back over the relay connection. The relay's completion message carries the comment and the verdict record. The hub validates the record with the same check the watcher applies to resident verdicts and posts the review through the existing review-request watcher, so it goes out under the hive's App identity, lands on the audit trail, and is routed like any other verdict. The hub always posts a contributor review as a comment (see risk 6). The posted comment names the contributor and the model the relay reported.
  4. Gates. reviewer becomes a privileged delegatable role: the hive must allow-list it, the contributor must hold the trusted tier, and the owner must grant it on that contributor's card. The grant is the owner's trust decision. There is no separate reviewer model floor (see risk 1).
  5. Stand-in mode. An owner can turn on review.contributor_perspectives.stand_in_when_no_resident. While it is on and no resident reviewer is available (every review-capable lane is disabled, paused, or held by the governor, for example for provider quota), one contributor review per head may stand alone, and its verdict counts exactly like a resident reviewer's, including an approve that makes the pull request merge-eligible. As soon as a resident reviewer is available again, new heads go back to the normal defaults; verdicts already recorded stay as they are. Stand-in mode is off by default.
  6. Controls and docs. The Settings page gains reviewer in the delegatable-roles list and the stand-in switch; the contributor card gains the grant; the review queue shows which perspective a contributor holds. Each admin MCP write for these settings ships with its dashboard control. The contributor-trust-and-roles doc and the contributor-relay doc describe the new role.

Risks and mitigations

Review is the gate. Each mitigation below exists so that opening the gate to contributors cannot make it weaker.

1. A weak model becomes the gate.
A contributor can run anything from a frontier model to a small local one.
Mitigation: the owner decides who may review, and can ask what model a contributor runs before granting the role. Three safeguards back that up. A resident perspective always reviews the same head, so a weak contributor review cannot clear a pull request on its own (risk 4). The hive-wide contributor floor still applies when the relay connects (hub.contribute_allow_models, hub.contribute_min_reasoning_effort and the two reject-unknown switches). And the model the relay reported is recorded with every verdict, so a weak model shows up and the grant can be revoked.
In stand-in mode there is no resident perspective behind the contributor; turning stand-in mode on is the owner deciding that the granted contributors are trusted to be the review.
This design adds no reviewer-specific floor. If one proves necessary, it should reuse the capability tiers #7629 already built (hub.standby_model_tiers and the per-lane standby.min_model_capability) rather than add a new floor.

2. The relay misreports its model.
A relay reports its backend, model and reasoning effort itself. The hub cannot verify them.
Mitigation: the trusted tier plus an explicit per-contributor grant (the owner knows who they are granting), and the model recorded on every verdict. The hive already tracks reviewer accuracy by reviewer model and author model family. A per-contributor view is added in step 3, so a bad grant shows up in numbers and gets revoked.

3. Someone reviews their own work, or a model reviews its own output.
Mitigation: a relay is never offered a pull request its contributor authored. It is also not offered a pull request whose recorded author model matches the model the relay reported (or the same model family, when exclude_author_family is set). Both rules are new. Today review_models does not refuse a reviewer: it chooses which model a resident reviewer runs, and by default (fallback: pinned) falls back to the reviewer's own model even when it matches the author's. A pull request written by a person carries no author model, so only the authorship rule applies to it.

4. A contributor review quietly becomes the whole review.
On a hive with a fan-out of one, a single contributor perspective would be the entire review.
Mitigation: by default, every pull request head keeps at least one resident perspective, and at most one contributor perspective. Both are settings the owner can relax later, deliberately; the default never asks them to.
The one built-in exception is stand-in mode: when the owner has turned it on and no resident reviewer is available, a single contributor review is the whole review. The owner opts in, the mode switches itself off as soon as a resident reviewer returns, and the posted review says it was a stand-in review.

5. Contributor-first silences the resident reviewer.
The contributor_first setting (from PR #16518) withholds a resident agent's kicks while a relay is connected and acting as its role. Kicks resume only after contributor_first_grace (10 minutes by default) with no healthy covering relay. The review dispatcher's kicks pass through that same gate, so turning contributor_first on for reviewer would stop the resident reviewer reviewing at all while a relay is connected, with nothing checking that the relay is keeping up.
Mitigation: the loader and the Settings toggle refuse contributor_first on the reviewer lane in this design, with a message saying why. Stand-in mode is the supported way to let contributors cover review, and it cannot silence a working resident reviewer, because it applies only while none is available. Lifting that refusal is a separate decision after step 3 below.

6. A contributor review acts with the hive's authority.
The hub posts every contributor review under the App identity, with a footer naming the contributor. If relays posted from their own shells instead, the hive would never see the review. Resident agents are told never to do that, and are prevented only where write_surface.enforce lists their lane.
Posting under the App identity has two consequences that need guarding:

  • Approvals. Today the watcher downgrades an approve or request-changes to a comment only on pull requests the hive did not open. On the hive's own pull requests, a verdict posted as the App can be a real approval.
  • Text the hive acts on. The hive reads an App-posted comment shaped /approve … Posted by @X from the Hive dashboard as X's approval (sentinel release and the contributor workflow fence). It also reads instructions from the review body: <!-- hive-redundant-of: #N --> feeds the already-landed close, and a needs-decision marker line, the decision question and a decision-risk marker route the pull request to a human. Prow, per the hive's own runbook, processes /lgtm and /approve posted by the App and refuses them only because the App is not a collaborator or in OWNERS.

Mitigation: the hub always posts a contributor verdict as a comment, whatever the pull request. Before posting, it neutralises every slash-command line, the dashboard-approval shape and every hive marker in the contributor's text. A contributor asking for a human decision says so in the structured verdict (requires_human), not in the body. The rule that hive reviews are comment-only (never approve or request changes; a human decides those) then holds for contributor reviews on every pull request, and GitHub's required-approval protection is untouched.

7. A relay disconnects, times out, or returns a malformed verdict.
Mitigation: the same pending_ttl expiry and re-dispatch as resident reviews. A malformed verdict is refused and nothing is posted, as the watcher does today. It is never counted as a completed review and never defaults to "no findings".
One addition is needed. Today a head whose reviews expire review.max_redispatch times (3 by default) is held for a human as review-dispatch-exhausted, so a relay that accepts reviews and goes silent could push heads into that hold. In this design, an expired contributor review is re-dispatched to a resident replica and does not count toward max_redispatch. In stand-in mode, with no resident replica to fall back to, it goes to another eligible contributor and does count, so a head that no reviewer can finish still reaches review-dispatch-exhausted and a person. All of this is new behaviour.

8. A high-volume contributor floods the review queue, or a revoked one keeps going.
Mitigation: review tasks count against the contributor's tier limits (max_per_hour, max_per_day, max_concurrent) like any other task. Revoking the grant is pushed to the contributor's live connection and re-checked on every task request, so no new review is offered. Revoking the contributor disconnects them immediately. A review already in flight runs to its time limit or its verdict.

9. Private repositories: the contributor sees the diff.
Mitigation: grant review only to people you would give read access to, and the grant control says so. (For standby work, #7629 instead added a switch, hub.standby_allow_private_repos, that is off by default. See the open questions.)

10. A pull request can try to steer the reviewer (prompt injection).
Reviewing means the contributor's agent reads text that pull request authors wrote, and a hostile pull request can try to steer it.
Mitigation: as with private repositories, the operator decides whom to trust with review, and the contributor decides what their own agent may touch. The hive's side is covered elsewhere: the hub posts every review as a comment and neutralises commands and markers in it (risk 6), and, outside stand-in mode, a resident reviewer always reviews the same head (risk 4). One rule goes into the review guidance: read the pull request, never build, test or install anything from it. Separately, contributor agents can currently read the contributor's personal GitHub token; that affects every contributor task, not only review, and is tracked in #18238.

Proposed configuration and flow

Owner side, in hive.yaml or Settings:

hub:
  contribute_delegatable_roles: [scanner, quality, outreach, reviewer]   # existing list; reviewer is new here
review:
  contributor_perspectives:            # new
    require_resident_perspective: true # a contributor review never stands alone (default)
    max_per_head: 1                    # at most one contributor perspective per pull request head (default)
    stand_in_when_no_resident: false   # when on and no resident reviewer is available, one contributor review may stand alone (default off)

plus, on the contributor's card, the owner grants reviewer the same way they grant ci-maintainer today. The grant control notes that reviewers see the diff of every pull request they are offered.

Contributor side: nothing new to install beyond a relay release that understands the review task. The contributor sets their relay to act as reviewer (or the owner assigns it from the card).

Hub side: each review cycle, the planner considers connected relays acting as reviewer next to the resident replicas. It applies the authorship and author-model rules and the rate limits, and hands out at most one contributor perspective per head while always leaving a resident one, except in stand-in mode while no resident reviewer is available.

What the owner sees: the review queue shows a contributor's login against the perspective they hold; the Contribute page shows review tasks on the contributor's card; the hive log says when a relay was refused a review and why (authored the PR, author model excluded, rate limited).

Rollout

Each step is its own pull request, and each is useful on its own.

  1. Fix the role lists. Build the Acting-as menu, the owner's assign action and the Settings check-box list from the allow-list instead of a hard-coded set. Independent of everything below.
  2. Protocol and relay. The review-pr task kind, the capability flag in the handshake, the verdict carried in the completion message, and the hub posting it through the watcher as a comment, with commands and markers neutralised. Nothing is dispatched yet; this step can be exercised with an owner-triggered review on one pull request.
  3. Dispatch and controls. reviewer added to the privileged grant table; relays acting as reviewer become review capacity; the authorship and author-model rules; the resident-perspective and one-per-head defaults; stand-in mode; expired contributor reviews not counting toward max_redispatch; the contributor_first refusal on reviewer; the dashboard and MCP controls; the docs.
  4. Outcomes. Per-contributor reviewer accuracy on the dashboard, and an automatic suspension of the grant after repeated bad outcomes (closed-unmerged after a clean verdict, or a verdict a human overturned), cleared by the owner. Standby already has a suspension rule of this shape for donated configurations; this step should follow it. The step-2 refusals (sole contributor perspective, contributor_first on reviewer) should be revisited only after this step exists.

Open questions

  • Identity of the posted review. This proposal posts under the hive's App identity with the contributor named in a footer, so routing and audit are unchanged. The alternative, posting from the contributor's own account, would make the review an outside comment to the merge pipeline and lose the audit trail. Is there a case for the alternative?
  • trusted or contributor tier? The proposal says trusted plus a grant, the same class as ci-maintainer, because the grant is the owner's trust decision. A grant alone on the contributor tier would widen the pool at the cost of letting auto-promoted accounts review.
  • Private repositories. Is the grant enough, or should review mirror standby's standby_allow_private_repos switch, off by default?
  • Hosted hubs. The new keys need the usual Settings-parity handling (TestSettingsDialogReferencesEveryHiveYAMLLeaf and its allowlist) so hosted spokes can set them without a hub operator.

Glossary

  • Hub — the hive's server process. It talks to the relays, runs the dashboard, and decides who gets what work.
  • Resident agent — an agent the hive runs itself, in its own container, configured as a lane in hive.yaml (scanner, reviewer, and so on). A kick is the prompt the hub sends a resident agent to start a round of work.
  • Contributor relay — a program a contributor runs on their own machine. It connects to the hub, asks for work, runs the contributor's own AI agent on it, and reports back. The contributor pays for the model and pushes and opens pull requests under their own GitHub identity. For each task the hub also issues a short-lived App token scoped to the task's repository.
  • Trust tier — the hub's rank for a contributor: newcomer and advisor (lowest), contributor (reached automatically after 5 verified pull-request tasks), then trusted and merger, which an owner grants by hand. revoked removes access and disconnects the contributor.
  • Acting as — a contributor relay can take on a resident agent's role: scanner, quality and outreach by default, and the privileged roles ci-maintainer, sec-check and architect, which need an owner's grant on the contributor's card. The relay then receives that role's guidance with each task.
  • Perspective — the hive reviews each pull request from several angles, each as a separate agent run. A pull request's review is complete when its perspectives have reported. "Fan-out" is how many perspectives a pull request gets. The head is the pull request's latest commit; a new head means a new review, unless the new head is the same patch, in which case a review in flight carries over.
  • Verdict — the structured record a reviewer hands back (approve, changes_requested, requires_human or reject) together with the comment a person reads. The hive routes on the verdict: hold for a human, send to the fixer, clear for merge.
  • Review-request watcher — the hive's reviewers do not post reviews from their own shells. The agent writes the comment and verdict to a request file; the hive's watcher validates it, posts the review with the hive's GitHub App identity and records it on the audit trail.
  • Model record — the reviewer model and author model stored with each verdict. The hive uses it to track how accurate reviews are by model.
  • Admin MCP — the hive's administration interface for an operator's own AI assistant. Every admin MCP write ships with a matching dashboard control.

For implementers: where this lives in the code

All references are to v6 at 15a6de7fc (v6.30.1).

  • Delegatable-role allow-list (defaults always merged in, supervisor skipped): src/pkg/config/hub_config.go:335, :608-627
  • Role gate: privileged grant table src/pkg/dashboard/contribute_agent_roles.go:20-24; tier ranks :26-32; roleClaimAllowed :63-103 (unlisted roles default to trusted, :92-95); role match for issues issueMatchesAgentRole :157-183
  • Task kinds the hub assigns: issue at src/pkg/dashboard/contribute_select.go:1523; fix-pr at src/pkg/dashboard/contribute_fixqueue.go:40; handshake capability precedent fix_pr_interrupt_v1 at :34
  • The relay's local review cycle (own pull requests only): bin/contributor-relay.js:8113, :8248-8277, :8310-8335
  • Task-outcome verdict field in the relay protocol: src/pkg/dashboard/contribute_ws.go:787-817
  • Role-list bug (step 0): menu src/pkg/dashboard/api_contribute.go:1011-1034; assign refusal src/pkg/dashboard/contribute_admin.go:294-303; grant refusal :211-215; Settings list src/pkg/dashboard/static-src/js/config-hub.js:24
  • Hive-wide contributor floor: keys src/pkg/config/hub_config.go:199-212; checked at connect src/pkg/dashboard/contribute_ws.go:2997-3021; self-reported backend and model :3041-3046
  • Standby capability tiers and per-lane floor ([RFC] [v6] Standby contributors: a lane paused for budget hands its queue to volunteers, behind a model floor #7629): src/pkg/config/hub_config.go:351; src/crux/config/standby.go; suspension rule src/pkg/standby/suspend.go; private-repo switch src/pkg/config/hub_config.go:368
  • Tier limits: keys src/pkg/config/hub_config.go:673-675, enforced src/pkg/dashboard/contribute_select.go:189-204; grant push to live connections src/pkg/dashboard/contribute_admin.go:228-231; revoked disconnect :173-175; auto-promotion threshold src/pkg/dashboard/api_contribute.go:26
  • Reviewer pool built from resident lanes: src/cmd/hive/main_sweeps.go:2691-2696; same-patch carry-over :2687-2690; the waiting log line :2783; reason code src/pkg/review/dispatch.go:624; reviewer eligibility :2118-2127
  • Pending expiry and re-dispatch cap: src/pkg/review/dispatch.go:28-47
  • Verdict values: src/pkg/review/review.go:52-62; validation and body markers src/pkg/github/review_verdict_relay.go:72-86, :357-369
  • Verdict path and the comment-only prompt rule: src/pkg/review/prompts_publish.go:38-42; the watcher src/pkg/github/review_request_watcher.go:22-28; comment-only downgrade for pull requests the hive did not open :459-465
  • App-posted approvals the hive trusts: shape src/pkg/github/pr_decision_operator.go:257, :296-299; sentinel release src/pkg/github/sentinel_clearance.go:274-279; workflow fence src/pkg/github/automerge/automerge_contributor_workflow_approval.go:337; Prow handling src/docs/fork-pr-presubmit-stall-runbook.md:21
  • Direct-write enforcement per lane: src/crux/proxy/write_surface_enforce.go:8-16
  • Review model selection and its fallback: src/pkg/config/review_config.go:47-82; keys src/crux/config/agent_runtime.go:296-312
  • Reviewer accuracy grouping: src/pkg/review/accuracy.go:22-46
  • Review-dispatch kicks pass the governor's event-kick gate, which honours contributor-first coverage: src/cmd/hive/main_eval_cycle.go:1131-1139, src/pkg/governor/governor.go:1298-1302; grace default src/docs/agent-configuration.md:1521

Activity

  1. added
    help wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.
    EpicEpic tracking issue
    on Nov 13, 2026
  2. added
    kind/designCreated by Hive for agent-filed issue provenance
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 13, 2026
  3. changed the title [-][RFC] [v6] Contributor relays as reviewers: let a trusted contributor's agent take a review perspective, behind a model floor[/-] [+][RFC] [v6] Contributor relays as reviewers: let a trusted contributor's agent take a review perspective[/+] on Nov 14, 2026
  4. Danathar commented on Nov 15, 2026

    @Danathar
    ContributorAuthor

    issue too complex at this time

  5. removed
    stage/018-open-for-discussionOpen for discussion: proposal / design issue with no live claim; claimable, no agent work queued
    on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    EpicEpic tracking issuearchitecture discussionArchitecture discussion neededhelp wantedDenotes an issue that needs help from a contributor. Must meet "help wanted" guidelines.kind/designCreated by Hive for agent-filed issue provenance

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions