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-contributor-tier-history.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Every contributor trust-tier change (operator trust/revoke, newcomer→contributor auto-promotion, registration) now appends `{tier, prev, at, by, reason, source}` to the contributor's `tier_history`, writes a `contributor-tier-changed` audit event, and is shown as "tier since … · by … · reason" on the Contributors view and in `GET /api/contributors`; same-tier writes are no-ops. The stage lane re-reads the author's registry tier every sweep — including for PRs parked on needs-rebase/hold/excluded labels — so a promotion or demotion reaches parked PRs on the next pass instead of sticking to the stale `role/*` label ([#15177](https://github.com/hivecommons/hive/issues/15177)).
19 changes: 19 additions & 0 deletions src/docs/contributor-trust-and-roles.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,25 @@ Contributor profiles carry a `trust_tier` field. The current tier order is:
| `merger` | maintainer/owner grant; it is not auto-promoted | May queue **other people's** PRs for Hive's auto-merge-on-green flow. |
| `advisor` | maintainer/owner grant | Advisory/invite tier; it is not ordered above `merger` for role-claim checks. |

### Who changed a tier, when and why

Every tier change — operator dropdown or `PUT /api/contributors/{id}/trust`
(optional `reason`), `POST /api/contributors/{id}/revoke`, the
newcomer→contributor auto-promotion, and the initial `newcomer` at
registration — appends `{tier, prev, at, by, reason, source}` to the
contributor record's `tier_history` (`by` is the operator login,
`hive:auto-promotion` or `hive:registration`; capped at the latest 50) and
writes an `audit.jsonl` event with `action: "contributor-tier-changed"`
carrying the same fields. Setting the tier a contributor already holds is a
no-op: no history entry, no audit line. `GET /api/contributors` returns
`tier_history`, and the Contributors view shows the current tier's provenance
("trusted since … · by … · reason") under and on hover of the tier chip.

The stage lane re-reads the author's registry tier on every sweep, including
for PRs parked on `needs-rebase`/hold/excluded labels, so a promotion or
demotion reaches every open PR on the next pass instead of sticking to the
`role/*` label a previous pass wrote.

The merger tier is deliberately **never allowed to own its own merge**. Queueing a PR as `merger` or `owner` is rejected when the authenticated dashboard user matches the PR author, and the auto-merge sweep re-checks the queued-by user before merging.

Task leases are also the unit for staged runs. A staged run stays on the same
Expand Down
1 change: 1 addition & 0 deletions src/pkg/dashboard/audit.go
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ var auditSensitiveActions = map[string]bool{
"config_governor_work_source": true,
"config_review": true,
"config_write_surface": true,
"contributor-tier-changed": true,
"copilot_auth_logout": true,
"copilot_auth_start": true,
"copilot_token_missing": true,
Expand Down
36 changes: 30 additions & 6 deletions src/pkg/dashboard/contribute_admin.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package dashboard

import (
Expand Down Expand Up @@ -123,25 +123,36 @@
return
}
var req struct {
Tier string `json:"tier"`
Tier string `json:"tier"`
Reason string `json:"reason,omitempty"`
}
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
jsonError(w, "Invalid request", http.StatusBadRequest)
return
}
validTiers := map[string]bool{"newcomer": true, "contributor": true, "trusted": true, "merger": true, "advisor": true, "revoked": true}
validTiers := map[string]bool{contributorTierNewcomer: true, contributorTierContributor: true, contributorTierTrusted: true, contributorTierMerger: true, contributorTierAdvisor: true, contributorTierRevoked: true}
if !validTiers[req.Tier] {
jsonError(w, "Invalid tier", http.StatusBadRequest)
return
}
p.TrustTier = req.Tier
reason := strings.TrimSpace(req.Reason)
if reason == "" {
reason = "operator set tier"
}
change, changed := applyContributorTierChange(p, req.Tier, requestUser(r), reason, tierChangeSourceOperator, time.Now())
if !changed {
// Same tier: nothing to persist, no history entry, no audit event.
jsonResponse(w, map[string]any{"ok": true, "trust_tier": p.TrustTier, "unchanged": true})
return
}
// H2: admin path — adminOverride lets this change a terminal (revoked) tier and
// wins the CAS reconcile against any concurrent stale WS save. The write is
// server-authoritative.
if err := saveContributorProfileCAS(p, true); err != nil {
jsonError(w, "Failed to save", http.StatusInternalServerError)
return
}
s.auditContributorTierChange(p, change)
// H2: if this change revokes access, fence any live WebSocket sessions the
// contributor holds so an in-flight connection cannot keep working (or keep
// saving a stale "contributor" profile) after the revoke.
Expand All @@ -151,8 +162,8 @@
s.contributeHub.DisconnectContributor(p.ContributorID, "contribution access revoked")
}
}
s.logger.Info("contributor tier changed", "username", p.GitHubUsername, "tier", req.Tier)
jsonResponse(w, map[string]any{"ok": true, "trust_tier": req.Tier})
s.logger.Info("contributor tier changed", "username", p.GitHubUsername, "tier", req.Tier, "prev", change.Prev, "by", change.By, "reason", change.Reason)
jsonResponse(w, map[string]any{"ok": true, "trust_tier": req.Tier, "tier_change": change})
}

