Skip to content

✨ feat(attention): per-recipient budgets with opt-in digest overflow (off by default) - #16309

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

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

Conversation

@hivecommons-hive

@hivecommons-hive hivecommons-hive Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Part of #16271 (partial: budget package, config keys, tests and docs land here; wiring the check into live non-urgent posts and loading the keys from the github.attention block follows once #16291 — the episode store for #16267 — merges, to avoid conflicting with that open contributor PR)
Part of #16075 (epic; other children remain)

Why

Per-condition reminder limits don't add up to an attention budget. Ten conditions on ten items, each reminding once a day, still adds up to ten pings a day for one person. The #16075 decision asks for per-recipient budgets and opt-in digest overflow to be scoped in their own child before anything enables them, and says newly actionable requests must never be dropped silently.

What

New store-agnostic package src/pkg/attentionbudget:

  • Budget: counts non-urgent attention writes (Ping, Reminder) per responsible recipient over a rolling 24h window, across items. Seed loads the episode ledger's delivered history (paged_to/paged_at) so the window survives restarts. Admit decides each write.
  • Overflow, never drop: when enabled and at or over N, the write is not posted. It is recorded as an open, overflowed ask (Overflowed, cleared by Resolve) and rendered for the item's status card (attention-overflow section via RenderSection), the per-repo action queue, and the digest.
  • Opt-in digest: one comment per recipient per repo (<!-- hive:attention-digest recipient=<login> -->), created once through the existing UpsertIssueMarkerComment boundary and edited in place after that. An empty digest never creates a comment. No external service is involved. Recipients who haven't opted in keep per-episode delivery, so their new asks are always posted and only their reminders are budgeted.
  • Exempt classes: security/destructive-action, required reviews, machine protocol commands and security/merge hold notices always deliver and never use budget. Unknown classes are treated as exempt.

Shadow mode (why it ships off)

Following the decision recorded on the issue, the budget ships disabled. With recipient_budget: 0, every decision is Deliver, so there is no behaviour change. The package still computes would_overflow against a candidate cap (ShadowBudget = 5) and reports per-login delivered/exempt/overflowed/would_overflow in an attention budget: log line (LogLine/Snapshot). That lets operators pick N from observed traffic before any hive enables it. The 5 is a measurement point, not policy.

New config keys (documented in src/docs/notifications.md)

Key Default
github.attention.recipient_budget 0 (off) max non-urgent writes per recipient per rolling 24h; ≤1000
github.attention.digest_recipients [] logins that opted into the digest

attentionbudget.Config carries these yaml tags and Validate(). The github.attention block, the pkg/attention episode ledger and its writer wiring are added by the still-open #16291 (#16267). Producer migration and the action queue belong to #16270. To avoid conflicting with that contributor PR, this change doesn't edit config.go, validate.go, the settings-parity allowlist or pkg/attention. Once #16291 lands, wiring the budget in means embedding attentionbudget.Config inline in attention.Config and calling Admit before each non-urgent POST.

Tests

src/pkg/attentionbudget/budget_test.go, table tests covering:

  • disabled-by-default no-op
  • shadow would-overflow counter without changing writes
  • (N+1)th ask recorded as overflowed and visible in the status/queue section, not dropped, for both opt-in and not-opted-in recipients
  • rolling window and seeding
  • each exempt class bypasses the budget
  • config validation
  • digest created once, then edited in place, one comment per recipient

Not run locally; CI decides.

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

…(off by default)

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 2, 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 kellyaa 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/XL Denotes a PR that changes 500-999 lines, ignoring generated files. label Nov 2, 2026
@hivecommons-hive

hivecommons-hive Bot commented Nov 2, 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 `#16309c63510f` sha256:dead5b2306390aaed5ae37be5b5e71b0d0781a0f953bdec436c10afbccd7b3fa — download from the dashboard or `hivectl review evidence #16309`.

@github-actions

github-actions Bot commented Nov 2, 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
#16321 ✨ feat(notifications): shadow-mode would-notify instrumentation and write-site classification same files src/docs/notifications.md

@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 2, 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 src/pkg/attentionbudget/budget.go in full and checked how it sits on v5. The package does what the body says and I have no correctness findings: exempt classes short-circuit before the window is touched (Admit, budget.go), recipient_budget: 0 always returns Deliver while tallying would_overflow against ShadowBudget, an over-cap Ping to a non-opted-in login is still delivered and only Reminder is deferred, and Overflowed/Resolve keep the deferred ask visible rather than dropping it. The landing order (package first, wiring after #16291) is stated in the body, so I am not raising it as a question.

One low-severity docs note. The new table in src/docs/notifications.md presents github.attention.recipient_budget and github.attention.digest_recipients as config fields with defaults, but on this head nothing reads them: attentionbudget has no importer outside its own package, and the github.attention block itself does not exist on v5 — it is introduced by #16291 (src/pkg/config/config.go, Attention attention.Config), which is an open fork PR. pkg/config does not reject unknown keys, so an operator who follows the table today sets a value that is silently ignored. The paragraph under the table does say the budget "takes effect once the ledger routes its non-urgent writes through it", which covers it, but I'd make that explicit in the table itself (e.g. a "not yet read by any loader; lands with the wiring" note) or hold the table for the wiring PR, so the doc does not describe a knob that is not there.

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

@hivecommons-hive
hivecommons-hive Bot merged commit 78d046d into v5 Nov 2, 2026
87 of 95 checks passed
@kubestellar-prow
kubestellar-prow Bot deleted the scanner/fix-16271 branch November 2, 2026 23:01
@github-actions

github-actions Bot commented Nov 2, 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

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. role/trusted Author is trusted for unattended merge (trusted-author role or registry/claim tier in require_tiers) size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. stage/050-review-pending Review swarm requested; awaiting a verdict for the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants