diff --git a/changelog.d/added-contributor-abandoned-status.md b/changelog.d/added-contributor-abandoned-status.md new file mode 100644 index 0000000000..c330a64a88 --- /dev/null +++ b/changelog.d/added-contributor-abandoned-status.md @@ -0,0 +1 @@ +- Show abandoned PR counts and recent-adoption tooltips on Contributors cards, and expose historical totals and per-login counts in `/api/status.contributorPool`. diff --git a/dashboard/openapi.json b/dashboard/openapi.json index c7a0757390..6e45967174 100644 --- a/dashboard/openapi.json +++ b/dashboard/openapi.json @@ -1323,6 +1323,30 @@ "hiveId": { "type": "string" }, + "contributorPool": { + "type": "object", + "description": "Registered contributor pool; historical counts include offline and revoked profiles.", + "properties": { + "active": { "type": "integer" }, + "online": { "type": "integer" }, + "registered": { "type": "integer" }, + "presence_window": { "type": "string" }, + "by_role": { + "type": "object", + "additionalProperties": { "type": "integer" } + }, + "abandoned": { + "type": "integer", + "description": "Sum of persisted per-profile abandoned PR counters, deduped per PR by the adoption recorder." + }, + "abandoned_by_login": { + "type": "object", + "description": "Abandoned counts keyed by lowercase GitHub login, including zero counts; empty object for an empty registry.", + "additionalProperties": { "type": "integer" } + } + }, + "required": ["active", "online", "registered", "presence_window", "abandoned", "abandoned_by_login"] + }, "governor": { "type": "object", "description": "dashboard.FrontendGovernor (src/pkg/dashboard/server.go), built by buildGovernor (status_builder.go).", diff --git a/src/docs/api-reference/contribute.md b/src/docs/api-reference/contribute.md index d663fe449f..e69f2b1b33 100644 --- a/src/docs/api-reference/contribute.md +++ b/src/docs/api-reference/contribute.md @@ -5,50 +5,50 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | Method | Path | Auth | Purpose | Source | |---|---|---|---|---| -| `GET` | `/contribute` | Public | Contribute Landing | `pkg/dashboard/api_contribute.go:165` | -| `GET` | `/contribute/{tab}` | Public | Contribute Landing | `pkg/dashboard/api_contribute.go:171` | -| `GET` | `/api/contribute/ws` | Public | s.contribute Hub.Handle WS | `pkg/dashboard/api_contribute.go:179` | -| `POST` | `/api/contribute/register` | Public | Contribute Register | `pkg/dashboard/api_contribute.go:180` | -| `POST` | `/api/contribute/invite` | Public | Contribute Invite | `pkg/dashboard/api_contribute.go:186` | -| `POST` | `/api/contribute/reissue-token` | Public | Contribute Reissue Token | `pkg/dashboard/api_contribute.go:187` | -| `GET` | `/api/contribute/status` | Public | Contribute Status | `pkg/dashboard/api_contribute.go:189` | -| `GET` | `/api/contribute/repositories` | Public | Contribution-eligible repositories for a contributor `repo_scope`: `{repositories:[{id,forge,host,full_name}],generated_at}`, the monitored repos minus `hub.disabled_repos`; `id` is `{forge}/{host}/{owner}/{name}` lower-cased ([#12805](https://github.com/hivecommons/hive/issues/12805)) | `pkg/dashboard/api_contribute.go:192` | -| `GET` | `/api/contribute/activity` | Public | Contribute Activity | `pkg/dashboard/api_contribute.go:196` | -| `GET` | `/api/contribute/fleet` | Public | Contribute Fleet | `pkg/dashboard/api_contribute.go:197` | -| `GET` | `/api/contribute/events` | Public | Contribute Events (SSE). Every frame carries a monotonic `seq`; a connection whose channel filled gets a `gap` frame naming how many events it missed, so a long-lived client can tell "nothing happened" from "I missed events" ([#6218](https://github.com/hivecommons/hive/issues/6218)) | `pkg/dashboard/api_contribute.go:201` | -| `GET` | `/api/contribute/queue` | Public | Contribute Queue | `pkg/dashboard/api_contribute.go:204` | -| `GET` | `/api/contribute/opportunistic` | Public | Contribute Opportunistic | `pkg/dashboard/api_contribute.go:208` | -| `GET` | `/api/contribute/limits` | Public | Contribute Limits | `pkg/dashboard/api_contribute.go:213` | -| `GET` | `/api/contribute/metrics` | Public | Contribute Metrics | `pkg/dashboard/api_contribute.go:219` | -| `GET` | `/api/contribute/me` | Public path; caller identity resolved server-side (401 anonymous; a signed-in caller with no profile on this hive gets 200 with `has_profile:false` and no counters, [#12111](https://github.com/hivecommons/hive/issues/12111)) | The caller's OWN contribution stats — issues worked (24h and all-time), completions that produced a verified PR (24h and all-time, [#7894](https://github.com/hivecommons/hive/issues/7894)), and failures. No username parameter, so it only ever answers for its caller ([#6543](https://github.com/hivecommons/hive/issues/6543)) | `pkg/dashboard/api_contribute.go:229` | +| `GET` | `/contribute` | Public | Contribute Landing | `pkg/dashboard/api_contribute.go:187` | +| `GET` | `/contribute/{tab}` | Public | Contribute Landing | `pkg/dashboard/api_contribute.go:193` | +| `GET` | `/api/contribute/ws` | Public | s.contribute Hub.Handle WS | `pkg/dashboard/api_contribute.go:201` | +| `POST` | `/api/contribute/register` | Public | Contribute Register | `pkg/dashboard/api_contribute.go:202` | +| `POST` | `/api/contribute/invite` | Public | Contribute Invite | `pkg/dashboard/api_contribute.go:208` | +| `POST` | `/api/contribute/reissue-token` | Public | Contribute Reissue Token | `pkg/dashboard/api_contribute.go:209` | +| `GET` | `/api/contribute/status` | Public | Contribute Status | `pkg/dashboard/api_contribute.go:211` | +| `GET` | `/api/contribute/repositories` | Public | Contribution-eligible repositories for a contributor `repo_scope`: `{repositories:[{id,forge,host,full_name}],generated_at}`, the monitored repos minus `hub.disabled_repos`; `id` is `{forge}/{host}/{owner}/{name}` lower-cased ([#12805](https://github.com/hivecommons/hive/issues/12805)) | `pkg/dashboard/api_contribute.go:214` | +| `GET` | `/api/contribute/activity` | Public | Contribute Activity | `pkg/dashboard/api_contribute.go:218` | +| `GET` | `/api/contribute/fleet` | Public | Contribute Fleet | `pkg/dashboard/api_contribute.go:219` | +| `GET` | `/api/contribute/events` | Public | Contribute Events (SSE). Every frame carries a monotonic `seq`; a connection whose channel filled gets a `gap` frame naming how many events it missed, so a long-lived client can tell "nothing happened" from "I missed events" ([#6218](https://github.com/hivecommons/hive/issues/6218)) | `pkg/dashboard/api_contribute.go:223` | +| `GET` | `/api/contribute/queue` | Public | Contribute Queue | `pkg/dashboard/api_contribute.go:226` | +| `GET` | `/api/contribute/opportunistic` | Public | Contribute Opportunistic | `pkg/dashboard/api_contribute.go:230` | +| `GET` | `/api/contribute/limits` | Public | Contribute Limits | `pkg/dashboard/api_contribute.go:235` | +| `GET` | `/api/contribute/metrics` | Public | Contribute Metrics | `pkg/dashboard/api_contribute.go:241` | +| `GET` | `/api/contribute/me` | Public path; caller identity resolved server-side (401 anonymous; a signed-in caller with no profile on this hive gets 200 with `has_profile:false` and no counters, [#12111](https://github.com/hivecommons/hive/issues/12111)) | The caller's OWN contribution stats — issues worked (24h and all-time), completions that produced a verified PR (24h and all-time, [#7894](https://github.com/hivecommons/hive/issues/7894)), and failures. No username parameter, so it only ever answers for its caller ([#6543](https://github.com/hivecommons/hive/issues/6543)) | `pkg/dashboard/api_contribute.go:251` | | `GET` | `/api/contribute/run-stats/models` | Public | Per-model run evidence for the contributor wall: runs, verified-PR share, and failure rate over the selected window. | `pkg/dashboard/api_contribute.go` | | `GET` | `/api/contribute/wall` | Public | Contributor wall posts when the hive-wide wall switch is enabled; anonymous readers see visible posts, authors can still see their own hidden posts. | `pkg/dashboard/api_contribute.go` | | `POST` | `/api/contribute/wall` | Signed-in contributor | Create a 500-character plain-text wall post or one-level reply, with optional `model`, `backend`, and `repo` tags. Returns 401 anonymous, 403 when disabled/revoked/muted, and 429 when rate-limited. | `pkg/dashboard/api_contribute.go` | | `DELETE` | `/api/contribute/wall/{id}` | Post author | Author deletes their own wall post; action is audit logged. | `pkg/dashboard/api_contribute.go` | | `POST` | `/api/contribute/wall/{id}/hide` | Owner/read-write | Hide a wall post from public readers while leaving it visible to the author; action is audit logged and pushed over `/api/contribute/events`. | `pkg/dashboard/api_contribute.go` | | `POST` | `/api/contribute/wall/{id}/flag` | Signed-in contributor | Flag a wall post for Management review; action is audit logged. | `pkg/dashboard/api_contribute.go` | -| `GET` | `/api/contribute/triage` | Public | Contribute Triage | `pkg/dashboard/api_contribute.go:250` | -| `PUT` | `/api/contribute/queue/order` | Public | Contribute Queue Order | `pkg/dashboard/api_contribute.go:254` | -| `POST` | `/api/contribute/queue/hold` | Public | Contribute Queue Hold | `pkg/dashboard/api_contribute.go:259` | -| `POST` | `/api/contribute/queue/hold/clear` | Public | Contribute Queue Hold Clear | `pkg/dashboard/api_contribute.go:263` | -| `GET` | `/api/contribute/interests` | Public | Contribute Interests | `pkg/dashboard/api_contribute.go:269` | -| `PUT` | `/api/contribute/interests` | Public | Contribute Interests | `pkg/dashboard/api_contribute.go:270` | -| `GET` | `/api/contributors` | Dashboard auth/session | Contributors List | `pkg/dashboard/api_contribute.go:278` | -| `GET` | `/api/contributors/{id}` | Dashboard auth/session | Contributor Get | `pkg/dashboard/api_contribute.go:279` | +| `GET` | `/api/contribute/triage` | Public | Contribute Triage | `pkg/dashboard/api_contribute.go:272` | +| `PUT` | `/api/contribute/queue/order` | Public | Contribute Queue Order | `pkg/dashboard/api_contribute.go:276` | +| `POST` | `/api/contribute/queue/hold` | Public | Contribute Queue Hold | `pkg/dashboard/api_contribute.go:281` | +| `POST` | `/api/contribute/queue/hold/clear` | Public | Contribute Queue Hold Clear | `pkg/dashboard/api_contribute.go:285` | +| `GET` | `/api/contribute/interests` | Public | Contribute Interests | `pkg/dashboard/api_contribute.go:291` | +| `PUT` | `/api/contribute/interests` | Public | Contribute Interests | `pkg/dashboard/api_contribute.go:292` | +| `GET` | `/api/contributors` | Dashboard auth/session | Contributors List | `pkg/dashboard/api_contribute.go:300` | +| `GET` | `/api/contributors/{id}` | Dashboard auth/session | Contributor Get | `pkg/dashboard/api_contribute.go:301` | | `POST` | `/api/contributors/{id}/wall-mute` | Owner only | Mute or unmute a contributor from posting to the contributor wall; action is audit logged. | `pkg/dashboard/api_contribute.go` | -| `PUT` | `/api/contributors/{id}/trust` | Owner only | Contributor Trust | `pkg/dashboard/api_contribute.go:281` | -| `PUT` | `/api/contributors/{id}/agent-role` | Owner only | Contributor Agent Role | `pkg/dashboard/api_contribute.go:282` | -| `PUT` | `/api/contributors/{id}/agent-role-grants` | Owner only | Contributor Agent Role Grants | `pkg/dashboard/api_contribute.go:283` | -| `POST` | `/api/contributors/{id}/revoke` | Owner only | Contributor Revoke | `pkg/dashboard/api_contribute.go:284` | -| `POST` | `/api/contributors/{id}/requeue` | Dashboard auth/session | Contributor Requeue | `pkg/dashboard/api_contribute.go:285` | -| `DELETE` | `/api/contributors/{id}` | Owner only | Contributor Delete | `pkg/dashboard/api_contribute.go:286` | -| `GET` | `/contribute/dossier/{username}` | Public | Contributor Dossier Page (HTML) | `pkg/dashboard/api_contribute.go:178` | -| `GET` | `/api/contribute/run-stats` | Public | Contribute Run Stats | `pkg/dashboard/api_contribute.go:237` | -| `GET` | `/api/contribute/runs` | Public | Contribute Per-Run History | `pkg/dashboard/api_contribute.go:327` | -| `GET` | `/api/contribute/decisions` | Owner/read-write | Contribute Hub Decisions | `pkg/dashboard/api_contribute.go:337` | -| `GET` | `/api/contribute/dossier` | Public | Contribute Dossier Get | `pkg/dashboard/api_contribute.go:274` | -| `POST` | `/api/contribute/dossier` | Public | Contribute Dossier Update | `pkg/dashboard/api_contribute.go:275` | -| `GET` | `/api/leaderboard/contributor/{username}/heraldry` | Public | Contributor Heraldry | `pkg/dashboard/api_contribute.go:307` | +| `PUT` | `/api/contributors/{id}/trust` | Owner only | Contributor Trust | `pkg/dashboard/api_contribute.go:303` | +| `PUT` | `/api/contributors/{id}/agent-role` | Owner only | Contributor Agent Role | `pkg/dashboard/api_contribute.go:304` | +| `PUT` | `/api/contributors/{id}/agent-role-grants` | Owner only | Contributor Agent Role Grants | `pkg/dashboard/api_contribute.go:305` | +| `POST` | `/api/contributors/{id}/revoke` | Owner only | Contributor Revoke | `pkg/dashboard/api_contribute.go:306` | +| `POST` | `/api/contributors/{id}/requeue` | Dashboard auth/session | Contributor Requeue | `pkg/dashboard/api_contribute.go:307` | +| `DELETE` | `/api/contributors/{id}` | Owner only | Contributor Delete | `pkg/dashboard/api_contribute.go:308` | +| `GET` | `/contribute/dossier/{username}` | Public | Contributor Dossier Page (HTML) | `pkg/dashboard/api_contribute.go:200` | +| `GET` | `/api/contribute/run-stats` | Public | Contribute Run Stats | `pkg/dashboard/api_contribute.go:259` | +| `GET` | `/api/contribute/runs` | Public | Contribute Per-Run History | `pkg/dashboard/api_contribute.go:349` | +| `GET` | `/api/contribute/decisions` | Owner/read-write | Contribute Hub Decisions | `pkg/dashboard/api_contribute.go:359` | +| `GET` | `/api/contribute/dossier` | Public | Contribute Dossier Get | `pkg/dashboard/api_contribute.go:296` | +| `POST` | `/api/contribute/dossier` | Public | Contribute Dossier Update | `pkg/dashboard/api_contribute.go:297` | +| `GET` | `/api/leaderboard/contributor/{username}/heraldry` | Public | Contributor Heraldry | `pkg/dashboard/api_contribute.go:329` | | `GET` | `/api/cards/player/{asset}` | Public | OpenAPI alias for a cacheable contributor social-card SVG (`asset` is `.svg`). | `pkg/dashboard/social_cards.go:112` | | `GET` | `/api/cards/achievement/{login}/{asset}` | Public | OpenAPI alias for a cacheable attained-achievement SVG (`asset` is `.svg`). | `pkg/dashboard/social_cards.go:113` | | `GET` | `/api/cards/leaderboard/{asset}` | Public | OpenAPI alias for a cacheable leaderboard-summary SVG (`contributors.svg`, `teams.svg`, or `swarm.svg`). | `pkg/dashboard/social_cards.go:114` | @@ -58,10 +58,10 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `GET` | `/share/player/{login}` | Public | Share landing page with Open Graph/Twitter metadata for a contributor card and link to the public dossier. | `pkg/dashboard/social_cards.go:115` | | `GET` | `/share/achievement/{login}/{achievementID}` | Public | Share landing page with metadata for an unlocked achievement card and link to the public dossier. | `pkg/dashboard/social_cards.go:116` | | `GET` | `/share/leaderboard/{board}` | Public | Share landing page with metadata for a public leaderboard card and link to live standings. | `pkg/dashboard/social_cards.go:117` | -| `PUT` | `/api/contribute/help-links` | Owner/read-write | Contribute Help Links | `pkg/dashboard/api_contribute.go:195` | -| `GET` | `/api/contribute/operators/message` | Public path; caller identity resolved server-side (401 anonymous, 403 without a profile) | Returns only the signed-in contributor's unacknowledged operator messages; no username/body field can select another recipient ([#8461](https://github.com/hivecommons/hive/issues/8461)). | `pkg/dashboard/api_contribute.go:230` | -| `POST` | `/api/contribute/operators/message` | Owner/read-write | Sends a sanitized, length-capped one-to-one operator note to a contributor profile, persists it until acknowledgement, and pushes it to matching live relay sockets only ([#8461](https://github.com/hivecommons/hive/issues/8461)). | `pkg/dashboard/api_contribute.go:231` | -| `POST` | `/api/contribute/operators/message/ack` | Public path; caller identity resolved server-side | Acknowledges the signed-in contributor's own message, optionally recording a short sanitized reply for operators. | `pkg/dashboard/api_contribute.go:232` | +| `PUT` | `/api/contribute/help-links` | Owner/read-write | Contribute Help Links | `pkg/dashboard/api_contribute.go:217` | +| `GET` | `/api/contribute/operators/message` | Public path; caller identity resolved server-side (401 anonymous, 403 without a profile) | Returns only the signed-in contributor's unacknowledged operator messages; no username/body field can select another recipient ([#8461](https://github.com/hivecommons/hive/issues/8461)). | `pkg/dashboard/api_contribute.go:252` | +| `POST` | `/api/contribute/operators/message` | Owner/read-write | Sends a sanitized, length-capped one-to-one operator note to a contributor profile, persists it until acknowledgement, and pushes it to matching live relay sockets only ([#8461](https://github.com/hivecommons/hive/issues/8461)). | `pkg/dashboard/api_contribute.go:253` | +| `POST` | `/api/contribute/operators/message/ack` | Public path; caller identity resolved server-side | Acknowledges the signed-in contributor's own message, optionally recording a short sanitized reply for operators. | `pkg/dashboard/api_contribute.go:254` | ### Issue claims (hivecommons/hive#8380) diff --git a/src/docs/api-reference/dashboard-misc.md b/src/docs/api-reference/dashboard-misc.md index b94fd39fb8..26aac1af9e 100644 --- a/src/docs/api-reference/dashboard-misc.md +++ b/src/docs/api-reference/dashboard-misc.md @@ -47,21 +47,21 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f | `PUT` | `/api/hive-id` | Owner only | Hive IDSet | `pkg/dashboard/api.go:429` | | `POST` | `/api/chat` | Dashboard auth/session | Chat | `pkg/dashboard/api.go:458` | | `GET` | `/api/auth/token` | Public | Auth Token | `pkg/dashboard/api.go:492` | -| `GET` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:288` | -| `POST` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:289` | -| `GET` | `/api/docs` | Dashboard auth/session | APIDocs | `pkg/dashboard/api_contribute.go:290` | -| `GET` | `/leaderboard` | Public | Leaderboard Page | `pkg/dashboard/api_contribute.go:292` | -| `GET` | `/api/leaderboard` | Public | Leaderboard API | `pkg/dashboard/api_contribute.go:293` | -| `GET` | `/api/leaderboard/teams` | Public | Team Leaderboards | `pkg/dashboard/api_contribute.go:294` | -| `GET` | `/api/leaderboard/style` | Public | Leaderboard Style | `pkg/dashboard/api_contribute.go:295` | +| `GET` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:310` | +| `POST` | `/api/v1/` | GitHub token | Contributor v1 API dispatcher | `pkg/dashboard/api_contribute.go:311` | +| `GET` | `/api/docs` | Dashboard auth/session | APIDocs | `pkg/dashboard/api_contribute.go:312` | +| `GET` | `/leaderboard` | Public | Leaderboard Page | `pkg/dashboard/api_contribute.go:314` | +| `GET` | `/api/leaderboard` | Public | Leaderboard API | `pkg/dashboard/api_contribute.go:315` | +| `GET` | `/api/leaderboard/teams` | Public | Team Leaderboards | `pkg/dashboard/api_contribute.go:316` | +| `GET` | `/api/leaderboard/style` | Public | Leaderboard Style | `pkg/dashboard/api_contribute.go:317` | | `GET` | `/api/leaderboard/battle-log` | Public | Scrubbed public Battle Log activity feed for leaderboard widgets. | `pkg/dashboard/battle_log.go:108` | | `GET` | `/api/leaderboard/hive-of-week` | Public | Featured weekly project metadata, configured render URLs (empty when none), gource source URL, and embed snippets. | `pkg/dashboard/battle_log.go:109` | | `GET` | `/api/leaderboard/gource-log` | Public | Gource custom log source for a project/week, derived from public hive event data. | `pkg/dashboard/battle_log.go:110` | | `POST` | `/api/leaderboard/hive-of-week/archive` | Owner only | Archive the selected project's weekly gource source log into knowledge; stores source only, never rendered video. | `pkg/dashboard/battle_log.go:111` | -| `GET` | `/api/leaderboard/contributor/{username}` | Public | Contributor Profile | `pkg/dashboard/api_contribute.go:302` | -| `GET` | `/api/hives` | Dashboard auth/session | Hives List | `pkg/dashboard/api_contribute.go:313` | -| `POST` | `/api/hives/register` | Dashboard auth/session | Hives Register | `pkg/dashboard/api_contribute.go:314` | -| `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:315` | -| `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:316` | -| `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:317` | +| `GET` | `/api/leaderboard/contributor/{username}` | Public | Contributor Profile | `pkg/dashboard/api_contribute.go:324` | +| `GET` | `/api/hives` | Dashboard auth/session | Hives List | `pkg/dashboard/api_contribute.go:335` | +| `POST` | `/api/hives/register` | Dashboard auth/session | Hives Register | `pkg/dashboard/api_contribute.go:336` | +| `POST` | `/api/hives/{id}/heartbeat` | Dashboard auth/session | Hives Heartbeat | `pkg/dashboard/api_contribute.go:337` | +| `DELETE` | `/api/hives/{id}` | Owner only | Hives Delete | `pkg/dashboard/api_contribute.go:338` | +| `POST` | `/api/hives/onboard` | Dashboard auth/session | Hives Onboard | `pkg/dashboard/api_contribute.go:339` | | `GET` | `/sso` | Public | SSO | `pkg/dashboard/server.go:1657` | diff --git a/src/docs/api-reference/health-status-events.md b/src/docs/api-reference/health-status-events.md index 81330e9160..a3bc5e453f 100644 --- a/src/docs/api-reference/health-status-events.md +++ b/src/docs/api-reference/health-status-events.md @@ -1,5 +1,21 @@ # Dashboard REST API reference — Health, status, events +## Contributor pool counters + +`GET /api/status` includes `contributorPool.abandoned`, the sum of persisted +abandoned-PR counters across all registered profiles, and +`contributorPool.abandoned_by_login`, an object keyed by lowercase GitHub login. +Offline and revoked contributors remain included; zero-count logins are present. +An empty registry returns `abandoned: 0` and `abandoned_by_login: {}`. These are +historical adoption counts, not failed tasks or disconnected task runs. +`GET /api/contributors` provides each profile's `abandoned` and `abandoned_prs` +records (`repo`, `pr`, `adopted_into_pr`, `reason`, `at`). The Contributors tile +shows a nonzero count with the five most recent records in its tooltip. +See [Abandoned contributor PRs](../operator-reference.md#abandoned-contributor-prs) +for counting semantics. + +## Endpoints + Part of the [Dashboard REST API reference](../api-reference.md); see that page for how auth levels and `pkg/:` source citations are read and checked. Edit this file for routes in this area and run `src/scripts/check-api-reference-citations.sh --fix` to resync citations. diff --git a/src/docs/operator-reference.md b/src/docs/operator-reference.md index f915f32641..5b374d431b 100644 --- a/src/docs/operator-reference.md +++ b/src/docs/operator-reference.md @@ -18,6 +18,29 @@ read or mutate live `/data` state and have killed agent sessions. Human operators can debug inside the pod by setting `HIVE_ALLOW_LOCAL_GO_TEST=1`; all other Go subcommands pass through unchanged. +## Abandoned contributor PRs + +An abandoned PR is a contributor PR the hive adopts to finish, either **in +place** on the contributor's branch or by **supersession** into a hive PR. +Operator **Adopt now** / `adoption/supersede` takeovers count with reason +`operator_takeover`; automatic adoptions carry `offline` or `unresponsive`. +A relay disconnect or failed task alone is not a PR adoption. + +The adoption recorder deduplicates by repository and original PR: adopting the +same PR again does not increment the count. If an in-place adoption is later +superseded, its existing record gains `adopted_into_pr` rather than counting +again. A zero `adopted_into_pr` means adoption in place. Records also carry the +original `repo`, `pr`, `reason`, and timestamp `at`. + +The dashboard **Contributors** tile shows **Abandoned N** in muted red only for +nonzero counts. Hover for the five most recent adopted PRs, newest first, with +the superseding PR (or “in-place”), reason, and timestamp. +`/api/status.contributorPool` exposes the historical `abandoned` total and +`abandoned_by_login` counts (lowercase login keys), including offline and +revoked profiles. `/api/contributors` exposes the underlying per-profile +`abandoned` and `abandoned_prs` data. These counters are independent of +Completed/Failed task counts and do not change contributor trust tiers. + ## Minimum required configuration Most of `hive.yaml.example` is optional. The smallest config the hive will start diff --git a/src/pkg/dashboard/api_contribute.go b/src/pkg/dashboard/api_contribute.go index 21b6db2e17..454b2bd011 100644 --- a/src/pkg/dashboard/api_contribute.go +++ b/src/pkg/dashboard/api_contribute.go @@ -97,6 +97,10 @@ type ContributorPoolStatus struct { // PresenceWindow is the window Online was judged against ("15m"). PresenceWindow string `json:"presence_window"` ByRole map[string]int `json:"by_role,omitempty"` + // Abandoned totals adopted PRs across all registered profiles, including + // offline and revoked contributors. Login keys are canonical lowercase. + Abandoned int `json:"abandoned"` + AbandonedByLogin map[string]int `json:"abandoned_by_login"` } func (s *Server) BuildContributorPoolStatus() *ContributorPoolStatus { @@ -110,15 +114,33 @@ func (s *Server) BuildContributorPoolStatus() *ContributorPoolStatus { window = s.contributeHub.presenceWindow() online = countOnlineContributors(profiles, s.contributeHub.LastHeartbeats(), window, time.Now()) } + abandoned, abandonedByLogin := contributorAbandonedCounts(profiles) return &ContributorPoolStatus{ - Active: active, - Online: online, - Registered: len(profiles), - PresenceWindow: stageTrackerShortDuration(window), - ByRole: byRole, + Abandoned: abandoned, + AbandonedByLogin: abandonedByLogin, + Active: active, + Online: online, + Registered: len(profiles), + PresenceWindow: stageTrackerShortDuration(window), + ByRole: byRole, } } +// contributorAbandonedCounts reads the persisted counters, not the size of +// the recent-PR tooltip. Presence and trust tier do not filter historical cost. +func contributorAbandonedCounts(profiles []ContributorProfile) (int, map[string]int) { + total := 0 + byLogin := make(map[string]int) + for _, p := range profiles { + total += p.Abandoned + login := strings.ToLower(strings.TrimSpace(p.GitHubUsername)) + if login != "" { + byLogin[login] += p.Abandoned + } + } + return total, byLogin +} + // countOnlineContributors counts the registered profiles whose freshest // relay heartbeat is within window of now — the tracker's presence // predicate (liveConnectionsFor) applied across the registry, so the diff --git a/src/pkg/dashboard/contributor_abandoned_badge_test.go b/src/pkg/dashboard/contributor_abandoned_badge_test.go new file mode 100644 index 0000000000..cd65a87a5c --- /dev/null +++ b/src/pkg/dashboard/contributor_abandoned_badge_test.go @@ -0,0 +1,44 @@ +package dashboard + +import ( + "os/exec" + "strings" + "testing" +) + +func TestContributorAbandonedBadge(t *testing.T) { + html := indexHTML(t) + render := jsFunctionBody(t, html, "function renderContributors(contributors)") + if !strings.Contains(render, "${contributorAbandonedBadge(c)}") { + t.Fatal("contributor cards do not render the abandoned badge") + } + node, err := exec.LookPath("node") + if err != nil { + t.Skip("node not on PATH — abandoned badge rendering was NOT executed") + } + js := jsFunctionBody(t, html, "function esc(s)") + "\n" + jsFunctionBody(t, html, "function contributorAbandonedBadge(c)") + ` +function assert(ok, message) { if (!ok) throw new Error(message); } +for (const c of [{}, {abandoned: 0}, {abandoned: -1}]) { + assert(contributorAbandonedBadge(c) === '', 'zero/legacy counters should be hidden'); +} +const records = Array.from({length: 7}, (_, i) => ({repo: 'org/repo', pr: i + 1, + adopted_into_pr: i === 6 ? 90 : 0, reason: 'offline', at: '2026-10-0' + (i + 1) + 'T12:00:00Z'})); +records[6].reason = 'operator_takeover'; +const before = JSON.stringify(records); +const badge = contributorAbandonedBadge({abandoned: 7, abandoned_prs: records}); +assert(badge.includes('Abandoned 7'), badge); +assert(badge.includes('class="contrib-abandoned"'), 'badge class missing'); +assert(badge.includes('org/repo#7 → #90 · operator_takeover · 2026-10-07T12:00:00Z'), badge); +assert(badge.includes('org/repo#6 → in-place · offline'), badge); +assert(badge.indexOf('org/repo#7') < badge.indexOf('org/repo#6'), 'not newest first'); +assert(!badge.includes('org/repo#2') && badge.includes('org/repo#3'), 'tooltip must cap at five recent PRs'); +assert(JSON.stringify(records) === before, 'render mutated source records'); +const unsafe = contributorAbandonedBadge({abandoned: 1, abandoned_prs: [{repo: '\"', pr: 2, + reason: '\" onmouseover=\"evil', at: '