Multi-project port management to prevent conflicts and orphaned servers

[adamdaum]

Summary

When running ralph.sh on multiple codebases on the same machine, all projects default to localhost:3000. This causes port collisions, and stale dev servers from one project can block another. There's also no centralized tracking of which ports are in use, leading to orphaned processes.

Current Behavior

• dev-up.sh hardcodes port 3000 for the Next.js dev server
• coding_prompt.md hardcodes curl http://localhost:3000 for server readiness checks
• PID tracking is local to each project (.dev-server.pid), but nothing prevents two projects from fighting over the same port
• If a user switches between projects without running dev-down.sh, the old server stays running and blocks the new one
• fuser/lsof port cleanup is reactive (kills whatever is on the port) rather than scoped to the current project

Proposal

1. Per-project port assignment

• Add a PORT or DEV_PORT variable to .env.local (generated during scaffolding)
• dev-up.sh reads this variable and starts the server on that port
• coding_prompt.md references the port dynamically instead of hardcoding 3000
• create-ralph-loop CLI could auto-assign a port (e.g., 3000 + hash of project name, or sequential from 3000)

2. Global process registry

• Maintain a lightweight registry file (e.g., ~/.ralph/servers.json) tracking active dev servers:

  [
    { "project": "/home/user/my-app", "port": 3000, "pid": 12345, "started": "2025-06-08T10:00:00Z" },
    { "project": "/home/user/other-app", "port": 3001, "pid": 12346, "started": "2025-06-08T11:30:00Z" }
  ]

• dev-up.sh registers on start, dev-down.sh deregisters on stop
• A cleanup command (ralph cleanup or dev-cleanup.sh) can scan the registry and kill orphaned processes

3. Orphan detection

• On startup, check if the PID in .dev-server.pid is still alive and belongs to this project
• Check the global registry for stale entries (PID no longer running)
• Auto-clean orphans before starting a new server

Considerations

• Port range should avoid common conflicts (databases on 5432/3306, other dev tools)
• The registry approach is optional — projects should still work standalone without it
• init_prompt.md and coding_prompt.md need to reference port dynamically via env var