P6-T2: Build a terminal frontend for broker daemon monitoring and control

SPECS/ARCHIVE/INDEX.md

@@ -1,11 +1,12 @@
 # mcpbridge-wrapper Tasks Archive
 
-**Last Updated:** 2026-03-07 (REVIEW_broker_runtime_status_surface archived)
+**Last Updated:** 2026-03-07 (P6-T2 review archived)
 
 ## Archived Tasks
 
 | Task ID | Folder | Archived | Verdict |
 |---------|--------|----------|---------|
+| P6-T2 | [P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/](P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/) | 2026-03-07 | PASS |
 | P6-T1 | [P6-T1_Add_explicit_broker_runtime_status_surface_for_frontend_consumers/](P6-T1_Add_explicit_broker_runtime_status_surface_for_frontend_consumers/) | 2026-03-07 | PASS |
 | P1-T12 | [P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/](P1-T12_Improve_troubleshooting_docs_for_Zed_broker_startup_timeouts/) | 2026-03-07 | PASS |
 | P5-T2 | [P5-T2_Release_0.4.1_to_PyPI_and_MCP_Registry/](P5-T2_Release_0.4.1_to_PyPI_and_MCP_Registry/) | 2026-03-06 | PASS |
@@ -194,6 +195,7 @@
 
 | File | Description |
 |------|-------------|
+| [REVIEW_broker_terminal_frontend.md](_Historical/REVIEW_broker_terminal_frontend.md) | Review report for P6-T2 |
 | [REVIEW_broker_runtime_status_surface.md](_Historical/REVIEW_broker_runtime_status_surface.md) | Review report for P6-T1 |
 | [REVIEW_p1_t12_zed_timeout_docs.md](_Historical/REVIEW_p1_t12_zed_timeout_docs.md) | Review report for P1-T12 |
 | [REVIEW_P4-T2_broker_readiness_cache.md](_Historical/REVIEW_P4-T2_broker_readiness_cache.md) | Review report for P4-T2 |
@@ -331,6 +333,7 @@
 
 | Date | Task ID | Action |
 |------|---------|--------|
+| 2026-03-07 | P6-T2 | Archived task artifacts and validation report |
 | 2026-03-07 | P6-T1 | Archived REVIEW_broker_runtime_status_surface report |
 | 2026-03-07 | P6-T1 | Archived task artifacts and validation report |
 | 2026-03-07 | P1-T12 | Archived task artifacts and validation report |
@@ -593,3 +596,4 @@
 | 2026-03-01 | P3-T11 | Archived REVIEW_p3_t11_webui_stop_control report |
 | 2026-03-06 | BUG-T9 | Archived Fix_broker_daemon_not_sending_notifications_initialized_before_tools_list_probe (PASS) |
 | 2026-03-06 | BUG-T9 | Archived REVIEW_BUG-T9 report |
+| 2026-03-07 | P6-T2 | Archived REVIEW_broker_terminal_frontend report |

SPECS/ARCHIVE/P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control.md

