Skip to content

✨ Activity Monitor: needs-human popover says what to decide and offers the actions - #14995

Merged
hivecommons-hive[bot] merged 2 commits into
v5from
feat/needs-human-decision-popover
Oct 28, 2026
Merged

hivecommons-hive[bot] merged 2 commits into
v5from
feat/needs-human-decision-popover

Conversation

@clubanderson

Copy link
Copy Markdown
Member

Fixes #14994

Part (a) of the owner's three-cue plan for the Activity Monitor (b = in-flight chevron / toasts / live event line, c = ✓ decision trail, #14992).

Owner request (verbatim)

When I hover over 'Needs human' on an issue or PR, the hover text should show WHAT decision I need to make. Then offer me 'Let hive decide' or the other actions that can apply to advance the item.

This is the hardest part of my job now — I look at these and want to take some action, but I need to know what my options are (surface them from the comments on the PR). […] Throughout the activity monitor we need visual cues to let people know (a) what the current state is, (b) if work is happening in the current state, (c) what decisions were made by the human and hive to affect the state.

Hive is doing the right things mostly; we now need to keep the user informed of it — like a video game they can watch and see what happens easily.

This has to be exceedingly clear, easy to read, and concise.

Don't change the tracker to LOOK like the Frogger video game — but the feedback to the user is important. Make it professional and enterprise-acceptable.

Before / after

Before — the chevron word only carries a native title with the stage name and reason slug:

Before: hovering Needs human decision shows a native tooltip with the stage name and a reason slug

After — hover or focus opens an in-app popover: the question → the blocker → the actions (Let hive decide first; disabled ones greyed with the reason) → who asked, when:

After: a popover under the chevron with the reviewer's question, the plain-words blocker, action buttons, and Asked by a reviewer · 3h ago

What changed

Payload — GET /api/stage-tracker rows parked on a person (PR at Needs human decision or with the needs-decision modifier, issue at Needs human direction or Needs triage, any row with the needs-human pill) carry:

"decision_needed": {
  "question":       "Should we merge the docs-only change or wait for the API rename?",
  "asked_by":       "a reviewer",
  "since":          "2026-10-28T14:02:11Z",
  "blocker":        "The hive will not merge until a person decides.",
  "blocker_reason": "reviewer-requires-human",
  "options": [
    {"action": "decide:delegate",         "label": "Let hive decide",     "enabled": true},
    {"action": "decide:approve",          "label": "Approve",             "enabled": true},
    {"action": "decide:direction",        "label": "Give direction",      "enabled": true},
    {"action": "decide:close-superseded", "label": "Close as superseded", "enabled": true},
    {"action": "decide:close-wontfix",    "label": "Close as won't fix",  "enabled": true},
    {"action": "hold",                    "label": "Hold",                "enabled": true}
  ]
}
  • question is the reviewer's own decision question when the verdict record (review-verdicts.json, matched by repo / number / head) has one — the same text the hive's Needs a decision comment prints after "reviewer question:". Otherwise a plain-words sentence for the park reason.
  • options[].action are the row context menu's own ids, so the popover, the menu and the (b) helper runRowAction(action,row) share one vocabulary; the client intersects server enabled with the menu's own stageTrackerRowActions so a button is never offered the menu would refuse.
  • blocker_reason keeps the raw token for machines; operator copy never shows it.
  • Mirrored onto the issue's linked_prs[] entry.

UI — button.ham-decision-trigger replaces the native title on the chevron word / lead pill. Hover opens (250 ms leave grace, re-checks :hover across re-renders), click or focus pins; Esc (refocuses trigger), click-away, scroll and resize close. role=dialog, aria-label="Decision needed on repo#N". Positioned/clamped with stageTrackerMenuPosition. Buttons call runRowAction when present, else stageTrackerDoAction — so (b)'s toast and in-flight chevron apply unchanged. Tiny shared tracker-cues token block (--cue-state, --cue-work, --cue-decision) for the three PRs to compose; no new blinking — the row still has at most the state pill, the work spin and the decision badge.

