cmpnd 0.3.0__tar.gz → 0.4.0__tar.gz

{cmpnd-0.3.0 → cmpnd-0.4.0}/CLAUDE.md

@@ -35,7 +35,7 @@ uv run ruff format --check .             # format check
 - `cmpnd/callback.py` - DSPy instrumentation, signature extraction
 - `cmpnd/optimizers/tracker.py` - Optimization tracking
 - `cmpnd/packaging.py` - Source ZIP generation for deploy (ported from deploy/local_cmpnd.py)
-- `cmpnd/deployment.py` - `deploy()` function: SDK -> Rails -> AWS deploy stack
+- `cmpnd/deployment.py` - `deploy()` function: SDK -> serve -> AWS deploy stack
 
 ## Reflector ↔ DSPy compatibility
 

{cmpnd-0.3.0 → cmpnd-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmpnd
-Version: 0.3.0
+Version: 0.4.0
 Summary: DSPy observability and deployment SDK for cmpnd
 Project-URL: Homepage, https://cmpnd.ai
 Author-email: cmpnd <hello@cmpnd.ai>

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/__init__.py

@@ -129,4 +129,11 @@ def auto_instrument() -> CmpndCallback:
 
     _gepa_patch.patch_gepa()
 
+    # Persist the compiled-from lineage tag across state-only save/load so a
+    # continued optimization still stamps compiled_from_run_id after a disk
+    # reload / process restart (CMP-444).
+    from . import _program_patch
+
+    _program_patch.patch_program_state()
+
     return callback

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/_gepa_patch.py

@@ -144,7 +144,9 @@ def patch_gepa() -> None:
 
         except Exception as e:
             if callback is not None:  # pyright: ignore[reportUnnecessaryComparison]
-                callback._tracker.set_error(e)
+                # Flush a terminal 'failed', not just in-memory state — else the
+                # running row start() sent lingers forever (CMP-414).
+                callback._tracker.finalize_error(e)
             raise
 
         finally:

cmpnd-0.4.0/cmpnd/_program_patch.py

@@ -0,0 +1,112 @@
+"""Persist the compiled-from lineage tag across DSPy's state-only save/load.
+
+GEPA tags a compiled program with ``result._optimization_run_id`` (see
+``cmpnd/optimizers/gepa.py`` and ``cmpnd/_gepa_patch.py``); a subsequent
+``compile()`` starting from that program reads the tag back in
+``tracker.enrich_from_program`` and sends it as ``compiled_from_run_id``, which
+is how the cross-run lineage chain (Go breadcrumb bar) is built.
+
+That tag is a plain instance attribute. DSPy's state-only save path
+(``module.save("p.json")`` / ``.pkl`` with ``save_program=False``) serializes
+**only named parameters** — ``BaseModule.dump_state`` returns
+``{name: param.dump_state()}`` and ``load_state`` iterates only parameter names
+— so the tag is dropped on both ends of a disk round-trip and the lineage
+silently vanishes across a save/load or process restart. (``save_program=True``
+cloudpickles the whole instance and already preserves it; the gap is exclusively
+the state-only path, which is the one DSPy steers users toward.)
+
+DSPy exposes no extension point for out-of-band instance state (no
+``get_extra_state`` / attribute allowlist; ``metadata`` is DSPy-owned). Rather
+than change DSPy upstream (CMP-444 decision), ``patch_program_state()`` wraps
+``dump_state`` / ``load_state`` on the two classes that define them — the
+composite ``Module`` path and the bare ``Predict`` path — to round-trip the tag
+under a namespaced carrier key. Installed lazily from
+``cmpnd.auto_instrument()`` alongside ``patch_gepa()``.
+
+The carrier is a single reserved top-level key (the same shape DSPy itself uses
+for its sibling ``metadata`` key). Stock ``Module.load_state`` ignores it (it
+reads only parameter names); ``Predict.load_state`` ``setattr``s every key, so
+the ``Predict`` wrapper strips the carrier after restoring the attribute so it
+doesn't leak onto the instance.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Reserved top-level key carrying cmpnd's out-of-band program state. Namespaced
+# so it can't collide with a DSPy named-parameter path.
+_LINEAGE_KEY = "_cmpnd"
+_RUN_ID_FIELD = "optimization_run_id"
+
+_patched = False
+
+
+def _inject(state: Any, module: Any) -> Any:
+    """Add the lineage carrier to a dumped state dict when the module is tagged."""
+    run_id = getattr(module, "_optimization_run_id", None)
+    if run_id is not None and isinstance(state, dict):
+        state[_LINEAGE_KEY] = {_RUN_ID_FIELD: str(run_id)}
+    return state
+
+
+def _restore(state: Any, module: Any) -> None:
+    """Re-attach ``_optimization_run_id`` from a loaded state dict's carrier."""
+    if not isinstance(state, dict):
+        return
+    carrier = state.get(_LINEAGE_KEY)
+    if isinstance(carrier, dict) and carrier.get(_RUN_ID_FIELD):
+        module._optimization_run_id = str(carrier[_RUN_ID_FIELD])
+
+
+# The wrappers forward *args/**kwargs verbatim rather than naming dump_state's
+# json_mode / load_state's allow_unsafe_lm_state: those signatures differ across
+# DSPy versions (allow_unsafe_lm_state was added after 3.1.x), and the patch is
+# installed process-wide, so it must be transparent to every caller and version.
+def _wrap_dump(orig):
+    def dump_state(self, *args, **kwargs):
+        return _inject(orig(self, *args, **kwargs), self)
+
+    return dump_state
+
+
+def _wrap_load(orig, *, strip: bool):
+    def load_state(self, state, *args, **kwargs):
+        _restore(state, self)
+        # Predict.load_state setattrs every non-excluded key; drop the carrier
+        # so it doesn't land as a stray `_cmpnd` attribute. Module.load_state
+        # reads only parameter names, so it needs no strip.
+        if strip and isinstance(state, dict) and _LINEAGE_KEY in state:
+            state = {k: v for k, v in state.items() if k != _LINEAGE_KEY}
+        return orig(self, state, *args, **kwargs)
+
+    return load_state
+
+
+def patch_program_state() -> None:
+    """Wrap dump_state/load_state so the lineage tag survives a disk reload.
+
+    Idempotent (a module-level flag guards against double-patching); a no-op
+    when dspy isn't installed.
+    """
+    global _patched
+    if _patched:
+        return
+
+    try:
+        import dspy
+    except ImportError:
+        return
+
+    # Composite programs (dspy.Module subclasses, ChainOfThought, …) inherit
+    # dump_state/load_state from BaseModule; patching on dspy.Module covers every
+    # composite. A bare Predict program overrides both, so patch that path too.
+    # The methods are swapped via getattr/setattr rather than direct attribute
+    # assignment because dspy.*.load_state types as Unknown to basedpyright (its
+    # body imports the untyped dspy.predict.predict) — reflection keeps the swap
+    # off the type checker's attribute-access path across every DSPy version.
+    for cls, strip in ((dspy.Module, False), (dspy.Predict, True)):
+        setattr(cls, "dump_state", _wrap_dump(getattr(cls, "dump_state")))
+        setattr(cls, "load_state", _wrap_load(getattr(cls, "load_state"), strip=strip))
+
+    _patched = True

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/deployment.py

@@ -72,7 +72,7 @@ def _raise_http_error(response: httpx.Response, action: str) -> None:
 class DeployFailed(RuntimeError):
     """Raised when a deployment transitions to ``status=failed``.
 
-    Carries the structured failure detail Rails persists when the parser
+    Carries the structured failure detail the server persists when the parser
     writes a failure marker. ``failure_phase`` is one of a closed set of
     pipeline-stage names (e.g. ``unpack_zip``, ``signature_extraction``,
     ``lm_load``); ``failure_reason`` is a constant template synthesized
@@ -86,7 +86,7 @@ class DeployFailed(RuntimeError):
     parser Lambda's CloudWatch group.
 
     Both fields are ``None`` when the server didn't return structured
-    detail (older deployments or older Rails versions).
+    detail (older deployments or older server versions).
 
     Subclasses ``RuntimeError`` so existing ``except RuntimeError`` callers
     keep working.
@@ -117,7 +117,7 @@ class DeployFailed(RuntimeError):
 def deploy(module, metric=None, timeout=300, metadata=None):
     """Deploy a DSPy module via the Cmpnd platform.
 
-    Packages the module into a source ZIP, uploads it through Rails to the
+    Packages the module into a source ZIP, uploads it through the platform API to the
     deploy stack, and polls until the program is parsed and ready.
 
     Args:
@@ -192,18 +192,18 @@ def deploy(module, metric=None, timeout=300, metadata=None):
         if lm_kwargs.get("api_base"):
             deploy_body["lm_api_host"] = lm_kwargs["api_base"]
 
-    # Client for Rails API calls (JSON)
-    rails_headers = {
+    # Client for platform API calls (JSON)
+    api_headers = {
         "X-API-Key": config.api_key,
         "Content-Type": "application/json",
     }
 
     with httpx.Client(timeout=30.0) as client:
-        # Step 1: Create deployment via Rails
+        # Step 1: Create deployment via the platform API
         create_resp = client.post(
             f"{config.endpoint}/api/v1/deployments",
             json=deploy_body,
-            headers=rails_headers,
+            headers=api_headers,
         )
         _raise_http_error(create_resp, "create deployment")
         data = create_resp.json()
@@ -241,7 +241,7 @@ def deploy(module, metric=None, timeout=300, metadata=None):
 
             poll_resp = client.get(
                 f"{config.endpoint}/api/v1/deployments/{deployment_id}",
-                headers=rails_headers,
+                headers=api_headers,
             )
             _raise_http_error(poll_resp, "poll deployment status")
             status_data = poll_resp.json()

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/optimizers/gepa.py

@@ -221,7 +221,9 @@ class TrackedGEPA:
 
         except Exception as e:
             if self._tracker:
-                self._tracker.set_error(e)
+                # Flush a terminal 'failed', not just in-memory state — else the
+                # running row start() sent lingers forever (CMP-414).
+                self._tracker.finalize_error(e)
             raise
 
         finally:

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/optimizers/gepa_callback.py

@@ -292,10 +292,14 @@ class CmpndGEPACallback:
             if will_continue:
                 logger.warning(f"GEPA recoverable error at iteration {event.get('iteration')}: {exception}")
             else:
+                # Terminal error: flush a 'failed' now. If GEPA also re-raises,
+                # the compile wrapper's finalize_error no-ops (shared _finalized
+                # guard); if GEPA swallows it, this is the only terminal flush,
+                # so the running row still transitions (CMP-414).
                 if exception is not None:
-                    self._tracker.set_error(exception)
+                    self._tracker.finalize_error(exception)
                 else:
-                    self._tracker.set_error(RuntimeError(f"Unknown error at iteration {event.get('iteration')}"))
+                    self._tracker.finalize_error(RuntimeError(f"Unknown error at iteration {event.get('iteration')}"))
         except Exception:
             logger.exception("Error in on_error")
             raise

cmpnd-0.4.0/cmpnd/optimizers/resume.py

@@ -0,0 +1,91 @@
+"""GEPA checkpoint-resume continuity: a ``run_id`` sidecar in the ``log_dir``.
+
+CMP-443. GEPA's identity for a resumed job is its ``log_dir`` (== gepa's
+``run_dir``): it reloads ``gepa_state.bin`` and continues iteration/budget. But
+the SDK mints a fresh ``run_id`` per ``compile()``, so N resumes become N
+unrelated optimization-run rows. This module persists the server-assigned
+``run_id`` as ``cmpnd_run.json`` alongside GEPA's own state, and reads it back on
+resume so the SDK re-adopts the original id (one continuous run).
+
+Resume is detected by GEPA's ``gepa_state.bin`` checkpoint: if it is present the
+next ``compile()`` continues cumulative state, so the SDK must re-adopt; if it is
+absent (a fresh ``log_dir``, or a first run that died before its first
+checkpoint) GEPA starts over and the SDK mints a new run.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import datetime
+
+logger = logging.getLogger(__name__)
+
+_SIDECAR = "cmpnd_run.json"
+_CHECKPOINT = "gepa_state.bin"
+
+
+def sidecar_path(log_dir: str) -> str:
+    return os.path.join(log_dir, _SIDECAR)
+
+
+def write_run_id(log_dir: str, run_id: str, program_signature_hash: int | None, start_time: datetime | None) -> None:
+    """Persist the server-assigned ``run_id`` into ``log_dir`` so a later resume
+    can re-adopt it. Called at ``start()``, which runs before GEPA creates its
+    ``run_dir`` — so create the directory if it isn't there yet. Best-effort: a
+    write failure must not break the optimization run.
+    """
+    payload = {
+        "run_id": run_id,
+        "program_signature_hash": program_signature_hash,
+        "start_time": start_time.isoformat() if start_time is not None else None,
+    }
+    try:
+        os.makedirs(log_dir, exist_ok=True)
+        with open(sidecar_path(log_dir), "w", encoding="utf-8") as f:
+            json.dump(payload, f)
+    except OSError as e:
+        logger.warning("could not write resume sidecar in %s: %s", log_dir, e)
+
+
+def read_resumable(log_dir: str, program_signature_hash: int | None) -> tuple[str, datetime | None] | None:
+    """Return ``(run_id, start_time)`` to re-adopt, or ``None`` if this is not a
+    resumable job.
+
+    Resumable requires: GEPA's ``gepa_state.bin`` checkpoint present (else GEPA
+    itself starts fresh) AND a readable sidecar carrying a ``run_id``. A definite
+    ``program_signature_hash`` mismatch (a different program reusing the same
+    ``log_dir``) is rejected so it can't hijack the id; a missing hash on either
+    side errs toward stitching, since ``log_dir`` is the strong identity signal.
+    """
+    if not os.path.exists(os.path.join(log_dir, _CHECKPOINT)):
+        return None
+    try:
+        with open(sidecar_path(log_dir), encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError):
+        return None
+
+    run_id = data.get("run_id")
+    if not run_id:
+        return None
+
+    prior_hash = data.get("program_signature_hash")
+    if prior_hash is not None and program_signature_hash is not None and prior_hash != program_signature_hash:
+        logger.warning(
+            "resume sidecar in %s is for a different program (hash %s != %s); not re-adopting",
+            log_dir,
+            prior_hash,
+            program_signature_hash,
+        )
+        return None
+
+    start_time = None
+    raw_start = data.get("start_time")
+    if raw_start:
+        try:
+            start_time = datetime.fromisoformat(raw_start)
+        except ValueError:
+            start_time = None
+    return str(run_id), start_time

{cmpnd-0.3.0 → cmpnd-0.4.0}/cmpnd/optimizers/tracker.py

@@ -617,12 +617,33 @@ class OptimizationTracker:
             logger.warning(f"Failed to capture compiled program state: {e}")
 
     def set_error(self, exception: Exception) -> None:
-        """Mark the optimization run as failed."""
+        """Mark the optimization run as failed (in-memory only)."""
         self.status = "failed"
         self.error_message = str(exception)
         self.end_time = datetime.now(timezone.utc)
         logger.error(f"Optimization failed: {exception}")
 
+    def finalize_error(self, exception: Exception) -> None:
+        """Mark the run failed AND flush the terminal 'failed' to the backend.
+
+        The success path is finalize(); on an optimizer exception the run must
+        still post a terminal 'failed' — otherwise the 'running' row start()
+        created never transitions and the program page shows a perpetual
+        in-progress optimization (CMP-414). Idempotent and mutually exclusive
+        with finalize() via the shared _finalized guard (whichever fires first
+        wins, so a swallowed-then-completed run can't overwrite a failure and
+        vice versa). The export is best-effort: a flush failure is logged, never
+        raised, so it can't mask the original optimizer exception the caller is
+        about to re-raise."""
+        if self._finalized:
+            return
+        self._finalized = True
+        self.set_error(exception)
+        try:
+            self._flush_terminal()
+        except Exception:
+            logger.exception("Failed to export terminal 'failed' optimization run")
+
     def start(self) -> None:
         """Send initial optimization run record with status='running'.
 
@@ -634,20 +655,38 @@ class OptimizationTracker:
         self._started = True
 
         from .. import exporter
+        from . import resume
 
         exp = exporter.get_exporter()
-        if exp:
-            # CMP-313: the SDK doesn't mint — the component behind the exporter
-            # assigns the id and returns it; adopt it before any trace ships.
-            assigned = exp.export_optimization_start(self)
-            if assigned:
-                self.optimization_run_id = assigned
-            logger.info(
-                f"Started optimization tracking: run_id={self.optimization_run_id}, "
-                f"max_metric_calls={self.max_metric_calls}"
-            )
-        else:
+        if not exp:
             logger.debug("No exporter available, optimization start not exported")
+            return
+
+        # CMP-443: a GEPA job resumed from the same log_dir is one continuous
+        # run. If a prior run left a checkpoint + our run_id sidecar, re-adopt
+        # that id (and its original start_time, so duration stays cumulative)
+        # instead of minting a fresh row. Jobs without a log_dir stay per-run.
+        log_dir = self.config.get("log_dir") if self.config else None
+        readopted = resume.read_resumable(log_dir, self.program_signature_hash) if log_dir else None
+        if readopted is not None:
+            self.optimization_run_id, prior_start = readopted
+            if prior_start is not None:
+                self.start_time = prior_start
+            logger.info(f"Resuming optimization run: run_id={self.optimization_run_id} (log_dir={log_dir})")
+            return
+
+        # CMP-313: the SDK doesn't mint — the component behind the exporter
+        # assigns the id and returns it; adopt it before any trace ships.
+        assigned = exp.export_optimization_start(self)
+        if assigned:
+            self.optimization_run_id = assigned
+        # Persist the id so a later resume of the same log_dir re-adopts it.
+        if log_dir and self.optimization_run_id:
+            resume.write_run_id(log_dir, self.optimization_run_id, self.program_signature_hash, self.start_time)
+        logger.info(
+            f"Started optimization tracking: run_id={self.optimization_run_id}, "
+            f"max_metric_calls={self.max_metric_calls}"
+        )
 
     def send_progress_update(self) -> None:
         """Send a progress update to the backend.
@@ -751,12 +790,29 @@ class OptimizationTracker:
             f"best_score={self.best_score:.3f}"
         )
 
-        # Export via cmpnd exporter
-        # If we already sent a start record, update it; otherwise create new
-        if self._started:
-            self._export_update()
-        else:
+        # Export via cmpnd exporter: create, update, or skip — see _flush_terminal.
+        self._flush_terminal()
+
+    def _flush_terminal(self) -> None:
+        """Send the terminal run to the backend, choosing create vs. update.
+
+        - never started (no start() call): create the record (_export).
+        - started with an id: update the existing record (_export_update).
+        - started but WITHOUT an id: start()'s synchronous create raised
+          (export_optimization_start returns a real id or raises — it never
+          returns an empty one), so no server run exists to transition and
+          there is no id to address. Skip rather than PATCH/POST a missing
+          ("None") id — the optimizer exception already propagated, and serve's
+          abandon-sweep (CMP-412) is the backstop for a running row whose create
+          response was lost in flight.
+        """
+        if not self._started:
             self._export()
+            return
+        if not self.optimization_run_id:
+            logger.error("optimization run has no id (start export failed); no terminal run written")
+            return
+        self._export_update()
 
     def _export_update(self) -> None:
         """Update existing optimization run record."""

{cmpnd-0.3.0 → cmpnd-0.4.0}/pyproject.toml

@@ -5,7 +5,7 @@ name = "cmpnd"
 # it's new) — no git tags. Bump with `uv version --bump {minor,patch}` or by
 # hand. Runtime `cmpnd.__version__` reads installed metadata, so it tracks
 # this automatically. See docs/plans/2026-07-02-sdk-pypi-tag-free-publish.md.
-version = "0.3.0"
+version = "0.4.0"
 description = "DSPy observability and deployment SDK for cmpnd"
 readme = "README.md"
 requires-python = ">=3.10"

cmpnd-0.4.0/scripts/gepa_resume_bug.py

@@ -0,0 +1,187 @@
+"""Reproduce the GEPA checkpoint-resume duplication bug (CMP-442 / CMP-443).
+
+Drives the *real* dspy.GEPA + cmpnd.auto_instrument export path twice against a
+single GEPA log_dir (== gepa run_dir), the way a laptop-sleep / power-cut resume
+actually happens:
+
+  phase 1 (crash):  start a GEPA job with log_dir=D. After GEPA writes its second
+                    gepa_state.bin checkpoint, hard-exit the process (os._exit) —
+                    modelling a killed process. The SDK has already POSTed the
+                    "running" row but never finalizes it, so run R1 sticks at
+                    status='running'. The checkpoint (gepa_state.bin) is on disk.
+  phase 2 (resume): a fresh process re-runs GEPA with the SAME log_dir. GEPA
+                    reloads gepa_state.bin and continues to completion. Because
+                    the SDK mints a fresh run_id per compile(), this is run R2 —
+                    unrelated to R1. R2 finalizes status='completed', cumulative.
+
+Result today: two rows for one job — R1 (running, orphaned) + R2 (completed),
+sharing config.log_dir and program_signature_hash but nothing linking them. That
+is the bug CMP-443 fixes (re-adopt R1's id keyed on log_dir → one row).
+
+Doubles as the acceptance harness for CMP-443: after the fix, `--phase both`
+against a clean log_dir yields ONE run row, not two.
+
+Offline: student + reflection are DummyLM, so no third-party inference. Only the
+cmpnd export POSTs leave the process (to --endpoint).
+
+Usage:
+  python gepa_resume_bug.py --endpoint http://host.orb.internal:8081 \
+      --api-key cmpnd_review_app_deterministic_key_for_ci
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+
+
+def _build_examples():
+    import dspy
+
+    # Committee-classification flavour so the run reads like the existing seed
+    # data (program "Predict", email_body -> committee).
+    rows = [
+        ("please refer this to the finance subcommittee", "finance"),
+        ("this concerns veterans healthcare access", "veterans"),
+        ("a bill about farm subsidies and crop insurance", "agriculture"),
+        ("questions on naval shipbuilding appropriations", "armed_services"),
+        ("immigration and border enforcement funding", "judiciary"),
+        ("public school funding formula reform", "education"),
+    ]
+    trainset = [dspy.Example(email_body=b, committee=c).with_inputs("email_body") for b, c in rows]
+    valset = [dspy.Example(email_body=b, committee=c).with_inputs("email_body") for b, c in rows[:4]]
+    return trainset, valset
+
+
+def _metric(example, pred, trace=None, pred_name=None, pred_trace=None):
+    import dspy
+
+    got = str(getattr(pred, "committee", "")).strip().lower()
+    want = str(example.committee).strip().lower()
+    score = 1.0 if got == want else (0.5 if want in got else 0.0)
+    fb = "correct committee" if score == 1.0 else "name the single most specific committee"
+    return dspy.Prediction(score=score, feedback=fb)
+
+
+class _CrashAfterCheckpoints:
+    """GEPA callback that hard-exits after the Nth gepa_state.bin checkpoint,
+    modelling a power-cut. Prints the SDK run_id first so the caller can see
+    which row was orphaned."""
+
+    def __init__(self, n: int):
+        self._n = n
+        self._seen = 0
+
+    def on_state_saved(self, event) -> None:  # gepa StateSavedEvent
+        from cmpnd import context, exporter
+
+        self._seen += 1
+        if self._seen >= self._n:
+            # Push the queued progress PATCHes synchronously so the orphaned row
+            # reflects the iterations/metric-calls it reached — a killed process
+            # otherwise loses the async queue and the row reads as 0-progress.
+            exp = exporter.get_exporter()
+            if exp is not None:
+                try:
+                    exp.flush(timeout=5.0)
+                except Exception:
+                    pass
+            run_id = context.get_current_optimization_run_id()
+            sys.stdout.write(f"CRASH_RUN_ID={run_id}\n")
+            sys.stdout.flush()
+            sys.stderr.flush()
+            os._exit(0)
+
+
+def _run_compile(endpoint: str, api_key: str, log_dir: str, crash_after: int | None) -> None:
+    import dspy
+    from dspy.utils.dummies import DummyLM
+
+    import cmpnd
+
+    cmpnd.configure(
+        api_key=api_key,
+        endpoint=endpoint,
+        project_tags=["seed-data", "gepa-resume-demo"],
+        flush_interval_seconds=1,
+    )
+    cmpnd.auto_instrument()  # patches dspy.GEPA to export via the tracker
+
+    # DummyLM cycles a fixed answer set; the student ignores instructions so the
+    # score curve is modest — the bug is about run identity, not lift.
+    student_lm = DummyLM([{"committee": "finance"}, {"committee": "veterans"}] * 500)
+    reflection_lm = DummyLM([{"new_instruction": "Name the single most specific committee."}] * 500)
+    dspy.settings.configure(lm=student_lm)
+
+    program = dspy.Predict("email_body -> committee")
+    trainset, valset = _build_examples()
+
+    callbacks = []
+    if crash_after is not None:
+        callbacks.append(_CrashAfterCheckpoints(crash_after))
+
+    gepa = dspy.GEPA(
+        metric=_metric,
+        reflection_lm=reflection_lm,
+        max_metric_calls=30,
+        reflection_minibatch_size=2,
+        num_threads=1,
+        seed=0,
+        use_merge=False,
+        track_stats=True,
+        log_dir=log_dir,
+        gepa_kwargs={"callbacks": callbacks},
+    )
+    try:
+        optimized = gepa.compile(program, trainset=trainset, valset=valset)
+        run_id = getattr(optimized, "_optimization_run_id", None)
+        sys.stdout.write(f"RESUME_RUN_ID={run_id}\n")
+    finally:
+        cmpnd.shutdown_exporter()
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--endpoint", required=True)
+    ap.add_argument("--api-key", required=True)
+    ap.add_argument("--log-dir", default=None)
+    ap.add_argument("--phase", choices=["both", "crash", "resume"], default="both")
+    args = ap.parse_args()
+
+    if args.phase == "crash":
+        _run_compile(args.endpoint, args.api_key, args.log_dir, crash_after=4)
+        return 0
+    if args.phase == "resume":
+        _run_compile(args.endpoint, args.api_key, args.log_dir, crash_after=None)
+        return 0
+
+    # both: run each phase in its own process (crash hard-exits the interpreter)
+    log_dir = args.log_dir or tempfile.mkdtemp(prefix="gepa_resume_demo_")
+    sys.stdout.write(f"log_dir={log_dir}\n")
+    sys.stdout.flush()
+    for phase in ("crash", "resume"):
+        sys.stdout.write(f"\n===== phase {phase} =====\n")
+        sys.stdout.flush()
+        rc = subprocess.call(
+            [
+                sys.executable,
+                os.path.abspath(__file__),
+                "--endpoint",
+                args.endpoint,
+                "--api-key",
+                args.api_key,
+                "--log-dir",
+                log_dir,
+                "--phase",
+                phase,
+            ],
+        )
+        sys.stdout.write(f"[{phase}] exit={rc}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())