@@ -0,0 +1,135 @@
+# P6-T2 — Build a terminal frontend for broker daemon monitoring and control
+
+## Objective Summary
+
+Users who adopt the dedicated broker host pattern still need a first-class
+operator surface that does not require a browser. This task adds a standalone
+terminal frontend that attaches to the existing broker-hosted Web UI, reads the
+broker runtime status API introduced in `P6-T1`, and presents broker health in
+one explicit place. The frontend should make it obvious whether the shared
+daemon is healthy, reconnecting, awaiting approval, or no longer reachable.
+
+The implementation should stay dependency-light. Prefer the Python standard
+library (`curses`, `urllib`, `json`) and existing `WebUIConfig` loading over a
+new third-party terminal framework. The TUI may require an already running
+broker-hosted Web UI; that constraint is acceptable as long as failure modes are
+clear and actionable.
+
+## Deliverables
+
+- Add a standalone `--tui` runtime mode that launches an interactive terminal
+  dashboard instead of proxy, bridge, or daemon execution.
+- Implement a TUI module that polls `GET /api/broker/status`, inspects control
+  capability, and renders broker state, PID information, connected client
+  counts, readiness flags, and reconnect indicators.
+- Surface recent broker activity by tailing the recommended local
+  `~/.mcpbridge_wrapper/broker.log` file inside the terminal UI.
+- Expose at least one lifecycle control action from the TUI, with `stop` backed
+  by `POST /api/control/stop`.
+- Add automated tests for argument parsing, HTTP/status handling, and terminal
+  rendering/control logic.
+
+## Success Criteria
+
+- Users can run `mcpbridge-wrapper --tui` to inspect broker status without
+  tailing logs manually.
+- The terminal UI shows broker state, daemon PID, upstream PID, connected
+  client count, readiness/cached-tool status, and reconnect attempt count.
+- The UI displays recent broker log lines or equivalent reconnect indicators in
+  the same screen.
+- The UI exposes an explicit stop control and handles unavailable/unauthorized
+  backends with clear messaging.
+- No new runtime dependency is required for the terminal frontend.
+
+## Test-First Plan
+
+1. Add parser/main tests that lock down `--tui` mode, including invalid
+   flag combinations with `--broker*` and `--web-ui`.
+2. Add unit tests for a pure rendering/presentation layer so the terminal
+   layout is testable without a real curses session.
+3. Add client tests for status fetches, stop requests, auth header behavior,
+   and log tail handling using mocks or a lightweight HTTP stub.
+4. Implement the production TUI only after the expected runtime contract and
+   screen sections are pinned in tests.
+5. Run required quality gates: `pytest`, `ruff check src/`, `mypy src/`,
+   and `pytest --cov`.
+
+## Execution Plan
+
+### Phase 1: Standalone TUI mode and configuration
+
+Inputs:
+- `src/mcpbridge_wrapper/__main__.py`
+- `src/mcpbridge_wrapper/webui/config.py`
+- existing broker/Web UI CLI flag behavior
+
+Outputs:
+- `--tui` argument parsing and validation
+- Web UI endpoint resolution for host, port, and optional auth credentials
+- clear errors for unsupported flag combinations
+
+Verification:
+- `main()` routes cleanly into TUI mode
+- `--tui` does not accidentally start bridge, proxy, or broker-daemon codepaths
+
+### Phase 2: Terminal frontend runtime
+
+Inputs:
+- `GET /api/broker/status`
+- `POST /api/control/stop`
+- broker log path conventions from `BrokerConfig.default()`
+
+Outputs:
+- new `src/mcpbridge_wrapper/tui.py` module
+- polling client + screen model + curses runner
+- keyboard actions for refresh, quit, and stop
+
+Verification:
+- healthy and degraded states render distinct operator-facing output
+- unreachable backend and auth failures produce actionable terminal messages
+
+### Phase 3: Validation and integration hardening
+
+Inputs:
+- TUI runtime implementation
+- parser/main tests and pure rendering tests
+
+Outputs:
+- unit test coverage for TUI rendering, HTTP control, and CLI wiring
+- validation report with required quality gate results
+
+Verification:
+- the TUI remains dependency-free and CI-stable
+- quality gates remain green with coverage at or above project threshold
+
+## Acceptance Tests
+
+- `pytest tests/unit/test_tui.py`
+- `pytest tests/unit/test_main_tui.py`
+- `pytest`
+- `ruff check src/`
+- `mypy src/`
+- `pytest --cov`
+
+## Decision Points
+
+- The TUI should be a standalone mode (`--tui`), not a secondary view embedded
+  into `--broker-daemon`, so operator lifecycle stays explicit and predictable.
+- The TUI should consume the existing broker-hosted Web UI APIs rather than
+  opening the broker socket directly; that keeps one runtime contract for both
+  browser and terminal frontends.
+- Recent activity should come from the recommended local `broker.log` tail. The
+  status API already covers health, while the log tail adds human-readable event
+  context without expanding the HTTP schema again in `P6-T2`.
+
+## Notes
+
+- Keep user-facing documentation mostly scoped to `P6-T3`, aside from any small
+  inline CLI/help text needed for correctness.
+- Prefer pure helper functions for layout and formatting so the curses shell is
+  thin and easy to test.
+- Review subject name for this task: `broker_terminal_frontend`.
+
+---
+**Archived:** 2026-03-07
+**Verdict:** PASS

SPECS/ARCHIVE/P6-T2_Build_a_terminal_frontend_for_broker_daemon_monitoring_and_control/P6-T2_Validation_Report.md

