AutoDeploy/docs/superpowers/plans/2026-07-14-backend-restart-healthcheck.md

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.