Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-14685-reviewer-autoscale.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The reviewer lane can scale with the PR backlog: `review.reviewers.autoscale` hands review and cadence kicks to between `min` and `max` replicas of the reviewer agent, stepping up on a sustained backlog or an over-age waiting PR and down after sustained idle, with cooldown, headroom, provider-budget and saturation guards ([#14685](https://github.com/hivecommons/hive/issues/14685)).
8 changes: 8 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -7346,6 +7346,9 @@ func runEvalCycle(
}
return ""
})
// Replicas the reviewer autoscaler has scaled in take no cadence kick
// either, or an idle reviewer-5 would still run a turn every interval.
agentsDue, agentsSkipped = withholdInactiveReviewerReplicas(agentsDue, agentsSkipped, cfg, &reviewerAutoscale)

// PROVIDER SPEND REBUFF (#4294). When the inference gateway is refusing on a
// money limit, every kick launched this cycle is a run that cannot buy a
Expand Down Expand Up @@ -7653,6 +7656,7 @@ func runEvalCycle(
gov.RecordKickFailure(msg.Agent, err, time.Now())
if k, ok := reviewKickByMessage[reviewKickKey(msg)]; ok {
logUndeliveredReviewKick(logger, dashSrv, k, err)
noteReviewerAutoscaleKickFailure(cfg, &reviewerAutoscale, k.Agent, err, time.Now())
}
},
onDelivered: func(msg scheduler.KickMessage) {
Expand Down Expand Up @@ -10762,7 +10766,11 @@ func planReviewDispatchWith(ctx context.Context, cfg *config.Config, actionable
DeltaRereview: cfg.Review.DeltaRereviewEnabled(),
DeltaTrivialLines: cfg.Review.EffectiveDeltaTrivialLines(),
DeltaMaxAge: cfg.Review.EffectiveDeltaMaxAge(),
ReplicaLimits: reviewerReplicaLimits(cfg, &reviewerAutoscale),
})
if cfg.Review.Reviewers.Autoscale.Enabled {
decideReviewerAutoscale(cfg, &reviewerAutoscale, plan, liveReviewerAutoscaleSignals(), logger)
}
recordReviewDeltaRestamps(plan, logger)
for _, k := range plan.ReviewKicks {
if k.BotAuthorRouted {
Expand Down
100 changes: 100 additions & 0 deletions src/cmd/hive/review_autoscale.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
package main

import (
"log/slog"
"strings"
"time"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/dashboard"
"github.com/hivecommons/hive/pkg/review"
)

// reviewerAutoscale is the reviewer lane's autoscaler (review.reviewers.
// autoscale, hivecommons/hive#14685): how many of the scaled agent's replicas
// the review swarm hands kicks to this cycle.
var reviewerAutoscale review.ReviewerAutoscaler

// reviewerReplicaLimits is DispatchOptions.ReplicaLimits for this cycle: the
// scaled agent capped at the autoscaler's active count, nil when autoscale is
// off so every declared replica takes work as before.
func reviewerReplicaLimits(cfg *config.Config, as *review.ReviewerAutoscaler) map[string]int {
if cfg == nil || !cfg.Review.Reviewers.Autoscale.Enabled {
return nil
}
ac := cfg.Review.Reviewers.Autoscale
return map[string]int{ac.EffectiveAgent(): as.Active(ac)}
}

// decideReviewerAutoscale feeds one planned cycle to the autoscaler and logs
// the step when it moves the active count. The new count applies from the
// next cycle's plan.
func decideReviewerAutoscale(cfg *config.Config, as *review.ReviewerAutoscaler, plan review.DispatchPlan, sig review.ReviewerAutoscaleSignals, logger *slog.Logger) review.ReviewerAutoscaleDecision {
if cfg == nil || !cfg.Review.Reviewers.Autoscale.Enabled {
return review.ReviewerAutoscaleDecision{}
}
ac := cfg.Review.Reviewers.Autoscale
sig.Waiting = plan.ReviewerStarved
if sig.Now.IsZero() {
sig.Now = time.Now().UTC()
}
d := as.Decide(ac, sig)
if d.Changed() && logger != nil {
logger.Info("reviewer autoscale: "+d.String(),
"agent", ac.EffectiveAgent(), "action", d.Action, "from", d.From, "to", d.To,
"backlog", d.Backlog, "oldest_wait", d.OldestWait.Round(time.Second).String(),
"min", ac.EffectiveMin(), "max", ac.EffectiveMax())
}
return d
}

// liveReviewerAutoscaleSignals are the guards read from the running hive:
// the provider spend latch and the pod's cgroup headroom.
func liveReviewerAutoscaleSignals() review.ReviewerAutoscaleSignals {
cause, _, _, _ := dashboard.InferenceBudgetExceeded()
return review.ReviewerAutoscaleSignals{
BudgetLatched: cause != "",
Headroom: dashboard.PodHeadroom,
}
}

// noteReviewerAutoscaleKickFailure records a review kick to one of the scaled
// agent's replicas that failed because the CLI never reached its input
// prompt: saturation, which holds scale-up for a cooldown.
func noteReviewerAutoscaleKickFailure(cfg *config.Config, as *review.ReviewerAutoscaler, agent string, err error, at time.Time) {
if cfg == nil || !cfg.Review.Reviewers.Autoscale.Enabled || !review.IsPromptNotReadyKickError(err) {
return
}
base := strings.TrimSpace(agent)
if ac, ok := cfg.Agents[base]; ok && ac.ReplicaOf != "" && !ac.IsReviewHead() {
base = ac.ReplicaOf
}
if base != cfg.Review.Reviewers.Autoscale.EffectiveAgent() {
return
}
as.NoteSaturation(at)
}

// withholdInactiveReviewerReplicas drops the cadence kicks of the scaled
// agent's replicas numbered above the autoscaler's active count, reporting
// each as skipped "(autoscale-inactive)". With autoscale off it returns its
// inputs unchanged.
func withholdInactiveReviewerReplicas(agentsDue, skipped []string, cfg *config.Config, as *review.ReviewerAutoscaler) ([]string, []string) {
limits := reviewerReplicaLimits(cfg, as)
if len(limits) == 0 {
return agentsDue, skipped
}
kept := make([]string, 0, len(agentsDue))
for _, key := range agentsDue {
name, _ := config.SplitCadenceTargetKey(key)
ac, ok := cfg.Agents[name]
if ok && ac.ReplicaOf != "" && !ac.IsReviewHead() {
if limit, scaled := limits[ac.ReplicaOf]; scaled && ac.ReplicaIndex > limit {
skipped = append(skipped, key+" (autoscale-inactive)")
continue
}
}
kept = append(kept, key)
}
return kept, skipped
}
107 changes: 107 additions & 0 deletions src/cmd/hive/review_autoscale_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
package main

import (
"errors"
"strings"
"testing"
"time"

"github.com/hivecommons/hive/pkg/config"
"github.com/hivecommons/hive/pkg/review"
)

// Wiring for review.reviewers.autoscale (hivecommons/hive#14685).

func autoscaleWiringConfig(enabled bool) *config.Config {
cfg := &config.Config{}
cfg.Agents = map[string]config.AgentConfig{
"reviewer": {Enabled: true, Replicas: 1},
"scanner": {Enabled: true, Replicas: 1},
}
cfg.Review.Reviewers.Autoscale = config.ReviewerAutoscaleConfig{Enabled: enabled, Min: 1, Max: 3, Cooldown: "1m"}
if err := cfg.ExpandAgentReplicas(); err != nil {
panic(err)
}
return cfg
}

func TestReviewerReplicaLimitsOffIsNil(t *testing.T) {
var as review.ReviewerAutoscaler
if got := reviewerReplicaLimits(autoscaleWiringConfig(false), &as); got != nil {
t.Fatalf("limits with autoscale off = %v, want nil", got)
}
if got := reviewerReplicaLimits(autoscaleWiringConfig(true), &as); got["reviewer"] != 1 || len(got) != 1 {
t.Fatalf("limits = %v, want reviewer:1", got)
}
}

// Inactive replicas get no cadence kick, are reported as skipped, and every
// other agent (and repo-scoped cadence key) passes through.
func TestWithholdInactiveReviewerReplicas(t *testing.T) {
cfg := autoscaleWiringConfig(true)
var as review.ReviewerAutoscaler
due := []string{"reviewer", "reviewer-2", config.CadenceTargetKey("reviewer-3", "acme/hive"), "scanner"}
kept, skipped := withholdInactiveReviewerReplicas(due, nil, cfg, &as)
if strings.Join(kept, ",") != "reviewer,scanner" {
t.Fatalf("kept = %v, want reviewer and scanner", kept)
}
if len(skipped) != 2 || !strings.HasSuffix(skipped[0], "(autoscale-inactive)") {
t.Fatalf("skipped = %v", skipped)
}

kept, skipped = withholdInactiveReviewerReplicas(due, nil, autoscaleWiringConfig(false), &as)
if len(kept) != len(due) || len(skipped) != 0 {
t.Fatalf("autoscale off: kept %v skipped %v, want everything kept", kept, skipped)
}
}

func TestDecideReviewerAutoscaleScalesFromPlanBacklog(t *testing.T) {
cfg := autoscaleWiringConfig(true)
var as review.ReviewerAutoscaler
plan := review.DispatchPlan{ReviewerStarved: []string{"a#1@x", "a#2@x", "a#3@x"}}
t0 := time.Date(2026, 10, 27, 20, 0, 0, 0, time.UTC)
decideReviewerAutoscale(cfg, &as, plan, review.ReviewerAutoscaleSignals{Now: t0}, nil)
d := decideReviewerAutoscale(cfg, &as, plan, review.ReviewerAutoscaleSignals{Now: t0.Add(time.Minute)}, nil)
if d.Action != review.AutoscaleUp || d.To != 2 {
t.Fatalf("decision = %+v, want up to 2", d)
}
if got := reviewerReplicaLimits(cfg, &as)["reviewer"]; got != 2 {
t.Fatalf("next cycle limit = %d, want 2", got)
}
if d := decideReviewerAutoscale(autoscaleWiringConfig(false), &as, plan, review.ReviewerAutoscaleSignals{Now: t0}, nil); d.Action != "" {
t.Fatalf("autoscale off decided %+v", d)
}
}

// Only a prompt-not-ready failure on the scaled agent's own replicas counts
// as saturation.
func TestNoteReviewerAutoscaleKickFailure(t *testing.T) {
cfg := autoscaleWiringConfig(true)
t0 := time.Date(2026, 10, 27, 20, 0, 0, 0, time.UTC)
busy := review.DispatchPlan{ReviewerStarved: []string{"a#1@x", "a#2@x", "a#3@x"}}
scaleUp := func(as *review.ReviewerAutoscaler) review.ReviewerAutoscaleDecision {
decideReviewerAutoscale(cfg, as, busy, review.ReviewerAutoscaleSignals{Now: t0.Add(10 * time.Second)}, nil)
return decideReviewerAutoscale(cfg, as, busy, review.ReviewerAutoscaleSignals{Now: t0.Add(20 * time.Second)}, nil)
}
promptErr := errors.New("agent reviewer-2 CLI did not reach input prompt")

var saturated review.ReviewerAutoscaler
noteReviewerAutoscaleKickFailure(cfg, &saturated, "reviewer-2", promptErr, t0)
if d := scaleUp(&saturated); d.Changed() {
t.Fatalf("scaled up right after saturation: %+v", d)
}

for name, tc := range map[string]struct {
agent string
err error
}{
"other agent": {"scanner", promptErr},
"other failure": {"reviewer-2", errors.New("tmux: no server running")},
} {
var as review.ReviewerAutoscaler
noteReviewerAutoscaleKickFailure(cfg, &as, tc.agent, tc.err, t0)
if d := scaleUp(&as); !d.Changed() {
t.Fatalf("%s: counted as saturation, decision %+v", name, d)
}
}
}
50 changes: 50 additions & 0 deletions src/docs/review-swarm.md
Original file line number Diff line number Diff line change
Expand Up @@ -332,6 +332,56 @@ Source: `ReviewCapable` in `src/pkg/review/dispatch.go`, which the dashboard
(`dashboardAgentReviewCapable` in `src/pkg/dashboard/status_builder.go`), the relay and
the merge-eligibility gate all call.

## Reviewer autoscaling (`review.reviewers.autoscale`)

A reviewer lane with a fixed `replicas` count becomes the bottleneck when the PR backlog
grows, even with CPU and memory to spare. `review.reviewers.autoscale` lets the planner
vary how many of one reviewer agent's replicas take review kicks, between `min` and `max`
([#14685](https://github.com/hivecommons/hive/issues/14685)).

```yaml
review:
reviewers:
autoscale:
enabled: true
agent: reviewer # base agent to scale (default "reviewer")
min: 2 # default 1
max: 5 # default and ceiling: 5 (MaxAgentReplicas)
target_backlog_per_reviewer: 2 # scale up above this many waiting PRs per active reviewer
scale_up_cycles: 2 # consecutive cycles of pressure before a step up
scale_down_cycles: 5 # consecutive idle cycles before a step down
cooldown: 5m # minimum time between two steps
max_wait: 30m # a PR waiting this long is pressure on its own
cpu_per_reviewer: 0.5 # headroom one more reviewer needs (cores)
mem_per_reviewer_mb: 1024 # headroom one more reviewer needs (MB)
```

- **Replicas.** Enabling it materializes the agent's replicas up to `max`
(`reviewer-2` … `reviewer-N`) through the same machinery as `agents.<name>.replicas`, so
token minting, tmux wiring, cadence keys and the dashboard treat them as ordinary
replicas. The declared `replicas` is never rewritten. Replicas numbered above the active
count take no review-swarm kick and no cadence kick (the eval log lists them under
`agents_skipped` as `autoscale-inactive`). Review heads are not scaled.
- **Backlog.** Each cycle the planner records the PR heads that needed a plain reviewer
and found every active one busy (`DispatchPlan.ReviewerStarved`); the autoscaler tracks
how long each has waited.
- **Scale up** when the backlog exceeds `target_backlog_per_reviewer` per active reviewer,
or the oldest waiting PR is older than `max_wait`, for `scale_up_cycles` consecutive
cycles. A step is held at `max`, inside `cooldown`, while the provider budget latch is
set, when the pod's cgroup headroom is below one reviewer's `cpu_per_reviewer` /
`mem_per_reviewer_mb`, and for one `cooldown` after a reviewer kick failed with
`did not reach input prompt` (saturation, not demand).
- **Scale down** when fewer PRs wait than there are active reviewers for
`scale_down_cycles` consecutive cycles. The highest-numbered replica stops receiving new
work; a turn it already started is never interrupted and its verdict is recorded as
usual, so it drains rather than dies.
- **Observability.** Every step logs one line, e.g.
`reviewer autoscale: 2→3 reason=backlog=7 oldest=41m0s`, with the agent, min and max.
The active count is held in memory: after a restart the lane starts again at `min`.

Source: `ReviewerAutoscaler.Decide` in `src/pkg/review/autoscale.go`; wiring in
`src/cmd/hive/review_autoscale.go`.

## Review heads: several models per perspective

`agents.<name>.review_heads` gives one base reviewer several model "heads" ([#13542](https://github.com/hivecommons/hive/issues/13542)). Each head is materialized like `replicas`: `<base>-<alias>-<n>` copies the base agent with only `backend` and `model` replaced, is stripped on save, and is provisioned at boot by the entrypoint. `alias` defaults to a slug of `<backend>-<model>` (without repeating the backend when the model already starts with it). The agent's Unix user and token group are `hive-<name>`, and group names are limited to 32 characters, so `<base>-<alias>-<n>` may be at most 27 characters; a longer name fails config load, so set a shorter `alias`.
Expand Down
6 changes: 6 additions & 0 deletions src/hive.yaml.example
Original file line number Diff line number Diff line change
Expand Up @@ -834,6 +834,12 @@ governor:
# # shadow.review_gate.would_have_held on the evidence bundle (#12104)
# fan_out: false
# max_parallel_reviews: 5
# reviewers:
# autoscale: # scale the reviewer lane with the PR backlog (#14685); see docs/review-swarm.md
# enabled: false
# agent: reviewer
# min: 1
# max: 5
# reviewer_agents: [] # optional explicit list; otherwise agents with review role/keywords are used
# combined_perspectives: true # RECOMMENDED (#12126): one session + one comment covering every
# # perspective; shared review boilerplate is sent once instead of once
Expand Down
11 changes: 9 additions & 2 deletions src/pkg/config/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -6501,6 +6501,7 @@ func (c *Config) ExpandAgentReplicas() error {
if replicas < 1 || replicas > MaxAgentReplicas {
return fmt.Errorf("agent %s: replicas must be between 1 and %d", name, MaxAgentReplicas)
}
replicas = c.Review.Reviewers.Autoscale.expandedReplicas(name, replicas)
for i := 2; i <= replicas; i++ {
derived := replicaAgentName(name, i)
if existing, ok := baseAgents[derived]; ok && existing.ReplicaOf == "" {
Expand All @@ -6522,8 +6523,11 @@ func (c *Config) ExpandAgentReplicas() error {
}
}
for name, agent := range baseAgents {
replicas := normalizeReplicaCount(agent.Replicas)
agent.Replicas = replicas
agent.Replicas = normalizeReplicaCount(agent.Replicas)
// The autoscaler's max materializes the dynamic replicas
// (reviewer-3…reviewer-N) through this same path, without rewriting
// the declared replicas a save would persist.
replicas := c.Review.Reviewers.Autoscale.expandedReplicas(name, agent.Replicas)
agent.ReplicaOf = ""
agent.ReplicaIndex = 1
agent.ReplicaCount = replicas
Expand Down Expand Up @@ -7502,6 +7506,9 @@ type ReviewConfig struct {
// Backlog is where findings below the blocking line are filed
// (hivecommons/hive#11088). See ReviewBacklogConfig.
Backlog ReviewBacklogConfig `yaml:"backlog,omitempty" json:"backlog,omitempty"`
// Reviewers tunes the reviewer lane itself; today only its autoscaler
// (hivecommons/hive#14685). See ReviewReviewersConfig.
Reviewers ReviewReviewersConfig `yaml:"reviewers,omitempty" json:"reviewers,omitempty"`
}

// PlanMatchConfig is the switch for the plan_match review perspective
Expand Down
Loading
Loading