Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/added-waiting-on-you.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The dashboard now tells the operator when work is parked on a human: `/api/stage-tracker` carries `waiting_on_human` (`count`, `items[{repo, number, type, kind, since, who}]`; kinds `needs-decision`, `ready-for-human-merge`, `approve-needed`, `returned-to-contributor-offline`, `other-human-wait`) and each item `waiting_on_you` / `wait_kind`. A second, orange **Hive activity monitor** sidebar badge and a **Waiting on you · N** topbar pill (hidden at zero) show the count; both, `?filter=waiting-on-you` and the new **Waiting on you** toolbar chip narrow the activity monitor to those rows; a debounced in-app toast (one per ten minutes, none in kiosk mode) fires when the count rises. Hold, advisories, decided rows and contributors still inside their grace are not counted.
11 changes: 11 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -799,13 +799,24 @@ The header reports the filtered row count and how many need attention; paginatio

**The counter beside the section name.** The left-menu counter and the header lead (`37 rows (33 issues + 4 PRs on their own row) · 3 need attention`) count *rows* of the default view, not items: every open issue is a row; a pull request is its own row only when it is not drawn under a listed issue. The Overview counter (`33/13`) prints the same open set as issues/PRs, so the two differ by exactly the pull requests that share their issue's row (`9 PRs shown on their issue's row` in the tooltip). The header and tooltip also name the PRs sharing issue rows. Filters and the kind tabs narrow the list and the `showing X–Y of N` line, never the counter.

### How you'll know something is waiting on you

The hive often parks work on a person: a decision asked at **045** / **085**, a PR at **090** ready for a human merge, an approval the hive's GitHub App cannot give (`needs-human`, `unauthorized`), or a contributor who has gone offline past their grace so the operator is the fallback. Those waits used to look like any other row ("PR in progress"); nothing added them up and nothing said so. Three surfaces now read one server block, `/api/stage-tracker` → `waiting_on_human` (`count`, `items[{repo, number, type, kind, since, who}]`), so a human wait is never silent:

- **Sidebar.** A second, orange badge on **Hive activity monitor** carries the waiting-on-you count (the grey badge stays the row count). Its tooltip lists the five longest waits with what each needs and how long it has waited. Hidden at zero.
- **Topbar.** A **Waiting on you · N** pill sits beside **Health**, hidden at zero. Click it to land on the activity monitor with the **Waiting on you** filter applied; `?filter=waiting-on-you` on the dashboard URL does the same (for links from chat or a notification).
- **Toast.** When the count rises between two polls, one in-app toast says **N items need your decision — #15312, #15433 …** with a **Show** action that applies the filter. At most one toast per ten minutes; none in kiosk mode.

`kind` is one of `needs-decision` (045 / 085 or the `needs-decision` modifier), `ready-for-human-merge` (090), `approve-needed` (`needs-human` / `unauthorized`), `returned-to-contributor-offline` (071 / 072 once the author's grace has elapsed — `who` is then the contributor, the operator being their fallback), `other-human-wait` (015 triage). `who` is `operator` for everything the signed-in operator / maintainers must do themselves. Rows on **hold**, advisories, decided rows and PRs nested under a listed issue are not counted: hold is the operator's own choice, an advisory asks for nothing, and a decided row is the hive's to act on next. Each item also carries `waiting_on_you` / `wait_kind`, which is what the **Waiting on you** toolbar chip filters on.

### Filters, sorting and pagination

Filters run on the cached browser payload and persist across reloads, except the page number:

- Kind, **Repo**, **Author** kind and search (`#number`, number or title substring, including covering PRs).
- **Since**: any, over one hour/day/week on the current step, or past that stage's configured dwell. Stalled items always qualify.
- **Needs attention**: drawn health modifiers or a human-gated stage. Deferred merge-gate pills do not qualify; a handled regression alone does not qualify.
- **Waiting on you**: only rows the server flagged `waiting_on_you` (see *How you'll know something is waiting on you* above).
- Synthetic **Needs human** / **On hold** facets and label chips, described below. Stage labels sort numerically, then other labels alphabetically, case-insensitively. Chips within one family OR; families AND; synthetic facets AND with label chips.

**+N more** opens *All labels*, with every label and count, type-to-filter, toggles and **Clear**. Selected labels are promoted into the visible row. **Clear filters** appears whenever the view is narrowed.
Expand Down
11 changes: 11 additions & 0 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,10 @@ type StageTrackerResponse struct {
// filter cannot disagree.
NeedsHuman int `json:"needs_human"`
OnHold int `json:"on_hold"`
// WaitingOnHuman lists the items parked on the operator / maintainers
// (stage_tracker_waiting.go): the sidebar badge, topbar pill and
// toast read it so a human wait is never silent.
WaitingOnHuman StageTrackerWaitingOnHuman `json:"waiting_on_human"`
// Engine is the ADR-0025 central stage engine's mode and counters for
// the tracker's status strip; absent when the hive has no engine.
Engine *stageengine.Status `json:"engine,omitempty"`
Expand Down Expand Up @@ -327,6 +331,12 @@ type StageTrackerItem struct {
// OnHold is true when the item wears a hold pill: paused on purpose,
// waiting on nobody.
OnHold bool `json:"on_hold,omitempty"`
// WaitingOnYou is true when the item is parked on the signed-in
// operator / maintainers (stage_tracker_waiting.go); WaitKind names
// why (needs-decision, ready-for-human-merge, approve-needed,
// returned-to-contributor-offline, other-human-wait).
WaitingOnYou bool `json:"waiting_on_you,omitempty"`
WaitKind string `json:"wait_kind,omitempty"`
// Hold says who set the `hold` label and why, when the stage-label
// pass could read it (hivecommons/hive#15020): the pill then reads
// "Held by hive · reporter trust (issue #N by @X, contributor)" or
Expand Down Expand Up @@ -2441,6 +2451,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
applyRebaseAttempts(resp.Items)
s.applyRebaseMergeFollowThrough(resp.Items, now)
resp.NeedsHuman, resp.OnHold = stageTrackerHumanCounts(resp.Items)
resp.WaitingOnHuman = stageTrackerWaitingOnHuman(resp.Items)
stageTrackerResolveLinkedPRs(resp.Items, prOpen)
stageTrackerMarkClosedBy(resp.Items, s.mergedLedger().ClosedBy)
stageTrackerResolveActors(resp.Items)
Expand Down
10 changes: 10 additions & 0 deletions src/pkg/dashboard/stage_tracker_ui_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,16 @@ func TestStageTrackerSectionWiring(t *testing.T) {
`.ham-select {`,
`.ham-repo-filter {`,
`id="activity-monitor-sidebar-badge"`,
// Waiting-on-you surfacing (hivecommons/hive#15638): second sidebar
// badge, topbar pill, toolbar chip and the filter key they share.
`id="activity-monitor-waiting-badge" class="badge-count oc-nav-count oc-nav-count--waiting" data-zero`,
`id="oc-waiting-on-you" data-action="showWaitingOnYou"`,
`id="activity-monitor-waiting" data-action="hamFilter" data-arg0="waitingOnYou" data-arg1="toggle"`,
`if (f.waitingOnYou && !item.waiting_on_you) return false;`,
`function stageTrackerRenderWaiting(d, nowMs)`,
`function stageTrackerWaitingToast(w, nowMs)`,
`if (typeof window.hiveKioskMode === 'function' && window.hiveKioskMode()) return;`,
`const STAGE_TRACKER_WAITING_FILTER_PARAM = 'waiting-on-you';`,
`'activity-monitor-section': { title: '📍 Hive activity monitor'`,
`'activity-monitor-section': { heading: 'Hive activity monitor'`,
`'activity-monitor-section', 'agents-section', 'agent-activity-section', 'faq-section'`,
Expand Down
164 changes: 164 additions & 0 deletions src/pkg/dashboard/stage_tracker_waiting.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
package dashboard

import (
"slices"
"sort"
"time"

"github.com/hivecommons/hive/pkg/stagelabels"
)

// Waiting-on-you aggregation (hivecommons/hive#15638): the stage tracker
// payload names every open item that is parked on the signed-in operator
// (or any maintainer) so the SPA can wear a second sidebar badge, a topbar
// pill and fire a toast. Before this the operator learned that a dozen
// PRs had sat at 085 needs-decision for 3–21 hours only by reading each
// row. The aggregation reuses the per-item fields the tracker already
// computes (Stage, Modifiers, DecisionNeeded, Adoption, Takeover, Decided,
// Advisory) and invents no new state.

// Wait kinds carried in StageTrackerWaitingItem.Kind and
// StageTrackerItem.WaitKind.
const (
// waitKindNeedsDecision: 085 PR needs-decision / 045 issue
// needs-decision, or the needs-decision modifier.
waitKindNeedsDecision = "needs-decision"
// waitKindReadyForHumanMerge: 090, a trusted human must press merge.
waitKindReadyForHumanMerge = "ready-for-human-merge"
// waitKindReturnedOffline: 071 / 072 with the contributor offline past
// the grace, so the operator is the fallback (adopt / reroute).
waitKindReturnedOffline = "returned-to-contributor-offline"
// waitKindApproveNeeded: needs-human or unauthorized — the hive's App
// lacks the permission or a lane rule wants a human approval.
waitKindApproveNeeded = "approve-needed"
// waitKindOther: any other stage only a person can advance (015
// triage-needed).
waitKindOther = "other-human-wait"
)

// waitWhoOperator is the Who value for a wait that falls to the signed-in
// operator / maintainers rather than a named contributor.
const waitWhoOperator = "operator"

// StageTrackerWaitingOnHuman is the payload header's waiting_on_human block.
type StageTrackerWaitingOnHuman struct {
// Count is len(Items): the number the badges show.
Count int `json:"count"`
// Items lists the waits, longest waiting first.
Items []StageTrackerWaitingItem `json:"items"`
}

// StageTrackerWaitingItem is one item parked on the operator.
type StageTrackerWaitingItem struct {
Repo string `json:"repo"`
Number int `json:"number"`
// Type is pr or issue.
Type string `json:"type"`
// Kind is one of the waitKind* constants.
Kind string `json:"kind"`
// Since is when the wait began: the decision's asked time when one is
// recorded, else when the item entered its stage.
Since *time.Time `json:"since,omitempty"`
// Who is the login the wait is attributed to: "operator" for the
// signed-in operator / maintainers, else the contributor whose
// offline grace ran out (the operator is their fallback).
Who string `json:"who"`
}

// stageTrackerReturnedStages are the stages where the row waits on its
// author; the operator only inherits the wait once the author is offline
// past the grace.
var stageTrackerReturnedStages = []int{stagelabels.NeedsAuthor.Number(), stagelabels.ReturnedToContributor.Number()}

// stageTrackerWaitKind classifies the human wait on it, "" when the item
// waits on nobody the operator is answerable for. Hold, advisories and
// already-decided rows never count: hold is the operator's own choice,
// an advisory asks for nothing, and a decided row is the hive's to act
// on next.
func stageTrackerWaitKind(it StageTrackerItem) (kind, who string) {
if stageTrackerOnHold(it) || it.Advisory != nil || it.Decided != nil {
return "", ""
}
switch {
case it.Stage == stagelabels.NeedsDecision.Number(), it.Stage == stagelabels.IssueNeedsDecision.Number(), slices.Contains(it.Modifiers, modNeedsDecision):
return waitKindNeedsDecision, waitWhoOperator
case it.Stage == stagelabels.ReadyForHumanMerge.Number():
return waitKindReadyForHumanMerge, waitWhoOperator
case slices.Contains(it.Modifiers, modNeedsHuman), slices.Contains(it.Modifiers, modUnauthorized):
return waitKindApproveNeeded, waitWhoOperator
case slices.Contains(stageTrackerReturnedStages, it.Stage):
if !stageTrackerContributorGraceElapsed(it) {
return "", ""
}
who := it.Author
if it.Adoption != nil && it.Adoption.Author != "" {
who = it.Adoption.Author
}
if who == "" {
who = waitWhoOperator
}
return waitKindReturnedOffline, who
case it.Stage == stagelabels.TriageNeeded.Number():
return waitKindOther, waitWhoOperator
}
return "", ""
}

// stageTrackerContributorGraceElapsed reports whether a row returned to
// its contributor has outlived their grace, so the operator is now the
// one the hive waits on (adopt / reroute / nudge by hand).
func stageTrackerContributorGraceElapsed(it StageTrackerItem) bool {
if it.Takeover != nil && (it.Takeover.GraceElapsed || it.Takeover.AdoptNow) {
return true
}
if it.Adoption != nil && it.Adoption.Due {
return true
}
return it.Presence != nil && it.Presence.Next == presenceNextAdopt
}

// stageTrackerWaitSince is when the wait on it began.
func stageTrackerWaitSince(it StageTrackerItem) *time.Time {
if it.DecisionNeeded != nil && it.DecisionNeeded.Since != nil {
return it.DecisionNeeded.Since
}
if it.Presence != nil && it.Presence.Since != nil {
return it.Presence.Since
}
return it.StageSince
}

// stageTrackerWaitingOnHuman flags every item parked on the operator
// (WaitingOnYou / WaitKind) and returns the header block, longest wait
// first. Nested rows (an issue's covering PR drawn under it) are skipped
// so one decision is counted once.
func stageTrackerWaitingOnHuman(items []StageTrackerItem) StageTrackerWaitingOnHuman {
out := StageTrackerWaitingOnHuman{Items: []StageTrackerWaitingItem{}}
for i := range items {
it := &items[i]
it.WaitingOnYou, it.WaitKind = false, ""
if it.NestedUnder != 0 {
continue
}
kind, who := stageTrackerWaitKind(*it)
if kind == "" {
continue
}
it.WaitingOnYou, it.WaitKind = true, kind
out.Items = append(out.Items, StageTrackerWaitingItem{Repo: it.Repo, Number: it.Number, Type: it.Kind, Kind: kind, Since: stageTrackerWaitSince(*it), Who: who})
}
sort.SliceStable(out.Items, func(a, b int) bool {
sa, sb := out.Items[a].Since, out.Items[b].Since
switch {
case sa == nil && sb == nil:
return false
case sa == nil:
return false
case sb == nil:
return true
}
return sa.Before(*sb)
})
out.Count = len(out.Items)
return out
}
Loading
Loading