[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
Fixes a regression where N concurrent lazy init_client calls each blocked a default executor thread for up to 10s while LaunchDarkly was down, which could starve other asyncio.to_thread work.

Concurrent first-time inits now share a single _InitAttempt, aligned with the TypeScript SDK. One daemon thread builds LDClient with start_wait=10; callers on any event loop or thread wait on a shared concurrent.futures.Future, with per-loop waiters so cancelling one caller does not tear down the attempt for the rest. Failed attempts are still not cached: all waiters get the same error, unadopted clients are closed, and the next call retries.

Lifecycle edge cases are tightened under _state_lock: shutdown() or a BYOC init_client(client=...) abandons an in-flight attempt (waiters get abandoned or the passed client); adoption no longer races telemetry setup. The README now states that concurrent lazy calls share one attempt instead of each building their own client.

Tests replace the old “two clients” race with gated-SDK coverage for shared attempts, shared failure, cross-thread/cross-loop join, shutdown/BYOC replacement, and cancellation behavior.

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

[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 be42e21. Configure here.}

[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.