Tests — TestStageTrackerDecisionNeeded (reviewer question quoted; requires_human fallback; sentinel; changes requested disables Approve; adoption stalled; unauthorized; held; issue 045; triage 015; needs-human pill; plain rows nil; jargon scan), TestStageTrackerVerdictLookup, node renderer tests for popover content/order/escaping, option narrowing, trigger attributes and runRowAction vs stageTrackerDoAction wiring. Style ratchet, no-native-dialog and tooltip scanners pass.

Docs — dashboard-sections.md (popover + cue tokens), api-reference.md (decision_needed, citations script clean), changelog fragment.

Strings (cue → text)

Cue Text
Question — reviewer asked one the reviewer's own question, verbatim
Question — reviewer handed off, no question A reviewer handed this PR to a person without a specific question. Merge it as is, give direction, or close it?
Question — security check The security check flagged <reason> on <sha>. Accept it as is, give direction, or close it?
Question — changes requested A reviewer requested changes on <sha>. Give direction for a new commit, or close it?
Question — hive took over, stuck The hive took this PR over but could not move it (it edits CI workflow files). Give direction, or close it?
Question — lane rule The hive never merges this by itself (it touches files a person must merge). Approve it for a maintainer to merge, give direction, or close it?
Question — fork CI CI will not run for this fork PR (…). A maintainer must push the branch to this repo — or close it?
Question — issue, needs direction The hive parked this issue for a person. Approve the direction, send it back with direction, or close it?
Question — issue, triage Should the hive work on this issue? Accept triage so an agent can take it, hold it, or mark it needs-human.
Question — needs-human pill This PR is marked needs-human: automated fixes ran out, or a person flagged it. Review it on GitHub and remove the label when the hive may continue.
Blocker — changes requested A reviewer requested changes on <sha> — needs a new commit. Approving cannot override that.
Blocker — security check The security check has an open alert. The hive will not merge until a person removes the <label> label.
Blocker — lane rule The hive never merges this by itself. After approval, a maintainer merges.
Blocker — fork CI Neither the author nor the hive can make CI run for this fork PR.
Blocker — reviewer deferred The hive will not merge until a person decides.
Blocker — issue direction No agent picks this up until a person answers. The hive's question is in its latest comment on the issue.
Blocker — triage No agent picks up an issue until a maintainer accepts triage.
Blocker — needs-human The hive does nothing with a needs-human item until a person removes the label.
Blocker — held (appended) On hold — the hive does nothing until the hold is released.
Buttons Let hive decide · Approve · Approve direction · Give direction · Send back · Close as superseded · Close as won't fix · Accept triage · Hold · Release hold · Mark needs-human
Disabled reasons On hold — release the hold first · Only a person with the permission can do this · Approving does not grant the missing permission · (the changes-requested blocker)
Asked by a reviewer · the security check · the hive · GitHub permissions · triage · the needs-human label
Meta line Asked by a reviewer · 3h ago
Dialog name Decision needed on owner/repo#123

Plain-word slugs: contributor-lane:workflow-path → "it edits CI workflow files"; tests-removed → "it removes tests"; no-reviewer → "no reviewer is configured for this repo"; reporter-trust-hold → "the author's trust level is not yet known"; human-merge-path → "it touches files a person must merge"; merge-refused:review → "GitHub requires a review the hive cannot give"; merge-refused:method → "GitHub refused the hive's merge method".

3-second pass — each string was read as a new maintainer: no stage codes, no slugs, no "lane/sentinel/clanker"; every button is one verb; the order is the same everywhere (waiting on → can do → who/when).