@@ -0,0 +1,83 @@
+# P6-T2 Validation Report
+
+**Task:** P6-T2 — Build a terminal frontend for broker daemon monitoring and control
+**Date:** 2026-03-07
+**Verdict:** PASS
+
+## Summary
+
+Implemented a terminal frontend for the broker daemon by:
+
+- adding a curses-backed TUI module in `src/mcpbridge_wrapper/tui.py`
+- wiring `--tui` into `src/mcpbridge_wrapper/__main__.py`
+- resolving dashboard endpoint/auth settings from existing Web UI config
+- surfacing broker runtime details from `/api/control` and `/api/broker/status`
+- adding local PID/socket/version fallback details and broker-log tailing
+- normalizing wildcard/IPv6 dashboard bind hosts into client-safe TUI endpoints
+- tailing broker logs from the end of the file so refresh cost stays bounded
+- degrading gracefully when `broker.log` is temporarily unreadable
+- adding dedicated unit coverage for runtime resolution, HTTP aggregation,
+  rendering, interactive loop behavior, and main CLI integration
+
+## Files Validated
+
+- `src/mcpbridge_wrapper/tui.py`
+- `src/mcpbridge_wrapper/__main__.py`
+- `tests/unit/test_tui.py`
+- `tests/unit/test_main_tui.py`
+
+## Targeted Verification
+
+```bash
+PYTHONPATH=src pytest tests/unit/test_tui.py tests/unit/test_main_tui.py -q
+```
+
+- Result: `40 passed`
+
+```bash
+ruff check src/mcpbridge_wrapper/tui.py src/mcpbridge_wrapper/__main__.py tests/unit/test_tui.py tests/unit/test_main_tui.py
+```
+
+- Result: `All checks passed!`
+
+```bash
+mypy src/mcpbridge_wrapper/tui.py src/mcpbridge_wrapper/__main__.py
+```
+
+- Result: `Success: no issues found in 2 source files`
+
+## Required Quality Gates
+
+```bash
+PYTHONPATH=src pytest
+```
+
+- Result: `827 passed, 5 skipped in 8.06s`
+
+```bash
+ruff check src/
+```
+
+- Result: `All checks passed!`
+
+```bash
+mypy src/
+```
+
+- Result: `Success: no issues found in 19 source files`
+
+```bash
+PYTHONPATH=src pytest --cov
+```
+
+- Result: `827 passed, 5 skipped in 9.16s`
+- Coverage: `91.52%`
+
+## Notes
+
+- `PYTHONPATH=src` was required for local `pytest` invocations because the
+  package is not installed into the active interpreter environment.
+- The TUI depends only on the Python standard library plus the existing local
+  Web UI API surface; no new project dependency was introduced.
+- Remaining warnings are pre-existing `websockets` / `uvicorn` deprecations and
+  are not introduced by this task.

SPECS/ARCHIVE/_Historical/REVIEW_broker_terminal_frontend.md

@@ -0,0 +1,70 @@
+## REVIEW REPORT — Broker Terminal Frontend
+
+**Scope:** `origin/main..HEAD`
+**Files:** 9
+**Date:** 2026-03-07
+
+---
+
+### Summary Verdict
+- [x] Approve
+- [ ] Approve with comments
+- [ ] Request changes
+- [ ] Block
+
+---
+
+### Critical Issues
+
+None.
+
+---
+
+### Secondary Issues
+
+None.
+
+---
+
+### Architectural Notes
+
+- The standalone `--tui` mode stays consistent with the project's existing
+  hand-rolled mode dispatch in `__main__.py` and avoids introducing any new CLI
+  or terminal UI dependency.
+- The TUI reuses the broker-hosted Web UI APIs (`/api/control`,
+  `/api/control/stop`, `/api/broker/status`) instead of opening another broker
+  transport, so browser and terminal frontends share one runtime contract.
+- The final implementation hardens two operational edges that matter for a
+  broker dashboard: bind hosts are normalized into client-safe URLs
+  (wildcard/IPv6-safe), and broker log tailing now degrades gracefully on read
+  errors while keeping refresh work bounded to tail-sized reads.
+
+---
+
+### Tests
+
+- Validation report confirms:
+  - `PYTHONPATH=src pytest tests/unit/test_tui.py tests/unit/test_main_tui.py -q`
+    -> `40 passed`
+  - `ruff check src/mcpbridge_wrapper/tui.py src/mcpbridge_wrapper/__main__.py tests/unit/test_tui.py tests/unit/test_main_tui.py`
+    -> pass
+  - `mypy src/mcpbridge_wrapper/tui.py src/mcpbridge_wrapper/__main__.py`
+    -> pass
+  - `PYTHONPATH=src pytest` -> `827 passed, 5 skipped`
+  - `ruff check src/` -> pass
+  - `mypy src/` -> pass
+  - `PYTHONPATH=src pytest --cov` -> `91.52%`
+- The focused TUI tests now cover:
+  - CLI routing and invalid flag combinations
+  - auth/header propagation and HTTP error shaping
+  - wildcard/IPv6 host normalization for dashboard attachment
+  - bounded tail reads and unreadable `broker.log` fallback behavior
+  - curses loop behavior for refresh, stop, and quit actions
+
+---
+
+### Next Steps
+
+- FOLLOW-UP skipped: no actionable review findings remain after the final
+  hardening pass.
+- Proceed to `ARCHIVE-REVIEW`, then open the PR for `P6-T2`.

