claude-smart 0.2.44 → 0.2.46

package/plugin/vendor/reflexio/reflexio/server/services/playbook/playbook_service_utils.py

@@ -5,8 +5,9 @@ from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
 
-from reflexio.models.api_schema.domain.entities import Interaction
+from reflexio.models.api_schema.domain.entities import Interaction, UserPlaybook
 from reflexio.models.api_schema.internal_schema import RequestInteractionDataModel
+from reflexio.models.structured_output import StrictStructuredOutput
 from reflexio.server.prompt.prompt_manager import PromptManager
 from reflexio.server.services.playbook.playbook_service_constants import (
     PlaybookServiceConstants,
@@ -21,6 +22,35 @@ from reflexio.server.services.service_utils import (
 
 logger = logging.getLogger(__name__)
 
+
+def _normalized_playbook_key(playbook: UserPlaybook) -> tuple[str, str]:
+    """Return the same-batch duplicate key for a user playbook."""
+    return (
+        (playbook.trigger or "").strip().casefold(),
+        playbook.content.strip().casefold(),
+    )
+
+
+def dedupe_and_drop_empty(playbooks: list[UserPlaybook]) -> list[UserPlaybook]:
+    """Drop empty user playbooks and collapse exact same-batch duplicates.
+
+    This is intentionally deterministic and local to one extraction batch. The
+    LLM-backed consolidator still handles semantic deduplication against stored
+    rows when its feature flag is enabled.
+    """
+    deduped: list[UserPlaybook] = []
+    seen: set[tuple[str, str]] = set()
+    for playbook in playbooks:
+        if not playbook.content.strip():
+            continue
+        key = _normalized_playbook_key(playbook)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(playbook)
+    return deduped
+
+
 # ===============================
 # Pydantic classes for playbook_extraction_main prompt output schema
 # ===============================
@@ -84,7 +114,7 @@ class StructuredPlaybookContent(BaseModel):
         return bool(self.content and self.content.strip())
 
 
-class StructuredPlaybookList(BaseModel):
+class StructuredPlaybookList(StrictStructuredOutput):
     """
     Wrapper schema for extracting zero or more playbook entries in a single LLM call.
 
@@ -105,7 +135,7 @@ class StructuredPlaybookList(BaseModel):
     )
 
 
-class PlaybookAggregationOutput(BaseModel):
+class PlaybookAggregationOutput(StrictStructuredOutput):
     """
     Output schema for the playbook_aggregation prompt.
 

package/plugin/vendor/reflexio/reflexio/server/services/playbook/{playbook_generation_service.py → service.py}

@@ -8,6 +8,7 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     from reflexio.server.api_endpoints.request_context import RequestContext
     from reflexio.server.llm.litellm_client import LiteLLMClient
+    from reflexio.server.services.storage.storage_base import BaseStorage
 
 from reflexio.models.api_schema.internal_schema import RequestInteractionDataModel
 from reflexio.models.api_schema.service_schemas import (
@@ -26,8 +27,8 @@ from reflexio.server.services.base_generation_service import (
     BaseGenerationService,
     StatusChangeOperation,
 )
-from reflexio.server.services.playbook.playbook_aggregator import PlaybookAggregator
-from reflexio.server.services.playbook.playbook_extractor import PlaybookExtractor
+from reflexio.server.services.playbook.components.aggregator import PlaybookAggregator
+from reflexio.server.services.playbook.components.extractor import PlaybookExtractor
 from reflexio.server.services.playbook.playbook_service_constants import (
     PlaybookServiceConstants,
 )
@@ -45,6 +46,33 @@ from reflexio.server.services.service_utils import (
 logger = logging.getLogger(__name__)
 
 
+def read_user_playbook_as_of_for_learning(
+    storage: BaseStorage, *, user_playbook_id: int, served_at: int
+) -> UserPlaybook | None:
+    """Return the exact cited playbook row iff its body is still attributable.
+
+    This is the strict learning-time read path: it dereferences ONLY the cited
+    id, never follows merged/superseded pointers to a current survivor. When the
+    exact row body is unavailable or was revised in-place after ``served_at``,
+    the row is unattributable and the helper returns ``None``.
+    """
+    playbook = storage.get_user_playbook_by_id(
+        user_playbook_id, include_tombstones=True
+    )
+    if playbook is None:
+        return None
+    if playbook.created_at >= served_at:
+        return None
+    if not playbook.content.strip():
+        return None
+    events = storage.get_lineage_events(
+        entity_type="user_playbook", entity_id=str(user_playbook_id)
+    )
+    if any(event.op == "revise" and event.created_at >= served_at for event in events):
+        return None
+    return playbook
+
+
 @dataclass
 class PlaybookGenerationServiceConfig:
     """Runtime configuration for playbook generation service shared across all extractors.
@@ -84,6 +112,9 @@ class PlaybookGenerationService(
     Runs the configured PlaybookExtractor for each generation request.
     """
 
+    # Playbook generation produces learnings — opt in to ② Learning billing.
+    EMITS_LEARNING_BILLING: bool = True
+
     def __init__(
         self,
         llm_client: LiteLLMClient,
@@ -257,12 +288,19 @@ class PlaybookGenerationService(
 
     def _finalize_extracted_items(self, all_playbooks: list[UserPlaybook]) -> None:
         """Deduplicate, persist, and aggregate extracted user playbook items."""
+        from reflexio.server.services.playbook.playbook_service_utils import (
+            dedupe_and_drop_empty,
+        )
+
+        all_playbooks = dedupe_and_drop_empty(all_playbooks)
+
         # Deduplicate against existing entries in DB when deduplicator is enabled
         existing_ids_to_delete: list[int] = []
+        merge_groups: list[tuple[int, list[int]]] = []
         from reflexio.server.site_var.feature_flags import is_deduplicator_enabled
 
         if is_deduplicator_enabled(self.org_id):
-            from reflexio.server.services.playbook.playbook_consolidator import (
+            from reflexio.server.services.playbook.components.consolidator import (
                 PlaybookConsolidator,
             )
 
@@ -276,7 +314,11 @@ class PlaybookGenerationService(
                 llm_client=self.client,
                 dedup_config=dedup_config,
             )
-            deduplicated_playbooks, existing_ids_to_delete = consolidator.deduplicate(
+            (
+                deduplicated_playbooks,
+                existing_ids_to_delete,
+                merge_groups,
+            ) = consolidator.deduplicate(
                 [all_playbooks],
                 self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
                 self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
@@ -308,21 +350,9 @@ class PlaybookGenerationService(
             try:
                 self.storage.save_user_playbooks(all_playbooks)  # type: ignore[reportOptionalMemberAccess]
                 self._enqueue_user_playbook_optimization(all_playbooks)
-
-                # Delete superseded existing entries only after save succeeds
-                if existing_ids_to_delete:
-                    try:
-                        deleted_count = self.storage.delete_user_playbooks_by_ids(  # type: ignore[reportOptionalMemberAccess]
-                            existing_ids_to_delete
-                        )
-                        logger.info(
-                            "Deleted %d superseded existing entries", deleted_count
-                        )
-                    except Exception as e:
-                        logger.error(
-                            "Failed to delete superseded existing entries: %s",
-                            str(e),
-                        )
+                self._apply_consolidation_lineage(
+                    all_playbooks, merge_groups, existing_ids_to_delete
+                )
             except Exception as e:
                 logger.error(
                     "Failed to save %s results for request id: %s due to %s, exception type: %s",
@@ -331,12 +361,73 @@ class PlaybookGenerationService(
                     str(e),
                     type(e).__name__,
                 )
+                raise
 
             # Trigger playbook aggregation
             if not self.output_pending_status and not self.skip_aggregation:
                 logger.info("Trigger playbook aggregation")
                 self._trigger_playbook_aggregation()
 
+    def _apply_consolidation_lineage(
+        self,
+        saved_playbooks: list[UserPlaybook],
+        merge_groups: list[tuple[int, list[int]]],
+        existing_ids_to_delete: list[int],
+    ) -> None:
+        """Materialize consolidation merges as lineage tombstones.
+
+        Runs AFTER ``save_user_playbooks`` has assigned survivor ids. For each
+        ``unify`` merge group, routes the sources atomically through
+        ``storage.merge_records`` so each becomes a MERGED tombstone pointing at
+        its survivor with a ``merge`` lineage event (``resolve_current`` then
+        follows the pointer). Any archived id NOT covered by a merge group
+        (e.g. a ``differentiate`` split source, which has no single survivor) is
+        soft-superseded in place so the dead source content stays auditable for
+        point-in-time attribution reads.
+
+        Args:
+            saved_playbooks: The just-persisted entries (survivor ids assigned).
+            merge_groups: ``(survivor_index, source_existing_ids)`` per merge.
+            existing_ids_to_delete: ALL archived ids (merge sources + leftovers).
+        """
+        from reflexio.models.api_schema.domain.entities import LineageContext
+
+        merged_source_ids: set[int] = set()
+        for survivor_idx, source_ids in merge_groups:
+            survivor_id = saved_playbooks[survivor_idx].user_playbook_id
+            merged_source_ids.update(source_ids)
+            self.storage.merge_records(  # type: ignore[reportOptionalMemberAccess]
+                entity_type="user_playbook",
+                survivor_id=str(survivor_id),
+                source_ids=[str(s) for s in source_ids],
+                context=LineageContext(
+                    op_kind="merge",
+                    actor="consolidator",
+                    source_ids=[str(s) for s in source_ids],
+                    reason="dedup-merge",
+                    request_id=self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+                ),
+            )
+
+        # Leftover archives not covered by any merge group (e.g. differentiate
+        # split sources) have no single survivor, so preserve them as dead-source
+        # tombstones instead of hard-deleting them.
+        leftover_ids = [
+            pid for pid in existing_ids_to_delete if pid not in merged_source_ids
+        ]
+        if leftover_ids:
+            try:
+                superseded_count = self.storage.supersede_user_playbooks_by_ids(  # type: ignore[reportOptionalMemberAccess]
+                    leftover_ids,
+                    self.service_config.request_id,  # type: ignore[reportOptionalMemberAccess]
+                )
+                logger.info(
+                    "Superseded %d split-source existing entries", superseded_count
+                )
+            except Exception:
+                logger.exception("Failed to supersede split-source existing entries")
+                raise
+
     def _enqueue_user_playbook_optimization(
         self, saved_playbooks: list[UserPlaybook]
     ) -> None:
@@ -446,10 +537,21 @@ class PlaybookGenerationService(
         )
 
         # Initialize and run aggregator (synchronous)
+        from reflexio.server.services.playbook.user_detail_stripping import (
+            create_aggregation_user_detail_stripper,
+        )
+
+        user_detail_stripper = create_aggregation_user_detail_stripper(
+            self.request_context.configurator
+        )
+        aggregator_kwargs = {}
+        if user_detail_stripper is not None:
+            aggregator_kwargs["user_detail_stripper"] = user_detail_stripper
         aggregator = PlaybookAggregator(
             llm_client=self.client,
             request_context=self.request_context,
             agent_version=self.service_config.agent_version,  # type: ignore[reportOptionalMemberAccess]
+            **aggregator_kwargs,
         )
         try:
             run_with_operation_limit(

package/plugin/vendor/reflexio/reflexio/server/services/playbook/user_detail_stripping.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass(frozen=True)
+class DetectedEntity:
+    start: int
+    end: int
+    entity_type: str
+    replacement: str
+    confidence: float
+    source: str
+
+
+@dataclass(frozen=True)
+class StrippingResult:
+    text: str
+    detections: list[DetectedEntity] = field(default_factory=list)
+
+
+class UserDetailDetector(Protocol):
+    def detect(self, text: str) -> list[DetectedEntity]: ...
+
+
+class UserDetailStripper(Protocol):
+    prompt_extra_instructions: str | None
+
+    def strip_user_details(
+        self,
+        text: str,
+        shared_mapping: dict[str, int] | None = None,
+    ) -> StrippingResult: ...
+
+    def sanitize_aggregation_output_text(
+        self,
+        text: str | None,
+    ) -> tuple[str | None, int]: ...
+
+
+class PassthroughStripper:
+    prompt_extra_instructions: str | None = None
+
+    def strip_user_details(
+        self,
+        text: str,
+        shared_mapping: dict[str, int] | None = None,  # noqa: ARG002
+    ) -> StrippingResult:
+        return StrippingResult(text=text, detections=[])
+
+    def sanitize_aggregation_output_text(
+        self,
+        text: str | None,
+    ) -> tuple[str | None, int]:
+        return text, 0
+
+
+UserDetailStripperFactory = Callable[[object], UserDetailStripper | None]
+
+
+def _default_user_detail_stripper_factory(
+    _configurator: object,
+) -> UserDetailStripper | None:
+    return None
+
+
+_user_detail_stripper_factory: UserDetailStripperFactory = (
+    _default_user_detail_stripper_factory
+)
+
+
+def set_user_detail_stripper_factory(factory: UserDetailStripperFactory) -> None:
+    """Register the deployment-specific aggregation stripper factory."""
+    global _user_detail_stripper_factory  # noqa: PLW0603
+    _user_detail_stripper_factory = factory
+
+
+def create_aggregation_user_detail_stripper(
+    configurator: object,
+) -> UserDetailStripper | None:
+    """Create the deployment-specific stripper for aggregation, if any."""
+    return _user_detail_stripper_factory(configurator)

package/plugin/vendor/reflexio/reflexio/server/services/playbook_optimizer/README.md

@@ -0,0 +1,10 @@
+# playbook_optimizer
+
+GEPA-driven playbook content optimizer.
+
+- `optimizer.py` orchestrates one optimization run and persists candidates, evaluations, events, and optional successor playbooks.
+- `scheduler.py` owns deferred optimization scheduling.
+- `models.py` owns optimizer-local data shapes.
+- `judge.py`, `rollout.py`, `gepa_adapter.py`, `assistant_webhook.py`, and `scenario_resolver.py` are mature implementation units and intentionally remain at the package root.
+
+Do not introduce a `components/` package without a separate design that proves the dependency direction is clearer after the move.

package/plugin/vendor/reflexio/reflexio/server/services/playbook_optimizer/models.py

@@ -13,6 +13,7 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field
 
 from reflexio.models.api_schema.domain import Interaction
+from reflexio.models.structured_output import StrictStructuredOutput
 
 
 class ChatMessage(BaseModel):
@@ -58,7 +59,7 @@ class JudgeASI(BaseModel):
     recommended_mutation: str | list[str] = ""
 
 
-class JudgeOutput(BaseModel):
+class JudgeOutput(StrictStructuredOutput):
     verdict: Literal["candidate", "incumbent", "tie"]
     score: float = Field(ge=0.0, le=1.0)
     likert: int = Field(ge=1, le=5)

package/plugin/vendor/reflexio/reflexio/server/services/playbook_optimizer/optimizer.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import json
 import logging
+import os
+from pathlib import Path
 from typing import Any, Literal, cast
 
 from pydantic import BaseModel
@@ -14,6 +16,7 @@ from reflexio.models.api_schema.domain import (
     PlaybookStatus,
     UserPlaybook,
 )
+from reflexio.models.api_schema.domain.entities import LineageContext
 from reflexio.models.config_schema import PlaybookOptimizerConfig
 from reflexio.server.api_endpoints.request_context import RequestContext
 from reflexio.server.llm.litellm_client import LiteLLMClient
@@ -28,6 +31,22 @@ from .scenario_resolver import ScenarioResolver
 
 logger = logging.getLogger(__name__)
 
+# Prefix used when constructing the run-scoped lineage request_id from a job id.
+# Shared with tests so the format is defined in one place.
+_OPTIMIZER_RUN_ID_PREFIX = "optjob_"
+
+
+def optimizer_run_request_id(job_id: int) -> str:
+    """Return the lineage request_id for a playbook optimizer run.
+
+    Args:
+        job_id (int): The ``PlaybookOptimizationJob.job_id`` for this run.
+
+    Returns:
+        str: A non-empty, job-scoped request id of the form ``optjob_<job_id>``.
+    """
+    return f"{_OPTIMIZER_RUN_ID_PREFIX}{job_id}"
+
 
 class PlaybookOptimizationTarget(BaseModel):
     """A single playbook (agent or user) the optimizer should try to improve."""
@@ -126,6 +145,7 @@ class PlaybookOptimizer:
                 metadata_json=json.dumps(split_metadata, ensure_ascii=False),
             )
         )
+        run_request_id = optimizer_run_request_id(job.job_id)
         logger.info(
             "event=playbook_optimization_start job_id=%d candidate_id=none "
             "target_kind=%s target_id=%d "
@@ -248,7 +268,9 @@ class PlaybookOptimizer:
             )
             return "completed"
 
-        successor_id = self._commit_if_allowed(target, incumbent, best_content, config)
+        successor_id = self._commit_if_allowed(
+            target, incumbent, best_content, config, run_request_id
+        )
         logger.info(
             "event=playbook_optimization_committed job_id=%d candidate_id=%d "
             "successor_target_id=%s best_score=%.3f",
@@ -331,6 +353,13 @@ class PlaybookOptimizer:
                 backoff_base_s=config.webhook_backoff_base_seconds,
             )
         if config.assistant_script_path:
+            if not _is_executable_file(config.assistant_script_path):
+                logger.warning(
+                    "Skipping playbook optimization: assistant_script_path is not "
+                    "an executable file path=%s",
+                    config.assistant_script_path,
+                )
+                return None
             return LocalScriptAssistant(
                 script_path=config.assistant_script_path,
                 script_args=config.assistant_script_args,
@@ -415,6 +444,7 @@ class PlaybookOptimizer:
         incumbent: AgentPlaybook,
         best_content: str,
         config: PlaybookOptimizerConfig,
+        run_request_id: str,
     ) -> int | None:
         # The optimize() entrypoint already gates on _can_adopt_winner before
         # creating the job, but check again so this stays correct if called
@@ -432,49 +462,39 @@ class PlaybookOptimizer:
                 or current.playbook_status != PlaybookStatus.PENDING
             ):
                 return None
-            self.storage.archive_agent_playbooks_by_ids([target.target_id])
-            successor = incumbent.model_copy(
-                update={
-                    "agent_playbook_id": 0,
-                    "content": best_content,
-                    "status": None,
-                    "playbook_status": PlaybookStatus.PENDING,
-                    "playbook_metadata": _append_optimizer_metadata(
-                        incumbent.playbook_metadata, target.target_id
-                    ),
-                }
+            metadata = _append_optimizer_metadata(
+                incumbent.playbook_metadata, target.target_id
+            )
+            successor_id = _supersede_agent_playbook(
+                self.storage,
+                incumbent,
+                best_content,
+                "playbook_optimizer",
+                playbook_metadata=metadata,
+                request_id=run_request_id,
             )
-            saved = self.storage.save_agent_playbooks([successor])
-            if saved and saved[0].agent_playbook_id:
+            if successor_id is not None:
                 self.storage.set_source_windows_for_agent_playbook(
-                    saved[0].agent_playbook_id, source_windows
+                    successor_id, source_windows
                 )
-                return saved[0].agent_playbook_id
-            return None
+            return successor_id
         current_user = self.storage.get_user_playbook_by_id(target.target_id)
         if current_user is None or current_user.status is not None:
             return None
         if current_user.user_id is None:
             return None
-        archived = self.storage.archive_user_playbook_by_id(
-            current_user.user_id, current_user.user_playbook_id
-        )
-        if not archived:
-            return None
         # The optimizer can legitimately flip framing (positive guidance ->
         # negative anti-pattern or vice versa). Orientation lives entirely in
         # the rule wording, so writing ``best_content`` is sufficient — there
         # is no derived polarity label or separate polarity field to keep in
         # sync.
-        successor_user = current_user.model_copy(
-            update={
-                "user_playbook_id": 0,
-                "content": best_content,
-                "status": None,
-            }
+        return _supersede_user_playbook(
+            self.storage,
+            current_user,
+            best_content,
+            "playbook_optimizer",
+            request_id=run_request_id,
         )
-        self.storage.save_user_playbooks([successor_user])
-        return successor_user.user_playbook_id or None
 
 
 def _agent_like_playbook(playbook: UserPlaybook) -> AgentPlaybook:
@@ -506,6 +526,129 @@ def _append_optimizer_metadata(existing: str, predecessor_id: int) -> str:
     return f"{existing}; {suffix}"
 
 
+def _supersede_user_playbook(
+    storage: Any,
+    incumbent: UserPlaybook,
+    best_content: str,
+    source: str,
+    *,
+    request_id: str,
+) -> int | None:
+    """Insert a user-playbook successor then atomically supersede the incumbent.
+
+    Returns the new ``user_playbook_id`` on success, or ``None`` when the
+    incumbent is no longer CURRENT (lost race / already superseded).
+
+    Args:
+        storage: A storage instance implementing ``save_user_playbooks``,
+            ``supersede_record``, and ``delete_user_playbooks_by_ids``.
+        incumbent: The current user playbook to replace.
+        best_content: Content for the successor playbook.
+        source: Provenance label written to the lineage event actor field.
+        request_id: Run-scoped correlation id for the lineage event. Must be
+            non-empty; use the job-derived id from the calling optimizer run.
+
+    Returns:
+        int | None: ``user_playbook_id`` of the successor, or ``None`` if the
+            incumbent was not CURRENT.
+
+    Raises:
+        ValueError: If ``request_id`` is empty or None.
+    """
+    if not request_id:
+        raise ValueError(
+            "_supersede_user_playbook: request_id must be non-empty (run-correlation id)"
+        )
+    successor = incumbent.model_copy(
+        update={"user_playbook_id": 0, "content": best_content, "status": None}
+    )
+    storage.save_user_playbooks([successor])
+    ctx = LineageContext(
+        op_kind="revise",
+        actor=source,
+        request_id=request_id,
+    )
+    ok = storage.supersede_record(
+        entity_type="user_playbook",
+        incumbent_id=str(incumbent.user_playbook_id),
+        successor_id=str(successor.user_playbook_id),
+        context=ctx,
+    )
+    if not ok:
+        # Lost CAS: remove the never-live successor without auditing it as erasure.
+        storage.delete_user_playbooks_by_ids(
+            [successor.user_playbook_id], emit_hard_delete=False
+        )
+        return None
+    return successor.user_playbook_id
+
+
+def _supersede_agent_playbook(
+    storage: Any,
+    incumbent: AgentPlaybook,
+    best_content: str,
+    source: str,
+    playbook_metadata: str = "",
+    *,
+    request_id: str,
+) -> int | None:
+    """Insert an agent-playbook successor then atomically supersede the incumbent.
+
+    Returns the new ``agent_playbook_id`` on success, or ``None`` when the
+    incumbent is no longer CURRENT.
+
+    Args:
+        storage: A storage instance implementing ``save_agent_playbooks``,
+            ``supersede_record``, and ``delete_agent_playbooks_by_ids``.
+        incumbent: The current agent playbook to replace.
+        best_content: Content for the successor playbook.
+        source: Provenance label written to the lineage event actor field.
+        playbook_metadata: Optional metadata string for the successor row.
+        request_id: Run-scoped correlation id for the lineage event. Must be
+            non-empty; use the job-derived id from the calling optimizer run.
+
+    Returns:
+        int | None: ``agent_playbook_id`` of the successor, or ``None`` if the
+            incumbent was not CURRENT.
+
+    Raises:
+        ValueError: If ``request_id`` is empty or None.
+    """
+    if not request_id:
+        raise ValueError(
+            "_supersede_agent_playbook: request_id must be non-empty (run-correlation id)"
+        )
+    successor = incumbent.model_copy(
+        update={
+            "agent_playbook_id": 0,
+            "content": best_content,
+            "status": None,
+            "playbook_status": PlaybookStatus.PENDING,
+            "playbook_metadata": playbook_metadata,
+        }
+    )
+    saved = storage.save_agent_playbooks([successor])
+    if not saved or not saved[0].agent_playbook_id:
+        return None
+    successor_id = saved[0].agent_playbook_id
+    ctx = LineageContext(
+        op_kind="revise",
+        actor=source,
+        request_id=request_id,
+    )
+    ok = storage.supersede_record(
+        entity_type="agent_playbook",
+        incumbent_id=str(incumbent.agent_playbook_id),
+        successor_id=str(successor_id),
+        context=ctx,
+    )
+    if not ok:
+        # Lost CAS: remove the never-live successor without auditing it as erasure.
+        storage.delete_agent_playbooks_by_ids([successor_id], emit_hard_delete=False)
+        return None
+    return successor_id
+
+
 class _GEPAStorageCallback:
     def __init__(self, storage: Any, job_id: int) -> None:
         self.storage = storage
@@ -627,6 +770,11 @@ def _split_metadata(
     }
 
 
+def _is_executable_file(path: str) -> bool:
+    candidate = Path(path)
+    return candidate.is_file() and os.access(candidate, os.X_OK)
+
+
 def _result_metadata(result: Any, split_metadata: dict[str, Any]) -> dict[str, Any]:
     metadata = result.to_dict()
     if not isinstance(metadata, dict):