Follow-ups / coordination

  • The reviewer's question comes from the verdict record the comment is rendered from; the PR snapshot carries no comment bodies, so reading a hand-edited Needs a decision comment live is a follow-up.
  • runRowAction is typeof-guarded — when the (b) PR lands the popover picks it up without a change; the decision_needed fields are additive beside ✨ Activity monitor: decision badge shows what you chose and what hive did next #14992's last_operator_action.

Requested by @clubanderson.

@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 28, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#15011 🐛 Close superseded hive PRs automatically and re-stage adopted originals out of the merge gate same files src/pkg/dashboard/static/index.html
#15003 ✨ feature: show Activity Monitor operator decision trails same files src/pkg/dashboard/static/index.html
#15013 🐛 dashboard: Needs human chip counts only human-gated rows; Refs-only PRs address, not cover, an issue same files src/docs/dashboard-sections.md
src/pkg/dashboard/stage_tracker.go
src/pkg/dashboard/static/index.html
#15014 ✨ Activity Monitor: live row feedback — confirm opt-out, result toasts, working cue, event line, merge celebration CONFLICT src/pkg/dashboard/static/index.html
#15004 ✨ feature: persist Activity Monitor operator actions same files src/docs/api-reference.md
src/pkg/dashboard/stage_tracker.go
src/pkg/dashboard/static/index.html
#14992 ✨ Activity monitor: decision badge shows what you chose and what hive did next CONFLICT src/pkg/dashboard/stage_tracker.go
src/pkg/dashboard/static/index.html
#14987 ✨ review: gate PR reviews on an approval label (review.require_labels) same files src/docs/dashboard-sections.md
src/pkg/dashboard/static/index.html
#14807 ✨ dashboard: stream Job pod logs in the terminal pane for sandbox.runtime: job agents same files src/docs/api-reference.md
src/pkg/dashboard/static/index.html
#14524 ✨ feat(hub,agent): Hub-coordinated live CLI session pool for multi-tenant runner capacity same files src/docs/api-reference.md

…s the actions

Hovering or focusing the 'Needs human decision' chevron word or a lead
needs-human / triage-needed pill opens an in-app popover: what the row
waits on (the reviewer's own question when the verdict record has one,
else the park reason in plain words, plus the blocker), the applicable
actions as buttons (Let hive decide first) down the row context menu's
code path, and who asked, when. GET /api/stage-tracker rows carry
decision_needed {question, asked_by, since, blocker, blocker_reason,
options[]} under the context menu's action ids; mirrored onto
linked_prs[].

Requested by @clubanderson.

Fixes #14994

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson
clubanderson force-pushed the feat/needs-human-decision-popover branch from a048e0b to 375ffa1 Compare October 28, 2026 16:35
@kubestellar-prow kubestellar-prow Bot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 28, 2026
@github-actions github-actions Bot added the conflicts-with-open-pr Open PR has a merge conflict with another open PR label Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@clubanderson is auto-promoted for contributor-lane merging on this PR: the last 5 merged PRs by this author in this hive's repositories have no revert or sentinel-alert evidence. CI, reviewer verdict, diff fences, soak, holds and branch protection still apply.

@hivecommons-hive hivecommons-hive Bot added role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head and removed stage/071-needs-author Human-authored PR: CI red, changes requested or conflicting; diagnosis posted, the author must act labels Oct 28, 2026
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@hivecommons-hive
hivecommons-hive Bot merged commit e30f9f4 into v5 Oct 28, 2026
78 of 80 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the feat/needs-human-decision-popover branch October 28, 2026 16:55
@hivecommons-hive

Copy link
Copy Markdown
Contributor
Evidence bundle `#14995cf65b6b` sha256:26a6e6b9d91609eebf5f686772bfee5737fd38e074cc1f2dbc4e5965c57d2cb7 — download from the dashboard or `hivectl review evidence #14995`.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at cf65b6b.

@github-actions

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/human A person pushed this PR themselves conflicts-with-open-pr Open PR has a merge conflict with another open PR dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Activity Monitor: hovering 'Needs human' should say what to decide and offer the actions

1 participant