SPECS/INPROGRESS/next.md

@@ -1,18 +1,15 @@
-# Next Task: P6-T2 — Build a terminal frontend for broker daemon monitoring and control
+# Next Task: P6-T3 — Document the explicit dedicated-host frontend workflow
 
-**Priority:** P1
+**Priority:** P2
 **Phase:** Phase 6: Explicit Broker Frontend
-**Dependencies:** P6-T1
+**Effort:** 4h
+**Dependencies:** P6-T1, P6-T2
 **Status:** Ready
 
 ## Description
 
-Implement a terminal-first operator interface for the broker daemon so users can explicitly see whether the daemon is running, whether upstream Xcode connectivity is healthy, which clients are attached, and what recent reconnect/error events occurred. The interface should give a clearer operational model than auto-spawn alone.
-
-## Recently Archived
-
-- `P6-T1` — Add explicit broker runtime status surface for frontend consumers (`PASS`, archived 2026-03-07)
+Update the operator docs so the recommended path for multi-editor setups is an explicit dedicated broker host plus a single monitoring frontend. The docs should explain when to prefer a dedicated host over implicit auto-spawn, how to verify that both editors share one daemon, and how the new frontend fits into that workflow.
 
 ## Next Step
 
-Run the PLAN command for `P6-T2` and define the TUI scope, entrypoint, and control flow against the new broker runtime status API.
+Run the PLAN command to document the dedicated-host workflow, multi-editor validation steps, and terminal frontend usage.

SPECS/Workplan.md

@@ -438,19 +438,20 @@ Add new tasks using the canonical template in [TASK_TEMPLATE.md](TASK_TEMPLATE.m
   - [x] Status makes reconnecting/not-ready states explicit so a frontend can distinguish them from a healthy shared daemon
   - [x] Automated tests cover both healthy and degraded broker runtime status responses
 
-#### ⬜️ P6-T2: Build a terminal frontend for broker daemon monitoring and control
+#### ✅ P6-T2: Build a terminal frontend for broker daemon monitoring and control
+- **Status:** ✅ Completed (2026-03-07)
 - **Description:** Implement a terminal-first operator interface for the broker daemon so users can explicitly see whether the daemon is running, whether upstream Xcode connectivity is healthy, which clients are attached, and what recent reconnect/error events occurred. The interface should give a clearer operational model than auto-spawn alone.
 - **Priority:** P1
 - **Dependencies:** P6-T1
 - **Parallelizable:** no
 - **Outputs/Artifacts:**
-  - `src/mcpbridge_wrapper/` TUI entrypoint/module for broker monitoring and control
-  - Tests covering the TUI status rendering and control integration where practical
-  - CLI/docs wiring for launching the TUI
+  - `src/mcpbridge_wrapper/tui.py` terminal frontend for broker monitoring and stop control
+  - `src/mcpbridge_wrapper/__main__.py` CLI wiring for `--tui`
+  - `tests/unit/test_tui.py` and `tests/unit/test_main_tui.py` covering runtime resolution, rendering, control requests, and CLI integration
 - **Acceptance Criteria:**
-  - [ ] Users can launch a terminal UI from the wrapper package to inspect broker runtime state without tailing logs manually
-  - [ ] The TUI shows at minimum broker state, daemon/upstream PIDs, connected client count, and recent broker events or reconnect indicators
-  - [ ] The TUI exposes at least one explicit control action for the daemon lifecycle (for example stop or restart)
+  - [x] Users can launch a terminal UI from the wrapper package to inspect broker runtime state without tailing logs manually
+  - [x] The TUI shows at minimum broker state, daemon/upstream PIDs, connected client count, and recent broker events or reconnect indicators
+  - [x] The TUI exposes at least one explicit control action for the daemon lifecycle (for example stop or restart)
 
 #### ⬜️ P6-T3: Document the explicit dedicated-host frontend workflow
 - **Description:** Update the operator docs so the recommended path for multi-editor setups is an explicit dedicated broker host plus a single monitoring frontend. The docs should explain when to prefer a dedicated host over implicit auto-spawn, how to verify that both editors share one daemon, and how the new frontend fits into that workflow.