Governor

The governor is hive’s scheduler. It watches the GitHub work queue and decides, on a fixed interval, which agents to kick and how often — running agents harder when there is more work and easing off when the queue is quiet.

Agents do not schedule themselves. Every enabled agent is driven by the governor: on each evaluation cycle the governor measures the queue, picks a mode, and kicks each agent on the cadence that mode assigns it. This page is the full reference. For the agent-side view — cadence syntax in an agent’s own config — see Agent Configuration.

The evaluation cycle

Once per eval_interval_s (default 300 seconds), the governor:

1. Enumerates actionable GitHub work across project.repos — open issues, open PRs, held items, and SLA violations.
2. Refreshes the token budget from lifetime usage and fires any budget alerts.
3. Computes a mode from the queue depth — actionable issues plus open PRs.
4. For each enabled, non-on_demand agent, checks whether its per-mode cadence has elapsed since its last kick, and kicks it if so.

The cycle runs continuously as one of the container’s processes. Changing eval_interval_s at runtime (including via an ACMM pack apply) takes effect on the next tick — the ticker resets itself. The valid range is 10–86400 seconds.

Note: mode is driven by actionable issues + open PRs summed across project.repos. Held items and SLA violations are recorded and shown on the dashboard, but they do not change the mode — held items are waiting on a human by definition, so faster kicks cannot move them.

Modes and thresholds

The governor has four modes. Queue depth (actionable issues + open PRs) selects the highest mode whose threshold it exceeds:

The defaults are per-repo base values multiplied by the number of repos in project.repos (governor.threshold_scaling: linear | sqrt | none, default linear), so a 3-repo hive surges at 60 and “surge” means the same thing at any hive size. A threshold you set yourself is used verbatim and never scaled. ACMM packs ship their own ladders (L3: 15/10/3; L4–L6: 10/5/2). Full details: Governor mode thresholds and repo-count scaling.

Thresholds are overridable per mode. A threshold left unset (or set to 0) falls back to its built-in default, so an unset value never accidentally makes the queue surge:

governor:
  eval_interval_s: 300
  modes:
    busy:
      threshold: 16        # queue depth that activates this mode
      supervisor: 5m       # per-agent kick interval in this mode
      scanner: 15m
      ci-maintainer: 1h
      architect: pause     # suspend kicks for this agent in this mode

Per-mode, per-agent cadences

Inside each mode block, every entry other than threshold is a cadence for one agent: agent-name: duration. The duration is anything Go’s duration parser accepts — 5m, 30m, 2h, 4h.

• An agent listed under a mode is kicked on that interval while the hive is in that mode.
• An agent with no entry for the current mode is not kicked in that mode.
• Cadences are independent per mode, so an agent can be busy in surge and slow in idle.

An agent is due for a kick when the time since its last kick is at least its cadence interval. Last-kick times are persisted (in /data/hive-state.json) and honored across container/pod restarts, so a Deployment roll does not re-kick every agent at boot (#3817) — only agents whose cadence has actually elapsed are kicked on the first eval. A fresh install with no persisted state still kicks every eligible agent once so the hive doesn’t idle waiting out a full cadence.

Pausing an agent in a mode

The value pause (or paused) suspends kicks for that agent in that mode only:

governor:
  modes:
    surge:
      architect: pause     # don't kick architect while the queue is deep

Note: pause here only stops governor kicks. It is not a process pause and it does not disable the agent — the agent stays running and can still be triggered by other means. To keep an agent configured but off entirely, use enabled: false in the agent’s config.

On-demand agents

An agent with on_demand: true is skipped by the governor timer completely. It runs only when something triggers it explicitly — a manual kick from the dashboard or hivectl, or a workflow such as inception driving the brainstorm agent. On-demand agents never appear in a mode’s cadence list. (kick is the only supported channels: type; the former webhook/schedule/bead trigger types were removed in hive#5591 and are now rejected by config validation.)

The budget system

The governor enforces a rolling token budget so a hive cannot run up unbounded API cost. It is off by default.

governor:
  budget:
    total_tokens: 50000000   # 0 (the default) disables budgeting entirely
    period_days: 7
    critical_pct: 90

• Window. Spend accrues over a rolling 7-day window. When the window rolls over, spend re-baselines and the one-shot alerts reset.
• Warn. At 90% of the limit the governor emits a one-time warning for the window.
• Exhaustion. At 100%, kicks are suppressed hive-wide until the window rolls over — the queue keeps filling, but agents stop being kicked.

Two escape hatches keep critical agents running under exhaustion:

• Ignored agents — a per-agent exemption. Exempt agents keep getting kicked even when the budget is exhausted.
• Ignore-all — a global toggle that opens the kick gate for everyone while keeping the limit, window, and alerts intact (useful for a temporary override without discarding budget tracking).

The budget also interacts with model selection: for an unpinned agent, the governor may auto-select a cheaper model as spend grows. Pin the model to opt out — see model pinning.

ACMM pack integration

You rarely hand-write the governor: block. The six ACMM packs ship governor tuning alongside their agent rosters, and the tuning tightens as the level rises:

Applying a level reconciles the governor config: a fresh apply or level change writes the pack’s eval_interval_s, thresholds, and cadences; a merge onto an existing roster fills only the gaps, preserving your customizations. See the ACMM Policy Matrix for the full per-level cadence table and the L5 worked example.

Tuning guidance

• Keep stale_timeout above the longest cadence. An agent kicked every 4h with a 30-minute stale timeout looks dead between kicks. The shipped packs use “longest cadence × 2.”
• Match cadence to repo velocity. A hot repo may want scanner: 15m; a quiet one 4h.
• Pause the noisy agent at depth. If an agent adds churn exactly when the queue is deep, pause it in surge and let the workers drain the backlog.
• Adjust thresholds, not just cadences. Lower the surge threshold to reach maximum cadence sooner on a busy project; raise it to hold steady longer.

See also

• Agent Configuration — the agent-side config, including the cadence and kick-template fields the governor drives.
• ACMM Policy Matrix — per-level, per-agent policy and cadence tables.
• Variable Substitution — how kick prompts are built each cycle.
• Architecture — where the governor sits among the container’s processes.
• Troubleshooting — stuck sessions and agents that look dead between kicks.