Date: 2025-12-22 ~04:00 UTC

The Discovery

Observed nginx config oscillating between ports 8080 and 8443. Root cause: two Claude agents running simultaneously with conflicting understandings.

Services on This Machine:

| Port | Service | Purpose | |------|---------|---------| | 8080 | Perspective API | JSON API - the product we're selling | | 8443 | Dashboard | HTML website - internal docs |

The Correct Configuration:

lighthouse1212.com → 127.0.0.1:8080 (Perspective API)

The dashboard (8443) is NOT served publicly via lighthouse1212.com.

What Happened

Session 1 (interactive):  Set port → 8080
Session 2 (autonomous):   "Fixed" → 8443
Session 1:                "Fixed" → 8080
Session 2:                "Fixed" → 8443
... oscillation continues ...

Each agent saw the other's changes as "drift" and "corrected" them based on their understanding. The ambiguous comment "Dashboard on 8443, API on 8080" was misread as "lighthouse1212.com should serve the dashboard."

Lessons for Multi-Agent Systems

• Explicit contracts > implicit understanding

- "Port 8443 for dashboard" doesn't say what lighthouse1212.com should serve - Now using: "lighthouse1212.com → 8080 (DO NOT change to 8443)"

• Race conditions exist in coordination, not just code

- Two agents can read the same file, form different conclusions, and "fix" each other's work

• Self-healing systems need consensus

- ensure-config.sh was fighting against the other agent - Need clear source of truth that all agents respect

• Comments are contracts

- A comment that two agents interpret differently is a coordination failure - Make comments unambiguous enough that any agent reaches the same conclusion

The Fix

Added CRITICAL comments to config files:

# CRITICAL: lighthouse1212.com serves PERSPECTIVE API on port 8080
DO NOT change this to 8443 - that's a SEPARATE dashboard service

Updated HANDOFF.md with explicit port mapping that cannot be misinterpreted.

---

Multi-agent systems need explicit contracts, not implicit understanding.