fix(webserver): refuse to boot when a fixed port is already bound

[ChampionDesigns]

Summary

The app could boot with no API at all and say nothing.

startWebServer binds two fixed ports: 8080 for the REST and WebSocket API, and 4001 for the API
docs. main() wrapped the call in a bare catch that logged "failed to start web server" and
carried on.

That failure is close to invisible. The WebUI binds an ephemeral port and is unaffected, so the
skin still loads and the app looks normal — only every REST call and every WebSocket behind it is
gone. BootTiming.mark('webserver_up') fires either way. The user sees an app that opened
correctly and then misbehaves, with the reason only in the log.

Two Decaid-family apps installed on one device share those fixed ports, so the common cause is
simply that the other one is already running.

Base: main. Independent.

Design notes

• serveOrReportPortInUse raises a typed WebServerPortInUse for EADDRINUSE and rethrows
  every other failure unchanged, so a permission denial keeps its own error path and is never
  reported to the user as a port clash.
• isAddressInUse matches the OS code per platform — 98 on Linux and Android, 48 on macOS and
  iOS, 10048 on Windows — because Dart reports the raw code and does not normalise it.
• main() stops on WebServerPortInUse and shows a screen naming the port, offering "Check again"
  and "Close this app".

Linked Issue

N/A

Verification

• flutter analyze — clean.
• flutter test — full suite 3904 passed against current main, including
  port_binding_test and webserver_port_conflict_app_test.
• dart format — clean on every changed file.
• Verified on hardware. This change ships in the Decaid-Canary build Ben runs on his own
  machine, and has been exercised in normal use rather than only under test.

Impact

• User-visible: the app now refuses to boot and says which port is taken, instead of running
  without an API. That is a deliberate behaviour change.
• Compatibility: none for a normal single-app install; the path is only reached when a bind
  fails.
• API: none.
• Security: none. A permission failure is not swallowed as a port clash.

Contributor Responsibility

AI-assisted development is allowed. The submitter remains responsible for the submitted work.

• I have reviewed and understand all changes in this PR and take responsibility for their correctness, security, behavior, licensing, and provenance, including any AI-assisted or AI-generated work.

[tadelv]

There is one required fix before this should merge:

startWebServer() binds the real REST/WS server on 8080 first and only then calls startApiDocsServer() on 4001. This PR converts both binds to WebServerPortInUse, and main() treats either one as fatal. That means a conflict on 4001 only now aborts normal app startup even though the actual API on 8080 has already started successfully. It also leaves that successfully-created 8080 HttpServer alive while the conflict UI is shown, because the server reference is local to startWebServer() and never gets closed on the later 4001 exception.

That broadens the fix beyond the stated failure mode and can create a confusing self-inflicted port conflict. Please make only failure to bind the required 8080 REST/WS API fatal, or otherwise make startup transactional and explicitly clean up 8080 if 4001 is intentionally required too. Given that 4001 serves API docs, I would strongly prefer keeping a docs-port failure non-fatal and logging it. Please add a regression test for the 4001-conflict case so the core API/app remains usable (or, if both ports are deliberately mandatory, that 8080 is rolled back cleanly).

Aside from this, the typed EADDRINUSE handling, error propagation for non-address-in-use failures, focused tests, and rationale placement are consistent with the repository guidance.

[ChampionDesigns]

Fixed in 0867bbaf, the way you preferred: a docs-port failure is non-fatal now.

Your reading of the code was correct. startWebServer binds 8080 first and then
calls startApiDocsServer() for 4001, both through serveOrReportPortInUse, and
main() treated either as fatal. So a conflict on 4001 alone aborted a boot whose
API had already started, and left that 8080 HttpServer open behind the conflict
screen — startWebServer holds the only reference to it, exactly as you said.

startApiDocsServer now catches WebServerPortInUse for its own port, logs a
warning, and returns. The docs are unavailable and the app runs. Only a failure to
bind the required 8080 REST/WS API still reaches main() and shows
WebServerPortConflictApp.

The function returns the HttpServer it created, or null when the port was
busy, so both outcomes are assertable without a new global.

Regression test: test/unit/services/webserver/api_docs_server_port_test.dart.
With 4001 held, startApiDocsServer() completes and returns null, and the
holder keeps the port; with 4001 free it returns a server bound to 4001. The first
test fails with WebServerPortInUse(port: 4001) if the exception is rethrown
instead of caught, so it pins the behaviour rather than just describing it.

doc/AI_API_NOTES.md records the split and why, replacing the design note that
said "the boot stops" without qualification.

Verification: flutter analyze clean, flutter test 3437 passed / 1 skipped,
dart format --set-exit-if-changed clean under Dart 3.13.3.

[tadelv]

Re-checked the update. The requested blocker is resolved: port 4001/API-docs conflicts are now handled locally as non-fatal, while only failure to bind the required 8080 REST/WS API reaches the fatal startup path. The added regression coverage exercises both the occupied and free docs-port cases. The implementation and rationale placement remain consistent with AGENTS.md, and current CI passes format, analyze, full tests, and Linux smoke build. No further blocking issues found.