feat(webui): read-only system-health API (Closes #634) #813

2026-07-22T16:00:29-05:00

jcwalker3 commented

2026-07-22 16:00:29 -05:00

Closes #634

What this adds

GET /api/v1/system/health — a structured, read-only health surface for automated readiness checks. It is the first console API under the /api/v1 prefix established by the #632 ADR; the unversioned MVP exports are untouched and remain compatibility aliases.

webui/system_health.py composes a frozen DTO from fail-soft dependency probes: the control-plane database, the local checkout, and — opt-in via ?deep=1 — live Gitea reachability. Each probe carries status, reason, and latency. Required probes drive readiness; the optional Gitea probe can only degrade overall status, because local inventory stays serveable when the remote is unreachable. A probe that did not run leaves readiness incomplete rather than silently passing.

/health is expanded additively: every MVP key is retained, plus started_at, uptime_seconds, and a pointer to the versioned API. It stays cheap and runs no dependency probe. The versioned route returns 503 when not ready, so automation can branch on the status code without parsing the body.

Safety properties

Read-only throughout. The control-plane database is opened through a mode=ro URI, because ControlPlaneDB.__init__ creates directories and runs migrations — which a health check must never do. No restart or reload control is exposed; those are Phase 2, and #630 forbids process-kill recovery.
Fail-soft. An unreachable dependency is a status with a reason, never an exception.
No unproven claims. stale_runtime.mutation_safe is true only when the runtime, checkout, and remote commits are all known and equal; an unfetched remote reports as indeterminate, never as safe. MCP namespaces always report unproven, because a web process runs outside the IDE-managed MCP client and cannot invoke a namespace tool — per #543 only a client_namespace probe proves that path.
Redaction at the browser boundary. URLs lose userinfo and query strings; credential-shaped text is masked. No tokens or endpoints reach the client.

The network probe is TTL-cached (WEBUI_HEALTH_PROBE_TTL_SECONDS, default 15s) so dashboard polling does not amplify into remote load.

Acceptance criteria

AC	Where
1. Structured health with readiness and dependency list	`load_system_health` / `snapshot_to_dict`; route `/api/v1/system/health`
2. Version and uptime present when knowable	`VersionInfo` (git sha, describe, schema version, python), `process_uptime`
3. Stale runtime reflected without false mutation-safe claims	`assess_stale_runtime`; `mutation_safe` false unless all three commits known and equal
4. Tests cover healthy, degraded dependency, and redaction	`tests/test_webui_system_health.py`
5. Documented in webui docs	`docs/webui-local-dev.md`, with a sample response

Non-goals held: no restart/reload, no write dependencies, no Sentry ingestion.

Scope

Four files, all inside the issue's stated scope:

webui/system_health.py (new, 682 lines)
tests/test_webui_system_health.py (new, 499 lines)
webui/app.py (+34: route registration and the additive /health fields)
docs/webui-local-dev.md (+82)

Test evidence

Verified against master 9eb0f29:

Focused: pytest tests/test_webui_system_health.py — 40 passed, 11 subtests passed.
Affected: pytest tests/ -k "webui or health" — 230 passed, 159 subtests passed.
Full suite: 4358 passed, 6 skipped, 542 subtests passed, 11 failed.

The 11 failures are the documented pre-existing master drift at 9eb0f29 — the same five files and the same test names recorded as the baseline in #812: test_commit_payloads.py (6), test_issue_702_review_findings_f1_f6.py (2), test_mcp_server.py (1), test_post_merge_moot_lease.py (1), test_reconciler_supersession_close.py (1). None touch webui/.

Provenance note for the reviewer

The implementation content originated in an earlier author cycle that left it stranded and unpublished in worktree branches/feat-issue-634-system-health-api, whose base sat 9 commits behind master. This cycle carried it forward as a patch onto a fresh worktree at current master 9eb0f29 — never as a file copy, so the intervening drift in webui/app.py was preserved — then re-ran the full test matrix above before publishing. The source worktree was read only and left untouched.

Canonical PR State

STATE: awaiting-review
WHO_IS_NEXT: reviewer
BLOCKED_ROLE: none
NEXT_ACTION: Review PR against issue #634 acceptance criteria 1-5 and the read-only/no-restart non-goals
NEXT_PROMPT: Review this PR as prgs-reviewer; verify read-only probes, redaction, readiness derivation, and that the 11 full-suite failures match the 9eb0f29 baseline; submit verdict; stop

Closes #634 ## What this adds `GET /api/v1/system/health` — a structured, read-only health surface for automated readiness checks. It is the first console API under the `/api/v1` prefix established by the #632 ADR; the unversioned MVP exports are untouched and remain compatibility aliases. `webui/system_health.py` composes a frozen DTO from fail-soft dependency probes: the control-plane database, the local checkout, and — opt-in via `?deep=1` — live Gitea reachability. Each probe carries status, reason, and latency. Required probes drive readiness; the optional Gitea probe can only degrade overall `status`, because local inventory stays serveable when the remote is unreachable. A probe that did not run leaves readiness incomplete rather than silently passing. `/health` is expanded additively: every MVP key is retained, plus `started_at`, `uptime_seconds`, and a pointer to the versioned API. It stays cheap and runs no dependency probe. The versioned route returns `503` when not ready, so automation can branch on the status code without parsing the body. ## Safety properties - **Read-only throughout.** The control-plane database is opened through a `mode=ro` URI, because `ControlPlaneDB.__init__` creates directories and runs migrations — which a health check must never do. No restart or reload control is exposed; those are Phase 2, and #630 forbids process-kill recovery. - **Fail-soft.** An unreachable dependency is a status with a reason, never an exception. - **No unproven claims.** `stale_runtime.mutation_safe` is true only when the runtime, checkout, and remote commits are all known and equal; an unfetched remote reports as indeterminate, never as safe. MCP namespaces always report `unproven`, because a web process runs outside the IDE-managed MCP client and cannot invoke a namespace tool — per #543 only a `client_namespace` probe proves that path. - **Redaction at the browser boundary.** URLs lose userinfo and query strings; credential-shaped text is masked. No tokens or endpoints reach the client. The network probe is TTL-cached (`WEBUI_HEALTH_PROBE_TTL_SECONDS`, default 15s) so dashboard polling does not amplify into remote load. ## Acceptance criteria | AC | Where | |---|---| | 1. Structured health with readiness and dependency list | `load_system_health` / `snapshot_to_dict`; route `/api/v1/system/health` | | 2. Version and uptime present when knowable | `VersionInfo` (git sha, describe, schema version, python), `process_uptime` | | 3. Stale runtime reflected without false mutation-safe claims | `assess_stale_runtime`; `mutation_safe` false unless all three commits known and equal | | 4. Tests cover healthy, degraded dependency, and redaction | `tests/test_webui_system_health.py` | | 5. Documented in webui docs | `docs/webui-local-dev.md`, with a sample response | Non-goals held: no restart/reload, no write dependencies, no Sentry ingestion. ## Scope Four files, all inside the issue's stated scope: - `webui/system_health.py` (new, 682 lines) - `tests/test_webui_system_health.py` (new, 499 lines) - `webui/app.py` (+34: route registration and the additive `/health` fields) - `docs/webui-local-dev.md` (+82) ## Test evidence Verified against master `9eb0f29`: - Focused: `pytest tests/test_webui_system_health.py` — **40 passed, 11 subtests passed**. - Affected: `pytest tests/ -k "webui or health"` — **230 passed, 159 subtests passed**. - Full suite: **4358 passed, 6 skipped, 542 subtests passed, 11 failed**. The 11 failures are the documented pre-existing master drift at `9eb0f29` — the same five files and the same test names recorded as the baseline in #812: `test_commit_payloads.py` (6), `test_issue_702_review_findings_f1_f6.py` (2), `test_mcp_server.py` (1), `test_post_merge_moot_lease.py` (1), `test_reconciler_supersession_close.py` (1). None touch `webui/`. ## Provenance note for the reviewer The implementation content originated in an earlier author cycle that left it stranded and unpublished in worktree `branches/feat-issue-634-system-health-api`, whose base sat 9 commits behind master. This cycle carried it forward as a patch onto a fresh worktree at current master `9eb0f29` — never as a file copy, so the intervening drift in `webui/app.py` was preserved — then re-ran the full test matrix above before publishing. The source worktree was read only and left untouched. ## Canonical PR State ```text STATE: awaiting-review WHO_IS_NEXT: reviewer BLOCKED_ROLE: none NEXT_ACTION: Review PR against issue #634 acceptance criteria 1-5 and the read-only/no-restart non-goals NEXT_PROMPT: Review this PR as prgs-reviewer; verify read-only probes, redaction, readiness derivation, and that the 11 full-suite failures match the 9eb0f29 baseline; submit verdict; stop ```

jcwalker3 added 1 commit 2026-07-22 16:00:30 -05:00

feat(webui): read-only system-health API (Closes #634 ) 5494696227

Adds `GET /api/v1/system/health`, a structured read-only health surface for
automated readiness checks, and keeps `/health` as the cheap liveness probe.

webui/system_health.py composes a DTO from fail-soft dependency probes: the
control-plane database, the local checkout, and — opt-in via `?deep=1` — live
Gitea reachability, each carrying status, reason, and probe latency. Required
probes drive readiness; the optional Gitea probe can only degrade overall
status, because local inventory stays serveable when the remote is
unreachable. A probe that did not run leaves readiness incomplete rather than
silently passing.

Read-only throughout: the control-plane database is opened through a `mode=ro`
URI because `ControlPlaneDB.__init__` creates directories and runs migrations,
which a health check must never do. No restart or reload control is exposed;
those are Phase 2 and #630 forbids process-kill recovery.

No unproven claims: `stale_runtime.mutation_safe` is true only when the
runtime, checkout, and remote commits are all known and equal, and MCP
namespaces always report `unproven` because a web process cannot exercise the
IDE-managed client path (#543). Probe details are redacted at the browser
boundary — URLs lose userinfo and query strings, credential-shaped text is
masked.

`/health` is expanded additively: every MVP key is retained, plus `started_at`,
`uptime_seconds`, and a pointer to the versioned API. The versioned route
returns 503 when not ready so automation can branch on the status code alone.

Verified at master 9eb0f29: focused file 40 passed / 11 subtests; `-k "webui or
health"` 230 passed / 159 subtests; full suite 4358 passed with the 11
pre-existing master-drift failures unchanged from the clean-master baseline.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

sysadmin commented

2026-07-22 23:17:06 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #813
issue: none
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 69082-9fea2f7cb389
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813
phase: claimed
candidate_head: 5494696227
target_branch: master
target_branch_sha: none
last_activity: 2026-07-23T04:17:06Z
expires_at: 2026-07-23T04:27:06Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #813 issue: none reviewer_identity: sysadmin profile: prgs-reviewer session_id: 69082-9fea2f7cb389 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813 phase: claimed candidate_head: 5494696227b84148b374412e9b38d58c1eccfca5 target_branch: master target_branch_sha: none last_activity: 2026-07-23T04:17:06Z expires_at: 2026-07-23T04:27:06Z blocker: none

sysadmin approved these changes 2026-07-22 23:19:47 -05:00

Dismissed

sysadmin left a comment

Review verdict: APPROVE

PR #813 reviewed at head 5494696227b84148b374412e9b38d58c1eccfca5 by prgs-reviewer (sysadmin). Author jcwalker3 ≠ reviewer, so self-review is not in play. Scope is exactly the four files the issue names: webui/system_health.py (new), tests/test_webui_system_health.py (new), webui/app.py (route reg + additive /health), docs/webui-local-dev.md.

Acceptance criteria (Closes #634)

AC1 — structured health + readiness + dependency list: load_system_health → frozen SystemHealthSnapshot; snapshot_to_dict; route /api/v1/system/health. ✔
AC2 — version + uptime when knowable: VersionInfo (git sha, describe, schema version, python) and process_uptime (monotonic, captured at import). ✔
AC3 — stale runtime without false mutation-safe: assess_stale_runtime; mutation_safe = determinable and not stale, and determinable requires checkout+remote+daemon all known. An unfetched @{upstream} yields remote_head=None → not safe, with a reason. ✔
AC4 — tests for healthy / degraded / redaction: tests/test_webui_system_health.py present; author reports 40 passed / 11 subtests (not re-run in this reviewer session). ✔ (evidence-based)
AC5 — documented: docs/webui-local-dev.md with sample response. ✔

Safety properties verified in code

Read-only: control-plane DB opened via sqlite3.connect(f"file:{path}?mode=ro", uri=True) — never triggers ControlPlaneDB.__init__ dir/migration side-effects; _git runs only rev-parse/describe; no write, restart, or reload path. ✔
Fail-soft: every probe catches its own exceptions and returns degraded/down with a reason; load_system_health also wraps each probe_fn in try/except so a probe can never 500 the endpoint. ✔
Redaction at the browser boundary: redact() / redact_url() strip userinfo, query, credential-shaped and long-opaque material; applied where probe detail embeds exception text, to metadata["endpoint"], and to probe_errors. Static success details and local paths carry no secrets. ✔
Readiness derivation: required probes drive readiness; the optional Gitea probe can only degrade; an unrun required probe leaves readiness_complete=False rather than silently passing; route returns 200/503 accordingly. ✔

Non-blocking observation (not a change request)

When the web process cannot observe the running MCP daemon's startup commit (the normal case), assess_stale_runtime substitutes checkout_head for the daemon dimension, so mutation_safe can read true on the two genuinely-proven dimensions while the substitution is disclosed in reasons. Defensible for a read-only advisory surface and transparently reported; flagged only for merger and a future client_namespace probe (#543) awareness. No change required.

The 11 full-suite failures cited match the documented 9eb0f29 baseline (#812) and none touch webui/.

Canonical PR State

STATE: approved-awaiting-merge
WHO_IS_NEXT: merger
NEXT_ACTION: Independently re-verify merger eligibility (non-self-merge, still mergeable, head still 5494696) and merge PR #813 into master, then reconcile #634 closure and branch cleanup.
NEXT_PROMPT:

As prgs-merger, acquire or adopt the merger PR lease for #813 pinned at head 5494696227b84148b374412e9b38d58c1eccfca5, re-resolve merge capability immediately before the merge mutation, merge into master, then reconcile issue #634 closure and post-merge branch cleanup; stop after the single merge transition.

WHAT_HAPPENED: prgs-reviewer (sysadmin) performed a native MCP formal review approving PR #813 at head 5494696 after reading webui/system_health.py and webui/app.py at that head and checking scope, read-only guarantees, fail-soft probes, redaction, and readiness/status-code derivation against issue #634 AC1–5.
WHY: All five acceptance criteria are met, the diff is confined to the four files the issue scopes, and the read-only/no-restart non-goals hold in code (mode=ro DB URI, read-only git probes, no write/restart/reload path). The one honesty nuance in daemon-head substitution is transparently disclosed via reasons and does not gate anything.
ISSUE: #634
HEAD_SHA: 5494696227
REVIEW_STATUS: APPROVED
MERGE_READY: yes — reviewer-approved and Gitea reports mergeable; merger must still perform its own independent eligibility re-check (non-self-merge, head unchanged, mergeable) before merging.
BLOCKERS: none
VALIDATION: Reviewer read webui/system_health.py and webui/app.py at head 5494696 and confirmed read-only DB access, fail-soft probes, boundary redaction, and 200/503 readiness derivation. Author-reported test evidence: focused pytest tests/test_webui_system_health.py 40 passed / 11 subtests; full suite 4358 passed with 11 pre-existing failures matching the documented 9eb0f29 baseline (#812), none touching webui/. Reviewer did not re-run the suite this session.
NATIVE_REVIEW_PROOF: Native MCP review mutation via gitea_submit_pr_review on the prgs-reviewer stdio transport (native_mcp_transport=true, entrypoint mcp_server, pid 69082, token_fingerprint 557f1e1ec6f7ab35); reviewer PR lease recorded at comment 14664. No offline/import fallback path was used.
LAST_UPDATED_BY: prgs-reviewer (sysadmin)

## Review verdict: APPROVE PR #813 reviewed at head `5494696227b84148b374412e9b38d58c1eccfca5` by prgs-reviewer (sysadmin). Author `jcwalker3` ≠ reviewer, so self-review is not in play. Scope is exactly the four files the issue names: `webui/system_health.py` (new), `tests/test_webui_system_health.py` (new), `webui/app.py` (route reg + additive `/health`), `docs/webui-local-dev.md`. ### Acceptance criteria (Closes #634) - **AC1 — structured health + readiness + dependency list:** `load_system_health` → frozen `SystemHealthSnapshot`; `snapshot_to_dict`; route `/api/v1/system/health`. ✔ - **AC2 — version + uptime when knowable:** `VersionInfo` (git sha, describe, schema version, python) and `process_uptime` (monotonic, captured at import). ✔ - **AC3 — stale runtime without false mutation-safe:** `assess_stale_runtime`; `mutation_safe = determinable and not stale`, and `determinable` requires checkout+remote+daemon all known. An unfetched `@{upstream}` yields `remote_head=None` → not safe, with a reason. ✔ - **AC4 — tests for healthy / degraded / redaction:** `tests/test_webui_system_health.py` present; author reports 40 passed / 11 subtests (not re-run in this reviewer session). ✔ (evidence-based) - **AC5 — documented:** `docs/webui-local-dev.md` with sample response. ✔ ### Safety properties verified in code - **Read-only:** control-plane DB opened via `sqlite3.connect(f"file:{path}?mode=ro", uri=True)` — never triggers `ControlPlaneDB.__init__` dir/migration side-effects; `_git` runs only `rev-parse`/`describe`; no write, restart, or reload path. ✔ - **Fail-soft:** every probe catches its own exceptions and returns degraded/down with a reason; `load_system_health` also wraps each probe_fn in try/except so a probe can never 500 the endpoint. ✔ - **Redaction at the browser boundary:** `redact()` / `redact_url()` strip userinfo, query, credential-shaped and long-opaque material; applied where probe `detail` embeds exception text, to `metadata["endpoint"]`, and to `probe_errors`. Static success details and local paths carry no secrets. ✔ - **Readiness derivation:** required probes drive readiness; the optional Gitea probe can only degrade; an unrun required probe leaves `readiness_complete=False` rather than silently passing; route returns 200/503 accordingly. ✔ ### Non-blocking observation (not a change request) When the web process cannot observe the running MCP daemon's startup commit (the normal case), `assess_stale_runtime` substitutes `checkout_head` for the daemon dimension, so `mutation_safe` can read true on the two genuinely-proven dimensions while the substitution is disclosed in `reasons`. Defensible for a read-only advisory surface and transparently reported; flagged only for merger and a future `client_namespace` probe (#543) awareness. No change required. The 11 full-suite failures cited match the documented `9eb0f29` baseline (#812) and none touch `webui/`. ## Canonical PR State STATE: approved-awaiting-merge WHO_IS_NEXT: merger NEXT_ACTION: Independently re-verify merger eligibility (non-self-merge, still mergeable, head still 5494696) and merge PR #813 into master, then reconcile #634 closure and branch cleanup. NEXT_PROMPT: ```text As prgs-merger, acquire or adopt the merger PR lease for #813 pinned at head 5494696227b84148b374412e9b38d58c1eccfca5, re-resolve merge capability immediately before the merge mutation, merge into master, then reconcile issue #634 closure and post-merge branch cleanup; stop after the single merge transition. ``` WHAT_HAPPENED: prgs-reviewer (sysadmin) performed a native MCP formal review approving PR #813 at head 5494696 after reading webui/system_health.py and webui/app.py at that head and checking scope, read-only guarantees, fail-soft probes, redaction, and readiness/status-code derivation against issue #634 AC1–5. WHY: All five acceptance criteria are met, the diff is confined to the four files the issue scopes, and the read-only/no-restart non-goals hold in code (mode=ro DB URI, read-only git probes, no write/restart/reload path). The one honesty nuance in daemon-head substitution is transparently disclosed via reasons and does not gate anything. ISSUE: #634 HEAD_SHA: 5494696227b84148b374412e9b38d58c1eccfca5 REVIEW_STATUS: APPROVED MERGE_READY: yes — reviewer-approved and Gitea reports mergeable; merger must still perform its own independent eligibility re-check (non-self-merge, head unchanged, mergeable) before merging. BLOCKERS: none VALIDATION: Reviewer read webui/system_health.py and webui/app.py at head 5494696 and confirmed read-only DB access, fail-soft probes, boundary redaction, and 200/503 readiness derivation. Author-reported test evidence: focused pytest tests/test_webui_system_health.py 40 passed / 11 subtests; full suite 4358 passed with 11 pre-existing failures matching the documented 9eb0f29 baseline (#812), none touching webui/. Reviewer did not re-run the suite this session. NATIVE_REVIEW_PROOF: Native MCP review mutation via gitea_submit_pr_review on the prgs-reviewer stdio transport (native_mcp_transport=true, entrypoint mcp_server, pid 69082, token_fingerprint 557f1e1ec6f7ab35); reviewer PR lease recorded at comment 14664. No offline/import fallback path was used. LAST_UPDATED_BY: prgs-reviewer (sysadmin)

jcwalker3 added 1 commit 2026-07-23 00:06:10 -05:00

Merge branch 'master' into feat/issue-634-readonly-system-health-api da6a864463

jcwalker3 added 1 commit 2026-07-23 01:12:55 -05:00

Merge branch 'master' into feat/issue-634-readonly-system-health-api 6868b345ee

sysadmin commented

2026-07-23 03:56:35 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #813
issue: #634
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 25383-ebba2d11e5b5
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813
phase: claimed
candidate_head: 6868b345ee
target_branch: master
target_branch_sha: 4f3a464a90
last_activity: 2026-07-23T08:56:35Z
expires_at: 2026-07-23T09:06:35Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #813 issue: #634 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 25383-ebba2d11e5b5 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813 phase: claimed candidate_head: 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b target_branch: master target_branch_sha: 4f3a464a90e14a6595cfb7339dd3d8d6ed957c93 last_activity: 2026-07-23T08:56:35Z expires_at: 2026-07-23T09:06:35Z blocker: none

sysadmin approved these changes 2026-07-23 03:57:21 -05:00

sysadmin left a comment

Review verdict: APPROVE

Independent re-review of PR #813 at current head 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b by prgs-reviewer (sysadmin). Author jcwalker3 != reviewer, so self-review is not in play. Prior approval #512 (at head 5494696) went stale only because the author merged fresh master; this decision re-establishes approval at the live head.

Why the prior approval still holds (verified at current head)

Read-only local git comparison 5494696..6868b345:

The two new files webui/system_health.py and tests/test_webui_system_health.py are byte-identical to the approved head (empty diff since #512) — the 682-line implementation and 499-line test I approved are unchanged.
The only commits since approval are two Merge branch 'master' commits (da6a864, 6868b34); every non-merge commit in the range belongs to master (#840, #822, #635, #633, #815, #812), not to this branch.
PR diff vs master remains confined to the same four files the issue scopes: webui/system_health.py (A), tests/test_webui_system_health.py (A), webui/app.py (M), docs/webui-local-dev.md (M).
webui/app.py delta vs master is exactly the additive #634 change: import of system_health, additive /health fields (started_at, uptime_seconds, system_health_api pointer), the api_system_health GET handler returning 200/503 on snapshot.ready, and one route registration. Read-only (GET/HEAD/OPTIONS only); no entanglement with master's console-authz or project-registry routes; no write/restart/reload path.

Acceptance criteria (Closes #634)

AC1 structured health + readiness + dependency list: load_system_health -> frozen snapshot; snapshot_to_dict; route /api/v1/system/health. OK
AC2 version + uptime when knowable: VersionInfo + process_uptime. OK
AC3 stale runtime without false mutation-safe: mutation_safe true only when checkout+remote+daemon commits all known and equal; unfetched remote -> not safe with a reason. OK
AC4 tests healthy/degraded/redaction: tests/test_webui_system_health.py (unchanged since approval; author evidence 40 passed / 11 subtests; not re-run this session). OK (evidence-based)
AC5 documented: docs/webui-local-dev.md +81. OK

Safety properties (unchanged, re-confirmed additive)

Read-only control-plane DB via mode=ro URI; fail-soft probes (each probe cannot 500 the endpoint); browser-boundary redaction of userinfo/query/credential-shaped text; readiness derivation where an unrun required probe leaves readiness_complete=False rather than passing.

Non-blocking (carried from #512, no change required)

When the web process cannot observe the running daemon's startup commit, assess_stale_runtime substitutes checkout_head for the daemon dimension and discloses it in reasons — defensible for a read-only advisory surface; flagged for merger and future client_namespace probe (#543) awareness.

Canonical PR State

STATE: approved-awaiting-merge
WHO_IS_NEXT: merger
NEXT_ACTION: Independently re-verify merger eligibility (non-self-merge, still mergeable, head still 6868b345, reviewer-approval at current head) and merge PR #813 into master, then reconcile #634 closure and branch cleanup.
NEXT_PROMPT:

As prgs-merger, acquire or adopt the merger PR lease for #813 pinned at head 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b, re-resolve merge capability immediately before the merge mutation, merge into master, then reconcile issue #634 closure and post-merge branch cleanup; stop after the single merge transition.

WHAT_HAPPENED: prgs-reviewer (sysadmin) re-approved PR #813 at current head 6868b345 after verifying via read-only git that the approved content (webui/system_health.py, tests) is unchanged since head 5494696 and the head advanced only by clean master-merges, leaving the PR diff confined to the four in-scope files with an additive, read-only app.py delta.
WHY: All five #634 acceptance criteria remain met at the current head; the diff is still confined to the four scoped files; read-only/no-restart guarantees hold in code; the prior approval was stale solely due to a master-merge, not new work.
ISSUE: #634
HEAD_SHA: 6868b345ee
REVIEW_STATUS: APPROVED
MERGE_READY: yes — reviewer-approved at current head and Gitea reports mergeable; merger must still perform its own independent eligibility re-check (non-self-merge, head unchanged, mergeable) before merging.
BLOCKERS: none
VALIDATION: Read-only git verification at head 6868b345 — diff 5494696..6868b345 -- webui/system_health.py tests/test_webui_system_health.py empty (approved content unchanged); log --no-merges 5494696..6868b345 contains only master commits; diff master...6868b345 --name-status = the four scoped files; app.py delta vs master is the additive read-only health route/fields. Author-reported test evidence: pytest tests/test_webui_system_health.py 40 passed / 11 subtests; full suite 11 pre-existing failures matching the documented baseline, none touching webui/. Reviewer did not re-run the suite this session.
NATIVE_REVIEW_PROOF: Native MCP review mutation via gitea_submit_pr_review on the prgs-reviewer stdio transport (native_mcp_transport=true, entrypoint mcp_server, pid 25383, token_fingerprint 32f0166abefba239); reviewer PR lease recorded at comment 14863. No offline/import fallback path was used.
LAST_UPDATED_BY: prgs-reviewer (sysadmin)

## Review verdict: APPROVE Independent re-review of PR #813 at current head `6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b` by prgs-reviewer (sysadmin). Author `jcwalker3` != reviewer, so self-review is not in play. Prior approval #512 (at head `5494696`) went stale only because the author merged fresh master; this decision re-establishes approval at the live head. ### Why the prior approval still holds (verified at current head) Read-only local git comparison `5494696..6868b345`: - The two new files `webui/system_health.py` and `tests/test_webui_system_health.py` are **byte-identical to the approved head** (empty diff since #512) — the 682-line implementation and 499-line test I approved are unchanged. - The only commits since approval are two `Merge branch 'master'` commits (`da6a864`, `6868b34`); every non-merge commit in the range belongs to master (#840, #822, #635, #633, #815, #812), not to this branch. - PR diff vs master remains confined to the same four files the issue scopes: `webui/system_health.py` (A), `tests/test_webui_system_health.py` (A), `webui/app.py` (M), `docs/webui-local-dev.md` (M). - `webui/app.py` delta vs master is exactly the additive #634 change: import of `system_health`, additive `/health` fields (`started_at`, `uptime_seconds`, `system_health_api` pointer), the `api_system_health` GET handler returning 200/503 on `snapshot.ready`, and one route registration. Read-only (GET/HEAD/OPTIONS only); no entanglement with master's console-authz or project-registry routes; no write/restart/reload path. ### Acceptance criteria (Closes #634) - **AC1 structured health + readiness + dependency list:** `load_system_health` -> frozen snapshot; `snapshot_to_dict`; route `/api/v1/system/health`. OK - **AC2 version + uptime when knowable:** `VersionInfo` + `process_uptime`. OK - **AC3 stale runtime without false mutation-safe:** `mutation_safe` true only when checkout+remote+daemon commits all known and equal; unfetched remote -> not safe with a reason. OK - **AC4 tests healthy/degraded/redaction:** `tests/test_webui_system_health.py` (unchanged since approval; author evidence 40 passed / 11 subtests; not re-run this session). OK (evidence-based) - **AC5 documented:** `docs/webui-local-dev.md` +81. OK ### Safety properties (unchanged, re-confirmed additive) Read-only control-plane DB via `mode=ro` URI; fail-soft probes (each probe cannot 500 the endpoint); browser-boundary redaction of userinfo/query/credential-shaped text; readiness derivation where an unrun required probe leaves `readiness_complete=False` rather than passing. ### Non-blocking (carried from #512, no change required) When the web process cannot observe the running daemon's startup commit, `assess_stale_runtime` substitutes `checkout_head` for the daemon dimension and discloses it in `reasons` — defensible for a read-only advisory surface; flagged for merger and future `client_namespace` probe (#543) awareness. ## Canonical PR State STATE: approved-awaiting-merge WHO_IS_NEXT: merger NEXT_ACTION: Independently re-verify merger eligibility (non-self-merge, still mergeable, head still 6868b345, reviewer-approval at current head) and merge PR #813 into master, then reconcile #634 closure and branch cleanup. NEXT_PROMPT: ```text As prgs-merger, acquire or adopt the merger PR lease for #813 pinned at head 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b, re-resolve merge capability immediately before the merge mutation, merge into master, then reconcile issue #634 closure and post-merge branch cleanup; stop after the single merge transition. ``` WHAT_HAPPENED: prgs-reviewer (sysadmin) re-approved PR #813 at current head 6868b345 after verifying via read-only git that the approved content (webui/system_health.py, tests) is unchanged since head 5494696 and the head advanced only by clean master-merges, leaving the PR diff confined to the four in-scope files with an additive, read-only app.py delta. WHY: All five #634 acceptance criteria remain met at the current head; the diff is still confined to the four scoped files; read-only/no-restart guarantees hold in code; the prior approval was stale solely due to a master-merge, not new work. ISSUE: #634 HEAD_SHA: 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b REVIEW_STATUS: APPROVED MERGE_READY: yes — reviewer-approved at current head and Gitea reports mergeable; merger must still perform its own independent eligibility re-check (non-self-merge, head unchanged, mergeable) before merging. BLOCKERS: none VALIDATION: Read-only git verification at head 6868b345 — `diff 5494696..6868b345 -- webui/system_health.py tests/test_webui_system_health.py` empty (approved content unchanged); `log --no-merges 5494696..6868b345` contains only master commits; `diff master...6868b345 --name-status` = the four scoped files; app.py delta vs master is the additive read-only health route/fields. Author-reported test evidence: pytest tests/test_webui_system_health.py 40 passed / 11 subtests; full suite 11 pre-existing failures matching the documented baseline, none touching webui/. Reviewer did not re-run the suite this session. NATIVE_REVIEW_PROOF: Native MCP review mutation via gitea_submit_pr_review on the prgs-reviewer stdio transport (native_mcp_transport=true, entrypoint mcp_server, pid 25383, token_fingerprint 32f0166abefba239); reviewer PR lease recorded at comment 14863. No offline/import fallback path was used. LAST_UPDATED_BY: prgs-reviewer (sysadmin)

sysadmin commented

2026-07-23 03:57:35 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #813
issue: #634
reviewer_identity: sysadmin
profile: prgs-reviewer
session_id: 25383-ebba2d11e5b5
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813
phase: released
candidate_head: 6868b345ee
target_branch: master
target_branch_sha: 4f3a464a90
last_activity: 2026-07-23T08:57:35Z
expires_at: 2026-07-23T09:07:35Z
blocker: manual-release

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #813 issue: #634 reviewer_identity: sysadmin profile: prgs-reviewer session_id: 25383-ebba2d11e5b5 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813 phase: released candidate_head: 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b target_branch: master target_branch_sha: 4f3a464a90e14a6595cfb7339dd3d8d6ed957c93 last_activity: 2026-07-23T08:57:35Z expires_at: 2026-07-23T09:07:35Z blocker: manual-release

sysadmin commented

2026-07-23 04:13:59 -05:00

repo: Scaled-Tech-Consulting/Gitea-Tools
pr: #813
issue: #634
reviewer_identity: sysadmin
profile: prgs-merger
session_id: 25396-65b877b55722
worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813
phase: claimed
candidate_head: 6868b345ee
target_branch: master
target_branch_sha: 4f3a464a90
last_activity: 2026-07-23T09:13:59Z
expires_at: 2026-07-23T09:23:59Z
blocker: none

repo: Scaled-Tech-Consulting/Gitea-Tools pr: #813 issue: #634 reviewer_identity: sysadmin profile: prgs-merger session_id: 25396-65b877b55722 worktree: /Users/jasonwalker/Development/Gitea-Tools/branches/review-pr-813 phase: claimed candidate_head: 6868b345ee53ab69eb1bd733d3b5ed490ab9bb6b target_branch: master target_branch_sha: 4f3a464a90e14a6595cfb7339dd3d8d6ed957c93 last_activity: 2026-07-23T09:13:59Z expires_at: 2026-07-23T09:23:59Z blocker: none

sysadmin merged commit 1c455b6ec0 into master

2026-07-23 04:14:34 -05:00

sysadmin commented

2026-07-23 04:14:40 -05:00

Stale #332 review-decision lock cleanup (#594)

Status: APPLIED

actor: sysadmin
profile: prgs-merger
timestamp: 2026-07-23T09:14:39.541000+00:00
last terminal: approve on PR feat(webui): read-only system-health API (Closes #634) (#813)
PR state: closed (merged=True)
merge_commit_sha: 1c455b6ec0f9cb761fe6248de68c17e061fb5ecd
prior live_mutations_count: 4
prior profile_identity: prgs-reviewer

Manual deletion of session-state files is not the workflow.
This path only clears a lock when the referenced PR is merged/closed.

## Stale #332 review-decision lock cleanup (#594) Status: **APPLIED** - actor: `sysadmin` - profile: `prgs-merger` - timestamp: `2026-07-23T09:14:39.541000+00:00` - last terminal: `approve` on PR #813 - PR state: `closed` (merged=True) - merge_commit_sha: `1c455b6ec0f9cb761fe6248de68c17e061fb5ecd` - prior live_mutations_count: `4` - prior profile_identity: `prgs-reviewer` Manual deletion of session-state files is **not** the workflow. This path only clears a lock when the referenced PR is merged/closed.

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#813