Keep usable Xcode routes responsive when sibling processes stall

[lynnswap]

Purpose

Keep MCP client startup and tool discovery responsive when multiple GUI Xcode processes are running and one process never produces a tool catalog.

The proxy already lets the first compatible route complete protocol initialization, but foreground tools/list still waited for every exposed process catalog. A workspace-backed route could therefore be blocked by an initialized, workspace-less sibling until the sibling timed out.

Changes

• Return the currently available process-catalog union immediately, while keeping partial results separate from the canonical all-route cache.
• Let a cold foreground load complete from its first valid route, cancel the remaining structured children, and restart missing route catalogs under the background refresh owner.
• Coalesce background catalog admission per active route load while preserving intentional concurrent foreground loads.
• Keep exact catalog leases, RPC cancellation, request cleanup, later full-union publication, and notifications/tools/list_changed under their existing owners.
• Cover downstream initialize first-success, sibling cancellation, partial repeat reads, background full-union completion, cataloged-route XcodeListWindows, failure/recovery boundaries, and overlapping foreground/background loads.
• Document the available-surface versus canonical-catalog contract.

Review focus

• The available subset is client-visible but remains non-canonical until every currently required route catalog is present.
• Background refresh coalescing prevents repeated clients from multiplying stalled RPCs without changing foreground overlap semantics.
• Unresolved explicit window-owner hints still retain complete conflict detection; only catalog-surface window discovery skips uncataloged routes once a usable catalog exists.

Testing

• scripts/check.sh
  • standard package suite
  • XcodeMCPProcessRuntimeTests (24 tests)
  • ProxyStdioAdapterTests (13 tests)
• swift test --no-parallel --filter 'ControlPlaneAuthorityTests|RuntimeCoordinatorRecoveryTests|RuntimeCoordinatorCatalogTests' -Xswiftc -strict-concurrency=minimal (115 tests)
• git diff --check
• Branch-wide Codex review against main: clean, 0 findings

Fixes #191

[chatgpt-codex-connector]

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

[lynnswap]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-02T08:31:14.048801Z	f7537a6	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Already looking forward to the next diff.

Reviewed commit: f7537a6e53

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".