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-15051-presence-indicator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Activity Monitor: the waiting-on pill carries a presence indicator for the person the hive waits on ([#15051](https://github.com/hivecommons/hive/issues/15051)) — a filled dot when their clanker is online (the hive waits), a filled square when it is offline (adoption is next; the tooltip says when: "@hanthor's clanker: offline 26h — hive will adopt at 15:10 (in 38m)"), a hollow ring when no clanker is registered ("waiting for a human reply"). Every PR row waiting on a named person (071 / 072 / 017) now carries `presence{login, state, kind, since, last_seen, next, adopt_at}` from the same hub lookup and clock adoption uses; the Needs-human popover and per-PR sub-rows show the same indicator. Shape, not colour alone, carries the state; nothing moves under `prefers-reduced-motion`.
2 changes: 2 additions & 0 deletions src/docs/dashboard-sections.md
Original file line number Diff line number Diff line change
Expand Up @@ -684,6 +684,8 @@ Fed by `GET /api/stage-tracker`. Every issue and pull request follows the same p

**Adopted → #N (074 / 085).** An adopted pull request names the hive's superseding copy in its detour word (`adopted_by`). When that copy was closed without merging (hivecommons/hive#15052) the row does not fall back to *Needs human decision*: `adopted_by_state: "closed"` renders "Adopted → #N (closed) · recovering" while the hive opens a fresh copy from the same head, and the caption says so in plain words; once the new copy is on record the word reads "Adopted → #M". If two copies are closed within an hour the hive stops (`adopted_by_state: "closed-twice"`, park reason `adoption-child-closed-twice`): the row reads "Adopted → #N (closed twice) · needs a person" and the popover question asks you to reopen the last copy, give direction, or close the PR.

**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 clanker — their connected 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 clanker is registered here, "@zoe: no clanker registered — waiting for a human reply" with the pill reading `waiting on @zoe (human · no clanker)`. 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.

**Blocked pill.** An issue wearing `blocked` because the hive parked it on a pull request — its body carries `<!-- hive:blocked-on pr=owner/repo#N -->` (the review backlog's spin-off issues, `hive-open-issue comment --blocked-on-pr`) — names that PR: the payload carries `blocked_on_pr: {repo, number, url, state}`, the pill reads `blocked on #N` and links to the PR, its tooltip says `Blocked on PR owner/repo#N (open) — lifts when it merges; re-triage if closed unmerged`, the caption reads `Blocked on PR #N — lifts when it merges` instead of `No stage recorded yet`, and the row's title and chevron tooltip carry the blocker too ([#14952](https://github.com/hivecommons/hive/issues/14952): #14863 showed a bare grey pill and "blocked · since 7h" with nothing to say what it waited on). The state (`open`, `merged`, `closed`, or absent when nothing knows) comes only from what the hive already holds — the status snapshot's open PRs, the ForgeState cache, the recent-merge ring — never a GitHub call from the tracker build; a merged or closed-unmerged blocker says so (`merged; the blocked sweep lifts the label next` / `closed unmerged; the blocked sweep re-triages it next`). The server reads the marker from the issue body when it has one, else from the enumeration's `blocked on owner/repo#N` reason, so sidelined rows (which carry only the reason) name it too. A `blocked` issue with neither (a human-applied label) keeps the bare pill. This is distinct from `blocked_on`, the open GitHub "blocked by" dependencies of a sequenced sub-issue ([#14765](https://github.com/hivecommons/hive/issues/14765)); when a row has both, the chevron tooltip lists them together.

**New row (`000-new`, the pre-stage state).** Every open issue and pull request in `project.repos` is on the list from the moment GitHub reports it — there is no gap between "opened" and "the hive has an opinion about it" ([#15094](https://github.com/hivecommons/hive/issues/15094)). The `issues.opened` / `pull_request.opened` webhook re-read inserts the item into the status payload straight away (`insertFrontendRepoItem`; the governor side keeps the same row in its cached snapshot so a republish does not drop it), the per-item replay re-applies that insert after a governor republish, and the enumeration poll is the fallback for a missed delivery. Until something places the item — a stage record, a `stage/*` label, a hold, a blocked marker, a bucket other than *reporter triage* / *unclassified* — the row is anchored in the **Open** column with the lit chevron reading **New** (`ham-open-new`, blue ✦ rather than amber) and a caption that names who moves it next and when: `New · waiting for the stage-label pass (→ 010 actionable), then the scanner (next pass in 7m)` for an issue the reporter gate has already admitted, `New · waiting for a maintainer's triage (add `triage/accepted`); the hive's next pass in 7m` for a human contributor's issue the reporter-trust gate is still holding (the label names come from `issues.filter.reporter_trust.untrusted_require_labels`), and `New · waiting for the stage-label pass (→ 050 review pending)` for a pull request. The *since* time is the item's `created_at`; "next pass" is the governor's next kick (`governor.nextKickAt`, so it counts down with the Governor tile and reads *due now* once it has passed). The payload carries it all as `new{since, next_mover (maintainer|hive), next_mover_text, next_pass_at, next_pass_in_seconds, gates[], text}`; the chevron tooltip lists the gates ahead — **triage** (the reporter gate: done when admitted, next when a triage label is still needed), **actionable** (the stage-label pass marks it 010), **claimed** (the scanner claims it, 020) — each marked ✓ done, → next or · later, and the row's actor icon reads *human* while the next mover is a maintainer and *hive* otherwise. A row that already wears a hold, `blocked`, a draft marker or any stage record is never *New*; neither is an issue at `015` once the stage-label pass has written it.
Expand Down
15 changes: 15 additions & 0 deletions src/docs/labels-and-control-signals.md
Original file line number Diff line number Diff line change
Expand Up @@ -925,6 +925,21 @@ When a clanker-authored contributor PR goes red the hive does not just relabel i
never adopt, and release an existing adoption of a maintainer's head.
Under every setting a human-authored PR (no `author/clanker`) is never
adopted.
The activity monitor shows the same presence the adoption rules read, so
the operator can anticipate the next move ([hivecommons/hive#15051](https://github.com/hivecommons/hive/issues/15051)):
every PR row waiting on a named person (071, 072, 017) carries
`presence{login, state, kind, since, last_seen, next, adopt_at}` and
its waiting-on pill an indicator before the `@login` — a filled **dot**
when the author's clanker is online (`next: wait`: the hive waits for
them through the online grace), a filled **square** when it is offline
(`next: adopt`; `adopt_at` is the projection of the rule below, and the
tooltip reads "@hanthor's clanker: offline 26h — hive will adopt at
15:10 (in 38m)"), a **hollow ring** when no clanker is registered here
(a human's PR: "no clanker registered — waiting for a human reply", pill
`waiting on @zoe (human · no clanker)`; another hive's PR: the
unregistered clock). A held adoption (`ask` / `never`, or
`adoption.enabled: false`) keeps `next: wait` with no `adopt_at`, so the
indicator never promises an adoption the pill text denies.
- `reason=contributor-offline` — the author has a contributor profile
here and no relay heartbeat within `governor.labels.stage.presence_window`:
adopted `governor.labels.stage.adoption.after_offline` (default 15m)
Expand Down
12 changes: 12 additions & 0 deletions src/pkg/dashboard/stage_tracker.go
Original file line number Diff line number Diff line change
Expand Up @@ -412,6 +412,11 @@ type StageTrackerItem struct {
// line the row shows instead of a bare "Returned to contributor"
// (hivecommons/hive#14524).
Adoption *StageTrackerAdoption `json:"adoption,omitempty"`
// Presence is, on a PR row waiting on a named person, whether that
// person's clanker is online / offline / not registered here and the
// hive's likely next move (wait or adopt, with the adopt-at time), so
// the waiting-on pill can carry an indicator (hivecommons/hive#15051).
Presence *StageTrackerPresence `json:"presence,omitempty"`
// ClaimantKind is the author kind of whoever holds the live claim on a
// claimed issue (human / clanker / hive), from the worker-claim ledger.
ClaimantKind string `json:"claimant_kind,omitempty"`
Expand Down Expand Up @@ -531,6 +536,8 @@ type StageTrackerLinkedPR struct {
// parent shows a compact "↳ #N · under #M" reference instead of a
// second identical row (hivecommons/hive#14921 drew twice).
DrawnUnder int `json:"drawn_under,omitempty"`
// Presence mirrors the nested PR's own row field (hivecommons/hive#15051).
Presence *StageTrackerPresence `json:"presence,omitempty"`
}

// StageTrackerHold is the row's hold provenance (stagelabels.HoldProvenance
Expand Down Expand Up @@ -1690,6 +1697,7 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
presence, maintainerPolicy := s.stageTrackerPresence(), s.stageTrackerMaintainerPolicy()
sweep := s.stageTrackerSweepState()
workers := stageTrackerWorkersFromStatus(status)
adoptionClock := s.stageTrackerAdoptionClock()
finish := func(it *StageTrackerItem, labels []string, stage stagelabels.Stage, rec stagelabels.Record, hasRec bool, draft bool) {
// "Needs human decision" is read from the item's current labels, not
// a store record that outlived them: once the park label is gone
Expand Down Expand Up @@ -1761,6 +1769,9 @@ func (s *Server) buildStageTracker(status *StatusPayload, store *stagelabels.Sto
it.Caption = stageTrackerAdoptionCaption(it.Caption, it.Adoption)
}
}
if login := stageTrackerWaitingOn(*it, stage); login != "" {
it.Presence = stageTrackerPresenceFor(*it, login, stage, rec, hasRec, presence, adoptionClock, now)
}
base, approver := stagelabels.HumanApprovedReason(it.Reason)
it.HumanApprover = approver
it.ManualMerge = stageTrackerManualMergeReason(base)
Expand Down Expand Up @@ -2677,6 +2688,7 @@ func stageTrackerResolveLinkedPRs(items []StageTrackerItem) {
lp.StageSince, lp.Caption = pr.StageSince, pr.Caption
lp.SentinelAlert, lp.SentinelReason, lp.Head = pr.SentinelAlert, pr.SentinelReason, pr.Head
lp.Adoption = pr.Adoption
lp.Presence = pr.Presence
lp.HumanApprover, lp.ManualMerge = pr.HumanApprover, pr.ManualMerge
lp.HumanMergeReason, lp.HumanMergeReasonText = pr.HumanMergeReason, pr.HumanMergeReasonText
lp.BaseRef = pr.BaseRef
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/stage_tracker_adoption_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -284,6 +284,7 @@ func TestStageTrackerAdoptionJS(t *testing.T) {
jsFunc(t, html, "stageTrackerAdoptOffered"),
jsFunc(t, html, "stageTrackerAdoptionChipText"),
jsFunc(t, html, "stageTrackerAdoptionChipHtml"),
stageTrackerPresenceJS(t, html),
`
const ask = { kind: 'pr', repo: 'hivecommons/hive', number: 14524, stage: 72, stage_label: 'stage/072-returned-to-contributor', author: 'hanthor', labels: [],
adoption: { author: 'hanthor', due: true, blocked_by: 'author-is-maintainer', nudges: 2, author_online: false, author_maintainer: true, policy: 'ask', action: 'decide:adopt', text: 'waiting on @hanthor (maintainer, offline 26h) — adopt?' } };
Expand Down
189 changes: 189 additions & 0 deletions src/pkg/dashboard/stage_tracker_presence.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,189 @@
package dashboard

import (
"strings"
"time"

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

// Presence on a waiting-on row (hivecommons/hive#15051): when a PR row
// waits on a named person (071 Needs author, 072 Returned to contributor,
// 017 Possibly existing on a PR), the operator wants to know whether that
// person's clanker — their connected contributor agent — is there to
// answer, because that decides the hive's next move: a connected clanker
// means the hive waits; a disconnected one means adoption is the likely
// next move and the row can say when; no registered clanker means a human
// has to reply. The lookup is the one the adoption engine consults
// (automerge.ContributorPresenceSource via stageTrackerPresence) and the
// adopt-at clock follows automerge.adoptionDue's rules, so the indicator
// never contradicts the adoption text on the same row.

// Presence states and kinds on the wire.
const (
presenceStateOnline = "online"
presenceStateOffline = "offline"
presenceStateUnknown = "unknown"

presenceKindClanker = "clanker"
presenceKindHuman = "human"

presenceNextWait = "wait"
presenceNextAdopt = "adopt"
)

// StageTrackerPresence is the `presence` field of a row that waits on a
// person.
type StageTrackerPresence struct {
// Login is the GitHub login the row waits on.
Login string `json:"login"`
// State is online / offline (a registered clanker, by its heartbeat)
// or unknown (no clanker registered here for this login).
State string `json:"state"`
// Kind is clanker when a contributor clanker is registered for the
// login or the PR was authored by one, else human.
Kind string `json:"kind"`
// Since is when the wait on this person began: the first nudge when
// one went out, else when the row entered its stage.
Since *time.Time `json:"since,omitempty"`
// LastSeen is the clanker's freshest heartbeat (absent when never seen).
LastSeen *time.Time `json:"last_seen,omitempty"`
// Next is the hive's likely next move: wait (for the person) or adopt
// (the adoption clock is running on a disconnected or unregistered
// clanker and nothing holds it).
Next string `json:"next"`
// AdoptAt is when the adoption engine would judge adoption due at the
// current head, when its clock is running (072, nudged, not held).
AdoptAt *time.Time `json:"adopt_at,omitempty"`
}

// stageTrackerAdoptionClock is the slice of governor.labels.stage the
// adopt-at projection needs, mirroring what cmd/hive hands the adoption
// engine as automerge.StageLabelPolicy.
type stageTrackerAdoptionClock struct {
Enabled bool
GraceOnline time.Duration
AdoptAfterOffline time.Duration
AdoptAfterUnregistered time.Duration
}

func (s *Server) stageTrackerAdoptionClock() stageTrackerAdoptionClock {
var stage config.StageLabelsConfig
if s != nil && s.deps != nil && s.deps.Config != nil {
stage = s.deps.Config.Governor.Labels.Stage
}
return stageTrackerAdoptionClock{
Enabled: stage.Adoption.IsEnabled(),
GraceOnline: stage.EffectiveContributorGraceOnline(),
AdoptAfterOffline: stage.Adoption.EffectiveAfterOffline(),
AdoptAfterUnregistered: stage.Adoption.EffectiveAfterUnregistered(),
}
}

// stageTrackerWaitingOn names the person a PR row waits on: its author at
// the stages whose caption says "@author must act". "" when the row waits
// on the hive, a gate or an unnamed maintainer.
func stageTrackerWaitingOn(it StageTrackerItem, stage stagelabels.Stage) string {
if it.Kind != "pr" || strings.TrimSpace(it.Author) == "" {
return ""
}
switch stage {
case stagelabels.NeedsAuthor, stagelabels.ReturnedToContributor, stagelabels.PossiblyExisting:
return strings.TrimSpace(it.Author)
}
return ""
}

// stageTrackerPresenceFor builds the `presence` field for a row waiting on
// login. presence is the live lookup (nil when the server has none: the
// state is then unknown); rec is the row's stage record for the nudge
// clock; clock is the adoption timing policy.
func stageTrackerPresenceFor(it StageTrackerItem, login string, stage stagelabels.Stage, rec stagelabels.Record, hasRec bool, presence func(string) (automerge.ContributorPresence, bool), clock stageTrackerAdoptionClock, now time.Time) *StageTrackerPresence {
if login == "" {
return nil
}
out := &StageTrackerPresence{Login: login, State: presenceStateUnknown, Kind: presenceKindHuman, Next: presenceNextWait}
var p automerge.ContributorPresence
if presence != nil {
if got, ok := presence(login); ok {
p = got
}
}
switch {
case p.Registered && p.Online:
out.State, out.Kind = presenceStateOnline, presenceKindClanker
case p.Registered:
out.State, out.Kind = presenceStateOffline, presenceKindClanker
case it.AuthorKind != "" && it.AuthorKind != authorKindHuman:
// A clanker's PR whose author has no profile here: another hive
// posted it. Adoption treats it as unregistered.
out.Kind = presenceKindClanker
}
if !p.LastSeen.IsZero() {
t := p.LastSeen
out.LastSeen = &t
}
start := time.Time{}
if hasRec && rec.NudgeCount > 0 && !rec.NudgeStart().IsZero() {
start = rec.NudgeStart()
} else if it.StageSince != nil {
start = *it.StageSince
}
if !start.IsZero() {
t := start
out.Since = &t
}
// The adoption clock runs only where adoption itself does: a nudged
// clanker PR at 072 whose head has not moved since the nudge, not yet
// adopted, with nothing holding it.
if stage != stagelabels.ReturnedToContributor || !clock.Enabled || it.AuthorKind == authorKindHuman || out.Kind != presenceKindClanker {
return out
}
if !hasRec || rec.NudgeCount == 0 || rec.NudgeStart().IsZero() {
return out
}
head := it.Head
if head == "" {
head = rec.NudgeHead
}
if rec.NudgeHead != "" && head != rec.NudgeHead {
return out
}
if rec.AdoptedHead != "" && (rec.Adopted(head) || rec.AdoptedInPlace()) {
return out
}
if rec.AdoptionBlocked(head) != "" {
// Held (maintainer_policy ask / never): the adoption text says so;
// the engine will not adopt on its own.
return out
}
nudged := rec.NudgeStart()
var at time.Time
switch out.State {
case presenceStateOnline:
// Mirrors adoptionDue: an online clanker keeps the online grace; the
// hive waits for it meanwhile.
at = nudged.Add(orDefault(clock.GraceOnline, config.DefaultContributorGraceOnline))
case presenceStateOffline:
since := nudged
if p.LastSeen.After(since) {
since = p.LastSeen
}
at = since.Add(orDefault(clock.AdoptAfterOffline, config.DefaultAdoptAfterOffline))
out.Next = presenceNextAdopt
default:
at = nudged.Add(orDefault(clock.AdoptAfterUnregistered, config.DefaultAdoptAfterUnregistered))
out.Next = presenceNextAdopt
}
out.AdoptAt = &at
return out
}

func orDefault(d, def time.Duration) time.Duration {
if d <= 0 {
return def
}
return d
}
Loading
Loading