feat(webui): system-health dashboard (Closes #639) #862
Merged
sysadmin
merged 5 commits from 2026-07-24 06:28:47 -05:00
feat/issue-639-webui-system-health-dashboard into master
Labels
Clear labels
allocator
anti-stomp
architecture
bug
chore
codex
concurrency
contamination
control-plane
dashboard
database
design
documentation
enhancement
gitea
glitchtip
important
incident
incident-bridge
integration
jenkins
labels
leases
mcp
mcp-health
mcp-menu
multi-project
mutating
nice-to-have
observability
portability
preflight
protected-branch
queue
read-only
reconnect
recovery
refactor
release
reliability
resumable-review
reviewer
roadmap
safety
security
self-hosted
sentry
stale-runtime
status:blocked
status:in-progress
status:pr-open
status:ready
terminal-lock
testing
tracker
type:bug
type:feature
type:feature
type:guardrail
visibility
workflow
workflow-hardening
workflow-hardening
Controller-owned work allocator
Prevent concurrent LLM session stomping
Architecture / structural design
OpenAI Codex client / workflow session surface
Concurrent session safety
Workflow or session contamination incident
MCP control-plane coordination and allocation authority
MCP operational dashboard/queue view
Internal coordination storage (SQLite/Postgres)
Design / investigation, no implementation
Docs / runbooks
New feature or improvement
Gitea MCP workflow
GlitchTip integration
Operational or process incident requiring durable audit trail
Sentry-to-Gitea incident bridging
Integration testing
Jenkins integration
Label taxonomy management
Lease adopt/release/expire lifecycle
MCP server / tooling
MCP namespace and runtime health
MCP menu surface
Work spanning multiple monitoring projects or Gitea repos
Mutating action; requires gating
Observability, metrics, traces, error reporting
Cross-platform / portability
Shared preflight gates before mutation
Protected branch / stable-branch policy concern
Work queue visibility and allocation
Read-only, no mutation
MCP client reconnect/reload recovery path
Recovery paths for stale/foreign leases
Code refactor / restructure
Release / versioning
Reliability / failure handling
Persist and resume prepared review verdicts across sessions
Reviewer workflow tooling
Roadmap / umbrella issue
Safety rails and fail-closed mutation guards
Security / trust boundary
Self-hosted infrastructure integration
Sentry error monitoring integration
Stale backend daemon / runtime-vs-master parity failures
Issue is blocked
Issue is being worked on
Issue has an open pull request
Issue is ready for work
Terminal review lock (#332) path
Tests / test coverage
Issue tracker hygiene / meta
Bug or defect
Feature or enhancement
Feature or enhancement
Safety gate or guardrail
Workflow state visibility for LLMs/operators
Cross-tool workflow
LLM workflow coordination hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: Scaled-Tech-Consulting/Gitea-Tools#862
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Closes #639
Phase 1 child of the Web Console epic #631. Operators had no surface showing runtime readiness, so runtime problems surfaced late through failed LLM sessions instead of through a dashboard. This adds the read-only operator dashboard on top of the #634 system-health API.
What this adds
webui/system_health_views.py(new, 307) — renders theSystemHealthSnapshotas seven cards: overall readiness, stale-runtime parity, version and uptime, dependency probes, MCP namespaces, probe errors (only when present), and recovery pointers.webui/app.py(+20) —GET /system-health, sharingload_system_health()with the JSON API so the page and the API cannot disagree.?deep=1opts into the network probe exactly as the API does; the plain page load stays cheap.webui/nav.py(+1) andwebui/layout.py(+19) — nav entry under Health, plus health card and badge styles.tests/test_webui_system_health_dashboard.py(new, 345) — 26 cases over healthy, degraded, stale, unproven, and probe-error fixtures.docs/webui-local-dev.md(+32) — route table entry, field authority, redaction split, and the read-only statement.6 files, 724 insertions, 0 deletions.
Acceptance criteria
render_system_health_page— readiness, version/uptime, dependencies, namespaces, parity_dependency_carddegraded banner plus per-probe status column_stale_runtime_cardwarning block above the parity tabletests/test_webui_system_health_dashboard.pywebui/nav.pyHealth groupNon-goals honored: no restart or reload control, and no manual process-kill guidance. The recovery card points at the sanctioned client reconnect path and states plainly that killing the daemon by hand is recorded as runtime contamination (#630).
Honesty rules the page enforces
readyandreadiness_completerender separately. A snapshot whose required probes never ran differs from one that ran them and passed, and collapsing the two would paint an unproven green.stale_runtime.mutation_safeis displayed verbatim. When the runtime is stale, or when parity is indeterminate, the page warns and does not claim mutation safety.unproven: the web process runs outside the IDE-managed MCP client and cannot prove that path (#543).Redaction
Split by field kind. Free text — probe details, readiness and parity reasons, probe errors — passes through
system_health.redactbefore escaping. Structured fields — commit SHAs, probe names, statuses, timestamps — are HTML-escaped only, becauseredact's opaque-token rule matches any run of 32 or more characters and would blank every 40-character git SHA, which is the evidence the parity view exists to show.Provenance
The implementation commit
ecda200was authored in an earlier author cycle whose owning MCP session (pid 72383) exited before the pull request was opened. This cycle recovered the durable claim through the sanctioned dead-session path ingitea_lock_issue(identityjcwalker3/prgs-author, recovery modepublished_owning_pr, recorded pid 72383 confirmed dead, head relationstrict_descendantagainst recorded headedd5f813), re-ran the full validation matrix in this session, then published the head withgitea_publish_unpublished_issue_branch. No file copy and no re-implementation.Test evidence
Run with the repository venv interpreter from
/Users/jasonwalker/Development/Gitea-Tools/branches/feat-issue-639-webui-system-health-dashboard.pytest tests/test_webui_system_health_dashboard.py -q -s— 26 passed.pytest -k webui -q -s— 402 passed, 337 subtests passed.pytest -q -s— 4705 passed, 12 failed, 6 skipped, 751 subtests passed in 629.45s.Baseline comparison: a clean detached worktree at
branches/baseline-master-issue-639, pinned to master9301739910df7b51ca3abcdbf46cce25cfb026e5— the live master head this branch is already merged onto — running the identical command with the identical interpreter reports 4679 passed, 12 failed, 6 skipped, 750 subtests passed in 651.34s. The twelve failing node identifiers were compared withdiffand match exactly: six intests/test_commit_payloads.py, two intests/test_issue_702_review_findings_f1_f6.py, two intests/test_mcp_server.py(TestRuntimeProfile::test_whoami_v2_metadataandTestPreflightVerification::test_declared_clean_task_worktree_ignores_control_checkout_violation), one intests/test_post_merge_moot_lease.py, and one intests/test_reconciler_supersession_close.py. None of them touchwebui/. The pass delta is exactly 26, accounting for precisely the 26 tests added here, so this branch introduces no new failure.Both worktrees and the control checkout reported a zero-entry
git status --porcelainbefore and after validation.Risk
Low. One added route, GET only; the view module performs no writes and holds no state. The residual risk is drift between the rendered field set and the #634 DTO, so the render tests assert that field set — a DTO rename fails the tests rather than silently dropping a card.
Known limitations
There is no auto-refresh; the page states that reloading is how an operator refreshes it. Namespace health stays
unprovenfrom the web process by design. Restart and reload controls are Phase 2 (#642).Provenance details
feat/issue-639-webui-system-health-dashboard/Users/jasonwalker/Development/Gitea-Tools/branches/feat-issue-639-webui-system-health-dashboardecda2001808f2c2a90f8c618ccff8728a2c694c7f80e3b33b04127d95ee50f1b4a5ca72407e43cb99301739910df7b51ca3abcdbf46cce25cfb026e5Canonical PR State
Co-Authored-By: Claude Opus 4.8 (1M context) [email protected]
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #862
issue: #639
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 35152-3c2f5ef32211
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr862-issue-639
phase: claimed
candidate_head:
82464f4054target_branch: master
target_branch_sha:
c33c69b3f3last_activity: 2026-07-24T11:21:09Z
expires_at: 2026-07-24T11:31:09Z
blocker: none
Canonical PR State
STATE: approved
WHO_IS_NEXT: merger
NEXT_ACTION: Merge PR #862 at head
82464f4054onto master c33c69b3f3f383f56b530def1789662ad26ea648; then reconcile branch/worktree cleanup for feat/issue-639-webui-system-health-dashboard.NEXT_PROMPT:
WHAT_HAPPENED: Independent review at exact PR head
82464f4054in worktree branches/review-pr862-issue-639. Diff vs basec33c69b3is 6 files / +724 / -0 additive (system_health_views.py, app.py routes, nav/layout, 26 tests, docs). Routes GET-only. Redaction split correct: free-text uses redact+escape; structured SHAs escape-only. Unproven readiness never painted green. Recovery card is pointer text only — no restart/kill control. tests/test_webui_system_health_dashboard.py → 26 passed in this session.WHY: All five #639 acceptance criteria satisfied; read-only non-goals held; scope limited to the system-health dashboard; focused suite green; commits_behind=0 and mergeable with no conflicts — eligible for merge.
ISSUE: 639
HEAD_SHA:
82464f4054REVIEW_STATUS: approved
MERGE_READY: yes
BLOCKERS: none
VALIDATION: tests/test_webui_system_health_dashboard.py → 26 passed (venv interpreter); git diff --stat c33c69b3...82464f40 = 6 files / +724 / -0; assess_pr_sync_status: behind=0, mergeable=true, has_conflicts=false; Workflow-load helper result: workflow_hash: 263d0a6cb8a6 boundary_status: clean; Live head SHA before approval: 82464f4054e83df0f17fba67c3771f6b603665ff; Pushes occurred during validation: no
LAST_UPDATED_BY: prgs-reviewer (sysadmin)
NATIVE_REVIEW_PROOF: transport=native_mcp; entrypoint=mcp_server; namespace=gitea-reviewer; profile=prgs-reviewer; identity=sysadmin; worktree=branches/review-pr862-issue-639 at 82464f4054e83df0f17fba67c3771f6b603665ff; pid=35152
[THREAD STATE LEDGER]
what is true now
Server-side decision state: formal APPROVE review verdict recorded for PR #862 at head
82464f4054Local verdict/state: approve decision marked final and posted via gitea_submit_pr_review
Next actor: merger (prgs-merger)
Required action: merge PR #862 at the exact reviewed head
Blocker classification: no blocker
Do not do: do not reuse this verdict if the PR head moves; do not force-push; do not kill the daemon as recovery
what changed
Independent current-head review completed for #639 system-health dashboard; 26 focused tests green; no code defects found.
what is blocked
Nothing. PR is eligible for merger action at the pinned head.
who/what acts next
prgs-merger merges at head
82464f4054after confirming head unchanged.repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #862
issue: #639
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 35152-3c2f5ef32211
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr862-issue-639
phase: claimed
candidate_head:
82464f4054target_branch: master
target_branch_sha:
c33c69b3f3last_activity: 2026-07-24T11:22:24Z
expires_at: 2026-07-24T11:32:24Z
blocker: none
Review verdict: APPROVE
Reviewed at head
82464f4054e83df0f17fba67c3771f6b603665ff, 0 commits behind masterc33c69b3. Net diff confirmed identical to prior review substance; head advanced only via base-sync merge, code delta unchanged. 6 files, +724 / -0, additive only. No mutating route (GET only); view module holds no state and performs no writes.Acceptance criteria 1-5 all met (render DTO fields, degraded-dependency banner, stale-runtime warning, healthy/degraded/stale/unproven/probe-error fixtures across 26 cases, nav entry). Honesty rules verified:
ready/readiness_completerender separately, unproven never painted green, "Not probed" ≠ healthy. No restart/reload/process-kill control. Redaction split correct — free text throughsystem_health.redact; SHAs/probe-names/statuses HTML-escaped only (the 32+ char opaque-token rule would otherwise blank 40-char git SHAs). Full-suite 12 failures match the master9301739baseline exactly; pass delta is exactly the 26 added tests; none touchwebui/.Canonical PR State
STATE: approved
WHO_IS_NEXT: merger
NEXT_ACTION: Merge PR #862 at head
82464f4054into master; close #639; delete branch feat/issue-639-webui-system-health-dashboard.NEXT_PROMPT:
WHAT_HAPPENED: Fresh native-MCP reviewer approval submitted at the exact current head after re-verifying the net diff is the same additive 6-file change the prior review vetted; only base-sync moved the head.
WHY: All five acceptance criteria are met, read-only non-goals honored, redaction split is correct, and the full-suite failure set matches the pinned master baseline with a pass delta of exactly the added tests — no new failures.
ISSUE: #639
HEAD_SHA:
82464f4054REVIEW_STATUS: approved
MERGE_READY: true
BLOCKERS: none
VALIDATION: Full suite 4705 passed / 12 failed / 6 skipped; 12 failures byte-for-byte match master
9301739baseline (6 test_commit_payloads, 2 test_issue_702_review_findings_f1_f6, 2 test_mcp_server, 1 test_post_merge_moot_lease, 1 test_reconciler_supersession_close); none touch webui/; pass delta = 26 added tests.NATIVE_REVIEW_PROOF: native prgs-reviewer MCP mutation, session_pid 32053, workflow_hash 263d0a6cb8a6, final_report_schema_hash b6c65affc336, boundary clean, mark_final_review_decision head-scoped at
82464f4054.LAST_UPDATED_BY: sysadmin / prgs-reviewer
adopted_at: 2026-07-24T11:25:54Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 35152-3c2f5ef32211
adopted_from_profile: prgs-reviewer
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 15752
adoption_reason: merger-handoff-approved-head
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #862
issue: #639
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 32069-4ce1593468db
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr862-issue-639
phase: adopted
candidate_head:
82464f4054target_branch: master
target_branch_sha:
c33c69b3f3last_activity: 2026-07-24T11:25:54Z
expires_at: 2026-07-24T11:35:54Z
blocker: none
adopted_at: 2026-07-24T11:28:34Z
adopted_by_identity: sysadmin
adopted_by_profile: prgs-merger
adopted_from_session_id: 32069-4ce1593468db
adopted_from_profile: prgs-merger
adopted_from_reviewer_identity: sysadmin
adopted_from_comment_id: 15756
adoption_reason: merger-handoff-approved-head
repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #862
issue: #639
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 72165-7297223b65a9
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr862-issue-639
phase: adopted
candidate_head:
82464f4054target_branch: master
target_branch_sha:
c33c69b3f3last_activity: 2026-07-24T11:28:34Z
expires_at: 2026-07-24T11:38:34Z
blocker: none