Repository navigation
Description
Held RFC. This is a design proposal for discussion. It carries hold so no hive agent picks it up until maintainers settle Decisions for maintainers. It is one of three related Activity Monitor RFCs: this one (wall display mode), #15861 (hub-wide activity monitor) and #15862 (Matrix code-rain mode). Each one stands alone; this RFC supplies the display shell the other two reuse.
| Field | Value |
|---|---|
| Status | Proposal, not accepted |
| Target | v5 (dashboard SPA). Part C (display credential) could instead go to v6 (Decision 2) |
| Scope | src/pkg/dashboard/static-src/js/boot.js, css/kiosk.css, the pop-out code from #15830 (js/tracker-popout.js, css/popout.css), dashboard auth (read-only viewer role), src/deploy/stream/authproxy |
| Out of scope | Sections other than the Activity Monitor; a Grafana plugin; any change to what ?kiosk=1 renders for the headless streamer |
| Builds on | #15594 / #15596 (?kiosk=1, shipped), #15829 / #15830 (⧉ Pop out, ⛶ Full screen, open), #15846 (streamer proxy limited to GET/HEAD), #15804 (roll/upgrade animation), src/docs/streaming-the-activity-monitor.md |
Summary
People want the Activity Monitor on a TV or a spare monitor, the way teams put Grafana on a wall. Most of the pieces exist. ?kiosk=1 hides the dashboard chrome, but nothing in the UI reaches it. #15830 adds a pop-out window and a full-screen toggle. What is still missing is everything a display needs to run unattended for weeks:
- a way into kiosk mode and back out from the UI;
- views a URL can describe;
- an honest signal when the data is stale;
- rotation between views;
- a credential that is safe to leave on a TV.
None of this changes what the default dashboard renders.
What exists today (v5 be04a9cb4)
| Capability | Today | Gap on a wall |
|---|---|---|
| No chrome | ?kiosk=1 (boot.js:19, css/kiosk.css) hides the sidebar, topbar, notices, Welcome, NPS and chat, and hides the cursor. Dark unless &theme=light; &sound=off |
Only reachable by editing the URL |
| Own window / full screen | #15830: ⧉ → ?popout=1, ⛶ → Fullscreen API |
Not kiosk, nothing persists |
| Filter state | localStorage hive-activity-monitor-filter |
Shared by every tab on one browser profile; a URL can't say "PRs only, repo X, grouped by repo" |
| Liveness | SSE stage-tracker frame on /api/events, plus a ~30 s poll of /api/stage-tracker |
When SSE or the spoke dies, the last frame keeps looking live |
| Credential | Owner bearer behind the streamer's GET/HEAD proxy (#15846), or a person's GitHub token on the public route | Nothing revocable, scoped to a display, or auditable per screen |
Design
A. Display mode (client only)
-
Getting in and out. A third header button, 📺 Display, sits next to ⧉ and ⛶. It adds
kiosk=1to the current URL, so the existing kiosk CSS applies, then requests full screen andnavigator.wakeLock.request('screen'). All three steps are best-effort, and a refusal stays silent.Esc, or the overlay's Exit display, removeskiosk=1.dtoggles display mode while focus is in the tracker. -
Overlay. Moving the mouse shows a small overlay with Exit display, Copy display link and View settings. It hides again after 3 s idle. The headless streamer has no pointer, so it never sees the overlay.
-
URL state. Each tracker filter maps to a namespaced parameter:
am.kind,am.repo,am.q,am.age,am.author,am.sort,am.dir,am.group. If anyam.*parameter is present, it wins overlocalStorage, and display mode never writes it back, so two screens on one profile cannot clobber each other. Copy display link serialises the current view into a URL. -
TV layout (
density=tv). Larger type, and only the stage, title and actor columns. Rows are capped to the viewport with a "+N more" footer instead of pagination. -
Honest liveness. The header shows the hive name, a clock and a live dot. The board dims and reads Stale: last update 4 m ago when either:
- SSE has been down for more than 2× the poll interval, or
generated_atis older than 2×cache_ttl_s.
It reloads on a backoff after repeated reconnect failures, and when a roll is announced (reusing the ✨ Show the upgrade animation for every roll (announce + SIGTERM fallback) #15804 signal).
-
Burn-in (
shift=1, off by default). A 1–2 px content shift every few minutes, for OLED panels. -
Motion.
prefers-reduced-motionturns off movement animations in display mode, as the existing CSS already does for toasts.
B. Playlists
?kiosk=1&playlist=<view>,<view>&interval=60s rotates through views. A view is one of:
- a tracker preset (an
am.*set); - the hub-wide monitor (📝 RFC: Hub-wide Activity Monitor with per-hive aggregation #15861);
- Matrix mode (📝 RFC: Activity Monitor Matrix mode — ambient code rain of the lines hive is pushing #15862).
Until those two land, playlists rotate presets, for example needs a human → in CI → merged today. A one-character progress bar shows time to the next view.
C. Display credential (server)
-
Minting. The owner mints a display credential in Settings, or with
hivectl display create --name lobby-tv. It is stored hashed and listed with last-seen time and IP. It can be revoked on its own. Mint, revoke and first use go to the audit log. -
Scope. The credential maps to the dashboard's existing read-only viewer role, then narrows it further:
GET/HEADonly;- an allow-list of
/, static assets,/api/theme.css,/api/stage-tracker, and/api/eventsfiltered to display frames; - never pane output (
paneTailViewerstays false), settings or row actions.
The tracker renders without the ⋯ / right-click menus.
-
Pairing without a token in the URL. This works like a device code. The TV opens
/displayand shows a short code. The owner approves the code in Settings. The TV then receives an HttpOnly cookie bound to that credential. Headless capture keeps header injection:src/deploy/stream/authproxyswaps the shared owner bearer for a display credential.
D. Terminal parity (v6)
The v6 line keeps dashboard features reachable without the dashboard. For that, hivectl tui --display would be a read-only, full-screen board view with no key bindings that mutate. It uses the same credential.
Security
- Parts A, B and D change rendering only.
- Part C reduces exposure. Today an unscoped owner token sits on the streaming box, and only the proxy keeps it read-only. A display credential is read-only on the server, revocable per screen, and audited.
- The private-repository warning in
streaming-the-activity-monitor.mdstill applies, and the display mode docs repeat it.
Acceptance
- A.
- 📺 enters display mode and
Escleaves it. - A copied display link reproduces the exact filter set in a fresh profile.
- Killing the spoke dims the board within 2× the poll interval.
- Without the new parameters, the dashboard renders exactly as it does today, and the existing tracker and kiosk tests still pass.
- 📺 enters display mode and
- B. A two-view playlist alternates at the given interval and survives an SSE reconnect.
- C.
- A display credential gets 403 on any
POSTand on/api/config. - Revocation takes effect on the next request.
- The authproxy runs with a display credential and no owner token.
- A display credential gets 403 on any
changelog.d/added-*fragment per part.
Alternatives
- Grafana on
/api/stage-tracker(JSON data source, or Prometheus gauges per stage). Useful as a complement. But a table loses what makes the tracker worth watching: rows moving through stages, merge toasts, sounds. - Keep the owner bearer behind the proxy. It works in-cluster. But one leaked box is an owner credential, and it doesn't help a TV on office Wi-Fi.
- OS or browser kiosk only. That covers full screen, but not URL state, liveness or credentials.
Decisions for maintainers
- Presets. URL only, or also named presets under
dashboard.display.presetsinhive.yaml? - Display credential. A new spoke credential on v5? Or wait for the v6 auth work? Or lean on hub viewer accounts (a read-only GitHub user on the public route) instead?
- Pairing. Device-code approval (proposed), or a one-time pairing URL?
- Full screen and wake lock. Should 📺 request them automatically, or should they stay separate toggles?
Activity
hivecommons-hive commentedon Oct 31, 2026
Parking on
stage/045-needs-decision: this RFC is marked Proposal, not accepted and its body says it should carryholduntil the Decisions for maintainers are settled, but the label was never applied, so it landed in the actionable queue. The hive will not implement an unaccepted design that adds a new display credential and pairing flow.Risk: credentials / security posture (Part C mints a new long-lived display credential and a device-code pairing path).
Maintainer question — pick one and the hive proceeds:
Reply
/hive decision A|B|C(or/hive approvefor A). Related: #15861, #15862.— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88
hivecommons-hive commentedon Oct 31, 2026
What to reply
/hive approve: go with the recommendation/hive decision <your instructions>: go ahead, following your instructions/hive help: show these againIf what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply
/fixedto close it as completed; Hive clears its park labels.Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.
clubanderson commentedon Oct 31, 2026
/hive decision Proceed with a bounded v5 display-mode implementation. Start with URL-based presets; defer persisted named presets until usage justifies them. Use existing authenticated read-only viewer access and preserve per-user authorization; do not introduce a new display credential or pairing protocol in this increment. Defer device-code versus pairing-URL work to the auth design. Full screen and wake lock must be separate explicit user controls, with graceful unsupported/denied states, not automatic requests. Preserve existing headless ?kiosk=1 behavior. No public exposure of private activity, no new mutation privileges, and no changes to the ordinary Activity Monitor layout or flow when display mode is off. Reuse the existing pop-out/full-screen shell. This authorizes source implementation, not live access/configuration changes.
hivecommons-hive commentedon Oct 31, 2026
Un-parked by @clubanderson. Decision: Proceed with a bounded v5 display-mode implementation. Start with URL-based presets; defer persisted named presets until usage justifies them. Use existing authenticated read-only viewer access and preserve per-user authorization; do not introduce a new display credential or pairing protocol in this increment. Defer device-code versus pairing-URL work to the auth design. Full screen and wake lock must be separate explicit user controls, with graceful unsupported/denied states, not automatic requests. Preserve existing headless ?kiosk=1 behavior. No public exposure of private activity, no new mutation privileges, and no changes to the ordinary Activity Monitor layout or flow when display mode is off. Reuse the existing pop-out/full-screen shell. This authorizes source implementation, not live access/configuration changes.
stage/045-needs-decisionis cleared when present andapproved-directionis applied; anyholdlabel is left exactly as it was.14 remaining items
hivecommons-hive commentedon Oct 31, 2026
PR #15969 covers this issue: #15969
The PR body says this is partial/non-closing work (
Refs/Part ofor leave-open wording), so Hive will not add a closing keyword. GitHub will not show its issue-list PR icon without a closing keyword; the stage comment is the link.hivecommons-hive commentedon Oct 31, 2026
All children delivered: #15924 → PR #15948, #15925 → PR #15948, #15929 → PR #15969, #15930 → PR #15970, #15931 → PR #15970, #15932 → PR #15969.
Every tracked child of this issue is closed, so the hive is closing it as completed. Reopen it if something it asked for is still missing.
github-actions commentedon Oct 31, 2026
@hanthor this issue was closed by @hivecommons-hive[bot] as completed.
If this was closed by a merged PR, the fix only takes effect once it ships in a tagged release and your deployment updates to it — check your running version against the fix before concluding the fix failed.
If you are still seeing the problem, comment
/reopenand it will be reopened for you — you do not need write access. Please add what you are still observing (running version, logs, steps) so it is not closed the same way again.✨ feature(hub): wire the Fleet activity page into display mode
✨ feature(hub): wire the Fleet activity page into display mode (#16088)