func (s *Server) handleContributorAgentRoleGrants(w http.ResponseWriter, r *http.Request) {
Expand Down Expand Up @@ -346,14 +357,17 @@
jsonError(w, "Contributor not found", http.StatusNotFound)
return
}
p.TrustTier = "revoked"
change, changed := applyContributorTierChange(p, contributorTierRevoked, requestUser(r), "operator revoked contribution access", tierChangeSourceOperator, time.Now())
// H2: admin path — adminOverride wins the CAS reconcile so this revoke cannot be
// silently clobbered by a concurrent stale WS save, and the tier is now
// server-authoritative and terminal for any later non-admin write.
if err := saveContributorProfileCAS(p, true); err != nil {
jsonError(w, "Failed to save", http.StatusInternalServerError)
return
}
if changed {
s.auditContributorTierChange(p, change)
}
// H2: fence live sessions — close any WebSocket connections this contributor
// holds so an in-flight session cannot keep working, keep minting credentials, or
// keep saving a stale non-revoked profile after the revoke lands.
Expand Down Expand Up @@ -455,3 +469,13 @@
s.logger.Info("contributor deleted", "username", p.GitHubUsername)
jsonResponse(w, map[string]any{"ok": true, "deleted": p.GitHubUsername})
}

// auditContributorTierChange writes the audit.jsonl event that pairs with a
// TierHistory entry: user = who moved the tier (operator login or the hive
// writer), agent = the contributor id, detail = the same fields as the entry.
func (s *Server) auditContributorTierChange(p *ContributorProfile, change ContributorTierChange) {
if s == nil || s.audit == nil || p == nil {
return
}
s.audit.Log(change.By, auditActionContributorTierChanged, tierChangeAuditDetail(p.GitHubUsername, change), p.ContributorID)
}
122 changes: 113 additions & 9 deletions src/pkg/dashboard/contribute_profiles.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
package dashboard

import (
Expand Down Expand Up @@ -144,12 +144,18 @@
TokenRotationDue bool `json:"token_rotation_due,omitempty"`
TokenPlain string `json:"registration_token_plain,omitempty"`
TrustTier string `json:"trust_tier"`
PreferredRole string `json:"preferred_role,omitempty"`
CLIBackend string `json:"cli_backend,omitempty"`
Model string `json:"model,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
KnowledgeLoaded *bool `json:"knowledge_loaded,omitempty"`
KnowledgeError string `json:"knowledge_error,omitempty"`
// TierHistory is the append-only provenance of TrustTier: one entry per
// real change (registration, operator set/revoke, auto-promotion) naming
// who moved the tier, when, from what and why. It is what answers "who
// changed this contributor to trusted?" — every writer goes through
// applyContributorTierChange, which also refuses to record a no-op.
TierHistory []ContributorTierChange `json:"tier_history,omitempty"`
PreferredRole string `json:"preferred_role,omitempty"`
CLIBackend string `json:"cli_backend,omitempty"`
Model string `json:"model,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
KnowledgeLoaded *bool `json:"knowledge_loaded,omitempty"`
KnowledgeError string `json:"knowledge_error,omitempty"`
// AdvisorModel / AdvisorEffort: the last-reported second model that
// reviewed this contributor's work (hivecommons/hive#7760). Display only.
AdvisorModel string `json:"advisor_model,omitempty"`
Expand Down Expand Up @@ -401,20 +407,21 @@
func createContributorProfile(username string, policies ...contributorTokenPolicy) (*ContributorProfile, string) {
cid := "c-" + randomHex(6)
token := randomHex(32)
now := time.Now().UTC()
p := &ContributorProfile{
GitHubUsername: username,
ContributorID: cid,
RegistrationToken: sha256Hex(token),
TokenPlain: token,
TrustTier: "newcomer",
RegisteredAt: time.Now().UTC().Format(time.RFC3339),
RegisteredAt: now.Format(time.RFC3339),
RateLimits: ContributorRateLimits{
MaxConcurrent: 1,
MaxPerHour: 3,
MaxPerDay: 10,
},
}
policyOrDefault(policies).issue(p, time.Now().UTC())
applyContributorTierChange(p, contributorTierNewcomer, tierChangeByRegistration, "self-registered", tierChangeSourceRegistration, now)
policyOrDefault(policies).issue(p, now)
_ = saveContributorProfile(p)
return p, token
}
Expand Down Expand Up @@ -500,3 +507,100 @@
}
return newToken
}

