Feature: Test infrastructure determinism — flaky test example
  As a CleverAgents developer
  I want the test suite to be fully deterministic
  So that CI results are reliable and do not mask real regressions

  # This feature was created to resolve the flaky-test detection alert for
  # ``test_example_flaky_test`` (issue #1542).  The root cause was that the
  # async-job heartbeat step used a bare ``time.sleep(0.01)`` that was
  # insufficient on fast CI runners, causing the "heartbeat updated" assertion
  # to fail intermittently when two consecutive ``datetime.now(UTC)`` calls
  # returned the same microsecond value.
  #
  # The fix replaces the fixed sleep with a monotonic busy-wait that spins
  # until the clock has actually advanced, making the step deterministic on
  # any hardware.  The scenarios below verify that the fixed implementation
  # is stable across repeated executions.

  Background:
    Given an async job store is initialised

  # -- Core determinism: heartbeat timestamp always advances -----------------

  Scenario: test_example_flaky_test - heartbeat timestamp strictly advances after busy-wait
    Given I create a new async job for plan "01HXYZ01HXYZ01HXYZ01HXYZ01" phase "execute"
    When I mark the async job as running with worker "worker-determinism-1"
    And I record a heartbeat on the async job
    Then the async job last_heartbeat should be updated

  Scenario: Heartbeat timestamp advances on a second consecutive recording
    Given I create a new async job for plan "01HXYZ01HXYZ01HXYZ01HXYZ01" phase "execute"
    When I mark the async job as running with worker "worker-determinism-2"
    And I record a heartbeat on the async job
    And I record a heartbeat on the async job
    Then the async job last_heartbeat should be updated

  Scenario: Heartbeat recording is rejected for a queued job
    Given I create a new async job for plan "01HXYZ01HXYZ01HXYZ01HXYZ01" phase "execute"
    When I try to record a heartbeat on the async job
    Then a ValueError should be raised for heartbeat

  Scenario: Heartbeat recording is rejected for a completed job
    Given I create a running async job
    And I mark the async job as succeeded
    When I try to record a heartbeat on the async job
    Then a ValueError should be raised for heartbeat

  # -- Busy-wait guard: step never hangs indefinitely ------------------------

  Scenario: Busy-wait heartbeat step completes within a reasonable wall-clock budget
    Given I create a new async job for plan "01HXYZ01HXYZ01HXYZ01HXYZ01" phase "execute"
    When I mark the async job as running with worker "worker-determinism-4"
    And I record a heartbeat on the async job within 2 seconds
    Then the async job last_heartbeat should be updated