Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
2ccf4a9
✨ feature: persist single-admitter condition episodes
mendezr Nov 2, 2026
ff5de88
🐛 fix: align attention rollout with CI contracts
mendezr Nov 2, 2026
044c41d
🧪 test: cover attention recovery and fail-closed transitions
mendezr Nov 2, 2026
536c74b
🐛 fix: page never-delivered conditions on first report, prune resolve…
clubanderson Nov 2, 2026
e5e13a7
📝 docs: link attention episodes page, separate top-level decls
hivecommons-hive[bot] Nov 2, 2026
f825488
🐛 fix: reconcile uncertain resolved episodes, page first reopen, prun…
hivecommons-hive[bot] Nov 3, 2026
847ecfb
Merge remote-tracking branch 'origin/v5' into hive/adopt-16291
hivecommons-hive[bot] Nov 3, 2026
eebe6ed
🌱 chore(writeback): annotate status-comment forge plumbing for the di…
hivecommons-hive[bot] Nov 3, 2026
642e526
🌱 chore(notifications): inventory attentionDelivery.Post and the stat…
hivecommons-hive[bot] Nov 3, 2026
e1aef49
fix(attention): mark acknowledged reopen quiet
hivecommons-hive[bot] Nov 3, 2026
a6adc08
Merge branch 'v5' into hive/adopt-16291
hivecommons-hive[bot] Nov 3, 2026
19356b2
Merge origin/v5 into hive/adopt-16291 (resolve ratchet baseline and n…
hivecommons-hive[bot] Nov 3, 2026
3e588f6
Merge remote-tracking branch 'origin/v5' into sync-adopt-16291
hivecommons-hive[bot] Nov 3, 2026
1b2a631
🐛 fix: expire stale history baselines and report status-comment write…
hivecommons-hive[bot] Nov 3, 2026
53e7367
📖 docs: list attention-episodes.md in the documentation map and docs …
hivecommons-hive[bot] Nov 3, 2026
1d4c0be
🌱 chore(settingsparity): collect pkg/attention so github.attention le…
hivecommons-hive[bot] Nov 3, 2026
f95df3d
🌱 chore: retrigger CI after transient npm registry outage
hivecommons-hive[bot] Nov 3, 2026
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/added-condition-episodes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- Add an opt-in, per-repo single-admitter attention primitive with durable condition episodes, quiet recovery, and uncertain-POST reconciliation; existing quiet-mode writers and review/hold behavior remain unchanged.
2 changes: 2 additions & 0 deletions src/cmd/hive/github_client_config.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
cruxconfig "github.com/hivecommons/hive/crux/config"

"github.com/hivecommons/hive/crux"
"github.com/hivecommons/hive/pkg/attention"
"github.com/hivecommons/hive/pkg/authorkind"
"github.com/hivecommons/hive/pkg/beads"
"github.com/hivecommons/hive/pkg/claims"
Expand Down Expand Up @@ -109,6 +110,7 @@ func (b *boot) applyGitHubClientConfigHooks(client *github.Client) {
// one process-wide write-back gate (pkg/writeback); a rebuilt client
// must inherit it or the sweeps regress to ungated.
client.SetWritebackGate(b.writebackGate())
client.SetAttention(b.cfg.HiveID, func() attention.Config { return b.cfg.GitHub.Attention })
client.SetSentinelAlertLabel(b.cfg.Sentinel.LabelOrDefault())
// Evaluated heads persist so a restart or rebuild neither re-diffs every
// open PR nor blanks the Matrix feed until the next sweep (#16276).
Expand Down
1 change: 1 addition & 0 deletions src/docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ A terminal agent is a power tool: you hold it, aim it, and it stops when you sto
- [Integrations](integrations.md) — backends, trackers, forges and sandboxes Hive works with, at a glance.
- [Getting started](getting-started.md)
- [Operator reference](operator-reference.md)
- [Attention episodes](attention-episodes.md) — single-admitter condition episodes, flap window, and the `github.attention` rollout controls.
- [GitHub webhooks: cadence, patch and reconcile](webhooks.md) — polling fallback, webhook patch and reconcile, and the state-accuracy guarantees.
- [Dashboard sections explained](dashboard-sections.md) — what each dashboard section shows and what to do about it.
- [Activity monitor copy inventory](dashboard-copy-inventory.md) — every operator-visible string builder in the activity monitor, with before/after word counts and the hover budget.
Expand Down
93 changes: 93 additions & 0 deletions src/docs/attention-episodes.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# Condition episodes and attention admission

The opt-in condition delivery primitive for RFC #16075 / #16267 reuses the
writeback gate and `hive:status`. It does **not** migrate existing note producers,
change quiet mode, or enable the issue-side pilot (#16270). The authoritative
status writer (#16263) is a prerequisite to enabling concurrent producer routing.
No review, machine command, security hold or merge hold is changed. An
acknowledgement is not approval.

## Configuration

```yaml
github:
attention:
admitter:
hivecommons/hive: hosted-hive-id
flap_window: 12h
```

Keys must be fully qualified repositories. Exactly one deployment may own the
configured hive ID for a repo. Other hive IDs record **would notify** and update
status only; they cannot create attention events. This is explicit single-owner
admission, **not** a distributed lock or atomic GitHub list-before-create scheme.
Do not clone an admitter's identity into another active deployment. During
handoff, stop the old admitter before starting the new one, preserve its ledger,
and reconcile its uncertain attempts before changing the configured owner.
Unknown-owner uncertain attempts remain visible and are not automatically retried.

Unset/empty `admitter` means this new path does nothing, without opening a ledger
or changing today's quiet-mode delivery. The default flap window is 12 hours.
There is no reminder or per-recipient budget in this layer (#16270 / #16271).

## Producer contract

`github.Client.ReportAttention` takes the full current condition inventory for
one item, a writeback item/kind, and structured observations. All reporters must
use the same action class, responsible recipient and subject, independent of
producer. Do not derive identities from comment prose:

- CI: `attention.CISubject(requiredJobName, normalizedErrorClass)`. The caller
classifies errors; run IDs and head SHAs belong in evidence only.
- Sentinel/security: `attention.FindingSubject(findingidentity.Record)` reuses the
existing subject/predicate/location identity, without head SHA.
- Holds/decisions: `attention.DecisionSubject(requiredDecisionID)`.

A materially different risk, action or owner changes the key. Consequently a
new urgent finding does not share a previous finding's delivery budget. The
attention body is supplied by the producer (the action contract belongs to
#16270); this API must not be used for arbitrary untrusted/protocol text.

Repeated reports update `last_seen` and evidence, not the episode or delivery.
Explicit resolved observations close episodes; absence from an inventory is not
proof of recovery. Within the flap window, recovery/reappearance reopens quietly.
After that window a recorded recovery followed by recurrence starts a new episode.
`Store.Update` records acknowledgement, snooze or resolution; it has no access to
holds, permissions or reviews.

## Recovery and delivery

The ledger lives beside the writeback state (`writeback.json.attention`, following
`HIVE_WRITEBACK_STATE_PATH`), uses a versioned JSON schema and fsync/atomic rename,
and is shared by clients using the process-wide writeback gate. Save failures
fence POSTs. Unknown schema versions fail closed instead of being overwritten.

The first **complete inventory per item** consults delivery history: list trusted
Hive attention comments (status-card condition markers do not count) and seed any
matching current condition without sending. A condition with no prior attention
comment notifies on its first report, so ledger loss never swallows a genuinely
new risk and never replays an already-paged one. Do not send partial producer
snapshots during recovery: aggregate the item's known conditions before calling
this API. Conditions seeded from history are marked uncertain for human
reconciliation in the status section. This deliberately chooses no historical
replay over guessing which unrecorded old incident deserves another page.

Before POST, persist a random attempt ID and its owner. Comments carry
`<!-- hive:attention key=<hash> attempt=<id> -->`. After any ambiguous failure or
restart with an unfinished attempt, paginate comments and look for that exact
trusted marker before retrying. A lookup failure never permits a retry; a found
attempt becomes notified without another POST. An absent attempt retries with
the **same** ID, even if evidence/body changed. This reconciliation is only for
the single admitter's own attempts, not cross-instance deduplication. The existing
mutation journal remains in the GitHub write path as an additional safeguard.

The file is bounded to 4096 episodes and 4096 initialized items. Resolved
episodes are pruned once the flap window has passed (recurrence would start a
fresh episode anyway); uncertain episodes and history-seeded baselines are kept.
Capacity errors fail closed and retain history instead of evicting an active
incident and replaying it. Operators must reconcile/archive inventory before
resetting a full ledger; a reset re-enters baseline recovery, never an automatic
re-page. Status displays up to 20 active conditions with an overflow count; all
records remain in the ledger. Status includes owner/action, last evidence,
acknowledged/snoozed state and uncertain/would-notify indicators, with copied
mentions neutralized. This is a queue snapshot, not an unbounded transcript.
1 change: 1 addition & 0 deletions src/docs/documentation-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,7 @@ Documentation for the current Hive line (branch `v5`; the code and docs live und
- [Security notes](security.md) — log scrubbing and secret redaction guarantees/limits.
- [Token collection and usage tracking](token-tracking.md) — session JSONL, `/api/cost`, and hub usage rollups.
- [Notifications](notifications.md) — ntfy, Slack, and Discord alert channels, plus the two-way [Discord bot](../../discord/README.md).
- [Attention episodes](attention-episodes.md) — single-admitter condition episodes, flap window, and the `github.attention` rollout controls.
- [State-triggered hooks](hooks.md) — declarative `transition → action` rules, the transition catalog, the vetted action set, and the security model (RFC #4001).
- [CEL-based agent triggers](cel-triggers.md) — the `triggers:` config key: declarative CEL rules that kick an agent on a normalized source-control event, additive to built-in label/governor triggering, the `event.*` field reference, and the fail-closed compile/runtime contract.

Expand Down
3 changes: 2 additions & 1 deletion src/docs/notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -414,7 +414,7 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).PostNoteOrFold` | `status` | passthrough wrapper; attributed to its caller |
| `github.(*Client).SweepLegacyFleetReportIssues` | `status` | |
| `github.(*Client).UpsertIssueMarkerComment` | `status` | passthrough wrapper; attributed to its caller |
| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (prstatus.Write status-comment creation); attributed to its caller |
| `github.(*clientStatusForge).CreateComment` | `status` | passthrough wrapper (status-comment forge under `prstatus.Write`); attributed to its caller |
| `github.(*Client).closeDecomposedParent` | `status` | |
| `github.(*Client).closeIssueForMergedPRClaimWithIssue` | `status` | |
| `github.(*Client).closeSupersededPRDecision` | `status` | |
Expand Down Expand Up @@ -449,6 +449,7 @@ without a class. Review submissions and review requests are always counted as
| `github.(*Client).parkClankerRequestedPR` | `attention` | |
| `github.(*Client).redirectToExistingPR` | `attention` | |
| `github.(*Client).resolveDuplicateFixGroup` | `attention` | |
| `github.attentionDelivery.Post` | `attention` | condition-episode page; live write-back policy rechecked before the write |
| `main.(*repoForgeRouter).CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller |
| `main.claimEscalationLookup` | `attention` | |
| `main.liveTriageCommenter.CreateIssueComment` | `attention` | passthrough wrapper; attributed to its caller |
Expand Down
1 change: 1 addition & 0 deletions src/internal/settingsparity/settingsparity.go
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ func ConfigLeaves(repoRoot string) ([]Leaf, error) {
filepath.Join("crux", "config"),
filepath.Join("pkg", "dashboard", "theme"),
filepath.Join("pkg", "writeback"),
filepath.Join("pkg", "attention"),
} {
if err := c.collect(fset, repoRoot, rel); err != nil {
return nil, err
Expand Down
21 changes: 21 additions & 0 deletions src/internal/settingsparity/settingsparity_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,27 @@ func TestConfigLeavesRealRepo(t *testing.T) {
}
}

// github.attention is typed attention.Config (pkg/attention); its sub-keys
// must be enumerated rather than collapsing into one opaque leaf.
func TestConfigLeavesRealRepoEnumeratesAttention(t *testing.T) {
leaves, err := ConfigLeaves(filepath.Join("..", "..", ".."))
if err != nil {
t.Fatalf("ConfigLeaves on the real repo: %v", err)
}
got := map[string]bool{}
for _, leaf := range leaves {
got[leaf.Path] = true
}
for _, want := range []string{"github.attention.admitter.<key>", "github.attention.flap_window"} {
if !got[want] {
t.Errorf("leaf %q must be enumerated", want)
}
}
if got["github.attention"] {
t.Error("github.attention must not be an opaque leaf")
}
}

func TestAllowlist(t *testing.T) {
path := filepath.Join(t.TempDir(), "allow.txt")
writeFile(t, path, "# header comment\n\n a.b \nc.d # why it is allowed\n")
Expand Down
58 changes: 58 additions & 0 deletions src/pkg/attention/config_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
package attention

import (
"os"
"path/filepath"
"testing"
"time"

"github.com/hivecommons/hive/pkg/findingidentity"
)

func TestConfigValidation(t *testing.T) {
for _, cfg := range []Config{
{FlapWindow: -time.Second},
{Admitter: map[string]string{"repo": "owner"}},
{Admitter: map[string]string{"o/r": ""}},
{Admitter: map[string]string{"o/r": "one", "O/R": "two"}},
} {
if err := cfg.Validate(); err == nil {
t.Fatalf("accepted ambiguous config: %+v", cfg)
}
}
if err := testConfig.Validate(); err != nil {
t.Fatal(err)
}
if (Config{}).Window() != 12*time.Hour || (Config{FlapWindow: 6 * time.Hour}).Window() != 6*time.Hour {
t.Fatal("flap defaults")
}
if testConfig.Owner("ORG/REPO") != "owner" || testConfig.Owner("repo") != "" {
t.Fatal("owner must match full repo")
}
}

func TestFindingIdentityUsesExistingKey(t *testing.T) {
r := findingidentity.Record{SubjectDigest: "subject", Predicate: "security", Location: "pkg/file.go:12"}
want := findingidentity.Key(r)
if FindingSubject(r) != want {
t.Fatal("finding identity changed")
}
r.Location = "pkg/file.go:25"
if FindingSubject(r) != want {
t.Fatal("new head line number split episode")
}
r.Predicate = "urgent-new-risk"
if FindingSubject(r) == want {
t.Fatal("new risk collapsed")
}
}

func TestUnknownVersionDoesNotOverwrite(t *testing.T) {
path := filepath.Join(t.TempDir(), "state")
if err := os.WriteFile(path, []byte(`{"version":2,"items":{},"episodes":{}}`), 0600); err != nil {
t.Fatal(err)
}
if _, err := Open(path); err == nil {
t.Fatal("future ledger version accepted")
}
}
Loading
Loading