# Backend Restart and Health Check Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Restart the process occupying the configured backend port and report deployment success only after the replacement backend is listening.

**Architecture:** Add testable process/port helpers to `deploy_tool/deployer.py`, then compose them in the existing background runner. Add a main-thread deployment state guard to `deploy_tool/gui.py` so both deploy buttons share one running state.

**Tech Stack:** Python standard library, `unittest`, Tkinter, Windows `netstat` and `taskkill`.

---

### Task 1: Listener discovery and process replacement

**Files:**
- Modify: `tests/test_deployer.py`
- Modify: `deploy_tool/deployer.py`

- [ ] Add failing tests for server-port extraction and parsing IPv4/IPv6 `netstat` listener rows.
- [ ] Run the targeted tests and confirm they fail because the helpers do not exist.
- [ ] Implement `_extract_server_port()` and `_parse_windows_listening_pids()`.
- [ ] Run the targeted tests and confirm they pass.
- [ ] Add a failing test proving listener PIDs are terminated and the port must become free before launch.
- [ ] Implement listener lookup, process-tree termination, and bounded port-release polling.
- [ ] Run all deployer tests.

### Task 2: Backend startup readiness

**Files:**
- Modify: `tests/test_deployer.py`
- Modify: `deploy_tool/deployer.py`

- [ ] Add failing tests for early child exit, startup timeout cleanup, and successful readiness.
- [ ] Run the targeted tests and confirm the current immediate-success behavior fails them.
- [ ] Refactor the background runner behind injectable `_restart_backend()` dependencies.
- [ ] Add Windows detached-process creation flags and a timestamped log separator.
- [ ] Poll child state and TCP readiness; return non-zero on early exit or timeout.
- [ ] Run all deployer tests.

### Task 3: Duplicate GUI deployment guard

**Files:**
- Modify: `tests/test_gui_navigation.py`
- Modify: `deploy_tool/gui.py`

- [ ] Add failing tests that a running deployment ignores another invocation and that button state is updated together.
- [ ] Run the targeted tests and confirm failure.
- [ ] Store both deployment button instances, add `deployment_running`, and centralize button state changes.
- [ ] Set the guard before the worker starts and clear it when `deploy_done` is handled.
- [ ] Run GUI tests.

### Task 4: Verification

**Files:**
- Verify: `deploy_tool/deployer.py`
- Verify: `deploy_tool/gui.py`
- Verify: `tests/test_deployer.py`
- Verify: `tests/test_gui_navigation.py`

- [ ] Run `python -m unittest discover -s tests -p 'test_*.py' -v` and require zero failures.
- [ ] Run `python -m compileall -q deploy_tool main.py tests` and require exit code 0.
- [ ] Inspect `git diff --check` and the final diff for unrelated changes.