Skip to content

✨ feat(hub): surface "Pause hive" in the hub spoke dropdown menu - #15105

Closed
Karibhou wants to merge 2 commits into
hivecommons:v5from
Karibhou:feat/hub-spoke-pause-hive
Closed

Karibhou wants to merge 2 commits into
hivecommons:v5from
Karibhou:feat/hub-spoke-pause-hive

Conversation

@Karibhou

Copy link
Copy Markdown
Contributor

Summary

Adds a ⏸ Pause hive / ▶ Resume hive item to the per-hive dropdown in the hub's hive list (next to Contribute, API Docs, Permissions, Activity Timeline…), so an operator can pause a spoke without opening its dashboard.

No new pause mechanism: it drives the spoke's existing fleet breaker — the same EngageBreaker / ReleaseBreaker path as the spoke's own top-bar "running ⏸" button (/api/breaker/{engage,release}).

How it works

  • Hub — POST /api/saas/hives/{id}/breaker with {"engaged": true|false}. Owner-or-hub-admin (mirrors the spoke endpoints' owner gate). Queues the instruction durably on the SaaSHive record (pending_breaker, pending_breaker_by), logs an audit line and an Activity Timeline entry. A newer click replaces an undelivered older one.
  • Heartbeat — the next heartbeat response carries it once in HeartbeatResponse.Breaker ("engage"/"release") and the record is cleared (one-shot, like ResetAgentRestarts). Heartbeat is the only channel that reaches every spoke, including clusters the hub cannot touch. One-shot rather than desired-state so a later release done on the spoke itself is never re-engaged by the hub.
  • Spoke — new spoke.BreakerCallback wired in bootHeartbeatWith: engages/releases the breaker and writes the same breaker-engage/breaker-release dashboard audit entries; unknown values are logged and ignored. The run loop's regular persist makes the state durable.
  • Hub UI — label follows the current state, derived from agents reporting pausedTrigger === 'fleet-breaker' (already in heartbeats). Confirmation dialog explains it applies on the next heartbeat (≤ ~2 min).

Tests

  • pkg/hub/spoke_breaker_test.go: 404 / 403 non-owner / 400 bad bodies / owner queues engage, last click wins; one-shot delivery, unknown hive, invalid stored action never delivered.
  • cmd/hive/boot_heartbeat_deps_test.go: callback is registered (14 callbacks) and drives the real breaker engage → ignore bogus → release.

Other

  • src/docs/api-reference.md row for the new route; citations re-anchored with check-api-reference-citations.sh --fix (route insertion shifted saas.go lines).
  • gofmt normalized the HeartbeatResponse struct alignment in pkg/hub/heartbeat.go (was already misaligned on v5).
  • Changelog fragment changelog.d/added-15092-hub-pause-hive.md.

Note: the issue lists v6 as target; this PR targets v5 as assigned (purely additive change).

Closes #15092

🤖 Generated with Claude Code

https://claude.ai/code/session_01HRH6kkwbjSjorhcbXnoxg3

— hive: backend=claude model=claude-opus-5-5

Add a "⏸ Pause hive" / "▶ Resume hive" item to the per-hive menu in the
hub's hive list (owner or hub admin). It drives the spoke's existing fleet
breaker — the same EngageBreaker/ReleaseBreaker path as the spoke's own
top-bar "running ⏸" button — so no new pause mechanism is introduced.

- hub: POST /api/saas/hives/{id}/breaker {"engaged": bool} queues the
  instruction durably on the SaaSHive record (owner-or-admin gate,
  audit log + activity timeline entry)
- hub: the next heartbeat response carries it once in
  HeartbeatResponse.Breaker and clears it (one-shot, like
  ResetAgentRestarts)
- spoke: new BreakerCallback applies engage/release via the agent
  runtime and writes the dashboard audit entry
- dashboard: menu label follows breaker state, derived from agents
  whose pausedTrigger is "fleet-breaker"
- tests for the handler's authz/validation/queueing, one-shot delivery,
  and the boot callback driving the real breaker
- api-reference row for the new route (citations re-anchored)

Hive-Run: hivecommons#15092
Hive-Plan: hivecommons#15092 proposed solution
Hive-Spec: hivecommons#15092#proposed-solution
Co-authored-by: kanrenibm <91967876+kanrenibm@users.noreply.github.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HRH6kkwbjSjorhcbXnoxg3
Signed-off-by: Karibhou <157208370+Karibhou@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Oct 28, 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 Oct 28, 2026
@hivecommons-hive hivecommons-hive Bot added author/clanker A contributor's own hive authored this PR under their login dco All commits are DCO signed-off role/contributor Author holds the contributor tier in this hive's registry; a human must lgtm/approve stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 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
#15085 ✨ Activity Monitor: Adopt now and Reroute to another clanker for PRs waiting on a contributor's clanker same files src/cmd/hive/main.go
src/docs/api-reference.md
#15157 ✨ Conflict-aware merge train in the automerge lanes same files src/cmd/hive/main.go
#15134 🐛 Delegated decision on a capability gap: model the blocker, stop the un-park/re-park loop, name the missing App permission same files src/docs/api-reference.md
#15150 🐛 Activity Monitor: persist the merged count in a server ledger, pin the Merged chip, banner and bee flight on merge same files src/docs/api-reference.md
#15149 ✨ feat(automerge): pick one merge-train front per group of file-overlapping approved PRs same files src/cmd/hive/main.go
#15122 🐛 Write-back containment: per-kind gate for every unsolicited GitHub write, with backfill guard same files src/cmd/hive/main.go
src/docs/api-reference.md
#14807 ✨ dashboard: stream Job pod logs in the terminal pane for sandbox.runtime: job agents same files src/docs/api-reference.md

@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.

Read the tree at 65a353c, not just the diff. The design is sound; one check failure is caused by this diff and blocks it.

Blocking — TestStyleRatchet (test rest 3/4, coverage): pkg/dashboard/webstatic/style_ratchet_test.go:88 reports hub static pages has 942 style= attributes, above the baseline of 941. The extra one is the new menu item at src/pkg/hub/assets/dashboard.html:8717 (... style="' + mi + '">). The neighbouring items use the same mi string, so the ratchet is about the count, not the content: either give the dropdown items a class and drop the inline style= on this one (or on one existing item in the same menu), or convert one existing inline style elsewhere to tokens, per the test's message. The baseline must not be raised.

Verified correct (no action needed):

  • One-shot delivery holds: pendingBreakerForHeartbeat (spoke_breaker.go:67-89) load→clear→save is the same idiom as pendingAgentRestartResetsForHeartbeat (saas.go:552-574), and handleHeartbeat does not re-save the saasHive it loaded at server.go:2941 after line 3344, so the cleared record is not resurrected. resp.Breaker is set before signHeartbeatResponse (server.go:3344-3346), so it rides inside the signed response.
  • The spoke applies it only via the existing fleet-breaker path: main.go callback calls agentMgr.EngageBreaker() / ReleaseBreaker(ctx) (crux/api/client/client.go:514, 520), and the UI's state read (a.pausedTrigger === 'fleet-breaker') matches crux/pause.go:12 BreakerTrigger = "fleet-breaker", which the hub already serialises as pausedTrigger (hub/heartbeat.go:21).
  • Authorisation: owner-or-hub-admin at spoke_breaker.go:31. Note this is wider than handleRestartSpoke (admin-only, spoke_restart.go:155) but matches the spoke's own /api/breaker/* owner gate and the action is reversible; I think that is the right call, flagging it only so a maintainer sees it was deliberate.
  • The confirmation uses hiveConfirm (dashboard.html:3131), not a native dialog.

Could not run tests here (go test is blocked on agent hosts); the above is from reading the tree and the CI log.

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

@hivecommons-hive hivecommons-hive Bot added stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act and removed stage/050-review-pending Review swarm requested; awaiting a verdict for the current head labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Karibhou 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
  • test
  • test (rest 3/4)

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.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Karibhou the hive has adopted this PR (stage/074-adopted-by-hive): your hive has been offline since the nudge. The hive will rebase this branch on v5 and fix CI here; your commits and sign-off stay. Push a new head yourself at any time and the hive yields it back to you.

@hivecommons-hive hivecommons-hive Bot added stage/074-adopted-by-hive Contributor PR adopted: author unavailable after red CI; the hive is finishing it (takeover path) and removed stage/072-returned-to-contributor Contributor PR: CI red, changes requested or conflicting; diagnosis posted, author must act labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

CI: test (rest 3/4) fails on pkg/dashboard/webstatic.TestStyleRatchet — hub static pages now carry 942 style= attributes, one above the baseline of 941 (run 40773982744). The ratchet only allows the count to go down, so the new "Pause hive" menu item must not add an inline style=: move its inline styling into a class in the hub CSS (tokens) instead. coverage/test are red only because this shard failed. Head is in your fork, so this is a comment-only report; once it is green the sweep handles the rest.


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

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

…items

Review fix for the TestStyleRatchet failure: the new Pause/Resume menu
item pushed hub static pages to 942 inline style= attributes (baseline
941). Replace the ad-hoc `mi` inline-style string with a `.hive-menu-item`
class built from design tokens (--sp-3/--sp-5, --text, --fs-sm) and apply
it to every item in the spoke dropdown, including the new one. That drops
the surface to 930 style= attributes with no change to the raw color,
font-size, padding or border-radius counters, so the baseline is lowered
to 930 rather than raised.

Hive-Fix-Attempt: 2/6
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 size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Oct 28, 2026
@hivecommons-hive

Copy link
Copy Markdown
Contributor

@Karibhou the hive has adopted this PR (stage/074-adopted-by-hive): the hive's fix on this branch cannot carry a sign-off the squash merge accepts (the hive signs as the App, the squash lands as you). It is being finished as #15163, which carries your commits (and sign-off) unchanged; the hive will rebase and fix CI there. This PR is closed automatically once #15163 merges. If you would rather finish it yourself, push a new head here and say so on #15163.

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Closing: #15163 (the hive's adoption of this PR, with @Karibhou's commits) has merged. Thank you!

@hivecommons-hive hivecommons-hive Bot closed this Oct 28, 2026
@Karibhou
Karibhou deleted the feat/hub-spoke-pause-hive branch November 15, 2026 11:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

author/clanker A contributor's own hive authored this PR under their login dco All commits are DCO signed-off dco-signoff: yes Indicates the PR's author has signed the DCO. role/contributor Author holds the contributor tier in this hive's registry; a human must lgtm/approve size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. stage/074-adopted-by-hive Contributor PR adopted: author unavailable after red CI; the hive is finishing it (takeover path)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

✨ feature: (hub): surface "Pause hive" action in the hub spoke dropdown menu

1 participant