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/fixed-tracker-human-reason.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Explain exact-head human requirements separately from optional delegation and neutral ownership without inferring human presence, preserve covering-PR reasons and genuine current actions, reconcile old-head push requests and observed same-head CI retries, and keep pending head validation and requested review changes in CI/Review rather than implying approval or preparation admits a ready merge-queue seat.
48 changes: 43 additions & 5 deletions src/docs/dashboard-sections/activity-monitor.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,48 @@ Part of [Dashboard sections explained](../dashboard-sections.md); see that page

A progress strip per open issue and pull request showing which step of the pipeline it is on and who must act next.

Human requirements have visible **Needs human: …** text inside the corresponding
row, with the actual PR number, requester and next mover when known. This is
separate from its pipeline stage: a covered issue can still read **PR in
progress** while a specific linked PR asks a person to act. Multiple-PR trees
identify the asking PR rather than placing its siblings on hold; a PR drawn
under another issue names that host. A missing reason explicitly says **Human
decision required; reason unavailable** and links to the item.

The person glyph is reserved for an exact-current requirement. Claim ownership
and ordinary author work instead have explicit **Claimed by** / **Next move**
context; **Let hive decide** can be an optional delegation action, not a status
indicator. These lines do not change stages, sorting, reference-versus-closing
links, preparation train styling, native queues, or live notes' tuck/reopen
controls. Cleared decisions and mismatching PR heads lose the requirement.
An operator's recorded approval is not a review verdict: current-head review
changes requested remain the visible blocker and keep the author/rework stage.
The tracker records the approval separately rather than claiming that the merge
queue will take the PR. Approval on an earlier head is historical, not permission
or current review proof for a new head.
When the PR's new head satisfies a recorded old-head author-push request, the
backend reconciles push/rework observations before building the row: its pill,
actor and caption return to pending CI/re-review instead of still asking for a
push. An independently evaluated author action on the new head remains visible.
If the head is known but its push time is not, no push age is invented.
When the current-head snapshot observes real checks running again without any
failing checks, an old CI-only push request becomes **checks pending · no new push
requested**. This is not a push or merge-readiness proof; independent review,
conflict and sign-off requirements still stand.
Adoption ownership policy is not a PR rejection: the chip distinguishes
**author-owned**, **maintainer-owned** and **contributor-managed** from an actual
**adoption blocked** capability. No adoption observation means no adoption chip.
Operator admission never promises that outstanding review/CI findings are clear.
Human availability is unknown: agent heartbeats do not prove that a person is
online or offline. Observed push/comment and waiting timestamps remain action
history, not presence evidence or an implied relinquishment of ownership.
Explicit adoption actions/provenance remain visible; a returning human does not
silently revoke an adoption.

### First use: find the next action

1. Find an item by repository, number or title. Every open issue and PR in the watched repositories is represented, including held, draft, filtered, exempt and reporter-triage work. Being visible does not make it actionable.
2. Read the lit step and its words, then the reason on the item's `#N` link or lit chevron. The word says where the work is; the actor icon says whose move it is.
2. Read the lit step and the visible human/actor context beneath it. The word says where the work is; **Needs human** names the actual requirement, while **Next move** and **Claimed by** distinguish ordinary actor/claim ownership. Links and chevrons retain further detail.
3. Use **🙋 Needs human** for work waiting on a person's action. Use **⏸ On hold** separately for work a maintainer deliberately paused. Neither filter grants permission to act.
4. Open **⋯** (or right-click / Shift+F10) for the actions allowed in that state. Read the confirmation and the result toast; a queued decision is not proof the PR merged.

Expand Down Expand Up @@ -276,13 +314,13 @@ A copy that then fails (closed unmerged, or red at two heads) reopens the origin

#### Presence indicator on the waiting-on pill

