diff --git a/changelog.d/added-hive-dashboard-help-guides.md b/changelog.d/added-hive-dashboard-help-guides.md new file mode 100644 index 0000000..feb8a18 --- /dev/null +++ b/changelog.d/added-hive-dashboard-help-guides.md @@ -0,0 +1 @@ +- Publish the Hive dashboard UI map and the guides linked from dashboard settings, including hub onboarding, deployment, and review evidence. diff --git a/docs/content/hive/advisory.md b/docs/content/hive/advisory.md new file mode 100644 index 0000000..3b4d5a6 --- /dev/null +++ b/docs/content/hive/advisory.md @@ -0,0 +1,558 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md) during the docs build. Edit the canonical source in the Hive repository. + +# Advisory digest + +Advisory agents (scanner, ci-maintainer, reviewer, and friends) file their +findings as **advisory beads**. Once per governor eval cycle the hive rolls the +open advisory beads of every agent into a single **advisory digest** and posts it +as a pinned comment on the advisory issue of the primary repo, rewriting the same +comment each cycle so a repo owner has exactly one place to look. + +A hive that manages several repos still keeps exactly **one** advisory report, +in `project.primary_repo` (or the first repo in `project.repos` when no primary +is set). By default no other repo in `project.repos` gets an advisory issue or a +digest comment. The report is found by its title and the `hive/advisory` label +before anything is created, so a restart reuses the open report instead of +filing a new one ([#18568](https://github.com/hivecommons/hive/issues/18568)). +An owner who wants a report in every repo can opt in; see +[One report, or one per repo](#one-report-or-one-per-repo). + +Everything on this page lives under `governor.advisory` in `hive.yaml`, and every +setting is also editable from **Governor Config → Advisory** in the dashboard +(owner role required). + +```yaml +governor: + advisory: + max_findings: 10 + show_all: false # true = ignore max_findings + staleness_days: 7 + pr_autoclose: true + update_interval_s: 0 # 0 = default (~60s cycle); 30–3600 to slow the refresh + digest_min_interval: 1h # a CHANGED digest is rewritten at most this often; 0 = every changed cycle + target: github # github (default) | linear + linear_issue: "" # required when target is linear, e.g. ONB-123 + per_repo: false # true = every monitored repo also gets its own report +``` + +## One report, or one per repo + +`governor.advisory.per_repo` (Settings, **Governor Config → Advisory**, +"Advisory report in every repo"; default **off**) decides whether a multi-repo +hive files one report or one per repo +([#18448](https://github.com/hivecommons/hive/issues/18448)). + +- **Off** (default): one Hive Advisory Report in your primary repo covers all + repos. Nothing is created in any other repo. +- **On**: each monitored repo also gets its own report, with the same digest + posted to it. Each repo gets exactly one: before creating anything the hive + looks for an existing report by its title together with the `hive/advisory` + label or the `` marker in its body, open or + closed, so a restart never files a second one. A repo added in Settings gets + its report on the next eval cycle. +- **A closed report stays closed.** If someone closes a repo's report, the hive + stops posting to it and never reopens it or files a replacement, on this run + or after a restart. (The primary repo's report is different: it is reopened + when closed, because it is the hive's one place to look.) +- **Repos the hive cannot write to are skipped.** A repo with Issues disabled, + or where the hive's GitHub App has no write access, is logged once and shown + as a dashboard warning; the hive checks it again at most hourly rather than + every cycle, and the other repos are not affected. +- **Turning it off** stops updating the per-repo reports. They are not closed + or deleted; close them by hand if you no longer want them. + +When `per_repo` is absent from `hive.yaml`, the `HIVE_ADVISORY_PER_REPO` +environment variable (`true` / `false`) sets the default. An explicit value in +`hive.yaml`, or a change in Settings, always wins. Every change made in Settings +is recorded in the audit log. + +## Keeping findings current + +The dashboard shows each finding's original creation time and **last seen** +time. Last seen means last reported, not last verified; older beads without +that timestamp display `unknown`. The digest/API preserves creation time in +`timestamp` and exposes the separate optional `last_seen_at` field. + +Each row also displays Hive's existing provenance-stale, cached-replay, and +stale-file/path warnings. "No known freshness warning" is not a claim that Hive +has re-run the finding's evidence. + +Explicit GitHub references in a finding's external reference, title, or detail +appear in `linked_work`, with issue OPEN/CLOSED or PR OPEN/MERGED/CLOSED state. +References may be GitHub URLs, `owner/repo#123`, `repo#123`, `gh-123`, or bare +`#123` in the primary repository's context. The server resolves them once per +distinct reference per digest (up to 250 references and 10 seconds for the +pass); the browser makes no GitHub requests. Each successful lookup includes +`checked_at`. Failed or skipped lookups show UNKNOWN while retaining the link. +"No linked remediation" means the finding names no deterministic reference; +it does not claim that no remediation exists. These annotations do not change +the retirement rules below. + +A digest is only useful if it distinguishes current findings from findings no +agent has recently re-verified. Only positive evidence retires a finding. + +### Staleness marking + +An advisory agent re-files a finding for as long as its condition holds. The +re-file does **not** create a second bead: the hive upserts it, refreshing the +bead's `last_seen_at` stamp instead. A finding no agent has re-reported for +`governor.advisory.staleness_days` days is no longer recently verified, but +silence alone does **not** prove the condition is gone: an agent run can be +partial, truncated, non-deterministic, or absent. + +Each eval cycle, before the digest is built, the hive marks every open advisory +bead whose `last_seen_at` is older than that window. Marked findings stay in the +open list with a warning caption: "not re-reported within the staleness window — +still open, but not recently verified". They do **not** appear under +**Recently Resolved** unless another path has positive evidence of resolution. + +- `governor.advisory.staleness_days` — default `7`, minimum `1`. Agents re-scan + far more often than weekly, so a week is a generous margin. Shorten it on a + hive whose advisory agents run constantly; lengthen it on one whose agents run + rarely, or a finding may be marked stale between two runs of the agent that reports + it. +- Beads filed **before** this feature existed carry no `last_seen_at` and are + never marked for staleness. "Not re-reported" cannot be told apart from + "never stamped", so those beads are left alone and close through the normal + paths. + +The stale marker is recorded on the bead as +`stale_unverified: not re-reported within staleness window`, so every warning is +inspectable with `bd show`. A fresh re-report clears it. + +Agents get the upsert behavior for free: `bd create --type advisory` with a title +matching an open advisory bead refreshes that bead instead of adding a second +one. No other bead type upserts — two tasks with similar titles are two tasks. + +### PR-linked auto-close + +When a pull request is verified merged, the hive compares its title against the +titles of open advisory findings and closes the ones that are close enough. A fix +therefore retires the finding it addresses immediately, instead of waiting out +the staleness window. + +- `governor.advisory.pr_autoclose` — default `true`. Set it to `false` to rely on + explicit agent closes and other positive-resolution paths alone. +- Matching is title similarity only, so it is deliberately best-effort: a finding + closed in error comes straight back the next time an agent files it, because a + re-file after a close opens a fresh bead. +- The close is recorded as + `close_reason: auto-closed: a merged pull request addresses this finding`. + Because a title match is inference, the digest lists these closes as + **fix not verified**, not as resolved (see below). + +### Only verified closes are resolutions + +Advisory agents re-check their own open findings each cycle and `bd close` the +ones they judge fixed or invalid. That judgement is an LLM's, and it is +routinely wrong: the digest of 2026-09-24 reported a still-undocumented +feature as resolved because the `guide` agent closed its finding with no docs +change behind it ([#6262](https://github.com/hivecommons/hive/issues/6262)). +The hive's own inference-based auto-closes can be wrong the same way: a PR +title can share words with a finding it never touched, and a finding can cite +an issue that closes for reasons unrelated to its remedy. + +The digest therefore splits recently closed findings by what backs the close: + +- **✅ Recently Resolved** — struck through, "resolved ". Only closes + where the hive re-ran the failing check itself and saw it pass: a healed App + or repo-access finding. +- **☑️ Recently Closed — Fix Not Verified** — not struck through, + " — closed (), fix not verified", where `` is the + agent that reported the finding (a bead does not record who closed it) and + `` is one of: + - `a merged PR's title matched` — PR-linked auto-close. + - `the issues/PRs it cites closed` — every GitHub issue or PR the finding + references has closed, including stale findings retired that way. + - `no evidence recorded` — every other close, including `bd close` and + `bd update --status done|closed`. + + The condition may still hold. + +Both sections share the `max_findings` changelog cap described below. The +zero-findings digest says "all previously reported findings are resolved" only +when every listed close, and every close hidden by the cap, is verified. The +digest JSON carries the basis on each entry as `close_basis` +(`hive-verified`, `pr-title-match`, `cited-refs-closed`, `unverified`). + +### Evidence provenance + +The digest footer stamps one commit — `Analyzed at owner/repo@` — across +every finding it renders. That stamp describes when the digest was *built*, not +when each finding's evidence was *computed*, and the two drift apart: findings +persist as open beads and are re-rendered verbatim every cycle, so a finding +whose evidence was gathered several commits ago is republished under today's +commit without anything re-checking it. + +That drift is not just noise. A finding that was accurate when computed, then +fixed in the target repo, kept appearing under a commit at which it no longer +reproduced — and a re-verifying agent that checked it against the stamped commit +concluded the evidence had been fabricated when it was merely stale (#5130). + +So the digest now tracks the commit a finding's evidence came from, and captions +any finding that was **not** computed at the analyzed commit: + +> - **[coverage-gap]** contrib/aib has no test coverage ⚠️ _(evidence computed at +> `c9546a8`, not re-verified at the analyzed commit)_ _quality_ + +The digest cannot re-run a finding's own evidence — that evidence is arbitrary +(a `grep`, a workflow-file read, a coverage run), and a coverage-specific refresh +would still republish the rest. What it can do is stop asserting a freshness it +never checked, so the caption says exactly that and the footer no longer implies +otherwise. + +A finding's provenance commit is read from, in order: + +1. `provenance_sha` in the finding's advisory JSONL, or the same key in the + bead's metadata. This is the **explicit** form, and the one to prefer. +2. The finding's own prose, when it already names its provenance — wordings like + `revision `, `commit `, `computed at ` or `as of ` are + recognised. A bare hex run with no such keyword is never read as a commit: + log ids and digests appear in finding text far too often. + +A finding that names no provenance at all is left **unmarked**. Silence about +provenance is not a freshness claim in either direction, so the digest neither +captions it nor implies it was verified. + +#### Provenance and the staleness clock + +Provenance also fixes a hole in [staleness marking](#staleness-marking). +The re-report of a finding is what refreshes its `last_seen_at`, on the reasoning +that an agent only re-files a finding while its condition holds. But agents +re-report from **cached prior findings**, not from re-verification — so a +finding that had already been fixed kept re-stamping itself and survived every +prune window. + +A re-report that carries the **same** `provenance_sha` the bead already records +is therefore a restatement of evidence computed once, not fresh confirmation +that the condition still holds. It no longer refreshes `last_seen_at`, so the +staleness clock keeps running and `staleness_days` marks the finding as +unverified on the normal schedule. A re-report computed at a *different* commit +is a genuine re-check: it refreshes the stamp, records its new provenance, and +clears the stale marker. + +Two deliberate limits keep this from retiring findings that still hold: + +- Only an **explicit** `provenance_sha` gates the refresh, never the prose- + inferred one. Misreading "regressed in commit ``" as provenance would age + out a live finding, so inference is trusted for captions only. +- A finding that records no provenance behaves exactly as it did before — every + re-report still counts as a confirmation. Nothing starts ageing out merely + because its producer does not report a commit. + +## How much the digest shows + +By default the digest renders the **top 10** findings, ranked by severity +(critical → high → medium → low → minor), then by whether the finding's file +still exists at the analyzed commit, and then by recency, across all agents at +once. Ranking globally rather than per agent is deliberate: an owner cares which +findings matter most, not which agent produced them. + +- `governor.advisory.max_findings` — default `10`, minimum `1`. +- `governor.advisory.show_all` — default `false`. `true` bypasses the cap + entirely, whatever `max_findings` says. This is the only supported way to + render an uncapped digest: `max_findings: 0` reads as "unset" and resolves + straight back to the default on the next config load. + +Nothing is dropped silently. When the cap holds findings back, the digest carries +a note directly under the finding count: + +> 💡 Showing top 10 findings (by severity). 24 more exist. Set +> `governor.advisory.show_all: true` to see all. + +The hub's My Hives view shows the same thing on the hive's row: a +`10 findings (top 10)` pill, whose tooltip names the full total. + +The top-N cap is applied **after** near-duplicate collapsing, so a single +recurring problem re-filed under a dozen wordings cannot consume the whole +budget. A separate, unconditional cap still limits how many findings one agent +may render under one finding type in a single severity section — that one exists +to keep the comment inside GitHub's 65,536-character limit and is not +configurable. + +`max_findings` bounds the **Recently Resolved** changelog too. It is a +changelog, not work: a reader opens the digest to learn what still needs doing, +and there is no length at which a long list of healed findings serves that +better than the open ones do. Left outside the cap it crowds them out — the live +digest of 2026-09-03 rendered 10 open findings in 4,937 characters, under a note +saying 286 more existed, and 100 resolved ones in 22,138, so 82% of the comment +was work already done. + +Each entry's `resolved` date comes from the bead's persisted first resolution +time. When the finding names a GitHub issue or PR that has closed, the digest +uses that closure or merge timestamp instead of the time a later render noticed +the bead was resolved. + +Withheld resolved entries are announced the same way withheld findings are, as +the last line of the section: + +> - *…plus 20 more resolved in the last 48h, collapsed so the open findings +> above stay readable* + +`show_all: true` lifts the cap off the changelog as well. A hard ceiling of 100 +resolved entries still applies above it — an owner asking to see every finding +is not asking for an unbounded changelog, and past GitHub's character limit the +digest is truncated from the bottom, which is where this section and the +analyzed-commit footer under it live. + +For the same reason, a finding whose file no longer exists at the analyzed +commit — the ones captioned *"file path not found at analyzed commit — finding +may be outdated"* — does not take a slot ahead of a live finding of the **same +severity**. Freshness only breaks ties within a severity band: a path that moved +does not prove the problem is gone, so a stale critical still outranks a live +low. Stale findings are set aside rather than dropped, and backfill any slot no +live finding of that severity claims, so the digest never renders short. + +This ordering requires a pinned `AnalyzedSnapshot`, which the governor resolves +once per evaluation cycle (so the dashboard and status digests are snapshot-pinned +too, not only the posted comment). Without one (no GitHub client, or the commit could not be +resolved) the ranking falls back to severity-then-recency and no path is +checked. Path lookups are cached per commit and stop as soon as the cap is +filled, so ranking the full finding set costs roughly what verifying only the +rendered ones used to. + +## The digest stopped updating + +The digest is posted to one pinned issue per repo, titled **🐝 Hive Advisory +Report**. By default it refreshes every governor eval cycle (~60s); an operator +can slow that deliberately (see below), which is a configured cadence, not a +stall. + +Three things can stop it, and all three now surface rather than fail +quietly: + +- **The pinned issue could not be resolved.** The hive ensures the issue at boot; + if that call fails (rate limit, 5xx, search-API blip) it is retried on every + eval cycle until it succeeds. While it is unresolved and there are findings to + publish, the spoke records a post error — `no advisory issue resolved for + ` — so the hub flags the hive's digest stale with that cause instead of + reading it as a hive that simply does not post advisories. +- **The repo has Issues disabled.** Forks have `has_issues=false` by default — + there is no Issues tab, so the pinned issue can neither be found nor created. + The hive checks the flag before attempting the create and records a distinct + post error naming the remedy: enable Issues in the repo's **Settings > + General > Features**, or point the hive at the upstream repo. This is not an + App-permission problem; the App banner stays down. +- **Someone closed the pinned issue.** The hive reopens the existing issue rather + than filing a new one. Filing a new one splits the digest: the hive writes to + the new issue while everyone subscribed to the old one watches a comment that + never changes again — which looks exactly like a wedged digest. If a repo + already has several `🐝 Hive Advisory Report` issues from before this behavior, + close the stale duplicates and keep the one the hive is currently updating (the + one with the newest digest comment). +- **The App cannot write.** A 403 on the digest post raises the App banner with + its specific cause; the hub pill carries the same string. + +To check freshness: the hive's row on the hub shows the last successful post +time and any error; on the spoke, `posted advisory digest` is logged at INFO on +every successful update, and `advisory digest not posted` at WARN when there is +nothing to post to. + +## When the write is refused + +GitHub answers `403 Resource not accessible by integration` when an +installation token may not act on the resource. For the digest that happens +in three shapes, none of them transient: the existing digest comment was +authored by another identity, the repository was removed from the App +installation, or — the most confusing — the repository was **transferred to +another owner**. GitHub follows the rename redirect on every read, so the hive +still finds the advisory issue and its digest comment under the old +`owner/repo`, but the installation token is bound to the old owner and every +write is refused. + +What the hive does: + +- A refused (403) or vanished (404) **edit** of the existing digest comment + falls back to **creating a fresh comment** under the hive App's own identity; + later cycles find and edit that one. Transient failures (5xx, rate limit) + do not fall back and are retried next cycle as before. +- If the **create** is refused too, the hive probes the repository's canonical + name. When it has moved, the recorded error — shown on the hub health row and + the dashboard App banner — names the move and the remedy: install the hive + App on the new owner if it is not already, then update the hive's configured + repo to the new `owner/repo`. Otherwise the existing write-forbidden + diagnosis (repo not in the installation's selected repositories) applies. +- Post attempts then **pause** for `governor.advisory.post_retry_backoff_s` + (default `3600`; `HIVE_ADVISORY_POST_RETRY_BACKOFF_S` overrides the default; + negative disables the pause) instead of re-sending the same refused write + every eval cycle. The recorded error stays visible for the whole window; a + successful post — e.g. after the operator repoints the hive — clears it. + +## How often the digest updates + +`governor.advisory.update_interval_s` — default `0`, meaning the digest is +checked and refreshed every governor eval cycle (~60s), exactly the behavior +before the knob existed. Set it between `30` and `3600` seconds to slow the +refresh — useful to cut GitHub API writes, notification churn on watched +repos, and audit-log noise. Also editable from **Governor Config → Advisory → +When it updates**; dashboard edits apply live from the next cycle, no restart. + +Details worth knowing: + +- The throttle paces only the GitHub comment write. The digest itself, the + dashboard view, and the status broadcast still refresh every cycle. +- The window advances only on a **successful** post, so a failed write is + retried on the very next cycle rather than waiting out the interval — except + a `403 Resource not accessible by integration`, which pauses attempts for + `post_retry_backoff_s` (see below). +- A brand-new finding on a quiet hive posts immediately; only subsequent + refreshes wait for the interval. +- Byte-identical digests are skipped regardless of this setting, with a + periodic forced full rewrite to heal hand-edited comments; that forced + rewrite is counted in post attempts, so its spacing stretches proportionally + at longer intervals. +- The maximum (1 hour) is deliberately capped under the hub's 90-minute + wedged-digest alarm, so a healthy slow cadence can never be flagged as a + stalled digest. +- Values outside the band are rejected by the dashboard API and clamped (with + a one-time warning in the hive log) when hand-edited into `hive.yaml`. + +### One comment, rewritten at most hourly + +The digest lives in exactly one comment per advisory issue, anchored by an +`` marker and closed by an +`Updated N times · last ` footer; the counter is read back from the +comment itself, so it continues across restarts. `update_interval_s` paces how +often the hive *checks*; `governor.advisory.digest_min_interval` (default `1h`, +**Settings → Advisory → Rewrite floor for a changed digest**) bounds how often +a *changed* body is actually written. Live counts in the Advice block drift on +every eval cycle, which used to rewrite the comment every ~5 minutes; now the +first change after the window is written and later drift waits for the next +window. An unchanged digest never writes. The baseline is the comment's own +`updated_at` on GitHub, so a restarted governor never reposts inside the +window; `0` disables the floor. The governor log line +`advisory digest comment written` marks the cycles that really reached GitHub +(`posted advisory digest` is logged for every healthy cycle, skipped or not). + +## Where the digest is posted + +`governor.advisory.target` — default `github`. Chooses which tracker hosts the +digest comment. Also editable from **Governor Config → Advisory**. + +- `github` (default, and the only behavior before the key existed): the pinned + comment on the advisory issue of the primary repo, exactly as described at + the top of this page. Leaving the key out means this; nothing about the + GitHub path changes when the key is absent. +- `linear`: the digest is maintained as **one comment on a designated Linear + issue**, named by `governor.advisory.linear_issue` (an identifier such as + `ONB-123`). The comment body is identical to what the GitHub comment would + contain, and it is rewritten in place every cycle: the hive finds its own + comment by the fixed footer it stamps on it (`hive-advisory-digest`) and + updates that comment rather than adding a new one, skipping the write when + the body is unchanged. Authentication reuses the work source's key + (`governor.work_source.linear.api_key`, the same bare-token header the + issue enumerator sends), so a Linear-sourced hive needs no extra credential. + The `update_interval_s` throttle and the hub's staleness signal apply to + this route exactly as to GitHub. + +This is meant for hives whose work source is Linear +(`governor.work_source.type: linear`) and whose owners live in Linear rather +than GitHub. It is a choice, not an inference: a Linear work source does +**not** move the digest by itself, because a living GitHub issue that is never +closed is a perfectly good digest home and many operators prefer it. + +The Linear route fails closed. If `target` is `linear` and `linear_issue` is +empty, or the API key is missing, or the issue cannot be found, the hive logs +an error naming the missing key (`governor.advisory.linear_issue is required +when governor.advisory.target is linear — digest not posted`), records the +cycle as a failed post so the hub's stale-advisory pill trips, and does +**not** fall back to the GitHub issue. The dashboard API rejects a `linear` +target with no issue up front, and rejects any target other than `github` or +`linear`; a hand-edited unknown value in `hive.yaml` is reported the same way +at post time. + +## Owner advice + +The digest opens with an **Advice** block — the same weekly owner advice the +dashboard card and `GET /api/hive-advice` show. It is computed by +`pkg/hiveadvisor` (`Recommend`, `src/pkg/hiveadvisor/hiveadvisor.go`), a pure +rule table over the status payload. + +### What the advice explains + +Two families of rules feed the block: + +- **Mode-gated rules** read the governor's counters: enable a disabled agent, + give idle agents a cadence, widen `HIVE_REPOS`, rebalance toward merge-side + agents, and so on. They run only in the governor mode they are written for. +- **Queue-health rules** read the **Overview chart's per-item band breakdown** + — every open and held issue/PR across repo cards, classified by the same + `bands.go` classifier the Overview donuts and the `/api/overview/*.csv` + exports use ([#9102](https://github.com/hivecommons/hive/issues/9102)). + They fire in **every** governor mode, because 70 blocked PRs are a problem + whether the governor calls the hive `IDLE` or `SURGE` + ([#9103](https://github.com/hivecommons/hive/issues/9103)). + +| Rule | Fires when | Says | +| --- | --- | --- | +| `reduce-blocked-prs` | Blocked PRs ≥ `blocked_pr_pct` of open PRs | the dominant cause and the first action: *"41 of 70 fail check `go-security-analysis` — fix the check before touching cadence"*, *"N have merge conflicts — rebase or close the oldest"*, or the top blocked-verdict reason | +| `fix-failing-check` | one check fails on ≥ `check_share_pct` of CI-blocked PRs (at least 2) | the check name and how many PRs it holds | +| `throttle-lane` | one agent lane produced ≥ `lane_share_pct` of Blocked PRs (at least 2) | the lane to slow down | +| `clear-human-gate-prs` | Needs-human PRs ≥ `needs_human_pr_pct` of open PRs | how many are held, labelled `needs-human`, or `needs-decision` | +| `unblock-human-issues` | Needs-human issues ≥ `needs_human_issue_pct` of open issues | the `needs-decision` / `blocked` / `2-discussing` split | +| `review-stale-prs` | Blocked PRs past `dashboard.issue_bands.stale_days` ≥ `stale_blocked_prs` | stale = no activity past the threshold, not proven dead | +| `confirm-and-close` | any issue in Confirm & close | how much of the backlog confirming them removes | + +Every queue-health recommendation carries: + +- **First:** the first five issues/PRs it is about (oldest activity first), + each with why it is listed (the failing check, "merge conflict", "held"). +- **Full list:** the matching Overview export, e.g. + `/api/overview/prs.csv?band=blocked` (plus a `repo=` link when one repo + holds half the blocked PRs). The digest prefixes the link with + `dashboard.public_url` (or the hub-delivered `hub.dashboard_url`); with + neither set it prints the path as code. +- **Band rules:** the one-line rule for each band the advice names, the same + text the Overview tooltips print — so *Blocked* is read as "blocked sweep + verdict, merge conflicts, or failing CI", not the `blocked` label. + +### Which count is quoted + +The block states both totals because they are different things: + +- **Governor actionable queue** (`governor.issues` / `governor.prs` in the + status payload): what mode and cadence key on. It excludes held, draft, + in-review and human-gated items, so a hive can legitimately report a queue + of 0 PRs while the Overview shows 93 open PRs. The mode-gated rules quote + it (signal names prefixed `governor_`). +- **Overview chart**: every open or held item across repo cards. The + queue-health rules count this (signal names prefixed `overview_`). + +### Freezing the advice, not the numbers + +The **set** of recommendations is frozen for seven days (`EpochLength`) unless +the governor mode changes, so the top-three list does not flicker across eval +cycles. Their **numbers, item lists and links are recomputed on every +digest**: "70 blocked" a week after the CI fix would be worse than no advice. +A frozen recommendation whose trigger no longer holds stays in the list, +struck through and marked *cleared*, with its stale numbers dropped; a rule +that starts firing mid-epoch waits for the next epoch. An epoch that froze +only the "Keep observing" placeholder is not kept once real advice appears. + +### Tuning the thresholds + +The trigger points are starting values to calibrate against real hives, not +settled policy. Each is a whole number under `governor.advisory.queue_health`; +absent keys use the defaults below and never appear in a re-saved `hive.yaml`. + +```yaml +governor: + advisory: + queue_health: + blocked_pr_pct: 50 # Blocked PRs as % of open PRs + needs_human_pr_pct: 25 # Needs-human PRs as % of open PRs + needs_human_issue_pct: 30 # Needs-human issues as % of open issues + stale_blocked_prs: 10 # count of Blocked PRs past stale_days + lane_share_pct: 50 # one lane's share of Blocked PRs + check_share_pct: 50 # one check's share of CI-blocked PRs +``` + +## Related + +- [Advisory digest staleness](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory-staleness.md) — the other side of the + section above: which of these failures light the hub's stale-advisory pill, + which are deliberately suppressed, and how to measure the suppressed ones. +- [`bd` beads CLI](https://github.com/hivecommons/hive/blob/v5/src/docs/beads-cli.md) — inspecting advisory beads directly, including + their `close_reason`. +- [Governor mode thresholds](/docs/hive/operations/agent-and-governor-controls/governor-thresholds) — the eval cycle the digest + is built on. diff --git a/docs/content/hive/agent-logging.md b/docs/content/hive/agent-logging.md new file mode 100644 index 0000000..3b6d427 --- /dev/null +++ b/docs/content/hive/agent-logging.md @@ -0,0 +1,302 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-logging.md) during the docs build. Edit the canonical source in the Hive repository. + +# Agent peer-awareness logging (pluk) + +Hive attaches [`pluk`](https://www.npmjs.com/package/@hivecommons/pluk) — an +external, per-agent output-capture layer — to every agent's tmux session. Pluk +writes a structured JSONL event stream for that session, and other agents (or +operators) can read it for read-only peer awareness without attaching to the +agent's tmux socket. + +This page documents what pluk is, the log format Hive's own code depends on, +and how `hive-panes` uses it. It does not document pluk's internals — pluk is +a separate npm package (`@hivecommons/pluk`), not part of this repo — only the +parts of its output that Hive code and scripts actually consume. + +## What pluk is + +Pluk is installed in the container image as an npm global package +(`@hivecommons/pluk`, pinned by `PLUK_VERSION` in `Dockerfile`). It is not a +Hive-authored component; Hive only shells out to it. + +When the agent manager creates a tmux session for an agent +(`pkg/agent/manager.go`), it looks up `pluk` on `PATH` and, if found, attaches +it to that session's pane with: + +```text +pluk watch --cli= +``` + +via `tmux pipe-pane`. `` is the agent's configured CLI backend +(`claude`, `codex`, etc.), defaulting to `claude` when the backend is empty or +is an inference backend. If the `pluk` binary is not on `PATH`, attachment is +skipped silently — the agent still runs, it just has no peer-visible log. + +Pluk also exposes a `send` subcommand (`pluk send hive- +--text= --enter`), which writes through a named FIFO and confirms +delivery via a `command_received` event rather than relying on `tmux +send-keys`. Hive no longer calls it: its only caller was the retired inception +workflow's fallback kick path. + +## Availability conditions + +- Pluk attachment is automatic for every agent tmux session Hive creates — no + per-agent configuration is required. +- It requires the `pluk` binary to be present on `PATH` in the container. It + is installed unconditionally in the shipped image, but a custom or stripped + image without it will run agents with no pluk logs and no `hive-panes` + output. +- The run directory (`/var/run/pluk` — `logs/` and `commands/` subdirectories) + is created ahead of time in the image (`Dockerfile`) and re-created + defensively before each attach by `ensurePlukRunDirs` + (`pkg/agent/pluk_dirs.go`). Both subdirectories are `0770` plus setgid, + owned by the `dev` user and the shared `node` group, so any agent UID in + that group can read another agent's log without world-readable + permissions. +- If directory setup fails, Hive logs a warning + (`"pluk run directory setup failed; pluk publisher may be degraded"`) and + still attempts the attach — a degraded or absent log is non-fatal to the + agent itself. + +## Log location and format + +Each agent's events land in one file per tmux session: + +```text +/var/run/pluk/logs/.jsonl +``` + +Session names follow Hive's `hive-` convention (e.g. +`hive-brainstorm.jsonl` for the `brainstorm` agent). Each line is one JSON +object, newline-delimited (JSONL), appended as the agent produces output. + +The file is written by a shell redirect, not by pluk. `pluk watch` classifies +its stdin and prints events to stdout; it opens no file of its own. `tmux +pipe-pane` feeds the pane into that command's stdin but does nothing with its +stdout, so the publisher invocation in `pkg/agent/manager.go` has to end in +`>> /var/run/pluk/logs/.jsonl` for anything to be written at all. It +did not between [#1759](https://github.com/hivecommons/hive/pull/1759) — which +replaced the Go `pluk-publish` binary, a publisher that wrote the log itself, +with the TypeScript `pluk watch` — and +[#4285](https://github.com/hivecommons/hive/issues/4285). Throughout that +window this directory was empty and every consumer below was reading files that +did not exist. + +Hive pre-creates each session log `0660` and `dev:node` before attaching +pipe-pane. `hive-panes` is run by one agent to read every *other* agent's log, +and agent UIDs differ, so the shared `node` group is what makes cross-agent +reads work — leaving creation to the shell's `>>` would take whatever umask the +pane shell carries and a tight one yields a log no peer can read. + +Nothing rotates or caps these files. `hive-panes` only ever reads the last 2000 +lines, so no consumer needs the history, but the files themselves grow for the life of the container. + +The event envelope, as read by Hive's own code, is: + +```json +{"type": "", "session": "", "data": {...}} +``` + +`type` is a string discriminator; `data` is a flat string-to-string map whose +keys depend on `type`. Hive's dashboard used to subscribe to this stream for +the `brainstorm` session (the inception watcher, retired with the inception +workflow); `hive-panes.sh` is the reader today. The event types: + +- `raw_output` — captured pane output. The text is on `data.line`, and only + there. `hive-panes.sh` has always read `data.line`; the retired dashboard + subscriber read `data.message` until + [#4285](https://github.com/hivecommons/hive/issues/4285) corrected it, which + had left its whole `raw_output` arm dead. Earlier revisions of this page + advised new consumers to check both keys; that was wrong, and generalised + from the `error`/`rate_limit` shape below. pluk builds the event as + `createEvent(..., 'raw_output', { line })` in `dist/classifier.js`. + + `raw_output` is opt-in: `pluk watch` defaults `includeRaw` to false, so the + publisher has to pass `--include-raw` or no such event is ever emitted. It is + the only event type `hive-panes.sh` consumes, so peer awareness depends on + that flag. +- `state_change` — `data.state` is `"working"` or `"idle"`. +- `rate_limit` — `data.message` describes a provider rate limit. +- `error` — `data.message` describes an agent-side error. +- `tool_call_completed` — no payload; emitted after a tool call finishes. + +No in-process Hive consumer tails these logs today. They exist for +`hive-panes` and manual/operator inspection. + +## How `hive-panes` reads it + +`hive-panes` (installed by `src/deploy/hive-panes.sh` when the deployment +includes that script) is a read-only peer-awareness command available inside +an agent's shell: + +```text +hive-panes [lines] # default: 30 +``` + +It: + +1. Lists every `hive-*.jsonl` file in `/var/run/pluk/logs`. +2. Skips the file for the calling agent's own session, identified by the + `HIVE_PROXY_AGENT` environment variable (so an agent never has to filter + its own output out of the results). +3. For each remaining file, takes the last 2000 raw lines, parses each as + JSON, keeps only entries where `type == "raw_output"`, and extracts + `data.line`. +4. Strips ANSI escape sequences and cursor-position control codes, drops + blank lines, and prints the last `N` cleaned lines per agent under a + banner naming that agent. + +It never attaches to another agent's tmux socket — it only reads the JSONL +file on disk, so it cannot send input or otherwise disturb another agent's +session. If `/var/run/pluk/logs` does not exist, it exits with an error +rather than printing empty output, which is the fastest signal that pluk +never attached (binary missing, or the agent manager could not create the +run directory). + +## Retention and rotation + +This repo does not implement rotation or a retention policy for +`/var/run/pluk/logs/*.jsonl` — there is no cron, size cap, or truncation +logic in `pkg/agent` or `src/deploy` for these files. `/var/run` is typically +an in-memory or ephemeral filesystem inside the container, so logs do not +outlive the agent's tmux session/container lifecycle, but within that +lifetime the files grow unbounded from Hive's side. Any rotation behavior +(e.g. size-based rollover) would come from pluk itself; check the installed +`@hivecommons/pluk` version's own behavior if you need to reason about disk +growth, since Hive does not manage it. + +## Using peer awareness as an agent + +- Use `hive-panes [lines]` when you need situational awareness of what other + agents in the fleet are currently doing — for example, before duplicating + work, or to check whether another agent already touched a file you are + about to change. +- Treat its output as recent raw terminal text, not structured data — it is + ANSI-stripped CLI output, not a machine-readable event feed. Do not parse + it for automation; if you need structured events, read the JSONL files + directly. +- Avoid depending on it being present. It requires `hive-panes.sh` to be + deployed and `pluk` to have attached successfully; on a deployment that + omits either, `/var/run/pluk/logs` will not exist and the command exits + with an error. Code and prompts should not treat pluk logs as a guaranteed + input. +- It is read-only by design: it cannot be used to send input to another + agent's session. Use each agent's own kick/messaging path + (`SendKick`/`pluk send`) for that, not `hive-panes`. + +## Terminal scrollback and full-log capture + +Separate from pluk's JSONL stream, each agent's tmux session keeps a deep +terminal scrollback: + +- Agent sessions are created with tmux `history-limit` **50000** (tmux's own + default is 2000, which silently truncated long runs — + [#3790](https://github.com/hivecommons/hive/pull/3790)). Override with + `HIVE_TMUX_HISTORY_LIMIT` (positive integer); it must be set at session + creation — raising it later never deepens an existing pane. The attach-time + twin `HIVE_TTYD_HISTORY_LIMIT` (also 50000) only affects panes created after + a browser attach. +- The browser terminal attaches with tmux mouse mode on, so the scroll wheel + drives copy-mode scrollback; hold Shift (Option on macOS) for native browser + text selection ([#3722](https://github.com/hivecommons/hive/pull/3722)). +- **Full-log view/download:** `GET /api/agents/{name}/log` returns the entire + retained buffer for the agent's latest run as `text/plain` (add `?download=1` + for a `Content-Disposition` download named + `hive--.log`) — [#3711](https://github.com/hivecommons/hive/pull/3711). + In the dashboard these are the `📄 full log` and `⬇ log` controls on the + agent card. Normal dashboard auth applies (any authenticated role); output + passes through token redaction, so it is not a redaction bypass. + +The live capture is scoped to the agent's **current** tmux session: a restart +kills and recreates the session, and a hive upgrade replaces the whole +container. Per-kick log archiving (below) is what preserves run logs across +those boundaries. + +## Per-kick log history + +Hive archives each kick's terminal output to a durable file so operators can +read the logs of the last several runs — not just the latest — +([#4296](https://github.com/hivecommons/hive/issues/4296), +[#4295](https://github.com/hivecommons/hive/issues/4295)): + +- **When snapshots happen.** The scrollback is captured to a file as soon + as the kick's turn is observed to end (the CLI is back at its idle prompt — + the same moment the `kick turn ended` log line and the kick outcome come + from), and again *before* it can be destroyed: when the next kick is + delivered (the previous kick's output is archived and the tmux history is + cleared, so each archive covers exactly one kick), before `kill-session` + on an agent restart, and on graceful shutdown (SIGTERM — pod roll or hive + upgrade) for every agent with un-archived kick output. There is one + archive per kick: the later snapshot of the same kick replaces the + turn-end one (latest content wins), so a daily-cadence agent whose + container crashes hours after its turn ended — a hard kill that never runs + the shutdown snapshot — still has that run under *past kicks*. +- **Where they live.** `/data/logs/kicks//-.log` + (override the root with `HIVE_KICK_LOG_DIR`). `/data` is the persistent + volume on hosted hives, so archives survive agent restarts, pod rolls, and + hive image upgrades. Each file starts with a small header (agent, archive + time, snapshot reason, kick start time, prompt snippet, build/backend/model, + `source`) followed by the raw scrollback. `` is `turn-end`, `kick`, + `restart`, or `shutdown` — what wrote the archive, not how the kick ended. +- **Transcript source.** The scrollback is what the CLI painted, so tool + output the CLI collapsed (`(N lines hidden)`) is not in it. + `HIVE_KICK_LOG_SOURCE=transcript` (or `auto`) builds the archive and the + live full log from the CLI's own transcript instead — Copilot CLI + `events.jsonl` and Claude Code session JSONL — rendered as plain text: + timestamped turns, every tool call with its full arguments (the shell + command on a `$ ` line) and its full output. Only entries since the kick + started are included. A missing, stale or unparseable transcript falls back + to the scrollback with one warning in the hive log, and the header's + `source:` line says which was used. A transcript over + `HIVE_KICK_LOG_MAX_BYTES` keeps its head and tail around a + `[… N bytes omitted …]` marker. The default, `scrollback`, is unchanged. + The source is also a dashboard setting: **Settings → Logging → Kick log + source** (config key `governor.logging.kick_log_source`) offers + *Scrollback*, *CLI transcript* and *Auto*, applies to the next kick without + a restart, and the kick history page shows each archive's `source`. A + `HIVE_KICK_LOG_SOURCE` set on the deployment wins over the saved setting; + the control is then shown disabled with the effective value and a "set by + `HIVE_KICK_LOG_SOURCE`" note. +- **Retention.** Per agent, the newest **10** archives are kept + (`HIVE_KICK_LOG_RETENTION`; `0` disables archiving) within a **64 MiB** + per-agent size cap (`HIVE_KICK_LOG_MAX_BYTES`); the oldest files are pruned + first and the newest archive is never deleted. An agent with less history + than normal (fresh install, retention just lowered) simply lists fewer + entries — never an error. +- **Dashboard access.** The `🕘 past kicks` control on the agent card opens + `GET /agents/{name}/kicks`, an index of the live log plus every archived + kick with view/download links. Programmatic access: + `GET /api/agents/{name}/kicks` (JSON list, newest first) and + `GET /api/agents/{name}/kicks/{id}` (`text/plain`; `?download=1` for an + attachment). Same auth rule as the full-log endpoint (any authenticated + role), and archived content passes through the same token redaction. +- **Sandboxed agents.** A sandboxed kick (`sandbox.enabled: true`, Podman or + `runtime: job`) has no tmux session. When the run ends hive archives the + container's captured stdout/stderr here instead, as + `-sandbox.log` with `source: sandbox-podman` or + `source: sandbox-job` and an outcome block (exit code, commits, branch, + PR or `pr_withheld` reason, agent-report path and status, error) ahead of + the output, followed by one `---- verify: () ----` section + per `publish.verify` command that ran. For these agents the `📄 full log` / `📋 log text` controls and + `GET /api/agents/{name}/log` serve the newest such archive — the only + durable copy, since a completed Job is deleted at once and the sandbox + workspace is swept after two hours — and an agent that has not run yet + gets a plain "no archived run yet" message rather than a pane error. + `HIVE_KICK_LOG_RETENTION=0` disables these archives too, and the card + then has no log to show. +- **Limitations.** The archive holds at most the retained scrollback + (`history-limit`, 50000 lines by default), so an extremely long run + self-truncates from the top. A hard kill (SIGKILL, OOM, node loss) skips the + shutdown snapshot, so a turn still running at that moment loses whatever + it produced after the last snapshot; turns that had already ended were + archived at turn end, and the previous kicks' archives on `/data` are + unaffected. + +## Related + +- [`src/deploy/README.md`](https://github.com/hivecommons/hive/blob/v5/src/deploy/README.md) — `hive-panes.sh` inventory + entry. +- [Agent configuration](/docs/hive/agent-configuration) — where `hive-panes` is + introduced as an agent-facing capability. +- [Architecture](/docs/hive/architecture) — system-level mention of the read-only + peer-observation workflow. diff --git a/docs/content/hive/agent-watchdog.md b/docs/content/hive/agent-watchdog.md new file mode 100644 index 0000000..36cde95 --- /dev/null +++ b/docs/content/hive/agent-watchdog.md @@ -0,0 +1,274 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-watchdog.md) during the docs build. Edit the canonical source in the Hive repository. + +# Agent Self-Healing Watchdog + +Implements [RFC #4665](https://github.com/hivecommons/hive/issues/4665): +k8s-style liveness/readiness reconciliation for hive agents. Before the +watchdog, an agent's dashboard state was a config echo — an agent could sit +dead at a shell prompt (or at a login screen, or behind a first-run modal) +while the UI said `running`. The watchdog observes the actual tmux pane and +reconciles. + +## What it does + +On every governor evaluation tick (self-gated to `probe_interval_s`), for each +launched, running, unpaused agent: + +1. **Liveness** — the visible pane is classified as a state machine: + `ready`, `shell-prompt`, `auth-required`, `stuck-overlay`, `no-output`, + `no-session`, or `unknown`. Classification reuses the same CLI markers and + login-prompt patterns the agent manager uses for sensing. `unknown` is + never treated as healthy — it simply takes no action. +2. **Restart with backoff** — dead panes (`no-session`, `shell-prompt`, + `stuck-overlay`, stale `no-output`) are restarted with exponential backoff + (default `1m, 2m, 4m, 8m, 16m`; the last entry is the cap). Restarts run + detached with a hard timeout, so a wedged tmux/kick path can never block + the governor tick; a wedge is surfaced as an alert on the next sweep. +3. **Crash-loop escalation** — after `crash_loop_after` consecutive failed + restarts (default 5) the agent is paused with trigger `watchdog-crashloop`, + a dashboard banner alert is raised, and an error is journaled. No more + restarts until a human (or the resume API) intervenes. A continuous-ready + window of `healthy_reset` (default 30m) clears the failure counter. +4. **Auth probing** — a pane sitting at a login screen sets + `Authenticated=False` (reason `PaneShowsLogin`) and raises an alert but + deliberately does **not** restart: restarting into a dead credential is + the 1042-restart loop the RFC documents. Two guards keep a CLI's own + startup handshake from paging anyone: login chrome is ignored inside the + boot grace of the agent's most recent CLI (re)launch — a kick restart or + memory-drain recycle hours into an agent's life boots exactly like a fresh + start — and it must persist for `liveness.login_streak` consecutive polls + (default 3; one sighting reports `Ready=Unknown` with reason + `login chrome seen 1/3 polls`) before it counts, mirroring the pane + poller's own `loginStreak` guard. Provider-level credential probes reuse the rotation + package's probers (Claude OAuth usage, Codex app-server handshake, Agy + headless usage, DeepSeek balance) and the owner-aware per-agent credential + check (per-agent `$HOME` layouts, 0600 session files). +5. **Readiness** — production evidence (pane activity plus newest mtime under + the backend's state directories in the agent's `$HOME`) feeds a + `Producing` condition. No evidence for `no_production_for` (default 6h) + degrades to `Producing=False` plus a warning alert — never a pause or + restart. + +## Conditions + +Each agent carries k8s-style conditions in the `/api/agents` payload: + +```json +"conditions": [ + {"type": "Ready", "status": "True", "reason": "PaneReady", "lastTransitionTime": "..."}, + {"type": "Authenticated", "status": "True", "reason": "CredentialPresent", "lastTransitionTime": "..."}, + {"type": "Producing", "status": "True", "reason": "RecentProduction", "lastTransitionTime": "..."} +] +``` + +`lastTransitionTime` only moves when the status flips; the reason/message may +refresh in place. A probe that cannot tell reports `Unknown`. + +### When most of the fleet goes `auth-required` at once + +A burst — every Claude agent but ONE flipping to `auth-required` / +`PaneShowsLogin` within a few minutes, hours after a healthy boot — is almost +never an expired login, and re-authenticating will not fix it +([#5730](https://github.com/hivecommons/hive/issues/5730)). + +Agents share one operator login: each runs as its own uid, but their +`~/.claude` all symlink to `/data/home/.claude` (#4619). Claude Code refreshes +that OAuth credential roughly every 8 hours and rewrites it as whichever agent +refreshed it, mode `0600`. The surviving agent is the one that owns the file; +every other uid, which reaches it through the shared `node` group, is locked +out of a credential that is otherwise perfectly healthy. + +Check the mode before you touch the login: + +```console +$ podman exec hive ls -l /data/home/.claude/.credentials.json +-rw-------. 1 hive-supervisor node 508 Sep 2 19:06 /data/home/.claude/.credentials.json +``` + +Owner-only (no group `r`) is the failure. One command fixes it, with no restart +and no re-login: + +```console +$ podman exec hive chmod g+r /data/home/.claude/.credentials.json +``` + +Agents recover within seconds — the log shows `auto-restarting agent after +token detected in shared config`, then `credential watchdog: durable credential +restored`. + +**Do not restart the container.** It is unnecessary, and it only re-runs the +boot-time repair that made the file readable in the first place, which hides +the cause. + +The same shape applies to antigravity (`agy`), whose token lives one directory +deeper, at `/data/home/.gemini/antigravity-cli/antigravity-oauth-token` +([#5734](https://github.com/hivecommons/hive/issues/5734)) — check and fix it +the same way. + +Two layers keep this from recurring, and both report rather than hide a +failure: the entrypoint's permission guards reopen the credential on every +write and on a 5s poll (they are the only actor that can, since they run as +root and the file is owned by an agent uid), and the in-process permissions +watcher logs at ERROR — naming the mode, the owner and the `chmod` — when it +finds a shared credential it cannot repair itself. If the watchdog reports + +```text +reason=unreadable by the hive process (permission denied) +recovery=chmod g+r /data/home/.claude/.credentials.json +``` + +that is this condition, stated plainly. A report of `login expired (no usable +refresh grant)` is the other condition and does need an operator login. + +## Configuration + +Everything lives under `governor.watchdog` and is optional; an absent block +means the defaults below. Invalid values fall back to the default for that +field with a logged warning — a config typo never silently disables healing. + +```yaml +governor: + watchdog: + mode: observe # observe (default) | heal | off + probe_interval_s: 300 + liveness: + stuck_overlay_after: 10m + shell_prompt_after: 5m + login_streak: 3 # consecutive polls of login chrome before auth-required + restart: + backoff: [1m, 2m, 4m, 8m, 16m] + crash_loop_after: 5 + healthy_reset: 30m + readiness: + no_production_for: 6h + auth_probe: true +``` + +`mode` is the authority level, and the default is deliberately `observe`: + +| mode | classifies, publishes conditions, alerts | restarts / pauses | +|---|---|---| +| `observe` (default) | yes | **no** | +| `heal` | yes | yes | +| `off` | no | no | + +This reconciler restarts agents across the fleet, so it does not ship with that +authority. In `observe` it records what healing *would* have done — as audit +entries suffixed `-observed` — on your own agents, so promotion to `heal` is a +decision made on evidence rather than trust. Read the Audit Log, then switch. + +The pre-mode `enabled` flag still works: `false` maps to `off`, and `true` or +absent maps to `observe` — never straight to `heal`, because a config written +before modes existed never consented to fleet-wide restarts. An unrecognized +`mode` falls back to `observe` and logs; a typo never grants authority. + +Settings are editable in the dashboard under **Settings → Governor → Health**, +beside the escalation breaker, so nobody has to hand-edit `hive.yaml`. The +backoff ladder is shown there read-only: it is a derived progression, and an +arbitrary ladder invites a one-second cap. + +### Watchdog activity strip + +"Read the Audit Log, then switch" is only a data-driven decision if the data is +on the page, so the Health tab shows a **Watchdog activity** strip directly +under the mode banner ([#7254](https://github.com/hivecommons/hive/issues/7254)): + +- **The number** — every `watchdog-*` audit action in the trailing 30 days, + broken down by action. In `observe` the headline reads "N actions the + watchdog WOULD have taken in 30 d"; in `heal`, "N actions taken". A hive + that has sat in `observe` with nothing to act on shows **0**, which is an + answer rather than an absence. +- **The sparkline** — a per-day histogram of those actions with real axes, + coloured by the worst thing in the window: observed-only is muted, a taken + restart is amber, a crash-loop pause or give-up (taken *or* observed) is red. +- **Per-agent liveness** — the reconciler's current verdict for every agent it + has probed (`ready`, `stuck-overlay`, `shell-prompt`, `no-output`, + `no-session`, `auth-required`, or `crash-loop` once the watchdog has paused + it), how long the agent has been in that state, and the `Authenticated` / + `Producing` axes. Agents the watchdog has never swept are omitted rather than + listed as healthy. +- **The promotion hint**, beside the mode select. In `observe`: **Safe to + promote to Heal** when the window holds no crash-loop pause or give-up + verdict, with the number of would-be restarts the verdict rests on; otherwise + the count of severe verdicts to investigate first. In `heal`: when the + watchdog last acted, so a healing hive that has been quiet for weeks is + visibly quiet rather than silently trusted. + +The strip is served by `GET /api/watchdog/activity?days=30` (read-write role, +the same tier as the Audit Log it is derived from). The endpoint reads the +on-disk audit log — current file plus rotated backups, so the window survives +pod restarts and the 500-entry in-memory ring — and buckets by UTC calendar +day. `days` is clamped to the log's 90-day retention. + +### Fleet-wide kill switch + +Set `HIVE_WATCHDOG_PAUSE=true` on the deployment to downgrade every hive that +reads it from `heal` to `observe` — conditions and alerts keep flowing, but no +agent is restarted or paused. It is read at every config resolve, so engaging +it needs no restart, and it can only ever *reduce* authority: it never turns a +watchdog on and never promotes `observe` to `heal`. This is the analogue of the +hub's spoke-upgrade pause, for the case where an operator needs the automated +actor to stop across the fleet without editing 55 configs. + +Backoff and crash-loop state persist in the hive state file (`watchdog` key), +so a pod restart does not reset an escalated agent back into a restart storm. + +## Audit trail + +Every action the watchdog takes is written to the durable audit log +(`/data/audit.jsonl`, 90-day retention) under the user `watchdog`, visible in +the dashboard Audit Log: + +| action | when | +|---|---| +| `watchdog-restart` | a dead agent was restarted (detail carries the pane class, failure count and backoff step) | +| `watchdog-crashloop-pause` | the give-up threshold was reached and the agent was paused | +| `watchdog-giveup` | recorded alongside the pause: no further restarts will be attempted | +| `watchdog-healthy-reset` | a continuously healthy agent's failure counter was cleared | + +In `observe` mode the same decisions are recorded with an `-observed` suffix +(`watchdog-restart-observed`), so a reader can never mistake "would have +paused" for "paused". Sweeps and probes write nothing — only actions and +transitions — because the in-memory ring is small and per-sweep noise would +evict the entries that matter. Entries carry the reasoning, never pane content. + +The `watchdog` user is deliberately not one of the audit log's pseudo-users: +its actions must be auditable, but they must not count as *human* engagement in +the activity signal the hub reports. + +## Coordination with existing machinery + +- Restarts go through the agent manager's `Restart` (same path as the manual + kick), so restart counts stay in one ledger. The watchdog only reconciles + launched, running agents; crashed/stopped agents remain the crash-restart + loop's job, and auth-required panes are never restarted, respecting the + capped token-restart accounting from #4606. +- Provider auth probes are the rotation package's probers (#4608), so probe + improvements there (e.g. #4645) apply here unchanged. +- Dead-session and bare-pane recovery is the watchdog's ONLY in `heal` mode: + the agent manager's crash loop stops restarting those two conditions so the + bounded ladder is the single throttle. In `observe` (and `off`) the manager + keeps that job, so there is never a window in which neither restarts a dead + agent. Consent-screen dismissal and the inference stall nudge are not + restarts and always stay with the manager. +- `Producing=False` requires work to actually be queued. An agent with an empty + queue producing nothing is behaving correctly, and reporting it would light + the condition on every healthy quiet hive — the same rule the hub applies to + agent inactivity. Advisory-tier agents, which cannot drain a queue by design, + are never marked down for a backlog they may not touch. Nor are agents the + governor is deliberately not kicking — cadence paused in the current mode + (the same predicate as the dashboard card's "off by cadence"), or a reviewer + lane with nothing to adjudicate: they are reported + `Producing=True / IdleNotScheduled` with the reason, and a not-producing + alert raised before the suppression began is cleared on the next reconcile. +- The window is never shorter than the agent's own cadence (#13817). A lane + the governor kicks once a day cannot be expected to show evidence every 6h; + for an agent with a periodic cadence the threshold is + `max(no_production_for, period + period/4)` — 30h for a daily lane — and the + condition reports `Producing=True / WithinCadence` with the cadence named + once the configured window has passed. Silence past the widened threshold + with queued work still degrades to `Producing=False`. Continuous, paused and + on-demand cadences have no period and keep the configured window. +- The shared-`$HOME` 0600 permission clobber (RFC failure mode 3) was fixed + at the source by the `umask 007` launch change (#4668) and is not + re-implemented here. diff --git a/docs/content/hive/audit-campaign.md b/docs/content/hive/audit-campaign.md new file mode 100644 index 0000000..5a08c7c --- /dev/null +++ b/docs/content/hive/audit-campaign.md @@ -0,0 +1,104 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-campaign.md) during the docs build. Edit the canonical source in the Hive repository. + +# Audit campaign + +The audit campaign proves the runs three-gate model on a workload that never opens a pull request. It inspects a configured scope, validates findings, deduplicates them, records receipts, and only publishes when the operator has enabled publication. + +## Fixture + +The fixture scope lives at `src/pkg/convergence/testdata/audit-scope/components.json`. Run it through the package tests: + +```sh +cd src && go test ./pkg/convergence ./pkg/convergence/proof ./pkg/retro -count=1 +``` + +The test clears `HIVE_GITHUB_TOKEN` and uses a fake GitHub client that must remain at zero calls. The pilot refuses to run if `HIVE_GITHUB_TOKEN` is present. + +## Activation + +Owners activate a campaign through the dashboard API: + +```sh +curl -X POST "$HIVE_URL/api/runs/audit" \ + -H "Authorization: Bearer $HIVE_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "campaign_key": "audit-campaign", + "scope_dir": "/data/convergence/audit/scope", + "store": "audit", + "generation": 1 + }' +``` + +`scope_dir` points at a directory containing `components.json` in the same shape as the fixture. If omitted, it defaults to `/data/convergence/audit/scope`. `store` selects the bead store that receives the campaign, inspection, finding, and publication beads; when omitted the server tries `audit`, `auditor`, `scanner`, `supervisor`, then the first configured store. The response reports the burndown, receipt count, finding count, and whether publication was skipped. + +## State model + +Campaign state is stored as ordinary beads: + +- one `campaign` bead for the pinned scope; +- one `inspection` bead per component, with state `pending`, `inspected`, or `Unknown` when the mutation journal cannot prove whether a crash-window effect completed; +- one `finding` bead per candidate finding, with state `validated`, `rejected`, or `duplicate_of`; +- publication starts as `none` and records the publisher summary only when publication is enabled. + +No new store, CRD, DSL, or GitHub credential path is introduced. + +## Shadow execution and receipts + +Each component inspection uses the existing mutation executor in `shadow` mode with effect kind `hive.record-finding/v1`. The logical operation ID is derived from the campaign, component, and content hash, so rerunning unchanged content reuses the same journal entry instead of creating another finding. + +Each inspected component emits a `stage-receipt/v1` `StageReceipt` with result class `completed`. The proof predicate `hive.inspection.recorded/v1` binds the inspection bead ID and receipt digest to producer `hive-audit-lane`. + +## Burndown + +Burndown reports completed inspection obligations, known remaining work, and unknown evidence. If any component is `Unknown`, the satisfied count is `null` with a reason; the pilot never substitutes a percentage or guessed number. + +## Publication + +Publication is the third gate. Verification and permission to publish are different decisions: a validated finding never implies a public issue, because hive's policy requires private security disclosure. The publisher in `src/pkg/convergence/publish` is the single trusted publication effect. + +### Turning it on + +Publication is off by default. The activation endpoint still runs inspection when publication is disabled, but skips the publisher and returns `publication_skipped: true` with `publication_reason: "publication.disabled"`. It files only when every one of these holds: + +```yaml +publication: + enabled: true # default false + owner: maintainer-login # the campaign owner every publication runs under + private_channel: "repo:org/security-intake" # or "notify" +``` + +- `publication.enabled` is the operator opt-in. The Features panel exposes it (owner-only) together with the owner and private channel fields. +- The hive's ACMM level must be at least L3. Below L3 no agent holds issue-writing authority, so the publisher refuses with `ErrLevelBelowFloor` and writes a `finding_publication_refused` audit entry. +- The convergence mode must be `enforce`. In `shadow` and `off` the publisher records `withheld:mode` and performs no forge write at all; the test `TestAuditPublishDisabledAndShadowPerformNoGitHubWrites` runs the campaign against an httptest GitHub that fails on any write. +- `publication.owner` names the maintainer principal the publisher acts as. It is the actor on the outcome ledger and in the audit trail; publication stays off until it is set. + +### What one publication does + +Each validated finding is one `github.create-issue/v1` effect executed through `mutation.Executor` under the campaign's claim. The logical operation ID derives from the campaign key, the finding hash, and the channel, never from the holder, epoch, or attempt, so: + +- rerunning the campaign replays the recorded issue instead of filing a second one; +- a crash between intent and acknowledgment leaves the operation `Unknown`; the next run reconciles it by looking the issue up by its marker before any retry; +- an open issue that already carries the marker records `existing:` and files nothing. + +The published body carries the evidence, the cited files, the inspection receipt digest, a link to the run, the marker ``, and a `Hive-Run: ` trailer. A `hive.finding.published/v1` proof binds the issue number and finding hash. + +### Private disclosure + +A named classifier (`publish.ConservativeClassifier`, replaceable) reads the finding's predicate, labels, and title. Any security vocabulary marks the finding sensitive, and a sensitive finding goes only to the private channel: + +| `private_channel` | Where the finding goes | +|---|---| +| `repo:owner/name` | An issue in that private repository, through the same forge seam, with the full evidence. | +| `notify` | The operator notifier, carrying only the title and finding hash. | +| unset | Refused: `ErrNoPrivateChannel`, audited as `finding_publication_refused`, nothing filed anywhere. | + +The publication bead records `private:` without the finding body. + +### Outcome ledger + +The publisher books the campaign's predicted end state, one issue per validated public finding, one disclosure per sensitive finding, nothing for duplicates and rejections, as an `outcome.Record` (`default/@audit-`). The prediction is created at generation 1, superseded when the finding set changes, and accepted only when the actual publications satisfy it. "Issue filed" (the mutation journal) and "repository outcome satisfied" (the outcome ledger) therefore stay different statuses; the publication bead carries no extra status field for this. + +### Publication records + +Finding beads carry `publication_state` with one of `published:`, `existing:`, `private:`, `withheld:disabled`, `withheld:mode`, `refused:level`, `refused:no-private-channel`, or `none`. The campaign's publication bead summarises the counts, for example `none=1 private=1 published=1`. diff --git a/docs/content/hive/backend-support-tiers.md b/docs/content/hive/backend-support-tiers.md new file mode 100644 index 0000000..6361fdf --- /dev/null +++ b/docs/content/hive/backend-support-tiers.md @@ -0,0 +1,563 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-support-tiers.md) during the docs build. Edit the canonical source in the Hive repository. + +# Agent-backend support tiers and acceptance bar + +This is the acceptance bar for adding a CLI backend to hive, and the policy +for which support tier it lands in. It exists so a backend PR can point at +the criterion it satisfies instead of restating the argument every time. +Every criterion below names the file or test a submitter has to touch; the +existing backends are the worked examples. Nothing here changes runtime +behavior. Tracking issue: +[#6231](https://github.com/hivecommons/hive/issues/6231). + +Companion docs: [docs/backend-setup.md](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md) describes +each backend after the fact; [sandbox-isolation.md](/docs/hive/security/sandbox-isolation) +holds the per-backend confinement matrix; `config/backends.conf` is the +implementation. + +## The three tiers + +The 15 shell-known CLIs (`KNOWN_BACKENDS` in `config/backends.conf`) already +fall into three classes that are enforced in code. This document names them. + +| Tier | Meaning | Backends today | Enforcement point | +| --- | --- | --- | --- | +| **T1 - core (headless-pod)** | Runs unattended in a TTY-less pod from staged or env-injected credentials | `claude`, `litellm`, `copilot`, `codex`, `goose` | `HEADLESS_BACKENDS` in the `Justfile` (`contribute-k8s`) and `K8S_HEADLESS_BACKENDS` in `src/pkg/dashboard/api_contribute.go` | +| **T2 - supported (confined)** | Has a confinement floor hive can wire on the contributor local path: an OS sandbox, or at least a host-state deny-list | `claude`/`litellm`, `codex`, `copilot`, `muse` (sandboxed); `opencode` (deny-listed) | `backend_perm_flag` and the `*_local_perm_flag_shell` helpers in `config/backends.conf` | +| **T3 - experimental (unconfined)** | No confinement hive can wire; local mode refuses to launch without a per-backend opt-in, container mode is the default | `goose`, `agy`, `bob`, `pi`, `aider`, `kilo`, `omp`, `openhands`, `omnigent` | `unconfined_local_perm_flag_shell` and `HIVE__DANGEROUSLY_RUN_UNCONFINED=1` (#4918) | + +Tier assignment is per launch path. `goose` is T1 on the pod path (it has a +one-shot `goose run` and an env-key credential) and T3 on the local path (no +sandbox). `omp` is now a hub-agent method, but remains T3 on contributor local +mode because its unattended approval flag is not an OS sandbox. A PR states the +tier it claims for each path it wires. + +`openhands` is T3 experimental, headless-only, on the legacy local-path CLI. +Upstream considers that CLI/headless path legacy and no longer actively +maintained (OpenHands/OpenHands#18046), and Hive will not promote OpenHands +beyond T3 on that surface. + +`omnigent` is T3 experimental (open-source meta-harness over Claude Code, Codex, Cursor, Pi, and custom agents). On the contributor local launch path, the bare CLI runs with no OS sandbox wired by Hive, so local launches refuse by default without `HIVE_OMNIGENT_DANGEROUSLY_RUN_UNCONFINED=1`. While Omnigent has its own internal policy engine and optional agent sandboxing (`enforce_sandbox`), Hive treats these as additive: Hive's API/egress proxy strictly decides and controls all GitHub writes (`POST /repos/{owner}/{repo}/pulls`, `PUT /repos/{owner}/{repo}/pulls/{n}/merge`, Git pushes), and Omnigent policies can never override or bypass Hive proxy denials. See [backend-omnigent-cli-contract.md](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-omnigent-cli-contract.md). + +The T3 tier also bounds what an already-running OMP workbench may take as an +external host (#8361 step 9, #6899): it is admissible only in report-only and +shadow modes, where it holds no repository credential and no dashboard token +and returns a receipt Hive verifies rather than trusts, and the adapter +(`pkg/extwork/omp`, `CheckReportOnly`) refuses any write-capable stage in +code. The escape-hatch env var above concerns launching `omp` locally under +Hive; it does not widen what an external OMP host may do. + +Hosted agent runtimes (Claude Managed Agents, the OpenAI Agents API) are not +CLI backends either. They have their own +[hosted execution tier](#hosted-execution-tier) below. + +`gemini` is Go-only (`cliBackendExceptions`): it is launched by the hub-side +manager and has no contributor-relay wiring at all, so the local-path tiers do +not apply to it. Adding it to the relay would go through this bar as a new +backend. + +## GitHub Agentic Workflows: on-ramp, not a CLI backend + +[GitHub Agentic Workflows (gh-aw)](https://github.com/github/gh-aw) compiles +Markdown jobs into Actions. It has **no T1/T2/T3 assignment**: it is not a new +`KNOWN_BACKENDS` CLI. Engine overlap with Hive does not transfer confinement, +authentication, or metering evidence. The +[report-only sample](https://github.com/hivecommons/hive/blob/v5/src/deploy/gh-aw/README.md) lets an existing gh-aw repo use +Hive's deterministic classifier before engine judgment, keeping its existing +workflows while adopting Hive for continuous fleet work. + +Hive dispatch into gh-aw through `pkg/extwork` is a proposed external-host path, +**not a supported adapter today**. As with external OMP, initial admission must +be limited to report-only/shadow stages, with no repository-write credential or +dashboard token held by the external worker. A future adapter must reject +write-capable capabilities in code, implement the extwork lease/receipt and +cancellation contracts, bind receipts to the dispatched run, and supply +conformance tests proving refusal and verification. An Actions run's success is +not a verified receipt or permission to merge. Do not promote the underlying +CLI's tier or claim budget metering based on this sample. + +## The acceptance bar + +A PR adding backend `` states, in its body, the tier it claims per path +and the evidence for each criterion below. The PR template's backend-addition +checklist is the standing enforcement mechanism for that body-level claim: if a +backend PR deletes the optional section as inapplicable, reviewers should still +ask for it when the diff wires a CLI backend. The criteria are cumulative: T3 is +the floor, T2 adds confinement, T1 adds the unattended-credential story. + +### All tiers + +1. **List parity.** Add `` to `KNOWN_BACKENDS`, `backend_binary`, and + `backend_perm_flag` in `config/backends.conf`, and to `CLIBackends` in + `src/pkg/config/config.go`, in the same PR. The guard is + `TestShellAndGoCLIBackendListsAgree` in + `src/pkg/config/backend_list_parity_test.go`; a name that legitimately + lives on one side only goes in `cliBackendExceptions` with a reason, and + that list is deliberately short (`litellm`, `gemini`). +2. **Declared local posture.** Add `` to `localBackendPostures` in + `src/pkg/dashboard/contribute_local_mode_backend_matrix_test.go` as one of + `postureSandboxed`, `postureDenylisted`, or `postureRefusalGated`. + `TestEveryKnownBackendDeclaresLocalConfinementPosture` fails for any + `KNOWN_BACKENDS` entry without one. The posture must match what + `backends.conf` actually wires, not what the vendor advertises. +3. **Flag-honoring proof.** The PR body shows the exact `backend_perm_flag` + string and a transcript proving the CLI rejects an invalid value for each + safety-relevant flag with a non-zero exit, rather than ignoring it. This is + the `agy --sandbox` lesson recorded in `config/backends.conf`: a flag the + binary accepts and ignores is not a control. The unattended flag is the + vendor's approval-off flag, not its disable-everything flag; the latter + belongs behind the tier's escape-hatch env var (compare + `--dangerously-skip-permissions` for claude and the hub-path + `--dangerously-bypass-approvals-and-sandbox` for codex; contributor-local + codex keeps its explicit approval/sandbox posture from + `config/backends.conf`). +4. **Honest credential detection.** Add a `` case to `detect_cli` in + `bin/contributor-agent.sh`. `--version` is acceptable only when it proves + the CLI can authenticate; if the binary exits 0 with no credential at all, + probe the credential instead (the `codex_is_authenticated` pattern). +5. **Documentation.** A row in the CLI backends table of + [docs/backend-setup.md](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md), a row in the + [per-backend confinement matrix](/docs/hive/security/sandbox-isolation#per-backend-confinement-on-the-contributor-local-path), + and the `AGENT_BACKEND` row in [contributor-relay.md](/docs/hive/contributor-relay), + at the same level of detail as the neighbouring rows: auth mechanism, + credential storage path, headless status, and the escape hatch. +6. **Pinned install.** If the CLI is added to `src/Dockerfile.contributor` or + `src/Dockerfile`, it is fetched from a versioned release with a per-arch + `SHA256` `ARG` and a `sha256sum -c` step. Download failures for optional + backends may be tolerated; checksum mismatches never are (precedent: the + `agy`, `goose`, and `bobshell` layers). +7. **Changelog fragment.** One `changelog.d/added--.md` bullet. + +### T3 - experimental, additionally + +8. **Refusal gate.** Add `` to `unconfined_local_backend_env_var` in + `config/backends.conf` with its own `HIVE__DANGEROUSLY_RUN_UNCONFINED` + variable, and extend the sentence in that file's "no confinement + mechanism" comment that lists the unconfined backends. + `TestUnconfinedBackendsRefuseToLaunchByDefault`, + `TestUnconfinedBackendsLaunchWithExplicitOptIn`, + `TestEveryUnconfinedBackendHasItsOwnEscapeHatch`, and + `TestBackendsConfDocumentsWhyUnconfinedBackendsHaveNoWiring` pin all of + this; the last one asserts the comment's exact wording, so the comment and + the test change together. + +The bar for T3 is honesty about posture, not confinement. A backend with no +sandbox, no deny-list, and no unattended-credential story still lands here. + +### T2 - supported, additionally + +9. **Confinement floor wired and tested.** One of: + - *Sandboxed.* The CLI has an OS-enforced sandbox (Seatbelt, bubblewrap, + seccomp, or equivalent) that is on by default or that hive turns on, and + the unattended flags from criterion 3 leave it intact. Local mode narrows + it to the agent cwd plus `HIVE_WORKSPACE_DIR` (codex `--add-dir`, claude + `--settings` sandbox JSON with `failIfUnavailable`, copilot `--sandbox`), + refuses to emit a grant it cannot express (the whitespace-path guard in + the codex block), and has its own + `HIVE__DANGEROUSLY_BYPASS_*` escape hatch. Matrix tests assert the + narrowing flags are emitted, the bypass drops them, and the + disable-everything flag never appears (compare the copilot and codex + cases in `contribute_local_mode_backend_matrix_test.go`). + - *Deny-listed.* The CLI has no sandbox but honors a command deny rule + that survives its unattended flag. Wire the same host-state family as + `CLAUDE_HOST_DENY_TOOLS` (privilege escalation plus the boot/deployment + tools named in #4918), with a `HIVE__DANGEROUSLY_ALLOW_HOST_STATE` + opt-out. `TestOpencodeLocalModeDeniesHostStateCommands` and + `TestShellAndGoDenyListsAgree` (`src/pkg/agent/host_state_deny_test.go`) + are the templates. The local-mode banner must not call a deny-listed + backend "confined" (`TestLocalModeBannerNeverCallsOpencodeConfined`). + +### T1 - core, additionally + +10. **Headless entry point.** Add `` to `HEADLESS_BACKENDS` in + `bin/contributor-relay.js` with the one-shot sub-command or flag, and a + test in `bin/contributor-relay.test.js` pinning the argv it builds. The + CLI must run the prompt to completion and exit with a meaningful status; + an invocation that prints help and exits 0 would be reported to the hub + as a completed task. +11. **Unattended-credential verification.** Add a `` case to the + credential preflight (#5103) in the `Justfile`'s `contribute-k8s` recipe + that names the env var or staged file a fresh, TTY-less pod + authenticates from, and show in the PR that such a pod completed a real + tool call. "Works on a host that already signed in" is T2 evidence, not + T1: `copilot` and `codex` are in `HEADLESS_BACKENDS` for capability but + the preflight still refuses them because their OAuth state directories + are unverified in a pod, and `agy`, `opencode`, `kilo`, and `muse` are kept + out of the allowlist until their credentials are verified in a fresh pod (see + [Backends excluded from the headless K8s allowlist](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md#backends-excluded-from-the-headless-k8s-allowlist)). +12. **Allowlist touchpoints.** Update all three together: `HEADLESS_BACKENDS` + in the `Justfile`, `K8S_HEADLESS_BACKENDS` in + `src/pkg/dashboard/api_contribute.go` (the `/contribute` page), and the + excluded-backends section of `docs/backend-setup.md`. Consider adding a + lane to the [backend smoke](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-smoke.md) when a credential can exist + in CI. + +## Tier movement + +Promotion (T3 to T2, T2 to T1) is a normal PR that supplies the missing +criteria for the higher tier, the same bar as initial acceptance. Demotion +happens when a criterion is found unmet (a flag discovered to be ignored, a +credential that does not survive a pod restart); the discovering issue cites +the criterion number above, and the fix moves the backend's posture in +`localBackendPostures` and the allowlists in the same PR. + + +## Gateway-path tier + +The three tiers above are the CLI-agent acceptance bar (`KNOWN_BACKENDS`) and do +not apply to the OTHER on-ramp: OpenAI-compatible model gateways (`vllm`, +`llm-d`, `litellm`, `watsonx`, and named Model Gateways such as `openrouter` or +a self-hosted `kind: custom` endpoint — see +[docs/inference-backends.md](https://github.com/hivecommons/hive/blob/v5/docs/inference-backends.md)). A gateway is +not an agent binary; it is a routing target that the built-in Anthropic-to- +OpenAI translator (`pkg/proxy/anthropic_translate.go`, "inference translation +server") calls on behalf of the Claude CLI running in bare mode. That +architectural difference is also why it was untiered: the T1/T2/T3 criteria +above are all about a CLI's own confinement and credential story, which does +not exist on this path. This section states, per feature, what a gateway +backend is expected to do — determined from what the code actually does today, +not from the vendor's advertised capability. Tracking: this section closes the +gap named in [#6515](https://github.com/hivecommons/hive/issues/6515); adopter +symptom: [#6489](https://github.com/hivecommons/hive/issues/6489). + +| Dashboard/agent feature | Gateway-path status | Why | +| --- | --- | --- | +| Model inference (chat) | **Guaranteed** | The whole point of the path: `forwardToInference` translates the Anthropic Messages request to OpenAI Chat Completions, forwards it to `route.Endpoint` + `/v1/chat/completions`, and translates the response (or SSE stream) back. This is what the hermetic canary in `pkg/proxy/gateway_path_canary_test.go` asserts. | +| Model picker / model discovery | **Guaranteed, with unverified fallback** | Hive probes `GET /v1/models` on the gateway (`pkg/dashboard/gateways.go`), with bearer auth when a key is configured. If discovery fails, the dashboard falls back to a static or configured model list and marks entries unverified (`docs/inference-backends.md#model-discovery`) — the picker never simply goes empty, but an unverified entry is not proof the model is reachable. | +| Login flow | **Not applicable — no CLI-style login exists** | Gateway auth is `api_key_env` / `api_key_file` (or, for `watsonx`, an IBM Cloud API key exchanged for a short-lived IAM bearer, `pkg/watsonx`) resolved from `config.GatewayConfig.ResolveAPIKey`. There is no device-flow or interactive `/login` button for a gateway backend the way there is for `copilot`/`claude` — the operator configures the key once in **Governor Config → Model Gateways** or YAML, and a stale/missing key surfaces as a `401` from the gateway itself, not as a login prompt. | +| Token metering | **Guaranteed for the translator path itself; per-kind claim otherwise** | `InferenceSink` (`pkg/tokens/inference_sink.go`) records usage from the OpenAI usage block on every translator response regardless of which gateway kind served it — `vllm`, `llm-d`, `litellm`, `watsonx`, and any named `custom` gateway all flow through the same `forwardToInference` call and the same sink, so the sniff genuinely covers the translator path, not just the two backends historically named in [docs/token-tracking.md](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md). The gap is upstream of the sink: a gateway that never emits an OpenAI `usage` block on its response (some third-party proxies omit it, especially on non-streaming errors) yields zero recorded tokens for that call — see `docs/token-tracking.md`'s "zero consumed" diagnostics table for how that failure is surfaced instead of silently invoicing nothing. Budget-gated hives should treat a newly-added named gateway as unmetered until a real response with usage is observed. | +| Terminal access | **Guaranteed** | Terminal handoff (`pkg/dashboard/terminal_handoff.go`) requires a non-empty `terminalassert.SigningKey()` plus a configured hive ID (`canMintTerminalAssertion`). `SigningKey()` resolves, in order: `HIVE_TERMINAL_KEY` (hub-injected), a self-derived key from `HIVE_HUB_SECRET` + `HIVE_ID`, or — since [#6489](https://github.com/hivecommons/hive/issues/6489) — a persisted per-instance key a standalone/compose spoke auto-provisions with `crypto/rand` under `/data/.hive/terminal-key` (override the directory with `HIVE_TERMINAL_KEY_DIR`); a hub-provisioned hive always resolves through one of the first two lanes and never touches the fallback file. This is independent of the gateway path itself (terminal access never touches the translator). One caveat: on a read-only `/data` mount the fallback key cannot persist, so it degrades to the pre-#6489 static allowlist rather than the signed path (safety-preserving, not a hard failure). | + +### What a gateway smoke check must prove + +A gateway canary — CI or manual — is only meaningful if it proves the parts of +the path that can silently regress independently of each other: + +1. **Request shape survives translation.** The model id set on the route + reaches the gateway verbatim (no silent rewrite), and Anthropic + system/user/assistant turns map to the correct OpenAI roles in order. +2. **Auth reaches the wire.** Whatever key `api_key_env`/`api_key_file` + resolves is the exact value sent as `Authorization: Bearer ` — not a + stale or empty one, and not leaked into `ExtraHeaders` improperly for + backends (like `watsonx`) that use both a bearer and a plain header. +3. **Both response shapes decode.** A non-streaming Chat Completions response + and a streaming SSE response (with `stream_options.include_usage`) both + translate back to a valid Anthropic message/SSE event sequence, including a + non-nil `usage` block. +4. **Failure is not swallowed.** An upstream error status (e.g. `401` for a + bad key) is surfaced to the caller as an error, not silently treated as a + successful empty completion. + +`pkg/proxy/gateway_path_canary_test.go` is the current implementation of this +list: it drives the real translator against an `httptest` fake +OpenAI-compatible endpoint for a named custom gateway authenticated via +`api_key_file`, covering non-streaming, streaming, and the wrong-key failure +case, entirely hermetically (no network, no sleeps) as an ordinary PR-time Go +test rather than a new CI workflow arm. + + +## Hosted execution tier + +Vendors now sell hosted agent runtimes: a platform that runs the agent loop, +keeps its state, and executes its tools in a sandbox the vendor operates. +[#14093](https://github.com/hivecommons/hive/issues/14093) asked whether Hive +can drive two of them, Claude Managed Agents and the OpenAI Agents API, as +backends. This section records the decision +([#14111](https://github.com/hivecommons/hive/issues/14111)), made from two +gap analyses: + +- Claude Managed Agents: + [backend-gap-claude-managed-agents.md](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-gap-claude-managed-agents.md) + ([#14106](https://github.com/hivecommons/hive/issues/14106)). +- OpenAI Agents API: the note proposed in + [#14130](https://github.com/hivecommons/hive/pull/14130) + ([#14108](https://github.com/hivecommons/hive/issues/14108)). + +Neither existing on-ramp fits a hosted runtime: + +- **Not CLI-style.** Criteria 1, 2 and 8 assume a local binary whose flags + Hive controls. A hosted runtime has no binary. A name in `KNOWN_BACKENDS` + would make the shell launch path try to exec it. +- **Not gateway-path.** That tier routes the Claude CLI's model calls through + `pkg/proxy/anthropic_translate.go`. A hosted runtime runs the whole loop, + tools included, so the gateway rows (model picker, login, terminal) do not + describe it. + +What does fit is the `pkg/extwork` external-host contract that Flue, OMP and +vibe-kanban already use (see +[design/external-workflow-admission.md](https://github.com/hivecommons/hive/blob/v5/src/docs/design/external-workflow-admission.md)): +start keyed by execution key, observe by status, cancel, and a receipt fetched +by artifact path and checked against a declared digest. So a hosted runtime +gets its own tier, **hosted execution**. It has no T1/T2/T3 assignment and is +never added to `KNOWN_BACKENDS` or `CLIBackends`. It is an engine adapter +under `pkg/extwork`, switched on per engine under `runs.external.` in +`hive.yaml`, like the existing engines. + +### Decision per runtime + +| Runtime and shape | Placement | Ceiling | +| --- | --- | --- | +| Claude Managed Agents, `self_hosted` environment whose worker runs in a Hive pod with forced egress | Hosted execution | `report-only` at entry; can be promoted | +| Claude Managed Agents, `cloud` environment, credential-less: `networking: limited` with no GitHub host, no vaulted GitHub secret, no GitHub MCP server, web tools off; repo delivered as a file resource or under a read-only one-repo token | Hosted execution | `report-only` at entry; can be promoted | +| Claude Managed Agents, any setup with a direct GitHub write path: a write token on the `github_repository` resource, a vaulted GitHub secret, or the GitHub MCP server | Hosted execution | **Advisory for good** (`shadow` or `report-only`) | +| OpenAI hosted loop (Responses API with a hosted container), credential-less: no network or an allowlist without GitHub, no GitHub token, no GitHub MCP server, writes only as Hive-answered function tools | Hosted execution | `report-only` at entry; can be promoted | +| OpenAI hosted loop where the container can reach GitHub with a write credential, or a remote MCP server holds one | Hosted execution | **Advisory for good** | +| OpenAI Agents SDK loop in a Hive pod with local tools | CLI-style | Not a new backend. `codex` already covers it. Any other SDK-based CLI goes through the T1-T3 bar above. | + +### Advisory-mode ceiling + +The GitHub proxy hard-denies `POST /repos/{o}/{r}/pulls` and +`PUT /repos/{o}/{r}/pulls/{n}/merge` for every agent mode (`denyRules` in +`src/crux/proxy/rules.go`). Those denials only bind traffic that the iptables +redirect forces through the proxy +([net-admin-requirement.md](/docs/hive/net-admin-requirement)). Traffic from a hosted +sandbox does not pass through it. + +A hosted sandbox **egresses GitHub directly** when it can reach GitHub with a +write-capable credential by a path Hive's proxy does not see: from the +sandbox itself, through a vendor-side git or MCP proxy, or through a secret +the vendor substitutes at its own egress. **Such a backend cannot exceed +advisory mode**, meaning `shadow` or `report-only` (`ModeShadow` and +`ModeReportOnly` in `src/pkg/extwork/admission.go`). No promotion lifts this +ceiling. The only way past it is a setup with no direct path. The adapter +enforces the ceiling in code. Before `Start`, it checks the session or +request configuration and refuses a write-capable stage if any direct path is +present. It refuses; it does not downgrade, matching how the existing +engines treat an item bound to an engine they cannot honour. + +Two consequences: + +- Today `pkg/extwork` has no write-capable mode at all, so every hosted + backend enters at advisory regardless of shape. The ceiling above is the + part that still holds after such a mode exists. +- A read-only, one-repo token is not a write path, but it is still a GitHub + credential held by a third party. It must be a short-lived installation + token scoped to one repository with `contents: read`, minted per run. It is + never the App's own key and never a broad PAT. + +### Acceptance criteria + +These replace criteria 1-12 for a hosted backend. They are numbered H1-H6 so +a PR can cite them next to the CLI criteria without confusion. + +- **H1. Engine adapter.** The runtime is an `extwork.Adapter` registered in + `src/pkg/extwork/registry.go`. It is linked into `hive` only behind its own + `extwork_` build tag, and offered only to relays that declare its + `ext-exec/` capability. It passes the #8201 conformance rows that + the Flue and OMP adapters pin in their `conformance_test.go` (admitted task + and replay, held task starts nothing, capability and version refused, + conflict and recreated engine, crash windows, cancel ignored and late + success, outage and waiting, artifact and verifier refusals, store write + fails). `Start` is idempotent on the execution key: the adapter stores the + vendor's session or response ID against the key (vendor `metadata` can hold + it) and reconciles before any retry. +- **H2. Egress statement and refusal.** The PR names the environment type or + container network policy it uses. For each row of that runtime's egress + table in its gap note, it says why the `POST /pulls` and + `PUT /pulls/{n}/merge` denials still hold. Tests pin that the adapter + refuses a write-capable stage for each direct-path row. +- **H3. Default off.** `runs.external.` defaults to off and to + `shadow` when enabled with no mode, the same as `FlueBindingConfig`. It + dispatches only in an explicitly chosen mode. This is the hosted + counterpart of criterion 8's refusal gate. +- **H4. Credential handling.** Before dispatch, an authenticated read proves + the vendor key works (for example `GET /v1/environments/{id}` or + `GET /v1/models`), the counterpart of criterion 4. The vendor key never + enters the sandbox. A Managed Agents `self_hosted` worker holds only its + environment key and the per-session work secret, never `ANTHROPIC_API_KEY`. +- **H5. Metering and spend cap.** Each model call becomes a token record in + `pkg/tokens`, deduplicated on the vendor's ID (the `span.model_request_end` + event ID, or `response.id`), with the model recorded at dispatch when the + usage record omits it. Non-token charges (session run time, web searches, + hosted-tool calls) are recorded, or the dashboard shows the backend as + partly unmetered, under the policy in + [Metering coverage and budget-gated hives](#metering-coverage-and-budget-gated-hives). + On a budget-gated hive the dispatch caps spend from the governor's + remaining budget. For Managed Agents that is the session `budget`; for + OpenAI it is per-call `max_output_tokens` and `max_tool_calls`, and the + adapter stops chaining calls when the governor says so. +- **H6. Pins, docs and changelog.** The request pins what the runtime runs: the + agent version and toolset version for Managed Agents, and the model + snapshot and tool version for OpenAI. The PR adds the documentation rows + listed below and a changelog fragment (criterion 7). + +### Promotion beyond advisory + +A hosted backend in a setup with no direct path may later run a stage beyond +`report-only`. Promotion is a PR that supplies all of: + +1. A write-capable `pkg/extwork` mode, designed in its own issue, in which the + change still reaches GitHub only through Hive's relays (`hive-open-pr`). + The sandbox never writes to GitHub itself. +2. Live evidence from a real run: the vendor refusing an invalid network + policy or tool configuration with an error instead of ignoring it (the + counterpart of criterion 3), a test showing both proxy denials still hold, + and metering for that run reconciled against the vendor's own total + (`session.usage.list_cost` or the organisation usage API). + +A setup with a direct path is never promoted. + +### Which backend is prototyped first + +**Claude Managed Agents, with a `self_hosted` environment**, has the smaller +gap: + +- Tool traffic goes through Hive's own proxy, so the two denials hold through + the existing `denyRules`. No new argument about who holds GitHub tokens is + needed. +- A session `budget` is a hard spend cap that the platform checks before every + model request. +- Agent, environment and session objects map directly onto `Start`, `Observe` + and `Cancel`. The durable, paginated event list is the transcript. + +The OpenAI hosted loop has the smaller gap on telemetry: model and usage are +on every response. But it has no environment type that keeps tool traffic on +Hive's proxy, no server-side spend cap, and hosted-tool charges are missing +from `usage`. Its SDK-in-pod shape is already the `codex` backend. + +The prototype is [#14124](https://github.com/hivecommons/hive/issues/14124). +It is implemented as the `claude-managed-agents` `pkg/extwork` adapter: +`runs.external.claude_managed_agents` is default off, `shadow` when enabled +without a mode, and dispatches only in explicit `report-only` mode. The adapter +is linked only with `-tags extwork_claude_managed_agents`, requires a +`self_hosted` environment and `forced-egress` or `proxy-only` policy, and +stores vendor session bindings under the extwork record directory. It does not +touch `KNOWN_BACKENDS`, `CLIBackends`, or CLI parity/posture tests. + +### Follow-ups + +These are filed as #14124 completes, as its checklist requires: + +- **Second backend.** The OpenAI hosted loop as a hosted-execution adapter in + the credential-less shape, under H1-H6, after #14124 lands. +- **Tier promotion.** The write-capable `pkg/extwork` mode and the live + evidence that the promotion criteria above call for. + +### Rows shipped for the hosted prototype + +The first hosted row is now present in +[`agent-configuration.md`](/docs/hive/agent-configuration#methods-subscription-clis-vs-self-hosted-inference): + +- **Methods table:** `hosted / claude-managed-agents`, authenticated by an API + key reference (`api_key_env` or `api_key_file`) and pinned agent/model + metadata. There is no CLI login or model discovery. +- **Engine block:** a hosted engine is not a `backend:` value. It is selected + under `runs.external.claude_managed_agents`. +- **Per-engine block:** the endpoint, workflow/agent/toolset versions, pinned + `self_hosted` environment, forced-egress policy, report-only mode, state + directory, and USD 25 daily ledger cap are documented. Token events are + metered in `pkg/tokens`; cumulative session list cost, runtime, and web + search usage are persisted in the managed-agents ledger. The adapter stops + at the ledger cap and the vendor session budget is set to the remaining + cents, so the hosted path is not treated as unmetered. + +## Metering coverage and budget-gated hives + +Backend support is also a metering contract. Budget gates in `pkg/governor` +close when token spend reaches the configured weekly budget: the governor reads +collector totals through `UpdateBudgetFromTotals`, stores the current window in +`BudgetInfo`, and suppresses scheduled, resume, and CEL kicks while the budget is +exhausted unless an agent is explicitly exempt. A backend that produces no token +or cost data can therefore make a budget-gated hive look cheaper than it is. + +Metered sources today are the scanner and sink implementations in `pkg/tokens`: + +| Source | Coverage today | Notes | +| --- | --- | --- | +| `claude_scanner.go` | Claude Code session JSONL | Native usage blocks from recent Claude session files. | +| `copilot_scanner.go` | Copilot CLI `events.jsonl` | Reads `session.shutdown.modelMetrics` and avoids double-counting live proxy captures. | +| `bob_scanner.go` | Bob CLI chat recordings | Uses Bob's explicit token fields, falling back to content-size estimates only when a recording lacks token data. | +| `inference_sink.go` | vLLM, llm-d, LiteLLM, live Copilot proxy usage | Hive-written JSONL under the metrics directory. | +| `managed_agents_ledger.go` | Claude Managed Agents self_hosted sessions | Deduplicates `span.model_request_end` IDs into collector JSONL and persists cumulative USD list cost, active seconds, and web searches with a hard USD 25 daily cap. | + +### Tagging Bob sessions for Bobalytics + +Some adopters (for example Enrico) run Hive through Bob and want those Bob +sessions to stand out in Bobalytics without renaming Hive agents. Use the Bob +session-label controls instead: + +```yaml +governor: + bob: + session_prefix: hive- + +agents: + scanner: + backend: bob + # Optional override; otherwise this reports as hive-scanner. + bob: + session_label: hive-triage +``` + +When a label is set, Hive passes it to Bob as `--instance-id` and exports +`HIVE_BOB_SESSION_LABEL` for prompts/scripts. The Hive identity remains +`scanner`: tmux, workdir, HOME, beads, claims, token buckets, and local token +attribution do not move. If both fields are unset, Bob's launch command and env +stay on the legacy path. + +Policy: a backend without token/cost coverage **cannot run under a +budget-gated hive unless the operator explicitly marks it unmetered**, and the +dashboard must display that backend as `unmetered` rather than folding it into +normal spend. New backend PRs should state whether the backend is metered, +unmetered but allowed outside budget gates, or blocked until a scanner/sink +exists. This ties directly to the ccusage sourcing RFC +[#6234](https://github.com/hivecommons/hive/issues/6234): if Hive adopts +ccusage for the nine covered CLI backends, tier assignment should prefer that +shared parser over adding one-off scanners. + +## Deprecation path + +A backend can be demoted or removed when its upstream CLI breaks Hive's contract +and no maintainer or community owner repairs it within the grace period. + +1. **Detection.** The scheduled [backend smoke](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-smoke.md) workflow is the + primary canary. Its `latest` lane detects incoming vendor drift before Hive's + pinned image moves; its `pinned` lane detects breakage in the contributor + image operators already use. Matrix/list-parity tests catch repository-local + drift such as a backend present in `KNOWN_BACKENDS` but missing from Go config + or docs. +2. **Triage and grace period.** A red `latest` smoke opens or updates a + `backend-smoke` issue and starts a 14-day repair window for supported and + experimental backends. A red `pinned` lane is production breakage: it may + trigger immediate demotion from T1/T2 while keeping a 7-day window to restore + the old tier. Core/headless-pod backends get maintainer escalation before + removal because hives may depend on them for unattended operation. +3. **Demotion.** If the backend still authenticates but no longer satisfies a + higher-tier criterion, move only the tier-specific allowlists or posture: + `HEADLESS_BACKENDS` in the `Justfile`, `K8S_HEADLESS_BACKENDS` in + `src/pkg/dashboard/api_contribute.go`, the confinement posture tests, and the + docs rows that claimed the higher tier. +4. **Removal.** If the backend cannot be launched reliably or has no owner after + the grace period, remove it from `KNOWN_BACKENDS`, `CLIBackends`, backend + matrix tests, `docs/backend-setup.md`, this tier document, and any + sandbox/contributor docs. The removal PR cites the smoke issue and states the + replacement path for operators. + +Deprecation is not punishment for vendor drift; it keeps the public backend list +honest. A removed backend can return through the same acceptance bar as a new +backend, with fresh smoke evidence and metering posture. + +## Retroactive tier record: Muse Code + +PR [#6379](https://github.com/hivecommons/hive/pull/6379) (Muse Code, carrying +forward [#6222](https://github.com/hivecommons/hive/pull/6222)) is now recorded +retroactively as **local path T2** and **pod path not T1**. The merged diff added +`muse` to `KNOWN_BACKENDS` and `backend_perm_flag` in `config/backends.conf`, to +`CLIBackends` in `src/pkg/config/config.go`, and to the local posture matrix as +`postureSandboxed` in +`src/pkg/dashboard/contribute_local_mode_backend_matrix_test.go`. Its local +path is T2 because `muse_local_perm_flag_shell` keeps Muse Code's own OS +sandbox on, narrows it with `--workspace`, `--sandbox-network proxy-only`, and +`--no-foreign-personal-context`, and keeps the disable-sandbox `--yolo` flag +behind `HIVE_MUSE_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1`; the same posture +is documented in `src/docs/sandbox-isolation.md` and `docs/backend-setup.md`. +The pod path is not T1 yet because `muse` is absent from the `Justfile` +`contribute-k8s` `HEADLESS_BACKENDS` allowlist and from +`K8S_HEADLESS_BACKENDS` in `src/pkg/dashboard/api_contribute.go`, and +`docs/backend-setup.md` says unattended fresh-pod credentials have not been +verified. The images pin Muse Code by `MUSE_VERSION` and per-architecture +`MUSE_SHA256_*` values in both `src/Dockerfile` and +`src/Dockerfile.contributor`. Metering remains unclaimed: `pkg/tokens` has +scanners/sinks for Claude, Copilot, Bob, and inference proxy usage, but no Muse +scanner, so budget-gated hives must treat Muse as unmetered or blocked until a +scanner/sink is added. diff --git a/docs/content/hive/cel-triggers.md b/docs/content/hive/cel-triggers.md new file mode 100644 index 0000000..4a336ce --- /dev/null +++ b/docs/content/hive/cel-triggers.md @@ -0,0 +1,277 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/cel-triggers.md) during the docs build. Edit the canonical source in the Hive repository. + +# CEL-based agent triggers + +The `triggers:` config key lets an operator declare CEL ([Common Expression +Language](https://github.com/cel-expr/cel-spec)) rules that decide when an +agent should be kicked for an incoming event — issue opened, issue labeled, +PR opened, a comment posted, and so on — without writing code. + +```yaml +triggers: + - name: bug-triage + expr: event.kind == "issue.opened" && hasLabel(event.labels, "bug") + agent: triager + priority: 10 +``` + +This is implemented by `pkg/celtrigger`. + +## How it composes with existing triggering + +`triggers:` is **additive**. It runs *alongside* — not in place of — hive's +built-in label/governor triggering: the governor's eval cycle evaluates the +compiled rule set against each enumerated actionable item and **unions** the +matched agent names into the due-agents set, after its own pause/budget/ +on-demand gates already apply. An empty (or absent) `triggers:` list compiles +to a valid engine that never matches anything, so leaving it out is +byte-identical to today's behavior — nothing about default triggering +changes because this feature exists. + +## The `TriggerRule` schema + +Each entry under `triggers:` is one `TriggerRule` (`pkg/config/config.go`): + +| YAML field | Type | Required | Notes | +| --- | --- | --- | --- | +| `name` | string | yes (in practice) | Human-readable identifier for logs/diagnostics. Not enforced non-empty by the schema, but an empty name is rendered as `rule[]` in error messages, so name your rules. | +| `expr` | string | **yes** | The CEL expression. Must compile and must evaluate to a `bool`. An empty expression is a compile-time error. | +| `agent` | string | **yes** | The agent to trigger when `expr` evaluates `true`. A rule with an empty `agent` compiles fine but is silently skipped when collecting matched agents. | +| `priority` | int | no (default `0`) | Orders competing rules when several match the same event — higher sorts first. Ties preserve declaration order. | + +Source: `TriggerRule` struct, `pkg/config/config.go` (`Name`, `Expr`, `Agent`, +`Priority` fields with their `yaml:"..."` tags), and `pkg/celtrigger/wire.go`'s +`CompileFromConfig`, which maps each `TriggerRule` 1:1 onto a +`celtrigger.Rule`. + +## What the CEL expression binds to + +Every rule is evaluated against exactly one variable: **`event`**, a +`celtrigger.NormalizedEvent` — hive's forge-neutral representation of a +source-control event. `event` is the *only* activation exposed to the +expression; there is no other variable, no access to config, no access to +agent state. + +The reachable fields, taken from the `cel:"..."` struct tags on +`NormalizedEvent` (`pkg/celtrigger/celtrigger.go`), are: + +| CEL field | Go type | Meaning | +| --- | --- | --- | +| `event.kind` | string | Event kind — see the `Kind*` constants below. | +| `event.repo` | string | Repository spelling from `project.repos`, e.g. `"name"` or `"org/name"`; use the configured spelling, not necessarily the qualified display label. | +| `event.labels` | list of string | Labels on the issue/PR. | +| `event.title` | string | Issue/PR title. | +| `event.author` | string | Login/handle of the actor that produced the event. | +| `event.body` | string | Issue/PR/comment body. | +| `event.is_draft` | bool | Whether a PR is a draft. | +| `event.number` | int | Issue/PR number. | +| `event.state` | string | Current state, e.g. `"open"`/`"closed"`. | +| `event.base_branch` | string | Target branch for a PR. | +| `event.head_branch` | string | Source branch for a PR. | +| `event.assignees` | list of string | Currently-assigned logins. | +| `event.added_labels` | list of string | Labels this event added (`pr.labeled` only); empty otherwise. | +| `event.comment` | string | Body of the triggering comment (for `comment.created`). | + +Field access is type-checked at compile time against this registered native +type — an expression that references a field not in this table (e.g. +`event.does_not_exist`) is rejected at `Compile`, not left to fail silently +at runtime. + +`event.kind` takes one of these forge-neutral values (`pkg/celtrigger/celtrigger.go`): + +```text +issue.opened +issue.labeled +issue.closed +issue.reopened +pr.opened +pr.labeled +pr.ready_for_review +pr.closed +pr.merged +comment.created +``` + +`issue.opened` and `pr.opened` are edge-triggered: the eval cycle emits them +once per issue/PR (keyed `repo#number`) per hive process, the first time the +item is enumerated, not on every cycle while it stays actionable. The seen-set +is in memory, so a hive restart re-emits currently actionable items once. + +`pr.labeled` is edge-triggered the same way +([#18538](https://github.com/hivecommons/hive/issues/18538)): when a PR the +eval cycle has already seen carries labels it did not carry at the previous +eval, it is emitted once with those labels in `event.added_labels` and the +full current set in `event.labels`. A label removed and added back fires +again. The first sight of a PR, including the first eval after a restart, is +`pr.opened`, never `pr.labeled`, so a restart does not replay old labels. + +### Review a PR when a maintainer adds the opt-in label + +With `review.require_labels: [hive-review]`, the reviewer only reviews PRs a +maintainer labelled, but on its own it notices the label only at its next +cadence kick. This rule kicks it on the next eval after the label lands: + +```yaml +triggers: + - name: review-on-label + expr: event.kind == "pr.labeled" && "hive-review" in event.added_labels + agent: reviewer +``` + +Use the label your `review.require_labels` names. The kick is an ordinary +governor kick: the reviewer's kick list is still filtered by the label gate, +and pause, budget and on-demand gates still apply. + +### Run the scanner for newly seen GitHub issues + +Open **Settings → Features → Work intake & issue lifecycle → Event triggers**, +or use the **Event triggers** button in **Agent → Configuration → Channels**. +Owner access is required. Choose **Run scanner when an issue is first seen**, +enter a rule name, select the existing scanner agent and **one managed +repository**, then use **Save Event trigger**. No YAML editing is required. +The repository picker displays qualified labels but saves the exact configured +repository spelling used by evaluation; there is no all-repositories default. + +Existing rules can be edited with **Advanced CEL**, preserving their expression, +order, target and priority unless explicitly changed. Higher priority sorts +first; ties retain declaration order. There is no `enabled` field: remove a rule +to stop its routing. These operations do not change unrelated settings or +default governor behavior. + +The editor validates the complete rule list, including CEL compilation and a +boolean result, before persistence. New or edited rules must name an existing +agent. Save errors keep the draft visible; a revision conflict requires +reloading the latest rules instead of overwriting another operator's changes. +**Reload (discard draft)** explicitly discards the pending edit. This editor +has its own save button; the dialog's **Save & close** does not save its draft. +Successful saves are durable and apply on the **next event evaluation**, with +no restart required; saving does not immediately kick an agent. Updating rules +does not reset already-seen item history. + +Agent → Configuration → Channels is **not** a GitHub webhook installer. +Only the governor `kick` channel has a supported runtime; the old `webhook`, +`discord`, `schedule`, and `bead` channel runtimes were removed. +For file-based configuration, the equivalent is a top-level rule in +`hive.yaml` (keep existing rules): + +```yaml +triggers: + - name: scanner-new-issue + expr: event.kind == "issue.opened" && event.repo == "org/repo" + agent: scanner +``` + +Replace `org/repo` with the exact spelling from `project.repos` and ensure the +scanner is enabled. Normal pause, budget, and on-demand gates still apply. +This means **first seen actionable issue**, not exclusively an issue created +after the rule was installed: existing actionable issues match once, and +restart replays them once as described above. + +For prompt delivery rather than waiting for reconciliation, use the existing +signed GitHub webhook receiver and subscribe to `issues`: +[operator setup](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#webhook-driven-pr-cache-invalidation). +Hosted hives normally receive the GitHub App's signed deliveries through the +hub relay; stand-alone hives use `POST /api/webhook/github`. +The receiver requires `GITHUB_WEBHOOK_SECRET` and a matching HMAC signature. +Saving a channel or adding a CEL rule neither registers a webhook nor +configures its secret. Delivery wakes an early governor evaluation subject +to debounce/minimum-gap pacing; it does not bypass agent execution gates. + +### Available functions + +Besides the standard CEL string/list operators (`in`, `.contains(...)`, +`.startsWith(...)`, `.matches(...)`, `&&`, `||`, `!`, `==`, comprehensions +like `.exists(...)`/`.all(...)`), one custom helper is registered: + +- `hasLabel(event.labels, "bug")` — convenience for + `"bug" in event.labels`; returns `false` (not an error) for non-list or + non-string arguments. + +No other custom functions exist. Do not invent one — an expression calling +an unregistered function is a compile-time error. + +### Evaluation cost budget + +Each rule's evaluation is bounded (`maxEvalCost = 10_000` in +`pkg/celtrigger/celtrigger.go`) to stop pathological nested comprehensions +(e.g. a triple-nested `.all()` over labels) from burning runtime per event. +A rule that exceeds the budget is treated as **no-match** for that +evaluation (not an error, not a crash) and logs a warning naming the rule +and the budget so you can diagnose why it stopped firing. Realistic +operator rules — field checks, string predicates, a label +`.exists(...)`/`.contains(...)` — comfortably fit inside the budget. + +## Fail-closed semantics + +This is a safety property, stated plainly: + +- **Compile time (config load):** every rule's `expr` is parsed, + type-checked, and confirmed to return `bool`. If *any* rule in `triggers:` + is malformed — a syntax error, a reference to a field that doesn't exist, + a call to an unknown function, an expression that returns something other + than `bool`, or an empty expression — the **entire config load fails** + with an error. No partial engine is produced; the bad rule cannot reach a + running fleet. +- **Runtime (event evaluation):** if a compiled rule still errors while + evaluating a specific event (including exceeding the cost budget above), + that is treated as **"no match,"** not a crash and not an error + propagated to the caller. One misbehaving rule cannot take down + evaluation for the other rules or for the event pipeline. + +In short: a bad rule is caught early and loudly (at config load); a rule +that merely fails to match at runtime does so quietly and safely. + +## Worked example + +This rule set compiles and matches, verified against +`pkg/celtrigger/wire_test.go`'s `TestCompileFromConfig_ValidAndMatch`: + +```yaml +triggers: + - name: bug + expr: hasLabel(event.labels, "bug") + agent: triager + priority: 10 + - name: pr + expr: event.kind == "pr.opened" + agent: reviewer + priority: 5 +``` + +An `issue.labeled` event carrying the label `bug` matches the `bug` rule and +kicks `triager`. A more selective example, combining a kind check, a +non-draft check, and a target-branch check — verified against +`pkg/celtrigger/celtrigger_test.go`'s `TestMatch_BooleanCombos`: + +```yaml +triggers: + - name: ready-pr + expr: event.kind == "pr.opened" && !event.is_draft && event.base_branch == "main" + agent: reviewer +``` + +This matches a non-draft PR opened against `main`, and does not match a +draft PR against the same branch. + +A slash-command-style comment trigger — verified against +`TestMatch_CommentEvent`: + +```yaml +triggers: + - name: slash-cmd + expr: event.kind == "comment.created" && event.comment.startsWith("/hive") + agent: cmd +``` + +## Relationship to hook predicates (`when:`) + +[State-triggered hooks](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md) use the same CEL engine and the same +fail-closed posture for their optional `when:` predicate, but bind a +different, unrelated variable (`t`, the transition payload) — see +[Predicates (`when:`)](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md#predicates-when) in that doc. `triggers:` +and hooks' `when:` are two separate surfaces that happen to share an +evaluation engine: `triggers:` decides whether to *kick an agent* for a +normalized source-control event, while hooks' `when:` decides whether to +*fire an action* on a state transition. Don't mix `event.*` fields into a +hook's `when:` or `t.*` fields into a `triggers:` rule — the field sets are +disjoint and referencing the wrong one is a compile error. diff --git a/docs/content/hive/cli-pins.md b/docs/content/hive/cli-pins.md new file mode 100644 index 0000000..9ae0126 --- /dev/null +++ b/docs/content/hive/cli-pins.md @@ -0,0 +1,217 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/cli-pins.md) during the docs build. Edit the canonical source in the Hive repository. + +# CLI pins and the automated pin bump + +Every agent CLI hive drives is baked into the images at a fixed version: + +| CLI | Pin (`ARG`) | Source of truth | Verified by | +|---|---|---|---| +| Claude Code | `CLAUDE_CODE_VERSION` | npm `@anthropic-ai/claude-code` | npm (no download hash) | +| Codex | `CODEX_VERSION` | npm `@openai/codex` | npm | +| Copilot | `COPILOT_VERSION` | npm `@github/copilot` | npm | +| pi | `PI_VERSION` (hub), `PI_CODING_AGENT_VERSION` (contributor) | npm `@earendil-works/pi-coding-agent` | npm | +| Goose | `GOOSE_VERSION`, `GOOSE_SHA256_{AMD64,ARM64}` | GitHub releases `aaif-goose/goose` | SHA-256 per arch | +| Antigravity (agy) | `AGY_VERSION` + `AGY_BUILD`, `AGY_SHA512_*` (hub); `AGY_VERSION=-`, `AGY_SHA256_*` (contributor) | Google's updater artifact, as tracked by the Homebrew `antigravity-cli` cask | SHA-512 (hub) / SHA-256 (contributor) per arch | +| spektacular | `SPEKTACULAR_VERSION`, `SPEKTACULAR_SHA256_{AMD64,ARM64}` | GitHub releases `hivecommons/spektacular` | SHA-256 per arch, from the release `checksums.txt` (manual bump for now; not yet in `cli-pin-bump.sh`) | +| quorum (meetings bundle, not a CLI backend) | `QUORUM_VERSION`, `QUORUM_SHA256`, `QUORUM_DAVEY_VERSION` | GitHub releases `hivecommons/quorum` (`quorum.mjs` asset); `@snazzah/davey` at the version quorum's `package-lock.json` pins | SHA-256 of the single arch-independent bundle from the release `quorum.mjs.sha256`; davey through npm (manual bump) | +| Oh My Pi (omp) | `OMP_VERSION`, `OMP_SHA256_*` | GitHub releases `can1357/oh-my-pi` | SHA-256 per arch, cross-checked with `SHA256SUMS.txt` | +| Muse Code | `MUSE_VERSION`, `MUSE_SHA256_*` | `api.meta.ai/muse-code/channels/muse-stable` and its release manifest | SHA-256 per arch, cross-checked with the manifest | +| bobshell (bob) | `BOBSHELL_VERSION`, `BOBSHELL_SHA256_*` | `bobshell2-version.txt` on IBM COS | SHA-256, cross-checked with the vendor `.tgz.sha256` | +| gh | `GH_VERSION`, `GH_SHA256_*` (hub only); also `GITHUB_CLI_VERSION` in `src/deploy/ci-runners/Dockerfile` | GitHub releases `cli/cli` | SHA-256 per arch, cross-checked with `gh__checksums.txt` | + +The pins live in `src/Dockerfile` (hub and spoke image) and +`src/Dockerfile.contributor` (containerized contributors), and the two must +agree: `bin/test_backend_smoke.sh` section A2/A3 fails when the claude or +codex pins differ. Pinning is deliberate ([#2903](https://github.com/hivecommons/hive/issues/2903)): +a floating `@latest` makes builds non-reproducible, and the per-arch digest +makes a tampered download fail the build instead of running. + +## Why a bump workflow + +Nothing else moves these pins. `.github/dependabot.yml` covers Go modules, +GitHub Actions, `FROM` tags and the proxy's npm tree, none of which reach an +`ARG *_VERSION` line. Left alone the pins drift until a user hits a wall, +which is what [#8417](https://github.com/hivecommons/hive/issues/8417) was: +Claude Code 2.1.226 refusing `claude-opus-5-5` six weeks after 2.1.280 shipped. + +Letting the CLIs update themselves at runtime is the wrong fix: it undoes the +reproducible, hash-checked build, the update is lost on every container +restart (the CLIs live in the image layer), agents on one hive end up on +different versions, and a TUI change reaches production with no test in +between while hive reads those TUIs (pane scraping, onboarding dialogs, +working-state text). The contributor path already writes +`autoUpdates: false` into `~/.claude.json` for these reasons. + +## What `.github/workflows/cli-pin-bump.yml` does + +Once a day (`23 5 * * *`) and on `workflow_dispatch`, one job per CLI checks +for a new release. The daily automation opens PRs only for **major or minor** +version changes. Patch-only releases (`X.Y.Z` -> `X.Y.W`, including suffixes +such as prereleases or agy's build id) are treated as current and skipped so +routine patch churn does not create PRs. To force a patch bump, dispatch the +workflow with `include_patch=true` (or run the script with +`HIVE_PIN_INCLUDE_PATCH=1`). + +For eligible major/minor changes, the job: + +1. **Resolve.** `src/scripts/cli-pin-bump.sh bump ` asks the CLI's + source of truth for the latest release and, for download-verified CLIs, + downloads every per-arch artifact and recomputes its digest. Where the + vendor publishes a digest (omp, gh, Muse, bobshell, the agy cask) the + computed value must match it or the job fails. A digest is never copied + from a page and never guessed: the script refuses to write anything that is + not a 64- or 128-hex-character value, and it validates every value before + the first edit so a Dockerfile is never left half-updated. +2. **Edit.** Both Dockerfiles are rewritten in place (the `ARG` lines only), + plus `src/pkg/config/dockerfile_contributor_test.go`, which asserts pi's + exact `ARG` line. +3. **Smoke before the PR exists.** The job builds `src/Dockerfile` for + linux/amd64 with the new pin and runs ` --version` inside the image + (for claude also an unauthenticated `claude --help`). A CLI whose install + layer or startup path broke never becomes a PR. +4. **Open one PR per CLI** on branch `cli-pin-bump/` against the base + branch (`v5` by default; the dispatch input `base` picks another). The PR + body carries the resolved `KEY=VALUE` provenance and the smoke transcript. + An open PR for the same CLI is refreshed rather than duplicated, and if it + already carries the same target version the job does nothing. + +Labels on a bump PR: + +- `security` - admits the PR through the v4 feature-freeze gate + (`.github/workflows/v4-freeze-gate.yml`), so a CLI fix can still land on a + frozen line. +- `dependencies`, `no-changelog` - the dependabot convention; a pin bump is + dependency churn and needs no changelog fragment. +- `needs-human` - added only for a **major** version change. Minor bumps follow + the repo's normal merge-on-green path; patch bumps are skipped unless an + operator explicitly forces one, except for patch-eligible CLIs (below). + +### Patch policy + +Most CLIs ship features on major/minor releases, so patch-only bumps are +skipped. **Claude Code is patch-eligible**: it ships new models as 2.1.x +patches (for example Sonnet 5.5 needs 2.1.284), so skipping patches left the +image unable to launch models Hive lists. `cli-pin-bump.sh` bumps patch +releases of the CLIs in `HIVE_PIN_PATCH_ELIGIBLE` (default `claude gh`; set it to +empty to restore the strict rule). Add a CLI there when it starts shipping +models in patches. + +### Model lists + +A pin change can leave Hive's model lists behind. Two layers cover it: + +- `src/scripts/check-cli-model-lists.sh` (self-test: + `test-check-cli-model-lists.sh`) fails when a model listed in + `src/scripts/cli-model-requirements.txt` (CLI, model id, first version that + accepts it) is missing from the allowlist of a CLI pinned at or above that + version, and when the "version pinned ... (X" / "matches codex X" comments in + `cli_models.go` differ from the Dockerfile pin. Add a requirements line when a + CLI release introduces a model. The check runs in the workflow's `selftest` + job on PRs touching the pins or lists, and its output goes in every bump PR. + It warns instead of failing until the lists are current; set + `HIVE_MODEL_CHECK_STRICT=1` to make drift fail. +- Each bump PR body carries a checklist for what cannot be automated: + allowlists/fallbacks, `static/index.html`, and `src/pkg/tokens/pricing.go`. +- For Claude, `.github/workflows/claude-model-freshness.yml` does those edits + weekly (#18754). It takes the Claude ids on OpenRouter's public catalogue + that are newer than the lists' newest of the same line (Fable, Opus, Sonnet, + Haiku; never Mythos, never an id OpenRouter is withdrawing) and probes each + with the pinned Claude Code, unauthenticated: the CLI prints an + `unrecognized_model` diagnostic for an id its model table does not know. + Recognised ids go into `claudePinnedCLIModels`, `claudeStaticModels`, + `CLAUDE_CLI_MODELS`, `static/index.html`, a requirements line at the pin, + and a `modelPrices` row from `pricetable --add` (same plausibility rules as + the price refresh). Everything else is listed under "needs a check" in one + PR on `bot/claude-model-freshness`, which carries `needs-human`. +- Gemini: `geminiPinnedCLIModels` is kept by hand. Neither `src/Dockerfile` + nor `src/Dockerfile.contributor` installs a Gemini CLI, so there is no + pinned binary to check ids against. The weekly + `static-model-freshness.yml` report still flags drift for it. +- Goose: out of scope. Its models depend on whichever provider an operator + configures, so there is no single list to keep fresh; the dashboard's ACP + probe asks the configured provider at run time. +- agy and omp: the running CLI already bounds what a hive can launch, because + the dashboard asks the local binary at run time (`agy models`, + `omp models --json`), so neither needs an allowlist. Their static floors + (`agyStaticModels` in `cli_models_agy.go`, `ompStaticModels` in + `cli_models_omp.go`, and the matching `AGY_CLI_MODELS` / `OMP_CLI_MODELS` + in `backends-tokens.js` and `static/index.html`) are **not** refreshed by CI, + because neither subcommand answers without a login. Checked on the pinned + binaries (agy 1.5.0, omp 18.22.0) with an empty `HOME` and no credentials: + `agy models` prints `Please sign in to view available models` and exits 1, + and `omp models --json` exits 0 with `{"models":[]}`. A key in the + environment would make omp list that one provider's catalogue, but that is + not what a signed-in account sees (the omp floor also carries OAuth-only + providers and a reasoning-effort map), so it is not used as a source. Both + floors are therefore **a manual capture**: sign in on a machine running the + pinned binary, run the two commands above, and copy the result into the Go + and JS lists in the CLI's own order. The agy floor is still the 1.1.18 + snapshot until someone does that. Neither list is guessed. +- Copilot and codex are tracked under + [#19028](https://github.com/hivecommons/hive/issues/19028). + +The PR then runs the normal gates. The docker workflow builds both images for +linux/amd64 and linux/arm64, where every hash-verified layer runs +`sha256sum -c` / `sha512sum -c`; the [backend smoke](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-smoke.md)'s +pinned lane picks the new CLI up on its next scheduled run. + +Credentials: the workflow opens PRs with `GITHUB_TOKEN` under +`pull-requests: write`, the same path `v5-topup.yml` uses, and pushes with +`TOPUP_PUSH_TOKEN` when that optional PAT is set (the bump never touches +`.github/workflows/`, so `GITHUB_TOKEN` can push it too). No new secret. + +## Running it by hand + +```sh +# what is pinned right now +src/scripts/cli-pin-bump.sh current codex + +# resolve the latest release and its digests without editing anything +src/scripts/cli-pin-bump.sh resolve goose + +# resolve + edit both Dockerfiles for major/minor changes; patch-only changes +# print CHANGED=false/SKIPPED=patch unless HIVE_PIN_INCLUDE_PATCH=1 is set +src/scripts/cli-pin-bump.sh bump claude +``` + +`resolve` and `bump` need `curl`, `jq` and `sha256sum`/`shasum`; set +`GH_TOKEN` to avoid the anonymous GitHub API rate limit. `apply ` +edits from a saved `KEY=VALUE` file with no network at all, which is what the +self-test (`src/scripts/test-cli-pin-bump.sh`, run by the workflow's +`selftest` job on any PR that touches the script or workflow) exercises. + +To bump one CLI on demand from the Actions tab, dispatch **CLI pin bump** +with `cli=`; `all` checks every pin. Leave `include_patch=false` for the +normal major/minor-only policy, or set `include_patch=true` to force a +patch-only bump PR. + +## Adding a CLI + +1. Add the `ARG` lines to both Dockerfiles following an existing + download-verified layer (version plus per-arch digest, `sha256sum -c` + before install, never a `curl | sh` installer). +2. Add a `resolve_` function and the `apply_cli` / `hub_version_arg` + cases to `src/scripts/cli-pin-bump.sh`, and a fixture line plus assertions + to `src/scripts/test-cli-pin-bump.sh`. +3. Add the name to the workflow's matrix and dispatch `options`, and to the + `CLIS` list in the script. + +## Not covered (yet) + +- The workflow does not diff each CLI's full model catalog before and after a + bump (catalogs baked into binaries cannot be read at build time; see Model + lists above). The dashboard's live probes (`codex app-server` model/list, + `agy models`, `omp models --json`) remain the source of truth on a running + hive; a static-catalog refresh, when one is needed, is a hand edit to + `codexStaticModels` in `src/pkg/dashboard/cli_models.go` and its + `static/index.html` mirror. +- No fast lane from a "this model needs version X" runtime error + ([#8418](https://github.com/hivecommons/hive/issues/8418)) to a dispatch of + this workflow. Dispatching by hand with `cli=` is the interim path. +- `KILO_CLI_VERSION` and `COPILOT_SDK_VERSION` are pinned but not bumped by + this workflow. +- The Plaud knowledge connector's default MCP command is pinned to + `npx -y @plaud-ai/mcp@0.3.14` by the `plaudMCPVersion` constant in + `src/pkg/knowledge/connector/plaud.go` (not a Dockerfile `ARG`: npx fetches + it at run time). It is bumped by hand; the constant's comment lists the + steps. See [knowledge-connectors.md](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-connectors.md#plaud-note-pro-voice-notes-type-plaud). diff --git a/docs/content/hive/compliance.md b/docs/content/hive/compliance.md new file mode 100644 index 0000000..33a7a70 --- /dev/null +++ b/docs/content/hive/compliance.md @@ -0,0 +1,621 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/compliance.md) during the docs build. Edit the canonical source in the Hive repository. + +# Compliance controls + +> **Hive is not certified for SOC 2, FedRAMP, ISO 27001 or any other +> framework, and makes no claim to be.** This page and the Compliance surface +> it describes help *your* control owners configure, verify and evidence +> *your* controls. Whether a Hive setting satisfies a control is decided by +> your organisation's policy and your auditor, not by Hive. This is the same +> position as the [general technical review](https://github.com/hivecommons/hive/blob/v5/src/docs/general-technical-review.md) and +> the [outreach policy](https://github.com/hivecommons/hive/blob/v5/docs/outreach-antispam.md). + +Hive's controls that matter to an auditor already exist but are spread +across many settings: owner/merger roles, the audit log, human-merge paths, +review gates, ACMM levels, the sentinel, sandbox confinement and credential +injection. The compliance registry (`src/pkg/compliance`, tracked by the +epic [#11077](https://github.com/hivecommons/hive/issues/11077)) presents +them as *controls*: it says which framework requirement each setting is +evidence for, and whether the hive is currently in the posture a framework +profile recommends. + +## What this is, and what it is not + +It **is**: + +- A **mapping** from framework controls (for example SOC 2 CC8.1) to the + Hive settings that implement them, shipped as data in + `src/pkg/compliance/profiles/*.yaml`. +- A **read-only evaluation** of the live config against each mapping's + recommended value: `meets`, `deviates`, `off`, or `not_covered`. +- A list of controls Hive **cannot** evidence, marked `not_covered` with the + reason, so nobody mistakes silence for coverage. + +It is **not**: + +- A certification, attestation or audit opinion. +- A second source of truth. Every mapping points at a setting that lives in + its own section (`review:`, `auto_merge:`, `sentinel:`, …). Changing a + posture means changing that setting. The registry never writes config. +- A replacement for GitHub branch protection, your identity provider, or + your organisation's incident-response, vendor-management and HR controls. + +## Review status and how to read control IDs + +The shipped profiles were checked against the published framework +numbering and titles in [#13578](https://github.com/hivecommons/hive/issues/13578): +SOC 2 uses the 2017 Trust Services Criteria (CC6.1–CC9.2), FedRAMP uses +NIST SP 800-53 Rev 5 identifiers, and ISO 27001 uses the **2022** Annex A +numbering (A.5.x–A.8.x, not the 2013 A.9–A.18 numbers). Control text on this +page is a paraphrase for orientation, never the framework's own wording; read +the cited publication for the authoritative requirement. + +- Each profile is a **subset** of its framework, not a full checklist. A + control missing from a profile is not "passed": it is simply not mapped. + Passing every row here says nothing about the controls that are absent. +- `ELIG-1` is a Hive-specific row, not a NIST control identifier. It marks + the US-persons/location eligibility conditions that FedRAMP assessors ask + about under AC-2 and AC-3. +- The mapping of a setting to a control is a plausibility judgement by the + Hive maintainers. It has not been reviewed by a person with audit + experience; have your own control owners and auditor confirm it before + relying on it. +- Hive is not certified or assessed under any of these frameworks. Exports are + configuration evidence for your own control owners, not an audit opinion. + +## Turning it on + +```yaml +compliance: + frameworks: [soc2-type2] # profile ids; default none + posture_checks: + interval: 1h # 5m..168h; unset = 1h + window_days: 30 # look-back of the merged-PR checks; 1..90, unset = 30 + history_days: 365 # posture-history retention; 30..1095, unset = 365 +``` + +Validation rejects unknown, malformed or duplicate framework ids and an +interval outside 5 minutes–7 days (or a window / history retention outside +the ranges above), so a typo cannot leave you believing a +profile is being evaluated when it is not. Shipped profile ids: +`soc2-type2`, `fedramp-moderate` and `iso27001-annex-a`. + +## Reading the status + +`GET /api/compliance/status` (merger or owner; see the +[API reference](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md)) returns one entry per control of every +selected framework: + +| Status | Meaning | +|---|---| +| `meets` | Every mapped setting matches the profile's recommendation. | +| `deviates` | At least one mapped setting is on but differs from the recommendation, or the settings disagree. | +| `off` | Every mapped setting is switched off or unset. | +| `not_covered` | The profile marks this control as outside what any Hive setting can evidence; the `rationale` says why. | + +Each covered control lists its settings with `setting_path`, `current`, +`recommended`, `evaluator` and a per-setting status. A `builtin: true` +setting is behaviour fixed in code today (for example audit retention); it +is reported so the gap is visible, and becomes an operator setting under the +epic. The response always carries the non-certification `disclaimer`, a +`summary` of counts, and the shipped profiles under `available`. + +Setting paths are YAML key paths of `hive.yaml` (a test walks the config +structs to prove each one exists), plus two documented namespaces: + +- `env.` — a process environment variable, for example + `env.HIVE_PROXY_INJECT_GH_AUTH` (proxy-side GitHub credential injection; + see the [security model](/docs/hive/security-model)). +- `audit.retention_days` — currently the audit log's fixed 90-day + maximum age (see [audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md)); a configurable floor is + planned. + +## The Settings → Compliance tab + +The framework and controls panels ship in +[#11080](https://github.com/hivecommons/hive/issues/11080); posture history, +evidence exports and attestations ship in +[#11081](https://github.com/hivecommons/hive/issues/11081) — see +[Using the Compliance tab](#using-the-compliance-tab). The tab has four +panels: + +1. **Framework profile** — select one or more frameworks (SOC 2 Type II, + FedRAMP Moderate, ISO 27001 Annex A; or none). The selection is + `compliance.frameworks`. +2. **Controls** — grouped by domain (Access control, Segregation of duties, + Change management, Logging & monitoring, Vulnerability management, + Incident response, Risk management, Data handling). Each row shows the + control id, the Hive setting(s) that implement it, current and + recommended value, status, and a link to the section that owns the + setting. Owner-only writes go through that section's existing endpoint. +3. **Posture checks** — continuous checks the hive runs against itself, with + pass/fail history (see the catalogue below). +4. **Evidence & attestations** — exports and owner attestations (see below). + +## SOC 2 Type II mapping + +Control text in the profile is a short paraphrase for orientation, not the +AICPA's wording; the authoritative criteria are the AICPA 2017 Trust +Services Criteria. The table below is generated from +`src/pkg/compliance/profiles/soc2-type2.yaml` — do not edit it by hand. +Regenerate with: + +```sh +python3 src/scripts/render-compliance-tables.py # rewrite in place +python3 src/scripts/render-compliance-tables.py --check # verify only +``` + +A Go test in `pkg/compliance` fails CI when the committed table and the +profile disagree. + + +| Control | Domain | Hive setting | Recommended | Evaluator | Notes | +|---|---|---|---|---|---| +| CC1.1 — Commitment to integrity and ethical values | Risk management | _not covered by Hive_ | — | — | Integrity standards, conduct reviews and remediation are organisational governance and personnel processes; no Hive setting can evidence them. | +| CC1.2 — Independent oversight of internal control | Risk management | _not covered by Hive_ | — | — | Board independence, expertise and oversight are organisational governance responsibilities outside the system Hive can observe. | +| CC1.3 — Structures, reporting lines, authorities and responsibilities | Segregation of duties | _not covered by Hive_ | — | — | Hive roles cover access to Hive, not the entity's governance structures, reporting lines or assignment of control responsibilities. | +| CC1.4 — Commitment to attract, develop and retain competent people | Risk management | _not covered by Hive_ | — | — | Recruitment, training, competency assessment and succession planning are organisational personnel processes outside Hive. | +| CC1.5 — Accountability for internal control responsibilities | Risk management | _not covered by Hive_ | — | — | Performance measures, incentives, discipline and accountability are organisational processes; Hive cannot evidence that they operate. | +| CC2.1 — Relevant, quality information supports internal control | Data handling | _not covered by Hive_ | — | — | Hive produces operational records, but cannot evidence the entity's information requirements, asset inventory, classification or data flows. | +| CC2.2 — Internal communication of control information | Risk management | _not covered by Hive_ | — | — | Internal communications, awareness training and confidential reporting channels are operated by the organisation, not by Hive settings. | +| CC2.3 — Communication with external parties | Risk management | _not covered by Hive_ | — | — | Communications with customers, regulators, auditors and other external parties are organisational processes that Hive cannot evidence. | +| CC3.1 — Clear objectives support risk identification and assessment | Risk management | _not covered by Hive_ | — | — | Defining business, reporting, compliance and system objectives and their risk tolerances is the operator's risk-management process. | +| CC3.2 — Identification and analysis of risks | Risk management | _not covered by Hive_ | — | — | Hive can expose technical findings but cannot evidence an entity-wide risk assessment, risk significance decisions or accepted residual risk. | +| CC3.3 — Consideration of fraud risk | Risk management | _not covered by Hive_ | — | — | Fraud-risk assessment, including incentives, pressures and rationalisations, is an organisational process outside Hive. | +| CC3.4 — Identification and assessment of significant change | Risk management | _not covered by Hive_ | — | — | Hive reviews repository changes but cannot evidence the entity's broader assessment of regulatory, business, leadership, vendor and technology change. | +| CC4.1 — Ongoing and separate evaluations of internal control | Logging & monitoring | `sentinel.enabled` | `true` | `equals` | Sentinel supplies ongoing security evaluation and required independent review supplies a separate evaluation of proposed repository changes. These are evidence inputs, not an entity-wide internal-audit programme. | +| CC4.1 — Ongoing and separate evaluations of internal control | Logging & monitoring | `review.require_approval` | `true` | `equals` | | +| CC4.2 — Evaluation and communication of control deficiencies | Logging & monitoring | _not covered by Hive_ | — | — | Hive can report findings, but cannot evidence management's evaluation, communication and tracking of control deficiencies to remediation. | +| CC5.1 — Control activities mitigate risks | Risk management | _not covered by Hive_ | — | — | Selecting entity-wide controls from assessed risks and deciding acceptable residual risk are organisational responsibilities outside Hive. | +| CC5.2 — General control activities over technology | Risk management | _not covered by Hive_ | — | — | Hive exposes controls over its own workflows but cannot evidence the entity's complete technology infrastructure, security-management and acquisition controls. | +| CC5.3 — Deployment of controls through policies and procedures | Risk management | _not covered by Hive_ | — | — | Establishing, assigning, performing and periodically reassessing organisation-wide policies and procedures is outside Hive's evidence. | +| CC6.1 — Logical access security over protected information assets | Access control | `dashboard.authorized_users` | `2` | `max_owners` | | +| CC6.1 — Logical access security over protected information assets | Access control | `env.HIVE_PROXY_INJECT_GH_AUTH` | `true` | `equals` | | +| CC6.2 — Registration and authorization of users before access is granted | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | On a hub-proxied hive the hub's Manage Access screen is the registration point and delivers this list; on a standalone spoke the list itself is the gate. Either way an empty list means no named-user allowlist exists. | +| CC6.3 — Role-based access, least privilege and segregation of duties | Segregation of duties | `dashboard.authorized_users` | `1` | `min_mergers` | | +| CC6.3 — Role-based access, least privilege and segregation of duties | Segregation of duties | `auto_merge.trusted_authors.enabled` | `false` | `equals` | | +| CC6.3 — Role-based access, least privilege and segregation of duties | Segregation of duties | `auto_merge.trusted_authors.require_github_permission` | `true` | `equals` | | +| CC6.4 — Physical access to facilities and protected information assets | Access control | _not covered by Hive_ | — | — | Hive is software running on infrastructure the operator chooses. Physical security belongs to the operator's hosting provider and facilities controls; no Hive setting can evidence it. | +| CC6.5 — Secure disposal of protected data and software | Data handling | _not covered by Hive_ | — | — | Media sanitisation and disposal are performed by the operator and its infrastructure providers; Hive cannot observe or evidence them. | +| CC6.6 — Protection against threats from outside system boundaries | Access control | `agent_sandbox.enabled` | `true` | `equals` | | +| CC6.7 — Restricted and protected transmission and removal of information | Data handling | `env.HIVE_PROXY_INJECT_GH_AUTH` | `true` | `equals` | Proxy credential injection keeps the GitHub credential out of agent processes, while the sandbox restricts the processes that may receive it. Operators remain responsible for transport and endpoint controls outside Hive. | +| CC6.7 — Restricted and protected transmission and removal of information | Data handling | `agent_sandbox.enabled` | `true` | `equals` | | +| CC6.8 — Prevention and detection of unauthorized or malicious software | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| CC6.8 — Prevention and detection of unauthorized or malicious software | Vulnerability management | `sentinel.disabled_behaviors` | `none` | `empty` | | +| CC7.1 — Detection of configuration changes that introduce vulnerabilities | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| CC7.1 — Detection of configuration changes that introduce vulnerabilities | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| CC7.2 — Monitoring of system components for anomalies | Logging & monitoring | `audit.retention_days` | `365` | `at_least` | Audit retention is currently fixed in code (90 days, size-rotated); the configurable audit.retention_days floor is tracked by the Compliance epic (hivecommons/hive#11077), so this control reports a deviation until it lands. Delegated relay work is covered by the relay_* rows in the audit log and the relay_audit_coverage posture check. | +| CC7.2 — Monitoring of system components for anomalies | Logging & monitoring | `review.post_comments` | `true` | `equals` | | +| CC7.3 — Evaluation of security events | Incident response | `escalation.disabled` | `false` | `equals` | | +| CC7.3 — Evaluation of security events | Incident response | `sentinel.enabled` | `true` | `equals` | | +| CC7.4 — Incident response | Incident response | _not covered by Hive_ | — | — | The incident-response programme is the operator's. Hive supplies tools such a programme can use (pause, hold labels, sentinel alerts, the audit log) but no setting can evidence that a programme exists or was followed. | +| CC7.5 — Recovery from identified security incidents | Incident response | _not covered by Hive_ | — | — | Backup, restore and disaster recovery are run by the operator (see the hub disaster-recovery guide); Hive has no setting that evidences a tested recovery. | +| CC8.1 — Authorization, testing and approval of changes | Change management | `review.require_approval` | `true` | `equals` | Whether an automated review satisfies "approved" is a decision for the organisation's own change-management policy, not for Hive. These recommendations describe the conservative posture in which every merge has an independent approval, CI evidence and a human on sensitive paths. | +| CC8.1 — Authorization, testing and approval of changes | Change management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| CC8.1 — Authorization, testing and approval of changes | Change management | `auto_merge.human_merge_paths` | `non-empty` | `non_empty` | | +| CC8.1 — Authorization, testing and approval of changes | Change management | `auto_merge.self_authored` | `false` | `equals` | | +| CC8.1 — Authorization, testing and approval of changes | Change management | `acmm_level` | `5` | `at_most` | | +| CC9.1 — Mitigation of risks from potential business disruptions | Risk management | `tool_approval.enabled` | `true` | `equals` | | +| CC9.1 — Mitigation of risks from potential business disruptions | Risk management | `acmm_level` | `5` | `at_most` | | +| CC9.2 — Vendor and business partner risk | Risk management | _not covered by Hive_ | — | — | Model providers, GitHub and the hosting platform are the operator's vendors. Assessing them is the operator's vendor-management process; Hive can only list which backends and gateways are configured. | +| A1.1 — Capacity monitoring and management | Logging & monitoring | _not covered by Hive_ | — | — | Infrastructure capacity measurement, forecasting and scaling belong to the operator's hosting and service-management controls. | +| A1.2 — Environmental protection, backup and recovery infrastructure | Risk management | `governor.backup.key_file` | `non-empty` | `non_empty` | A resolvable backup encryption key enables Hive's fail-closed encrypted backup path. The value is the effective key source the backup path uses (governor key_file, the default Secret or PVC mount, or the HIVE_BACKUP_KEY env fallback), not the raw key_file setting. It does not evidence backup scheduling, off-site storage, environmental protection or successful restoration; operators must supply that evidence separately. | +| A1.3 — Testing of recovery procedures | Risk management | _not covered by Hive_ | — | — | Hive provides backup and restore tooling but cannot evidence that the operator maintains or tests a business-continuity and recovery plan. | +| C1.1 — Identification and retention of confidential information | Data handling | _not covered by Hive_ | — | — | Information classification, confidentiality commitments and retention schedules are defined and operated by the organisation, not Hive. | +| C1.2 — Disposal of confidential information | Data handling | _not covered by Hive_ | — | — | Hive cannot determine which operator data is confidential or evidence its secure destruction across repositories, hosts and service providers. | +| PI1.1 — Quality information about processing objectives | Data handling | _not covered by Hive_ | — | — | Defining service-processing requirements, specifications and data semantics is the operator's product and service-management process. | +| PI1.2 — Complete and accurate system inputs | Data handling | _not covered by Hive_ | — | — | Hive cannot evidence completeness and accuracy controls for every input to the operator's in-scope products, services and reports. | +| PI1.3 — Controlled system processing | Data handling | _not covered by Hive_ | — | — | Processing specifications, error correction and complete processing records depend on the operator's in-scope systems, not Hive settings. | +| PI1.4 — Complete, accurate and timely output | Data handling | _not covered by Hive_ | — | — | Hive cannot establish or evaluate the output specifications, intended recipients and delivery controls of the operator's services. | +| PI1.5 — Complete, accurate and timely storage | Data handling | _not covered by Hive_ | — | — | Storage specifications, archival controls and complete storage-activity records belong to the operator's in-scope systems. | +| P1.1 — Notice of privacy practices | Data handling | _not covered by Hive_ | — | — | The organisation determines whether it is a data controller or processor and owns its privacy notice; Hive cannot evidence that notice. | +| P2.1 — Privacy choices and consent | Data handling | _not covered by Hive_ | — | — | Consent collection, withdrawal and purpose records are features of the operator's products and privacy programme, not Hive. | +| P3.1 — Collection consistent with privacy objectives | Data handling | _not covered by Hive_ | — | — | Hive cannot classify all personal information collected by the operator or determine whether each collection is necessary, fair and lawful. | +| P3.2 — Explicit consent before collection when required | Data handling | _not covered by Hive_ | — | — | Required consent and its timing depend on the operator's products, jurisdictions and privacy programme; Hive does not administer them. | +| P4.1 — Use limited to identified privacy purposes | Data handling | _not covered by Hive_ | — | — | Hive cannot determine the purposes for which the operator processes personal information or evidence purpose limitation. | +| P4.2 — Retention consistent with privacy objectives | Data handling | _not covered by Hive_ | — | — | Personal-information retention schedules and legal exceptions are organisational controls outside Hive. | +| P4.3 — Secure disposal of personal information | Data handling | _not covered by Hive_ | — | — | Hive cannot identify all personal information held by the operator or evidence its deletion across in-scope systems and service providers. | +| P5.1 — Data-subject access to personal information | Access control | _not covered by Hive_ | — | — | Data-subject authentication and access-request fulfilment are operated by the organisation's privacy programme, not Hive. | +| P5.2 — Correction of personal information | Data handling | _not covered by Hive_ | — | — | Hive cannot process data-subject correction requests or propagate corrections through the operator's in-scope systems and third parties. | +| P6.1 — Consented disclosure to third parties | Data handling | _not covered by Hive_ | — | — | The operator controls personal-information disclosures, purposes, recipients and consent; Hive cannot evidence those decisions. | +| P6.2 — Records of authorized disclosures | Logging & monitoring | _not covered by Hive_ | — | — | Hive's audit log covers Hive actions, not every authorized disclosure of personal information by the operator's in-scope systems. | +| P6.3 — Records of unauthorized disclosures | Logging & monitoring | _not covered by Hive_ | — | — | Hive cannot evidence a complete breach and unauthorized-disclosure register for the operator's systems and third parties. | +| P6.4 — Third-party privacy commitments and compliance | Risk management | _not covered by Hive_ | — | — | Contracting with and assessing vendors is the operator's privacy and vendor-management process. | +| P6.5 — Third-party notification of unauthorized disclosures | Incident response | _not covered by Hive_ | — | — | Vendor breach-notification commitments and the response to their reports are organisational and contractual controls outside Hive. | +| P6.6 — Breach notification | Incident response | _not covered by Hive_ | — | — | Determining notification obligations and issuing legally sufficient notices are responsibilities of the operator's privacy programme. | +| P6.7 — Accounting of personal information and disclosures | Data handling | _not covered by Hive_ | — | — | Hive cannot inventory all personal information held about a data subject or all disclosures made by the operator and its third parties. | +| P7.1 — Quality of personal information | Data handling | _not covered by Hive_ | — | — | Data-quality requirements and correction processes belong to the operator's in-scope products and privacy programme. | +| P8.1 — Privacy inquiries, disputes and compliance monitoring | Logging & monitoring | _not covered by Hive_ | — | — | Hive cannot evidence the operator's privacy complaint process, compliance reviews, remediation or disciplinary actions. | + + +A step-by-step SOC 2 operator guide, written for auditors and control +owners, is [SOC 2 control mapping](https://github.com/hivecommons/hive/blob/v5/src/docs/soc2-control-mapping.md); it maps auditor +questions to the fields of a PR's [review evidence bundle](/docs/hive/hub/review-evidence-bundle). +This page is the reference for what the registry evaluates. + +## FedRAMP Moderate mapping + +A **subset** of the NIST SP 800-53 Rev 5 Moderate baseline: the families AC, +AU, CM, IA, RA, SA and SI. Control text is a short paraphrase, not NIST's +wording; the authoritative text is NIST SP 800-53 Rev 5 and the FedRAMP +baseline. Relevant controls Hive cannot evidence (for example AC-17, AU-9, +CM-2, SC-7, SC-8, SC-28, CP-9, SR-*, PE-3 and PS-3) are listed `not_covered` +so silence is not read as coverage, as are external service providers (SA-9) +and location/citizenship eligibility (ELIG-1, a non-NIST identifier). IA-2 is informational: +authentication happens at GitHub or the hub, Hive only holds the allowlist. +Selecting this profile does not make a hive FedRAMP authorized, and Hive is +not a FedRAMP authorization boundary. Generated from +`src/pkg/compliance/profiles/fedramp-moderate.yaml`; do not edit by hand. + + +| Control | Domain | Hive setting | Recommended | Evaluator | Notes | +|---|---|---|---|---|---| +| AC-2 — Account management | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | The dashboard allowlist is the account roster; periodic review of it is the operator's process. | +| AC-2 — Account management | Access control | `dashboard.authorized_users` | `2` | `max_owners` | | +| ELIG-1 — Personnel eligibility by location or citizenship (not a NIST control) | Access control | _not covered by Hive_ | — | — | Hive cannot verify where a person is or their citizenship. Enforce eligibility at the identity provider and the hosting region; Hive only records who is on the allowlist. | +| AC-3 — Access enforcement | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | | +| AC-3 — Access enforcement | Access control | `auto_merge.trusted_authors.require_github_permission` | `true` | `equals` | | +| AC-5 — Separation of duties | Segregation of duties | `dashboard.authorized_users` | `1` | `min_mergers` | | +| AC-5 — Separation of duties | Segregation of duties | `auto_merge.self_authored` | `false` | `equals` | | +| AC-5 — Separation of duties | Segregation of duties | `review.require_approval` | `true` | `equals` | | +| AC-6 — Least privilege | Access control | `auto_merge.trusted_authors.enabled` | `false` | `equals` | | +| AC-6 — Least privilege | Access control | `agent_sandbox.enabled` | `true` | `equals` | | +| AC-6 — Least privilege | Access control | `env.HIVE_PROXY_INJECT_GH_AUTH` | `true` | `equals` | | +| AU-2 — Event logging | Logging & monitoring | `review.post_comments` | `true` | `equals` | Delegated relay work is covered by the relay_* rows in the audit log and the relay_audit_coverage posture check. | +| AU-2 — Event logging | Logging & monitoring | `audit.retention_days` | `365` | `at_least` | | +| AU-3 — Content of audit records | Logging & monitoring | `review.post_comments` | `true` | `equals` | Review verdicts are published as PR comments with the evidence; the audit log record format is fixed in code. | +| AU-6 — Audit record review and reporting | Logging & monitoring | `sentinel.enabled` | `true` | `equals` | | +| AU-6 — Audit record review and reporting | Logging & monitoring | `escalation.disabled` | `false` | `equals` | | +| AU-11 — Audit record retention | Logging & monitoring | `audit.retention_days` | `365` | `at_least` | Retention is fixed in code at 90 days today; the configurable floor is tracked by hivecommons/hive#11077, so this reports a deviation until it lands. | +| AU-12 — Audit record generation | Logging & monitoring | `sentinel.enabled` | `true` | `equals` | | +| AU-12 — Audit record generation | Logging & monitoring | `review.post_comments` | `true` | `equals` | | +| CM-3 — Configuration change control | Change management | `review.require_approval` | `true` | `equals` | Whether an automated review satisfies approval is the organisation's change-management policy; these values describe the conservative posture. | +| CM-3 — Configuration change control | Change management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| CM-3 — Configuration change control | Change management | `auto_merge.human_merge_paths` | `non-empty` | `non_empty` | | +| CM-3 — Configuration change control | Change management | `auto_merge.self_authored` | `false` | `equals` | | +| CM-5 — Access restrictions for change | Change management | `auto_merge.human_merge_paths` | `non-empty` | `non_empty` | | +| CM-5 — Access restrictions for change | Change management | `auto_merge.trusted_authors.require_github_permission` | `true` | `equals` | | +| CM-5 — Access restrictions for change | Change management | `dashboard.authorized_users` | `1` | `min_mergers` | | +| CM-6 — Configuration settings | Change management | `sentinel.enabled` | `true` | `equals` | | +| CM-6 — Configuration settings | Change management | `sentinel.disabled_behaviors` | `none` | `empty` | | +| IA-2 — Identification and authentication (organizational users) | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | Informational. Authentication is performed by GitHub OAuth or the hub; Hive only holds the allowlist of named users, so a non-empty list is the most it can evidence. | +| IA-5 — Authenticator management | Access control | `env.HIVE_PROXY_INJECT_GH_AUTH` | `true` | `equals` | Hive keeps the real GitHub credential out of agent processes; issuing, rotating and revoking credentials belongs to the operator and GitHub. | +| RA-5 — Vulnerability monitoring and scanning | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| RA-5 — Vulnerability monitoring and scanning | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| SA-11 — Developer testing and evaluation | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| SA-11 — Developer testing and evaluation | Vulnerability management | `review.require_approval` | `true` | `equals` | | +| SA-9 — External system services | Risk management | _not covered by Hive_ | — | — | Model providers, GitHub and the host are the operator's external providers; assessing them is the operator's vendor-management process. | +| SI-4 — System monitoring | Logging & monitoring | `sentinel.enabled` | `true` | `equals` | | +| SI-4 — System monitoring | Logging & monitoring | `escalation.disabled` | `false` | `equals` | | +| SI-4 — System monitoring | Logging & monitoring | `tool_approval.enabled` | `true` | `equals` | | +| SI-7 — Software, firmware and information integrity | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| SI-7 — Software, firmware and information integrity | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| SI-7 — Software, firmware and information integrity | Vulnerability management | `agent_sandbox.enabled` | `true` | `equals` | | +| PE-3 — Physical access control | Access control | _not covered by Hive_ | — | — | Hive is software on infrastructure the operator chooses; physical security belongs to the hosting provider. | +| PS-3 — Personnel screening | Access control | _not covered by Hive_ | — | — | Hiring and background screening are HR processes; no Hive setting can evidence them. | +| AC-8 — System use notification | Access control | _not covered by Hive_ | — | — | The dashboard does not present a configurable use banner; the notice belongs to the operator's identity provider or reverse proxy. | +| AC-17 — Remote access | Access control | _not covered by Hive_ | — | — | Remote access paths (VPN, bastion, reverse proxy) are operator infrastructure; Hive only exposes its dashboard allowlist. | +| AU-8 — Time stamps | Logging & monitoring | _not covered by Hive_ | — | — | Clock synchronization is a property of the host; no Hive setting evidences it. | +| AU-9 — Protection of audit information | Logging & monitoring | _not covered by Hive_ | — | — | Protection of the audit log files depends on host file permissions and backup controls outside Hive's settings. | +| CM-2 — Baseline configuration | Change management | _not covered by Hive_ | — | — | Baselines of the hosting environment are the operator's; Hive settings are not a full system baseline. | +| CM-7 — Least functionality | Change management | _not covered by Hive_ | — | — | Host and container hardening are outside what Hive settings can evidence. | +| CM-8 — System component inventory | Change management | _not covered by Hive_ | — | — | Hive does not maintain an authoritative inventory of host components. | +| CP-9 — System backup | Risk management | _not covered by Hive_ | — | — | Backup of hive state is an operator process; no Hive setting evidences it. | +| IA-8 — Identification and authentication (non-organizational users) | Access control | _not covered by Hive_ | — | — | Authentication of outside contributors is performed by GitHub and the operator's identity provider, not Hive. | +| IR-4 — Incident handling | Incident response | _not covered by Hive_ | — | — | Incident handling is an organisational process; Hive escalation is a signal, not an incident-response program. | +| IR-6 — Incident reporting | Incident response | _not covered by Hive_ | — | — | Reporting obligations and channels are the operator's. | +| SC-7 — Boundary protection | Access control | _not covered by Hive_ | — | — | Network boundaries are operator infrastructure outside Hive's settings. | +| SC-8 — Transmission confidentiality and integrity | Access control | _not covered by Hive_ | — | — | Transport encryption is terminated by operator infrastructure; Hive settings do not evidence it. | +| SC-28 — Protection of information at rest | Access control | _not covered by Hive_ | — | — | Disk and volume encryption belong to the host and storage provider. | +| SI-2 — Flaw remediation | Vulnerability management | _not covered by Hive_ | — | — | Patching of the host and dependencies is an operator process; Hive settings do not evidence it. | +| SI-3 — Malicious code protection | Vulnerability management | _not covered by Hive_ | — | — | Endpoint and malware protection are host-level controls outside Hive. | +| SR-2 — Supply chain risk management plan | Risk management | _not covered by Hive_ | — | — | Supply chain risk planning is an organisational document; Hive cannot evidence it. | +| SR-3 — Supply chain controls and processes | Risk management | _not covered by Hive_ | — | — | Supplier selection and controls are organisational processes. | +| SR-11 — Component authenticity | Risk management | _not covered by Hive_ | — | — | Hive settings do not verify component provenance; use the operator's artifact signing and provenance checks. | + + +## ISO 27001 Annex A mapping + +Selected controls of ISO/IEC 27001:2022 Annex A, covering policies and roles +(5), people (6), physical (7) and technological controls (8: access, secure +development, logging, change). Control text is a short paraphrase, not ISO's +wording; the authoritative text is the standard. Policy, supplier, incident +programme, continuity, screening and physical controls are `not_covered`. +Selecting this profile does not make a hive ISO 27001 certified. Generated +from `src/pkg/compliance/profiles/iso27001-annex-a.yaml`; do not edit by hand. + + +| Control | Domain | Hive setting | Recommended | Evaluator | Notes | +|---|---|---|---|---|---| +| A.5.1 — Policies for information security | Risk management | _not covered by Hive_ | — | — | Policies are organisational documents; Hive cannot evidence that they exist or were approved. | +| A.5.2 — Information security roles and responsibilities | Segregation of duties | `dashboard.authorized_users` | `non-empty` | `non_empty` | | +| A.5.2 — Information security roles and responsibilities | Segregation of duties | `dashboard.authorized_users` | `1` | `min_mergers` | | +| A.5.3 — Segregation of duties | Segregation of duties | `auto_merge.self_authored` | `false` | `equals` | | +| A.5.3 — Segregation of duties | Segregation of duties | `review.require_approval` | `true` | `equals` | | +| A.5.3 — Segregation of duties | Segregation of duties | `auto_merge.trusted_authors.enabled` | `false` | `equals` | | +| A.5.15 — Access control | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | | +| A.5.15 — Access control | Access control | `dashboard.authorized_users` | `2` | `max_owners` | | +| A.5.16 — Identity management | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | Hive holds the allowlist of named users; identity lifecycle is run at the identity provider. | +| A.5.18 — Access rights | Access control | `dashboard.authorized_users` | `non-empty` | `non_empty` | | +| A.5.18 — Access rights | Access control | `auto_merge.trusted_authors.require_github_permission` | `true` | `equals` | | +| A.5.19 — Information security in supplier relationships | Risk management | _not covered by Hive_ | — | — | Model providers, GitHub and hosting are the operator's suppliers; supplier assessment is the operator's process. | +| A.5.24 — Incident management planning and preparation | Incident response | _not covered by Hive_ | — | — | The incident process is the operator's. Hive supplies tools it can use (pause, hold labels, sentinel alerts, audit log) but cannot evidence the process. | +| A.5.25 — Assessment and decision on information security events | Incident response | `escalation.disabled` | `false` | `equals` | | +| A.5.25 — Assessment and decision on information security events | Incident response | `sentinel.enabled` | `true` | `equals` | | +| A.5.30 — ICT readiness for business continuity | Incident response | _not covered by Hive_ | — | — | Backup, restore and disaster recovery are run by the operator; no Hive setting evidences a tested recovery. | +| A.6.1 — Screening | Access control | _not covered by Hive_ | — | — | Screening and other HR controls are the organisation's; Hive cannot verify who a person is or where they are, including any geographic or citizenship eligibility rule. | +| A.7.2 — Physical entry | Access control | _not covered by Hive_ | — | — | Physical security belongs to the operator's hosting provider and facilities. | +| A.8.2 — Privileged access rights | Access control | `dashboard.authorized_users` | `2` | `max_owners` | | +| A.8.2 — Privileged access rights | Access control | `auto_merge.trusted_authors.enabled` | `false` | `equals` | | +| A.8.4 — Access to source code | Access control | `env.HIVE_PROXY_INJECT_GH_AUTH` | `true` | `equals` | | +| A.8.4 — Access to source code | Access control | `agent_sandbox.enabled` | `true` | `equals` | | +| A.8.4 — Access to source code | Access control | `auto_merge.human_merge_paths` | `non-empty` | `non_empty` | | +| A.8.7 — Protection against malware | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| A.8.7 — Protection against malware | Vulnerability management | `sentinel.disabled_behaviors` | `none` | `empty` | | +| A.8.8 — Management of technical vulnerabilities | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| A.8.8 — Management of technical vulnerabilities | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| A.8.9 — Configuration management | Change management | `sentinel.enabled` | `true` | `equals` | | +| A.8.9 — Configuration management | Change management | `acmm_level` | `5` | `at_most` | | +| A.8.15 — Logging | Logging & monitoring | `audit.retention_days` | `365` | `at_least` | Audit retention is fixed at 90 days in code today; the configurable floor is tracked by hivecommons/hive#11077, so this reports a deviation until it lands. Delegated relay work is covered by the relay_* rows in the audit log and the relay_audit_coverage posture check. | +| A.8.15 — Logging | Logging & monitoring | `review.post_comments` | `true` | `equals` | | +| A.8.16 — Monitoring activities | Logging & monitoring | `sentinel.enabled` | `true` | `equals` | | +| A.8.16 — Monitoring activities | Logging & monitoring | `escalation.disabled` | `false` | `equals` | | +| A.8.16 — Monitoring activities | Logging & monitoring | `tool_approval.enabled` | `true` | `equals` | | +| A.8.25 — Secure development life cycle | Change management | `review.require_approval` | `true` | `equals` | | +| A.8.25 — Secure development life cycle | Change management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| A.8.28 — Secure coding | Vulnerability management | `review.require_approval` | `true` | `equals` | | +| A.8.28 — Secure coding | Vulnerability management | `sentinel.enabled` | `true` | `equals` | | +| A.8.29 — Security testing in development and acceptance | Vulnerability management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| A.8.31 — Separation of development, test and production environments | Change management | `agent_sandbox.enabled` | `true` | `equals` | | +| A.8.32 — Change management | Change management | `review.require_approval` | `true` | `equals` | Whether an automated review satisfies approval is the organisation's change-management policy; these values describe the conservative posture. | +| A.8.32 — Change management | Change management | `auto_merge.required_checks` | `non-empty` | `non_empty` | | +| A.8.32 — Change management | Change management | `auto_merge.human_merge_paths` | `non-empty` | `non_empty` | | +| A.8.32 — Change management | Change management | `auto_merge.self_authored` | `false` | `equals` | | +| A.5.23 — Information security for use of cloud services | Risk management | _not covered by Hive_ | — | — | Cloud supplier governance is an organisational process. | +| A.5.28 — Collection of evidence | Incident response | _not covered by Hive_ | — | — | Forensic evidence handling is an organisational process. | +| A.8.3 — Information access restriction | Access control | _not covered by Hive_ | — | — | Data-level restriction inside the operator's systems is outside Hive's settings. | +| A.8.5 — Secure authentication | Access control | _not covered by Hive_ | — | — | Authentication is performed by GitHub and the operator's identity provider. | +| A.8.12 — Data leakage prevention | Access control | _not covered by Hive_ | — | — | Hive settings do not evidence data-loss prevention tooling. | +| A.8.13 — Information backup | Risk management | _not covered by Hive_ | — | — | Backup of hive state is an operator process. | +| A.8.20 — Networks security | Access control | _not covered by Hive_ | — | — | Network security is operator infrastructure. | +| A.8.21 — Security of network services | Access control | _not covered by Hive_ | — | — | Network service agreements are the operator's. | +| A.8.22 — Segregation of networks | Access control | _not covered by Hive_ | — | — | Network segregation is operator infrastructure. | +| A.8.23 — Web filtering | Access control | _not covered by Hive_ | — | — | Egress filtering is operator infrastructure. | +| A.8.24 — Use of cryptography | Access control | _not covered by Hive_ | — | — | Cryptographic key and transport management are outside Hive's settings. | +| A.8.26 — Application security requirements | Change management | _not covered by Hive_ | — | — | Requirements definition is an organisational process. | +| A.8.30 — Outsourced development | Change management | _not covered by Hive_ | — | — | Supplier oversight is an organisational process. | + + +## Posture checks catalogue + +Posture checks are continuous checks over what the hive actually *did*, not +just how it is configured +([#11079](https://github.com/hivecommons/hive/issues/11079)). While at least +one framework is selected, the dashboard runs every check once a minute after +start and then every `compliance.posture_checks.interval`; with no framework +selected the runner stays idle. Each check records a result with `status` +`pass`, `fail`, `skip` (the evidence is unavailable — for example no GitHub +client or no repos configured — so nothing was asserted) or `error` (the +evidence fetch failed), a short `detail`, the profile `control_ids` it +evidences and `evidence_refs` (PR URLs, config file paths, doc links) an +auditor can follow. Details never echo a secret value. + +| Check id | Passes when | Controls (SOC 2) | Evidence source | +|---|---|---|---| +| `non_author_review` | Every PR merged in the last `window_days` had an approving, change-requesting or commenting review from someone other than its author | CC8.1, CC6.3 | GitHub merged-PR search and reviews | +| `owner_not_auto_merge_author` | No dashboard owner (`dashboard.authorized_users` with the owner role) authored a PR that a bot merged in the window | CC6.3 | GitHub merged-PR search (merger is a bot) | +| `audit_retention` | The audit log's retention (`audit.retention_days`, today the built-in 90 days) is at least the strictest floor of the selected profiles (365 days for SOC 2 CC7.2) | CC7.2 | [Audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md#rotation-and-retention) | +| `agent_confinement` | Every enabled agent runs at tier T2 or better: T1 = credential-free sandbox, T2 = proxy-injected GitHub credential (`HIVE_PROXY_INJECT_GH_AUTH`), T3 = unconfined. The floor becomes `agent_backends.min_confinement_tier` under [#11077](https://github.com/hivecommons/hive/issues/11077) | CC6.6, CC6.1 | Agent and sandbox config, process env | +| `sentinel_enabled` | `sentinel.enabled` is on with no behaviour disabled and the sentinel label exists on every repo | CC6.8, CC7.1 | `sentinel` config, repo labels | +| `no_secrets_in_config` | No secret-looking value in `hive.yaml`, the dashboard overlay, the runtime config or the per-agent overlays (the log scrubber's token patterns, PEM blocks, and literal values under credential-named keys such as `*_token`; `$ENV` references and paths are fine) | CC6.1 | Config file scan (file and line only) | +| `dashboard_auth` | The dashboard is hub-proxied, enforces per-user login (`dashboard.authorized_users`) or requires the shared auth token | CC6.1, CC6.2 | `dashboard` config | +| `relay_audit_coverage` | At least one `relay_*` row was written to the audit log in the last 24h, or no relay connected in that window; fails only when relays connected but no `relay_*` row was written | CC7.2 | [Audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) (`/data/audit.jsonl`), hub relay connections | +| `hold_labels_exist` | The hive's hold label and the needs-human label exist on every repo, so a human can stop automation | CC8.1, CC7.3 | Repo labels | + +Results are appended to `/data/compliance-posture.jsonl`, so the history +survives restarts and upgrades; runs older than +`compliance.posture_checks.history_days` (and beyond a hard cap of 9000 runs) +are pruned. When a check goes from `pass` to `fail` the hive writes a +`compliance_posture_failed` [audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) entry naming the check, +its controls and the detail; manual runs are audited as +`compliance_posture_run`. + +- `GET /api/compliance/posture` (merger or owner) returns the catalogue, the + effective `interval`, `window_days` and `history_days`, and the `latest` + run. Add `?since=` (an RFC 3339 time, a `YYYY-MM-DD` date or a look-back + such as `168h`) for every run since then, oldest first (at most 1000, with + `truncated: true` when more matched). +- `POST /api/compliance/posture/run` (merger or owner) runs one pass now and + returns it; `409` when no framework is selected or a pass is already + running. + +A passing posture check is evidence that the hive behaved as configured over +the window; it is not an attestation that your organisation meets the +control, and it is not a certification. + +## Evidence exports and attestations + +Exports and attestations shipped in +[#11081](https://github.com/hivecommons/hive/issues/11081). Every endpoint +below is owner only (verified owner session), because the evidence names +owners, PRs and config locations. + +**Exports.** `GET /api/compliance/export?kind=&format=&since=&until=` +returns inline text (`Content-Disposition: inline`, never cached) for the +range `[since, until)` so dashboards can show exports without triggering +browser download permission prompts. Add `download=1` for an explicit +attachment outside the dashboard. `since` takes an RFC 3339 time, a `YYYY-MM-DD` date +or a look-back such as `720h`; `until` takes an RFC 3339 time or a +`YYYY-MM-DD` date meaning the end of that day. Without them the range is +the last 30 days. Every export is written to the +[audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) as `compliance_export` with its kind, format, +range and the `sha256` of the delivered file. + +| `kind` | Formats | Contents | +|---|---|---| +| `controls` | `json` (default), `md` | The control-mapping report: the evaluated status above, stamped with the hive id, generation time and each profile's name and version | +| `posture` | `json` (default), `csv` | Every posture run in the range, including its schedule/manual trigger and `triggered_by` identity, plus per-check series in JSON. The CSV has one `evidence` row per check result | +| `audit` | `json` | The audit log entries in the range, from the current file and rotated backups. Rotation is size-triggered, so `covered_from` reports the oldest entry actually found. If it is later than `since`, the log no longer holds the start of the range | +| `config` | `json` | The effective config with secrets redacted (the same redaction as the config export) and the `sha256` of exactly the `effective` bytes. Use the hash to tie a report to one configuration | +| `attestations` | `json` (default), `csv` | Attestations recorded in the range; CSV names the owner in the `attester` column | +| `bundle` | `json` | All of the above in one file | + +Every format carries export metadata: `kind`, the non-certification +`disclaimer`, `hive_id`, `source_system`, the authenticated `generated_by` +owner, `generated_at`, the `[since, until)` period, selected profile ids and +versions, attester identities found in that period, and source-retention +statements. `generated_by` records chain of custody for the download; it is +not itself an attestation. + +Every export also carries a SHA-256 manifest. JSON manifests hash the compact +JSON bytes (no HTML escaping, so `jq -c` reproduces them) of `meta` and each +included top-level evidence section. Markdown +appends a JSON metadata block whose manifest hashes the report before that +block and the compact metadata JSON. CSV starts with a `metadata` row followed +by `evidence` rows; its manifest hashes the compact metadata JSON and the +domain-only CSV (the kind-specific header and evidence rows, with LF line +endings). This excludes the manifest itself and avoids a self-referential +digest. The manifest travels inside the file it covers, so on its own it only +detects accidental corruption: anyone editing a row can recompute it. To tie a +file to what the hive actually handed out, each `compliance_export` audit entry +records `sha256=` of the exact delivered bytes; compare a file's digest +(`sha256sum`) against that entry. CSV metadata is also +available as named columns, including `profile_versions`, `attesters`, +`retention` and the exact compact `metadata` JSON used for its hash. CSV cells +that start with `=`, `+`, `-` or `@` are prefixed with `'` so a spreadsheet +does not run them as formulas. PDF output is not offered. Bulk review-evidence +bundles depend on the per-PR bundles from #11058 and will join the exports when +that lands. + +**Posture history.** `GET /api/compliance/posture/history?since=&until=` +returns the posture history for the range as one series per check: +`points` (`at`, `status`), status counts, `last_fail_at` and the latest +result with its detail and evidence refs. It covers at most the 1000 most +recent runs, with `truncated: true` when more matched. The Compliance tab +draws each series as a sparkline. + +**Attestation workflow.** An owner reviews the Controls panel for a +framework and records "reviewed on " with an optional +note. `POST /api/compliance/attestations` takes +`{"framework", "reviewed_on", "note"}`. The framework must be a shipped +profile id. `reviewed_on` must be a `YYYY-MM-DD` date that is not in the +future. The note can be at most 2000 characters. The attesting login comes +from the session, never from the body. Each attestation is written to the +audit log as `compliance_attestation`, so it is part of the same record the +exports draw from. A copy goes to `/data/compliance-attestations.jsonl`, +where it outlives audit-log rotation (the newest 5000 are kept). +`GET /api/compliance/attestations` (`?framework=` filters) lists them newest +first. An attestation records that a person looked. It is not a pass/fail +verdict and does not change any status. + +## Your organisation's policy must authorise automated review + +Hive can show that every merge had an independent review, that CI was green, +and that sensitive paths needed a person. It cannot decide whether an +**automated** reviewer counts as the approval your change-management policy +requires. That is your organisation's decision, written into its own policy +and accepted by its auditor. + +- If your policy requires a human approval on every change, configure for + it: `review.require_approval: true`, `auto_merge.self_authored: false`, + `auto_merge.trusted_authors.enabled: false`, an ACMM level of 5 or lower + (L5 is holdgated: agents open PRs, people merge), and human-merge paths for + anything sensitive. The SOC 2 profile's recommendations describe this + conservative posture. +- If your policy explicitly authorises automated review for some classes of + change, record that authorisation in the policy itself, keep the review + evidence (comments on the PR via `review.post_comments: true`, the audit + log, #11058 bundles), and expect the Controls panel to show `deviates` for + the settings you deliberately relaxed. A deviation you have authorised is + still a deviation from the profile; the profile does not know your policy. + +## Gaps Hive does not cover + +Some requirements cannot be met by any Hive setting, and the profiles say so +rather than implying coverage: + +- **Personnel eligibility (geography and citizenship).** Some frameworks and + contracts (for example some US public-sector or export-controlled work) + restrict + who may access systems or data by location or citizenship. Hive cannot + verify where an operator, contributor or model provider is, or who they + are. Restrict access at your identity provider and choose model backends + and hosting regions that meet the requirement. +- **Legal responsibility for agent actions.** An agent is not a person and + cannot be accountable. Every change an agent makes is the responsibility of + the people and organisation operating the hive. Name accountable owners + (`dashboard.authorized_users`) and keep a human on the merge decision + wherever your policy requires accountability. +- **Organisational, physical and infrastructure controls.** The SOC 2 profile + lists all 61 Trust Services Criteria. It marks criteria `not_covered` when + evidence must come from the operator or its providers: governance and HR, + entity-wide risk and communication processes, physical security, capacity, + recovery testing, data life-cycle and processing-integrity controls, and the + privacy programme. The generated table above gives the criterion-specific + reason instead of allowing an omitted criterion to look covered. FedRAMP + ELIG-1, SA-9, PE-3 and PS-3 and ISO 27001 A.5.1, A.5.19, A.5.24, A.5.30, + A.6.1 and A.7.2 are likewise explicit. + +## Related + +- [Security model](/docs/hive/security-model) — the layered controls these mappings + point at. +- [Audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) — the record exports and attestations draw from. +- [General technical review](https://github.com/hivecommons/hive/blob/v5/src/docs/general-technical-review.md) — the project's + statement that it holds no certification. +- [ACMM policy matrix](/docs/hive/acmm-policy-matrix) — what each autonomy level + allows. + +## Using the Compliance tab + +Open **Settings → Compliance** (merger or owner; read and read-write users +see a notice instead). A banner at the top repeats that Hive is not +certified — the tab maps your configuration to control requirements, nothing +more. + +**Framework profile.** One checkbox per shipped profile, with its version, +control count and a one-line description. Checking or unchecking stages +`compliance.frameworks`; the footer **Save & close** writes it through +`PUT /api/config/governor/compliance` (owner only; unknown or duplicate ids +are rejected before anything changes, and the change is audited as +`config_compliance`). Unchecking every box turns evaluation off. + +**Controls.** Every control of the saved selection, grouped by domain. Each +row shows the control id and title (hover the **i** for the requirement text +and citation), the implementing setting(s), current → recommended value, and +a `meets` / `deviates` / `off` / `not covered` pill. For each setting: + +- a boolean the owning section can write (`review.require_approval`, + `auto_merge.self_authored`, `auto_merge.trusted_authors.*`, + `sentinel.enabled`, `agent_sandbox.enabled`, `escalation.disabled`) gets an + inline toggle; +- any other setting with a Settings home (authorized users, required checks, + Sentinel behaviours) gets **Open setting**, which switches to the owning + tab without discarding staged edits; +- `env.*` settings, built-in behaviour and hive.yaml-only keys are labelled + as such and are read-only here. + +**Apply recommended** (per domain) opens a confirmation listing every +boolean it will change, `setting: current → recommended`, plus the deviating +settings it cannot change for you. Confirming stages those values. + +Toggles and Apply recommended only **stage** changes, marked `staged`, in the +owning section (Features, Security or Health). Nothing is written until +**Save & close**, which saves each section through its own owner-only +endpoint — exactly as if you had edited it on that tab. Statuses are +re-evaluated from the saved config the next time the tab opens. Non-owners +see the same panels read-only. + +**Posture checks** (owners only). One row per check: its control ids, a +sparkline of up to the last 60 results in the selected range (7, 30, 90 or +365 days), pass/fail/skip/error counts, the last result and when it ran, the +failing detail, the last failure time and links to the evidence (PRs, config +files, docs). **Run checks now** runs one pass through +`POST /api/compliance/posture/run` and refreshes the panel. + +**Evidence & attestations** (owners only). Pick an optional date range and +open any export in the table above. Each button renders the export in an +in-app viewer with copy support; it does not force a browser download. To +attest, choose a framework, the review date (default today) and a note, then **Record attestation**. A confirmation dialog shows +what will be written to the audit log under your login. Recorded +attestations are listed below the form, newest first. diff --git a/docs/content/hive/contributor-trust-and-roles.md b/docs/content/hive/contributor-trust-and-roles.md new file mode 100644 index 0000000..d5641e3 --- /dev/null +++ b/docs/content/hive/contributor-trust-and-roles.md @@ -0,0 +1,129 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md) during the docs build. Edit the canonical source in the Hive repository. + +# Contributor trust tiers and delegated agent roles + +Hive exposes two related but separate authorization models: + +- **ClankeR contributor trust tiers** on `/contribute` decide what a community contributor relay may claim. +- **Hub dashboard access roles** in **Manage Access** decide what an authenticated dashboard user may do to a hosted hive. + +They intentionally overlap in names only where the capability is similar. A contributor's AI CLI still runs with the contributor's own GitHub identity and scoped credential; taking a role never grants the spoke agent's secrets. + +## Contributor trust tiers + +Contributor profiles carry a `trust_tier` field. The current tier order is: + +| Tier | How it is reached | What it means | +| --- | --- | --- | +| `newcomer` | default self-registration | Rate-limited entry tier. | +| `contributor` | auto-promoted after 5 completed tasks with PRs | May claim default delegated roles such as `scanner`, `quality`, and `outreach`. | +| `trusted` | granted by an operator once a contributor reaches about 20 PR tasks; never automatic | May use higher-trust workflows and, with explicit grants, privileged delegated roles. Operators grant it with the tier dropdown on the contributor card under **Operations → Connected clankers**, which calls `PUT /api/contributors/{id}/trust`. | +| `merger` | maintainer/owner grant; it is not auto-promoted | May queue **other people's** PRs for Hive's auto-merge-on-green flow. | +| `advisor` | maintainer/owner grant | Advisory/invite tier; it is not ordered above `merger` for role-claim checks. | + +### Who changed a tier, when and why + +Every tier change — operator dropdown or `PUT /api/contributors/{id}/trust` +(optional `reason`), `POST /api/contributors/{id}/revoke`, the +newcomer→contributor auto-promotion, and the initial `newcomer` at +registration — appends `{tier, prev, at, by, reason, source}` to the +contributor record's `tier_history` (`by` is the operator login, +`hive:auto-promotion` or `hive:registration`; capped at the latest 50) and +writes an `audit.jsonl` event with `action: "contributor-tier-changed"` +carrying the same fields. Setting the tier a contributor already holds is a +no-op: no history entry, no audit line. `GET /api/contributors` returns +`tier_history`, and the Contributors view shows the current tier's provenance +("trusted since … · by … · reason") under and on hover of the tier chip. + +The stage lane re-reads the author's registry tier on every sweep, including +for PRs parked on `needs-rebase`/hold/excluded labels, so a promotion or +demotion reaches every open PR on the next pass instead of sticking to the +`role/*` label a previous pass wrote. + +The merger tier is deliberately **never allowed to own its own merge**. Queueing a PR as `merger` or `owner` is rejected when the authenticated dashboard user matches the PR author, and the auto-merge sweep re-checks the queued-by user before merging. + +Task leases are also the unit for staged runs. A staged run stays on the same +server-issued lease while Hive advances its `stage` through `spec`, `plan`, and +`implement`; each advance or retry mints a new `task_gen`, so stale relays are +fenced the same way as a reassigned task. Plain tasks have no stage. Staged work +is offered only to relays that declare the `run-stage` relay capability, so an +old relay can continue normal work but is not silently handed a staged run it +does not understand. + +### Audit attestation is voluntary + +A hive can *ask* contributors to share their relay's local audit record +(`hub.contribute_audit_share_request`, shown on `/contribute` before setup and +advertised on `auth_ok`). Sharing is opt-in, per hive, with +`hivectl hives set --share-audit ` (the +relay-side flag lands with the v6 follow-up to +[#13458](https://github.com/hivecommons/hive/issues/13458); until then no relay +sends `audit_share` and the hub is simply ready for it), and +never above the relay's capture level. Trust tier, role grants and admission do +**not** depend on it: a contributor who shares nothing is admitted exactly as +before. Making a minimum share level an admission condition is an open +governance question ([#13441](https://github.com/hivecommons/hive/issues/13441)) +and is not implemented. See +[contributor-relay.md](/docs/hive/contributor-relay#sharing-your-audit-record-with-a-hive---share-audit). + +## Merger capability and setup + +Operators grant merger from the hosted hive's **Manage Access** UI. The role sits between `read-write` and `owner` for dashboard access: + +`read` < `read-write` < `merger` < `owner` + +A merger inherits read/write dashboard access and can queue another contributor's PR. Queueing: + +1. approves the PR as the Hive GitHub App, +2. applies the configured auto-merge label, and +3. lets the auto-merge sweep merge once the PR is clean, non-draft, and green. + +Configure the label under `governor.labels.automerge`: + +```yaml +governor: + labels: + automerge: lgtm +``` + +The default is `lgtm`, matching the Kubernetes/Prow convention. Hive creates the label on demand if it does not already exist. + +Merger appears in contributor tier listings, profile badges, leaderboard tier filters, and the Credly milestone mapping so operators and contributors can see that it is a distinct maintainer-granted trust tier. + +## Clanker-requested policy for outside PRs + +Trust tiers describe contributors who already use the relay. The opt-in `project.issue_filter.reporter_trust.clanker_requested` policy covers the other side: untrusted people who open issues and PRs directly. Setup, config keys, and the exact behaviour are in [Steering outside PRs to the relay](/docs/hive/contributor-relay#steering-outside-prs-to-the-relay-clanker_requested); the dashboard controls are under **Settings → Labels → Reporter trust**. + +- **Issues:** the reporter-trust wait comment on an untrusted reporter's issue also points them at the relay's Basic setup guide. +- **PRs:** an open PR from an untrusted author that did not come through the relay (no contributor claim for that author, and not App-authored) is labelled `clanker-requested` (configurable) and shown as held, with a one-shot notice. +- **Human override:** removing the label releases the PR permanently; Hive never re-applies it. A PR resubmitted through the relay is never parked. +- **Non-goals:** this is not a branch-protection change. It does not block pushes, change required reviews, or alter GitHub permissions; it only holds Hive's own automation on the labelled PR, and a maintainer can still review or merge it by hand. + +## Delegated ClankeR agent roles + +A contributor relay can request an agent role with `HIVE_AGENT_ROLE` or the WebSocket `auth_response.role`. The `/contribute` UI labels this as **Acting as**. Operators may also assign a role directly from a contributor card; that owner assignment is shown as the active role and takes precedence over whatever the relay requested. + +The current role gates are: + +| Role | Minimum contributor tier | Extra grant required? | +| --- | --- | --- | +| `scanner` | `contributor` | No | +| `quality` | `contributor` | No | +| `outreach` | `contributor` | No | +| `ci-maintainer` | `trusted` | Yes | +| `sec-check` | `trusted` | Yes | +| `architect` | `trusted` | Yes | +| `supervisor` | never delegatable | N/A | + +Hive also checks that the corresponding agent is enabled and that the role is in the hive-wide allow-list: + +```yaml +hub: + contribute_delegatable_roles: + - scanner + - quality + - outreach + - ci-maintainer +``` + +If the list is empty, Hive uses the safe default: `scanner`, `quality`, and `outreach`. Privileged roles must be both listed here and granted on the contributor profile. The owner UI exposes these grants as chips/check boxes; assigning a privileged role auto-preserves the matching grant so reconnects keep working. diff --git a/docs/content/hive/fleet-health.md b/docs/content/hive/fleet-health.md new file mode 100644 index 0000000..17a82a8 --- /dev/null +++ b/docs/content/hive/fleet-health.md @@ -0,0 +1,631 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-health.md) during the docs build. Edit the canonical source in the Hive repository. + +# Fleet health: the verdict and remediation hints + +The hub's fleet page (`/fleet`) shows one health verdict per hive: a colored +dot, a small "WHY" chip next to the hive name that states the reason in one +phrase, and — for a non-green verdict that matches a known failure signature — +a one-line remediation hint that says what to do and where to do it. + +This page documents what each verdict state means, how the verdict is +computed, every remediation hint an operator can see, and how to go from a +symptom on the fleet page to a fix. + +For sustained congestion, [Guide flow-health diagnosis](https://github.com/hivecommons/hive/blob/v5/src/docs/guide-flow-health.md) +adds ranked, advisory root-cause recommendations using existing queue signals. + +The verdict answers one question: + +> **Does this hive have recent output back to its work source, for the ACMM +> level it is at?** + +"Recent" is a 12-hour window, owned by the hub — a spoke cannot widen it. +The verdict is computed on the hub at read time from signals the spoke +already reports in its heartbeat; it costs the spoke no extra work and no +extra GitHub API calls. + +This is a different check from +[dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md), which covers HTTP +probes of the dashboard URL. A hive can pass every route probe and still be +red here, because the verdict measures *output*, not *reachability*. + +It is also distinct from [fleet drift signals](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-drift-signals.md), the +per-hive deviation badges on My Hives (`heartbeat-stale`, `duplicate-spoke`, +`version-absent`, …): drift asks whether the row can be trusted and whether the +hive's configuration matches the fleet, while the verdict here asks whether the +hive is producing output. + +## The four states + +| State | Dot on `/fleet` | Meaning | +|---|---|---| +| **green** | ok | The hive has recent output for its level, or legitimately has nothing to produce (empty queue, or no agent is configured/on duty for the output its level is judged on). A green verdict **never** carries a remediation hint — a healthy hive gets no instruction. | +| **amber** | warning | The hive is working or intentionally quiet, but something needs an operator: all agents paused with work queued, output parked behind hold labels awaiting human review, an agent looping on a consent screen, an agent that will never be kicked, or a spoke lagging its release channel. | +| **red** | problem | Output is absent or impossible and the hive is expected to produce. The chip names the most fundamental cause it can prove (see [precedence](#precedence-the-most-fundamental-cause-wins)). | +| **unknown** | dashed ring | The hub cannot see enough to claim health: the hive is not reporting (offline), or the spoke is too old to send the signals the verdict needs. Unknown is never softened to green. | + +Two display states on `/fleet` are more specific than the verdict and take +over the row when they apply: + +- **parked** — every agent is deliberately paused or off-schedule and the + hive has no queued reason to run; shown as a parked chip instead of a + plain ok dot. A broken GitHub App still outranks parked: auth is broken + whether or not the hive is in use. +- **offline** — not reporting; the dashed offline dot replaces the WHY chip. + +## What "output" means at each ACMM level + +The verdict is banded by the hive's ACMM level, because different levels are +*supposed* to produce different things. Absence of output a level does not +produce is never a fault. + +| Level | Judged on | Healthy when | +|---|---|---| +| L1 (Inception) | nothing | Always green while reporting — no output is expected, and even precondition gaps (App, logins, cadences) are not faulted at L1. | +| L2 (Advisory) | the advisory digest | The advisory issue is fresh or aging. A spoke-reported posting error is red regardless of timestamps — the spoke proved the digest is wedged. | +| L3–L5 | writes to the work source: issue/PR creates, comments, and reviews | Any write in the last 12 hours. Merges are the human's job at these levels, so an unmerged PR is never a fault. Comments and reviews count: an agent triaging a backlog is producing real output. | +| L6 | merges | A merge in the last 12 hours. A create that never merges, with work still queued, is exactly the failure this level exists to catch. | + +Three gates soften "no output" into green before anything goes red: + +- **The queue gate.** If the actionable backlog (open issues + PRs the hive + could work) is zero, "no output" means *idle*, not broken: the chip reads + "queue empty — idle". +- **No writers on duty.** If no on-duty agent holds the write grant the level + is judged on (for example, a quiet-mode hive whose only running agent + cannot open issues or PRs), the hive is quiet by configuration, not + failing. When grant-holding agents exist but are paused or off-schedule, + the chip names them: "no output expected — create-capable agent(s) off: + …", so you don't have to hunt the agent rows for the correlation. +- **Hold-stale (amber, not red).** At L3–L5, when the write stream is stale + but work is parked behind hold labels awaiting human review, the agents + produced and then correctly stood down — the next move is a person's. + The chip reads "awaiting human review — N held for approval" and the row + goes amber instead of red. + +## Precedence: the most fundamental cause wins + +When output is absent, three preconditions explain why it was *impossible*: +the GitHub App must be green, at least one agent must be logged in, and at +least one agent must be running at cadence. The verdict checks these in a +fixed order and returns on the first match, so a deeper cause can never be +shadowed by a shallower one: + +1. **Inference gateway failing** — beats inferred App breakage. Runtime proxy + failures and Gateway Test report DNS/connect/5xx/auth/budget classes; the + chip says, for example, "inference gateway 'litellm' unreachable (dns)" + or "inference gateway 'litellm' rejected key (401)" and points at + Settings → Model Gateways. +2. **GitHub App broken** — applies when an actual App/auth problem is reported + or no gateway fault is present. The chip names the specific failure when the + spoke reported one (for example "GitHub App: repo-not-covered", which needs + a different remedy than a bad key). New spokes also send the App host, + App ID, installation ID, HTTP status, and error class, so token-mint 404s + render as an installation mismatch instead of a generic auth failure. +3. **Provider spending limit reached** — the model provider is refusing + calls; shown with the refused-call count when known. +4. **Budget exhausted / budget misconfigured** — the hive's own token budget + closed the gate (see [the budget signals](#budget-exhausted-vs-budget-misconfigured)). +5. **Blocked agents** — all blocked agents share one cause when possible: + "N agent(s) out of provider quota", "N agent(s) stuck at login — + re-login needed", "starting failed ×N: (last )", + "N agent(s) down — restart needed", "N agent(s) idle with work queued", + "agent restarts: NAME ×N/24h (reason)", or the generic "N agent(s) + blocked". Agent restart storms use the hub threshold + `HIVE_HUB_AGENT_RESTART_PROBLEM_THRESHOLD` (default `5`). Provider quota + is counted per named quota-exhausted agent unless the heartbeat explicitly + marks the provider limit as hive-wide. +6. **No agents running** (red) or **all agents paused** (amber — pausing is + operator choice, not an outage, but queued work will not move until + someone resumes them). +7. **Repo Issues disabled** — the repo's Issues tab is off (the GitHub + default on forks), so the advisory digest and every agent-filed issue + have nowhere to go. Nothing about the App, key, or agents is wrong; the + fix is the repo setting. +7. **Banded output freshness** — only now, with every precondition green, + can "no write in 30h (7 queued)" or "advisory stale" appear. + +Because the precondition reds return early, a budget-exhausted hive shows +"budget exhausted", never the downstream "no write in Nh" — the remedies are +entirely different. + +### Detector layering on top of the base verdict + +Three detector signals refine the base verdict without ever masking a harder +fault: + +- **Error-streak (red, re-explains).** When the base verdict is the + *generic* stale-output red and an agent has 3 or more consecutive failed + model calls, the chip is rewritten to "agent NAME model calls failing + (N consecutive) — pin a working model". It only ever re-explains the + generic red: precondition reds (App, provider, budget, login) keep their + reason, because they gate the output stream upstream of the model calls + and already name a more fundamental fix. +- **Consent-wedge and no-cadence (green → amber).** These demote a green + verdict only. Output may still look acceptable, but a named agent is + looping on a consent screen, or is enabled yet will never be kicked, and + only an operator can fix either. They never touch a red or amber verdict — + a harder fault stays the headline. +- **Channel-lag (green → amber).** A spoke tracking the `stable` release + channel that is 2 or more commits behind the channel head, and not + currently upgrading, ambers with "spoke lags its channel — N commits + behind stable". One commit behind is a rollout in flight and is ignored, + as is any hive where the channel signals are absent. See + [release channels](/docs/hive/release-channels). + +L1 (Inception) hives and non-reporting hives are exempt from all detector +layering: no output is expected there, so a configuration gap is not a +health fault. + +## Remediation hints: the signature → action table + +Every non-green verdict whose cause matches a known signature carries a +one-line hint, rendered under the WHY chip as "→ *action*", with an +**open** link when the hub can build a direct URL. A hint is only shown when +it is *specifically* true: causes without a precise fix (provider limit, +agents down, advisory stale, …) deliberately get none rather than a guess. + +| Cause | WHY chip you see | Verdict | Hint (action) | Where to do it | +|---|---|---|---|---| +| Inference gateway | "inference gateway 'litellm' unreachable (dns)" / "rejected key (401)" | red | Fix or retest the failing gateway (Settings → Model Gateways) | spoke dashboard settings | +| App broken | "GitHub App broken" or "GitHub App: \" | red | Install or repair the GitHub App for this repo | GitHub App settings (link resolved per cluster/forge) | +| Login stuck | "N agent(s) stuck at login — re-login needed" | red | Copilot device-flow login on the spoke dashboard | spoke dashboard `/login` | +| Budget exhausted | "budget exhausted — spend X of Y, kicks suppressed" | red | Raise or reset the budget limit (Settings → Budget) | spoke dashboard settings | +| Budget misconfigured | "budget limit misconfigured (N tokens) — agents halted, window reset will not help" | red | Raise or reset the budget limit (Settings → Budget) | spoke dashboard settings | +| Error streak | "agent NAME model calls failing (N consecutive) — pin a working model" | red | Pin a working model on the agent card | spoke dashboard agent card | +| Consent wedge | "agent(s) NAME stuck at Copilot consent — restarting in a loop" | amber | Complete the Copilot consent flow on the live pod dashboard | spoke dashboard | +| No cadence | "agent(s) NAME enabled but never kicked — set cadences" | amber | Set cadences on the agent card | spoke dashboard agent card | +| Hold stale | "awaiting human review — N held for approval" | amber | Review the needs-human queue | the repo's PR list (direct link) | +| Channel lag | "spoke lags its channel — N commits behind stable" | amber | Check auto-upgrade / force rollout | hub fleet version controls | + +## Detector semantics + +These are the signals behind the table above — what each one actually +measures on the spoke, and why a recovered hive clears its own alarm. + +### Budget exhausted vs. budget misconfigured + +`budget exhausted` means the governor is actively suppressing agent kicks +because the current budget window's tokens ran out. The chip shows "spend X +of Y" when the spoke reported the numbers, so you can tell at a glance +whether the hive is one rolled window away from healing or needs a bigger +limit. + +`budget misconfigured` is separated out because the remedy is unrelated: a +positive limit below 100,000 tokens cannot fund even one model call, so the +gate closed on the first kick and *nothing was ever spent* — waiting for the +window to roll changes nothing, and the operator must fix the number. This +is almost always a unit mistake (a limit of "50" that meant 50M). A limit of +zero is exempt: it is the documented way to disable budget tracking +entirely. + +### Agent error streaks + +An agent whose CLI keeps running turns while every model call inside them +dies produces no output and no token usage, yet its session stays up and +reads green. The spoke detects this from its own chat recordings: each kick +appends a user turn, and a successful call appends an assistant reply +carrying real token usage — so a run of trailing turns with no usage-bearing +reply *is* the consecutive-failure streak, attributed per agent. + +- The newest unanswered turn is ignored for its first 10 minutes (a kick + delivered moments ago legitimately has no reply yet). A reply that + explicitly recorded zero usage is a completed failure and counts + regardless of age. +- A streak whose newest failure is older than 24 hours is history, not a + live fault, and is not reported. +- The hub only rewrites the chip at 3 or more consecutive failures: one + failure is noise, three in a row is a pattern. + +The fix is to pin a working model on the agent's card in the spoke +dashboard. Note that when the agent is in automatic model selection, editing +config files cannot outrun the auto-picker — pin in the dashboard. + +### Consent wedge + +A Copilot CLI parked on an interactive consent screen looks alive to the +kick path's prompt check, so the kick path restarts the agent before sending +— which lands right back on the same consent screen. The result is a restart +loop (roughly once a minute) during which the agent reads green while doing +no work. + +The spoke reports an agent as consent-wedged when its kick path hit a +consent-screen restart **within the last hour**. A live loop refreshes the +stamp on every kick attempt; once you complete the consent flow on the +spoke dashboard, no new restarts occur and the agent ages out of the list +by itself. + +### No cadence + +An agent that is enabled and governor-kickable but appears in **no** mode's +cadence map is never timer-kicked; if it has also never been kicked by any +other path, it will sit green and idle forever until someone sets a cadence. +The detector names exactly that: enabled + kickable + no cadence configured +in any mode + never kicked. An explicit "off" or "pause" cadence entry +counts as configured — that is operator choice, not omission — and on-demand +or event-driven agents are excluded. Fix: set cadences on the agent card. +See [agent configuration](/docs/hive/agent-configuration). + +### Carry-forward: why a recovered hive clears its own alarm + +The three detector fields (error streaks, consent-wedged list, no-cadence +list) distinguish **"not measured"** from **"measured and clear"**: + +- A spoke that is too old to report them, or that just restarted and whose + collectors have not warmed up yet, sends *nothing* (null). The hub + **carries the last real measurement forward** — blanking it would hide a + live wedge for exactly the window an operator is most likely to be + looking. +- A spoke that measured and found nothing wrong sends an explicit **empty** + value (`{}` / `[]`), which **overwrites** the carried value on the hub. + +The practical consequence: you never need to clear these alarms by hand. +Complete the consent flow, set the cadence, or pin a working model, and the +spoke's next heartbeat carries a measured all-clear that clears its own +signal. Conversely, an alarm that persists across a spoke restart is not a +stale artifact — it is the last real measurement, held until the spoke +measures again. + +The scalar quadrant signals (budget spend/limit/exhausted, hold totals) +follow the same nil-means-not-measured rule: an old spoke that never sends +them is simply not judged on them. + +## Output-freshness telemetry + +For L3-L6 hives, newer spokes add optional heartbeat fields that explain stale write/merge streams: the most recent write-capable kick, the last kick disposition or skip reason, and how many queued items were deliberately deemed not writable. The hub treats missing fields as an old spoke and keeps the legacy red `no write in Nd (M queued)` behavior. When the fields are present, the verdict can distinguish a broken pipeline (recent write-capable kicks but no writes) from quiet-by-design states such as no due agents, budget-suppressed kicks, advisory-only operation, or work that agents intentionally declined as not writable. + +## Agent backend-auth health canary (#6558) + +The verdict above answers "is this hive producing output?" — but a hive whose +agents cannot even authenticate to their model backend produces nothing to +judge, and (before this canary) could sit at a stale green/unknown verdict +indefinitely. That is exactly what happened in #6500 (every agent hit +`You are not licensed to use Copilot`) and #6489 (a self-hosted inference +backend went unreachable): the fleet was fully down and nothing on the hub or +dashboard said so until a human happened to open a terminal. + +Each agent tracks its own `backend_auth` state, derived from the same +provider-error classifier the dashboard already uses +(`classifyProviderError` in `src/pkg/agent/pane_classify.go`): + +| Status | Meaning | +|---|---| +| `ok` | The agent's last completed turn succeeded, or it has never seen an auth-shaped provider error. | +| `unlicensed` | The provider rejected the account/token as not licensed to use this backend (the #6500 shape). | +| `token-expired` | The provider rejected a **credential**: a 401, bad credentials, or an invalid/expired key/token. Re-login is the remedy. | +| `forbidden` | An auth-class rejection whose cause the pane does not spell out — a bare `403 Forbidden` with neither the `not licensed` wording nor a recognised credential rejection (#6500). Reported honestly as "authorization denied, cause undetermined" rather than guessing an expiry: a re-login may not help (it can be an entitlement or org-policy denial). The pane is still relaunched onto a refreshed token in case a stale credential caused it. | +| `unreachable` | The inference backend itself could not be reached (the #6489 shape). | +| `quota` | The provider is refusing calls on quota grounds. | + +This is per-agent state, visible on the spoke dashboard's `/api/status` +(`backendAuthStatus` / `backendAuthSince` / `backendAuthLastError` on each +agent, omitted entirely when the agent is `ok`) and carried in the same +heartbeat the spoke already sends the hub. + +The hub aggregates per hive into `auth_health`, stored on the hive's registry +entry and returned from the fleet/My-Hives APIs alongside the health verdict: + +| `auth_health` | Meaning | +|---|---| +| `ok` | Every enabled agent's `backend_auth` is `ok`. | +| `degraded` | At least one, but not all, enabled agents are failing backend auth. | +| `down` | **Every** enabled agent has been failing backend auth for longer than the down threshold — default 15 minutes, configurable per hub via the `HIVE_HUB_AUTH_HEALTH_DOWN_THRESHOLD` env var (a Go duration string, e.g. `10m`). | + +On `/fleet` and My Hives, a hive whose `auth_health` is `down` renders its row +red (`problem`) regardless of what the base verdict would otherwise say, and +the expanded diagnosis block names the failing agents and their status — +this is deliberately checked before every other verdict signal, so a fleet +that is silently dead can never hide behind a stale green dot. + +**Notification.** When a hive's `auth_health` transitions from `ok`/`degraded` +to `down`, the hub sends the hive owner one Slack DM (the same +`HIVE_HUB_SLACK_BOT_TOKEN` + `slack_id` channel issue #4149's access-request +notifier uses — see `src/pkg/hub/auth_health_notify.go`). Exactly one DM per +down episode: the hub does not re-notify while the hive stays down, and only +notifies again after a genuine recovery to `ok` followed by a second, +independent outage. If no Slack token or no `slack_id` is on file for the +owner, the hub logs a structured `Warn` line instead of failing silently. + +This canary is intentionally a separate signal from the health verdict above, +not yet folded into its cause/remediation taxonomy (see [where the verdict +comes from](#where-the-verdict-comes-from-for-the-curious)) — the verdict's +precondition-red ordering and per-cause remediation hints are their own +well-tested surface, and merging `auth_health` into that taxonomy is left as +a deliberate follow-up rather than risking that machinery in the same change +that adds the canary. + +## Provider auth vs availability (#12611) + +[ADR-0024](/docs/hive/adr/0024-provider-credential-lifecycle) splits provider health +into two separate dimensions, so "not authenticated" never reads as +"provider unavailable" or the other way round. It is read-only status: hive +does not refresh, warm or share credentials. + +Each agent's backend-auth evidence gains `backendAuthRefreshable` (on +`/api/status` and in the heartbeat's `agents[]`). For Claude agents it is +`claude.HasUsableToken` over the agent's own credential: `true` when the +access token is live or the refresh grant behind it still is (a CLI restart +heals it), `false` when only a human login can. It is absent for every other +backend, because hive has verified no idle-refresh path for them. + +The spoke rolls its **enabled** agents up per provider (the agent's effective +backend) into a `providers[]` block, served on `/api/status` and sent in the +hub heartbeat. The hub stores it on the hive's registry entry as `providers`. +Disabled agents are skipped, so a provider nobody uses never becomes an +incident. Each entry: + +| Field | Meaning | +|---|---| +| `provider` | Effective backend name (`claude`, `copilot`, …). | +| `auth_state` | Worst auth state across the provider's enabled agents. | +| `availability_state` | Worst availability state across the provider's enabled agents. | +| `since` | Earliest `backendAuthSince` among affected agents (RFC3339), when known. | +| `evidence` | Status counts only, for example `2 of 3 enabled agents: token-expired×2`. Never pane text or credential material. | +| `next_action` | The one operator action for the worst condition. | +| `affected_agents` | Agents contributing a non-healthy state. | + +`backendAuthStatus` is mapped onto the two dimensions, not replaced: + +| Per-agent evidence | `auth_state` | `availability_state` | +|---|---|---| +| `ok` / empty | `usable` | `available` | +| `token-expired`, refreshable | `refreshable` | no evidence | +| `token-expired`, not refreshable or unknown | `needs-login` | no evidence | +| `unlicensed` | `needs-login` (next action: restore the seat) | no evidence | +| `forbidden` | `unknown` (cause undetermined, never convicted as a logout) | no evidence | +| `unreachable` | no evidence | `unavailable` | +| `quota` | `usable` | `quota-exhausted` | +| CLI sitting on a login prompt | `refreshable` or `needs-login` | no evidence | + +A dimension with no evidence from any agent is `unknown`, never silently +healthy. `store-inaccessible` and `rate-limited` are part of the vocabulary +but are not emitted yet: today's evidence cannot tell an unreadable store from +an absent one, and rate limits are transient and deliberately never change +`backendAuthStatus`. + +On `/fleet`, a hive with any provider that is not `usable` + `available` +shows a **providers** row in its diagnosis block (red for `needs-login`, +`store-inaccessible`, `unavailable` or `quota-exhausted`). The spoke +dashboard shows the same as a **Providers** chip in the header. Set +`providers.status.enabled: false` in `hive.yaml` to omit the block from both +`/api/status` and the heartbeat (default `true`). Old hubs ignore the block; +old spokes do not send it, which the hub reads as no signal. + +## Compliance rollup (#11083) + +A spoke with a compliance framework selected (`compliance.frameworks`) adds a +`compliance` block to its hub heartbeat: + +```json +{"compliance": {"frameworks": ["soc2-type2"], "posture": {"pass": 7, "fail": 1, "lastRun": "2026-10-01T12:00:00Z"}}} +``` + +`posture` is the summary of the spoke's latest posture-check run and is absent +until the first run. A spoke with no framework selected sends an empty block, +which clears whatever the hub stored; a beat with no block at all (an older +spoke, or a minimal upgrade beat) keeps the last stored profile. + +The hub Fleet table (`my-hives`) does not yet render this data: there is no +Compliance column in the hub UI. The stored profile is exposed only through the +API below, and only to the hive owner and hub admins: the compliance summary is +omitted from `/api/registry` entirely and from other members' rows in +`/api/saas/my-hives`. + +`GET /api/hub/compliance` (hub admin only) exports the fleet-wide aggregate: +spoke counts, per-framework spoke counts, total pass/fail with the overall +pass rate, and one row per spoke with a framework selected. Pass rates are +rounded to whole percent and are `null`/absent when no check has been decided. + +## Evidence summary heartbeat (#12114) + +Every spoke adds an `evidence` block to its hub heartbeat: a 90-day summary of +its [review evidence](/docs/hive/hub/review-evidence-bundle) bundles. Every bundle of a PR is +folded into one row and windowed on PR open time with the same +`evidence.FoldPRs` behind `GET /api/evidence/summary` (#12516), so a PR with a +live and a backfilled bundle counts once, with the live verdicts and the +forge outcome: + +```json +{"evidence": {"verdicts_90d": 30, "false_approve_90d": 2, "false_block_90d": 3, + "merged_90d": 12, "reverted_14d_90d": 1, "automerge_self_authored": false, + "reviewer_families": ["claude", "gpt"], "author_families": ["gpt"], + "calibration": [{"n": 4, "bad": 1}, {"n": 0, "bad": 0}, {"n": 0, "bad": 0}, + {"n": 0, "bad": 0}, {"n": 6, "bad": 0}, {"n": 20, "bad": 4}]}} +``` + +- `false_approve_90d` — approve verdicts on PRs later reverted or followed up + within 14 days of merge; `false_block_90d` — blocking verdicts on PRs that + were merged anyway; `reverted_14d_90d` — merged PRs reverted or followed up + within 14 days. +- `calibration` — six reviewer-confidence buckets (bucket `i` covers + `[i/6, (i+1)/6)`); `bad` counts verdicts that were a false approve or false + block. +- `automerge_self_authored` — `auto_merge.self_authored` at the hive's ACMM + level (`AutoMerge.SelfAuthoredAutoMergeAllowed`). +- `reviewer_families` / `author_families` — model families (`claude`, `gpt`, + …) seen on verdicts and agent-authored PRs; unknown models are omitted. +- Fleet-panel aggregates (#12370), each optional and omitted when the spoke + has nothing to report: `outcomes_by_author_kind` (`human`/`agent`/`bot` → + `{n, merged, reverted}` PRs, `reverted` ⊆ `merged`), `write_counters` + (intent tier → `{attempted, blocked}` agent writes seen by the proxy since it + started — not a 90-day window), and `shadow_gate` (`review_gate` / `intent` + → `{held, passed}`, each `{n, merged, reverted}`: what the shadow gate would + have done versus how the PR turned out). A spoke predating #12370 sends none + of them and the hub shows "not reported", never zero. +- `time_to_merge` ([#12464](https://github.com/hivecommons/hive/issues/12464)) + — `{median_s, n}`: the median time from PR opened to merged, in seconds, + over the `n` merged PRs that recorded `merge.opened_at`. Omitted when no + merged PR in the window recorded it (and by older spokes); the hub shows + "not reported", never zero. The hub reports the median of hive medians per + ACMM level (see [review evidence](/docs/hive/hub/review-evidence-bundle#median-time-to-merge-per-autonomy-level)). +- `windows` ([RFC #12062](https://github.com/hivecommons/hive/issues/12062)) — + the same counts (verdicts, false approves/blocks, merged, reverted, + calibration, author-kind outcomes, shadow gates, time to merge) re-counted over trailing + windows keyed `24h`, `7d` and `30d`, so the hub evidence view can switch + between windows. The field names keep their `_90d` suffix for wire + compatibility; `write_counters` (lifetime) and `automerge_self_authored` + are not repeated. A spoke predating windows sends none and the hub lists it + as "not reported for this window" when a shorter window is selected. +- `hive_state` — the spoke's 24 h / 7 d hive state trends + ([#12339](https://github.com/hivecommons/hive/issues/12339)): per window + (`24h`, `7d`) `samples`, `coverage_hours`, median/p90 `queue_issues`, + `queue_prs` and `queue_hold`, `sla_violation_rate`, `agent_idle_ratio`, + `kicks_per_day` and `tokens_per_day`. Omitted when the spoke has no snapshot + in the last 7 days. See + [Hive state time series](https://github.com/hivecommons/hive/blob/v5/src/docs/strategy-lab.md#hive-state-time-series). + +The hub clamps every count (subset counts never exceed their total), caps and +de-duplicates the family lists, bounds `hive_state` (ratios to `[0, 1]`, +coverage to the window, p90 never below the median), and stores the result with the other per-hive +quadrant inputs. A beat without the block (an older spoke, a minimal upgrade +beat, or a spoke whose evidence directory was unreadable that cycle) keeps the +last stored summary. Reporting only: nothing here gates a merge. + +## Fleet quadrant + +The **Fleet quadrant** card on the hub dashboard (and the kite in each hive's +Quadrant column) scores every hive on four axes — Trust, Productivity, +Satisfaction, Efficiency — from 0 to 100. The rules are deliberately simple so +a reader can check any number by hand: + +- **Every criterion maps to 0–100 on a fixed, named curve.** Scores are + absolute, not ranks: a hive's Trust does not change because a different set + of hives is in view. The curves are the `curve*` constants in + `pkg/hub/quadrant_curve.go`; the table below is their documentation. +- **An axis is the weighted mean of its *measured* criteria only.** A + criterion whose input the spoke has not reported (or whose sample is too + small to be honest) is listed as *not measured yet* with the reason, and is + left out of the average — it is never scored 0. An axis with no measured + criterion is unscored and draws collapsed to the centre of the kite with a + "—". +- **The fleet card is the per-axis median across the *active* hives** — + assigned (not an unassigned `available-*` placeholder slot) and online (the + same heartbeat-staleness flag the table's status column shows). The header + names that population ("47 active hives · 54 offline or unassigned + excluded"); a hive that is not reporting has nothing to say about the fleet, + and counting it would turn its silence into zeros. Per axis the median is + over the active hives that *measured* the axis, and each axis tile says so + ("47 of 61 measured"); a hive with no measured criterion on an axis never + enters that axis as a zero. A median cannot be dragged by one runaway hive + the way the previous fleet mean could. Each hive's `delta` is against that + same active-hive median. +- **The ⓘ beside each axis label** opens the same explainer on the fleet card + and in the per-hive hover: *What this covers* (each criterion with its + current value, sub-score and weight, or its not-measured reason), *How it's + scored*, *What good looks like* and *What ours shows*. Under the fleet glyph + there is one plain line per scored axis, weakest first — "Productivity 26: + median over 47 of 61 hives · merges per active repo per week 0.5 + merges/repo/week (47 hives) · …" — and an axis at or below 50 also names the + criterion with the lowest median score, so a 0 is never shown without the + fact that produced it. The per-hive hover keeps the single line for its + weakest axis. + +Weights: ×3 is the criterion the axis is named for, ×2 a major signal, ×1 +supporting. "Measured when" states the input and its minimum sample. Linear +curves interpolate straight between worst and best; log curves interpolate on +log₁₀ so an order of magnitude is worth the same anywhere on the scale. Values +past either end clamp. + +| Axis | Criterion | Input | Curve (0 → 100) | Weight | Measured when | +|---|---|---|---|---|---| +| Trust | Reverted within 14 days | heartbeat `evidence.reverted_14d_90d / merged_90d` | linear 10% → 0% | ×2 | ≥10 merges with evidence | +| Trust | Approved then fixed by a human | `evidence.false_approve_90d / verdicts_90d` | linear 10% → 0% | ×2 | ≥10 reviewer verdicts | +| Trust | Autonomy level | ACMM level | linear L1 → L6 | ×2 | always | +| Trust | Self-merge delegated | App may merge its own PRs | yes = 100, no = 0 | ×1 | setting reported | +| Trust | Merge acceptance | merged / (merged + rejected) 90d | linear 50% → 100% | ×1 | ≥4 agent PRs reached a verdict | +| Trust | Merges with evidence | `evidence.merged_90d / prs_merged_90d` | linear 0% → 100% | ×1 | PR counts and evidence reported | +| Trust | Agent writes blocked at the boundary | Σ `evidence.write_counters` blocked / attempted | linear 20% → 0% | ×1 | ≥10 proxied writes | +| Trust | Org repos enrolled | enrolled / org repo count | linear 0% → 100% | ×1 | *not yet* — spokes do not report the org count | +| Productivity | Merges per active repo per week | Σ `repo_activity[].merges` / weeks / active repos; falls back to org-wide `prs_merged_90d` per enrolled repo | log 0.1 → 10 per week | ×3 | PR counts reported | +| Productivity | Contributor-relay tasks (7d) | `tasks_completed_7d` | linear 0 → 20 | ×1 | relay reported | +| Productivity | Contributors active | active / enrolled contributors | linear 0% → 100% | ×1 | contributors reported | +| Productivity | Finds its own work | scanner-sourced vs human-filed | yes = 100, no = 0 | ×1 | merges or PR counts reported (a setting alone must not score the axis) | +| Productivity | Items waiting on a human | hold labels + plans awaiting review | linear 20 → 0 | ×1 | queues reported | +| Productivity | Items past SLA | `sla_violations` | linear 10 → 0 | ×1 | SLA counts reported | +| Productivity | Time to merge | median open → merge | log 14 days → 0.5 day | ×2 | *not yet* — spokes do not report it | +| Efficiency | Tokens per merged PR | tokens/day × 90 / `prs_merged_90d` | log 20M → 100k | ×3 | ≥5 merges and a token trend | +| Efficiency | Token burn rate | budget window or `hive_state.last_7d.tokens_per_day` | log 10M → 100k per day | ×1 | hive is shipping | +| Efficiency | Agent PRs rejected | rejected / (merged + rejected) 90d | linear 50% → 0% | ×1 | ≥4 agent PRs reached a verdict | +| Efficiency | Merged PRs per agent (90d) | `prs_merged_90d` / agents | linear 0 → 10 | ×1 | agents configured | +| Efficiency | Agent time idle (7d) | `hive_state.last_7d.agent_idle_ratio` | linear 100% → 0% | ×1 | ≥6 hive-state samples | +| Efficiency | Cost per merged PR | spoke `GET /api/launch-cost` | log $100 → $1 | ×2 | *not yet* — stays on the spoke, not in the heartbeat | +| Satisfaction | Swarm blocks lifted by a human | `evidence.false_block_90d / verdicts_90d` | linear 10% → 0% | ×2 | ≥10 reviewer verdicts | +| Satisfaction | SLA kept (7d) | 1 − `hive_state.last_7d.sla_violation_rate` | linear 0% → 100% | ×1 | ≥6 hive-state samples | +| Satisfaction | Time to lift a hold | median hold → lift | log 7 days → 6 hours | ×1 | *not yet* — not reported | +| Satisfaction | Contributors who come back | relay users who return | linear 0% → 100% | ×1 | *not yet* — not reported | +| Satisfaction | Direct feedback on agent output | thumbs up share | linear 0% → 100% | ×2 | *not yet* — no feedback signal exists; a thumbs up/down on agent output would feed it | + +Why Satisfaction used to read "—" for the whole fleet: it had a single +criterion (human-override rate) that needed ten verdicts *and* a five-hive +percentile population, so a fleet where most spokes had not yet shipped the +evidence heartbeat was declared "too small" everywhere. It is now scored for +any hive that reports ten verdicts or six hive-state samples, and where it is +still unscored the explainer says exactly which input is missing. + +Reading the merge-throughput curve: it is logarithmic from 0.1 to 10 +merges per active repo per week, so 0.1/week (one merge a quarter) scores 0, +0.5/week scores 35, 1/week 50, 3/week 74 and 10/week 100. A hive shipping +0.5 merges/repo/week is therefore a 35 on the headline criterion, not a 0 — +a Productivity 0 on the fleet card used to come from counting silent hives, +not from this curve. + +Why Productivity used to read 0 for the whole fleet while the card's own +line said the median hive merged 0.5 merges/repo/week across 47 hives: the +median ran over every row in the view (101, including 44 unassigned +placeholders and 10 offline hives), and "Finds its own work" was always +measured, so a hive that had reported nothing else still scored Productivity +0 from that one setting. 54 zeros out of 101 made the median 0. The +population is now the active hives only, and work source is unmeasured until +the hive reports merges or PR counts. + +The quadrant is reporting only: it reads the heartbeat evidence summary +(read-only, see above) and never feeds a merge decision. + +## Troubleshooting: symptom → hint → fix + +| Symptom on `/fleet` | What it means | Fix, and where | +|---|---|---| +| "GitHub App broken" / "GitHub App: repo-not-covered" | The hive cannot authenticate to its repo, or the App is installed but this repo is not selected | Install or repair the App; for repo-not-covered, add the repo to the App installation. Follow the row's **open** link, or see [GitHub App setup](/docs/hive/integrating-with-hive/github-app-setup) | +| "GitHub App N on HOST: installation M not found (404) …" | The spoke can identify the App/host it used, but GitHub did not find that installation for the App on that host | Reinstall the App for the target account, or fix `github.app_id`, `github.installation_id`, or the GitHub Enterprise host | +| "GitHub App: repo-moved" | The App installation is healthy, but it covers this hive's repositories under a **different account** — they were transferred to another org | Point the hive's configured organization at the account named in the message. Do **not** add the repo to the old org's installation: it has left that account, so there is nothing there to add | +| "provider spending limit reached — N refused calls" | The model provider is refusing calls on billing/limit grounds | Raise the provider's spending limit or wait for it to reset (provider console — no hint link) | +| "budget exhausted — spend X of Y, kicks suppressed" | The hive spent its window's tokens; the governor halted kicks | Raise the limit in the spoke dashboard (Settings → Budget), or wait for the window to roll | +| "budget limit misconfigured (N tokens) …" | The limit is too small to fund one model call — likely a unit mistake | Fix the number in Settings → Budget. Window reset will **not** help | +| "N agent(s) stuck at login — re-login needed" | Every blocked agent is wedged at a login prompt | Run the Copilot device-flow login on the spoke dashboard `/login` | +| "N agent(s) out of provider quota" | Agents hit per-account model quota | Wait for quota reset or change the account/model on the agent cards | +| "N agent(s) down — restart needed" | Agent sessions failed or died | Restart the agents from the spoke dashboard | +| "starting failed ×N: REASON (last AGE ago)" | The spoke has a current launch failure, even if it has not reached the blocked threshold yet | Follow the named reason (for example login, missing CLI, rejected key, or no prompt); restart only after fixing that cause | +| "N agent(s) idle with work queued" | Sessions are alive but agents sat past the idle threshold with work available | Kick the agents or review their schedules — this is not a restart problem | +| "agent restarts: NAME ×N/24h (reason)" | One agent has been relaunched at least the configured threshold within the recent window | Use the `/fleet` reset button next to the restart chip before troubleshooting; the hub records a reset marker and asks the spoke to zero its counter on the next heartbeat so recurrence is visible | +| "agent restarts: NAME ×N/24h **(login token refreshed)**" | The token-triggered restart: the agent sits at a login prompt while a valid shared credential exists, so hive relaunches the CLI to nudge it into picking the credential up | Guarded by a quiet-output window so hive does not restart an agent that is still producing pane output; then bounded at three consecutive attempts. After that hive stops and writes the reason into the agent's error line instead ("still at a login prompt after 3 restarts…"). Read that line — it names which credential file is the problem. **A count in the hundreds means the cap was not holding** ([#6578](https://github.com/hivecommons/hive/issues/6578), fixed): the give-up latch was being cleared by the boot pane of its own restart. These agents are blocked on a **human** device-flow login, which no number of restarts can supply — log in on the spoke dashboard | +| "no agents running" | Agents are expected on but none are running | Start/resume agents on the spoke dashboard | +| "all agents paused — resume to produce output" (amber) | Every agent is operator-paused while work is queued | Resume agents when you want the queue to move — deliberate pause is respected, not faulted | +| "repo Issues disabled — advisory/issues have nowhere to go" | The repo's Issues tab is off (common on forks) | Enable Issues in the repo's settings on your forge | +| "advisory stale" / "advisory posting failing" | The L2 output — the advisory digest — is old, or the spoke reported a posting error | See [advisory digest staleness](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory-staleness.md) | +| "pipeline broken — write-capable kick … but no writes" | Kicks are reaching write-capable agents, but no work-source writes are appearing | Check the kicked agent logs and write permissions on the spoke dashboard | +| "nothing to write — governor idle since … because …" | The governor is intentionally idle (for example no due agents), so stale writes are not a broken pipeline | Review schedules only if you expected an agent to be due | +| "advisory-only — …" | The hive is in an advisory-only band/path, so writes are not expected from that activity | Nothing, unless you intended L3+ write behavior | +| "nothing writable — N queued deemed not writable" | Agents classified queued items as held or not writable and stood down | Review the queued/held items; no restart is implied | +| "no write in Nh (M queued)" / "no create output" | Older spoke or no freshness telemetry: preconditions are green but the write stream appears stalled | Check agent activity and logs on the spoke dashboard; if an error-streak chip appears instead, follow that hint first | +| "no merge in Nh (M queued)" (L6) | PRs are being created but nothing merges | Check merge-agent grants and required checks on the queued PRs | +| "agent NAME model calls failing (N consecutive) — pin a working model" | The agent's turns run but every model call dies | Pin a working model on the agent card in the spoke dashboard | +| "agent(s) NAME stuck at Copilot consent — restarting in a loop" | The kick path keeps restarting an agent parked on a consent screen | Complete the consent flow on the spoke dashboard; the alarm clears itself within the hour | +| "agent(s) NAME enabled but never kicked — set cadences" | The agent has no cadence in any mode and has never been kicked | Set cadences on the agent card | +| "awaiting human review — N held for approval" | Output is parked behind hold labels; the next move is a person's | Review the held PRs (the hint links straight to the repo's PR list) | +| "spoke lags its channel — N commits behind stable" | The channel moved and the spoke did not follow | Check auto-upgrade / force a rollout from the hub's fleet version controls; see [release channels](/docs/hive/release-channels) | +| "not reporting (offline)" (unknown) | No recent heartbeat | Check the spoke's pod/container and network path to the hub; see [troubleshooting](/docs/hive/troubleshooting) | +| "spoke too old to report health" (unknown) | The spoke predates the health signals | Upgrade the spoke image | +| "queue empty — idle" (green) | Nothing to work on — this is healthy | Nothing. Add work sources if you expected a backlog | +| "no output expected — …-capable agent(s) off: NAMES" (green) | The agents that could produce this level's output are paused/off-schedule | Nothing, unless you want output — then resume the named agents | + +## Where the verdict comes from (for the curious) + +The verdict is computed in `src/pkg/hub/health_verdict.go` (base verdict and +ACMM banding) and `src/pkg/hub/remediation.go` (detector layering and the +signature → action map), from fields the spoke reports in its heartbeat +(`src/pkg/hub/heartbeat.go`). The spoke-side detectors live in +`src/pkg/tokens/error_streak.go` (error streaks, from chat recordings), +`src/pkg/agent/consent_wedge.go` (consent-screen restart tracking), and +`src/pkg/governor/no_cadence.go` (cadence-less agents). The `/fleet` +rendering — dot, WHY chip, and hint line — is in +`src/pkg/hub/static/my-hives.html`. diff --git a/docs/content/hive/formal-verification.md b/docs/content/hive/formal-verification.md new file mode 100644 index 0000000..43fe5fb --- /dev/null +++ b/docs/content/hive/formal-verification.md @@ -0,0 +1,117 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/formal-verification.md) during the docs build. Edit the canonical source in the Hive repository. + +# Formal verification in the quality lane + +Hive can let the quality agent author and maintain Spin/Promela models for +protocol-shaped code. This is an optional capability, not another default lane +and not a claim that Hive proves functional correctness. + +## Enablement and maturity gate + +Enable it in the trusted hive configuration: + +```yaml +acmm_level: 5 +quality: + formal: true +``` + +You can also set the same `quality.formal` toggle from the dashboard under Settings -> Features. + +Both conditions are required. `quality.formal` defaults to false, and an +explicit true is inert below ACMM L5. Downgrading a hive therefore disables +formal-model authoring immediately without deleting the operator's preference; +raising it back to L5/L6 restores the capability. + +The contract is injected after ordinary policy-template resolution. It reaches +scheduled and manual kicks, quality replicas, and locally customized or remote +quality prompts. Operators can customize the rest of the quality policy without +silently weakening what `quality.formal` promises. + +## What is worth modeling + +The agent must justify model-worthiness in every PR that introduces a model. A +candidate should have one or more concrete signals such as: + +- a state-machine lifecycle; +- concurrent actors; +- retry, escalation, or durable ledger state; +- ordering or lock invariants; +- lease, claim, or ownership transfer; or +- prior incidents caused by a protocol interleaving. + +If no subsystem qualifies, the quality agent continues its normal test and +coverage work. It must not add a placeholder model. Formal scope is protocol, +safety, and liveness behavior; modeling every component or proving general +functional correctness is out of scope. + +## Repository artifact contract + +Each modeled subsystem owns: + +```text +formal// +├── model.pml +├── run.sh +└── README.md +``` + +A repository organized below a component root may put `formal/` at that root. +The README maps every modeled state and transition to its production code, +documents abstractions and fairness assumptions, lists each property, and gives +counterexample replay commands. The model PR explains why ordinary tests cannot +reliably explore the interleavings being modeled. + +`run.sh` is the executable source of truth. It performs exhaustive Spin checks +and returns nonzero whenever an observed verdict differs from the pinned +expectation. That includes both must-pass properties and intentional +expected-fail witnesses. A new violation and an undocumented fix that makes a +known witness disappear are both model drift and both make the script red. + +## CI and failure reporting + +The model PR adds a path-gated CI job covering the model, the corresponding +production subsystem, and the workflow itself. The job is reporting-only and +must not be configured as a required merge check. It preserves the logs or +trails needed for local replay, but a raw Spin trail is not an actionable issue. + +The quality agent minimizes and replays each unexpected counterexample, then +files one issue per violated property using this stable title: + +```text +[formal::] +``` + +Before creating, it performs only a narrow exact-title lookup. If that property +already has an open issue, the agent updates it with the new model revision, +run, and narrative instead of creating a duplicate. Different properties never +share one issue. The narrative records user impact, an actor-by-actor +interleaving, the reproducible model revision/run, matching production code, +and what a modeled candidate fix proves when one exists. + +Issue narration stays agent-owned. A pull-request workflow should not receive +broad issue-write permission solely to turn an untrusted raw trail into prose. +When the repository supplies an issue relay such as `hive-open-issue`, the agent +uses that relay and its exact-title deduplication contract. + +## Modeled-code maintenance + +A PR that touches a modeled subsystem and turns its formal job red must either +fix the code or update the model in the same PR with the new invariant story. +Rerunning past the evidence, weakening a property, deleting an expected witness, +or narrowing the path gate merely to make CI green is not maintenance. + +Existing red quality PRs still take precedence under FIX-BEFORE-NEW. Enabling +formal verification does not authorize the quality agent to abandon repair work +and start a fresh model. + +## Current repository models + +- `src/formal/escalation/` models the escalation ledger and reviewer lane. +- `src/formal/contribute-lease/` models the contributor lease/reconnect + protocol: task assignment, websocket drop, release cooldown, reconnect resume, + lease expiry, and reassignment for one issue and two contributors. It pins two + lease invariants: no issue is held by two contributors with valid leases at + once, and an abnormal disconnect that reconnects within the relay's first + backoff window is not booked as `abandoned_disconnect`. Its expected-fail rows + preserve the pre-fix #7773 and #7838 counterexamples. diff --git a/docs/content/hive/github-app-setup.md b/docs/content/hive/github-app-setup.md new file mode 100644 index 0000000..55861df --- /dev/null +++ b/docs/content/hive/github-app-setup.md @@ -0,0 +1,426 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/github-app-setup.md) during the docs build. Edit the canonical source in the Hive repository. + +# GitHub App setup + +> **Terminology:** the dashboard and docs call this the **Forge App** — the app Hive installs on your forge (your source control system, e.g., GitHub, GitHub Enterprise, GitLab, or Gitea). On **GitHub.com and GitHub Enterprise (GHE)** the Forge App **is a GitHub App**; this page covers creating and installing it. Dashboard controls live under **Governor Config → Forge App**. + +> **On GitLab, Gitea, or Forgejo?** This page does not apply, and there is no +> equivalent setup to perform: those forges are **not supported for running a +> hive** today. The adapters exist in the source tree but are not wired into any +> running code path, and the agent execution path is GitHub-only. See +> [Forge setup: GitLab, Gitea, and Forgejo](https://github.com/hivecommons/hive/blob/v5/src/docs/forge-app-setup.md) for exactly what +> is and is not implemented before you attempt an install. + +Hive can authenticate with either a personal access token or a GitHub App. Use a GitHub App for production hives because installation tokens are scoped to selected repositories and can author PRs as the app bot when `github.app_authored_prs` is enabled. + +## Personal access token (PAT) scopes + +The PAT path is `HIVE_GITHUB_TOKEN` (or `github.token` in `hive.yaml`); the App path is `github.app_id`/`github.key_file` as described below. If you set `app_id`/`key_file` this section does not apply — the App permission table further down does. + +Hive never validates token scopes at startup. A PAT with missing scopes fails **at request time** with generic GitHub 403 responses (fine-grained PATs typically say `Resource not accessible by personal access token`). The visible symptoms are agents reporting no actionable work, advisory digests not appearing on the tracking issue, empty fleet-stats widgets, or failed issue/PR writes in agent logs — none of which name the missing scope. If you see unexplained 403s, check the scopes below first. + +### Classic PATs + +Classic scopes are coarse, so one scope covers every ACMM tier: + +| ACMM tier | Minimum classic scopes | Why | +| --- | --- | --- | +| L1–L2 (advisory) | `repo` (private repos) or `public_repo` (public repos only) | Read issues/PRs/contents; post advisory digest comments to the pinned tracking issue (an issues **write**, even though the tier is otherwise read-only). | +| L3–L4 (issue filing) | same | Create, label, comment on, and close issues. | +| L5–L6 (PR/merge) | same, plus `workflow` if agent PRs may touch `.github/workflows/` | Push branches, open/update/merge PRs, read checks/statuses. GitHub rejects workflow-file pushes without `workflow`. | + +Add `read:org` when Hive should identify org members and contributor roles (recommended for org-owned hives). + +### Fine-grained PATs + +Fine-grained PATs are supported — the token is sent as a plain bearer, same as a classic PAT. Grant the token access to every repository the hive works on, with repository permissions mirroring the App table below: + +| Permission | L1–L2 (advisory) | L3–L4 (issues) | L5–L6 (PR/merge) | +| --- | --- | --- | --- | +| Metadata | Read | Read | Read | +| Contents | Read | Read | Read and write | +| Issues | Read and write | Read and write | Read and write | +| Pull requests | Read | Read | Read and write | +| Checks | Read | Read | Read | +| Actions | Read and write | Read and write | Read and write — needed by the default-on gated-run approval sweep (`governor.ci.auto_approve_workflows`); Read suffices with it set to `false`, see below | +| Commit statuses | Read | Read | Read and write — needed when `governor.labels.automerge` is the default `lgtm` on a Prow repository, so the queue action can set the `prow/lgtm` status beside the label. With only Read, every queue action still applies the label but posts a PR comment that the status could not be set. | + +Since the gated-run approval sweep (`governor.ci.auto_approve_workflows`, **default on**, [#16603](https://github.com/hivecommons/hive/issues/16603)) Hive approves `action_required` `pull_request` runs with the App token — `POST /actions/runs/{id}/approve`, once per PR head, for Dependabot/Renovate/App-authored or -triggered runs and for heads a verified owner or merger admitted from the dashboard — which needs **Actions: Read and write**. With only **Actions: Read** the call fails with `403`, the hive records one `permission_error` in `/api/status` `workflow_approvals`, logs `workflow approval refused; needs workflow approval on GitHub`, and the CI caption reads `CI waiting · needs workflow approval on GitHub`; the refusal is recorded per PR head and not retried, so granting the permission afterwards takes effect for new heads (or after a hive restart), while an already-refused head needs **Approve and run** on GitHub or a fresh push; set `governor.ci.auto_approve_workflows: false` to stay on Read and leave approvals to the `/ok-to-test` workflow described below. The other direct approval Hive performs — a contributor-lane PR whose author the contributor registry admitted at a `require_tiers` tier (`auto_merge.contributor_lane.approve_held_runs_for_registry_trusted`, default on) — needs the same grant. For that path it is **optional**: without it the call fails with `403 Resource not accessible by integration`, the hive labels the PR `hive:unauthorized`, posts one comment naming the permission and the human step (**Approve and run** on the checks banner or Actions tab, with the run ids), logs `lane unauthorized` once per head, parks the PR at 085 (`Awaiting human: approve workflow runs` in the activity monitor), and clears all of it the tick the required checks report ([#14589](https://github.com/hivecommons/hive/issues/14589)). When GitHub leaves same-repository `pull_request` runs in `action_required` on trusted Dependabot/Renovate/App PRs or registry-trusted `author/clanker` PRs, and the approval sweep is off or lacks the grant, Hive posts `/ok-to-test` once for that head and reports `workflow-approval-required:` / `stage/085-needs-decision` until the repository's own self-contained `hive-ok-to-test` workflow approves the held runs. The approval is performed by that repository's `GITHUB_TOKEN` through `.github/workflows/hive-ok-to-test.yml`; that path needs no Prow and no Hive App Actions-write grant, and it never covers fork heads. Fork heads are reached only by the two App-token paths above — the gated-run approval sweep and the registry-trusted contributor lane — since GitHub holds only fork `pull_request` runs behind the gate; a trusted head's workflow files then run on the repository's runners, which is what the **Actions: Read and write** grant buys. No path approves runs on PRs carrying `sentinel-alert`. + +Install the workflow in each governed repository: run `hivectl ok-to-test-template > .github/workflows/hive-ok-to-test.yml` against your hive (it reads the App bot login from `/api/config`; pass `--app-login [bot]` to override), or copy `src/docs/templates/hive-ok-to-test.yml` and replace `HIVE_APP_LOGIN[bot]` with the App bot login shown by Hive for that installation. + +The rendered workflow is **self-contained**: it triggers on `issue_comment`, runs with job-level `permissions: actions: write, contents: read, issues: write, pull-requests: read`, and performs the whole approval in one `bash` + `gh` step with the repository `GITHUB_TOKEN`. It carries no `uses: hivecommons/hive/...` reference, so it works in repositories whose Actions policy only allows selected actions/reusable workflows, on GitHub Enterprise Server, and in organizations that do not permit workflows from `hivecommons`. The step: + +1. exits quietly unless the comment is on a pull request and its body is exactly the command (`/ok-to-test` by default); +2. requires the commenter to be a configured Hive App login or to hold write/maintain/admin (`GET /repos/{owner}/{repo}/collaborators/{login}/permission`); +3. requires the PR head repository to equal the base repository (same-repo only) and the PR author to be in `TRUSTED_AUTHORS` (`dependabot[bot],renovate[bot]` plus the App login(s) by default); +4. refuses when the `sentinel-alert` label is present; +5. lists the head SHA's `status=action_required` runs and `POST /repos/{owner}/{repo}/actions/runs/{id}/approve`s each, then posts one summary comment carrying an idempotent marker (re-runs for the same head only add a 👍 reaction); +6. fails the job with `::error::` if the token cannot approve runs, so a missing `actions: write` grant or a read-only workflow-permissions setting is visible instead of silent. + +Organization permission: **Members: Read** where contributor/owner identification is configured. Note that Issues read-and-write is needed even at advisory tiers because digests are posted as issue comments. + +## Create the app + +In GitHub, open **Settings → Developer settings → GitHub Apps → New GitHub App** (or the equivalent organization settings page). On **GitHub Enterprise**, do this on your enterprise host (`https:///settings/apps/new`), not github.com — the app, its install page (`https:///github-apps/`), and the source control host Hive is configured for must all be the same host. + +Recommended values: + +- **GitHub App name**: any unique operator-owned name. +- **Homepage URL**: your project or Hive dashboard URL. +- **Setup URL** (optional): `https:///gh-setup`. `` means + **the address you type into your browser to reach this hive** — not where the + hive process runs. GitHub redirects *your browser* here; it never fetches this + URL itself, and neither does the hive. See + [Choosing a Setup URL](#choosing-a-setup-url) before setting it, and leave it + blank if the hive is not reachable from the browser you administer it with — + Hive discovers `installation_id` on its own. +- **Redirect on update**: enabled — but only alongside a Setup URL that is + actually reachable. It re-fires the redirect on every repository add or + removal, so an unreachable Setup URL produces a dead browser tab every time + you change the installation, not just once at install. +- **Webhook**: inactive unless you separately configure webhook channels; the dashboard setup flow does not require webhooks. +- **Device Flow**: enabled, so dashboard login can use the app's client ID. +- **Visibility**: private for an organization-specific app; public only if you intentionally operate one app for many unrelated owners. + +Repository permissions used by the dashboard setup UI are: + +| Permission | Level | Why | +| --- | --- | --- | +| Metadata | Read-only | Required by GitHub. | +| Contents | Read/write | Clone, branch, and push agent changes. | +| Issues | Read/write | Enumerate, comment on, create, and close issues. | +| Pull requests | Read/write | Create, update, approve/merge, and inspect PRs. | +| Checks | Read-only | Monitor CI status. | +| Actions | Read and write (Read-only with `governor.ci.auto_approve_workflows: false`) | Inspect workflow runs; the default-on approval sweep approves gated `pull_request` runs for trusted bots, the App and dashboard-admitted heads with the App token ([#16603](https://github.com/hivecommons/hive/issues/16603)). If the sweep is off or refused and GitHub holds trusted Dependabot/App/clanker runs in `action_required`, Hive posts `/ok-to-test`; the repository-local `hive-ok-to-test` workflow uses its own `GITHUB_TOKEN` with Actions write to approve those runs. With Read and write, the contributor lane also approves held runs directly for a PR author the contributor registry admitted at a `require_tiers` tier (`auto_merge.contributor_lane.approve_held_runs_for_registry_trusted`). Optional: without it the hive marks such a PR `hive:unauthorized` and waits for a maintainer to click **Approve and run** ([#14589](https://github.com/hivecommons/hive/issues/14589)). | +| Administration | Read-only | Read branch-protection rules before the merge-request watcher lands a PR; Hive refuses closed if it cannot verify the base branch is protected. | +| Commit statuses | Read/write | Needed when `governor.labels.automerge` is the default `lgtm` on a repository running Prow's commit-bound `lgtm` (prow-github-actions v3): the queue action sets a `prow/lgtm` success status on the approved head so Prow does not strip the label. Without the write grant the label and approval still land, but every queue action takes the failure branch and posts a PR comment saying the status could not be set. Choose a distinct label such as `hive/auto-merge` if you would rather keep this at Read. | +| Dependabot alerts | Read-only | Required for the sec-check agent's Dependabot scanning (`gh api repos///dependabot/alerts`, [#17426](https://github.com/hivecommons/hive/issues/17426)). Least privilege: only the token minted for an agent with role `sec-check` at ISSUES_AND_PRS or ISSUES_PRS_MERGE ([#17496](https://github.com/hivecommons/hive/issues/17496)) requests `vulnerability_alerts: read`; every other agent's token is unchanged. The App itself must still declare the permission, and that is a GitHub UI change only the App owner can make — see [Adding a permission to an existing App](#adding-a-permission-to-an-existing-app). Optional: until it is declared and re-accepted, the sec-check mint logs `scoped token mint with vulnerability_alerts:read failed; retrying without it`, mints without the grant, and the Dependabot call returns 403; the hive still mints tokens and every other agent is unaffected. | +| Workflows | Read/write | Let trusted-tier agents push branches that modify `.github/workflows/`, and let the contributor lane merge an owner-approved PR that edits `.github/workflows/**` (`auto_merge.contributor_lane.owner_approval_releases_workflow_fence`, [#14664](https://github.com/hivecommons/hive/issues/14664)); without the grant such a merge is refused and the hive marks the PR `hive:unauthorized` (`merge-workflow-path`) and parks it at 090 for a maintainer's **Merge** click. Without it GitHub also rejects any GitHub App-token push touching those files server-side ("refusing to allow a GitHub App to create or update workflow … without workflows permission") no matter what the token requests. Maintainer user credentials are separate and can still push workflow-file changes when their account has the normal repository rights; the Hive App cannot until this grant is added **and re-accepted on each installation** (an existing install must approve the new permission under Settings → Integrations → the app → Review request). See [`hive-open-pr`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-pr.md#workflow-file-pushes-rejected-by-app-tokens) for the agent delivery procedure and [#6985](https://github.com/hivecommons/hive/issues/6985) for the outstanding permission change. | + +Organization permission: + +| Permission | Level | Why | +| --- | --- | --- | +| Members | Read-only | Identify contributors and owners where configured. | + +### Adding a permission to an existing App + +Hive does not ship an App manifest and never edits the App's permissions for +you: GitHub exposes no API for changing a GitHub App's declared permissions, so +when a Hive release starts requesting a grant the App does not yet declare +(Workflows in [#6985](https://github.com/hivecommons/hive/issues/6985), +Dependabot alerts in [#17426](https://github.com/hivecommons/hive/issues/17426)), +the token mint is refused with `422 The permissions requested are not granted +to this installation`, Hive logs a warning, retries without the grant, and the +feature that needed it degrades (a 403 on that API call) until two people have +clicked through the GitHub UI: + +1. **The App owner** (whoever owns the App under **Developer settings**, e.g. + the organization that created it) opens **Settings → Developer settings → + GitHub Apps → _your app_ → Permissions & events → Repository + permissions**, sets the new permission (for example **Dependabot alerts: + Read-only**), and clicks **Save changes** at the bottom of the page. + Nothing changes for any installation until this is saved. +2. **Each installation owner** then sees **Permission updates requested** on + the installation page — **Settings → Integrations → Applications → + _your app_ → Configure** for a user account, or **Organization settings → + Third-party access → GitHub Apps → _your app_ → Configure** for an + organization — and must click **Review request → Accept new permissions**. + GitHub also emails the installation owner. Until an installation accepts, + that installation keeps minting without the grant; installations that have + accepted get it on their next mint without a hive restart. + +The hive confirms the grant landed when the `scoped token mint with +vulnerability_alerts:read failed` (or `workflows:write failed`) warning stops +appearing in the spoke log on the next mint for that tier. + +### Optional shared-CI recovery + +The shared-CI rerun sweep (`shared_ci_rerun.enabled`, default on) can inspect +failed runs with Actions read, but `rerun-failed-jobs` requires **Actions: Read +and write** on the repository's recovery identity. This is optional, not a new +baseline permission for every Hive App. A refusal is an operator handoff, not +a source-code defect: Hive records `unauthorized:rerun-shared-ci`, posts one +head-scoped actionable note using the existing unauthorized mechanism, and +retries no more than once per repository per permission cooldown (one hour). +An unchanged PR remains eligible after the cooldown; a successful rerun or +observing no failed runs clears the recovery block. + +A maintainer may re-run the named workflow with their already-authorized +identity. That manual recovery does **not** change the App's permissions. For +automatic recovery, the App owner must explicitly request Actions read and +write for the intended recovery installation, and its installation owner must +accept the update in **Settings → GitHub Apps → Configure**. Do not broaden +unrelated Apps or repositories or silently substitute a PAT. Leaving the grant +at read is supported; an operator may disable the optional sweep instead. +Neither action grants merge approval or bypasses required checks. + +### The optional Visual Hive App (#4030) + +Visual Hive needs two grants the Hive App does not otherwise require — Actions +at write (to dispatch its installed workflow) and Commit statuses at write (to +publish the provenance-bound setup authorization status). The Hive App only +asks for Commit statuses write for the `prow/lgtm` auto-merge binding above, +and never for Actions write. Rather than widen the +Hive App, those grants live in a separate, optional, Hive Commons-owned App, so +enabling Visual Hive never changes what an installation that will never use it +has approved. + +| App | App ID | Forge | +| --- | --- | --- | +| `hivecommons-viz-hive` | 4729416 | github.com | +| `hivecommons-viz-hive-ghe` | 5945 | github.ibm.com | + +Its permission set is exactly: + +| Permission | Level | Why | +| --- | --- | --- | +| Actions | Read/write | Dispatch the installed Visual Hive workflow. | +| Commit statuses | Read/write | Publish the setup authorization status. | +| Metadata | Read-only | Required by GitHub. | + +Nothing else — no Contents, Workflows, Issues, Pull requests or Checks — and no +webhooks. Install it on **selected repositories**, not all repositories. + +These identities are declared in `src/pkg/config/provenance.go` and are inert on +this branch: nothing resolves a key for them, delivers one, or authenticates as +them. Registering them ahead of the feature only means a config naming one is +described accurately instead of reported as an unknown App. + +#### Reading the granted Actions and Commit-statuses permissions + +App auth classification turns solely on the Issues permission, and an +installation that has not been granted the two Visual Hive permissions is +healthy — its `state` is `ok`. That is correct, and it is also why those grants +have to be reported separately: without it, an installation that has approved +them and one that has not are indistinguishable. + +Every credential verdict now logs what is actually granted, including when the +verdict is `ok`: + +```text +github app credential verdict owner= state=ok grants="actions=read statuses=none" visual_hive_execution_grants=false +``` + +`grants` reports the level GitHub returned for each permission (`none` when +there is no grant), and `visual_hive_execution_grants` is true only when both +are at `write`. Emitting it for a healthy verdict is the point: an installation +that has not approved a permission update is the one that still looks fine, and +GitHub keeps an App on its old permissions until an org owner accepts, so a +partly approved fleet is otherwise invisible. + +Permission verdicts are computed where a GitHub call has failed and on the +dashboard's **Re-check** button, not on every eval cycle. Repository coverage +is checked separately on the self-heal loop, including on a healthy hive, as +described below. To read a specific installation's grants on demand — for +example to confirm the demo/canary install — press Re-check on that hive and +read the line above from its logs. + +## PR-contents gate posted by the hive + +From 2026-12-02 GitHub blocks `pull_request_target` workflows by default in public repositories. A repository whose required `verify PR contents` check comes from such a workflow would stop reporting it, and its PRs would park as `required-check-missing`. The hive can post that gate itself as a **commit status** on the exact PR head, so customers do not have to change anything in their repositories. It needs the Hive App's **Commit statuses: Read and write** grant (the same optional grant the `prow/lgtm` binding uses above). + +It is configured in `hive.yaml` only, ships **off**, and needs an explicit repository list: + +```yaml +auto_merge: + pr_gate: + mode: shadow # off (default) | shadow | enforce + repos: [your-org/your-repo] +``` + +- `off` posts nothing and changes nothing. +- `shadow` posts only `verify PR contents (hive)` (a name no branch rule requires) on each PR head and compares the verdicts with the workflow's own `PR Type`, `PR Issue` and `verify PR contents` results. Nothing a branch rule reads can change. +- `enforce` is accepted in the file but runs as `shadow` until the grant check and the visible failure paths ship; it never posts the real names yet. + +The verdict logic is a Go port of the PR title verifier (`PR Type`, `PR Issue`); both implementations replay one shared golden corpus in CI, so they cannot drift. The poster can write exactly four contexts: `verify PR contents`, `PR Type`, `PR Issue` and `verify PR contents (hive)`. Any other context, `DCO` included, is refused in code before a request is made. Drafts and closed PRs are skipped, the head is re-read from GitHub before posting, and an identical status is never posted twice. + +**Verify in shadow.** Open or edit a PR in a listed repository. Within seconds its **Checks** box shows a status named `verify PR contents (hive)` whose description reads `PR Type: success; PR Issue: success` (or `failure`). In the hive log, `pr-gate: status posted` names the repository, head and context, and `pr-gate: comparison with the workflow result agrees` (or `DISAGREES`, logged as a warning) appears when the workflow's check lands on the same head. A `pr-gate: status refused with 403` line means the installation has no Commit statuses write grant: accept the App's pending permission request in the organization settings (see [Adding a permission to an existing App](#adding-a-permission-to-an-existing-app)). + +## Install and configure Hive + +1. After creating the app, note the **App ID**, **Client ID**, and app slug from the app page/URL. +2. Generate a private key and mount it into the hive, for example `./secrets/gh-app-key.pem` on the host mounted as `/secrets/gh-app-key.pem`. +3. Install the app on the organization/repositories Hive manages. +4. Configure Hive: + +```yaml +github: + app_id: + installation_id: # optional; auto-discovered (see below) + app_slug: + key_file: /secrets/gh-app-key.pem + oauth_client_id: +``` + +For GitHub Enterprise, also set `api_url`/`base_url` or the supported `forge` value so install URLs and API calls target the same host. + +### Signed commits on agent PRs (`app_signed_commits`) + +Agents commit with plain `git` in their pane and cannot sign: a GitHub App has no account to hold a GPG or SSH key. A base branch whose ruleset **requires signed commits** therefore blocks every agent PR from merging, however many approvals it has. GitHub does sign commits it creates itself — commits authored through the `createCommitOnBranch` GraphQL mutation are GPG-signed by GitHub and shown as **Verified**, and a GitHub App may author them directly. + +```yaml +github: + app_signed_commits: true # opt-in; needs an installed App +``` + +In the dashboard the same switch is **Settings → Forge App → Re-author agent PRs as GitHub-signed commits** (Owner role required to save). + +With it on, the PR-request watcher (the choke point every `hive-open-pr` request passes through) re-authors the head branch before it opens the PR: it reads the `base...head` diff, builds one commit through the mutation with the App installation token — same tree, the agents' original commit messages and DCO trailers as the message — force-updates the branch to it, and then opens the PR. The PR arrives with a single commit, signed by GitHub, authored by `[bot]`, that a `required_signatures` rule accepts. + +**DCO.** The mutation takes no author: GitHub stamps its own bot account on the commit (`[bot] `). That is fine for the DCO checks - probot-dco exempts a commit whose GitHub author resolves to a Bot account, and Prow's `dco` plugin only requires a `Signed-off-by` line to be present. The `Signed-off-by` trailers copied from the agents' commits are what the hive controls, and they are re-addressed to the bracket-free form the pane identity uses since #6276: a `[bot]@users.noreply.github.com` sign-off (with or without GitHub's numeric prefix) becomes `@hive.hivecommons.dev` (`HIVE_GIT_BOT_EMAIL_DOMAIN`), because probot-dco rejects the bracketed local-part as "not a valid email address" wherever it does validate it (#6251). Every other sign-off address, a human's or the legacy `hive-bot@hivecommons.dev`, is copied unchanged. + +What it does not do, and falls back on (the PR still opens on the agent's own commits, the reason lands in the request's `.result.json` as `signed_skipped` and in the hive log at WARN): + +- changes the mutation cannot express: executable bits, symlinks, submodule pointers; +- changes above 20 MiB of file content, or past the compare API's 300-file list; +- a head branch that moved (the agent pushed again) between reading the diff and updating the ref — nothing is replaced that the signed commit does not carry; +- a head branch that already has an open PR — that PR is reused untouched at open time, and the follow-up pass below signs it instead. + +**Follow-up commits.** An agent's later pushes to its open PR (a CI fix, review follow-ups, a rebase) are plain git and unsigned, and so is a PR that opened on a `signed_skipped` fallback. With `app_signed_commits` on, the PR-request watcher also runs a reconcile pass, at most once a minute (#9364). A PR needs signing when *any* of its commits is not **Verified**, not only its head: a person can sign their own commit on top of an agent's unsigned one, which leaves the head Verified while the PR is still blocked (#9531). For every open PR authored by the App bot, the pass finds the first unverified commit (oldest to newest) and re-authors everything from there through the head as one GitHub-signed commit on top of the commit right before it. The tree is the same, and the message carries the range's messages and DCO trailers, re-addressed as above. When the PR's first commit is the unverified one, it signs against the PR's base branch, as at open time. A fully Verified PR is left alone. The open path's guards all still apply. A head that moves mid-rewrite is retried on the next pass, and so is a head GitHub could not be reached for (a 5xx or network error). A head GitHub *refuses* to sign (a 4xx answer, such as the 422 on the scratch ref in #16193) is retried on three consecutive passes and then settled, with the `hive:signed-commits-blocked` comment quoting the error; there is no person's commit to squash in that case, so the remedy is to push a new head (which restarts signing) or fix the repository-side cause the error names. A PR whose head hasn't changed since the last pass costs no calls beyond the open-PR list. + +The pass re-signs only the hive's own work. Every commit in that range, Verified or not, must have an author and committer that are the App bot or an address in the pane identity domain (`HIVE_GIT_BOT_EMAIL_DOMAIN`, default `hive.hivecommons.dev`). Verified App-bot commits in the range are folded in. A person's commit (even a Verified one on top), or a merge commit, leaves the branch as pushed. The PR gets one comment (marked ``, posted once per PR) naming the blocker. To unblock it, squash the unsigned commit into a commit the person signs, or drop the person's commit so the hive can re-sign the range and then push it again, signed, on top. + +Changes the signing mutation cannot safely express also leave the branch untouched and get a single comment with the reason. For example, it cannot preserve executable files, symlinks or submodule pointers. A contributor can re-author the unsigned commits with their own verified signature, preserving their contents and modes, and push the signed branch. These deliberate skips are logged at INFO rather than as API failures; a new head is examined again. + +**Agents after a push.** The rewrite replaces the agent's commits on the remote, so its local branch no longer matches, even though the tree is identical. Before committing again on a branch with an open PR, run `git fetch && git rebase origin/`. The rebase drops the now-empty local commits and keeps any new work. Never force-push over the signed commit: that puts the unsigned commits back, and the next pass has to sign them again. + +Leave it off (the default) on hives whose base branches do not require signatures; it rewrites agent branches for no benefit there. + +## Choosing a Setup URL + +The Setup URL is a **browser redirect target**, not a callback GitHub's servers +make. After an install — and, with **Redirect on update** enabled, after every +repository add or removal — GitHub sends whatever browser you were using to +that address. So the only question that matters is: + +> Can the browser I administer this hive from open that URL? + +That is a property of how *you* reach the hive, not of where the hive runs: + +| How you reach the dashboard | Correct Setup URL | +| --- | --- | +| Desktop session on the hive machine | `http://localhost:3001/gh-setup` | +| SSH tunnel (`ssh -L 3001:localhost:3001 you@hive`) | `http://localhost:3001/gh-setup` — the tunnel makes `localhost` genuinely the hive | +| Another machine on the network | `http://:3001/gh-setup` | +| Public hostname behind TLS | `https:///gh-setup` | +| Not reachable from your browser at all | **leave it blank** — see below | + +`localhost` is the common trap. It is correct only for the first two rows, and +it fails silently everywhere else: set it while sitting at the hive machine and +it works, then administer the hive from a laptop and every install-update +redirect lands on the laptop's own port 3001, which is nothing at all. + +### Headless, NATed, and remotely administered hives + +**The Setup URL is optional. A hive that is not reachable from anywhere should +leave it blank and turn Redirect on update off.** Nothing is lost. + +The callback's only job is to save you from pasting an `installation_id`, and +Hive already resolves that itself: it asks GitHub `GET /orgs/{org}/installation` +authenticated with the **App JWT**, falling back to walking +`GET /app/installations`. That runs when the hive starts, whenever App +credentials are (re)loaded, and when you press **Re-check** on the dashboard's +Forge App panel — adopting and persisting an unambiguous match, so it corrects a +missing *or wrong* `installation_id` without any redirect. An ambiguous or +absent result leaves your configuration untouched rather than guessing. + +Every one of those calls is **outbound, hive to GitHub**. A headless Fedora +CoreOS host, a VM on a NAT network, or any server you only reach over SSH needs +no inbound reachability for GitHub App authentication to work. The +preconditions are the ones App auth already has: the private key mounted at +`key_file`, and `project.org` set so Hive knows whose installation to look for. + +If you do leave a Setup URL configured that your browser cannot reach, the +resulting dead redirect is cosmetic. Adding a repository modifies the existing +installation rather than creating a new one, so the `installation_id` in that +redirect is one the hive already holds — the failed page does not mean App +authentication is broken. + +An installation can authenticate successfully while excluding a private +repository under **Only select repositories**. When adding a repo in the +dashboard, use the reported installation settings link to add it to the +selection, then re-check access. For repos already configured, the Forge App +banner identifies missing repository coverage; update the installation and +re-check it. A rejected advisory issue creation can then be retried without +waiting for the next UTC day. + +Boot coverage checks have a time limit; a timeout is inconclusive. The +background self-heal loop rechecks installation coverage every two minutes, +including on a healthy hive, using the cached installation token. Each check +walks up to 10 pages of `GET /installation/repositories`. If that bounded +listing is incomplete, the dashboard checks the repository's App installation +directly. Temporary GitHub errors still block adding the repository until a +check succeeds. + +## `/gh-setup` flow + +When the app's Setup URL points at `https:///gh-setup`, GitHub redirects back with `setup_action` and, for install/update, `installation_id`. + +Hive accepts `setup_action=install` and `setup_action=update`, verifies that: + +- a real `github.app_id` is configured, +- a private key file is resolvable, +- the installation ID can mint/verify a GitHub App installation, and +- the installation account matches the configured project org. + +If verification succeeds, Hive persists `github.installation_id`, reinitializes the GitHub client, and redirects the browser to `/?ghSetup=ok`. `setup_action=request` records a pending approval redirect but does not configure an installation. + +The setup endpoint is intentionally public because GitHub opens it in a browser that may not have a Hive session. The query string is not trusted; verification is done with the app key and GitHub API. + +## Rotation and recovery + +To rotate a private key, generate a new key in GitHub, mount it at the configured `key_file`, restart Hive, then delete the old key in GitHub after the new one is confirmed working. If an installation was replaced, use `/gh-setup` again or update `github.installation_id` and restart/reload the hive. + +## API quota: conditional requests and post-reset pacing + +An installation token has an hourly REST allowance (about 6,650 requests for a 16-repo installation) shared by everything that uses that installation — the hive's own sweeps and every agent's scoped token. Two behaviours in the shared HTTP transport keep the hive's share small ([#7430](https://github.com/hivecommons/hive/issues/7430)): + +- **Conditional requests.** Every repeat `GET` of a resource the hive has already fetched carries `If-None-Match` with the remembered `ETag`; GitHub answers `304 Not Modified`, which is **not charged** against the quota, and the hive replays the remembered body. Unchanged issue and PR lists — the common case between two governor cycles — cost nothing. Cached bodies are keyed by the requesting identity as well as the URL, so an agent's scoped token never reads a body the App fetched. A replayed response carries `X-Hive-Cache: revalidated`. The cache is bounded — `github.etag_cache_max_mb` (default `128` MiB of gzip-compressed bodies, env `HIVE_GITHUB_ETAG_CACHE_MAX_MB`) and `github.etag_cache_max_entries` (default `8192`) — and evicts least-recently-used bodies past either bound. A body evicted before its next poll costs a charged fetch instead of a free `304`, so a hive whose hit rate slides while **Debug → GitHub API budget → ETag cache** sits at the cap should raise the cap; the change applies from Settings → Forge App without a restart. +- **Post-reset pacing.** When GitHub answers a primary-limit `403` (`X-RateLimit-Remaining: 0`), the hive does not fire everything it had queued the instant the window resets — that is how a spoke re-exhausted its quota one second after every reset. For ten minutes after the reset, requests are spaced ~2 s apart (the same slow start already used after a secondary limit), so the new window is spent gradually. + +If a hive is still exhausting its quota, look for consumers outside the hive process on the same installation: agents' `gh` calls and the API proxy count against it too. + +## Hub-distributed App keys (hosted fleet) — operator runbook + +On a hosted fleet the hub — not the hive owner — is the App-key authority. The hub keeps one PEM per cluster at `/data/saas/app-keys/.pem` (owner-only file modes, on the same PVC as the hub's other secrets) and reconciles it to every spoke on that cluster over the heartbeat. A claimed hive whose cluster has no stored key is delivered `key_delivered=false` at claim time and then receives nothing on any beat — it stays `Degraded` on `key-missing` forever until an operator uploads a key. **The hive owner cannot see, supply, or fix this key**; every owner-facing surface deliberately stays silent for the operator-side states (`key-missing`, `key-invalid`, `no-app-assigned`). + +### Uploading (or replacing) a cluster's App key + +The upload endpoint is the ONLY way key material enters the hub. Admin-gated: + +```text +PUT /api/saas/admin/cluster-app-keys/{clusterID} +Content-Type: application/json + +{"private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----", "app_id": 123456} +``` + +- `private_key` (required) — the GitHub App's PEM private key. Validated before it is persisted; a non-PEM or unparsable key is rejected with 400 and nothing is stored. +- `app_id` (optional) — the App's numeric ID; when supplied it is persisted alongside in `clusters.json` so the cluster carries a complete identity. +- An unknown `{clusterID}` returns 404. + +The response echoes back only the key's **fingerprint** (never the key), so you can verify the right key landed: + +```json +{"cluster_id": "oke-frankfurt-1", "app_id": 123456, "has_key": true, "fingerprint": "sha256:..."} +``` + +Compare that fingerprint with one computed locally from the PEM you meant to upload. Delivery to the spokes then happens automatically on the next heartbeats — no restart needed. + +### Checking which clusters hold a key + +```text +GET /api/saas/admin/cluster-app-keys +``` + +returns `[{cluster_id, app_id, has_key, fingerprint}, ...]` for every cluster. A cluster with `has_key: false` will strand the first App-requiring hive claimed onto it — check this *before* pointing a pool at a new cluster. + +### The `app-creds-undelivered` fleet alert + +When a claimed, online hive reports an operator-side App-credential state, the hub raises a **critical** fleet alert (type `app-creds-undelivered`) in the dashboard's "Attention needed" panel. The alert names the hive and its cluster, shows how long it has been stranded, and carries the exact `PUT` remedy above. One alert per hive; it clears automatically once the key is delivered and the spoke reports healthy. The states it covers: + +- `key-missing` — no key ever reached the spoke (usually: the cluster has no stored PEM — upload one). +- `key-invalid` — a key is present but GitHub rejects the JWTs it signs (it belongs to a different App — replace it with the correct PEM). +- `no-app-assigned` — the hive still carries the placeholder `app_id` and was never assigned a real App (assign the cluster's App and upload its key). diff --git a/docs/content/hive/governor-thresholds.md b/docs/content/hive/governor-thresholds.md new file mode 100644 index 0000000..11f5c21 --- /dev/null +++ b/docs/content/hive/governor-thresholds.md @@ -0,0 +1,117 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/governor-thresholds.md) during the docs build. Edit the canonical source in the Hive repository. + +# Governor mode thresholds and repo-count scaling + +The governor picks a mode — **idle → quiet → busy → surge** — by comparing queue depth (actionable issues + open PRs, summed across every repo the hive watches) against three thresholds. The mode then selects each agent's kick cadence, so the thresholds are what decide how hard the hive works. + +Queue depth counts the enumerated work queue, not stage labels: an issue at `stage/018-open-for-discussion` (an unclaimed `proposal` / `kind/design` / `architecture discussion` or `[RFC]`-titled issue, [#17150](https://github.com/hivecommons/hive/issues/17150)) is still an open, claimable issue and still counts toward the actionable issue depth, exactly as it did when it read `stage/010-actionable`. The stage only changes how the activity monitor labels it. + +## The problem the scaling solves + +Queue depth scales with how many repos a hive watches; the thresholds did not. A fixed `surge: 20` therefore encoded an implicit repo count: + +- A 39-repo hive naturally carries a queue in the low hundreds. Against absolute thresholds it sat in **SURGE permanently**, running the most aggressive cadences even though the per-repo backlog was small. Observed live: queue ~210 against a threshold of 70. +- A 3-repo hive with the same thresholds would idle through a backlog that is genuinely deep *per repo*. + +Every hive with a different repo count had to hand-tune, and re-tune whenever repos were added or archived. + +## What happens by default + +The **default** thresholds are now per-repo base values, multiplied by the number of repos in `project.repos`: + +| | base (1 repo) | 3 repos | 39 repos | +|---|---:|---:|---:| +| `surge` | 20 | 60 | 780 | +| `busy` | 10 | 30 | 390 | +| `quiet` | 2 | 6 | 78 | + +A hive watching one repo (or none — `primary_repo` still counts as one) gets exactly the numbers it got before, so single-repo hives see no change at all. + +The effect is that the mode ladder means the same thing at any hive size: **surge is "20+ items per repo"** rather than "20 items, however many repos you watch". + +## Choosing a curve + +```yaml +governor: + threshold_scaling: linear # linear (default) | sqrt | none + coverage_target: 91 # test-coverage goal in percent, 1-100 (default 91) +``` + +| Value | Factor | When to use | +|---|---|---| +| `linear` (default) | `× repo_count` | The general case. Exactly equivalent to comparing per-repo queue pressure against the base thresholds. | +| `sqrt` | `× ceil(√repo_count)` | Hives whose queue depth does not grow linearly with repo count — many small, quiet repos alongside a few busy ones. Reaches surge sooner than linear. | +| `none` | `× 1` | Treat the thresholds as absolute queue depths. This is the behavior from before scaling existed. | + +For 39 repos, `linear` surges at 780 and `sqrt` at 140 (`ceil(√39) = 7`). Note that `sqrt` and `linear` are identical at 1 and 2 repos and only separate from 3 onward, because the ceiling cannot produce a factor below 2 until 5 repos. + +An unrecognized value is rejected at config load. + +## Operator-set thresholds always win + +A threshold **you** set yourself is used **verbatim and never scaled**: + +```yaml +governor: + modes: + surge: + threshold: 300 # used as-is on a 39-repo hive, not 300 × 39 +``` + +So a hive that already hand-tuned its way around this problem keeps working unchanged, and dragging a handle in the dashboard's **Governor → Thresholds** tab pins that threshold to an absolute value. + +A threshold of `0` counts as **unset**, not as an explicit zero — mode entries often exist only to carry cadences, and a literal zero would put every non-empty queue in that mode. + +### Mixing explicit and scaled thresholds + +Because explicit values are not scaled, mixing them with scaled defaults can put the ladder out of order. On a 39-repo hive: + +```yaml +governor: + modes: + surge: + threshold: 70 # explicit → stays 70 + # busy and quiet unset → scaled to 390 and 78 +``` + +`busy` (390) now sits **above** `surge` (70). The governor tests surge first and returns on the first threshold the queue exceeds, so BUSY becomes unreachable. The governor logs a warning naming all three effective values when it detects this: + +```text +governor mode thresholds are not in descending order — a mode is unreachable + surge=70 busy=390 quiet=78 repo_count=39 threshold_scaling=linear +``` + +It warns rather than silently reordering, because the inversion comes from a number you set. Either set all three explicitly, or remove the explicit one so all three scale together. + +## ACMM packs seed thresholds, and those DO scale + +ACMM level packs (`src/pkg/config/packs/level-*.yaml`) write `surge`/`busy`/`quiet` thresholds into `governor.modes` when a level is applied — for example L4–L6 seed `surge: 10, busy: 5, quiet: 2`, and L3 seeds `15/10/3`. + +Applying a pack is the normal path, so if those counted as hand-tuned the scaling above would almost never engage. Config therefore records **where the thresholds came from** ([#4037](https://github.com/hivecommons/hive/issues/4037)): + +```yaml +governor: + thresholds_source: pack # written by the pack-apply path + modes: + surge: + threshold: 10 # a per-repo BASE, not an absolute +``` + +With that marker present the seeded numbers are treated as **per-repo bases** and scaled exactly like the built-in defaults — so a 39-repo hive at L4 surges at `10 × 39 = 390`, and L3's `15` stays distinct from L4's `10` rather than collapsing onto one default. + +**Editing any threshold clears the marker.** The moment you set one in the dashboard's **Governor → Thresholds** tab (or by hand), the whole set becomes yours and is used verbatim. That is deliberate: clearing only the mode you touched would leave the others scaling, and a scaled `busy` of 195 sitting above a hand-set `surge` of 30 inverts the ladder described above. All three move together, so they cannot invert. + +### On upgrade + +A hive that applied a pack **before** this change has seeded thresholds and no `thresholds_source` marker. Those read as operator-set and keep their exact current values — upgrading never silently multiplies your thresholds. **Re-apply the level** (or change it) to stamp the marker and turn scaling on. + +To go the other way — pack-seeded values you want as absolutes — set them explicitly once; that clears the marker. + +## Where the numbers are shown + +The dashboard governor gauge and the **Governor → Thresholds** settings tab both display the **effective** thresholds — the same values the governor laddered on, resolved through the same code path — along with the watched repo count. The settings sliders edit the base values. + +## Related + +- [Agent configuration → Cadences and the governor](/docs/hive/agent-configuration#cadences-and-the-governor) +- Issue [#3498](https://github.com/hivecommons/hive/issues/3498) diff --git a/docs/content/hive/hive-merge.md b/docs/content/hive/hive-merge.md new file mode 100644 index 0000000..d337f47 --- /dev/null +++ b/docs/content/hive/hive-merge.md @@ -0,0 +1,1613 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md) during the docs build. Edit the canonical source in the Hive repository. + +# `hive-merge` — merge a PR as the App bot + +`bin/hive-merge.sh` is how an agent merges a pull request. Agents call it +**instead of the GitHub MCP `merge_pull_request` tool** (or a GraphQL +`mergePullRequest` mutation). GitHub rejects that mutation for App +installation tokens with "Resource not accessible by integration" even when +the token holds `contents:write` + `pull_requests:write`. The hive merges the +PR over REST with the App token instead, which succeeds — so the merge is +authored by the App bot (`[bot]`) and uses the transport that actually +works for an App token. + +It does not merge the PR itself. It writes a request file that the hive's +merge-request watcher picks up and acts on. + +## Why it exists + +Two reasons. + +**Transport.** The MCP/GraphQL merge path is rejected outright for App +installation tokens. Routing through the hive's REST-based merge path is not +optional convenience — it's the only path that works. + +**Authorization + forge resistance.** The script runs **as the agent**, in +that agent's tmux session under that agent's UID, so the request file it +writes is owned by that UID. The watcher re-derives the requesting agent from +the **file's owner**, not from anything written inside the file. `hive-merge` +**adds no privilege**: the watcher enforces the same per-agent forge-resistance +check and a `CanMerge` ACMM gate (`AuthorizeMerge`) that a direct merge would +need — an agent whose mode allows opening PRs but not merging them still +cannot merge through this path. + +Auto-merge is effective only at L6. Below L6, stored per-repo values resolve +to off; at L6, `project.repo_policies[].auto_merge: false` is also enforced +here. A repo with that switch off may still receive Hive-opened PRs, but the +relay refuses to merge them and reports that auto-merge is disabled for the +repository. The same repo policy is enforced by the App self-merge sweep and by +the proxy's direct REST/GraphQL merge denial path, so agents cannot bypass it +by calling GitHub directly. + +On top of `AuthorizeMerge`, the watcher's authorizer is wrapped with a second, +target-specific check (the F4 target-binding, CWE-863) before any merge is +attempted: + +- the request must carry a non-empty `expect_sha` — an empty expected SHA + would mean "merge whatever HEAD is now," which is a TOCTOU hole: a commit + pushed after the PR was judged eligible could get merged unseen; +- the `(repo, number)` pair must currently appear in the governor's + merge-eligible list **at that exact head SHA** — so an agent cannot request + landing an arbitrary reachable PR (including its own) merely because its + checks happen to be green; it must be a PR the hive's governor already + deemed eligible, at the commit it reviewed. + +Both the agent/UID/`CanMerge` check and this target-binding check must pass +before the merge is attempted. + +**The hive does not force-merge.** GitHub still enforces whatever write +permissions, branch protection, rulesets, required reviews, allowed merge +methods, and required checks apply to the App token. A PR GitHub refuses fails +here, and the result file records why. + +**The hive verifies CI itself, and absent is not passing.** Before any merge is +attempted the watcher requires *positive* CI confirmation on the pinned head SHA +(#6173). This gate applies equally to protected and unprotected base branches: +a red PR, or one whose workflows all died at startup with zero jobs (and +therefore zero check runs and an empty status rollup), does not merge merely +because GitHub branch protection is absent. The watcher computes its own +verdict: + +- **green** - at least one commit status or check run exists on the SHA, every + gating one has succeeded (`neutral`/`skipped` count as success, the + non-required ignore list still applies), every config-declared required + check has reported, and no workflow run on the SHA failed without producing + a job. The merge proceeds. +- **pending** - a gating check is still queued/in progress, a required check + has not been created yet, or a workflow run is in flight without a job. The + request is parked (`ci_waits` in the result file, no attempt consumed) and + re-evaluated with a per-PR+SHA backoff: every tick (10 s) for the first + minute, then once a minute, then every five minutes. After + `mergeRequestMaxCIWaits` polls or one hour pending, whichever comes first, + the wait becomes a failed attempt. +- **never-created** - a required check has no status or check run on the + head, nothing else on the head (statuses, check runs of any kind, workflow + runs) is queued or in progress, and the head is older than 30 minutes + (`mergeCIMissingRequiredGrace`). The check will never appear, typically + because the PR was opened with a token that cannot trigger workflows. The + request is quarantined (`.exhausted`) on the first such verdict, an operator + alert is raised, and the fix loop is **not** re-engaged: no code push can + create the check. +- **red** - a gating check failed, or a workflow run concluded failure with + zero jobs. Refused; counts as a failed attempt and, at the retry limit, is + classified and re-engaged into the fix loop like a branch-protection + refusal. +- **unverified** - zero statuses, zero check runs, zero workflow runs. GitHub + has no verdict, so neither does the hive. Refused; quarantined at the retry + limit with the reason in the result file. Repos with genuinely no CI (docs- + only, config-only) can be opted out per-repo with `auto_merge.no_ci_ok` + (#6281): listing the repo (`owner/repo` or bare name) downgrades this — and + ONLY this — verdict to green. Red and pending are never downgraded, and the + default stays refuse. + +An API error while gathering that evidence is a failed attempt, never a pass. + +**A merge-queue-required refusal is terminal on the first attempt.** When the +merge call itself (`PUT /pulls/{n}/merge`) answers `405 Changes must be made +through the merge queue`, the base branch's ruleset forbids direct merges and no +retry, code push or re-engaged fix loop can change that. The request is +quarantined (`.exhausted`) for that head immediately, without consuming the +retry budget, raising an operator alert or re-engaging the fix loop; the result +file records `repo requires merge queue; direct merge not possible — enqueue via +merge queue or merge by hand` followed by GitHub's message, and the watcher logs +it once per head at INFO. Clear it by enqueuing the PR through the merge queue +(see `auto_merge.native_merge_queue.enabled` in the +[operator reference](/docs/hive/operator-reference/readme)) or merging by hand; a new +head SHA starts fresh like any other exhausted request. + +**Wait state survives restarts and re-requests.** The attempt count, `ci_waits`, +the pending-poll backoff and an "exhausted" record are kept per PR and head SHA +in `/data/merge-request-state.json` (the PVC), not only in the tmpfs result +files. A new `hive-merge` request for a PR whose previous request was exhausted +on the same head SHA is refused within 24 hours: the request is moved to +`.exhausted` and its result file repeats the recorded reason instead of starting +another poll cycle. Pushing a new commit (a new head SHA) starts fresh. + +**Fork PR workflow approval remains manual.** When a cross-repo pull request's +workflow runs conclude `action_required`, the watcher refuses the merge with a +reason that says the fork PR workflow runs are awaiting maintainer approval. +The operator alert links to the repository Actions settings and tells the owner +to approve the runs manually or relax "Approval for running fork pull request +workflows". The hive does not call GitHub's workflow-run approval API. +Two refinements (#13818): a held run whose workflow already has a successful +run on the same head under another event (a `GITHUB_TOKEN`-opened PR whose +opener dispatches the same workflows by `workflow_dispatch`) is listed as +ignored and does not block — the verdict is on the head through the twin's +check runs; and when the PR is not from a fork the reason says so, because +GitHub also holds `pull_request` runs for same-repo PRs opened by a bot token +and the approval setting may already be at its minimum. + +"Merge blocked" operator alerts retire themselves. Besides clearing on the next +successful App merge in that repo, the watcher re-checks live alerts every +five minutes (`mergeAlertRevalidateInterval` in +`src/pkg/github/merge_failure_alert.go`): an alert is dropped once the blocked +PR is no longer open, and a fork-approval alert is dropped as soon as the PR +head has no workflow runs still `action_required` — i.e. the operator approved +them or relaxed the repo/org setting. A merge-queue-required alert is dropped +once the base branch's active rules, read successfully, no longer include a +merge queue; otherwise it stays until the PR is closed or merged. API errors +keep the alert in place. + +**Unprotected base branches are allowed.** The watcher no longer makes a +separate branch-protection lookup and no longer refuses solely because the base +branch is unprotected. It merges into any protected or unprotected branch the +GitHub App can write, provided the hive's positive CI-evidence gate passes and +GitHub accepts the merge. The legacy `auto_merge.allow_unprotected_base` key is +accepted as a deprecated no-op so existing configs keep loading; it is no +longer needed. + +**No-CI repositories require an explicit repo opt-in.** Repositories with no CI +by design can be listed under `auto_merge.no_ci_ok`. That opt-in only downgrades +the **unverified** verdict (zero statuses, zero check runs, zero workflow runs) +to green for that listed repo, and the watcher logs that +`auto_merge.no_ci_ok` enabled it. Any non-zero failing CI evidence still +refuses, and pending evidence still waits. + +**Paths a person must merge.** `auto_merge.human_merge_paths` is a per-repo map +of `owner/repo` to glob patterns (same syntax as `intent.guardrail_path_patterns`), +unset by default. When a merge request touches a listed path, `hive-merge` +refuses it, adds `hold`, and posts one `` comment +naming the path(s); a person must merge it. The same key guards the automerge +sweep lanes whatever the intent tier. If the changed-file list for a configured +repo cannot be fetched completely, the merge is withheld (fail closed). See +[operator-reference.md](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md). + +**Pin-only policy (enforced by the automerge sweep, `/approve`, and relay).** + +`auto_merge.human_merge_pin_only` provides the schema and conservative diff +classifier for #16242 / #16262. **The automerge sweep lanes and `/approve` +(#16266) and the `hive-merge` relay (#16265) enforce it.** The native merge +queue is entered only after a lane's human-merge-path gate, so queued PRs inherit the exception. A sweep lane +does not hold a PR on its human-merge-path matches when the repo has an enabled +entry, the PR author is in `trusted_authors` (case-insensitive login match), +GitHub's reported changed-file count is present and equals the fetched list, +the classifier accepts the diff, and every commit behind the head is a +trusted author's: the PR's commit list must end at the current head and each +commit must have an author login in `trusted_authors`, a committer login that +is either GitHub's own `web-flow` or in `trusted_authors`, **and** a signature +GitHub reports as verified. The PR author login only records who opened the +PR; any principal with write access can push onto that branch afterwards, and +a locally crafted commit can carry a bot's author email. GitHub verifies a +signature against the committer's email only, so a verified signature proves +the committer, not the author; a write-access principal with their own signing +key could otherwise sign a commit authored as a bot. Requiring the committer to +be `web-flow` (GitHub created and signed the commit, so GitHub set its author) +or a trusted login (a human trusted author signing locally) is what ties the +commit to the listed identity, since a spoofed committer email is not on the +signer's account and fails verification. Dependabot and Renovate commits are +web-flow committed and signed; a human trusted author must commit and sign as +themselves. A commit list that cannot be fetched, is empty, is longer than +GitHub serves, or does not end at the head holds the PR. Finally every new +`action-sha` pin must be anchored in its upstream action repository, because +GitHub resolves a `uses:` SHA across the whole fork network: with a +`# vX[.Y[.Z]]` comment, the upstream `tags/vX…` ref (annotated tags +dereferenced) must point at exactly the new SHA; without one, the new SHA must +be an ancestor of the upstream default branch. A 404, mismatch, rate limit or +any other API error holds the PR. Image digests are content-addressed and need +no such check. The diff check reuses the file list the +path gate already fetches, so a PR the classifier refuses costs no extra API +call; the commit list and upstream refs are read only once the diff qualifies. A repo without an +enabled entry behaves exactly as before. `/hive approve` applies the same check, so its +reply never contradicts the lane. Any other outcome holds the PR as before. +The exception only prevents a new path hold: a PR that already carries `hold` +stays held until a person (or the #16269 release integration) clears it. +Do not remove `human_merge_paths` or manually clear a +hold to simulate this feature. The YAML example, per-field contract and seed +reload instructions live in the +[operator reference](/docs/hive/operator-reference/readme#human-merge-pin-only-rollout); +this section covers only the grammar and restrictions of the classifier. + +Repository keys are case-insensitive; duplicate normalized keys are rejected. +Absent/disabled entries have no effect. Enabled entries require nonempty paths, +kinds and trusted authors; unknown kinds are rejected, including when disabled. +The classifier accepts only existing modified files in both the actual guarded +path matches and exception paths, and checks **all** files in the PR: callers +pass the full changed-file list, so a pin bump that also edits any unguarded +file — including a changelog fragment or documentation — is not pin-only and +stays held for a person (#16326). Bump tooling that adds such files must open +them in a separate PR. Every +changed line must be a paired pin replacement. Supported forms are unquoted +`uses: owner/repo[/path]@<40-hex>` (an existing simple `# vN[.N[.N]]` +comment may change), `FROM image@sha256:<64-hex>` / `image: image@sha256:...`, +and literal `version: 1.2.3` / `ARG TOOL_VERSION=1.2.3` updates. Other syntax, +missing patches, line-count mismatches, added/renamed files, owner files, +permission/credential/signing text and non-pin edits fail closed. + +This classifier proves **syntax only**, not authenticated identity, exact-head +binding, file-list completeness, semantic interpretation or review of upstream +references. The sweep supplies the author (GitHub's PR author login), the +verified-commit provenance of the head, file-list completeness and the +upstream anchoring of each action SHA itself (#16399). The relay applies +the same checks through `Client.SetHumanMergePinOnly` (#16265) and additionally +requires a nonempty requested head SHA matching the PR head before and after +fetching files; +attribution and safe hold release are tracked in #16269. None of the +schema or classifier APIs grants permission to merge or clears a hold. Native +required checks and producer bindings, freshness, current reviews, substantive +objections, unrelated holds and configured soak must remain independent gates. + +Operators stage the key in the controller's configured `hive.yaml` seed, not in +the image repository (reload behaviour is documented in the operator reference +linked above). On an image that contains #16266 and #16265, reloading the seed +enables the sweep, `/approve`, and `hive-merge` relay exception at once. Non-GitHub +forge relays retain the existing fail-closed human-merge-path policy. + +There is **no minimum deployable version enabling this lane yet**. Utah rollout +and current-head positive/negative deployment evidence remain tracked by +projectbluefin/utah#1082 and #16242; projectbluefin/utah#1068 is not pre-authorized. + +**Pin-only exception rollout (#16242).** The opt-in key is +`auto_merge.human_merge_pin_only`; see the +[operator reference](/docs/hive/operator-reference/readme#human-merge-pin-only-rollout) +for its configuration and deployment prerequisites. The schema/classifier +(#16262), relay admission (#16265), and sweep admission (#16266) are +separate, landed changes: this attribution change alone does **not** enable the exception. +New path-hold comments retain `` and append +`` only when Hive +observes that exact head without a pre-existing hold. Legacy comments and +pre-existing holds are not retroactively attributed. + +The shared release API requires a later, qualifying exact head, the configured +App identity, an unedited App marker, and complete label-event history proving +one App-applied path hold immediately before the notice. Human-applied or +re-added holds, ambiguous history, and timeline errors keep the hold. Admission +callers must supply their live writeback gate (a missing gate or denied +hold-gate notice leaves the hold intact), wire that API after pin-only +qualification, and re-read labels; +that wiring remains part of the rollout, not an authorization to clear labels +manually. Required checks and their producer bindings, strict freshness, +current reviews and substantive objections, other holds, and configured soak +remain mandatory. Neither a pin-looking diff nor this API authorizes a merge. + +**Contributor PRs are held to the contributor-lane policy.** A merge request +for a PR whose author is not the hive App, a configured trusted bot, or a +trusted-author role is evaluated against the same `auto_merge.contributor_lane` +gates the sweep applies — verified claim tier within `require_tiers`, the +contributor `soak`, `min_head_age`, reviewer verdict, control labels (`hold`, +sentinel alert, parked-on-decision), human-merge paths and head-SHA pinning — +before `hive-merge` merges it. A refusal is terminal for that request (`.denied`), +names the failing gate in the result the agent sees (for example +`contributor-lane:claim-tier-untrusted (author tier "untrusted", require_tiers +merger, trusted)` or `contributor-lane:soaking, 27m0s remaining`), and is audited +as `merge_request_refused`. An agent cannot use the relay to land a contributor +PR the lane would not merge; the lane still merges it on its own tick once the +gates clear. Hive-authored PRs keep the relay's existing checks. + +**Actionable merge failures alert the operator.** Failures that require an +operator configuration change raise one dashboard system alert per repo+reason, +not one per PR or retry tick. The alert text names the fix: install/grant the +App Contents and Pull requests write permissions, adjust review/ruleset bypass +or approve the PR, make a missing required check report, or enable/use an +allowed merge method. Conflicts re-engage the fix loop instead of alerting, and +rate limits are treated as transient. Each aggregate banner retains every +originating PR; a successful merge or confirmed PR closure resolves only that +PR's blocker, not another PR's head-specific alert with the same reason. +Successful App merges still retire repository write-permission alerts and +disallowed-method alerts when the successful merge used that same method. +Method alerts also retire when a repository read positively confirms the +originally refused method is now enabled. A different method's success cannot +prove squash/rebase/merge settings, and unknown methods or failed reads retain +the banner. Reviews, absent CI and approval-held runs remain PR/head-specific; +another PR's successful merge does not prove those blockers resolved. + +The existing five-minute alert revalidation also retires a missing-required-check +banner when every named check succeeds on the PR's exact current head. Check-run +success, neutral and skipped conclusions follow the existing CI policy; commit +statuses must succeed. Readable protection metadata binds checks to the required +App when specified. The observer completes bounded pagination, rejects older-head +evidence and re-reads the PR head/base before retiring the originating blocker. +API errors, incomplete evidence, unknown protection metadata and pending/failed +checks retain the alert. Concurrent refusals replace the observation token and +cannot be cleared by an older observation. This changes only alert freshness: +all CI, review, protection and merge gates remain authoritative and unchanged. + +```yaml +auto_merge: + no_ci_ok: + - your-org/docs-only-repo +``` + +### Self-merge review gate + +Immediately before an automerge lane merges a PR — the self-authored sweep for +the App's own and trusted-bot PRs, and the trusted-author tier for a human's +(after the head SHA is re-verified) — it reads the swarm review verdict for that +head from the same `review-verdicts.json` the merge-eligible lane uses and +classifies it as `no-review-bundle`, `awaiting-review-approval`, +`changes-requested:`, `requires-human` or `approved` +([#12592](https://github.com/hivecommons/hive/issues/12592)). The class +follows the normalized **aggregate** verdict — the same one the contributor +lane and `stage/085-needs-decision` route on — so a `requires_human` head +reads as `requires-human` to the merge gate even when one perspective asked +for changes; the perspective list only names who asked. The mode is +`governor.review_gate.mode: off | shadow | enforce` (default `shadow`), raised +to `enforce` by `review.require_approval` and to at least `shadow` by +`review.shadow`; all three are re-read on every evaluation, so a config reload +takes effect without a restart. + +- **shadow** (default): the merge proceeds as before; the evidence bundle for + the head (started on the spot when none exists) records + `shadow.review_gate` with `lane: self-merge` (the App's own PRs), + `trusted-bot` or `trusted-author`, `would_have_held` and the reason, so the Evidence card's Shadow gates panel can show what the gate + would have held. +- **enforce**: anything but `approved` holds the merge with reason + `review-gate:`; the PR is retried on a later sweep. A trusted + merger's GitHub **Approve** review on the exact head outranks every + non-approved swarm outcome — `requires-human`, `awaiting-review-approval`, + `no-review-bundle` and `changes-requested:` alike: the person + has read the reviewer's objection and decided the head lands as-is. The + outcome becomes `human-approved` and the merge proceeds. +- **off**: no evaluation. + +**A decision is head-scoped — except across the hive's own base refresh.** +A recorded operator decision (dashboard Approve, `/hive decision …`, a +hand-applied return label) names the exact head the person saw; a new head +is a new tree nobody has decided on, so the record is superseded and the +reviewer's `decision_requested` question stands again. The one head change +that does not supersede it is the hive's own `require_current_base` refresh: +a merge commit authored by the App, committed by GitHub (`web-flow`) or the +App and carrying a signature GitHub verified, whose parents are the decided +head and a commit on the base branch, and whose three-dot diff against the +base is file-for-file (name, status, blob, line counts, patch) identical to +the decided head's. An App login GitHub derived from an unsigned commit's +author email does not count, and a compare that lists GitHub's 300-file cap +cannot be verified, so neither carries +([#16860](https://github.com/hivecommons/hive/issues/16860)). Up to five such refreshes may stack before any gate reads +the PR: the carry walks the first-parent chain back from the new head and +every hop must itself pass the same check, so two App merge-from-base +commits in a row still carry while a content commit anywhere in the chain +does not ([#15766](https://github.com/hivecommons/hive/issues/15766)). +Before any gate reads the new head — the reviewer-verdict +stage route, the automerge review gate, operator admission and the hold +guard — the decision is re-recorded on it with `carried_from_head` naming +the original, and one INFO line `decision carried over base refresh` is +logged; the reviewer route then reads `decision_answered=true` instead of +parking the PR at `stage/085-needs-decision` a second time +([#15751](https://github.com/hivecommons/hive/issues/15751), seen on #15649). A content push, +a merge by anyone but the App, a rebase, a refresh whose diff differs, and +GitHub review approvals (which are never moved between heads) all keep the +record where it was. The answer for a (PR, head) pair is memoised, so the +check costs one commit read and two compares per new head. + +Each evaluation writes one audit line, action `review_evaluated`, detail +`lane= would_hold= reason= enforce= head=`, +plus `human_approver= overrode=` when a human's +approval cleared the gate, so the audit trail records who overrode what. +The gate covers every sweep lane because the swarm reviews every PR +regardless of author ([#12974](https://github.com/hivecommons/hive/issues/12974)); +until then it covered the `self-authored` lane only, and a trusted human's PR +(hivecommons/hive#12966) could merge through the trusted-author tier with no +swarm verdict at all. The contributor lane has its own +`auto_merge.contributor_lane.require_reviewer_verdict` (default on). The merge +and the CI snapshot are recorded in the evidence bundle in every mode, +including when the bundle is created at merge time. + +### Trusted bot authors + +The self-authored automerge sweep merges the App's own open, CI-green PRs. It +also merges PRs from `auto_merge.trusted_bot_authors` through the identical +gates (required checks green, mergeable, no hold/exempt label, intent tier, +approval desk, head SHA re-verified at merge time). The default is +`dependabot[bot]` only; set an explicit empty list to keep the sweep App-only, +or add other dependency bots you trust. Each merge is recorded with +`lane=trusted-bot` so audits can tell it from `lane=self-authored`. Changing +ACMM level at runtime restarts the relay generation when the L6 self-merge gate +changes, so the sweep starts or stops under the new level immediately. A +promotion into L6 never auto-releases existing level-applied `hold` labels; use +`release_level_holds: true` on `PUT /api/packs/level` for a deliberate one-off +release. Hub, config-driven, and ordinary dashboard promotions leave those holds +for human removal. On a dashboard promotion into L6, Hive shows an informational +modal with the held App-authored PRs and per-repo auto-merge switches. +Switching to L6 turns auto-merge on for all active repositories; the owner can +then switch off repositories that should not participate before manually +removing `hold`. + +```yaml +auto_merge: + trusted_bot_authors: + - dependabot[bot] + - renovate[bot] +``` + +The same list is editable from the dashboard: **Settings → Features → Auto +merge → Trusted bot authors** shows a toggle per bot. Known dependency bots +(`dependabot`, `renovate`, `mergeraptor`, `pre-commit-ci`, `github-actions`) +are listed first, bots currently authoring open PRs in your repos are +discovered from the last scan and listed automatically, and any other login +can be typed in. Saving writes `auto_merge.trusted_bot_authors` in full; +turning every bot off writes an explicit empty list (App-only sweep). The +underlying endpoint is `GET/PUT /api/config/auto-merge` (owner-only), whose +response carries `bot_authors: [{login, source: known|discovered|custom, +trusted}]`. + +Every login on that list — a Settings toggle or a typed-in custom bot — is +owned by the trusted-bot lane: the contributor lane hands it off as +`trusted-bot-lane` (never `contributor-lane:app-authored`), and every +`automerge skip` / `automerge hold` line the self-authored sweep logs carries +`tier=trusted-bot` so a stuck bot PR can be grepped by lane. The lane's +contract is "safety is established by CI", so the review swarm's verdict on +a trusted bot's PR is **advisory** by default: a `requires_human`, +decision-requested or `changes_requested` verdict is recorded on the +evidence bundle and logged (`trusted-bot lane: review verdict advisory`) +but neither holds the merge nor parks the PR at "needs a person". Set +`auto_merge.trusted_bot_skip_review: false` to make bot PRs obey the swarm +exactly like the App's own; a trusted human's `changes_requested` review +always holds regardless. When `auto_merge.required_checks` names a check +the repo never produces (for example `build-gate` declared hive-wide but +absent on a docs repo), the lane does not wait forever: if at least one +other check reports on the head and none is red or still running, it merges +on "every reported check green" and warns once per repo per hour +(`trusted-bot lane: required check "build-gate" never reported on +/`); if nothing else reports, the PR is held with +`required-check-never-reported:`, which the Activity Monitor shows as +the human-gate reason. Declare the repo's real set under +`auto_merge.repos..required_checks` to clear either condition. + +### Event-driven sweeps on the ForgeState cache + +With `forgestate.enabled: true` the three sweep lanes (self-authored, +trusted-author, contributor lane) stop listing `/pulls` per repo on the 10 s +ticker. They read one shared open-PR set from the ForgeState cache +(`pkg/forgestate`, [#13373](https://github.com/hivecommons/hive/issues/13373)) +and run when a `check_suite`, `check_run`, `status`, `pull_request_review` or +`pull_request` webhook arrives for a PR: that delivery patches the cache and +triggers a pass that evaluates only the affected PR(s). A periodic floor pass +over the whole cached set runs every 5 minutes as the fallback when no events +arrive (`automergeSweepFloorInterval`). Before any merge the lane re-reads the +PR through the cache with a 60 s freshness bound +(`automergeMergeFreshnessBound`): an item older than that is refreshed once +from GitHub; a repo whose snapshot is marked stale is skipped at enumeration +and its PRs are never merged (`forgestate-stale`); a head SHA that moved since +evaluation defers the PR to the next pass. The review gate, required checks, +hold/exempt labels, intent tier and the existing head-SHA re-verify at merge +time are unchanged ([#13377](https://github.com/hivecommons/hive/issues/13377)). +With `forgestate.enabled` off (the default) the lanes list `/pulls` on the +ticker as before. + +### github-actions[bot] PR takeover + +A PR that `github-actions[bot]` opens with a workflow `GITHUB_TOKEN` never +triggers `pull_request` workflows (GitHub's anti-recursion rule), so a required +check those workflows produce stays `required-check-missing` forever. When +`github-actions[bot]` is in `auto_merge.trusted_bot_authors`, the sweep takes +such a PR over instead of polling it: once the head is older than both +`auto_merge.min_head_age` and 30 minutes with no `pull_request` run at all, the +App pushes the same change (the bot head's tree on the merge base) as one +DCO-signed-off commit to `hive/takeover-`, opens a PR with the original +title and body plus `Supersedes #`, comments `Superseded by #N` on the bot +PR and closes it. The App PR triggers workflows normally and merges through the +self-authored lane. Fork heads are never taken over, and each bot head SHA gets +one attempt whatever the outcome. No GitHub App secrets are needed in the +workflow that opened the bot PR. + +```yaml +auto_merge: + trusted_bot_authors: + - dependabot[bot] + - github-actions[bot] + bot_takeover: + enabled: true # default; set false to leave such PRs held +``` + +### Breaking-titled or `needs-owner-merge` PRs wait for a human + +A PR whose trimmed title starts with `⚠️` (U+26A0, with or without the VS16 +selector — the PR-title convention for a breaking change) or that carries a +`needs-owner-merge` label is never merged by hive. One shared predicate, +`automerge.RequiresHumanMerge(pr)`, is evaluated once per PR where each lane +already computes eligibility (the App self-merge, label-queued, trusted-author +and contributor prefilters, and the refetch just before a merge), so the merge +train — which draws its candidates from the same prefilters — never fronts or +carries such a PR either. The prefixes and labels are configurable via +`auto_merge.human_merge_title_prefixes` and `auto_merge.human_merge_labels` +(see the operator reference); an empty list turns that half of the rule off. + +When the PR is otherwise merge-ready (green checks, approvals satisfied) the +stage tracker parks it at **090 Ready for human merge** with the chip +*human merge* and the reason *breaking change — owner merges*; the owner +merges it with **Merge now as maintainer** (the existing gated operator +path; **Approve and let hive merge** is greyed, since the lanes never +merge a breaking change) or on GitHub. Hive posts one comment, through the writeback +gate, saying it will wait for a human. The rule exists because a ⚠️-titled +PR was auto-merged by the trusted-author lane while its owner was still +deciding whether to ship it. + +### Final base preparation: one refresh owner, no ready-work blockade + +For repositories governed by `auto_merge.require_current_base` (including +the inherited default), automatic base refreshes share **one preparation +owner per canonical repository and destination branch**, across App, +trusted-author and contributor lanes. Repository names are case-insensitive; +branch names remain case-sensitive. Unrelated destinations progress independently. + +A behind head enters final preparation only after its existing CI, review +and lane admission gates pass, **without first requiring an up-to-date base**. +The owner refreshes with an expected-head SHA and then waits for CI and review +on the new head. Pending runner jobs (including queued sign-off checks) are +pending, not failures. Preparation is outside ready merge-train membership: +`base-refresh:preparing` and `base-refresh:queued-behind#N` remain at CI / Review, +never ready-to-merge. Waiting heads may continue development and review. +The adopted stale-red recovery path can also admit its existing, proven +base-fixes-failure repair; that admission never authorizes a merge. +Explicit trusted-human merge-forward repair shares the same owner and +write-ahead identity. Its conflict-repair allowance lasts only through the +existing mutation-reconciliation TTL; a failed/conflicting result returns to +the normal repair path, never a ready seat. + +**Ownership serializes refreshes, not ready merges.** A successor that is +already current-base, CI-green and reviewed passes every normal merge gate +without waiting for a preparing owner. A behind successor cannot skip testing. +Train sibling refreshes and client-side follow-up/relay/supersession updates +defer to preparation on these repositories; opted-out repositories retain +their previous behavior. + +Ownership and first-admission FIFO tickets live in `/data/base-preparation/`, +with per-destination file locking and atomic durable snapshots. An update +identity (PR/head/base SHA) is recorded before the request, across lanes, +concurrent sweeps and restarts. An unchanged unresolved pair waits; after the +existing mutation-reconciliation TTL it can retry only with an authoritative, +still-identical head and the API's expected-head guard. Accepted updates must +complete their normal current-head gates; no approval is transferred. +Release occurs on merge, closed/missing/retargeted/draft/conflicting/held heads, +failed checks, rejected review, or lost admission. An unresolved refresh or active +repair keeps exclusive ownership. A completed refresh whose new head has known +pending CI/review can yield to an independently ready successor under the +[readiness-first preparation gates](https://github.com/hivecommons/hive/blob/v5/docs/readiness-preparation.md); the +former owner retains its ticket, original priority and attempt deduplication. +Pending ownership remains bounded by the existing review-pending dwell (its +default when stall detection is disabled), so a genuinely hung owner yields to +successors. +Ordinary waiting tickets are removed when their head changes or stops qualifying; +yielded owners retain their tickets through pending CI/review observations. +Admission provenance prevents a different lane's non-admission from revoking +the owning lane's reservation or FIFO ticket. An old waiting ticket reserves +order only: its head must qualify afresh in its lane before becoming owner. + +The persisted owner head is the **admitted source head**, so a different live +head is not by itself a stale reservation: an App-authored refresh preserves +that source and its write-ahead attempt while the new head earns CI and a fresh +review. Required-green alone does not release ownership or confer approval. +State-changing lane observations re-read the head/base, author, policy labels +and review inputs outside the preparation lock, then compare the persisted +owner/attempt or exact waiting ticket before settling it. Superseded callbacks +cannot release a newer reservation or rewind a yielded head. An accepted refresh +whose expected head is still live remains exclusive through the existing +mutation-reconciliation window, even if an older evaluation reports failure. +Unavailable or changed evidence retains ownership for normal reevaluation; +neither this validation nor a dashboard snapshot forcibly clears the queue. + +Audit logs use `automerge base preparation selected`, `refresh claimed`, +`waiting`, `released` and `completed owner yielded`, with repository, base, PR, +head/base SHA where relevant, and release/skip reason. `automerge update-branch` and the sweep's +`updated_branches` count actual successful refresh effects; queued/preparing +reasons do not consume the branch-update budget. Ready-only train seating and +reviewer dispatch scheduling are separate policies. + +The review planner observes the durable preparation owner once per destination +per pass. Only its exact live, CI-green, mergeable head with a verdict still +owed receives `base-preparation` review priority; it does not need a ready train +seat. A refreshed head must pass the existing App-authored base-refresh proof: +the attempted head is preserved, the merged base lies on the destination branch, +and the PR's content is unchanged. The actual merged base can be newer than the +attempt's recorded base SHA; this remains valid after a restart without rewriting +ownership. An author's content push or amended merge cannot inherit priority. +Closed, held, retargeted, released and expired owners receive no promotion. +Observation is read-only and performs GitHub reads outside preparation locks. +Busy valid reviews are never interrupted. After a confirmed preparation review +handoff, other non-pending heads promoted by the existing three-cycle starvation +rule go first as `base-preparation-fairness`; their confirmed service restores +preparation preference. Unrelated deliveries cannot clear the owed yield. This +uses the existing dispatch history, survives restarts, and prevents successive +owners from indefinitely starving aged work. Without an active eligible owner, +the existing review order is unchanged. Priority is not review approval or merge +eligibility: normal label, model, current-head verdict and merge gates still run. +`review swarm kick planned` exposes `priority=base-preparation`; the normal +waiting reasons continue to expose reviewer/parallel-slot exhaustion. +`automerge base preparation observation skipped` with +`reason=unverified-app-base-refresh` records a failed refreshed-head proof. + +Human pushes, direct merges and external automation can still move a base. +Such a move is coalesced until the preparation owner qualifies again; it must +then refresh and re-pass current-head gates if still behind. This scheduler +cannot stop external writers and does not relax strict current-base checks. +Deploying the changed hive binary activates the policy; no agent, memory, +review, CI, hold or authorization setting needs changing. + +### CI reporting reconciliation + +An unfinished required check is not green merely because its Actions workflow +ended. PR CI evaluation now reports `ci-reporting-stalled` only after two fresh, +consistent observations separated by a propagation grace. It verifies the exact +current PR head, Actions App/check/suite provenance, owning workflow execution, +latest attempt's job-to-check URL, and a final head/base/attempt consistency read. +A newer execution, changed head, unsupported provider or unavailable API cannot +be used to declare a stall. Ordinary queued/running workflows remain ordinary +pending CI, regardless of elapsed time. Workflow success does not fabricate a +successful check; workflow failure and pending job/check reporting remain +separately visible. + +The structured `CIReportingObservation` and existing reason tooltip identify +the check, run, latest attempt, job, conclusion and observation time. API refusal +is `ci-reporting-unverified`, not green. The stage remains CI-pending-compatible, +and all current-head review, authorization, hold and merge gates remain intact. +Commit-only/base observations retain their existing behavior. No rendering API +polling is added: evaluation uses an identity/PR/head/check-set-scoped, bounded +single-flight cache. `HIVE_CI_REPORTING_RECHECK` and `HIVE_CI_REPORTING_GRACE` +default to five minutes; verified check/workflow events request a refresh bounded +to once per minute. Duplicate deliveries cannot shorten grace; cold restart +requires fresh consistency observations again. + +**Automatic recovery is not implemented or enabled.** A confirmed stall exposes +owner action: inspect the exact workflow's current attempt and logs before one +affected-workflow rerun. Do not rerun all CI or rebase to hide reporting failure. +The existing filesystem mutation ledger only serializes users sharing that +filesystem; shared-CI post-effect comment markers are not atomic cross-hive +claims. Future recovery must prove a pre-mutation episode claim and enforced +designated executor (other hives observe only), with durable ambiguous intent +blocking blind retries. Actions rerun RPCs accept no fencing/idempotency token: +designated routing or a forge CAS alone is not failover fencing or exactly-once +execution, and ambiguous intent must not be automatically stolen after a TTL. +App permission changes, live configuration and experimental integration +activation are not prerequisites for detection and are not made by this change. +### Merge train: ready PRs lead + +Every lane groups its candidates on one base whose changed files overlap +into a **merge train** (`auto_merge.merge_train.*`, [#15117](https://github.com/hivecommons/hive/issues/15117)) +and merges one front at a time; the siblings park at stage/080 with lane +reason `merge-train:queued-behind#:/:…` and, the moment +the front merges, are update-branched (`behind`) or handed to the rebase +resolver (`dirty`) so the next front is evaluated on a current base. Hive's +own repo also runs the current-base gate (`require_current_base`), which +holds a behind head until the update lands. On current-base-gated repositories +the separate preparation owner above refreshes the next admitted head, rather +than refreshing every waiting sibling when a front merges. + +**Dependency-bot branches are the bot's to rebase.** A PR whose head ref is +`renovate/*` or whose author is `renovate[bot]`, `dependabot[bot]` or +`mergeraptor[bot]` never gets a hive commit merging its base: no lane +update-branch, no current-base refresh, no merge-forward, no merge-train +update or rebase request, no trusted-author fixer rebase, no adopted-PR +recovery update and no `hive-merge --update-branch`. Renovate stops rebasing +a branch for good once another identity has committed to it +([projectbluefin/utah#1097](https://github.com/projectbluefin/utah/pull/1097)). +A behind bot branch holds as `behind` (logged once per head as `leaving the +base sync to the bot`) until the bot rebases it — Renovate does so on its own +when the repository requires up-to-date branches, and resolves conflicts on +its own. On a repository gated only by `require_current_base_default` (no +GitHub up-to-date rule, so no bot rebase is coming) such a head merges as +tested, like a head the App may not write. + +The train's order is **readiness first**. Each pass the lane sorts the +members by what it last saw of their heads: a head at the merge gate — +green, approved, soaking or waiting on a sweep — leads; a head the lane has +not evaluated since it was pushed comes next (so it is evaluated and +sorted); a head still at CI / Review trails; a blocked head (red required +check, terminal hold) trails everything and never fronts. Within a tier the +old tiebreak holds (clean-mergeable first, then oldest, then number). The +order is recomputed every pass, so a member that turns green moves up and +one that turns red moves back. The front of a train is therefore always a +ready member when the train has one; a train whose every member is still +short of the gate has a *provisional* front, and the Activity Monitor says +so rather than reading "1st in the merge queue". + +This replaced the age-first order after hive's own #15741, still at CI / +Review, led #15748 and #15755 — both green and queued at 080 — and nothing +merged until its checks finished. In the Activity Monitor only members at +080 and beyond ride a train chip in the *Merge queue* column; a member still +at CI / Review keeps its chevron in its own column with a muted +"train · joins behind #N when green" note. + +**Membership is ready-only** ([#15825](https://github.com/hivecommons/hive/issues/15825)). +The rule: *items that have not passed the review or CI is not green should +not be (a) ready for merge, (b) in a merge train.* A PR takes a seat only +while its **current head** is green, has every required perspective +verdict recorded, is mergeable, not conflicting and not held. A PR that +shares files with a train but is short of that is a *candidate*: the +tracker keeps the overlap note, but it holds no position and is never the +front. A member that regresses — new push (head moved), CI pending or red, +a verdict owed again, a conflict with the base — is **ejected** on the +next evaluation (one INFO line `merge train: member ejected pr=N +why=head-moved|ci-pending|ci-red|verdict-owed|conflicting`), the next +ready member fronts and merges, and the ejected PR re-enters at the back +once it is ready again. Its tracker row drops back to the CI / Review +column (never the *Merge queue* column) with a caption that says what is +owed ("left the merge train — new push, CI re-running after push") and a +gray lineage pill ("left merge train · pushed 3m ago"). Among ready +members the order is the readiness tiers above, then age. The one +exception is a member the train itself made dirty by merging the front +ahead of it: it keeps its seat (trailing every clean member) while the +resolver rebases it, so the rebase keeps its place in line. Its row still +shows in the CI / Review column while the rebase runs ("Rebasing · attempt +1/2"): the rebased head has no CI or verdicts yet. The tracker's train +header counts seated members only — a candidate or an ejected row never +adds to "merge train · N PRs" — and a seated row always reads its seat +("Merge train · 2nd of 2 · behind #15771"); "checking now" is said only +of the PR the sweep is evaluating at that moment. + +### Trusted-author auto-merge + +`auto_merge.trusted_authors` is a third, default-off sweep tier for +human-authored PRs. It exists for hives whose maintainers want Hive to land a +maintainer's own green PR without waiting for Prow/tide's distinct +`lgtm`+`approved` path. It is not a privilege escalation: the PR author must be +in the hive's `dashboard.authorized_users` allowlist at the configured role +(`merger` by default, or `owner`), and by default GitHub must also report that +the author has write/maintain/admin permission on that repository. If that +GitHub permission lookup errors, the PR does not merge. + +The tier uses the same merge mechanics as the self-authored sweep: required CI +must be green, the PR must be open, non-draft, mergeable, SHA-pinned at the +evaluated head, and the merge method follows `hive-merge` semantics (forward +merges use merge commits; other PRs squash). It refuses excluded labels +(`hold`, `do-not-merge`, and `needs-human` by default), existing hold/exempt +labels, fork PRs whose author is not a repo member, and any PR with an +outstanding `CHANGES_REQUESTED` review. Each merge records the tier as +`trusted-author` and records an audit note naming the author role, GitHub +permission, and green head SHA: an `auto-merge` section of the PR's `hive:status` +card in `quiet` notification mode (the default), a standalone comment in `normal`. + +```yaml +auto_merge: + trusted_authors: + enabled: false + repos: [] # optional allow-list; empty = all managed repos + require_role: merger # merger or owner + require_github_permission: true + exclude_labels: + - hold + - do-not-merge + - needs-human +``` + +Operators can set `require_github_permission: false` only when the +`authorized_users` role list is the desired authority, but fork PRs still need a +successful GitHub permission check so non-member forks do not merge through +this tier. + +The same block is editable from the dashboard: **Settings → Features → Auto +Merge → Trusted-author auto-merge** writes `auto_merge.trusted_authors` through +owner-only `GET/PUT /api/config/auto-merge`. The form exposes the enabled +switch, repository allow-list (select none for all watched repos), required +role (`merger` or `owner`), GitHub permission requirement, and excluded labels +so hosted spokes can opt in without editing `hive.yaml`. + +### Contributor-lane auto-merge + +`auto_merge.contributor_lane` is a fourth sweep tier, **default on**, for PRs +that this hive's own contributor lane produced. When Hive claims an issue for +a contributor it posts an App-authored `` +marker on the issue; the contributor's +PR then closes that issue with `Fixes #N`. Before this tier existed such a PR +was skipped by every lane (`untrusted-author-role` from the trusted-author tier, +`not-app-authored` from the App tier) and waited indefinitely for a human +`/lgtm` + `/approve`, even though the hive had already vetted and reviewed the +work. The maintainer position is that work the hive trusted enough to hand out +should land unattended once it is green, so the tier ships enabled; set +`enabled: false` to restore the wait-for-human behaviour. + +The claim marker on its own proves only that the relay leased the issue to a +connection: relay registration (`POST /api/contribute/register`) is +self-asserted and every new profile starts as `newcomer`. So the tier merges +only for contributors the operator vetted: the marker's `tier=` must be in +`require_tiers` (default `trusted`, `merger`; only operator-granted tiers are +accepted, never the auto-promoted `newcomer`/`contributor`), and `verified=true` +(the contributor proved the GitHub login with `POST +/api/contribute/reissue-token`). Markers written before these fields existed +read as `newcomer`/unverified and are refused. + +The marker is not the only statement of trust the hive holds. The operator +sets each contributor's trust tier on their profile in the hive's contributor +registry (**Contribute → Admin**, `POST /api/contribute/admin/contributors/ +{id}/trust`), and that tier is what the claim marker copies when the relay +leases an issue. So the tier also admits a PR directly from the registry +(`registry_tiers_sufficient`, default `true`): if the PR author's profile +carries a tier in `require_tiers`, no linked issue or marker is needed. Live +on hive's own hive a contributor the operator had marked `trusted` was still +skipped with `contributor-lane:no-linked-issue` because the PR body said +`Part of #N` rather than `Fixes #N`, and with `contributor-lane:no-claim` when +the issue had been claimed outside the relay; the registry path admits both. +Every other gate below still applies to a registry-admitted PR. Set +`registry_tiers_sufficient: false` to require the marker for everyone. + +A registry-admitted author also gets their CI started. GitHub's fork-approval +policy holds a first-time contributor's `pull_request` runs in +`action_required`, and the hive otherwise approves a human-authored lane's +held runs in only one other case: the gated-run approval sweep +(`governor.ci.auto_approve_workflows`, default `true`, hivecommons/hive#16603) +approves held runs for allowlisted actors (`auto_approve_workflow_actors`) and +for a head a verified owner or merger admitted from the dashboard (the +`hive-ok-to-test` workflow approves same-repo heads only). hivecommons/docs#481 by a `trusted` registry contributor sat 17 hours +at `required-check-missing:Audit production dependencies` until an operator +clicked "Approve and run". When the registry path admitted the author and the +lane stops at `required-check-missing:`, it now approves the head's held +runs once (`POST /repos/{owner}/{repo}/actions/runs/{id}/approve`, fork head +included), posts one `` audit +comment naming the author and tier, and logs `contributor-lane approved held +runs` with the run ids (`approve_held_runs_for_registry_trusted`, default +`true`). Claim-marker, auto-promotion and association admissions are never +approved for, nor is a PR carrying the sentinel or an `exclude_labels` label, +nor one touching `.github/workflows/**`. The App needs **Actions: Read and +write** for the call; without it the approve fails, is logged once per head, +and the PR waits for a person as before. + +The lane also asks Prow to start presubmits for any admitted author +(hivecommons/hive#17474). On a Prow-managed repository (Prow's labels such as +`size/*` or `needs-ok-to-test`, or its `[APPROVALNOTIFIER]` comment) the +trigger plugin runs presubmits for a non-member's fork PR only after a trusted +user comments `/ok-to-test`, so #17359 sat green on GitHub Actions while Tide +reported `Jobs … have not succeeded`. While such a fork head is not green, the +author's `author_association` is not `OWNER`, `MEMBER` or `COLLABORATOR`, the +PR has no `ok-to-test` label and Prow has reported no presubmit status on the +head (a status other than `tide` from the account that reports `tide`), the +lane posts `/ok-to-test` once per head with the same per-head marker and +mutation-boundary dedupe as the trusted-lane command. If Prow replies +`Cannot trigger testing until a trusted user`, the lane logs it once with +`skipped=prow-rejects-bot-commands`, leaves one +`` needs-human note and never posts the +command on that PR again; making the App a Prow trusted user is the +repository's Prow configuration. Prow's answer is the repository's, so it is +also remembered per repository (hivecommons/hive#18608): once Prow has refused +the App anywhere in the repository, the lane skips the first command on every +later fork PR there and leaves the `` note +directly. The memory is not stored: after a restart it is re-derived from one +bounded read of the repository's comments of the last 30 days (Prow's refusal +addressed to the App, or the hive's own note quoting it), kept for an hour, and +cleared while the repository carries `.github/workflows/hive-ok-to-test.yml`. +A repository with no refusal on record behaves as before. The note in that case +does not quote Prow's wording, so only a real refusal renews the memory and it +ages out if Prow later trusts the App. The merge-request relay's read-only +evaluation posts nothing. + +A PR merges through this tier only when all of the following hold: + +- The PR author is admitted by one of three paths: + - **Adopted by the hive**: the stage store records an in-place adoption of + the PR (`stage/074-adopted-by-hive`) and the head being evaluated is + exactly the head the hive adopted or pushed (`AdoptedHead`). The hive + owns that head, so the original author's tier, marker and GitHub + association are not consulted — hive owner decision (hivecommons/hive, + 2026-10-27): "If items are adopted, then the hive agents own it and they + should be eligible for auto merge." The sweep logs `contributor-lane + admitted reason=contributor-lane:adopted-by-hive adopted_head=` and + the merge log carries `admitted_by=contributor-lane:adopted-by-hive`. A + contributor push over the adopted head yields the adoption (074 → 072, + `AdoptedHead` cleared), so the next pass falls through to the two paths + below; a superseding adoption (`hive/adopt-`) is never admitted on the + original PR — its App PR merges through the self-authored lane and closes + the original. Off with `governor.labels.stage.adoption.auto_merge: false` + (default on). Every other gate below still applies. + - **Registry**: the author's contributor-registry profile has a trust tier in + `require_tiers`. The sweep logs `contributor-lane admitted + reason=contributor-lane:registry-trusted registry_tier=` and the + merge log carries `admitted_by=contributor-lane:registry-trusted`. A + profile at `newcomer`/`contributor`/`revoked`, no profile at all, or + `registry_tiers_sufficient: false` falls through to the marker path with + that path's skip reasons unchanged. + - **Claim marker**: the PR body closes a same-repo issue + (`Fixes`/`Closes`/`Resolves #N`) whose App-authored `hive:claim` marker has + `kind=contributor`, `who=` equal to the PR author, and `hive=` equal to this + hive's `hive_id`. Markers from other commenters, other kinds, other authors + or other hives are rejected with distinct skip reasons + (`contributor-lane:no-claim`, `contributor-lane:claim-author-mismatch`, + `contributor-lane:claim-other-hive`); a body with no closing keyword skips + with `contributor-lane:no-linked-issue`. The marker's `tier=` must be in + `require_tiers` (`contributor-lane:claim-tier-untrusted`) and it must say + `verified=true` (`contributor-lane:claim-unverified`). + - **Auto-promotion**: when the marker path fails on tier, the conservative + clean-history ratchet (`auto_merge.contributor_tier.auto_promote_after_merged`, + default 5; negative disables) admits the author if their last N merged + PRs have no revert or sentinel-alert evidence — none is itself a revert, + none carries the sentinel label, none was undone by a later merged + `Revert ""` / "This reverts commit <sha>" PR — and the author is + not `revoked` in the registry. By default the merges are counted across + **every repository the hive manages** + (`auto_merge.contributor_lane.auto_promotion_scope: hive`): trust is a + property of the person, and the small satellite repos of a multi-repo + hive never reach the threshold on their own (hivecommons/docs#481 sat 17h + at `contributor-lane:claim-tier-untrusted` while the same author had nine + clean merges in hivecommons/hive; #14517). The PR's own repository is + walked first; only when it is short does one `search/issues` query + (`is:pr is:merged author:<login> repo:… repo:…`) find which other hive + repos hold the author's merges, and only those are walked for revert + evidence — a revert or sentinel hit in any repository blocks. When + GitHub refuses that query with `422 Validation Failed` (a listed + repository was renamed, deleted or is invisible to the App, or the + author cannot be searched), its repositories are re-asked one at a time + so the searchable ones still count; each refused (author, repository) + pair warns once (`contributor-lane auto-promotion search cannot see + repository for this author`) and is left out of the search for an hour + (#17148). Any other search failure counts the PR's own repository only. + Promotion is a property of the author in the hive, not of a PR, so the + sweep announces it **once per (hive, author)**: the first PR that earns it + gets a `<!-- hive:trust-promoted login=… merged=N scope=hive + repos=hive:4,docs:1 -->` comment ("@login is now trusted for + contributor-lane merging in this hive … Applies to their open and + future PRs here"), and the author's other open PRs, later PRs and PRs + after a restart post nothing — the "announced" fact lives in the stage + store (`trust-promoted:<login>`), with the PR's own marker as a + fallback when the store was rebuilt. Revert or sentinel evidence that + withdraws the promotion forgets the announcement, so regaining it is + announced once more (#15443). Every admission still logs + `contributor-lane admitted reason=contributor-lane:auto-promoted + merged_prs=5 scope=hive repos=hive:4,docs:1`. `auto_promotion_scope: + repo` restores the per-repository count. +- When neither admission path above vouches for the author, GitHub's + `author_association` for the PR author must be `OWNER`, `MEMBER`, + `COLLABORATOR` or `CONTRIBUTOR`; `NONE`, `FIRST_TIMER`, + `FIRST_TIME_CONTRIBUTOR` or a missing value then skip with + `contributor-lane:author-association`, outranking the marker path's own + reason. A verified claim marker or a registry tier is this hive's own + statement of trust and admits the PR regardless of the association — + GitHub reports `FIRST_TIME_CONTRIBUTOR` for every relay contributor's + first PR to a repo, which left admitted, green, reviewer-approved PRs + skipping every cycle (#12344; #12195, #12290). An unmarked, unregistered + first-timer is still never admitted. +- The diff does not touch `.github/workflows/**` or `.github/actions/**` + (`contributor-lane:workflow-path`) — **or** a hive owner / trusted merger + has explicitly approved the current head + (`owner_approval_releases_workflow_fence`, default `true`, + [#14664](https://github.com/hivecommons/hive/issues/14664)). Explicit + approval is a GitHub pull-request review in state `APPROVED` whose commit + is the current head by a login the hive's merger authorizer trusts (the + same bar that releases a `requires_human` verdict), or a dashboard + approval (`/hive decision approve`, which posts `/lgtm` + `/approve` + attributed to the maintainer and bound to the head) or a trusted merger's + own `/hive decision approve` comment posted after the hive first observed + the head. An unmarked approval is bound to the PR `updated_at` pinned on + the hive's first sweep of the head, not to the push: an approval typed + between the push and that sweep is judged stale and must be typed again + (fail-closed by design, + [#14754](https://github.com/hivecommons/hive/issues/14754)). Approval on an + earlier head does not count: a new push re-arms the fence and the 085 note + reads "awaiting owner approval … re-approve after a push". The one + exception is the hive's own base refresh — the update-branch the lane runs + on a BEHIND PR under a strict up-to-date rule, or another merge of the + base branch GitHub verified as the App's (signed, committed by `web-flow` + or the App). When every commit between an approved head and + the current head is such a merge (at most five in a row) and the PR's + three-dot diff against the base is file-for-file what was approved, the + approval carries over and the lane logs `workflow-path fence approval + carried over hive base refresh login=… approved_head=… head=…`. The + earlier approval is read from a trusted merger's standing `APPROVED` + review, a dashboard approval marked for that head, or the hive's own audit + marker for it; the approver must still be trusted. A contributor commit + re-arms the fence even when it leaves the workflow files alone (the + existing head-bound rule), as do a rebase, a base merge pushed by anyone + but the App, and a base merge that changed a file the PR also changes. + When released the lane logs `workflow-path fence released by owner + approval login=… head=…`, leaves one `<!-- hive:workflow-approval head=… + by=… -->` audit comment per head (with `from=<approved head>` when the + approval carried over), and the PR goes through every other gate below + like any other. Merging such a PR needs the App's + **Workflows: Read and write**; when GitHub refuses the merge for want of + it the lane marks the PR + `hive:unauthorized` (step `merge-workflow-path`), stops retrying that + head, and the approved head parks at `090-ready-for-human-merge` for a + person's **Merge** click as before. With the toggle off, or with no + approval, a workflow-path PR is never merged by the hive. +- The diff does not delete a test file or remove 25+ test lines while + deleting at least 3× what it adds (`contributor-lane:tests-removed`). +- Required CI is green on the current head, using the same merge-CI gate as + the App self-merge tier. +- A reviewer agent is configured (otherwise `contributor-lane:no-reviewer`: + the tier never merges unreviewed), and `review-verdicts.json` records an + approving aggregate verdict for the current head + (`require_reviewer_verdict`, default `true`). Missing or failing verdicts + skip with `contributor-lane:no-verdict`. +- Sentinel has no blocking finding (`contributor-lane:sentinel-blocked`), the + reporter-trust gate has not held the PR (`contributor-lane:reporter-trust-hold`), + and no reviewer has an outstanding `CHANGES_REQUESTED`. +- No excluded label (`hold`, `do-not-merge*`, `needs-human`, `blocked`, + `needs-rebase` by default), not draft, mergeable, no human-merge path. +- The head SHA has stayed green for `soak_minutes` (`0`/unset = default 30; + the shortest real soak is `1`). The soak is measured from when the head + went green — the latest `completed_at` over its check runs, read once per + (repo, PR, head) and then pinned in process — so a pod restart or upgrade + does not restart it; a new push restarts + the soak. The skip reason is the stable `contributor-lane:soaking`; the + soak head, start and window are recorded once on the stage record, so the + stage tracker computes "N left" from that deadline at request time instead + of the hive re-stamping its note every pass. The window is also editable + from the Activity Monitor's ⚙ → Toasts & timing ("Pre-merge soak"), which + writes `soak_minutes` through `PUT /api/config/auto-merge`; the lane reads + the knob on every pass, so a running soak follows the new window. + +Merges squash through the same effect-claimed `MergePR` path as the other tiers, +log `automerge merged tier=contributor-lane admitted_by=<path>`, record the +sweep audit, and leave one comment naming the admission path: `Merged by hive +contributor-lane auto-merge: CI green for ≥120m, reviewer verdict approve, +claim by @author on #N verified.` for the marker path, or `… @author holds the +trusted tier in this hive's contributor registry.` for the registry path. + +```yaml +auto_merge: + contributor_lane: + enabled: true # default on; false restores the human /lgtm wait + soak_minutes: 30 + require_reviewer_verdict: true + repos: [] # optional allow-list; empty = all watched repos + exclude_labels: + - hold + - do-not-merge + - needs-human + - blocked + - needs-rebase + require_tiers: # operator-granted tiers only (trusted, merger, advisor) + - trusted + - merger + registry_tiers_sufficient: true # a require_tiers tier on the author's registry profile admits without a claim marker + auto_promotion_scope: hive # count clean merged PRs across every hive repo (repo = this repository only) + approve_held_runs_for_registry_trusted: true # approve action_required runs once per head for registry-admitted authors + owner_approval_releases_workflow_fence: true # a trusted merger's approval on the current head lets the lane merge .github/workflows/** PRs + contributor_tier: + auto_promote_after_merged: 5 # clean merged PRs before the lane trusts an author on its own; negative disables +``` + +The block is editable from **Settings → Features → Auto Merge → +Contributor-lane auto-merge** (enable switch, soak minutes, reviewer-verdict +switch, required tiers, auto-promotion scope, excluded labels, repository +allow-list) through the +same owner-only `GET/PUT /api/config/auto-merge` overlay. + +**Operator workflow.** To let a known contributor's relay PRs merge +unattended (for example `mrbobbytables`): + +1. The contributor proves their GitHub login once: + `curl -X POST -H "Authorization: Bearer <their GitHub token>" + <hub>/api/contribute/reissue-token`. +2. Grant them `trusted` (or `merger`) in **Contributors**. +3. Issues the relay leases to them from then on carry `tier=trusted + verified=true`, and their green, reviewed, soaked PRs merge through this + tier. Every other contributor's PRs keep waiting for a human `/lgtm`. + +A claim keeps the tier the contributor held when it was taken, so grant the +tier before the issue is leased. + +**No decision during CI/Review; the operator has the last word on +untrusted merges.** A contributor PR is not parked at +`stage/085-needs-decision` on a reviewer decision marker alone. While it is +in CI/Review the hive runs CI and the review swarm to completion and the +row always names its mover; the only early exit is a concrete security / +trust finding (`review.IsSecuritySensitiveFinding`: high-risk marker, +security perspective hold, security-class question, finding on a sensitive +path — `sentinel.sensitive_paths` plus `security.sensitive_paths` — or +insecure behaviour flagged), recorded as `decision_finding` and printed as +`the review found: …`. Anything else goes back to the clanker or is +advisory and the PR keeps moving. At the merge gate a contributor the lane +cannot vouch for parks at `stage/090-ready-for-human-merge` +(`contributor-lane:claim-tier-untrusted`, `untrusted-author-role`, the +human-merge rule) and waits for the operator's merge — the hive never +auto-merges an untrusted author's PR, however green, approved and soaked. +See [review-swarm.md](/docs/hive/operations/automation-and-review/review-swarm) ("Contributor and human-authored +PRs: no decision in CI/Review"). + +### Issue-author credit at merge time + +Every merge the hive performs — the self-authored, trusted-author, +contributor-lane and queue sweeps as well as `hive-merge` relay requests — +credits the humans who opened the issues the PR closes. The merge reads the +closing references the PR already carries (`Fixes|Closes|Resolves #N` in the +body) and resolves each referenced issue's author with at most one +`GET /issues/{n}` per newly seen issue, cached for the life of the process +(attributed as `hive:merge_credit` in the API-quota ledger). Bots and Apps +(`type=Bot`, `[bot]`/`-bot` suffixes, `github-actions*`), the PR author +themself, and issues that are really PRs are skipped; the remaining logins are +de-duplicated and appended as `Co-authored-by: <login> +<id+login@users.noreply.github.com>` trailers to the squash commit message. A +`merge-method/merge` PR gets the trailer on the merge commit instead; a rebase +merge has no commit to carry it and is left alone. + +`Co-authored-by` is the trailer GitHub counts toward the contributor graph, so +a reporter whose issue was fixed by someone else's clanker shows up on the +repository's contributors page rather than only in the issue timeline. It is +purely additive: the branch's own commit subjects, bodies and `Signed-off-by` +lines are reproduced unchanged ahead of the new trailers, so the squash +sign-off gate and `check-squash-signoff-attribution.sh` see exactly what they +saw before plus the credit. This is the single mechanism: a hive-opened PR +already carries the trailer on its commits (`issue-coauthor.sh`, +`hive-open-pr`), and the merge recognises an existing trailer for the same +login (by noreply address or login) and does not add a duplicate. The credited +logins are recorded on the merge audit entry (`issue_authors=`) and in the PR's +review-evidence `merge.issue_authors`, so dashboards and DIBS statistics can +report them. If the branch's commits cannot be read at merge time, the hive +falls back to GitHub's default message rather than risk dropping a sign-off. +Switch it off with `auto_merge.credit_issue_authors: false` (#14581). + +### Issues close only after the merge + +The hive never closes an issue for a pull request that has not merged. The +only PR-driven close path is close-on-merge (`CloseOnMergeLedgerSweep`, +`close_on_merge.go`), which reads the PR back from the forge and returns +`pr_not_merged` without touching the issue unless `merged_at` is set (or +`merged` is true); opening a PR, admitting it to the merge train or the +pre-merge soak, and a `Fixes #N` in its body change nothing on the issue. On +GitHub's default branch GitHub itself closes the issue in the same instant +the PR merges, attributed to whoever pressed merge; on a release line the +hive's sweep does it on the next pass, with a "Fixed by #N (merged …)" +comment. Every such close goes through the central `CloseIssue` (which +refuses tracking issues and honours the reporter-confirmation gate) and is +counted by the direct-write ratchet, so no other code path can grow a close +of its own. + +The tracker shows the consequence honestly. A follow-up or duplicate PR whose +body names an issue an *earlier* PR already delivered — `Refs #15422` on +#15425 after #15426 merged, `extending #15058` on #15431 after #15068 merged — +sits under the struck-through issue with the chip **closed by #N**, linking +to the merged PR GitHub records as the closer +(`closedByPullRequestsReferences`, with the hive's merged ledger as the +fallback). Only a merged PR is ever named: an open PR with `Fixes #N` is +listed under the same relation and has closed nothing. When no merged closer +can be found the chip reads **closed · this PR unmerged**, never a bare +`closed` that could be read as the issue having been closed before its fix +merged. + +### Stage labels + +Every sweep cycle also writes the hive-owned `stage/NNN-*` label for each PR +it evaluated, derived from the same per-lane reason it logs +(`contributor-lane:no-verdict` → `stage/050-review-pending`, unless the +swarm's known verdict is `requires_human`, which the lane also reports as +no-verdict → `stage/085-needs-decision` with reason +`reviewer-verdict:requires_human`, +`contributor-lane:soaking(...)` → `stage/095-pre-merge-soak` (admitted, soak window +running; promoted to `stage/100-merge-queue` once the soak is complete), approve verdict + +green CI but no lane decision yet → `stage/080-awaiting-merge-admission` +(a stall there is logged on the PR with the lane's last skip reason), red CI on a +human-authored PR → `stage/071-needs-author`, on a clanker PR → +`stage/072-returned-to-contributor`, a trusted human's changes-requested +review or `/hive decision <text>` on a hive-authored PR's current head → +`stage/070-fixing` with reason `human-changes-requested` and one fix kick +carrying the text ([#13041](https://github.com/hivecommons/hive/issues/13041)), +hold / sentinel alert → a **gate on the PR's real stage**, not a stage of its own (the column follows CI / review / merge-queue progress, the Merge queue cell reads *Held · sentinel · confirm intent* / *Held · hold*, and the lanes refuse the merge on the label itself — a parked PR never merges unattended, [#17327](https://github.com/hivecommons/hive/issues/17327)), hive-authored PR whose fix +dispatch is refused with `fix-attempts-exhausted` → `stage/085-needs-decision` +with reason `fixer-exhausted:<N>` and a once-per-head decision comment (re-author / +hand to a person / close as not planned; a stale `decision-answered` cannot pull it +back to 070 while the head is unchanged, [#15744](https://github.com/hivecommons/hive/issues/15744)), untrusted author with an approve verdict at the +current head, green checks, DCO and soak done → +`stage/090-ready-for-human-merge` (only a maintainer's `/lgtm` `/approve` is +missing; the dashboard derives a compact **human-merge reason code** from the +090 record's lane reason — `prstage.HumanMergeReason` — so the gate cell says +why a person merges: `workflow-files` (`contributor-lane:workflow-path`), +`tests-removed`, `manual-merge-policy` (`human-merge-path`), `branch-protection`, +`merge-method`, `auto-merge-off` (`repo-auto-merge-disabled`), `untrusted-author` +(every trust reason: `untrusted-author-role`, `claim-tier-untrusted`, `no-claim`, +`no-linked-issue`, `claim-unverified`, `claim-author-mismatch`, `claim-other-hive`, +`author-association`), `unauthorized` (the App's 403, #14595), `reviewer-deferred` +(`reviewer-verdict:requires_human` a trusted merger approved), and `policy` for +any other lane reason, quoted in the tooltip; #14658), merged → no stage), plus one `role/*` label saying +which admission tier the lane actually used, one `author/*` label saying who +wrote the PR (`human`, `clanker` = a contributor's own agent, `hive` = this repo's +own; #12581) and `stage/stalled` when nobody +but the hive has touched the PR for the stage's dwell (never while checks run +or the reviewer verdict is pending). Backward moves are a one-line stage +comment and dashboard history, not a label. Writes happen only when +the planned set differs from the labels already on the PR, under the +`hive:stage_labels` REST caller, and the whole family is switched by +`governor.labels.stage.enabled`. The mapping table, numbering rules, dwell +thresholds, the mermaid state machine and the off-happy-path flow +(072 → nudge → 074 → takeover) are in +[labels-and-control-signals.md](/docs/hive/labels-and-control-signals/stage-labels#stage-labels-stagennn--the-pipeline-state-machine); +the code is `src/pkg/stagelabels` and +`src/pkg/github/automerge/automerge_stage_labels.go`. Adoption +(`stage/074-adopted-by-hive`, `automerge_contributor_adopt.go`) reuses this +sweep's own red-PR route: the superseding App PR it opens from `hive/adopt-<n>` +is red with the contributor's failures, lands in `ci-failing.json` like any +hive-authored red PR, and the scanner's FIX-BEFORE-NEW kick rebases and fixes +it on that branch (never a replacement PR), after which it follows the normal +`050 → 100` path. When adoption is in-place on the contributor PR's own +branch, the hive owns the head it pushed: once that head is green, approved +by the reviewer, DCO-clean and soaked, the contributor lane admits it under +the hive's own authority (`contributor-lane:adopted-by-hive`, see the +admission paths above) rather than waiting for the original author's trust +tier or a maintainer `/lgtm`; a changed head stays adopted only with hive-controlled evidence +(GitHub-linked App commit metadata; the stage store only remembers SHAs that +already passed that check); +forgeable git author/committer names and emails are treated as contributor +pushes and release adoption once repo evidence exists +(`governor.labels.stage.adoption.strict_attribution`, default on). Push-capable +App-authored agents commit with the App bot noreply email (keyed by the bot's +GitHub user id, not the App id) so their fixer pushes +normally provide the GitHub linkage, while their commit name/sign-off still +shows the lane. An in-place adoption does not sit at 074 forever: the sweep +re-evaluates every adopted record each pass, and when the hive cannot finish +on the contributor branch because a blocking review-swarm finding was left +on a head that sat idle for the 074 dwell, it converts to a supersession +(`reason=in-place-stalled`) and the superseding PR takes the same red-PR / +review-fix route. A hive commit the squash sign-off gate strips +(`hive-signoff-attribution`) now re-homes immediately if the lane cannot +elect a merge commit: an App-authored superseder changes the squash +attribution while preserving the contributor's commits and sign-offs. +All DCO and merge gates still run on that PR. Loss of push access also +re-homes immediately (`reason=push-rehome`). A pushable `needs-rebase` or +conflicting branch first gets the normal fixer window; if its head remains +unchanged past the 074 dwell, the same sweep supersedes it +(`reason=rebase-rehome`) rather than parking at 085. Previously escalated +adoptions are re-evaluated for these recoveries too (#13975). A red adopted +head whose failing check is green on the base branch tip — the shared-CI +flake or red base it fell to was fixed since, but the head never ran CI +again — is recovered before anyone is asked: the sweep merges the base into +the head when it is behind (GitHub update-branch, which works on a fork the +maintainers may edit) or re-runs the failed workflow jobs when it is current, +at most once per (head, base tip) and three times per adoption, logged as +`adopted PR recovery` with `reason=update-branch`, `rerun-failed-jobs` or +`skipped:<why>` (`skipped:dependency-bot-branch` for a behind `renovate/*` or +dependency-bot branch, which is never updated); an escalation already in place for that head is released +(hivecommons/hive#14500). An adoption with nothing the hive can +push past the dwell — after that recovery was tried and the head is still +red — goes to `stage/085-needs-decision` as +`adoption-stalled:<lane reason>` with one comment naming the blocker, so the +dashboard shows a person's item, not a silent 074; "waiting on maintainer +lgtm" is only ever the state at 080+ (hivecommons/hive#12858). The dwell runs +from the head's last hive push, a red optional check alone is not a blocker, +and the escalation releases back to 074 when its reason clears +(hivecommons/hive#13040). The issues a PR covers +follow it: once the sweep stages a PR at 050 or later, the enumeration cycle +writes the same stage on each linked issue (`stage/040-covered-by-pr` until +then), so the issue list and the PR list read the same +([#12436](https://github.com/hivecommons/hive/issues/12436)). + +An adoption pair is one logical PR everywhere a person might otherwise be +asked to pick between PRs (hivecommons/hive#15495). A clanker- or +hive-authored original closes in the adopting pass by policy +(`governor.labels.stage.adoption.close_superseded: on_adopt`, the default; +`on_merge` keeps it open until the copy merges): the write-back gate admits +the close as `superseded-agent-pr` without the repo opt-in label the +`contributor_adopt` kind otherwise wants, because the copy carries the same +commits and sign-off (hivecommons/hive#15526 sat open beside hive's #15574 +as "Adopted → #15574 · superseded" with the gate saying +`needs-opt-in-label`). A human-authored original still needs that opt-in +label to close in the adopting pass; without it the gate keeps it open after +supersession (`needs-opt-in-label`, or a fork the hive cannot edit) and it +sits at 072 "superseded by #N" until the copy merges. Either way the +superseded original draws in the Activity Monitor as one muted, +chevron-less line under the issue (greyed title, no stage strip) whose +trailing note reads "superseded · hive adopted → #M" — or "superseded · +closed · hive adopted → #M" once it is closed — on a single line (the title +ellipsizes first); the hover carries the long form ("Hive re-authored this +PR as #M with the same commits and sign-off. This PR closes as superseded +when #M merges." / "…is closed as superseded."). The tracker marks it +`superseded_by: M`; the line stays only while #M is open and listed and +drops once #M merges or closes. The issue's caption, open-PR count, parked-PR check and "Let hive decide — all N +PRs" fan-out all see only the hive's copy: the original's review verdict never +gates the issue, and the copy's body carries every `Fixes #N` / `Refs #N` line +of the original (an annotated `Refs #N — partial` travels as the bare +reference, so the copy keeps the issue link). The original counts again only +when the copy is closed without merging (`adopted_by_state` closed / +closed-twice / copy-failed). + +A clanker PR entering `stage/072-returned-to-contributor` also triggers the +contributor nudge: the sweep keeps one `<!-- hive:contributor-nudge +reason=<slug> head=… -->` comment per PR and reason class naming the failing +checks / review asks — a changed reason or new head edits that comment in +place; one re-nudge after `auto_merge.nudge_repeat_after` (default 72h) if +the condition persists, then no more — and hands the diagnosis to the +contribute hub, which — when the author's relay heartbeat is fresh — pushes a `fix-pr` +interrupt task into their relay session (parallel sub-session or preempt, +per the relay's declared capability) under a per-contributor fix budget; +queued fixes are served before new work ("contributors should clean up their +mess before taking on new stuff"). Code: +`src/pkg/github/automerge/automerge_contributor_nudge.go`, `src/pkg/fixqueue` +and `src/pkg/dashboard/contribute_fixqueue.go`. + +One exception: a PR the merge train holds because **another open PR already +fixes the same issue** (lane reason `merge-train:duplicate-of#<winner>:…`) +is parked with its author — 072 for a relay contributor, 071 for a person, +070 for the App's own — as *superseded*, not at the merge gate as "Approved; +waiting its turn", and the 07x pass neither nudges nor adopts it: there is +nothing to fix, and adopting it would land the issue twice. Its one notice +is the duplicate-fix sweep's gated `<!-- hive:duplicate-fix -->` comment; +the tracker pill reads *Duplicate of #winner · needs a pick*, and *Let hive +decide* on either row closes it as superseded +([#15469](https://github.com/hivecommons/hive/issues/15469)). Upstream of +the train, an open PR's webhook that covers an issue also releases any +contributor task already dispatched on it (see +[operator-reference.md § Open-PR dispatch guard](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#open-pr-dispatch-guard-and-duplicate-fix-sweep-scanner)), +so the hive does not open the second PR in the first place. + +The duplicate pick above sees one lane at a time. When the two PRs sit in +**different lanes** — the hive's own PR in the self lane and a trusted +human's PR in the trusted lane both closing one issue, as #15783 and +#15793 did for #15773 — neither lane's winner rule saw the other and both +marched toward merge. Every lane therefore also runs a **same-issue claim +gate** before its trains are grouped: a candidate whose closing issue any +other open PR of the repository also claims (`Fixes`/`Closes`/`Resolves`; +a `Refs` line is not a claim; an adoption copy and the original it +`Supersedes` are one change, not a pair) is held with lane reason +`merge-train:claim-conflict#<other>:<issue>/0:0/0:` and the log line +`same-issue claim conflict undecided: #A vs #B` — in every lane, so +**neither PR is admitted** while the conflict stands. The hive does not +pick: the stage engine parks the held PR at 085, the tracker chevron reads +*held · duplicate of #B · needs decision*, the row's options name the +concrete PRs (*Keep #A — admit it to the merge queue*, *Close #A as +superseded by #B*), and *Let hive decide* only recommends ("Hold both: #A +and #B claim issue #N. Keep #B, close #A — or keep #A, close #B"). A +recorded trusted decision on a PR's head (the tracker's Approve, or any +`/hive decision` on it — the downstream gates still judge the merge) is +what lifts the gate for that PR; closing the other ends it +([#15810](https://github.com/hivecommons/hive/issues/15810)). + +Both rules judge **heads at the merge gate only**: a head the lane last saw +green with every required verdict recorded, the readiness a train seat needs +([#17439](https://github.com/hivecommons/hive/issues/17439)). A same-issue +PR whose CI is still running, or whose review is outstanding, is not held: +the lane evaluates it on its normal path, so its row reads CI running / +review pending, never *needs a pick* or *needs decision*. Should that head +reach the merge point it is held there instead of merging — on an undecided +claim conflict, or behind the PR that already holds its issue — and from the +next pass it is held at the gate like any other. Within one lane the first +PR at the merge point takes the issue; when several are already at the gate +the pick is the usual green-first, then earlier-opened. The pick then +**stands** until the kept PR closes or is blocked for good (a person merges +it, not mergeable, a terminal required-check hold, a permanent merge +refusal): a check that goes red mid-run no longer hands the issue to the +other PR, so two PRs never point at each other. The kept PR is remembered in +memory per lane and issue; a restart re-plans. + +### Hive-authored superseding PRs auto-merge + +Owner rule (@clubanderson): *"if a pr is superseded by a pr that a hive +agent creates, it should auto merge"* — *"the only exception would be if +this is sentinel or some other emergent problem with the pr."* + +A **hive superseding PR** is a PR the hive App itself authored +(`@hivecommons-hive[bot]`) whose body declares `Supersedes #N` — the PR a +takeover, close-first adoption or re-author lead opens to carry a +contributor's or bot's change. `github.IsHiveSupersedingPR` / +`github.HiveSupersedingPR` detect it; `PullRequest.Supersedes` carries the +number. Twice in one morning such PRs (#15649, #15646) parked at +`stage/085-needs-decision` on a reviewer's security-sensitive +`requires_human` and the owner had to click approve for work the hive had +already decided to carry. Under this rule they do not: + +- **Reviewer findings go to the fixer.** On a hive superseding PR the + aggregate (`review.hiveSupersedingFixRoute`) turns a `requires_human` — + a risk-class decision question, a security-sensitive finding, an + unresolved escalation — into `changes_requested` with the reason + `hive-authored superseding PR: reviewer requires_human routed to the fixer; auto-merges once CI and review are clean`; the fixer + addresses it and the swarm re-reviews, exactly like any other finding. + A `reject` is not converted: it is an emergent problem with the PR. The + stage engine captions the head *"hive-authored superseding PR — + auto-merging once CI/review are clean"* (lane reason + `hive-superseder:fixer`) rather than "needs your decision", and the + reviewer prompts say so (`hiveSupersedingGuidance`). +- **Green and clean merges with no decision.** Once CI is green and the + review has no open findings the PR follows the hive-authored admission + path (`stage/080` → merge). The superseded PR is closed as superseded by + the existing writeback (`Superseded by #N`) once it merges, as before. +- **The only exceptions are the hard stops**, computed in one place + (`automerge.hiveSupersederHardStop`) and named in the 085 caption + (`hive-superseder-hard-stop:<token>`): + - `sentinel-unacknowledged` — the sentinel label is on and nobody has + acknowledged its finding (`sentinel_acknowledged` in the review + evidence bundle; an acknowledged sentinel, as on #15650, is not a + stop); + - `hold` — a `hold` / decision-class label or a repo/global hold; + - `fix-attempts-exhausted` — the fixer spent its cycle cap on the + reviewer's findings; reported as `ci-red-after-fixes` when CI is + still red, `base-conflict-unresolved` when the head still conflicts; + - `base-conflict-unresolved` — the hive's rebase-resolve episode + already failed twice. + + A pending check, a first conflict or an ordinary reviewer finding is + never a stop. The tracker row reads *"The hive's superseding PR would + auto-merge (owner rule), but <stop>"*, and *Let hive decide* answers + recommend-only, naming the stop (`delegatedecision.RuleHiveSuperseder`); + without a stop it releases the PR under the same rule. + +`auto_merge.hive_superseding.auto_merge: false` turns the rule off and +restores the previous behaviour (a `requires_human` parks the superseding +PR at 085 like any hive-authored PR). + +### Empty-diff PRs of the hive's own + +A PR of the hive's own (the App's, or an adoption it opened) whose diff +against its base is **empty** — GitHub reports zero changed files, and the +`base...head` compare agrees — carries nothing the base does not already +have. This is what an adoption looks like once the original's fix landed +through another PR. The hive closes it itself, through the writeback gate, +with the sweep's edited-in-place comment naming the PR that carries the +change (`<!-- hive-redundant-of: #N -->`, the marker the reviewer's verdict +set) and the `hive/superseded` label, and raises **no** human decision. The +same guards as the superseded rule hold: `governor.auto_close_superseded` on, +ACMM L6, not held / keep-open / draft / parked by a person, and a head at +least 15 minutes old so a branch mid-push is not read as empty. A *person's* +empty PR is never closed by the hive; it gets the decision prompt as before. +Code: `src/pkg/github/pr_empty_diff_hive_autoclose.go`, hooked from the +self-authored sweep and from the 085 route +([#15499](https://github.com/hivecommons/hive/pull/15499)). + +Three things made #15499 sit a day at 085 instead: + +- The adoption's dispatch records carried no `author_agent`, so the relay + judged the App's own PR non-hive and its decision question went down the + **contributor** lane (`contributor-lane:decision-requested`) to a person. + Dispatch records now carry `hive_authored`, and the relay falls back to + the PR author's login against the hive identity; an adoption routes + through the self lane. +- Every merge-from-base pushed by the hive's own `update-branch` was a new + head with no verdict, so the swarm re-reviewed and re-asked the same + question (six heads, ~16 "Decision needed" reviews and 085 comments). A + PR with no diff against its base now re-stamps its prior verdict on each + head (`review.delta_rereview`); a decision question is identified by its + `hive-redundant-of` PR (else its normalised words), and a second ask with + the same identity refreshes the standing review in place and posts no + second 085 entry comment. +- The tracker's *Decision needed* popover read the verdict at the current + head only, so during a re-review it fell back to "a reviewer handed this + PR to a person without a specific question". A row parked on a reviewer + decision now quotes the newest decision-requested verdict on any head, + shows a *redundant of #N* chip, and leads with **Close as superseded**. + +**Already landed, by the reviewer's word.** #15647 and #15648 (adoptions of +#15324 / #15343) still parked at 085 with the question "should decide +whether to close this adoption … as already landed, since v5 already +contains the identical change via #15506": the empty-diff closer ran, but +its 15-minute freshness guard read the PR's `updated_at`, which the hive's +own labels and comments bump every pass, so the head was "too fresh" +forever. "Already landed / redundant / no-op" is the hive's own decision +about its own PR, not a person's. The 085 route now takes the +**already-landed** entry when the verdict for the head says so — the +`hive-redundant-of` marker, or wording that names the landing PR +explicitly ("already landed … via #N", "identical change merged in #N"; +a question that merely mentions a PR is not a claim, and two candidate +numbers are ambiguous and name none). On that entry there is no +freshness guard (a reviewer confirmed this head), a head whose files +are each byte-identical on the base tip counts as empty when GitHub +still reports a diff, and the landing PR is taken from the marker or +the words; with no number the compare alone must prove redundancy. The +close is logged once with reason `self-authored:already-landed` +(tracker caption "already landed via #N — closing as superseded"), +and settles the adoption's lineage: each original the copy declared +`Supersedes #M` whose record names this copy is told, marked superseded +on the stage store (so the orphan recovery does not re-adopt a head the +base already has) and closed, and issues the copy would have closed are +closed with the redundant-of note. Only when the verdict names no PR +*and* the compare is not empty does the PR fall through to 085 as before +([#15647](https://github.com/hivecommons/hive/pull/15647)). + +**Already landed, any author.** That entry was the hive's own: #15544, a +trusted contributor's PR for #15543, was +0/−0 against `v5` because +#15545 (merged) carried the identical change, and the reviewer's "should +decide whether #15544 can be closed as a no-op now that #15545 (merged) +carries this change" still parked it at 085 for nine hours. Whether a +change is already on the base is a measurement, not a trust call, so the +already-landed entry now takes any author's PR when the evidence is +unambiguous: the diff against the current base is empty (no files, or +every file byte-identical on the base tip) **and** the landing is proven +— the PR the reviewer named is merged, the issue this PR closes was +closed by a merged PR, or the compare lists no commits (the head is +contained in the base). "#N (merged)" in the reviewer's words names the +landing PR like "via #N" does. The hive comments "already landed via #N +— closing as superseded; thank you @author", closes the PR through the +supersession-close write-back gate, and logs +`already-landed:<author_kind>` (the caption is the same "already landed +via #N — closing as superseded"). A trusted author is treated exactly +like anyone else. A PR with a real diff, an empty PR whose landing is not +proven, a held or `keep-open` PR, or one a person parked keeps the +reviewer's question as before. The "Let hive decide" preview for such a +PR gives the evidence as its reason — "diff is empty — the change already +landed via #N (merged)" — never the author's standing +([#15732](https://github.com/hivecommons/hive/issues/15732)). + +## Usage + +```sh +hive-merge --repo <owner/repo> --number <N> [--method squash|merge|rebase] \ + [--expect-sha <sha>] [--update-branch] +``` + +| Flag | Required | Default | +| --- | :---: | --- | +| `--repo` | yes | — | +| `--number` (alias `--pr`) | yes | — | +| `--method` | no | `squash` | +| `--expect-sha` | no | auto-resolved (see below) | +| `--update-branch` | no | off | + +Both `--flag value` and `--flag=value` forms work. `--squash`, `--merge`, and +`--rebase` are accepted as method shorthands. `--admin` is accepted and +**ignored** — the hive never admin-bypasses branch protection. + +`--repo` and `--number` must resolve, or the script exits `2`. `--number` must +be an integer, or the script exits `2`. + +### `--expect-sha` is auto-resolved, not optional in effect + +The merge-request watcher **requires** a non-empty `expect_sha` (the F4 TOCTOU +guard above) — a request with none is denied outright. Rather than push that +burden onto every call site, the script resolves the PR's *current* head SHA +itself when `--expect-sha` is not given, using the cached App token at +`/var/run/hive-metrics/gh-app-token.cache`, and pins it into the request. The +head is captured at request time, closing the TOCTOU window exactly as +intended, so existing call sites that never passed `--expect-sha` keep +working unchanged. + +If the SHA cannot be resolved (no token cache, `gh` unavailable, or the +lookup fails), the script prints an error naming the token-cache path and +**exits `3`** rather than writing a request with no pinned head. + +### `--update-branch` + +When set, the watcher syncs the PR branch with its base before attempting the +merge (resolves the common "behind main" case). A failure to update the +branch is not fatal — the merge attempt still proceeds and surfaces the real +blocker. A dependency bot's branch (`renovate/*` head ref, or a Renovate, +Dependabot or Mergeraptor author) is never updated: the watcher logs the skip +and goes straight to the merge attempt, leaving the rebase to the bot. + +## It is asynchronous, by design + +On success the script prints the request path and returns `0`. **The PR has +not been merged yet at that point.** It merges on the next watcher tick +(polling every 10 seconds). + +To confirm, poll the `.result.json` written next to the request file, or +simply check whether the PR is merged. + +## Retries and what happens when a merge can't land + +The watcher retries a failed merge attempt up to **3 attempts total**, +tracked across ticks via the prior `.result.json`. What happens after the +final attempt depends on why it failed: + +- **A required check is failing or pending** (classified from GitHub's own + branch-protection error text, e.g. "required status check ... has not + succeeded") — the request is quarantined (renamed `.exhausted`), but the + hive re-engages its fix loop for that PR instead of abandoning it, subject + to a per-red-SHA re-dispatch cap. +- **The blocker is unfixable by pushing code** — a true merge conflict or a + permission error (matched against GitHub's own wording, e.g. "merge + conflict", "not accessible by integration", "403", "must be a member") — + the request is quarantined (`.exhausted`) and not retried further; the + result file records the last error. + +An authorization denial (forge-resistance failure, `CanMerge` gate failure, +or F4 target-binding failure) is not retried at all — the request file is +renamed `.denied` immediately and the result file records the reason. + +A malformed request file (invalid JSON) is renamed `.bad`. + +## Where things live + +| Path | What | +| --- | --- | +| `/var/run/hive-metrics/merge-requests` | request files the watcher consumes | +| `/var/run/hive-metrics/gh-app-token.cache` | cached App token, used to auto-resolve `--expect-sha` | +| `/var/run/hive/uid-map.json` | UID → agent-name map, used for a nicer log line | +| `/data/stage-labels.json` | persisted stage timing, last-activity clock and transition history for `stage/stalled` and the review-queue stage history | + +The UID map is **informational only** here. The watcher re-derives ownership +from the file's UID regardless. + +## Related + +- [`hive-open-pr`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-pr.md) — the equivalent relay for opening a PR; + same request-file mechanism and authorship model +- [Security threat model](/docs/hive/security-threat-model) — forge resistance and the + UID-ownership anchor +- [Agent configuration](/docs/hive/agent-configuration) — ACMM levels and the + merge gate (`CanMerge`, `ModeIssuesPRsMerge`) that governs whether an agent + may merge a PR at all +- [Audit log](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) — merges are recorded there with the requesting + agent diff --git a/docs/content/hive/hub-fleet-activity.md b/docs/content/hive/hub-fleet-activity.md new file mode 100644 index 0000000..f6c70bf --- /dev/null +++ b/docs/content/hive/hub-fleet-activity.md @@ -0,0 +1,195 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-fleet-activity.md) during the docs build. Edit the canonical source in the Hive repository. + +# Hub Fleet activity page + +The **Fleet activity** page at `https://<hub>/activity` is a read-only board of +the open issues and pull requests that the hives you can see are working on. +It is the hub-side view of the Activity Monitor: each spoke attaches a bounded +activity digest to its heartbeat, and the hub merges the digests of your hives +into one board. + +Open it from the **📡 Fleet activity** link next to **🔬 Evidence** on the +dashboard's Fleet quadrant card, or go to `/activity` directly. You must be +signed in; a browser without a hub session is sent to `/login`. + +The design is RFC [#15861](https://github.com/hivecommons/hive/issues/15861) +by @hanthor, delivered in [#15965](https://github.com/hivecommons/hive/issues/15965) +and its children. The page itself is [#16063](https://github.com/hivecommons/hive/issues/16063); +its display mode is [#16064](https://github.com/hivecommons/hive/issues/16064). + +## Who sees what + +The page shows exactly what `GET /api/hub/activity` returns for you. That +endpoint decides access per hive on the server before it reads any data: + +- A hub admin sees every registered hive. +- Everyone else sees the hives they own and the hives they hold an unexpired + grant for. +- Another hive's rows, counts and freshness never reach your browser, so they + are not in the page and not in its ETag. + +The page itself carries no fleet data. It is a static shell that loads the +board from the endpoint. + +## Reading the board + +Each row is one open issue or PR: + +| Column | Shows | +| --- | --- | +| **Hive** | A colour chip per hive. The colour is stable per hive id. The chip opens that hive's own dashboard and tracker through the hub's hive route (`/api/saas/hives/<id>/open`), which signs you in or explains why it cannot. | +| **Item** | `owner/repo#N` and whether it is an issue or a PR. It links to the item on GitHub. | +| **Title** | The item title as plain text, capped at 200 characters by the hub. A leading `[agent]` tag is drawn as a chip. | +| **Stage** | The strip column the spoke tracker would light (Open, Actionable, Claimed, PR in progress, CI / Review, Merge gate, Merged) and the stage slug. | +| **Author** | `human`, `clanker` or `hive` when the spoke knows it. | + +Rows are ordered like the spoke tracker's default sort: furthest strip column +first; within a column, rows with a modifier or parked on a person first and +held or draft rows last; then longest in stage. `am.sort` and `am.dir` change +the order (see [Display mode and URL views](#display-mode-and-url-views)). + +**Group by hive** is on by default. It draws one header row per hive, even when +the hive has no open items. The header shows: + +- the item count, plus the hive's tracked total when the digest held some back; +- freshness: + - `fresh`: the hive's activity report is recent; + - `stale`: the last activity report is older than two missed heartbeats + (more than 4 minutes); + - `not reporting`: the hive heartbeats but sends no activity block. + Upgrade it to report activity; + - `missing`: you hold a grant for a hive the hub registry does not know. + +Turn grouping off for one flat list. The Hive column still tells rows apart. + +## What the board leaves out + +The list above the table is always visible. It never hides in a tooltip. It +names every gap in the data: + +- items left out by the hub's response cap; +- items a hive's own digest cap left out (`truncated`); +- events dropped before they reached the hub (`events_dropped`); +- stale, not-reporting and missing hives. + +When nothing is missing it says so: "All N hives reporting; nothing left out". + +## Refresh + +The page polls `GET /api/hub/activity` every 15 seconds with `If-None-Match`. +The hub answers `304 Not Modified` while nothing in your view changed, and the +board is redrawn only when the ETag changes. Polling pauses while the tab is +hidden and resumes, with an immediate refresh, when you come back. The status +line shows when the data last changed and when it was last checked. If your +session expires, the page sends you to `/login`. + +## Display mode and URL views + +The page takes the same display parameters as the spoke Activity Monitor +(see [Display mode and URL views](https://github.com/hivecommons/hive/blob/v5/src/docs/streaming-the-activity-monitor.md#display-mode-and-url-views)). +They are the spoke's own parameters, read by the spoke's own code: the hub +serves a byte-identical copy of the spoke's URL-view and playlist helpers +(`src/pkg/webassets/trackerview`). There are no hub-only display parameters. + +| Parameter | On `/activity` | +|---|---| +| `kiosk=1` | Unattended screen: hides the hub header, the description and the **Group by hive** toggle, and hides the cursor. The status line and the coverage list stay. A kiosk never rotates a playlist. | +| `display=1` | Attended wall screen: the same chrome-less board, with the cursor. **Esc** (unless the browser is in full screen) or **d** leaves display mode and keeps the rest of the URL. `kiosk=1` wins when both are set. | +| `am.*` | The board's view, with the spoke's keys and values. See the table below. | +| `am.view`, `interval` | A playlist, in display mode only. Each `am.view` is a URL-encoded `am.*` query string, and every entry is a `hub-activity` view: this board under that entry's `am.*` state. `interval` is `Ns` or `Nm`, clamped to 10 s – 1 h, default 60 s. With fewer than two valid entries the board does not rotate. | + +How each `am.*` key applies here: + +| Key | Effect on the hub board | +|---|---| +| `am.kind` | `pr` or `issue` only. | +| `am.repo` | One `owner/repo`, exact match. | +| `am.q` | Title text, or the item number (`123` or `#123`). | +| `am.author` | `human`, `clanker` or `hive`. | +| `am.sort`, `am.dir` | `furthest` (default), `waiting` (longest in stage) or `number`; `asc` / `desc`. `newest` needs an opening time the digest does not carry, so it sorts as `furthest`. | +| `am.group` | `none` turns grouping off. Grouping by hive is the default and is never written into the URL. A spoke value the hub board has no grouping for (`repo`) falls back to the default, as an unknown value does on the spoke. | +| `am.labels`, `am.needsHuman`, `am.onHold`, `am.attention`, `am.age`, `am.acted` | Not applied: the activity digest carries no labels or verdicts for them. They stay in the URL, so the link still works on a spoke, and the coverage list names them under *Not applied on the hub*. | + +A link copied from a spoke display therefore opens on the hub with the same +view where the hub has the data for it, and says which parts it could not +apply. Turning **Group by hive** on or off rewrites `am.group` in the address +bar, so the address is always a link to the current view; credentials in the +URL never survive that rewrite. + +The playlist follows the spoke's rules: + +- The current view follows the wall clock, so a reload resumes on the same + view. Rotation happens in memory: it does not navigate, refetch or change + the URL. +- A thin bar at the top shows the time until the next view. With reduced + motion it is a static *N/M · next in Ns* label instead. + +```text +/activity?display=1&am.view=am.kind%3Dpr&am.view=am.group%3Dnone%26am.repo%3Dhivecommons%2Fhive&interval=2m +``` + +The spoke-only wall options `density=tv` and `shift=1` are ignored here. + +## Public-safe view + +`https://<hub>/activity/public` is the same board served to anyone, without a +session ([#15966](https://github.com/hivecommons/hive/issues/15966)). It is the +source of the `twitch.tv/hivecommonsfleet` broadcast +([Streaming the Activity Monitor](https://github.com/hivecommons/hive/blob/v5/src/docs/streaming-the-activity-monitor.md#the-hivecommonsfleet-broadcast)). +On that path the page polls `GET /api/hub/activity/public` with +`credentials: 'omit'`, and the endpoint never reads a cookie, token or +`Authorization` header, so a signed-in browser or an admin gets the same rows +as an anonymous visitor. + +The view is filtered on the hub before it is built: + +- Only hives the registry lists as **public** (the flag the public registry + and leaderboard use) on public github.com. A hive with no public flag, or + on a GitHub Enterprise host, is left out. +- Only items and events the spoke marked public. A spoke marks a repository + private unless it knows it is public, so unknown visibility is left out. +- No `totals`, digest `truncated` or `events_dropped`, since those can count + private items, and no hive owner. +- No per-user grants: your own access never widens it. + +The body is served from a hub-side cache: it is built at most once every +2 seconds per parsed filter and shared by every anonymous caller, so rows, +`generated_at` and the `ETag` can lag the latest heartbeat by up to 2 seconds, +and a client polling faster than that gets `304` until the next build. Query +strings that parse to the default view share one entry. Toggling a hive's +visibility drops the cache immediately. + +## What the page does not do + +- It has no action menus. The hub is visibility-only: act on an item on + GitHub, or from the hive's own tracker. +- `/activity` is not a broadcast source. Display mode only changes how the + signed-in page looks; the page still needs a hub session and shows only + your hives. Broadcast only the [public-safe view](#public-safe-view). + +## Security + +- The page is served with its own Content-Security-Policy. Scripts and styles + load only as files from the hub (`'self'`). Inline scripts, inline event + handlers and inline style attributes are refused, and the page loads nothing + from other origins. +- Titles and every other value from a spoke are written as text, never parsed + as HTML. +- The page, its script and the shared row-presentation and view assets are revalidated + on every load (`Cache-Control: no-cache` with a content ETag), so a hub + upgrade is picked up on the next visit. +- `/activity` (including `/activity/public`) is marked `noindex` and is + disallowed in `robots.txt`. + +## For operators + +- A spoke publishes its digest only when `hub.activity.enabled` is on. It is + on by default for hosted spokes and opt-in for self-hosted ones. A hive that + heartbeats without it shows as `not reporting`. +- Digests live in hub memory only. After a hub restart, hives show + `not reporting` until a later heartbeat carries a full digest again. +- Rows are drawn with the tracker's own row-presentation asset + (`src/pkg/webassets/trackerrow`), which the hub serves under + `/activity/assets/`. The page defines the stage constants that asset reads, + with the spoke's values, so a hub row lights the same column as the spoke + tracker. diff --git a/docs/content/hive/ioscan.md b/docs/content/hive/ioscan.md new file mode 100644 index 0000000..46355b6 --- /dev/null +++ b/docs/content/hive/ioscan.md @@ -0,0 +1,254 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan.md) during the docs build. Edit the canonical source in the Hive repository. + +# ioscan: scanning untrusted text before agents read it + +Last reviewed: 2026-10-23 + +Issue titles, bodies, labels, author names and comments are written by +anyone on GitHub. `ioscan` scans that text before Hive builds it into an +agent's task, and checks what agents send out for planted secrets. It is on +by default. + +## What it does + +* **Cleans and matches.** Removes invisible Unicode characters and + look-alike letters, then matches the text against rules for known + prompt-injection phrasing, dangerous instructions and secret-shaped + strings. These rules always run when `ioscan` is enabled. +* **Peels encodings.** Base64 is decoded up to three layers deep. Hex + escapes, HTML entities, percent encoding, rot13 and hyphen or underscore + slugs (`ignore-all-previous-instructions`) are each turned back into + plain text and rescanned. A hit in a decoded layer is reported as + `injection.obfuscated` at high. +* **Tells use from mention.** A short quoted phrase on one line that the + text frames as something being talked about ("issues containing '...'", + "the string '...'") is recorded at low and not withheld. A critical rule + such as `rm -rf` is never softened this way. A quoted phrase with no such + framing, or a fenced block, is still a payload. +* **Withholds matched text.** Text that trips a rule is replaced with + `[ioscan: content withheld — ...]`. The original never reaches the agent. + How strong a match has to be depends on who wrote the text and where. + See [Block thresholds](#block-thresholds). +* **Reads a thread as one unit.** Where Hive hands an agent several + comments from the same issue or PR, it scans them one at a time and then + once more joined in order. A payload split across two comments matches on + the joined text, and both halves are withheld. The joined scan covers the + most recent 64 comments or 128 KB, whichever is smaller. +* **Plants canaries.** Each task gets its own marker string. Hive scans + everything the agent sends out for that marker, including copies that are + base64-, hex- or percent-encoded, reversed, re-cased, split across + separators or written with look-alike characters. A hit writes an + `ioscan_canary_leak` audit entry and, in `closed` mode, blocks the request. + Encodings outside that list are not caught. Git push bodies are not + inspected; in `closed` mode they are refused. +* **Semantic classifier.** A language model scores the already-cleaned text + for injections written in plain English that no rule matched. It is on by + default at autonomy levels L4–L6 and off below. When it cannot answer, + the rules have already run; what happens next depends on its fail mode. + See [Classifier](#classifier). + +## What it does not do + +Rules match specific phrasings. A measured test against 63 attack payloads +withheld 97% and let 3% reach the agent, with one wrongly withheld benign +case in twelve. A paraphrase that avoids every rule still passes; the +classifier is the control for that. Details and numbers: +[ioscan-red-team.md](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan-red-team.md). The control that stops a persuaded +agent from merging code is the network proxy, which denies pull-request +creation and merge calls for every agent, not `ioscan`. + +## Configuration + +```yaml +ioscan: + enabled: true # default true + fail_mode: open # default: open at ACMM L1–L4, closed at L5–L6 + canaries: true # default true + block_at: # per-surface line for untrusted authors + issue_body: medium # default medium on every surface + comment: medium + pr_body: medium + review: medium + classifier: + enabled: true # default: on at ACMM L4–L6, off at L1–L3 + fail_mode: closed # default: follows ioscan.fail_mode (closed at L5–L6) + model: "" # empty uses the governor's default model (CLI backends: the CLI's own; omp: the omp agents' model) + backend: "" # empty = model endpoint, or the agents' CLI when none; "claude"/"copilot"/"omp" = tool-less CLI + cli_budget_per_eval: 8 # CLI backend only: calls per scheduler pass (max 64) + cli_daily_quota: 500 # CLI backend only: calls per UTC day + warn_threshold: 0.55 + block_threshold: 0.85 +``` + +* `fail_mode: open` withholds matched text and lets the task proceed. + `closed` blocks the task on a Critical finding or a canary leak. The + default is `open` at autonomy levels L1–L4 and `closed` at L5–L6, where + agents can merge. An explicit value in the hive config always wins. In + `closed` mode a Critical false positive stalls that queue item until an + operator clears it. +* `fail_mode` and the classifier are owner-only settings, shown in the + dashboard under Governor Config → Security, together with the classifier's + **Classifier backend** (`classifier.backend`), **CLI calls per pass** + (`classifier.cli_budget_per_eval`) and **CLI calls per day** + (`classifier.cli_daily_quota`). +* `block_at` is set in the hive config file. A typo in a surface name or a + severity is a config error at load time, never a silent default. + +## Block thresholds + +Every rule has a severity: low, medium, high or critical. Text is withheld +when a finding reaches the line for its surface and author. The four +surfaces are `issue_body` (issue title, body and labels), `comment`, +`pr_body` (PR title, body and author login) and `review` (review bodies and +inline review-thread comments). + +| Author | Line | What it means | +|---|---|---| +| Untrusted (anyone else) | `block_at` for the surface, default **medium** | Any injection or dangerous-instruction rule that fires withholds the text. | +| Trusted | **high**, always | Only a strong match withholds the text. | + +A critical finding withholds text on every line. A secret-shaped string +below critical never withholds input on its own; it is reported, not acted +on. + +Trusted means the hive's own identities, GitHub Apps and bot accounts, and +for pull requests a repository owner or member. Collaborators, contributors +and unknown authors are untrusted. Review-bot threads are always untrusted, +because the bot quotes text written by anyone. + +Why the default moved to medium: in the red-team test, 19% of attacks +matched a rule that was recorded and then handed to the agent anyway. The +medium line withholds those. The cost is more withheld text from strangers +when a rule misfires; raise one surface at a time with `block_at` if that +happens on your hive. + +## Classifier + +The rules catch phrasings; the classifier reads intent. After the rules have +cleaned a piece of untrusted text, the classifier asks a small model for a +score from 0 to 1. Above `warn_threshold` it files an advisory. Above +`block_threshold` it withholds the text, or in `closed` mode blocks the +task. + +**Defaults by level.** From L4 up agents open pull requests, so a paraphrase +that slips past the rules has somewhere to go. The classifier is therefore +on by default at L4–L6 and off at L1–L3. Set `classifier.enabled` to +override either way. + +**Fail mode.** When the classifier cannot answer (endpoint down, timeout, +unreadable reply), `open` passes the rule-cleaned text on and records a skip. +`closed` withholds the text with an `injection.semantic_classifier_unavailable` +marker and records a fail-closed entry. `classifier.fail_mode` left unset +follows `ioscan.fail_mode`, so it is `closed` at L5–L6 and `open` below. At +L5–L6 a hive with no model endpoint configured therefore withholds all +untrusted text until one is set, or until the owner sets +`classifier.backend: claude`, `copilot` or `omp` (see **CLI backend** below), +`classifier.enabled: false` or `classifier.fail_mode: open`. The boot log +says so in one line, and the dashboard shows a persistent +`ioscan-classifier-blocked` alert naming those fixes, since every kick that +carries untrusted text is withheld while this lasts (#14499). Runtime classifier +errors in fail-closed mode also raise this alert; a subsequent successful score +clears it. A hive whose +agents all run on a subscription CLI such as Copilot has no such endpoint; +with `classifier.backend` left empty, boot then runs the classifier through +the tool-less CLI most of the hive's agents run on (the most common of +`claude`/`copilot`/`omp` across `agents.*.backend`, ties by name), so such a hive +needs no extra setting. The classifier is built at boot and rebuilt whenever +an ioscan setting is saved in Settings → Security → Input Defense or the ACMM +level changes at runtime, so a new backend or fail mode saved there, or an +L4↔L5 level change, applies immediately; a model endpoint change or a direct +`hive.yaml` edit takes effect after a restart. The Security tab exposes +`ioscan.fail_mode` (which the classifier inherits), not +`classifier.fail_mode`; the alert names that dashboard key. + +**What still passes.** The classifier has a budget of 64 calls per scheduler +pass (8 with a CLI backend, see below). Text beyond that budget is passed on with a `budget_exhausted` skip in +the audit log, in either fail mode; with a CLI backend, so is text beyond +the daily quota. Review-bot threads are not sent to the classifier; the +rules alone cover them. + +**CLI backend.** A hive with no model endpoint, for example one whose agents +all run on subscription CLIs, can run the classifier through a CLI instead +with `classifier.backend`. Empty (the default) keeps the HTTP endpoint path +when an endpoint is resolved and otherwise falls back to the agents' own +tool-less CLI as described above. The accepted backends are `claude`, `copilot` +and `omp`. + +* **Tool-less guarantee.** The CLI is launched with every built-in tool + disabled and no MCP server, in an empty temporary working directory, with + an environment reduced to `PATH`, `HOME`, locale, terminal and the CLI's + own login variables, so no GitHub or hive token reaches a process that + reads untrusted text. No permission-bypass flag is ever passed. Hooks in + the host's own `~/.claude/settings.json` are turned off for the run with + `--settings '{"disableAllHooks":true}'`, so they never see the text; login, + env and model keys in that file still load, and hooks from managed + settings are the operator's own and still run. Its reply must contain + exactly one valid JSON verdict; anything else is a classifier error and + follows `classifier.fail_mode`. +* **copilot.** Copilot CLI is launched as `copilot -s --no-color + --available-tools hive-ioscan-no-tools --disable-builtin-mcps + --no-custom-instructions --no-ask-user --no-auto-update [--model m] -p + <prompt>`. `--available-tools` is an allowlist; naming a tool that does not + exist leaves the model with no tool at all (the CLI logs `Disabled tools: + bash, create, edit, glob, grep, view, web_fetch, …` and every MCP server, + built-in or user-configured, reports `disabled`); an empty list is ignored + by the CLI, hence the sentinel. `--allow-all-tools` is never passed. + Copilot does not read stdin in prompt mode, so the prompt is the value of + `-p`, passed as one argv element with no shell involved. The environment + carries `COPILOT_HOME` and `COPILOT_GITHUB_TOKEN` for copilot's own login + and never `GH_TOKEN`/`GITHUB_TOKEN`, which copilot would otherwise honour. +* **omp.** omp is launched as `omp -p --mode text --no-tools --no-lsp + --no-extensions --no-skills --no-rules --no-session --no-title + --no-context-files --profile hive-ioscan --system-prompt <text> --model m`, + with the prompt on stdin. + The `hive-ioscan` profile is never configured, so no MCP server, hook or + context file from the agents' profile loads, and the default system prompt + is replaced. The environment adds only `OMP_AUTH_BROKER_URL` and + `OMP_AUTH_BROKER_TOKEN` (when set) and never `GH_TOKEN`/`GITHUB_TOKEN`; + omp reads the broker pair from the environment inside the isolated + profile too, so no `auth.broker.*` setting is needed in that profile. + Because `--profile` also isolates settings, the profile has **no default + model**: a launch without `--model` prints `No default model selected` + (exit 0) instead of a verdict. omp therefore always gets `--model`: + `classifier.model` when set, otherwise the model most of the hive's `omp` + agents run with (`agents.*.model`, ties by name). With neither, boot + refuses the backend with one log line naming the fix and behaves as for + any classifier that cannot be built (see **Refused backends**). +* **Refused backends.** `codex` and `gemini` have no command-line + flag that removes every tool, so boot refuses them with one log line and + then behaves as for any classifier that cannot be built: at a closed + classifier fail mode untrusted text is withheld, at open the classifier + does not run. Settings will not save them. +* `classifier.model`, when set, is passed to the CLI as `--model`; empty + uses the CLI's own default for `claude` and `copilot`, and the omp + agents' model for `omp`, which has none of its own in its isolated + profile. +* **Per-pass budget.** Each call starts a CLI process, so the per-pass + budget drops from 64 to `cli_budget_per_eval` (default 8, at most 64). + This is the bound for a pass with many uncached texts: a pass with 64 + uncached texts makes at most 8 CLI calls, and the other 56 pass on with a + `budget_exhausted` skip, in either fail mode. They are classified on later + passes as the budget refills, and cached results cost nothing. +* **Daily quota.** At most `cli_daily_quota` (default 500) CLI calls per UTC + day. Once reached, text passes on unclassified with a + `daily_quota_exhausted` skip in the audit log, in either fail mode, just as + for an exhausted per-pass budget, and the scheduler logs one WARN per UTC + day. The count starts again at 00:00 UTC. Cache hits do not count. +* The backend is chosen at boot and again on every Input Defense save or + runtime ACMM level change in the dashboard; a direct `hive.yaml` edit takes + effect after a restart. + +**Cost.** One call per untrusted text per pass, cached by content, with an +8,000-character cap per call. At the default model that is on the order of +a few thousand input tokens per call; a hive that sees 200 new or edited +untrusted texts a day spends well under a dollar a day. Pick a cheaper model +with `classifier.model` or turn it off with `classifier.enabled: false` if +that is too much. + +## Related checks that do not depend on ioscan + +* Prompt and agent-definition sources must be on the repository allowlist; + unlisted sources are refused. +* If a prompt fetch fails, Hive uses the last cached or built-in template. +* Pull-request claim and trust checks refuse when duplicate work or + privilege escalation is possible. diff --git a/docs/content/hive/linear-agent.md b/docs/content/hive/linear-agent.md new file mode 100644 index 0000000..c3271f2 --- /dev/null +++ b/docs/content/hive/linear-agent.md @@ -0,0 +1,279 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/linear-agent.md) during the docs build. Edit the canonical source in the Hive repository. + +# Linear agent integration + +Part 2 of [RFC #4492](https://github.com/hivecommons/hive/issues/4492) +("converse capability + Linear agents as first-class workspace members"). +With this integration a hive joins a Linear workspace **as an agent**: it can +be assigned or @-mentioned on issues, it acknowledges each agent session +within Linear's 10-second budget, kicks a configured hive agent to do the +work, and narrates completion back into the session as agent activities. + +Part 1 ([#4515](https://github.com/hivecommons/hive/pull/4515)) added the +`converse` capability; the `api.linear.app` proxy enforcement (component F) +merged in [#4522](https://github.com/hivecommons/hive/pull/4522). + +## Architecture + +```text +Linear hive spoke +────── ────────── +issue delegated to app ──webhook──▶ POST /api/linear/webhook (public; HMAC = credential) + │ verify Linear-Signature + ±60s replay window + │ respond 200 immediately (5s budget) + ▼ + Responder (pkg/linearagent) + │ 1. post `thought` activity ◀── SYNCHRONOUS, ≤8s deadline + │ (never waits on the governor loop or tmux) + │ 2. resolve session agent (config, no I/O) + │ 3. SendKick(agent, issue context) + │ 4. post `action` activity ("Delegated") + ▼ + agent works (tmux CLI session) + │ + kick log archived (next rotation point, #4296) + ▼ + kick observer → `response` activity, session finished +``` + +The <10s acknowledgement never depends on the governor's `eval_interval_s` +(300s) or on agent startup: the thought is posted synchronously on webhook +receipt, before the kick is even attempted. A kick refusal (paused agent, +unknown agent) is reported into the session as an `error` activity. + +Completion detection is intentionally coarse: a run "ends" at the next kick-log +rotation point (a newer kick, an agent restart, shutdown). There is no +mid-run streaming of agent output into Linear yet. + +## Setup + +1. **Create a Linear OAuth application** (Linear → Settings → API → + Applications) with: + - Callback URL: `https://<your-hive>/linear/callback` + - Webhooks enabled, URL `https://<your-hive>/api/linear/webhook`, + with the **Agent session events** category checked. Copy the signing + secret. +2. **Set the environment variables** on the hive (see + [env-vars.md](/docs/hive/env-vars#linear-agent-integration)): + `LINEAR_CLIENT_ID`, `LINEAR_CLIENT_SECRET`, `LINEAR_WEBHOOK_SECRET`. +3. **Tell the hive its public origin** when the dashboard is not reached at + `https://<your-hive>` directly. The `redirect_uri` the hive sends Linear + is built from, in order: `dashboard.public_url`, then `hub.dashboard_url` + (hub-hosted spokes only), then the request's + `X-Forwarded-Proto`/`X-Forwarded-Host`/`Host`. Set the first one on a + standalone (`hub.enabled: false`) hive whose dashboard is private but + whose `/linear/callback` is published on another hostname, or that sits + behind an ingress that rewrites the `Host` header (Traefik with a fixed + upstream `Host`, a Cloudflare Tunnel "HTTP Host Header") — otherwise the + install request and the callback request derive different origins and + Linear refuses the code exchange with `redirect_uri is invalid`: + + ```yaml + dashboard: + public_url: https://hive.example.com # origin only: no path or query + ``` + + It must be an absolute `http(s)://` origin; a path, query, fragment or + credentials fail config load with a clear error, and a trailing slash is + trimmed. It is honored from the seed config (`hive.yaml`). Do **not** reach + for `hub.dashboard_url` on a hub-less hive — it is the hub's notion of the + spoke's dashboard link and stays only as the fallback for hub-hosted + spokes. +4. **Connect the workspace**: as an owner, `POST /api/linear/agent/install` + returns an `authorize_url` and the `redirect_uri` it was built with — that + `redirect_uri` is the exact value the Linear app's Callback URL must match, + so check it here rather than decoding the authorize URL. Open the + `authorize_url` in a browser and approve the app for the workspace (the + flow uses `actor=app` and the `app:assignable,app:mentionable` scopes, so + the app becomes an assignable, mentionable workspace member). Linear + redirects back to `/linear/callback`, and the hive stores the workspace + grant + its per-workspace app user id at `LINEAR_AGENT_STORE` + (default `/data/linear-agent.json`). +5. **Pick the session agent** when the hive runs more than one agent — from + the dashboard (Governor → Work Source → Linear → *Session agent*) or in + `hive.yaml`: + + ```yaml + governor: + work_source: + linear: + session_agent: scanner # agent that takes Linear sessions + ``` + + With exactly one configured agent this is implicit. The dashboard rejects + (400) a name that matches no configured agent. +6. **Optional — enumerate only delegated/assigned issues**: when the Linear + work source is active, *Assigned only* in the dashboard (or + `assigned_only: true` in `hive.yaml`) narrows backlog enumeration to + issues assigned **or delegated** to the app user (Linear sets `delegate`, + not `assignee`, when an issue is handed to an agent): + + ```yaml + governor: + work_source: + type: linear + linear: + api_key: ${LINEAR_API_KEY} + assigned_only: true + ``` + + This fails closed: `assigned_only` without a connected Linear agent is a + startup error, never "enumerate everything" — and the dashboard refuses to + save it (400) until step 4 has been completed. +7. **Map teams to repos.** The whole `work_source.linear` block — API key, + hold labels, session agent, assigned-only, and the team list with each + team's `repo`, `states`, `cycles` and per-project repo overrides — is + settable from the dashboard's Work Source tab, backed by + `GET`/`PUT /api/config/governor/work-source` (owner-only). Set `states` + (e.g. `Todo, In Progress`) on each team: without it every open issue in + the team counts toward the governor's backlog and a large backlog will put + the hive into SURGE. `GET` never returns the API key value, only + `api_key_set`; a `PUT` that omits `api_key` keeps the stored one. The + `teams` list is replaced when present and untouched when absent: + + ```json + { + "type": "linear", + "linear": { + "session_agent": "scanner", + "assigned_only": false, + "hold_labels": ["hold"], + "teams": [ + {"key": "ENG", "repo": "my-org/app", "states": ["Todo", "In Progress"], + "cycles": "current", "projects": [{"name": "Billing", "repo": "my-org/billing"}]} + ] + } + } + ``` + +With `type: linear` the GitHub App does **not** need the Issues read +permission: a failed GitHub issue enumeration is logged as a warning and the +cycle continues, with the Linear backlog supplying issues and GitHub supplying +PRs when it can. + +`GET /api/linear/agent/status` (owner) reports configuration, the connected +workspace, the resolved session agent, and recent sessions. +`POST /api/linear/agent/disconnect` (owner) forgets the stored grant (revoke +the app itself from Linear's settings). + +## GitHub-issue parity: agents writing to Linear + +With the pieces above a hive could *read* Linear and *acknowledge* sessions, +but an agent still had no way to do the tracker half of its policy — +file an issue, comment, cite the issue from a PR — against Linear. The +policy templates are written for GitHub Issues (`gh issue create`, +`Fixes #N`, the `hold` label), and the proxy's mutation allowlist was gated +but nothing reachable: no agent held a Linear credential. Parity is built +the same way the GitHub path is, from the config that already exists: + +| GitHub Issues | Linear | Mechanism | +|---|---|---| +| App installation token, tier-scoped, pushed as `GITHUB_TOKEN` to push-capable agents and refreshed hourly | The connected app's OAuth token pushed as `LINEAR_ACCESS_TOKEN` (Bearer) to **ISSUES_ONLY+** agents; falls back to `work_source.linear.api_key` as `LINEAR_API_KEY`; re-pushed on the same hourly refresh tick. **The copy in the agent's environment is not what Linear sees:** the OAuth token rotates (~24h) and a running CLI keeps the environment it was forked with, so the egress proxy — which already terminates every agent request to `api.linear.app` for the tier gate — replaces the `Authorization` header of every ISSUES_ONLY+ request with the hive's *current* credential. A stale, absent, or placeholder token in the agent's shell all work. | `agent.Manager.SetLinearCredentialResolver` and `proxy.GitHubProxy.SetLinearCredentialResolver`, both wired in `main.go` from the same closure over `dashboard.Server.LinearAgentAccessToken` | +| Advisory agents have `GH_TOKEN`/`GITHUB_TOKEN` stripped | Advisory agents have both Linear variables stripped from the tmux session | `ensureTmuxSession` | +| Writes authored by the App bot | Writes authored by the Hive app user (the same identity that acknowledges sessions) | `actor=app` grant | +| `${GH_AUTH}` explains auth; templates give `gh issue create` and `Fixes #N` | A **Work Tracker: Linear** section rendered from `work_source.linear` (team → repo map, states, hold labels, `assigned_only`) and injected into every kick at the same post-resolution seam as held-PR coordination, so customized templates cannot omit it; `${WORK_TRACKER}` places it explicitly | `pkg/scheduler/work_tracker.go` | +| `Fixes #N` auto-closes on merge | Linear's GitHub integration: identifier in the branch name or `Fixes TEAM-123` in the PR body links the PR, moves the issue to In Progress when it opens and Done when it merges; `Part of` / `Refs` / `Contributes to` are the non-closing forms | Linear-side, nothing hive-specific | +| REST route table gates writes by tier | GraphQL operation allowlist gates writes by tier (below) | `pkg/proxy/linear_rules.go` | + +Nothing changes for a GitHub-sourced hive: with no Linear credential the +resolver injects nothing and the tracker section is empty. + +Agents are told **not** to change the state of PR-driven issues by hand — +Linear's GitHub integration owns that transition, exactly as GitHub's +`Fixes` keyword owns issue closure. Make sure the integration is enabled +for the workspace and the repos in `work_source.linear.teams[].repo` are +connected to it. + +### Session kicks and governor kicks + +A delegated issue reaches the hive twice: the webhook opens an agent +session (kicked immediately to the session agent), and — with +`assigned_only: true` — the same issue is enumerated into the governor's +backlog on the next sweep. Kicks never interrupt a running agent +(`SendKick` waits for the CLI's input prompt), so the risk is a *re-hand*: +the governor kicking the same issue again the moment the session's run +ends, or a second agent in the lane taking it in parallel. + +The session tracker is therefore the in-flight ledger. While a session is +`working`, the scheduler withholds its issue from every governor kick's +`${ISSUE_LIST}` and `IssueRefs`, and says so in an **In Flight** note +appended at the same seam as the tracker section (`${IN_FLIGHT}` places it +explicitly). The hold releases when the session finishes — its kick log +archives — or fails. GitHub-sourced items are never session-held. + +### Which agent takes sessions + +`work_source.linear.session_agent` when set; otherwise the sole configured +agent; otherwise the sole enabled agent whose ACMM mode allows tracker +writes (`ISSUES_ONLY` and above) — which is what makes the L3 pack (six +agents, quality the only writer) work without extra config. Two or more +writers is ambiguous and the session is acknowledged with an error naming +the setting. + +### PRs in the session + +When the hive's `hive-open-pr` watcher opens a PR for an agent with an +active session, the PR is narrated into the session as an `action` +activity and attached to the session's external links +(`agentSessionUpdate.externalUrls`), so the person who delegated the issue +sees where the work landed before the run ends. Linear's GitHub integration +attaches the same PR to the *issue* on its own; this is the session +surface. + +## Proxy enforcement + +Agent-side calls to `api.linear.app` go through the ACMM proxy +(`pkg/proxy/linear_rules.go`, merged in #4522): a deny-by-default GraphQL +mutation allowlist where `agentActivityCreate`/`agentSessionUpdate` are +reachable at every tier (they carry the 10-second session invariant), +`issueUpdate`/`commentCreate` require ISSUES_ONLY, the mutations an in-hive +Spek publish makes (`issueCreate` with `parentId`, `issueRelationCreate` for +`blockedBy`, `projectCreate`/`projectUpdate` for the RFC parent) also sit at +ISSUES_ONLY, and anything unknown or unparseable is denied — including the +destructive siblings (`issueRelationDelete`, `projectDelete`, +`projectArchive`). The control-plane client in `pkg/linearagent` (webhook +ack, identity query, token refresh) runs in the hive process itself, not +through the agent proxy. + +## What requires a live workspace to verify + +CI exercises every component against recording fakes; these behaviors depend +on Linear's side of the contract and need a manual pass against a real +workspace: + +1. **OAuth install**: authorize with `actor=app` and confirm the app appears + as an assignable, mentionable member; callback lands with + `?linear=connected` and status shows the workspace + `viewer_id`. +2. **Webhook signatures**: real deliveries verify against + `LINEAR_WEBHOOK_SECRET` (bare hex HMAC in `Linear-Signature`, no + `sha256=` prefix) and pass the ±60s `webhookTimestamp` window. +3. **Ack timing**: delegate an issue to the app and confirm the session shows + the thought within 10s (the responder's deadline is 8s). +4. **Prompt field positions**: `prompted` events are parsed from + `agentActivity.content.body` with a fallback to `agentActivity.body`, and + issue context from `promptContext` at both the top level and under + `agentSession` — confirm real payloads land in one of those. +5. **Delegate filter**: with `assigned_only: true`, confirm delegated issues + (Linear sets `delegate`) are enumerated and unrelated backlog is not. +6. **Token refresh**: after ~24h, confirm the stored access token refreshes + transparently (30-minute grace window; the old refresh token is kept when + the response omits a new one). +7. **Agent writes**: from an ISSUES_ONLY+ agent session, confirm + `LINEAR_ACCESS_TOKEN` is set (and absent in an advisory session), that + `LINEAR_API_KEY`, `LINEAR_CLIENT_SECRET` and `LINEAR_WEBHOOK_SECRET` are + **absent** even though the hive process holds them (a fresh pane must not + inherit them from the tmux server's global environment), that an + `issueCreate` lands authored by the Hive app user — an issue created by a + *person* means the agent found the work-source key — and that an + `issueDelete` is refused by the proxy with a 403 naming the operation. +8. **PR auto-link**: open a PR on a branch named `<agent>/team-123-slug` with + `Fixes TEAM-123` in the body and confirm Linear attaches it and moves the + issue to In Progress, then Done on merge. +9. **Session PR link**: with a session `working`, have the agent open a PR + through `hive-open-pr` and confirm the session shows an "Opened pull + request" activity and the PR under its external links. +10. **In-flight withholding**: while a session is `working`, trigger a + governor kick for the same agent and confirm the delegated issue is + absent from its work list and named under "In Flight"; after the run + ends, confirm it is handed out again on the next sweep (or has left the + enumerated states via the PR). diff --git a/docs/content/hive/maintainer-commands.md b/docs/content/hive/maintainer-commands.md new file mode 100644 index 0000000..4913d43 --- /dev/null +++ b/docs/content/hive/maintainer-commands.md @@ -0,0 +1,372 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md) during the docs build. Edit the canonical source in the Hive repository. + +# Maintainer commands + +Maintainers steer Hive by commenting commands on issues and pull requests. Hive +does not depend on a webhook for the state-changing `/hive` issue commands: the +spoke scans comments during its issue un-park sweep, which runs about every five +minutes. The `/hive help`, `/fixed`, `/reopen`, label-helper, and assignment +helper commands are GitHub Actions conveniences that answer new comments as +soon as Actions schedules the workflow. + +Canonical v5 URL: +https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md + +## Command table + +| Command | What it does | Who may use it | Where it works | Pickup speed | Labels changed | +| --- | --- | --- | --- | --- | --- | +| `/hive approve` | Accepts the recommendation already written on a parked issue. | Human commenter with `write`, `maintain`, or `admin` repository permission. | Open issues carrying `needs-human` or `stage/045-needs-decision` (or the retired `needs-decision` / `needs-direction` / a pre-045 `stage/085-needs-decision`, until migrated). On an open pull request the command gets one acknowledgement or explanation reply and changes no labels (see [PR approval command feedback](#pr-approval-command-feedback)). | Next un-park sweep, normally within 5 minutes. | Removes `stage/045-needs-decision` (and the retired spellings) when present; adds `approved-direction`; removes `needs-human` **whoever added it** — your approval is the human input the label asked for ([#13075](https://github.com/hivecommons/hive/issues/13075), [docs#419](https://github.com/hivecommons/docs/issues/419)); the reply names who had added it. Never removes `hold`: add `hold` to keep agents off an issue through a decision. | +| `/hive decision <text>` | Gives explicit direction for a parked issue. | Human commenter with `write`, `maintain`, or `admin` repository permission. | Open issues carrying `needs-human` or `stage/045-needs-decision` (or the retired `needs-decision` / `needs-direction` / a pre-045 `stage/085-needs-decision`, until migrated); pull requests are ignored. | Next un-park sweep, normally within 5 minutes. | Removes `stage/045-needs-decision` (and the retired spellings) when present; adds `approved-direction`; removes `needs-human` **whoever added it** — your decision is the human input the label asked for, and left in place it would re-derive 045 two minutes later ([#13075](https://github.com/hivecommons/hive/issues/13075), [docs#419](https://github.com/hivecommons/docs/issues/419)); the reply names who had added it. Never removes `hold`: add `hold` to keep agents off an issue through a decision. An agent's later re-park on 085 is refused while `approved-direction` is present and the recorded decision text is unchanged; an agent's later `needs-human` (the remaining work is human-only) keeps `approved-direction` and holds the issue out of the pipeline instead of re-deriving `stage/045-needs-decision` ([#16579](https://github.com/hivecommons/hive/issues/16579)). A newer `/hive decision` with different text means direction is changing: an agent's park goes through, the stale `approved-direction` is cleared, and the issue waits at `stage/045-needs-decision` until the sweep applies the new decision. | +| `/hive decision proceed — <gap>` | Confirms a feature request parked by the prior-art gate is a real gap. | The issue author, or a human commenter with `write`, `maintain`, or `admin`. | Open issues carrying `stage/017-possible-existing` below a `<!-- hive:prior-art-gate -->` comment. | Next un-park sweep. | Removes `stage/017-possible-existing`, appends a **Scope vs existing** section with `<gap>` to the issue body, records the un-park so the issue re-derives `stage/010-actionable` ([#13575](https://github.com/hivecommons/hive/issues/13575)). | +| `/hive decision exists` | Agrees the request already exists. | Same as above. | Same as above. | Next un-park sweep. | Adds `already-exists`, closes the issue `not_planned`, replies with a pointer at the quoted findings. Reopen the issue to continue; the gate does not ask again. | +| `/hive help` | Posts this command list. On parked issues it also repeats the issue-specific approve/decision options. | Any human commenter with at least `triage` repository permission for the on-demand workflow; the sweep path on parked issues requires `write`, `maintain`, or `admin`. | Any open issue or pull request. | GitHub Actions on the new comment; if Actions is unavailable on a parked issue, the next un-park sweep can also answer. | None. | +| `/hive ack [episode]` | Acknowledges an attention episode on the item: you have seen it, so reminders for it stop. **Acknowledgement is not approval.** See [Attention ack and snooze](#attention-ack-and-snooze). | The episode's named responsible person, or a human with `write`, `maintain`, or `admin` repository permission. Anyone else is ignored in silence. | Open issues and pull requests with an unresolved attention episode, on a repository whose `github.attention.admitter` is this hive. | Next un-park sweep, normally within 5 minutes. | None. Never releases a security, merge or review hold and never opens a merge gate. | +| `/hive snooze <duration> [episode]` | Pauses reminders for an attention episode until the duration elapses (`90m`, `4h`, `2d`, `1w`; 1m to 30d). | Same as `/hive ack`. | Same as `/hive ack`. | Next un-park sweep, normally within 5 minutes. | None. A snooze releases no hold. | +| `/fixed` | Confirms that an open issue's fix is verified — or that what a parked issue waited on was done, in or outside the repository — and closes it as completed. Alias: `/close`. Plain-language confirmations such as "yes, this has been fixed" are accepted only when Hive is already waiting for reporter confirmation. | The issue reporter, or a human with `write`, `maintain`, or `admin` repository permission. On a parked issue (`stage/045-needs-decision`, `needs-human`, or a retired park spelling) the un-park sweep honours it from a human with `write`, `maintain`, or `admin` permission. | Open issues only, not pull requests. | GitHub Actions on the new comment where the repository runs the `/fixed` workflow; on parked issues, the next un-park sweep, normally within 5 minutes ([dibs#459](https://github.com/hivecommons/dibs/issues/459)). | Closes the issue as completed. The workflow adds `hive: reporter-confirmed` and removes `hive/likely-done` and `needs-reporter-confirmation` when present. On a parked issue the sweep removes `needs-human` and the retired park spellings, the stage engine strips `stage/*`, and Hive posts one acknowledgement; `hold` is never touched. | +| `/reopen` | Reopens a closed issue that was closed too early. | The issue reporter, or a human with `write`, `maintain`, or `admin` repository permission. | Closed issues only, not pull requests. | GitHub Actions on the new comment. | Removes `needs-reporter-confirmation` when present. The reopen sticks: close-on-merge does not close the issue again for a PR that merged before the reopen, whether Hive (`<!-- hive-close-on-merge -->` comment) or GitHub's closing keyword closed it; Hive records the latter with a `<!-- hive-reopened-after-merge pr=<pr> -->` comment. A later PR can still close it. | +| `/help-wanted` | Adds the `help wanted` label. | Any non-bot commenter accepted by the label-helper workflow. | Issues and pull requests. | GitHub Actions on the new comment. | Adds `help wanted`. | +| `/good-first-issue` | Adds the `good first issue` label. | Any non-bot commenter accepted by the label-helper workflow. | Issues and pull requests. | GitHub Actions on the new comment. | Adds `good first issue`. | +| `/hacktober-fest` | Adds the `hacktober-fest` label. | Any non-bot commenter accepted by the label-helper workflow. | Issues and pull requests. | GitHub Actions on the new comment. | Adds `hacktober-fest`. | +| `/kind <kind>` | Validates or requests a kind label. The Hive label helper reports invalid values and lists the accepted kind names; repositories may also have Prow or other automation that applies valid labels. | Any non-bot commenter accepted by the label-helper workflow, subject to any repository label automation that applies the label. | Issues and pull requests. | GitHub Actions on the new comment. | The helper itself changes no labels for valid `/kind` comments; companion repository automation may add `kind/<kind>` or equivalent labels. | +| `/area <area>` | Validates or requests an area label. The Hive label helper reports invalid values and lists the accepted area names; repositories may also have Prow or other automation that applies valid labels. | Any non-bot commenter accepted by the label-helper workflow, subject to any repository label automation that applies the label. | Issues and pull requests. | GitHub Actions on the new comment. | The helper itself changes no labels for valid `/area` comments; companion repository automation may add `area/<area>` or equivalent labels. | +| `/assign` | Assigns the commenter where the repository's assignment automation supports slash-command assignment. The Hive assignment helper deliberately ignores the exact command because Prow handles it, but it points natural-language assignment requests to this command. | Repository assignment automation decides; the helper response is available to non-bot issue commenters. | Issues. | Repository assignment automation or GitHub Actions helper on the new comment. | Assignment state changes, not labels. | +| `/unassign` | Removes the commenter's assignment where the repository's assignment automation supports it. | Repository assignment automation decides; the helper response is available to non-bot issue commenters. | Issues. | Repository assignment automation or GitHub Actions helper on the new comment. | Assignment state changes, not labels. | +| `/claim` | Says "I am working this issue": a contributor-lane lease on the issue is released and its relay task yanked, no new contributor claim is accepted on it and the hive will not adopt a contributor PR for it unless you release it ([#18899](https://github.com/hivecommons/hive/issues/18899)). It is read from the forge by the claim gate, not parsed by a sweep and not written to the ledger by itself: to register a claim in the ledger use the dashboard or `hivectl claim owner/repo#N`. | A commenter with author association `OWNER`, `MEMBER` or `COLLABORATOR`; bots and the contributor holding the lease are ignored. | Open issues. | The contributor claim's next lease renewal or the five-minute claim release tick. | Applies `hive/claimed-by-human` and `stage/020-claimed` when the claim is recorded in the ledger. | +| `/unclaim` | Withdraws your own `/claim` comment. | The same commenter. | Open issues. | Same as `/claim`. | None. | + +## Claiming an issue + +A person's claim outranks the contributor lane. Any of these on an open issue, made by an owner or maintainer (a person with `write`, `maintain` or `admin` repository permission, never a bot or the hive's own App), counts as a human claim even though none of them goes through the claim ledger ([#18899](https://github.com/hivecommons/hive/issues/18899), child of [#18890](https://github.com/hivecommons/hive/issues/18890)): + +- **Assigning the issue.** This is what an operator's dispatcher does: `gh issue edit --add-assignee` plus a plain "Claimed; fix in progress." comment. The assignment is the claim; the comment is courtesy. An assignee who is the contributor holding the lease is not a claim against that contributor (a maintainer handing the issue to them). +- **A `/claim` comment** (or a plain comment opening with "Claimed") from an `OWNER`, `MEMBER` or `COLLABORATOR`, until the same person comments `/unclaim`. +- **Applying `hive/claimed-by-human` by hand.** The same label applied by the hive is the ledger speaking and is not a claim. + +What a human claim does: a live contributor lease on the issue is released (release reason `human claim: assigned by <login>`, `human claim: /claim comment by <login>` or `human claim: hive/claimed-by-human label by <login>`), its relay task is yanked so the lane moves on, and the person is recorded as the ledger claim holder. While it stands a contributor's fresh claim and renewal are refused, and the hive does not adopt a contributor PR whose `Fixes #N` names the issue (the tracker row reads "an owner or maintainer has claimed the issue"). It lifts when the person unassigns, removes the label or comments `/unclaim`. The supported way to register a claim in the ledger is the dashboard or `hivectl claim owner/repo#N`; the three forge signals above are detected, not ledger entries of their own. + +## Eligibility rules + + +Hive-authored issues normally arrive actionable rather than parked when the question is only an engineering choice (sequencing, naming, numbering, config shape, scope, or approach A vs B). With `project.agent_issue_decision_policy: resolve` (the default), the relay downgrades those attempted parks and records `Decision taken by hive: …`; maintainers can still override with `/hive hold` or `needs-human`. Parked Hive-authored issues should include `Risk: <category>` for the reason a person is required. + +The un-park sweep only honors `/hive approve`, `/hive decision <text>`, `/fixed` +(alias `/close`), and the sweep fallback for `/hive help` when the command is +the first non-empty line of the comment, outside quoted text and fenced code. The comment must be newer than +seven days, unedited, authored by a human rather than the hive or another bot, +and posted by someone who currently has `write`, `maintain`, or `admin` +permission on the repository. A `/hive decision` must include non-empty +instructions. + +On an issue, a first line of `Decision: <text>` (or `Decision (owner): <text>`) +is read as `/hive decision <text>`, under the same permission, freshness and +unedited rules; the lines after it are kept as part of the decision. A first +line that names a decision without recording one (`Decision:` with no text, +`decide ...`, `option 1`, or a bare option letter such as `B`) un-parks nothing +and gets a reply telling the commenter to use `/hive decision <text>`. PRs keep +the strict `/hive decision` shape. + +The on-demand `/hive help` workflow uses the same first-line command shape, is +ignored for bot comments, and allows `triage`, `write`, `maintain`, or `admin` +because it only posts reference text and changes no labels. + +PRs use GitHub's native review signal instead of `/hive approve`; a +`/hive approve` comment on a PR is acknowledged or explained but changes no +labels and is not consumed by any merge lane (see [PR approval command +feedback](#pr-approval-command-feedback)). When the swarm has not approved +the current head because it returned `requires_human`, a human who is +trusted to queue merges can submit a normal GitHub **Approve** review on +that exact head SHA to clear `stage/085-needs-decision` for any author +kind/lane. No special review body is required; the queued human-merge +lane's `Approved by @... for Hive auto-merge on green CI.` body remains +specific to that queue flow. A swarm `changes_requested` or `reject` verdict +is not overridden by a human approval; the head must be fixed or merged +manually. + +For a PR whose closing claims were superseded by another merged PR, a trusted +maintainer with repository write access can reply `/hive decision reject` or +`/hive decision close superseded by #N`. Hive rechecks that the claimed issues +are closed and a different merged PR closed them; an explicit `#N` must match +that closer. It comments and closes the PR with `hive/superseded`, including +PRs opened by contributors, without pushing to their branches. Hold and +`do-not-merge` gates still prevent the close. When nothing supersedes the PR, +a bare `reject` keeps its ordinary meaning (changes requested, nudging the +author), while an explicit `close superseded by #N` is answered with why the +PR stays open. The sweep's +`hive/supersession-pending` cause label keeps the unresolved decision at 085 +through CI or rebase failures; reopening the issue, rewriting the claim, or +choosing `hive/keep-open` clears the sweep's park on its next pass. + +On a **hive-authored** PR (`author/hive`) parked at `stage/085-needs-decision` +the same trusted human has a second lever +([#13041](https://github.com/hivecommons/hive/issues/13041)): a GitHub +**changes requested** review on the current head, or a `/hive decision <what +to change>` comment, moves the PR to `stage/070-fixing` and kicks the author +agent once per head with the review/decision text quoted verbatim plus the +swarm's outstanding findings; the swarm verdict for that head is superseded, +and the new head the agent pushes gets the normal swarm re-review. One kick per +(head, review/comment): a second sweep over the same head does not re-kick, a +dismissed review or a later approval by the same reviewer clears it, and a +changes-requested review left on an older head is outdated. The fix kick is +delivered ahead of the governor's own kick to the same agent in that eval +cycle, so it does not time out behind routine queue work; a kick that still +cannot be sent is logged as `review swarm kick not delivered` with the PR and +audited as `review_kick_undelivered`, and the planner re-plans it next cycle. +The whole comment after `/hive decision` is the instruction — numbered points +on the lines below the command are kept and quoted verbatim — and the +decision on the current head outranks the swarm's decision-requested verdict +on that head, so the stage moves in the same pass as the acknowledgement +rather than waiting on a re-review. A `/hive decision` whose first word is +`approve`, `approved`, or `lgtm` (a trailing comma or period is fine) is +recorded as approval; the rest of the comment is retained as its rationale. A +bare `yes` approves too, but `yes, but …` is a conditional answer and is routed +as an instruction. To request changes, start with the instruction +(e.g. `/hive decision change the PR body to Refs #123`). No fix is kicked +for an approval, requires_human is released for that head and the +PR follows the normal merge path. An acknowledged decision whose record did +not survive a pod restart is rebuilt from the comment thread; a decision +answered for an older head is left alone +([#14679](https://github.com/hivecommons/hive/issues/14679)). +The sweep also reads `/hive decision` at `stage/070-fixing`: approve the +current head after a body or metadata fix to release a standing request without +pushing a cosmetic commit. A later trusted GitHub APPROVED review on the same +head also supersedes the recorded request; an older approval does not. If +that review is later dismissed, or the reviewer asks for changes again on the +same head, the review-backed approval is dropped and the earlier instruction +stands again — a `/hive decision approve` comment is durable and is not. +Issue-link repair preserves edited `Refs` bodies and PRs with a recorded +decision, so it cannot restore auto-close over the owner's direction. +The 085 entry comment names both actions. The commenter must hold `write` or better on the +repo *and* be in the hive's trusted-merger set (the bar a human approval +already meets). `/hive decision` on a PR the hive did **not** open, or `/hive +approve` / `/hive help` on any PR, gets one reply naming the review-side +equivalents instead of silence; the hive never pushes to a PR it did not open. + +`/fixed` and `/reopen` are intentionally narrower: they work for the issue's own +reporter or for `write`/`maintain`/`admin` collaborators. `/fixed` plain prose is +only meaningful when Hive has already asked whether a merged referenced fix can +close the issue; an explicit `/fixed` works on any open issue. Ambiguous prose +with negation or remaining-work language asks the commenter to use `/fixed` +instead of closing. On a parked issue — many park for an action a person must +take outside the repository — the un-park sweep itself honours a maintainer's +`/fixed`, so a repository without the `/fixed` workflow still gets the close, +the label clean-up and one acknowledgement. + +## Attention ack and snooze + +Attention episodes ([#16270](https://github.com/hivecommons/hive/issues/16270)) +ask one named person to act on one condition. `/hive ack` and +`/hive snooze <duration>` let that person, or a maintainer, answer the ask +without resolving it ([#16359](https://github.com/hivecommons/hive/issues/16359)): + +- The command must be the first non-empty line of a recent, unedited comment + by a human, outside quotes and fences — the same rules as the un-park + commands. Only the hive named by `github.attention.admitter` for the + repository answers, so a fleet replies once. +- Without an `[episode]` argument the command applies to every unresolved + episode on the item that you may act on. To target one, pass the key prefix + shown in the item's attention status section, e.g. `/hive ack 3f9a0c12b7de`. +- `/hive ack` records who acknowledged and when; `/hive snooze` records who + snoozed and until when. Both are stored on the episode in the attention + ledger, refresh the status section, and get one reply. +- **Acknowledgement is not approval.** Neither command adds or removes a + label, releases a security, merge or review hold, or opens a merge gate. To + release a hold use the lever the hold names (for example a trusted merger's + GitHub **Approve** review); to resolve the episode, fix the condition — it + resolves when Hive no longer observes it. +- A caller who is neither the episode's responsible person nor a maintainer + is ignored in silence and nothing is recorded. A malformed duration from an + eligible caller gets a reply explaining the accepted forms. + +## Prose replies on parked issues + +Plain approvals such as "approved", "go ahead", "sounds good", or "ship it" do +not un-park an issue. When an eligible maintainer writes prose that looks like +assent, Hive posts a hint asking for `/hive approve` or `/hive decision <text>` +and leaves all labels unchanged. This avoids turning casual agreement into a +state-changing instruction. + +## Model-defined replies + +A repository bound to a [workflow model](/docs/hive/design/workflow-models) may +declare its own human-gate verbs per state (`replies`). On a parked issue in +such a repository, `/hive <verb>` with one of those verbs — multi-word verbs +are fine, case does not matter — is accepted like `/hive decision`: the +parking labels are cleared, `approved-direction` is added, the label the model +maps to the verb's target state is applied when it declares one, and the reply +comment says what the model did with the verb. Any text after the verb is kept +as the decision. The Activity Monitor's human-gate pill offers the same verbs +after the built-in ones. Repositories without a binding, and pull requests, +behave exactly as described above; the model's verbs are not recognised there. + +## Idempotency markers + +Hive marks its standing parked-issue notice with +`<!-- hive:unpark-notice:9879 -->` and edits that comment in place when the +issue options change. Each answer to a specific maintainer comment is marked +with `<!-- hive:unpark-reply:9879 id=<comment-id> -->`. The sweep and the +on-demand `/hive help` workflow both check that per-comment marker before +posting, so reruns and sweep/action overlap do not duplicate replies or repeat +label changes. + +The `/fixed` workflow uses the reporter-confirmation labels and comments +described above. While Hive waits, issues carry `needs-reporter-confirmation` +(and may also carry `needs-human` when the reporter is a maintainer). `/reopen`, +label-helper, and assignment-helper commands are single-comment workflows; +repeat comments can repeat their documented action. + +However an issue closes — `/fixed`, a merged PR's `Fixes #N`, or by hand — Hive +clears the stage labels it left on it: the closed-issue sweep (every 10 +minutes) strips `stage/*` and a Hive-added `needs-human` from recently closed +issues, so a closed issue never sits in the dashboard tracker as needing a +decision ([homebrew-hive#127](https://github.com/hivecommons/homebrew-hive/issues/127)). +A person's `needs-human` and any `hold` stay. + +## The `hive/selfreport` label + +Issues labelled `hive/selfreport` were filed by a hive about itself +(`[selfreport] <class>: …`, see [fleet-report.md](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-report.md)). Each +affected hive is listed in the `Affected hives (N)` block of the body; hives +that hit the same condition add themselves rather than filing duplicates, so +the body block is the fleet-wide tally. Hives post a "cleared on <hive>" comment when the +condition stops — at most once per hive per 24h for a flapping condition, and +never under a closed issue (the hive reads the state first and records the +close) — but never close these issues; close them when the fix has rolled +out. Closing a self-report silences its reporter for that fingerprint for as +long as the reporter keeps observing the condition (the 7-day cooldown runs +from the last observation, not the close), so an old build that still carries +the bug does not re-file daily after an "already fixed on v5" close. A hive +that was quiet about it for 7 days and then sees it again files a new issue, +so `/reopen` the original instead if the fix did not hold. + +## Label-driven repositories + +Some repositories accept and park issues entirely with labels and their own +lifecycle bot (for example `needs-triage` → `triage/accepted`, with the bot +removing `needs-human`). Clearing those labels from Hive would fight that +workflow, so an operator can opt a repository in per repo — in the config file +or from the dashboard (Settings → Repos → "Label-driven approvals +(Prow-style)", write or owner role): + +```yaml +project: + label_driven_approval_labels: [triage/accepted] # default + label_driven_trust_org_members: true # default (Prow's rule) + label_driven_trusted_bots: [hivecommons-prow[bot]] # default + # label_driven_supersede_park_actors: ["github-actions[bot]"] # default empty + repo_policies: + - repo: projectbluefin/common + label_driven: true + # label_driven_approval_labels: [accepted] # optional per-repo list + # label_driven_supersede_park_actors: ["github-actions[bot]"] # optional per-repo list +``` + +This is strictly opt-in (hivecommons/hive#11313). Repositories without +`label_driven: true` behave exactly as described in the sections above; the only +global changes are that an `issues` label webhook lets the un-park sweep run +early, and once-only reply markers are trusted only when the hive itself wrote +them. + +On an opted-in repository the un-park sweep: + +- posts no "What to reply" notice (`<!-- hive:unpark-notice:9879 -->`) and no + hint for prose assent; +- treats a **trusted** addition of an approval label as approval: it removes + the park labels Hive itself added, adds `approved-direction`, and replies once + per acceptance (`<!-- hive:label-approval:11313 event=N -->`). No `/hive` + comment is needed; +- answers `/hive approve` and `/hive decision <text>` the same way (Hive-added + park labels only), and also accepts them from collaborators with the GitHub + **triage** role; `/hive help` gets a one-line reply pointing at the labels; +- never removes a park label a person added, nor `hold` / `do-not-merge`. When + one of those is present the issue stays parked and Hive posts one + "accepted, but still held by …" note naming the labels. + +#### Lifecycle bots that park every new issue + +Some repositories run a lifecycle bot that adds `needs-human` to every new +issue and never removes it; Hive's rule of removing only its own park labels +would then keep an accepted issue parked forever +([#13605](https://github.com/hivecommons/hive/issues/13605)). List that bot in +`label_driven_supersede_park_actors` (project-wide, or per repo under +`repo_policies[]`) and a trusted acceptance added **after** the bot's park +label supersedes it: Hive removes the label, says so in the release comment +("`needs-human` (added by @github-actions[bot]), superseded by the acceptance +as this repository's configuration allows"), and releases the issue. A park +label added by a person, by an unlisted bot, or by a listed bot *after* the +acceptance still blocks exactly as before, and `hold` / `do-not-merge` are +never superseded. The list is empty by default. + +Parked issues are still filtered from enumeration, and Hive may still add +`stage/045-needs-decision` with a comment asking the question. (Owner +decision, 2026-10-17: issues park at `stage/045-needs-decision`; +`stage/085-needs-decision` is PR-only. The un-park sweep still clears a +pre-045 085 from an issue.) + +### Who may apply the approval label + +Only the actor of the most recent `labeled` event for the label is checked +(removing and re-adding re-evaluates the newest event). Trusted, in order: + +1. a bot in `label_driven_trusted_bots` (Prow command bots relaying + `/triage accepted`). The default list is only `hivecommons-prow[bot]`. + `github-actions[bot]` is not trusted by default because it is the shared + identity of every workflow in the repo; if your Prow emulation runs as + `github-actions[bot]`, add it explicitly per deployment; +2. a collaborator whose GitHub `role_name` is `triage`, `write`, `maintain` or + `admin` (custom roles that build on triage count as triage); +3. a public member of the repository's owning org, when + `label_driven_trust_org_members` is on (default). + +Anything else — an untrusted person, an unlisted bot, a label Hive applied +itself, or a timeline that could not be read — is **not** approval; the sweep +fails closed and logs once. + +### What each label does on a label-driven repository + +Label approval layers on top of the existing label paths rather than replacing +them; the table states every effect in one place. + +| Label | Un-park sweep (label-driven repo) | PR self-authorization sign-off | Reporter-trust admission (`issue_filter.reporter_trust`) | +|---|---|---|---| +| `triage/accepted` (or configured approval label) applied by a trusted actor | Releases the issue: Hive-added `stage/045-needs-decision` (and retired spellings) removed, `approved-direction` added, one reply; `needs-human` is kept even when Hive added it (only the `/hive` commands lift a Hive-added one) | Counts as human sign-off, like `approved-direction` | Unchanged: still one of the labels that admits an untrusted reporter's issue if listed in `untrusted_require_labels` | +| same label applied by an untrusted actor / unreadable timeline | No effect (fail closed) | Not sign-off | Unchanged | +| `approved-direction` | Issue is not parked | Human sign-off (unchanged) | n/a | +| `stage/045-needs-decision` added by Hive | Removed on label approval or `/hive approve` | Parked → no sign-off | n/a | +| `stage/045-needs-decision` added by a person | Kept; issue stays parked, Hive posts one "still held" note | Parked → no sign-off | n/a | +| `needs-human` added by Hive | Removed on `/hive approve` / `/hive decision` / `/fixed` — the maintainer's answer to the hive's own ask ([#13075](https://github.com/hivecommons/hive/issues/13075)); kept on label approval; removed when the issue closes | Parked → no sign-off | n/a | +| `needs-human` added by a bot listed in `label_driven_supersede_park_actors` before the acceptance ([#13605](https://github.com/hivecommons/hive/issues/13605)) | Removed on label approval, named in the release comment; added after the acceptance it is kept like a person's | Parked → no sign-off | n/a | +| `needs-human` added by a person (or unreadable timeline) | Kept on a label-driven repo: the lifecycle bot owns it, and only a person removes it; the issue stays derived at 045 and out of the agent queue. (Elsewhere `/hive approve` / `/hive decision` / `/fixed` lift it whoever added it — [docs#419](https://github.com/hivecommons/docs/issues/419).) | Parked → no sign-off | n/a | +| retired `needs-decision` / `needs-direction` ([#12683](https://github.com/hivecommons/hive/issues/12683)) | Migrated by the issue stage reconciler: `stage/045-needs-decision` added, retired label removed; a person's retired label therefore becomes a Hive-added 045 and `/hive approve` can clear it | Parked → no sign-off | n/a | +| `hold`, `do-not-merge` | Kept; issue stays parked (unchanged) | Hold (unchanged) | n/a | + +## How the hive sees comments + +The un-park path is polling, not a webhook: every sweep lists open issues, keeps +the "What to reply" notice on issues parked by `needs-human` or +`stage/045-needs-decision`, and then considers the newest eligible +comments within a bounded seven-day window and a per-sweep action cap. Agents may +still read issue threads directly in their prompts, but the deterministic label +transition to `approved-direction` happens only when the sweep accepts +`/hive approve` or `/hive decision <text>`. + +## PR approval command feedback + +Hive answers recent `/hive approve` comments on open PRs once per comment, +including PRs without a parking label +([#13087](https://github.com/hivecommons/hive/issues/13087)). Its reply +acknowledges the comment and names the lever that actually releases a +`requires_human` hold on this release line — a trusted merger's GitHub +**Approve** review on the current head — or explains why the lane cannot act +on it: for example, the commenter is not a trusted merger (on any merge lane — +contributor, trusted-author or hive-authored — since only a trusted merger's +Approve releases a hold), the contributor-lane verdict is a rejection rather +than `requires_human`, or the PR touches a manual-only path. An ordinary +contributor cannot release their own PR. + +The acknowledgement does not merge the PR, remove labels, or bypass any +merge gate; no merge lane consumes `/hive approve` on a PR. +`stage/085-needs-decision` comments name the action for that lane under +**How to release it**, including the GitHub **Approve** review when that is +the lever, and explicitly identify manual-only merges such as workflow edits, +removed tests or configured human-merge paths. diff --git a/docs/content/hive/native-merge-queue.md b/docs/content/hive/native-merge-queue.md new file mode 100644 index 0000000..a1eb3d4 --- /dev/null +++ b/docs/content/hive/native-merge-queue.md @@ -0,0 +1,496 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/native-merge-queue.md) during the docs build. Edit the canonical source in the Hive repository. + +# Native GitHub merge queues + +## Composable capabilities, not three merge engines + +1. **Conventional direct merge:** coordinated, per-repo/base preparation + ([#15836](https://github.com/hivecommons/hive/pull/15836)) reduces competing + refresh writers and separates ready seats from pending preparation. It is + independently useful without a native queue. Check that PR's merge and the + deployed version before assuming it is available on a particular hive. +2. **Native GitHub queue:** the admission hand-off shipped in + [#15308](https://github.com/hivecommons/hive/pull/15308). This page describes + the accompanying CI/policy integration. It is per-repository opt-in; + merged code, deployed code, Hive's enabled flag, and GitHub's queue rule + are four different states. Hive controls admission and repair; GitHub is + the sole integration/landing writer. +3. **Integration-aware multi-agent orchestration:** planned coordination + layered on these capabilities, not implemented or selectable here. + +The existing Features settings panel shows native-queue configuration and +links here. Configuration remains in `hive.yaml`; the panel does not change +GitHub rules or activate a queue. Hive's visual train is not GitHub's FIFO +queue. A pending native group can still block later landings, and a queue's +merge limits do **not** combine CI builds or eliminate head-of-line blocking. + +## Opting in + +The hand-off is **off by default** and opt-in per repository. A hive that +never sets `auto_merge.native_merge_queue` sees no behaviour change: no lane +probes a queue, enqueues, withdraws an entry or lists a paused repo's PRs, and +a queue-required base still parks at `merge-queue-required`. + +```yaml +auto_merge: + native_merge_queue: + enabled: true # default false + repos: [hivecommons/hive] # owner/repo allow-list; empty = every watched repo + bases: [hivecommons/hive#v5] # exact repo#base pairs; branch case is significant + skip_current_base_gate: false # default false — see "Current-base gate" below + probe_ttl: 30m # default 30m — see "API cost" below +``` + +| Key | Default | Meaning | +| --- | --- | --- | +| `auto_merge.native_merge_queue.enabled` | `false` | Turns the native-queue hand-off on. | +| `auto_merge.native_merge_queue.repos` | unset (every watched repo once enabled) | `owner/repo` allow-list, matched case-insensitively. Repos outside it keep the pre-queue behaviour. | +| `auto_merge.native_merge_queue.bases` | unset (all queue bases in opted-in repos) | Additional exact `owner/repo#base` allow-list. Branch names are case-sensitive. Unlisted bases never enqueue or bypass current-base refresh. | +| `auto_merge.native_merge_queue.skip_current_base_gate` | `false` | Lets a queue-enabled base bypass the `auto_merge.require_current_base` gate and the `behind` update-branch. Off keeps both gates in force on queue bases. | +| `auto_merge.native_merge_queue.probe_ttl` | `30m` | How long one base branch's `isMergeQueueEnabled` answer is reused before it is re-read. | + +Owners can configure the same policy at **Settings → Features → Auto-Merge → +Native GitHub merge queue**, then click **Save**. The enable switch and +“Queue owns freshness” switch are both **OFF by default**. Repositories, +exact repository/base pairs, and the queue-detection TTL are editable there. +Settings refuses enabling without both explicit scope lists, rejects malformed +or wildcard scopes, mismatched repositories and negative/invalid durations, +and preserves omitted fields on partial updates. `0` TTL uses the 30-minute +default. Existing YAML configurations retain their original unscoped semantics +when the optional lists are absent; the Settings enable path deliberately +requires explicit scope. + +Saving changes the Hive policy only: it does **not** create a GitHub queue, +change branch protection, set the external freshness variable, deploy code or +attest that prerequisites are satisfied. Follow the pilot rollout below first. +Disabling does not drain existing GitHub queue entries: drain or withdraw them +before rollback. Trust/review/hold/CI/soak and attribution gates remain intact. + +## Activity Tracker: observed operation, not a second merge engine + +When enabled, **Activity Tracker → ⛓ GitHub merge queues** is a separate +rail beside the preparation rail, outside actual pipeline rows, built from the +tracker's own parts (the preparation rail's head line, the Merged/Merge queue +popover lists, badges and the shared help mark). It reads overview first, +details on demand ([#18702](https://github.com/hivecommons/hive/issues/18702)): + +- **One head line for the panel:** how many PRs are queued on how many + branches, how many test groups are running, how many branches need + attention, and when the newest check happened. A **?** help mark carries + every caveat once (membership never inferred from FIFO or ref names; + candidate checks belong to the synthetic SHA, never the PR head; an empty + list in an old snapshot does not prove an empty queue; a vanished group ref + is not a merge or failure receipt; repo filter and page/filter references). + The caveats are not repeated per branch or per group. +- **One status line per branch that has something to say:** `repo → base`, + then `2 PRs queued · front #801 awaiting checks, in queue 12m · testing: + checks running`, then `checked 9m ago`. Entry states are GitHub's own + (`QUEUED`, `AWAITING_CHECKS`, `MERGEABLE`, `UNMERGEABLE`, `LOCKED`) in plain + words; an unknown slug is shown as-is, never invented. Branches with + nothing queued, no live test group and no problem are folded into a single + `N branches with nothing queued` line (and `N not checked yet` for scopes the + rotation has not visited), with the per-branch lines behind a click. When + every branch is calm the panel is that head line plus the folded line. +- **Details on demand**, per branch, behind a `<details>` toggle: the full + entry order with exact heads and page/filter words, live test groups with + their proven members (or "members not proven") and the candidate SHA's + required checks, finished groups as a count, and lifecycle receipts. +- **Age instead of alarm.** Evidence past the six-minute fresh window is the + documented normal state of a rotating reader, so it reads as `checked 9m + ago` (plus a dashed `awaiting re-check` badge only when PRs are queued), + not as a STALE banner. Warning styling (`ham-badge` in the error colour, + scope name in the error colour) is reserved for real problems: `refresh + failed`, `GitHub App auth unavailable`, `not checked for 47m` (older than + the fresh window plus two full rotations of the configured scopes), and + `checks failed` on a live group. +- **Finished groups are history, not candidates.** A `merge_group` run whose + synthetic ref is gone or moved is sent with `expired: true` and never drawn + as a live validation candidate; the panel counts it as `N finished groups + (outcome not observed)`. It does not claim the group merged or failed; only + an observed merged receipt means merged. +- **Required-check policy on ruleset-only branches.** Classic protection + answers `404 Branch not protected` for a branch protected only by rulesets; + that is "no classic requirements", so the rules read supplies the policy and + it is known. A `403` or any other classic error still leaves the policy + unknown, and unknown is never shown as passing. + +Readiness/preparation, native admission, candidate testing and an actual +merged receipt remain different states. Linked issue/PR trees are not +reparented or duplicated into pipeline rows; references say whether that exact +repository/PR/head/base is on this page, on another page, or outside the +snapshot/changed. Repository filtering applies to the rail; its references are +not silently dropped by row pagination. The panel stays read-only and performs +no API reads of its own; the observation budgets below are unchanged. + +Candidate cards identify actual `merge_group` synthetic refs and SHAs from +authenticated events or Actions runs. **Membership is unknown** unless a signed +event base, the live queue chain, every exact member head's ancestry and a final +unchanged synthetic-ref read all agree. FIFO positions and PR numbers embedded +in ref names are never membership proof. Several observed candidates can appear +in parallel. The CI drilldown reads only the candidate SHA, including required +check names, status, conclusion, producer binding and available job links; it +never substitutes green PR-head checks. Classic protection and applicable rules +must both be readable before required policy is known. Missing/pending/skipped +checks or unreadable policy are never portrayed as passing. + +The provider-neutral `forgestate.QueueObservation` contract is read-only and carries +no admission or merge authority. The GitHub adapter feeds an in-memory cache +from the existing governor cycle, at most once per three minutes, rotating +across two scopes per pass with one 45-second background budget. Each scope +reads at most 100 entries and 100 workflow runs; at most four recent candidate +cards and eight member ancestry checks per card are observed. Larger/incomplete +cohorts explicitly report partial coverage rather than implied completeness. +There are no per-render or per-PR observation pollers; OFF performs no +observation API reads. Evidence older than six minutes is explicitly stale; +failed refreshes retain older evidence with unavailable/stale diagnostics. +More than two configured scopes can therefore be stale while rotation catches +up. Observations need App installation read access to queues, Actions, +checks/statuses, contents and branch policy (including Administration read for +classic protection). Verify those permissions explicitly; enqueue permissions +alone do not establish this visibility. Unavailable authentication +or permissions are reported, not silently substituted with configured checks. + +Authenticated `merge_group` deliveries retain candidate identities and +`destroyed` receipts. Complete consecutive entry snapshots can establish an entry's +removal, **not its reason**. Only an authenticated merged-PR delivery for a +previously observed exact queued/member head records a merged receipt and its +actual merge SHA. Failed required CI is shown on that candidate; moved/expired +refs do not prove failure, rebuild or merge. No rebuild reason, percentage or ETA +is invented. The last 32 lifecycle receipts and 16 event hints are memory-bounded, +not an exhaustive durable audit. At most 32 scope snapshots are retained; +evicted or not-yet-observed configured scopes report unknown. Missed deliveries and restart gaps remain +explicit. Configure delivery of `merge_group` and `pull_request` events to the +existing authenticated webhook endpoint for full event evidence; discovery +without a signed group base intentionally leaves member mapping unknown. + +## How it works + +Automerge sweeps detect a PR's target queue with GraphQL +`PullRequest.isMergeQueueEnabled`. Once the lane's existing approvals, trust, +holds, review, CI and soak gates allow a merge, Hive calls +`enqueuePullRequest` with `expectedHeadOid` set to the validated head. GitHub +runs the merge group's checks and performs the eventual merge. Branches without +a queue keep the direct REST merge path. + +Hive uses its GitHub App installation transport. Static tokens (including a +workflow's `GITHUB_TOKEN`) retain the existing direct-merge behavior and +`merge-queue-required` refusal, since workflow-token events cannot reliably +start `merge_group` workflows. The App installation must grant the existing +merge permissions (`contents: write` and `pull_requests: write`). Permission +or GraphQL failures are surfaced as queue failures; Hive never falls back to +bypassing a detected queue. This change does not request wider App permissions. + +Already queued PRs are left in place. The sweep reason reports +`native-merge-queued: queued (position N, STATE)` and maps to +`stage/100-merge-queue`; enqueueing does not emit a completed-merge event or +close an issue. The stage observation carries the reason to the dashboard. + +When the owning lane rejects a PR because it lost merge eligibility — a hold +or `do-not-merge`/`needs-human` label, a removed merger label, a missing, +untrusted or stale queue approval, changes requested, a draft or closed PR, a +release in progress on the repository, or a human-merge-path hold — Hive rechecks the entry's enqueuer and withdraws it only if it belongs to +this App (a `Bot` enqueuer whose login matches the App's slug). Every other +reason, including transient refusals such as `behind`, `not-mergeable`, pending +checks, a moved head, API read errors, author-routing skips and Hive's own +native-queue outcomes, leaves the entry for GitHub's queue to settle. Entries +from a person or another App are preserved. +The queued sweep also withdraws this App's entries on opted-in repositories +that are paused or have automerge disabled. Every enqueue and dequeue uses the +existing mutation boundary, including its write denials. Reconciliation is +periodic/event-driven, so a gate change can race GitHub's eventual merge. + +A queue-required base reports `mergeable_state: blocked` (or `behind`) until +the PR merges through the queue, so on a queue-enabled base the queued lane +does not treat those states as `not-mergeable`. A failed queue read keeps the +non-queue behavior. + +## Current-base gate + +The `auto_merge.require_current_base` gate and the `behind` update-branch stay +in force on a queue-enabled base exactly as on any other base: a behind head +is updated (or parked) before it is enqueued. The merge group does test the +merged result itself, and a pushed head drops the PR from the queue, so an +operator who prefers to let the queue own freshness can set +`auto_merge.native_merge_queue.skip_current_base_gate: true`. That bypass is +explicit and hive-wide for opted-in repos; it is never implied by the presence +of a queue. + +## API cost + +Each `isMergeQueueEnabled` probe is a GraphQL read. The answer is cached per +`owner/repo#base-branch` for `auto_merge.native_merge_queue.probe_ttl` +(default 30 minutes), so a sweep over many PRs on one base costs one probe, +not one per PR; a read failure is not cached. The per-held-PR entry +reconciliation, the extra `GET /pulls/{n}` the queued lane needs to run it +on a prefiltered PR, and the 10-minute paused-repo PR listing all run only on +repos that opted in through `auto_merge.native_merge_queue`. + +Queue rules choose the merge method. Where Hive elected a merge commit to +preserve mixed authorship and DCO attribution, the queue must use `MERGE`; +otherwise Hive reports `native-merge-queue-method` rather than enqueueing. +Like a direct merge GitHub refuses because the merge method is disabled, the +PR parks at `stage/085-needs-decision` for a person, with the `merge-method` +explanation: change the queue's merge method to `MERGE`, or merge it by hand. +The refusal is remembered for 30 minutes per head, so the queue's method is +not re-read every sweep; a new head or the recheck window reads it again. +Read and enqueue failures (`native-merge-queue-read`, `-enqueue`) stay at +`stage/100-merge-queue`; a failure to read the queue's merge method is a +read failure too, not a refusal, and is reported as `native-merge-queue-read`. + +Required workflows must subscribe to `merge_group` in addition to their PR +triggers. `v2-ci.yml`, `v2-tests.yml` and `go-security-analysis.yml` subscribe +to `merge_group: {types: [checks_requested]}`. Their default checkout tests +the synthetic `github.sha`, not a member's head. Group events always select +the full suite/scans, including coverage; the PR-only affected-package and +out-of-scope shortcuts do not apply. Distinct groups use independent run IDs +and cannot cancel each other. Failure issue creation/publishing stays scoped +to its existing push/schedule events; candidate test jobs have read-only +tokens. The coverage reporter's write permissions are job-scoped, not +inherited by group test jobs. + +## Required checks and provider boundaries + +The existing eleven v5 checks cannot simply be required under their old +names on a group SHA. Probot DCO (App **1861**) checks PR commits; GitHub +Actions (App **15368**) cannot legitimately impersonate that provider on a +synthetic commit. PR verifier/changelog/attribution checks also need real PR +metadata, not a fabricated last-member PR event. + +`native-queue-policy.yml` owns the **new** `native-queue-policy` check: + +- On `pull_request` (earlier runs on `pull_request_target`, which GitHub blocks + by default on public repositories from 2026-12-02, are still accepted as + replay evidence), it executes only the trusted base's validator + and waits up to 22.5 minutes for the five existing policy checks on that + exact PR head. No candidate code is executed; tokens are read-only. + `verify PR contents` is accepted from either provider: the `pr-verifier.yml` + check run (events `pull_request`, `pull_request_target` or `workflow_dispatch`) + or a commit status of that context created by the App bot named in the + repository variable `HIVE_PR_GATE_CREATOR_LOGIN`. With the variable unset the + hive status provider is not configured and the legacy check run is the only + evidence; a status from any other creator is always ignored. + Label, edit, or unlabel events re-trigger this workflow and serialize behind + any in-flight run (the concurrency group is per-PR and never cancels + in-progress); the queued run re-reads mutable PR state after the prior run + finishes, preserving fail-closed semantics. Labels the policy never reads + (`size/*`, `dco-signoff`, stage labels, ...) skip the wait: the job replays + the latest completed `native-queue-policy` `success` on the same head, + still checks the live PR for holds, draft and head moves, and re-validates + the five policy checks on that head — a provider re-run red since the + original verdict fails the job instead of being replayed. When there is no + prior success to replay (never evaluated, or the last wait failed or timed + out), a policy provider is still pending or missing on the head, the DCO + provider reports UNKNOWN, or GitHub returns a 5xx, the job falls through to + the full wait so a stale verdict is never pinned onto later cosmetic flips. + `hold`, `needs-human`, `release-in-progress` and `do-not-merge*` flips + always get the full wait. +- On a group it executes the event's trusted `base_sha` validator. It reads + the live queue prefix ending at the event's exact synthetic head, + verifies contiguous membership and the base/head commit chain, and checks + **every** member, not the PR number encoded in the temporary branch name. + Each current member head must be an ancestor of the synthetic head. +- Every member must have all eleven original check results on its exact + head from the expected App. Actions results additionally bind to their + actual workflow file, event, head, matching check-suite ID and exact job's + `check_run_url` through the Actions API. A copied `details_url` or check + name is not proof of membership in that workflow. Only technical PR jobs may + carry their existing path-scoped `skipped` result; the five policy proofs + require `success`. No missing, neutral, failed or unavailable evidence is + treated as success. The verifier retains its existing advisory behavior; + this bridge does not turn its underlying implementation into a strict + content validator. Dependabot runs that same trusted PR-target verifier + rather than skipping it; skipped policy evidence is never exempted by actor. +- One narrow exception replaces probot `DCO` (#17030): a PR whose head + branch is exactly `sync/v5-to-v6` in this repository, whose base is `v6`, + and which was opened by `github-actions[bot]` (the `v6-topup.yml` + identity). Every PR commit except the head must be reachable from `v5` + (compare API `v5...<sha>` is `behind`/`identical`), the head must be the + top-up's two-parent merge of `v5` history onto `v6` history, and the list + must stay under the REST 250-commit cap. Those commits already passed v5's + DCO gate and probot cannot be repaired PR-side, so the latest prow `dco` + commit status created by `hivecommons-prow[bot]` must be `success` instead; + a `dco` status from any other creator is ignored. Any unmet condition falls + back to requiring probot `DCO`. The check output names the DCO path taken + and, on fallback, why. +- A forward-merge PR (head `sync/vN-to-vM*` or `topup/*`) must land by merge + commit. On a group, every member head must already be an ancestor of the + synthetic head; a squash or rebase queue never contains the PR's own head, so + for these heads the failure names the merge-method violation (#18931) rather + than the generic "not contained" error. The narrow DCO exception above does + not cover a top-up that carries a history-restoring ours-merge (that commit is + not on `v5`); such a PR needs probot `DCO`, so its flagged inherited commits + are remediated by their own authors (see + [v5-sync-policy.md](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-sync-policy.md#dco-on-top-up-prs)). +- Draft/held PRs, changes requested, dismissed approvals and approvals on an + old head fail closed. A `pull_request_target` run on an already closed or + merged PR (re-fired by a post-merge label or comment edit) passes as a + no-op before any eligibility or evidence check; on `merge_group` a closed + PR still fails closed. Membership and mutable PR/review state are re-read + before success, and the synthetic ref must still name this group. + Missing/pending evidence has a bounded wait; API errors, inconsistent + membership and untrusted provenance fail the check. A later owner rerun + must read current evidence again; it cannot bless a vanished group. + +Hive's per-head author trust, internal reviewer verdicts, admission approvals, +soak and mutation boundary remain authoritative **before enqueue**. The +bridge does not recreate Hive's private approval store or invent another +reviewer. Admission loss is also reconciled by Hive's App-owned withdrawal; +[#15781](https://github.com/hivecommons/hive/pull/15781) is a rollout +dependency for release-freeze and human-merge-path withdrawal. It is not +included in this implementation. A label/approval/config change after the +final reads can race GitHub landing; neither this check nor periodic +withdrawal is an atomic lock spanning two systems. An urgent stop must +remove entries/disable the GitHub queue, not merely wait for a Hive sweep. + +### Equivalent check mapping (manual migration) + +Do **not** change live protection until the rollout below. The intended v5 +required set is seven contexts, all bound to GitHub Actions App **15368**: + +| Required on PR **and** group | What it enforces | +| --- | --- | +| `native-queue-policy` | PR-head `gate` (`docker.yml`), external `DCO`, `changelog-fragment-guard`, `verify PR contents`, `Sign-off survives the squash`; on groups, all eleven original member-head proofs plus live membership/holds/reviews | +| `build-and-test` | Real synthetic-group build/validation (`v2-ci.yml`) | +| `test` | Real synthetic-group aggregate; fails on missing/failed shards (`v2-tests.yml`) | +| `coverage` | Real synthetic-group shard profiles and unchanged package floors (`v2-tests.yml`) | +| `golangci-lint` | Real synthetic-group lint (`go-security-analysis.yml`) | +| `gosec (insecure patterns)` | Real synthetic-group security analysis | +| `govulncheck (known vulnerabilities)` | Real synthetic-group vulnerability analysis | + +The five replaced names **continue to run on PR heads** and are transitively +required by the new owned check; DCO has not been removed as a logical +requirement or relabeled as an Actions result. Do not retain those five as +direct group requirements without a supported provider implementation: that +would deadlock the queue. Do not add fake success statuses to get past it. +Do not bind `native-queue-policy` to Probot. Any `auto_merge.required_checks` +override must agree with the new required set; original member evidence is +still checked by the bridge. Non-pilot branches retain their current rules. + +## Pilot rollout + +No deployment, repository-variable update, branch-rule mutation or runtime +enablement is performed by this code. An owner must do the following, in order: + +1. Land and deploy #15836 first, and land #15781 plus this integration with + their latest-head CI green. Keep native queue disabled during preparation. + Do not cherry-pick or silently bundle those other branches. A Go fixture + repair on #15836 is independent of this integration. +2. Confirm the trusted base contains the new workflows and validator. Obtain + a real green `native-queue-policy` PR-target run on a disposable v5 PR, + including DCO from App 1861 and all original PR checks. This initial + integration PR cannot demonstrate its new PR-target base workflow until + that workflow exists on v5. Test a multi-member group in a controlled + queue pilot before expanding beyond one member; mocked fixtures are not + proof of GitHub's live membership/commit-chain representation. +3. In repository **Settings → Branches → v5 protection → required status + checks**, first add `native-queue-policy` (GitHub Actions) **alongside** + all eleven old checks. Confirm an ordinary PR passes all twelve. Preserve + every other protection, including `strict=false` and current review + policy; do not broaden bypass actors. Ensure the owner/reviewer workflow + fence protects changes to these trusted workflows/scripts. +4. Configure the external writer's repository Actions variable, initially + inert unless a real queue is detected: + + ```sh + unset GITHUB_TOKEN && gh variable set HIVE_NATIVE_QUEUE_FRESHNESS \ + --repo hivecommons/hive --body 'hivecommons/hive#v5' + ``` + + This is a space-separated, **case-sensitive** `owner/repo#base` allow-list. + Set Hive's repository allow-list to `[hivecommons/hive]` and explicitly + set `skip_current_base_gate: true`, leaving `enabled: false` for now. + The workflow variable alone cannot enable a queue or Hive admission. +5. In **Settings → Branches → v5 protection**, in a single saved rule edit, + enable **Require merge queue** and replace the old eleven-check binding + with the seven-context mapping above, each with expected source + **GitHub Actions**. The new owned gate is already verified and required + before this edit; never remove old bindings first in a separate save. + If the UI/plan cannot express this, stop rather than leave an interval + with incomplete requirements. Use **MERGE** (merge commits), build + concurrency **1**, minimum merge group size **1**, maximum **1** for + the first pilot, and a check timeout exceeding the 25-minute policy job + budget plus runner wait. Keep “only merge non-failing pull requests” + enabled. Build concurrency counts groups, not individual runner jobs. + Do not change rules for v6 or any other repo/base. +6. Only after that GitHub rule is saved, enable Hive: + + ```yaml + auto_merge: + native_merge_queue: + enabled: true + repos: [hivecommons/hive] + bases: [hivecommons/hive#v5] + skip_current_base_gate: true + probe_ttl: 30m + ``` + + Hive probes actual queues per base; only v5 has a queue in this pilot. + Other bases keep direct merge and coordinated refresh because they are + outside the explicit base allow-list. Do **not** enable a v6 queue until + its separate rollout is ready. Allow for probe-cache expiry + (or a controlled owner restart) before diagnosing stale queue detection. +7. Enqueue one signed, reviewed PR through the App. Record its expected head, + enqueuer, synthetic SHA, all seven group checks, merge method, resulting + commit and issue closure **after actual merge**. Exercise an intentionally + failing check, hold/review withdrawal, and the external updater on both + v5 and a non-queue branch. A queued membership observation is not merge + evidence. Expand concurrency/member count only after the controlled + multi-member test validates every member head and earlier-member failure. + +The safe initial method is **MERGE**, preserving existing commit authors and +their DCO trailers. A repository-wide squash preference does not override +the mixed-authorship guard. Keep existing `merge-method/merge` attribution +decisions; do not rewrite sign-offs or drop authors merely to make admission +green. A queue configured for SQUASH/REBASE can still park mixed-authorship +PRs at `stage/085-needs-decision`. + +### One freshness owner + +`pr-auto-update.sh` normally retains its push file-intersection and +shared-incident recovery behavior. Only an exact allow-listed repo/base +**and** a successful live `isMergeQueueEnabled` probe suppress author-head +updates, including incident recovery. This covers waiting PRs, not just +members already enqueued. A queue-read error in an opted-in repo stops the +writer rather than guessing “direct mode”. Outside that allow-list, or on +a positively detected non-queue base, behavior is unchanged. + +The variable and Hive's explicit `skip_current_base_gate` must be activated +together as above. #15836 owns conventional direct-mode preparation; +GitHub owns opted-in queue freshness. Existing return-to-author repair +handles rejected/broken heads; there is no second fixer or merge engine. + +## Diagnostics and rollback + +- If the authoritative DCO App cannot enumerate a large PR's complete commit + history, admission reports **DCO provider unavailable / verdict UNKNOWN** + and remains blocked. Follow the [provider diagnosis and recovery runbook](/docs/hive/operator-reference/dco-provider-unavailable); + a provider enumeration failure does not request a PR source change or permit + substitution of the lowercase prow `dco` status outside the narrow + `sync/v5-to-v6` forward-merge path above. +- Inspect the PR's exact-head checks and the **group SHA** checks separately. + A green member head does not establish green integration evidence. + `native-queue-policy` logs the failing provider, provenance, membership, + hold or review condition. An unknown/changed GitHub queue schema fails + closed and needs investigation; it is not permission to bypass the gate. +- A group waiting on `DCO` or another old policy name indicates an incomplete + binding migration. A missing build/test/security context indicates workflow + trigger, permission, runner or checkout failure. Read the actual run; + do not infer success from absence. +- A pending GitHub-hosted policy job can delay the queue independently of + self-hosted build capacity. The policy's minimal read token must read + queues, PRs/reviews, check runs and Actions provenance; permission failures + stop validation. Workflow-file push permissions are also required to land + this integration. +- To roll back, first disable new Hive admissions and remove/stop GitHub queue + entries through the owner UI (disabling Hive alone does not stop entries + already owned by GitHub). In one v5 rule edit restore the original eleven + required check bindings and remove **Require merge queue**; preserve all + other protections. Remove `HIVE_NATIVE_QUEUE_FRESHNESS`, restore + `skip_current_base_gate: false`, and leave native admission off. The + external updater resumes only after actual queue detection says false; + clear/expire Hive's probe cache. Conventional coordinated refresh remains + available. No history rewrite is needed. + +Workflow-trigger diagnosis is not automatic in the Hive runtime. +See GitHub's [merge queue guide](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) +and [GraphQL pull request reference](https://docs.github.com/en/graphql/reference/pulls). diff --git a/docs/content/hive/notifications.md b/docs/content/hive/notifications.md new file mode 100644 index 0000000..18890a6 --- /dev/null +++ b/docs/content/hive/notifications.md @@ -0,0 +1,817 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/notifications.md) during the docs build. Edit the canonical source in the Hive repository. + +# Notifications + +Hive can send operator notifications through three outbound channels configured under the top-level `notifications:` block in `hive.yaml`: + +- ntfy topics +- Slack incoming webhooks +- Discord webhooks + +The notifier is implemented in `src/pkg/notify/notify.go` and is constructed from `config.NotificationsConfig` in `src/pkg/config/config.go`. The same notification is sent to every configured channel. + +Every notification title is prefixed with the sending hive's ID as `[<hive-id>] <title>` (`Notifier.SetHiveID` in `src/pkg/notify/notify.go`). Filters or routing rules that match on title - an ntfy topic shared by several hives, for example - should account for the prefix. + +## Configuration + +```yaml +notifications: + ntfy: + server: https://ntfy.sh + topic: my-hive-alerts + slack: + webhook: ${SLACK_WEBHOOK_URL} + discord: + webhook: ${DISCORD_WEBHOOK_URL} + factory_webhook: ${DISCORD_FACTORY_WEBHOOK_URL} + github_activity: + enabled: true + # org defaults to project.org; keep explicit for hub/factory feeds. + org: hivecommons + # optional: defaults to 5 minutes + poll_interval_s: 300 + # empty repos means all org repos; otherwise list repo names in this org. + repos: [] + # empty events means the default full event set. + events: + - issue_opened + - issue_closed + - issue_reopened + - issue_claimed + - issue_released + - pr_opened + - pr_ready_for_review + - pr_review + - pr_ci_status + - pr_merged + - pr_closed + - hourly_digest + # default true; bot/dependabot noise is suppressed unless allow-listed. + filter_bots: true + filter_dependabot: true + allow_authors: [] + deny_authors: [] +``` + +All three channels are optional. Configure one channel or several. Webhook URLs are secrets; keep them in environment variables or Kubernetes Secrets rather than committing literal URLs. + +### ntfy + +| Field | Required | Notes | +|---|---:|---| +| `notifications.ntfy.server` | yes | ntfy base URL, for example `https://ntfy.sh` or your own HTTPS ntfy server. | +| `notifications.ntfy.topic` | yes | Topic name appended to the server URL. | + +Hive posts the notification body to `<server>/<topic>` and sets `Title` and `Priority` headers. Priorities are `high`, `default`, or `low`. + +When ntfy returns HTTP 429, Hive pauses ntfy delivery until the `Retry-After` deadline (positive seconds or a future HTTP date). If the header is absent or unusable, the cooldown starts at one minute and doubles on subsequent rate limits up to one hour, resetting after successful delivery. Notifications during the cooldown are dropped without replay; new notifications resume delivery after it expires. Slack and Discord delivery continue independently. + +Self-hosted ntfy works the same way as ntfy.sh as long as the Hive process can reach the HTTPS endpoint. On the public ntfy.sh server, choose a hard-to-guess topic because anyone who knows the topic can subscribe to it. + +### Slack + +| Field | Required | Notes | +|---|---:|---| +| `notifications.slack.webhook` | yes | Slack incoming webhook URL. The sender posts `{"text":"*title*\nmessage"}`. | + +The notifier accepts `http://` and `https://` URLs in the Go sender, but production configs should use Slack's HTTPS webhook URLs and keep the value in an environment variable. + +### Discord webhook + +| Field | Required | Notes | +|---|---:|---| +| `notifications.discord.webhook` | yes for webhook notifications | Discord webhook URL. The sender posts `{"content":"**title**\nmessage","flags":4,"allowed_mentions":{"parse":[]}}` — `flags: 4` is Discord's `SUPPRESS_EMBEDS`, so URLs in a notification render as plain links without a preview card, and the empty `allowed_mentions.parse` stops untrusted text (issue titles, repo names) from pinging `@everyone`, `@here`, roles or users. | +| `notifications.discord.factory_webhook` | yes for `notifications.github_activity.enabled` | Dedicated Discord webhook URL for org-wide GitHub issue/PR activity. The sender posts one-line `{"content":"🐝 [repo] ... <url>","flags":4}` messages; the `<url>` wrapping and `SUPPRESS_EMBEDS` flag keep the channel free of link preview cards. | + +Use a Discord **webhook URL**, not a bot token, for notification delivery. + +### GitHub activity feed + +`notifications.github_activity` enables the hub's org-wide issue/PR activity +poller. It is **off by default**. When enabled, hub mode enumerates repositories +from `orgs/<org>/repos`, diffs issue/PR state across poll cycles, and sends +concise activity lines to the dedicated +`notifications.discord.factory_webhook`. The state and sent-event dedupe keys +are persisted under the hive data directory so a hub restart seeds from disk +instead of replaying previously observed activity. + +| Field | Required | Default | Notes | +|---|---:|---|---| +| `notifications.github_activity.enabled` | no | `false` | Turns the feed on. | +| `notifications.github_activity.org` | no | `project.org` | GitHub organization to enumerate with `orgs/<org>/repos`. | +| `notifications.github_activity.api_url` | no | configured GitHub API URL / `https://api.github.com` | Override for GitHub Enterprise or tests. | +| `notifications.github_activity.poll_interval_s` | no | `300` | Hub poll cadence. | +| `notifications.github_activity.repos` | no | empty | Empty enumerates every org repository; non-empty limits polling to those repo names. | +| `notifications.github_activity.events` | no | empty/full set | Selected factory-feed events: `issue_opened`, `issue_closed`, `issue_reopened`, `issue_claimed`, `issue_released`, `pr_opened`, `pr_ready_for_review`, `pr_review`, `pr_ci_status`, `pr_merged`, `pr_closed`, `hourly_digest`. | +| `notifications.github_activity.filter_bots` | no | `true` | Suppresses `*[bot]` authors unless allow-listed. Forward-merge PRs are still allowed to emit their single merged line. | +| `notifications.github_activity.filter_dependabot` | no | `true` | Suppresses Dependabot authors unless allow-listed. | +| `notifications.github_activity.allow_authors` | no | empty | Case-insensitive author logins that bypass the default bot filters. | +| `notifications.github_activity.deny_authors` | no | empty | Case-insensitive author logins that are always suppressed. | + +Hub admins can edit the factory webhook, enablement, repo scope, event set, and bot filter in `/dashboard` under **Hub Admin — Notifications**. Saves persist to `hive.yaml` and hot-reload the poller by cancelling the old run and starting a new one against the same state file, so already-sent dedupe keys are not replayed. + +Event keys are deduped as `(repo, number, event, sha-or-version)`. Forward-merge +PR chatter is collapsed so only the final merged message is posted: + +```text +🐝 [hive] PR #8562 merged into v6 — 🌱 Forward-merge v5 into v6 (4 commits, hand-resolved) · @clubanderson +``` + +Current v1 event coverage: + +| Area | Event | Notes | +|---|---|---| +| Issue | opened | New open issues observed after the initial seed. | +| Issue | closed completed / not planned | Uses GitHub `state_reason` when present. | +| Issue | reopened | Closed → open transition. | +| Issue | hive label added | `claimed`, `hive/*`, and `priority/*`. | +| Issue | assigned/claimed | Newly added assignee. | +| Issue | claim marker taken/released | Diffs `<!-- hive:claim ... -->` in issue body when present in API responses. | +| PR | opened | New non-draft open PRs observed after the initial seed. | +| PR | ready for review | Draft → ready transition. | +| PR | review requested | Newly requested reviewers from the PR list response. | +| PR | approved / changes requested | Latest submitted PR review decision. | +| PR | CI red/green transition | Terminal combined-status changes (`success`, `failure`, `error`) on the head SHA. | +| PR | merged | Includes the target branch (`merged into v6`) and merge/head SHA dedupe. | +| PR | closed unmerged | Open → closed without merge. | + +### Per-recipient attention budget (opt-in, off by default) + +Per-condition reminder limits do not add up to an attention budget: ten +conditions on ten items each reminding daily is still ten pings a day for one +person. `pkg/attentionbudget` caps **non-urgent** attention writes (first +pings and reminders) per responsible recipient per rolling 24 hours, across +items, and never drops an ask that goes over the cap +([#16271](https://github.com/hivecommons/hive/issues/16271), part of +[#16075](https://github.com/hivecommons/hive/issues/16075)). + +| Field | Default | Notes | +|---|---|---| +| `github.attention.recipient_budget` | `0` (off) | Max non-urgent attention writes per recipient per rolling 24h. `0` keeps today's behaviour; maximum `1000`. | +| `github.attention.digest_recipients` | empty | GitHub logins (case-insensitive, optional `@`) that opted into the digest. | + +These keys live in the `github.attention` block owned by the condition-episode +ledger ([#16267](https://github.com/hivecommons/hive/issues/16267)), which +admits every non-urgent write through the budget: the ledger's first ping for +a newly actionable episode (`Store.Report`) and every attention-pilot reminder +(`SweepAttentionQueue`). The budget is seeded from the ledger's delivered +history (`paged_to`/`paged_at` and the last reminder) when the ledger opens, so +the rolling window survives restarts. An over-budget ask is never dropped: its +episode stays open and would-notify, is marked `overflowed` in the ledger, +stays in the repo's attention queue issue, and is posted on a later pass once +the recipient's budget frees up (or cleared when it is acknowledged, snoozed +or resolved). Producers mark exempt asks with `Observation.Class` +(`security`, `required_review`, `protocol_command`, `hold`); an unset class is +an ordinary non-urgent ping. + +- **Off (shadow mode).** With `recipient_budget: 0` every write is delivered + exactly as before. The budget still counts, per recipient, how many writes + would have overflowed a candidate cap of 5 (`ShadowBudget`) and reports + `delivered`, `exempt`, `overflowed` and `would_overflow` per login in the + `attention budget:` log line (emitted on every attention-queue sweep), so an + operator can choose N from evidence before enabling it. +- **Enabled, recipient opted into the digest.** The (N+1)th non-urgent ping or + reminder in the window is not posted. It stays an open, overflowed ask: it is + listed in the item's status card (`attention-overflow` section), in the + repo's action queue, and in the recipient's digest. +- **Enabled, recipient not opted in.** Per-episode delivery is kept: newly + actionable asks are always posted; only reminders over the cap are deferred + (and remain visible in the status card and action queue). +- **Digest.** One comment per recipient per repo, identified by + `<!-- hive:attention-digest recipient=<login> -->`, posted on the repo's + attention queue issue, created once through the existing marker-comment + upsert and edited in place afterwards (edits notify nobody). It serves as the reminder for the asks it lists. No external + service is involved. +- **Never budgeted.** Materially new security risk or imminent destructive + action, mandatory/required reviews, machine-consumed protocol commands, and + every security/merge hold notice always deliver immediately and do not + consume budget. Unclassified writes are treated as exempt. + +### Attention action contract + +Every admitted attention event must let the recipient act without digging +([#16359](https://github.com/hivecommons/hive/issues/16359), part of +[#16270](https://github.com/hivecommons/hive/issues/16270)). Producers build +the event body with `attention.NewObservation`, which refuses an incomplete +`attention.Event`; `Event.Render` emits, in order: + +| Field | Meaning | +|---|---| +| **Who** | The person or team asked to act. | +| **What changed / why now** | The change that made the condition need attention now. | +| **Requested action** | The single concrete thing asked of the recipient. | +| **Evidence** | What the condition was observed from (run, finding, SHA). | +| **What Hive tried** | What Hive already attempted on its own. | +| **What happens next** | What Hive will do if nobody acts. | +| **How to ack, snooze or resolve** | `/hive ack`, `/hive snooze <duration>`, and what clears the condition. | + +Every event ends with the same wording: *Acknowledgement is not approval: +`/hive ack` and `/hive snooze` only quiet reminders. They release no security, +merge or review hold, change no label and open no merge gate.* See +[maintainer commands](/docs/hive/operations/automation-and-review/maintainer-commands#attention-ack-and-snooze). + +## What triggers notifications + +The Hive Go process sends notifications for these events: + +| Event | Priority | Source | +|---|---|---| +| Weekly token budget crosses the warning threshold. | default | `applyBudgetAlerts` in `src/cmd/hive/main_eval_cycle.go` | +| Weekly token budget is exhausted and non-exempt kicks are suspended. | high | `applyBudgetAlerts` in `src/cmd/hive/main_eval_cycle.go` | +| Actionable issues exceed the SLA threshold; up to three `SLA 2x breach` notifications are sent per eval cycle for issues older than 60 minutes (`maxSLANotificationsPerCycle`, `doubleSLAMinutes`). | high | `selectSLABreachNotifications` in `src/cmd/hive/eval_cycle_seams.go`, sent from `runEvalCycle` in `src/cmd/hive/main_eval_cycle.go` | +| A running agent pane matches a configured login-required pattern; Hive pauses that agent and sends the backend-specific login instruction (`Login required: <agent>`). | high | `scanForLoginRequired` in `src/cmd/hive/main.go` | +| Trajectory review detects divergence and either pauses the agent or flags the divergence. | high | `src/pkg/dashboard/trajectory_sink.go` and `src/pkg/trajectory/lane.go` | +| The inference provider starts rebuffing kicks with spending-limit errors; sent once per crossing of the latch, not per cycle (`Provider spending limit reached`). | high | provider-budget kick gate in `runEvalCycle`, `src/cmd/hive/main_eval_cycle.go` | +| A probe kick succeeds after a spending-limit clip and agent kicks resume (`Provider spending limit lifted`). | default | provider-budget recovery path in `runEvalCycle`, `src/cmd/hive/main_eval_cycle.go` | +| A PR stays red after exhausting its automated fix-attempt budget and is escalated to a human (`Fix loop escalated`). | high | `runEscalationSweep` in `src/cmd/hive/main_sweeps.go` | +| The planning stall-replan lane re-kicks the architect on a stalled plan (`Plan replan`) or hits the replan cap (`Plan replan-cap`). | high | `src/pkg/planning/replan.go` via `src/pkg/dashboard/replan_sink.go` | +| The convergence rollout mode changes at runtime (settings PUT, YAML reload, or env override); sent once per transition, not per cycle (`Convergence mode changed`). | default | `applyConvergenceKickAdmission` in `src/cmd/hive/convergence_kick.go` | + +The dashboard **Settings → Notifications** tab can set ntfy, Discord, and Slack webhooks and choose which hook transitions should notify. The selected event set is persisted as `notifications.events`; the dashboard also manages matching `notify` hooks for `sweep_completed`, `escalation_red`, `stage_completed`, `issue_claimed`, and `issue_released` so those transitions use the same fanout. + +Operator-defined [hooks](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md) with the `notify` action send through the same fanout: title, message, and priority come from the hook definition (`ActionNotify` in `src/pkg/hooks/action.go`, bridged by `notifierAdapter` in `src/cmd/hive/hookwire.go`). An unknown priority falls back to `default`, so any transition a hook can observe can also page these channels. + +The legacy shell scripts in `bin/` also use `bin/notify.sh` for events such as stale agents, rate limits, backend switches, and kick status when those scripts are deployed. Those scripts read environment variables (`NTFY_TOPIC`, `NTFY_SERVER`, `SLACK_WEBHOOK`, `DISCORD_WEBHOOK`) rather than the `notifications:` YAML block. + +## Review requests + +An agent's `request_review` relay (`hive-open-issue request-review`, or +`gh pr edit --add-reviewer`) skips any user or team whose review request on +the PR is still pending: asking again would only re-ping them for the same +unresolved ask. The skipped names are reported in the request result as +`reviewers_already_pending` / `team_reviewers_already_pending` and in the +audit entry as `already_pending`; when everyone named is already pending, no +GitHub call is made. Someone who has already submitted a review is no longer +pending, so they can still be asked again for a new head. If the pending list +cannot be read, everyone named is requested, so a needed review is never +dropped. + +## Mention hygiene + +Text the hive copies into a body it authors (issue/PR titles, quoted comments, +evidence, attribution) must never notify the people it names. The status +comment writer (`prstatus.Write`) passes every section through +`advisory.NeutralizeMentions`, the same convention the advisory digest and +duplicate-sweep renderers use: `@login` becomes `` `login` `` (only the `@` is +dropped inside code spans and fences). Email addresses, URLs and `#123` +references are untouched, and the rewrite is idempotent. Sections of a status +comment another author posted are neutralised too when they are merged into +the hive-owned comment, since that body is re-edited on every pass. This +applies regardless of the attention-pilot flag. + +Deliberate mentions are posted as their own comments or reviews through the +notification-class framework and are not rewritten. The one deliberate mention +that lives in the status comment, the trusted-human 071 note's `@author` in +quiet-notification mode, goes through `prstatus.WriteMentioning`, which posts +the section verbatim; its composer neutralises the copied check names and +review asks itself, so the author is the only person it notifies. + +## Testing delivery + +Test the target channel directly before putting it in `hive.yaml`: + +```bash +# ntfy +curl -s -H 'Title: Hive test' -H 'Priority: default' \ + -d 'notification test from hive operator' \ + https://ntfy.sh/my-hive-alerts + +# Slack incoming webhook +curl -s -X POST -H 'Content-type: application/json' \ + --data '{"text":"*Hive test*\nnotification test from hive operator"}' \ + "$SLACK_WEBHOOK_URL" + +# Discord webhook +curl -s -X POST -H 'Content-type: application/json' \ + --data '{"content":"**Hive test**\nnotification test from hive operator"}' \ + "$DISCORD_WEBHOOK_URL" +``` + +After editing `hive.yaml`, restart or reload Hive through your normal deployment path. Dashboard saves for hive notifications persist ntfy, Discord, Slack, and event selections; hub factory-feed saves hot-reload without a hub restart. + +## Discord webhook vs Discord bot + +Webhook notifications are the `notifications.discord.webhook` field above. + +The repository also contains a separate Discord bot under [`../../discord/`](https://github.com/hivecommons/hive/blob/v5/discord/). That bot is a Node.js service using `DISCORD_BOT_TOKEN` and `DISCORD_CHANNEL_PRIMARY` to connect to Discord, route commands, and bridge dashboard/pipeline status. It is not required for webhook notifications, and a bot token cannot replace `notifications.discord.webhook`. + +For the Hive Go process, bot startup uses `notifications.discord.bot_token` and `notifications.discord.channel_id` when both are set. Those fields start the bot integration; they do not send ordinary webhook notifications unless `notifications.discord.webhook` is also configured. + +## RFC lifecycle notices (Discord bot) + +Set `notifications.discord.rfc_channel_id` (or the env var `HIVE_DISCORD_RFC_CHANNEL_ID`, which overrides it) together with `notifications.discord.bot_token` and the hive posts one line to that channel when an RFC issue in a managed repo: + +- is opened: `RFC opened: #N <title> - <url> (by @author)` +- is closed: `RFC closed (completed): ...` or `RFC closed (not planned): ...`, from GitHub's close reason +- is taken off hold so it can be implemented: `RFC ready to implement (hold removed): #N <title> - <url>`, when the `hold` label (Prow `/unhold`) comes off an open RFC, or a held RFC moves to `stage/010-actionable`. One notice per hold episode. + +An issue is an RFC when it carries the `rfc` label, its title starts with `RFC` after any leading emoji or `[tag]` (`RFC: ...`, `[RFC] ...`, `📝 RFC: [v6] ...`), or one of its leading `[tags]` contains the word `RFC` (`📝 [v5 RFC] ...`, `[RFC v6] ...`; `[RFC #N]` references an RFC and does not count). A hive that manages several repos prefixes the number with the repo (`owner/repo#N`). + +The default is empty, which turns the notices off. `channel_id` is not required: the notices only post with the bot token and never start the command bot. The hive polls GitHub every three minutes for issues updated since its last poll (one list call per repo) and keeps per-issue records in `/data/rfc-notify.json`, so a restart never re-announces a transition. The first poll after the key is set only records the current open RFCs; transitions announce from the next poll on. Each post is also written to the audit log as `rfc-notify`. + +```yaml +notifications: + discord: + bot_token: ${DISCORD_BOT_TOKEN} + rfc_channel_id: "1540404487099777136" +``` + +### Rich mode, the designated announcer, and private repositories + +These keys sit next to `rfc_channel_id`. All of them default off, and with none of them set the notices are the one-line posts above, unchanged. + +| Key | Default | Effect | +| --- | --- | --- | +| `rfc_format` | `""` (= `line`) | `line` posts one line per transition. `card` posts the transition text (including a linked RFC for accepted documents) alongside a Discord summary card (embed; with `rfc_threads: true` the post is plain text and the embed renders only when threads are off) with target, status, scrubbed summary, open-decision count and colour by state (held grey, needs-decision amber, ready green, closed completed blue, closed not-planned dark); malformed bodies fall back to the line. Card posts share the bounded `429` retry of every Discord call (see *Rate limits and failures* under [Threads](#one-thread-per-rfc-rfc_threads)). Any other value is a config error. | +| `rfc_threads` | `false` | Rich mode: one Discord thread per RFC in the existing text channel (see [Threads](#one-thread-per-rfc-rfc_threads)). Needs `rfc_announcer`. | +| `rfc_announcer` | `false` | Marks this hive as the one designated announcer for `rfc_channel_id`. Rich mode posts only from the announcer. | +| `rfc_backlink_comment` | `false` | With `rfc_threads`, comments `Discussion thread: <url>` on the RFC once, after the thread exists. | +| `rfc_include_private` | `false` | Authorizes posting RFCs from private repositories to the channel. | + +- **Announcer rule.** Rich mode means `rfc_format: card` or `rfc_threads: true`. A hive in rich mode without `rfc_announcer: true` posts nothing and logs `rfc notify: rich mode requires rfc_announcer; not posting` once. It keeps recording transitions, so turning on the announcer later does not backfill old ones. Set `rfc_announcer: true` on exactly one hive per channel. Line mode ignores the key. +- **RFC documents proposed as pull requests (rich mode only).** A pull request is an RFC document when its title starts with `📖 proposal:` or `📖 RFC` (a leading `📝` still counts), or it adds or changes `docs/rfc-*.md` or `src/docs/rfc-*.md`. The announcer posts `RFC doc proposed: #N <title> - <url> (by @author)` when one opens, titled by the document's first heading when the hive read it, and `RFC doc accepted (RFC #M): ...` when it merges, attributed to the RFC issue its body links (`Closes`/`Refs #M` or an issue URL), or `RFC doc accepted: ...` when it links none the hive tracks. PRs already open when the hive takes its baseline are not announced, and a PR closed without merging posts nothing. Each poll lists pull requests updated since the last poll, plus the changed files of those whose title does not already mark them. Line mode stays issues-only. +- **Lifecycle changes (rich mode only).** On the announcer the hive also posts one line per change to an open RFC: `RFC decisions: 2 → 1 open: ...` when the open count under *Decisions for maintainers* changes (at most one per RFC per 30 minutes; changes inside that window collapse into the next notice with the latest count), `RFC target: v5 → v6: ...` and `RFC status: <old> → <new>: ...` (values cut to 100 characters) when the RFC field table changes (a body that no longer parses is not a change), and `RFC needs a decision: ...` when `stage/045-needs-decision` or `needs-human` is added. A retitle posts nothing: with `rfc_threads` it edits the opened card in place and renames the thread. An RFC opened by the same author with the same title (lowercased, RFC prefix, leading bracketed tags such as `[v5 RFC]` or `[v6]` and emoji removed, leading/trailing punctuation stripped, whitespace collapsed) as an open RFC in the same repo opened up to an hour earlier gets no card: the hive posts `RFC duplicate filed as #M - <url>` once into the first RFC's thread, and closing the duplicate posts nothing. These lines are never cards. With `rfc_threads` they go into the RFC's thread; otherwise to the channel. The 30-minute and one-hour windows are fixed. Line mode posts none of them. +- **Private rule (every mode, line mode included).** An RFC in a private or `internal` repository is not posted unless `rfc_include_private: true`. This keeps its title and link out of the channel. The hive resolves each repo's visibility once and caches it for an hour. A repo whose visibility cannot be resolved counts as private (fail closed). A withheld transition is still recorded, so it is never posted later. + +```yaml +notifications: + discord: + bot_token: ${DISCORD_BOT_TOKEN} + rfc_channel_id: "1540404487099777136" + rfc_format: card + rfc_announcer: true # only on the one announcing hive + rfc_include_private: false # default: private-repo RFCs are not posted +``` + +#### One thread per RFC (`rfc_threads`) + +On the announcer, `rfc_threads: true` keeps the text channel (no Forum) and turns each RFC into a card plus a thread: + +- **Opened** posts the card, then starts a thread on it named `#N <title>` (cut to Discord's 100 characters). The card and the thread ID are stored per RFC in `/data/rfc-notify.json`, which is now state version 2; a version 1 file loads unchanged, and a file written by a newer hive is refused rather than downgraded. +- **Closed, ready to implement, doc accepted and the lifecycle changes above** post into the RFC's thread. Closed and ready also echo one line to the channel. An RFC announced before threads were enabled has no thread and keeps getting the plain channel line; it is never back-filled. +- **Idempotency.** Before the card is posted the hive saves a write-ahead intent with a deterministic nonce (a hash of `repo#number` plus `opened`, 25 characters) and sends it with Discord's `nonce` and `enforce_nonce`, so a retry inside Discord's dedup window returns the same message. Channel history is never treated as a claim between hives; the single announcer is the only writer. +- **Reconciliation.** At startup, and whenever an RFC has an intent without a confirmed card or a card without a thread, the hive does one lookup of the channel's last 50 messages for a message of its own bot with the card's nonce or exact text. A match is adopted (no second card); with no match the card is re-posted once more with the same nonce. A failed lookup re-posts nothing. Card posts and thread starts are each tried at most 3 times across polls and restarts, then logged and left alone. Only RFCs this hive began announcing are reconciled, so there is no historical burst. +- **Backlink (`rfc_backlink_comment: true`).** Once the thread is confirmed the hive comments `Discussion thread: <thread URL>` on the RFC, through the per-issue bot comment budget. The flag is saved after it succeeds, so restarts do not repeat it; a failure leaves the flag unset and is retried up to 3 times, then logged. Default off: the hive never comments on issues otherwise. +- **Rate limits and failures.** Every Discord call honours a `429` `retry_after` with at most 3 bounded retries (each wait capped at 15 seconds). Failures count in the sweep's `errors`, are logged as warnings, and are written to the audit log as `rfc-notify` lines with `threads`, `reconciled`, `backlinks` and `errors`. + +```yaml +notifications: + discord: + bot_token: ${DISCORD_BOT_TOKEN} + rfc_channel_id: "1540404487099777136" + rfc_threads: true + rfc_announcer: true # only on the one announcing hive + rfc_backlink_comment: false # opt in to comment the thread link on the RFC +``` + +The bot needs the `Create Public Threads` and `Send Messages in Threads` permissions, plus `Read Message History` for reconciliation. + +## GitHub writes: inventory and shadow mode (`github.notifications.shadow`) + +Every new issue/PR comment, review submission, review request and @-mention +the hive makes on GitHub emails the people involved and everyone watching the +repository. [`github.notifications.mode`](/docs/hive/operator-reference/sweeps-and-operations#notification-mode-githubnotificationsmode) +already folds the hive's own bookkeeping into one edited status comment; +shadow mode measures what is left so a later change can be judged against a +baseline ([#16075](https://github.com/hivecommons/hive/issues/16075)). + +```yaml +github: + notifications: + shadow: true # default false +``` + +Shadow mode is **instrumentation only**: nothing is suppressed, delayed or +rerouted, and the GitHub writes are byte-for-byte the same with the flag on +or off. With the flag on, each notification-capable write the Go client makes +is attributed to its producer (the inventoried function below), classified, +and given a *would-notify* decision: + +- **Record** — `{repo, item, producer, class, condition key, would_notify, + reason}` plus the logins the write mentions or requests. Comment bodies, + other recipients and inbox contents are never kept. The last 512 records + stay in memory (`Client.NotificationShadowRecords`). +- **Condition key** (provisional) — `(repo, item, class, subject)`, where the + subject is what the writer supplies (the status-comment section key for + `PostNoteOrFold`) or the producer name. A later change defines the + authoritative, producer-independent key. +- **Decision** — a write whose condition key was already written within 24 + hours is `would_notify=false`, reason `repeat_condition`, **only** for the + `status` and `attention` classes. `protocol_command`, `required_review` and + `security_event` writes are always `would_notify=true` (a repeat gets reason + `exempt_class_repeat`). A failed write is `delivery_failed`. + +### Counters + +The hourly `github notifications` log line gains `shadow_would_suppress`, +`shadow_reviews`, `shadow_review_requests`, `shadow_mentions`, +`shadow_delivery_failures` and `shadow_active_items` while shadow mode is on +(the line is unchanged while it is off). The opt-in Prometheus endpoint +(`HIVE_METRICS_ENABLED` + `HIVE_METRICS_TOKEN`) exports: + +| Series | Labels | Meaning | +|---|---|---| +| `hive_github_comments_total` | `op` = `created` / `edited` / `suppressed` | The always-on comment tally. | +| `hive_github_notification_comments_created_total` | `producer`, `class` | New comments. | +| `hive_github_notification_reviews_submitted_total` | `producer`, `class` | Review submissions. | +| `hive_github_notification_review_requests_total` | `producer`, `class` | Review requests. | +| `hive_github_notification_mentions_total` | `producer`, `class` | @-mentions in posted comments and reviews. | +| `hive_github_notification_suppressed_repeats_total` | `producer`, `class` | Notes the hive actually did not post (folded or already present). | +| `hive_github_notification_would_suppress_repeats_total` | `producer`, `class` | Writes shadow mode *would* suppress. | +| `hive_github_notification_delivery_failures_total` | `producer`, `class` | Failed writes. | +| `hive_github_notification_active_items` | — | Items with a notification-capable write in the last 24 hours. | + +All counts are API writes, a proxy for notifications — never "emails +delivered". Counters are cumulative since process start. + +### Comparing baseline windows + +Compare **per active item**, over **matched windows**: the same length (a +whole week, so weekday traffic is matched), similar open-item load, and no +change to `github.notifications.mode` or the hive version inside either +window. For each window compute + +```text +writes = increase(hive_github_notification_comments_created_total[7d]) + + increase(hive_github_notification_reviews_submitted_total[7d]) + + increase(hive_github_notification_review_requests_total[7d]) +per_item = writes / avg_over_time(hive_github_notification_active_items[7d]) +repeat_rate = increase(hive_github_notification_would_suppress_repeats_total[7d]) + / avg_over_time(hive_github_notification_active_items[7d]) +``` + +broken down by `class` and `producer`. The baseline is a shadow-on window +before any suppression ships; the candidate is the same metrics after it. The +80% reduction in repeat/non-actionable writes per active item named in #16075 +is an **acceptance target**, not a measured or claimed result: shadow mode +only produces the baseline that target will be checked against. + +### Write-site inventory + +Every function under `src/pkg` and `src/cmd` that calls a notification-capable +write primitive (`CreateIssueComment`, `CreateIssueCommentBudgeted`, +`PostNoteOrFold`, `PostClaimNote`, `PullRequests.CreateReview`, +`RequestReviewers`) or records a suppressed note is listed here and in +`notificationWriteSites` (`src/pkg/github/notification_write_sites.go`). +`TestNotificationWriteSitesInventory` fails when a new call site is added +without a class. Review submissions and review requests are always counted as +`required_review`, whichever producer made them. + +- `status` — bookkeeping readable on demand; repeats may be would-suppress. +- `attention` — asks a person to look or act; repeats may be would-suppress. +- `required_review` — a review or review request a merge depends on; never would-suppress. +- `protocol_command` — machine-consumed (claim markers, `/lgtm`, `/approve`, `/ok-to-test`); never would-suppress. +- `security_event` — trust or integrity signal; never would-suppress. + +| Producer | Class | Notes | +|---|---|---| +| `dashboard.(*ContributeWSHub).markAlreadyDoneIssue` | `status` | | +| `dashboard.(*ContributeWSHub).releaseGateParkLabel` | `status` | | +| `dashboard.(*ContributeWSHub).releaseToolingBlockedLabel` | `status` | | +| `dashboard.(*Server).armRebaseThenMerge` | `status` | | +| `dashboard.(*Server).executeDelegatedDecision` | `status` | | +| `dashboard.(*Server).handlePullRequestMergeDecision` | `status` | | +| `dashboard.(*Server).handleRepoItemAdoptNow` | `status` | | +| `dashboard.(*Server).handleRepoItemBlockerClosePartial` | `status` | | +| `dashboard.(*Server).handleRepoItemDecision` | `status` | | +| `dashboard.(*Server).handleRepoItemSentinelConfirm` | `status` | | +| `dashboard.(*Server).handleRepoItemSHAWaiver` | `status` | | +| `dashboard.(*Server).handleReviewQueueSupersededClose` | `status` | | +| `dashboard.(*Server).mirrorPlanWith` | `status` | | +| `github.(*Client).CloseIssueForConfiguredLinePR` | `status` | | +| `github.(*Client).CreateIssueCommentBudgeted` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).PostFleetReportCleared` | `status` | | +| `github.(*Client).PostFleetReportRecovery` | `status` | | +| `github.(*Client).PostFleetReportRollup` | `status` | | +| `github.(*Client).PostNoteOrFold` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).SweepLegacyFleetReportIssues` | `status` | | +| `github.(*Client).UpsertIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller | +| `github.(*Client).EditIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller | +| `automerge.(*engineStatusForge).CreateComment` | `status` | passthrough wrapper shared by normal-mode stage notes and the quiet-mode status-comment forge under `prstatus.Write`; attributed to its caller | +| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (status-comment forge under `prstatus.Write`); attributed to its caller | +| `github.(*Client).PostIssueNote` | `status` | passthrough wrapper (issue status card, `attention_pilot`); attributed to its caller | +| `github.(*Client).PostInformationalIssueNote` | `status` | passthrough wrapper (issue status card in quiet mode or under `attention_pilot`, for notes nobody acts on); attributed to its caller | +| `github.(*Client).closeDecomposedParent` | `status` | | +| `github.(*Client).closeDoneTracker` | `status` | | +| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | | +| `github.(*Client).closeSupersededPRDecision` | `status` | | +| `github.(*Client).fileReviewBacklog` | `status` | | +| `github.(*Client).foldReviewFollowUps` | `status` | review Follow-ups checklist folded into the PR status card (quiet mode) | +| `github.(*Client).foldSentinelNotice` | `status` | informational sentinel notice folded into the PR status card (quiet mode); a blocking alert is never folded | +| `github.(*Client).upsertFleetReportSeenLog` | `status` | | +| `github.(*Client).markInProgressStarted` | `status` | | +| `github.(*Client).postUnblockedNote` | `status` | | +| `github.(*Client).priorArtGateClose` | `status` | | +| `github.(*Client).reconcileBlockedTargets` | `status` | | +| `github.(*Client).recordReviewEvidenceMerge` | `status` | | +| `github.SyncIssueStageLabelsWith` | `status` | | +| `github.ensureIssueStagePRLink` | `status` | | +| `github.githubIssueBacklogSink.AppendToItem` | `status` | | +| `github.githubIssueBacklogSink.CloseItem` | `status` | | +| `github.githubIssueBacklogSink.LiftBlock` | `status` | | +| `github.handleMergedPRIssueStage` | `status` | | +| `github.runRecheckSoak` | `status` | | +| `main.postReviewAcknowledgements` | `status` | | +| `main.reviewFeedbackSweep.acknowledgeRules` | `status` | | +| `main.rfcNotifySource.Comment` | `status` | | +| `main.unparkEscalatedPR` | `status` | | +| `dashboard.(*ContributeWSHub).parkWrongBase` | `attention` | | +| `dashboard.(*Server).handleRepoItemReroute` | `attention` | | +| `dashboard.(*Server).handleReviewPipelineSendToHuman` | `attention` | | +| `dashboard.(*Server).reroutePickupLapsed` | `attention` | | +| `dashboard.(*Server).settleRebaseMergeLedger` | `attention` | | +| `github.(*Client).PostIssueAttention` | `attention` | the one explicit announcement of a newly required action (`attention_pilot`) | +| `github.(*Client).NudgeTrackingIssueClosingRefs` | `attention` | | +| `github.(*Client).appendFoldedFinding` | `attention` | | +| `github.(*Client).bindProwLgtm` | `attention` | | +| `github.(*Client).commentOnHumanFiledTwin` | `attention` | | +| `github.(*Client).createIssue` | `attention` | | +| `github.(*Client).handleOneIssueRequestFrom` | `attention` | | +| `github.(*Client).parkClankerRequestedPR` | `attention` | | +| `github.(*Client).redirectToExistingPR` | `attention` | | +| `github.(*Client).relayNotAgentWorkNote` | `attention` | scanner not-agent-work verdict: posted once with its marker and parks the issue on `needs-human`; an identical repeat records a suppressed comment (#18675) | +| `github.(*Client).relayScannerNote` | `attention` | scanner PR note: an unchanged or edited note records a suppressed comment (#18451) | +| `github.(*Client).remindAttention` | `attention` | attention-pilot reminder: at most one per unresolved episode per `reminder_interval`; write-back gate consulted first | +| `github.(*Client).resolveDuplicateFixGroup` | `attention` | | +| `github.(*Client).upsertScannerNote` | `attention` | one scanner note per PR; a new comment only for the first note or when the author must act on a new head (#18451) | +| `github.attentionDelivery.Post` | `attention` | condition-episode page; live write-back policy rechecked before the write | +| `main.(*repoForgeRouter).CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller | +| `main.claimEscalationLookup` | `attention` | | +| `main.factCheckSweep.needsHuman` | `attention` | one note per PR when the analysis fact-check loop stops without a passing verdict (#19074) | +| `main.liveTriageCommenter.CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller | +| `main.maintainHeldPRMergeability` | `attention` | | +| `main.rfcCoverageForge.CreateComment` | `attention` | | +| `main.runEscalationSweep` | `attention` | | +| `main.reviewFeedbackSweep.checkRuleReply` | `attention` | | +| `main.reviewFeedbackSweep.needsHuman` | `attention` | | +| `main.reviewFeedbackSweep.proposeRuleHome` | `attention` | | +| `prfollowup.postStaleHeadPushNotes` | `attention` | | +| `scheduler.(*Scheduler).judgePriorArt` | `attention` | | +| `scheduler.(*Scheduler).parkUnclearIssue` | `attention` | | +| `scheduler.(*Scheduler).postTriageClarifyComment` | `attention` | | +| `github.(*Client).QueuePRAutoMergeWithNoteResultAtHead` | `required_review` | | +| `github.(*Client).RequestReviewers` | `required_review` | passthrough wrapper; attributed to its caller | +| `github.(*Client).handleOneReviewRequest` | `required_review` | | +| `dashboard.postClaimComment` | `protocol_command` | | +| `github.(*Client).PostClaimNote` | `protocol_command` | | +| `github.(*Client).reportOperatorPullRequestApproval` | `protocol_command` | | +| `main.githubClaimHooks` | `protocol_command` | | +| `github.(*Client).handleOnePRRequest` | `security_event` | | +| `github.(*Client).markReporterTrustAwaiting` | `security_event` | | +| `github.(*Client).reconcileReporterTrustSignal` | `security_event` | | +| `main.enforceHoldGuard` | `security_event` | | + +Hive-maintained GitHub Actions workflows that comment (not instrumented by the +Go client; listed for completeness): + +| Workflow | Class | What it posts | +|---|---|---| +| `changelog-fragment-guard.yml`, `changelog-reminder.yml`, `docs-index-reminder.yml` | `status` | PR reminders about changelog fragments and the docs index. | +| `issue-closed-reopen-hint.yml`, `issue-reopen-command.yml` | `status` | Reopen hint on closed issues; reply to a reopen command. | +| `backend-smoke.yml`, `ci-runner-canary.yml`, `coverage-hourly.yml`, `dco-post-merge.yml`, `flue-smoke.yml`, `omp-smoke.yml`, `wavefront-smoke.yml`, `v2-ci.yml`, `v2-tests.yml` | `attention` | "Still failing" comments on an open failure-tracking issue. | +| `promote-stable.yml` | `attention` | Emergency stable-promotion exception note. | +| `weekly-competitor-report.md` (`.lock.yml`) | `status` | Weekly report comment on the tracking issue. | +| `hive-ok-to-test.yml` | `protocol_command` | The `/ok-to-test` command that releases held workflow runs. | + +## Attention pilot and the issue status card (`github.notifications.attention_pilot`) + +The attention pilot is the opt-in gate for the attention changes in +[#16270](https://github.com/hivecommons/hive/issues/16270); every +attention-pilot behaviour reads this one flag. It is **off by default**, and +with it off the hive behaves exactly as before. + +```yaml +github: + notifications: + attention_pilot: true # default false +``` + +Quiet mode (`github.notifications.mode: quiet`) folds the hive's PR +bookkeeping into one edited `hive:status` comment (including the auto-merge +note, under the `auto-merge` section: in `normal` mode it stays its own +comment, and a merge blocked on a person still gets its 085 / 090 entry +comment, hivecommons/hive#18452; the review Follow-ups checklist, under +`review-followups`, and a trust-only 090 entry, under `stage-ready`, while a +held or manual-merge 090 and every 085 stay comments, hivecommons/hive#18606) +but leaves issue notes (except the informational `issue-pr-link` stage note) +as +comments of their own, so one issue lifecycle (partial merge, remainder, +close) could still email its watchers several times. With the pilot on, the +issue gets the same card, written through the same single status writer +(`prstatus.Write`, serialised per item, duplicates merged into the oldest): + +- **Folded into the card** (section key in brackets): partial work left by a + non-closing merged PR (`issue-partial:<pr>`), close/auto-close narration — + "Fixed by #N … Reply /reopen if the problem persists" and the decomposed + parent's all-children-delivered close — (`issue-close`), + reopened-after-merge (`issue-reopened`), a lapsed claim's stage regression + (`stage-regressed`), the covering-PR stage note (`issue-pr-link`), the + relay's one-line state notes — awaiting CI, parking, already fixed — + (`agent-note:<state>`), an agent's free-text relay comment whose only + marker is the identity footer's `<!-- hive:origin … -->` + (`agent-note:origin`, latest note; outside quiet mode these append to the + one `<!-- hive:origin-notes -->` comment per item instead, last 10 kept — + hivecommons/hive#17067), the decision-downgrade note left when a label + change walks back an earlier maintainer decision + (`issue-decision-downgrade`) and the blocker-settled note (`unblocked`, + whatever `mode` says). Claim notes and the relay state notes already fold + under `claim` and `agent-note:<state>` in quiet mode; the + decision-downgrade note folds under the pilot only. The legacy markers + stay inside each section, so every reader that greps for them still finds + them, and the reopen/release guidance stays visible on the card. Section + text that quotes issue-authored prose has the card's own + `<!-- hive:status… -->` markers neutralised, so it cannot close its + section or open another. +- **Native events notify instead.** The issue is still closed (with its + state reason) by the API call, which is GitHub's own notification; the + hive no longer adds a "for visibility" comment beside it. +- **A newly required action is still announced once.** Editing a comment + notifies nobody, so an action asked of a person (today: confirming a + merged fix with `/fixed` or `/reopen`) is recorded on the card under + `attention:<cause>` *and* announced by exactly one notifying write — + creating the card when the issue has none, otherwise one explicit + comment tagged `<!-- hive:attention cause=<cause> -->`. A later pass that + sees the tag only refreshes the card; a new cause gets its own single + announcement. The explicit comment consults the write-back gate like + every other unsolicited comment; a refusal is returned to the caller as + `writeback.ErrSuppressed` before anything is written (no comment, no tag + on the card), so the action is not reported as announced and the next + pass retries once the policy admits it. +- **Not folded:** the blocked sweep's re-target note (`<!-- hive:blocked-on … -->`) + stays a comment, because the sweep reads the *newest* blocked-on marker + by comment order and a section in an older card would not be newest. + +Acknowledge/snooze commands, reminders and the per-repo attention queue are +separate pilot steps ([#16359](https://github.com/hivecommons/hive/issues/16359), +[#16361](https://github.com/hivecommons/hive/issues/16361)–[#16363](https://github.com/hivecommons/hive/issues/16363)) +and are not part of this flag's first behaviour. + +### Attention section, tracking issue and reminders + +The reminder policy ([#16361](https://github.com/hivecommons/hive/issues/16361)) +and the GitHub-native action queue ([#16362](https://github.com/hivecommons/hive/issues/16362)) +now run under the same flag, on repositories whose `github.attention.admitter` +is this hive. The un-park sweep (every 5 minutes) makes one pass per +repository after it has recorded that pass's `/hive ack` and `/hive snooze`: + +- **Attention section.** Each item's `hive:status` card carries an + **Attention** section (key `attention`): one line per unresolved episode + naming the action, who owes it, since when, any snooze deadline and how + many reminders were sent. It is written by the single status writer and + edited in place. +- **Per-repo tracking issue.** One issue titled `[governor] Hive attention + queue` (label `origin/governor`, body tag `<!-- hive:attention-queue -->`) + lists every open episode in the repository. It is created once, when the + first episode is open — its only notifying write — and afterwards edited in + place only when the list changes; item numbers are code spans and logins + are neutralised, so an edit never mentions or cross-references anyone. A + queue issue a person closed is left alone; reopen it to resume updates. +- **Closure.** When an item with open episodes is closed, its episodes are + resolved, its Attention section is removed from the card and it drops out + of the tracking issue, so no stale ask or reminder outlives it. +- **Reminders.** At most one reminder comment per unresolved episode per + `github.attention.reminder_interval` (default `24h`), counted from the page, + the previous reminder or the recipient's last action, whichever is latest. + None while the episode is acknowledged or snoozed, none for a never-paged + or uncertain episode, and none when the recipient has commented, reviewed + or changed a label on the item since the last ping. A reminder consults + the write-back gate like any unsolicited comment, goes through + `CreateIssueComment` (so shadow mode counts it under + `github.(*Client).remindAttention`) and refreshes the card. Hive never + removes and re-adds a reviewer or requests a review to manufacture a + reminder, so a request GitHub, CODEOWNERS or Prow already owns is never + duplicated. + +```yaml +github: + attention: + reminder_interval: 24h # default 24h +``` + +### Sentinel notices in the PR status card + +The sentinel (`pkg/github/sentinel_sweep.go`) has two kinds of result, and +only one of them asks a person to do anything +(hivecommons/hive#18453): + +- **Actionable: a hold.** The author is untrusted, or + `sentinel.trusted_authors_block` is `true`. The hive adds the + `sentinel-alert` label and posts its `<!-- hive-sentinel --> <head>` + "Sentinel alert - maintainer review required" comment. This happens in + **every** mode, quiet included, because only a new comment notifies. + A security hold is never folded into the card. +- **Informational.** The author is trusted and the merge is not blocked. In + `github.notifications.mode: quiet` (the default) this is the `sentinel` + section of the PR's `hive:status` card, edited in place. A new head + rewrites that section, so the PR gets no notice comment at all. The card + is created only when the PR has none yet. The section is stamped + `<!-- hive-sentinel-notice <head> -->`. It never carries the + `<!-- hive-sentinel -->` marker, because the sweep reads that marker back + to tell which head it alerted on and whether a maintainer cleared it. When + the same PR is later put on hold, the hive posts the alert comment and + drops the stale informational section from the card. A PR that already + has a sentinel comment from before this change keeps it, rewritten in + place for the new head. + +In `normal` mode the informational notice is still its own comment, as +before. Either way the finding is recorded for audit, the dashboard +Security tab and `/api/sentinel`. + +### Hive-maintained Actions workflows that defer to the card + +Some comments come from GitHub Actions workflows in this repository rather +than from the runtime. When one of them says what a `hive:status` card +section already says, it now defers (the check is +`.github/scripts/hive-status-card.sh has <repo> <number> <section>`, which +looks for `<!-- hive:status:section=<key> -->` inside the comment carrying +`<!-- hive:status -->`, considering only comments by a Bot account so a +human quoting the card's invisible markers cannot suppress a workflow; a +caller that has already fetched the comments passes them via +`HIVE_COMMENTS_FILE` instead of re-fetching). The companion +`hive-status-card.sh upsert <repo> <number> <marker> <body-file>` edits the +workflow's own earlier comment carrying `<marker>` in place, or creates it; +it only edits comments authored by `HIVE_COMMENT_AUTHOR` (default +`github-actions[bot]`, the identity `${{ github.token }}` posts as), never a +third party's comment that happens to contain the marker: + +| Workflow / script | Comment it posts | Behaviour | +| --- | --- | --- | +| Refs sweep (`.github/workflows/refs-sweep.yml`, `src/scripts/comment-merged-refs.sh`) | "PR #N has merged and referenced this issue with a non-closing `Refs`" (`<!-- hive-post-merge-refs-sweep: issue=N -->`) | **Skips** when the card carries `issue-partial:<pr>` for that PR; otherwise unchanged (still once per issue). | +| Issue Closed Hint (`.github/workflows/issue-closed-reopen-hint.yml`) | "@reporter this issue was closed by … comment `/reopen`" | **Pending** (tracked in #16363; the workflow edit must be landed by a maintainer). Once applied: **skips** when the card carries `issue-close`, which already says "Reply /reopen"; otherwise **edits** its earlier comment (`<!-- issue-closed-reopen-hint -->`) instead of adding one per closure. Until then it posts a new comment on every closure as before. **Skips** when the reporter is a bot or a maintainer (`author_association` OWNER / MEMBER / COLLABORATOR), who can reopen the issue themselves (#18607). | + +Editing a comment notifies nobody, so a workflow comment that is edited in +place stops re-mentioning the reporter on every close/reopen cycle. Both +paths apply only where a card exists; with +`github.notifications.attention_pilot` off there is no issue card, and the +workflows behave as before. + +A failure to read the card is not treated as "no card": when the comments +API call fails or its response is not a JSON list of comment objects, +`hive-status-card.sh` writes a `hive-status-card: error:` line and exits 3 +(`has` otherwise exits 0 for present, 1 for absent), and `upsert` writes +nothing. The refs sweep then skips that issue with an `::error::` annotation +and exits non-zero instead of posting a possible duplicate. +`.github/scripts/test-hive-status-card.sh` and +`src/scripts/test-comment-merged-refs.sh` pin this behaviour. + +### Scanner note: one comment per PR + +The scanner's CI-triage and rebase notes on a PR used to be a new comment on +every pass: PR #18254 got 17 near-identical triage comments on the same head +in nine hours ([#18450](https://github.com/hivecommons/hive/issues/18450)). +The comment relay (`hive-open-issue comment`, which every `gh pr comment` +from an agent goes through) now keeps one scanner note per PR, marked +`<!-- hive:scanner-note head=<sha> checks=<fingerprint> told=<sha> -->` +([#18451](https://github.com/hivecommons/hive/issues/18451)): + +| Situation | Write | +| --- | --- | +| First scanner note on the PR | **Posts** a new comment carrying the marker. | +| Same head SHA and same failing-check set as the current note | **Nothing.** The request completes with `already_existed`, and the relay logs `scanner note: unchanged head and failing checks, not re-posting`. | +| New head, or a different failing set, on a hive-authored PR | **Edits** the note in place. Edits do not notify. | +| The PR author must act (a non-hive author, something red) and has not been told for this head | **Posts** a new comment. It becomes the current note, and the old note loses its marker. Later changes on that head are edits. | + +The failing set is the head's red gating checks (as in the `recommend/*` +digest), plus `DCO` when the DCO context failed and `merge-conflict` when the +PR's mergeable state is dirty, so a rebase note is keyed the same way. When +the head's checks cannot be read, the note is never dropped; it is edited. +A note on an issue rather than a PR, from another lane, or carrying a +dedicated marker (a shared-CI incident reference `<!-- hive-shared-ci-<n> -->`, +a verification marker, any other `<!-- hive:… -->` marker) keeps its +usual path. In quiet mode or under the attention pilot, the relay's one-line +state notes (awaiting CI, parking) still fold into the status card first. + +The rule lives in the relay, not only in the scanner policy, because a +prompt-only rule drifts. Set `HIVE_SCANNER_NOTE_UPSERT=off` (or `0`, +`false`, `no`) on the hive to turn it off. It is on by default. +`src/pkg/github/scanner_note_test.go` pins this behaviour. + +### Per-PR workflow comments post only on a finding + +Three workflow comments used to land on every PR regardless of outcome, and +after the runtime's own reducers they were ~70% of the comments on a merged +PR ([#17863](https://github.com/hivecommons/hive/issues/17863)). Each now +posts only when it has something to say; the full report, including the +clean case, still goes to the job's step summary: + +| Workflow / script | Comment | Behaviour | +| --- | --- | --- | +| Open PR Overlap (`.github/workflows/pr-overlap.yml`, `.github/scripts/pr-overlap.sh`) | `<!-- hive-pr-overlap -->` table of conflicting / same-file open PRs | **Posts** only when at least one sibling PR conflicts or shares a file; **edits** the one marker comment in place on later pushes; when a later run finds nothing and a comment exists, **edits it** to a one-line "✅ Resolved" note; a PR that never had an overlap gets no comment. The `conflicts-with-open-pr` label is unchanged. | +| Mutation (advisory) (`.github/workflows/mutation-advisory.yml`, `src/scripts/mutation-report.sh post`) | `<!-- hive-mutation -->` surviving / uncovered mutant report | **Posts** only for a finding verdict (`lived`, `uncovered`, `misrouted`); an `error` verdict (gremlins wrote no report, so nothing for the author to act on) goes to the job summary and the failing verdict step only and never creates a comment (#18607); **edits** the one marker comment on later pushes (an `error` run edits an earlier finding comment so it is not stale); a later `pass` **edits** the existing comment to a one-line "✅ Resolved" note; a PR whose every run passes or errors gets no comment. | +| Feedback Wanted (`.github/workflows/feedback.yml` → `hivecommons/infra` `reusable-feedback.yml`, gated by `src/scripts/feedback-gate.sh`) | "Thank you for your contribution! Your PR has been merged." | **Posts** only for a person's first merged PR in the repo. Skipped for `[bot]` / App authors, hive-managed head branches (`scanner/*`, `hive/*`), PR bodies carrying a `<!-- hive:` marker (hive-agent PRs on any branch, e.g. `fix-*`), and any author with another merged PR. Knobs are the workflow's `env:` (`FEEDBACK_SKIP_BOTS`, `FEEDBACK_SKIP_BRANCHES`, `FEEDBACK_SKIP_HIVE_ORIGIN`, `FEEDBACK_SKIP_LOGINS`, `FEEDBACK_FIRST_TIME_ONLY`); a failed merged-PR lookup skips the comment rather than guessing. | + +`.github/scripts/test-pr-overlap.sh`, `src/scripts/test-mutation-report.sh` +and `src/scripts/test-feedback-gate.sh` pin these rules. + +**Outside Hive's control.** Comments from external bots, such as Prow, tide +and hivecommons-prow, are posted by their own services and cannot be edited, +folded or skipped from this repository. Hive does not try to suppress them; +configure those bots in the project that runs them. For hivecommons repos +that configuration is `prow/plugins.yaml` and `prow/config.yaml` in +`hivecommons/infra` (org-wide `approve` with `require_self_approval: true` +and `lgtm` with `review_acts_as_lgtm: true`; tide requires both `lgtm` and +`approved`). What Hive does control is its own relay: a dashboard approval +on a Prow-managed PR the hive account opened posts `/approve` only, because +a `/lgtm` from the PR's own author draws Prow's "you cannot LGTM your own +PR" every time (`PullRequestApprovalEvent.LGTMSkipped`, #17863); no hive +lane reads the relayed `/lgtm`. diff --git a/docs/content/hive/retro-lane.md b/docs/content/hive/retro-lane.md new file mode 100644 index 0000000..4a6e71c --- /dev/null +++ b/docs/content/hive/retro-lane.md @@ -0,0 +1,140 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md) during the docs build. Edit the canonical source in the Hive repository. + +# Retro lane + +The retro lane is a post-completion analysis pass for Hive work. It is disabled by default (`retro.enabled: false`) so existing hives see no behavior change unless operators opt in. LLM analysis is separately opt-in with `retro.analysis_model`; the empty default preserves phase-1 deterministic-only behavior. + +When enabled, the lane runs from the governor tick on its own scan interval. It scans done/closed beads that have a closed or merged PR association in bead metadata or the lifecycle timeline, reconstructs a compact `RetroRecord`, and applies rule-based pattern detection. It does not post to GitHub. + +## Reconstructed record + +For each eligible bead the lane combines local ledgers: + +- bead metadata: issue/bead identity, PR reference/state, claim/close times, explicit counters when present; +- lifecycle timeline: kicks, PR-open/merge events, and trajectory drift/pause markers; +- escalation ledger when still available: failed fix-attempt count for the PR. + +The compact record tracks bead metadata, issue/PR refs, kicks received, CI failures/fix attempts, drift pauses, and wall-clock time from claim to close. +It also carries advisory autonomy outcome signals when producers record them: +plan revisions before approval, PR rework commits after review, rollback +events, and the affected user/repo/change-class scope. These signals are facts +for retro analysis only; they do not change ACMM configuration. + +## Knowledge-advisor arm + +Each record also carries the knowledge advisor's arm for the bead's kicks +(`knowledge.advisor_llm`, see [agent-knowledge-and-memory.md](/docs/hive/agent-knowledge-and-memory)), +built from the advisor's decision records and joined by the issue ref: + +- `AdvisorArm`: `none` (no decisions), `shadow` (shadow mode, delivery unchanged), + `deliver` (rank mode, advice delivered), `holdout` (every kick was held out: + the model ranked but nothing was typed), or `mixed` (kicks in more than one arm). +- `AdvisorDecisions`, `AdvisorDelivered`, `AdvisorHeldOut`, `AdvisorRateLimited`: counters over + those decisions. A `rate-limited` decision (the model endpoint answered 429) is counted but + assigns no arm, so a throttled hour does not move a bead into `deliver`. + +Only these counters reach the analysis model; the advisor's reasons and pane text never do. + +The decision records live in the knowledge-advisor decision store, +`/data/knowledge-advisor-decisions.jsonl` (`retro.AdvisorDecisionStore`): one JSON line per +ranking decision with the agent, kick id, the kick's primed issue/PR refs, mode, arm, outcome and +slug (plus the model call's latency and token counts when one was made), rotated with lumberjack like prompt history, at 5 MiB, 3 gzipped backups, 90 days. The retro lane reads it in +production; without the PVC it is in-memory only. + +To read the comparison, call `Lane.AdvisorArmSummary()`: per arm it gives the bead +count and the mean `FixAttempts`, `CIFailureCount` and `KicksReceived`, with no model +call (it works with `retro.analysis_model` empty). Compare `deliver` against `holdout`: +both arms share the same selection, so a lower mean in `deliver` is the signal that +delivered advice helped. Treat small bead counts as noise, and ignore `mixed` and `none` +for the verdict. + +### Reading the comparison from the dashboard + +`GET /api/knowledge/advisor/summary` (read role or higher; optional `?since=<RFC3339>`) +returns the same comparison without an exec, and the Knowledge section shows it as the +**Advisor** card. The response carries: + +- `window`: the first and last decision timestamps, the first `rank` decision + (`rank_mode_start`) and the decision count. +- `settings`: the advisor settings read-only (`enabled`, `mode`, `model`, `holdout_percent`, + the call budget, `candidates`, `on_error`). The endpoint and API key are never returned. +- `counts`: decisions by mode, arm (`shadow`, `deliver`, `holdout`) and outcome. +- `arms`: the `Lane.AdvisorArmSummary()` rows for `shadow`, `deliver` and `holdout`, with + `mixed` and `none` listed separately under their own keys. These cover every closed bead + with a closed PR; `since` does not narrow them. +- `cost`: mean model latency and mean prompt and completion tokens, over the records that + carry them (decisions made before these fields existed, or that never reached the model, + have none; the sample counts are returned). +- `small_n` and `caveat`: true, with a one-line caveat, while either `deliver` or `holdout` + has fewer than 30 closed beads. + +Only counts and means are returned: never a slug, ref, agent, kick id or any entry content. + +## Deterministic findings + +Named threshold defaults are: + +- excessive fix attempts: `>= 3`; +- excessive kicks before completion: `>= 5`; +- long stall: claim-to-close `> 7 days`; +- drift pause occurred: any trajectory drift/pause marker. +- plan accepted first pass: a recorded approval outcome with `0` plan + revisions before approval; +- PR merged with no rework: a merged PR outcome with `0` review-driven rework + commits; +- run rolled back: one or more rollback events. + +Each finding is filed as an `advisory` bead attributed to actor `retro`, using the existing advisory-bead digest path. Source beads are marked with `retro_analyzed_at` after analysis to avoid duplicate findings. +Autonomy signal findings include scope metadata (`autonomy_scope_type`, +`autonomy_scope_value`, `autonomy_level`, and `autonomy_direction`) so the +dashboard can show them as ACMM overlay facts with no action button. A lack of +qualifying signals is terminal and acceptable; no nudge is shown. Automatic +promotion or demotion, including demotion-on-failure and per-repo scoping, is +deferred until the per-repo ceiling design settles. + +## Optional LLM analysis + +### Prerequisites: configure `governor.litellm` first + +`retro.analysis_model` names a model that must be served by the hive's LiteLLM +gateway (`governor.litellm`). Configure the gateway before setting this field: + +1. Set the endpoint and API key — either via environment variables + (`HIVE_LITELLM_ENDPOINT`, `HIVE_LITELLM_API_KEY`, documented in + [env-vars.md](/docs/hive/env-vars)) or via the dashboard API + (`PUT /api/config/governor/litellm`, see [api-reference.md](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md)). +2. Verify connectivity with `POST /api/config/governor/litellm/test`. +3. Set `retro.analysis_model` to any model name the gateway exposes, for example + `gpt-4o-mini` or the default model configured in the gateway itself. + +```yaml +retro: + enabled: true + analysis_model: gpt-4o-mini # a model your governor.litellm serves +``` + +If `governor.litellm` is not configured, the retro lane silently skips model +calls and files only deterministic findings — no error, no alert. + +### Analysis behavior + +Set `retro.analysis_model` to a model served by `governor.litellm` to enable bounded model analysis. The lane only calls the model for records that already triggered deterministic findings, keeping cost proportional to actionable anomalies. The prompt contains the compact record and finding types/details with hard truncation bounds. + +The model must return structured JSON: + +- `root_cause_hypothesis` +- `process_improvement` +- `generalizable` +- `generalizable_lesson` + +Invalid JSON is retried up to the shared structured-output retry bound. Transport, timeout, or validation failures fail open: deterministic advisory beads are still filed without model enrichment. + +Successful analyses are cached in a bounded in-memory LRU keyed by a hash of the deterministic finding set (pattern, severity, detail) and the analysis model, so an identical finding set is not re-sent to the model. An **empty** finding set is the only condition under which the model is skipped outright; any non-empty set either hits the cache or reaches the model. Cache hits are logged as `retro: analysis skipped reason=cached`; `Analyzer.CacheStats()` exposes hit/miss/skipped-empty counters. + +When analysis succeeds, advisory bead notes include a clearly marked “Model-generated retro analysis” section with the root-cause hypothesis and actionable process improvement. + +## Knowledge graph feeding + +If the model marks a lesson generalizable, Hive quality-gates it before ingestion: length bounds are enforced and secret-like token patterns are rejected with the shared log-scrub detector. Accepted lessons are stored as `pattern` facts tagged `retro` and `lesson`, attributed to source `retro` with the source bead and PR reference. Existing knowledge search/vault deduplication is checked first; when no matching fact exists, the normalized lesson hash keys the fact slug to avoid duplicates. + +If a graph store is attached (`/data/graph/knowledge.db`), the fact gets a `derived_from` edge to the retro source reference. The fact is then available to the primer like other knowledge entries. diff --git a/docs/content/hive/review-bot-threads.md b/docs/content/hive/review-bot-threads.md new file mode 100644 index 0000000..fa421b6 --- /dev/null +++ b/docs/content/hive/review-bot-threads.md @@ -0,0 +1,266 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/review-bot-threads.md) during the docs build. Edit the canonical source in the Hive repository. + +# Review-bot threads on hive-mediated PRs + +When a hive agent opens a PR on a repository that has an external review bot +installed — Copilot code review, `chatgpt-codex-connector[bot]`, CodeRabbit — +the bot reviews it a few minutes later and leaves inline threads. On a +repository with "require conversation resolution before merging" the PR cannot +merge until every thread is resolved. Before +[#7360](https://github.com/hivecommons/hive/issues/7360) nothing in the hive +noticed: the PR sat open until a human addressed the comments and resolved the +conversations by hand. + +The hive now reconciles those threads itself, for every PR it opened, with no +per-agent prompt rule. Three pieces, and one config key that turns them on. + +## Which PRs qualify + +A PR is the hive's to follow up on — *hive-mediated* — when **either** of two +things is true: + +- its **author is a hive login**: the App bot, or `project.ai_author` when + configured. These are the PRs the PR-request watcher opens; or +- its **body carries the `-- hive:` attribution trailer** + (`github.HasAttributionTrailer`). These are the PRs a hive agent opened on a + *person's* credentials — a contributor relay, or an operator running agents + under their own GitHub auth. GitHub shows the person as the author, so the + login rule alone can never recognise them. + +The second rule exists because of +[#7638](https://github.com/hivecommons/hive/issues/7638): the reconciler +originally keyed on the author login only, and every relay-run PR was dropped +before its threads were even fetched. Those are precisely the PRs external +review bots review — Codex skips bot-authored PRs — so the only PRs getting +Codex threads were the ones the hive could not follow up on. The trailer is +the same rule the task-list sweep already uses to decide an issue is the +hive's to close. + +Do **not** fix this by setting `project.ai_author` to the operator's own +login: that would make every PR they write by hand "hive-authored" too, and +agents would be told to fix and resolve review threads on the operator's own +work. `ai_author` is for a dedicated bot login. + +A relay-run PR's trailer usually has no `agent=` (the relay does not know a +hive-side agent name), and there is no App-bot audit entry for a PR the hive +did not open itself, so it is listed with an empty `agent` and reaches the +**scanner**, exactly as any other unattributed PR does. + +**On spoofing.** The trailer is a line of text; anyone can paste `-- hive:` +into a hand-written PR and have the hive answer that PR's review-bot threads. +This is accepted, as it was for the task-list sweep closing issues, because +the consequence is bounded: the hive will only ever reply in and resolve +threads that a *configured review bot* opened on that PR — the watcher-side +guard (§3) still refuses a human's thread, and it keys on the thread's first +author, never on the PR's author — which is something the PR's own author +could already do by hand. Nothing about the trailer lets a PR merge, be +approved, or have its human conversations touched. + +## Configuration: `classification.review_bots` + +```yaml +classification: + review_bots: + logins: + - "chatgpt-codex-connector[bot]" + - "Copilot" + min_priority: P1 # optional: only P0/P1 plus unknown badges + max_attempts_per_thread: 1 # default 1 + resolve_after_fix: true # default true +``` + +The key lives in `hive-project.yaml` next to its sibling monitor's config +(`classification.copilot_check`), and the Go binary also accepts the identical +block in `hive.yaml`; when both name a login, `hive.yaml` wins. A +`hive.yaml` `min_priority` (the field the dashboard edits) also overrides the +project file's threshold on its own. It is the one +key the Go side reads from the project file +(`config.LoadProjectReviewBots`, path `HIVE_PROJECT_YAML` or +`/etc/hive/hive-project.yaml`). + +- **Absent, or empty `logins`: the feature is off.** The monitor writes an + empty `review-threads.json` and the watcher denies every thread request. +- `logins` are matched case-insensitively against the **first** comment's + author, ignoring surrounding whitespace and a trailing `[bot]` suffix. Both + REST/web (`chatgpt-codex-connector[bot]`) and GraphQL + (`chatgpt-codex-connector`) spellings match either configured form. Do not + list a human here: it would let agents resolve that person's threads. +- `max_attempts_per_thread` is how many times the hive replies in one thread + before leaving it for a human. The counter is the thread itself — replies + authored by the App bot — so there is no state file to drift. +- `resolve_after_fix: false` makes the agent reply but leave the thread open. +- `min_priority` optionally limits routing to `P0` through `P3` (P0 is most + urgent). `P1` includes P0/P1 and excludes P2/P3. When neither `hive.yaml` + nor `hive-project.yaml` sets it, `review.severity.block_at` supplies the + threshold (see [review-swarm.md](/docs/hive/operations/automation-and-review/review-swarm#blocking-line-reviewseverity-reviewbacklog)). + With no threshold anywhere, or an unrecognised value, every finding is + routed. Case and surrounding whitespace + in the threshold are ignored. + Only Codex's Markdown badge format, `![P0 Badge]` through `![P3 Badge]`, + is recognised today, using the first matching badge in the first comment. + Unknown formats (including unbadged Copilot/CodeRabbit findings) always + remain included. Filtered threads stay open for humans: they are omitted + from the FIX-BEFORE-NEW work list and are not auto-resolved. + Each PR in `review-threads.json` reports `excluded_by_priority`, counting + otherwise actionable threads excluded solely by this threshold (not + resolved, outdated, human-authored, or attempt-capped threads). The + reviewer's jq filter applies the same badge threshold, so it need not + answer the lower-priority threads in its review. + +The dashboard's **Settings → Features → Review Gate** card displays the +effective review-bot settings, including defaults (one attempt per thread and +resolve after fix enabled). The governor settings bundle at +`GET /api/config/governor` exposes them in `review_bots` — `logins`, +`min_priority` (`P0`–`P3`, or empty when every finding is routed), +`max_attempts_per_thread`, `resolve_after_fix`, and `enabled`; `load_error` +reports an unreadable or malformed project file rather than hiding it as an +unconfigured feature. Logins, attempts, and resolve-after-fix are read-only +there: logins stay config-file-only because adding one grants agents +thread-resolution rights. + +`min_priority` is editable from the same card (**Minimum bot-finding +priority**: All, P0, P1, P2, P3). The owner-only `PUT /api/config/review` +accepts it as `{"review_bots": {"min_priority": "P1"}}`; an absent key leaves +it untouched, an empty string clears the dashboard override, `all` routes +every finding, and any other value is rejected with 400. The value is written +to `hive.yaml`'s `classification.review_bots.min_priority` and overrides the +project file's threshold even when `hive.yaml` names no login — the project +file's logins are never copied into `hive.yaml`. The change applies to the +thread reconciler and the reviewer without a restart. + +`copilot_check` / `bin/copilot-comment-checker.sh` are untouched: they cover +*merged* PRs; this covers *open* ones. + +## 1. Monitor: `/var/run/hive-metrics/review-threads.json` + +The governor's eval tick (`writeReviewThreads`, throttled to once per five +minutes) runs `Client.CollectReviewThreads` over the enumerated actionable +PRs. It keeps only hive-mediated PRs (see [Which PRs qualify](#which-prs-qualify): +a hive login as author, or the `-- hive:` trailer in the body — the trailer +test is computed from the PR list payload at enumeration time, so it costs no +extra call), skips drafts and anything carrying a hold / `do-not-merge` / +exempt label (the same exclusions as every other kick input), and for each +remaining PR runs one GraphQL `pullRequest.reviewThreads` query. A thread is listed when it is +**unresolved**, **not outdated**, its **first comment is from a configured +bot**, and it has **fewer than `max_attempts_per_thread` replies from the +hive**. Threads a human opened never appear. + +```json +{ + "generated_at": "2026-09-17T12:00:00Z", + "enabled": true, + "total_threads": 1, + "prs": [ + { + "repo": "org/repo", + "number": 123, + "title": "fix: nil deref in x", + "head_ref": "hive/fix-123", + "agent": "scanner", + "threads": [ + {"thread_id": "PRRT_kwDO…", "path": "src/x.go", "line": 42, + "author": "chatgpt-codex-connector[bot]", "body": "x may be nil here", + "comment_id": 2211, "hive_replies": 0} + ] + } + ] +} +``` + +`agent` is the hive agent whose relay request opened the PR, resolved from the +audit trail exactly as `ci-failing.json` does; empty means unattributed and the +kick builder defaults it to `scanner` (a PR opened on a person's credentials +is always in this state — see [Which PRs qualify](#which-prs-qualify)). `escalated: true` marks a PR the +escalation sweep has handed to a human. A PR whose bot threads are all +resolved (or all at the attempt cap) is listed with an empty `threads` array, +so the file shows the reconciler has nothing left to do there rather than +silently dropping the PR. + +## 2. Kick injection: FIX-BEFORE-NEW + +`Scheduler.addReviewThreadFixFirst` is a sibling of the red-CI +`addRedPRFixFirst`, called at the same post-resolution seam so no kick +template can omit it. For a PR-capable agent it prepends a block listing that +agent's own non-escalated PRs with actionable threads — path, line, and a +bounded excerpt of each finding (`redPRFixMaxDetailed` PRs, +`redPRFixExcerptRunes` per excerpt) — and the instructions: check out +`head_ref`, address each thread, `git commit -s`, push to the same branch, then +for each thread reply in-thread with one line and (if `resolve_after_fix`) +resolve it. One pass per kick; a thread already answered is filtered out by +the monitor, and the agent is told to skip it if it still appears. + +## 3. Resolution through the review-request watcher + +`ReviewRequest` gained a `thread_id` field and a `resolve_thread` event: + +```bash +hive-review <number> --repo <owner/repo> --comment --thread <PRRT_id> --body "<one line>" +hive-review <number> --repo <owner/repo> --resolve-thread <PRRT_id> +``` + +A `comment` with `--thread` is an **in-thread reply** (GraphQL +`addPullRequestReviewThreadReply`), not a PR-level review; `--resolve-thread` +runs `resolveReviewThread`. Both execute with the App token, go through the +same per-agent authorizer and UID forge-resistance as every other review +request, are audited as `agent_pr_reviewed` with `state=thread_replied` / +`state=thread_resolved` and `thread=<id>`, and write the usual +`<name>.result.json`. + +**The guard is in the watcher, not the prompt.** Before acting it re-fetches +the thread by id and quarantines the request as `.denied` (reason in the +result file, nothing touched on the forge) when: + +| Condition | Reason recorded | +|---|---| +| `review_bots.logins` is empty | `classification.review_bots is not configured` | +| the id resolves to nothing this token can see | `thread … not found` | +| the thread is on a different PR than the request names | `thread … belongs to o/r#N, not the requested PR` | +| the thread's first comment is not from a configured bot | `… opened by <login>, which is not a configured review bot; human threads are never resolved by the hive` | +| the thread is already resolved | `thread … is already resolved` | +| (reply only) the hive already replied `max_attempts_per_thread` times | `… already has N hive replies (max_attempts_per_thread=N); leaving it for a human` | + +Malformed requests (`resolve_thread` without `thread_id`, `thread_id` on an +`approve`) are quarantined as `.bad` before authorization, like any other +shape error. A transient forge failure on the re-fetch or the mutation keeps +the request for the same exponential-backoff retry and give-up horizon as a +failed review. + +## 4. The hive reviewer answers bot findings on every PR it reviews + +The three pieces above act only on hive-mediated PRs. The review swarm reads +the same threads on **every** PR it reviews +([#9360](https://github.com/hivecommons/hive/issues/9360)): before that, a +reviewer could post "Confidence: 5/5 (safe)" minutes after Codex left a correct +P1 finding on the same commit, without mentioning it. + +When `review_bots.logins` names any bot, each review kick +(`buildReviewBotFindingsInstruction`, `pkg/review/prompts_instructions.go`) carries a +`gh api graphql` read of the PR's `reviewThreads`, filtered to unresolved +threads whose first comment is from a configured bot. Logins are compared +lower-cased with the `[bot]` suffix removed, because GraphQL reports an App's +login without it. The reviewer must then: + +- answer every returned thread in its review: **agree**, **disagree** (reason + plus the refuting `file:line`), or **cannot verify**; +- verify each finding against the code at head and classify it with + `review_scope`, like one of its own; +- treat a confirmed, in-scope, severe finding (the bot's P0/P1) as a blocker: + the owning perspective may not approve, and the review may not call the PR + clean or safe. A refuted or out-of-scope finding is still answered but does + not lower the verdict. + +The reviewer stays comment-only. It never replies in, reacts to, or resolves +a bot thread; that remains the reconciler's job on hive-mediated PRs. With no +logins configured, the kick has no bot section. + +## What a human sees + +- A PR with two bot threads gets, within one kick, a push, two in-thread + replies from the App bot saying what changed, and two resolved threads. +- If the bot comments again on the fix, the new thread appears once, gets one + more attempt, and then stops: an open bot thread with one hive reply + explaining what it tried. +- A human's thread on the same PR is never listed, never replied to by this + path, and never resolved — including on a PR whose *author* is a human + because a hive agent opened it on their credentials: the guard looks at who + opened the thread, not who opened the PR. diff --git a/docs/content/hive/review-evidence.md b/docs/content/hive/review-evidence.md new file mode 100644 index 0000000..c30384d --- /dev/null +++ b/docs/content/hive/review-evidence.md @@ -0,0 +1,510 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/review-evidence.md) during the docs build. Edit the canonical source in the Hive repository. + +# Review evidence bundle + +A **review evidence bundle** is one self-contained JSON document per pull request head commit. It records what Hive reviewed, under which policy, what the reviewers found, what CI reported, who acted on the PR, and how it was merged. A bundle is **evidence, not certification**: it lets your own control owners decide whether Hive's automated review satisfies your change-management policy. See [SOC 2 control mapping](https://github.com/hivecommons/hive/blob/v5/src/docs/soc2-control-mapping.md) for how to use it, and [general technical review](https://github.com/hivecommons/hive/blob/v5/src/docs/general-technical-review.md) for what Hive does and does not claim. + +> **Status.** Live review fields are populated today (prospective `control_window` assignment is not yet enabled; see [Control arm](https://github.com/hivecommons/hive/blob/v5/src/docs/evidence.md#control-arm)): the review relay writes bundles (verdicts, posted reviews and the policy snapshot), the sentinel sweep adds its findings, and every merge path adds the CI check-run summary, human actions and the merge event and posts the evidence pointer comment (see [Where it lives](#where-it-lives-and-retention)). Bundles are hashed, optionally signed (`pkg/evidence`), and can be read through `GET /api/review/evidence`, the dashboard Evidence action and `hivectl review evidence` (see [Downloading](#downloading)). Tracked in [epic #11058](https://github.com/hivecommons/hive/issues/11058). + +## What a bundle is + +- One bundle per `owner/repo#number@headSHA` (its `id`). +- Append-only per head SHA. A new push does not edit the existing bundle: it starts a **new** bundle for the new head whose `previous_bundle_id` points at the old one, so the chain of heads for a PR stays traceable. +- Carries a content `hash` and, when a signing key is configured, a detached Ed25519 `signature`, so it can be checked offline. + +## Schema v1 + +The machine-readable schema is [`pkg/evidence/schema/v1.json`](https://github.com/hivecommons/hive/blob/v5/src/pkg/evidence/schema/v1.json); the Go types live in `pkg/evidence`. Timestamps are RFC 3339. + +### Top level + +| Field | Meaning | +|---|---| +| `schema_version` | Always `v1` for this schema. | +| `id` | `owner/repo#number@headSHA`. | +| `repo`, `number` | The repository (`owner/name`) and PR number. | +| `author` | `login` and `kind` (`human`, `agent` or `bot`). An `agent` author also carries `agent`, `backend` and `model`: the launch metadata the hive recorded when that agent opened the PR (the same values as the PR's attribution trailer); a field the hive did not know is omitted ([#12065](https://github.com/hivecommons/hive/issues/12065)). | +| `base_sha`, `head_sha` | The commits the PR compares. The bundle is about `head_sha`. | +| `previous_bundle_id` | The bundle for the previous head of this PR, if any. | +| `policy` | Snapshot of the policy in force (below). | +| `verdicts` | Every reviewer verdict (below). | +| `posted_reviews` | Reviews Hive posted on the PR: `url`, `head`, `at`. | +| `ci` | CI for the head: `status` (the merge gate's verdict, `success`, `failure` or `pending`; absent on bundles written before it was captured), `checks[]` (`name`, `conclusion`, `url`) and `captured_at`. | +| `sentinel` | Why the sentinel sweep flagged the PR, if it did: `rule`, `summary`, `paths`. | +| `human_actions` | Approvals, label changes, hold lifts: `actor`, `kind`, `detail`, `at`. | +| `merge` | Present once merged: `actor`, `method`, `at`, `sha`, and `opened_at` (when the PR was opened on GitHub, so `at` − `opened_at` is its time to merge; absent on bundles recorded before it was captured — such a merge is left out of time-to-merge, never counted as zero). Absent before merge. | +| `revert_of`, `followup_of` | Bundle ids of earlier merged PRs this PR reverts or follows up with a fix (see [Change-failure links](#change-failure-links)). | +| `reverted_by`, `followed_up_by` | Bundle ids of later PRs that reverted or followed up this one. | +| `issue_closures` | Confirmed closing-keyword issue closures captured at hive merge: issue `repo`, `issue`, closure `at`, and `clarity_gate` (marker present in the issue body or comments). Missing closure records mean unknown clarity status, not ungated. | +| `issue_reopens` | Issues this PR closed that a person reopened (legacy bundles capture only within 14 days of the merge): `issue`, `repo` (only when it differs from the PR's), `at`, `source` (`claim-ledger`). A change-failure signal for the Outcome card ([#13241](https://github.com/hivecommons/hive/issues/13241)). | +| `shadow` | Optional. What shadow-mode gates would have done, recorded only: `review_gate` (`would_have_held`, plus `lane` — `self-merge`, `trusted-bot` or `trusted-author` when the [self-merge review gate](/docs/hive/operations/automation-and-review/hive-merge#self-merge-review-gate) recorded it on that sweep lane, absent for the merge-eligible lane) and `intent` (`would_have_blocked`), each with `reason`, `tier`, `confidence` and `evaluated_at`. Absent unless a shadow gate ran; it never affects a merge ([#12103](https://github.com/hivecommons/hive/issues/12103)). | +| `control_window` | Optional prospective dispatch assignment at PR open time: `on` or `off`. Absent means unknown/unassigned, not `on`. Reporting foundation only; runtime collection is not yet enabled. See [Control arm](https://github.com/hivecommons/hive/blob/v5/src/docs/evidence.md#control-arm). | +| `backfilled`, `backfill` | Optional. Present only on bundles reconstructed from forge history by `hivectl evidence backfill` rather than recorded live: `backfilled: true` and a `backfill` block with `source`, `at`, `state` (`open`, `closed`, `merged`), `closed_at`, `author_kind_rule` and the pre-registration exclusion `flags` (`placeholder_hive`, `hive_on_hive`, `under_min_merged`). Such a bundle has no `verdicts`, `ci`, `sentinel` or `shadow`; see [Backfilled bundles](#backfilled-bundles) ([#12371](https://github.com/hivecommons/hive/issues/12371)). | +| `outcome` | Optional. What the forge said became of a PR this hive reviewed but did not merge, stamped by the governor's review-outcome ledger (see [Where outcomes come from](#where-outcomes-come-from)): `source` (`review-outcome-ledger`), `state` (`merged` or `closed`), `at`, and `merged_by` / `merged_at` or `closed_at`. A `merged` outcome comes with a `merge` block whose `actor` is the merger GitHub reported and whose `method` is `unrecorded`. | +| `created_at`, `updated_at` | When the bundle was first written and last completed. | +| `signed` | `true` only when a valid signing key produced `signature`. | +| `hash` | Hex SHA-256 of the canonical encoding (see below). | +| `signature` | Base64 Ed25519 signature over the `hash` string. Absent when `signed` is `false`. | + +### `policy` + +`acmm_level`, `perspectives`, `require_approval`, `min_priority`, `human_merge_paths`, and `sentinel_config_hash` (a hash of the sentinel configuration, so a later config change is detectable without copying the config). + +### `verdicts[]` + +`perspective`, `model`, `backend`, `verdict`, `confidence` (0 to 1), optional `confidence_raw` and `confidence_derived`, `recorded_at`, and `findings[]` of `path`, `line`, `severity`, `summary`. + +## Canonical form, hash and signature + +1. Marshal the bundle, drop the `hash` and `signature` fields, then re-encode with object keys sorted lexically, no insignificant whitespace, and no HTML escaping. This is the canonical JSON. Omitted optional fields stay omitted; do not add `null` or empty arrays. +2. `hash` is the lowercase hex SHA-256 of those bytes. The `signed` flag is inside the hashed content. +3. `signature` is the base64 Ed25519 signature of the ASCII `hash` string. + +Any change to any covered field changes the hash and fails verification. + +## Where it lives and retention + +Bundles are written under the hive data directory, not `/var/run`, so they survive restarts: + +```text +/data/evidence/<owner>/<repo>/<number>/<head_sha>.json +``` + +The review relay writes them whenever it records a validated verdict (with or without posting a comment) or posts a review: + +- The first write for a head fetches the PR once for `author` and `base_sha`, snapshots `policy` (ACMM level, `review.require_approval`, the repo's `auto_merge.human_merge_paths`, the perspective set, and a hash of the `sentinel` block), and sets `previous_bundle_id` to the newest bundle for an earlier head of the same PR. +- Later writes append to `verdicts` and `posted_reviews`. A verdict identical to one already recorded (ignoring `recorded_at`), or a review URL already listed, is not added again, and a pass that adds nothing leaves the file untouched, so re-running the relay never duplicates entries. A changed verdict from the same perspective is kept beside the earlier one. +- Every write recomputes `hash`, and signs when `evidence.signing_key_file` is set. Files are written then renamed, so a reader never sees a partial bundle. An existing bundle that cannot be parsed is left untouched rather than replaced. +- When the sentinel sweep flags a PR, its findings (`rule`, `summary`, sorted `paths`) are added to `sentinel` in the bundle for the flagged head. If the relay has not written that head yet, the sweep starts the bundle from the PR it already listed. A finding already recorded is not added again. +- Each time Hive evaluates a head's merge eligibility, it stores the CI gate's verdict as `ci.status` with the latest check runs and `captured_at`. If review has not started the head's bundle yet, the CI snapshot starts it from the PR metadata already fetched for the eligibility check. The bundle is rewritten only when the verdict or a check name or conclusion changed (check URLs alone do not count), so an unchanged verdict does not churn the hash; a merged bundle is never touched. When the PR merges, before the merge event is sealed in, Hive refreshes `ci` from GitHub, keeping the eligibility-time `status`: the latest check run per check name for the bundle's head, with its conclusion (or its status, such as `in_progress`, if it had not finished) and URL. It also captures `human_actions` from the PR's reviews and issue events: `approval` (an approving review of this head, or any approval since the bundle was created; `detail` is the review URL), `label_added`, `label_removed`, and `hold_lift` (a hold label removed); `detail` is the label name. Label changes count only from the bundle's `created_at`. Bot and App accounts, including Hive's own, are left out; their writes are in the hive audit log. Each capture is best-effort: if GitHub cannot be read, a warning is logged, that field stays empty, and the merge is still recorded. A replayed merge changes nothing. +- When the merged PR's title or body references an earlier PR of the same repo, the two bundles are linked; see [Change-failure links](#change-failure-links). +- A finding reported against the PR as a whole, with no file, is recorded with `path` `(pr)`. A verdict's `confidence` is the reviewer's self-report snapped to the nearest rubric bin (0.55 / 0.65 / 0.75 / 0.85 / 0.95), with midpoint ties rounded up and the original number retained as `confidence_raw`. Reports omitting confidence retain the historical aggregate score divided by 5. Neither calibration score changes the aggregate 0–5 merge gate. +- `evidence.enabled: false` stops new writes. Failures are logged and never fail or retry the review itself. + +Nothing prunes bundles automatically; they stay until an operator removes them. Reads follow the same retention contract as `/api/runs/audit`: a bundle Hive can prove existed (its PR directory is still there, or a newer bundle's `previous_bundle_id` names it) is reported with an explicit `expired` marker, never as silent absence. + +### Confidence inputs + +The self-report prompt requires a bin for each perspective independently of its verdict: + +| Bin | Rubric | +| --- | --- | +| 0.95 | Claim verified directly in the diff and tests | +| 0.85 | Verified in the diff; tests not checked or absent | +| 0.75 | Inferred from context, not directly verified | +| 0.65 | Plausible but uncertain | +| 0.55 | Mostly a guess / outside this perspective’s expertise | + +`review.DerivedConfidence` is an evidence-strength heuristic, frozen when a new verdict is recorded. All weights and thresholds are named constants in `pkg/review/calibration_confidence.go`: + +- Start at 0.55; add up to 0.10 for the fraction of findings with a real path and positive line. No findings adds nothing. +- Add 0.10 when the pinned base/head comparison touches conventional test paths. This says tests changed, not that they ran. +- Diff size (added + deleted lines): add 0.10 for ≤100, 0.05 for 101–500, or subtract 0.05 for >500. Failed fetches and comparisons reaching GitHub’s 300-file cap contribute neither size nor test signals. +- Add 0.05 for an already-recorded successful CI snapshot, subtract 0.05 for failure; pending or unknown contributes nothing. No future CI or merge outcome is read back into the score. +- Add `0.05 × (2 × agreement fraction − 1)` across the latest verdict from each other perspective already available for the same repo/PR/head, including the current combined batch. No peers contributes nothing; repeated reports from one perspective count once. +- Clamp the result to [0.55, 0.95]. The card groups the continuous score into the nearest rubric bin. + +Retries preserve the original score. These optional schema-v1 fields leave old bundles’ canonical hashes unchanged when absent. This score measures observable support, not a calibrated probability, and does not feed enforce/advisory decisions. + +### Issue reopen rate by repository + +The Evidence card and `/api/evidence/summary` (`issue_reopen_rates_30d`) +report distinct issues closed by hive-merged PRs in the trailing 30 days, +partitioned by the `<!-- hive:clarity-gate -->` marker captured in the issue +body or question comments at closure. This is a fixed rolling window by +**issue closure time**, independent of the selected PR-open-time window and +author filter; the repository selector applies to the issue repository, +including cross-repository closing links. + +At merge, explicit closing-keyword references are fetched and recorded only +when the issue is closed and GitHub's closure timestamp is within one minute +after the PR merge. Issue/comment fetch failures, older bundles without +closure capture, manual closures, and merges not recorded by this hive are +unknown and excluded, not treated as an ungated control arm. Collection uses +the existing bounded post-merge evidence context and is report-only. + +`/metrics` exports these **gauges**, each labelled +`hive_id`, `repo`, `clarity_gate="true|false"`: + +| Series | Meaning | +| --- | --- | +| `hive_issue_closures_30d` | Distinct issues in the closure cohort (denominator). | +| `hive_issue_reopens_30d` | Those issues subsequently observed reopened by webhook or polling (numerator). | +| `hive_issue_reopen_rate_30d` | Numerator / denominator, in [0, 1]. Omitted for an empty cohort (API `rate: null`, UI —), never a misleading zero. | + +Repeated bundle heads and repeated reopen observations do not inflate counts. +An issue closed more than once uses its latest captured closure in the window; +only a reopen after that closure counts. Both clarity cohorts are emitted for +repositories with captured closures, including zero counts. Historical status +is not reconstructed from today's marker. Recent closures have less time to +reopen, and an unobserved reopen is missed: this is a comparison, not proof +that the clarity gate caused an improvement. The existing 14-day PR-level +change-failure proxy is unchanged. + +### Issue opens : PR merges + +The Evidence card's **Issue opens : PR merges** panel reports how fast the hive files issues against how fast it lands PRs, per repository and fleet-wide over the selected window, read against the governor's current cadence mode rather than against a flat 1:1 (`pkg/evidence/opens_merges.go`, `/api/evidence/summary` → `issue_opens_pr_merges`, server card `cards["opens-merges"]`). + +**Definitions.** A *hive-opened issue* is an issue-create action in the hive's own audit log (`agent_issue_created`, `hive_issue_created`): an issue created through the hive's GitHub App identity, either on behalf of an agent or by hive automation. Issues humans or third-party bots open directly on GitHub never pass through the hive and are not counted — this is the hive's filing pace, not the repository's. A *hive-merged PR* follows the Outcome by author kind card: a folded evidence-bundle PR with a recorded merge where either this hive performed the merge (any author kind) or the author kind is `agent` (a merge the hive only observed through the review-outcome ledger counts when an agent wrote the PR). A human or bot PR merged outside the hive is not counted, and PRs the hive never saw are missing. + +**Expected band by mode.** The governor's mode is read at render time: with a `?repo=` filter, the card reads that repo's own cadence mode (`GetState().RepoModes`, populated under `cadence_scope: per_repo`) and falls back to the fleet mode when the governor has none recorded for it; with no repo filter it reads the fleet mode (`GetState().Mode`). Either way the mode is mapped to the band the ratio *opens ÷ merges* should fall in. Thresholds are named constants in `pkg/evidence/opens_merges.go` and mirrored as `EV_OM_*` in `index.html` for the explainer; change both together. + +| Mode | Expects opens per merge | Why | +|---|---|---| +| `surge`, `busy` | ≤ 1 (`OpensMergesDrainMax`) | drain: with a full queue the hive should land more than it files | +| `quiet`, `idle` | 1–2 (`OpensMergesScoutMin`–`OpensMergesScoutMax`) | scout: with room to spare the hive may file ahead, but bounded so idle does not manufacture backlog | +| unknown (no governor) | 0.75–1.25 (parity ± `OpensMergesParityTolerance`) | no cadence to lean on; expect parity | + +The headline states the ratio, the mode, the band and a verdict: ✓ inside the band; ⚠ *backlog growing* above it (also when there are opens and no merges); ⚠ *scouting below cadence* under the quiet/idle floor. Deviation is shown against the band, not against 1.0, so a 0.8 in surge mode is a tick and a 2.7 in quiet mode is a warning. + +**Rolling 30 days.** Independently of the window pills, the panel buckets the last 30 UTC days (`rolling_30d_days`, `OpensMergesRollingDays`) and reports the 30-day ratio against the parity band (`rolling_30d_expected`, `rolling_30d_status`): day to day the mode may push the ratio either way, but over a month it should regress toward 1:1. The sparkline plots a trailing 7-day ratio per day with the parity band shaded and a dashed 1:1 line; days with no hive merges in their trailing week are not plotted. + +**Grade.** Needs `GradeMinN` (20) hive opens + merges in the window. Score = 1 − how far the ratio lies outside the band, relative to the nearer edge: inside the band A+; 10% out A-; 20% B-; ≥ 30% out, or opens with no merges, C-. Repeated audit entries for the same issue count once per entry (the audit log writes one per create); nothing is weighted by size, and no open is linked to the merge that closed it. Descriptive, not causal. + +## Change-failure links + +A proxy for the change failure rate, not a verdict on any change ([#12067](https://github.com/hivecommons/hive/issues/12067)). When a PR merges, Hive scans its title and body for a keyword followed by `#N` or `owner/repo#N` (optionally `PR #N` / `pull request #N`) in the same repository: + +- **Revert:** `revert`, `reverts`, `reverting`, `revert of` (GitHub's Revert button writes `Reverts owner/repo#N`). +- **Follow-up fix:** `fix`, `fixes`, `fixed`, `follow-up to|of|for` (also `followup`, `follow up`), `regression from|in|of`. + +A PR named both ways counts as a revert. A referenced number is linked only when its newest merged bundle records a merge in the 14 days before this one, so issue numbers and PRs Hive never reviewed link nothing. The merging bundle gets `revert_of` / `followup_of` (bundle ids) before it is sealed; then each linked bundle gets `reverted_by` / `followed_up_by` naming it and is re-sealed (and re-signed), so its `hash` differs from the one in its own merge comment. Commit messages are not scanned. A replayed merge adds nothing, and failures are logged and never affect the merge. + +**Reverts the hive did not merge** ([#13241](https://github.com/hivecommons/hive/issues/13241)): a merge the hive only observes — the `pull_request` `closed` webhook with `merged: true`, the PR state fetched for the review-outcome ledger, or the merged-PR backfill listing — is also checked for revert text, from the title and body already in hand and with no further GitHub call. `Revert "…"` titles (including GitHub's generated `Revert "Original title (#N)"`), `Reverts #N` references and git's `This reverts commit <sha>` line (7+ hex characters, matched against each candidate bundle's merge commit and head SHA) resolve to merged bundles in the same 14-day window and receive a `reverted_by` back-link naming the reverting PR as `owner/repo#N@<head>` (or `@merged` when the head is unknown). A revert whose text names neither a PR nor a commit is missed; the card says so. + +**Issue re-opens:** when the duplicate-PR claim ledger voids a merged claim because a person reopened the issue it closed (the `issues` `reopened` webhook, or an enumeration listing the issue with `state_reason: reopened`), it hands the claim to `Client.RecordReviewEvidenceIssueReopen`, which stamps the closing PR's merged bundle with an `issue_reopens` entry, then re-seals it. Bundles with a matching captured `issue_closures` record retain later reopens too; legacy bundles retain the 14-day limit. The existing change-failure rate still counts only reopens within 14 days. Each issue is recorded once per bundle. Only issues linked by a closing keyword are tracked — the ledger never saw an issue closed by hand. + +### Shadow gates and cross-family review in the study + +The two opt-in experimental arms of the study (RFC [#12062](https://github.com/hivecommons/hive/issues/12062)) read these records: shadow-gate observations (`shadow`) and per-verdict reviewer model/backend. The run plan — consenting hives, 30-day periods, exact `review.shadow` / `intent.shadow` / `review_models.exclude_author_family` diffs, rollback — is [`research/ablation-plan-2026-10.md`](https://github.com/hivecommons/hive/blob/v5/src/docs/research/ablation-plan-2026-10.md). Auto-merge is unchanged everywhere in it. + +### Backfilled bundles + +`hivectl evidence backfill --repo <owner/repo> --since <date> [--until <date>] [--root <dir>] [--dry-run]` reconstructs bundles for PRs that predate Hive's recorder, so the study in [`research/preregistration-2026-10.md`](https://github.com/hivecommons/hive/blob/v5/src/docs/research/preregistration-2026-10.md) has a baseline ([#12371](https://github.com/hivecommons/hive/issues/12371); run plan in [`research/backfill.md`](https://github.com/hivecommons/hive/blob/v5/src/docs/research/backfill.md)). It writes what GitHub history still knows and nothing else: + +- `author.login` and `author.kind` by a documented heuristic, recorded in `backfill.author_kind_rule`: Hive's `-- hive:` attribution trailer in the body (`attribution_trailer`, carrying `agent`/`backend`/`model`), a login passed with `--agent-login` (`agent_login`), Hive's 🐝 identity footer (`identity_footer`), a GitHub `Bot` account or `[bot]` suffix (`bot_account`), else `default_human`. +- `merge` (`actor` from the merger GitHub reports, else `unrecorded`; `method` always `unrecorded`), or `backfill.state: closed` with `closed_at`, or `open`. +- `created_at` is the PR's creation time, so backfilled bundles fall into the right historical window; `updated_at` and `backfill.at` are when the backfill ran. +- `revert_of` / `followup_of` and the reverse links, under exactly the [change-failure link rules](#change-failure-links) (`pkg/evidence.ChangeRefs`, 14-day window), against bundles built in the same run and bundles already on disk. + +`verdicts`, `ci` (left with a zero `captured_at`), `sentinel` and `shadow` are **absent, never fabricated**; `policy.acmm_level` is 0 unless `--acmm-level` stamps a level known to be in force for the window. Every bundle carries `backfilled: true` so each chart and export can exclude or annotate it. Population exclusions from the pre-registration are applied as `backfill.flags`, never by dropping rows: `hive_on_hive` is added for `hivecommons/hive`, `under_min_merged` when fewer than `--min-merged` (default 10) PRs merged in the window, and `placeholder_hive` by `--flag`. Existing bundles for a head are skipped, so re-running is safe; the run pauses on GitHub rate limits and `--dry-run` prints counts only. Like everything in the evidence store, the backfill is record-only: nothing reads it to decide a merge. + +### Where outcomes come from + +A PR's outcome (`pkg/evidence.PR.OutcomeKnown`) has three sources, folded per PR by `evidence.FoldPRs`. **Live merge:** the hive's own merge paths (relay, sweep, queue) complete the merged head's bundle with `merge` via `RecordPRMergedAudit`, and a bundle started after GitHub already reports a merge records it on creation. **Review-outcome ledger:** every governor cycle folds the open-PR list into `/data/review-outcomes.json` (`pkg/review/outcomes.go`) and resolves PRs that left the list with one `GetPRState` each (capped at 40 per cycle); the same pass now stamps the PR's newest bundle with `outcome` — `merged` by someone other than this hive (a human by hand, prow/tide, another bot) plus an `unrecorded` `merge` naming the merger, or `closed` without merge — so no extra GitHub call is spent (`Client.RecordReviewEvidenceOutcome`). A bundle that already states an outcome is never touched, and a PR still open is not stamped. At read time, `GET /api/evidence/summary` also applies the ledger's rows to PRs whose records state no outcome (`evidence.ApplyOutcomeHints`): a PR that merged or closed before the ledger could write to its bundle, and a PR the ledger still sees open, both count as known. **Backfill:** `hivectl evidence backfill` reconstructs `backfill.state` from forge history for PRs that predate the recorder. The summary reports `merged_elsewhere` per author kind (a subset of `merged`), `missing.prs_outcome_from_ledger` (PRs whose outcome is known only from the ledger) and `missing.prs_outcome_unknown` (PRs with none of the three: typically opened and reviewed minutes before the ledger's first look, or in a repository the governor does not enumerate). + +## Downloading + +- **API:** `GET /api/review/evidence?repo=<owner/repo>&number=<n>[&head=<sha>][&format=json|zip]` for owner/merger roles. The default is the bundle for the PR's latest head; `head` takes a full SHA or a unique prefix of at least 7 characters (409 if it matches more than one). Before either format is served, Hive verifies a signed bundle with the public half of `evidence.signing_key_file`; when signing is not configured, it verifies the unsigned bundle's content hash. A failed or unavailable required signature is a 500 and no bundle bytes are returned. `format=json` returns the verified bytes exactly as stored; add `download=1` for an attachment. `format=zip` returns `bundle.json`, `verdicts.json` (the matching verdict reports), `review-links.json` (the PR's review-links slice) and `manifest.json` (SHA-256 of each file, plus the signing public key when the bundle is signed). A missing bundle is a 404 whose body has `status: "expired"` and `expired: true` when retention removed it, otherwise `status: "not_found"`. `GET /api/review/evidence/list?repo=&number=` lists every retained bundle id and head for the PR after applying the same verification. +- **Aggregate:** `GET /api/evidence/summary` reports read-only aggregates over stored bundles, including per-tier proxy `write_counters` (`{attempted, blocked, blocked_by_reason}`, omitted when the counter file is absent) per-tier `intent_counters` (below), and `complexity_by_repo` (the newest 12 [monthly complexity snapshots](#monthly-complexity-snapshot-report-only) per repo, omitted when none exist); see [API reference](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md). Bundles whose hash or configured signature does not verify are excluded and counted in `missing.records_unreadable`. +- **Window:** the summary takes `hours=` (default 24, `0` = all time, capped at 90 days) or a custom range `from=`/`to=` as RFC3339 or `YYYY-MM-DD` (a date-only `to` is inclusive; `to` defaults to now). `to` before `from`, a span over 3 × 366 days, or `to` without `from` is a `400`. A custom range echoes `from`/`to` in the response and keeps PRs opened in `[from, to)`. **A PR is placed in a window by its open time, never by when a bundle was written:** every bundle of the same PR is folded into one row — the newest record supplies verdicts, CI, sentinel and shadow observations, the earliest `created_at` (or `merge.opened_at`) is the open time, and the merge event, the change-failure links (`revert_of`, `followup_of`, `reverted_by`, `followed_up_by`) and a backfilled `backfill.state: closed` are taken from whichever record knows them. A live bundle is created when review starts and gains a merge event when the hive itself merged, or — when the bundle is started after the PR has already merged (automerge ran before the first review wrote one, or someone else merged) — carries the merge GitHub reports at creation (`method: unrecorded`, since the API says who and when, not how); a merge by another actor after the bundle exists is still unobserved until a backfill; a backfilled bundle ([#12371](https://github.com/hivecommons/hive/issues/12371)) is stamped with the PR's open time and the forge's outcome. Without the fold, a hive that reviews but does not merge (Bluefin) showed every reviewed PR as open and every approval as a false approve, and a review sweep over old PRs pulled them into the 24h window. The fold is `evidence.FoldPRs` in `pkg/evidence`; the [hub heartbeat evidence block](/docs/hive/hub/fleet-health#evidence-summary-heartbeat-12114) and [`hivectl evidence export`](#exporting) use the same one, so the three agree per PR ([#12516](https://github.com/hivecommons/hive/issues/12516)). The response also carries `available_windows` (`{"24", "168", "720", "all"}` → PR count under the same `repo`/`author_kind` filter) so the card can say "window too short — switch to 7d or 30d" instead of a bare "Not enough data". The Evidence card offers **24h · 7d · 30d · custom** pills (custom accepts backfilled history, up to 3 × 366 days) and remembers the choice per browser (`hive.evidence.window`); its header reads "Evidence · last 30d" or "Evidence · Oct 1 – Oct 15". +- **Hub revert rates by author kind:** heartbeat evidence includes `by_author_kind`, a fixed `human` / `agent` / `bot` map of merged PR counts (`n`) and linked revert counts (`bad`) over the newest bundle per PR in the 90-day creation window. Follow-up links do not count as reverts. The owner-only hub evidence drill-down pools these counts into `revert_rate_by_author_kind`, displaying the sample size and 95% Wilson interval (null rate below 10 merges). Older spokes without the map contribute no author-kind samples. Revert links are best-effort, within 14 days of merge; recent merges may not yet have a full observation window. These rates are descriptive, not merge gates. Each hive row's `counts.by_author_kind` carries the same buckets so a hive or ACMM-level selection re-pools them in the browser. +- **Outcome by author kind (panel 1):** `outcomes_by_author_kind` in the summary counts, over the folded record per PR in the window, `n`, `merged`, `closed`, `open`, `unknown`, `reverted_14d` (merged and then linked by `reverted_by` within 14 days), `issue_reopened_14d` (merged and then an issue it closed was reopened within 14 days, from `issue_reopens`), `change_failures` (the two added; a PR both reverted and re-opened counts twice) and `change_failure_rate` (change failures ÷ merged, `null` under 1 merge) for `human`, `agent` and `bot` authors ([#13241](https://github.com/hivecommons/hive/issues/13241)). The Evidence sub-panel draws it as the **Outcome by author kind** panel: one grouped bar per kind for merged / closed / undone (reverted or re-opened) plus a hollow bar for outcome unknown, with `n=`, the merged rate and the split of undone in the tooltip. **Denominator policy:** merged rate = merged ÷ PRs with a known outcome; change-failure rate = (reverted + re-opened) ÷ merged. This is the change-failure proxy for "a PR being accepted is not the same as the project being better off": it asks whether agent-written work gets undone more often than human work. Both signals are detected from data already fetched (see [Change-failure links](#change-failure-links)); reverts are only linked since 2026-10-15 and re-opens only since 2026-10-20. `merged_elsewhere` is the subset of `merged` that someone other than this hive performed, learned from the review-outcome ledger; `closed` and `open` come from a backfilled record of the PR or from the ledger (see [Where outcomes come from](#where-outcomes-come-from)). A PR with no merge event, no backfilled record and no ledger row has **no recorded outcome** — it is `unknown` (`pkg/evidence.PR.OutcomeKnown`), counted and shown, and excluded from every rate rather than counted as open or as not merged. The summary's `missing.prs_outcome_unknown` gives the window total and `missing.prs_outcome_from_ledger` how many the ledger resolved. A revert only counts once the reverting PR is linked. Reporting only ([#12364](https://github.com/hivecommons/hive/issues/12364)). +- **Change failures by author model:** `outcomes_by_author_model` has the same fields as `outcomes_by_author_kind`, keyed by the PR author's canonical model (`modelfamily.Canonical` of the recorded author model, the ids `GET /api/governor/pr-models` uses, so `claude-opus-5-5` and `anthropic/claude-opus-5-5` both count under `claude-opus-5.5`). A person's PR is under `human` and an agent PR with no recorded model under `unknown`, as in `outcomes_by_author_family`, so the per-model and per-family maps add up to the same totals. It reuses the same revert and re-open detection; nothing new is detected. The **Outcome by author kind** panel shows it as a table under the bars (model, `n`, merged, reverted, re-opened, change-failure rate), most PRs first. `n` counts only PRs with an evidence record, so it can differ from the PRs-by-model card; read a rate on a small `n` as weak evidence ([#18720](https://github.com/hivecommons/hive/issues/18720)). +- **Maintainability trend (panel 7):** the Evidence sub-panel draws `complexity_by_repo` as three per-repo lanes on separate scales — median Go cyclomatic complexity, functions over the threshold, and warnings by tool (dashed, one dash pattern per tool) — with the first and last month on the axis. Snapshots whose month falls in the selected window are kept, boundary months included, and `n=` is the number of repos with at least two snapshots in that window; a repo with one snapshot is drawn as points. Missing months and missing tool measurements stay gaps, never zero. Vertical dotted **ACMM markers** come from `acmm_changes`: for each repo and level, the month of the earliest stored bundle whose `policy.acmm_level` is that level (1 … `acmmadvisor.MaxLevel`). Unlike the other aggregates they are computed over **all** stored bundles for the repo — not the latest bundle per PR, not the `author_kind` filter, not the `hours`/`from`/`to` window — because policy maturity is a repo property, and the chart clips them to the months it shows. A marker is the first observation, not the moment the setting changed, and a return to an earlier level is not shown. The panel is deliberately **not graded**: its explainer ends in a **Not graded** badge (grade key `ungraded`, "report-only; no threshold to grade against") rather than a Strong/Fair/Weak/Not enough data rating, because complexity rising or falling is an observation with no causal claim about agents, so there is no threshold to hold it to. It shows an empty state while no repo has a monthly snapshot. Reporting only ([#12369](https://github.com/hivecommons/hive/issues/12369)). +- **Confidence series:** the self-reported / derived toggle selects `reviewer_calibration` or `reviewer_calibration_derived`, with a separate n for each. Old bundles without `confidence_derived` are excluded from the derived series; `reviewer_calibration_legacy` discloses self-series verdicts still using the historical fallback. The plain summary compares the pooled endpoint rise in merged share per bin, only across bins with at least five known outcomes and at least two such bins per series. A falling intermediate bucket disqualifies monotonicity; sparse data produces no winner. The comparison is descriptive, uses each series’ available cohort, and does not establish causation or correctness. +- **Reviewer calibration and accuracy (panels 2–3):** `reviewer_calibration` buckets each verdict by its stated confidence per perspective with `n`, `merged`, `blocks` and `unknown` (verdicts whose PR has no recorded outcome). **Denominator policy:** merged rate = merged ÷ (`n` − `unknown`); block rate = blocks ÷ `n` (a block is known at verdict time). The card draws a bucket with fewer than `EV_CALIB_MIN_BUCKET_N` (5) known-outcome verdicts hollow and leaves it out of the joined line, because one or two verdicts invert a line without meaning anything. `reviewer_accuracy_by_model` carries `approvals`, `approved_not_merged`, `approved_unknown`, `blocks`, `merged_after_block` and `blocked_unknown` per model family × author kind, with blocks split by the bundle's `policy.require_approval` into `enforced_blocks` (`merged_after_enforced_block`, `enforced_blocked_unknown`) and `advisory_blocks` (`dissent_before_merge`, `advisory_blocked_unknown`) — no row is dropped and the unsplit totals stay ([#12595](https://github.com/hivecommons/hive/issues/12595)): false-approve rate = approvals on PRs **known** not to have merged (closed without merge, or a backfilled record still open) ÷ approvals on PRs with a known outcome; false-block rate = **enforced** blocks on PRs that merged ÷ enforced blocks on PRs with a known outcome; an advisory block on a PR that merged is dissent before merge, shown as a count and a share of advisory blocks and never as an error rate (when every block in the window was advisory the card reads "Perspective verdicts were advisory on this hive (review.require_approval off); n blocks preceded a merge."); the unknown counts are shown beside each rate. Nothing is dropped silently and nothing unknown is counted as a failure. One bias is stated on the card because it cannot be removed by policy: on a live-only hive the only way an outcome becomes known is a merge this hive performed (or, since the merge-at-start fix, a merge GitHub already reported when the bundle began), so until a backfill covers the window "merged ÷ known" is an upper bound and "false-approve ÷ known" a lower bound; the unknown count is the honest measure of what is unresolved. +- **Boundary enforcement (panel 4):** the headline is **blocked ÷ every agent GitHub write** the hive can see in the window, from `write_activity` in the summary: `total_writes` = `mediated.n` (hive-mediated writes the audit log records — agent comments, issues, PRs, reviews, labels, issue closes, branch pushes, review requests) + `direct.attempted` (writes agents sent straight to GitHub through the proxy, summed from the proxy's weekly counter buckets that overlap the window, per tier under `direct.by_tier`); `blocked` = proxy refusals (`direct.blocked`, split by `direct.blocked_by_reason`) + audited refusals of mediated writes (`mediated.refused`). The panel prints "*B* of *T* agent writes blocked · *x*%" with both absolute counts, one row per intent tier (0 `ADVISORY` … 3 `ISSUES_PRS_MERGE`) showing blocked ÷ direct writes for that tier, one row for hive-mediated writes, the top block reasons in the legend, and `sentinel_hits_per_week` as a sparkline; `n=` is `total_writes`. **Denominator policy:** every agent write counts once; would-block counts from intent verification (`intent_counters`) are shown separately in the explainer and never added to blocked. The proxy's `write-counters.json` and the intent `intent-counters.json` now live under `/data/hive-metrics/` (the PVC) so they survive container restarts — before this they sat in container-local `/var/run/hive-metrics` and were lost on every restart, which is why a hive could show "16 attempted" after thousands of writes; a file left at the old path is folded in once on startup. The counter file records `recorded_since` (the Monday of its earliest week) and `direct.since` / `direct.partial_coverage` / `direct.recorded` tell the card when a window reaches back before direct-write counting began: the card then says "direct-write counters recorded since <date>" and the total for earlier weeks holds hive-mediated writes only — stated, never back-filled. Writes that bypass both the hive and the proxy are invisible. `write_counters` (all-time totals per tier) is still emitted for compatibility. Reporting only ([#12368](https://github.com/hivecommons/hive/issues/12368)). +- **Intent counters:** every intent evaluation — the merge-eligible lane's `writeIntentVerdicts` pass and the App self-merge sweep's gate, whether or not `intent.enforce` or `intent.shadow` is on — increments an in-memory counter keyed by tier (`tier0`..`tier3`) and writes one audit-log line, action `intent_evaluated`, detail `lane=<merge-eligible|self-merge> tier=<tierN> would_block=<bool> enforce=<bool> [reason=<code>]` ([#12362](https://github.com/hivecommons/hive/issues/12362)). `would_block` is what `BlocksMerge(true)` reports, so with enforcement off it is the shadow answer; reason codes are `tier1_needs_issue`, `tier2_needs_plan`, `tier3_needs_approval`, `alignment_misaligned`, `evidence_unavailable` or `unknown`. The counters flush once a minute (and on shutdown) into `/data/hive-metrics/intent-counters.json`, beside the proxy's `write-counters.json` and in the same shape: cumulative `totals` per tier (`attempted` = evaluations, `blocked` = would-block, `blocked_by_reason`) and `weeks` keyed by the UTC Monday of each ISO week. The summary API exposes `totals` as `intent_counters` (`{attempted, blocked}` per tier), omitted when the file is absent. Record-only: the counters are never read back into eligibility. +- **Shadow gates (panel 8):** `shadow_gate` in the summary counts, over the latest bundle per PR in the window, the PRs with any shadow observation (`n`), `would_have_held` (review gate) and `would_have_blocked` (intent), and for each gate (`review_gate`, `intent`) splits the evaluated PRs into `held` and `passed`, each with how they actually turned out: `merged`, `open`, `reverted` (merged and later linked by `reverted_by`), `closed` (from a backfilled record of the same PR; a live-only bundle does not record a close) and `unknown` (no recorded outcome; excluded from the false-alarm rate, shown as a count). `review_gate_by_lane` splits the review gate's counts into `merge_eligible` and `self_merge` (the self-merge ReviewGate, [#12592](https://github.com/hivecommons/hive/issues/12592)); `review_gate` stays the sum of both. The Throughput section's Evidence sub-panel draws it as the **Shadow gates** panel (one review-gate row per lane once the self-merge lane has observations), with a zero state while shadow mode is off. Reporting only; nothing reads it to decide a merge ([#12068](https://github.com/hivecommons/hive/issues/12068)). +- **Claim vs verdict (panel 5):** `claim_vs_verdict` in the summary groups the latest bundle per agent-authored PR (`author.kind == "agent"`) by the ISO week it was created and counts `claimed` (every such PR: opening or marking it ready is the agent saying "done"), `ci_not_green`, `verdict_not_approve` (any perspective verdict other than `approve`) and `both`, plus `n`, `ci_pending` and `ci_captured`, the CI column's denominator. CI state is classified by `evidenceCIState`: the bundle's `ci.status` (`success`/`failure`/`pending`) wins when set; otherwise any check with a failing conclusion (`failure`, `cancelled`, `timed_out`, `action_required`, `startup_failure`, `stale`) is not green, checks that all finished `success`/`skipped`/`neutral` are green (the same reading the merge gate applies — a skipped job is not a red one), and anything still `queued`/`in_progress` is **pending**. **Denominator policy:** CI not green rate = not green ÷ (`ci_captured` − `ci_pending`); a record with no captured checks is disclosed under `missing.records_empty_ci`, one still running under `missing.records_ci_pending`, and neither is counted as agreement or as failure. Before this classification every `skipped` check read as "not green", which flagged almost every captured record on hives that skip path-filtered jobs. The Evidence sub-panel draws it as the **Claim vs verdict** panel with grouped weekly bars. Reporting only; nothing reads it to decide a merge ([#12365](https://github.com/hivecommons/hive/issues/12365)). **Read as the CI gate — integrity + convergence** (`ci_recovery` in the summary; the panel is titled *CI gate*): this hive hands off to CI by policy — agents open the PR as soon as they believe it is done and do not wait for CI; a red check holds the PR until the agent pushes a fix (`auto_merge.self_authored` on, `auto_merge.required_checks` if set; there is no knob that makes agents wait for CI, and the summary echoes the policy under `ci_recovery.policy`). CI red at claim is therefore **by design: disclosed, not graded**. Two grades are: **Grade A, gate integrity (safety)** — `gate` covers every PR opened in the window that merged, any author, by the check state of the head that merged. The merged head is the backfilled record's `head_sha` (GitHub's view) when one exists, else the newest live head — a review-time record often predates the final push, so the newest reviewed head is frequently *not* the merged head. The state is GitHub's check-run conclusions on that head from the commit-trail rollup where the collector has reached the PR (authoritative), else the newest live snapshot for that head. **What counts as red is what the hive's own merge gate counts:** `PRCIRecoveryTrail` resolves the PR's base branch's required set *as it is now* (branch protection via `RequiredStatusCheckContexts`, else the configured `auto_merge.required_checks`; `required_known`, `required_checks` on the trail) and judges each head on those contexts only — green when every required context succeeded (a required DCO context is satisfied once any DCO context did), red when one failed (`required_red`), pending when one is still running or has never reported (`missing_required`). A failed check *outside* the required set — a docs link check, a labeller, a cancelled optional build — never blocked the merge and is **not** a breach; it is carried as `non_required_red` on the head and disclosed. Without a resolvable required set the head is judged on every gating check (the pre-existing reading) and counted under `required_unknown`. The trail also records `merged_by`. `merged_n`, `with_checks`, `green` (`green_from_bundles` of them rest on a snapshot — a re-run cannot turn a green head red, so they count; `non_required_red` of them merged with a red non-required check), `breaches` (**confirmed only**: GitHub reports a required check red on the merged head under a resolved required set; each listed in `breach_prs` with repo, number, head, author kind, `state`, `red` (the check names), `merged_at`, `merged_by`, `source` — a breach is a bypass by whoever merged, not a fault of the author, and a check made required after an older merge reads red for that merge, which is why the date is shown), `required_unknown`, `suspected` / `suspected_prs` (three readings that cannot be confirmed: a review-time snapshot that was red on the merged head — a check can be re-run to green on the same head after it; a required check GitHub shows no run for (`state` `missing_required`, `missing`) — the merge gate accepts a path-filtered skip and this panel cannot verify one; a red read under an unresolved required set — it may be an optional check. **Not** breaches; listed; the collector enriches these first), `pending` (merged while a check was still running), `unknown` (no snapshot on the merged head, no trail). **Denominator policy:** gate integrity = (`with_checks` − `breaches`) ÷ `with_checks` where `with_checks` = `green` + `breaches` + `pending`; `suspected` and `unknown` are counts outside the rate — a merged PR nobody snapshotted is not green and not a breach, and a stale red snapshot is a question for GitHub, not a verdict. Secondary **gate latency**: `median_green_to_merge_hours` over `green_to_merge_n` merged PRs, first green on the merged head → merge. **Grade B, convergence (efficiency)** — `convergence` covers agent-authored PRs with a live record (`n`): a *pass* is one CI evaluation of a distinct head SHA; `passes` buckets settled PRs by passes until the first green head: `"1"`, `"2"`, `"3"`, `"4+"`, `"never"` (closed without merge and without a green). Passes come from the GitHub commit trail where the collector has reached the PR (`from_github`: `PRCIRecoveryTrail` scans the PR's commits from the first, reading check-run conclusions through the app token, until the first green or `PRCIConvergenceCap` = 4 evaluated heads — `evaluated`, `passes_to_green`, `scan_capped`) and from the hive's own live snapshots otherwise (`from_bundles`; bundles can miss heads nobody reviewed, so this is a stand-in until the trail arrives). `settled` = Σ `passes`; `in_flight` (open, not yet green) and `unknown` (no CI captured, or merged without an observed green) are counts outside every denominator. `median_passes` is over PRs that went green, counting `4+` as 4. `by_week` repeats the read per ISO week of PR open time. **Denominator policy:** abandoned share = `never` ÷ `settled`; first-pass share = `"1"` ÷ (`settled` − `never`) — the RFC's C1 number, drawn as a neutral line, **not graded**. The collector enriches ≤ `ciRecoveryMaxPerPass` = 40 PRs per hourly pass — red-at-claim, suspected and merged-with-unknown-state PRs first, then the newest agent PRs without a trail — into the durable rollup `/data/hive-metrics/ci-recovery.json`. **Disclosed facts** (no grade): `at_claim` `{green, red, pending, none}` over agent claims (the claim is the first live agent bundle with captured checks), swarm non-approve verdicts, and the **recovery read** `red` for red-at-claim PRs: `recovered_merged`, `green_open`, `abandoned`, `pending`, `outcome_unknown`, `enriched` / `not_enriched`, `median_pushes_to_green`, `median_hours_to_green`, `same_head_recovered`; recovery rate = `recovered_merged` ÷ (`recovered_merged` + `abandoned`). **Grading constants** (`static/index.html`): Grade A — 0 breaches Excellent, breaches ÷ `with_checks` ≤ 1% Good (`EV_GATE_BREACH_GOOD`), ≤ 3% Fair (`EV_GATE_BREACH_FAIR`), above Weak. Grade B needs both conditions: median passes ≤ 1.5 and abandoned < 5% Excellent (`EV_CONV_PASSES_EXCELLENT`, `EV_CONV_ABANDON_EXCELLENT`); ≤ 2.5 and < 10% Good (`EV_CONV_PASSES_GOOD`, `EV_CONV_ABANDON_GOOD`); ≤ 4 and < 20% Fair (`EV_CONV_PASSES_FAIR`, `EV_CONV_ABANDON_FAIR`); otherwise Weak. Panel grade = the lower of A and B (`evLowerGrade`); both need `EV_GRADE_MIN_N` samples in their denominator. The weekly bars keep the claim-time facts (claimed, CI not green at claim, swarm not approve, both). +- **Work balance (panel 6):** answers "is the queue keeping up?" from GitHub truth rather than from the hive's own audit log alone. `work_balance` in the summary has one row per ISO week of the window with `opened` (issues, split `human` / `agent` / `bot`), `closed`, `prs_opened` (same split), `prs_merged`, `prs_closed` (closed without merge), `queue_issues` / `queue_prs` (open at week end), `issue_source` and `throttled`; `work_balance_sources` names where each series came from. **Sources:** issue opens and closes come from GitHub's issues API (`state=all`, `since`), every author included, pulled by the metrics collector hourly into the durable rollup `/data/hive-metrics/issue-activity.json` (42-day initial lookback, 180-day retention; `issues_github_since` is the first date it covers, `issues_fetched_at` the last refresh); author kind is `agent` when the body carries an agent attribution trailer, `bot` for GitHub `Bot` accounts, else `human`, and an audited agent-created issue overrides the kind to `agent`. Weeks whose Monday predates `issues_github_since` read the backfilled issue series at `<evidence-root>/<owner>/<repo>/issues/<YYYY-Www>.json` when its coverage contains the requested portion of that week. Event timestamps keep partial date ranges exact; zero-event files establish observed zero counts. The collector stays authoritative for weeks whose Monday is at or after `issues_github_since`, including exact equality. Missing, malformed, or insufficiently covered series files retain the audit fallback per repository (`issue_source: "audit"`, counted in `audit_only_weeks`); mixed repository rows also disclose audit coverage. Backfilled rows use `issue_source: "github"`; `issue_series_weeks` counts the repository-weeks supplied by the series. Series events carry no issue number, so the audited agent-created override above cannot be applied to series weeks: an agent-opened issue without the attribution trailer or 🐝 footer keeps the kind the writer recorded (`bot` for a `Bot` account) in series weeks while the collector reclassifies the same issue as `agent` in rollup weeks. The audit log sees only hive-mediated writes, so the human column is a floor for audit weeks. `hivectl evidence backfill-issues` writes the series (see [CLI reference](/docs/hive/hivectl#evidence--backfill-bundles-from-github-history)). When the collector starts midweek, backfill through the following Monday (exclusive `--until`) so the entire boundary week has series coverage; stopping at the collector timestamp leaves that week on audit fallback. PR opens, merges and closes come from the folded evidence bundles (live and backfilled) for PRs opened in the window, so PRs this hive never saw are missing. Week-end queue depth is the governor's last state snapshot of the week (`/data/nous/snapshots`, actionable open issues / PRs — the same numbers as the dashboard queue section, held items excluded; `queue_samples`, `queue_retention_days` 30). **Denominator policy:** issue ratio = `closed` ÷ `opened` and PR ratio = `prs_merged` ÷ `prs_opened` over the whole window; nothing is dropped, PRs closed without merge are drawn as a tick but never counted as merged, and an unmatched close (an issue opened before the window) still counts as closed because the question is throughput, not per-issue lifecycle. **Grading** (`EV_THROUGHPUT_*`, `EV_QUEUE_GROWTH_MAX`): issues and PRs are graded separately and the card takes the lower — ratio ≥ 0.95 Excellent, ≥ 0.85 Good, ≥ 0.70 Fair, below Weak, and any grade is Weak when the week-end queue grew more than 10% from the previous week. Raw volume is never graded: a hive that opens 400 issues a week and closes 400 is Excellent. The Evidence sub-panel draws two charts (issues, PRs): opened stacked by kind, a closed / merged line, a closed-unmerged tick and a dashed week-end depth line on the right axis, under a headline "Queue at end of <week>: N open issues · M open PRs". `throttled` stays false because this hive reports no governor issue-creation throttle windows (`missing.throttle_windows_unavailable`). Reporting only ([#12366](https://github.com/hivecommons/hive/issues/12366)). +- **Dashboard:** owners get an **Evidence** button on Review Queue rows and Pipeline cards. It opens a modal with the bundle id, head, hash, whether it is signed, the verdict count and merge status, and **Download JSON** / **Download ZIP** buttons. +- **CLI:** `hivectl review evidence <owner/repo#n> [--head <sha>] [-o FILE] [--zip]` prints or saves the bundle, and `hivectl review evidence verify FILE [--pubkey KEY]` checks it offline (see [hivectl](/docs/hive/hivectl#review--review-evidence)). +- **Export:** `hivectl evidence export [--since <RFC3339|duration>] [--format csv|jsonl] [--repo owner/name] [--out FILE] [--root DIR]` dumps one row per PR straight from the bundles on disk; see [Exporting](#exporting). +- **On the PR:** when a PR merges through any Hive merge path, the merge event is added to the head's bundle (re-signed) and Hive posts one comment: + + ```text + <!-- hive-review-evidence --> Evidence bundle `<id>` sha256:<hash> — download from the dashboard or `hivectl review evidence <owner/repo#n>`. + ``` + + The marker makes it idempotent: a PR gets one such comment, however many sweeps see the merge. + +## Exporting + +Operators and the study need the raw per-PR evidence off a spoke without scraping `/data/evidence`. `hivectl evidence export` reads the schema v1 bundles under `--root` (default `/data/evidence`, layout `<org>/<repo>/<pr>/<sha>.json`) from the local filesystem — no hive session, no network — and emits one row per pull request, **folding every bundle of the PR** exactly as `GET /api/evidence/summary` does (see **Window** under [Downloading](#downloading)), so exported counts reconcile with the dashboard Evidence charts ([#12367](https://github.com/hivecommons/hive/issues/12367), [#12516](https://github.com/hivecommons/hive/issues/12516), RFC [#12062](https://github.com/hivecommons/hive/issues/12062)). Identity, verdict, CI, sentinel, shadow and `created_at`/`updated_at` columns come from the newest bundle; `outcome`, `merged_at`, the four link columns and `opened_at` come from whichever bundle of the PR recorded them. + +```bash +hivectl evidence export --since 168h --format csv --out evidence.csv # last 7 days +hivectl evidence export --since 2026-10-01T00:00:00Z --repo hivecommons/hive # JSON Lines on stdout +``` + +- `--since` takes an RFC3339 timestamp or a Go duration and keeps PRs whose open time (`opened_at`) is at or after it, as the summary API does; a PR opened before the cutoff stays out even when a newer head was reviewed after it. +- `--format` is `jsonl` (default, one JSON object per line) or `csv` (header row first). Lists join with `;` in CSV and each verdict is `perspective:verdict:model:backend:confidence`. +- Columns: `repo`, `pr`, `head_sha`, `bundle_id`, `author_login`, `author_kind`, `author_model`, `acmm_level`, `perspectives`, `reviewer_models` (distinct, sorted), `verdicts` (perspective, verdict, model, backend, confidence; sorted by perspective), `ci_conclusion` (`ci.status`), `ci_captured_at`, `outcome` (`merged`, `closed` when a backfilled bundle records a close without merge, else `open`), `merged_at`, `revert_of`, `reverted_by`, `followup_of`, `followed_up_by` (bundle ids), `shadow_review_would_have_held`, `shadow_intent_would_have_blocked` (empty / `null` when the gate was not evaluated), `sentinel_hits`, `signed`, `created_at`, `updated_at` (of the newest bundle), `opened_at` (PR open time). +- Rows are ordered by repo (case-insensitive) then PR number, so two runs over the same files are byte-identical. Files that do not parse or are not schema v1 are skipped and counted on stderr; nothing is fabricated. +- Reporting only: the export reads bundles and never influences a merge. + +## Signing key + +Set `evidence.signing_key_file` in `hive.yaml` (see the [operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#notable-fields)). The file holds an Ed25519 private key as a 32-byte seed or 64-byte key, hex or base64 encoded. If the path is empty, bundles are written **unsigned** with `"signed": false`; they still carry a `hash`, which detects accidental change but not tampering by someone who can recompute it. A missing or unusable configured key also makes writers fall back to unsigned bundles, but dashboard readers fail closed until that configured key is restored, so an unavailable key cannot silently downgrade signed evidence. Keep the private key off shared hosts and publish only the public key. + +## Verify offline + +You need the bundle JSON and the operator's Ed25519 public key (32 bytes, hex). No Hive access is required. + +1. Check `"signed": true` and that `signature` is present. If not, the bundle is unsigned and cannot be verified beyond its hash. +2. Build the canonical JSON as described above. +3. Compute SHA-256 of it and compare, as lowercase hex, with `hash`. A mismatch means the content changed. +4. Base64-decode `signature` and verify it as an Ed25519 signature of the ASCII `hash` string under the public key. + +A reference check in Python (needs `pip install cryptography`): + +```python +import base64, hashlib, json, sys +from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey + +bundle = json.load(open(sys.argv[1])) +pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(sys.argv[2])) +sig = base64.b64decode(bundle.pop("signature")) +claimed = bundle.pop("hash") +canon = json.dumps(bundle, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode() +assert hashlib.sha256(canon).hexdigest() == claimed, "content changed" +pub.verify(sig, claimed.encode()) # raises InvalidSignature on failure +print("ok", bundle["id"]) +``` + +Go users can call `evidence.Verify(&b, pub)` from `pkg/evidence`. The Python sketch assumes numbers re-encode identically (integers and short decimals such as `0.9`); if a number does not round-trip, use the Go verifier. + +## How to read the Evidence card + +Every panel on the Throughput section's Evidence card shares one layout ([#13204](https://github.com/hivecommons/hive/issues/13204)): a header row — title · ⓘ · `n=…` · **letter grade** — then one plain-English sentence, then the chart and a compact legend. The letter grade and the sentence are computed on the server (`pkg/evidence/grade.go`) from the same `/api/evidence/summary` numbers the chart draws, and shipped as `cards[<panel>] = {grade: {letter, band, reason, enough_data, rubric}, plain_summary}`. Nothing inside a panel renders larger than the header row, and nothing in it is read by anything that decides a merge. + +The ⓘ button opens a popover over the chart (never inline) with the plain-language explainer — **What is measured**, **Why it matters**, **How it is measured**, **What good looks like**, **What ours shows**, **Details** (the denominators, policy and coverage text that used to sit under the chart), **What this does not show** — followed by the grade line: the letter, the one-line reason, and the rubric it was computed by. The "ours" and "details" sections are computed from the summary for the selected window, so they change with the 24h / 7d / 30d / custom pills. The button is keyboard reachable (`aria-expanded`, `aria-controls`); Esc closes an open explainer. + +### Grades and what they mean + +Boundary enforcement is deliberately **not graded**, including in the legacy client fallback. Its status is **Enforcement demonstrated** when at least one actual refusal is observed, even below 20 writes, and **Enforcement not observed** otherwise. This is positive evidence of enforcement on those attempts, not proof that bypasses or false positives are absent. Refusal frequency describes attempted-agent compliance, not enforcement effectiveness; increasing prohibited attempts is not a goal. Sentinel detections are informational, never counted as proven blocked writes. Counts and denominator coverage remain visible; missing direct counters and partial coverage remain explicit. + +A grade is a letter from **A+** to **C-** (A band green, B band amber, C band red) or **—** (grey, dashed) when the panel does not have enough data to be graded. Hovering the pill shows the reason ("86% of 22 PRs with a known outcome merged; 1 of 19 merged was reverted"); the popover adds the rubric. Where a rubric produces a 0–1 score the letter is: A+ ≥ 0.97, A ≥ 0.93, A- ≥ 0.90, B+ ≥ 0.87, B ≥ 0.83, B- ≥ 0.80, C+ ≥ 0.77, C ≥ 0.73, otherwise C-. Every rubric needs at least `GradeMinN` (20) samples of its denominator, else **—** with a reason that names what is missing. Rubrics are pure functions in `pkg/evidence/grade.go`, each table-tested; change the table and the code together. + +| Panel | Needs | Rubric | +|---|---|---| +| Outcome by author kind | 20 PRs with a known outcome (merged, closed or open) | score = merged ÷ known × (1 − (reverted + issue re-opened within 14 d) ÷ merged, capped at 1); letter from the score table | +| Reviewer calibration | 20 verdicts with a known outcome in the selected series’ 0.95 bucket | score = merged share in the top bucket, minus 0.10 when the merged share is not non-decreasing across buckets that hold ≥ 5 known outcomes | +| Reviewer accuracy × model family | the rework-based outcome ledger (`pkg/review/accuracy.go`) with ≥ 20 samples | score = 1 − max(false-approve rate, false-block rate) summed over reviewer models; **—** ("needs the reviewer outcome ledger") until the ledger exists — merge-vs-close is never used as ground truth | +| Maintainability trend | one repo with ≥ 2 monthly snapshots in the window | first→last change of median cyclomatic and of functions over threshold, summed across repos: neither worse → A- / A / A+ by how many improved (0 / 1 / 2); one worse → B (B+ if the other improved); both worse → C | +| Boundary enforcement | No minimum sample; observational, not graded | Any observed block → **Enforcement demonstrated** on those attempts; zero → **Enforcement not observed**, never failure or A-. Counts and blocked ÷ observed writes remain context, not a score | +| CI gate — integrity + convergence | 20 merged PRs with a known merge-time check state | confirmed breaches (required check red or missing on the merged head, as the merge gate judges): 0 → A+; ≤ 1% C+, ≤ 3% C, above C-. Convergence and CI red at claim are disclosed in the card and popover, not graded | +| Work balance | 20 issues opened in the window | issues opened ÷ closed: ≤ 0.8 A+, ≤ 0.9 A, ≤ 1.0 A-, ≤ 1.15 B+, ≤ 1.3 B, ≤ 1.5 B-, ≤ 1.75 C+, ≤ 2.0 C, above (or nothing closed) C- | +| Issue opens : PR merges | 20 hive issue opens + hive PR merges in the window | score = 1 − relative distance of opens ÷ merges outside the current governor mode's band (surge/busy ≤ 1; quiet/idle 1–2; unknown 0.75–1.25); inside the band A+, 10% out A-, 20% B-, ≥ 30% or no merges C-. The rolling 30 d is judged against parity and disclosed, not graded | +| Shadow gates | 20 PRs observed by the shadow gates | would-have-held ÷ observed: ≤ 5% A+, ≤ 10% A, ≤ 15% A-, ≤ 20% B+, ≤ 30% B, ≤ 40% B-, ≤ 50% C+, ≤ 65% C, above C- (nothing was actually held; the share says how often the gates would have intervened) | + +The plain sentence under the header is at most 20 words and is templated from the numbers, for example "Agents: 418 merged, 1 reverted, 0 re-opened (0.2%). Humans: 346 merged, 0 undone. 3 outcomes not recorded yet." (a kind with no change failures is shortened to "0 undone" to stay within the word budget) or "All 58 merged PRs with a known state had green required checks. Agent PRs needed a median 1 CI pass." Zero-data windows get an explicit sentence ("No PRs with a recorded outcome in this window.") rather than a blank. + +The legacy client-side Strong / Fair / Weak bands below are still computed inside the explainers (they feed the "What good looks like" wording) and remain the fallback grade line when a hive does not yet ship `cards`. + +Terms used on first sight: a **confidence bucket** groups verdicts by the reviewer's stated confidence (0.55, 0.65, 0.75, 0.85, 0.95); **calibration** asks whether that confidence matches how often the verdict turned out right; a **false approve** is an approval on a PR that did not merge; a **false block** is a block an *enforcing* gate was overridden on (the PR merged anyway while `review.require_approval` was on); a block recorded while perspective verdicts were advisory (`policy.require_approval` false) that preceded a merge is **dissent before merge** — a count and a share of advisory blocks, never an error rate ([#12595](https://github.com/hivecommons/hive/issues/12595)). + +Grades are **Strong**, **Fair**, **Weak** or **Not enough data** — Work balance uses the four-band **Excellent** / **Good** / **Fair** / **Weak** scale the throughput ratio calls for. They describe the data in the window and are never read by anything that decides a merge. Thresholds are named constants in `index.html` and listed here; change both together. + +| Panel | Graded on | Strong | Fair | Weak | +|---|---|---|---|---| +| Outcome by author kind | (reverts + issue re-opens) within 14 d ÷ merged (`EV_REVERT_*`) | ≤ 5% | ≤ 15% | above | +| Reviewer calibration | merged rate in the selected series’ 0.95 bucket (`EV_CALIB_*`) | ≥ 80% | ≥ 60% | below | +| Reviewer accuracy × model family | worse of false-approve and false-block rate (`EV_ERR_*`); the false-block rate counts enforced blocks only, so advisory dissent before merge never paints the panel red | ≤ 10% | ≤ 25% | above | +| Boundary enforcement | Not graded: observed blocked writes demonstrate exercised enforcement, independent of refusal rate or sample size | — | — | — | +| Shadow gates | would-have-stopped PRs that merged without a revert ÷ stopped PRs that merged (`EV_SHADOW_FALSE_ALARM_*`) | ≤ 25% | ≤ 50% | above | +| CI gate — A, integrity | breaches (merged with a *required* check red or missing, as the merge gate judges; red non-required checks are disclosed, not breaches) ÷ merged PRs with a known merge-time state (`EV_GATE_BREACH_*`); unknown, suspected and pending are counts outside the rate | 0 breaches Excellent; ≤ 1% Good | ≤ 3% | above | +| CI gate — B, convergence | median CI passes to first green over agent PRs that went green AND abandoned (never green, closed unmerged) ÷ settled (`EV_CONV_PASSES_*`, `EV_CONV_ABANDON_*`); panel grade = lower of A and B. CI red at claim is disclosed, not graded: this hive hands off to CI by policy | ≤ 1.5 passes & < 5% Excellent; ≤ 2.5 & < 10% Good | ≤ 4 & < 20% | beyond | +| Work balance | issues closed ÷ opened and PRs merged ÷ opened, graded separately, card takes the lower (`EV_THROUGHPUT_EXCELLENT` 0.95 / `EV_THROUGHPUT_GOOD` 0.85 / `EV_THROUGHPUT_FAIR` 0.70); Weak regardless when week-end queue depth grew > 10% week over week (`EV_QUEUE_GROWTH_MAX`) | Excellent ≥ 95% · Good ≥ 85% | ≥ 70% | below, or queue growing | + +**Maintainability trend** is not in the table on purpose: its explainer ends in a **Not graded** badge ("report-only; no threshold to grade against") rather than one of the rated grades, because complexity trends are observations with no causal claim. Not graded is distinct from Not enough data: more snapshots would not produce a grade, and its "What ours shows" section carries no early-read caveat. + +A panel is **Not enough data** when the graded denominator is below `EV_GRADE_MIN_N` (20); its reason line then names the denominator ("needs at least 20 merged PRs") and, when the summary's `available_windows` shows a longer preset holding more PRs, adds "window too short: 7d 509, 30d 2553, all time 8731 PRs; switch to 7d or 30d". The card header shows the same hint when the window holds no PRs at all. Windows of `EV_SHORT_WINDOW_HOURS` (48) or less add an "early read" caveat. Every explainer states its denominator policy and repeats the honest limits: merged is not the same as correct, a PR with no recorded outcome is reported as **unknown n=X** and left out of every rate (never counted as "not merged" or as a false approve), live evidence (verdicts, CI, sentinel) has only been recorded since `EV_DATA_SINCE` (2026-10-08) reverts only since `EV_REVERTS_SINCE` (2026-10-15) and issue re-opens only since `EV_REOPENS_SINCE` (2026-10-20); backfilled records reach further back but carry only author, outcome and dates. + +## What a new push does + +A push changes `head_sha`, so earlier verdicts no longer describe the code. Hive starts a new bundle for the new head with `previous_bundle_id` set, and re-reviews. The old bundle is left untouched and remains verifiable. + +## How to read the hub evidence view + +Hub admins reach the fleet evidence view from the **Fleet quadrant** card on +the hub dashboard (click the chart or its **🔬 Evidence** button). It is +`GET /api/hub/evidence` rendered findings-first: a **What this says** block +of three to six plain sentences generated from the data, then one table per +section — each with a one-line plain finding under its title, a sticky title +and column heads — a **window** selector (24h · 7d · 30d · 90d · custom +date range — hives report fixed windows in their heartbeat, so a custom range +is served from the smallest window that covers it and the view says so), hive +and autonomy-level filters, a **📄 Report / ⬇ Markdown** pair (see +*Downloadable report* below) and an ⓘ button per section that opens a +plain-language explainer with four headings: **What is measured · Why it +matters · How it is measured · How to read our numbers**. The last one is +computed from the numbers on screen and ends with a grade. + +### Findings first + +Every sentence in **What this says**, and every one-line finding under a +section title, is generated from the response fields (`findings[]` on the +API; regenerated client-side by the same rules when a filter is active) and +never typed in. Each has an explicit fallback when the data is not there +("No autonomy level has 10 merged PRs yet, so revert rates cannot be +reported") so no number is ever invented. Sections no selected hive reports +are not drawn as empty tables; they are listed once under **Waiting on +hives** at the bottom, in user-facing words ("hives report this once upgraded +to the Oct 16 build or later"). The technical pointer — which heartbeat field, +which issue — lives only in that item's ⓘ explainer and in this document. +Visible modal copy never cites an issue number +(`TestEvidenceModalNoIssueNumbers`). + +### Plain labels + +| On screen | Means | +|---|---| +| **All selected hives** | the pooled row — every hive the filter currently selects (the whole fleet with no filter). When exactly one hive is selected its own row reads *(same hive as above)* instead of repeating the numbers. | +| **Merged PRs** | the number of pull requests GitHub says were merged in the last 90 days (the denominator for coverage). | +| **X% of N** | the rate and how many cases it is computed from, in one cell. | +| **margin lo – hi** (muted line under a rate) | the **margin (95%)**: with this many cases, the true value is very likely inside this range. Fewer cases, wider range. | +| **—** | below the **minimum sample** of 10 cases a rate prints as a dash, never 0%, because a percentage from so few cases is mostly luck; the count is still shown. | +| **Reviewer confidence** | how sure the AI reviewer said it was, as one of four ranges (below). | +| **False approve** | the reviewer approved, but the PR was never merged or was reverted. | +| **False block** | the reviewer blocked while an enforcing gate was on (`review.require_approval`), but the PR merged anyway after a human override. | +| **Dissent before merge** | the reviewer blocked while verdicts were advisory (`review.require_approval` off) and the PR merged; reported as a count and a share of advisory blocks, not as an error. | +| **Autonomy level** | the ACMM level the hive runs at, L1 (advice only) to L6 (merges on green CI without a human). | +| **Median time-to-merge (median of hive medians)** | column of the *Autonomy level × outcome* table: time from PR opened to merged. See below. | + +### Median time-to-merge per autonomy level + +Each spoke reports, per heartbeat window, the median time-to-merge +(`merge.at` − `merge.opened_at`, via `evidence.MedianTimeToMerge`) of the +merged PRs opened in that window that recorded `merge.opened_at`, plus that +sample size, as `time_to_merge` (`median_s`, `n`) in its heartbeat evidence +block. Medians cannot be averaged or summed, and the heartbeat carries one +median per hive rather than a distribution, so the hub reports, per ACMM +level, the **median of the per-hive medians** (`by_acmm_level[].time_to_merge`: +`median_of_hive_medians_s`, `hives`, `n`; with an even number of hives, the +mean of the two middle medians, rounded down to the second). Each hive counts +once however many PRs it merged; `n` is the total PRs behind the medians and +is shown under the value. The column header says *median of hive medians* so +it is not read as a pooled median. A level where no hive reports it — older +builds, or only PRs merged before `opened_at` was captured — shows +**not reported**, never 0, and the item stays under **Waiting on hives**. +The client re-pools a hive / level selection by the same rule +(`newEvidenceLevelTimeToMerge` in `pkg/hub/evidence.go`, mirrored by +`evidenceLevelTimeToMerge` in `dashboard.html`). Reporting only: nothing reads +it to decide a merge. + +### Per-axis criteria + +The **Per-axis criteria** table sits below the findings and the evidence +tables. For each selected hive it lists the four quadrant axes (Trust · +Productivity · Satisfaction · Efficiency) and sorts each axis's criteria into +**met**, **unmet** and **not reported**. It is derived hub-side from the same +criteria the Fleet quadrant card scores (`pkg/hub/quadrant_axes.go`), so +spokes send nothing new. It is served as `hives[].criteria[]` on +`GET /api/hub/evidence`: one entry per axis (`axis`, `label`, `scored`) with +its `criteria[]` (`name`, `label`, `status`, and `display` / `score` when +measured, `reason` when not). Its rules: + +- A measured criterion is **met** when its 0–100 score is at least 50, that + is, at least halfway from its documented worst value to its documented best + (`evidenceCriterionMetScore` in `pkg/hub/evidence_criteria.go`; the curves + are in `pkg/hub/quadrant_curve.go`). Below 50 it is **unmet**. +- A criterion with no input is **not reported**, with the reason. It is never + **unmet**. +- An offline hive, a hive that has not sent an evidence summary, or a hive + with no scored axis shows every criterion as **not reported**. + +The table reflects each hive's latest heartbeat, not the selected window. +Reporting only: nothing reads it to decide a merge. + +### Reviewer-confidence ranges + +Spokes report calibration as six equal-width heartbeat buckets +(`int(confidence × 6)`, 0–5). The spoke's own Evidence card shows five nearest-bin confidence groups and can switch between self-reported and derived scores; heartbeat ranges are unchanged. +The hub view, the findings and the report fold the six buckets into those +four ranges and label each with both the name and the numeric range: + +| Hub label | Heartbeat buckets | Spoke card range | +|---|---|---| +| Not confident (0.0–0.5) | 0, 1, 2 | 0.0–0.5 | +| Somewhat confident (0.5–0.67) | 3 | 0.5–0.7 | +| Confident (0.67–0.83) | 4 | 0.7–0.9 | +| Very confident (0.83–1.0) | 5 | 0.9–1.0 | + +The bucket edges are sixths, so the hub's 0.67 / 0.83 boundaries approximate +the spoke card's 0.7 / 0.9; the mapping is in `evidenceConfidenceRanges` +(`pkg/hub/evidence_findings.go`) and its JS mirror `EVIDENCE_CONFIDENCE_RANGES`. +Pooled buckets carry `bad` (wrong calls) as well as `n` so the hub can +regroup them without re-deriving counts from a rounded rate. + +### Downloadable report + +The **📄 Report** link in the window row opens the current view — same window, +same hive / level filter — as a standalone plain-language page in a new tab; +**⬇ Markdown** downloads the same report as a `.md` file. Both are +`GET /api/hub/evidence/report` (hub admin / owner only, like +`/api/hub/evidence`): `?hive=<id>[,<id>…]`, `?level=<n>`, the same +`hours=` / `from=` / `to=` window parameters, `format=md` (default) or +`format=html`, and `download=1` to receive it as an attachment named +`hive-evidence-<hive|fleet>-<from>-<to>.md|html`. It is rendered server-side in +Go from the same `EvidenceView` the modal uses, so every figure reconciles with +what is on screen. Sections, in order: **Summary** (the *What this says* +sentences) · **What we measured and why** · **The numbers** (each section's +table with the plain labels) · **How to read these** (margin of error, merged +≠ correct, open PRs count as not merged, recording since 2026-10-08, backfilled +bundles carry no verdicts) · **What is not reported yet and why** · **Grade per +section** with the thresholds spelled out · a footer linking back here. The +HTML variant is a single page with inline CSS and no scripts or external +assets; hive names are escaped. Golden files live in +`pkg/hub/testdata/evidence_report_*.golden`. + +Grades and their thresholds (named constants in `dashboard.html` and mirrored +in `pkg/hub/evidence_report.go`; `Not enough data` whenever the graded rate is +below the minimum sample, `Not graded` where there is no "good" value): + +| Section | Graded on | Strong | Fair | Constants | +|---|---|---|---|---| +| Evidence coverage | share of merged PRs (90d) with a record, higher is better | ≥ 80% | ≥ 40% | `EVIDENCE_COVERAGE_STRONG/FAIR` | +| Reviewer confidence | wrong-call rate in the most-confident measurable range, lower is better (needs ≥ 2 measurable ranges) | ≤ 10% | ≤ 25% | `EVIDENCE_ERR_STRONG/FAIR` | +| Outcome by author kind | revert rate of agent authors (human if no agents), lower is better | ≤ 5% | ≤ 15% | `EVIDENCE_REVERT_STRONG/FAIR` | +| Autonomy level × outcome | revert rate of the highest level with enough data, lower is better | ≤ 5% | ≤ 15% | `EVIDENCE_REVERT_STRONG/FAIR` | +| Boundary enforcement | — (not graded: no block rate is "good" on its own) | | | | +| Same- vs cross-family review | false-approve rate of the mix with most verdicts, lower is better | ≤ 10% | ≤ 25% | `EVIDENCE_ERR_STRONG/FAIR` | +| Per-hive evidence | share of hives reporting for the window, higher is better (no minimum sample) | ≥ 80% | ≥ 40% | `EVIDENCE_REPORTING_STRONG/FAIR` | +| Shadow gates × outcome | false-alarm rate (would-have-held PRs that merged and stuck) of the gate with most held PRs, lower is better | ≤ 25% | ≤ 50% | `EVIDENCE_SHADOW_FALSE_ALARM_STRONG/FAIR` | + +Limits every explainer repeats: merged is not the same as correct; open PRs +are not failures; closed-without-merge is not recorded and counts as not +merged; reverts are only linked since 2026-10-15 (`EVIDENCE_REVERTS_SINCE`) +and evidence records only exist since 2026-10-08 (`EVIDENCE_DATA_SINCE`). +Nothing in this view or the report is read by any merge decision. + +## Not covered + +A bundle shows what Hive recorded. It does not prove who a reviewer's identity is, does not make the operator's policy accept automated review, and is not a compliance claim of any kind. + +## Monthly complexity snapshot (report-only) + +`pkg/evidence/complexity` writes one maintainability snapshot per repo per +month to `/data/evidence/<org>/<repo>/complexity/<YYYY-MM>.json`: Go +cyclomatic complexity (total, mean, median, p90, max, functions over a +threshold, top hotspots) plus static-analysis finding counts per tool. An +existing month is never overwritten. It is report-only and never blocks a +merge (RFC #12062, #12072, #12363); it feeds the dashboard maintainability +panel and the study. + +- **Schedule:** the hive runs the snapshot itself (spoke side; nothing is + added to the managed repos' CI). A background loop checks hourly which + managed repos have no file for the current month and snapshots only those, + so a pass in a month that is already covered is a `stat` per repo. The first + check runs two minutes after boot. The loop stops with the process and a shutdown waits + for an in-flight pass. +- **Source:** the repo's default branch, fetched as a GitHub tarball through + the App (no `git` on the spoke, no clone cache). The archive is extracted + into a temporary directory that is removed after measuring; `ref` in the + snapshot is the default-branch name. +- **Defaults:** `evidence.complexity.enabled` is on (it needs `evidence.enabled` + too) because a monthly archive download plus an AST pass is cheap. + `evidence.complexity.static_analysis` is off because `go vet` / `staticcheck` + compile the repo and download its modules; turn it on where that cost is + acceptable. Analyzer failures are logged and the snapshot is still written + without that tool's count. +- **Retention:** the newest 24 monthly files are kept per repo; older ones are + removed after a new month is written. `GET /api/evidence/summary` returns + the newest 12 per repo as `complexity_by_repo` (hotspot lists are left on + disk). The review-bundle walkers skip the `complexity/` directory. +- **Failures:** a repo whose snapshot fails (no GitHub client yet, archive + error, invalid repo name) is logged and retried on the next hourly check; + other repos are unaffected. diff --git a/docs/content/hive/review-swarm.md b/docs/content/hive/review-swarm.md new file mode 100644 index 0000000..ce3d2c2 --- /dev/null +++ b/docs/content/hive/review-swarm.md @@ -0,0 +1,897 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md) during the docs build. Edit the canonical source in the Hive repository. + +# Review swarm + +Hive's review swarm adds a structured review-to-fix decision point for pull requests. It includes the review data model, prompt construction, verdict collector, optional merge-gate integration, governor fan-out to review-capable agents, and a bounded auto-fix cycle for review findings. + +## Perspectives + +The `pkg/review` package ships five built-in review perspectives: + +- `correctness` — regressions, edge cases, data races, test adequacy +- `security` — exploitable vulnerabilities, unsafe permissions, injection, secrets, trust-boundary regressions +- `intent-alignment` — does the diff solve the linked issue without unrelated scope creep +- `style` — maintainability, conventions, readability, repository idioms +- `docs-currency` — documentation, examples, generated docs, operator-facing text that must change with behavior + +One more is built in but off by default: + +- `plan_match` — whether the diff implements the approved plan wave named by the PR's `Hive-Run:` / `Hive-Plan:` trailers (hivecommons/hive#8317). See [Plan match](#plan-match) below. + +Which perspectives run, and what each is told to look for, are per-hive settings under `review:` (Governor → Features → Review Gate → Perspectives in the dashboard): + +```yaml +review: + perspectives: [correctness, security, api-compat] # empty = all built-ins + perspective_prompts: + style: "follow docs/CONVENTIONS.md; flag any exported symbol without a doc comment" + api-compat: "breaking changes to the public Go API or CRD schema" + combined_perspectives: true +``` + +- `perspectives` selects the set, in dispatch order. Empty means every built-in. A name that is neither built in nor described in `perspective_prompts` fails validation rather than being dropped — a typo that silently disappeared would read as enabled everywhere it is displayed while nothing reviewed it. +- `perspective_prompts` overrides the focus line for a built-in, or defines a hive-specific perspective entirely (custom names: lowercase letters, digits, single dashes, ≤ 40 chars). A blank entry means the built-in text. +- `combined_perspectives` reviews every enabled perspective in **one** agent session that leaves **one** review comment, with findings grouped under the perspective they belong to. Off, each perspective is its own session and its own comment, and `max_perspectives_per_pr` caps how many a PR receives. Combined mode ignores that cap: it exists to bound comments, and a combined review is always exactly one. The reviewer still emits one verdict per perspective — as a JSON array in the verdict file — so any single perspective can still hold a PR for a human. + +### Live-linked perspectives (`review.perspectives_source`) + +`review.perspectives_source` links the perspective set to a file in a GitHub repo, so maintainers add, remove and re-describe perspectives through ordinary PRs instead of a hive config edit (hivecommons/hive#17975). It has the same shape as an agent's `definition_source` (`owner`, `repo`, `path`, optional `ref` that defaults to the repo's default branch; a source missing `owner`, `repo` or `path` counts as unset): + +```yaml +review: + combined_perspectives: true # stays operator-owned + perspectives_source: + owner: my-org + repo: my-repo + path: .hive/review-perspectives.yaml + ref: main # optional +``` + +```yaml +# .hive/review-perspectives.yaml +kind: ReviewPerspectives +perspectives: + - name: correctness # built-in; no focus = built-in text + - name: security + - name: my-constraints # hive-defined; focus is required + focus: "Head size a multiple of 64; fp16 only." +``` + +- **Names and focus only.** The file holds the perspective names, in dispatch order, and each one's optional focus text, validated exactly like inline `perspectives` / `perspective_prompts` (built-in names may omit `focus`; custom names need it; duplicates, an empty list, a wrong `kind` or a document over 512 KiB are rejected). `combined_perspectives`, `plan_match` and `max_perspectives_per_pr` are cost and dispatch settings and stay operator-owned in the hive config. +- **The source wins; inline is the fallback.** While the source resolves, its set replaces inline `review.perspectives` and `review.perspective_prompts` everywhere the effective set is read (`ReviewConfig.EffectivePerspectives`). Inline values stay in the config and apply whenever nothing resolves. +- **Fallback order.** A fetch that has no GitHub client or fails, and a document that is malformed, each keep the last-known-good document for that source. With none cached, the inline set applies, and if that is empty too, the built-ins. A source whose repo is not on the allowlist is ignored outright (logged, nothing fetched or cached) and the inline set applies. A malformed document keeps the last-known-good set and records a warning rather than quietly dropping to the five built-ins. Only a document that parsed cleanly is remembered, so the cache never holds a corrupt set. A fetch is bounded to 8 seconds. +- **When it resolves.** Resolution happens at startup, before the first relay install, and again on every config reload. Each time the relay's perspective set is reinstalled, so a verdict naming a removed perspective is refused and an added one is accepted without a restart. Heads waiting on a removed perspective settle rather than stay stuck (#14905). A dashboard edit of the review config keeps the linked set. +- **Same trust gate as `definition_source`.** The source repo must be allowed by `GitHubPromptAllowed`: on the seed `variables.security.github_prompt_allowlist`, or approved by an owner under Settings, Security, Prompt sources; see [agent-configuration.md](/docs/hive/agent-configuration#the-trust-boundary-allowlisted-repos-are-seed-only). +- **Dashboard.** Governor → Features → Review Gate → Perspectives has a "Link perspectives to a repo file" section with `owner`, `repo`, `path` and `ref` fields, so the source never needs a hand edit of the config files (hivecommons/hive#18797). While a source is set the section shows the resolver's status (`github:owner/repo@ref`, `github-cache:owner/repo`, or "not resolved yet") and any warning, plus an **Unlink** button. The perspectives below it show the linked set (not the inline fallback) with a "Linked to owner/repo/path@ref" line; the checkboxes and focus text are read-only and "Add perspective" is hidden. Blank all four fields and save to unlink too. If the linked repo is not approved the section says so and points to Settings, Security, Prompt sources. `combined_perspectives`, `plan_match` and `max_perspectives_per_pr` stay editable. +- **API.** `PUT /api/config/review` accepts `perspectives_source` as `{"owner": "...", "repo": "...", "path": "...", "ref": "..."}` to set it, and `null` (or an object missing `owner`, `repo` or `path`) to clear it. The repo must pass the same gate as `definition_source` (the seed allowlist or an owner approval, see below); otherwise the request is refused with 400 and a message that names the repo and points to Settings, Security, Prompt sources. A successful save re-resolves the source in the same request, so the new set is in effect without a restart, and unlinking drops the linked set at once. `GET /api/config/review` returns `perspectives_source`, `perspectives_linked`, `perspectives_source_status`, `perspectives_source_warning` and `perspectives_source_approved`. While a source is set, `PUT /api/config/review` answers 409 for `perspectives` / `perspective_prompts` edits that the next resolve would replace; the message names the Unlink button. Send `perspectives_source: null` together with the inline edit to unlink and edit in one request. +- **Both config files.** The save writes the same marshalled config to `/data/hive.yaml.runtime` and `/data/hive.yaml.dashboard` through the one `Config.Save` path, so a dashboard or API change to the source is never half-applied. Do not hand-edit either file for this setting. + +### Combined perspectives: recommended, opt-in + +**Turn `combined_perspectives: true` on** (Governor → Features → Review Gate, or the config above) unless you have a reason not to. It is the single largest review-swarm token saving available (hivecommons/hive#12126): + +- The per-perspective kick repeats ~4–6 KiB of shared instruction — scope contract, how to read the PR, review-bot thread obligations, grounding, output schema, publish contract — for every perspective a PR is sent for. The combined kick emits that block **once**, under a `SHARED INSTRUCTIONS` heading, then one short `[perspective:<name>]` section per perspective carrying only what differs (its focus line and, for `plan_match`, the plan wave). Five perspectives cost one shared block plus five short sections, not five full prompts. +- The diff and the surrounding tree are read once per session instead of once per perspective. The grounding tool-call budget is stated once for the whole session: `GroundingToolCallBudget` plus `GroundingToolCallBudgetPerExtraPerspective` for each perspective beyond the first. +- What is **not** changed by combining: every perspective still returns its own verdict object (the verdict file is a JSON array, one object per perspective, validated by `ValidateReportsFor`), the review-bot thread contract is unchanged (unresolved threads from `review_bots` are fetched, answered in the review, never replied to or resolved by the reviewer), and dispatch stays keyed on (repo, PR, head SHA, perspective) with durable pending state — a combined kick records one pending entry per perspective it covers. + +**Decision: it stays off by default.** Flipping the zero value of a plain bool would silently change the dashboard toggle's meaning, the relay's derived per-head review quota (one review per head in combined mode, one per perspective otherwise), the reviewer selection (combined dispatch sends the first eligible reviewer rather than fanning out), and the blast radius of a malformed verdict (one schema slip discards every perspective's verdict at once) on hives that never asked for it. Those are operator choices, so the hive promotes the setting — here, in `hive.yaml.example`, and in the settings UI — rather than making it for them. To opt out after enabling, set `combined_perspectives: false`. + +The review-bot thread fetch in both kick shapes is bounded to what the reviewer acts on: `reviewThreads(first:ReviewBotThreadPageSize)` pages through the threads (the command paginates, so this bounds the page, not the total), and `comments(first:ReviewBotThreadCommentsFetched)` fetches the bot's finding plus the first few replies per thread rather than the full back-and-forth. The reviewer answers the finding; it does not need the twentieth reply. + +Verdicts are validated against the hive's own perspective set: a verdict naming a perspective this hive does not review with is refused by the relay, since nothing dispatched it and nothing is waiting on it. + +### Plan match + +`plan_match` judges intent as well as diff. Implementation PRs opened for a long-running run carry `Hive-Run: <run key>` and `Hive-Plan: <plan ref>` trailer lines in their body (hivecommons/hive#8310). When the perspective is on, the hive reads those trailers at enumeration time, resolves the plan they name from its bead stores (the ref may be the epic bead ID or the source issue's `owner/repo#N`), and renders the approved wave - the epic and each planned item with its status - into the review kick. The reviewer compares the diff summary against that list and reports exactly two kinds of finding: + +- `scope exceeds plan` - a file, behaviour or surface the diff adds that no planned item covers. High severity when the unplanned change is user- or operator-visible or lands outside every planned item's area; medium for supporting changes the plan implies but does not name; low for incidental cleanup. +- `planned item missing` - an item in the wave the PR should have delivered and did not. + +A high-severity scope finding is a human decision: it promotes the aggregate to `requires_human` and the PR is held for a human exactly like any other blocking finding. The plan text is planner output, not the PR author's rationale, so quoting it does not reintroduce the measured worst-performing reviewer arm (see `groundingSection` in `pkg/review/prompts.go`). + +A PR with no run trailer has nothing to judge. The reviewer returns a **not applicable** report (`verdict: approve`, `not_applicable: true`, no findings), which the aggregate treats as approve for unanimity and the confidence score drops from both the reported and the expected count - it neither helps nor hurts. A PR whose trailer names a plan the hive cannot find gets `requires_human` from this perspective, since the reviewer must not infer a plan from the diff. + +Turn it on from Governor -> Features -> Review Gate -> "Match PRs against their approved plan", or in config: + +```yaml +review: + plan_match: + enabled: true # default false; appends plan_match to the perspective set +``` + +The toggle is separate from `review.perspectives` so enabling it never requires spelling out the whole selection; `plan_match` may also be listed there explicitly. It is omitted from the settings UI's built-in list for the same reason. Off by default because the perspective only earns its cost on a hive whose PRs carry run trailers and whose plans live in its bead stores. + +Each reviewer returns a JSON object that extends the `pkg/outputschema.AgentReport` contract — or, for a combined review, a JSON array of one such object per perspective, all for the same PR and head SHA. Required AgentReport fields remain `lane`, `kind`, `findings`, `prs_opened`, `beads_filed`, and `summary`; review reports add `perspective`, `verdict`, `repo`, `number`, and optional `head_sha`. `kind` must be `review`. `head_sha` should be the full 40-character head; an abbreviated one (7+ hex digits, as `git rev-parse --short` or the PR page prints) is accepted and widened by the relay to the dispatch head or the PR's current head it prefixes, so the verdict is stored under the spelling every lane looks it up by. + +Allowed verdicts are `approve`, `changes_requested`, `requires_human`, and `reject`. Finding severities reuse `outputschema.Severity`: `info`, `low`, `medium`, `high`, and `critical`. Each finding also carries `review_scope`: `in-scope` when it affects whether the PR satisfies its linked issue or lease task, `out-of-scope` when it is a real adjacent/pre-existing concern that should not block this PR. Older reports without the field are treated as in-scope. + +## Verdict flow + +The collector reads review report artifacts from `/data/review-reports/review-report-*.json`, validates the AgentReport envelope plus review fields, aggregates by PR, and writes `/data/review-verdicts.json`. + +Governor refreshes read the report files for the open PRs in their snapshot rather than validating the entire historical report directory. Historical verdicts remain in the durable artifact under the existing retention policy. Completed requests release their reviewers before the priority queue is walked, only when head, body digest, perspective and review-head/decision identity agree. An incomplete bundle supplies coverage only for the current title/body digest: other bodies are never combined to reach approval, and only the missing current perspectives are requested. An older collection finishing late cannot overwrite a more recently collected result. + +Slot settlement also requires a server-side report receipt from the assigned agent, no older than the dispatch; a fresh collection timestamp is not evidence that an old report completed a newer request. The relay overwrites `reporter_agent` with the actual sender. Sibling and advisory reviews retain their existing verdict authority but cannot release another agent's slot. Missing legacy sender/receipt metadata does not release slots early. The refresh log reports elapsed collection time, selected files read, new-to-artifact receipts and their maximum arrival-to-collection lag. The occupancy log distinguishes pending records/agents, pending agents with confirmed kick delivery, newly settled records and planned kicks. These are dispatch bookkeeping counts, not proof that processes are running; delivery confirmation is not review completion. + +Those artifacts are written by the **review relay**, not by the reviewing agent. The report directory is owned by the hive and each agent runs under its own account, so an agent-side write is refused by the filesystem; returning the JSON in kick output stores it nowhere. The agent hands its verdict over with `hive-review --verdict-file <path>` alongside the comment, or with `hive-review --record-verdict --verdict-file <path>` when it has nothing to post. The watcher validates the report, checks it names the PR that was actually reviewed, and writes the artifact server-side — so a malformed or mis-targeted verdict never reaches the collector, which fails the collection on the first unparseable selected file. + +Validation happens **before** the comment is posted, and a verdict that fails it refuses the whole request: nothing is posted, the request is quarantined as `.bad`, and the `.result.json` the agent polls carries `ok: false` with the validator's message and a complete example object. The two artifacts are atomic on purpose — a comment that landed without its verdict left the PR reading as never reviewed, so the next kick handed it back and the same comment was posted again. `hive-review` runs the same key check in the agent's own shell first, so the common mistake (a bare `{"repo","pr","verdict","summary"}`) fails immediately with the required shape. + +The cadence reviewer's kick template (`reviewer-queue.md`) quotes that schema verbatim, lists the hive's configured perspectives with their focus text via `${REVIEW_PERSPECTIVES}`, and requires the verdict file to be an array with one object per listed perspective — clean ones as `approve` with empty findings — so a clean PR scores `5/5` rather than being capped as `1 of 5 perspectives reported`. Every `${PR_LIST}` row whose current head already carries a verdict is marked `[hive-reviewed: <verdict>@<sha7>]` so the reviewer skips it. The mark is keyed on the head SHA exactly as the dispatch lane is, so a new push reads as unreviewed again. + +The mark has two sources: the verdict artifact, and the relay's own `review-links.json` ledger of what it actually posted (with the head it posted at), so a review whose verdict was discarded — a PR the fan-out lane never dispatched — still marks the row. + +**Per-head backstop.** Independently of any prompt, the relay suppresses the comment of a new top-level review on a head that already carries its quota of hive reviews — the verdict is still recorded, so a dispatch-bound judgement is never lost to the cap: one in `combined_perspectives` mode, one per perspective otherwise, or `review.max_reviews_per_head` when set (negative disables). `--revise` (update the existing review), `--thread` (reply in it) and APPROVE are exempt. The current head is read from GitHub, not from the verdict; a failed lookup proceeds, since this is a backstop against a loop rather than the primary gate. The result is `ok: true`, `state: record_verdict`, with a `note` naming the existing review and the way out. + +**Inline comments ([#18531](https://github.com/hivecommons/hive/issues/18531)).** A reviewer anchors line findings with `hive-review --comments-file <path>`: a JSON array of `{"path", "line", "body"}` objects, with optional `"side"` (`RIGHT`, the PR head, by default; `LEFT` for a deleted line) and `"start_line"` for a range. The relay submits the summary body, the verdict event and every comment in **one** GitHub create-review call, so the PR gets one notification and each finding becomes its own resolvable thread; comments are never posted one at a time. Before submitting, the relay reads the PR's changed files and keeps only comments whose line (and range start, in the same hunk) is in the diff; the rest are folded into the summary under **Findings not on a changed line**. If the file list cannot be read in full the comments are sent as-is, and a 422 from GitHub resubmits the review once with every comment folded into the body. Paths that edit an existing review in place (`--revise`, a refreshed decision question) and the per-head backstop's status-card fold carry the comments in the body, because an edit cannot open threads. A request may carry at most 50 comments; each body gets the same redaction-quote refusal, canary scan and mention neutralizing as the summary. Comments are refused on `--record-verdict`, `--thread` and `--resolve-thread`, and a request with comments is never treated as a clean no-findings review. `reviewer-queue.md` and the dispatch publish prompt tell the reviewer to use it. + +A verdict that is never handed over is not a neutral outcome: aggregation reports "never reviewed", and the PR is dispatched for review again from scratch. + +Aggregation rules are deterministic: + +1. Any `reject` recommends closing the PR. +2. Any in-scope finding at or above the human threshold defaults to `requires_human`. +3. Any explicit `requires_human` yields `requires_human`. +4. Any `changes_requested` enters a fix cycle while below the fix cap. +5. Every perspective in the hive's configured set approving (or, under `max_perspectives_per_pr`, every perspective the PR was eligible to receive) yields a merge-eligible aggregate. +6. Every delivered perspective approving while some the PR is owed have not reported yields `incomplete`: not merge-eligible, not a human hold, with a reason naming the missing perspectives (`review coverage incomplete: missing docs-currency`). An incomplete head stays in the dispatcher: only the missing perspectives are re-asked (under `pending_ttl` / `max_redispatch`), never the ones whose reports already exist. The exception is a head that already holds a settled non-approve verdict (`requires_human`, `changes_requested` or `reject`): an incomplete re-review of the same head does not replace it. The artifact keeps the prior decision, its findings or question and its `recorded_at`, so the dispatcher never sees `incomplete` for that head — a `requires_human` head keeps taking the human-hold path and stays at 085, and a `changes_requested` or `reject` head stays on the fix path (rather than dropping back to 050 to re-ask the missing perspectives) until a complete replacement review lands. When the stale entries expire under `pending_ttl`, the whole perspective set is asked again for that head, not just the missing ones (hivecommons/hive#12878). Before this state existed a reviewer kick that died after its peers had reported left the head on a `requires_human` hold that no re-dispatch could clear (hivecommons/hive#12045). +7. Any other non-unanimous result requires human review. + +One exception to rules 2–3: on a **hive superseding PR** (the App's own PR declaring `Supersedes #N`, `PerspectiveReport.hive_superseding`) a `requires_human` — security-sensitive included — becomes `changes_requested` and enters the fix cycle, because the owner's rule is that such PRs auto-merge with no operator decision; only the fix cap, a `reject`, or the stage engine's hard stops (sentinel, hold, red CI, unresolvable conflict) hand it to a person. `auto_merge.hive_superseding.auto_merge: false` turns this off. See [hive-merge.md](/docs/hive/operations/automation-and-review/hive-merge#hive-authored-superseding-prs-auto-merge). + +Out-of-scope findings alone are normalized to an approving perspective for aggregation and confidence. They remain in the structured record, but they never lower the verdict or the 0–5 confidence score for the PR. + +The default human threshold is `high`. Review-triggered fix cycles use the same cap value as the escalation re-engagement circuit breaker (`escalation.MaxReEngagements`) so bot loops remain bounded. + +### Out-of-scope backlog filing + +When the relay accepts a review verdict, cited out-of-scope findings (`review_scope: "out-of-scope"` with `file` and positive `line`) are filed as follow-up issues labeled `agent/reviewer` (the reviewer lane provenance/routing label — see [labels-and-control-signals.md](/docs/hive/labels-and-control-signals/reference#label-axes); the retired `from-review`, `origin/review`, and `origin/reviewer` names are accepted in config and migrated on open items). Each issue is titled `[reviewer] Review backlog (<perspective>): <finding>` — like every issue the hive files, the title starts with the filing agent in square brackets (`issueshape.AgentIssueTitle`, the one function every hive issue-creation path runs its title through — `CreateIssue`, the raw advisory/recommendations/upstream-watch creates and the egress proxy — so no filer can forget it; it puts the tag first, never doubles it, and title dedupe ignores it so items filed before the tag still match). Each issue body links back to the reviewed PR and records the perspective, severity, evidence location, and finding summary. The relay deduplicates against open issues through the normal issue-create path and also persists a finding key in `/data/review-backlog-issues.json`, so re-reviewing a new commit does not file the same backlog issue or summary comment again. + +The PR receives one summary comment listing the backlog issues filed from that review. Filing is enabled by default and bounded by `review.max_out_of_scope_backlog_issues` (default `3`) per PR; set `review.out_of_scope_backlog_disabled: true` to opt out. + +Out-of-scope findings follow `review.backlog` (destination, labels, per-PR daily cap) and the fingerprint dedup described under [Backlog routing](#backlog-routing). + +### Pipeline stages + +`GET /api/review/pipeline` places every review-queue PR in exactly one stage, derived by the pure `pkg/review/pipeline.Derive` from the verdict artifact, the review dispatch state, the `review-links.json` ledger, labels, the escalation ledger, CI state and merge state. Rules are checked in this order; the first match wins: + +| Stage | Meaning | +|---|---| +| `merged` | The PR merged. | +| `abandoned` | The PR closed without merging. | +| `human_hold` | A `hold`/`needs-human` label or held queue entry, a `requires_human` or `reject` verdict on the current head, a dispatch-state human hold, an escalated escalation entry, or a `changes_requested`/`fixing` PR whose loop counter reached the fix-cycle cap. | +| `approved` | A merge-eligible `approve` verdict on the current head, an `lgtm`/`approved`/`reviewer-passed` label, the escalation ledger's reviewer-passed SHA on the head, or an approving hive review on the head. The next action is merge, fix CI or wait for CI depending on the CI rollup. | +| `fixing` | A fix is dispatched for the current head. | +| `changes_requested` | The current head's verdict (or, without one, the hive's posted review) requests changes. | +| `reviewing` | Review perspectives are dispatched for the current head and not yet aggregated, or the head's aggregate is `incomplete` (every delivered perspective approved; the rest are still owed). | +| `unreviewed` | None of the above; a verdict on an older head does not count once the head moves. | + +Each card also carries the reviewers (perspective and model), in-scope finding counts on the P0–P3 scale `review_bots.min_priority` uses (critical → P0, high → P1, medium → P2, low/info → P3), the loop counter against its cap, one next action and the reasons for the stage. The review queue lists open PRs only, so the endpoint does not return `merged` or `abandoned` cards yet. + +### Loop safety + +A card carries `loop_warning` (reason, plus the reviewer and thread behind it) while the fix-cycle counter is at `loop_cap − 1` or over, or a review-bot thread has reached `review_bots.max_attempts_per_thread`, and no human has the PR yet. `POST /api/review/pipeline/{owner}/{repo}/{number}/send-to-human` (merger or owner role) applies `needs-human` and posts one `<!-- hive-review-loop -->` comment saying why; repeating it posts no second comment, and each use is audit-logged. The endpoint does not load bot-thread counts yet, so cards warn on the fix-cycle counter only. + +Review-loop safety checklist: + +- [ ] The fix-cycle counter is below `loop_cap`, or the PR is already with a human. +- [ ] No review-bot thread is at its attempt cap without a human reply. +- [ ] A PR sent to a human carries `needs-human` and exactly one loop-safety comment. +- [ ] Nobody re-dispatches a fix on a PR that carries `needs-human`. + +### Confidence score + +Every aggregate also carries a derived 0–5 **mergeability confidence** (`confidence.score`, with `confidence.reasons`) so a maintainer working a queue can sort or glance without reading each finding (hivecommons/hive#8182). It is computed from the same reports as the verdict — never asked of the model — so it means the same thing on every PR: + +| Input | Effect | +|---|---| +| clean, fully covered, unanimous approve | 5 | +| each `medium` finding | −1 | +| each `high` finding | −2 | +| any `critical` finding | 0 | +| any `changes_requested` or `requires_human` perspective | capped at 3 | +| a configured perspective that did not report | capped at 3 | +| a `not_applicable` report (`plan_match` on a PR without a run trailer) | excluded from both counts | +| any `reject` | 0 | + +`info` and `low` findings cost nothing. Bands: 4–5 *safe*, 1–3 *needs attention*, 0 *do not merge*. `reasons` lists only what actually moved the score, worst first. + +With `review.confidence_score: true` the relay appends one line to each posted review comment, above the attribution trailer: + +```text +**Confidence: 3/5** (needs attention) — 1 high finding +``` + +When the review carries `<!-- hive-redundant-of: #N -->` (the reviewer found a merged PR that already contains the change) and the score is below the *safe* band, the line is replaced by `**no-op merge: duplicate of #N**` so a redundant PR is not labelled as bad code. + +The same marker is the identity of the decision question. Two decision-requested reviews on one PR with the same `hive-redundant-of` (or, without one, the same question once mentions, item numbers, digits and punctuation are stripped) are one question however a model reworded them: the relay refreshes the hive's standing `COMMENTED` review in place instead of posting again, the 085 entry comment is not repeated, and a hive-authored PR with that marker is never self-approved — it goes to the empty-diff closer (see [hive-merge.md](/docs/hive/operations/automation-and-review/hive-merge#empty-diff-prs-of-the-hives-own)). A PR whose diff against its base is empty re-stamps its prior verdict on every new head rather than drawing a fresh review round ([#15499](https://github.com/hivecommons/hive/pull/15499)). + +The line is derived from the verdict file the agent hands over with the comment; a request without a parseable verdict gets no line. It is off by default — the verdict marker already routes the decision, and a repo that did not ask for a score should not see one. + +## Configuration + +Merge-gate and fan-out use are opt-in and preserve existing behavior by default: + +```yaml +review: + require_approval: true + fan_out: true + max_parallel_reviews: 5 + reviewer_agents: [reviewer-a, reviewer-b] # optional; otherwise agents with review role/keywords are selected + # perspectives_source: {owner: my-org, repo: my-repo, path: .hive/review-perspectives.yaml} # optional; live-link the perspective set, see "Live-linked perspectives" + fixer_agent: scanner # optional; defaults to the PR lane, then scanner + fixer_fallback_agents: [] # opt-in ordered fallback lanes, e.g. [fixer, scanner-2] + fixer_fallback_after_undeliverable: 3 # 0 defaults to 3 only when fallbacks are configured + confidence_score: true # optional; append the 0–5 mergeability line to review comments + self_authored_decision_policy: resolve # resolve (default) non-risk-class Hive-authored decision questions, or escalate all of them + # all_authors: true # deprecated no-op; every open PR is reviewed regardless of author + fix_human_prs: false # optional; also answer review-bot threads on PRs Hive did not open, by suggestion only (default off) + contributor_prs: + base_sync: false # optional; let GitHub update-branch unstick hive-authored fork PRs (default off) + priority_labels: false # optional; mirror the PR review queue rank onto review-priority/* labels (default off) + require_labels: [] # optional; review ONLY PRs carrying one of these labels (default empty = every open PR); see "Only review labelled PRs" + pending_ttl: 45m # optional; re-dispatch a review that has posted no verdict after this long (default 45m) + pending_fix_ttl: 2h # optional; dispatch the next bounded fix attempt when a fixer has pushed no new head after this long (default 2h; negative disables expiry) + max_redispatch: 3 # optional; expiries per head before the PR is held for a human (default 3) + bot_author_model: "" # optional; model (or backend/model) that reviews PRs opened by bot_authors, e.g. gpt-6-luna (default empty = off) + bot_authors: [dependabot[bot], renovate[bot], github-actions[bot], "*[bot]"] # optional; logins routed to bot_author_model; the hive's own App never matches + bot_author_full_review_paths: [".github/workflows/**", "Dockerfile*", "**/Dockerfile*"] # optional; a bot PR touching these keeps the full-strength model + delta_rereview: true # optional; re-review a PR already judged at an earlier head by its diff since that head (default on) + delta_trivial_lines: 20 # optional; a delta under this many lines in files the prior verdict passed re-stamps it without a model call (default 20; negative disables) + delta_max_age: 72h # optional; a changes_requested verdict with findings older than this anchors no delta, the PR is reviewed in full (default 72h) + preflight: # optional; repo rule documents and dependency evidence for the reviewer, see "Review preflight" below + rule_docs: true # default on; point the reviewer at the repo's own rule documents (GitHub API only, no new egress) + dependencies: false # default OFF; vulnerability and release-age lookups for added or bumped dependencies (sends package names and versions to OSV and the registries) + severity: + block_at: P2 # optional; P1 | P2 | P3, see "Blocking line" below + comment_below: true # default true + backlog_below: true # default true + backlog: + destination: github_issue # github_issue | github_project | linear | jira + labels: [agent/reviewer] # default [agent/reviewer]; from-review, origin/review, and origin/reviewer are mapped to it + min_severity: P2 # default P2; P0 | P1 | P2 | P3 — findings below it go to the PR's Follow-ups comment, not the tracker + max_per_pr: 3 # default 3; items per PR over the PR's lifetime (max_per_pr_per_day is a retired alias) +``` + +### Blocking line (`review.severity`, `review.backlog`) + +### Only review labelled PRs (`review.require_labels`) + +`review.require_labels` is the PR-side counterpart of the issue approval gate +`project.issue_filter.require_labels` ([agent-configuration.md](/docs/hive/agent-configuration#label-policy-which-issues-agents-may-work)): +a team that wants hive reviews **only on PRs a maintainer has opted in** names +the label(s) here, and the hive reviews nothing else. + +```yaml +review: + require_labels: [hive-review] # a PR is reviewed only if it carries at least one of these +``` + +Dashboard: **Settings → Features → Review Gate → "Only review labelled PRs"** +(toggle + comma-separated label list; saved through `PUT /api/config/review` +into the dashboard overlay, so it survives restarts and ACMM pack re-applies — +it is a `review.*` key, not an agent block). + +Semantics: + +- **Absent/empty = no gate.** Every open PR stays reviewable; no existing hive + goes quiet on upgrade. +- A PR must carry **at least one** listed label. Matching is case-insensitive + and **exact** (`approved-for-review` does not satisfy `approved`). +- **Enforced server-side in three places**, so a prompt cannot route around it: + the cadence reviewer's `${PR_LIST}` and the fan-out dispatch planner never + offer an unlabelled PR (log line `review label gate withheld PRs from …`), + and the `hive-review` relay refuses any request — review, thread reply, + resolution or bare `record_verdict` — on a PR that lacks the label after + re-reading its labels with the App token (`.denied`, audit + `review_label_gate_refused`). A failed label fetch is retried, never waved + through. +- The reviewer's kick carries a `REVIEW LABEL GATE` notice naming the labels, + mirroring the issue-filter notice. +- Labels are **never created** by the hive; name one the repo already + maintains. Exempt/hold labels still exclude a PR that also carries an + approval label. +- It is independent of `review.require_approval`: a hive that gates merge on + review AND gates review on a label simply does not merge unlabelled PRs + until a person labels (or merges) them. + +`review.severity.block_at` is the lowest finding priority that still blocks merge, on the P0–P3 scale (critical → P0, high → P1, medium → P2, low/info → P3). **Settings → Features → Review Gate → Severity & backlog** offers three presets: *Strict (P0–P2 block)* sets `P2`, *Ship fast (P0–P1 block)* sets `P1`, and *Everything blocks* sets `P3`. Unset keeps today's behaviour. Findings below the line are posted as non-blocking comments when `comment_below` is true (default) and filed as follow-up work when `backlog_below` is true (default). + +`review.backlog` says where that follow-up work goes: + +| Key | Default | Notes | +|---|---|---| +| `destination` | `github_issue` | `github_project`, `linear` and `jira` require `governor.work_source.type` to be `github_projects`, `linear` or `jira` respectively. The dashboard only offers the active work source's destination, and the owner-only `PUT /api/config/review` rejects a mismatch. If the work source later changes, the hive falls back to `github_issue` rather than failing to load. | +| `project_column_id` | — | Projects v2 status option id; required when `destination: github_project`. | +| `linear_state` | team default | Linear workflow state for new items. | +| `jira_status` | project initial status | Jira status for new tickets. | +| `labels` | `[agent/reviewer]` | Applied to every item. The retired `from-review`, `origin/review`, and `origin/reviewer` are accepted and mapped to `agent/reviewer`. | +| `min_severity` | `P2` | Lowest finding priority that still becomes a backlog item. Findings below it (P3 `low`/`info` by default — every docs-currency nit, for example) are appended to one upserted `hive:review-followups` comment on the PR instead, so nothing is lost and nothing is filed. `P3` restores filing every finding ([#17065](https://github.com/hivecommons/hive/issues/17065)). | +| `max_per_pr` | `3` | Items filed per PR over the PR's lifetime, not per day. `max_per_pr_per_day` is accepted as a retired alias for the size when `max_per_pr` is unset. | + +**Precedence with `classification.review_bots.min_priority`.** One blocking line governs both the hive reviewer and external review bots. The bot threshold resolves in this order, first non-empty wins: `hive.yaml` `classification.review_bots.min_priority` (including an explicit `all`), then `hive-project.yaml` `classification.review_bots.min_priority`, then `review.severity.block_at`. With none set, every bot finding is routed. `block_at` is never copied into `min_priority`; clearing the explicit override hands control back to `block_at`. Invalid values fail config load with an error naming the field (for example `review.severity.block_at`, `review.backlog.project_column_id`). + +#### Backlog routing + +When `block_at` is set and `backlog_below` is on, every cited in-scope finding (with `file` and a positive `line`) whose priority is below the line is filed to the backlog when the relay accepts the verdict. Cited out-of-scope findings go to the same destination as before (see [Out-of-scope backlog filing](#out-of-scope-backlog-filing)). + +- **Destination.** `github_issue` files an issue in the PR's repo. `github_project` also adds that issue to the `governor.work_source.github_projects` project and sets its Status to `project_column_id`. `linear` files an issue on the Linear team mapped to the repo, in `linear_state` when set (an unknown state is an error naming it; label names the team lacks are skipped). `jira` files a Task in the first `work_source.jira.project_keys` project and moves it to `jira_status` when set. All three use the work-source credentials. If the destination's work source is not active or cannot be built, the item is filed as a GitHub issue with the `agent/reviewer` label added, and the hive logs why. +- **Item body.** The finding title and summary, the PR link, a `file:line` permalink at the reviewed head SHA, the severity with its P-level, the fingerprint, and the line `filed by Hive review backlog`. `labels` are applied to every item. +- **Fingerprint dedup.** Each finding is fingerprinted as `sha256(rule | path | snippet)`: the title, the cleaned file path and the summary, lower-cased with whitespace collapsed. Line numbers are left out, so the same nit at a shifted line still matches. `/data/review-backlog-issues.json` keeps a per-repo map of fingerprint → item. When another PR raises a known fingerprint, the hive comments on the existing item with the new PR link and permalink instead of filing a second one. The same PR raising it again changes nothing. When the destination folds a new finding into an existing open item instead, the item receives the full finding — title, `file:line`, summary, severity, PR link and fingerprint — under an "Additional finding (folded in — same finding area and category)" heading with an unchecked task-list line, still tagged with the `hive:review-backlog-link` marker; the PR summary lists it as `#T (folded into an existing issue) — <finding title>` ([#13604](https://github.com/hivecommons/hive/issues/13604)). The `github_issue` sink folds into an open hive-filed issue that cites the same files only when that issue is in the same category (its `Review backlog (<perspective>)` title or `Perspective:` line matches the finding's perspective) and it either cites the same file within 10 lines of the finding or names a symbol the finding's title names. The same check applies to an open issue whose title differs from the finding's only after its `Review backlog (<perspective>):` prefix; only an exact title match is reused unconditionally. Sharing a file alone is not enough: the finding is filed as its own issue, which gets a `hive:review-backlog-same-file` comment reading "Same file as #N" ([#13906](https://github.com/hivecommons/hive/issues/13906)). +- **One item per finding per PR.** Each item filed from a PR is also remembered under that PR with its evidence file, line and title (`pr_findings` in the ledger). A later report from any perspective or at any head that names the same finding — same file and the same line, a shared code symbol, or the same title once its wrapping is stripped — is tracked against the existing item, never filed again. A report whose title is only a carry-over wrapper ("Previous style finding still present (non-blocking)", "Prior correctness note still present: …", "Previous security finding (…) unchanged at new head") or that carries the `<!-- hive-refers-to: #N -->` marker is a *reference*, not a finding: it is matched against the PR's tracked items and otherwise dropped with a log line, so one finding on one PR can no longer become three issues from three perspectives (hivecommons/hive#15627, #15628, #15629). The hive notes a tracked finding's persistence at most once per head, with one `Still present at <head> (<perspectives>).` comment on the item (counted against the daily cap). Title matching ignores a leading `[reviewer]` role tag, so an existing issue dedupes whichever filing path titled it. +- **Split on host close.** A folded finding lives only in its `hive:review-backlog-link` comment, so closing the host used to close it too. Every ten minutes, alongside the closed-issue stage sweep, the hive reads the hive-authored link comments on recently closed backlog hosts (the issues the ledger points findings at) and re-files each still-unchecked `- [ ]` finding as its own `github_issue` backlog item headed `hive:review-backlog-split` and "Split from #N (host closed)", comments the new link on the host under the same marker, and moves the finding's ledger item and fingerprint records to the new issue (or to the open twin the sink folded it into, which then carries the folded comment so its own close splits it again). A checked `- [x]` finding stays with the host. A host closed as not planned or duplicate keeps the findings that match it by the fold rule above and only splits out unrelated ones; the host itself is exempt from the issue filer's rejected-twin gate for that filing (a fold cites the host's own files, so the just-rejected host would otherwise always count as the rejection), while a rejection elsewhere still suppresses the finding and is logged and counted as `skipped`. `/data/review-backlog-issues.json` also keeps `split_keys`, link-marker key → the closed hosts it was split out of, so re-runs are idempotent. One pass files at most 20 findings across all repos; hosts the pass did not reach once that cap was hit are counted and logged as `deferred`. A host that received at least one split is bumped by its cross-link comment and re-surfaces in the next pass, but a deferred host keeps its old `updated_at` and is only revisited while it stays inside the pass window (the last ten-minute interval plus ten minutes of slack), so a backlog of more than 20 unchecked findings closing within one window may leave the trailing hosts unsplit; the `deferred` count in the sweep log is the signal to look for ([#13914](https://github.com/hivecommons/hive/issues/13914)). Hosts closed before the windowed sweep reached them are covered by a backfill pass that runs after each split sweep: it walks the ledger's host index, fetches each host directly and splits every closed one through the same idempotent path. A backfill pass that split, skipped or deferred anything logs `review backlog split backfill pass complete` with those counts. Once a pass visits every host without hitting the per-pass cap (including a host left part-split when the cap ran out) or a transient error, `/data/review-backlog-issues.json` records `split_backfilled` and later passes are no-ops; an incomplete pass logs `review backlog split backfill incomplete, retrying next pass` and the next pass retries. Clearing `split_backfilled` re-runs the walk ([#13947](https://github.com/hivecommons/hive/issues/13947)). +- **Severity floor.** Findings below `review.backlog.min_severity` (default `P2`, so `low`/`info`) are never filed. They are listed as `- [ ]` task lines in one `<!-- hive:review-followups-comment v1 -->` comment on the PR, edited in place on every pass: ticked lines stay ticked, a re-reported nit is not listed twice, and new nits are appended. Operators who want every finding filed set `min_severity: P3` ([#17065](https://github.com/hivecommons/hive/issues/17065)). +- **Same-family collapse.** New findings from one pass that share a perspective and scope (for example three docs-currency nits from one PR) become one item titled `[reviewer] Review backlog (<perspective>): <repo>#<pr> — N follow-ups` whose body is a checklist, one `- [ ]` per finding with `file:line`, severity and summary. Each finding's fingerprint is recorded against that one item, so another PR raising any of them comments on it instead of filing again. A single new finding keeps the per-finding title. +- **Cap.** At most `max_per_pr` items (default 3) are filed per PR over the PR's lifetime; the count is persisted in `/data/review-backlog-issues.json` (`pr_item_count`) and never resets. A collapsed item counts once. Findings over the cap are retried on the next review and may land after a human closes an item. Out-of-scope findings also stay within `review.max_out_of_scope_backlog_issues` per PR. +- **Audit.** Each filing pass that wrote anything records one `review_backlog_batch_routed` entry on the PR (`destination`, `filed`, `updated`, `capped`). Each new GitHub issue also gets its own `review_backlog_issue_filed` entry; an issue split out of a closed host carries `split_from=<host>` and `reused`, and the dashboard audit log records one `review-backlog-split` entry per split. The PR receives one summary comment that lists the items filed. +- **Blocked on the PR.** Every item the backlog creates is parked on the reviewed PR with the `blocked` label and the `<!-- hive:blocked-on pr=owner/repo#N -->` marker, in every destination ([#13833](https://github.com/hivecommons/hive/issues/13833)). A below-line or out-of-scope finding is almost always about lines the PR changes, so working it on the base branch first is wrong or conflicts. When the cited file only exists in the PR the note says so ([#13093](https://github.com/hivecommons/hive/issues/13093)); otherwise it says the finding is about code the PR is changing, and tells whoever picks it up to check it still applies after the merge and to close it without a PR if it is already fixed. The ledger records the PR each item waits on, and `ReconcileReviewBacklogBlocks` (every governor cycle) resolves it: when the PR **merged** the hive itself checks whether the finding still applies on the PR's base branch — the evidence file gone, or none of the code symbols the finding's title names left in it, closes the item as completed with a one-line note (`review_backlog_issue_closed` audit entry; GitHub-issue destination only); otherwise, or when the check cannot tell, the block is lifted with a one-line note and the item becomes actionable; the PR **closed unmerged** also lifts the block, with a `<!-- hive:review-backlog-retriage -->` note ("source PR #N closed unmerged — re-triage against current base"), and leaves the item open for normal triage and dedupe. The hive never closes or cancels a backlog item because its PR closed: a closed PR is often superseded by one that lands the same lines, so the finding may still apply. Closing it as not planned stays a human (or `/fixed`) action. Destinations without a resolver (Jira, GitHub Projects) get the note only. A finding folded into an existing open twin keeps the twin's own state ([#13364](https://github.com/hivecommons/hive/issues/13364)). +- **Heads mode.** With [review heads](#review-heads-several-models-per-perspective), only the decision step's decided reports file backlog items; raw head reports never do, so two heads' wordings of one finding cannot become two items. Instead of the once-per-PR summary comment, the relay appends a **Follow-ups filed** section to the decided review itself (edited in place, the App's own COMMENTED review only), listing every item that head's findings map to — filed, re-raised onto an existing item, or already tracked — so each head commit's review says where its nits went. + +### Verdict labels (`review.verdict_labels`) + +```yaml +review: + verdict_labels: + reviewing: hive-review/in-progress + approve: hive-review/approved + changes_requested: hive-review/changes-requested + requires_human: hive-review/needs-human +``` + +Each governor cycle mirrors the current head's review state onto exactly one of these labels ([#13833](https://github.com/hivecommons/hive/issues/13833)): `reviewing` while the head has review kicks pending (or an incomplete aggregate), then the settled aggregate verdict (`reject` maps to `requires_human`). Stale ones are removed, a new head clears the previous head's label until its own review starts, and PRs already labelled correctly cost no API calls (at most 25 writes per cycle). A PR that merges or closes while carrying one of these labels loses it: every 10 minutes the governor searches each configured owner for closed PRs with a verdict label and removes up to 25 ([#14361](https://github.com/hivecommons/hive/issues/14361)). It is independent of the automerge engine's `stage/0NN` labels, so a hive with repo auto-merge off still shows the outcome on the PR. Every key is optional; an empty block is off. Like `human_decision_label`, the labels are never created — a repo without them is skipped with a warning — and they never block anything. + +The confidence score also feeds the **PR review queue** (`GET /api/review/queue`), which ranks every open PR - agent- and contributor-authored - by triage class, confidence band, CI state and age, with the reasons for each position. An unreviewed PR ranks as *needs attention*, never *safe*. See [review-queue-triage.md](https://github.com/hivecommons/hive/blob/v5/src/docs/review-queue-triage.md#pr-review-queue). + +When `review.require_approval` is false or omitted, `merge-eligible.json` is produced as before. When true, a PR is included only if `review-verdicts.json` contains an aggregate `approve` for the same repo, PR number, and head SHA. + +For Hive-authored PRs, `review.self_authored_decision_policy: resolve` (default) +keeps reviewer decision questions advisory unless they are a **risk class**. +The test is a denylist, not an allowlist: a question escalates to +`stage/085-needs-decision` only when its wording lands in one of the named +classes in `review.DecisionRiskClasses` (`src/pkg/review/review.go`) or the +reviewer marked it `<!-- hive-decision-risk: high -->`; every other question — +naming, sequencing, defaults, config shape, scope, changelog wording, or +anything the list never anticipated — is resolved by the hive itself and +recorded on the approving aggregate as +`decision resolved by policy: <topic> — not a risk question; recorded as advisory: <question>`. +(Before [#13020](https://github.com/hivecommons/hive/pull/13020) the policy +only resolved questions matching a short allowlist of non-risk words, so a +green agent PR whose linked issue had already specified the default still +parked for a person.) The risk classes are: + +| Class | Escalates when the question names … | +|---|---| +| `permissions-credentials` | permissions, privileges, tokens, secrets, credentials, write/admin access, grants | +| `security` | security, vulnerabilities, injection, crypto/TLS/certificates/signing keys, auth/authn/authz/OAuth/SSO | +| `sensitive-paths` | `.github/workflows`, OWNERS/CODEOWNERS, branch protection/rulesets, and every path in the sentinel `sensitive_path` default list (`hive.yaml`, `policies/`, `Dockerfile`, `go.mod`, `deploy/`, `.env`, …) | +| `data-loss-irreversible` | data loss, delete/drop/truncate/purge, destructive or irreversible actions, migrations, breaking or public-facing changes, force-push | +| `merge-trust-policy` | merge or auto-merge policy, trust tiers, ACMM levels, roles, approvers, governance, policy | +| `external-side-effects` | publishing, releases, deploys, billing/spend/cost, outbound email or notifications to humans, webhooks, registries | +| `licensing-legal` | license, copyright, legal, privacy, compliance, trademark, CLA | +| `unverifiable` | the reviewer says it could not read, judge or test the change, or the requirement is ambiguous | + +Set the policy to `escalate` to preserve the older behavior where every +decision marker parks the PR for a person. The reviewer template +(`policies/reviewer-queue.md`) also tells the swarm to check the linked +issue/spec and PR body before asking, and to cite the answer +(`per #<issue>: …`) instead of raising a question the issue already settled. + +**Contributor and human-authored PRs: no decision in CI/Review unless the +review found something fishy or insecure.** The owner's rules +([#15640](https://github.com/hivecommons/hive/issues/15640)), verbatim: + +> there should be no decisions by a human while these are in ci/review — +> unless the review found something. +> unless you find something fishy and insecure happening at the pr in +> progress level, then we can let things go and then decide in merge +> queue, if needed. +> we dont want to create a log jam during pr in progress. +> i always have the last word when it comes to merge of untrusted. + +So while a PR the hive did not author is in CI/Review, the hive runs CI and +the review swarm to completion on its own, and the stage always has an +active mover (CI, the swarm, the clanker fixing, the hive adopting). The +**only** early exit to `stage/085-needs-decision` is a concrete security / +trust finding — one predicate, `review.IsSecuritySensitiveFinding` +(`src/pkg/review/security_finding.go`): + +- the reviewer's `<!-- hive-decision-risk: high -->` marker; +- the security perspective withholding approval (`requires_human`); +- a decision question in a security-class risk class — `security`, + `permissions-credentials`, `sensitive-paths` (workflows, CODEOWNERS, + branch protection, deploy, Dockerfiles, dependency manifests, …); +- an in-scope finding on a sensitive path: `sentinel.DefaultSensitivePaths` + plus the operator's extra globs in `security.sensitive_paths`; +- an in-scope finding, or the review summary, flagging insecure or + suspicious behaviour (injection, exfiltration, secrets, unpinned actions, + supply chain, …). + +A sentinel alert (`contributor-lane:sentinel-blocked`), a workflow-path or +tests-removed lane rule and a reporter-trust hold are the lane-side +equivalents and park the PR the same way. The finding is recorded as +`decision_finding` and the 085 comment and tracker popover print it as +`the review found: …` next to the reviewer's question, so the operator is +told WHAT was found. Another perspective's `changes_requested` on the same +head does not fold that exit into the fix cycle: the aggregate stays +`requires_human` with the finding, and the change requests wait in the +review for the person who decides +([projectbluefin/utah-packages#890](https://github.com/projectbluefin/utah-packages/pull/890) +went to its author at `stage/072-returned-to-contributor` for a PR-body +edit while the security review's App-credential question waited on a +maintainer). + +Everything else the review raises — ordinary nits and findings, a duplicate, +naming, scope, sequencing, licensing, a failing optional check, a conflict +— never asks a person during CI/Review: a finding goes back to the +clanker / adoption path as `changes_requested`; a bare question is +advisory, the aggregate is `approve`, recorded as +`no security finding — the PR keeps moving; a person has the last word at the merge gate; recorded as advisory: <question>`, +and the PR moves on. At the merge gate the untrusted-author invariant +holds: a contributor the lane cannot vouch for parks at +`stage/090-ready-for-human-merge` (`contributor-lane:claim-tier-untrusted`, +`untrusted-author-role`, the human-merge rule) and waits for the operator's +merge-now / queue-merge — the hive never auto-merges an untrusted author's +PR, green, approved and soaked or not. `self_authored_decision_policy: +escalate` restores the old park-on-every-marker behavior for these PRs too. +review. The same `self_authored_decision_policy: escalate` switch restores +the old park-on-every-marker behavior for these PRs too. + +Two decision questions never reach the swarm or a person at all, because +the hive already owns the answer: + +- **"Should this hive PR be closed in favour of #M?"** A hive-authored PR + whose closing targets are all closed, one of them by a *different* merged + PR #M, and whose head conflicts with the base (or whose files #M already + covers) is superseded. With `governor.auto_close_superseded` (default + on) the self-authored lane closes it as `hive/superseded` with a notice + naming #M *before* dispatching any review, the supersession sweep does + the same on a conflicting rebase, and the close-on-merge of #M closes it + immediately — no reviewer cycle, no `stage/085-needs-decision` + ([#14965](https://github.com/hivecommons/hive/pull/14965) asked the owner + this after #14957 merged and sat parked for over an hour). Human-authored + PRs keep the notice and the decision. +- **A `requires_human` on a PR the hive adopted.** When a contributor PR is + adopted in supersede mode (stage 074, superseding App PR #N carries the + head), the swarm's question is answered on #N. The original's 085 yields + to the adoption in the adopting pass: it leaves the merge gate for the + CI/Review column with an "Adopted → #N" pill, and is closed as + superseded when #N merges + ([#14975](https://github.com/hivecommons/hive/pull/14975) → #14980, + [#14947](https://github.com/hivecommons/hive/pull/14947) → #14977). A + hold, sentinel alert, `needs-human` a person applied, fork guard or + manual-merge lane rule still keeps 085. See + [labels-and-control-signals.md](/docs/hive/labels-and-control-signals/stage-labels#supersession-closed-issue-another-merged-pr). + +`review.shadow` (default false) evaluates the same approval gate (including the unavailable-artifact case) without enforcing it. A PR that is otherwise merge-eligible stays eligible; the result is recorded as `shadow.review_gate.would_have_held` (with reason and confidence) on the PR head's evidence bundle and logged. Shadow never blocks a merge and never weakens `require_approval: true`, which keeps blocking as above. Recording needs `evidence` enabled and an existing bundle for the head; if `evidence.signing_key_path` points at a key that exists but fails to load, the shadow write is skipped with a warning rather than rewriting a signed bundle unsigned (an absent key path or missing key file still records unsigned). + +`review.fan_out` is separately defaulted to false. When both `require_approval` and `fan_out` are true, the governor eval cycle plans review kicks for agent-authored PRs that do not yet have a fresh aggregate verdict for their current head SHA. + +## Reviewer selection + +**Settings → Features → Review Gate → Reviewers** lists every configured agent with its +engine and model as a pick-list bound to `review.reviewer_agents`; it shows how many agents +are review-capable under the current selection and, when **Fan out to multiple reviewers** +is on, warns if they all run on one engine (multi-model review needs reviewers on at least +two engines) and notes when **Review every perspective in one session** is also on, since +combined mode dispatches only the first eligible reviewer. The same section carries the +fan-out toggle and **Max parallel reviews**. + +An agent is considered review-capable if it is enabled, not paused, and not on-demand, +**and** one of the following is true: + +1. **Explicit list** — `review.reviewer_agents` names the agent, or the base agent a + replica was expanded from (`replicas: N` lanes qualify through their base, so the list + never needs each replica spelled out). When this list is non-empty, only agents on it + and their replicas qualify; the keyword scan below is skipped entirely. +2. **Keyword scan** — the string `review` (case-insensitive) appears in any of: + the agent's name, `role`, `aliases`, `lane_keywords`, or `detect_keywords`. + +The dashboard security section (the `security` block of `GET /api/config/governor`) exposes a `reviewCapableAgents` +count, and `GET /api/config/review` carries a `reviewer_candidates` list (name, backend, +model, `available`, `keyword_match`, `review_capable`) that the Reviewers pick-list renders. If `review.require_approval` is true and that count is zero, the dashboard +shows a warning: + +> Review approval is required, but no enabled review-capable agents were detected. + +To make an agent review-capable without the explicit list, set its `role` or add a +keyword: + +```yaml +agents: + my-reviewer: + engine: claude + role: reviewer # contains "review" → qualifies automatically +``` + +Or use the explicit list to name any agent regardless of its keywords: + +```yaml +review: + require_approval: true + fan_out: true + reviewer_agents: [my-reviewer, scanner] +``` + +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. + +## 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`. + +```yaml +agents: + code-reviewer: # the base; not dispatched as a head + backend: claude + model: claude-sonnet-5-5 + role: reviewer + review_heads: + - {backend: claude, model: claude-sonnet-5-5, alias: sonnet, replicas: 2} # code-reviewer-sonnet-1, -2 + - {backend: codex, model: gpt-6-sol, alias: sol} # code-reviewer-sol-1 +review: + combined_perspectives: false + reviewer_agents: [code-reviewer] # naming the base admits its heads +``` + +With split perspectives, every perspective is dispatched once per head, to a replica of that head with no review kick in flight (see *One kick in flight per agent* below); the base and its plain `replicas` are not dispatched (they are reserved for the decision step). Because head dispatch asks every perspective of every head, a reviewer lane *without* `review_heads` alongside one with them would have nothing left to review, so config load rejects that mix under `combined_perspectives: false` (under `combined_perspectives: true` it still loads, and the hive logs a `review heads config` warning at boot that the plain lanes receive no combined perspectives while the heads cover them): every admitted reviewer (the `reviewer_agents` list, or every agent carrying the `review` token when the list is empty) must declare `review_heads`, or be left out. Only heads of admitted bases are expected by the aggregate. Each kick costs one `max_parallel_reviews` slot, and `max_perspectives_per_pr` still bounds how many perspectives a PR head receives. A head reviews **blind** (it is told not to read other reviews of this head) and **records only**: it delivers its verdict with `hive-review --record-verdict` and posts nothing on the PR. The relay stamps each verdict with the head from the dispatch record it bound to (an advisory verdict with no dispatch row carries none) and keeps one report per perspective per head; `review_model` is stamped per head, so each head's report names the model that head ran. + +Heads have no `review_models` pool of their own (the head is the model). + +**Combined heads.** Under `combined_perspectives: true` ([#15058](https://github.com/hivecommons/hive/issues/15058)) each head gets **one** record-only kick per PR head carrying every perspective it still owes, instead of one kick per (perspective, head): with 2 heads and 5 perspectives a PR costs 2 head kicks plus the decision rather than 10 plus the decision, and each model reads the diff once. The head records one JSON array with a verdict per perspective through a single `hive-review --record-verdict`; pending entries stay one per (perspective, head), so settling, expiry and `head_max_retries` work per pair, and a head that answers only some perspectives is re-asked for the rest only. As with any combined review, `max_perspectives_per_pr` does not apply and the kick costs one `max_parallel_reviews` slot. The decision step is unchanged. + +Inside that one kick the head **fans out**: it fetches the PR metadata, the diff and any linked issue or contract once, then starts one sub-agent per perspective in parallel (the Task tool on Claude Code, the backend's sub-agent facility on Codex and others), handing each the diff, the contract text, the shared instructions and its own perspective's focus (including any `review.perspective_prompts` override). Every sub-agent is launched on the head's own model (the kick names it), so the per-head `review_model` stamp stays true; the per-perspective sub-agents replace the single pinned sub-agent of the independent-review instruction rather than adding to it, and a head whose sub-agent facility cannot pin its model reviews the perspectives itself. Sub-agents return one verdict object each; they post nothing, never call `hive-review` and do not refetch the PR. The head collects them into the one JSON array and records it once. Where sub-agents are unavailable the head reviews the perspectives one by one in the same session; the array contract does not change. A kick that re-asks a single perspective has nothing to fan out and carries no fan-out section. The point is latency: a head kick then takes about as long as its slowest perspective instead of the sum of all of them. + +### The decision step + +The heads' raw reports are evidence, never a verdict: while any head report exists without a decision, the PR head aggregates to `incomplete` (`Perspectives` shows the strictest head verdict and `heads` which heads answered, for the queue), so nothing routes on a single head. + +1. **Settled.** Once every expected head has reported every perspective, or ran out of retries (below), the aggregate is marked `awaiting_decision` and the planner sends **one decision kick per PR** to a base reviewer with no review kick in flight. It costs one parallel slot and covers every perspective the heads judged; one pending entry per perspective (`decision: true`) binds the reports it records. +2. **The kick carries every head's full report**: verdict, every finding with its severity, scope, summary and `file:line`, the summary and any decision question, plus any head that never answered. The base reviewer re-reads the code, gives **every** head finding a disposition (`confirmed`, `not_reproducible` or `out_of_scope`) with a reason, de-duplicates findings raised by several heads, sets the **final severity** of each confirmed finding (blocking: correctness, security, data, a broken contract or a missing required test; backlog: docs wording, style, naming, behaviour-neutral refactors), and decides each perspective's verdict. +3. **One comment.** The base posts the PR's only review comment with `hive-review --comment --verdict-file`: findings under per-perspective headings tagged with the heads that raised them, and a `### Head findings` section listing every head finding with its disposition. The relay stores the reconciled verdicts as **decided** reports (`decided: true`, with `dispositions`), set from the dispatch record, never from the reviewer's JSON, in their own `…-decided` files beside the heads' raw reports. +4. **Routing is unchanged.** The aggregate is built from the decided reports, so `review.severity.block_at`, `comment_below`, `backlog_below`, `review.backlog`, out-of-scope backlog filing, fix kicks and human holds all run on the decision's final severities exactly as on any review. The aggregate keeps `head_reports`, `dispositions` and `missing_heads` as evidence. + +**Skip rule.** When every head approved every perspective with no findings and no decision question, there is nothing to reconcile: the heads' unanimous approval is the decision and no session runs (`decision_skipped`). With `review.acknowledge_no_findings` on, the hive posts one line, once per PR head (`**Reviewed** — no findings from …, all N review heads agreed: …`); with it off, nothing is posted. + +**Retries.** A head whose review of a perspective outlives `pending_ttl` is re-sent up to `review.head_max_retries` times (Settings → Review gate; 0 means `max_redispatch`). Past that, if another head answered the perspective, the head is recorded as missing (`missing_heads` in the dispatch state and the aggregate): the decision proceeds without it and the comment says so, e.g. `sol-1: no verdict after 3 attempts; decided on claude-sonnet-5-5 only`. If **no** head answered the perspective, the head SHA's `max_redispatch` budget and human hold apply exactly as before. + +**Accuracy.** `GET /api/reviewer/accuracy` gains `review_heads`: per review model, how often its head's verdict agreed with the decided verdict (`missed_blocks` when it approved what the decision blocked, `over_blocks` the reverse), and how many of its findings the decision confirmed or rejected (`confirm_rate`). Only decided and skip-rule aggregates are scored; the decision is the reference, so no merge outcome is needed. + +## Dispatch and prompt construction + +`pkg/review` provides prompt builders for one prompt per perspective plus a sequential fallback prompt. These prompts instruct review-capable agents to emit the extended AgentReport JSON shape above. + +**Who gets reviewed: every PR, regardless of author.** When review is on (`review.require_approval` and `review.fan_out`), the planner dispatches reviews for every open PR in the hive's repositories — hive-agent PRs, human PRs, clanker PRs at either trust tier, dependabot and any other bot. There is no author-class filter and no opt-out below the review feature switch itself; the only way to stop reviews is to turn review off ([#12974](https://github.com/hivecommons/hive/issues/12974): *"if pr review is selected in hive, then all prs should be reviewed"*). Before this, the swarm reviewed only agent and `[bot]` authors unless `review.all_authors` was set, and human PRs such as hivecommons/hive#12966 reached merge with zero swarm reviews. Author kind still decides what happens *after* the verdict — who may be pushed to (below), which auto-merge lane may act on it ([hive-merge.md](/docs/hive/operations/automation-and-review/hive-merge#self-merge-review-gate)), and whether the hive may approve at all (a contributor-tier clanker's PR is reviewed like any other, then still parks at `090-ready-for-human-merge`; the hive never approves on their behalf). + +**Who may review a PR.** A PR's author never reviews it, and neither does any lane in the author's family: when the author is a replica (`replicas: N`), its base agent and sibling replicas are excluded too, and when the author is a base agent, all of its replicas are. The author's base is resolved from the full configured agent set, enabled or not, so an authoring replica that is itself paused, disabled or not review-capable still rules out its siblings; a replica name that a reduced `replicas:` count no longer materialises still maps to its declared base. The verdict relay applies the same family rule: a verdict no dispatch row binds is refused as `author_self_approval` when the submitting lane shares the author's base. + +Phase 2 adds dispatch state in `/data/review-dispatch-state.json`. Pending review kicks are scoped by repo, PR number, perspective, and head SHA; when a PR head changes, stale pending entries are pruned and the new head must be reviewed again. Multiple review-capable agents receive perspective prompts in parallel up to `max_parallel_reviews`; a single reviewer receives one perspective per eval round. + +**One kick in flight per agent.** An agent's CLI works one prompt at a time, so the planner never sends a review kick (per-perspective, head, combined or decision) to an agent that still has one pending, i.e. dispatched and not yet answered or expired. It picks the first reviewer in name order that is free; when every eligible reviewer (or every replica of a head) is busy, that work waits for a later cycle. Waiting records nothing, so it costs no `max_redispatch` or `head_max_retries`, and `pending_ttl` starts when the kick actually goes to an idle agent. Load is counted in kicks, not PR heads: counting PR heads let replicas holding the same PR tie, and one PR's remaining perspectives all went to the first replica, four kicks typed into one Claude session within three minutes, three of whose verdicts never arrived. + +### Reviewer autoscale (`review.reviewers.autoscale`) + +By default the reviewer lane is a fixed pool: `agents.reviewer.replicas: 2` runs `reviewer` and `reviewer-2`, and when both have a kick in flight every other PR waits. `review.reviewers.autoscale` ([#14685](https://github.com/hivecommons/hive/issues/14685)) instead lets the lane grow and shrink with that wait. It is off by default. + +```yaml +review: + reviewers: + autoscale: + enabled: true + agent: reviewer # optional; default: first role:reviewer agent, else reviewer_agents[0] + min: 1 + max: 4 # capped at the replicas limit (5) + target_backlog_per_reviewer: 2 + scale_up_cycles: 2 + scale_down_cycles: 5 + cooldown: 5m + cpu_per_reviewer: 1.0 + mem_per_reviewer_mb: 2048 +``` + +**Demand.** Each governor cycle the planner records the PRs it left *waiting*: PRs with perspectives still to review on their current head for which every eligible reviewer was busy (`no-free-reviewer`) or the `max_parallel_reviews` budget was spent (`no-parallel-slot`). Drafts, held PRs and PRs whose review is already dispatched are not waiting. The controller ages each wait across cycles, keyed on repo, number and head, so a push restarts the clock. + +**Scale-up.** The lane is *behind* when the backlog exceeds `target_backlog_per_reviewer` × active reviewers, or when the oldest wait is older than the `stage/050-review-pending` dwell (`governor.labels.stage.dwell` overrides apply). Behind for `scale_up_cycles` consecutive cycles adds one replica. Guards refuse a wanted scale-up, in this order, and the refusal is logged with the guard's name: `at-max`; `cooldown` (less than `cooldown` since the last action); `saturated` (half or more of the active reviewers' last kicks were undeliverable — `CLI did not reach input prompt` — which is a saturated pod, not demand); `provider-budget` (the inference budget latch is on); `provider-headroom` (any provider under 10% remaining, when rotation publishes readings); `max-parallel-reviews` (more reviewers than slots is pointless); `cpu` / `memory` (the pod cgroup — `cpu.max`, `cpu.stat`, `memory.max`, `memory.current` — has less free than one reviewer's reservation; a host without cgroup limits never blocks). A refused scale-up keeps its streak, so it fires as soon as the guard clears. + +**Scale-down.** The lane is *idle* when nothing is waiting and at least one reviewer has no kick in flight. Idle for `scale_down_cycles` consecutive cycles, with more than `min` replicas active and the cooldown elapsed, marks the highest-numbered replica *draining*: the planner and the cadence kick both skip it (the eval log shows `reviewer-3 (reviewer-autoscale draining)`), and it is retired — its tmux session ended and its config entry dropped — only once its turn has ended and it has no review pending. A reviewer is never interrupted mid-turn. If demand returns while a replica is draining it is simply un-drained rather than a fresh replica being added. + +**What a dynamic replica is.** Nothing new: the controller raises or lowers the lane's materialised replica count and the ordinary `ExpandAgentReplicas` path creates `reviewer-3`, `reviewer-4` … with the same role, prompt, beads directory, scoped token, tmux pane and cadence key as a configured `reviewer-2`. The planner, kick governor, dashboard agent list and token cache cannot tell them apart. The entrypoint pre-creates the per-agent user and token cache for every name up to `max`, so a replica added at 03:00 can read its token. The declared `replicas:` only seeds the initial count (clamped into `[min, max]`) and is what is persisted; the live count survives a config reload and is never written to `hive.yaml`. + +**Observability.** One log line per decision — `reviewer autoscale: 2→3 reason=backlog=7 oldest=41m0s`, `reviewer autoscale: 3→2 drain reviewer-3 reason=idle for 5 cycles`, `reviewer autoscale: 3→2 retire reviewer-3 reason=idle`, `reviewer autoscale: 2→3 blocked by cpu`. `/api/status.reviewerAutoscale` carries `enabled`, `agent`, `min`, `max`, `current`, `target`, `draining`, `backlog`, `oldestWait`, the streaks and `lastDecision`; the Agents section shows the lane's reviewer count with an *auto* badge (replicas show *auto* / *draining*) whose tooltip carries the last decision. The knobs live in Settings → Review Gate → Reviewers → *Scale reviewers with the backlog* (owner only; `PUT /api/config/review` sub-object `reviewer_autoscale`). + +### Pending-review expiry (`review.pending_ttl`, `review.max_redispatch`) + +A pending entry is the planner's only record that a perspective was asked, so a reviewer whose kick turn dies — model timeout, proxy read timeout, pod restart — leaves entries that post no verdict and, with no expiry, made every perspective look covered until someone pushed a new commit (hivecommons/hive#12045 and #12025 sat at queue position 1 for hours with CI green and the contributor lane stuck at `no-verdict`). Each cycle the planner therefore expires pending entries older than `pending_ttl` (Go duration string, default `45m`; a negative value disables expiry) whose head still has no verdict in the artifact: the expired perspectives are dropped from state and re-dispatched in the same cycle, the governor logs `review pending expired repo=… pr=… head=… perspective=… age=… expiries=N`, and the state file's `redispatches[]` counts expiries per head. Entries younger than the TTL are left alone, so a review genuinely in flight is never re-kicked, and a verdict for the head settles it however old the entries are. The same expiry releases a `revise_verdicts_before` revisit whose reviewer died. + +The retry is bounded. Once a head's expiry count reaches `max_redispatch` (default 3) the planner stops re-kicking it, leaves the entries in place, and records a `requires_human` hold whose reason starts `review-dispatch-exhausted`; `review.human_decision_label` is applied the same way as for a reviewer's own requires_human verdict, and the governor logs `review dispatch exhausted; holding PR for a human`. A new push clears the counter and the hold along with the head's pending entries. + +Expiry also covers a head whose aggregate is `incomplete`: the delivered perspectives are taken off the pending list (their reports exist) and only the undelivered ones expire and re-dispatch, against the same per-head budget. + +The PR review queue (`GET /api/review/queue`) shows this state on unreviewed items: `pending_since` (first dispatch for the current head still pending) and `redispatch_count`, plus a reason such as `review dispatched 32m ago, no verdict yet (re-dispatched 2x after expiry)` or `review dispatch exhausted: …; waiting on a human` after the generic `not reviewed at this head` line. + +When an aggregate verdict is `changes_requested`, Hive builds a review-fix kick containing the aggregate findings and sends it to `review.fixer_agent`, the classified PR lane, or `scanner`. + +Set `review.fixer_fallback_agents` to an ordered list of enabled, kick-capable repair agents to route around an undeliverable fixer. An empty or unset list preserves existing behavior; setting `review.fixer_fallback_after_undeliverable` alone has no effect. With the list set, a candidate yields after that many consecutive undeliverable kicks (default 3), or after at least one refusal when its last known transcript activity is older than its agent-level `busy_no_activity_threshold` (default 30m). Missing transcript activity is unknown, and an idle agent with no outstanding refusals does not yield merely because its transcript is old. + +Both review-fix kicks and stale CI-red PR re-engagements retain their existing owner/fixer selection order, then try the configured fallback list in order. Paused, disabled, on-demand, non-kick, cadence-paused, provider-backed-off or already refusing fallback agents are skipped. Routing is logged, and the next repair returns to the primary once its refusal count clears. No turn is interrupted or restarted, and a fix already delivered to a fallback remains pending under the usual `pending_fix_ttl` rather than being dispatched twice. + +Fix dispatches are capped by `escalation.MaxReEngagements`; once exhausted, dispatch state records a `requires_human` hold for the PR head so the automated loop stops. + +Once that cap is hit the hive is no longer fixing the PR, and the stage must say so ([#15744](https://github.com/hivecommons/hive/issues/15744)): + +- The stage engine moves a hive-authored PR the dispatcher refuses with `fix-attempts-exhausted` from `stage/070-fixing` to `stage/085-needs-decision` with reason `fixer-exhausted:<N>`. The tracker captions it `fixer gave up after N attempts — <first line of the reviewer's last finding>`, and the lead action is **Re-author** (`decide:re-author`); *Hand it to a person* (`/hive decision <text>`) and *Close as not planned* sit in the Decide… submenu. One decision comment per head lists the same three options; it goes through the normal write-back gate. +- A `070-fixing` row never claims `Fixing · @bot` when no fix job is dispatched or running. If the dispatcher excludes the head (attempts exhausted, no enabled fixer, budget), the caption reads `Fixing paused — <why>; no fix job is dispatched` (plus `conflicting with the base branch` when the PR is dirty) and the stage actor is *nobody*. +- A stale answered decision (`decision-answered`) does not clear `stage/stalled` or move the PR back to 070 while the fixer is excluded and the head has not changed; the 085 park is preserved. +- The `review fix dispatch excluded … reason=fix-attempts-exhausted` WARN is logged once per (PR, head, reason); later cycles log it at debug. + +### Who may be pushed to: `all_authors` and the retired `fix_human_prs` push + +A review-fix kick tells the fixer agent to check out the PR branch and push a commit to it. That is fine on a PR one of the hive's own agents opened; on a contributor's fork (reachable through GitHub's "allow edits by maintainers") or a maintainer's branch it is a bot rewriting someone else's work before any person has looked at it. Reviewing and pushing are therefore separate: + +- Every open PR is **reviewed**, whoever opened it ([#12974](https://github.com/hivecommons/hive/issues/12974)). `review.all_authors` used to be the switch for this; it is now a deprecated no-op that is still accepted (so existing `hive.yaml` files load) and logged once at boot. Remove it. Being reviewed never implies being pushed to. +- `review.fix_human_prs` is retained as an audited refusal setting only. It no longer lets the fix kick be dispatched for a PR whose login author is **not** a hive agent/App (unless the hive adopted the PR in place, `stage/074-adopted-by-hive`): GitHub's squash attributes the landing commit to the PR author, so a hive follow-up commit can only pass "Sign-off survives the squash" by forging that author's `Signed-off-by`, which Hive must not do. +- `review.contributor_prs.base_sync` (default off) is narrower: it only lets PR follow-up call GitHub's update-branch API for a hive-authored lane PR whose head is in a contributor fork, whose base moved (`behind`/`dirty`), and whose author enabled "allow edits by maintainers". `behind` produces a GitHub-authored merge commit; `dirty` falls back to the base-moved repair note and kick. Fork pushes still do not pass through Hive, so stale-head prevention is a post-push note/kick rather than a true pre-push rejection. + +For PRs the hive did not author, the scanner never pushes new content or fixup commits: it comments with the proposed change (or a GitHub suggestion) and leaves the author to apply it. The only sanctioned writes are the base-sync above and hive-owned cleanup of a bad commit the hive itself already pushed, which must drop/amend that commit or re-home it through the adoption/DCO supersede path; governance and policy text is never changed without the author's or a maintainer's consent. + +Before every fix kick the planner checks authorship. A PR may be pushed to only when its author LOGIN is an agent (`github.ai_author` or a `[bot]` login). The audit-trail agent and the `-- hive:` attribution trailer are not consulted here: under a person login the squash is attributed to that person, so a hive-signed fix commit would be rejected by the squash sign-off gate as `bot-signoff` ([#12897](https://github.com/hivecommons/hive/issues/12897), [#13124](https://github.com/hivecommons/hive/issues/13124)). That fix is withheld, regardless of `fix_human_prs`, and proposed in the review instead; the contributor relay's `fix-pr` task is the channel that lands a correctly signed commit. The one person-login exception is a PR the stage reconciler adopted in place (`stage/074-adopted-by-hive`), where adoption is the explicit decision that the hive owns the branch and fixes it there. + +When the check refuses, the `changes_requested` verdict still stands and the review is still published (`post_comments`). The reviewer's kick for such a PR carries an extra instruction: no agent will push to this branch, so every fix it wants goes into the review comment as a ```` ```suggestion ```` block or a ```` ```diff ```` patch the author can apply, and the reviewer must not check out or push to the branch itself. The refusal is recorded once per PR head in dispatch state (`withheld_fixes`) and on the audit log as `review_fix_withheld`, with the PR, its author, and the setting's value at the time (`setting=review.fix_human_prs=<value>`; a reason naming the squash sign-off gate when it was on), so a fix that did not happen can be traced rather than guessed at. A new push to the PR is a new decision. + +**Upgrading.** Older configs may still show `fix_human_prs: true` because a prior compatibility rule promoted `all_authors: true`. Both values are left in config for audit/UI continuity — `all_authors` no longer does anything, and branch-push fix kicks still require hive authorship. + +### Cheaper model for bot-authored PRs (`review.bot_author_model`) + +PRs opened by other bots (Dependabot, Renovate, github-actions) are mostly lockfile and version bumps, and over Oct 13-27 2026 they cost $38.61/day across three hosted hives ($30.60/day on the busiest), every one reviewed on the frontier model. Setting `review.bot_author_model` routes those reviews to a cheaper model: + +- `review.bot_authors` is the login list. Entries match case-insensitively; a leading `*` matches a suffix, so the default `*[bot]` catches any GitHub App. The hive's own App login (`project.ai_author`, or the App's `[bot]` login when it authors PRs) never matches, whatever the list says: the hive's own PRs are reviewed as before. +- `review.bot_author_model` is `model` or `backend/model` (`gpt-6-luna`, `copilot/gemini-flash-3-5`). It replaces whatever the reviewer's `review_models` pool or `perspective_models` chose for that kick, the same way: the kick's independent-review instruction names it and the reviewer runs the review in a sub-agent with that `model`, so **the reviewer agent's engine must be able to launch it**. A pool decision to skip or hold for a human is kept. Recommended values from `pkg/tokens/pricing.go`: `gemini-flash-3-5` ($0.075/$0.30 per MTok) or `gpt-6-luna` ($0.10/$0.50), against `claude-fable-5.1` at $10/$50. Empty (the default) leaves the route off. +- `review.bot_author_full_review_paths` are globs (`**` spans directories; a pattern without `/` also matches the base name) that keep a bot PR on the full-strength model when any changed file matches. The default is CI workflows and Dockerfiles only; lockfiles are deliberately not excepted, since they are the bulk of bot PRs. Set it to `[]` for no exceptions. The planner lists the PR's files once per head (only for a listed bot's PR about to be reviewed) and a PR whose files could not be listed is **not** downgraded. + +Routed kicks carry `bot_author_routed` on the dispatch kick and the model lands in the verdict's `review_model` as usual; the governor logs `review routed bot-authored PR to bot_author_model`. The route applies to the swarm's per-perspective and combined kicks; the cadence (queue-mode) kick's `review_with=` annotation still comes from the agent's `review_models` pool alone. +### Delta re-review (`review.delta_rereview`, `review.delta_trivial_lines`, `review.delta_max_age`) + +A re-review is a review of a PR the hive already judged at an earlier head SHA. Over Oct 13-27 2026 re-reviews were 28% of hive's attributed reviewer spend and 53% of Bluefin's, because every one re-read the whole PR. With `review.delta_rereview` on (the default) the planner looks for the most recent verdict for the same PR at another head within the artifact's retention and, when it finds one, builds the kick differently: + +- The prompt opens with a **`DELTA RE-REVIEW`** block naming the previous head, when it was judged, the aggregate and per-perspective verdicts, and the exact `gh api repos/O/R/compare/<prev>...<new>` commands for the file list and the unified diff. It tells the reviewer to read only the hunks in that compare (and enough of their surroundings to judge them), to re-check each previous finding by file and line and say whether it is fixed, still present or no longer applies, and that its verdict is still for the whole PR at the new head. When the governor fetched the compare itself, the block also lists the changed files and line count. +- When the compare is known and the delta is **empty** (a force-push or rebase with the same tree), or under `review.delta_trivial_lines` changed lines (default 20) touching no file the previous verdict recorded a finding in, no reviewer is kicked: the previous aggregate is **re-stamped** onto the new head with the new `head_sha`, `body_digest` and `recorded_at`, a `delta` block (`previous_head`, `trivial: true`, `changed_lines`, `note`) and a `delta re-review: …` reason, and the governor logs `review delta re-stamped verdict without a session`. A negative `delta_trivial_lines` keeps the re-stamp for identical trees only. A head that already has a review in flight is never re-stamped. +- The **full** review stays for a first review (no prior verdict at another head), when the prior verdict was `reject` or `incomplete`, and when it was `changes_requested` with findings recorded more than `review.delta_max_age` ago (default `72h`): the flagged code has had time to move on and the record of it is stale. A verdict at the current head is never treated as a prior. + +Every delta aggregate records `delta.previous_head` (and `delta_previous_head` on each perspective report, stamped from the dispatch state like `review_model`), so the cost dashboard can split delta reviews, re-stamps and full reviews. The compare is fetched once per candidate head (no verdict, no pending entry, a prior at another head) with one 300-file page; a bigger or failed compare still gets the delta instruction, just without the file list and never the re-stamp. + +## Independent fact-check for analysis PRs (`review.analysis_factcheck`) + +The swarm's built-in perspectives are shaped around code diffs. On a PR that is an analysis or a report (a docs assessment, an audit write-up, a scored comparison) they judge the build, the layout and whether the diff matches the PR body, not whether the content is true. The fact-check pass is an opt-in second reviewer for that kind of PR: a different agent re-verifies what the author claimed, so a person reviews after an agent has already checked the work ([#19074](https://github.com/hivecommons/hive/issues/19074)). It is off by default and changes nothing for a hive that does not enable it. + +### Enable it + +```yaml +review: + analysis_factcheck: + enabled: true + author_agents: [quality] # agents whose PRs qualify; a PR also qualifies by label + labels: [] # e.g. [analysis]; matched case-insensitively on PRs an agent opened + reviewer_agents: [reviewer] # who may run the pass; default review.reviewer_agents, else role: reviewer + reviewer_model: "" # optional: pin the review to a model (a sub-agent runs with it) + independence: model # agent | model | family + max_rounds: 3 # author/reviewer rounds per PR (1-10) + ready_policy: human # human | hive + revision_wait: 6h # how long the author has to push a revision after findings + authoritative_files: [] # default: MAINTAINERS, MAINTAINERS.md, OWNERS, CODEOWNERS, .github/CODEOWNERS, .project/maintainers.yaml, GOVERNANCE.md + rubric: "" # extra guidance for the reviewer, e.g. where the scoring rubric lives +``` + +`enabled` with neither `author_agents` nor `labels` fails config load, because no PR would qualify. Nothing in the block names a project, a repository or a workflow: the qualifying agents and labels are the operator's choice. Candidates are the PRs your agents opened (owner from the audit trail's `agent_pr_created` entries), so it reaches repositories the hive does not manage; a PR a person opened is not enumerated. When the PR is also covered by the review swarm, the swarm is unchanged and the two run side by side. + +### What the reviewer does + +The sweep (every 5 minutes, off the eval cycle, no webhook needed) kicks one reviewer agent with a brief generalised from the prompt a maintainer used by hand to review a hive's analysis: check the work for quality and correctness against the sources and domains the request names, and give comments a person can verify, with file and line numbers. The reviewer: + +1. reads the PR body, the request issue it links and earlier work in the repository, to learn the sources, domains and scoring rules; +2. re-verifies every factual claim, score, grade and attribution against the cited source or live evidence, and compares with any authoritative external score; +3. checks each judgment for skew in both directions (a rating or a "standout" claim that is too positive, a gap or negative rating that is too negative); +4. checks that the material the analysis rates was actually inspected, and that a capability installed is not counted as delivered; +5. checks people, roles and approvals against the authoritative files, not against other prose; +6. posts **one review** with `hive-review`: a summary and line-anchored comments, in one notification. + +The reviewer is read-only. It never pushes, approves, requests changes, merges, labels, or changes the draft state. + +### Output format + +The summary opens with `**Fact-check: PASS | FINDINGS | INCONCLUSIVE** (round N of M, head <sha>)`, then a short judgement, `Re-verified:` and `Not verified:` lists, and ends with a hidden marker the hive reads: + +```text +<!-- hive:factcheck round=2 verdict=findings head=<full head sha> --> +``` + +Each inline comment is anchored on the line that makes the claim and has exactly this shape; a finding without all three parts is not posted: + +```text +**<claim | score | attribution | skew-positive | skew-negative | not-inspected | authority | scope>** what is wrong, quoting the claim, and what the evidence shows +Verify: <a link or an exact command a person can run> +Confidence: high | medium | low +``` + +PASS means no finding of high or medium confidence remains. INCONCLUSIVE means a material part could not be checked, and goes to a person rather than into another round. + +### Independence + +The author never reviews its own PR, whatever `reviewer_agents` lists (a replica such as `quality-2` counts as the author `quality`). `independence` sets how different the reviewer must be: + +- `agent`: a different agent. +- `model` (default): a different model id. The review's model is `reviewer_model` when set, else the reviewer agent's own model. +- `family`: a different model family (`claude`, `gpt`, `gemini`, ...). Two Claude models are the same family. + +Independence that cannot be shown is refused: where the level needs a model and either model is unknown, the reviewer is not used. When no candidate qualifies, the hive posts one hand-off note instead of reviewing, so a misconfigured lane is visible rather than silent. + +### Draft state + +The pass is built around the draft as an end point. A workflow that opens its deliverable as a draft keeps it a draft while the pass runs. `ready_policy: human` (default) leaves the draft-to-ready call to a person, who finds a PR that already carries a fact-check review. `ready_policy: hive` marks the PR ready for review after a PASS on the current head. The hive never marks a PR ready on any other verdict, on a marker from anyone but its own identity, on an older head, or after a person has reviewed, and it never moves a ready PR back to draft. + +### The author/reviewer loop, and how it stays bounded + +The review-feedback sweep (#19027) ignores bot comments so two agents can never answer each other forever, which means it would not carry the reviewer's findings to the author. This pass has its own bounded path instead: + +- The reviewer's findings are marked by the hidden marker above. Only a marker on the hive's own review counts; a marker typed by anyone else is ignored. +- On FINDINGS the author agent is kicked **once per head** with the review's text quoted as data to test, never instructions. It runs each `Verify:` link or command, fixes what is right in a signed revision on the same branch, and replies with evidence on what is wrong. It does not mark the PR ready. +- A new head starts the next round. Rounds are capped by `max_rounds`, counted from the hive's own persisted record and from marked reviews, whichever is higher, so a silent reviewer or a missing marker cannot extend the loop. +- The loop stops, with the PR left as it is, on a PASS; when `max_rounds` is reached; when the author does not push within `revision_wait`; on INCONCLUSIVE; when no independent reviewer exists; and as soon as a person has reviewed the PR (their review is the review; the feedback sweep routes what they say to the author). Every stop that needs a person posts exactly one note marked `<!-- hive:factcheck-needs-human -->`, and nothing more is done after it. +- The per-head review cap (`max_reviews_per_head`, one review per head in quiet mode) exempts a review that carries a valid fact-check marker, because this pass is asked to post a review on a head the swarm may already have covered. The pass bounds its own rounds. + +State lives in `/data/factcheck/state.json` (`HIVE_FACTCHECK_DIR` overrides it). A hive that cannot write it keeps counting in memory, and the marked reviews on the PR still bound the loop. + +## Review preflight (`review.preflight`) + +The reviewer reads the diff and the tree. Review preflight adds facts the hive gathers before the review starts, so a finding can rest on a rule the repository published or on an advisory id instead of on a hunch (hivecommons/hive#19069, #19106). It is a general mechanism: it works for any repository and language, and every part can be turned off. + +Hive-wide defaults live under `review.preflight`; a repository overrides them under `repos.<repo>.review_preflight`. Precedence per field is repo, then hive-wide, then the default. Lists replace (the repo's list wins, including `rule_doc_paths`) except `rules` and `ignore`, which add to the hive-wide entries (same `id`, or same `id` and `package`, is replaced by the repo's). + +```yaml +review: + preflight: + rule_docs: true # default on + # rule_doc_paths: ["handbook/**"] # optional explicit list; replaces discovery when set + rule_doc_exclude: ["CODEOWNERS"] # documents matching these are never listed + rule_doc_budget_bytes: 60000 # total bytes of rule documents one review reads (default 60000) + rules: # short named rules the reviewer enforces + - id: no-sleep-in-tests + severity: medium # low | medium | high | critical (default medium) + text: Tests must not use fixed sleeps; wait on a condition. + dependencies: false # default OFF, see "What leaves the hive" + vulnerabilities: true # default on when dependencies is on; OSV lookup + release_age: true # default on when dependencies is on; registry publish date, reported as a fact + offline: false # true (or HIVE_REVIEW_PREFLIGHT_OFFLINE=true) makes every lookup say "could not check: offline" + osv_url: https://api.osv.dev # point at an internal mirror if you run one + registry_urls: {npm: https://npm.mirror.example} # per ecosystem id, see the table below + # min_release_age_days: 7 # optional declared policy; unset (default) means no policy and no verdict on age + severity_floor: low # advisories below this are not listed (default low; unstated severity is always listed) + block_severity: high # advisories at or above this are in-scope blockers, lower ones are notes (default high) + cache_ttl: 6h # reuse registry and advisory answers (default 6h) + request_timeout: 10s # per outbound request (default 10s) + max_dependencies: 30 # lookups per PR; the rest are listed as not checked (default 30) + ignore: # accepted risks: a reason is required, expires is optional (YYYY-MM-DD) + - {id: GHSA-xxxx-xxxx-xxxx, package: example.com/lib, reason: "not reachable from our code", expires: "2027-03-01"} +repos: + widgets: + review_preflight: + dependencies: true + rules: + - {id: widgets-api, text: "Public handlers must validate input before use.", severity: high} +``` + +### Repository rules + +With `rule_docs` on, the hive does not guess what a repository calls its rule documents. It starts from the standard entry files the repository has at the PR's base commit, in this order: `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `CONTRIBUTING*` (also under `.github/` and `docs/`), `README` (`.md`, `.rst`, `.adoc` or none), `docs/README` and `docs/index` pages, and `CODEOWNERS` (root, `.github/`, `docs/`) for context. It reads each entry file and follows the repository-relative references in it: markdown links and reference definitions, HTML `href`s, reStructuredText links, links to this repository's own files on github.com, and bare file mentions such as `docs/rules.md`. A link to a directory resolves to its README or index page. Only Markdown, MDX, reStructuredText and AsciiDoc files are followed, so a README that mentions `LICENSE` or `requirements.txt` does not pull them in; references that leave the repository or name a missing file are skipped, and a file already found is not found again, so cycles end. + +Discovery is breadth first and deterministic: entry files first, then the documents they point to (depth 1), then the documents those point to (depth 2), each in the order the references appear. Each document gets a read allowance of at most a quarter of `rule_doc_budget_bytes`, at most 40 documents are listed, and documents past either bound are named as not listed, with how they were found. Every listed document says how the hive found it (`entry file`, `linked from CONTRIBUTING.md`, `mentioned in docs/README.md`), so the reviewer and the reader can see that the repository itself points there. A file the hive could not read is reported, and the reviewer is told to follow its references itself. `CODEOWNERS` is listed for context and never followed. + +`rule_doc_paths` is the owner's override: when set, those patterns (matched case-insensitively; a pattern without a slash matches at the root, `dir/**` matches any text file below `dir`) name the documents and discovery is skipped. A repository's list replaces the hive-wide one. `rule_doc_exclude` removes documents in either mode. + +Either way the reviewer must name the document and the rule it applied, and quote it; a finding that invokes a rule it did not read is a false positive. + +`rules` are the operator's own named rules, for conventions no document states. The reviewer enforces them at the stated severity and cites the id. + +### Dependency evidence + +With `dependencies` on, the hive reads the PR's changed manifests and, for each dependency version the diff adds or bumps, queries the vulnerability database and the package registry. The reviewer receives advisory ids with a normalized severity and publish dates, nothing else from those services (no free text), and is told to report only what is listed and to cite the id. A line that says `not checked` or `could not check` means no data, never a clean result. + +| Ecosystem id | Manifests | OSV ecosystem | Publish date from | +|---|---|---|---| +| `go` | `go.mod`, `go.sum` | Go | proxy.golang.org | +| `npm` | `package.json`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml` | npm | registry.npmjs.org | +| `pypi` | `requirements*.txt`, `pyproject.toml` (exact pins), `poetry.lock`, `uv.lock` | PyPI | pypi.org | +| `crates` | `Cargo.lock` | crates.io | crates.io | +| `maven` | `pom.xml`, `gradle.lockfile` | Maven | search.maven.org | +| `rubygems` | `Gemfile.lock` | RubyGems | rubygems.org | +| `packagist` | `composer.lock` | Packagist | repo.packagist.org | +| `nuget` | `packages.lock.json` | NuGet | api.nuget.org | +| `actions` | `.github/workflows/*.yml` (`uses:` with a full version tag) | GitHub Actions | not looked up | +| `container` | `Dockerfile*`, compose files | none | not looked up | + +A changed manifest of a kind that has no entry yet (Pipfile.lock, mix.lock, pubspec.lock, Package.resolved, Podfile.lock, bun and deno lockfiles, Chart.lock, flake.lock, Terraform and Bazel lockfiles, Conan, sbt) is reported as `Not checked`, as is a manifest whose patch GitHub withheld, an action pinned by SHA or a floating tag, and every dependency past `max_dependencies`. Only versions written in the diff are checked; transitive dependencies of a manifest without a lockfile are not resolved. + +**Adding an ecosystem** is a table entry plus a test: append an `Ecosystem` to `Ecosystems` in `src/pkg/reviewpreflight/ecosystems.go` (manifest patterns, a parser over the patch lines, the OSV ecosystem id, and an `Age` lookup with its default registry URL), add a case to `TestEcosystemParsers`, and add a row to the table above. + +**Release age is a fact, not a verdict.** There is no universal right minimum age: new versions carry the risk of a compromised release that has not been caught yet, and old pins carry the risk of known holes. So by default the hive reports each looked-up version's publish date ("published 2026-11-02 (16 days ago)") with no pass or fail, and tells the reviewer to apply a release-age policy only if the repository's own documents state one, quoting it. A hive owner who wants a policy declares it with `min_release_age_days` (hive-wide or per repo; a negative value in a repo clears a hive-wide policy for that repo); a version younger than a declared policy is marked against it and the reviewer cites the policy. + +**Noise control.** A vulnerable-dependency finding needs an advisory id from the list. `block_severity` decides which advisories are in-scope blockers (`changes_requested`) and which are notes; `severity_floor` hides low-severity noise. An accepted risk goes in `ignore` with a reason (required) and an expiry; an expired entry stops suppressing and the evidence says so. The id `release-age` with a `package` exempts that package from a declared release-age policy. + +### What leaves the hive, and how to turn it off + +- **Rule documents** use the GitHub API the hive already calls (one repository tree listing per PR head, plus one file read per followed document, at most 40). Nothing new leaves. Turn off with `rule_docs: false`. +- **Dependency checks are off by default** because they contact third-party services about a repository that may be private. When on, per changed dependency the hive sends: to OSV (`osv_url`, default api.osv.dev) the package name, ecosystem and version; to the registry (see the table, overridable with `registry_urls`) a GET for that package or version. No token, credential, repository name, PR text or source code is sent, and requests carry no `Authorization` header. Requests follow the hive's upstream proxy settings (`network.upstream_proxy`, `HTTPS_PROXY`). The services see the hive's egress IP and the dependency names of the PRs it reviews. +- **Offline or air-gapped:** set `offline: true` or `HIVE_REVIEW_PREFLIGHT_OFFLINE=true`; no request is made and the evidence says `could not check: offline`. An unreachable service, a timeout, a 429 or a 5xx degrades the same way, per check, with the reason. Answers are cached in memory for `cache_ttl`, and a PR head is looked up once. +- **Internal mirrors:** set `osv_url` and `registry_urls` to your own endpoints. +- **Disable entirely:** `dependencies: false` (the default), per repo with `repos.<repo>.review_preflight.dependencies: false`. + +### Understanding the change + +The correctness perspective (and a combined review that includes it) asks for understanding rather than a checklist of bug patterns: state the intended behavior change in the reviewer's own words from the diff and the PR description, trace the changed code paths and their callers, identify the invariants and contracts the change relies on or alters and check each, check that everything describing the behavior (comments, docs, messages, tests) still matches, and report only findings backed by concrete evidence from the code. It names no specific defect classes on purpose (#19106). + +## Revising a recorded verdict + +Dispatch skips any PR that already carries a verdict for its head SHA. That is the right default — it stops the reviewer re-reviewing unchanged code every sweep — but it also makes a review final the moment it is written, even when the reviewer itself was defective. Two settings, both required, re-open such verdicts narrowly: + +```yaml +review: + revise_repos: [org/repo] # allowlist; empty (default) = no repo may be revised + revise_verdicts_before: 2026-09-19T14:00:00Z # RFC 3339; only verdicts recorded before this instant +``` + +- `revise_repos` allowlists the repos whose reviews may be edited. Silently rewriting text a maintainer has already read is a power worth granting deliberately, per repo — so the empty default means the feature is entirely off. A `--revise` request for a repo that is not allowlisted is denied once (`.denied`, result `authorization denied: repo … is not allowlisted for in-place review revision`) rather than retried on every watcher pass (#13252). +- `revise_verdicts_before` re-opens PRs whose verdict was recorded before the cutoff even though their head SHA has not moved. The cutoff is self-limiting: a complete re-review records a fresh timestamp that is necessarily after it, so each PR is revisited at most once per bump rather than looping. An incomplete re-review of a head holding a settled `requires_human`, `changes_requested` or `reject` verdict is the one exception: the settled verdict and its original `recorded_at` are retained (see verdict-flow rule 6 above), so the PR remains revisitable until a re-review with full perspective coverage replaces it. When a revisit is due, the head's pending dispatch entries are cleared so every enabled perspective is asked again, and an in-flight guard stops a revisit whose verdict is still outstanding from being re-kicked every cycle. + +The correction **edits the hive's existing review in place** rather than posting a second one — editing notifies nobody, while a new review pings every subscriber. The reviewing agent requests this with `hive-review --revise` (alongside its usual body and verdict file). Three guards in the relay make the edit safe to point at someone else's repo, each pinned by a test: + +- only a review authored by the hive's own App login is ever touched (no login configured → fail closed); +- only `COMMENTED` reviews are edited, never `APPROVED` or `CHANGES_REQUESTED`, since rewriting those would retroactively change what a formal state says; +- an identical body (modulo whitespace) issues no write at all. + +Both keys are also writable at runtime through `PUT /api/config/review` (owner only). The cutoff is validated as RFC 3339, and the GitHub client's cached revise allowlist refreshes on write rather than at the next boot. + +## Measuring effectiveness + +Verdict counts say how much the reviewer did; they cannot say whether it helped. The **review-outcome ledger** (`/data/review-outcomes.json`, `pkg/review/outcomes.go`) answers the question the review gate exists for — *do reviewed PRs leave the queue faster than unreviewed ones?* — by keeping a control group. + +Every eval cycle, after the verdict artifact is refreshed, the hive: + +1. upserts every open PR the governor enumerated (repo, number, author, agent- or human-authored, first-seen time); +2. attaches the **earliest** review evidence it has for each — the verdict artifact's `recorded_at`, or the posted-review links ledger's `at` when a queue-lane review could not bind a verdict; +3. resolves PRs that left the list with one `GET /pulls/{n}` each (capped at 40 per cycle; the rest resolve next cycle) to `merged` or `closed`; +4. appends one daily queue snapshot (open count, open-and-reviewed count). + +A PR counts as **reviewed** only if the hive's first review landed *before* its outcome; a review posted after the merge is control, not treatment. Rows are kept for 90 days after resolution. + +Read it from: + +- **Dashboard** — Features → Review gate → *Effectiveness* → "Load 30-day outcomes": reviewed vs control on PRs, merged %, closed, still open, median first-seen→merge hours and merged-within-72h, plus the queue trend from the snapshots. +- **`GET /api/review/outcomes?days=N`** (1–90, default 30) — the full `OutcomeSummary`: `reviewed`, `unreviewed`, `by_verdict`, `agent_authored`, `human_authored`, `snapshots`. +- **`GET /api/reviewer/accuracy?days=N`** (1–90, default 30 or `HIVE_REVIEWER_ACCURACY_WINDOW_DAYS`) — reviewer verdict calibration: false-approve/false-block rates with sample counts plus confidence buckets per perspective and reviewer model. +- **`/metrics`** — `hive_review_outcome_prs{reviewed,outcome}` and `hive_review_outcome_median_hours_to_merge{reviewed}` over the 30-day window. + +Read the numbers with care: the cohorts are not randomised. The reviewer reaches PRs in queue order, so early on the reviewed cohort skews towards whatever it got to first. The comparison becomes meaningful once both cohorts have dozens of resolved PRs; until then treat it as directional. + +## Event-driven dispatch + +With webhooks configured, a pushed PR does not wait for the next governor cadence to be reviewed (hivecommons/hive#11091). The spoke's existing signed webhook receiver (`POST /api/webhook/github`) queues a review dispatch for `pull_request` deliveries with action `opened`, `reopened`, `synchronize`, `ready_for_review` or `review_requested` on an open, non-draft PR in a managed repository. + +- **Debounce.** A PR fires once it has been quiet for `review.event_debounce_s` (default `90`, max `3600`). Each new delivery restarts the window and replaces the head SHA, so a burst of pushes is reviewed once, at its final head; a PR pushed continuously still fires four windows after its first event. +- **Idempotency.** A head SHA that already fired is not queued again for 24 hours. The per-head perspective budget and dispatch state still stop a second review of the same head either way. +- **Bounded.** At most 256 PRs wait at once; further deliveries are dropped and counted, and the cadence tick reviews those PRs as before. Wakes are spaced at least 30 seconds apart, so many PRs pushed together cost one early cycle. +- **Same gates.** Firing wakes the governor for an early eval cycle with the fired PRs first in the review list. Head age, loop caps, ACMM, hold labels and `max_parallel_reviews` apply exactly as on a cadence tick. +- **Fallback.** The cadence path is unchanged and still covers hives without webhooks, missed deliveries and dropped events. + +`review.event_driven` unset means on exactly when `GITHUB_WEBHOOK_SECRET` is set; `false` turns it off, `true` forces it on. It never runs while `require_approval` or `fan_out` is off. + +```yaml +review: + event_driven: true + event_debounce_s: 90 +``` + +`GET /api/review/dispatch/events` lists pending and recent dispatches with their counters (received, queued, coalesced, duplicates, dropped, fired, wakes). Review pipeline cards carry `trigger`: `event` (a webhook dispatch fired for the current head), `event_pending` (one is queued), or `cadence` (the head has reviewers without an event dispatch). + +## Deferred work + +- Map aggregate verdicts to labels/comments (`hold`, `needs-human`, close recommendation) once fan-out exists. +- Add dashboard visibility for review verdict artifacts. The per-PR [review evidence bundle](/docs/hive/hub/review-evidence-bundle) (tracked in #11058) is the planned durable, downloadable record; see also the [SOC 2 control mapping](https://github.com/hivecommons/hive/blob/v5/src/docs/soc2-control-mapping.md) (not a compliance claim). diff --git a/docs/content/hive/sandbox-isolation.md b/docs/content/hive/sandbox-isolation.md new file mode 100644 index 0000000..95d593c --- /dev/null +++ b/docs/content/hive/sandbox-isolation.md @@ -0,0 +1,599 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/sandbox-isolation.md) during the docs build. Edit the canonical source in the Hive repository. + +# Credential-free sandbox isolation + +## Threat model + +Hive agents are untrusted code executors: prompts, tool output, and cloned repositories can all contain hostile instructions. The safe target is therefore **no credentials in the agent sandbox** and a network policy that is as close to default-deny as the configured inference runtime allows. + +Two halves of that target hold differently, and the difference matters: + +- **Credentials and pushes are constrained on every path.** No agent receives a GitHub token or pushes directly; authorship goes through the App-gated `gh` wrapper and the push broker. +- **Workspace write confinement depends on the launch path and backend.** The Podman sandbox below is the hub-side boundary. Contributor container mode has its own container boundary. In contributor local mode: claude/litellm and codex have OS-enforced sandboxes; copilot has its own OS-enforced sandbox, wired the same way, gated on the installed CLI actually supporting it; opencode has no sandbox but does get a command-name deny-list (a floor, not a boundary); goose, agy, bob, pi, aider, kilo, omp, openhands, and omnigent have **no confinement mechanism this repo can wire at all** and refuse to launch in local mode unless the operator explicitly opts in per backend. See the [per-backend matrix](#per-backend-confinement-on-the-contributor-local-path) below. + +**#4918 is what that costs in practice, and it did not require a compromise.** An agent doing correct work on an assigned third-party repo ran that repo's own test suite; a latent defect in two of its tests let a hook escape its stubs and issue `rpm-ostree kargs --append-if-missing=...` against the operator's real deployment. Nothing was written, and the only reason is that the process happened to lack privilege. Benign behaviour was a sufficient precondition, so this is a routine exposure rather than an exceptional one. + +The claude-family launch path carries host-state denials for exactly this class — privilege escalation (`sudo`, `pkexec`, `doas`, `su`) and the boot/deployment tools that reach polkit without needing escalation of their own (`rpm-ostree`, `bootc`, `ostree`, `grubby`, `bootctl`, `efibootmgr`). Those denials remain only a command-list floor. On the contributor local path, Claude Code's native sandbox is now the OS-enforced write boundary around them. + +## Which confinement is available depends on the path you are on + +This is the part that is easy to get wrong, because the two paths have different levers and only one of them has the Podman sandbox at all. + +| | Hub / pod agents (`pkg/agent`) | Contributor relay (`just contribute-hive`) | +|---|---|---| +| Runs where | The hive spoke's own container | The contributor's machine | +| Podman agent sandbox (`agent_sandbox`) | Available, opt-in — see below | **Does not exist on this path.** `SandboxEnabled` is read only by `pkg/agent`; nothing in `bin/contributor-relay.js`, `bin/contributor-agent.sh` or the `Justfile` consults it | +| The confinement lever | `agent_sandbox` + the per-agent opt-in | Container mode (the default), or a backend-native sandbox in local mode — see the matrix below, coverage varies by backend | +| Host-state denials (#4938) | Yes | Yes (`config/backends.conf`) | +| Credentials / pushes | Constrained | Constrained | + +Hub-launched Codex agents use `--dangerously-bypass-approvals-and-sandbox`, +mirroring Claude's unattended posture. The hub path already relies on the pod, +the optional Podman agent sandbox, the egress proxy, and Hive's mode gates as +the boundary; Codex's `workspace-write` sandbox is not used there because it +also disables the network path `gh`/`git` need through the proxy and would +replace one unattended posture with approval prompts in an unwatched pane. + +**The #4918 incident happened on the contributor relay's local mode**, so enabling `agent_sandbox` would not have prevented it. Claude-family local launches now use Claude Code's native sandbox with hard-fail startup and unsandboxed retry disabled; codex keeps its `workspace-write` sandbox; copilot local launches now use Copilot CLI's own OS-enforced sandbox. Container mode remains the stronger backend-independent remedy and the `just contribute-hive` default. + +Operators running hive on a machine they care about should therefore prefer container mode on the contributor path, use only a locally sandboxed (or, for opencode, at least denylisted) backend when local mode is necessary, and enable the sandbox below on the hub path. + +### Per-backend confinement on the contributor local path + +This table is the ground truth for `just contribute-hive <backend> local` — the only mode where "the operator's host" means a real desktop with no container boundary. Verified against each backend's own current CLI documentation, not assumed; see `config/backends.conf` for the implementation and `src/pkg/dashboard/contribute_local_mode_backend_matrix_test.go` for the tests that pin it. + +| Backend | Mechanism | What it actually bounds | Escape hatch (unconfined opt-in) | +|---|---|---|---| +| `claude` / `litellm` | Claude Code's native OS sandbox (`--settings` sandbox JSON; Seatbelt on macOS, bubblewrap on Linux) | Filesystem writes confined to the agent cwd, `HIVE_WORKSPACE_DIR`, and the hive-created build-cache root `HIVE_AGENT_CACHE_DIR` (#6100); `failIfUnavailable: true`, no unsandboxed fallback | `HIVE_CLAUDE_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1` | +| `codex` | Codex's own `--sandbox workspace-write` | Filesystem writes confined to the workspace root(s) codex is given | `HIVE_CODEX_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1` | +| `copilot` | Copilot CLI's own `--sandbox` flag (MXC: Seatbelt on macOS, bubblewrap on Linux, ProcessContainer on Windows Insiders) | Filesystem/network/process access of the commands and tools Copilot runs, restricted by the OS-level backend; `--add-dir` grants the exact workspace | `HIVE_COPILOT_DANGEROUSLY_BYPASS_SANDBOX=1`, or automatic fallback with a loud warning if the installed CLI predates `--sandbox` (copilot-cli < 1.0.60) | +| `muse` | Muse Code's own OS sandbox (bubblewrap/seccomp + namespaces on Linux, seatbelt/`sandbox-exec` on macOS), **on by default**; hive narrows it with `--workspace $HIVE_WORKSPACE_DIR`, `--sandbox-network proxy-only`, and `--no-foreign-personal-context` | Filesystem/network reach of the shell muse runs, bounded by the OS mechanism; `--workspace` roots its policy-gated workspace tools at the exact workspace. Approval is turned off with `--approval-mode never`, which is a *policy*, not the boundary — the sandbox stays on. `--no-foreign-personal-context` additionally stops muse loading the operator's own `~/.claude` personal skills into an unattended agent. | `HIVE_MUSE_DANGEROUSLY_BYPASS_APPROVALS_AND_SANDBOX=1` | +| `opencode` | opencode's own `permission.bash` deny rules (inline via `OPENCODE_PERMISSION`), denying the same host-state command family the claude deny-list covers | **Not a filesystem boundary.** A command-name floor only — anything not on the list, or reached another way, is unconstrained. Deny rules are documented to hold even under `--auto`. | `HIVE_OPENCODE_DANGEROUSLY_ALLOW_HOST_STATE=1` | +| `goose` | **None.** `GOOSE_MODE` (`auto`/`approve`/`chat`/`smart_approve`) governs interactive approval only; no mode confines writes to a directory, and only `auto` is usable unattended. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_GOOSE_DANGEROUSLY_RUN_UNCONFINED=1` | +| `agy` | **None.** Antigravity CLI's execution modes (`default`/`accept-edits`/`plan`) govern approval only, same shape as goose; `--dangerously-skip-permissions` is what hive already passes and there is no lesser mode that confines the filesystem. agy 1.1.22 also advertises `--sandbox`, but its binary's own strings point to Google's remote/cloud sandbox machinery (a `Sandbox` proto with a network endpoint+port), not a local OS boundary — treat it as unrelated to host confinement until verified otherwise. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_AGY_DANGEROUSLY_RUN_UNCONFINED=1` | +| `bob` | **None.** No sandbox, approval mode, or path-restriction mechanism documented anywhere in Bob Shell's own docs. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_BOB_DANGEROUSLY_RUN_UNCONFINED=1` | +| `pi` | **None.** `@earendil-works/pi-coding-agent` ships with no sandbox by default; directory confinement exists only via a third-party extension (`pi-permission-modes`) hive does not install or depend on. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_PI_DANGEROUSLY_RUN_UNCONFINED=1` | +| `aider` | **None.** No Docker/OS isolation option of any kind. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_AIDER_DANGEROUSLY_RUN_UNCONFINED=1` | +| `omp` | **None.** OMP exposes `--auto-approve`, but that controls confirmation prompts rather than filesystem or host-state confinement; Hive does not pass it on the interactive contributor path. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_OMP_DANGEROUSLY_RUN_UNCONFINED=1` | +| `claude-managed-agents` | Claude Managed Agents `self_hosted` worker in the Hive pod, with `forced-egress`/`proxy-only` and the extwork `shadow`/`report-only` gate | Tool traffic stays on Hive's egress path; the worker gets an environment key and per-session work secret, never `ANTHROPIC_API_KEY` or a GitHub write token | No direct GitHub path is accepted; `github_repository`, vaulted-secret, and GitHub-MCP rows remain report-only and are refused for write-capable stages | +| `openhands` | **None.** The bare `openhands` CLI runs the agent directly on the host (OpenHands' own README: "the agent will have full access to your filesystem!"); `--always-approve` governs approval only, and the Docker sandbox exists only behind `openhands serve`/Agent Canvas, which have no one-shot task shape hive can drive. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_OPENHANDS_DANGEROUSLY_RUN_UNCONFINED=1` | +| `omnigent` | **None.** Omnigent provides an orchestration and policy layer over Claude Code, Codex, Cursor, Pi, and custom agents, with optional agent-level sandboxing (`enforce_sandbox`), but the local CLI invocation (`omnigent run --server local`) runs directly on the host with no OS-level boundary wired by Hive. `--server local` keeps the Omnigent server inside the Hive boundary (remote-server mode is unsupported); its internal policies evaluate additively, while Hive's proxy remains strictly authoritative for all repository writes and pushes. | Nothing — local mode refuses to launch without explicit opt-in | `HIVE_OMNIGENT_DANGEROUSLY_RUN_UNCONFINED=1` | + +**The build-cache root, and why it is a grant rather than a hole (#6100).** Every +compiled toolchain writes to a cache under `$HOME` by default — `GOCACHE` at +`~/.cache/go-build`, `ccache`, `$TMPDIR` — and all of those sit outside the +workspace. So `go build`, `go test` and `go vet` failed on a hive contributor +task, in hive's own Go repo, with an error naming a cache file rather than a +sandbox boundary; eight local-mode sessions over five days each rediscovered it +and invented its own `GOCACHE` redirect. The launcher now creates +`${XDG_CACHE_HOME:-~/.cache}/hive/agent-build`, exports `GOCACHE`, `GOMODCACHE`, +`GOTMPDIR`, `TMPDIR` and `CCACHE_DIR` into it, and the sandbox grants it as a +write root. That is strictly narrower than widening the sandbox: one directory +hive owns, rather than `$HOME`. It is a **write root only** — deliberately not in +`permissions.allow` and not an `--add-dir`, because Bash is what compilers run +under, an agent has no reason to `Edit` a build cache, and adding it as a working +directory would put megabytes of object files in the agent's view of the tree. + +The backends with no mechanism (goose, agy, bob, pi, aider, kilo, omp, openhands, omnigent) are a hard stop, by design: `just contribute-hive <backend> local` prints an honest refusal and a non-zero exit rather than a silent unconfined launch, unless the operator sets that backend's own escape-hatch env var. This is deliberately not a blanket `HIVE_DANGEROUSLY_RUN_UNCONFINED` — a single shared flag would let opting into one unconfined backend silently opt into all nine. + +For `agy` specifically, this local-mode refusal used to be a dead end (#5048): `src/Dockerfile.contributor` never installed the `agy` binary, so container mode — the only real boundary any of these five backends can get on this path — was unavailable too, leaving no working path at all. That is now fixed: the image installs `agy` from Google's published, checksummed release tarball, so `just contribute-hive agy` (container mode, the default) actually works. Nothing above about agy's *local*-mode posture changed — it still has no sandbox and still refuses without the escape hatch, exactly like goose/bob/pi/aider. + + +### Omnigent policy composition with Hive + +Omnigent ships with its own policy engine and configurable guardrails (such as `github_policy`, `ask_on_os_tools`, and `enforce_sandbox`). When Omnigent is run under Hive: + +1. **Hive policy strictly wins on GitHub writes.** All repository writes, PR submissions (`POST /repos/{owner}/{repo}/pulls`), PR merges (`PUT /repos/{owner}/{repo}/pulls/{n}/merge`), and git pushes are mediated by Hive's egress proxy and GitHub App authentication broker. Proxy denials remain authoritative: Omnigent's internal policy engine or harness configuration cannot grant or bypass write permissions that Hive denies. +2. **Omnigent's sandbox is additive, never a substitute for Hive proxy or container isolation.** If an Omnigent agent spec configures `enforce_sandbox` (e.g. Linux bwrap or macOS seatbelt) or targets remote cloud sandboxes, this adds an extra layer of host isolation. However, Hive treats Omnigent as unconfined on the bare contributor local path because Hive does not wire or guarantee an OS-level boundary through CLI launch flags. +3. **Underlying harness credential flow.** Omnigent orchestrates underlying harnesses (Claude Code, Codex, Cursor, Pi). In Hive, provider credentials pass through ambient environment variables or staged configs, but repository write tokens are never exposed directly to the harnesses. + +### Codex in container mode is bounded by the container, not by `workspace-write` (#6653) + +The matrix above is about **local** mode, and codex's `workspace-write` entry there is unchanged. Container mode is different, and the difference was a bug for as long as the two shared one hard-coded flag. + +`--sandbox workspace-write` is implemented with bubblewrap, and bubblewrap's first act is to create an unprivileged user namespace. The contributor container runs under the runtime's default seccomp profile with nothing relaxed, which denies that syscall — so asking for `workspace-write` there did not produce a weaker sandbox, it produced **no working command at all**: every model-generated command died with `bwrap: No permissions to create a new namespace`, including both of Codex's patch-application paths, leaving the agent to rediscover a working edit mechanism by trial and error on each task. The error text also names a *host* sysctl, pointing operators at a machine that was never the problem. + +Hive now resolves the value instead of fixing it, on two independent checks made at launch: + +- **Does an outer boundary exist?** The root-owned `/etc/hive/contributor-mode` marker baked into `src/Dockerfile.contributor` — a file, not an env var, so an agent running as `dev` cannot forge it. +- **Can the nested sandbox actually work?** A direct `unshare --user --map-root-user` probe, the same capability bwrap needs. + +Only "container, and no user namespaces" falls back to `danger-full-access`, and it says so in one line on stderr. This is not a weakening: the container is the boundary on that path, and it is the same boundary that was already load-bearing. **Local mode is never downgraded** — there is no outer boundary there, so a blocked probe leaves `workspace-write` in place rather than widening access to the operator's host. An operator who would rather have the nested sandbox can relax the runtime (`--security-opt seccomp=unconfined`) and the probe restores `workspace-write` on its own; the contributor image now ships a real `bubblewrap`, so that path uses a distro-maintained binary instead of Codex's bundled fallback. `HIVE_CODEX_SANDBOX_MODE` pins a value and skips the probe entirely. + +## Current wiring + +Sandbox execution is opt-in and the tmux path remains unchanged for all agents unless **both** gates are set — the global one and a per-agent one: + +```yaml +agent_sandbox: + enabled: true + image: ghcr.io/example/hive-agent:latest + # Default is "restricted" so local/proxy inference can still work. + # Use "none" for non-inference/test runs that require full network isolation. + network_mode: restricted + timeout_s: 2700 + # Optional deterministic preflight before any push/PR; see the publish + # preflight note under "kick path" below. + publish: + verify: [] +agents: + scanner: + sandbox: + enabled: true +``` + +**Both gates are required, and the global one alone does nothing.** `agent_sandbox.enabled: true` with no per-agent `sandbox.enabled: true` sandboxes zero agents. That matters more than it reads, because the dashboard's Security tab writes *only* the global flag and is the only sandbox control the UI offers: an owner can turn "agent sandbox" on and, without the fix below, be told the setting was updated while every agent kept running unconfined. + +Hive logs an `agent sandbox posture` warning at boot and on every config reload when the sandbox is enabled globally but some or all agents are not opted in (`config.AgentSandboxGateWarnings`), and — as of the #4918 fix — the same diagnosis also reaches the dashboard itself: `GET /api/config/governor`'s `security.sandboxWarnings` array carries it, and the Security tab renders it both in the page's "Coherence warnings" box and as an inline warning directly beneath the sandbox toggle, naming which agents are still unconfined and the exact `sandbox: {enabled: true}` key that fixes it. The array is empty (and nothing renders) on the documented default — sandbox off globally — and on a fully opted-in hive, so the warning appears only when it is actionable. + +**The per-agent toggle writes a complete block, or refuses (#18525).** The dashboard General tab's **Run in sandbox** toggle (`PUT /api/config/agent/{name}/general` with `sandboxEnabled`) used to write `sandbox.enabled: true` and nothing else, so an agent turned on while `agent_sandbox` had no image fell back to Podman with no image and failed every kick with "sandbox image is not configured". Turning the toggle on now resolves the agent's effective block — its own `sandbox` fields first, then the `agent_sandbox` defaults — and: + +- when that block is complete (an image, a runtime hive has, and `job.workspace_claim` for the Job runtime), writes it with the image and runtime pinned and `enabled: true`; +- when the request names another agent with `copy_from` (the dashboard sends `sandboxCopyFrom`), copies that agent's complete block instead, **minus its `publish` block**: `publish.verify` commands are written for one repository's work, so the receiving agent keeps its own; +- otherwise refuses with HTTP 400 naming what is missing and the agents a block could be copied from. + +When the toggle is switched on, the General tab shows a **Sandbox settings from** picker: the `agent_sandbox` defaults when they are complete, plus every agent that already has a complete block. If neither exists it shows an inline error instead, and the save would be refused. `GET /api/config/agent/{name}` carries the inputs as `general.sandboxDefaultsProblem` (empty when the defaults are complete) and `general.sandboxCopySources`. Turning the toggle off keeps the block and only sets `enabled: false`. + +**Switching an agent into sandbox mode stops its tmux session.** A sandboxed agent never runs a CLI in tmux, but the session it had before the switch used to stay alive and keep the agent in `running`, so every governor kick was refused. When an agent's config changes it into sandbox mode (the toggle, a config reload, or the global gate turning on), the manager archives the session's scrollback as a kick log, reaps the CLI, kills the session and parks the agent in `idle`, and writes a `sandbox_mode_entered` audit line. A kick refused because the agent is still `running` now says which state is holding it: `a sandbox kick is already running`, or `agent has a live interactive session; sandbox kicks are blocked until it stops`. + +The second gate is deliberate rather than an oversight, and it is not safe to simply collapse. A sandboxed agent runs a different execution model — no tmux CLI at all, and every kick is a Podman run against the primary repo — and `startSandboxKickLocked` has **no fallback to the tmux path**: an agent opted in without a resolvable image fails every kick outright rather than degrading. Making the global flag sufficient would therefore convert working agents into permanently failing ones on any hive that set it without an image. Changing that default is a fleet-affecting decision that wants measurement, not a code-reading; the warning above is the part that is safe today. + +**Cline's provider capability is separate from the Git workspace.** Its bounded +worker uses dedicated provider Secrets through existing `job.env_from_secrets` +for Jobs, or an opaque, per-run selected-provider file mounted `ro,Z` outside +the workspace for Podman. The latter requires an explicit absolute +`HIVE_CLINE_CONFIG_DIR`; it does not grant arbitrary host mounts, share the full +operator config, or change other engines' mounts. Private UID-owned tmpfs state, +container teardown and staged-file revocation/cleanup are part of that scoped +capability. GitHub credentials still never enter. No silent tmux fallback, +expanded credential environment allowlist, or confinement bypass is provided. +See [Cline sandbox setup](/docs/hive/integrations/cline#disposable-sandbox-kicks). + +For sandboxed agents, a kick now follows this path: + +1. Hive prepares a per-kick host workspace under the sandbox workspace root by cloning/fetching the primary repo with hive-owned credentials before the sandbox starts. The clone URL and sandbox environment are sanitized so GitHub/token variables are not carried into the workspace or container. +2. Hive writes the kick prompt to `.hive/kick-prompt.txt` in the workspace and launches `pkg/sandbox.Launcher` with a rootless Podman `LaunchSpec`, workspace mount, explicit env allowlist, and configured network mode. +3. The manager marks the agent busy while the sandbox runs and returns it to idle or failed when the timeout/completion path finishes. Because the agent sits in `idle` between kicks, dashboard health for sandboxed agents comes from the last-run record rather than the session check; see [Health and metrics](#health-and-metrics-for-sandboxed-agents). +4. Hive collects the transcript at `.hive/sandbox-transcript.log` and any `agent-report*.json` artifact following `pkg/outputschema` conventions. The container's captured stdout/stderr is also archived as the kick's log under the kick-log directory (`<kick_log_dir>/<agent>/<kick-start>-sandbox.log`, same retention as tmux kick logs — see [Agent logging](/docs/hive/operations/agent-and-governor-controls/agent-peer-awareness-logging#per-kick-log-history)). That archive, not the workspace transcript, is what the card's "full log" / "log text" buttons and the 🕘 kick history serve for a sandboxed agent, because the workspace is swept after two hours and a Job's pod is gone as soon as it completes. + **Publish gate.** Commits alone do not earn a PR. If the agent's report carries `"status": "failed"` or `"status": "blocked"`, or the sandbox exited non-zero, hive leaves the branch local, opens no PR, records the run as failed with the reason in `prWithheld` (shown on the card as "no PR opened: …"), and writes a `sandbox_pr_withheld` audit line naming the workspace, commit count and branch. The `status` field is optional; a report without one, or no report at all, does not block publishing, so agents that predate the field behave as before. Kick templates for sandboxed agents whose work must build or pass a smoke test before it is worth a PR should tell the agent to write `"status": "failed"` (with the failure in `summary`) instead of committing when that step fails. + **Publish preflight (`publish.verify`).** The report gate trusts the agent; the preflight is a determinism/regression check over the agent's own tree. When the run left commits and the gate above passed, hive runs each configured verify command — `sandbox.publish.verify` per agent or `agent_sandbox.publish.verify` globally — as `sh -lc <cmd>` in a fresh container/Job of the same image, workspace, env allowlist and network mode, with `HIVE_CHANGED_FILES` and `HIVE_CHANGED_TESTS` (newline-separated paths from the run's commits, base..HEAD) and `HIVE_BASE_SHA` exported. The first non-zero exit, launcher error or timeout (`publish.verify_timeout_s`, default 900 s per command) withholds the push and the PR exactly like a failed report: `prWithheld` reads `verify failed (1/2): <cmd> (exit N)` followed by the command's output tail, the card shows the first line with the tail in its tooltip, and the kick log archive gets a `---- verify: <cmd> (exit N) ----` section with the full output. With no commits there is nothing to publish and the preflight is skipped; with no commands configured it is a no-op. Typical use is a whole-suite `pytest --collect-only -q` plus running the tests the agent added — the two checks that would have caught a test-file basename clash that broke collection for an entire repository ([torch-spyre/spyre-inference#1412](https://github.com/torch-spyre/spyre-inference/pull/1412)): + > **Note:** Config is the only source of verify commands. A `<!-- hive:publish.verify … -->` block in a kick message is logged and ignored: the rendered message interpolates issue and PR titles, knowledge facts and delegated prompts, and none of that text may pick the commands that run against the agent's tree before it is pushed. + > + > **Note:** `publish.verify` runs the verify commands in the run's workspace at HEAD, so test-runner configuration the agent committed (conftest.py, pytest.ini, Makefile) is executed as-is. This is a determinism check, not an integrity gate; if stronger guarantees are needed, runner config can be reset to `HIVE_BASE_SHA` before verify in a future hardening. + + ```yaml + agents: + quality: + sandbox: + enabled: true + runtime: job + publish: + verify: + - uv run --no-sync pytest --collect-only -q + - sh -c '[ -z "$HIVE_CHANGED_TESTS" ] || uv run --no-sync pytest $HIVE_CHANGED_TESTS -q' + verify_timeout_s: 900 + ``` + +5. If the sandbox produced commits, `pkg/pushbroker.Broker` scans the committed diff for token-like secrets and protected-path edits, mints a short-lived scoped GitHub App token outside the sandbox, pushes the branch, and opens a PR through the existing App-authored GitHub client. Broker rejection records audit detail and nothing is pushed. + The PR title and body come from `.hive/pr-title.txt` (first line) and `.hive/pr-body.md` if the agent wrote them in the workspace, otherwise from the HEAD commit's subject and body; a generic `[<agent>] sandbox changes` placeholder is used only when neither exists. Kick templates for sandboxed agents should ask the agent to write those two files. + **The PR is credited to the agent** ([#18575](https://github.com/hivecommons/hive/issues/18575)). Hive records the PR the same way it records one an agent opens from its pane through the pr-request relay: the `-- hive: agent=<name> …` attribution trailer on the body (when `governor.attribution_trailer` is on) and an `agent_pr_created` audit entry for `repo=<owner/name>, number=<n>`, plus `via=sandbox`. Every governor path that maps a PR to its agent reads that entry: the FIX-BEFORE-NEW block, the red-CI webhook kick, the review-thread monitor and held-PR routing. Red CI on a sandbox PR therefore kicks the agent that opened it, not `scanner`. When the PR client cannot record the entry itself (the sidecar runtime's callback adapter), the runtime emits the same `agent_pr_created` entry through the sandbox audit callback, so the PR is still credited, without the trailer. As a last resort, the governor also reads the agent out of the work branch name, `hive/<agent>/<yyyymmddhhmmss>`. + +### Fix kicks on an existing PR + +A sandboxed fix kick can add commits to one of the agent's own open PRs instead of opening a new one ([#18574](https://github.com/hivecommons/hive/issues/18574)). Hive picks the target from hive-written parts of the kick message. The first match wins: + +1. An explicit `[hive:target-pr <owner>/<repo>#<n>]` first line (after an optional `[agent:<name>]` line). +2. The first line of the targeted red-PR kick, `🔴 FIX-BEFORE-NEW — <owner>/<repo>#<n> is red and has not moved`. +3. The first line of the red-CI webhook kick, `CI failed on <owner>/<repo>#<n> (<check>) …`. +4. The first row of the kick's FIX-BEFORE-NEW block (`## 🔴 FIX-BEFORE-NEW — your open PRs with failing CI or merge conflicts`). An adopted contributor PR is skipped. +5. The agent's topic claim, when the kick's topic-claims block lists exactly one PR. With several claims the kick does not say which topic it is for, so it opens a new PR as before. + +A target in another repository is ignored, because the workspace clones the primary repo only. The kick needs push rights (ACMM `CanPush` and `project.prs_allowed`) and a PR client that can read PR targets: the in-process hive client can, and the sidecar's callback adapter cannot yet. Without one, hive logs a warning and the kick opens a new PR as before. Review kicks and run-stage kicks never get a target. + +**Workspace prep.** Hive reads the PR and checks it before the sandbox starts. The PR must be open. Its head branch must live in the kick's repository, so a fork PR is refused. The PR's `agent_pr_created` record must credit it to this agent. If that record is older than the audit log's 90-day lookback, hive reads the body's attribution trailer instead, but only on a PR the hive's App authored. Hive then fetches `+refs/heads/<head>:refs/remotes/origin/<head>` with the clone token and checks the head out on `<head>`. If the fetched commit differs from the head GitHub reported, the kick is refused. Hive also prepends a `[hive:sandbox-target-pr]` section to the prompt. It names the PR, branch and head commit, and tells the agent to commit on top, without rebasing or opening a PR. The run's commits are counted from that head. + +**The push.** After the publish gate and `publish.verify`, hive reads the PR again. It must still pass every check above, keep the same head branch, and sit at the same head commit. The broker then runs its usual empty-commit, sign-off, protected-path and secret scans over the kick's own commits only (`base = <checked-out head>`). It also requires those commits to descend from the checked-out head. It pushes `HEAD:refs/heads/<head>` with `--force-with-lease=refs/heads/<head>:<checked-out head>`, so the push lands only if the remote branch still points at that commit. Together these make the push a fast-forward of exactly the head the kick started from: it never overwrites a commit someone else pushed. No new PR is opened. The run record's PR link is the existing PR, and `sandbox_complete` carries `target_pr=<n>`. + +**Refusals fail the kick and push nothing.** A closed PR, a fork PR, a PR another agent opened, a PR no hive agent opened, a head that moved since checkout, an unreadable PR or a failed scan all fail the kick with a reason that names the PR. The run record carries the reason, and the audit log gets a `sandbox_target_pr_refused` line with `repo=`, `number=`, `source=` and `reason=`, or the broker's usual `sandbox_broker_rejected`. If the refusal comes after the run, the commits stay in the workspace, and the run record notes them as withheld. + +## Setting up a sandbox from the dashboard + +Nothing about a sandbox needs a hand edit of the config files (hivecommons/hive#18797). Everything below saves through the normal config API, which writes both `/data/hive.yaml.runtime` and `/data/hive.yaml.dashboard`. + +- **Hive-wide defaults.** Settings, Security, "Advanced sandbox: default image and Job settings" edits `agent_sandbox.image`, `runtime`, the Job defaults (workspace claim and mount, service account, scheduler name, TTL) and `agent_sandbox.job.env_from_secrets`. The section opens by itself when the sandbox is on and no image is set. API: `PUT /api/config/governor/security` with `agentSandboxImage`, `agentSandboxRuntime`, `agentSandboxJobWorkspaceClaim`, `agentSandboxJobEnvFromSecrets` and the other `agentSandbox*` keys. +- **One agent.** The agent's General tab has "Sandbox settings: image, runtime and Job" with its own `sandbox.image`, `sandbox.runtime` and Job fields. A blank field inherits the hive default, shown as the placeholder. API: `PUT /api/config/agent/<name>/general` with `sandboxImage`, `sandboxRuntime` and `sandboxJob` (`workspaceClaim`, `workspaceClaimMount`, `serviceAccount`, `schedulerName`, `ttlSeconds`, `envFromSecrets`). Node selector, tolerations, resources and volumes have no field; they travel with the copy action below and survive an edit. +- **Copy from another agent.** "Copy sandbox settings from..." lists the agents whose block is complete (an image and a usable runtime, plus a workspace claim for `runtime: job`) and copies the block, turning the sandbox on. API: `PUT /api/config/agent/<name>/general` with `{"sandboxCopyFrom": "<agent>"}`. The copy is deep. The source's `publish.verify` commands are not copied (they are written for the source's repository); the receiving agent keeps its own. +- **Secrets are names only.** `env_from_secrets` holds Kubernetes Secret names. The API refuses anything that is not a valid name (a `KEY=value` pair, for one), so a value can never be written to the config file through these controls. +- **Refused without an image.** Turning the sandbox on, or saving an enabled sandbox, when no image resolves from the agent or `agent_sandbox.image` is refused with 400 and a message naming `sandbox.image` and `agent_sandbox.image`. The "no sandbox image" warning on the agent card and in the General tab links to the agent's Sandbox settings and to the default image controls. + +## Running sandboxed kicks as Kubernetes Jobs + +`sandbox.runtime: job` runs an agent's sandboxed kicks as a Kubernetes `Job` in the hive's own namespace instead of a rootless Podman container on the hive pod's node ([#6311](https://github.com/hivecommons/hive/issues/6311)). It exists for work that must run in a **different runtime than the hive image** - a different base OS, a heavyweight toolchain, or on **accelerator hardware** reached through a device plugin - while hive stays the orchestrator. + +Everything above about the kick path still holds. Hive prepares the workspace on its own data PVC, writes the prompt, and after the Job exits reads the commits back and hands them to the push broker and PR path. Only step 2 changes: the launcher is `pkg/kubejob` instead of Podman. + +```yaml +agent_sandbox: + enabled: true + job: + workspace_claim: hive-data # the PVC hive's /data lives on + workspace_claim_mount: /data # where hive sees it (default) +agents: + deps: + sandbox: + enabled: true + runtime: job + image: registry.example/project-dev:latest + job: + node_selector: { accelerator: spyre } + resources: + limits: { "vendor.com/device": "2" } + tolerations: + - { key: accelerator, operator: Exists, effect: NoSchedule } + scheduler_name: spyre-scheduler # only if the cluster's admission webhook requires a custom scheduler for device pods + env_from_secrets: [ artifact-registry ] + volumes: + - { name: cache, claim: compile-cache, mount_path: /cache } + ttl_seconds: 3600 +``` + +To run on any Spyre node except a known bad host, add Kubernetes node affinity +under `job` (replace `bad-spyre-node` with the node's actual hostname): + +```yaml +agent_sandbox: + job: + node_selector: { accelerator: spyre } + affinity: + nodeAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/hostname + operator: NotIn + values: [bad-spyre-node] +``` + +The node selector and required node affinity both have to match. Do not pin +`node_selector` to a particular `kubernetes.io/hostname` if the Job should +move among Spyre nodes; a hostname selector can restrict it to one node or +conflict with the exclusion and leave the Job pending. If using a custom +`scheduler_name`, ensure that scheduler honors Kubernetes `nodeAffinity`; +otherwise the exclusion is not guaranteed. + +### Node preflight and failing fast on an unschedulable Job + +Two checks keep a bad or missing node from costing a whole kick ([#18811](https://github.com/hivecommons/hive/issues/18811)). Both are for `runtime: job`. + +**`sandbox.preflight`: a node health check before the agent starts.** An accelerator card can be unusable on one node (a VFIO mmap failure, a crashed device) while the pod starts fine; without a check hive learns that only when the agent's own tests fail, minutes in. `preflight.commands` is a list of shell commands run in the Job's main container after hive's relay check and before the agent, in the same image, workspace and environment. Each runs as `sh -lc <cmd>`, like `publish.verify`, under `timeout_s` (default 120 s) and a `total_timeout_s` for the whole list (default 300 s). It is off unless `commands` is set, per agent (`agents.<name>.sandbox.preflight`) or hive-wide (`agent_sandbox.preflight`); an agent's block replaces the global one, and an empty `commands` there turns it off for that agent. Timeouts left at zero fall back to the global block, then the defaults. + +```yaml +agent_sandbox: + preflight: + commands: + # A device smoke test: fails on a node whose Spyre card is unusable. + - python -c 'import torch; torch.ones(1).to("spyre")' + timeout_s: 120 # per command + total_timeout_s: 300 # all commands + retry_delay_s: 0 # wait before the retry on another node; 0 = immediately +``` + +A failing command ends the container in seconds with exit code 75 after printing `hive-node-preflight: FAILED command 1 of 1 exited 1: <cmd>`, and hive reports the kick as `node_unhealthy`: + +- The command's output is in the kick transcript and the kick log, the run record carries `failReason: node_unhealthy` and the `node` the pod ran on (`spec.nodeName`), and the audit log names the node (`sandbox_node_unhealthy`). +- It is **not an agent failure.** The agent never ran, so it returns to `idle` rather than `failed`, nothing that watches failed agents (restart, escalation, a failure-fix loop) sees it, and the next cadence tries again. The dashboard shows `node unhealthy` with the node, distinct from `last run failed`. +- **One retry on another node.** Hive re-creates the Job once, after `retry_delay_s`, with a node-affinity `NotIn` on `kubernetes.io/hostname` for the failed node, added to every required term of the `affinity` above and never pinning a node (`sandbox_node_unhealthy_retry` in the audit log; the first attempt's output is kept at the top of the transcript). If the retry fails its preflight too, the kick fails as `node_unhealthy`. A cluster whose node names differ from the `kubernetes.io/hostname` label, or a custom `scheduler_name` that ignores node affinity, cannot honor the exclusion. + +The commands come from configuration only, never from a kick message, like `publish.verify`. They are part of the Job manifest and their output is in the pod log, so never put a credential on a command line; the script prints nothing from the environment. A preflight set for a runtime other than `job` is logged and ignored, and only agent kicks run it (the `publish.verify` Jobs do not). + +**`job.schedule_timeout_s`: fail fast when no node takes the pod.** While waiting on the Job, hive also reads its pod. If the pod stays `PodScheduled=False` with reason `Unschedulable` for `schedule_timeout_s` (default 600 s, in `job`, with the global value as the fallback for an agent's own `job` block), hive fails the kick as `waiting_for_node` with the scheduler's message (for example `0/38 nodes are available: ...`), deletes the Job and releases the agent, instead of holding its slot for the whole kick timeout plus the cluster-side deadline margin. There is no retry; the next cadence tries again. While it waits the dashboard shows `Job waiting for a node` with the scheduler's message, distinct from `Job running`, and the audit log records `sandbox_waiting_for_node`, then `sandbox_waiting_for_node_failed` if it gives up. If your cluster autoscaler needs longer than ten minutes to add an accelerator node, raise `schedule_timeout_s`; the kick timeout still bounds the wait. + +| Reason | Meaning | What to check | +|--------|---------|---------------| +| `node_unhealthy` | `preflight` failed on the node, and again on the retry node | The command's output in the kick log; the node named in the run record; cordon or fix the node | +| `waiting_for_node` | the pod stayed Unschedulable past `schedule_timeout_s` | The scheduler's message in the kick log: `node_selector`, `affinity`, `tolerations`, device `resources` and `scheduler_name` against the cluster's nodes; a retry excluding the only fitting node ends here | + +**Workspace transport is a shared claim, not a copy.** The Job mounts `workspace_claim` with a `subPath` pointing at the per-kick workspace, at the same `/workspace` mount the Podman launcher uses. The sandbox `workspace_dir` must therefore live under `workspace_claim_mount` (it does by default: `/data/agents/sandbox`). When the Job is scheduled onto a different node than hive, which is the whole point of a node selector, the claim must be **ReadWriteMany**. Hive cannot check the access mode from inside its pod; a Job that fails to start with a multi-attach error is the symptom. + +**The credential boundary.** The Job receives exactly the Secrets named in `env_from_secrets`, resolved by Kubernetes from the pod template; hive never reads them. Environment variables from the allowlist are copied in with the same credential-name filter Podman applies. An allowlisted `ANTHROPIC_BASE_URL` that points at a pod-local proxy (such as `127.0.0.1:18444`) is not reachable from a Job pod, so operators must supply a routable endpoint or model credentials via `env_from_secrets`. Hive's brokered GitHub token **never enters the Job**, so a Job cannot push or open a PR itself; hive does both from the returned workspace, with the same scan and scoped-token minting as the Podman path. If a workload needs its own registry or model credentials, they go in a Secret named here, and they are that workload's to protect. + +**What the operator sees.** The kick shows on the agent card like any sandboxed kick, with the runtime named in the output buffer and the audit line. The pod log is the transcript — hive collects it before the Job is deleted and archives it as the kick log, so "full log" on the card and the kick history keep working after the Job is gone — the container exit code is the sandbox exit code, and the kick timeout deletes a Job that is still running. A Job that **failed** is left in place until `ttl_seconds` (default one hour) so `kubectl describe job` and `kubectl logs` still work; a completed Job is deleted at once. Jobs carry the label `app.kubernetes.io/managed-by=hive-kubejob`. + +**Orphaned Jobs fail and are reaped (#18525).** The kick timeout lives in hive's memory, so a hive restart mid-kick used to leave its Job with no owner, and `ttl_seconds` only applies after a Job finishes; one Job sat `Pending` for 11 days. Two backstops now cover that: + +- Every Job carries `activeDeadlineSeconds`: the kick timeout (`timeout_s`, default 45 minutes) plus a fixed 15-minute margin (`kubejob.DeadlineMargin`), or the run's own context deadline plus the margin when that is later. Hive's own timeout always fires first; the deadline makes the cluster fail a Job that is still `Pending`, `Unschedulable` or running once hive has lost track of it. +- At boot, when any agent (or `agent_sandbox`) selects the Job runtime, hive lists the Jobs labelled `app.kubernetes.io/managed-by=hive-kubejob` in its namespace and deletes each unfinished agent-sandbox Job (`hive-<agent>-sandbox` kicks and `hive-<agent>-verify` preflights) that no live kick owns and that is older than the longest Job-runtime kick timeout, plus any that never got a ready pod and are past the deadline. Each one is logged (`audit: reaped orphaned sandbox job`) and recorded in the audit log as `sandbox_job_reaped`. Finished Jobs are left to `ttl_seconds`; Jobs without the label, and contained runs (`crux-run-<id>`), are never touched. The sweep uses the same `list` and `delete` grants on `batch/jobs` as the launcher. + +**The terminal pane.** A job-runtime agent has no tmux session in the hive pod, so the dashboard's ▶ terminal does not attach ttyd for it. Instead it opens `/terminal/job/<agent>`, a read-only viewer that streams the newest Job pod's log through the same in-cluster client and RBAC the launcher already uses ([#14798](https://github.com/hivecommons/hive/issues/14798)): it follows the pod while the kick runs (waiting while the pod is `Pending`, e.g. for an accelerator node), prints the container exit code when it ends, and between kicks, when the completed Job has already been deleted, shows the last run's persisted transcript (`<workspace>/.hive/sandbox-transcript.log`, which now ends with an `exit code: N` line) or a clear "no sandbox run yet" state. The pane is observation only; there is no input path into the Job. The same terminal handoff and role check as the tmux pane apply. + +**Private-registry images (#18819).** The Job pod's `imagePullSecrets` are the deduplicated union, in this order, of: hive's own pod secrets (so the `hive-relays` init container can pull the hive image), the Job service account's `imagePullSecrets`, and `sandbox.job.image_pull_secrets`. Kubernetes adds a service account's pull secrets only to a pod that has none of its own, so hive reads the service account through the API (`get serviceaccounts`) and merges the names itself. When that grant is missing or the read fails, hive logs a warning and carries on with the other two lists; it never fails the kick. `image_pull_secrets` holds Secret **names** only (DNS-1123 names, at most 32; a value is refused). A per-agent `job` block that names none inherits the `agent_sandbox.job` list. Hive reads, logs and writes names, never Secret contents. When `service_account` is set and `image_pull_secrets` is not, the boot and reload warning reminds the operator to set it if the grant is absent. The dashboard sandbox controls do not carry this field yet; the per-agent API accepts `sandboxJob.imagePullSecrets`. + +```yaml +agent_sandbox: + job: + service_account: hive-spyre-job + image_pull_secrets: [ registry-pull ] +``` + +**Authenticated GitHub reads for Jobs (#18865).** A Job runs in its own pod, so by default every `api.github.com` call it makes is anonymous: GitHub allows 60 requests per hour per source IP, shared by every agent on the node, and `uv lock --upgrade` on a repo with git dependencies falls back to full clones when the API call fails. The opt-in GitHub read relay fixes that without giving the Job a credential. Default off: + +```yaml +agent_sandbox: + job: + github_read_proxy: + enabled: true + listen_addr: ":8443" # required when enabled; there is no default + endpoint: https://hive.hive-system.svc:8443 # how Job pods reach hive; required, https only + no_proxy: [ models.internal.example ] # optional extra direct hosts +``` + +The feature is **off by default**. When `enabled` is true, `listen_addr` is required (there is no default bind, so hive never opens a port you did not name) and `endpoint` must be `https://`; config validation fails with an error naming the key otherwise. With it on, hive listens on `listen_addr`, **serving TLS only** with a certificate issued by hive's existing proxy CA for the `endpoint` host (a DNS or IP SAN; no new CA, and no CA key is written anywhere new), and every `sandbox.runtime: job` kick (the agent run, not the `publish.verify` preflights) gets `HTTPS_PROXY` set to `endpoint` (an `https://` proxy URL) with a **per-kick relay key**, plus `SSL_CERT_FILE`, `GIT_SSL_CAINFO`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE` and `NODE_EXTRA_CA_CERTS` pointing at a trust bundle hive writes to `<workspace>/.hive/github-read-ca.pem` (the system roots plus hive's proxy CA, so the Job still trusts the real internet). `localhost`, `.svc` and `.cluster.local` bypass the relay. The block is read from `agent_sandbox.job` only; a per-agent `job` block cannot enable or repoint it. You must expose the listener to the Job pods yourself: a Service for `listen_addr`, and a NetworkPolicy allowing only the Job pods to reach it. + +**Two layers guard the listener.** The first is the NetworkPolicy: it decides which pods can open a connection to the relay port at all. The second is the per-kick relay key: a connection that gets through must still present a live key, or it gets a 407 and nothing else. The key is random per kick, held by hive only as a hash, never logged, and revoked when the kick ends. Because the listener serves TLS only, the key never crosses the pod network in cleartext, and a plain-HTTP connection is dropped before any proxy handling. Example NetworkPolicy, applied in hive's namespace, allowing ingress on the relay port only from pods in the Jobs' namespace (replace the placeholders): + +```yaml +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: hive-github-read-relay + namespace: <hive-namespace> +spec: + podSelector: + matchLabels: + <label-selecting-the-hive-pod>: <value> + policyTypes: [ Ingress ] + ingress: + - from: + - namespaceSelector: + matchLabels: + kubernetes.io/metadata.name: <jobs-namespace> + podSelector: + matchLabels: + app.kubernetes.io/managed-by: hive-kubejob + ports: + - protocol: TCP + port: 8443 # your listen_addr port +``` + +Client support for an `https://` proxy URL varies. Go, Node (through its proxy agents) and libcurl 7.52 or newer (curl, and git built on it) can speak TLS to a proxy. libcurl checks an https proxy against its own CA setting rather than the origin's, so hive also sets `http.proxySSLCAInfo` through `GIT_CONFIG_COUNT`/`GIT_CONFIG_KEY_0`/`GIT_CONFIG_VALUE_0` (skipped when the Job already defines `GIT_CONFIG_COUNT`). Some clients, for example Python HTTP stacks built on urllib3 older than 2.0, cannot speak TLS to a proxy; for those the Job's reads go out anonymously, as without the relay. Hive does not downgrade to a cleartext proxy for them. + +What the relay does: + +| Host | Request | What hive does | +|---|---|---| +| `api.github.com`, `codeload.github.com`, `raw.githubusercontent.com` | `GET`, `HEAD` | Strips any `Authorization` the Job sent and attaches hive's read token. | +| `github.com` | `GET /<repo>.git/info/refs?service=git-upload-pack`, `POST /<repo>.git/git-upload-pack` (git fetch and clone, uv's git resolution) | Same, as Basic `x-access-token`. | +| `github.com` | other `GET`/`HEAD` (archives, release downloads) | Forwarded with no credential. | +| the four hosts above | every other method, GraphQL, `git-receive-pack` (push discovery included) | Refused with a 403 and never sent to GitHub. | +| any other host | `CONNECT` on 443 | Opaque tunnel, no interception and no credential, through the same destination guard as the agent proxy (loopback, link-local metadata and private ranges are refused). | + +The credential is the existing **read tier** (`shared-uid-read`: metadata, contents, actions, checks, pull requests and issues, all read), minted from the Hive App and narrowed to `project.repos`. It is never the write token and never enters the Job: the Job holds only the relay key, which authenticates it to hive's listener and is worthless to GitHub. Hive caches the token for 45 minutes and logs decisions, never token bytes. The key is revoked when the kick ends. When no read token can be minted (no App auth, a repo outside the installation), reads go out anonymously, as they did before; the Job never receives an error it would not have had without the relay. Public repositories outside `project.repos`, such as a git dependency, are readable with that token because GitHub serves public data to any authenticated caller. + +This is separate from `HIVE_PROXY_INJECT_GH_AUTH`, which governs the placeholder token of agents running on the hive pod; the relay does not need it and is not affected by it. Limits to know: a Job that sets its own `HTTPS_PROXY` or `NO_PROXY` can route around the relay and is back to anonymous reads; `publish.verify` Jobs do not use it; GraphQL reads from a Job are refused because the relay cannot prove a query is read-only. A shared git dependency cache ([#18865](https://github.com/hivecommons/hive/issues/18865), option 3) is a separate, complementary change. + +**RBAC.** The spoke's ServiceAccount needs a Role for `batch/jobs` (create, get, list, delete), `pods` plus `pods/log` (get, list) and, optionally, `serviceaccounts` (get) so the Job service account's pull secrets are merged; the terminal viewer needs nothing beyond that same `pods/log` grant. The standalone kustomize base ships it as `sandbox-job-rbac.yaml`, and the hub provisioner grants it to every hosted spoke as `hive-sandbox-jobs`. + +Hive warns at boot and on reload (`config.AgentSandboxGateWarnings`) when a job-runtime agent resolves no `workspace_claim` or names a runtime hive does not have, and refuses the kick with the same message rather than failing it after the agent is marked running. + +### Posting reviews from a sandbox + +A reviewer can run in a sandbox too, so a review of an accelerator change can actually run it on the card node ([#14986](https://github.com/hivecommons/hive/issues/14986)). `sandbox.runtime: job` is a legal setting for a `reviewer`-base agent; the review runs on the node the Job lands on. + +```yaml +agents: + reviewer: + sandbox: + enabled: true + runtime: job + image: registry.example/project-dev:latest # needs bash and python3; hive supplies its relays + job: + node_selector: { accelerator: spyre } + resources: + limits: { "vendor.com/device": "1" } +``` + +A sandbox cannot reach the pod-local review relay (`/var/run/hive-metrics/review-requests`), and it never holds a GitHub credential. Instead, every sandbox kick (Podman or Job) gets a **review spool**: + +1. Before launch, hive creates `.hive/review-requests` in the kick workspace and sets `HIVE_REVIEW_REQUEST_DIR=/workspace/.hive/review-requests` inside the sandbox. `hive-review` writes its request there instead of the pod-local dir, in the same JSON schema. +2. Hive registers the spool with a manifest under `<work_dir>/sandbox-review-spools/` (`work_dir` is `HIVE_WORK_DIR`, default `/data/agents`). The manifest names the kick's agent. It lives outside every workspace, in a directory only hive's uid may write, so the sandbox can neither see nor forge it. +3. The review-request watcher moves each spooled request into a hive-owned staging directory beside the manifest and runs it through the same handler as the pod-local drop box. `review.max_reviews_per_head`, repo pause, the lane write allowlist, the sentinel approval block, the contributor COMMENT-only guard, the canary scan and the `agent_pr_reviewed` audit all apply unchanged. The request is **attributed to the manifest's agent**, whatever its own `agent` field says; the per-agent authorization (ACMM `CanPush` or the `converse` capability) is checked for that agent. +4. The manifest says which workspace a request came from, not who wrote it: the spool is group-writable, so any agent sharing hive's group could drop a file into it. So hive also mints a random 256-bit **spool key** for each kick, keeps it in the manifest, and hands it to the sandbox only through `HIVE_REVIEW_SPOOL_KEY` in its environment (the Podman launcher passes env by name, so the value never appears on a command line). `hive-review` writes `{"request": "<request JSON>", "mac": "<hex HMAC-SHA256(key, request JSON)>"}`. The relay stages only a request whose MAC matches this run's key and that this spool has not already accepted. An unsigned request, one signed with another run's key, or a copy of an accepted one is set aside as `.rejected`, logged at WARN, and answered with a `rejected:` result file. This stands in for the file-owner check the pod-local relay does, which can't apply here because a Job's uid is not an agent's. +5. The result is copied back to `<request>.result.json` in the spool, where the sandboxed agent reads it exactly as it would in-pod. A bad `--verdict-file` is refused with the validator's message, so the agent can fix the verdict and resubmit within the same kick. + +#### Issue and topic requests through the spool + +The spool is typed ([#18572](https://github.com/hivecommons/hive/issues/18572), [#18573](https://github.com/hivecommons/hive/issues/18573)). Besides reviews, it carries two more kinds of request, each run through the handler that serves it in-pod: + +- **`issue`**: `hive-open-issue` (open, comment, claim, close, label, request-review). The request runs through the issue relay's own handler. The repository gate, the ACMM `CanCreateIssues` gate, the lane write allowlist, repo pause, repo scope, dedupe by exact title, consolidation, the canary scan and the `agent_issue_created` (or comment, claim, close, label) audit all apply unchanged, for the manifest's agent. +- **`topic`**: `hive-topic` (`claim`, `get`, `list`, `release`, the same arguments as `bd topic`). The request is applied to the manifest agent's own bead store, the one `bd topic` writes in-pod. A claim needs a repo the agent is scoped to. `hive-topic` waits for hive's reply and prints it, exiting 0 on success, 2 when the topic is held through another PR (or `get` finds none), and 1 on any other error or when no reply arrives in time (`--timeout`, default 120 seconds; `--no-wait` returns at once). + +Hive sets the spool path and key under two more names, `HIVE_SANDBOX_REQUEST_DIR` and `HIVE_SANDBOX_SPOOL_KEY`, which `hive-open-issue` and `hive-topic` read first. Both fall back to the `HIVE_REVIEW_*` names, and both write to the pod-local drop box (or, for `hive-topic`, run `bd topic`) when no spool key is set. The envelope names its kind, `{"kind": "issue", "request": "...", "mac": "..."}`, and every kind but `review` MACs `"<kind>\n" + request`. So a request signed as one kind is refused as any other, and the replay guard covers all kinds. An envelope with no `kind` is a review MACed over the request alone, so `hive-review` is unchanged and an older copy still works. An unknown kind is set aside as `.rejected`. + +**A topic claim for the PR hive opens.** A sandboxed kick has no PR number: hive opens the PR from the kick's branch after the sandbox exits. So the manifest also records the kick's repo and branch, and `hive-topic claim <key>` without `--pr` records a **pending** claim on that branch. On the next eval cycle the governor binds it to the PR whose head branch it is (an open PR wins over a closed one), and the claim then follows the PR like any other: hive releases it when the PR merges or closes. Until then the kick's topic block shows the claim as "PR not opened yet". A pending claim left by a kick that opened no PR moves to the next kick's branch when that kick claims the topic again. A review-only kick opens no PR, so it records no branch, and a claim from it needs `--pr`. + +While any spool is registered, the watcher scans on its short poll interval: a Job writes its spool over a shared volume, often from another node, where no file-change notification reaches the hive pod. After the sandbox exits, the kick waits up to a minute for the relay to take any request still in the spool, because a run-stage worktree is removed when the kick returns. The manifest is dropped once the kick has ended and nothing is left to deliver, or after 24 hours. + +The relay touches the spool only through an `os.Root` opened at the workspace. A symlink the sandbox plants can't redirect a read, rename or write outside its own workspace, and a request file that is a symlink, FIFO or oversized is set aside as `.rejected`. The relay ignores a manifest directory or manifest that is not owned by its own uid or is group- or world-writable, and a manifest without a spool key. In the sidecar runtime (`CRUX_MODE=sidecar`), the runtime and hive must therefore share both `/data` and a uid. On `sandbox.runtime: job`, the key is in the Job's pod spec, so anything that can read Jobs or Pods in the namespace through the Kubernetes API can read it; agents must not hold that permission. A group member can still delete or alter a request in the spool, which loses the review but cannot post one. + +Out of scope: the quality and deps lanes are unchanged, and nothing inside a Job writes to GitHub directly. + +### Hive's relays inside the sandbox + +The project image does not need to carry `hive-review` or any other hive script ([#18512](https://github.com/hivecommons/hive/issues/18512)). On every sandboxed agent kick, hive supplies its **sandbox-safe relays** itself, read-only at `/opt/hive/relays`, and runs the kick command through a short `/bin/sh` preflight that prepends that directory to `PATH`. The relays are `hive-review`, `hive-open-issue` and `hive-topic`, which work from a sandbox through the spool above. Relays that need the pod-local drop boxes (`hive-open-pr`, `hive-merge`, `hive-push-branch`) are left out until they have a spool of their own. + +- **Job runtime.** The Job gets an init container, `hive-relays`, from the **running hive image by digest**. Hive reads its own pod (`$POD_NAME`, else `$HOSTNAME`) through the `pods` get grant the launcher already has, and takes the hive container's `imageID`. When the runtime reports no pullable digest, hive falls back to the image as written. Hive's own `imagePullSecrets` are copied onto the Job so the node can pull it. The init container runs `cp /usr/local/bin/hive-review /usr/local/bin/hive-open-issue /usr/local/bin/hive-topic /opt/hive/relays/` into a 16Mi `emptyDir`, and the kick container mounts that `emptyDir` read-only. The init container passes OpenShift's restricted SCC and the Kubernetes `restricted` Pod Security Standard: `runAsNonRoot`, `readOnlyRootFilesystem`, `allowPrivilegeEscalation: false`, every capability dropped, `RuntimeDefault` seccomp. On OpenShift (hive's pod carries the `openshift.io/scc` annotation) it sets no uid, and the SCC assigns one from the namespace range. Elsewhere the hive image's default user is root, which `runAsNonRoot` refuses, so it runs as uid 65534. Two `job` fields override this: + - `relay_image` pins the init container's image, for example a mirror on an internal registry. `none` turns the relays off. + - `relay_run_as_user` pins its uid. It must be positive. + + The first kick on a node pulls the hive image, which is large. Later kicks reuse it (`imagePullPolicy: IfNotPresent`). If hive cannot read its own pod, the kick fails with a message that names both fields, and no Job is created. +- **Podman.** Hive copies its own relays (found on its `PATH`, or in `$HIVE_SANDBOX_RELAY_DIR` when that is set) into a private temporary directory. It bind-mounts that directory with `-v <dir>:/opt/hive/relays:ro,Z` and removes it after the run. If a relay cannot be found, the kick fails with a message that says so. +- **Preflight.** The relays need `bash` and `python3` in the image. If either is missing, the kick exits with code 78 before the agent starts, and its transcript reads `hive: this sandbox image has no python3 on PATH ... add python3 to the image.` The image also needs `/bin/sh`. A kick that relies on the image's own entrypoint (no command) cannot be wrapped: the relays are mounted but not put on `PATH`. +- **Precedence.** Hive's copy always comes first on `PATH`, and a copy in the image is ignored. The relay and the spool protocol it speaks ship together in the hive image, so an older or newer copy baked into a project image could sign or shape a request that this hive rejects. There is deliberately no "use the image's copy if newer" option. +- **OpenShell and Substrate.** Not yet. On these runtimes the gateway or the actor API builds the sandbox pod, and getting hive's image into it needs runtime-specific work: an init container in the OpenShell template, and Landlock read access to `/opt/hive/relays`. Until that follow-up lands, the image still has to include `hive-review` on these runtimes. + +### What a sandboxed reviewer sees + +The sandbox has no GitHub credential, so `gh pr view`, `gh pr diff` and `gh pr checkout` fail inside it. Hive does that work on the host before the sandbox starts ([#18513](https://github.com/hivecommons/hive/issues/18513)). + +**Which kicks count as review kicks.** Hive reads the PR targets from the hive-written header of the kick message, never from text a PR author supplied: + +- A review swarm kick opens with `[review-perspective:…]` followed by `Review PR <owner>/<repo>#<n>`. That gives one target. +- A reviewer-lane kick opens with `[agent:<name>]` followed by `REVIEWER — …`. Each escalated PR in its work list has a ` checkout: gh pr checkout <n> --repo <owner>/<repo>` line, and each of those lines is a target. The lane sends at most 3 PRs per kick. The sandbox takes at most 5. + +Hive only checks out targets in the hive's primary repo, because that is the only repo the workspace clones. Any other kick has no targets and behaves as before. + +**What workspace prep does for each target `N`:** + +1. It reads the PR through hive's own GitHub client: title, body, author, state, base and head refs and SHAs, head repo (and whether the PR comes from a fork), labels, changed files (up to 3000), the unified diff, and every conversation comment, review, and inline review-thread comment. Comments are not filtered by author. Each one carries its author association. +2. It runs `git fetch origin +refs/pull/N/head:refs/heads/pr-N +refs/heads/<base>:refs/remotes/origin/<base>` with the same clone token it used for the clone. `refs/pull/N/head` exists on the base repo for fork PRs too, so fork PRs need no access to the fork. +3. It checks out the first target's `pr-N`. With several targets, the other branches are already fetched, and the reviewer switches between them with `git checkout pr-M`. +4. It writes `.hive/pr/N.json`. The file has `"untrusted": true` and a notice saying that every field except `repo`, `number`, `checkout` and the hive's notes came from the PR author or commenters. It also has a `checkout` block that hive wrote from git (`ref`, `branch`, `sha`, `base_tracking_ref`, `diff_command`). If the fetched head differs from the head GitHub reported, `checkout.head_moved` says so. The diff is capped at 512 KiB and the description at 64 KiB. A truncated or missing diff (GitHub refuses to render very large diffs) gets a `diff_note` that points at `checkout.diff_command`, which works offline because the base is fetched. +5. It prepends a `[hive:sandbox-review-checkout]` section to the kick prompt. The section names each checked-out branch, its head SHA, its PR file and the offline diff command, and it repeats the untrusted-data warning. + +Hive writes the prompt and the PR files after the PR head is checked out, through an `os.Root` opened at the workspace. A `.hive` symlink in the PR's tree therefore cannot redirect a host write outside the workspace. + +**Failures fail the kick.** If hive cannot fetch `refs/pull/N/head` or the base, or the GitHub client returns an error or a different PR, the kick fails before the sandbox starts. The error names the PR and includes git's output. A reviewer that cannot see the PR must not post a review of the wrong tree. If the host has no PR reader at all, the head is still checked out. In that case the PR file has `"metadata_available": false`, and the reviewer works from git alone. + +**Review kicks never push.** The manager wires no push broker and no PR client for a kick that has targets, and the executor refuses to push one even if a caller wires them. Commits the reviewer leaves on `pr-N` are discarded, and the run record notes them as withheld. The review itself is posted through the review spool described above. A run-stage kick that carries review targets is refused. + +## Running sandboxed kicks in an OpenShell sandbox + +`sandbox.runtime: openshell` runs an agent's sandboxed kicks in an [NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell) sandbox instead of a Podman container or a plain Kubernetes Job ([ADR-0026](/docs/hive/adr/0026-sandbox-runtime-selection), epic [#17642](https://github.com/hivecommons/hive/issues/17642)). OpenShell adds what the other two runtimes lack: the workload runs with no capabilities under Landlock and seccomp mediation, and **egress is default-deny** — every outbound connection goes through the gateway's proxy and is checked against a per-binary policy. Phase 1 is opt-in; nothing changes for a hive that does not select it. + +Everything above about the kick path still holds. Hive prepares the workspace on its own data PVC, writes the prompt, and after the sandbox exits reads the commits back and hands them to the push broker and PR path. Only step 2 changes: the launcher is `sandbox.OpenShellLauncher`, which talks to an OpenShell **gateway** over gRPC (`github.com/ai-openshell/sdk-go` v0.1.8); the gateway owns the sandbox pod. + +```yaml +agent_sandbox: + enabled: true + runtime: openshell + openshell: + gateway_url: https://openshell-gateway.openshell.svc:8443 # host:port or http(s):// + namespace: hive # the OpenShell workspace (their term), default "default" + token_env: OPENSHELL_TOKEN # env var holding the gateway bearer token; never the token itself + workspace_claim: hive-data # the PVC hive's /data lives on + workspace_claim_mount: /data # where hive sees it (default) + allow_hosts: [litellm.example.com, hub.hivecommons.dev] # on top of github.com / api.github.com + timeout_s: 1800 # bounds one sandbox from create to delete +agents: + deps: + sandbox: + enabled: true + image: registry.example/project-dev@sha256:… # digest-pinned + openshell: + node_selector: { kernel: "6.12" } + tolerations: + - { key: sandbox, operator: Exists, effect: NoSchedule } + binaries: [/usr/bin/git, /usr/lib/git-core/git-remote-https, /usr/local/bin/node] +``` + +The gateway, workspace, token, TLS and claim fields are cluster facts and fall back from the per-agent block to the global one; `allow_hosts`, `binaries`, `node_selector`, `tolerations` and `runtime_class_name` are per-agent choices and replace the global values when set. + +**Workspace transport is the shared claim again, not a copy.** The SDK's file transfer is single-file and not available on every gateway, so the OpenShell runtime mounts `workspace_claim` at a `sub_path` pointing at the per-kick workspace, at the same `/workspace` mount the other launchers use, through the gateway's Kubernetes driver config. That needs two things on the cluster side: the gateway setting `allow_driver_config = true`, and the claim labelled `openshell.ai/sandbox-attachable: "true"` and `openshell.ai/sandbox-attachable-workspace: "<namespace>"`. The same ReadWriteMany caveat as the Job runtime applies when the sandbox lands on another node, and `agent_sandbox.workspace_dir` must live under `workspace_claim_mount`. + +**The egress policy.** Hive derives an OpenShell network policy from the hosts its own proxy brokers for a Podman sandbox: `github.com` read-write (git's fetch-pack is a `POST` even when it only reads) and `api.github.com` **read-only** — a sandbox that somehow obtained a token still could not mutate through the API — plus whatever `allow_hosts` names, as `host` (443) or `host:port`. URLs, userinfo, wildcards and anything but a literal host name are rejected, and a unit-level prover renders the policy for the shipped examples to keep it that way. Everything else is unreachable, including a raw TCP connect to an arbitrary IP. OpenShell matches rules per **real binary path** and allows nothing for an unlisted binary, so the policy is attached to a default set (`git`, `git-remote-https`, `curl`, `node`, `python3`, `crux` at their usual paths) that `binaries` overrides when an image puts them elsewhere; a denied connection shows the path OpenShell identified in the sandbox log. `network_mode: none` drops every rule. `policy_profile` is recorded on the sandbox as the annotation `hive.dev/policy-profile` for gateway admission to act on; the SDK has no create-time profile selection. + +**The credential boundary.** Same rule as the Job runtime: environment variables from the allowlist are copied in with the same credential-name filter, hive's brokered GitHub token never enters the sandbox, and hive pushes and opens the PR from the returned workspace. There is **no** Secret-reference path into the sandbox in phase 1, so model credentials have to arrive through an allowlisted non-credential variable pointing at a routable gateway named in `allow_hosts`. The Cline backend, which needs a provider file or Secret, is refused on this runtime. + +**Lifecycle.** The sandbox is named `hk-<agent>-<unix, base36>` (at most 19 characters, the gateway's limit for DNS-routable names) and labelled `app.kubernetes.io/managed-by=hive-openshell`. Hive waits for it to become ready, runs the kick command with the sanitized environment in `/workspace`, collects stdout, stderr and the exit code (capped at 16 MiB), and deletes the sandbox — on success, on failure, and on the kick timeout, in which case the kick ends with exit code `-1` and `context deadline exceeded`, exactly like a timed-out Job. Cleanup runs on a fresh, bounded context when the kick's own has expired, so a finished sandbox is not left behind because the deadline fired during log collection. + +**What hive checks, and what it cannot.** Hive warns at boot and on reload (`config.AgentSandboxGateWarnings`) when an openshell-runtime agent resolves no `gateway_url` or no `workspace_claim`, and refuses the kick with the same message before the agent is marked running. It also preflights each distinct gateway (`Health().Check` and `Config().GetGateway`, read-only, cached for five minutes, bounded to 30 s) and adds a warning when the gateway is unreachable or unhealthy, `allow_driver_config` is not enabled, or telemetry is on. It cannot see the node kernel, the CNI or the claim's labels from inside its pod; those remain the operator prerequisites in [deploy/openshell.md](https://github.com/hivecommons/hive/blob/v5/src/deploy/openshell.md). + +**The terminal pane.** An openshell-runtime agent has no tmux session either, so its ▶ terminal opens the same read-only `/terminal/job/<agent>` viewer as a job-runtime agent, behind the same handoff and role check ([#17645](https://github.com/hivecommons/hive/issues/17645)). While a kick runs it follows the newest live `hk-<agent>-<unix, base36>` sandbox's gateway log (`GetLogs`, polled at up to the gateway's 2,000-line buffer per read, scrubbed of token-shaped values like the pod log); between kicks, once the launcher has deleted the sandbox, or when the gateway cannot be listed, it shows the last persisted transcript exactly as the job viewer does. The live view is weaker than the job pod log, and the pane says so: the gateway log carries the sandbox's supervisor, policy (OCSF) and tracing events — the network and filesystem decisions made around the kick — not the kick's stdout, because the kick runs as an exec session and [exec output reaches neither the gateway log nor the container log](https://docs.nvidia.com/openshell/observability/accessing-logs). Likewise the exit code the gateway reports on the sandbox is its main process's, not the kick's; the launcher takes the kick's exit code from the exec result and deletes the sandbox at once. So the pane ends by saying the kick has finished and that its output and exit code are in the transcript, which it shows on the next open. The dashboard reaches the gateway with the agent's own `gateway_url`, `namespace`, `token_env` and `insecure_tls`. + +**How to verify.** With a gateway reachable and the claim attachable, run the env-gated integration test from a pod that has the claim mounted: `OPENSHELL_GATEWAY_URL=… OPENSHELL_WORKSPACE_CLAIM=hive-data OPENSHELL_IMAGE=<digest-pinned> go test ./crux/sandbox -run TestOpenShellIntegration -v`. It writes a file through `/workspace`, reads it back on the hive side, and logs the round-trip latency. Then run a kick and confirm in the sandbox log that a `POST` to `api.github.com` is denied while `git fetch` succeeds — that denial is the whole point of the runtime. + +**Limitations (phase 1).** Kubernetes driver only (no Podman-driver path for standalone hosts yet); no Secret references into the sandbox; `policy_profile` is advisory; kernel and claim-label prerequisites are not preflighted; latency and image size are not yet measured ([#17643](https://github.com/hivecommons/hive/issues/17643)). + +## Running sandboxed kicks in a Substrate actor + +`sandbox.runtime: substrate` runs an agent's sandboxed kicks as an [Agent Substrate](https://github.com/agent-substrate/substrate) **actor** ([ADR-0026 phase 2](/docs/hive/adr/0026-sandbox-runtime-selection#implementation-notes-phase-2-agent-substrate), epic [#17695](https://github.com/hivecommons/hive/issues/17695)). Substrate is a CNCF Sandbox project donated by Google: a `WorkerPool` of pods runs workloads under gVisor (`runsc`) or in a KVM microVM, every actor gets a SPIFFE identity, and all egress leaves through `atenet-router` under an `EgressPolicy`. It is the fourth runtime and, like OpenShell, opt-in; nothing changes for a hive that does not select it. + +Everything above about the kick path still holds; only step 2 changes. The launcher is `sandbox.SubstrateLauncher`, which talks to Substrate's gRPC **Control API** (`ate.control.v1`) with a trimmed, wire-compatible client generated in-repo (`crux/sandbox/substrateapi`; the upstream Go module needs a newer Go than hive builds with). + +```yaml +agent_sandbox: + runtime: substrate + substrate: + endpoint: api.ate-system.svc:443 # Control API, host:port or https:// + atespace: hive # Substrate's tenancy unit, default "default" + token_env: ATE_TOKEN # bearer token env var (or token_file for a projected SA token) + ca_file: /var/run/ate/ca.crt # Control API CA; insecure_tls: true only for a lab + router_url: https://atenet-router.ate-system.svc:8444 + router_client_bundle: /var/run/ate/credential-bundle.pem # hive's own mTLS client identity + router_ca_file: /var/run/ate/router-ca.crt + image: ghcr.io/hivecommons/crux-sandbox@sha256:… # digest-pinned; tags are refused + cpu_millicores: 2000 + memory_bytes: 4294967296 + worker_selector: {ate.dev/sandboxClass: gvisor} # pick the pool (gvisor | microvm) + snapshot_on_idle: false + allow_hosts: [models.example.com, hub.example.com:8443] + timeout_s: 1800 +agents: + reviewer: + sandbox: + substrate: + snapshot_on_idle: true # per-agent overrides merge onto the global block +``` + +**One actor per kick.** Hive creates an `ActorTemplate` (one container running the bridge command, the workspace as a `durableDir`, the operator's limits and `worker_selector`) and an `Actor` from it, both named `hive-kick-<agent>-<unix>`, attaches the egress policy, waits for the actor to report `RUNNING`, and then talks to a small HTTP **bridge** inside the actor (`crux substrate-bridge`, overridable with `bridge_command`, port `bridge_port`) through the router's mTLS `CONNECT` tunnel: it pushes the workspace as a tar, runs the kick with the sanitized environment, and pulls the workspace back. The hive-side workspace remains the source of truth and feeds the push broker exactly as for Podman. Substrate has no exec API and hive shares no PVC with the worker nodes, which is why the workspace is copied rather than mounted; the copy is bounded by the kick timeout. + +**The egress policy.** Hive derives an `atenet-egress` policy from the hosts its proxy brokers for a Podman sandbox — `github.com` and `api.github.com` on 443 — plus `allow_hosts` as `host` or `host:port`, all as TLS passthrough; URLs, userinfo and wildcards are rejected at validation, before any actor is created. Everything else, including all UDP and raw IP connects, is denied. Substrate's policy language has no per-method read-only mode, so `api.github.com` is reachable; the actor holds no token (`SanitizedEnv`) and hive performs every GitHub write itself after the kick. `network_mode: none` drops every rule. Actors run credential-free: there is no `HTTPS_PROXY` or MITM broker inside the actor and no credential enters it, and hive brokers pushes after the kick from the returned workspace (decision on [#17695](https://github.com/hivecommons/hive/issues/17695), [ADR-0026](/docs/hive/adr/0026-sandbox-runtime-selection)). Substrate's own credential injection is not used; SVID-authenticated broker delegation over the atenet mTLS channel is a future phase 3. + +**Lifecycle.** Success, failure and the kick timeout all delete the actor and then its template, on a fresh bounded context when the kick's own has expired, with exit code `-1` and `context deadline exceeded` on timeout, like a timed-out Job. With `snapshot_on_idle: true` the actor is **suspended** (snapshotted to Substrate's object storage) instead of deleted; the template is still deleted and the snapshot is not yet resumed on the next kick ([#17697](https://github.com/hivecommons/hive/issues/17697)). At most one suspended actor is retained per agent per hive process: the previous one is deleted after the next successful suspend (skipped with a warning if the agent's `atespace` changed in between), and actors left by an earlier hive process are not reclaimed because the Control API has no `ListActors`. `policy_profile` is passed to the actor as `HIVE_POLICY_PROFILE` for in-actor tooling; Substrate has no annotations. + +**What hive checks, and what it cannot.** At boot and on reload (`config.AgentSandboxGateWarnings`) a substrate-runtime agent is warned about, and its kick refused, when `endpoint` or `router_url` is missing or `image` is not digest-pinned. Hive also preflights each distinct Control API (read-only `ListWorkers`, cached for five minutes, bounded to 30 s) and warns when it is unreachable, has no `ACTIVE` worker matching `worker_selector`, or its workers advertise no sandbox class. It cannot see the CRDs, the operator, the pod-certificate feature gates or `/dev/kvm` from inside its pod; those are the operator prerequisites in [deploy/substrate.md](https://github.com/hivecommons/hive/blob/v5/src/deploy/substrate.md) and the prover in [#17698](https://github.com/hivecommons/hive/issues/17698). + +**The terminal pane.** A substrate-runtime agent has no tmux session either, so its ▶ terminal opens the same read-only `/terminal/job/<agent>` viewer behind the same handoff and role check ([#17777](https://github.com/hivecommons/hive/issues/17777)). The Control API has no `ListActors` and Substrate has no logs RPC, so the launcher — which runs in the same hive process as the dashboard — records each kick for the pane: the actor's `<atespace>/<name>`, every state it is seen in (`RESUMING`, `RUNNING`, then `SUSPENDED` with `snapshot_on_idle` or `DELETING`), and the worker's SPIFFE id from the actor's worker assignment. The bridge's `POST /run` streams the kick's stdout and stderr when asked (`"stream": true`, newline-delimited `RunResponse` frames; an older bridge answers with one complete response and still works), and the pane follows that output live, scrubbed of token-shaped values like the pod log, with each actor state change as a status line. Unlike OpenShell this is the kick's own output, and the pane ends with the kick's exit code and whether the actor was suspended or deleted. Between kicks it names how the last actor ended above the last persisted transcript; after a hive restart, before the agent's next kick, it shows the transcript alone. + +**Limitations (phase 2).** Workspace copied, not shared; `crux substrate-bridge` entrypoint and a published sandbox image land with the prototype ([#17697](https://github.com/hivecommons/hive/issues/17697)); no resume of suspended actors; `api.github.com` not read-only at the policy layer; latency and image size not yet measured. + +## Health and metrics for sandboxed agents + +A sandboxed agent (Podman or Job runtime) has no tmux session, no in-pod process and no `pluk` log between kicks: the manager parks it in the `idle` state and each kick runs to completion in a container or Job. The dashboard therefore must not read "not running" as "session down" for these agents, and the token collector cannot find their CLI session files because the CLI's home directory lives in the sandbox, not in the hive pod. + +**Last-run record.** When a sandboxed kick ends, `crux/agent` builds a `SandboxRun` (runtime, start/end, succeeded, timed out, error, commit count, branch, PR URL, `prWithheld` when the publish gate kept commits local, `logId` of the archived kick log, summary, usage) and keeps it on the agent process as `sandboxLastRun`. It is also written to `<work_dir>/sandbox-runs/<agent>.json` (restored on restart, so a pod roll does not blank the card) and appended to `<work_dir>/sandbox-runs/runs.jsonl`, which is compacted to its newest 1000 records once it passes 2 MiB (`work_dir` is `HIVE_WORK_DIR`, default `/data/agents`). The summary is the agent's `.hive/agent-report.json` `summary` when it left one, otherwise the scrubbed tail of the transcript. + +**Health.** `/api/status` carries a `sandboxRun` object on every sandboxed agent with a `health` verdict the SPA uses instead of the session check: + +| `health` | Meaning | Dot | +|-----------|---------|-----| +| `ok` | last run succeeded (or no run yet) and the next cadence occurrence is still in the future | green | +| `running` | a kick is in flight (container or Job running) | amber | +| `waiting_for_node` | a kick is in flight but its Job's pod is Pending and Unschedulable; `waitDetail` has the scheduler's message | amber | +| `node_unhealthy` | the last kick never reached the agent: the node `preflight` failed, also on the retry; `failReason` and `node` say why and where | red | +| `failed` | the last run failed or timed out — see the agent's log | red | +| `overdue` | the cadence had a due occurrence that never started, older than the grace (half the period, clamped to 15 min – 2 h); `dueAt` names it | red | + +On-demand agents, paused agents and `pause`/`continuous` cadences are never overdue. A never-kicked interval agent counts its first period from the time the agent came up. The card's blocker line reads `Job ok` / `Job running` / `Job ready` (or `sandbox …` for Podman) / `last run failed` / `last run timed out` / `run overdue` for sandboxed agents instead of `session down`, and the "Now:" line shows the last run's outcome, duration, PR link and summary. + +**Tokens and sessions.** The collector reads `sandbox-runs/runs.jsonl` and turns every run that reported usage into one session (`sandbox-<agent>-<startMs>`, backend `sandbox`), so TOKENS/SESSIONS, by-agent and by-model totals and cost include sandboxed work. Usage is parsed from the transcript: Claude's `--output-format json`/`stream-json` `result` line and Copilot's "Breakdown by AI model" footer are recognised. A backend that prints plain text only (Claude without `--output-format`) reports no usage; such runs stay healthy but contribute no tokens rather than an estimate. + +## Network trade-off + +`network_mode: none` remains available and maps to Podman's `--network=none`, but it only works for non-inference jobs or runtimes that already expose a local/socket model proxy inside the container. The default sandbox network mode is `restricted`: operators must provide a Podman network/proxy policy that allows only the inference endpoint and MITM proxy required by the selected backend. This is a compromise until every supported backend can run through a credential-free local socket without general egress. + +## Remaining gaps + +- The default target is the hive primary repo and default base ref; richer per-kick repo/ref selection is still future work. +- The Job runtime is a first slice: one Job per kick, workspace shared through a PVC, no per-kick Secret minting. A clone-inside-the-Job transport for clusters without ReadWriteMany storage is future work. +- Live Podman execution is covered by skip-when-absent tests; CI still needs a rootless-Podman runner lane for always-on integration coverage. +- Sandboxed inference depends on an operator-provided restricted network/proxy policy. `none` is stronger but not yet usable for all model backends. +- Stronger runtimes than plain containers ship opt-in: [ADR-0026](/docs/hive/adr/0026-sandbox-runtime-selection) (Accepted) covers NVIDIA OpenShell (phase 1) and Agent Substrate (phase 2); both still need their prototype measurements and cluster preflights. + +## Agent guardrails (defense in depth) + +Beyond the credential-free sandbox above, Hive's isolation model is defense in depth rather than a single sandbox switch. Agents run as long-lived CLI sessions, but the deterministic pipeline and proxy layers decide what work they see and what writes they can perform. + +### Isolation layers + +1. **Policy mode** — ACMM selects advisory, measured, hold-gated, or full behavior per agent. +2. **Deterministic admission** — Go and shell checks classify work, apply holds, and decide whether an agent is kicked. +3. **Scoped credentials** — contributor relays and spoke agents use the GitHub identity and token scope appropriate to that actor; a delegated ClankeR role does not grant spoke secrets. +4. **MITM GitHub proxy** — GitHub API writes are attributed and constrained according to the current mode. +5. **Merge gates** — the literal `hold` level-gate label, dashboard `hive-pause/<hive-id>` manual holds, green checks, self-merge bans, and auto-merge sweeps are enforced outside the LLM prompt. + +### Operator notes + +- Prefer the least-capable ACMM level that matches the project phase. +- Keep privileged delegated roles (`ci-maintainer`, `sec-check`, `architect`) behind explicit grants. +- Use the docs in this index for concrete setup: [ACMM policy matrix](/docs/hive/acmm-policy-matrix), [Agent configuration](/docs/hive/agent-configuration), and [Contributor trust tiers and delegated agent roles](/docs/hive/security/contributor-trust-and-roles). diff --git a/docs/content/hive/snapshots.md b/docs/content/hive/snapshots.md new file mode 100644 index 0000000..07e61e5 --- /dev/null +++ b/docs/content/hive/snapshots.md @@ -0,0 +1,42 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/snapshots.md) during the docs build. Edit the canonical source in the Hive repository. + +# Public snapshots + +`/snapshot` is a read-only, public view of a hive's current dashboard state. It is intended for sharing status with communities, embedding in project pages, or linking from a hub without granting dashboard write access. + +Snapshots are available when the spoke has auto-snapshots enabled: + +```yaml +hub: + auto_snapshot: true +``` + +The backing JSON is served from `/api/snapshot` with public cache headers. Both `/snapshot` and `/api/snapshot` are public paths, but they reject write methods and expose only the status payload, not mutating dashboard APIs. + +## Custom CSS + +The snapshot page accepts the same sanitized stylesheet parameter as the dashboard: + +```text +/snapshot?style=owner/repo/path/to/theme.css@ref +``` + +See [Custom stylesheets](https://github.com/hivecommons/hive/blob/v5/src/docs/custom-stylesheets.md) for allowed CSS and sanitizer reporting. + +## Embedding and frame ancestors + +By default Hive fails closed: snapshot pages send `X-Frame-Options: DENY` and `Content-Security-Policy: frame-ancestors 'none'`. + +To allow selected HTTPS origins to embed `/snapshot`, configure: + +```yaml +dashboard: + snapshot_frame_ancestors: + - https://docs.example.org + - https://status.example.org:8443 +``` + +Only exact HTTPS origins are accepted. Paths, wildcards, non-HTTPS origins, and malformed hosts are rejected. When an allow-list is present, `/snapshot` omits `X-Frame-Options` because that header cannot express multiple allowed origins; every other route keeps `DENY`. + +The current allow-list is visible at `/api/snapshot/frame-ancestors` for operators debugging embed configuration. + diff --git a/docs/content/hive/spektacular.md b/docs/content/hive/spektacular.md new file mode 100644 index 0000000..da85f28 --- /dev/null +++ b/docs/content/hive/spektacular.md @@ -0,0 +1,499 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/spektacular.md) during the docs build. Edit the canonical source in the Hive repository. + +# Spektacular (Spek) stage runner + +The Spektacular (Spek) stage runner is the Hive side of long-running runs +(hivecommons/hive#8303, part of the #8290 umbrella). A run moves through the +`spec`, `plan`, and `implement` stages on one task lease. Spek owns the +state of each artifact; Hive owns the workflow: it asks Spek whether the +current artifact is finished and advances the lease when it is. + +The runner is OFF by default. With `runs.spektacular.enabled` unset or `false` +Hive never starts a Spek process and every existing lease behaviour is +unchanged. + +Retained Spek runs are listed in [Runs](https://github.com/hivecommons/hive/blob/v5/src/docs/runs.md) (`GET /api/runs` and +`GET /api/runs/{key}`). The old campaign projection (`/api/campaigns`), campaign +Jam and campaign recheck were retired together with inception campaigns in +favour of [Inception (spek) sessions](/docs/hive/dashboard-sections/workflow-and-agents#inception-spek). +On the first start after the upgrade Hive writes a one-time, read-only export of +any campaign archives and Jam data it finds; see +[Inception: retired campaigns export](/docs/hive/api-reference/inception#retired-campaigns-export). + +## Enabling it + +```yaml +runs: + max_stage_retries: 2 # default; generations one stage may burn + spektacular: + enabled: true # default false + binary: spektacular # default; resolved through PATH + poll_interval_s: 30 # default +``` + +The Governor dialog's Features panel exposes the toggle and the binary path +under "Long-running runs"; the poll interval and the retry budget are yaml +only. The same keys are accepted by `PUT /api/config/governor/features` as +`spektacularEnabled` and `spektacularBinary`. The runner is installed at boot +(`cmd/hive`, `wireSpektacularRunner`), so a change to the toggle takes effect +on the next boot, like the other feature switches. + +Package layout: `pkg/spektacular` owns the CLI boundary, the poll loop, and +the receipt; `pkg/dashboard` exposes its lease registry as a primitives-only +surface on `*Server` (`VisitActiveStageLeases`, `AdvanceStageLease`, +`RetryStageLease`, `RefuseStageLease`, `EscalateStageLease`, `ImportRunPlan`) +and drives whatever `StageRunner` was installed with `SetStageRunner` from the +contribute hub's cleanup tick. The dashboard never imports `pkg/spektacular` +(its internal-import ratchet); `pkg/spektacular.NewHubRunner` takes the +server through the `LeaseRegistry` interface. + +## Publish hand-off + +Spek can also run the other way round: a finished spec or epic is +**published** as an RFC plus child issues into the hive's work source — GitHub +Issues, Jira or Linear — so Hive picks the children up from its normal queue +whether Spek ran standalone or in-hive +([spektacular#109](https://github.com/hivecommons/spektacular/issues/109), +[spektacular#114](https://github.com/hivecommons/spektacular/issues/114)). No +new input path is involved: the children are enumerated, staged and claimed +exactly like human-filed items. What Spek adds is one hidden marker in every +body it files: + +```text +<!-- spek:publish name=<name> artifact_id=<id> target=<github|jira|linear> [task=<id>] [rfc=<url>] --> +``` + +`name` and `artifact_id` identify the spek, `target` the work source. `task` +is the plan task / member spec id and is present on every **child**; the +**RFC** itself carries the marker without it. `rfc` is the RFC's URL. Values +are bare tokens (optionally quoted) separated by whitespace; a marker missing +`name`, `artifact_id` or a known `target` is malformed and is ignored as a +whole, and `rfc` is kept only when it parses as an http(s) URL — nothing in +the marker is echoed into a kick as free text. The parser is +`pkg/spekmarker`. + +Hive reads the marker in four places, none of which needs configuration: + +| Behaviour | Where | Effect of the marker | +|---|---|---| +| Triage | `runs.triage` (below) | A marker-carrying item is **never** routed into a new `spec` run, whatever `spec_labels` or complexity tier it carries; it takes the direct-fix path as `run/fix` does (signal `marker:spek:publish`). `run/spec` still overrides. | +| Clarity gate | `runs.triage.clarity_gate` | Not scored, the same way `approved-direction` is skipped: the item is already specified. | +| Kick context | kick issue list | A child's line gains `↳ specified by Spek: RFC <url> (spek <name>, artifact <id>, task <id>) — build against the spek's acceptance criteria …` and the instruction that the PR body must say `Fixes #<child>`. | +| Umbrella | `governor.claims.never_claim_labels`, `IsTrackerIssue` | A marker **without** `task=` is the RFC: it is treated like `epic` — refused by every automated claim producer (`never-claim label: spek:publish`), never staged 020/030 from a stray claim, and flagged `[TRACKER]` — even when the repo has no `epic` label. | + +Everything else in the handshake is unchanged and documented where it lives: +enumeration and the hard-suppress labels ([labels-and-control-signals.md](/docs/hive/labels-and-control-signals)), +reporter trust (`issue_filter.reporter_trust`: publish as a trusted identity +or expect the `triage/accepted` step), the prior-art gate (expected to fire on +the RFC title, not the children), native sub-issue / blocked-by relations +([hive-open-issue.md](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-issue.md)) and the Jira / Linear source +filters ([work-sources.md](/docs/hive/work-sources)). The in-hive stage runner is not +involved in a publish; a published issue is ordinary work. + +## Triage + +The runs triage pass is separate from the Spek runner and is also OFF by +default. When `runs.triage.enabled: true`, the scheduler classifies each +incoming actionable GitHub issue before a direct-fix kick: + +- `run/spec` always admits a `spec` run. +- `run/fix` always leaves the issue on the normal direct-fix path. +- An issue whose body carries the Spek publish marker (`<!-- spek:publish … -->`, + see [Publish hand-off](#publish-hand-off)) likewise stays on the direct-fix + path: it is already specified. +- Complex issues, or issues carrying `spec_labels` (default `kind/feature`, + `Epic`, `architecture discussion`), admit a `spec` run by creating the first + stage lease. The lease is keyed as the run-stage work source expects: the + repository plus the run key and `:spec` suffix (see + [work-sources.md](/docs/hive/work-sources)). +- Simple issues, medium issues, or issues carrying `fix_labels` (default + `kind/bug`, `good first issue`) stay on the existing direct-fix path. +- Short bodies (`min_body_chars`, default 80), unchosen option lists, and + unsubstituted template placeholders get one marker comment (`hive-triage`) + asking the reporter for the missing details and are skipped for that cycle. + +The decision is stored on the stage lease as `triage_verdict` and +`triage_rationale`, surfaced by `GET /api/runs` and run detail, and copied into +the first stage receipt timeline event. Owner reset with reason `triage_fix` +retires a run in the `spec` stage so the issue can return to the direct-fix path. + +```yaml +runs: + triage: + enabled: false # default + spec_labels: [kind/feature, Epic, architecture discussion] + fix_labels: [kind/bug, good first issue] + min_body_chars: 80 + clarify_comment: true +``` + +### Clarity gate + +`runs.triage.clarity_gate` ([#13577](https://github.com/hivecommons/hive/issues/13577)) +pushes back on vague issues before an agent claims them. It is OFF by default +and independent of `runs.triage.enabled`. When on, the scheduler scores every +human-filed, unclaimed GitHub issue in the kick list, without a model call: + +| Signal | Points | Found when the body has | +|---|---|---| +| Goal | 25 | a goal/problem/summary heading, or a goal sentence (`should`, `expected`, `so that`, `fails`, …) | +| Acceptance criteria | 35 | an `Acceptance criteria` / `Definition of done` / `Expected behavior` heading or line, or a `- [ ]` checklist | +| Scope | 20 | a code span, a path or file name, or a scope word (`component`, `command`, `page`, `out of scope`, …) | +| Detail | 20 | 300+ characters (10 at `min_body_chars` or more) | +| Open choice | −30 | an unchosen `high/medium/low` list, an unfilled `<placeholder>`, `TBD`, `???`, `not sure if`, `or maybe` | + +An issue scoring under `threshold` (default 60, Settings → Features → +Incoming issue triage → **Clarity threshold**) is withheld from the kick. Hive +posts one comment carrying `<!-- hive:clarity-gate -->` with one short question +per missing signal and adds the `needs-spec` hard-suppress label (the first +label of `project.issue_filter.hard_suppress_labels.needs_spec`). The issue then +derives `stage/045-needs-decision` ("parked on a person: needs-spec"), leaves +enumeration and is refused by the claim gate. The marker is never posted twice. +If the comment posts but the label write fails, the issue stays withheld and the +label is retried on the next kick; a restart in between does not lose the +retry, because the gate reads the issue's label history and tells a park that +never landed from one a person removed. + +The issue resumes on its own once somebody answers +([#13588](https://github.com/hivecommons/hive/issues/13588)). While the gate is +on, a resume sweep (every 5 minutes, at most 10 issues per pass) looks at open +issues carrying `needs-spec` and lifts it when all of these hold: + +- the issue has a `<!-- hive:clarity-gate -->` comment written by one of the + hive's own accounts (a pasted marker does not count); +- the newest `needs-spec` label event is by the hive, so a `needs-spec` a + person added, with or without an older gate comment, is never lifted; +- after both, the issue author, or a person other than the hive with write, + maintain or admin permission on the repo (checked live), commented. + +The sweep removes `needs-spec` and records the un-park on the stage engine, so +the issue re-derives `stage/010-actionable` and re-enters the queue. Removing +`needs-spec` by hand resumes it too. Either way the gate sees the marker and +does not ask again, however the issue scores. Issues filed by Hive or an agent, +issues already claimed, issues carrying `approved-direction` and Spek-published +issues (body marker `<!-- spek:publish … -->`) are not scored. + +```yaml +runs: + triage: + clarity_gate: + enabled: false # default + threshold: 60 # 0-100; 0 uses the default +``` + +### Prior-art gate + +`runs.triage.prior_art` ([#13575](https://github.com/hivecommons/hive/issues/13575)) +answers "does this already exist?" before any agent claims a feature request. +It is ON by default and independent of `runs.triage.enabled`. For every +unclaimed GitHub issue of a gated kind (`kinds`, default `feature`, `rfc`, +`epic`, `enhancement` — matched as a bare or `kind/`-prefixed label, or as a +leading `[RFC]` / `RFC:` / `Epic:` title tag; anything labelled `bug` is never +gated) the scheduler derives the issue's key terms (backticked identifiers, +config keys and `--flags` weigh 4, title words 3, the most frequent body +words 1) and asks, without a model call: + +| Source | What it searches | Hit kind | +|---|---|---| +| knowledge | the hive's knowledge layers (`SearchAll`, deprecated/superseded facts dropped) | `knowledge` | +| settings | the dashboard Settings search index, as the `rfc_existing_check` does | `setting` | +| merged_prs | merged PRs in the repo from the last 12 months | `merged PR` | +| closed_issues | closed issues in the repo (declined `not_planned` ones skipped unless `duplicate`) | `closed issue` | +| docs | `README*`, `CHANGELOG*`, `docs/` in every `project.repos` checkout under `checkouts_dir`, by identifier and top terms (local `pkg/codeindex` snapshot) | `doc` | +| code | source files in every registered checkout, by identifier only (local `pkg/codeindex` snapshot) | `code` / `setting` | + +Each candidate's confidence is the share of the issue's weighted terms it +contains; a candidate needs two shared terms including a title term or an +identifier to count at all. Every source is optional and soft (a failed +search drops its candidates only), a missing, dirty or partly indexed +checkout is called out as "checkout missing/partial for <repo>" instead of +being read as no prior art — in the gate comment when one is posted, and as a +`prior-art-gate-coverage-gap` audit entry otherwise; reports with a +still-building index are not cached, the whole search is bounded (20s, one +query per source) and the report is cached per issue content hash, so an +unchanged issue costs nothing on later cycles. + +When the best finding reaches `threshold` (default **70**: deliberately +high because a park costs a person a round trip — 70 means the finding +covers about three quarters of the issue's weighted vocabulary including a +title term) what happens depends on who filed the issue: + +| Author | Detected by | What the gate does | +|---|---|---| +| a person | `author/human`, or the enumerator's human verdict | one `<!-- hive:prior-art-gate -->` comment quoting up to `max_findings` (default 5) findings with links and a one-line quote, the `stage/017-possible-existing` park label, and a `discoverability: <feature> was asked for though it exists` advisory bead so the docs can be improved. Never auto-closed. | +| the hive's own agent | `author/hive`, the App login, or an `agent/*` / `origin/*` label | **never parked** — a `<!-- hive:prior-art-findings -->` note is attached once and the issue carries on; the claiming agent must open its claim comment with a *Gap vs existing* paragraph. At filing time the `hive-open-issue` relay enforces it for feature kinds: a high-confidence match is refused naming the existing item and recorded as a knowledge bead; a medium one is refused unless the body has a *Gap vs existing* section, and is then filed with the findings note attached. | +| a clanker (another hive, a contributor CLI, an external bot) | `author/clanker`, or a `[bot]` / non-human, non-hive login | parked like a person, with notice that silence closes it: after `bot_close_ttl` (default 72h) with no reply the resume sweep closes it `not_planned` with the `already-exists` label. Reopenable. | + +While an issue carries `stage/017-possible-existing` no agent claims it +(it is a hard suppress, like 045). The resume sweep (every un-park cadence) +answers the author's or a maintainer's reply: + +- `/hive decision proceed — <what is missing>` lifts the label, appends a + **Scope vs existing** section with the delta to the issue body as + acceptance criteria, and records the un-park so the issue re-derives + `stage/010-actionable`; +- `/hive decision exists` adds `already-exists`, closes the issue + `not_planned` and replies with a pointer at the findings; +- a plain reply lifts the label too (the claiming agent is told to state the + gap first). + +The gate's marker keeps it from asking twice; a `stage/017` a person added by +hand is never lifted by the sweep. At most `max_parks_per_cycle` (default 5) +issues are parked per enumeration cycle, so turning the gate on against a +backlog never floods a repo. + +```yaml +runs: + triage: + prior_art: + enabled: true # default + threshold: 70 # 0-100; 0 uses the default + max_findings: 5 + kinds: [feature, rfc, epic, enhancement] + max_parks_per_cycle: 5 + bot_close_ttl: 72h # clanker parks only; negative disables auto-close +``` + +## What the runner does + +Every 30 seconds (the contribute hub's cleanup tick) the runner looks at every +lease that carries a stage. For each `spec` or `plan` stage whose poll interval +has elapsed it runs + +```text +spektacular <spec|plan> status <name> +``` + +where `<name>` is the bare artifact name (`000057_git-commit`, never +`000057_git-commit.md` or `000057_git-commit/plan.md`): the lease's canonical +work-item key `<repo>!<runKey>:<stage>` (see [work-sources.md](/docs/hive/work-sources)) +with the repository prefix and stage suffix stripped, then reduced to the bare +name (`spektacular.ArtifactKey`; the dashboard applies the same rule in +`runKeyOfLease`). The CLI has no `--json` flag (its only global flag is +`--fields`); every verb already prints JSON, and an unknown flag is a usage +error. Then: + +- `document_status: draft` leaves the lease alone. +- `document_status: final` writes a stage receipt + (`/data/runs/receipts/<runKey>/<stage>-gen<gen>.json`, the + `stage-receipt/v1` shape from `pkg/outputschema`), records a `stage_receipt` + timeline event carrying the receipt digest and path, and calls the same + `advanceLeaseStage` path the API uses. That fires the `stage_completed` hook + and CEL trigger and records the `lease_stage_advanced` audit entry exactly + as a manual advance would. +- `document_status: stale` means Spek strict mode invalidated the plan + after the spek changed. Hive refuses the plan-to-implement advance, parks the + run with `waiting_on=human` and `waiting_reason=stale_plan`, and records a + `blocked` timeline event. The lease is not retried; recovery is a fresh + plan/re-approval. +- The status payload's `artifact_id`, when present, is the durable + Spek artifact join key Hive stores in receipts and stage attributes. + The bare `name` remains the CLI address and backward-compatible display + alias; older CLIs that lack `artifact_id` fall back to `name`. +- Progress is decided by `document_status`, `current_step` and + `completed_steps` only. The status document's `updated_at` is never read + for a progress or staleness decision: it is workflow activity only while + Spek's in-progress state matches the artifact, and otherwise a file + mtime that a `git checkout`, a reformat or a `touch` moves without anything + having happened. Spek may also omit it entirely when no workflow + state matches, so the parser treats an absent, `null` or empty + `updated_at` (and an empty `created_at` / `closed_at`) as unknown. A stale + stage is decided by Hive's own lease clock (the lease's expiry), never by + the artifact's timestamps. `TestUpdatedAtNeverDecides` in `pkg/spektacular` + keeps it that way. +- A lease that lapses without `final` is retried through `retryLeaseStage` + (a new generation of the same stage, `lease_stage_retried` in the audit + log) while the budget allows. `max_stage_retries` counts generations + including the first: at the default of 2 the stage runs once, is retried + once, and the second expiry raises an escalation with `decision` severity + (`lease_stage_escalated` in the audit log, a `blocked` timeline event with + `severity=decision`). No third generation is ever minted; a person resets + the stage or abandons the run. +- The `implement` stage has no Spek document. The runner never polls + it; its completion is the existing hold-gated PR flow. + +Ticks are idempotent per lease generation: once a generation has advanced it +is never polled or advanced again, a generation change (a retry, or the +successor stage of an advance) keeps the poll pacing instead of earning an +extra status call, and a second tick at the same instant is a no-op. + +A retry is the one lease mutation allowed on an expired lease: it exists +because the generation lapsed, so the expired lease is its expected input and +receives a fresh window under its new generation. An advance still requires a +live lease. + +### Plan import + +When a `plan` reaches `final` the runner runs + +```text +spektacular plan export <name> --format json +``` + +(requested upstream in +[spektacular#50](https://github.com/hivecommons/spektacular/issues/50)) and +admits the returned tasks through `planning.DecomposeFromOutput` with +`AutoApprove: false`. Spek's structure is rendered verbatim into the +planner's task-list shape (`[T1] title (depends: T2) [agent_suitable]`); no +model is asked to redecompose an already-structured plan. + +Until that export verb exists, Hive falls back only when export is unavailable +(for example `unknown_subcommand` for `plan export`). The fallback reads the +plan artifact through Spek's existing store boundary: + +```text +spektacular plan file read <name>/tasks.json +spektacular plan file read <name>/plan.md +``` + +The preferred fallback file is `<name>/tasks.json`, using the same shape Hive +asked upstream to standardize: + +```json +{ + "kind": "plan", + "name": "000057_git-commit", + "tasks": [ + { + "id": "T1", + "title": "Add encoding helpers", + "repo": "hivecommons/hive", + "depends_on": ["T0"], + "execution": "agent_suitable" + } + ] +} +``` + +If `tasks.json` is absent, Hive parses a deliberately small `plan.md` task-list +convention from the same plan directory: + +```markdown +- [T1] Add encoding helpers (repo: hivecommons/hive) [agent_suitable] +- [T2] Wire helpers into the parser (depends: T1) +``` + +`repo`, `depends`, and the trailing execution marker are optional; a missing +task id is assigned in order (`T1`, `T2`, ...). If neither fallback yields a +task list, the final plan stays parked and the runner logs the import error. + +The epic is found by its `run_key` metadata (or created with it, bound to the +run key as its external ref). Its plan is a DRAFT: the run-stage work source +lists `implement` only after `ApprovePlan` (`POST /api/plans/{id}/approve`) +sets `plan_status` to `approved`. A run whose epic already carries a plan is +not re-imported. + +## Continuous convergence (retired) + +Campaign recheck (scheduler-owned recheck revisions, outward discovery and the +`POST /api/campaigns/{id}/recheck` endpoint) was retired with inception +campaigns. `runs.spektacular.recheck` is still accepted in `hive.yaml` so an +existing file keeps loading and validating, but it has no effect and Hive logs a +one-line deprecation warning; remove the block. The design history is in +[ADR-0020](/docs/hive/adr/0020-spek-continuous-convergence). + +## Defensive handling of the open questions + +The #8227 questions were answered on jumppad-labs/spektacular#45. The runner +encodes the answers and still handles the alternatives it cannot rule out: + +- **The bare artifact name is the join key.** The stable key across spek, + plan and implement is the artifact name itself (`000057_git-commit`), + shared by convention across the spek file, the plan directory and the + changelog record, and recorded as the workflow's `data.name`. It is NOT the + `spec:` / `plan:` frontmatter cross-references the status response also + carries: those are almost never populated (0 of 57 speks, 3 of 55 plans in + the Spek repository itself), so the runner surfaces them as + `ArtifactStatus.Spec` / `.Plan` for diagnostics only and never joins on + them. Every spelling of an address (`<name>.md`, `<name>/plan.md`) reduces + to the bare name before it reaches the CLI. If a status answer ever + carries a different bare `name` than the one requested, the runner treats + it as a contract violation and does not advance. +- **Invalidation after `final`.** If `document_status` goes from `final` back + to `draft` under the same name, the runner treats the artifact as a stale + plan: it refuses to advance, logs, and records `lease_stage_refused` with + reason `stale_plan`. If the artifact the lease is bound to disappears after + having been observed (a new document with a new name replaced it), the + runner refuses with reason `replaced_document` and parks the lease for an + explicit reset. It never rebinds a lease to a document it was not minted + for. A parked stage is polled again only after its generation changes. + +## What Hive never does + +Hive never opens a Spek file. Every fact about an artifact reaches the +runner through the CLI boundary (`Runner.Exec`), which is also the seam tests +replace. `TestNoDirectFileAccess` in `pkg/spektacular` scans the package for +file access to keep it that way. + +## Contract: what is confirmed, what changed, what is still open + +`pkg/spektacular/testdata/spektacular-fake/spektacular` is a shell fake of the +CLI. It encodes the per-artifact status contract exactly as +jumppad-labs/spektacular#45 ships it, after the Spek maintainer's +review of 2026-09-23 answered the questions Hive had left open. The original +assumptions from the first cut of the runner (PR #8398) and their fate: + +Confirmed: + +1. `spektacular <spec|plan> status <name>` prints one JSON object with + `kind`, `name`, `document_status` (`draft|final`), `current_step`, + `completed_steps[]`, `created_at`, `updated_at`, `closed_at` (#8301). The + response also carries `error: false` (every Spek result does) and + the `spec` / `plan` frontmatter cross-references. `created_at` and + `closed_at` are frontmatter dates emitted as RFC3339 midnight UTC. +2. A missing artifact exits non-zero and prints the JSON error envelope on + stdout. The code is `artifact_not_found` (the `file` verbs use + `not_found` for the same condition; both are typed as `NotFoundError`). +3. Returning a `final` artifact to `draft` flips `document_status` on the + same document and clears its close date; it does not create a new + document. This is stated in the #45 description from the metadata + lifecycle rules and was not contradicted in review, though the maintainer + did not address it explicitly. The `stale_plan` refusal is therefore the + normal invalidation path and `replaced_document` the exception. + +Changed: + +4. The join key is the bare artifact name, not the `spec:` / `plan:` + cross-references (see above). Hive now strips a document path and a + markdown extension from every address before it reaches the CLI. +5. The error envelope is `{"error": true, "code", "message", "resource", + "next_action"}`, not `{"error": "<message>", "code"}`. The parser accepts + both (the string form stays as a defensive fallback). +6. `updated_at` is "last modified", not "last activity", and may be absent. + Hive no longer uses it anywhere: the receipt ends at `closed_at` (or the + advance instant) and its input hash excludes `updated_at` so two + observations of one final document hash the same. +7. `closed_at` is `""` while the document is open, not `null`; `created_at` + may be `""` when the frontmatter carries no date. Both decode as unknown. +8. There is no `--json` flag on any verb (`unknown flag: --json`); output is + already JSON. Hive passes none. `spec file list` / `plan file list` + likewise take no flag; Hive does not call them today, but Spek may + add a `ModTime` per list entry so one list call can replace N status + calls, which is the shape a future list-based poll would consume. +9. `plan status <name>` reports `plan.md` only (`PlanFilePath` hardcodes + it), so a plan's `document_status` is that of `plan.md`, not of the whole + plan document set. Hive advances on it as the plan's status; if a plan + ever grows documents whose completion matters, the verb has to widen + first. + +Still open: + +10. `spektacular plan export <name> --format json` printing `{kind: "plan", + name, tasks: [{id, title, repo, depends_on, execution}]}` for a final plan + is still an upstream ask + ([spektacular#50](https://github.com/hivecommons/spektacular/issues/50)). + Until it lands, Hive advances final plans through the documented + `<name>/tasks.json` or `<name>/plan.md` fallback contract above. + +Scenarios: `draft-final` (draft, draft, final), `never-final`, +`final-then-draft`, `final-no-updated-at` (final with the `updated_at` +member absent), `missing`, selected through `SPEK_FAKE_SCENARIO`. The fake +answers `artifact_not_found` for a name spelled with an extension or a +document path, as the real store does, and a usage error for `--json`. + +## Related + +- [work-sources.md](/docs/hive/work-sources): run stages as work items + (`run_stages: true`) and the `<repo>!<runKey>:<stage>` key. +- [hooks.md](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md): the `stage_completed` transition. +- [design/run-artifacts.md](https://github.com/hivecommons/hive/blob/v5/src/docs/design/run-artifacts.md): multi-repo waves. diff --git a/docs/content/hive/token-mint.md b/docs/content/hive/token-mint.md new file mode 100644 index 0000000..6025eb4 --- /dev/null +++ b/docs/content/hive/token-mint.md @@ -0,0 +1,196 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/token-mint.md) during the docs build. Edit the canonical source in the Hive repository. + +# Token mint (`mint:` config block) + +The `mint:` block configures Hive's opt-in OIDC token mint +(`pkg/mint`) — a short-lived, scoped-JWT issuer that lets agents (and +external Workload Identity Federation brokers) obtain a bounded-lifetime +credential instead of a long-lived shared secret. This page is the +operator-facing companion to +[ADR-0007: Mint short-lived scoped agent credentials](/docs/hive/adr/0007-token-mint), +which records the design decision; read that first for *why* this exists. +This page covers *how to configure it* and, more importantly, **what an +operator must get right for the trust boundary to hold.** + +**Disabled by default.** An absent `mint:` block, or `enabled: false`, is +byte-identical to a hive with no mint — the config comment says so +explicitly (`pkg/config/config.go:222-226`), and this document exists +because the feature had zero operator docs before this page. + +## What it issues, and to whom + +The mint signs short-lived RS256 JWTs (`pkg/mint/mint.go:34-186`). Each +token carries: + +- **Standard claims** — `iss` (the configured `issuer`), `sub` (the + requesting subject — for agent tokens, the agent's name), `aud` (a fixed + audience string), `exp`/`iat`/`nbf`/`jti`. +- **`scopes`** — a custom claim listing what the bearer may do, e.g. + `issues:read`, `contents:write`, `pulls:merge` + (`pkg/mint/agent.go:27-38`). +- **`hive_id`** — which hive minted the token. + +For agent credentials specifically (`pkg/mint/agent.go`), scopes are derived +from the agent's existing trust tier — the same tier string +`AgentMode.TokenTier()` already produces (`advisor`/`newcomer`/ +`contributor`/`trusted`) — mapped through a fixed, fail-closed table +(`tierScopes`, `agent.go:43-48`): + +| Tier | Scopes granted | +|---|---| +| `advisor` | `issues:read` | +| `newcomer` | `issues:read`, `issues:write` | +| `contributor` | `issues:read`, `issues:write`, `contents:write`, `pulls:write` | +| `trusted` | `issues:read`, `issues:write`, `contents:write`, `pulls:write`, `pulls:merge` | +| *unrecognized tier* | falls back to `advisor` (read-only) — **never** widens on a typo (`agent.go:53-58`) | + +The audience embedded in agent tokens is the fixed constant `hive-agent` +(`agentTokenAudience`, `agent.go:22`) — a downstream WIF/verifier is +configured to accept exactly this audience for hive agent workloads. + +**This supplements, not replaces, the GitHub App token path.** An agent that +gets a mint token keeps using its GitHub App token for GitHub operations; +the mint token is an *additional* credential a WIF-aware external system +(cloud provider, container registry) can accept +(`main.go:2152-2164`, ADR-0007 "Consequences"). + +## Config shape + +```yaml +mint: + enabled: true # default false — the mint is off unless you turn it on + key_path: /data/mint-signing-key.pem # required when enabled + issuer: https://your-hive.example.com # required when enabled — see "Choosing issuer" below + max_ttl_seconds: 900 # optional — default 900 (15m), hard-capped at 3600 (1h) +``` + +Fields (`MintConfig`, `pkg/config/config.go:227-239`): + +| YAML key | Go field | Required (when `enabled: true`) | Default | Notes | +|---|---|---|---|---| +| `enabled` | `Enabled` | — | `false` | Turns the service on. `buildAgentMinter` is only invoked when this is `true` (`main.go:1870-1871`). | +| `key_path` | `KeyPath` | **Yes** | — | PEM path of the RSA signing key. Startup fails with `mint.key_path is required when mint is enabled` if empty while `enabled: true` (`main.go:855-857`). | +| `issuer` | `Issuer` | **Yes** | — | The `iss` claim, and the identity string WIF providers are configured to trust — typically the hive's public URL. Startup fails with `mint.issuer is required when mint is enabled` if empty (`main.go:858-860`). | +| `max_ttl_seconds` | `MaxTTLSeconds` | No | `900` (15m, `mint.DefaultMaxTTL`) | Bounds a minted token's lifetime. **Clamped, never trusted verbatim**: any configured value is silently clamped into `[MinTTL 1m, HardCapTTL 1h]` (`mint.go:96-111,172-186`) — you cannot configure a token that outlives one hour no matter what you set here. | + +There is no field for scopes, entitlements, or a listener address in +`MintConfig` — those live outside `hive.yaml` today (see Trust boundary +below). + +## Key lifecycle + +`key_path` is loaded — or, if the file doesn't exist, generated and +persisted — by `mint.LoadOrCreateKey` (`mint.go:277-353`, called from +`main.go:1208`): + +- A missing key file causes a **fresh 2048-bit RSA key to be generated** and + written as PKCS#8 PEM with **`0600` permissions**, atomically (temp file + + rename, so a crash mid-write never leaves a partial key on disk). +- An existing file is parsed (PKCS#8, falling back to PKCS1 for keys written + by other tooling) and reused. +- **There is no rotation mechanism in this codebase.** Nothing rotates + `key_path` automatically. Rotating means: generate a new key out of band + (or delete the file and let the mint regenerate one on restart), update + any WIF provider's trusted-key configuration to the new `kid`/JWKS entry, + and expect a window where tokens signed by the old key are still being + verified by providers that haven't picked up the new JWKS yet. Plan key + rotation as a coordinated operator action, not an automated one. +- `key_path` must be on **persistent storage** the hive process can write + (e.g. under `/data`) — if it lives on ephemeral storage, every restart + mints a brand-new key, and every WIF provider trusting the old key's JWKS + entry starts rejecting the hive's tokens until reconfigured. + +## Choosing `issuer` + +`issuer` is checked on every `Verify` call (`mint.go:196-221`, `jwt.WithIssuer`) — +a token is only valid against a minter configured with the exact same +issuer string. Set it to the stable, public URL a WIF provider (or any other +verifier) will be configured to trust. Changing `issuer` after external +providers have been configured against the old value breaks verification for +every token issued with the new value until the provider config is updated +too — treat it as effectively immutable once anything trusts it. + +## The JWKS endpoint — and what is NOT wired + +ADR-0007 and the mint package describe a `.well-known/jwks.json` endpoint +that downstream WIF providers fetch to verify tokens (`Minter.JWKS`, +`mint.go:237-254`). **As of this branch, nothing in the hive process serves +that endpoint.** `pkg/mint/README.md` states this explicitly: + +> `Server.Handler()` returns a handler; it does not listen. Nothing in this +> repo currently serves it — the mint is used in-process through +> `AgentMinter`. Whoever wires a listener owns the short-term hardening the +> finding asks for: bind it to localhost or a pod-internal interface, and do +> not expose `/mint` beyond the pod network. + +Confirmed by search: no route registers `jwks` or `well-known` anywhere +under `pkg/dashboard/` or `cmd/hive/`. Today, `mint.enabled: true` only +wires the in-process `AgentMinter` that stamps agent-scoped tokens +(`main.go:1870-1877`) — it does **not** stand up an HTTP `/mint` endpoint or +a public JWKS endpoint. If your use case needs an *external* WIF broker +(GCP/AWS/Azure/registry) to independently verify hive-minted tokens over +HTTP, that transport does not exist yet in this codebase; enabling `mint:` +today only benefits in-process consumers of `AgentMinter`. + +## Trust boundary — read this before enabling + +This is the security-sensitive part. State these plainly to yourself before +turning `mint.enabled: true` on: + +1. **Who can obtain a token today**: only in-process callers holding an + `*mint.AgentMinter` — currently the agent manager, which mints a token + per agent on the same refresh cadence as its GitHub App token. There is no + exposed HTTP endpoint for an external caller to request a mint token from + this hive (see JWKS section above). +2. **What a token grants**: exactly the scopes for the subject's tier — + never more (fail-closed on unknown tiers, `agent.go:53-58`) — for the + fixed `hive-agent` audience, for at most `min(max_ttl_seconds, + 3600s)`. A minted token by itself is not a GitHub credential and grants + nothing against GitHub's API; it only means something to a verifier that + has been separately configured to trust this hive's `issuer` (via a JWKS + fetch mechanism you must supply, since this repo doesn't serve one yet). +3. **What the private key protects**: everything. Anyone who can read + `key_path` can forge a token with **any** subject, **any** scopes + (nothing enforces the tier table outside `AgentMinter.MintAgentToken` + itself — a caller using `Minter.Mint` directly is not restricted to + `tierScopes`), and up to the hard-cap TTL. `key_path` must be `0600`, + owned by the process user, and on storage an attacker who compromises one + agent's sandbox cannot read. Never commit it, never log it, never put it + in a ConfigMap — this repo's own dashboard code deliberately omits + `KeyPath` from every operator-facing status payload for exactly this + reason (`status_builder.go:438-447`, `api_governor_features.go:27-29` + comment: "the dashboard overlay is deliberately secret-free"). +4. **What "leaked" costs you**: bounded blast radius by design (ADR-0007 + Consequences) — a leaked minted token expires within the hour at the + absolute worst, and its scopes are capped to one trust tier's ladder. It + is not equivalent in blast radius to leaking `key_path` itself (point 3), + which is unbounded until you rotate. +5. **What an operator must never do**: never hand-write a value into + `key_path`'s target file, never set `max_ttl_seconds` expecting it to + exceed one hour (it won't — the clamp is silent, not an error, so a + config claiming a longer TTL will look accepted but simply be + ineffective), and never treat `mint.enabled: true` as adding + external-facing authentication surface — it does not, until a listener is + wired. + +## Dashboard visibility + +An owner can toggle `mint.enabled` and `mint.issuer` from the Governor +config dialog (`POST` handled by `handleGovernorFeatures`, +`api_governor_features.go:136-139`) — but **not** `key_path`, by design; the +signing key never appears in any dashboard payload. Status reporting +(`status_builder.go:505-514`) exposes only `enabled`, `issuer`, and a +boolean `keyPresent` (whether the file at `key_path` currently exists) — +never the key material or the path itself in a form that leaks key location +semantics beyond presence. + +## Open questions + +- No HTTP listener for `POST /mint` or `.well-known/jwks.json` exists in + this branch's `cmd/hive/main.go` or `pkg/dashboard`. Until one is wired, + `mint:` only benefits in-process agent-credential issuance + (`AgentMinter`), not external WIF exchange. Treat any plan that assumes an + externally reachable mint endpoint as **not yet implemented** rather than + a configuration gap on the operator's side. +- Key rotation is entirely manual/out-of-band; there is no `hivectl` or + dashboard action that rotates `key_path` for you. diff --git a/docs/content/hive/trajectory-review.md b/docs/content/hive/trajectory-review.md new file mode 100644 index 0000000..5e2bf5c --- /dev/null +++ b/docs/content/hive/trajectory-review.md @@ -0,0 +1,210 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/trajectory-review.md) during the docs build. Edit the canonical source in the Hive repository. + +# Trajectory-Review Lane + +The **trajectory-review lane** is a safety layer (on by default) that periodically reads +each running agent's recent transcript and asks a second model whether the +*sequence* of actions is still working toward the agent's assigned intent. If +the trajectory has diverged — individually-innocuous steps assembling toward an +outcome the intent does not authorize — the lane pauses the agent (or alerts) +and records an audit entry. + +It targets **trajectory-level goal drift**: the failure mode where no single +action trips an allow/deny check, but the arc of the session heads somewhere it +should not (escaping a sandbox, evading a scanner, splitting a credential to +avoid detection, escalating privileges, or adopting a goal taken from repo +content instead of the operator's instruction). Per-action gating cannot see +this; only looking at the direction of the whole sequence can. + +## How it works + +The lane runs off the governor tick, after the eval cycle (so each agent's +intent — its last kick — is current), gated by its own cadence: + +1. Snapshot every **running, non-paused, non-exempt** agent, with its assigned + intent (last kick message) and a tail of its live tmux transcript. +2. For each, send `{intent, transcript-tail}` to the reviewer model via the + hive's existing LiteLLM endpoint and get back a compact verdict: + `{divergent, confidence, reason}`. +3. On a divergent verdict, apply the configured response: **pause** the agent + and raise an error alert + notification, or **alert** only. + +The reviewer is instructed to judge *direction*, not any single line, and to +default to non-divergent when unsure — so ordinary engineering work (reading +code, running tests, opening a PR that matches the intent) is never paused on a +low-signal read. + +### Fail-open by design + +A reviewer outage (endpoint down, timeout, unparsable reply) yields a +non-divergent verdict: a broken reviewer must never pause a working fleet. Each +review has its own 30-second timeout so the lane cannot stall the governor. + +### Cost control + +Only a bounded transcript tail is sent (default 120 lines, hard-capped at +24 000 chars), at `temperature=0` with a 200-token cap, on a cadence you set +(default every 600 s, floored by the governor eval interval). A cheap reviewer +model is appropriate — this is a divergence classifier, not a coding model. + +A review is **skipped** only when the agent manager's own state proves the +agent idle (its last kicked turn has ended, or it is parked at the prompt +waiting on CI), it has produced no output since its last review, and the review +is not overdue (fewer than 6 intervals since the last review). Otherwise it +runs. The transcript itself is never used as a skip signal: a stalled tail on an +agent whose turn is still in progress is exactly what the reviewer should see +(see [ADR-0009 addendum](/docs/hive/adr/0009-trajectory-review)). Each skip is logged +(`trajectory review skipped agent=… reason=idle-no-new-output`), counted in the +Trajectory Review panel, and exported on `/metrics` as +`hive_trajectory_reviews_total{decision}` / `hive_trajectory_skipped_total{reason}`. + +## Configuration + +**Dashboard:** Governor Config → **Features** tab has a full **Trajectory Review** +panel: an on/off toggle (on by default), a status chip that distinguishes +*On — active* from *On — no reviewer endpoint (not running)* so the control is +never silently inert, an explanation of why it exists and what it requires, and +inline fields for the reviewer model, review interval, reviewer endpoint, and +the pause/alert-only choice. Changes persist immediately and take effect on the +next restart. Exemptions remain in `hive.yaml`. + +**hive.yaml** — under `governor.trajectory`: + +```yaml +governor: + litellm: + endpoint: https://litellm.example.com + api_key_env: HIVE_LITELLM_API_KEY + default_model: claude-haiku-4-5 + trajectory: + enabled: true # ON by default; set false to disable + endpoint: "" # reviewer /v1 base URL (LiteLLM/vLLM/llm-d); empty → inherit litellm.endpoint + api_key_env: "" # env var NAME for the reviewer key; empty → inherit litellm key + interval_s: 600 # review cadence (floored by eval_interval_s) + model: claude-haiku-4-5 # reviewer model; empty → litellm.default_model + transcript_lines: 120 # trailing lines sent per agent + on_divergence: pause # "pause" (default) or "alert" + exempt_agents: # never reviewed + - quality # advisory-only agent that opens no PRs +``` + +| Field | Default | Meaning | +| --- | --- | --- | +| `enabled` | `true` | Turn the lane on/off. Also on the Governor → Features tab. No reviews run (zero cost) until a LiteLLM reviewer endpoint is configured. | +| `interval_s` | `600` | Seconds between reviews; the governor eval interval is the floor. | +| `model` | `litellm.default_model` | Reviewer model id sent to LiteLLM. | +| `transcript_lines` | `120` | Trailing transcript lines sent per agent. | +| `on_divergence` | `pause` | `pause` stops the agent + alerts; `alert` only notifies. | +| `exempt_agents` | `[]` | Agents never reviewed. | + +### Reviewer endpoint + +The reviewer needs any **OpenAI-compatible `/v1/chat/completions`** endpoint — +a **LiteLLM** gateway, a **vLLM** server, or an **llm-d** front. Set +`governor.trajectory.endpoint` (with `api_key_env`/`api_key_file` if the +endpoint needs a key; a bare vLLM server needs none). When left empty, the +reviewer inherits the `governor.litellm` endpoint and key, so no new secret is +introduced for hives that already run LiteLLM. Pointing the reviewer at a cheap +local vLLM model is a good way to run oversight without spending gateway tokens. + +Protocol compatibility is all that's required — but model *capability* still +matters: a tiny local model emits weaker verdicts. Because the lane fails open, +a weak reviewer degrades toward "catches less," not "false-pauses everything." + +## Backend and model coverage + +The lane reads each agent's **tmux transcript**, which every CLI backend writes +to — so it works identically for `claude`, `copilot`, `gemini`, `goose`, +`bob`, and the self-hosted inference backends. It does not depend on a +provider-specific trace format. + +Two honest limits: + +- **It reads the rendered transcript, not hidden chain-of-thought.** It judges + what the agent *does and says in its session*, which is where drift becomes + observable — but a model that reasons silently and acts minimally gives it + less to see. This is why the lane is one layer among several (short + re-anchored rollouts, scoped per-task credentials, PR-gated writes), not the + only defense. +- **The reviewer is itself a model.** It can miss or false-positive. Keep the + reviewer model at least as capable as a small frontier model, start in + `alert` mode to calibrate on a given hive's agents, then switch to `pause`. + +## Relationship to other safeguards + +The lane is the semantic-oversight layer. It complements hive's structural +mitigations rather than replacing them: agents are re-kicked with fresh intent +every governor cycle (no hour-one directive to forget), write only via +CI-gated PRs, run under per-task GitHub tokens and per-tier rate limits, and +are already pausable/auditable. Trajectory review adds the missing "what +outcome is this sequence working toward?" check on top. + +## Operator response + +A trajectory-review pause asks for human judgment. The lane pauses the +agent with trigger `trajectory-review`. It deletes nothing. Do not assume +the reviewer is right. + +### Audit entry +The pause writes an audit entry. The user is `trajectory`. The action is +`trajectory-pause`. The detail is `confidence=<pct>% reason=<reason>`. The +entry names the agent in its `agent` field. A system alert accompanies the +pause with id `trajectory-<agent>` at severity `error`. A high-priority +notification is sent when a notifier is configured. Read the entry from +`/data/audit.jsonl`. The dashboard Audit page shows it. The API serves it +at `GET /api/audit`. The CLI reads it: + +```bash +hivectl observe audit +``` + +Alert-only mode (`on_divergence=alert`) writes action `trajectory-alert` +with severity `warning`. It does not pause the agent. + +| Field | Value | Meaning | +| --- | --- | --- | +| `user` | `trajectory` | The lane that wrote the entry. | +| `action` | `trajectory-pause` | The agent was paused. Alert-only mode writes `trajectory-alert`. | +| `detail` | `confidence=<pct>% reason=<reason>` | Reviewer confidence and the reason for the verdict. | +| `agent` | `<name>` | The paused agent. | + +### Read the transcript +The lane reads the last 400 lines of the agent's tmux pane. The reviewer +sees the configured `transcript_lines` (default 120). Inspect the same +pane from the dashboard agent view, or read the tail with: + +```bash +hivectl agent logs <name> --lines N +``` + +### False positive or genuine divergence +The reviewer judges direction, not any single line. It defaults to +non-divergent when unsure. The lane fails open on a reviewer outage. A +flagged sequence is not proof of drift. Compare it with the agent's +assigned intent, its last kick. + +- A false positive still serves the assigned intent. Resume the agent. +- Genuine divergence heads where the intent does not authorize. Keep the + agent paused and fix its intent before resume. + +Checklist: +- [ ] Read the audit entry: confidence and reason. +- [ ] Read the transcript tail in the dashboard agent view. +- [ ] Compare the flagged actions with the agent's last kick. +- [ ] Resume the agent after a false positive. +- [ ] Correct the intent before resume after genuine divergence. + +### Paused state and resume +While paused, the governor issues no kicks. The pause sends Ctrl-C to the +tmux session. The in-flight command stops. Beads and work items are kept. +Resume from the dashboard pause/resume toggle (`POST /api/resume/<name>`, +owner role required), or use the CLI: + +```bash +hivectl agent resume <name> +``` + +Resume clears the paused flags, persists, and force-relaunches the session. +Normal cadence kicks resume after relaunch. Start the lane in alert mode +first. Calibrate on a given hive's agents before you switch to pause. +See [agent configuration](/docs/hive/agent-configuration) and [hivectl](/docs/hive/hivectl). diff --git a/docs/content/hive/upstream-watch.md b/docs/content/hive/upstream-watch.md new file mode 100644 index 0000000..515e49a --- /dev/null +++ b/docs/content/hive/upstream-watch.md @@ -0,0 +1,228 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/upstream-watch.md) during the docs build. Edit the canonical source in the Hive repository. + +# Upstream watch + +A repo that began as a fork drifts from its upstream until git-level sync stops +being viable. The `upstream_watch` block declares, per repo, which upstream to +follow and how much of it to surface. It is **off by default**. + +When it is on, the hive polls each configured upstream and opens a labelled +issue in the fork for every merged PR or release that still applies, so the +existing fixer agents pick the port up like any other issue. It opens issues +only, never PRs. Tracking issues: +[#9963](https://github.com/hivecommons/hive/issues/9963), +[#9967](https://github.com/hivecommons/hive/issues/9967). + +## Configuration + +```yaml +upstream_watch: + enabled: true + interval: 6h # default 6h + repos: + myorg/forked-thing: # must be in project.repos (bare or org-qualified) + upstream: origin-owner/thing # optional + sources: [releases, prs] # default: both + pr_labels: [bug, security] # empty = all merged PRs + max_issues_per_run: 5 # omit = no cap + label: upstream/port # default upstream/port +``` + +| Key | Default | Notes | +|---|---|---| +| `enabled` | `false` | Master switch. | +| `interval` | `6h` | Poll cadence; must not be negative. | +| `repos.<repo>.upstream` | fork parent | `owner/repo`. If omitted it is resolved from the GitHub fork parent (`parent.full_name`) at runtime; an explicit value always wins. | +| `repos.<repo>.sources` | `[releases, prs]` | Known values: `releases`, `prs`. | +| `repos.<repo>.pr_labels` | all merged PRs | Only PRs carrying one of these labels. | +| `repos.<repo>.max_issues_per_run` | no cap | Must be positive when set. | +| `repos.<repo>.label` | `upstream/port` | Label on filed issues. | + +Loading fails if a `repos` key is not in `project.repos`, `upstream` is not +`owner/repo`, a source is unknown, or `max_issues_per_run` is negative. + +## The loop + +The governor's eval tick runs the watch at most once per `interval`. For each +repo under `upstream_watch.repos`, in key order, one pass: + +1. Lists upstream PRs merged (`merged_at`) and non-draft releases published + (`published_at`) strictly after the repo's watermark, filtered by + `sources` and `pr_labels`, oldest first. +2. Classifies each item as `security`, `bugfix`, `feature` or `chore` from + its labels and conventional-commit title prefix, and estimates the port + difficulty (`easy`, `moderate`, `hard`) from files and lines changed. +3. Checks applicability without a checkout: through the GitHub contents API, + at least one touched file must exist on the fork's default branch. An item + with none is recorded as `skipped`. Releases carry no file list and are + always applicable. +4. Files an issue for the rest, titled `upstream: <upstream title>`, with the + upstream link, a summary of the upstream body, the class, the affected + files, the difficulty estimate and a hidden marker such as + `<!-- upstream-ref: owner/repo#123 -->` (`owner/repo@<tag>` for a + release). The configured `label` (default `upstream/port`) is applied. + Mentions copied from upstream are neutralised so nobody upstream is pinged. +5. Advances the watermark past every item that was filed, skipped or + deduplicated. +6. Reconciles every previously filed ref against its fork issue: still open + leaves it `filed` (surfaced), closed as completed becomes `ported`, closed + as *not planned* or labelled `upstream/dismissed` becomes `dismissed`. A + ref filed earlier in the very same pass is left alone — it was just + opened, so it is certainly still open. The watermark is not touched by + this step; it already moved past a ref when the ref was first filed. + +`max_issues_per_run` stops a repo's pass after that many issues; the remaining +items stay behind the watermark and are picked up next pass. A GitHub error +stops the repo's pass the same way, after saving what was already handled. +Cancelling the hive's context stops the loop between items with the state +saved. + +## Dedupe and dismissal + +Each upstream item has a ref: `upstream#<pr>` or `release:<tag>`. + +- **State index first.** A ref with any recorded outcome is never filed again. +- **Marker search second.** Before filing, the fork is searched for the hidden + marker. A match is recorded as filed against that issue instead of opening a + duplicate, which covers a lost or restored state file. +- **Dismissal.** If the matching fork issue was closed as *not planned* or + carries the `upstream/dismissed` label, the ref is recorded as `dismissed` + and never resurfaced. + +## Reconciliation + +Filing an issue is not the end of a ref's story: the fork issue it opened can +later be closed. Every pass, after filing new items, the watch looks up each +previously filed ref's fork issue (skipping any ref it just filed in this same +pass) and updates the recorded status from what it finds: + +| Fork issue | Recorded status | +|---|---| +| still open | `filed` (surfaced) | +| closed, `state_reason: completed` | `ported` | +| closed, `state_reason: not_planned`, or labelled `upstream/dismissed` | `dismissed` | +| closed for any other reason | left unchanged | + +This is the only place `ported` is ever recorded: nothing marks a ref ported +at filing time, since the fork issue has only just been opened. A lookup +failure (for instance a rate limit) stops the reconciliation pass the same way +a filing error stops the filing pass — the rest is retried next run — and +never moves the watermark, which already advanced past the ref when it was +first filed. + +## Dashboard and API + +The Features tab of the dashboard carries an **Upstream Watch** panel: one +table per watched fork with the upstream it follows, the watermark and the +time of the last run, the surfaced / ported / dismissed / skipped counts, and +the recent upstream refs with their fork issue and state. Each recent pull +request offers *port this* — a link to the upstream patch. + +The panel is also the editor for the block, so `hive.yaml` is optional: + +- **Watch enabled** switches `upstream_watch.enabled`; **Poll interval** sets + `interval` (blank = 6h). +- **Add fork** lists only repos already in `project.repos` that are not yet + watched, and adds the bare repo name — the same spelling the Repos tab + stores. +- Each watched fork has its own row: `upstream` (blank = the GitHub fork + parent), the sources (releases, merged PRs), the PR label filter, the + per-run cap and the issue label, with **Save** and **Remove**. + +Edits are persisted to the config and take effect on the next poll — no +restart. Removing a repo in the Repos tab also drops its `upstream_watch` +entry (and an org change clears them all), so the saved config always passes +the loader's validation. + +It reads `GET /api/upstream-watch` (owner only), which is the same view as +JSON: + +```json +{ + "enabled": true, + "configured": true, + "state_path": "/data/upstream-watch.json", + "repos": [ + { + "repo": "myorg/forked-thing", + "upstream": "origin-owner/thing", + "watermark": "2026-01-02T03:04:05Z", + "last_run_at": "2026-01-02T04:00:00Z", + "surfaced": 3, "ported": 1, "dismissed": 1, "skipped": 1, + "recent": [ + { + "ref": "upstream#12", + "upstream_ref": "origin-owner/thing#12", + "upstream_url": "https://github.com/origin-owner/thing/pull/12", + "diff_url": "https://github.com/origin-owner/thing/pull/12.diff", + "status": "filed", "state": "surfaced", + "issue_number": 77, + "issue_url": "https://github.com/myorg/forked-thing/issues/77", + "recorded_at": "2026-01-02T00:00:00Z" + } + ] + } + ] +} +``` + +The response also carries `interval`, `project_repos` (the repos the editor +may add) and, per repo, `config` — the entry as configured, which the editor +prefills. + +The GET endpoint is strictly read-only: it reads the config and the state file +and never polls GitHub, so refreshing the panel costs no API quota. `state` is the +recorded outcome as the watch knows it — `surfaced` while the fork issue is +open, `ported` once the issue is completed, `dismissed` when it was closed as +*not planned* or labelled `upstream/dismissed`, `skipped` when no touched file +exists in the fork. A repo that is configured but has never run appears with +empty times and zero counts; an unreadable state file is reported as +`state_error` rather than silently looking idle. + +Edits go to `PUT /api/config/upstream-watch` (owner only). Every key is +optional and an absent key is left unchanged; a repo mapped to `null` is +removed, and a repo key may be bare or qualified with `project.org` (it is +stored bare): + +```json +{ + "enabled": true, + "interval": "6h", + "repos": { + "forked-thing": {"upstream": "origin-owner/thing", "sources": ["prs"], "pr_labels": ["bug"], "max_issues_per_run": 5, "label": "upstream/port"}, + "old-fork": null + } +} +``` + +The edit is validated with the same rules as `hive.yaml` before anything +changes; a rejected edit returns `400` with the reason and leaves the config +untouched. + +## Port this + +A fork issue the watch filed carries the hidden `upstream-ref` marker, so the +kick that offers it to a fixer can hand over the upstream patch with it. When +an issue carrying the configured label (default `upstream/port`) appears in a +kick list, the list entry gains one line: + +```text + 12m myorg/forked-thing#77 [upstream/port] upstream: fix the thing + ↳ upstream patch: https://github.com/origin-owner/thing/pull/12.diff — read it first, … +``` + +The URL is rebuilt from the validated `owner/repo#number` marker, never echoed +from the issue body, so an issue cannot inject a link of its own. A release +marker has no diff and gets no line. + +## State file + +The watermark, last-run time and per-ref outcomes (`filed`, `skipped`, +`ported`, `dismissed`, with the fork issue number) are kept in +`/data/upstream-watch.json` on the PVC, written atomically, so a restart never +re-scans an upstream from zero. A corrupt file stops the watch rather than +refiling everything. + +Sources: `src/pkg/config/upstream_watch.go`, `src/pkg/upstreamwatch/`, +`src/cmd/hive/upstream_watch.go`, `src/pkg/dashboard/api_upstream_watch.go`, +`src/pkg/scheduler/kickmessage.go`. diff --git a/netlify.toml b/netlify.toml index 6b16b9f..4e8b6b3 100644 --- a/netlify.toml +++ b/netlify.toml @@ -143,6 +143,24 @@ to = "/docs/spektacular/overview/introduction" status = 302 +# Hive pages that moved between nav sections (hivecommons/docs#740). The old +# nav-slug URLs were published, so keep inbound links and dashboard help links +# working. The flat /docs/hive/<file> URLs are unchanged and still resolve. +[[redirects]] + from = "/docs/hive/operations/hosted-hive-hub-onboarding" + to = "/docs/hive/hub/hosted-hive-hub-onboarding" + status = 301 + +[[redirects]] + from = "/docs/hive/operations/self-hosted-hub-deployment" + to = "/docs/hive/hub/self-hosted-hub-deployment" + status = 301 + +[[redirects]] + from = "/docs/hive/security/data-collection-and-telemetry" + to = "/docs/hive/dashboard/data-collection-and-telemetry" + status = 301 + # Short URLs [[redirects]] from = "/code" diff --git a/scripts/sync-hive-docs.files.json b/scripts/sync-hive-docs.files.json index 8e1e24b..efcd072 100644 --- a/scripts/sync-hive-docs.files.json +++ b/scripts/sync-hive-docs.files.json @@ -400,20 +400,144 @@ { "source": "ui-render-evidence.md" }, + { + "source": "advisory.md", + "route": "operations/automation-and-review/advisory-digest" + }, + { + "source": "agent-logging.md", + "route": "operations/agent-and-governor-controls/agent-peer-awareness-logging" + }, + { + "source": "agent-watchdog.md", + "route": "operations/agent-and-governor-controls/agent-watchdog" + }, + { + "source": "audit-campaign.md", + "route": "operations/automation-and-review/audit-campaign" + }, + { + "source": "backend-support-tiers.md", + "route": "operations/agent-and-governor-controls/agent-backend-support-tiers" + }, + { + "source": "cel-triggers.md", + "route": "operations/automation-and-review/cel-triggers" + }, + { + "source": "cli-pins.md", + "route": "operations/agent-and-governor-controls/cli-pins" + }, + { + "source": "compliance.md", + "route": "security/compliance-controls" + }, + { + "source": "contributor-trust-and-roles.md", + "route": "security/contributor-trust-and-roles" + }, { "source": "dashboard.md", - "comment": "Dashboard pages the dashboard help links and Ask AI answers rely on (hivecommons/hive#19182)." + "route": "dashboard/dashboard-page-reference" + }, + { + "source": "fleet-health.md", + "route": "hub/fleet-health" + }, + { + "source": "formal-verification.md", + "route": "operations/automation-and-review/formal-verification" + }, + { + "source": "github-app-setup.md", + "route": "integrating-with-hive/github-app-setup" + }, + { + "source": "governor-thresholds.md", + "route": "operations/agent-and-governor-controls/governor-thresholds" + }, + { + "source": "hive-merge.md", + "route": "operations/automation-and-review/hive-merge" + }, + { + "source": "hosted-hub.md", + "route": "hub/hosted-hive-hub-onboarding" + }, + { + "source": "hub-deployment.md", + "route": "hub/self-hosted-hub-deployment" + }, + { + "source": "hub-fleet-activity.md", + "route": "hub/fleet-activity" + }, + { + "source": "ioscan.md", + "route": "security/ioscan" + }, + { + "source": "linear-agent.md", + "route": "integrating-with-hive/linear-agent-integration" + }, + { + "source": "maintainer-commands.md", + "route": "operations/automation-and-review/maintainer-commands" + }, + { + "source": "native-merge-queue.md", + "route": "operations/automation-and-review/native-github-merge-queues" + }, + { + "source": "notifications.md", + "route": "dashboard/notifications" + }, + { + "source": "retro-lane.md", + "route": "operations/automation-and-review/retro-lane" + }, + { + "source": "review-bot-threads.md", + "route": "operations/automation-and-review/review-bot-threads" + }, + { + "source": "review-evidence.md", + "route": "hub/review-evidence-bundle" + }, + { + "source": "review-swarm.md", + "route": "operations/automation-and-review/review-swarm" + }, + { + "source": "sandbox-isolation.md", + "route": "security/sandbox-isolation" + }, + { + "source": "settings.md", + "route": "dashboard/dashboard-settings-explained" + }, + { + "source": "snapshots.md", + "route": "dashboard/public-snapshots" + }, + { + "source": "spektacular.md", + "route": "operations/automation-and-review/spektacular-stage-runner" }, { - "source": "settings.md" + "source": "telemetry.md", + "route": "dashboard/data-collection-and-telemetry" }, { - "source": "hosted-hub.md" + "source": "token-mint.md", + "route": "security/token-mint" }, { - "source": "hub-deployment.md" + "source": "trajectory-review.md", + "route": "operations/automation-and-review/trajectory-review" }, { - "source": "telemetry.md" + "source": "upstream-watch.md", + "route": "operations/automation-and-review/upstream-watch" } ] diff --git a/scripts/sync-hive-docs.unsynced-allowlist.txt b/scripts/sync-hive-docs.unsynced-allowlist.txt index 438121c..e4ff2f3 100644 --- a/scripts/sync-hive-docs.unsynced-allowlist.txt +++ b/scripts/sync-hive-docs.unsynced-allowlist.txt @@ -13,15 +13,11 @@ acmm-advisor.md acmm-waivers.md advisory-staleness.md -advisory.md -agent-logging.md -agent-watchdog.md agents-md.md api-reference.md api-reference/agents-and-controls.md apiproxy.md attention-episodes.md -audit-campaign.md audit-log.md auto-update-profile.md backend-auth-recovery-runbook.md @@ -29,21 +25,16 @@ backend-gap-claude-managed-agents.md backend-gap-openai-agents-api.md backend-omnigent-cli-contract.md backend-smoke.md -backend-support-tiers.md beads-cli.md benchmarks/outcomes-2026-10.md benchmarks/README.md branding.md -cel-triggers.md ci-runner-labels.md -cli-pins.md cncf-reference-architecture.md cncf-sandbox-onboarding.md community.md -compliance.md config-layering.md contributor-token-policy.md -contributor-trust-and-roles.md credly-badges.md cross-cluster-migration.md custom-stylesheets.md @@ -72,32 +63,25 @@ duplicate-sweep.md evidence.md feedback.md fleet-drift-signals.md -fleet-health.md fleet-report.md forge-app-setup.md -formal-verification.md general-technical-review.md -github-app-setup.md github-cli-compact.md github-write-surface.md good-first-issue.md -governor-thresholds.md guide-flow-health.md health-checks.md heartbeat-bearer-cutover.md -hive-merge.md hive-of-the-week.md hive-open-issue.md hive-open-pr.md hivecommons-migration.md hooks.md house-style.md -hub-fleet-activity.md inception.md intent-verification.md ios-widget.md ioscan-red-team.md -ioscan.md issue-labels.md knowledge-confidence.md knowledge-connectors.md @@ -105,9 +89,7 @@ knowledge-curator.md knowledge-lifecycle.md knowledge-toc.md kubernetes-deployment.md -linear-agent.md lite-enrollment.md -maintainer-commands.md migration-v2-v4.md migration-v4-v5.md monitoring.md @@ -115,9 +97,7 @@ move-cross-runtime.md move-host.md move-hub-registered-cutover.md move-kubernetes.md -native-merge-queue.md network-requirements.md -notifications.md nous-hive-self-experiments.md nps.md operations.md @@ -154,19 +134,13 @@ releases.md repo-pause.md research/ablation-plan-2026-10.md research/backfill.md -retro-lane.md -review-bot-threads.md -review-evidence.md review-queue-triage.md -review-swarm.md runs.md -sandbox-isolation.md scale-envelope.md security-response.md security-self-assessment.md security.md skills.md -snapshots.md soc2-control-mapping.md social-cards.md spoke-wildcard-tls.md @@ -177,10 +151,7 @@ supervisor.md swarm.md tls-setup.md token-access-log.md -token-mint.md token-tracking.md -trajectory-review.md -upstream-watch.md v4-freeze-runbook.md v5-candidate-week.md v5-ga.md diff --git a/src/__tests__/netlify-redirects.consistency.test.ts b/src/__tests__/netlify-redirects.consistency.test.ts index 6b7ece7..a089629 100644 --- a/src/__tests__/netlify-redirects.consistency.test.ts +++ b/src/__tests__/netlify-redirects.consistency.test.ts @@ -60,6 +60,17 @@ export function parseTableValue( } const redirects = parseRedirects(NETLIFY_TOML); + +// Published nav-slug URLs that moved when pages changed nav section +// (hivecommons/docs#740). Each old URL must 301 to the page's new nav URL. +const MOVED_HIVE_PAGES: Record<string, string> = { + "/docs/hive/operations/hosted-hive-hub-onboarding": + "/docs/hive/hub/hosted-hive-hub-onboarding", + "/docs/hive/operations/self-hosted-hub-deployment": + "/docs/hive/hub/self-hosted-hub-deployment", + "/docs/hive/security/data-collection-and-telemetry": + "/docs/hive/dashboard/data-collection-and-telemetry", +}; const docsRedirects = redirects.filter(r => (r.from ?? "").startsWith("/docs/") ); @@ -96,6 +107,7 @@ describe("netlify.toml redirects", () => { .filter( from => from !== "/docs/hive/overview/intro" && + !(from in MOVED_HIVE_PAGES) && !known.has(from.replace(/^\/docs\//, "").replace(/\/$/, "")) ); expect(stale).toEqual([]); @@ -109,6 +121,17 @@ describe("netlify.toml redirects", () => { expect(rule?.status).toBe("301"); }); + it.each(Object.entries(MOVED_HIVE_PAGES))( + "redirects moved Hive page %s to %s", + (from, to) => { + const rule = docsRedirects.find(r => r.from === from); + expect(rule, `missing [[redirects]] for ${from}`).toBeDefined(); + expect(rule?.to).toBe(to); + expect(rule?.status).toBe("301"); + expect(rule?.force).toBeUndefined(); + } + ); + it("has exactly one redirect per /docs/* source path", () => { const seen = new Map<string, number>(); for (const r of docsRedirects) diff --git a/src/app/docs/page-map.ts b/src/app/docs/page-map.ts index 33111be..49ceace 100644 --- a/src/app/docs/page-map.ts +++ b/src/app/docs/page-map.ts @@ -127,10 +127,30 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { 'Contributor relay': 'contributor-relay.md' }, { 'Using Spektacular with Hive': 'spektacular-runs.md' }, { 'The agent Terminal window': 'agent-terminal.md' }, + { 'Agent and governor controls': [ + { 'Agent peer-awareness logging': 'agent-logging.md' }, + { 'Agent watchdog': 'agent-watchdog.md' }, + { 'Agent backend support tiers': 'backend-support-tiers.md' }, + { 'CLI pins': 'cli-pins.md' }, + { 'Governor thresholds': 'governor-thresholds.md' }, + ] }, + { 'Automation and review': [ + { 'Advisory digest': 'advisory.md' }, + { 'Audit campaign': 'audit-campaign.md' }, + { 'CEL triggers': 'cel-triggers.md' }, + { 'Formal verification': 'formal-verification.md' }, + { 'Hive merge': 'hive-merge.md' }, + { 'Maintainer commands': 'maintainer-commands.md' }, + { 'Native GitHub merge queues': 'native-merge-queue.md' }, + { 'Retro lane': 'retro-lane.md' }, + { 'Review-bot threads': 'review-bot-threads.md' }, + { 'Review swarm': 'review-swarm.md' }, + { 'Spektacular stage runner': 'spektacular.md' }, + { 'Trajectory review': 'trajectory-review.md' }, + { 'Upstream watch': 'upstream-watch.md' }, + ] }, { 'Troubleshooting': 'troubleshooting.md' }, { 'Kick refusals': 'kick-refusals.md' }, - { 'Hosted Hive Hub onboarding': 'hosted-hub.md' }, - { 'Self-hosted hub deployment': 'hub-deployment.md' }, { 'Release channels': 'release-channels.md' }, { 'Stable soak and promotion policy': 'stable-soak-policy.md' }, { 'Backup and disaster recovery': 'backup-dr.md' }, @@ -141,6 +161,9 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { title: 'Dashboard', items: [ + { 'Notifications': 'notifications.md' }, + { 'Public snapshots': 'snapshots.md' }, + { 'Data collection and telemetry': 'telemetry.md' }, { 'Dashboard sections explained': 'dashboard-sections.md' }, { 'Dashboard settings explained': 'settings.md' }, { 'Dashboard page reference': 'dashboard.md' }, @@ -154,10 +177,22 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { 'Labels glossary and operations': 'labels-and-control-signals/glossary-and-operations.md' }, ] }, + { + title: 'Hub', + items: [ + { 'Hosted Hive Hub onboarding': 'hosted-hub.md' }, + { 'Self-hosted hub deployment': 'hub-deployment.md' }, + { 'Fleet activity': 'hub-fleet-activity.md' }, + { 'Fleet health': 'fleet-health.md' }, + { 'Review evidence bundle': 'review-evidence.md' }, + ] + }, { title: 'Integrating with Hive', items: [ { 'Integration guide': 'integration-guide.md' }, + { 'GitHub App setup': 'github-app-setup.md' }, + { 'Linear agent integration': 'linear-agent.md' }, { 'Public knowledge MCP endpoint': 'public-knowledge-mcp.md' }, { 'Work-source providers': 'integrations/work-source-providers.md' }, { 'Clanker (Flue-style) interface': 'integrations/clanker-flue.md' }, @@ -174,7 +209,11 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { 'Security threat model': 'security-threat-model.md' }, { 'Hive trust levels vs Copilot assisted permissions': 'copilot-permissions-comparison.md' }, { 'ACMM policy matrix': 'acmm-policy-matrix.md' }, - { 'Data collection and telemetry': 'telemetry.md' }, + { 'Compliance controls': 'compliance.md' }, + { 'Contributor trust and roles': 'contributor-trust-and-roles.md' }, + { 'ioscan': 'ioscan.md' }, + { 'Sandbox isolation': 'sandbox-isolation.md' }, + { 'Token mint': 'token-mint.md' }, ] }, {