epic-5/story-2: Add Post-MVP Automatic Config Refresh by usmanabbas7 · Pull Request #44 · convertcom/python-sdk

usmanabbas7 · 2026-06-08T14:02:34Z

Story 5.2 — Add Post-MVP Automatic Config Refresh

Part of sprint sprint/2026-04-06-convert-python-sdk. Stacked on epic-5/story-1 (PR #43 → … → Epic 3 chain).

Implements FR31 (post-MVP, opt-in automatic config refresh). MVP behavior is byte-for-byte unchanged when refresh=None (the default).

What was built

RefreshConfig (frozen dataclass) on SDKConfig.refresh: Optional[RefreshConfig] = None, with __post_init__ validation. Opt-in only — default spins up no daemon thread, emits no events, adds no cost.
ConfigRefresher daemon-thread worker (config_loader/refresh.py) — reuses the existing Story 1.2 Transport Protocol and the existing load_snapshot pipeline (no parallel transport). Interruptible sleep, deterministic test seams (no wall-clock timing in tests).
Atomic snapshot swap on Core (mutex-protected) so in-flight evaluations always see a single coherent snapshot; long-lived Context objects retain their creation-time snapshot. Core.refresh_now(), Core.close(), and context-manager protocol added.
Failure handling (AC-3): transient failures back off; the prior good snapshot keeps serving; failures surface via Story 4.1's diagnostic logger + Story 4.2's typed-error contract; background failures never crash the host process. refresh.start/success/skipped/fail/worker_crashed diagnostics.
JS parity: TrackingQueue.update_snapshot_metadata() re-points account/project IDs on swap; LifecycleEvent.CONFIG_UPDATED fires on each successful refresh.
Direct-config guard: RefreshConfig + direct config emits refresh.skipped instead of silently ignoring.
Docs: docs/initialization.md refresh-policy section; docs/migration-from-javascript.md unit/default-divergence mapping; towncrier fragment.

ADR gate (audit F-027 + F-028)

docs/adr/0001-config-refresh-concurrency-and-backoff.md ratifies the mutex-protected swap (atomic w.r.t. an evaluating caller, safe under free-threaded CPython 3.13+ — not relying on GIL atomicity) and every concrete backoff/interval/jitter value (interval 300s, jitter 30s, factor 2.0, max 600s).

Audit findings addressed

F-032 — AC-3 (background-failure resilience) retained and fully implemented.
F-027 — atomic swap; concurrency mechanism ratified in ADR 0001.
F-028 — backoff numeric values ratified in ADR 0001.
F-053 — Task 5 docs trace to FR31 (not FR54).

Tests

762 tests pass (was 732; +30 in tests/test_config_refresh.py). scripts/verify_release.py all gates green (ruff, mypy --strict, coverage ≥85% / evaluation ≥95%, parity suite, towncrier draft, uv build).

Beads

epic ai-driven-product-dev-14vo; tasks -9hwq / -577c / -usaq / -eugx / -5r84 (all closed).

Sprint-mode notes

Readiness gate: composite 8.6/10 PASS round 1; 5 ambiguities (clock seam, lifecycle placement, CONFIG_UPDATED reconciliation, F-027 concurrency, F-028 backoff) auto-delegated "your call" in sprint mode and resolved in the conductor's assessment report.
Code review: passed (round 1 fixed a stop() self-join deadlock guard + worker_crashed coverage; round 2 clean).

🤖 Generated with Claude Code

gemini-code-assist

Code Review

This pull request implements an opt-in automatic config refresh feature using a background daemon thread with mutex-protected atomic snapshot swaps, exponential backoff, and lifecycle event emissions. The review feedback highlights critical resilience issues, specifically potential OverflowError crashes during backoff calculations under persistent failures, and a race condition in the thread shutdown logic that could spawn duplicate active daemon threads.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

gemini-code-assist · 2026-06-08T14:04:58Z

+        backed_off = self._policy.interval_seconds * (
+            self._policy.backoff_factor ** self._consecutive_failures
+        )
+        return backed_off >= self._policy.backoff_max_seconds


Under persistent network or endpoint failures, self._consecutive_failures will grow indefinitely. When calculating self._policy.backoff_factor ** self._consecutive_failures, this will eventually raise an OverflowError (e.g., 2.0 ** 1024 overflows in Python), crashing the background daemon thread and preventing any future retries. Catching OverflowError ensures the worker remains resilient and correctly caps the backoff at backoff_max_seconds.

try: backed_off = self._policy.interval_seconds * ( self._policy.backoff_factor ** self._consecutive_failures ) return backed_off >= self._policy.backoff_max_seconds except OverflowError: return True

gemini-code-assist · 2026-06-08T14:04:58Z

+        if self._consecutive_failures > 0:
+            backed_off = base * (self._policy.backoff_factor ** self._consecutive_failures)
+            base = min(backed_off, self._policy.backoff_max_seconds)


Similarly to _at_terminal_backoff, calculating the exponential backoff here can raise an OverflowError if self._consecutive_failures grows large. Catching OverflowError and falling back to backoff_max_seconds prevents the daemon thread from crashing.

if self._consecutive_failures > 0: try: backed_off = base * (self._policy.backoff_factor ** self._consecutive_failures) base = min(backed_off, self._policy.backoff_max_seconds) except OverflowError: base = self._policy.backoff_max_seconds

gemini-code-assist · 2026-06-08T14:04:58Z

+        thread = self._thread
+        if (
+            thread is not None
+            and thread.is_alive()
+            and thread is not threading.current_thread()
+        ):
+            thread.join(timeout=timeout)
+        self._thread = None


Setting self._thread = None at the end of stop() before the thread has actually exited (or when called re-entrantly from the worker thread itself where join() is skipped) creates a race condition. If start() is called immediately after, it will see self._thread as None, clear self._stopping, and spawn a new thread. The old thread, seeing self._stopping cleared, will continue running, resulting in duplicate active daemon threads. Keeping the reference to self._thread if it is still alive prevents start() from clearing self._stopping and spawning a duplicate thread.

Suggested change

thread = self._thread

if (

thread is not None

and thread.is_alive()

and thread is not threading.current_thread()

):

thread.join(timeout=timeout)

self._thread = None

thread = self._thread

if (

thread is not None

and thread.is_alive()

and thread is not threading.current_thread()

):

thread.join(timeout=timeout)

if not thread.is_alive():

self._thread = None

Beads: ai-driven-product-dev-9hwq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Beads: ai-driven-product-dev-577c Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

…— implementation (GREEN) Beads: ai-driven-product-dev-577c Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

…t — tests (RED) Beads: ai-driven-product-dev-usaq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

…king re-point — implementation (GREEN) Beads: ai-driven-product-dev-usaq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Beads: ai-driven-product-dev-eugx Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

…rier fragment Beads: ai-driven-product-dev-5r84 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

…shed coverage) - stop() skips self-join when called from worker thread (deadlock guard) - remove pragma; test refresh.worker_crashed guard + re-entrant stop Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

