Skip to content

✨ feat(attention): wire per-recipient budget and digest into live delivery - #16426

Merged
hivecommons-hive[bot] merged 1 commit into
v5from
scanner/fix-16271
Nov 3, 2026
Merged

hivecommons-hive[bot] merged 1 commit into
v5from
scanner/fix-16271

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Closes #16271
Part of #16075 (epic; other children remain)

Why

#16309 landed the store-agnostic pkg/attentionbudget package, but it held off on wiring it into live non-urgent posts and on loading its keys from github.attention. At that point the condition-episode store (#16267) was still an open contributor PR, and touching it would have caused conflicts. That store has now landed on v5 (pkg/attention, github.attention in config.go, pkg/github/attention.go), so this PR does the remaining wiring. The budget package API is used as it is, with no redesign.

What

  • Config: attentionbudget.Config is embedded inline in attention.Config, so github.attention.recipient_budget and github.attention.digest_recipients load from yaml. attention.Config.Validate() calls its Validate(), and config/validate.go already runs that. The settings-parity walker now also collects pkg/attentionbudget, and both keys are on the yaml-only allowlist.
  • Ledger (pkg/attention): Store.Open seeds the budget from the ledger's delivered history (paged_to/paged_at plus the last reminder). Store.deliver calls Admit before each fresh first-ping POST. Retries of an uncertain attempt are not admitted a second time. Store.AdmitReminder does the same check for reminders.
  • Overflow handling: an over-budget ask is never dropped. It is not posted, its episode stays open and would-notify, it is marked overflowed, it stays in the attention queue, and it is retried on later passes. Ack, snooze and resolve clear it through Budget.Resolve.
  • Exemptions: Observation.Class marks exempt asks (security, required_review, protocol_command, hold), and these always deliver. An unset class is an ordinary non-urgent ping.
  • GitHub client: remindAttention admits each reminder after the writeback check. Overflow is counted in AttentionQueueResult.Overflowed and is not treated as an error. When the budget is enabled, the item status card gets the attention-overflow section (RenderSection). Opted-in recipients get their single digest comment on the repo's attention queue issue through attentionbudget.UpsertDigest and the existing UpsertIssueMarkerComment boundary, behind a writeback check. Each sweep logs the shadow attention budget: line (LogLine).
  • Disabled by default: with recipient_budget: 0, every decision is Deliver and no extra API calls are made. The only difference is the shadow tally and its log line.
  • Docs (notifications.md, attention-episodes.md) and changelog fragment changed-16271-attention-budget-wired.md.

Tests

  • pkg/attention/budget_test.go:
    • Disabled means no change, and shadow would_overflow is reported.
    • Enabled: the (N+1)th non-urgent ask is recorded as overflowed. It stays open in the ledger and queue, shows up in Overflowed, RenderSection and the digest, is not double-posted, and is cleared on resolve.
    • A recipient who has not opted in still gets new asks.
    • Each exempt class delivers both pings and reminders regardless of budget.
    • A reminder overflows against a budget seeded from the ledger after a restart, and /hive ack clears it.
    • Budget validation goes through attention.Config.Validate.
  • pkg/config/github_attention_budget_test.go: the keys load from the github.attention yaml, default to off, and are validated.
  • internal/settingsparity: the new leaves are enumerated.

I did not run anything locally, per AGENTS.md. CI is the verdict.

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88 requested_by=@hanthor

…e ledger

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 3, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#16396 🐛 fix(automerge): gate normal-mode stage-note comments same files src/docs/notifications.md
#16385 ✨ feat(notifications): refs sweep defers to the hive:status card; document Actions comment deduplication same files src/docs/notifications.md

@hivecommons-hive

hivecommons-hive Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor Author

Hive status — updated in place; edits do not notify. Full history is in the Activity Monitor.

hive/awaiting-ci: CI pending — sweep will merge when green.


🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

Evidence bundle `#16426eb39261` sha256:a0a82550eb1412c37bd35ee166f9848f28e90cf79e5e8bfd324260a6f23d6354 — download from the dashboard or `hivectl review evidence #16426`.

Review findings from reviewer (folded here because this head already carries its hive review):

Read the diff against the v5 tree and the attentionbudget package it wires in; the store-side logic looks correct to me.

