Skip to content

✨ feature: persist single-admitter condition episodes - #16291

Closed
mendezr wants to merge 4 commits into
hivecommons:v5from
mendezr:scanner/condition-episodes-16267
Closed

mendezr wants to merge 4 commits into
hivecommons:v5from
mendezr:scanner/condition-episodes-16267

Conversation

@mendezr

@mendezr mendezr commented Nov 2, 2026

Copy link
Copy Markdown
Contributor

Fixes #16267

Summary

  • Add producer-independent CI/finding/decision keys and persisted condition episodes with acknowledgement, snooze, recovery and configurable 12h flap handling.
  • Add explicit per-repo github.attention.admitter ownership. Non-admitters record would-notify and fold status only; unset ownership leaves existing behavior unchanged.
  • Persist attempt markers before POST, reconcile trusted paginated markers after uncertain outcomes, and reuse the same attempt on retry.
  • Wire the additive API through the existing writeback gate, with bounded state/status, atomic persistence, fail-quiet recovery and rollout documentation.

Rollout boundary

Existing producers, reviews, machine commands and holds are intentionally unchanged. Producer migration and the opt-in pilot remain #16270; concurrent status routing requires #16263. The first complete item inventory after ledger loss seeds without sending. Capacity exhaustion fails closed rather than evicting history. Ownership requires one deployment per configured hive ID; marker lookup is not presented as cross-instance atomic admission.

Validation

  • Added episode scenario tests, persisted restart/corruption/capacity tests, concurrent-producer tests, and GitHub adapter tests for ownership, writeback pause, bounded status and trusted paginated marker lookup.
  • gofmt -l on changed Go files: clean.
  • Tests not run locally, per AGENTS.md; CI is the test verdict.

— hive: backend=pi model=openai-codex/gpt-6.1-sol


🐝 Hive Agent: contributor | SHA: 2ccf4a9ef

Add opt-in per-repo attention ownership, durable producer-independent episodes, quiet baseline recovery, and exact-attempt reconciliation before uncertain POST retries. Keep existing writers, reviews, commands and holds unchanged for the separate pilot.

Hive-Run: hivecommons#16267
Hive-Plan: RFC-16075/phase-3-condition-episodes
Hive-Spec: RFC-16075#2
Signed-off-by: mendezr <mendezr@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 nicholasjackson 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/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. label Nov 2, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@mendezr this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • coverage

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Your relay session received this as a fix-pr task and launched a parallel fix session; your current work continues.

Signed-off-by: mendezr <mendezr@users.noreply.github.com>
@mendezr

mendezr commented Nov 2, 2026

Copy link
Copy Markdown
Contributor Author

Follow-up on the coverage nudge for 2ccf4a9: head ff5de88 already adds the attention config golden fixture, YAML-only settings parity entry, and writeback-gate annotation to address the CI contract failures. CI has restarted on that head; no failing checks are currently reported, with the remaining test/coverage work still pending. No additional code changes made in this pass. Base v5 is mergeable (no DIRTY/BEHIND repair needed).


🐝 Hive Agent: contributor | SHA: unknown

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@mendezr this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • coverage

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Your relay session received this as a fix-pr task and launched a parallel fix session; your current work continues.

Signed-off-by: mendezr <mendezr@users.noreply.github.com>
@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
#16300 ✨ feat(config): stage bounded human-merge pin-only policy and classifier same files src/pkg/config/config.go
src/pkg/config/validate.go
src/pkg/dashboard/settings_parity_allowlist.txt
#16321 ✨ feat(notifications): shadow-mode would-notify instrumentation and write-site classification same files src/pkg/github/client.go