usmanabbas7 · 2026-06-15T12:12:28Z

F-066 propagation (rebase onto remediated 3-3)

Rebased --onto the remediated 5-1 (dropping the now-duplicated [REL-1] parent commit). This branch's own commits do not touch evaluation/segments.py, so the F-066 latch is inherited cleanly — segments.py byte-identical to remediated 3-3, two latch parity tests present. No conflicts.

uv run pytest → 772 passed · uv run ruff check clean · uv run mypy --strict clean (44 files)
CI gate: PASSED — all 21 checks green (ruff, mypy --strict, changelog, build, bounds-check, full py3.9–3.13 × {ubuntu,macos,windows} matrix).

abbaseya · 2026-06-18T16:30:51Z

Superseded — all commits already in main (bc76b64). Closing without merge as part of post-sprint cleanup.

usmanabbas7 self-assigned this Jun 8, 2026

usmanabbas7 requested a review from clllaur June 8, 2026 14:02

gemini-code-assist Bot reviewed Jun 8, 2026

View reviewed changes

usmanabbas7 mentioned this pull request Jun 8, 2026

epic-5/story-3: Add Planned Expansion Surfaces for Async and Framework Integrations #45

Closed

usmanabbas7 force-pushed the epic-5/story-1-establish-maintainer-release-and-parity-validation-workflow branch from 13f7556 to 87786af Compare June 14, 2026 17:13

usmanabbas7 force-pushed the epic-5/story-2-add-post-mvp-automatic-config-refresh branch from b99ceaa to 65349c2 Compare June 14, 2026 17:15

usmanabbas7 force-pushed the epic-5/story-1-establish-maintainer-release-and-parity-validation-workflow branch from 87786af to 331edf0 Compare June 15, 2026 12:03

usmanabbas7 and others added 9 commits June 15, 2026 17:08

wf(wf-52ref): [SDK-1] RefreshConfig surface — tests (RED)

cdd8f33

Beads: ai-driven-product-dev-9hwq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-1] RefreshConfig + ADR 0001 — implementation (GREEN)

9326370

Beads: ai-driven-product-dev-9hwq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-2] ConfigRefresher + Core swap seam — tests (RED)

6ddf7b4

Beads: ai-driven-product-dev-577c Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-2] ConfigRefresher worker + atomic Core swap seam …

8b0b43f

…— implementation (GREEN) Beads: ai-driven-product-dev-577c Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-3] failure/backoff/CONFIG_UPDATED/tracking re-poin…

ae0a8bc

…t — tests (RED) Beads: ai-driven-product-dev-usaq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-3] failure/backoff/diagnostics/CONFIG_UPDATED/trac…

7fd834d

…king re-point — implementation (GREEN) Beads: ai-driven-product-dev-usaq Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-4] MVP-stability + thread-safety regression — tests

cfcd5c9

Beads: ai-driven-product-dev-eugx Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

wf(wf-52ref): [SDK-5] docs refresh section + JS migration map + townc…

dac6aef

…rier fragment Beads: ai-driven-product-dev-5r84 Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

usmanabbas7 force-pushed the epic-5/story-2-add-post-mvp-automatic-config-refresh branch from 65349c2 to 8a6badc Compare June 15, 2026 12:08

abbaseya closed this Jun 18, 2026

abbaseya deleted the epic-5/story-2-add-post-mvp-automatic-config-refresh branch June 18, 2026 16:30

Navigation Menu

Uh oh!

epic-5/story-2: Add Post-MVP Automatic Config Refresh - #44

epic-5/story-2: Add Post-MVP Automatic Config Refresh#44
usmanabbas7 wants to merge 9 commits into
epic-5/story-1-establish-maintainer-release-and-parity-validation-workflowfrom
epic-5/story-2-add-post-mvp-automatic-config-refresh

usmanabbas7 commented Jun 8, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Uh oh!

usmanabbas7 commented Jun 15, 2026

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

usmanabbas7 commented Jun 8, 2026

Story 5.2 — Add Post-MVP Automatic Config Refresh

What was built

ADR gate (audit F-027 + F-028)

Audit findings addressed

Tests

Beads

Sprint-mode notes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

usmanabbas7 commented Jun 15, 2026

F-066 propagation (rebase onto remediated 3-3)

Uh oh!

abbaseya commented Jun 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants