testmcpy 0.8.0__tar.gz → 0.9.2__tar.gz

{testmcpy-0.8.0/testmcpy.egg-info → testmcpy-0.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: testmcpy
-Version: 0.8.0
+Version: 0.9.2
 Summary: A comprehensive testing framework for validating LLM tool calling capabilities with MCP services
 Author: Amin Ghadersohi
 License-Expression: Apache-2.0
@@ -351,6 +351,13 @@ profiles:
 
 The setup command is **idempotent** — safe to run multiple times. Use `--force` to overwrite existing files.
 
+**`TESTMCPY_CHAT_OAUTH_LOGIN`** (default `true`): when a chat message hits an
+OAuth (`oauth_auto_discover`) MCP profile with no cached token, the server opens
+the interactive browser OAuth flow and retries. This assumes a browser is
+available on the machine running the server — in headless deployments set
+`TESTMCPY_CHAT_OAUTH_LOGIN=false` so the request fails fast with a clear error
+instead of blocking on a login that can never complete.
+
 ### 2. Explore Your MCP Service
 
 ```bash

{testmcpy-0.8.0 → testmcpy-0.9.2}/README.md

@@ -271,6 +271,13 @@ profiles:
 
 The setup command is **idempotent** — safe to run multiple times. Use `--force` to overwrite existing files.
 
+**`TESTMCPY_CHAT_OAUTH_LOGIN`** (default `true`): when a chat message hits an
+OAuth (`oauth_auto_discover`) MCP profile with no cached token, the server opens
+the interactive browser OAuth flow and retries. This assumes a browser is
+available on the machine running the server — in headless deployments set
+`TESTMCPY_CHAT_OAUTH_LOGIN=false` so the request fails fast with a clear error
+instead of blocking on a login that can never complete.
+
 ### 2. Explore Your MCP Service
 
 ```bash

{testmcpy-0.8.0 → testmcpy-0.9.2}/pyproject.toml

@@ -93,7 +93,7 @@ testmcpy = [
 
 [project]
 name = "testmcpy"
-version = "0.8.0"
+version = "0.9.2"
 description = "A comprehensive testing framework for validating LLM tool calling capabilities with MCP services"
 authors = [{name = "Amin Ghadersohi"}]
 license = "Apache-2.0"

{testmcpy-0.8.0 → testmcpy-0.9.2}/testmcpy/models.py

@@ -139,6 +139,12 @@ class TestRunModel(Base):
     total_tokens: Mapped[int] = mapped_column(Integer, default=0)
     started_at: Mapped[str] = mapped_column(String, nullable=False)
     completed_at: Mapped[str | None] = mapped_column(String, nullable=True)
+    # Touched every ~30s while the run executes (UTC ISO, same format as
+    # the reconciliation cutoff it's compared against). Lets crash
+    # reconciliation distinguish a live run — possibly owned by another
+    # server sharing this DB — from a dead one, instead of guessing from
+    # started_at age.
+    heartbeat_at: Mapped[str | None] = mapped_column(String, nullable=True)
     metadata_: Mapped[dict | None] = mapped_column("metadata", JSON, nullable=True)
     created_at: Mapped[datetime] = mapped_column(
         DateTime, nullable=False, default=lambda: datetime.now(timezone.utc)

{testmcpy-0.8.0 → testmcpy-0.9.2}/testmcpy/server/api.py

@@ -12,6 +12,7 @@ warnings.filterwarnings("ignore", category=DeprecationWarning, module="websocket
 warnings.filterwarnings("ignore", category=DeprecationWarning, module="websockets.legacy")
 warnings.filterwarnings("ignore", category=DeprecationWarning, module="uvicorn")
 
+import contextlib  # noqa: E402
 from contextlib import asynccontextmanager  # noqa: E402
 from datetime import datetime  # noqa: E402
 from enum import Enum  # noqa: E402
@@ -150,6 +151,22 @@ def _get_init_lock(cache_key: str) -> asyncio.Lock:
     return _client_init_locks[cache_key]
 
 
+def _primary_mcp_provider_kwargs(
+    clients_to_use: list[tuple[str, str, MCPClient]],
+) -> dict[str, Any]:
+    """mcp_url/auth kwargs from the FIRST selected MCP client.
+
+    SDK providers support a single MCP server; the Chat UI sends exactly one
+    "profileId:mcpName". Without these kwargs the providers fall back to the
+    DEFAULT profile's URL/auth, breaking chat for any other selected profile.
+    create_llm_provider filters these out for providers that don't accept them.
+    """
+    if not clients_to_use:
+        return {}
+    _profile_id, _mcp_name, client = clients_to_use[0]
+    return {"mcp_url": client.base_url, "auth": client.auth_config}
+
+
 async def get_mcp_clients_for_profile(profile_id: str) -> list[tuple[str, MCPClient]]:
     """
     Get or create MCP clients for all MCP servers in a profile.
@@ -298,12 +315,15 @@ async def get_mcp_client_for_server(profile_id: str, mcp_name: str) -> MCPClient
         return client
 
 
-async def clear_cached_client(cache_key: str) -> bool:
+async def clear_cached_client(cache_key: str, record_failure: bool = True) -> bool:
     """
     Clear a cached MCP client by its cache key.
 
     Args:
         cache_key: Cache key in format "{profile_id}:{mcp_name}"
+        record_failure: When True (default), throttle the next reconnect via
+            back-off. Pass False for deliberate re-initialization (e.g. an
+            interactive OAuth re-login) where an immediate reconnect is wanted.
 
     Returns:
         True if a client was cleared, False if no client was cached
@@ -312,8 +332,9 @@ async def clear_cached_client(cache_key: str) -> bool:
 
     client = mcp_clients.pop(cache_key, None)
     if client:
-        # Record a failure so the next reconnect is throttled via back-off.
-        _record_failure(cache_key)
+        if record_failure:
+            # Record a failure so the next reconnect is throttled via back-off.
+            _record_failure(cache_key)
         try:
             await client.close()
             print(f"Cleared cached client '{cache_key}'")
@@ -323,6 +344,69 @@ async def clear_cached_client(cache_key: str) -> bool:
     return False
 
 
+# Marker substring of the ValueError raised by BaseSDKProvider when an
+# oauth_auto_discover profile has no cached token (see
+# llm_integration.BaseSDKProvider._resolve_mcp_bearer_token).
+_OAUTH_TOKEN_ERROR = "No usable cached OAuth token"
+
+
+def _chat_oauth_login_enabled() -> bool:
+    """Feature flag for interactive OAuth login during chat (default ON).
+
+    Disable with TESTMCPY_CHAT_OAUTH_LOGIN=false (or 0/no). Read at call time
+    so tests can monkeypatch the environment.
+    """
+    return os.environ.get("TESTMCPY_CHAT_OAUTH_LOGIN", "true").strip().lower() not in (
+        "0",
+        "false",
+        "no",
+    )
+
+
+async def _relogin_oauth_servers(server_keys: list[str]) -> dict[str, MCPClient]:
+    """Deliberate interactive re-auth for the given "profileId:mcpName" keys.
+
+    Drops cached clients WITHOUT recording back-off, clears any pre-existing
+    back-off state, and re-initializes. MCPClient.initialize() with
+    oauth_auto_discover opens the browser OAuth flow and caches the token via
+    fastmcp FileTokenStorage; duplicate popups are prevented by the per-key
+    init locks.
+
+    Returns the fresh clients keyed by cache key so callers can replace any
+    references to the old, now-closed client objects.
+    """
+    new_clients: dict[str, MCPClient] = {}
+    for cache_key in server_keys:
+        await clear_cached_client(cache_key, record_failure=False)
+        _clear_failure(cache_key)  # earlier failures must not block deliberate re-auth
+        profile_id, mcp_name = cache_key.split(":", 1)
+        client = await get_mcp_client_for_server(profile_id, mcp_name)
+        if client:
+            new_clients[cache_key] = client
+    return new_clients
+
+
+def _refresh_client_refs(
+    new_clients: dict[str, MCPClient],
+    clients_to_use: list[tuple[str, str, MCPClient]],
+    tool_to_client: dict[str, tuple[MCPClient, str, str]],
+) -> tuple[list[tuple[str, str, MCPClient]], dict[str, tuple[MCPClient, str, str]]]:
+    """Swap re-logged-in clients into the chat endpoints' lookup structures.
+
+    After _relogin_oauth_servers the old client objects are closed; tool
+    execution through tool_to_client must use the replacements.
+    """
+    refreshed_clients = [
+        (pid, name, new_clients.get(f"{pid}:{name}", client))
+        for pid, name, client in clients_to_use
+    ]
+    refreshed_tools = {
+        tool: (new_clients.get(f"{pid}:{name}", client), pid, name)
+        for tool, (client, pid, name) in tool_to_client.items()
+    }
+    return refreshed_clients, refreshed_tools
+
+
 def is_auth_error(error_msg: str) -> bool:
     """Check if an error message indicates an authentication failure."""
     error_lower = error_msg.lower()
@@ -395,6 +479,30 @@ async def lifespan(app: FastAPI):
     except SQLAlchemyError as e:
         print(f"Warning: could not reconcile stale runs: {e}")
 
+    # …and keep reconciling while we run, so a crashed sibling server (or
+    # a row orphaned by an event-loop death that didn't restart the
+    # process) flips to 'interrupted' within minutes rather than at the
+    # next restart. Heartbeat-only (no started_at fallback): legacy rows
+    # without heartbeats carry local-naive timestamps that can't be
+    # compared reliably against a UTC cutoff.
+    async def _stale_run_sweeper() -> None:
+        from testmcpy.storage import get_storage
+
+        while True:
+            await _asyncio.sleep(60)
+            try:
+                get_storage().mark_stale_runs_interrupted(no_heartbeat_older_than_hours=None)
+            except _asyncio.CancelledError:
+                raise
+            except Exception as sweep_err:  # noqa: BLE001 — long-lived loop:
+                # any escaping error (not just SQLAlchemyError — e.g. an
+                # OSError on first-time DB-path init) would otherwise kill
+                # the sweeper permanently and silently, reverting crash
+                # reconciliation to startup-only. (PR #90 review)
+                print(f"Warning: stale-run sweep failed: {sweep_err}")
+
+    sweeper_task = _asyncio.create_task(_stale_run_sweeper())
+
     # Startup
     try:
         mcp_url = config.get_mcp_url()
@@ -410,6 +518,10 @@ async def lifespan(app: FastAPI):
     yield
 
     # Shutdown
+    sweeper_task.cancel()
+    with contextlib.suppress(_asyncio.CancelledError):
+        await sweeper_task
+
     if mcp_client:
         await mcp_client.close()
 
@@ -907,9 +1019,25 @@ async def chat(request: ChatRequest) -> ChatResponse:
         provider_kwargs = {}
         if api_key:
             provider_kwargs["api_key"] = api_key
-        llm_provider = create_llm_provider(provider, model, **provider_kwargs)
+        provider_kwargs.update(_primary_mcp_provider_kwargs(clients_to_use))
         print("[Chat] Initializing LLM provider...")
-        await llm_provider.initialize()
+        try:
+            llm_provider = create_llm_provider(provider, model, **provider_kwargs)
+            await llm_provider.initialize()
+        except ValueError as e:
+            if not (_chat_oauth_login_enabled() and _OAUTH_TOKEN_ERROR in str(e)):
+                raise
+            print("[Chat] No cached OAuth token; triggering interactive OAuth login...")
+            new_clients = await _relogin_oauth_servers(accessed_servers)
+            # The old client objects are closed now — swap in the replacements
+            # so tool execution doesn't hit a closed client.
+            clients_to_use, tool_to_client = _refresh_client_refs(
+                new_clients, clients_to_use, tool_to_client
+            )
+            provider_kwargs.update(_primary_mcp_provider_kwargs(clients_to_use))
+            llm_provider = create_llm_provider(provider, model, **provider_kwargs)
+            # Single retry; a second failure falls to the existing handlers.
+            await llm_provider.initialize()
         print(
             f"[Chat] LLM provider initialized. Generating response with {len(all_tools)} tools..."
         )
@@ -1180,8 +1308,24 @@ async def chat_stream(request: ChatRequest):
             provider_kwargs: dict = {}
             if api_key:
                 provider_kwargs["api_key"] = api_key
-            llm_provider = create_llm_provider(provider, model, **provider_kwargs)
-            await llm_provider.initialize()
+            provider_kwargs.update(_primary_mcp_provider_kwargs(clients_to_use))
+            try:
+                llm_provider = create_llm_provider(provider, model, **provider_kwargs)
+                await llm_provider.initialize()
+            except ValueError as e:
+                if not (_chat_oauth_login_enabled() and _OAUTH_TOKEN_ERROR in str(e)):
+                    raise
+                yield send_event("status", "Waiting for OAuth login in browser...")
+                new_clients = await _relogin_oauth_servers(accessed_servers)
+                # The old client objects are closed now — swap in the replacements
+                # so tool execution doesn't hit a closed client.
+                clients_to_use, tool_to_client = _refresh_client_refs(
+                    new_clients, clients_to_use, tool_to_client
+                )
+                provider_kwargs.update(_primary_mcp_provider_kwargs(clients_to_use))
+                llm_provider = create_llm_provider(provider, model, **provider_kwargs)
+                # Single retry; a second failure falls to the existing handlers.
+                await llm_provider.initialize()
 
             # --- Detect if provider is SDK-based (handles its own agentic loop) ---
             from testmcpy.src.llm_integration import ClaudeSDKProvider

{testmcpy-0.8.0 → testmcpy-0.9.2}/testmcpy/server/routers/results.py

@@ -11,6 +11,7 @@ from typing import Any
 from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel
 
+from testmcpy.server.run_persistence import question_result_kwargs
 from testmcpy.storage import get_storage
 
 router = APIRouter(prefix="/api/results", tags=["results"])
@@ -98,21 +99,7 @@ def save_test_run_to_file(data: dict[str, Any]) -> dict[str, Any]:
 
     # Save individual question results
     for r in results:
-        storage.save_question_result(
-            run_id=run_id,
-            question_id=r.get("test_name", r.get("question_id", "unknown")),
-            passed=r.get("passed", False),
-            score=r.get("score", 0.0),
-            answer=r.get("response", r.get("answer")),
-            tool_uses=r.get("tool_calls", r.get("tool_uses")),
-            tool_results=r.get("tool_results"),
-            tokens_input=(r.get("token_usage") or {}).get("input", 0),
-            tokens_output=(r.get("token_usage") or {}).get("output", 0),
-            duration_ms=int(r.get("duration", 0) * 1000),
-            evaluations=r.get("evaluations"),
-            error=r.get("error"),
-            cost_usd=r.get("cost", r.get("cost_usd", 0.0)),
-        )
+        storage.save_question_result(run_id=run_id, **question_result_kwargs(r))
 
     # Complete the run
     storage.complete_run(run_id, datetime.now().isoformat())

{testmcpy-0.8.0 → testmcpy-0.9.2}/testmcpy/server/routers/runs.py

@@ -11,8 +11,11 @@ from __future__ import annotations
 from typing import Any
 
 from fastapi import APIRouter, HTTPException
+from sqlalchemy.exc import SQLAlchemyError
 
 from testmcpy.server import run_registry
+from testmcpy.server.run_persistence import wire_status_for_db_status
+from testmcpy.storage import get_storage
 
 router = APIRouter(prefix="/api", tags=["runs"])
 
@@ -65,9 +68,40 @@ async def list_runs(active_only: bool = True) -> dict[str, Any]:
 @router.get("/runs/{run_id}")
 async def get_run(run_id: str) -> dict[str, Any]:
     handle = await run_registry.get_run(run_id)
-    if handle is None:
+    if handle is not None:
+        return _serialise(handle)
+    # Registry miss (GC'd after CLEANUP_TTL, or a server restart) — fall
+    # back to the results DB so a stale tab asking about its run gets the
+    # final state instead of a 404. ``source: history`` tells the client
+    # this is a finished record, not a live handle. A DB hiccup is treated
+    # as a miss (matching the WS twin, _attach_history_run) rather than
+    # surfacing a 500 to the indicator's poll loop.
+    try:
+        record = get_storage().get_run(run_id)
+    except SQLAlchemyError:
+        record = None
+    if record is None:
         raise HTTPException(status_code=404, detail=f"Run not found: {run_id}")
-    return _serialise(handle)
+    status = wire_status_for_db_status(record.get("status"))
+    return {
+        "run_id": run_id,
+        # Only single-run ids ever land a DB row today — directory-batch
+        # ids persist per-file under fresh ids (see _attach_history_run),
+        # so anything resolvable here is a single run by construction.
+        "kind": "single",
+        "status": status,
+        "started_at": record.get("started_at"),
+        "finished_at": record.get("completed_at"),
+        "meta": {
+            "test_path": record.get("test_id"),
+            "model": record.get("model"),
+            "provider": record.get("provider"),
+        },
+        "summary": record.get("summary"),
+        "result_count": len(record.get("question_results") or []),
+        "is_attached": False,
+        "source": "history",
+    }
 
 
 @router.post("/runs/{run_id}/stop")

testmcpy-0.9.2/testmcpy/server/run_persistence.py

@@ -0,0 +1,208 @@
+"""Incremental DB persistence for in-flight test runs.
+
+Historically the WebSocket runner saved a run to the database only once,
+at the very end (``save_test_run_to_file``) — a server crash at test 29/30
+lost everything. ``RunRecord`` makes the DB the source of truth for
+partial progress instead:
+
+- ``begin()``   — creates the suite + a ``test_runs`` row (status=running)
+  as soon as the run starts executing.
+- ``append()``  — writes one ``question_results`` row per completed test.
+- ``finish()``  — stamps the terminal status (completed/error/stopped) and
+  the denormalized totals. Idempotent.
+
+DB errors are swallowed (logged through the run's own log stream): a
+persistence hiccup must degrade history, never kill a live run.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from datetime import datetime, timezone
+from typing import Any
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from testmcpy.storage import get_storage
+
+
+def mint_run_id() -> str:
+    """Legacy ``<8-hex>_<timestamp>`` run-id shape shared with the run
+    registry and ``save_test_run_to_file`` so every code path mints
+    correlatable identifiers."""
+    return f"{uuid.uuid4().hex[:8]}_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+
+
+def question_result_kwargs(r: dict[str, Any]) -> dict[str, Any]:
+    """Map a TestResult.to_dict() shape onto ``save_question_result``
+    kwargs. Single source of truth for the mapping — used by both the
+    end-of-run ``save_test_run_to_file`` and the incremental ``RunRecord``.
+    """
+    # LLM providers report token_usage as {prompt, completion, total}
+    # (see llm_integration.py); the old mapping read input/output and
+    # silently stored 0 for every UI-triggered run. Keep input/output as
+    # a fallback for callers of POST /api/results/save that adopted the
+    # old keys.
+    usage = r.get("token_usage") or {}
+    return {
+        "question_id": r.get("test_name", r.get("question_id", "unknown")),
+        "passed": r.get("passed", False),
+        "score": r.get("score", 0.0),
+        "answer": r.get("response", r.get("answer")),
+        "tool_uses": r.get("tool_calls", r.get("tool_uses")),
+        "tool_results": r.get("tool_results"),
+        "tokens_input": usage.get("prompt", usage.get("input", 0)),
+        "tokens_output": usage.get("completion", usage.get("output", 0)),
+        "duration_ms": int(r.get("duration", 0) * 1000),
+        "evaluations": r.get("evaluations"),
+        "error": r.get("error"),
+        "cost_usd": r.get("cost", r.get("cost_usd", 0.0)),
+    }
+
+
+def ui_result_from_question_result(q: dict[str, Any]) -> dict[str, Any]:
+    """Inverse of ``question_result_kwargs``: map a stored question_results
+    row (as returned by ``storage.get_run``) back onto the TestResult
+    wire shape the UI's test_complete / all_complete handlers expect —
+    including the live {prompt, completion, total} token_usage keys the
+    client sums (TestRunContext reads token_usage.total)."""
+    tokens_in = q.get("tokens_input", 0) or 0
+    tokens_out = q.get("tokens_output", 0) or 0
+    return {
+        "test_name": q.get("question_id"),
+        "passed": bool(q.get("passed")),
+        "score": q.get("score", 0.0),
+        "response": q.get("answer"),
+        "tool_calls": q.get("tool_uses") or [],
+        "tool_results": q.get("tool_results") or [],
+        "token_usage": {
+            "prompt": tokens_in,
+            "completion": tokens_out,
+            "total": tokens_in + tokens_out,
+        },
+        "duration": (q.get("duration_ms") or 0) / 1000,
+        "evaluations": q.get("evaluations") or [],
+        "error": q.get("error"),
+        "cost": q.get("cost_usd", 0.0) or 0.0,
+    }
+
+
+# DB statuses that map straight onto the wire's terminal statuses. A DB
+# row still 'running' (or already 'interrupted') with no registry handle
+# means the server died mid-run — report it as interrupted.
+_TERMINAL_WIRE_STATUS = {"completed": "completed", "stopped": "stopped", "error": "error"}
+
+
+def wire_status_for_db_status(db_status: str | None) -> str:
+    """Map a test_runs.status onto the WebSocket/REST wire status for a
+    run that is NOT in the in-memory registry: terminal statuses pass
+    through, anything else (running / interrupted / NULL / unknown) means
+    the owning process died mid-run — interrupted."""
+    return _TERMINAL_WIRE_STATUS.get(db_status or "", "interrupted")
+
+
+def history_replay_messages(record: dict[str, Any]) -> list[dict[str, Any]]:
+    """Synthesize the WebSocket message sequence for attaching to a run
+    that's no longer in the in-memory registry (GC'd after CLEANUP_TTL,
+    or lost to a server restart) but lives in the results DB: a
+    ``run_started`` marker, one ``test_complete`` per stored result (so
+    the UI rebuilds its per-test panels), and a terminal ``all_complete``
+    carrying the run's real status — including ``interrupted`` with
+    partial results for runs that died mid-flight."""
+    status = wire_status_for_db_status(record.get("status"))
+    results = [ui_result_from_question_result(q) for q in record.get("question_results", [])]
+    passed = sum(1 for r in results if r["passed"])
+    summary = {
+        "total": len(results),
+        "passed": passed,
+        "failed": len(results) - passed,
+        "total_cost": sum(r["cost"] for r in results),
+        "status": status,
+    }
+    return [
+        {
+            "type": "run_started",
+            "run_id": record.get("run_id"),
+            "kind": "single",
+            "reattached": True,
+            "status": status,
+            "source": "history",
+        },
+        *({"type": "test_complete", "test_name": r["test_name"], "result": r} for r in results),
+        {"type": "all_complete", "status": status, "summary": summary, "results": results},
+    ]
+
+
+class RunRecord:
+    """Write-through record of one run (one YAML file) in the results DB.
+
+    All writes are best-effort: a failure marks the record broken and is
+    reported once through ``log``, after which subsequent calls no-op so
+    a flaky DB doesn't spam the run log or slow the run down.
+    """
+
+    def __init__(self, run_id: str | None = None, log: Callable[[str], None] | None = None):
+        self.run_id = run_id or mint_run_id()
+        self._log = log or (lambda msg: None)
+        self._began = False
+        self._finished = False
+        self._broken = False
+
+    def _report_db_error(self, op: str, exc: SQLAlchemyError) -> None:
+        self._broken = True
+        self._log(f"⚠️ Results DB unavailable ({op}): {exc} — run continues without history")
+
+    def begin(
+        self,
+        *,
+        test_file: str,
+        model: str,
+        provider: str,
+        mcp_profile: str | None = None,
+        llm_profile: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Create the suite + the run row (status=running) up front."""
+        if self._began or self._broken:
+            return
+        try:
+            storage = get_storage()
+            storage.save_suite(suite_id=test_file, name=test_file, questions=[])
+            storage.save_run(
+                run_id=self.run_id,
+                test_id=test_file,
+                test_version=1,
+                model=model,
+                provider=provider,
+                started_at=datetime.now(timezone.utc).isoformat(),
+                mcp_profile_id=mcp_profile,
+                llm_profile_id=llm_profile,
+                metadata=metadata,
+            )
+            self._began = True
+        except SQLAlchemyError as exc:
+            self._report_db_error("begin", exc)
+
+    def append(self, result: dict[str, Any]) -> None:
+        """Persist one completed test immediately (crash-safe progress)."""
+        if not self._began or self._finished or self._broken:
+            return
+        try:
+            get_storage().save_question_result(run_id=self.run_id, **question_result_kwargs(result))
+        except SQLAlchemyError as exc:
+            self._report_db_error("append", exc)
+
+    def finish(self, status: str) -> None:
+        """Stamp the terminal status + denormalized totals. Idempotent —
+        the first terminal status wins (e.g. ``stopped`` from the cancel
+        path must not be overwritten by a later generic finalizer)."""
+        if not self._began or self._finished or self._broken:
+            return
+        try:
+            get_storage().finish_run(
+                self.run_id, status=status, completed_at=datetime.now(timezone.utc).isoformat()
+            )
+            self._finished = True
+        except SQLAlchemyError as exc:
+            self._report_db_error("finish", exc)