[XieX]

Stacked on #254. Retarget to main once #254 merges.

Problem

Since #254, init_client raises when the client it built has not initialized within start_wait=10, and caches nothing so a later call retries. While LaunchDarkly is unreachable, every lazy call (config().invoke(), graph(), inspect_config) builds its own client in asyncio.to_thread and blocks for 10 s. N concurrent callers each hold a default-executor thread for that long, which can starve other to_thread users.

Change

Concurrent first calls now share one in-flight attempt, as the TypeScript SDK's initClient does.

• The attempt builds the client on a daemon thread it starts itself, not on a default-executor thread. Its result is a concurrent.futures.Future, so callers on any event loop or thread can join it. The skills watcher, for example, runs asyncio.run on its own thread.
• The attempt thread adopts the client itself, under _state_lock. Each caller waits on a future of its own loop, which is woken through call_soon_threadsafe, so cancelling one caller leaves the attempt running for the rest. (asyncio.wrap_future would cancel the shared future.)
• Every caller of a failed attempt gets the same error. The attempt is cleared before any of them sees it, so a later call retries. A failure is still not cached.
• The attempt closes its client instead of adopting it when shutdown() ran, when a client was passed in, or when every caller waiting on it was cancelled. A lone cancelled call still leaves nothing behind. Before this change, an attempt still in flight when shutdown() ran adopted its client afterwards.
• Callers waiting on an attempt that a passed-in client replaced get the passed client, as before.
• The README no longer says concurrent calls each build their own client.

Tests

New tests in packages/client/tests/test_lifecycle.py use a client constructor that blocks until the test releases it:

• 5 concurrent calls construct one client.
• 5 concurrent calls during a failing init construct one client, all raise, and the client is closed once; a later call constructs a new one.
• Cancelling one of two waiters doesn't cancel the attempt for the other.
• A call from asyncio.run on another thread joins the attempt.
• shutdown() abandons an attempt in flight.
• A client passed in mid-attempt replaces the attempt.

The old two-calls-build-two-clients test was replaced, since it tested the old behavior.

make lint format-check typecheck api-report-check test passes: 3805 passed, 18 skipped.

🤖 Generated with Claude Code

---

Note

Overview
Concurrent lazy init_client calls now share a single in-flight connection attempt instead of each starting its own 10-second LD client build on the default executor (which could starve other asyncio.to_thread work during outages).

The lifecycle module introduces _InitAttempt guarded by _state_lock: one daemon thread builds the client and settles a shared concurrent.futures.Future, while each async caller waits on a loop-local future wired via call_soon_threadsafe so cancelling one waiter does not tear down the attempt for others. Failed attempts are still not cached; shutdown(), a BYOC client passed mid-flight, or no remaining waiters abandons the attempt (closes the built client, raises abandoned where appropriate, and uses a successor when BYOC replaced the attempt). README text is updated to match.

Lifecycle tests replace the old “two concurrent calls → two clients” expectation with coverage for shared success/failure, cross-loop join, shutdown/BYOC races, and cancellation edge cases.

^{Reviewed by Cursor Bugbot for commit cecb9b0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Stale Bugbot comment from a previous run.

[jeffdupont]

The shared-attempt design is sound. I checked cancellation (per-loop futures, waiters only under the lock), retry after failure (attempt cleared before the future settles), and the all-cancelled path; they behave as described. Three timed-out wait_for calls during an outage build one client.

Requesting changes for the two spec mismatches in the inline comments (passed client when the built client is uninitialized, and shutdown followed by re-init). Both are small. Please add tests for those two orders and for "all waiters cancelled, a new caller joins before the attempt finishes".

Nit: start_wait=10 and the "10 seconds" in the message and docstring could be one constant.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 6452178. Configure here.}