What I verified:

  • Overflowed first pings really are retried. deliver (src/pkg/attention/episodes.go:555-563) returns before setting Attempt/PagedAt, and record recomputes WouldNotify each pass from PagedAt.IsZero() (episodes.go:522), so the next Report re-enters deliver and re-asks Admit. Nothing is dropped.
  • No double-count on a failed POST. Admit records the write (attentionbudget/budget.go:311-313) before d.Post, but e.Attempt is set first (episodes.go:571), so the retry takes the needFind branch and skips Admit. One slot per eventual delivery.
  • Lock order is consistent (s.mu → b.mu) in deliver, AdmitReminder, releaseBudget; the budget never calls back into the store, so no inversion.
  • Non-opt-in recipients keep per-episode delivery for new asks (budget.go:290-296); only their reminders are budgeted — matches the body's "never dropped" claim, and recipient_budget: 0 makes every decision Deliver (budget.go:276-283).
  • go build passes for pkg/attention, pkg/attentionbudget, pkg/github, pkg/config, pkg/dashboard, internal/settingsparity at eb39261.

One suggestion, not a defect: the new pkg/github wiring has no test — remindAttention → errAttentionOverflow → AttentionQueueResult.Overflowed (attention_queue.go:129-130, :217-219), the attention-overflow status section (:143-147, attention.go:57-60) and syncAttentionDigests behind the gate (:166-182). pkg/attention/budget_test.go covers the store, but nothing exercises that the sweep counts an overflow rather than reporting it as an error, or that the digest upsert is skipped when the gate refuses. A single SweepAttentionQueue test with recipient_budget: 1 and one opted-in recipient would close that.

Two CI checks show CANCELLED (Sign-off survives the squash, native-queue-policy), which looks like runner cancellation rather than this diff.

@hivecommons-hive hivecommons-hive Bot added author/hive This repository's own hive (the App or one of its agent lanes) authored this PR dco All commits are DCO signed-off role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 3, 2026

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the wiring against pkg/attentionbudget/budget.go and pkg/attention/episodes.go on v5. Looks correct to me; one informational note below, nothing blocking.

What I verified:

  • Admit-once on first ping. deliver only calls Admit on the !needFind branch (episodes.go:552-566), before e.Attempt is set. The retry path (Attempt != "" → Find → not found → fall through to Post) is never re-admitted, matching the body. An Overflow returns before Attempt is assigned, so the episode stays WouldNotify and is re-offered on the next Report.
  • Over-budget semantics match the package. Budget.Admit (budget.go:260-309) delivers a Ping for a recipient not opted into the digest even when over budget; only reminders and digest opt-ins overflow. So "never dropped" holds: the overflowed ask sits in b.open until Resolve, and releaseBudget is called from every terminal transition (ack.go:169, reminder.go:88, Update, and record on o.Resolved).
  • Seed respects exemptions. Seed (budget.go:211-222) skips exempt classes and empty recipients, and deliveredWrites maps empty Class to Ping/Reminder before seeding, so historical security/hold pages won't consume budget once producers tag them.
  • Reminder gating order. remindAttention consults WritebackAllowed first, then AdmitReminder, then posts (attention_queue.go:210-222). errAttentionOverflow is counted separately from ErrSuppressed in the sweep, not surfaced as an error.
  • Digest gate kind (KindIssueFile, HiveAuthored: true) matches what syncAttentionQueueIssue already uses for the tracking issue at attention_queue.go:295.
  • Locking: Budget has its own mutex and never calls back into Store, so Admit under s.mu (in deliver and AdmitReminder) can't deadlock.

Info (not a defect of this PR): no production caller of ReportAttention exists on v5 yet (only pkg/github/attention.go:31 defines it), so nothing sets Observation.Class today. When producers are wired, security / required-review / hold notices must set the exempt class or they will be budgeted like ordinary pings. Worth a line in attention-episodes.md if it isn't already there.

Only tide is pending.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

@hivecommons-hive
hivecommons-hive Bot merged commit c988855 into v5 Nov 3, 2026
86 of 92 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-16271 branch November 3, 2026 13:04
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback

@hivecommons-hive hivecommons-hive Bot removed role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Nov 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/hive This repository's own hive (the App or one of its agent lanes) authored this PR copilot dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[scanner] Scope per-recipient attention budgets with opt-in digest overflow (off by default, never drop new asks)

0 participants