FE-1529: Document the local optimizer loop and make its launcher self-healing

[kube]

🌟 What is the purpose of this PR?

Documents yarn dev:petrinaut-optimization in the architecture docs and makes its launcher recover from its own leftovers. Replaces #9388 (same ticket, different stack): this version also fixes the failure where a container leaked by a hard-killed launcher holds port 4004 and every later launch exits with "port is already allocated" before Vite starts — reproduced today with a 46-minute-old petrinaut-opt-website-dev-71483.

🔗 Related links

• FE-1529 (internal)
• Replaces FE-1529: Document the local optimizer loop #9388

🔍 What does this change?

apps/petrinaut-website/scripts/optimization-dev.mjs:

• Uses one fixed container name (petrinaut-opt-website-dev) and, before starting, force-removes any container matching it — including the PID-suffixed names earlier versions leaked. A launcher that never reached its cleanup no longer blocks every later run, and the image rebuild stays meaningful: a leftover would keep serving the code it was built from.
• Reuses an optimizer the launcher does not own that already serves 127.0.0.1:4004 healthily (the compose stack's container, or a bare uvicorn), skipping Docker entirely; teardown leaves it alone. Launcher-owned leftovers never reach this check — they are removed first. (From FE-1529: Document the local optimizer loop #9388.)
• Forwards extra arguments to Vite, so yarn dev:petrinaut-optimization --port 5175 --strictPort pins the website port. (From FE-1529: Document the local optimizer loop #9388.)

Docs:

• Adds libs/@local/petrinaut-arch-docs/content/optimizer/running-the-loop-locally.mdx (from FE-1529: Document the local optimizer loop #9388), with the step list updated to the new leftover-sweep and scoped-reuse behaviour. The rest of the page — the /optimization route gate, the request path through the Vite proxy and the petrinaut serve subprocess, and the no-Docker uvicorn flow — carries over unchanged.

🐾 How to test

1. yarn dev:petrinaut-optimization, then kill -9 the launcher — the container survives (this is the leak).
2. yarn dev:petrinaut-optimization again: it prints "Removing leftover Petrinaut Opt dev container…", rebuilds, and reaches Vite. Before this change it exited with "Bind for 127.0.0.1:4004 failed: port is already allocated".
3. With the compose stack's optimizer running instead: it prints "Reusing the optimizer already serving…" and leaves it running on exit.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• require changes to docs which are made as part of this PR

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hash	Ready	Preview	Aug 28, 2026 12:30am
petrinaut	Ready	Preview	Aug 28, 2026 12:30am
petrinaut-docs	Ready	Preview	Aug 28, 2026 12:30am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hashdotdesign-tokens	Ignored		Aug 28, 2026 12:30am