CS-10564, CS-10699: Fix env var port leaks and prerender heartbeat escape

[habdelra]

Summary

• CS-10564: Replace module-level env var constants (DEFAULT_REALM_SERVER_PORT, DEFAULT_COMPAT_REALM_SERVER_PORT, DEFAULT_PRERENDER_PORT, CONFIGURED_PRERENDER_URL) with explicit CLI args and function parameters. Strips ambient port env vars at shared.ts module load to prevent dev shell pollution. Follows the pattern from CS-10560 (worker-manager port fix).
• CS-10699: Test harness prerender servers were escaping their hermetic seal and registering with external prerender managers (e.g. the dev-all manager on :4222), causing stale heartbeat entries like Heartbeat sweep: prerender server http://localhost:44289 is stale; removing. Fixed by setting PRERENDER_MANAGER_URL to an unreachable address (http://127.0.0.1:1) when spawning test harness prerender servers, so their heartbeats never reach the outside manager. This is safe because the test harness doesn't use a prerender manager at all — the worker-manager and realm-server talk directly to the prerender server via --prerendererUrl, bypassing the manager entirely. The heartbeat registration is a side-effect from the prerender server code designed for the production/dev-all multi-server setup.
• Worktree host dist fix: test-run-execution.ts defaulted hostDistDir to a worktree-relative path that fails in worktrees where the host app hasn't been built locally. Now uses findHostDistPackageDir() to resolve from the root repo checkout first, matching how support-services.ts already resolves the host dist for the main app.

Files changed

File	Change
shared.ts	Strip 4 ambient env vars, remove 4 module-level constants, add compatRealmServerPort/realmServerPort/prerenderURL to FactoryRealmOptions
isolated-realm-stack.ts	Accept realmServerPort and prerenderURL as explicit params
api.ts	Thread new port params through to startIsolatedRealmStack and resolveFactoryRealmLocation
serve-realm.ts	Parse --realmServerPort, --compatRealmServerPort, --prerenderURL CLI args
fixtures.ts	Pass ports as CLI args to serve-realm.ts instead of env vars
support-services.ts	Remove DEFAULT_PRERENDER_PORT import, set PRERENDER_MANAGER_URL to unreachable address so test prerender servers can't register with external managers
test-run-execution.ts	Use findHostDistPackageDir() for host dist lookup, fixing worktree test execution

Test plan

• Unit tests pass (386/386)
• ESLint and Prettier pass
• Playwright tests pass (23/25 on first run — 2 failures were the host dist worktree issue, now fixed)
• Re-run factory-test-realm.spec.ts to confirm host dist fix
• Verify no prerender heartbeat messages appear in dev-all when running tests

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR tightens the software-factory harness’ test isolation by removing ambient env-var–driven port configuration in favor of explicit CLI args / function params, and prevents harness-spawned prerender servers from registering heartbeats with external prerender managers. It also improves host dist resolution for worktrees when executing QUnit runs via Playwright.

Changes:

• Replace env-var-based default port/prerender configuration with explicit --realmServerPort, --compatRealmServerPort, and --prerenderURL plumbing through the harness.
• Prevent harness prerender servers from heartbeating to external prerender managers by overriding PRERENDER_MANAGER_URL when spawning the prerender server.
• Fix worktree failures by resolving the host dist directory via findHostDistPackageDir() before falling back to a worktree-local path.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/software-factory/tests/fixtures.ts	Spawn serve-realm.ts with explicit port/prerender CLI flags instead of env vars.
packages/software-factory/src/harness/support-services.ts	Default prerender port selection to dynamic ports; force PRERENDER_MANAGER_URL to a local unreachable URL for harness prerender servers.
packages/software-factory/src/harness/shared.ts	Strip several ambient env vars at module load; add explicit port/prerender options; remove module-level defaults sourced from env.
packages/software-factory/src/harness/isolated-realm-stack.ts	Thread explicit realmServerPort and prerenderURL into isolated stack startup and prerender reuse logic.
packages/software-factory/src/harness/api.ts	Thread new options through to location resolution and isolated stack startup.
packages/software-factory/src/cli/serve-realm.ts	Add simple CLI parsing for the new flags and adjust positional arg handling.
packages/software-factory/scripts/lib/test-run-execution.ts	Resolve host dist using findHostDistPackageDir() to improve worktree behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.