stop-server.sh reports success without verifying process died

[robert-mstr]

Bug

scripts/stop-server.sh in the brainstorming visual companion sends SIGTERM to the server process and immediately reports {"status": "stopped"} without verifying the process actually exited. In practice, the node server can survive the signal and keep running on the port.

Steps to Reproduce

1. Start the visual companion: scripts/start-server.sh --project-dir /path/to/project
2. Stop it: scripts/stop-server.sh <screen_dir>
3. Script reports {"status": "stopped"}
4. Check: lsof -i :<port> — server is still listening

Root Cause

In stop-server.sh (lines 18-28):

if [[ -f "$PID_FILE" ]]; then
  pid=$(cat "$PID_FILE")
  kill "$pid" 2>/dev/null        # sends SIGTERM
  rm -f "$PID_FILE" ...          # immediately removes PID file
  echo '{"status": "stopped"}'   # reports success without checking
fi

No verification that the process actually died. The PID file is also deleted, so retrying is not possible.

Suggested Fix

Wait for graceful shutdown, escalate to SIGKILL if needed:

if [[ -f "$PID_FILE" ]]; then
  pid=$(cat "$PID_FILE")
  kill "$pid" 2>/dev/null
  
  # Wait for graceful shutdown
  for i in {1..20}; do
    kill -0 "$pid" 2>/dev/null || break
    sleep 0.1
  done
  
  # Force kill if still alive
  if kill -0 "$pid" 2>/dev/null; then
    kill -9 "$pid" 2>/dev/null
  fi
  
  rm -f "$PID_FILE" "${SCREEN_DIR}/.server.log"
  # ...
fi

Environment

• Superpowers v5.0.2
• macOS (Darwin 24.6.0)
• Node.js server started via nohup + disown

[obra]

Fixed in v5.0.5 — stop-server.sh now confirms the process is dead before reporting success (SIGTERM + 2s wait + SIGKILL fallback).