// Trust tier names the registry stores. The admin handler validates against
// this set; the lane and relay read the raw string.
const (
contributorTierNewcomer = "newcomer"
contributorTierContributor = "contributor"
contributorTierTrusted = "trusted"
contributorTierMerger = "merger"
contributorTierAdvisor = "advisor"
contributorTierRevoked = "revoked"
)

// Actors and sources recorded on a ContributorTierChange. By is an operator
// login for operator changes; these constants cover the machine writers.
const (
tierChangeByAutoPromotion = "hive:auto-promotion"
tierChangeByRegistration = "hive:registration"

tierChangeSourceOperator = "operator"
tierChangeSourceAutoPromotion = "auto-promotion"
tierChangeSourceRegistration = "registration"

// contributorTierHistoryMax bounds the per-profile history; a tier is
// changed by hand a handful of times over a contributor's life, so the
// oldest entries are dropped only under pathological churn.
contributorTierHistoryMax = 50
// contributorTierReasonMax bounds the operator-supplied reason text.
contributorTierReasonMax = 240
)

// auditActionContributorTierChanged is the audit.jsonl action every tier
// change writes, alongside the TierHistory entry on the profile.
const auditActionContributorTierChanged = "contributor-tier-changed"

// ContributorTierChange is one entry of ContributorProfile.TierHistory.
type ContributorTierChange struct {
Tier string `json:"tier"`
Prev string `json:"prev,omitempty"`
At string `json:"at"`
By string `json:"by"`
Reason string `json:"reason,omitempty"`
Source string `json:"source"`
}

// applyContributorTierChange moves p to tier and records the change on
// TierHistory. It returns the entry and true when the tier actually changed;
// a write of the tier the profile already holds is a no-op that touches
// neither TrustTier nor the history, so repeated saves never spam it.
func applyContributorTierChange(p *ContributorProfile, tier, by, reason, source string, now time.Time) (ContributorTierChange, bool) {
if p == nil {
return ContributorTierChange{}, false
}
tier = strings.ToLower(strings.TrimSpace(tier))
if tier == "" || tier == p.TrustTier {
return ContributorTierChange{}, false
}
reason = strings.TrimSpace(sanitizeString(reason))
if len(reason) > contributorTierReasonMax {
reason = reason[:contributorTierReasonMax]
}
ch := ContributorTierChange{
Tier: tier,
Prev: p.TrustTier,
At: now.UTC().Format(time.RFC3339),
By: strings.TrimSpace(by),
Reason: reason,
Source: source,
}
p.TrustTier = tier
p.TierHistory = append(p.TierHistory, ch)
if n := len(p.TierHistory); n > contributorTierHistoryMax {
p.TierHistory = append([]ContributorTierChange(nil), p.TierHistory[n-contributorTierHistoryMax:]...)
}
return ch, true
}

// currentTierChange is the history entry that set the tier the profile holds
// now, or false when the tier predates history (legacy profile) or the
// history was rewritten past it.
func currentTierChange(p *ContributorProfile) (ContributorTierChange, bool) {
if p == nil {
return ContributorTierChange{}, false
}
for i := len(p.TierHistory) - 1; i >= 0; i-- {
if p.TierHistory[i].Tier == p.TrustTier {
return p.TierHistory[i], true
}
}
return ContributorTierChange{}, false
}

// tierChangeAuditDetail is the audit.jsonl detail for a tier change: the
// same fields as the TierHistory entry, in the key=value form the rest of
// the log uses.
func tierChangeAuditDetail(username string, ch ContributorTierChange) string {
return auditDetail("username", username, "tier", ch.Tier, "prev", ch.Prev, "by", ch.By, "reason", ch.Reason, "source", ch.Source)
}
Loading
Loading