Every PR row that waits on a named person — `stage/071-needs-author`, `stage/072-returned-to-contributor` (before and after the nudge), `stage/017-possibly-existing` on a PR — carries `presence{login, state: online|offline|unknown, kind: clanker|human, since, last_seen, next: wait|adopt, adopt_at}`, read from the contributor hub's live presence (registered profile + relay heartbeat: the same lookup adoption consults, so the indicator and the adoption text never disagree) and projected through adoption's own clock ([hivecommons/hive#15051](https://github.com/hivecommons/hive/issues/15051)). The pill draws it just before the `@login`: a filled **dot** (`--cue-decision`, a soft breathe; none under `prefers-reduced-motion`) when the person's contributor agent is online, tooltip "@Danathar's clanker: online, last seen 2 min ago — hive is waiting for them"; a filled **square** (`--status-error`) when it is offline, "@hanthor's clanker: offline 26h — hive will adopt at 15:10 (in 38m)" (or "— hive is waiting for them" when `ask`/`never`/adoption-off holds the clock); a **hollow ring** when no contributor agent is registered here, "@zoe: no clanker registered — waiting for a human reply" with the pill reading `waiting on @zoe (human · no clanker)`.
Every PR row that waits on a named person — `stage/071-needs-author`, `stage/072-returned-to-contributor` (before and after the nudge), `stage/017-possibly-existing` on a PR — carries `presence{login, state: online|offline|unknown, kind: clanker|human, since, last_seen, next: wait|adopt, adopt_at}` ([hivecommons/hive#15051](https://github.com/hivecommons/hive/issues/15051)). For a contributor agent, presence comes from the contributor hub's profile/relay heartbeat and uses the same adoption clock: a filled **dot** (`--cue-decision`, a soft breathe; none under `prefers-reduced-motion`) for an online clanker, a filled **square** (`--status-error`) for an offline clanker, and a **hollow ring** when that clanker is not registered here. These are agent states, never human availability. A human author carries only the person glyph and `unknown`: "Waiting on @zoe (human) — human availability is unknown; waiting for a human reply". No agent heartbeat, elapsed response time or GitHub activity becomes a human online/offline indicator or an implied ownership transfer.

Shape, not colour alone, carries the state; the indicator has its own `aria-label` ("@hanthor: clanker offline — hive will adopt at …"). A row with presence but no adoption line (071, a 072 not yet nudged, a human's PR) gets a muted `waiting on @login` pill carrying the indicator; a nudged 072 row keeps its single amber adoption pill with the indicator inside it. The Needs-human popover shows the same line under the question when the waiting person is named, a per-PR sub-row under an issue mirrors it, and the row tooltip adds a `Presence:` line.

It refreshes with the tracker like every other pill.

**An offline clanker's PR that has not been returned.** A clanker-authored PR the engine has not classified yet (the chevron reads `PR in progress · @odttlnt's clanker`) carries the same `presence` for its author, with `next: wait` and no `adopt_at` — the adoption clock runs only at 072. When the clanker is offline (or not registered here) the chevron's holder gains a muted suffix with the state square: `PR in progress · @odttlnt's clanker · ■ offline 3h`, and the caption states the next automatic step: "@odttlnt's clanker is offline 3h; a green PR is reviewed and merged without its author — hive adopts it only once it is returned (red CI, conflicts or review asks) and nothing is pushed for 15m" (`governor.labels.stage.adoption.after_offline`). A green PR does not need its author online: review and merge admission run on the contributor lane regardless; adoption is the exit for a PR that is red, conflicting or asked to change while its clanker is away, never for a green one, and never for a human's PR.
**An offline clanker's PR that has not been returned.** A clanker-authored PR the engine has not classified yet (the chevron reads `PR in progress · @odttlnt's clanker`) carries the same agent `presence`, with `next: wait` and no `adopt_at` — the automatic clock runs only at 072. When the clanker is offline (or not registered here) the chevron's holder gains a muted suffix with the state square: `PR in progress · @odttlnt's clanker · ■ offline 3h`, and the caption states the next automatic step: "@odttlnt's clanker is offline 3h; a green PR is reviewed and merged without its author — hive adopts it only once it is returned (red CI, conflicts or review asks) and nothing is pushed for 15m" (`governor.labels.stage.adoption.after_offline`). This automatic clanker projection does not infer a human's availability or an adoption request. Explicit adoption actions and provenance are separate; a returning human's activity does not silently undo an adoption.

A contributor PR whose `stage/*` labels the write-back gate kept off GitHub (no opt-in label, see [What hive writes to GitHub, and when](../operator-reference.md#what-hive-writes-to-github-and-when)) is tracked from the engine's record alone: the record carries `labels_suppressed` and the tracker trusts its stage (085 reads *Needs human decision*, not *PR in progress*) even though the item's labels say nothing. Until this fix the tracker read the missing park label as a lifted park and dropped the record, so a dozen fork PRs parked at 085 for a human's decision sat under "PR in progress · @x's clanker" for hours while their clankers were offline.

Expand Down Expand Up @@ -511,9 +549,9 @@ Every PR at the gate now carries `merge_gate: {state, reason, sweep_running, las
| 100 merge queue | **Merging** | — | ⟳ (static) — *Admitted and soaked; hive is merging it now (GitHub merge queue / merge window).* |
| any stage while hive's merge call is in flight (`merge_gate.merging_since`, `merge_path`) | **Merging** | *merge call in flight*, then *merge landed* while the SPA holds the row | ⟳ (static) — *hive is merging it now (automerge sweep) — the merge call has been in flight since 3s ago.* |
| any stage after GitHub refused hive's merge call (`merge_gate.state: merge-failed`, `merge_failed`, `merge_failed_kind`, `merge_failed_text`, `merge_failed_at`) | **Merge failed** | the refusal translated to a short phrase — *branch protection*, *needs rebase*, *not allowed*, *review required*, or *retrying* while the sweep is on it; never GitHub's raw text | 🕓 clock — *hive tried to merge this (maintainer merge from the dashboard) 9s ago and GitHub refused — branch protection blocks it. The lane re-evaluates it on its next pass. Details: 405 Pull Request is not mergeable* |
| any stage after the merge call drew *N of M required status checks are expected* (`merge_failed_kind: checks-pending`, `merge_failed_checks`) | **Waiting for CI** | *4 checks* | ⟳ while the sweep is on it, else 🕓 — *hive tried to merge this (automerge sweep) 1m ago before its required checks had reported — 4 required checks haven't finished. It merges once they pass.* |
| a queue/gate stage after the merge call drew *N of M required status checks are expected* (`merge_failed_kind: checks-pending`, `merge_failed_checks`) | **Waiting for CI** | *4 checks* | ⟳ while the sweep is on it, else 🕓 — *hive tried to merge this (automerge sweep) 1m ago before its required checks had reported — 4 required checks haven't finished. It merges once they pass.* |

A merge outcome (**Merging**, **Merge failed**, **Waiting for CI**) lights the **Merge queue** column, whatever numeric stage the lane fell back to (hivecommons/docs#512 drew "Merge failed" in CI / Review because the PR sat at 060) — unless the PR is under repair. The chevron column follows the **current** state, never the highest stage the row once reached: a PR at 070 fixing, 071 needs-author, 072 returned-to-contributor, 074 adopted-by-hive or with a red required check lights **CI / Review** even while a stale `merge_gate` (`merge-failed` from the attempt that found the conflict) or a planner-ordered `merge_train` still rides on the record (hive's own #15574 read *Fixing · conflicting* under Merge queue with the caption *fell back to Fixing — … — conflicting*; the maintainer: "why is this in merge queue if it is being fixed?"). The "fell back to …" caption keeps the history; the column follows the fallback. One predicate decides both — `stageTrackerTrainUnderRepair` (Go, `stageTrackerItemColumn`) and `stageTrackerUnderRepair` (SPA, `stageTrackerAnchor`) — so train membership and column can never disagree; the 085 decision park is the one exception that rides no train yet stays at the gate, where the person decides.
A live merge call or actual queue-stage refusal lights the **Merge queue** column. A premature merge call refused for pending PR-head checks does **not** admit a PR still at 050/060: it remains **CI / Review**, and the earlier refusal is retained as history rather than current CI proof. A preparation ticket does not change that placement; forge-owned queue entries and synthetic candidate validation remain separate observations. The chevron column follows the **current** state, never the highest stage the row once reached: a PR at 070 fixing, 071 needs-author, 072 returned-to-contributor, 074 adopted-by-hive or with a red required check lights **CI / Review** even while a stale `merge_gate` (`merge-failed` from the attempt that found the conflict) or a planner-ordered `merge_train` still rides on the record (hive's own #15574 read *Fixing · conflicting* under Merge queue with the caption *fell back to Fixing — … — conflicting*; the maintainer: "why is this in merge queue if it is being fixed?"). The "fell back to …" caption keeps the history; the column follows the fallback. Go's `stageTrackerItemColumn` and the SPA's `stageTrackerAnchor` apply the same precedence; the 085 decision park is the exception that rides no train yet stays at the gate, where the person decides.

A refusal is scoped to the head it failed on. Once the PR head moves (merge-from-base, a new push) or the record falls back below 080 to wait on CI (`required-check-pending:*`) after the refusal, the chevron reads the live stage word (**CI running · build-and-test**, **Review pending**) and the refusal survives only in the hover — *merge attempt on previous head 92d4cef failed: branch protection* (`merge_gate.prior_head_merge_failed`, `prior_head_merge_failed_kind`, `prior_head_merge_failed_text`, `prior_head_merge_failed_at`, `prior_head_merge_failed_head`). The chevron and the caption never disagree about whether a merge is failing now ([#15611](https://github.com/hivecommons/hive/issues/15611); hive#15574 read "Merge failed · branch protection" over a caption waiting on CI for the new head).
| 110 | **Merged** (the ✓ cap) | — | — |
Expand Down
6 changes: 3 additions & 3 deletions src/pkg/dashboard/api_repo_item_takeover_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -338,7 +338,7 @@ func TestStageTrackerTakeoverQueuedAfterAdoptNow(t *testing.T) {
store.NoteAdmission(key, "feed", stagelabels.OperatorApprovalAdmission("andan02"), now.Add(-10*time.Minute))
store.NoteAdoptionBlocked(key, "feed", stagelabels.AdoptBlockedOperatorAdmission, now.Add(-9*time.Minute))
it := trackerItem(t, s.buildStageTracker(status, store, now), "pr", 14524)
if it.Adoption == nil || it.Adoption.BlockedBy != stagelabels.AdoptBlockedOperatorAdmission || !strings.Contains(it.Adoption.Text, "a maintainer approved this head") || it.Takeover == nil || !it.Takeover.AdoptNow {
if it.Adoption == nil || it.Adoption.BlockedBy != stagelabels.AdoptBlockedOperatorAdmission || !strings.Contains(it.Adoption.Text, "operator approval recorded for this head; existing review/CI requirements still apply") || it.Takeover == nil || !it.Takeover.AdoptNow {
t.Fatalf("precondition (approved, blocked, Adopt now offered): adoption=%+v takeover=%+v", it.Adoption, it.Takeover)
}

Expand All @@ -354,8 +354,8 @@ func TestStageTrackerTakeoverQueuedAfterAdoptNow(t *testing.T) {
if it.DecisionNeeded != nil {
t.Fatalf("queued adoption still asks a person: %+v", it.DecisionNeeded)
}
if strings.Contains(it.Caption, "not adopted") {
t.Fatalf("caption still says not adopted: %q", it.Caption)
if strings.Contains(it.Caption, "not adopted") || strings.Contains(it.Caption, "contributor-managed") {
t.Fatalf("explicit queued adoption still shows the prior ownership-only state: %q", it.Caption)
}
for _, o := range takeoverDecisionOptions(tk, false) {
if o.Action == decisionActionAdoptNow {
Expand Down
27 changes: 17 additions & 10 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -362,6 +362,9 @@ type StageTrackerItem struct {
// stalled, a handled regression, blocked-on-pr, 040 covered or a PR
// ready for auto-merge — the hive advances those (hivecommons/hive#15008).
NeedsHuman bool `json:"needs_human,omitempty"`
// HumanAttention is the current item's actionable human requirement,
// separate from an actor/claimant icon or optional delegation action.
HumanAttention *StageTrackerHumanAttention `json:"human_attention,omitempty"`
// OnHold is true when the item wears a hold pill: paused on purpose,
// waiting on nobody.
OnHold bool `json:"on_hold,omitempty"`
Expand Down Expand Up @@ -413,6 +416,9 @@ type StageTrackerItem struct {
// says — a header read "8 PRs" over seven seats because a red 090
// row was counted.
ciRed bool
// ciChecking is a real check observed running on this snapshot's head
// with no failing checks, not a pending reviewer or meta check.
ciChecking bool
// SentinelAlert is true on a PR the suspicious-activity sentinel flagged:
// it wears the configured alert label (sentinel.label, default
// sentinel-alert) or the review evidence bundle for its current head
Expand Down Expand Up @@ -667,16 +673,17 @@ type StageTrackerLinkedIssue struct {

// StageTrackerLinkedPR is one covering PR nested under an issue row.
type StageTrackerLinkedPR struct {
Preparation *StageTrackerPreparation `json:"preparation,omitempty"`
BaseRef string `json:"base_ref,omitempty"`
Number int `json:"number"`
Title string `json:"title,omitempty"`
URL string `json:"url,omitempty"`
Author string `json:"author,omitempty"`
AuthorKind string `json:"author_kind,omitempty"`
Stage int `json:"stage,omitempty"`
StageSince *time.Time `json:"stage_since,omitempty"`
Caption string `json:"caption,omitempty"`
HumanAttention *StageTrackerHumanAttention `json:"human_attention,omitempty"`
Preparation *StageTrackerPreparation `json:"preparation,omitempty"`
BaseRef string `json:"base_ref,omitempty"`
Number int `json:"number"`
Title string `json:"title,omitempty"`
URL string `json:"url,omitempty"`
Author string `json:"author,omitempty"`
AuthorKind string `json:"author_kind,omitempty"`
Stage int `json:"stage,omitempty"`
StageSince *time.Time `json:"stage_since,omitempty"`
Caption string `json:"caption,omitempty"`
// NoteChangedAt mirrors the PR row's: when the caption last changed
// meaning.
NoteChangedAt *time.Time `json:"note_changed_at,omitempty"`
Expand Down
Loading
Loading