|
| 1 | +# P4-T1 PRD — Auto-restart stale broker daemon on version mismatch after upgrade |
| 2 | + |
| 3 | +## Task Metadata |
| 4 | + |
| 5 | +- **Task ID:** P4-T1 |
| 6 | +- **Phase:** Phase 4: Broker Lifecycle Management |
| 7 | +- **Priority:** P0 |
| 8 | +- **Dependencies:** none |
| 9 | +- **Source:** `SPECS/Workplan.md` open task entry |
| 10 | + |
| 11 | +## Objective Summary |
| 12 | + |
| 13 | +Prevent stale broker daemons from surviving wrapper upgrades and silently serving old behavior to new `--broker` clients. The wrapper must use a single version source of truth, persist daemon runtime version in broker state, detect mismatch before proxy reuse, and automatically restart stale daemons. The CLI must also expose explicit lifecycle control (`--broker-status`, `--broker-stop`) so users and scripts can inspect and remediate broker state without manual PID/socket file handling. |
| 14 | + |
| 15 | +The implementation scope includes runtime behavior, CLI surface, install/uninstall operational safety, docs, and regression tests. Backwards compatibility requirement: legacy daemons without a version file must still be accepted as compatible unless a mismatch can be proven. |
| 16 | + |
| 17 | +## Success Criteria |
| 18 | + |
| 19 | +1. `__version__` is derived from package metadata (`importlib.metadata`) instead of hard-coded constants. |
| 20 | +2. Broker daemon writes `broker.version` on startup and removes it during shutdown/cleanup paths. |
| 21 | +3. Proxy detects mismatched daemon version and auto-restarts stale daemon before connecting. |
| 22 | +4. Missing `broker.version` file is treated as compatible (no forced restart). |
| 23 | +5. `--broker-status` reports PID/status/version info and mismatch warning. |
| 24 | +6. `--broker-stop` gracefully stops daemon, waits for exit, and removes pid/socket/version state files. |
| 25 | +7. Install and uninstall scripts stop any running broker daemon before replacing/removing wrapper files. |
| 26 | +8. Broker-mode docs describe new lifecycle commands and version management flow. |
| 27 | +9. Required quality gates pass: `pytest`, `ruff check src/`, `mypy src/mcpbridge_wrapper`, `pytest --cov=src/mcpbridge_wrapper --cov-report=term-missing` (>= 90%). |
| 28 | + |
| 29 | +## Acceptance Tests |
| 30 | + |
| 31 | +- Unit tests for `BrokerConfig.version_file` path derivation. |
| 32 | +- Unit tests for daemon version-file write/remove and status payload version field. |
| 33 | +- Unit tests for proxy version mismatch detection and restart behavior. |
| 34 | +- Unit tests for `_parse_broker_args` handling of `--broker-status` and `--broker-stop`. |
| 35 | +- CLI behavior validation: |
| 36 | + - `python -m mcpbridge_wrapper --broker-status` |
| 37 | + - `python -m mcpbridge_wrapper --broker-stop` |
| 38 | +- Script-level behavior validation for install/uninstall broker-stop logic (covered by shell-path checks and existing script tests if present). |
| 39 | + |
| 40 | +## Test-First Plan |
| 41 | + |
| 42 | +1. Add/extend tests for version file state in broker config and daemon lifecycle. |
| 43 | +2. Add/extend proxy tests for mismatch detection, backward-compatible no-version behavior, and stale daemon restart. |
| 44 | +3. Add/extend main/CLI tests for new broker control flags and argument parsing. |
| 45 | +4. Implement runtime logic minimally to satisfy new failing tests. |
| 46 | +5. Update docs and scripts after runtime tests pass. |
| 47 | +6. Run full quality gates and capture outputs in validation report. |
| 48 | + |
| 49 | +## Implementation Plan (Hierarchical TODO) |
| 50 | + |
| 51 | +### Phase A — Version Source and Broker State |
| 52 | + |
| 53 | +- **Inputs:** Existing `__version__` declaration, `BrokerConfig`, daemon lifecycle logic. |
| 54 | +- **Outputs:** Metadata-derived version string; `version_file` property; daemon writes/cleans version file; status includes version. |
| 55 | +- **Verification:** New daemon/config unit tests pass and stale-lock cleanup removes version artifacts. |
| 56 | + |
| 57 | +### Phase B — Proxy and CLI Lifecycle Controls |
| 58 | + |
| 59 | +- **Inputs:** Proxy spawn/reuse flow, broker arg parsing and command dispatch in `__main__.py`. |
| 60 | +- **Outputs:** Version mismatch detection + stale daemon restart; `--broker-status`; `--broker-stop` cleanup behavior. |
| 61 | +- **Verification:** New proxy/main tests pass and manual status/stop commands return expected output/exit semantics. |
| 62 | + |
| 63 | +### Phase C — Operational Scripts, Docs, and Validation |
| 64 | + |
| 65 | +- **Inputs:** `scripts/install.sh`, `scripts/uninstall.sh`, `docs/broker-mode.md`, quality gate tooling. |
| 66 | +- **Outputs:** Install/uninstall stop running daemon before file replacement/removal; docs updated for status/stop/version behavior; validation report. |
| 67 | +- **Verification:** Required quality gates pass; acceptance criteria checklist fully satisfied. |
| 68 | + |
| 69 | +## Decision Points and Constraints |
| 70 | + |
| 71 | +- Use defensive behavior when metadata/version files are unavailable: prefer safe fallback over hard failure. |
| 72 | +- Keep broker-stop idempotent (safe when daemon already dead or files are stale/corrupt). |
| 73 | +- Avoid introducing behavior that depends on non-portable process APIs beyond existing macOS/Linux constraints. |
| 74 | +- Keep implementation scoped to P4-T1 artifacts; do not refactor unrelated broker subsystems. |
| 75 | + |
| 76 | +## Notes (Post-Completion Docs/Artifacts) |
| 77 | + |
| 78 | +- Create `SPECS/INPROGRESS/P4-T1_Validation_Report.md` with command evidence and verdict. |
| 79 | +- Archive PRD and validation report to `SPECS/ARCHIVE/P4-T1_Auto_restart_stale_broker_daemon_on_version_mismatch_after_upgrade/`. |
| 80 | +- Mark `P4-T1` complete in `SPECS/Workplan.md` and update `SPECS/ARCHIVE/INDEX.md`. |
| 81 | +- Create and archive `REVIEW_p4_t1_broker_version_restart.md` after review. |
| 82 | + |
| 83 | +--- |
| 84 | +**Archived:** 2026-03-05 |
| 85 | +**Verdict:** PASS |
0 commit comments