Epic: MCP Control Plane Web Console #631

Open
opened 2026-07-10 14:37:23 -05:00 by jcwalker3 · 2 comments
Owner

Problem statement

Operators and LLM workers still lack a single durable MCP Control Plane Web Console that unifies system health, project registry, traffic-control/queue visibility, sessions/leases/locks/worktrees, workflow events, Gitea linkage, observability bridges, AI-provider insights, cost/latency analytics, notifications, and policy management.

The closed MVP tracker #425 and children #426–#436 delivered a read-only internal Starlette UI under webui/ (queue, projects, prompts, runtime, audit, worktrees, leases, gated-actions stubs, deployment boundary, tests). That MVP is foundation, not the full console product.

Without a next-generation epic:

  • future work fragments across unlinked issues;
  • LLMs cannot retrieve a complete product roadmap from Gitea alone;
  • operational actions (restart, rebind, initiate workflow) risk ad-hoc shell recovery (#630) or ungated browser writes;
  • observability (Sentry/GlitchTip, model cost) and orchestration (#600/#613/#628) remain disconnected from the operator surface.

User and operational impact

  • Operators need one console to see health, traffic, blockers, and next safe actions.
  • Controllers need policy visibility and audited privileged actions.
  • LLM workers need machine-readable APIs (not chat dumps) for inventory and recovery.
  • Humans should only be interrupted at the defined attention boundary (#628).

Scope (umbrella)

This epic owns the product roadmap and linkage for the Web Console. Implementation is delivered via child issues only.

Phase 1 — Read-only operational visibility (implement first)

Foundation children (create as independent issues linked here):

  1. Architecture & information architecture
  2. Authorization, RBAC, secret redaction, audit/retention model
  3. Read-only system-health API
  4. Project registry API (evolve #427)
  5. Session / lease / lock / worktree inventory API
  6. Workflow-event and conversation timeline model
  7. Web-console application shell (evolve #426)
  8. System-health dashboard
  9. Workflow traffic-control view
  10. Runtime and session view

Phase 2 — Controlled operational actions

  1. System restart / graceful reload (sanctioned only)
  2. Requests, intent preview, authorization, workflow initiation
  3. Stale-runtime recovery, worktree rebinding, reconciliation controls

Phase 3 — Workflow orchestration

  1. Gitea issue and PR linkage console
  2. Workflow policy, guardrail, and configuration visibility
  3. Versioned policy editing, validation, simulation, approval, rollback
  4. Notifications and human-attention routing

Phase 4 — AI-assisted insights and optimization

  1. Sentry/GlitchTip connections, error correlation, durable issue creation
  2. AI-provider connections and evidence-backed operational insights
  3. Model usage, token cost, latency, and workflow-performance analytics

Explicit non-goals

  • Do not re-implement closed MVP #425–#436 from scratch; extend webui/ and APIs.
  • Do not replace Gitea, MCP capability gates, or canonical workflows as policy source of truth.
  • Do not enable ungated review/merge/close/comment from the browser.
  • Do not implement product features in this epic issue itself.
  • Do not use manual pkill/host process killing as recovery (#630).
  • Do not auto-assign raw unclassified monitoring incidents (#612 ADR).

Required implementation investigation

Future implementers must inspect:

  • webui/ package and docs/webui-*.md
  • control_plane_db.py, allocator_service.py
  • lease/lock/worktree modules; runtime health; namespace health
  • docs/architecture/mcp-allocator-control-plane-observability-adr.md
  • docs/safety-model.md, docs/tool-boundaries.md, docs/credential-isolation.md
  • Closed #425–#436, open #605/#606/#607/#603/#628/#626/#630

Proposed architecture direction

Layer Authority
Gitea Durable issues/PRs/comments/reviews/labels
Control-plane DB / allocator Sessions, assignment, leases, coordination events
MCP tools / capability gates Mutation authorization
Web Console Read views + gated privileged actions with audit
Sentry/GlitchTip Observe only; bridge creates durable Gitea work
Canonical handoffs Stage continuation payload (#626/#628)

Rule: Console never invents policy. It projects live state and executes only capability-checked, audited actions.

Stack preference: extend existing Starlette webui/ with versioned JSON APIs, then progressive UI enhancement. Prefer server-side secret handling; never ship tokens to the browser.

Security and workflow-safety requirements

  • Fail closed on unknown auth, missing RBAC, or ambiguous leases.
  • Redact secrets, tokens, keychain IDs, raw endpoints by default.
  • Privileged actions require capability + confirmation + audit log.
  • Read-only phase must not open mutation endpoints without gated framework.
  • Session contamination (e.g. manual daemon kill) must surface and block clean claims (#630).

Acceptance criteria (epic)

  1. All phase child issues exist, are linked from this epic, and are independently implementable.
  2. Each child includes problem, impact, scope, non-goals, investigation, architecture direction, security, AC, tests, observability, dependencies, canonical state, evidence, handoff expectations.
  3. Phase 1 foundation set is ordered so architecture + auth/audit land before dashboards that depend on them.
  4. Epic body remains the durable product definition; stage reports stay brief (#628).
  5. No product feature implementation is claimed complete solely on this epic.
  6. Related existing components (#425 MVP, #600/#613, #605–#607, #628) are referenced, not duplicated.

Required tests (epic-level)

  • Linkage integrity: every listed child references this epic.
  • No duplicate recreation of closed #426–#436 scopes without an explicit “evolve/extend” statement.
  • Phase ordering documented and reflected in dependency fields of children.

Observability and audit requirements

  • Epic progress tracked via child status labels and canonical issue comments.
  • Console-related defects discovered during implementation must file separate durable issues and link here.

Dependencies and linkage

Foundation (closed MVP — extend, do not recreate)

Related open / coordination

  • #605 MCP menu/dashboard next-safe-action (MCP-menu surface; complement console)
  • #606/#607 Sentry observability & incident bridge
  • #603 lifecycle labels
  • #613/#600 control-plane DB & allocator (closed; APIs to project)
  • #628 autonomous handoffs & concurrent orchestration (umbrella)
  • #626 self-propagating handoffs
  • #630 block manual MCP daemon process killing
  • #610/#615/#584 stale-runtime / reconnect

Phased delivery policy

  1. Phase 1 must ship usable read-only APIs + views without privileged writes.
  2. Phase 2 may enable gated ops only after auth/audit model exists.
  3. Phase 3 orchestration/policy editing requires Phase 1 inventory + Phase 2 action framework.
  4. Phase 4 insights must be evidence-backed and never bypass gates.

Canonical issue state (template for updates)

STATE: needs-author | needs-review | blocked | complete
WHO_IS_NEXT: author | reviewer | controller | none
NEXT_ACTION: <one sentence>
NEXT_PROMPT: <stored for automatic retrieval; paste only for recovery>

Required final evidence (for this intake session)

  • Epic number and URL
  • Child issue numbers by phase
  • Confirmation MVP #425 is referenced as foundation
  • No product feature implementation performed

Required final response and handoff expectations

User-facing response: brief list of created issues + next role. Full child bodies are durable Gitea context for future LLMs. Controller may reorder; authors claim one child at a time with leases.

## Problem statement Operators and LLM workers still lack a single durable **MCP Control Plane Web Console** that unifies system health, project registry, traffic-control/queue visibility, sessions/leases/locks/worktrees, workflow events, Gitea linkage, observability bridges, AI-provider insights, cost/latency analytics, notifications, and policy management. The closed MVP tracker **#425** and children **#426–#436** delivered a read-only internal Starlette UI under `webui/` (queue, projects, prompts, runtime, audit, worktrees, leases, gated-actions stubs, deployment boundary, tests). That MVP is foundation, not the full console product. Without a next-generation epic: * future work fragments across unlinked issues; * LLMs cannot retrieve a complete product roadmap from Gitea alone; * operational actions (restart, rebind, initiate workflow) risk ad-hoc shell recovery (#630) or ungated browser writes; * observability (Sentry/GlitchTip, model cost) and orchestration (#600/#613/#628) remain disconnected from the operator surface. ## User and operational impact * Operators need one console to see health, traffic, blockers, and next safe actions. * Controllers need policy visibility and audited privileged actions. * LLM workers need machine-readable APIs (not chat dumps) for inventory and recovery. * Humans should only be interrupted at the defined attention boundary (#628). ## Scope (umbrella) This epic owns the **product roadmap and linkage** for the Web Console. Implementation is delivered via child issues only. ### Phase 1 — Read-only operational visibility (implement first) Foundation children (create as independent issues linked here): 1. Architecture & information architecture 2. Authorization, RBAC, secret redaction, audit/retention model 3. Read-only system-health API 4. Project registry API (evolve #427) 5. Session / lease / lock / worktree inventory API 6. Workflow-event and conversation timeline model 7. Web-console application shell (evolve #426) 8. System-health dashboard 9. Workflow traffic-control view 10. Runtime and session view ### Phase 2 — Controlled operational actions 11. System restart / graceful reload (sanctioned only) 12. Requests, intent preview, authorization, workflow initiation 13. Stale-runtime recovery, worktree rebinding, reconciliation controls ### Phase 3 — Workflow orchestration 14. Gitea issue and PR linkage console 15. Workflow policy, guardrail, and configuration visibility 16. Versioned policy editing, validation, simulation, approval, rollback 17. Notifications and human-attention routing ### Phase 4 — AI-assisted insights and optimization 18. Sentry/GlitchTip connections, error correlation, durable issue creation 19. AI-provider connections and evidence-backed operational insights 20. Model usage, token cost, latency, and workflow-performance analytics ## Explicit non-goals * Do not re-implement closed MVP #425–#436 from scratch; extend `webui/` and APIs. * Do not replace Gitea, MCP capability gates, or canonical workflows as policy source of truth. * Do not enable ungated review/merge/close/comment from the browser. * Do not implement product features in this epic issue itself. * Do not use manual `pkill`/host process killing as recovery (#630). * Do not auto-assign raw unclassified monitoring incidents (#612 ADR). ## Required implementation investigation Future implementers must inspect: * `webui/` package and `docs/webui-*.md` * `control_plane_db.py`, `allocator_service.py` * lease/lock/worktree modules; runtime health; namespace health * `docs/architecture/mcp-allocator-control-plane-observability-adr.md` * `docs/safety-model.md`, `docs/tool-boundaries.md`, `docs/credential-isolation.md` * Closed #425–#436, open #605/#606/#607/#603/#628/#626/#630 ## Proposed architecture direction | Layer | Authority | |-------|-----------| | Gitea | Durable issues/PRs/comments/reviews/labels | | Control-plane DB / allocator | Sessions, assignment, leases, coordination events | | MCP tools / capability gates | Mutation authorization | | Web Console | Read views + **gated** privileged actions with audit | | Sentry/GlitchTip | Observe only; bridge creates durable Gitea work | | Canonical handoffs | Stage continuation payload (#626/#628) | **Rule:** Console never invents policy. It projects live state and executes only capability-checked, audited actions. Stack preference: extend existing Starlette `webui/` with versioned JSON APIs, then progressive UI enhancement. Prefer server-side secret handling; never ship tokens to the browser. ## Security and workflow-safety requirements * Fail closed on unknown auth, missing RBAC, or ambiguous leases. * Redact secrets, tokens, keychain IDs, raw endpoints by default. * Privileged actions require capability + confirmation + audit log. * Read-only phase must not open mutation endpoints without gated framework. * Session contamination (e.g. manual daemon kill) must surface and block clean claims (#630). ## Acceptance criteria (epic) 1. All phase child issues exist, are linked from this epic, and are independently implementable. 2. Each child includes problem, impact, scope, non-goals, investigation, architecture direction, security, AC, tests, observability, dependencies, canonical state, evidence, handoff expectations. 3. Phase 1 foundation set is ordered so architecture + auth/audit land before dashboards that depend on them. 4. Epic body remains the durable product definition; stage reports stay brief (#628). 5. No product feature implementation is claimed complete solely on this epic. 6. Related existing components (#425 MVP, #600/#613, #605–#607, #628) are referenced, not duplicated. ## Required tests (epic-level) * Linkage integrity: every listed child references this epic. * No duplicate recreation of closed #426–#436 scopes without an explicit “evolve/extend” statement. * Phase ordering documented and reflected in dependency fields of children. ## Observability and audit requirements * Epic progress tracked via child status labels and canonical issue comments. * Console-related defects discovered during implementation must file separate durable issues and link here. ## Dependencies and linkage ### Foundation (closed MVP — extend, do not recreate) * #425 Tracker: MCP Control Plane web UI * #426 skeleton · #427 projects · #428 prompts · #429 queue · #430 runtime · #431 audit paste · #432 worktrees · #433 leases · #434 gated actions · #435 auth/deployment · #436 tests/CI ### Related open / coordination * #605 MCP menu/dashboard next-safe-action (MCP-menu surface; complement console) * #606/#607 Sentry observability & incident bridge * #603 lifecycle labels * #613/#600 control-plane DB & allocator (closed; APIs to project) * #628 autonomous handoffs & concurrent orchestration (umbrella) * #626 self-propagating handoffs * #630 block manual MCP daemon process killing * #610/#615/#584 stale-runtime / reconnect ## Phased delivery policy 1. **Phase 1** must ship usable read-only APIs + views without privileged writes. 2. **Phase 2** may enable gated ops only after auth/audit model exists. 3. **Phase 3** orchestration/policy editing requires Phase 1 inventory + Phase 2 action framework. 4. **Phase 4** insights must be evidence-backed and never bypass gates. ## Canonical issue state (template for updates) ```text STATE: needs-author | needs-review | blocked | complete WHO_IS_NEXT: author | reviewer | controller | none NEXT_ACTION: <one sentence> NEXT_PROMPT: <stored for automatic retrieval; paste only for recovery> ``` ## Required final evidence (for this intake session) * Epic number and URL * Child issue numbers by phase * Confirmation MVP #425 is referenced as foundation * No product feature implementation performed ## Required final response and handoff expectations User-facing response: brief list of created issues + next role. Full child bodies are durable Gitea context for future LLMs. Controller may reorder; authors claim one child at a time with leases.
jcwalker3 added the type:featurestatus:readyworkflow-hardeningdashboardmcp-health labels 2026-07-10 14:37:23 -05:00
Author
Owner

Canonical Issue State

STATE:
ready-for-author

WHO_IS_NEXT:
author

NEXT_ACTION:
Claim Phase 1 foundation issues starting with architecture (#632) and auth/audit model (#633); implement only one leased issue at a time

CONTINUATION:
Stored in this epic and child issue bodies. Future sessions must retrieve #631 + selected child from Gitea; do not rely on chat history. Ready-to-paste prompts are recovery aids only.

NEXT_PROMPT:

You are the AUTHOR session for Scaled-Tech-Consulting/Gitea-Tools on remote prgs.

Work epic #631 (MCP Control Plane Web Console). Prefer first implementation order:
1) #632 Architecture
2) #633 Authorization/RBAC/audit
3) #634 System-health API
4) #635 Project registry API
5) #636 Inventory API
6) #637 Timeline model
7) #638 Application shell
8) #639 System-health dashboard
9) #640 Traffic-control view
10) #641 Runtime/session view

Preflight: whoami + resolve_task_capability + lock_issue on the chosen child only.
Extend existing webui/ MVP (#425–#436 closed); do not recreate it.
Do not implement Phase 2–4 children until Phase 1 dependencies are ready unless controller reorders.
Open PR for one child; stop for review; no self-merge.

WHAT_HAPPENED:
Created umbrella epic #631 and linked child issues #632–#651 covering Phases 1–4. Surveyed live webui/ package, docs/webui-*.md, closed MVP tracker #425–#436, open related #605/#606/#607/#603/#628/#626/#630. No product feature implementation performed.

WHY:
Durable multi-issue structure so future LLMs can retrieve complete console roadmap and implement independently without this intake chat.

RELATED_ISSUES:

Phase 1 — Read-only operational visibility (implement first)

  • #632 Architecture and information architecture
  • #633 Authorization, RBAC, secret redaction, and audit model
  • #634 Read-only system-health API
  • #635 Project registry API evolution
  • #636 Session, lease, lock, and worktree inventory API
  • #637 Workflow-event and conversation timeline model
  • #638 Application shell evolution
  • #639 System-health dashboard
  • #640 Workflow traffic-control view
  • #641 Runtime and session view

Phase 2 — Controlled operational actions

  • #642 Sanctioned restart and graceful reload controls
  • #643 Requests, intent preview, authorization, and workflow initiation
  • #644 Stale-runtime recovery, worktree rebinding, and reconciliation controls

Phase 3 — Workflow orchestration

  • #645 Gitea issue and PR linkage console
  • #646 Workflow policy and guardrail configuration visibility
  • #647 Versioned policy editing, validation, simulation, approval, and rollback
  • #648 Notifications and human-attention routing

Phase 4 — AI-assisted insights and optimization

  • #649 Sentry/GlitchTip connections, correlation, and durable issue creation
  • #650 AI-provider connections and evidence-backed operational insights
  • #651 Model usage, token cost, latency, and workflow-performance analytics

Foundation (closed MVP — extend, do not recreate)

  • #425–#436 MCP Control Plane web UI MVP (implemented under webui/)

Related open coordination

  • #605 MCP menu dashboard · #606/#607 Sentry · #603 labels · #628 orchestration · #626 handoffs · #630 manual daemon kill ban · #610/#615/#584 runtime

RELATED_PRS:
none created in this intake session

BLOCKERS:
none for intake

VALIDATION:
Duplicate search completed; #425 is foundation not duplicate; children independently implementable with full durable bodies

LAST_UPDATED_BY:
jcwalker3 / prgs-author / author / 2026-07-10 web-console issue intake

## Canonical Issue State STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Claim Phase 1 foundation issues starting with architecture (#632) and auth/audit model (#633); implement only one leased issue at a time CONTINUATION: Stored in this epic and child issue bodies. Future sessions must retrieve #631 + selected child from Gitea; do not rely on chat history. Ready-to-paste prompts are recovery aids only. NEXT_PROMPT: ```text You are the AUTHOR session for Scaled-Tech-Consulting/Gitea-Tools on remote prgs. Work epic #631 (MCP Control Plane Web Console). Prefer first implementation order: 1) #632 Architecture 2) #633 Authorization/RBAC/audit 3) #634 System-health API 4) #635 Project registry API 5) #636 Inventory API 6) #637 Timeline model 7) #638 Application shell 8) #639 System-health dashboard 9) #640 Traffic-control view 10) #641 Runtime/session view Preflight: whoami + resolve_task_capability + lock_issue on the chosen child only. Extend existing webui/ MVP (#425–#436 closed); do not recreate it. Do not implement Phase 2–4 children until Phase 1 dependencies are ready unless controller reorders. Open PR for one child; stop for review; no self-merge. ``` WHAT_HAPPENED: Created umbrella epic #631 and linked child issues #632–#651 covering Phases 1–4. Surveyed live `webui/` package, docs/webui-*.md, closed MVP tracker #425–#436, open related #605/#606/#607/#603/#628/#626/#630. No product feature implementation performed. WHY: Durable multi-issue structure so future LLMs can retrieve complete console roadmap and implement independently without this intake chat. RELATED_ISSUES: ### Phase 1 — Read-only operational visibility (implement first) - #632 Architecture and information architecture - #633 Authorization, RBAC, secret redaction, and audit model - #634 Read-only system-health API - #635 Project registry API evolution - #636 Session, lease, lock, and worktree inventory API - #637 Workflow-event and conversation timeline model - #638 Application shell evolution - #639 System-health dashboard - #640 Workflow traffic-control view - #641 Runtime and session view ### Phase 2 — Controlled operational actions - #642 Sanctioned restart and graceful reload controls - #643 Requests, intent preview, authorization, and workflow initiation - #644 Stale-runtime recovery, worktree rebinding, and reconciliation controls ### Phase 3 — Workflow orchestration - #645 Gitea issue and PR linkage console - #646 Workflow policy and guardrail configuration visibility - #647 Versioned policy editing, validation, simulation, approval, and rollback - #648 Notifications and human-attention routing ### Phase 4 — AI-assisted insights and optimization - #649 Sentry/GlitchTip connections, correlation, and durable issue creation - #650 AI-provider connections and evidence-backed operational insights - #651 Model usage, token cost, latency, and workflow-performance analytics ### Foundation (closed MVP — extend, do not recreate) - #425–#436 MCP Control Plane web UI MVP (implemented under `webui/`) ### Related open coordination - #605 MCP menu dashboard · #606/#607 Sentry · #603 labels · #628 orchestration · #626 handoffs · #630 manual daemon kill ban · #610/#615/#584 runtime RELATED_PRS: none created in this intake session BLOCKERS: none for intake VALIDATION: Duplicate search completed; #425 is foundation not duplicate; children independently implementable with full durable bodies LAST_UPDATED_BY: jcwalker3 / prgs-author / author / 2026-07-10 web-console issue intake
Author
Owner

Canonical Issue State

STATE:
implementation-umbrella-active

WHO_IS_NEXT:
author

NEXT_ACTION:
Treat #652 as product vision SoT and #653 as phased roadmap; implement children #632–#651 only; do not treat closing children as vision complete

NEXT_PROMPT:

AUTHOR session, prgs, Scaled-Tech-Consulting/Gitea-Tools.
Canonical vision: #652. Roadmap: #653. This issue #631 is the implementation umbrella for children #632–#651.
Start Phase 1 at #632. Worktrees under branches/; lock one issue; open PR; stop.

WHAT_HAPPENED:
Planning package completed: vision #652, roadmap #653. Children #632–#651 unchanged (no duplicates). Role split: #652=vision, #653=sequencing, #631=child registry/umbrella.

WHY:
Avoid three competing incomplete epics; preserve full vision while keeping existing implementation issues.

RELATED_ISSUES:
#652 #653 #632–#651 #425–#436

RELATED_PRS:
none

BLOCKERS:
none

VALIDATION:
No recreation of Phase 1 issues; preserved catalog on #653

LAST_UPDATED_BY:
jcwalker3 / prgs-author / author / 2026-07-10

## Canonical Issue State STATE: implementation-umbrella-active WHO_IS_NEXT: author NEXT_ACTION: Treat #652 as product vision SoT and #653 as phased roadmap; implement children #632–#651 only; do not treat closing children as vision complete NEXT_PROMPT: ```text AUTHOR session, prgs, Scaled-Tech-Consulting/Gitea-Tools. Canonical vision: #652. Roadmap: #653. This issue #631 is the implementation umbrella for children #632–#651. Start Phase 1 at #632. Worktrees under branches/; lock one issue; open PR; stop. ``` WHAT_HAPPENED: Planning package completed: vision #652, roadmap #653. Children #632–#651 unchanged (no duplicates). Role split: #652=vision, #653=sequencing, #631=child registry/umbrella. WHY: Avoid three competing incomplete epics; preserve full vision while keeping existing implementation issues. RELATED_ISSUES: #652 #653 #632–#651 #425–#436 RELATED_PRS: none BLOCKERS: none VALIDATION: No recreation of Phase 1 issues; preserved catalog on #653 LAST_UPDATED_BY: jcwalker3 / prgs-author / author / 2026-07-10
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

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