feat(ui): last-refresh meta + manual refresh on the analytics and maintainer headers

[reyanthony062001-ops]

Summary

• Adds a shared RefreshMeta primitive (apps/gittensory-ui/src/components/site/refresh-meta.tsx): a last refresh Xm ago label plus a manual refresh button, reusing StateActionButton + the RefreshCw icon already used by StateBoundary's refresh affordances so the control reads consistently.
• Adds the pure relativeTimeFromNow(timestampMs, nowMs) helper to apps/gittensory-ui/src/lib/utils.ts with unit tests across every bucket boundary (seconds → minutes → hours → days) and a clamp for marginally-future timestamps.
• Extends useApiResource with a loadedAt stamp (set when a load succeeds, null while loading/on error/disabled) so headers can show refresh recency without any new fetch plumbing; reload is unchanged and is what the button calls.
• Adopts it on the analytics header pill row (app.analytics.tsx) and on the maintainer dashboard header row. The maintainer adoption lives at the top of MaintainerDashboardView (in maintainer-panel.tsx) rather than the route's PageHeader because the maintainer resource is created behind the session/role check inside the panel — the route header renders before any data exists to describe.
• The label re-renders on a coarse 30s interval (cleared on unmount) so it stays honest without a per-second timer; RefreshMeta renders nothing until the first successful load since the loading/error/empty states already carry their own retry/refresh affordances in StateBoundary.

Scoped to the dashboard headers only, per the issue — no StateBoundary refactor.

Closes #2219

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked a currently open issue this PR resolves (e.g. Closes #123) — a linked open issue is required for every contributor PR.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

If any required check was skipped, explain why:

• None skipped — full npm run test:ci run locally. The diff is confined to apps/gittensory-ui/** (Codecov-exempt paths); the new helper, hook field, and component are still fully unit-tested (11 new cases: every relative-time bucket boundary + future-clamp, loadedAt on success/error/disabled, label tick, refetch-on-click, disabled-while-refreshing, null-before-first-load, interval cleanup).

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

UI Evidence

State / title	Before	After
/app/analytics header — refresh meta joins the status pill row	before: pills only, no refresh affordance	after: last refresh just now + Refresh button beside the boundary badge
/app/maintainer — dashboard header row above the metric cards	before: metrics start with no refresh recency	after: right-aligned last refresh meta + Refresh above the cards

Notes

• Loading/error/empty states intentionally show no RefreshMeta — StateBoundary already renders retry/refresh there; this control only describes a successfully loaded dashboard.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[gittensory-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-10 15:26:31 UTC}

7 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a shared RefreshMeta primitive plus a pure relativeTimeFromNow helper, wires a loadedAt stamp through useApiResource, and adopts the label/refresh control on the analytics and maintainer headers, closing #2219. The state-machine change to useApiResource is correct (loadedAt stamped only on success, null for loading/error/disabled) and the new tests exercise real bucket boundaries and the loadedAt lifecycle rather than fabricated states. The change is narrow, reuses StateActionButton/RefreshCw as described, and doesn't touch StateBoundary itself.

Nits — 5 non-blocking

• refresh-meta.tsx:26 hardcodes the 30_000ms tick interval inline; naming it as a constant (e.g. `TICK_MS`) would make the coarse-refresh intent easier to spot on future edits.
• utils.ts:15-20 repeats the 60/60/24 unit conversions as bare literals; extracting SECONDS_PER_MINUTE/MINUTES_PER_HOUR/HOURS_PER_DAY constants would make the boundary logic self-documenting.
• maintainer-panel.tsx's RefreshMeta usage doesn't pass a `refreshing` prop (unlike app.analytics.tsx isn't shown either) — worth confirming whether the maintainer dashboard has an in-flight reload signal to wire up, or note explicitly why it's omitted.
• The 30s re-render tick in refresh-meta.tsx runs even when the tab is backgrounded; not worth a visibilitychange guard for a label this coarse, but flagging in case a reviewer expects it.
• Consider exporting the bucket thresholds (60/3600/86400 seconds) as named constants in utils.ts for readability, per the nit above.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2219
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 30 registered-repo PR(s), 19 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	reyanthony062001-ops; Gittensor profile; 30 PR(s), 1 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The diff adds the RefreshMeta primitive, a pure relativeTimeFromNow helper with boundary-covering unit tests, wires loadedAt/reload into useApiResource, and adopts the control in both the analytics header and the maintainer dashboard header (via MaintainerDashboardView rather than the route file itself, with a stated rationale), plus click-triggered refetch tests.

Review context

• Author: reyanthony062001-ops
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Cuda, HTML, Python
• Official Gittensor activity: 30 PR(s), 1 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

Visual preview

Route	Viewport	Before (production)	After (this PR's preview)	Diff
/app/analytics	desktop			—
/app/analytics	mobile			—

Click any thumbnail to open the full-size screenshot. Before = production · After = this PR's preview deploy.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[gittensory-orb]

Gittensory approves — the gate is satisfied and CI is green.