Local backend startup review#

Reviewed source and test commit: 4b37df090402469cafed0cf9f5e16b9528dae60f. This follows the public-app receiving review and auth dependency update. It concerns test setup and workspace discovery, not an adapter production defect. There is no shipped adapter production code change.

The root agent reported that the browser CI job exited before test collection with the official Convex CLI error Requested port 43330 is not available. That establishes an unavailable requested port. It does not establish which process occupied it or why. The fixture had imposed that machine-wide port requirement itself.

Contract and repair#

Without a user port override, the fixture should start an isolated local backend on available ports rather than require its former fixed numbers. The reviewer inspected all three setup call sites and the installed Convex 1.47 CLI source. Its anonymous deployment path calls chooseLocalBackendPorts, which delegates to detect-port: explicit requested ports are mandatory, while defaults and suggestions can select other available ports. The default search starts at 3210. The test does not calculate or promise the allocator's exact result.

All three setups now omit mandatory port arguments by default. The existing CONVEX_TEST_PORT override still supplies an explicit port to the main fixture. The shared launcher retains strict loopback URL validation and verifies the exact requested port when one was supplied. No custom free-port allocator, retry loop, or silent fallback for an explicit override was added.

A separate workspace discovery issue was also repaired. Auth setup creates an ignored auth-app/runtime/package.json, which the broad packages/** workspace glob could discover during concurrent pnpm checks. An exact exclusion now keeps that generated runtime out of the workspace project set. The real auth fixture remains a workspace package. This changes configuration, not dependency versions or lockfile resolutions.

Witness and execution evidence#

e2e/backend-startup-oracle.test.ts supplies an independent resource judgment: while the old public fixture port 43320 is occupied, setup must fulfill and provide another loopback port serving a fresh empty upstream messages query. It invokes the actual pinned public-app setup and queries the real backend. Expected startup success and empty data do not come from copying CLI selection logic. An explicit startup-fulfillment assertion precedes the URL and query observations.

The reviewer inspected that test, the setup changes, cleanup paths, workspace exclusion, and installed CLI implementation. The following execution evidence comes from the author and root agent, it is not presented as an independent rerun by this reviewer:

• Restoring the former fixed 43320 setup argument failed the startup-fulfillment assertion in 292 ms with Requested port 43320 is not available. This is the intended startup outcome comparison. The later query checkpoint was not reached, so this is not a failure at a data comparison.
• Restoring default allocation passed in 1.05 seconds and reached the actual upstream empty-page query, including isDone: true.
• The first combined 18-test run passed with normal allocation. A second run held port 43330 from before pnpm and global setup began, matching the occupied auth-port condition from CI, and all 18 tests passed in 33.69 seconds. The root agent verified and terminated its own blocker afterward. Only this second run establishes the specifically occupied auth-port condition.
• Final package typecheck and ESLint passed. With a synthetic generated runtime package present, pnpm list -r succeeded and excluded it. The synthetic runtime was removed afterward.

The fixed startup witness runs in the normal backend suite. It releases its own listener and backend independently through the existing failure-preserving cleanup instrument. EADDRINUSE is accepted as an observation of an existing external owner at bind time, that owner's lifetime is not leased by the test, and the test never closes it.

Scope#

This closes the fixture's mandatory-default-port assumption for the reviewed serial setup paths. The public fixture regression observes the shared startup boundary directly; the complete suite also receives the auth setup under its formerly required occupied port. The source inspection confirms that all three call sites delegate their default choice to the same supported CLI path.

This is a fixed native startup witness, not a generated port-allocation model or a proof against every concurrent bind race. It does not promise startup when no ports are available, override an occupied port explicitly requested by a user, or identify the owner of the original CI port. Network access and backend availability remain setup prerequisites. Existing public-app, auth, pagination, and offline contracts and their recorded limits are unchanged.