From a83def867ea15406b7ae92ab26fc216f57d940ed Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 28 Oct 2026 15:55:01 -0400 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=90=9B=20Activity=20monitor:=20one=20?= =?UTF-8?q?merge-gate=20vocabulary=20and=20a=20labelled=20leading=20glyph?= =?UTF-8?q?=20on=20every=20gated=20row?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit At 15:11 ET two Merge gate rows both read 'Ready for auto merge ⬡' while one carried a spinning glyph and the other none. The glyph was the agent-working cue (an agent's lastAction on that PR this round — the review swarm was re-reviewing #15042; nobody was on #15054), unlabelled, so it read as merge progress; and STAGE_TRACKER_ACTIVE_WORD mapped 060, 080 and 100 all to 'Ready for auto merge', so a 060 PR with CI still pending read as ready. - /api/stage-tracker PR items (and nested linked_prs) carry merge_gate {state, reason, sweep_running, last_sweep_at, next_sweep_at, soak_until, soak_remaining_seconds}; automerge gains a SweepClock that records the running pass (cause, targets) and the next floor time. - Pill words in pipeline order: Awaiting merge gate (what holds it) → Ready for auto merge (next sweep in Ns) → Soaking (time left) → Merging → Merged. Every gated row gets a leading glyph with the same sentence as title + aria-label; it spins while a sweep is on the PR, shows a clock while it waits; countdowns tick from the existing cue timer. - The agent-working spinner now carries 'Working now: …' as title + aria-label. - Legend in docs/dashboard-sections.md; node fixture tests on the captured #15042 / #15054 / #15044 payloads; Go tests for merge_gate. Fixes #15073 Signed-off-by: Andrew Anderson --- changelog.d/fixed-merge-gate-pill-glyph.md | 1 + src/docs/dashboard-sections.md | 15 +- src/docs/labels-and-control-signals.md | 2 +- src/pkg/dashboard/server.go | 3 + src/pkg/dashboard/stage_tracker.go | 13 + src/pkg/dashboard/stage_tracker_merge_gate.go | 106 +++++++ .../stage_tracker_merge_gate_test.go | 261 ++++++++++++++++++ src/pkg/dashboard/stage_tracker_ui_test.go | 10 +- src/pkg/dashboard/static/index.html | 163 ++++++++++- .../github/automerge/automerge_forgestate.go | 2 + src/pkg/github/automerge/automerge_sweep.go | 12 + src/pkg/github/automerge/sweep_clock.go | 97 +++++++ 12 files changed, 673 insertions(+), 12 deletions(-) create mode 100644 changelog.d/fixed-merge-gate-pill-glyph.md create mode 100644 src/pkg/dashboard/stage_tracker_merge_gate.go create mode 100644 src/pkg/dashboard/stage_tracker_merge_gate_test.go create mode 100644 src/pkg/github/automerge/sweep_clock.go diff --git a/changelog.d/fixed-merge-gate-pill-glyph.md b/changelog.d/fixed-merge-gate-pill-glyph.md new file mode 100644 index 0000000000..9f1b6d7054 --- /dev/null +++ b/changelog.d/fixed-merge-gate-pill-glyph.md @@ -0,0 +1 @@ +- Activity monitor: the Merge gate column now reads one word per state in pipeline order — Awaiting merge gate (what holds it) → Ready for auto merge (next sweep in Ns) → Soaking (time left) → Merging → Merged — instead of "Ready for auto merge" for 060/080/100 alike; every row at the gate carries a leading glyph (spinning while hive's sweep is on the PR, a clock while it waits) whose tooltip and aria-label say in plain words what is happening and when the next sweep is, and the agent-working spinner names the agent. New `merge_gate` field on `/api/stage-tracker` PR items and nested linked PRs. Legend in docs/dashboard-sections.md ([#15073](https://github.com/hivecommons/hive/issues/15073)). diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 97d5d7a6f7..214f897a7f 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -646,7 +646,7 @@ More about the line: A progress strip per open issue and pull request showing which step of the pipeline it is on and who must act next. -Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same pipeline, named once in the column header above the list: `Open → Actionable (010) → Claimed (020) → PR in progress (030/040) → CI / Review (050/060) → Merge gate (080/100) → ✓ merged`. Each entry is a title line over a thin chevron strip. Only the current step is coloured: it is filled amber and carries the step name in words; once the PR is merged the final ✓ chevron is the lit one, in green. Motion is reserved for what is running or needs a hand — the lit chevron falls into one of three buckets (`stageTrackerMotion()` in `index.html`): **static** (steady): Open, Open · on hold (any hold label wins over every other signal), Actionable (010), Claimed (020), PR in progress / Covered by PR (030/040) by a human author, Merged, and any unrecognised stage; **active** (gentle pulse): the hive is acting — 030/040 by a hive or clanker author, 050 review pending, 060 reviewed, 070 fixing, 074 adopted by hive, 080 merge gate, 095 pre-merge soak, 100 merge queue; **needs-human** (slower amber→red breathe): a person must move — 015 triage needed, 045/085 needs decision, 071 needs author, 072 returned to contributor, 090 ready for a human merge, or a `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier on any stage. Under `prefers-reduced-motion` nothing animates; a needs-human step keeps a steady red tint so it still stands out. Every other step is a low-contrast shape with a small grey glyph (circle, bolt, lock, branch, eye, shield, check) — passed steps a subtle neutral fill, steps ahead a faint outline. Side stages are not extra steps: `070 Fixing` (the author's move; the `needs-rebase` chip next to it says what is being fixed — the stage labeller always parks a needs-rebase PR at 070/071/072, never at CI / Review), `071 Needs author` (human-authored), `072 Returned to contributor` (clanker-authored) and `074 Adopted by hive` light *CI / Review* with their own name (an adopted PR stays on 074 through the hive's pushes going pending, green or red again, and moves on only when *Merge gate* takes it); `085 Needs human decision` (PR-only) and `090 Ready for human merge` light *Merge gate* with their own name (the 085 tooltip says what must be decided); an issue parked on a person wears `045 Needs human decision` and lights *Actionable* (the issue side) with that name — a pre-045 issue still wearing 085 is drawn the same way until the reconciler re-stages it; an actionable issue no maintainer has looked at yet wears `015 Triage needed` (carrying `needs-triage`, or held in the reporter-trust gate's `reporter_triage` bucket — never derived from who filed it) and lights *Actionable* as "Triage needed" (a human's move) — so the Actionable column reads "Actionable", "Triage needed" or "Needs human decision", and the Open column is untouched. An issue carrying a hold-class label (`hold`, `do-not-merge*`, `hive-pause/`) is never parked: it sits at *Open* as "Open · on hold" even beside `needs-human`, and the reconciler removes any 045 the hold caught it with ([#13012](https://github.com/hivecommons/hive/issues/13012)). The lit chevron ends with an ink-coloured icon of whose move it is — person (human), robot (clanker) or hexagon (hive): the claim holder on Claimed, the PR author on PR in progress and Returned to contributor, hive on CI / Review, Adopted by hive and Ready for auto merge, a human on Needs human decision and Ready for human merge. A row at `090 Ready for human merge` always says *why* a person and not the hive merges it (#14658): the lit word ends `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred` or `· policy` (payload `human_merge_reason`, a `prstage.HumanMergeReason*` code derived from the stage record's lane reason — no second store), the chevron tooltip leads with the one-sentence `human_merge_reason_text` ("Changes .github/workflows/** — the hive never merges workflow changes …; click Merge on GitHub"), the manual-merge word reads `Awaiting human merge · workflow files · approved by @login`, the search / needs-attention headline carries the same tail, and a PR nested under its issue mirrors `human_approver`, `manual_merge`, `human_merge_reason` and `human_merge_reason_text` onto its `linked_prs` entry so the sub-row says the same. `040 Covered by PR` shares the *PR in progress* column with 030; `060 Reviewed`, `080 Awaiting merge admission` and `100 Merge queue` all light *Merge gate* as "Ready for auto merge" (the chevron tooltip says "not yet admitted — " for 060/080 and "admitted, merging" for 100); `095 Pre-merge soak` lights the same column as "Soaking" (hive's move; tooltip "admitted, soaking — Xm left", headline "Pre-merge soak — Xm left" from the payload's `soak_remaining_seconds`, aged from the lane's last sweep), so an admitted PR inside its soak window is no longer drawn as merging; the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `↳ [author icon] #PR title` under the *PR in progress* header on the same title line (the ↳ marks a PR drawn on its issue's row; the PR link's tooltip says so — "linked PR, shown on its issue's row" — and, when two open issues list the same PR, every row but the lowest-numbered issue adds "also under #N"), and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. A PR whose only linked issue is already closed — a superseded PR whose body still says `Fixes #N` after an earlier PR fixed it — keeps its own row with the closed issue in the issue slot: `#N title` as a link, muted and struck through, followed by a small `closed` chip, so the pairing reads at a glance; when the title cannot be resolved the slot says `#N (closed issue)` rather than a bare number (the title comes from the snapshot, or from one cached issue read the cycle makes once per issue — see [Linked issues](dashboard.md#pr-review-and-link-signals)). The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). A plain *Open* step — no stage label yet and not on hold — also carries that age in its own words, "Open · since 3d" ("since 14h" under two days), taken from the same `stage_since` instant the column draws (falling back to the time the item was opened, which the chevron tooltip then marks "(opened)"); past `STAGE_TRACKER_OPEN_STALE_DAYS` (2) the chevron takes a subtle red tint. *Open · hold* never shows the age. An Open item carrying the `blocked` label is drawn the same way as a hold — "Open · blocked" with a ⛔ glyph in the hold's yellow — but keeps the age ("Open · blocked · since 7h"; a stale blocked item is exactly what should stand out, [#14194](https://github.com/hivecommons/hive/issues/14194)) and its chevron tooltip says why: "blocked on owner/repo#N" when the payload names the blocker (`blocked_on`), else "carries the blocked label"; when an item is both held and blocked, hold wins — it is a human instruction. A draft PR — the forge's draft bit, or prow's `do-not-merge/work-in-progress` label — reads "Draft · since 18h" in the Open cell with a ✎ glyph in the muted draft tint, never turns stale (the hive's review and merge lanes skip drafts, so the wait is the author's, not a stuck pipeline), and wears a muted `draft` chip whose tooltip says the lanes skip it until the author marks it ready; a hold or blocked label still wins the cell, with `draft` folded into the chip's `+N` ([#14572](https://github.com/hivecommons/hive/issues/14572)). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-triage` — shown as "triage needed" (amber) on an issue still carrying the `needs-triage` label before the claim (010, 017, 045; at 015 the lit chevron already says so); a `needs-triage` left on a claimed or later issue (020+) is stale, never shown as a chip or stage text, and reported instead as `stale_labels` in the payload with a muted *Stale label* line in the hover tooltip until the stage sweep removes it (hivecommons/hive#14586) —, `needs-rebase`, `blocked`, `draft` — set by the PR's draft bit or prow's `do-not-merge/work-in-progress` label, which the tracker reads as a draft rather than a hold) with a `+N` for the rest. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines wrap rather than push the strip out of alignment: the issue title stays before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chip; hovering a title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then, within a column, attention-first: rows a person must act on now (any shown pill — `stalled`, `unauthorized`, `needs rebase`, `needs human`, … — or a human-gated stage: 045, 071, 072, 085, 090) come first, plain rows next, and rows nobody should act on — `hold` (incl. `do-not-merge/*`), `draft`, and a PR standing in for a closed issue — sink to the bottom of the column; within a tier the longest on the step comes first, then repo and number. Pills the server holds back until the merge gate (`deferred_modifiers`) never promote a row. The same tiering orders the PR sub-rows under an issue, and the server pre-sorts `GET /api/stage-tracker` the same way (stage, tier, wait, repo, number) so chat `/prs` and the hub read the same order. *Sort* also offers longest waiting (tier first, then wait), newest and number (no tiering); the arrow beside it flips the column / age / repo / number keys but never the tier — attention stays on top in both directions, as its tooltip says ("Attention-first within each column; arrow flips age order"). Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a drawn health modifier or on 071 / 072 / 085 / 090 — merge-gate pills held back before the gate do not count), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header count "N rows · M need attention" is for the filtered set, the **sidebar badge is the row count of the default view** (owner: the tracker counts rows, not items — a covering PR drawn on its issue's row is not a row of its own, and an issue with several PRs already has several), and both come from the same `stageTrackerCountsText()` call so they cannot disagree. When rows sit below the payload's open issues + PRs, the "showing" line's tooltip and the badge's footnote say why — "2 PRs shown on their issue's row" — rather than printing a second total.the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `[author icon] #PR title` under the *PR in progress* header on the same title line, and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-rebase`, `blocked`, `draft` — the PR's draft bit or prow's `do-not-merge/work-in-progress` label) with a `+N` for the rest. A `regressed` chip is red only when the row is parked on a person (a human-gate modifier or stage 045 / 071 / 072 / 085 / 090); on a hive-driven stage with nothing waiting on a human it draws as a muted dashed `stage ↓` pill, yields the lead slot to any other modifier, keeps the row out of **Needs attention**, and its tooltip ends "the hive is handling it — no action needed; clears on the next forward step". The marker is set by a genuine backward hop (a lapsed claim 020 → 010, a 030 ↔ 020 flicker and a 040 → 010 after a partially-addressing merge are not regressions) and clears on the first forward hop; see "The regressed marker" in `labels-and-control-signals.md`. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines wrap rather than push the strip out of alignment: the issue title stays before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chip; hovering a title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then, within a column, attention-first: rows a person must act on now (any shown pill — `stalled`, `unauthorized`, `needs rebase`, `needs human`, … — or a human-gated stage: 045, 071, 072, 085, 090) come first, plain rows next, and rows nobody should act on — `hold` (incl. `do-not-merge/*`), `draft`, and a PR standing in for a closed issue — sink to the bottom of the column; within a tier the longest on the step comes first, then repo and number. Pills the server holds back until the merge gate (`deferred_modifiers`) never promote a row. The same tiering orders the PR sub-rows under an issue, and the server pre-sorts `GET /api/stage-tracker` the same way (stage, tier, wait, repo, number) so chat `/prs` and the hub read the same order. *Sort* also offers longest waiting (tier first, then wait), newest and number (no tiering); the arrow beside it flips the column / age / repo / number keys but never the tier — attention stays on top in both directions, as its tooltip says ("Attention-first within each column; arrow flips age order"). Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a drawn health modifier or on 071 / 072 / 085 / 090 — merge-gate pills held back before the gate do not count), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header reads "N items (I issues / P PRs) · M need attention" — N, I and P are the whole list, the same `openItems` set the Overview tile and its left-menu counter print, so N always equals the tile's **Total open issues + Total open PRs**; a "· X match filters" note follows while a filter is on. The sidebar counter beside **Hive activity monitor** is that same N — total open items, written in the same render pass as the header, so the two cannot drift apart; how many need attention is the warn-coloured header suffix and the counter's hover tooltip (counted over every item, filters or not). When covering pull requests are nested under their issue the "showing X–Y of R" line counts rows and adds "(P nested under their issues)" so R never reads as a different total. The small monospace strip beside the count — `engine enforce · N anomalies` — is the central stage engine ([ADR-0025](adr/0025-central-stage-engine.md)): `engine` names the current `governor.labels.stage.engine.mode` (green `enforce`, neutral `shadow` = paused, nothing written; hover for what the mode does and the derivation count), `anomalies` counts stage moves the engine's admission table did not expect (red when non-zero). The same numbers are `/api/status.stageEngine`; the mode is changed under **Settings → Labels → Central stage engine mode** and the operator notes are in [operator-reference.md](operator-reference.md#central-stage-engine-rollout). "updated Ns ago · cache" says how old the server-built payload is: the spoke rebuilds it at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from its existing snapshot and serves it with an `ETag`, so the browser's 30-second poll is a 304 and no request ever reaches GitHub (`/api/gh-rate-limits` lists the caller `dashboard:stage-tracker` with nothing charged). See [Stage labels](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine). +Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same pipeline, named once in the column header above the list: `Open → Actionable (010) → Claimed (020) → PR in progress (030/040) → CI / Review (050) → Merge gate (060/080/095/100) → ✓ merged`. Each entry is a title line over a thin chevron strip. Only the current step is coloured: it is filled amber and carries the step name in words; once the PR is merged the final ✓ chevron is the lit one, in green. Motion is reserved for what is running or needs a hand — the lit chevron falls into one of three buckets (`stageTrackerMotion()` in `index.html`): **static** (steady): Open, Open · on hold (any hold label wins over every other signal), Actionable (010), Claimed (020), PR in progress / Covered by PR (030/040) by a human author, Merged, and any unrecognised stage; **active** (gentle pulse): the hive is acting — 030/040 by a hive or clanker author, 050 review pending, 060 reviewed, 070 fixing, 074 adopted by hive, 080 merge gate, 095 pre-merge soak, 100 merge queue; **needs-human** (slower amber→red breathe): a person must move — 015 triage needed, 045/085 needs decision, 071 needs author, 072 returned to contributor, 090 ready for a human merge, or a `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier on any stage. Under `prefers-reduced-motion` nothing animates; a needs-human step keeps a steady red tint so it still stands out. Every other step is a low-contrast shape with a small grey glyph (circle, bolt, lock, branch, eye, shield, check) — passed steps a subtle neutral fill, steps ahead a faint outline. Side stages are not extra steps: `070 Fixing` (the author's move; the `needs-rebase` chip next to it says what is being fixed — the stage labeller always parks a needs-rebase PR at 070/071/072, never at CI / Review), `071 Needs author` (human-authored), `072 Returned to contributor` (clanker-authored) and `074 Adopted by hive` light *CI / Review* with their own name (an adopted PR stays on 074 through the hive's pushes going pending, green or red again, and moves on only when *Merge gate* takes it); `085 Needs human decision` (PR-only) and `090 Ready for human merge` light *Merge gate* with their own name (the 085 tooltip says what must be decided); an issue parked on a person wears `045 Needs human decision` and lights *Actionable* (the issue side) with that name — a pre-045 issue still wearing 085 is drawn the same way until the reconciler re-stages it; an actionable issue no maintainer has looked at yet wears `015 Triage needed` (carrying `needs-triage`, or held in the reporter-trust gate's `reporter_triage` bucket — never derived from who filed it) and lights *Actionable* as "Triage needed" (a human's move) — so the Actionable column reads "Actionable", "Triage needed" or "Needs human decision", and the Open column is untouched. An issue carrying a hold-class label (`hold`, `do-not-merge*`, `hive-pause/`) is never parked: it sits at *Open* as "Open · on hold" even beside `needs-human`, and the reconciler removes any 045 the hold caught it with ([#13012](https://github.com/hivecommons/hive/issues/13012)). The lit chevron ends with an ink-coloured icon of whose move it is — person (human), robot (clanker) or hexagon (hive): the claim holder on Claimed, the PR author on PR in progress and Returned to contributor, hive on CI / Review, Adopted by hive and Ready for auto merge, a human on Needs human decision and Ready for human merge. A row at `090 Ready for human merge` always says *why* a person and not the hive merges it (#14658): the lit word ends `· workflow files`, `· tests removed`, `· manual-merge policy`, `· branch protection`, `· merge method`, `· auto-merge off`, `· untrusted author`, `· unauthorized`, `· reviewer deferred` or `· policy` (payload `human_merge_reason`, a `prstage.HumanMergeReason*` code derived from the stage record's lane reason — no second store), the chevron tooltip leads with the one-sentence `human_merge_reason_text` ("Changes .github/workflows/** — the hive never merges workflow changes …; click Merge on GitHub"), the manual-merge word reads `Awaiting human merge · workflow files · approved by @login`, the search / needs-attention headline carries the same tail, and a PR nested under its issue mirrors `human_approver`, `manual_merge`, `human_merge_reason` and `human_merge_reason_text` onto its `linked_prs` entry so the sub-row says the same. `040 Covered by PR` shares the *PR in progress* column with 030; `060 Reviewed`, `080 Awaiting merge admission` and `100 Merge queue` all light *Merge gate* as "Ready for auto merge" (the chevron tooltip says "not yet admitted — " for 060/080 and "admitted, merging" for 100); `095 Pre-merge soak` lights the same column as "Soaking" (hive's move; tooltip "admitted, soaking — Xm left", headline "Pre-merge soak — Xm left" from the payload's `soak_remaining_seconds`, aged from the lane's last sweep), so an admitted PR inside its soak window is no longer drawn as merging; the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `↳ [author icon] #PR title` under the *PR in progress* header on the same title line (the ↳ marks a PR drawn on its issue's row; the PR link's tooltip says so — "linked PR, shown on its issue's row" — and, when two open issues list the same PR, every row but the lowest-numbered issue adds "also under #N"), and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. A PR whose only linked issue is already closed — a superseded PR whose body still says `Fixes #N` after an earlier PR fixed it — keeps its own row with the closed issue in the issue slot: `#N title` as a link, muted and struck through, followed by a small `closed` chip, so the pairing reads at a glance; when the title cannot be resolved the slot says `#N (closed issue)` rather than a bare number (the title comes from the snapshot, or from one cached issue read the cycle makes once per issue — see [Linked issues](dashboard.md#pr-review-and-link-signals)). The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). A plain *Open* step — no stage label yet and not on hold — also carries that age in its own words, "Open · since 3d" ("since 14h" under two days), taken from the same `stage_since` instant the column draws (falling back to the time the item was opened, which the chevron tooltip then marks "(opened)"); past `STAGE_TRACKER_OPEN_STALE_DAYS` (2) the chevron takes a subtle red tint. *Open · hold* never shows the age. An Open item carrying the `blocked` label is drawn the same way as a hold — "Open · blocked" with a ⛔ glyph in the hold's yellow — but keeps the age ("Open · blocked · since 7h"; a stale blocked item is exactly what should stand out, [#14194](https://github.com/hivecommons/hive/issues/14194)) and its chevron tooltip says why: "blocked on owner/repo#N" when the payload names the blocker (`blocked_on`), else "carries the blocked label"; when an item is both held and blocked, hold wins — it is a human instruction. A draft PR — the forge's draft bit, or prow's `do-not-merge/work-in-progress` label — reads "Draft · since 18h" in the Open cell with a ✎ glyph in the muted draft tint, never turns stale (the hive's review and merge lanes skip drafts, so the wait is the author's, not a stuck pipeline), and wears a muted `draft` chip whose tooltip says the lanes skip it until the author marks it ready; a hold or blocked label still wins the cell, with `draft` folded into the chip's `+N` ([#14572](https://github.com/hivecommons/hive/issues/14572)). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-triage` — shown as "triage needed" (amber) on an issue still carrying the `needs-triage` label before the claim (010, 017, 045; at 015 the lit chevron already says so); a `needs-triage` left on a claimed or later issue (020+) is stale, never shown as a chip or stage text, and reported instead as `stale_labels` in the payload with a muted *Stale label* line in the hover tooltip until the stage sweep removes it (hivecommons/hive#14586) —, `needs-rebase`, `blocked`, `draft` — set by the PR's draft bit or prow's `do-not-merge/work-in-progress` label, which the tracker reads as a draft rather than a hold) with a `+N` for the rest. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines wrap rather than push the strip out of alignment: the issue title stays before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chip; hovering a title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then, within a column, attention-first: rows a person must act on now (any shown pill — `stalled`, `unauthorized`, `needs rebase`, `needs human`, … — or a human-gated stage: 045, 071, 072, 085, 090) come first, plain rows next, and rows nobody should act on — `hold` (incl. `do-not-merge/*`), `draft`, and a PR standing in for a closed issue — sink to the bottom of the column; within a tier the longest on the step comes first, then repo and number. Pills the server holds back until the merge gate (`deferred_modifiers`) never promote a row. The same tiering orders the PR sub-rows under an issue, and the server pre-sorts `GET /api/stage-tracker` the same way (stage, tier, wait, repo, number) so chat `/prs` and the hub read the same order. *Sort* also offers longest waiting (tier first, then wait), newest and number (no tiering); the arrow beside it flips the column / age / repo / number keys but never the tier — attention stays on top in both directions, as its tooltip says ("Attention-first within each column; arrow flips age order"). Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a drawn health modifier or on 071 / 072 / 085 / 090 — merge-gate pills held back before the gate do not count), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header count "N rows · M need attention" is for the filtered set, the **sidebar badge is the row count of the default view** (owner: the tracker counts rows, not items — a covering PR drawn on its issue's row is not a row of its own, and an issue with several PRs already has several), and both come from the same `stageTrackerCountsText()` call so they cannot disagree. When rows sit below the payload's open issues + PRs, the "showing" line's tooltip and the badge's footnote say why — "2 PRs shown on their issue's row" — rather than printing a second total.the chevron's own tooltip names the exact stage. Covering pull requests nest under their issue. An issue with no PR yet draws the whole strip like any other row, lit at Open, Actionable or Claimed with the steps ahead faint. Once exactly one PR covers it, issue and PR are a single entry: the issue's `#N title` on the left, `[author icon] #PR title` under the *PR in progress* header on the same title line, and one continuous strip — Open, Actionable and Claimed passed, the PR's stage lighting the chevron from PR in progress through CI / Review, Merge gate and ✓; the chip, tooltip and `since` are the PR's. With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing on the issue line lit. Directly beneath, tighter than the gap between entries, sits one indented sub-row per open covering PR, furthest along first: `[author icon] #N title` at the *PR in progress* column, then that PR's own strip from there on — `PR in progress → CI / Review → Merge gate → ✓` — with its own lit chevron, chip, tooltip and `since`. So an issue with two PRs, one at 030, shows "PR in progress" lit on that sub-row, not on the issue. A PR linked to an open issue in the list has no top-level row of its own; a PR with no linked issue keeps a full-width row and shows the first steps as passed. The *Pull requests* filter flattens the list — every PR as a top-level row; *Issues* and *All* show the nested view. Each row is named once on the left; a covering PR appears under the *PR in progress* header as `[author icon] #N title`. A pull request with no linked issue is named once: `[PR icon] [author icon] #N title` on the left over one continuous strip (first steps passed, its own step lit) and nothing in the *PR in progress* column, which is reserved for covering PRs — so a title never appears twice in a row. Pull requests are never issues here: when a number arrives through both the issues feed and the pulls feed the PR record wins and the issue copy is dropped on the server (pairing is keyed by repository, kind and number), and the *Issues* filter never lists a PR. The author icon is the one coloured legend: hive hexagon in blue, clanker robot in purple, human silhouette in teal (the `author/*` kind, inferred from the snapshot when the label is absent; the login is in the `#N` link's tooltip). The right-hand `since` column, in line with the chevron strip, is how long the item has been on its step (red when `stalled`). At most one muted chip sits at the right end of the title line, directly over the strip's ✓ cap (on the last line when the title wraps; a hairline above each entry and a hover tint over the whole entry keep chip and `since` unambiguously with their own row — [#14640](https://github.com/hivecommons/hive/issues/14640)): the most important health modifier (`stalled`, `regressed`, `hold`, `needs-human`, `needs-decision` — shown as "needs human decision" —, `needs-rebase`, `blocked`, `draft` — the PR's draft bit or prow's `do-not-merge/work-in-progress` label) with a `+N` for the rest. A `regressed` chip is red only when the row is parked on a person (a human-gate modifier or stage 045 / 071 / 072 / 085 / 090); on a hive-driven stage with nothing waiting on a human it draws as a muted dashed `stage ↓` pill, yields the lead slot to any other modifier, keeps the row out of **Needs attention**, and its tooltip ends "the hive is handling it — no action needed; clears on the next forward step". The marker is set by a genuine backward hop (a lapsed claim 020 → 010, a 030 ↔ 020 flicker and a 040 → 010 after a partially-addressing merge are not regressions) and clears on the first forward hop; see "The regressed marker" in `labels-and-control-signals.md`. Everything else — the reason sentence, who must act, nudges sent, the repository, all flags and the last stage hops — is in the hover tooltip on the item's `#N` link (on a nested sub-row, on its `#N` PR link). Hover text in a row lives only on the `#N` link, the covering-PR link, the title and the lit chevron (its stage, and whose move it is); passed and upcoming chevrons, the kind and author icons, chips and the `since` column have none. Title lines wrap rather than push the strip out of alignment: the issue title stays before the *PR in progress* column (a clear gap always separates it from the PR entry, which starts at the column edge) and the PR title before the chip; hovering a title shows the full text. Rows are sorted furthest-along first by default — a covered issue ranks by its furthest-along PR — then, within a column, attention-first: rows a person must act on now (any shown pill — `stalled`, `unauthorized`, `needs rebase`, `needs human`, … — or a human-gated stage: 045, 071, 072, 085, 090) come first, plain rows next, and rows nobody should act on — `hold` (incl. `do-not-merge/*`), `draft`, and a PR standing in for a closed issue — sink to the bottom of the column; within a tier the longest on the step comes first, then repo and number. Pills the server holds back until the merge gate (`deferred_modifiers`) never promote a row. The same tiering orders the PR sub-rows under an issue, and the server pre-sorts `GET /api/stage-tracker` the same way (stage, tier, wait, repo, number) so chat `/prs` and the hub read the same order. *Sort* also offers longest waiting (tier first, then wait), newest and number (no tiering); the arrow beside it flips the column / age / repo / number keys but never the tier — attention stays on top in both directions, as its tooltip says ("Attention-first within each column; arrow flips age order"). Every open issue and pull request of the watched repositories is listed — actionable, held, claimed, in progress, covered by a PR, filtered by a `needs-*` label, reporter-triage, draft and exempt-labelled alike; an item without a stage label or journal entry sits at *Open*, and one in a scanner bucket with no label yet is placed from the bucket (claimed → 020, in progress → 030, covered → 040). Filters work on the cached payload in the browser and persist across reloads (the page number does not): kind chips, *Repo*, a search box (`#number` / number / title substring, also matching a covering PR), *Since* (any, over 1 hour / 1 day / 1 week on the current step, or past the stage's configured dwell — stalled items always qualify), *Author* kind, *Needs attention* (anything with a drawn health modifier or on 071 / 072 / 085 / 090 — merge-gate pills held back before the gate do not count), and label chips built from every label present, each with its count: a **🙋 Needs human** facet first (attention-coloured; it matches any item carrying a label of the needs-human set — the server's `needs_human_labels`, the same list as the Projects *Needs human* preset: `stage/045-needs-decision`, `stage/085-needs-decision`, `needs-decision`, `needs-direction`, `needs-spec`, `needs-signal`, `needs-human` and `needs-human/*`, the hold labels, `stage/071-needs-author`, `sentinel-alert`, `needs-triage`; its count is the number of distinct items, not the sum of label counts), then every `stage/NNN-*` label in numerical order, then all other labels alphabetically (case-insensitive). When the row would overflow, the **+N more** button opens an in-app *All labels* dialog listing every label in the same order with counts, a type-to-filter box, the same toggles the chips use and a *Clear* button; a label selected there is promoted into the visible row. Chips of one family OR, families AND; *Needs human* ANDs with the label chips. *Clear filters* shows while anything is narrowed. The list is paged — 25 / 50 / 100 rows, default 50 — with Prev / Next and "showing X–Y of N (M filtered out)" above and below; the header reads "N items (I issues / P PRs) · M need attention" — N, I and P are the whole list, the same `openItems` set the Overview tile and its left-menu counter print, so N always equals the tile's **Total open issues + Total open PRs**; a "· X match filters" note follows while a filter is on. The sidebar counter beside **Hive activity monitor** is that same N — total open items, written in the same render pass as the header, so the two cannot drift apart; how many need attention is the warn-coloured header suffix and the counter's hover tooltip (counted over every item, filters or not). When covering pull requests are nested under their issue the "showing X–Y of R" line counts rows and adds "(P nested under their issues)" so R never reads as a different total. The small monospace strip beside the count — `engine enforce · N anomalies` — is the central stage engine ([ADR-0025](adr/0025-central-stage-engine.md)): `engine` names the current `governor.labels.stage.engine.mode` (green `enforce`, neutral `shadow` = paused, nothing written; hover for what the mode does and the derivation count), `anomalies` counts stage moves the engine's admission table did not expect (red when non-zero). The same numbers are `/api/status.stageEngine`; the mode is changed under **Settings → Labels → Central stage engine mode** and the operator notes are in [operator-reference.md](operator-reference.md#central-stage-engine-rollout). "updated Ns ago · cache" says how old the server-built payload is: the spoke rebuilds it at most every `dashboard.stage_tracker.cache_ttl_s` (default `governor.eval_interval_s`) from its existing snapshot and serves it with an `ETag`, so the browser's 30-second poll is a 304 and no request ever reaches GitHub (`/api/gh-rate-limits` lists the caller `dashboard:stage-tracker` with nothing charged). See [Stage labels](labels-and-control-signals.md#stage-labels-stagennn--the-pipeline-state-machine). **Filter chips (Needs human / On hold / labels).** The label row under the toolbar starts with two synthetic chips, then one chip per label the listed items carry. **🙋 Needs human** means a person's decision or action is the *only* thing that advances the row: an issue at `015` triage-needed, `045` or `085` needs-decision, a PR at `090` ready-for-human-merge, a PR at `071`/`072` whose author is a human, or any row wearing a `needs human` / `needs human decision` / `unauthorized` pill. It is **not** `hold`, `stalled`, `blocked`, a handled regression, a `040` issue an open PR covers, or a PR the hive will merge itself — those are the hive's (or nobody's) to move. **⏸ On hold** is the separate chip for rows a maintainer paused on purpose with a hold label; a held row never counts as Needs human. The chip label, its count, the filter it toggles and the payload's `needs_human` / `on_hold` totals (and per-item flags) all come from one predicate (`stageTrackerNeedsHuman` in Go, `stageTrackerItemNeedsHuman` in the page), so what the chip counts is exactly what the filter shows ([#15008](https://github.com/hivecommons/hive/issues/15008)). Hover a chip for a one-line explanation. Label chips AND with the synthetic chips. @@ -710,6 +710,19 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p **Hold pill with provenance.** When the hive can say who set a row's `hold` label and why, the pill does not read a bare *hold*: it reads **Held by hive · reporter trust (issue #15017 by @Karibhou, contributor)** when the hive's own reporter-trust gate ([#9665](https://github.com/hivecommons/hive/issues/9665)) set it, **Held by hive** when the hive set it for another reason, or **Held by @login** when a person added the label; a hold the hive cannot attribute keeps the plain *hold* word. The hover text repeats the pill, says since when, and for a hive-set reporter-trust hold explains that the hive set it itself and that *Release hold* lifts it. That same pill opens the needs-human decision popover: its question reads *The hive held this PR itself for reporter trust (issue #N by @X, contributor). Release the hold, or keep it?*, **Release hold** leads the buttons (enabled), *Let hive decide* waits until the hold is released, and `blocker_reason` is `hold:hive`. A person's hold names them in the blocker instead (*On hold (set by @login) — the hive does nothing until the hold is released.*). The data rides the tracker payload as `hold {by, source, reason, since, issue, reporter, association, pill}` on the item and on each nested `linked_pr`; `by` is `hive` or the login of the person whose label event set it, `source` is `reporter-trust` or `label`. It comes from the stage-label pass, which reads the hive's `` notice and the newest `hold` label event ([#15020](https://github.com/hivecommons/hive/pull/15020): a hive-authored PR sat 49 minutes as *hold +1 · Needs human decision* with no way to tell that the hive had held it two seconds after opening it). A hive-authored PR never keeps a hive-set reporter-trust hold: the same pass releases it, so the pill is normally seen only on contributor PRs. +**Merge gate pills — legend** ([#15073](https://github.com/hivecommons/hive/issues/15073)). Four stages share the **Merge gate** column, and until this fix three of them (060, 080, 100) all read *Ready for auto merge* — a 060 PR whose CI was still running read as ready, and a spinning glyph that appeared on one such row and not its neighbour was the *working* cue (an agent's `lastAction` on that PR this round), unlabelled, so the operator read it as merge progress. Every PR at the gate now carries `merge_gate: {state, reason, sweep_running, last_sweep_at, next_sweep_at, soak_until, soak_remaining_seconds}` in the payload (mirrored on the issue's nested `linked_prs`), and the lit chevron reads one word per state, in pipeline order, with the live detail after a `·`: + +| stage | pill word | detail after `·` | glyph before the word (tooltip + `aria-label`) | +| --- | --- | --- | --- | +| 060 reviewed | **Awaiting merge gate** | what holds it, from the lane's reason — *CI still running (build-and-test)*, *CI is red (lint)*, *branch has conflicts*, … | 🕓 clock — *Review approved, not yet admitted to auto merge — CI still running (build-and-test). hive re-checks the gate on its next sweep in 3m. A GitHub event on the PR (check run, review, push) triggers a pass sooner. Last checked 2m ago.* | +| 080 awaiting merge admission | **Ready for auto merge** | *next sweep in 42s* (counts down in place; *sweep due now* once past) | 🕓 clock — *Approved and green; waiting for hive's merge sweep — next sweep in 42s. …* | +| 095 pre-merge soak | **Soaking** | *7m left* (counts down; *soak window complete* once past) | 🕓 clock — *Admitted by the automerge lane; waiting for the soak window: 7m left. hive merges on its first sweep after that.* | +| any of the above while a pass is evaluating this PR | the stage's word | *merge sweep running* | ⟳ spinning — *hive's merge sweep is running on this PR now.* | +| 100 merge queue | **Merging** | — | ⟳ spinning — *Admitted and soaked; hive is merging it now (GitHub merge queue / merge window).* | +| 110 | **Merged** (the ✓ cap) | — | — | + +The glyph is drawn for **every** row on the gate, so two rows in the same state always look the same; the ⬡ / 🤖 / 👤 icon *after* the word is whose move it is (`STAGE_TRACKER_ACTOR`), unchanged. The *working* spin (an agent on the item right now) stays a separate cue and now also carries its sentence as tooltip and `aria-label` (*Working now: reviewer reviewed it · 2m ago*). `next_sweep_at` comes from the automerge lanes' sweep clock (`automerge.SweepSnapshot()` — the next periodic floor pass, 5 min event-driven or the legacy 10 s tick); webhook-named passes run sooner, which the tooltip says. `last_sweep_at` is the stage record's `last_seen` (when a lane last evaluated the PR). + **Cue tokens.** The three cues of the legend above (state pill, working spin, decision badge) share one `tracker-cues` CSS block on `.ham-row`: `--cue-state` (what the row waits on — the pill and this popover), `--cue-work` (the hive is working right now — the chevron spin), `--cue-decision` (what people and the hive decided — the ✓ badge). Nothing else blinks; motion stays in the 150–300 ms range. ### Let hive decide diff --git a/src/docs/labels-and-control-signals.md b/src/docs/labels-and-control-signals.md index 1b5d01cff5..a5a026b669 100644 --- a/src/docs/labels-and-control-signals.md +++ b/src/docs/labels-and-control-signals.md @@ -1376,7 +1376,7 @@ The Governor dialog's Features tab has a "Question Auto-Close" section: a switch ### Hive activity monitor -The dashboard renders every open issue and PR's stage as one unified tracker strip in the **Hive activity monitor** section (`GET /api/stage-tracker`): `Open → 010 → 020 → 030/040 (PR in progress) → 050/060 (CI / Review) → 080/100 (Merge gate) → merged`, with 060/080/100 lit as "Ready for auto merge" (tooltip: not yet admitted vs admitted, merging), 070/072/074 as the lit *CI / Review* step named after the side stage, 085/090 as *Merge gate* lit "Needs human decision" / "Ready for human merge", and an issue parked at 045 lit at *Actionable* (the issue side) as "Needs human decision"; an issue wearing a hold-class label is "Open · on hold" whatever else it carries, `needs-human` included ([#13012](https://github.com/hivecommons/hive/issues/13012)). 070 "Fixing" is the author's move (a `needs-rebase` chip says what is being fixed — needs-rebase always lands at 070/072, never at 050/060). An issue with exactly one covering PR is a single entry whose strip is driven by the PR's stage from 030 on; with two or more covering PRs the issue's own strip stops at 020 Claimed and each PR nests beneath as an indented sub-row (`[author/*-coloured icon] #N title` plus its own strip from *PR in progress* on), and PRs linked to a listed issue have no top-level row (`nested_under`); a PR with no linked issue is one row named once on the left, and a PR is never listed as an issue (the PR record wins over any issues-feed copy of the same number). `stage/stalled` and the store's regressed marker (the retired `stage/regressed` label's successor) appear as chips and colour the `since` value; the stage store's per-item transition history (last eight hops) is in the row tooltip. See [dashboard.md](dashboard.md#hive-activity-monitor). +The dashboard renders every open issue and PR's stage as one unified tracker strip in the **Hive activity monitor** section (`GET /api/stage-tracker`): `Open → 010 → 020 → 030/040 (PR in progress) → 050/060 (CI / Review) → 080/100 (Merge gate) → merged`, with 060 lit as "Awaiting merge gate" (what holds it), 080 as "Ready for auto merge" (next sweep countdown), 095 as "Soaking" (time left) and 100 as "Merging" ([dashboard-sections.md](dashboard-sections.md#hive-activity-monitor) has the legend), 070/072/074 as the lit *CI / Review* step named after the side stage, 085/090 as *Merge gate* lit "Needs human decision" / "Ready for human merge", and an issue parked at 045 lit at *Actionable* (the issue side) as "Needs human decision"; an issue wearing a hold-class label is "Open · on hold" whatever else it carries, `needs-human` included ([#13012](https://github.com/hivecommons/hive/issues/13012)). 070 "Fixing" is the author's move (a `needs-rebase` chip says what is being fixed — needs-rebase always lands at 070/072, never at 050/060). An issue with exactly one covering PR is a single entry whose strip is driven by the PR's stage from 030 on; with two or more covering PRs the issue's own strip stops at 020 Claimed and each PR nests beneath as an indented sub-row (`[author/*-coloured icon] #N title` plus its own strip from *PR in progress* on), and PRs linked to a listed issue have no top-level row (`nested_under`); a PR with no linked issue is one row named once on the left, and a PR is never listed as an issue (the PR record wins over any issues-feed copy of the same number). `stage/stalled` and the store's regressed marker (the retired `stage/regressed` label's successor) appear as chips and colour the `since` value; the stage store's per-item transition history (last eight hops) is in the row tooltip. See [dashboard.md](dashboard.md#hive-activity-monitor). ## Lifecycle examples diff --git a/src/pkg/dashboard/server.go b/src/pkg/dashboard/server.go index 4796a15b99..33b6b3aed3 100644 --- a/src/pkg/dashboard/server.go +++ b/src/pkg/dashboard/server.go @@ -123,6 +123,9 @@ type Server struct { // presenceLookup overrides the contribute hub as the tracker's author // presence source for 072 rows (stage_tracker_adoption.go); tests only. presenceLookup func(login string) (automerge.ContributorPresence, bool) + // sweepState overrides the automerge lanes' live sweep state for the + // tracker's merge-gate rows (stage_tracker_merge_gate.go); tests only. + sweepState func() automerge.SweepState // stageTrackerCache is the last /api/stage-tracker payload built from // the status snapshot, served until its TTL lapses (stage_tracker.go). stageTrackerCache stageTrackerCache diff --git a/src/pkg/dashboard/stage_tracker.go b/src/pkg/dashboard/stage_tracker.go index 1ad5465f91..c3d87fdd34 100644 --- a/src/pkg/dashboard/stage_tracker.go +++ b/src/pkg/dashboard/stage_tracker.go @@ -330,6 +330,10 @@ type StageTrackerItem struct { // `soaking(remaining=…)` reason aged by the time since it was recorded); // 0 when unknown or not soaking. SoakRemainingSeconds int64 `json:"soak_remaining_seconds,omitempty"` + // MergeGate narrates a PR's position at the merge gate (060 / 080 / + // 095 / 100): state, what holds it, whether hive's merge sweep is on + // it now, the next pass and the soak countdown (hivecommons/hive#15073). + MergeGate *StageTrackerMergeGate `json:"merge_gate,omitempty"` // SentinelAlert is true on a PR the suspicious-activity sentinel flagged: // it wears the configured alert label (sentinel.label, default // sentinel-alert) or the review evidence bundle for its current head @@ -491,6 +495,10 @@ type StageTrackerLinkedPR struct { // DecisionNeeded mirrors the nested PR's own row field so the issue's // sub-row can open the same "Needs human" popover. DecisionNeeded *StageTrackerDecision `json:"decision_needed,omitempty"` + // SoakRemainingSeconds / MergeGate mirror the PR item's (#15073): a + // nested Soaking sub-row shows its time left too. + SoakRemainingSeconds int64 `json:"soak_remaining_seconds,omitempty"` + MergeGate *StageTrackerMergeGate `json:"merge_gate,omitempty"` // Adoption mirrors the nested PR's own row field (hivecommons/hive#14524). Adoption *StageTrackerAdoption `json:"adoption,omitempty"` // LastOperatorAction / OperatorActionCount mirror the nested PR's own @@ -1580,6 +1588,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto return store.Get(stagelabels.Key(repo, number)) } presence, maintainerPolicy := s.stageTrackerPresence(), s.stageTrackerMaintainerPolicy() + sweep := s.stageTrackerSweepState() finish := func(it *StageTrackerItem, labels []string, stage stagelabels.Stage, rec stagelabels.Record, hasRec bool, draft bool) { // "Needs human decision" is read from the item's current labels, not // a store record that outlived them: once the park label is gone @@ -1615,6 +1624,9 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto it.Stage = stage.Number() it.StageSlug = stage.Slug() it.StageLabel = stage.Label() + if it.Kind == "pr" { + it.MergeGate = stageTrackerMergeGate(it.Repo, it.Number, stage, rec, hasRec, sweep, now) + } if m := trackerPRNumberRE.FindStringSubmatch(it.Reason); m != nil && it.Kind == "issue" { it.LinkedPR, _ = strconv.Atoi(m[1]) } @@ -2543,6 +2555,7 @@ func stageTrackerResolveLinkedPRs(items []StageTrackerItem) { lp.HumanMergeReason, lp.HumanMergeReasonText = pr.HumanMergeReason, pr.HumanMergeReasonText lp.BaseRef = pr.BaseRef lp.DecisionNeeded = pr.DecisionNeeded + lp.SoakRemainingSeconds, lp.MergeGate = pr.SoakRemainingSeconds, pr.MergeGate lp.LastOperatorAction, lp.OperatorActionCount = pr.LastOperatorAction, pr.OperatorActionCount lp.Hold = pr.Hold if len(pr.Modifiers) > 0 { diff --git a/src/pkg/dashboard/stage_tracker_merge_gate.go b/src/pkg/dashboard/stage_tracker_merge_gate.go new file mode 100644 index 0000000000..34ae6880ef --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_merge_gate.go @@ -0,0 +1,106 @@ +package dashboard + +import ( + "time" + + "github.com/hivecommons/hive/pkg/github/automerge" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// Merge-gate states (StageTrackerMergeGate.State), in pipeline order. The +// Activity Monitor's Merge gate column lights one chevron for 060, 080, +// 095 and 100; the state names which, in words a row can show without a +// hover (hivecommons/hive#15073). +const ( + // MergeGateStatePending: 060 reviewed — the review swarm approved but + // the admission gate still holds (CI pending or red, soak on an + // unadmitted head, …); Reason says which. + MergeGateStatePending = "gate-pending" + // MergeGateStateReady: 080 awaiting merge admission — green and + // approved, waiting for the automerge lane's next pass. + MergeGateStateReady = "ready" + // MergeGateStateSoaking: 095 pre-merge soak — admitted, the soak window + // is running; SoakRemainingSeconds counts down. + MergeGateStateSoaking = "soaking" + // MergeGateStateMerging: 100 merge queue — admitted and soaked, the + // merge is being attempted (GitHub merge queue / tide / merge window). + MergeGateStateMerging = "merging" + // MergeGateStateMerged: 110. + MergeGateStateMerged = "merged" +) + +// StageTrackerMergeGate narrates a PR's position at the merge gate: the +// state, what holds it (gate-pending), whether hive's merge sweep is on +// it right now, when the lane last evaluated it and when its next +// periodic pass is due, and the soak countdown. nil off the gate. +type StageTrackerMergeGate struct { + State string `json:"state"` + // Reason is the lane's reason token for the current stage (what the + // gate waits on at 060: check-pending, required-check-pending:). + Reason string `json:"reason,omitempty"` + // SweepRunning is true while an automerge pass that evaluates this PR + // is in flight. + SweepRunning bool `json:"sweep_running,omitempty"` + // LastSweepAt is when the lane last evaluated this PR (the stage + // record's LastSeen). + LastSweepAt *time.Time `json:"last_sweep_at,omitempty"` + // NextSweepAt is when the next full pass is due. A GitHub event on the + // PR (check run, review, push) triggers a targeted pass sooner. + NextSweepAt *time.Time `json:"next_sweep_at,omitempty"` + // SoakUntil / SoakRemainingSeconds: the soak window's end, at 095. + SoakUntil *time.Time `json:"soak_until,omitempty"` + SoakRemainingSeconds int64 `json:"soak_remaining_seconds,omitempty"` +} + +// stageTrackerMergeGateState maps a stage to its merge-gate state; "" off +// the gate. +func stageTrackerMergeGateState(stage stagelabels.Stage) string { + switch stage { + case stagelabels.Reviewed: + return MergeGateStatePending + case stagelabels.AwaitingMergeAdmission: + return MergeGateStateReady + case stagelabels.PreMergeSoak: + return MergeGateStateSoaking + case stagelabels.MergeQueue: + return MergeGateStateMerging + } + return "" +} + +// stageTrackerMergeGate builds the merge-gate narration for a PR at +// stage, or nil when the PR is not at the gate. +func stageTrackerMergeGate(repo string, number int, stage stagelabels.Stage, rec stagelabels.Record, hasRec bool, sweep automerge.SweepState, now time.Time) *StageTrackerMergeGate { + state := stageTrackerMergeGateState(stage) + if state == "" { + return nil + } + mg := &StageTrackerMergeGate{State: state} + if hasRec { + mg.Reason = rec.Reason + if !rec.LastSeen.IsZero() { + t := rec.LastSeen + mg.LastSweepAt = &t + } + if left := stageTrackerSoakRemaining(rec, now); left > 0 { + mg.SoakRemainingSeconds = int64(left / time.Second) + until := now.Add(left) + mg.SoakUntil = &until + } + } + if sweep.OnPR(repo, number) { + mg.SweepRunning = true + } else if !sweep.NextFloorAt.IsZero() && sweep.NextFloorAt.After(now) { + t := sweep.NextFloorAt + mg.NextSweepAt = &t + } + return mg +} + +// stageTrackerSweepState is the lanes' live state, or the test override. +func (s *Server) stageTrackerSweepState() automerge.SweepState { + if s != nil && s.sweepState != nil { + return s.sweepState() + } + return automerge.SweepSnapshot() +} diff --git a/src/pkg/dashboard/stage_tracker_merge_gate_test.go b/src/pkg/dashboard/stage_tracker_merge_gate_test.go new file mode 100644 index 0000000000..942a6158e6 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_merge_gate_test.go @@ -0,0 +1,261 @@ +package dashboard + +import ( + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/github/automerge" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// TestStageTrackerMergeGatePayload: the merge_gate narration a PR row +// carries at 060 / 080 / 095 / 100 (hivecommons/hive#15073) — state, the +// gate's reason, the lane's last look, the next floor pass, whether a +// sweep is on it now, and the soak countdown — and nothing off the gate. +func TestStageTrackerMergeGatePayload(t *testing.T) { + now := time.Date(2026, 10, 28, 19, 23, 0, 0, time.UTC) + seen := now.Add(-2 * time.Minute) + next := now.Add(3 * time.Minute) + idle := automerge.SweepState{NextFloorAt: next, FinishedAt: seen} + rec := func(stage stagelabels.Stage, reason string) stagelabels.Record { + return stagelabels.Record{Stage: stage, Reason: reason, LastSeen: seen, EnteredAt: seen} + } + + // 060 reviewed, CI pending (hivecommons/hive#15054 at 15:11 ET). + mg := stageTrackerMergeGate("hivecommons/hive", 15054, stagelabels.Reviewed, rec(stagelabels.Reviewed, "required-check-pending:build-and-test"), true, idle, now) + if mg == nil || mg.State != MergeGateStatePending || mg.Reason != "required-check-pending:build-and-test" { + t.Fatalf("060: %+v", mg) + } + if mg.SweepRunning || mg.LastSweepAt == nil || !mg.LastSweepAt.Equal(seen) || mg.NextSweepAt == nil || !mg.NextSweepAt.Equal(next) { + t.Errorf("060 timing: %+v", mg) + } + if mg.SoakUntil != nil || mg.SoakRemainingSeconds != 0 { + t.Errorf("060 carries no soak: %+v", mg) + } + + // The same PR while a pass that names it is in flight + // (hivecommons/hive#15042): sweep_running, no next pass. + running := automerge.SweepState{Running: true, Cause: "event", StartedAt: now, NextFloorAt: next, Targets: automerge.SweepTargets{"hivecommons/hive": {15042: true}}} + mg = stageTrackerMergeGate("hivecommons/hive", 15042, stagelabels.Reviewed, rec(stagelabels.Reviewed, "check-pending"), true, running, now) + if mg == nil || !mg.SweepRunning || mg.NextSweepAt != nil { + t.Errorf("060 mid-sweep: %+v", mg) + } + // A targeted pass on another PR is not on this one. + mg = stageTrackerMergeGate("hivecommons/hive", 15054, stagelabels.Reviewed, rec(stagelabels.Reviewed, "check-pending"), true, running, now) + if mg == nil || mg.SweepRunning || mg.NextSweepAt == nil { + t.Errorf("060 beside a targeted pass: %+v", mg) + } + // A full pass (nil targets) is on every PR. + full := automerge.SweepState{Running: true, Cause: "floor"} + if mg = stageTrackerMergeGate("hivecommons/hive", 15054, stagelabels.AwaitingMergeAdmission, rec(stagelabels.AwaitingMergeAdmission, ""), true, full, now); mg == nil || !mg.SweepRunning { + t.Errorf("080 during a full pass: %+v", mg) + } + + // 080 ready: waiting for the next pass. + mg = stageTrackerMergeGate("hivecommons/hive", 1, stagelabels.AwaitingMergeAdmission, rec(stagelabels.AwaitingMergeAdmission, ""), true, idle, now) + if mg == nil || mg.State != MergeGateStateReady || mg.NextSweepAt == nil { + t.Errorf("080: %+v", mg) + } + + // 095 soaking (hivecommons/hive#15044): the reason's remaining aged by + // the time since the lane last looked. + mg = stageTrackerMergeGate("hivecommons/hive", 15044, stagelabels.PreMergeSoak, rec(stagelabels.PreMergeSoak, "contributor-lane:soaking(remaining=10m0s)"), true, idle, now) + if mg == nil || mg.State != MergeGateStateSoaking || mg.SoakRemainingSeconds != 8*60 || mg.SoakUntil == nil || !mg.SoakUntil.Equal(now.Add(8*time.Minute)) { + t.Errorf("095: %+v", mg) + } + + // 100 merging. + if mg = stageTrackerMergeGate("hivecommons/hive", 2, stagelabels.MergeQueue, rec(stagelabels.MergeQueue, ""), true, idle, now); mg == nil || mg.State != MergeGateStateMerging { + t.Errorf("100: %+v", mg) + } + + // Off the gate: nothing. A past floor time is not a next pass. + for _, st := range []stagelabels.Stage{stagelabels.None, stagelabels.ReviewPending, stagelabels.Fixing, stagelabels.NeedsDecision, stagelabels.ReadyForHumanMerge} { + if mg = stageTrackerMergeGate("hivecommons/hive", 3, st, rec(st, "x"), true, idle, now); mg != nil { + t.Errorf("%v must carry no merge_gate: %+v", st, mg) + } + } + stale := automerge.SweepState{NextFloorAt: now.Add(-time.Second)} + if mg = stageTrackerMergeGate("hivecommons/hive", 4, stagelabels.AwaitingMergeAdmission, stagelabels.Record{}, false, stale, now); mg == nil || mg.NextSweepAt != nil || mg.LastSweepAt != nil { + t.Errorf("no record, stale floor: %+v", mg) + } +} + +// TestStageTrackerMergeGateInPayload: buildStageTracker stamps merge_gate +// on the PR item and mirrors it (with soak_remaining_seconds) onto the +// issue's nested linked_prs, reading the sweep state through the Server's +// seam. +func TestStageTrackerMergeGateInPayload(t *testing.T) { + now := time.Date(2026, 10, 28, 19, 23, 0, 0, time.UTC) + s, store := stageTrackerFixture(t, now) + s.sweepState = func() automerge.SweepState { return automerge.SweepState{NextFloorAt: now.Add(90 * time.Second)} } + resp := s.buildStageTracker(s.status, store, now) + // PR 102: soaking, 12m left as of a sweep 5m ago → 7m. + pr := trackerItem(t, resp, "pr", 102) + if pr.MergeGate == nil || pr.MergeGate.State != MergeGateStateSoaking || pr.MergeGate.SoakRemainingSeconds != 7*60 || pr.MergeGate.NextSweepAt == nil || !pr.MergeGate.NextSweepAt.Equal(now.Add(90*time.Second)) || pr.MergeGate.SweepRunning { + t.Fatalf("PR 102 merge_gate: %+v", pr.MergeGate) + } + // Off the gate: no merge_gate. + if off := trackerItem(t, resp, "pr", 103); off.MergeGate != nil { + t.Errorf("PR 103 (050) must carry no merge_gate: %+v", off.MergeGate) + } + if issue := trackerItem(t, resp, "issue", 8); issue.MergeGate != nil { + t.Errorf("issue rows carry no merge_gate: %+v", issue.MergeGate) + } + // Issue 7 mirrors PR 102: the nested copy carries the gate and the soak. + issue := trackerItem(t, resp, "issue", 7) + var lp *StageTrackerLinkedPR + for i := range issue.LinkedPRs { + if issue.LinkedPRs[i].Number == 102 { + lp = &issue.LinkedPRs[i] + } + } + if lp == nil || lp.MergeGate == nil || lp.MergeGate.State != MergeGateStateSoaking || lp.SoakRemainingSeconds != 7*60 { + t.Fatalf("nested PR 102 must mirror merge_gate + soak_remaining_seconds: %+v", issue.LinkedPRs) + } + raw, err := json.Marshal(pr) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{`"merge_gate":{`, `"state":"soaking"`, `"soak_remaining_seconds":420`, `"next_sweep_at":`, `"soak_until":`, `"last_sweep_at":`} { + if !strings.Contains(string(raw), want) { + t.Errorf("PR 102 json missing %s: %s", want, raw) + } + } + // A pass naming the PR: sweep_running, next_sweep_at withheld. + s.sweepState = func() automerge.SweepState { + return automerge.SweepState{Running: true, Cause: "event", StartedAt: now, NextFloorAt: now.Add(90 * time.Second), Targets: automerge.SweepTargets{"acme/console": {102: true}}} + } + pr = trackerItem(t, s.buildStageTracker(s.status, store, now), "pr", 102) + if pr.MergeGate == nil || !pr.MergeGate.SweepRunning || pr.MergeGate.NextSweepAt != nil { + t.Fatalf("PR 102 mid-sweep: %+v", pr.MergeGate) + } +} + +// TestStageTrackerMergeGateNode: the SPA's pure helpers over the two rows +// the operator compared (hivecommons/hive#15042 mid-sweep, #15054 waiting) +// and the soaking sub-row (#15044): every row on the gate gets the leading +// glyph with the same sentence as title and aria-label, the pill word is +// the stage's own with its live detail, countdowns tick in place, and the +// agent-working spinner carries its own sentence. +func TestStageTrackerMergeGateNode(t *testing.T) { + html := indexHTML(t) + for _, want := range []string{ + `const STAGE_TRACKER_MERGE_GATE_WORD = { 'gate-pending': 'Awaiting merge gate', ready: 'Ready for auto merge', soaking: 'Soaking', merging: 'Merging', merged: 'Merged' };`, + `60: 'Awaiting merge gate', 80: 'Ready for auto merge', 95: 'Soaking', 100: 'Merging'`, + `const gateCue = gateWord && typeof stageTrackerGateCueHtml === 'function' ? stageTrackerGateCueHtml(item, nowMs) : '';`, + `else if (active) inner = gateCue + workIco + (decision ? stageTrackerDecisionTriggerHtml(decision, word, tip) : word) + actorIco;`, + `if (gateInfo) tip = sg.label + ' — ' + gateInfo.tip;`, + `if (typeof stageTrackerGateCountdownSync === 'function') stageTrackerGateCountdownSync(el, nowMs);`, + `.ham-gate-ico { display: inline-flex;`, `.ham-gate-detail {`, + } { + if !strings.Contains(html, want) { + t.Errorf("index.html missing merge-gate wiring %q", want) + } + } + // The legend lives on the help page the (?) mark links to. + docs, err := os.ReadFile(filepath.Join("..", "..", "docs", "dashboard-sections.md")) + if err != nil { + t.Fatal(err) + } + for _, want := range []string{"**Merge gate pills — legend**", "Awaiting merge gate", "Ready for auto merge", "**Soaking**", "**Merging**", "next sweep in"} { + if !strings.Contains(string(docs), want) { + t.Errorf("docs/dashboard-sections.md missing merge-gate legend %q", want) + } + } + runStageTrackerRowActionsScript(t, "function esc(s) { return String(s).replace(/&/g, '&').replace(/ new Date(ms).toISOString(); +// Vocabulary pinned once: the column words and the gate words agree. +for (const [n, k] of [[60, 'gate-pending'], [80, 'ready'], [95, 'soaking'], [100, 'merging']]) assert.strictEqual(STAGE_TRACKER_ACTIVE_WORD[n], STAGE_TRACKER_MERGE_GATE_WORD[k], 'stage ' + n); + +// Captured 15:11 ET: both rows at 060 reviewed, CI pending. #15042 had a +// targeted sweep pass on it; #15054 was waiting for the next pass. +const pr15042 = { repo: 'hivecommons/hive', number: 15042, kind: 'pr', base_ref: 'v6', author_kind: 'hive', stage: 60, stage_slug: 'reviewed', reason: 'check-pending', + caption: 'Review swarm approved; a gate is still pending — CI is red (check-pending)', + merge_gate: { state: 'gate-pending', reason: 'check-pending', sweep_running: true, last_sweep_at: iso(now - 30000) } }; +const pr15054 = { repo: 'hivecommons/hive', number: 15054, kind: 'pr', base_ref: 'v5', author_kind: 'clanker', stage: 60, stage_slug: 'reviewed', reason: 'required-check-pending:build-and-test', + caption: 'Review swarm approved; a gate is still pending — check build-and-test still running', + merge_gate: { state: 'gate-pending', reason: 'required-check-pending:build-and-test', last_sweep_at: iso(now - 120000), next_sweep_at: iso(now + 42000) } }; +const pr15044 = { repo: 'hivecommons/hive', number: 15044, kind: 'pr', base_ref: 'v5', author_kind: 'clanker', stage: 95, stage_slug: 'pre-merge-soak', + merge_gate: { state: 'soaking', reason: 'contributor-lane:soaking(remaining=10m0s)', last_sweep_at: iso(now - 60000), next_sweep_at: iso(now + 200000), soak_until: iso(now + 452000), soak_remaining_seconds: 452 } }; +const ready = { repo: 'hivecommons/hive', number: 15060, kind: 'pr', stage: 80, merge_gate: { state: 'ready', last_sweep_at: iso(now - 10000), next_sweep_at: iso(now + 42000) } }; +const merging = { repo: 'hivecommons/hive', number: 15061, kind: 'pr', stage: 100, merge_gate: { state: 'merging', last_sweep_at: iso(now - 1000) } }; + +// Both 060 rows read the same word — neither is "Ready for auto merge" with CI pending. +let a = stageTrackerMergeGateInfo(pr15042, now), b = stageTrackerMergeGateInfo(pr15054, now); +assert.strictEqual(a.word, 'Awaiting merge gate'); assert.strictEqual(b.word, 'Awaiting merge gate'); +assert.strictEqual(a.cue, 'running'); assert.strictEqual(a.detail, 'merge sweep running'); +assert.strictEqual(a.tip, "hive's merge sweep is running on this PR now."); +assert.strictEqual(b.cue, 'waiting'); assert.strictEqual(b.detail, 'CI still running (build-and-test)'); +assert.ok(b.tip.startsWith('Review approved, not yet admitted to auto merge — CI still running (build-and-test). hive re-checks the gate on its next sweep in 42s.'), b.tip); +assert.ok(b.tip.includes('A GitHub event on the PR (check run, review, push) triggers a pass sooner.') && b.tip.endsWith('Last checked 2m ago.'), b.tip); + +// Every row on the gate gets the glyph; the sentence is its title AND aria-label. +for (const [it, cue, spin] of [[pr15042, 'running', true], [pr15054, 'waiting', false], [pr15044, 'soaking', false], [ready, 'waiting', false], [merging, 'merging', true]]) { + const g = stageTrackerGateCueHtml(it, now); + const tip = stageTrackerMergeGateInfo(it, now).tip; + assert.ok(g.startsWith(''), '#' + it.number + ': ' + g); + assert.ok(g.includes(spin ? 'class="ham-ico" viewBox' : 'class="ham-ico" viewBox') && g.includes(spin ? STAGE_TRACKER_ICONS.sweep : STAGE_TRACKER_ICONS.wait), '#' + it.number + ' glyph body'); +} +assert.strictEqual(stageTrackerGateCueHtml({ repo: 'r', number: 1, kind: 'pr', stage: 50 }, now), '', 'off the gate: no glyph'); +assert.strictEqual(stageTrackerGateCueHtml({ repo: 'r', number: 1, kind: 'pr', stage: STAGE_TRACKER_TERMINAL }, now), '', 'merged: no glyph'); + +// The pill word with the live detail; the waiting row says what it waits for. +assert.strictEqual(stageTrackerMergeGateWordHtml(ready, now), 'Ready for auto merge · next sweep in 42s'); +assert.strictEqual(stageTrackerMergeGateWordHtml(pr15044, now), 'Soaking · 8m left'); +assert.strictEqual(stageTrackerMergeGateWordHtml(pr15042, now), 'Awaiting merge gate · merge sweep running'); +assert.strictEqual(stageTrackerMergeGateWordHtml(merging, now), 'Merging'); +assert.strictEqual(stageTrackerMergeGateWordHtml({ stage: 50 }, now), ''); +const soak = stageTrackerMergeGateInfo(pr15044, now); +assert.strictEqual(soak.tip, 'Admitted by the automerge lane; waiting for the soak window: 8m left. hive merges on its first sweep after that. Last checked 1m ago.'); +assert.strictEqual(stageTrackerMergeGateInfo(ready, now).tip, "Approved and green; waiting for hive's merge sweep — next sweep in 42s. A GitHub event on the PR (check run, review, push) triggers a pass sooner. Last checked 10s ago."); +assert.strictEqual(stageTrackerMergeGateInfo(merging, now).tip, 'Admitted and soaked; hive is merging it now (GitHub merge queue / merge window). Last checked 1s ago.'); + +// Without merge_gate (older server) the stage alone picks the word and a plain sentence. +const old = stageTrackerMergeGateInfo({ stage: 80 }, now); +assert.deepStrictEqual([old.word, old.detail, old.cue], ['Ready for auto merge', '', 'waiting']); +assert.strictEqual(old.tip, "Approved and green; waiting for hive's merge sweep. A GitHub event on the PR (check run, review, push) triggers a pass sooner."); +assert.strictEqual(stageTrackerMergeGateInfo({ stage: 95, soak_remaining_seconds: 90 }, now).detail, '2m left', 'legacy soak_remaining_seconds still counts'); +assert.strictEqual(stageTrackerSoakLeft({ merge_gate: { soak_remaining_seconds: 452 } }), ' — 8m left', 'the 095 chevron tooltip reads the mirrored field too'); + +// Reason words. +assert.strictEqual(stageTrackerGateReasonText('check-pending'), 'CI still running'); +assert.strictEqual(stageTrackerGateReasonText('required-check-failing:lint'), 'CI is red (lint)'); +assert.strictEqual(stageTrackerGateReasonText('conflicting'), 'branch has conflicts'); +assert.strictEqual(stageTrackerGateReasonText('something-else'), 'something-else', 'unknown tokens pass through'); +assert.strictEqual(stageTrackerGateReasonText(''), ''); +assert.deepStrictEqual([stageTrackerShortLeft(42000), stageTrackerShortLeft(170000), stageTrackerShortLeft(3900000), stageTrackerShortLeft(0)], ['42s', '3m', '1h05m', '']); + +// Countdowns tick in place and flip to the "due" words once past. +const mk = (until, kind) => ({ attrs: { 'data-ham-until': String(until), 'data-ham-until-kind': kind }, textContent: '', getAttribute(n) { return this.attrs[n]; } }); +const n1 = mk(now + 42000, 'ready'), n2 = mk(now + 452000, 'soaking'); +const el = { querySelectorAll: () => [n1, n2] }; +stageTrackerGateCountdownSync(el, now + 30000); +assert.deepStrictEqual([n1.textContent, n2.textContent], ['· next sweep in 12s', '· 8m left']); +stageTrackerGateCountdownSync(el, now + 500000); +assert.deepStrictEqual([n1.textContent, n2.textContent], ['· sweep due now', '· soak window complete']); +console.log('merge-gate helpers ok'); +`) +} diff --git a/src/pkg/dashboard/stage_tracker_ui_test.go b/src/pkg/dashboard/stage_tracker_ui_test.go index 1566b01be4..85e36bf0c2 100644 --- a/src/pkg/dashboard/stage_tracker_ui_test.go +++ b/src/pkg/dashboard/stage_tracker_ui_test.go @@ -422,7 +422,7 @@ assert.ok(!stageTrackerRowHtml({ repo: 'acme/console', number: 30, kind: 'pr', t // With the PR's stage known the issue strip rides it (merge queue → Merge gate lit, hive move). row = stageTrackerRowHtml({ repo: 'acme/console', number: 8, kind: 'issue', stage: 40, linked_prs: [{ number: 102, title: 'Fix it', author_kind: 'human', author: 'bob', stage: 100, stage_since: new Date(now - 7200000).toISOString(), modifiers: ['stalled'], caption: 'Admitted, merging' }] }, stages, ctx); assert.deepStrictEqual(segStates(row), [D, D, D, D, D, 'active', 'todo cap']); -assert.ok(row.includes('Ready for auto mergeMergingstalled') && row.includes('2h'), 'chips + since come from the covering PR: ' + row); assert.ok(tooltip(row).includes('Admitted, merging') && tooltip(row).includes('Covering PR: #102'), tooltip(row)); assert.ok(prCol(row)[0].includes('ham-author-human') && prCol(row)[0].includes('Fix it'), prCol(row)[0]); @@ -431,11 +431,11 @@ assert.strictEqual(subs(row).length, 0); row = stageTrackerRowHtml({ repo: 'acme/console', number: 8, kind: 'issue', stage: 40, linked_prs: [{ number: 102, stage: 100 }, { number: 104 }] }, stages, ctx); assert.ok(subs(row)[1].includes('#104') && segStates(subs(row)[1]).every(st => st.startsWith('blank') || st === 'todo' || st === 'todo cap'), 'unknown PR stage: blank lead-in, nothing lit'); assert.ok(tooltip(row).includes('acme/console'), 'repo lives in the tooltip'); -// Full PR row for 100: Merge gate lit as Ready for auto merge with the hive actor icon. +// Full PR row for 100: Merge gate lit as Merging with the hive actor icon (#15073 vocabulary). row = stageTrackerRowHtml({ repo: 'acme/console', number: 102, kind: 'pr', stage: 100, author: 'hive-bot', author_kind: 'hive' }, stages, ctx); assert.deepStrictEqual(segStates(row), [D, D, D, D, D, 'active', 'todo cap']); assert.ok(strip(row).includes('title="Merge queue — admitted, merging · Next move: hive"'), 'chevron tooltip carries 100: ' + row); -assert.ok(text(row).includes('#102 Ready for auto merge'), text(row)); +assert.ok(text(row).includes('#102 Merging'), text(row)); // Full PR row for 095: Merge gate lit as Soaking (not a detour), hive actor, // chevron tooltip names the real stage and the time left; headline carries it too. row = stageTrackerRowHtml({ repo: 'acme/console', number: 13020, kind: 'pr', stage: 95, author: 'hive-bot', author_kind: 'hive', soak_remaining_seconds: 17 * 60 + 1 }, stages, ctx); @@ -689,7 +689,7 @@ assert.deepStrictEqual(segStates(row), ['active', T, T, T, T, T, 'todo cap']); // is what the chevron says, the actor is whose move it is. The active // chevron now leads with its stage icon, so the regex skips that svg. const prWords = {}; -for (const [st, word, actor] of [[50, 'CI / Review', 'hive'], [60, 'Ready for auto merge', 'hive'], [70, 'Fixing', 'author'], [71, 'Needs author', 'author'], [72, 'Returned to contributor', 'author'], [74, 'Adopted by hive', 'hive'], [80, 'Ready for auto merge', 'hive'], [85, 'Needs human decision', 'human'], [90, 'Ready for human merge', 'human'], [100, 'Ready for auto merge', 'hive']]) { +for (const [st, word, actor] of [[50, 'CI / Review', 'hive'], [60, 'Awaiting merge gate', 'hive'], [70, 'Fixing', 'author'], [71, 'Needs author', 'author'], [72, 'Returned to contributor', 'author'], [74, 'Adopted by hive', 'hive'], [80, 'Ready for auto merge', 'hive'], [85, 'Needs human decision', 'human'], [90, 'Ready for human merge', 'human'], [100, 'Merging', 'hive']]) { const r = stageTrackerRowHtml({ repo: 'acme/console', number: 500 + st, kind: 'pr', stage: st, author_kind: 'clanker' }, stages, ctx); const m = /aria-current="step">]*>[\s\S]*?<\/svg>([^<]*)<\/span>]*aria-label="Next move: ([a-z]+)"[^>]*>/.exec(r); assert.ok(m, 'stage ' + st + ' has no active word + actor: ' + r); @@ -700,7 +700,7 @@ for (const [st, word, actor] of [[50, 'CI / Review', 'hive'], [60, 'Ready for au // and the next mover for the strip's active segment; it stays empty when no // active segment is in range. assert.strictEqual(stageTrackerCurrentStageHtml({ repo: 'acme/console', number: 570, kind: 'pr', stage: 70, author_kind: 'clanker' }, stages), '

CI / Review · Fixing · Next move: clanker

'); -assert.strictEqual(stageTrackerCurrentStageHtml({ repo: 'acme/console', number: 560, kind: 'pr', stage: 60 }, stages), '

Ready for auto merge · Next move: hive

', 'no detour → column word only'); +assert.strictEqual(stageTrackerCurrentStageHtml({ repo: 'acme/console', number: 560, kind: 'pr', stage: 60 }, stages), '

Awaiting merge gate · Next move: hive

', 'no detour → column word only'); assert.strictEqual(stageTrackerCurrentStageHtml({ repo: 'acme/console', number: 570, kind: 'pr', stage: 70, author_kind: 'clanker' }, stages, { from: 500 }), '', 'no caption when the active segment is out of range'); assert.strictEqual(STAGE_TRACKER_ACTOR[70], 'author', '070 fixing is the author\'s move'); // Filters. diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index cbca72ba5b..c628090674 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -1556,6 +1556,14 @@ .ham-current-stage { display: none; margin: 0; font-size: var(--fs-xs); color: var(--muted); overflow-wrap: anywhere; } .ham-active-ico { display: none; } .cue-working .ham-seg.active:not(.cap) .ham-active-ico { display: inline-block; margin-right: var(--sp-1); } + .ham-active-ico-wrap { display: contents; } + /* Merge-gate cue (#15073): the leading glyph every row on the gate + wears — spinning while hive's sweep / merge is on it, a clock while + it waits; its title + aria-label say so in words. The live detail + after the word ("next sweep in 42s", "7m left") is muted. */ + .ham-gate-ico { display: inline-flex; align-items: center; margin-right: var(--sp-1); cursor: help; } + .ham-gate-ico .ham-ico { width: 12px; height: 12px; } + .ham-gate-detail { font-weight: normal; opacity: 0.85; white-space: nowrap; font-variant-numeric: tabular-nums; } @keyframes ham-pulse { 0%, 100% { opacity: 0; } 50% { opacity: 0.3; } } /* ---- tracker-cues: the Activity Monitor's shared cue vocabulary ------ Owner request: a viewer must always read where an item stands, @@ -13961,7 +13969,22 @@

Where to get help

const STAGE_TRACKER_POSSIBLY_EXISTS = 17; // Stages that share a column (or a detour word) and what the lit chevron says. const STAGE_TRACKER_PRE_MERGE_SOAK = 95; - const STAGE_TRACKER_ACTIVE_WORD = { 15: 'Triage needed', 17: 'Possibly exists', 60: 'Ready for auto merge', 80: 'Ready for auto merge', 95: 'Soaking', 100: 'Ready for auto merge', 45: 'Needs human decision', 85: 'Needs human decision' }; + // Merge-gate pill vocabulary (hivecommons/hive#15073), one word per + // stage sharing the Merge gate column, in pipeline order: + // 060 Awaiting merge gate — review approved; a gate still holds + // (CI pending / red, …): the pill says which + // 080 Ready for auto merge — green and approved; waiting for hive's + // merge sweep: "next sweep in 42s" + // 095 Soaking — admitted; the soak window runs: "7m left" + // 100 Merging — admitted and soaked; the merge is being + // attempted (GitHub merge queue / tide) + // 110 Merged — the ✓ cap + // stageTrackerMergeGateWordHtml adds the live detail; the leading glyph + // (stageTrackerGateCueHtml) says the same in a tooltip + aria-label. + // STAGE_TRACKER_ACTIVE_WORD repeats the words literally (fixtures lift + // it alone); stage_tracker_merge_gate_test.go pins the two equal. + const STAGE_TRACKER_MERGE_GATE_WORD = { 'gate-pending': 'Awaiting merge gate', ready: 'Ready for auto merge', soaking: 'Soaking', merging: 'Merging', merged: 'Merged' }; + const STAGE_TRACKER_ACTIVE_WORD = { 15: 'Triage needed', 17: 'Possibly exists', 60: 'Awaiting merge gate', 80: 'Ready for auto merge', 95: 'Soaking', 100: 'Merging', 45: 'Needs human decision', 85: 'Needs human decision' }; // Whose move it is on each lit chevron: 'author' = the PR's author kind, // 'claimant' = the live claim holder's kind; Open and Actionable carry none. const STAGE_TRACKER_ACTOR = { 15: 'human', 17: 'human', 20: 'claimant', 30: 'author', 40: 'author', 45: 'human', 50: 'hive', 60: 'hive', 70: 'author', 71: 'author', 72: 'author', 74: 'hive', 80: 'hive', 85: 'human', 90: 'human', 95: 'hive', 100: 'hive' }; @@ -14142,12 +14165,125 @@

Where to get help

// " — Xm left" for a 095 row whose payload carries the soak remaining. function stageTrackerSoakLeft(item) { - const sec = Number(item.soak_remaining_seconds) || 0; + const sec = Number(item.soak_remaining_seconds) || (item.merge_gate && Number(item.merge_gate.soak_remaining_seconds)) || 0; if (sec <= 0) return ''; const min = Math.ceil(sec / 60); return ' — ' + (min >= 60 ? Math.floor(min / 60) + 'h' + (min % 60 ? (min % 60) + 'm' : '') : min + 'm') + ' left'; } + /* ---- Merge gate (hivecommons/hive#15073) -------------------------------- + Pure helpers over the payload's merge_gate {state, reason, + sweep_running, last_sweep_at, next_sweep_at, soak_until, + soak_remaining_seconds}: the pill word with its live detail, the + plain-words sentence the leading glyph carries as tooltip + aria-label, + and the glyph itself. Every row on the gate gets the glyph — a sweep + on it now spins, a wait shows the clock — so two rows in the same + state never differ. Countdowns tick in place (data-ham-until) from the + cue age timer; no re-render. Run under node by + stage_tracker_merge_gate_test.go. */ + // Pure: a stage number's merge-gate state when the payload has none. + function stageTrackerMergeGateStateOf(item) { + if (item && item.merge_gate && item.merge_gate.state) return String(item.merge_gate.state); + const n = Number(item && item.stage) || 0; + if (n === 60) return 'gate-pending'; + if (n === 80) return 'ready'; + if (n === STAGE_TRACKER_PRE_MERGE_SOAK) return 'soaking'; + if (n === 100) return 'merging'; + if (n >= STAGE_TRACKER_TERMINAL) return 'merged'; + return ''; + } + // Pure: "42s" / "3m" / "1h05m" for a positive duration; '' otherwise. + function stageTrackerShortLeft(ms) { + if (!(ms > 0)) return ''; + const s = Math.ceil(ms / 1000); + if (s < 60) return s + 's'; + const m = Math.ceil(s / 60); + if (m < 60) return m + 'm'; + return Math.floor(m / 60) + 'h' + (m % 60 ? String(m % 60).padStart(2, '0') + 'm' : ''); + } + // Pure: the gate's reason token in plain words — "CI still running + // (build-and-test)", "CI is red (lint)"; '' for none. + const STAGE_TRACKER_GATE_REASON_WORDS = { + 'check-pending': 'CI still running', 'required-check-pending': 'CI still running', 'check-failing': 'CI is red', 'required-check-failing': 'CI is red', + 'optional-check-failing': 'an optional check is red', conflicting: 'branch has conflicts', 'needs-rebase': 'needs a rebase', 'dco-missing': 'DCO sign-off missing', + }; + function stageTrackerGateReasonText(reason) { + const raw = String(reason || '').trim(); + if (!raw) return ''; + const i = raw.indexOf(':'); + const slug = (i >= 0 ? raw.slice(0, i) : raw).replace(/\(.*$/, ''); + const detail = i >= 0 ? raw.slice(i + 1).replace(/\(.*$/, '') : ''; + const words = STAGE_TRACKER_GATE_REASON_WORDS[slug]; + if (!words) return raw; + return words + (detail ? ' (' + detail + ')' : ''); + } + // Pure: { word, detail, tip, cue } for an item on the gate, null off it. + // word — the pill word (STAGE_TRACKER_MERGE_GATE_WORD) + // detail — the live part after " · " ("next sweep in 42s", "7m left") + // tip — one plain sentence for the glyph's title + aria-label + // cue — 'running' (sweep on it now) | 'waiting' | 'soaking' | 'merging' | '' + // until — ms epoch the detail counts down to (0 when none) + function stageTrackerMergeGateInfo(item, nowMs) { + const state = stageTrackerMergeGateStateOf(item); + if (!state || state === 'merged') return null; + const mg = (item && item.merge_gate) || {}; + nowMs = typeof nowMs === 'number' ? nowMs : Date.now(); + const word = STAGE_TRACKER_MERGE_GATE_WORD[state] || state; + const nextAt = mg.next_sweep_at ? Date.parse(mg.next_sweep_at) : 0; + const lastAt = mg.last_sweep_at ? Date.parse(mg.last_sweep_at) : 0; + const lastSeen = lastAt > 0 ? ' Last checked ' + stageTrackerAgoText(lastAt, nowMs) + '.' : ''; + if (mg.sweep_running) { + return { state, word, detail: 'merge sweep running', tip: "hive's merge sweep is running on this PR now.", cue: 'running', until: 0 }; + } + const nextWords = nextAt > nowMs ? 'next sweep in ' + stageTrackerShortLeft(nextAt - nowMs) : (nextAt > 0 ? 'sweep due now' : ''); + const sooner = ' A GitHub event on the PR (check run, review, push) triggers a pass sooner.'; + if (state === 'soaking') { + const soakSec = Number(mg.soak_remaining_seconds) || Number(item.soak_remaining_seconds) || 0; + const until = mg.soak_until ? Date.parse(mg.soak_until) : (soakSec > 0 ? nowMs + soakSec * 1000 : 0); + const left = until > nowMs ? stageTrackerShortLeft(until - nowMs) : ''; + return { state, word, detail: left ? left + ' left' : 'soak window complete', tip: left ? 'Admitted by the automerge lane; waiting for the soak window: ' + left + ' left. hive merges on its first sweep after that.' + lastSeen : 'Admitted; the soak window is complete — hive merges on its next sweep' + (nextWords ? ' (' + nextWords + ')' : '') + '.' + lastSeen, cue: 'soaking', until: left ? until : 0 }; + } + if (state === 'ready') { + return { state, word, detail: nextWords, tip: "Approved and green; waiting for hive's merge sweep" + (nextWords ? ' — ' + nextWords + '.' : '.') + sooner + lastSeen, cue: 'waiting', until: nextAt > nowMs ? nextAt : 0 }; + } + if (state === 'merging') { + return { state, word, detail: '', tip: 'Admitted and soaked; hive is merging it now (GitHub merge queue / merge window).' + lastSeen, cue: 'merging', until: 0 }; + } + const why = stageTrackerGateReasonText(mg.reason || item.reason); + return { state, word, detail: why, tip: 'Review approved, not yet admitted to auto merge' + (why ? ' — ' + why : '') + '.' + (nextWords ? ' hive re-checks the gate on its ' + nextWords.replace(/^next /, 'next ') + '.' : '') + sooner + lastSeen, cue: 'waiting', until: 0 }; + } + // Pure: the pill word with its live detail — "Ready for auto merge · + // next sweep in 42s". The detail span carries data-ham-until so the + // countdown ticks in place. + function stageTrackerMergeGateWordHtml(item, nowMs) { + const info = stageTrackerMergeGateInfo(item, nowMs); + if (!info) return ''; + const detail = info.detail ? ` · ${esc(info.detail)}` : ''; + return `${esc(info.word)}${detail}`; + } + // Pure: the leading glyph for a row on the gate — spinning while hive's + // sweep is on it, a clock while it waits — with the sentence as title + // and aria-label. '' off the gate. + function stageTrackerGateCueHtml(item, nowMs) { + const info = stageTrackerMergeGateInfo(item, nowMs); + if (!info) return ''; + const spin = info.cue === 'running' || info.cue === 'merging'; + return `${stageTrackerIcon(spin ? 'sweep' : 'wait', 'ham-ico')}`; + } + // Pure: ticks every countdown in el from nowMs; "sweep due now" once a + // ready row's next pass has come. + function stageTrackerGateCountdownSync(el, nowMs) { + if (!el || typeof el.querySelectorAll !== 'function') return; + nowMs = typeof nowMs === 'number' ? nowMs : Date.now(); + for (const n of Array.from(el.querySelectorAll('.ham-gate-detail[data-ham-until]'))) { + const until = Number(n.getAttribute('data-ham-until')); + const left = stageTrackerShortLeft(until - nowMs); + const kind = n.getAttribute('data-ham-until-kind'); + const t = kind === 'soaking' ? (left ? '· ' + left + ' left' : '· soak window complete') : (left ? '· next sweep in ' + left : '· sweep due now'); + if (n.textContent !== t) n.textContent = t; + } + } + function stageTrackerHoldLabels(item) { const labels = Array.isArray(item.labels) ? item.labels : []; return labels.filter(label => { @@ -14328,6 +14464,10 @@

Where to get help

clanker: '', hive: '', pr: '', + // Merge-gate cues (#15073): sweep = two arrows chasing (spins while + // hive's sweep is on the PR); wait = a clock (waiting for the next pass). + sweep: '', + wait: '', }; // label is exposed to assistive tech only (aria-label, no ): hover // text in a tracker row belongs to the links, titles and the lit chevron. @@ -14424,7 +14564,11 @@ <h3 class="faq-group-title">Where to get help</h3> if (sg.draft) tip += ' — ' + STAGE_TRACKER_DRAFT_TIP; if (sg.openSince) tip += ' — open since ' + new Date(sg.openSince.ms).toISOString() + (sg.openSince.fromCreated ? ' (opened)' : ''); // The shared Merge gate word hides 080 vs 095 vs 100; the chevron tooltip carries it. - if (!sg.detour && (curStage === 60 || curStage === 80)) tip = sg.label + ' — not yet admitted' + (item.caption || item.reason ? ' — ' + (item.caption || item.reason) : ''); + // With merge_gate in the payload the sentence is the gate's own + // (what holds it, next sweep, soak left — #15073). + const gateInfo = !sg.detour && typeof stageTrackerMergeGateInfo === 'function' ? stageTrackerMergeGateInfo(item, nowMs) : null; + if (gateInfo) tip = sg.label + ' — ' + gateInfo.tip; + else if (!sg.detour && (curStage === 60 || curStage === 80)) tip = sg.label + ' — not yet admitted' + (item.caption || item.reason ? ' — ' + (item.caption || item.reason) : ''); else if (curStage === STAGE_TRACKER_PRE_MERGE_SOAK) tip = sg.label + ' — admitted, soaking' + stageTrackerSoakLeft(item); else if (curStage === 100) tip = sg.label + ' — admitted, merging'; // Why a person merges a 090 PR leads its tooltip (hivecommons/hive#14658). @@ -14442,9 +14586,17 @@ <h3 class="faq-group-title">Where to get help</h3> // becomes a button and the chevron drops its native title so the // popover (which repeats the stage line) is its one hover text. const decision = active && !sg.cap && typeof stageTrackerDecisionOf === 'function' ? stageTrackerDecisionOf(item) : null; - const word = sg.detour ? `<span class="ham-detour">${esc(sg.detour.text)}</span>` : `<span class="ham-seg-t">${esc(sg.short)}</span>`; + // On the merge gate the word carries its live detail and the + // leading glyph says in words what hive is doing (#15073). + const gateWord = active && !sg.cap && !sg.detour && typeof stageTrackerMergeGateWordHtml === 'function' ? stageTrackerMergeGateWordHtml(item, nowMs) : ''; + const word = sg.detour ? `<span class="ham-detour">${esc(sg.detour.text)}</span>` : (gateWord || `<span class="ham-seg-t">${esc(sg.short)}</span>`); + const gateCue = gateWord && typeof stageTrackerGateCueHtml === 'function' ? stageTrackerGateCueHtml(item, nowMs) : ''; + // The agent-working spinner (tracker-cues) names the agent and what + // it did, so a spinning glyph is never unexplained. + const workTip = worker && typeof stageTrackerCueLead === 'function' ? stageTrackerCueLead(item, worker, nowMs).replace(/ — $/, '') : ''; + const workIco = workTip ? `<span class="ham-active-ico-wrap" role="img" title="${esc(workTip)}" aria-label="${esc(workTip)}">${stageTrackerIcon(sg.number, 'ham-ico ham-active-ico')}</span>` : stageTrackerIcon(sg.number, 'ham-ico ham-active-ico'); if (sg.cap) inner = stageTrackerIcon(sg.number, 'ham-ico'); - else if (active) inner = stageTrackerIcon(sg.number, 'ham-ico ham-active-ico') + (decision ? stageTrackerDecisionTriggerHtml(decision, word, tip) : word) + actorIco; + else if (active) inner = gateCue + workIco + (decision ? stageTrackerDecisionTriggerHtml(decision, word, tip) : word) + actorIco; else inner = stageTrackerIcon(sg.number, 'ham-ico'); return `<li class="${cls}"${active ? `${sg.cap ? '' : motionAttr}${decision ? '' : ` title="${esc(tip)}"`} aria-current="step"` : ''}${sentinel ? ` aria-label="${esc(STAGE_TRACKER_SENTINEL_WORD + ' — ' + stageTrackerSentinelTip(item))}"` : ''}>${inner}</li>`; }).join(''); @@ -15297,6 +15449,7 @@ <h3 class="faq-group-title">Where to get help</h3> const t = stageTrackerAgoText(Number(n.getAttribute('data-at')), nowMs); if (n.textContent !== t) n.textContent = t; } + if (typeof stageTrackerGateCountdownSync === 'function') stageTrackerGateCountdownSync(el, nowMs); } let _stageTrackerCueTimer = null; function stageTrackerCueTick() { diff --git a/src/pkg/github/automerge/automerge_forgestate.go b/src/pkg/github/automerge/automerge_forgestate.go index 78c0cb40e5..88a6ea01d6 100644 --- a/src/pkg/github/automerge/automerge_forgestate.go +++ b/src/pkg/github/automerge/automerge_forgestate.go @@ -354,12 +354,14 @@ func (c *Engine) runEventDrivenSweep(ctx context.Context, maxMerges int, acmmAll } floor := time.NewTicker(c.floorInterval()) defer floor.Stop() + c.sweepClock.armFloor(c.now().Add(c.floorInterval())) c.sweepPass(ctx, maxMerges, acmmAllowed, nil, "startup") for { select { case <-ctx.Done(): return case <-floor.C: + c.sweepClock.armFloor(c.now().Add(c.floorInterval())) // The floor pass is low-priority work like the legacy tick: under // rate-limit caution it yields to the queue (#13382); event passes // are targeted and still run. diff --git a/src/pkg/github/automerge/automerge_sweep.go b/src/pkg/github/automerge/automerge_sweep.go index eeef03493a..5010d46851 100644 --- a/src/pkg/github/automerge/automerge_sweep.go +++ b/src/pkg/github/automerge/automerge_sweep.go @@ -293,6 +293,8 @@ type Engine struct { sweepTrigger *SweepTrigger // sweepFloor overrides automergeSweepFloorInterval (tests only). sweepFloor time.Duration + // sweepClock records the lanes' passes for the dashboard (sweep_clock.go). + sweepClock *SweepClock } // New returns an automerge sweep engine over a GitHub transport client. @@ -305,6 +307,7 @@ func New(transport Transport, opts Options) *Engine { transport: transport, gh: ghClient, logger: opts.Logger, + sweepClock: defaultSweepClock, mergerAuthz: opts.MergerAuthorizer, requiredChecks: opts.RequiredChecks, requiredChecksForRepo: opts.RequiredChecksForRepo, @@ -1439,6 +1442,7 @@ func (c *Engine) StartSelfAuthoredAutoMergeSweep(ctx context.Context, maxMerges defer close(done) t := time.NewTicker(interval) defer t.Stop() + c.sweepClock.armFloor(c.now().Add(interval)) // cautionTick is non-zero while the ticker is running at the caution // floor instead of the adaptive interval. var cautionTick time.Duration @@ -1452,6 +1456,11 @@ func (c *Engine) StartSelfAuthoredAutoMergeSweep(ctx context.Context, maxMerges t.Reset(gate.tick) } cautionTick = gate.cautionTick + tick := interval + if cautionTick != 0 { + tick = cautionTick + } + c.sweepClock.armFloor(c.now().Add(tick)) if gate.skip { continue } @@ -1461,6 +1470,7 @@ func (c *Engine) StartSelfAuthoredAutoMergeSweep(ctx context.Context, maxMerges } if next, changed := nextSelfAuthoredSweepInterval(repos, interval, result); changed { t.Reset(next) + c.sweepClock.armFloor(c.now().Add(next)) c.info("self-authored automerge sweep interval adjusted", "previous_interval", interval, "next_interval", next, @@ -1486,6 +1496,8 @@ func (c *Engine) StartSelfAuthoredAutoMergeSweep(ctx context.Context, maxMerges // for the log. It returns nil when the self-authored lane failed outright // (its callers then keep the current cadence). func (c *Engine) sweepPass(ctx context.Context, maxMerges int, acmmAllowed bool, targets SweepTargets, cause string) *AutoMergeSweepResult { + c.sweepClock.begin(cause, targets, c.now()) + defer func() { c.sweepClock.end(c.now()) }() result := &AutoMergeSweepResult{} if acmmAllowed { var err error diff --git a/src/pkg/github/automerge/sweep_clock.go b/src/pkg/github/automerge/sweep_clock.go new file mode 100644 index 0000000000..81e34b356c --- /dev/null +++ b/src/pkg/github/automerge/sweep_clock.go @@ -0,0 +1,97 @@ +package automerge + +import ( + "sync" + "time" +) + +// SweepState is what the automerge lanes are doing right now, for the +// dashboard's merge-gate rows (hivecommons/hive#15073): whether a pass is +// running and on which PRs, when the last pass finished and when the next +// periodic (floor) pass is due. Event-driven passes also run as webhooks +// name PRs, so NextFloorAt is the latest a waiting PR is re-evaluated, not +// the only time. +type SweepState struct { + Running bool + Cause string + StartedAt time.Time + FinishedAt time.Time + // NextFloorAt is when the next full pass is due; zero before the loop + // has started. + NextFloorAt time.Time + // Targets names the PRs the running pass evaluates; nil means every PR. + Targets SweepTargets +} + +// OnPR reports whether a pass is running now and evaluating repo#n. +func (s SweepState) OnPR(repo string, n int) bool { + if !s.Running { + return false + } + if s.Targets == nil { + return true + } + return s.Targets[canonicalSweepRepo(repo)][n] +} + +// SweepClock records sweep passes for SweepState. One lives process-wide +// (SweepSnapshot) so the dashboard, which never holds the engine, can read +// the lanes' cadence. +type SweepClock struct { + mu sync.Mutex + st SweepState +} + +func (c *SweepClock) begin(cause string, targets SweepTargets, now time.Time) { + if c == nil { + return + } + c.mu.Lock() + c.st.Running, c.st.Cause, c.st.StartedAt, c.st.Targets = true, cause, now, targets + c.mu.Unlock() +} + +func (c *SweepClock) end(now time.Time) { + if c == nil { + return + } + c.mu.Lock() + c.st.Running, c.st.FinishedAt, c.st.Targets = false, now, nil + c.mu.Unlock() +} + +func (c *SweepClock) armFloor(next time.Time) { + if c == nil { + return + } + c.mu.Lock() + c.st.NextFloorAt = next + c.mu.Unlock() +} + +// Snapshot returns a copy of the current state. +func (c *SweepClock) Snapshot() SweepState { + if c == nil { + return SweepState{} + } + c.mu.Lock() + defer c.mu.Unlock() + st := c.st + if st.Targets != nil { + cp := make(SweepTargets, len(st.Targets)) + for repo, nums := range st.Targets { + m := make(map[int]bool, len(nums)) + for n, v := range nums { + m[n] = v + } + cp[repo] = m + } + st.Targets = cp + } + return st +} + +var defaultSweepClock = &SweepClock{} + +// SweepSnapshot is the process-wide lanes' state (see SweepState). +func SweepSnapshot() SweepState { return defaultSweepClock.Snapshot() } From 7396333b64a8e8c75f7a20a554f48d6c8df5bb12 Mon Sep 17 00:00:00 2001 From: Andrew Anderson <andy@clubanderson.com> Date: Wed, 28 Oct 2026 15:55:31 -0400 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=8C=B1=20automerge:=20SweepClock=20un?= =?UTF-8?q?it=20test?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson <andy@clubanderson.com> --- src/pkg/github/automerge/sweep_clock_test.go | 51 ++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 src/pkg/github/automerge/sweep_clock_test.go diff --git a/src/pkg/github/automerge/sweep_clock_test.go b/src/pkg/github/automerge/sweep_clock_test.go new file mode 100644 index 0000000000..58532bf0bc --- /dev/null +++ b/src/pkg/github/automerge/sweep_clock_test.go @@ -0,0 +1,51 @@ +package automerge + +import ( + "testing" + "time" +) + +// TestSweepClock: begin/end/armFloor shape the SweepState the dashboard +// reads (hivecommons/hive#15073); a targeted pass is on its PRs only, a +// full pass on every PR, and the snapshot is a copy. +func TestSweepClock(t *testing.T) { + var nilClock *SweepClock + nilClock.begin("event", nil, time.Now()) + nilClock.end(time.Now()) + nilClock.armFloor(time.Now()) + if st := nilClock.Snapshot(); st.Running || !st.NextFloorAt.IsZero() { + t.Fatalf("nil clock must be inert: %+v", st) + } + + c := &SweepClock{} + t0 := time.Date(2026, 10, 28, 19, 11, 0, 0, time.UTC) + c.armFloor(t0.Add(5 * time.Minute)) + if st := c.Snapshot(); st.Running || st.OnPR("acme/console", 1) || !st.NextFloorAt.Equal(t0.Add(5*time.Minute)) { + t.Fatalf("armed, idle: %+v", st) + } + + targets := SweepTargets{"acme/console": {15042: true}} + c.begin("event", targets, t0) + st := c.Snapshot() + if !st.Running || st.Cause != "event" || !st.StartedAt.Equal(t0) { + t.Fatalf("running: %+v", st) + } + if !st.OnPR("acme/console", 15042) || !st.OnPR("ACME/Console", 15042) || st.OnPR("acme/console", 15054) || st.OnPR("acme/other", 15042) { + t.Errorf("targeted pass is on its PRs only: %+v", st.Targets) + } + st.Targets["acme/console"][15054] = true + if c.Snapshot().OnPR("acme/console", 15054) { + t.Errorf("Snapshot must copy targets") + } + + c.end(t0.Add(2 * time.Second)) + if st = c.Snapshot(); st.Running || st.Targets != nil || !st.FinishedAt.Equal(t0.Add(2*time.Second)) || st.OnPR("acme/console", 15042) { + t.Fatalf("ended: %+v", st) + } + + c.begin("floor", nil, t0.Add(5*time.Minute)) + if st = c.Snapshot(); !st.OnPR("acme/console", 15054) || !st.OnPR("any/repo", 1) { + t.Fatalf("full pass is on every PR: %+v", st) + } + c.end(t0.Add(5*time.Minute + time.Second)) +} From b7285dcc5a5895ba57ce98404f9a97831daac2af Mon Sep 17 00:00:00 2001 From: Andrew Anderson <andy@clubanderson.com> Date: Wed, 28 Oct 2026 16:06:40 -0400 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=96=20docs:=20resync=20api-referen?= =?UTF-8?q?ce=20citations=20after=20server.go=20line=20shift?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Andrew Anderson <andy@clubanderson.com> --- src/docs/api-reference.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/src/docs/api-reference.md b/src/docs/api-reference.md index 83c4fe36d4..95a05354cc 100644 --- a/src/docs/api-reference.md +++ b/src/docs/api-reference.md @@ -13,17 +13,17 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | `GET` | `/api/version` | Dashboard auth/session | Build/version metadata; includes `upgradeMarker` (`target`, `current`, `attempts`, `maxAttempts`, `failed`, `requestedAt`, `lastError`) while a self-upgrade is in flight or has failed ([#6765](https://github.com/hivecommons/hive/issues/6765)), the hub-delivered `upgradePolicy` (`hub_managed`, `spoke_managed`, `schedule`, `schedule_hour`, `schedule_timezone`, `schedule_weekday`, `paused`, `branch`, `channel`, `target_sha`, `target_resolved`, `armed_target`, and `next_update_at` — the hub's RFC3339 ETA for the next promotion into the `stable` channel, omitted when unknown ([#10256](https://github.com/hivecommons/hive/issues/10256))) when available, and an `autoUpdate` object (`enabled`, `state` — one of `disabled`/`up_to_date`/`behind`/`retrying`/`failed`/`unknown` — `healthy`, `period`, `targetBranch`, `targetCommit`, `currentCommit`, `commitsBehind`, `lastAttemptAt`, `lastError`, `detail`, and `nextUpdateAt` — the hub's RFC3339 ETA for the next update, omitted when unknown, disabled or paused ([#10257](https://github.com/hivecommons/hive/issues/10257))) that never reports a failed or unknown update as healthy ([#6962](https://github.com/hivecommons/hive/issues/6962), [#6963](https://github.com/hivecommons/hive/issues/6963)) | `pkg/dashboard/api.go:42` | | `GET` | `/api/version/release-notes` | Dashboard auth/session | Changelog gap between two revisions: `?from=<sha>&to=<channel-branch-tag-or-sha>` returns `{from:{sha,version?}, to:{sha,ref,version?}, sections:[{version,date,categories:{added,changed,fixed,security,deprecated}}], unreleased?, truncated, source, error?}` — the `CHANGELOG.md` release sections present at `to` and absent at `from`, newest first, plus (when `to` is not a release tag) the `changelog.d/` fragments new at `to` under an `Unreleased (in this build)` section. Fetch failures return `source: "unavailable"` with `error` rather than an error status; results are cached per (from, to) for an hour ([#11065](https://github.com/hivecommons/hive/issues/11065)) | `pkg/dashboard/api.go:43` | | `POST` | `/api/release-channel` | Owner only | Hosted spoke self-service release-channel selector; relays `stable`/`candidate`/`edge` to the hub's existing switch-branch endpoint with the spoke dashboard-token proof, and reports the requested channel as pending until the Deployment image lands | `pkg/dashboard/api.go:64` | -| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1530` | -| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1531` | -| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1532` | -| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1538` | -| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced}` is the governor strip's `running N · $X this hour` figure; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376) | `pkg/dashboard/server.go:1543` | -| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1544` | -| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1545` | -| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1546` | -| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1547` | -| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1548` | -| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1549` | +| `GET` | `/api/health` | Public | Basic health probe | `pkg/dashboard/server.go:1533` | +| `GET` | `/api/health/deep` | Public | Deep health probe | `pkg/dashboard/server.go:1534` | +| `GET` | `/api/livez` | Public | Kubernetes liveness probe | `pkg/dashboard/server.go:1535` | +| `GET` | `/metrics` | Registered only when `HIVE_METRICS_ENABLED`; requires `Authorization: ****** (403 if the token is unset) | Prometheus metrics | `pkg/dashboard/server.go:1541` | +| `GET` | `/api/status` | Dashboard auth/session | Dashboard aggregate status; `labelPresets[]` (`{key,label,description,labels[],states[]}`) lists the built-in label-filter presets for the Projects cards, led by `needs-human` whose `labels[]` are the effective hard-suppress labels plus `needs-signal`, the hold labels, `stage/071-needs-author` and the reporter-trust awaiting label (#12172); accepts `?fields=a,b` for top-level selection and `?omit=repos` to drop heavy sections, and honors `Accept-Encoding: gzip`; `agents[]` includes busy-pane visibility fields (`kicksUndeliverable`, `busySince`, `lastTranscriptActivity`, `condition`, `conditionMessage`) when a Working pane cannot accept kicks; a working agent also carries `agents[].run` — the live per-run line (#14576): `{since, elapsedS, costUSD, tokens, priced, tests, filesChanged}`, the estimated spend/tokens since the kick was delivered (`lastKickAt`, falling back to `busySince`) (delta of the token collector's per-agent cumulative figure; `priced:false` when the agent has none yet), the last visible test-runner result (`pass`/`fail`/empty) and the last `N files changed` git summary (`-1` when none) parsed from the captured pane; top-level `fleetRun` `{running, hourUSD, hourPriced}` is the governor strip's `running N · $X this hour` figure; `sla` (fleet) and `repos[].sla` (per repo) carry the Delivery SLA block derived from the lifecycle timeline with no extra GitHub calls: `windows.{7d,30d}.{open_to_triage,triage_to_start,start_to_pr,pr_to_merge,open_to_merge}` as `{p50_h,p95_h,n}` (hours, nearest-rank), `history[]` of up to 30 daily buckets `{day,start_to_pr_p50,pr_to_merge_p50,open_to_merge_p50,n_started,n_pr,n_merged}` persisted under `/data/sla-history.json`, `stale_in_progress[]` (`{number,repo,started_at,age_h,agent}` — issues carrying `hive/in-progress` longer than the agent claim TTL with no linked PR), `stale_count`, `merged_7d`, `claim_ttl_s` and, on the fleet block, the effective `targets` (`start_to_pr_h`, `pr_to_merge_h`, `open_to_merge_h`); `staleSince` and `repos[].countsStale` / `countsStaleSince` mark totals served from last-good figures — the previous enumeration (#13382) or the ForgeState cache's last-good counts (#13376) | `pkg/dashboard/server.go:1546` | +| `GET` | `/api/status/summary` | Dashboard auth/session | Compact agent/governor/budget status summary for pollers; honors `Accept-Encoding: gzip` | `pkg/dashboard/server.go:1547` | +| `GET` | `/api/overview/issues.csv` | Dashboard auth/session | Cached Overview issue-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1548` | +| `GET` | `/api/overview/issues.json` | Dashboard auth/session | Cached Overview issue-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1549` | +| `GET` | `/api/overview/prs.csv` | Dashboard auth/session | Cached Overview PR-band export as browser-compatible CSV; filters `band`, `repo`/`repos`, `stale`, and `held` are ANDed. | `pkg/dashboard/server.go:1550` | +| `GET` | `/api/overview/prs.json` | Dashboard auth/session | Cached Overview PR-band export as typed JSON with `bands[]` metadata and row fields matching the CSV columns. | `pkg/dashboard/server.go:1551` | +| `GET` | `/api/events` | Dashboard auth/session | Server-sent event stream | `pkg/dashboard/server.go:1552` | | `GET` | `/api/swarm` | Dashboard auth/session | Current swarm status: display name, duration, active repo, expiry, persisted prep metrics when available, and idle-unlock fields. | `pkg/dashboard/swarm.go:310` | | `POST` | `/api/swarm` | Owner only | Start a 24h repo swarm for a configured repo, returning 409 when another swarm is active and 423 when a previous swarm keeps the next swarm locked until enough agents are idle unless body `{"repo":"owner/name","force":true}` is used; saves the active record before repo prep, persists prep metrics, and announces the start to Discord when configured. | `pkg/dashboard/swarm.go:311` | | `DELETE` | `/api/swarm` | Owner only | End the active swarm, score issues closed and PRs merged in the window, append it to history, and announce the result to Discord when configured. | `pkg/dashboard/swarm.go:312` | @@ -66,7 +66,7 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| | `GET` | `/api/style` | Public | Sanitized custom dashboard CSS | `pkg/dashboard/api.go:44` | -| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](branding.md)) | `pkg/dashboard/server.go:1610` | +| `GET` | `/branding/custom.css` | Dashboard auth/session | Operator branding stylesheet override, read per request (see [branding](branding.md)) | `pkg/dashboard/server.go:1613` | | `GET` | `/api/snapshot/frame-ancestors` | Public | Snapshot framing allowlist | `pkg/dashboard/api.go:77` | | `GET` | `/api/snapshot` | Public | Snapshot data | `pkg/dashboard/api.go:78` | | `GET` | `/snapshot` | Public | Public read-only snapshot page | `pkg/dashboard/api.go:79` | @@ -94,9 +94,9 @@ History point limits, timestamp cutoffs, incremental cost reads and ETag/304 beh | `GET` | `/api/openrouter/models` | Dashboard auth/session | Open Router Models | `pkg/dashboard/openrouter.go:47` | | `GET` | `/api/openrouter/credit` | Dashboard auth/session | Open Router Credit | `pkg/dashboard/openrouter.go:48` | | `GET` | `/openrouter/callback` | Public | Open Router Callback | `pkg/dashboard/openrouter.go:49` | -| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1550` | -| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1551` | -| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1552` | +| `POST` | `/api/github-app/recheck` | Dashboard auth/session | GitHub App Recheck | `pkg/dashboard/server.go:1553` | +| `POST` | `/api/github-app/install-clicked` | Dashboard auth/session | GitHub App Install Clicked | `pkg/dashboard/server.go:1554` | +| `GET` | `/gh-setup` | Public | GitHub App Setup Callback | `pkg/dashboard/server.go:1555` | ## Configuration @@ -595,7 +595,7 @@ always resolved server-side from the validated token. | `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:275` | | `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:276` | | `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:277` | -| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1557` | +| `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1560` | ## Hub SaaS