[Cedric Vidal (cedricvidal)]

Summary

Depends on #1603 (cedricvidal-decouple-pnpm-bootstrap at 9406483ab1acc86d0a5386ab2d424348d6291bd9) and is the host-endpoint verification layer in the user-requested seven-PR native stack registered by #1608.

Original problem: Docker Compose can report healthy containers and published port mappings even when the selected runtime VM does not expose those ports to the host. A Portal healthcheck succeeding inside its container therefore did not prove that localhost was usable. Portal reachability also did not prove that the Copilot worker had created its queue and connected to MongoDB, so the startup command could present a success-shaped stack that could not process runs.

This layer:

• verifies the Portal root, API /ready, and gateway /health/ready through the actual published host ports before printing their URLs as usable;
• verifies Copilot worker readiness separately using a running container plus the existing queue-created and MongoDB-connected startup signals;
• uses bounded attempts, per-request timeouts, small backoff, nonzero failure, secret-safe output, and distinct diagnostics for unhealthy/not-running containers, healthy containers with host-unreachable published ports, reachable non-ready HTTP responses, and missing worker readiness;
• preserves foreground/watch signal and exit propagation, detached starts, explicit infra-only starts, and non-up Compose commands;
• never inspects, selects, restarts, or changes the user's Docker context/runtime.

Acceptance-discovered lifecycle regression: the first implementation started the bounded verifier at the same time as docker compose up --build --watch. On a cold Podman build, the selected containers legitimately remained not-created while images compiled. Those polls consumed the readiness budget, after which the verifier failed and terminated Compose before containers could be created.

Correction: the wrapper now resolves the selected application services and waits for Compose to create every selected container before starting the bounded endpoint/worker window. That pre-readiness gate is tied to the Compose lifecycle, not another arbitrary clean-build timer: long legitimate builds may continue, while a nonzero Compose build/start exit is propagated immediately and cannot wait forever. Once containers exist, the original bounded readiness and failure contracts apply unchanged.

Current PR head is 1c495ee3c9f8a483093013ca595f76d80c2e9253, a normal merge of the readiness fix head 5d78953acb6313bc8294e5d5a1e5371c7619e54c with the updated dependent base 9406483ab1acc86d0a5386ab2d424348d6291bd9. The PR remains draft and targets the dependent branch, not main.

Demos

Before

N/A — developer startup tooling only. The reproduced failure was a healthy in-container Portal with no host listener, followed during cumulative acceptance by a cold Podman build being terminated while services were still not-created.

After

N/A — deterministic process/Docker/curl stubs cover the complete lifecycle and diagnostics without disrupting unrelated user containers. A bounded real Podman cold-build run also confirmed the verifier no longer starts during image compilation.

Testing

• PASS — focused behavior and Compose rendering tests: pnpm exec vitest run scripts/verify-dev-stack.test.ts scripts/docker-compose.test.ts --reporter=default — 14/14 tests passed. Coverage includes success, delayed readiness, non-success HTTP, connection refusal, healthy-container/host-unreachable distinction, unhealthy service, worker-not-ready, bounded attempts, secret-safe output, wrapper success/failure propagation, a long not-created build phase followed by creation/readiness, and immediate propagation of Compose build exit 17 without endpoint probes.
• PASS — focused typecheck: pnpm exec vitest run scripts/verify-dev-stack.test.ts --reporter=default --typecheck.enabled — 13/13 tests passed; no type errors.
• PASS — shell syntax: bash -n scripts/dev-compose.sh scripts/verify-dev-stack.sh.
• PASS — rendered full development Compose configuration: GITHUB_TOKEN='' NPM_CONFIG_REGISTRY='https://registry.npmjs.org/' docker compose -f docker-compose.yml -f docker-compose.dev.yml --profile mongodb --profile auth --profile portal --profile copilot config --quiet.
• PASS — license headers after synchronizing the dependent base: pnpm headers:check — all 967 in-scope files have the required header.
• PASS — patch integrity: git diff --check.
• PASS — bounded real Podman lifecycle evidence: GITHUB_TOKEN="$(gh auth token)" pnpm docker:dev:copilot ran for approximately 55 minutes through cold image compilation. During that legitimate build, no selected application containers existed and captured output contained zero occurrences of both Verifying published development endpoints and Development stack readiness verification failed. The attempt was deliberately stopped before all cold images completed rather than spending unbounded time; it therefore did not reach live endpoint verification, but it directly confirms the acceptance regression—premature verifier timeout during builds—is removed.
• PASS — final-base CI at head 1c495ee3c9f8a483093013ca595f76d80c2e9253: CI run 41753422826 completed successfully, including License Headers, Third-party NOTICE, Unit Tests (Node.js 22), Lint Code, Build Applications, CLI Bundle Integration Tests, and CI Summary. Secret Scan run 41753422881, Pull Request Labeler run 41753422813, both gitleaks checks, and CLA also passed. Path-filtered queue/worker integration, gateway, Windows worker, and LLM-eval jobs were skipped as expected for this diff.

Documentation and compatibility

Updated CONTRIBUTING.md and docs/architecture/overview.md with the verified-ready contract, clean-build lifecycle gate, worker readiness boundary, and failure interpretation.

No API, CLI, dependency, migration, persisted-data, Docker-context, or runtime-selection changes. Existing non-up Compose commands, explicit infra-only starts, detached behavior, and published endpoint/worker contracts remain compatible. Because this is a dependent stack layer, upper branches may need the stack's server-side rebase/sync operation after this lower-layer head changes.

Checklist

All checklist items are N/A for this developer startup-script and documentation change.

• If Portal features changed, keep CLI capabilities in sync.
• If Portal components changed, update their Storybook stories.
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible.
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed.
• Video showing the behavior before the suggested change
• Video showing the behavior after the suggested change

[github-actions]

Test Results (Node.js 22)

test: Run #444

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3256	3256	0	0	0	0	0	1m31s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #448

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3258	3258	0	0	0	0	0	1m16s

🎉 All tests passed!

Github Test Reporter

[github-actions]

Test Results (Node.js 22)

test: Run #454

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3258	3258	0	0	0	0	0	1m30s

🎉 All tests passed!

Github Test Reporter

[Cedric Vidal (cedricvidal)]

Closing this layer because the host-port verification approach is no longer part of the onboarding stack. Colima host forwarding is out of scope, and the surviving fixes do not depend on this verifier.