@hivecommons-hive hivecommons-hive Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Correctness review (head 044c41d, read against #16267)

1. Every new item's first inventory is swallowed, not just the first after ledger loss — src/pkg/attention/episodes.go:261,289
baseline := !s.state.Items[itemKey] is true for any PR/issue the ledger has never seen, ledger intact or not. Episodes created on that report get Baseline: true permanently, and episodes.go:329 never POSTs a baseline episode. So a required job that is already red the first time a producer reports a PR gets zero attention writes (until it resolves and recurs >12h later). That contradicts the PR body ("first complete item inventory after ledger loss seeds without sending"), src/docs/attention-episodes.md ("On missing/corrupt state, the first complete inventory per item is a recovery baseline"), and #16267's scenario "same failure across pushes ⇒ one episode, one attention write". Every test only passes because it pre-seeds with an empty report(t, s, f, "owner") first (episodes_test.go TestAcrossProducersPushesAndRestart etc.); drop that line and posts==0. Real producers cannot know whether their first snapshot is "the first for this item".

History already supplies the replay guard (a key with a prior trusted marker is seeded as Baseline), and a key with no prior marker was never paged, so there is nothing to replay. Suggested fix:

			e = &Episode{Key: o.Key, State: Observed, FirstSeen: now, Baseline: historical[hash]}

and drop the "Call with an empty inventory after recovery" contract from src/pkg/github/attention.go:27 / the doc, or keep the per-item baseline only when Open actually took a recovery path (missing/corrupt/zero-version), recorded in a recovered bool on Store.

2. Status-card hive:condition markers count as delivery history — src/pkg/github/attention.go:67,122, episodes.go:267-277
attentionKeyMarker matches hive:condition markers, which attentionStatus emits for every non-resolved episode, including would notify ones a non-admitter folded into the shared status comment and ones that were never paged. On the admitter's first report for that item, History returns those hashes, the episode is seeded Baseline: true, and the admitter never pages it. In the documented two-hive topology this means whichever condition a non-admitter saw first is permanently suppressed for the owner. Only hive:attention markers evidence a real POST:

var attentionKeyMarker = regexp.MustCompile(`<!-- hive:attention key=([a-f0-9]{64}) attempt=[a-f0-9]{32} -->`)

(TestAttentionMarkerLookupPaginatesAndRequiresTrustedAuthor still passes; it uses e.Marker().)

3. Resolved episodes are never pruned, so the 4096 cap is a deployment-wide dead stop — episodes.go:274,286, recovery_test.go TestRecoveryFailuresFenceDelivery
Resolved episodes (and the hash-only entries History seeds) stay in the ledger forever; once len(Episodes) == MaxEpisodes, every Report across all repos errors and no new condition can page, with no API to archive. Pruning State == Resolved && !Uncertain && now.Sub(ResolvedAt) > cfg.Window() is behaviour-preserving: a recurrence after the window already replaces such an episode with a fresh one (episodes.go:292-294) and attentionStatus already skips resolved ones. Suggest doing that prune at the top of Report (under s.mu) before the capacity checks.

Not blocking: Report holds s.mu across paginated History/Find/Post calls, so one slow GitHub listing stalls every producer and every Snapshot process-wide; fine for the pilot, worth noting for #16270.

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

@hivecommons-hive

hivecommons-hive Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

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

Hive filed review findings that do not block this PR as backlog items:

Cap: 10 backlog item(s) per PR per day.

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

Read the new package and its wiring against v5 (9103327), not just the diff. This looks correct to me for what #16267 scopes — the persistence/admission primitive, with producer migration left to #16270 as the issue itself decided.

What I verified:

  • Single-admitter is enforced at the write, not only at planning. src/pkg/attention/episodes.go Report skips any POST when owner != hiveID, and src/pkg/github/attention.go attentionDelivery.Post re-reads the live config and returns writeback.ErrSuppressed if ownership moved between plan and write. Non-admitters only reach UpsertPRStatusSection, which edits (never creates, when text is empty — pr_status_comment.go:25) the status card.
  • Uncertain-POST reconciliation reuses the attempt. Attempt is minted once, saved with Uncertain=true before Post, and a later Report goes through Find on the same marker before re-posting. Post lands on Client.CreateIssueComment (client.go:2933), which is already canary-gated and journaled via effects.ExecuteReconciling, so an ambiguous 5xx is fenced at two layers rather than retried blind.
  • No replay after state loss. First Report per item seeds Baseline=true episodes from trusted hive:attention/hive:condition markers and the e.Baseline check skips notification for them; Open refuses unknown ledger versions instead of overwriting them.
  • ReportAttention has no production caller in this PR (only attention_test.go), which matches the "Rollout boundary" section and the issue's split from [scanner] Issue-side hive:status consolidation, actionable attention events, 24h reminders and GitHub-native action queue (opt-in pilot) #16270.

One behaviour worth knowing, not a defect: episodes seeded from history alone carry a zero Key, so snapshot() (filters on Key.Repo/Key.Item) omits them from the status card until the same condition is re-observed. Under the "full current inventory" contract that is the right reading — an unobserved condition is gone — but it means the "uncertain; reconciliation required" line only appears for conditions that recur, which operators reading src/docs/attention-episodes.md may want spelled out.

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

Conclusion: read pkg/attention/episodes.go, pkg/github/attention.go, the writeback/gate.go wiring and the callers on v5. The ledger/state machine does what the body says, the writeback gate and admitter check are re-applied immediately before the only CreateIssueComment (attention.go Post), and nothing on v5 calls ReportAttention yet, so merging changes no live behaviour. Two things worth a maintainer's eye before the consumer lands, and one sequencing question I can't settle.

1. Capacity is a one-way door (medium). Report hard-errors at MaxItems/MaxEpisodes = 4096 (episodes.go:265, :287) and nothing in Store ever deletes — resolved episodes, and the keyless episodes seeded from history markers at :267-279, stay forever. Items is keyed per repo#number, so 4096 distinct PRs/issues exhausts it; this repo alone is past 16k. attention-episodes.md:85 tells operators to "reconcile/archive old resolved inventory", but there is no API or CLI that archives, so the only remedy is deleting the file (full baseline reset). Fine for a pilot with zero producers; it needs a prune path before any producer with per-PR fan-out is routed in. Suggestion, not a blocker: drop Resolved episodes older than Window() on save().

2. Admitter handoff can double-page (medium, open question). History is consulted only when an item is first seen (:261, :267). A hive running as non-admitter initialises items and records WouldNotify episodes; pages the old admitter posts afterwards are never read back. When the config flips the owner to this hive, :329 passes and :364 posts — a second page for a condition the previous admitter already paged. The doc's handoff recipe ("preserve its ledger", attention-episodes.md:25) doesn't help here, because the ledger is a per-deployment file (gate.go:205-217). The doc does say cross-instance dedup is out of scope, so this may be accepted; if not, re-running History on the first Report after owner == hiveID becomes true would close it.

3. Cosmetic (low). A resolved observation continues at :310 before :321, so would_notify keeps its previous value on a Resolved episode. The status card skips Resolved, so this is ledger-only.

Body vs diff: consistent; the rollout-boundary paragraph accurately describes what is and isn't wired. CI is green bar tide.

I have not approved or blocked anything; the decision above is for a maintainer.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@mendezr this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Review asks:

  • the review swarm requested changes

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (2 waiting): fixes are handed out before new work as soon as you have capacity.

…d episodes

Address review findings on hivecommons#16291:

- Baseline only conditions whose key appears in trusted attention delivery
  history. A never-paged condition on a never-seen item now notifies on its
  first report instead of being permanently swallowed; History remains the
  replay guard after ledger loss. Drop the empty-inventory baseline contract
  from the adapter/doc comments and docs.
- Only hive:attention markers with an attempt ID count as delivery history.
  Status-card hive:condition markers (emitted for non-admitter and never-paged
  episodes) no longer seed baselines that would suppress a first page.
- Prune resolved, reconciled episodes once the flap window has passed so the
  4096-episode cap bounds live inventory instead of becoming a dead stop.
  Uncertain episodes and history-seeded baselines are retained.

Tests cover first-report paging, condition-marker-only history, and pruning.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>
@clubanderson

Copy link
Copy Markdown
Member

Pushed 536c74b to this branch (maintainer edits enabled) so it can land while @mendezr is away — original commits preserved with authorship. Addresses the review findings:

  1. First inventory swallowed — Baseline is now set only from trusted delivery history (Baseline: historical[hash]); a never-paged condition on a never-seen item notifies on first report. Dropped the empty-inventory baseline contract from ReportAttention/Report comments and docs/attention-episodes.md.
  2. Condition markers as delivery history — attentionKeyMarker now matches only hive:attention key=… attempt=…; status-card hive:condition markers no longer seed baselines.
  3. Capacity dead stop — Report prunes Resolved && !Uncertain episodes older than the flap window before capacity checks; uncertain and history-seeded entries are retained.

Tests: TestFirstReportOfNewItemPagesOnce, TestResolvedEpisodesPrunedAfterWindow, and the recovery tests reworked to use marker history instead of pre-seeding an empty report. go vet/go test/golangci-lint clean on pkg/attention and pkg/github. #16327 (mutex across GitHub calls) left as-is per the non-blocking note.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@mendezr this PR is back in your court (stage/072-returned-to-contributor). The hive will not merge it until the head changes.

Failing checks:

  • Sign-off survives the squash

Reply here or push a new head to this branch (same sign-off); CI and the review swarm re-run automatically and the PR returns to the normal path.

Queued in your relay fix queue (1 waiting): fixes are handed out before new work as soon as you have capacity.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Superseded by hive: re-authored as #16328 with the same commits and sign-off because the author's clanker is offline. This PR is closed; if #16328 fails, hive reopens it.

@hivecommons-hive hivecommons-hive Bot added the hive/superseded Closed by Hive: a different merged PR already landed this change label Nov 2, 2026
@hivecommons-hive hivecommons-hive Bot closed this Nov 2, 2026
clubanderson added a commit that referenced this pull request Nov 3, 2026
* ✨ feature: persist single-admitter condition episodes

Add opt-in per-repo attention ownership, durable producer-independent episodes, quiet baseline recovery, and exact-attempt reconciliation before uncertain POST retries. Keep existing writers, reviews, commands and holds unchanged for the separate pilot.

Hive-Run: #16267
Hive-Plan: RFC-16075/phase-3-condition-episodes
Hive-Spec: RFC-16075#2
Signed-off-by: mendezr <mendezr@users.noreply.github.com>

* 🐛 fix: align attention rollout with CI contracts

Signed-off-by: mendezr <mendezr@users.noreply.github.com>

* 🧪 test: cover attention recovery and fail-closed transitions

Signed-off-by: mendezr <mendezr@users.noreply.github.com>

* 🐛 fix: page never-delivered conditions on first report, prune resolved episodes

Address review findings on #16291:

- Baseline only conditions whose key appears in trusted attention delivery
  history. A never-paged condition on a never-seen item now notifies on its
  first report instead of being permanently swallowed; History remains the
  replay guard after ledger loss. Drop the empty-inventory baseline contract
  from the adapter/doc comments and docs.
- Only hive:attention markers with an attempt ID count as delivery history.
  Status-card hive:condition markers (emitted for non-admitter and never-paged
  episodes) no longer seed baselines that would suppress a first page.
- Prune resolved, reconciled episodes once the flap window has passed so the
  4096-episode cap bounds live inventory instead of becoming a dead stop.
  Uncertain episodes and history-seeded baselines are retained.

Tests cover first-report paging, condition-marker-only history, and pruning.

Signed-off-by: Andrew Anderson <andy@clubanderson.com>

* 📝 docs: link attention episodes page, separate top-level decls

Hive-Fix-Attempt: 1/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🐛 fix: reconcile uncertain resolved episodes, page first reopen, prune items

Hive-Fix-Attempt: 2/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🌱 chore(writeback): annotate status-comment forge plumbing for the direct-write ratchet

Merging v5 (#16319, #16321) moved the hive status comment's edit/create/
delete into prstatus.Forge adapters in automerge_stage_labels.go and
pr_status_comment.go without updating the write-back ratchet, so
TestDirectWriteRatchet failed on every PR's merge commit. Mark the forge
adapter calls writeback:gated — they are plumbing under prstatus.Write and
the write-back decision lives at the ratcheted entry points — and lower the
automerge_stage_labels.go baseline now that the old in-place edit is gone.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🌱 chore(notifications): inventory attentionDelivery.Post and the status-comment forge create

TestNotificationWriteSitesInventory (v5, #16321) flags two untagged
notification-capable writes on this branch's merge commit:
attentionDelivery.Post, this PR's condition-episode page (attention), and
clientStatusForge.CreateComment from #16319's status writer (status,
passthrough to its caller). Tag both and mirror the rows in
src/docs/notifications.md.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* fix(attention): mark acknowledged reopen quiet

Hive-Fix-Attempt: 3/6
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🐛 fix: expire stale history baselines and report status-comment writes as ungated

Hive-Fix-Attempt: 4/6

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 📖 docs: list attention-episodes.md in the documentation map and docs README

Closes #16330

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🌱 chore(settingsparity): collect pkg/attention so github.attention leaves are enumerated

Closes #16331

Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

* 🌱 chore: retrigger CI after transient npm registry outage

build/docker jobs failed in the Dockerfile cline install step with
"No matching version found for @ai-sdk/openai@4.0.108"; the version
is present on the registry, so this was a transient fetch failure.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>

---------

Signed-off-by: mendezr <mendezr@users.noreply.github.com>
Signed-off-by: Andrew Anderson <andy@clubanderson.com>
Signed-off-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Signed-off-by: scanner <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: mendezr <mendezr@users.noreply.github.com>
Co-authored-by: Andrew Anderson <andy@clubanderson.com>
Co-authored-by: architect <280983584+hivecommons-hive[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. hive/superseded Closed by Hive: a different merged PR already landed this change size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[scanner] Persist producer-independent condition episodes with single per-repo attention admitter and uncertain-POST reconciliation

2 participants