@mock_only
Feature: PluginState.EXECUTING lifecycle state
  The PluginManager must set the EXECUTING state when a plugin method is
  being invoked, completing the plugin lifecycle state machine as defined
  in the specification.

  Based on issue #5691.

  # -----------------------------------------------------------------------
  # Happy path: execute_plugin transitions ACTIVATED -> EXECUTING -> ACTIVATED
  # -----------------------------------------------------------------------

  Scenario: execute_plugin transitions plugin to ACTIVATED after successful execution
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I execute method "search" on plugin "exec-plugin" with valid args
    Then the plugin "exec-plugin" state should be "activated"

  Scenario: execute_plugin returns the method result
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I execute method "search" on plugin "exec-plugin" with valid args
    Then the execution result should be an empty list

  # -----------------------------------------------------------------------
  # Error path: execute_plugin transitions ACTIVATED -> EXECUTING -> ERRORED
  # -----------------------------------------------------------------------

  Scenario: execute_plugin transitions plugin to ERRORED on method exception
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I attempt to execute a failing method on plugin "exec-plugin"
    Then the plugin "exec-plugin" state should be "errored"
    And a PluginError should be raised

  Scenario: execute_plugin wraps method exceptions in PluginError
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I attempt to execute a failing method on plugin "exec-plugin"
    Then a PluginError should be raised
    And the plugin error message should contain "execution failed"

  # -----------------------------------------------------------------------
  # Guard: execute_plugin requires ACTIVATED state
  # -----------------------------------------------------------------------

  Scenario: execute_plugin raises PluginError if plugin is not activated
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I attempt to execute method on non-activated plugin "exec-plugin"
    Then a PluginError should be raised

  Scenario: execute_plugin raises PluginError if plugin is in ERRORED state
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I attempt to execute a failing method on plugin "exec-plugin"
    And I attempt to execute method on non-activated plugin "exec-plugin"
    Then a PluginError should be raised

  # -----------------------------------------------------------------------
  # Thread safety: EXECUTING state prevents concurrent deactivation
  # -----------------------------------------------------------------------

  Scenario: Cannot deactivate a plugin that is in EXECUTING state
    Given a fresh PluginManager instance
    And a PluginDescriptor for "exec-plugin" with module "cleveragents.domain.models.acms.stubs" and class "InMemoryTextBackend"
    When I register the plugin descriptor
    And I activate the plugin "exec-plugin"
    And I manually set plugin "exec-plugin" state to "executing"
    And I attempt to deactivate the plugin "exec-plugin"
    Then a PluginError should be raised

  # -----------------------------------------------------------------------
  # PluginState enum includes EXECUTING
  # -----------------------------------------------------------------------

  Scenario: PluginState enum includes the EXECUTING value
    Given the PluginState enum is available
    Then it should have values "discovered", "activated", "executing", "deactivated", "errored"

  # -----------------------------------------------------------------------
  # execute_plugin raises PluginNotFoundError for unknown plugin
  # -----------------------------------------------------------------------

  Scenario: execute_plugin raises PluginNotFoundError for unknown plugin
    Given a fresh PluginManager instance
    When I attempt to execute method on unknown plugin "nonexistent-plugin"
    Then a PluginNotFoundError should be raised