diff --git a/changelog.d/changed-pills-until-merge-gate.md b/changelog.d/changed-pills-until-merge-gate.md new file mode 100644 index 0000000000..c1750d2f33 --- /dev/null +++ b/changelog.d/changed-pills-until-merge-gate.md @@ -0,0 +1 @@ +- Hive activity monitor: `sentinel`, `needs human`, `needs human decision` and merge-time `unauthorized` pills are held back (payload `deferred_modifiers`) until the pull request reaches the merge gate (stage/080+), and do not count under *Needs attention* before then; `hold`, `draft`, `stalled`, `regressed` and an `unauthorized` on held workflow runs always show. diff --git a/src/docs/dashboard-sections.md b/src/docs/dashboard-sections.md index 5343658fa7..9002212db4 100644 --- a/src/docs/dashboard-sections.md +++ b/src/docs/dashboard-sections.md @@ -640,7 +640,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. 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`) 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 health modifier or on 071 / 072 / 085 / 090), 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`) 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 health modifier or on 071 / 072 / 085 / 090), 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/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. 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`) 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`) 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). **Repo chip.** Each row carries a small monospace chip before the number naming the repository it belongs to (`dibs #456`, `hive #13524`); the chip is tinted per repository from a fixed palette so one repo always looks the same, the configured primary repo is shown muted, and the full `owner/repo` is in the tooltip. Linked PR sub-rows carry the same chip. Clicking a chip sets the **Repo** filter to that repository (click it again, or pick "All repos", to clear). By default the chip appears only when the list spans more than one repository; the ⚙ settings modal's **Repositories** section offers **Show repo chip: always / only when multiple repos / never** (stored under `hive.tracker.repochip`). @@ -652,11 +652,26 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p **Movement animation (⚙ on the card header).** When a refresh moves an item's lit chevron to a different column — forward (advance) or backward (regress) — the row plays a short, subtle three-beat sequence so the eye can see where it went: first the chevron it is *leaving* flashes the active highlight twice (two ~140 ms pulses with a short gap), then the chosen effect travels from that chevron to the new one, and finally the new chevron lands lit — the whole sequence takes about a second. Pick the travel effect in the same settings modal, under **Movement animation** below the sound settings: **None**, **A Sliding puck** (a highlight glides from the old chevron to the new one and settles), **B Ripple** (each chevron between old and new lights in turn), **C Ghost crossfade** (the old highlight fades out while the new one fades in with a slight slide), **D Comet** (a streak with a bright head travels the strip and lands on the destination), **E Destination bump** (the destination chevron scales briefly with a fading direction arrow), or **F Colour wash** (default — a tinted sweep flows across the intermediate chevrons). Each option has a *Preview* button that plays the full flash → move → land sequence on a sample row inside the dialog. The choice is remembered per browser (`localStorage` key `hiveStageTrackerMotion`). Items that stay put never move; a row that leaves the list (merged, closed, or filtered away) collapses and fades out over `--ham-move-exit-ms` and a row that arrives fades in over `--ham-move-enter-ms`; nothing animates on first load, and at most twelve rows animate per refresh (a filter or page change that turns over more rows than that redraws at once). The list is reconciled row by row on every refresh rather than rebuilt, so a move keeps playing while the hive keeps publishing. When the operating system asks for reduced motion (`prefers-reduced-motion: reduce`), every style falls back to a single soft flash followed by a plain crossfade and departing rows only fade, regardless of the setting; **None** disables the flash, the effect and the row fades entirely. Durations, the flash timing (`--ham-move-flash-ms`, `--ham-move-flash-gap-ms`, `--ham-move-flash-count`) and tints come from the `--ham-move-*` tokens in `tokens.css`. -**Sentinel alert.** A pull request the suspicious-activity sentinel flagged — it wears the `sentinel-alert` label (`sentinel.label`), or the review evidence bundle for its current head records sentinel findings — carries `sentinel_alert: true` in the tracker payload (with `sentinel_findings` and a short `sentinel_reason` when the bundle has them); a webhook label change flips it live. In the **Needs human decision** lane the lit chevron's own words read **Sentinel alert · needs human** (danger-tinted, the same wording in the cell's `title` and `aria-label`, and in the compact caption), so a maintainer reads the security implication before the stage mechanics; in every other lane the row shows a compact danger-tinted `sentinel` chip ahead of `needs rebase` / `regressed` / `stalled`. The tooltip reads "Sentinel flagged security-relevant changes at ``: ``" (a generic description stands in when the bundle has no reason). An issue carried by one flagged PR shows the lane text too, and a nested PR sub-row shows its own. The *Decide…* dialogs for a flagged PR open with a ⚠ line per flagged PR naming the sentinel reason, and *Approve* is styled as a dangerous action. Lane text and chip update in place on refresh (keyed reconcile, no flash). +**Sentinel alert.** A pull request the suspicious-activity sentinel flagged — it wears the `sentinel-alert` label (`sentinel.label`), or the review evidence bundle for its current head records sentinel findings — carries `sentinel_alert: true` in the tracker payload (with `sentinel_findings` and a short `sentinel_reason` when the bundle has them); a webhook label change flips it live. In the **Needs human decision** lane the lit chevron's own words read **Sentinel alert · needs human** (danger-tinted, the same wording in the cell's `title` and `aria-label`, and in the compact caption), so a maintainer reads the security implication before the stage mechanics; in every other lane at or past the merge gate (080, 090, 095, 100) the row shows a compact danger-tinted `sentinel` chip ahead of `needs rebase` / `regressed` / `stalled`; before the gate the chip is held back with the other merge-gate pills (see *Pills before the merge gate*) while `sentinel_alert` stays truthful in the payload. The tooltip reads "Sentinel flagged security-relevant changes at ``: ``" (a generic description stands in when the bundle has no reason). An issue carried by one flagged PR shows the lane text too, and a nested PR sub-row shows its own. The *Decide…* dialogs for a flagged PR open with a ⚠ line per flagged PR naming the sentinel reason, and *Approve* is styled as a dangerous action. Lane text and chip update in place on refresh (keyed reconcile, no flash). -**Unauthorized pill.** A pull request the hive cannot move because its GitHub App lacks a permission for the next step — it wears `hive:unauthorized` ([#14589](https://github.com/hivecommons/hive/issues/14589)); first case: approving held `action_required` workflow runs needs `actions: write` — carries the `unauthorized` modifier in the tracker payload, drawn in the far-right pill column exactly like `stalled` / `hold` / `draft` but muted (dashed, `--text-muted`), never red: it is nothing wrong, just a step only a person may take. It counts under **Needs attention**. Its tooltip (payload `unauthorized`) names the missing permission and the human step; on the **Needs human decision** lane the lit chevron and the caption read **Awaiting human: approve workflow runs** (payload `unauthorized_step`, from the `unauthorized:` stage reason). The pill, label and payload fields clear themselves in the tick the step is no longer needed. -**Closed issue, open PR.** A pull request whose `Fixes #N` issue has already closed (auto-closed by a bot, or closed by hand) while the PR is still open is live work, not a stale line: the row is anchored on the PR ([#14655](https://github.com/hivecommons/hive/issues/14655)). The PR's own icon, number and title lead the row at full width, its stage drives the strip and its timestamps sort it — closing the issue is not a regression of the PR — and the closed issue shrinks to a muted `closes #N · closed` chip linking to it. An issue closed as *not planned* adds an `issue closed (not planned)` chip so the reader can tell the PR may be moot. At 090 such a row still counts under *Needs attention*: the human has a merge to click. When the PR closes or merges too, the row leaves the list as before (a merged PR shows in *Recently merged* for its retention window). +**Unauthorized pill.** A pull request the hive cannot move because its GitHub App lacks a permission for the next step — it wears `hive:unauthorized` ([#14589](https://github.com/hivecommons/hive/issues/14589)); first case: approving held `action_required` workflow runs needs `actions: write` — carries the `unauthorized` modifier in the tracker payload, drawn in the far-right pill column exactly like `stalled` / `hold` / `draft` but muted (dashed, `--text-muted`), never red: it is nothing wrong, just a step only a person may take. It counts under **Needs attention**. Before the merge gate only the held-workflow-runs step shows (see *Pills before the merge gate*). Its tooltip (payload `unauthorized`) names the missing permission and the human step; on the **Needs human decision** lane the lit chevron and the caption read **Awaiting human: approve workflow runs** (payload `unauthorized_step`, from the `unauthorized:` stage reason). The pill, label and payload fields clear themselves in the tick the step is no longer needed. + +**Pills before the merge gate.** Owner's rule (2026-10-27): until a pull request is in the merge gate there is nothing a person can do about a `sentinel`, `needs human` or `unauthorized` notice — the PR is still in motion — so the tracker must not show them. The server splits every marker into two classes (`stageTrackerModifiers` in `stage_tracker.go`; each carries an explicit `ActionableNow` flag) and the row's payload carries the pills it draws in `modifiers` and the ones it holds back in `deferred_modifiers`. A deferred pill is simply absent — no chip, no breathing chevron, no **Needs attention** count — until the PR's stage reaches the merge-gate band (`stage/080` and later: 080, 085, 090, 095, 100, the same boundary adoption yields at), when it renders exactly as before and counts; the row tooltip alone says "Pending at merge gate: sentinel, needs-human". The merge-gate cell's own words ("Sentinel alert · needs human", "Awaiting human: …") are unchanged — they only appear at the gate anyway. Issues on their own stages (Open, 010, 020, 045) keep every pill: a `needs-human` there is a park the person owes now; an issue riding its covering PR's stage follows the PR. The GitHub labels are untouched — this is presentation and counting only. +| pill | class | when shown | +| --- | --- | --- | +| `hold` | actionable now | always (a person placed it) | +| `draft` | actionable now | always (the author's move) | +| `stalled` | actionable now | always | +| `regressed` | actionable now | always; muted `stage ↓` unless the row is parked on a person (see above) | +| `needs-rebase`, `blocked`, `triage needed`, `possible dupe` | actionable now | always | +| `unauthorized` — `unauthorized:approve-workflow-runs` | actionable now | always — the carve-out: held workflow runs mean CI cannot even start, and waiting for the gate would waste the whole CI / review cycle (rationguard#397 at 072) | +| `unauthorized` — any other step (merge, branch update, no step named) | merge gate | PR at stage/080 or later | +| `sentinel` (the trusted-author notice and the real `sentinel-alert` alike) | merge gate | PR at stage/080 or later; `sentinel_alert` itself stays truthful in the payload for the lane word and the Decide… preface | +| `needs human` (`needs-human` label) | merge gate | PR at stage/080 or later; always on an issue at its own stage | +| `needs human decision` (`needs-decision` labels on another stage) | merge gate | PR at stage/080 or later; always on an issue at its own stage | + +**Closed issue, open PR.** A pull request whose `Fixes #N` issue has already closed (auto-closed by a bot, or closed by hand) while the PR is still open is live work, not a stale line: the row is anchored on the PR ([#14655](https://github.com/hivecommons/hive/issues/14655)). The PR's own icon, number and title lead the row at full width, its stage drives the strip and its timestamps sort it — closing the issue is not a regression of the PR — and the closed issue shrinks to a muted `closes #N · closed` chip linking to it. An issue closed as *not planned* adds an `issue closed (not planned)` chip so the reader can tell the PR may be moot. At 090 such a row still counts under *Needs attention*: the human has a merge to click. When the PR closes or merges too, the row leaves the list as before (a merged PR shows in *Recently merged* for its retention window). **Row gutter.** Every issue and PR row (never a column or repo-group header) carries a left gutter with a select checkbox and a ⋯ actions button that is always present and always visible: dimmed at rest (`--ham-tool-rest-opacity`), at full emphasis on the row under the pointer or holding focus, on a selected row, and on every row while anything is selected or the context menu is open — the only animation is the hover fade (`--ham-tool-fade-ms`, ≤ 120 ms), and nothing about it depends on scrolling, row position or which rows the live refresh re-created. diff --git a/src/pkg/dashboard/stage_tracker.go b/src/pkg/dashboard/stage_tracker.go index 00cb6088dc..6e52fc82e7 100644 --- a/src/pkg/dashboard/stage_tracker.go +++ b/src/pkg/dashboard/stage_tracker.go @@ -262,11 +262,20 @@ type StageTrackerItem struct { Reason string `json:"reason,omitempty"` Caption string `json:"caption"` Actor string `json:"actor,omitempty"` - // Modifiers are the health and control markers in effect: stalled, - // regressed, hold, needs-human, needs-decision (stage/045 on an issue or - // stage/085 on a PR carried as a park signal), needs-rebase, blocked, - // draft. + // Modifiers are the health and control markers in effect and drawn as + // pills: stalled, regressed, hold, needs-human, needs-decision + // (stage/045 on an issue or stage/085 on a PR carried as a park + // signal), needs-rebase, blocked, draft, unauthorized. A merge-gate + // marker on a PR that has not reached the gate band is not listed + // here; it waits in DeferredModifiers. Modifiers []string `json:"modifiers"` + // DeferredModifiers are the merge-gate markers held back while the PR + // is still in motion before the gate (needs-human, needs-decision, + // sentinel, a merge-time unauthorized step): nothing a person does now + // moves the row, so the tracker draws no pill and "Needs attention" + // does not count them until the PR reaches stage/080 or later. The + // labels themselves are untouched; this is presentation only. + DeferredModifiers []string `json:"deferred_modifiers,omitempty"` // RegressedFrom / RegressedTo / RegressedAt / RegressedReason narrate // the unresolved regression behind the `regressed` modifier: the // high-water stage the item fell from, the stage that fall landed on @@ -399,6 +408,9 @@ type StageTrackerLinkedPR struct { StageSince *time.Time `json:"stage_since,omitempty"` Caption string `json:"caption,omitempty"` Modifiers []string `json:"modifiers,omitempty"` + // DeferredModifiers mirrors the nested PR's own row field: the + // merge-gate pills it is not yet drawing. + DeferredModifiers []string `json:"deferred_modifiers,omitempty"` // SentinelAlert / SentinelReason mirror the nested PR's own row fields // so a sub-row under an issue names the alert too. SentinelAlert bool `json:"sentinel_alert,omitempty"` @@ -461,6 +473,9 @@ const ( // hive's GitHub App lacks the permission for its next step and a // person must take it (hivecommons/hive#14589). modUnauthorized = "unauthorized" + // modSentinel names the sentinel chip in DeferredModifiers; the chip + // itself is drawn from SentinelAlert, never from Modifiers. + modSentinel = "sentinel" ) // Lane names. @@ -684,7 +699,48 @@ func (s *Server) stageTrackerSentinel(verifier *github.ReviewEvidenceVerifier, r // stageTrackerModifierOrder is the modifier precedence the payload carries. var stageTrackerModifierOrder = []string{modStalled, modRegressed, modHold, modUnauthorized, modNeedsHuman, modNeedsDecision, modNeedsTriage, modPossibleDupe, modNeedsRebase, modBlocked, modDraft} -func stageTrackerModifiers(labels []string, hiveID string, rec stagelabels.Record, hasRec bool, overrides map[string]time.Duration, now time.Time, draft bool) []string { +// stageTrackerModifier is one health or control marker with its class. +type stageTrackerModifier struct { + Name string + // ActionableNow: a person must do something right now for the row to + // move, whatever its stage (hold, draft, stalled, regressed, a step + // the App may not take that blocks the current stage). False marks a + // merge-gate marker — needs-human, needs-decision, a merge-time + // unauthorized step — that only becomes actionable once the PR reaches + // the gate band; before that the tracker holds it back. + ActionableNow bool +} + +// stageTrackerPillsDeferred reports whether a row's merge-gate markers are +// held back: a PR (or an issue riding its covering PR's stage) that has +// not reached the merge-gate band yet. The band starts at stage/080 — +// stagelabels.AwaitingMergeAdmission, the same boundary adoption yields +// at — and runs through 085/090/095/100. Issues on their own stages keep +// every pill: a needs-human on an unclaimed issue is a park the person +// owes now, not a merge-time notice. +func stageTrackerPillsDeferred(kind string, stageNumber int, mirrored bool) bool { + if kind != "pr" && !mirrored { + return false + } + return stageNumber < stagelabels.AwaitingMergeAdmission.Number() +} + +// stageTrackerUnauthorizedActionableNow reports whether the step the App +// may not take blocks the row where it stands, so a person must act now: +// held workflow runs mean CI cannot even start, and waiting for the merge +// gate would waste the whole CI / review cycle. Any other refused step +// (merge, branch update, …), or a label whose reason no longer names the +// step, is a merge-time step and waits for the gate. +func stageTrackerUnauthorizedActionableNow(reason string) bool { + base, _ := stagelabels.HumanApprovedReason(strings.TrimSpace(reason)) + rest, ok := strings.CutPrefix(base, stageengineprstage.StageReasonUnauthorizedPrefix) + return ok && strings.TrimSpace(rest) == stageengineprstage.UnauthorizedStepApproveWorkflowRuns +} + +// stageTrackerClassifyModifiers derives the row's markers from its labels, +// store record and draft flag, each with its class; reason is the lane's +// stage reason, read for the unauthorized step. Order is the pill priority. +func stageTrackerClassifyModifiers(labels []string, hiveID string, rec stagelabels.Record, hasRec bool, overrides map[string]time.Duration, now time.Time, draft bool, reason string) []stageTrackerModifier { set := map[string]bool{} for _, l := range labels { switch lower := strings.ToLower(strings.TrimSpace(l)); lower { @@ -727,11 +783,19 @@ func stageTrackerModifiers(labels []string, hiveID string, rec stagelabels.Recor if draft { set[modDraft] = true } - out := make([]string, 0, len(set)) + out := make([]stageTrackerModifier, 0, len(set)) for _, m := range stageTrackerModifierOrder { - if set[m] { - out = append(out, m) + if !set[m] { + continue } + actionable := true + switch m { + case modNeedsHuman, modNeedsDecision: + actionable = false + case modUnauthorized: + actionable = stageTrackerUnauthorizedActionableNow(reason) + } + out = append(out, stageTrackerModifier{Name: m, ActionableNow: actionable}) } return out } @@ -774,6 +838,26 @@ func stageTrackerBlockerList(repo string, blockers []string) string { return strings.Join(parts, ", ") } +// stageTrackerModifiers splits a row's markers into the pills it draws +// (shown) and the merge-gate pills it holds back (deferred) until the PR +// reaches the gate band. Everything actionable now is always shown; a +// merge-gate marker is shown once stageTrackerPillsDeferred says the row +// is at or past the gate, or the row is an issue on its own stage. +func stageTrackerModifiers(labels []string, hiveID string, rec stagelabels.Record, hasRec bool, overrides map[string]time.Duration, now time.Time, draft bool, reason string, kind string, stage stagelabels.Stage, mirrored bool) (shown, deferred []string) { + held := stageTrackerPillsDeferred(kind, stage.Number(), mirrored) + for _, m := range stageTrackerClassifyModifiers(labels, hiveID, rec, hasRec, overrides, now, draft, reason) { + if m.ActionableNow || !held { + shown = append(shown, m.Name) + } else { + deferred = append(deferred, m.Name) + } + } + if shown == nil { + shown = []string{} + } + return shown, deferred +} + // noVerdictClause is the bare no-verdict clause; stageTrackerCaption swaps // in "awaiting review of head " when the item's head is known. const noVerdictClause = "no review verdict yet" @@ -1276,7 +1360,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto // An issue wearing a PR stage (050+) is riding its covering PR; its // own parking bay 045 is not a mirror. it.Mirrored = it.Kind == "issue" && stage != stagelabels.None && !stage.Applies(stagelabels.IssueItem) - it.Modifiers = stageTrackerModifiers(labels, status.HiveID, rec, hasRec, overrides, now, draft) + it.Modifiers, it.DeferredModifiers = stageTrackerModifiers(labels, status.HiveID, rec, hasRec, overrides, now, draft, it.Reason, it.Kind, stage, it.Mirrored) // 045/085 have their own chevron word ("Needs human decision"); the // chip only adds information when needs-decision modifies another // stage. @@ -1301,7 +1385,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto if stage == stagelabels.ReadyForHumanMerge { it.HumanMergeReason, _, it.HumanMergeReasonText = stageTrackerHumanMergeReason(it.Reason) } - if slices.Contains(it.Modifiers, modUnauthorized) { + if slices.Contains(it.Modifiers, modUnauthorized) || slices.Contains(it.DeferredModifiers, modUnauthorized) { it.UnauthorizedStep, it.Unauthorized = stageTrackerUnauthorized(it.Reason) } it.History = stageTrackerHistory(rec) @@ -1404,6 +1488,13 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto } finish(&it, pr.Labels, labelStage(pr.Labels), rec, ok, pr.Draft) it.SentinelAlert, it.SentinelFindings, it.SentinelReason = s.stageTrackerSentinel(evidenceVerifier, repoName, pr.Number, pr.HeadSHA, pr.Labels) + // The sentinel chip is a merge-gate pill too (the trusted-author + // notice and the real alert alike): sentinel_alert stays truthful + // for the gate word and the Decide… preface, but before the gate + // the chip is held with the other deferred pills. + if it.SentinelAlert && stageTrackerPillsDeferred(it.Kind, it.Stage, it.Mirrored) { + it.DeferredModifiers = append([]string{modSentinel}, it.DeferredModifiers...) + } it.LinkedIssues = stageTrackerPRLinkedIssues(pr, repoName, status.GitHubBaseURL) add(it) } @@ -2106,6 +2197,9 @@ func stageTrackerResolveLinkedPRs(items []StageTrackerItem) { if len(pr.Modifiers) > 0 { lp.Modifiers = append([]string(nil), pr.Modifiers...) } + if len(pr.DeferredModifiers) > 0 { + lp.DeferredModifiers = append([]string(nil), pr.DeferredModifiers...) + } if lp.URL == "" { lp.URL = pr.URL } diff --git a/src/pkg/dashboard/stage_tracker_pills_gate_test.go b/src/pkg/dashboard/stage_tracker_pills_gate_test.go new file mode 100644 index 0000000000..1d420f9186 --- /dev/null +++ b/src/pkg/dashboard/stage_tracker_pills_gate_test.go @@ -0,0 +1,242 @@ +package dashboard + +import ( + "encoding/json" + "os/exec" + "slices" + "strings" + "testing" + "time" + + "github.com/hivecommons/hive/pkg/config" + "github.com/hivecommons/hive/pkg/github" + "github.com/hivecommons/hive/pkg/stageengine/prstage" + "github.com/hivecommons/hive/pkg/stagelabels" +) + +// The owner's rule (2026-10-27): until a PR is in the merge gate, the +// tracker must not show pills nobody can act on while the PR is in motion +// — sentinel, needs-human, needs-decision, a merge-time unauthorized step. +// Pills a person must act on right now (hold, draft, stalled, regressed, +// held workflow runs) always show. The split is computed server-side: +// every modifier carries an explicit ActionableNow class, and +// stageTrackerModifiers hands the row its shown and deferred lists. +func TestStageTrackerModifiers_DeferredUntilMergeGate(t *testing.T) { + now := time.Now() + heldRuns := prstage.StageReasonUnauthorizedPrefix + prstage.UnauthorizedStepApproveWorkflowRuns + merge403 := prstage.StageReasonUnauthorizedPrefix + "merge" + for _, tc := range []struct { + name string + labels []string + draft bool + reason string + kind string + stage stagelabels.Stage + mirrored bool + wantShown []string + wantDeferred []string + }{ + {name: "needs-human at 050 is deferred", labels: []string{"needs-human"}, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{}, wantDeferred: []string{modNeedsHuman}}, + {name: "needs-human at 072 is deferred", labels: []string{"needs-human"}, kind: "pr", stage: stagelabels.ReturnedToContributor, wantShown: []string{}, wantDeferred: []string{modNeedsHuman}}, + {name: "needs-human at the gate shows", labels: []string{"needs-human"}, kind: "pr", stage: stagelabels.AwaitingMergeAdmission, wantShown: []string{modNeedsHuman}}, + {name: "needs-human at 085 shows", labels: []string{"needs-human"}, kind: "pr", stage: stagelabels.NeedsDecision, wantShown: []string{modNeedsHuman}}, + {name: "needs-decision at 050 is deferred", labels: []string{stagelabels.NeedsDecision.Label()}, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{}, wantDeferred: []string{modNeedsDecision}}, + {name: "hold at 050 shows", labels: []string{"hold"}, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{modHold}}, + {name: "draft at 050 shows", draft: true, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{modDraft}}, + {name: "stalled at 050 shows", labels: []string{stagelabels.StalledLabel}, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{modStalled}}, + {name: "unauthorized held runs at 072 shows", labels: []string{stagelabels.UnauthorizedLabel}, reason: heldRuns, kind: "pr", stage: stagelabels.ReturnedToContributor, wantShown: []string{modUnauthorized}}, + {name: "unauthorized held runs with approver suffix shows", labels: []string{stagelabels.UnauthorizedLabel}, reason: heldRuns + ":human-approved@pat", kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{modUnauthorized}}, + {name: "unauthorized merge 403 at 050 is deferred", labels: []string{stagelabels.UnauthorizedLabel}, reason: merge403, kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{}, wantDeferred: []string{modUnauthorized}}, + {name: "unauthorized merge 403 at the gate shows", labels: []string{stagelabels.UnauthorizedLabel}, reason: merge403, kind: "pr", stage: stagelabels.AwaitingMergeAdmission, wantShown: []string{modUnauthorized}}, + {name: "unauthorized without a step is deferred before the gate", labels: []string{stagelabels.UnauthorizedLabel}, reason: "contributor-lane:no-verdict", kind: "pr", stage: stagelabels.ReviewPending, wantShown: []string{}, wantDeferred: []string{modUnauthorized}}, + {name: "mixed row keeps order in both lists", labels: []string{"needs-human", "hold", stagelabels.UnauthorizedLabel, "needs-rebase"}, reason: merge403, kind: "pr", stage: stagelabels.Fixing, wantShown: []string{modHold, modNeedsRebase}, wantDeferred: []string{modUnauthorized, modNeedsHuman}}, + {name: "a PR with no stage yet is before the gate", labels: []string{"needs-human"}, kind: "pr", stage: stagelabels.None, wantShown: []string{}, wantDeferred: []string{modNeedsHuman}}, + {name: "an issue on its own stage keeps needs-human", labels: []string{"needs-human"}, kind: "issue", stage: stagelabels.Actionable, wantShown: []string{modNeedsHuman}}, + {name: "an issue at 045 keeps needs-human", labels: []string{"needs-human"}, kind: "issue", stage: stagelabels.IssueNeedsDecision, wantShown: []string{modNeedsHuman}}, + {name: "an issue riding its PR at 050 defers", labels: []string{"needs-human"}, kind: "issue", stage: stagelabels.ReviewPending, mirrored: true, wantShown: []string{}, wantDeferred: []string{modNeedsHuman}}, + {name: "an issue riding its PR at 085 shows", labels: []string{"needs-human"}, kind: "issue", stage: stagelabels.NeedsDecision, mirrored: true, wantShown: []string{modNeedsHuman}}, + } { + t.Run(tc.name, func(t *testing.T) { + shown, deferred := stageTrackerModifiers(tc.labels, "hv", stagelabels.Record{}, false, nil, now, tc.draft, tc.reason, tc.kind, tc.stage, tc.mirrored) + if !slices.Equal(shown, tc.wantShown) || !slices.Equal(deferred, tc.wantDeferred) { + t.Fatalf("shown %v deferred %v; want %v / %v", shown, deferred, tc.wantShown, tc.wantDeferred) + } + }) + } +} + +// The class table itself: which markers are actionable now and which wait +// for the gate, independent of the stage. +func TestStageTrackerClassifyModifiers(t *testing.T) { + heldRuns := prstage.StageReasonUnauthorizedPrefix + prstage.UnauthorizedStepApproveWorkflowRuns + rec := stagelabels.Record{Stage: stagelabels.ReviewPending, RegressedFrom: stagelabels.MergeQueue, EnteredAt: time.Now()} + got := stageTrackerClassifyModifiers([]string{"needs-human", stagelabels.NeedsDecision.Label(), "hold", stagelabels.UnauthorizedLabel, "needs-triage", stagelabels.PossiblyExisting.Label(), "needs-rebase", "blocked", stagelabels.StalledLabel}, "hv", rec, true, nil, time.Now(), true, heldRuns) + want := map[string]bool{ + modStalled: true, modRegressed: true, modHold: true, modUnauthorized: true, + modNeedsHuman: false, modNeedsDecision: false, + modNeedsTriage: true, modPossibleDupe: true, modNeedsRebase: true, modBlocked: true, modDraft: true, + } + if len(got) != len(want) { + t.Fatalf("classified %d modifiers, want %d: %+v", len(got), len(want), got) + } + for _, m := range got { + if actionable, ok := want[m.Name]; !ok || actionable != m.ActionableNow { + t.Fatalf("%s actionable_now = %v, want %v (known %v)", m.Name, m.ActionableNow, actionable, ok) + } + } + if got := stageTrackerClassifyModifiers([]string{stagelabels.UnauthorizedLabel}, "hv", stagelabels.Record{}, false, nil, time.Now(), false, prstage.StageReasonUnauthorizedPrefix+"update-branch"); len(got) != 1 || got[0].ActionableNow { + t.Fatalf("a merge-time unauthorized step must not be actionable now: %+v", got) + } + if !stageTrackerPillsDeferred("pr", stagelabels.Fixing.Number(), false) || stageTrackerPillsDeferred("pr", stagelabels.AwaitingMergeAdmission.Number(), false) || stageTrackerPillsDeferred("pr", stagelabels.ReadyForHumanMerge.Number(), false) { + t.Fatal("the gate band starts at stage/080") + } + if stageTrackerPillsDeferred("issue", stagelabels.Claimed.Number(), false) || !stageTrackerPillsDeferred("issue", stagelabels.ReviewPending.Number(), true) { + t.Fatal("issues defer only while riding a covering PR") + } +} + +// End to end through the payload: a PR at 050 wearing the sentinel label +// and needs-human draws no pill (both wait in deferred_modifiers, sentinel +// first) while sentinel_alert stays truthful; the same PR at 085 draws +// both; a PR at 050 held by hive:unauthorized on workflow runs keeps the +// pill, its step and its tooltip; a hold at 050 shows; and the nested +// sub-row under an issue mirrors the deferred list. +func TestStageTrackerDeferredPillsPayload(t *testing.T) { + now := time.Date(2026, 10, 27, 14, 0, 0, 0, time.UTC) + s, store := stageTrackerFixture(t, now) + heldRuns := prstage.StageReasonUnauthorizedPrefix + prstage.UnauthorizedStepApproveWorkflowRuns + store.Observe(stagelabels.Key("acme/console", 141), stagelabels.ReturnedToContributor, heldRuns) + store.Observe(stagelabels.Key("acme/console", 142), stagelabels.ReviewPending, prstage.StageReasonUnauthorizedPrefix+"merge") + s.statusMu.Lock() + s.status.Repos[0].OpenPrs = append(s.status.Repos[0].OpenPrs, + FrontendPR{PullRequest: github.PullRequest{Number: 140, Title: "In review, flagged", Author: "mallory", Labels: []string{"stage/050-review-pending", config.DefaultSentinelLabel, "needs-human"}}}, + FrontendPR{PullRequest: github.PullRequest{Number: 141, Title: "Runs held", Author: "pat", Labels: []string{"stage/072-returned-to-contributor", stagelabels.UnauthorizedLabel}}}, + FrontendPR{PullRequest: github.PullRequest{Number: 142, Title: "Merge refused", Author: "pat", Labels: []string{"stage/050-review-pending", stagelabels.UnauthorizedLabel}}}, + FrontendPR{PullRequest: github.PullRequest{Number: 143, Title: "Held in review", Author: "pat", Labels: []string{"stage/050-review-pending", "hold"}}}, + FrontendPR{PullRequest: github.PullRequest{Number: 144, Title: "At the gate, flagged", Author: "mallory", Labels: []string{"stage/085-needs-decision", config.DefaultSentinelLabel, "needs-human"}}}, + ) + s.status.Repos[0].ActionableIssues = append(s.status.Repos[0].ActionableIssues, + github.Issue{Number: 40, Title: "Covered by a flagged PR", Author: "pat", AuthorIsHuman: true, Labels: []string{"stage/050-review-pending"}, + LinkedPRs: []github.IssueLinkedPR{{Number: 140, State: "open"}}}, + ) + s.statusMu.Unlock() + resp := s.buildStageTracker(s.status, store, now) + + flagged := trackerItem(t, resp, "pr", 140) + if flagged.Stage != 50 || !flagged.SentinelAlert || len(flagged.Modifiers) != 0 || !slices.Equal(flagged.DeferredModifiers, []string{modSentinel, modNeedsHuman}) { + t.Fatalf("PR 140 = stage %d alert %v mods %v deferred %v", flagged.Stage, flagged.SentinelAlert, flagged.Modifiers, flagged.DeferredModifiers) + } + raw, err := json.Marshal(flagged) + if err != nil { + t.Fatal(err) + } + if !strings.Contains(string(raw), `"modifiers":[],"deferred_modifiers":["sentinel","needs-human"]`) || !strings.Contains(string(raw), `"sentinel_alert":true`) { + t.Fatalf("payload: %s", raw) + } + if held := trackerItem(t, resp, "pr", 141); held.Stage != 72 || !hasMod(held, modUnauthorized) || len(held.DeferredModifiers) != 0 || held.UnauthorizedStep != "approve workflow runs" || !strings.Contains(held.Unauthorized, "`actions: write`") { + t.Fatalf("PR 141 = stage %d mods %v deferred %v step %q", held.Stage, held.Modifiers, held.DeferredModifiers, held.UnauthorizedStep) + } + if refused := trackerItem(t, resp, "pr", 142); refused.Stage != 50 || hasMod(refused, modUnauthorized) || !slices.Equal(refused.DeferredModifiers, []string{modUnauthorized}) || refused.UnauthorizedStep != "merge" { + t.Fatalf("PR 142 = stage %d mods %v deferred %v step %q", refused.Stage, refused.Modifiers, refused.DeferredModifiers, refused.UnauthorizedStep) + } + if hold := trackerItem(t, resp, "pr", 143); !hasMod(hold, modHold) || len(hold.DeferredModifiers) != 0 { + t.Fatalf("PR 143 = mods %v deferred %v", hold.Modifiers, hold.DeferredModifiers) + } + if gate := trackerItem(t, resp, "pr", 144); gate.Stage != 85 || !gate.SentinelAlert || !hasMod(gate, modNeedsHuman) || len(gate.DeferredModifiers) != 0 { + t.Fatalf("PR 144 = stage %d alert %v mods %v deferred %v", gate.Stage, gate.SentinelAlert, gate.Modifiers, gate.DeferredModifiers) + } + issue := trackerItem(t, resp, "issue", 40) + k := slices.IndexFunc(issue.LinkedPRs, func(lp StageTrackerLinkedPR) bool { return lp.Number == 140 }) + if k < 0 || len(issue.LinkedPRs[k].Modifiers) != 0 || !slices.Equal(issue.LinkedPRs[k].DeferredModifiers, []string{modSentinel, modNeedsHuman}) { + t.Fatalf("issue 40 linked PRs = %+v", issue.LinkedPRs) + } + for _, m := range resp.Items { + if m.Kind == "issue" && len(m.DeferredModifiers) != 0 && !m.Mirrored { + t.Fatalf("issue #%d on its own stage must not defer pills: %+v", m.Number, m.DeferredModifiers) + } + } +} + +// The frontend honours the server's split: a row whose deferred_modifiers +// names sentinel draws no sentinel chip and no modifier pill, stays out of +// Needs attention and does not breathe red; its tooltip alone says what +// waits at the gate. The same row at the gate (nothing deferred) draws +// both as before. +func TestStageTrackerDeferredPillsJS(t *testing.T) { + html := indexHTML(t) + node, err := exec.LookPath("node") + if err != nil { + t.Skip("node not on PATH — deferred pills were NOT executed by this run") + } + script := strings.Join([]string{ + "const assert = require('assert');", + "var _stageTracker = { stages: [{ number: 50, short: 'CI / Review' }, { number: 85, short: 'Needs decision' }] };", + "function agentNowClockTime(ms, nowMs) { return 'T' + ms; }", + "function agentNowAgo(ms) { return ms + 'ms'; }", + "function esc(s) { return String(s).replace(/&/g, '&').replace(/needs human<'), stageTrackerChipsHtml(atGate)); +assert.ok(stageTrackerNeedsAttention(atGate)); +assert.ok(stageTrackerTooltip(atGate, Date.now()).includes(STAGE_TRACKER_SENTINEL_TIP)); +const gate80 = { kind: 'pr', stage: 80, modifiers: [], sentinel_alert: true, head: HEAD }; +assert.ok(stageTrackerChipsHtml(gate80).includes('ham-badge-sentinel'), 'sentinel chip at 080'); +// Actionable-now pills show wherever the row stands. +assert.ok(stageTrackerChipsHtml({ kind: 'pr', stage: 50, modifiers: ['hold'], deferred_modifiers: ['needs-human'] }).includes('>hold<')); +assert.ok(stageTrackerChipsHtml({ kind: 'pr', stage: 72, modifiers: ['unauthorized'], unauthorized: 'needs actions: write' }).includes('>unauthorized<')); +assert.ok(stageTrackerNeedsAttention({ kind: 'pr', stage: 50, modifiers: ['hold'], deferred_modifiers: ['needs-human'] })); +// A payload without the field (older server) renders exactly as before. +assert.ok(stageTrackerChipsHtml({ kind: 'pr', stage: 50, modifiers: ['needs-human'], sentinel_alert: true }).includes('ham-badge-sentinel')); +` + out, err := exec.Command(node, "-e", script).CombinedOutput() + if err != nil { + t.Fatalf("node: %v\n%s", err, out) + } + for _, want := range []string{ + `deferred_modifiers: lp.deferred_modifiers || []`, + `deferred_modifiers: lp.deferred_modifiers || item.deferred_modifiers || []`, + } { + if !strings.Contains(html, want) { + t.Fatalf("index.html lacks %q (sub-rows must carry the deferred list)", want) + } + } +} diff --git a/src/pkg/dashboard/stage_tracker_sentinel_lane_test.go b/src/pkg/dashboard/stage_tracker_sentinel_lane_test.go index 6be5240d70..8db8740e63 100644 --- a/src/pkg/dashboard/stage_tracker_sentinel_lane_test.go +++ b/src/pkg/dashboard/stage_tracker_sentinel_lane_test.go @@ -25,6 +25,8 @@ func stageTrackerSentinelJS(t *testing.T, html string) string { jsConstLine(t, html, "STAGE_TRACKER_SENTINEL_TIP"), jsConstLine(t, html, "STAGE_TRACKER_SENTINEL_TIP_FALLBACK"), jsConstLine(t, html, "STAGE_TRACKER_SHORT_SHA"), + jsConstLine(t, html, "STAGE_TRACKER_DEFERRED_NOTE"), + jsFunc(t, html, "stageTrackerDeferredMods"), jsFunc(t, html, "stageTrackerSentinelTip"), jsFunc(t, html, "stageTrackerSentinelInLane"), jsFunc(t, html, "stageTrackerSentinelChipHtml"), @@ -265,7 +267,7 @@ func TestStageTrackerSentinelLaneWiring(t *testing.T) { `message: preface + 'Post "/lgtm" and "/approve" on '`, `confirmLabel: 'Post /lgtm + /approve', danger: !!sentinel`, `label: preface + 'What should the hive change on '`, - `if (item.sentinel_alert) lines.push(stageTrackerSentinelTip(item));`, + `if (item.sentinel_alert && deferred.indexOf(STAGE_TRACKER_SENTINEL_CHIP) < 0) lines.push(stageTrackerSentinelTip(item));`, `sentinel_alert: !!lp.sentinel_alert, sentinel_reason: lp.sentinel_reason || '', head: lp.head || ''`, } { if !strings.Contains(html, want) { diff --git a/src/pkg/dashboard/stage_tracker_triage_modifier_test.go b/src/pkg/dashboard/stage_tracker_triage_modifier_test.go index 7c9701771c..4b44372b17 100644 --- a/src/pkg/dashboard/stage_tracker_triage_modifier_test.go +++ b/src/pkg/dashboard/stage_tracker_triage_modifier_test.go @@ -13,11 +13,11 @@ import ( // An issue still carrying needs-triage reports the needs-triage modifier so // the activity monitor's action chip can read "triage needed". func TestStageTrackerModifiers_NeedsTriage(t *testing.T) { - got := stageTrackerModifiers([]string{"needs-triage", "bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false) + got, _ := stageTrackerModifiers([]string{"needs-triage", "bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false, "", "issue", stagelabels.Actionable, false) if !slices.Equal(got, []string{modNeedsTriage}) { t.Fatalf("modifiers = %v, want [%s]", got, modNeedsTriage) } - if got := stageTrackerModifiers([]string{"bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false); len(got) != 0 { + if got, _ := stageTrackerModifiers([]string{"bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false, "", "issue", stagelabels.Actionable, false); len(got) != 0 { t.Fatalf("modifiers = %v, want none", got) } } diff --git a/src/pkg/dashboard/stage_tracker_unauthorized_test.go b/src/pkg/dashboard/stage_tracker_unauthorized_test.go index eb034c4403..b44913ccfc 100644 --- a/src/pkg/dashboard/stage_tracker_unauthorized_test.go +++ b/src/pkg/dashboard/stage_tracker_unauthorized_test.go @@ -17,11 +17,11 @@ import ( // hold: it rides the label, outranks the needs-* chips and counts under // Needs attention, since only a person can clear it. func TestStageTrackerModifiers_Unauthorized(t *testing.T) { - got := stageTrackerModifiers([]string{stagelabels.UnauthorizedLabel, "needs-human", "bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false) + got, _ := stageTrackerModifiers([]string{stagelabels.UnauthorizedLabel, "needs-human", "bug"}, "hv", stagelabels.Record{}, false, nil, time.Now(), false, "", "pr", stagelabels.NeedsDecision, false) if len(got) != 2 || got[0] != modUnauthorized || got[1] != modNeedsHuman { t.Fatalf("modifiers = %v, want [%s %s]", got, modUnauthorized, modNeedsHuman) } - if got := stageTrackerModifiers([]string{"hold", stagelabels.UnauthorizedLabel}, "hv", stagelabels.Record{}, false, nil, time.Now(), false); len(got) != 2 || got[0] != modHold || got[1] != modUnauthorized { + if got, _ := stageTrackerModifiers([]string{"hold", stagelabels.UnauthorizedLabel}, "hv", stagelabels.Record{}, false, nil, time.Now(), false, "", "pr", stagelabels.NeedsDecision, false); len(got) != 2 || got[0] != modHold || got[1] != modUnauthorized { t.Fatalf("hold (a human instruction) must lead: %v", got) } } diff --git a/src/pkg/dashboard/static/index.html b/src/pkg/dashboard/static/index.html index df56424e2d..c81e5bd0c2 100644 --- a/src/pkg/dashboard/static/index.html +++ b/src/pkg/dashboard/static/index.html @@ -7063,7 +7063,7 @@

Hive activity moni - + @@ -13855,6 +13855,15 @@

Where to get help

const STAGE_TRACKER_SENTINEL_CHIP = 'sentinel'; const STAGE_TRACKER_SENTINEL_TIP = 'Sentinel flagged security-relevant changes'; const STAGE_TRACKER_SENTINEL_TIP_FALLBACK = 'possible security override, privilege escalation or codebase damage — a maintainer must review before merge'; + // Merge-gate pills the server held back (payload deferred_modifiers: + // sentinel, needs-human, needs-decision, a merge-time unauthorized + // step) because the PR has not reached the gate yet: nothing a person + // does now moves the row, so no pill is drawn and the row stays out of + // "Needs attention"; the row tooltip alone names what waits at the gate. + const STAGE_TRACKER_DEFERRED_NOTE = 'Pending at merge gate: '; + function stageTrackerDeferredMods(item) { + return Array.isArray(item && item.deferred_modifiers) ? item.deferred_modifiers : []; + } const STAGE_TRACKER_SHORT_SHA = 7; var _stageTracker = null; var _stageTrackerSig = ''; @@ -14256,7 +14265,9 @@

Where to get help

if (mods.length) lines.push('Flags: ' + mods.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', ')); const stale = stageTrackerStaleLabelsText(item); if (stale) lines.push(stale); - if (item.sentinel_alert) lines.push(stageTrackerSentinelTip(item)); + const deferred = stageTrackerDeferredMods(item); + if (deferred.length) lines.push(STAGE_TRACKER_DEFERRED_NOTE + deferred.map(m => STAGE_TRACKER_MOD_TEXT[m] || m).join(', ')); + if (item.sentinel_alert && deferred.indexOf(STAGE_TRACKER_SENTINEL_CHIP) < 0) lines.push(stageTrackerSentinelTip(item)); const regressed = stageTrackerRegressionText(item, nowMs); if (regressed) lines.push(regressed.charAt(0).toUpperCase() + regressed.slice(1)); if (mods.indexOf('unauthorized') >= 0 && item.unauthorized) lines.push('Unauthorized: ' + item.unauthorized); @@ -14268,7 +14279,7 @@

Where to get help

// The sentinel chip: drawn in the chip area (beside needs rebase / // regressed) on every lane but the one whose word already says it. function stageTrackerSentinelChipHtml(item) { - if (!item || !item.sentinel_alert || stageTrackerSentinelInLane(item)) return ''; + if (!item || !item.sentinel_alert || stageTrackerSentinelInLane(item) || stageTrackerDeferredMods(item).indexOf(STAGE_TRACKER_SENTINEL_CHIP) >= 0) return ''; return `${esc(STAGE_TRACKER_SENTINEL_CHIP)}`; } @@ -14352,7 +14363,7 @@

Where to get help

// PR's full tooltip rides its link; the sub-row container has none. function stageTrackerSubRowHtml(lp, issue, stages, nowMs, ctx) { const pr = { repo: issue.repo, number: lp.number, kind: 'pr', title: lp.title || '', url: lp.url || '', author: lp.author || '', author_kind: lp.author_kind || '', - stage: lp.stage || 0, stage_since: lp.stage_since || '', modifiers: lp.modifiers || [], caption: lp.caption || '', reason: lp.reason || '', + stage: lp.stage || 0, stage_since: lp.stage_since || '', modifiers: lp.modifiers || [], deferred_modifiers: lp.deferred_modifiers || [], caption: lp.caption || '', reason: lp.reason || '', human_approver: lp.human_approver || '', manual_merge: !!lp.manual_merge, human_merge_reason: lp.human_merge_reason || '', human_merge_reason_text: lp.human_merge_reason_text || '', sentinel_alert: !!lp.sentinel_alert, sentinel_reason: lp.sentinel_reason || '', head: lp.head || '' }; let ref = stageTrackerPRRef(pr.number, pr.url, pr.author_kind, pr.author, pr.title, (pr.title ? pr.title + ' · ' : '') + stageTrackerTooltip(pr, nowMs) + ' · ' + stageTrackerLinkedTip(issue, pr.number, ctx)); if (lp.base_ref) ref += ` ${esc(lp.base_ref)}`; @@ -14532,7 +14543,7 @@

Where to get help

const lp = linked[0]; const who = (lp.author_kind || 'hive') + (lp.author ? ' · @' + lp.author : ''); prRefs = [STAGE_TRACKER_LINKED_GLYPH + stageTrackerPRRef(lp.number, lp.url, lp.author_kind || '', lp.author, lp.title, (lp.title ? lp.title + '\n' : '') + 'Author: ' + who + ' · ' + stageTrackerLinkedTip(item, lp.number, ctx)) + (lp.base_ref ? ` ${esc(lp.base_ref)}` : '')]; - shown = Object.assign({}, item, { via_pr: true, stage: lp.stage || 40, stage_since: lp.stage_since || item.stage_since, modifiers: lp.modifiers || item.modifiers, caption: lp.caption || item.caption, reason: lp.reason || item.reason, + shown = Object.assign({}, item, { via_pr: true, stage: lp.stage || 40, stage_since: lp.stage_since || item.stage_since, modifiers: lp.modifiers || item.modifiers, deferred_modifiers: lp.deferred_modifiers || item.deferred_modifiers || [], caption: lp.caption || item.caption, reason: lp.reason || item.reason, human_approver: lp.human_approver || '', manual_merge: !!lp.manual_merge, human_merge_reason: lp.human_merge_reason || '', human_merge_reason_text: lp.human_merge_reason_text || '', sentinel_alert: !!lp.sentinel_alert, sentinel_reason: lp.sentinel_reason || '', head: lp.head || '' }); } else if (linked.length) { // Several covering PRs: the issue strip ends at Claimed, all passed @@ -15820,7 +15831,7 @@

All labels

const parked = it => (Array.isArray(it.modifiers) ? it.modifiers : []).indexOf('needs-decision') >= 0 || STAGE_TRACKER_DECISION_STAGES.indexOf(Number(it.stage) || 0) >= 0; if (item.kind === 'pr') return parked(item) ? item : null; for (const lp of (Array.isArray(item.linked_prs) ? item.linked_prs : [])) { - const pr = { repo: item.repo, number: lp.number, kind: 'pr', title: lp.title || '', url: lp.url || '', stage: lp.stage || 0, modifiers: lp.modifiers || [], author: lp.author || '', + const pr = { repo: item.repo, number: lp.number, kind: 'pr', title: lp.title || '', url: lp.url || '', stage: lp.stage || 0, modifiers: lp.modifiers || [], deferred_modifiers: lp.deferred_modifiers || [], author: lp.author || '', human_approver: lp.human_approver || '', manual_merge: !!lp.manual_merge, human_merge_reason: lp.human_merge_reason || '', human_merge_reason_text: lp.human_merge_reason_text || '', sentinel_alert: !!lp.sentinel_alert, sentinel_reason: lp.sentinel_reason || '', head: lp.head || '' }; if (parked(pr)) return pr; }