alysis-code 0.13.0__py3-none-any.whl

alysis_code/branding.py

@@ -0,0 +1,270 @@
+"""Product identity, and the compatibility shims that keep pre-rebrand installs working.
+
+The CLI shipped as "Sylliptor" (package ``sylliptor-agent-cli``, command
+``sylliptor``, env prefix ``SYLLIPTOR_``) before being renamed to Alysis Code.
+Everything a user could have written down — env vars in a CI config, a
+``.sylliptor/`` directory committed to their repo, a keyring entry holding MCP
+OAuth tokens — still resolves, with a one-time deprecation notice. See
+``docs/migration-alysis-code.md`` for the removal timeline.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import threading
+import warnings
+from collections.abc import Mapping
+from importlib import metadata as importlib_metadata
+from pathlib import Path
+from urllib.parse import urlparse
+
+from platformdirs import user_config_dir, user_data_dir
+
+LOGGER = logging.getLogger(__name__)
+
+PRODUCT_NAME = "Alysis Code"
+CANONICAL_APP_NAME = "alysis"
+CANONICAL_SERVER_APP_NAME = "alysis-code-server"
+PYTHON_PACKAGE_NAME = "alysis-code"
+PROJECT_SOURCE_URL = "https://github.com/AlysisAi/alysis-code"
+SANDBOX_IMAGE_REPOSITORY = "alysis-sandbox"
+ENV_PREFIX = "ALYSIS_"
+PROJECT_DIR_NAME = ".alysis"
+PLUGIN_MANIFEST_NAME = "alysis-plugin.toml"
+
+# --- pre-rebrand identities -------------------------------------------------
+LEGACY_PRODUCT_NAME = "Sylliptor"
+LEGACY_APP_NAME = "sylliptor"
+LEGACY_SERVER_APP_NAME = "sylliptor-agent-cli-server"
+LEGACY_PYTHON_PACKAGE_NAME = "sylliptor-agent-cli"
+LEGACY_ENV_PREFIX = "SYLLIPTOR_"
+LEGACY_PROJECT_DIR_NAME = ".sylliptor"
+LEGACY_PLUGIN_MANIFEST_NAME = "sylliptor-plugin.toml"
+
+# Written into a migrated legacy directory so a second run does not re-copy, and
+# so a human poking around understands why the directory is now inert.
+MIGRATION_MARKER_NAME = ".migrated-to-alysis"
+
+_notice_lock = threading.Lock()
+_legacy_env_seen: dict[str, str] = {}
+_migrated_paths: dict[str, str] = {}
+_legacy_paths_in_use: dict[str, str] = {}
+
+
+def legacy_env_name(name: str) -> str | None:
+    """Return the pre-rebrand spelling of an ``ALYSIS_*`` variable, if any."""
+    if not name.startswith(ENV_PREFIX):
+        return None
+    return LEGACY_ENV_PREFIX + name[len(ENV_PREFIX) :]
+
+
+def _record_legacy_env(legacy: str, current: str) -> None:
+    with _notice_lock:
+        if legacy in _legacy_env_seen:
+            return
+        _legacy_env_seen[legacy] = current
+    message = (
+        f"{legacy} is deprecated and will be removed in a future release; rename it to {current}."
+    )
+    LOGGER.warning("legacy_env_var legacy=%s current=%s", legacy, current)
+    warnings.warn(message, DeprecationWarning, stacklevel=3)
+
+
+def env_get(name: str, default: str | None = None) -> str | None:
+    """Read an environment variable, falling back to its pre-rebrand name.
+
+    The new name always wins when both are set, so a user midway through the
+    migration gets the value they most recently wrote.
+    """
+    return env_get_from(os.environ, name, default)
+
+
+def env_get_from(
+    environ: Mapping[str, str],
+    name: str,
+    default: str | None = None,
+) -> str | None:
+    """Read ``name`` from a mapping with the same rename fallback as :func:`env_get`.
+
+    Runtime settings often accept an injected environment mapping for tests or
+    subprocess construction. Keeping the prefix-derived fallback here prevents
+    those paths from drifting from process-environment behavior.
+    """
+    value = environ.get(name)
+    if value is not None:
+        return value
+
+    legacy = legacy_env_name(name)
+    if legacy is not None:
+        legacy_value = environ.get(legacy)
+        if legacy_value is not None:
+            _record_legacy_env(legacy, name)
+            return legacy_value
+
+    return default
+
+
+def with_legacy_env_aliases(env: Mapping[str, str]) -> dict[str, str]:
+    """Duplicate ``ALYSIS_*`` entries under their legacy names.
+
+    Used when building the environment for code we do not control — user-authored
+    hooks and custom tools, which may still read ``SYLLIPTOR_TOOL_NAME`` and
+    friends. Existing legacy keys in ``env`` are left alone.
+    """
+    merged = dict(env)
+    for key, value in env.items():
+        legacy = legacy_env_name(key)
+        if legacy is not None and legacy not in merged:
+            merged[legacy] = value
+    return merged
+
+
+def consume_legacy_notices() -> list[str]:
+    """Drain accumulated deprecation notices for the CLI to surface once."""
+    with _notice_lock:
+        env_items = sorted(_legacy_env_seen.items())
+        migrated = sorted(_migrated_paths.items())
+        in_use = sorted(_legacy_paths_in_use.items())
+        _legacy_env_seen.clear()
+        _migrated_paths.clear()
+        _legacy_paths_in_use.clear()
+
+    notices = [
+        f"Environment variable {legacy} is deprecated — use {current}."
+        for legacy, current in env_items
+    ]
+    notices.extend(f"Copied {legacy} to {current}." for legacy, current in migrated)
+    notices.extend(
+        f"Using legacy directory {legacy}; rename it to {current} when convenient."
+        for legacy, current in in_use
+    )
+    return notices
+
+
+def _github_owner_from_url(url: str) -> str | None:
+    value = url.strip()
+    if value.startswith("git@github.com:"):
+        path = value.removeprefix("git@github.com:")
+        parts = [part for part in path.removesuffix(".git").split("/") if part]
+        return parts[0] if len(parts) >= 2 else None
+
+    parsed = urlparse(value)
+    if parsed.hostname != "github.com":
+        return None
+    parts = [part for part in parsed.path.removesuffix(".git").strip("/").split("/") if part]
+    return parts[0] if len(parts) >= 2 else None
+
+
+def _packaging_source_urls() -> tuple[str, ...]:
+    urls: list[str] = [PROJECT_SOURCE_URL]
+    try:
+        package_metadata = importlib_metadata.metadata(PYTHON_PACKAGE_NAME)
+    except importlib_metadata.PackageNotFoundError:
+        return tuple(urls)
+
+    homepage = package_metadata.get("Home-page")
+    if homepage:
+        urls.append(homepage)
+    for project_url in package_metadata.get_all("Project-URL") or ():
+        label, _, value = project_url.partition(",")
+        if label.strip().lower() in {"source", "repository", "homepage"} and value.strip():
+            urls.append(value.strip())
+    return tuple(dict.fromkeys(urls))
+
+
+def resolve_ghcr_owner() -> str | None:
+    for source_url in _packaging_source_urls():
+        owner = _github_owner_from_url(source_url)
+        if owner:
+            return owner
+    return None
+
+
+def default_sandbox_docker_image(variant: str = "dev") -> str:
+    tag = variant.strip() or "dev"
+    owner = resolve_ghcr_owner()
+    if owner:
+        return f"ghcr.io/{owner.lower()}/{SANDBOX_IMAGE_REPOSITORY}:{tag}"
+    return f"{SANDBOX_IMAGE_REPOSITORY}:{tag}"
+
+
+def _migrate_legacy_dir(current: Path, legacy: Path) -> Path:
+    """Seed ``current`` from a pre-rebrand ``legacy`` directory, once.
+
+    The legacy tree is *copied*, not moved: an older install sharing the machine
+    keeps working, and a failed copy never destroys the only copy of a user's
+    credentials. A marker file in the legacy directory makes this idempotent.
+    """
+    if current.exists() or not legacy.is_dir():
+        return current
+    if (legacy / MIGRATION_MARKER_NAME).exists():
+        return current
+
+    try:
+        shutil.copytree(legacy, current, dirs_exist_ok=False)
+    except (OSError, shutil.Error) as exc:
+        # A failed migration must not be fatal: fall through to a fresh
+        # directory rather than blocking startup entirely.
+        LOGGER.warning(
+            "legacy_dir_migration_failed legacy=%s current=%s error=%s", legacy, current, exc
+        )
+        return current
+
+    try:
+        (legacy / MIGRATION_MARKER_NAME).write_text(
+            f"Copied to {current} during the Sylliptor -> Alysis Code rename.\n"
+            "This directory is no longer read. Delete it once you are confident "
+            "the migration went through.\n",
+            encoding="utf-8",
+        )
+    except OSError:
+        # Marker is an optimisation; a missing one only costs a redundant check.
+        pass
+
+    with _notice_lock:
+        _migrated_paths.setdefault(str(legacy), str(current))
+    LOGGER.info("legacy_dir_migrated legacy=%s current=%s", legacy, current)
+    return current
+
+
+def canonical_user_config_dir() -> Path:
+    current = Path(user_config_dir(CANONICAL_APP_NAME, CANONICAL_APP_NAME))
+    legacy = Path(user_config_dir(LEGACY_APP_NAME, LEGACY_APP_NAME))
+    return _migrate_legacy_dir(current, legacy)
+
+
+def canonical_user_data_dir() -> Path:
+    current = Path(user_data_dir(CANONICAL_APP_NAME, CANONICAL_APP_NAME))
+    legacy = Path(user_data_dir(LEGACY_APP_NAME, LEGACY_APP_NAME))
+    return _migrate_legacy_dir(current, legacy)
+
+
+def canonical_server_data_dir() -> Path:
+    current = Path(user_data_dir(CANONICAL_SERVER_APP_NAME, CANONICAL_APP_NAME))
+    legacy = Path(user_data_dir(LEGACY_SERVER_APP_NAME, LEGACY_APP_NAME))
+    return _migrate_legacy_dir(current, legacy)
+
+
+def resolve_project_dir(root: Path) -> Path:
+    """Return the per-repo agent directory, preferring ``.alysis``.
+
+    A ``.sylliptor`` directory is honoured in place when it is the only one
+    present: it is typically committed to the user's repository, so silently
+    renaming it would show up as an unexplained diff in their working tree.
+    """
+    current = root / PROJECT_DIR_NAME
+    if current.exists():
+        return current
+    legacy = root / LEGACY_PROJECT_DIR_NAME
+    if legacy.is_dir():
+        with _notice_lock:
+            _legacy_paths_in_use.setdefault(str(legacy), str(current))
+        return legacy
+    return current
+
+
+def plugin_manifest_candidates() -> tuple[str, ...]:
+    """Manifest filenames to probe, newest spelling first."""
+    return (PLUGIN_MANIFEST_NAME, LEGACY_PLUGIN_MANIFEST_NAME)

alysis_code/budget_policy.py

@@ -0,0 +1,390 @@
+"""Run-budget policy: sizing, stop-reason, watchdog, and progress checkpoint.
+
+This module is deliberately dependency-light -- standard library only, and no
+imports from the rest of the package. Two reasons:
+
+* it is loaded by ``agent/turn/core.py`` and ``agent/session.py`` on the hot
+  path, and must not drag anything in;
+* it holds the decision logic that has to be unit-testable in a bare
+  interpreter, without executing ``alysis_code/__init__`` (which pulls
+  in httpx/pydantic/rich). ``tests/test_budget_policy.py`` loads this file
+  directly by path.
+
+Environment lookups stay local rather than importing ``branding`` for the same
+reason. The prefix-derived ``SYLLIPTOR_*`` fallback is repeated in the small
+lookup helper so standalone and package execution keep the same behavior.
+
+Why a watchdog exists at all
+----------------------------
+Every pre-existing budget check in the engine is a *start gate*: it is
+evaluated before an operation begins (``ExecutionDeadline.start_decision``,
+``deadline_timeout_or_raise``). Nothing re-checks the clock while an operation
+is in flight, so any blocking call that does not bound itself by the deadline
+can outlive the budget indefinitely -- which is exactly what was observed in
+production, where runs recorded ``exhausted: true`` and then kept going for
+hours. :class:`BudgetWatchdog` is the stop gate: a daemon timer armed once at
+run start that trips a cancellation event at ``budget + grace``, regardless of
+what the main thread is blocked on.
+"""
+
+from __future__ import annotations
+
+import math
+import os
+import threading
+from collections.abc import Callable, Mapping
+from typing import Any
+
+# Wall-clock budget applied to a non-interactive run that did not configure
+# one. Unchanged from the value this replaced, so default behaviour is
+# identical; it is now overridable per-run instead of being a literal.
+DEFAULT_RUN_BUDGET_SECONDS = 3600.0
+
+# How long past the deadline an in-flight operation is given to unwind
+# cooperatively before the watchdog cancels it.
+DEFAULT_BUDGET_GRACE_SECONDS = 60.0
+
+# Fraction of the budget at which a run with nothing to show for itself is
+# told so.
+DEFAULT_BUDGET_CHECKPOINT_FRACTION = 0.33
+
+RUN_BUDGET_SECONDS_ENV = "ALYSIS_RUN_BUDGET_SECONDS"
+BUDGET_GRACE_SECONDS_ENV = "ALYSIS_BUDGET_GRACE_SECONDS"
+BUDGET_CHECKPOINT_FRACTION_ENV = "ALYSIS_BUDGET_CHECKPOINT_FRACTION"
+
+# Machine-readable marker for "the run stopped because it ran out of budget".
+# Written to the session log's final event and to the run_finished
+# crash-diagnostic event so a harness can tell a budget stop from a crash
+# without parsing prose.
+STOP_REASON_RUN_BUDGET_EXHAUSTED = "run_budget_exhausted"
+
+PROGRESS_CHECKPOINT_FAILED_EVENT = "progress_checkpoint_failed"
+
+# A budget stop is a normal outcome, not a failure: the agent did what it could
+# in the time it was given and reported honestly. Exiting non-zero made every
+# harness record it as NonZeroAgentExitCodeError.
+BUDGET_STOP_EXIT_CODE = 0
+DEFAULT_FAILURE_EXIT_CODE = 1
+
+# The single model-visible string introduced by this module. Kept as one
+# constant so it is greppable and cannot drift.
+BUDGET_CHECKPOINT_NOTICE = (
+    "Budget checkpoint: no material progress recorded yet. "
+    "Reassess approach or report the concrete blocker."
+)
+
+# Terminal reasons that are *not* failures. Everything else exits non-zero.
+GRACEFUL_STOP_REASONS = frozenset(
+    {
+        "",
+        "completed",
+        "session_close",
+        STOP_REASON_RUN_BUDGET_EXHAUSTED,
+    }
+)
+
+
+class RunBudgetCancelled(Exception):
+    """Fallback cancellation error used when no error class is injected.
+
+    Production wires :class:`BudgetCancellationToken` with
+    ``cancellation.CooperativeCancellationError`` so that every existing
+    ``except CooperativeCancellationError`` clause keeps working. This class
+    exists so the module stays importable, and testable, on its own.
+    """
+
+    def __init__(self, reason: str = STOP_REASON_RUN_BUDGET_EXHAUSTED) -> None:
+        super().__init__(reason)
+        self.reason = str(reason or STOP_REASON_RUN_BUDGET_EXHAUSTED)
+
+
+def _env_value(name: str, environ: Mapping[str, str] | None = None) -> str | None:
+    source: Mapping[str, str] = os.environ if environ is None else environ
+    raw = source.get(name)
+    if raw is None and name.startswith("ALYSIS_"):
+        raw = source.get("SYLLIPTOR_" + name.removeprefix("ALYSIS_"))
+    if raw is None:
+        return None
+    cleaned = str(raw).strip()
+    return cleaned or None
+
+
+def _positive_float(raw: str | None, fallback: float) -> float:
+    """Parse a strictly positive finite float, falling back on anything else.
+
+    A misconfigured budget must never be able to abort a run or, worse, make
+    the budget effectively infinite. Every bad value -- unparseable, negative,
+    zero, NaN, inf -- resolves to the documented default.
+    """
+    if raw is None:
+        return fallback
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return fallback
+    if not math.isfinite(value) or value <= 0.0:
+        return fallback
+    return value
+
+
+def _non_negative_float(raw: str | None, fallback: float) -> float:
+    """Like :func:`_positive_float` but admits ``0`` (a zero-length window)."""
+    if raw is None:
+        return fallback
+    try:
+        value = float(raw)
+    except (TypeError, ValueError):
+        return fallback
+    if not math.isfinite(value) or value < 0.0:
+        return fallback
+    return value
+
+
+def resolve_run_budget_seconds(environ: Mapping[str, str] | None = None) -> float:
+    """Default wall-clock budget for a non-interactive run, in seconds.
+
+    ``ALYSIS_RUN_BUDGET_SECONDS`` overrides
+    :data:`DEFAULT_RUN_BUDGET_SECONDS`. This sets only the *default* rung of
+    the existing precedence ladder (``--deadline-seconds`` >
+    ``ALYSIS_RUN_DEADLINE_SECONDS`` > ``run_deadline_seconds`` config >
+    this), so nothing that already configured a budget changes behaviour.
+    """
+    return _positive_float(
+        _env_value(RUN_BUDGET_SECONDS_ENV, environ),
+        DEFAULT_RUN_BUDGET_SECONDS,
+    )
+
+
+def resolve_budget_grace_seconds(environ: Mapping[str, str] | None = None) -> float:
+    """Grace window between the deadline passing and forced cancellation.
+
+    ``ALYSIS_BUDGET_GRACE_SECONDS``; default
+    :data:`DEFAULT_BUDGET_GRACE_SECONDS`. Zero is legal and means "cancel the
+    moment the budget is gone".
+    """
+    return _non_negative_float(
+        _env_value(BUDGET_GRACE_SECONDS_ENV, environ),
+        DEFAULT_BUDGET_GRACE_SECONDS,
+    )
+
+
+def resolve_checkpoint_fraction(environ: Mapping[str, str] | None = None) -> float:
+    """Budget fraction at which the no-progress checkpoint is evaluated.
+
+    ``ALYSIS_BUDGET_CHECKPOINT_FRACTION``; default
+    :data:`DEFAULT_BUDGET_CHECKPOINT_FRACTION`. Values outside ``(0, 1]`` fall
+    back, so the checkpoint can never be armed at "already past the end".
+    """
+    value = _positive_float(
+        _env_value(BUDGET_CHECKPOINT_FRACTION_ENV, environ),
+        DEFAULT_BUDGET_CHECKPOINT_FRACTION,
+    )
+    if value > 1.0:
+        return DEFAULT_BUDGET_CHECKPOINT_FRACTION
+    return value
+
+
+def exit_code_for_stop(
+    stop_reason: str | None,
+    *,
+    failure_exit_code: int = DEFAULT_FAILURE_EXIT_CODE,
+) -> int:
+    """Process exit code for a run terminating with ``stop_reason``.
+
+    The whole point of this table: a run-budget stop is a *normal* outcome and
+    must exit 0, while genuine errors keep their non-zero code. Callers pass
+    their own ``failure_exit_code`` so infrastructure failures can still use
+    ``INFRASTRUCTURE_FAILURE_EXIT_CODE``.
+    """
+    reason = str(stop_reason or "").strip().lower()
+    if reason in GRACEFUL_STOP_REASONS:
+        return BUDGET_STOP_EXIT_CODE
+    return int(failure_exit_code)
+
+
+def is_budget_stop(stop_reason: str | None) -> bool:
+    return str(stop_reason or "").strip().lower() == STOP_REASON_RUN_BUDGET_EXHAUSTED
+
+
+def is_budget_cancellation(error: BaseException | None) -> bool:
+    """True when ``error`` is a cancellation raised by the budget watchdog.
+
+    Distinguishes a watchdog stop from a user-requested cancellation, which
+    share an exception type. Matching on the ``reason`` attribute is what
+    ``CooperativeCancellationError`` already exposes.
+    """
+    if error is None:
+        return False
+    return is_budget_stop(getattr(error, "reason", None))
+
+
+class BudgetCancellationToken:
+    """Cancellation token whose cancellation means "the run budget is gone".
+
+    Duck-types ``cancellation.EventCancellationToken``: ``is_cancelled`` plus
+    ``throw_if_cancelled``. The error class is injected rather than imported so
+    this module keeps no package dependencies; production passes
+    ``CooperativeCancellationError`` so every existing handler still catches it.
+    """
+
+    def __init__(
+        self,
+        event: threading.Event,
+        *,
+        error_class: type[BaseException] | None = None,
+        reason: str = STOP_REASON_RUN_BUDGET_EXHAUSTED,
+    ) -> None:
+        self._event = event
+        self._error_class: type[BaseException] = error_class or RunBudgetCancelled
+        self.reason = str(reason or STOP_REASON_RUN_BUDGET_EXHAUSTED)
+
+    @property
+    def is_cancelled(self) -> bool:
+        return self._event.is_set()
+
+    def throw_if_cancelled(self, reason: str | None = None) -> None:
+        """Raise if cancelled, always attributing the stop to the budget.
+
+        The caller-supplied ``reason`` is ignored on purpose: the turn engine
+        passes the literal ``"cancelled_by_user"`` at every checkpoint, and
+        this token knows better why it fired. Preserving the real reason is
+        what lets the stop be finalized as a clean budget exit rather than a
+        user abort.
+        """
+        _ = reason
+        if self.is_cancelled:
+            raise self._error_class(self.reason)
+
+
+class BudgetWatchdog:
+    """Daemon timer that trips a cancellation event at ``budget + grace``.
+
+    Armed once at run start and disarmed in a ``finally``. Firing sets a
+    :class:`threading.Event`, which is all a cooperative checkpoint or a
+    ``wait``-style blocking call needs to unblock; the watchdog itself never
+    touches execution state, so it cannot corrupt a run that was about to
+    finish normally.
+    """
+
+    def __init__(
+        self,
+        *,
+        budget_seconds: float,
+        grace_seconds: float = DEFAULT_BUDGET_GRACE_SECONDS,
+        on_fire: Callable[[], None] | None = None,
+        event: threading.Event | None = None,
+        timer_factory: Callable[..., Any] = threading.Timer,
+    ) -> None:
+        self.budget_seconds = max(0.0, float(budget_seconds))
+        self.grace_seconds = max(0.0, float(grace_seconds))
+        self._on_fire = on_fire
+        self._event = event if event is not None else threading.Event()
+        self._timer_factory = timer_factory
+        self._timer: Any | None = None
+        self._lock = threading.Lock()
+
+    @property
+    def event(self) -> threading.Event:
+        return self._event
+
+    @property
+    def fired(self) -> bool:
+        return self._event.is_set()
+
+    @property
+    def armed(self) -> bool:
+        return self._timer is not None
+
+    def fire_delay_seconds(self) -> float:
+        """Seconds from arming to firing: the whole budget plus the grace."""
+        return self.budget_seconds + self.grace_seconds
+
+    def arm(self) -> BudgetWatchdog:
+        with self._lock:
+            if self._timer is not None:
+                return self
+            timer = self._timer_factory(self.fire_delay_seconds(), self._fire)
+            # Daemon: a watchdog must never be the reason a process refuses to
+            # exit once the run has finished on its own.
+            try:
+                timer.daemon = True
+            except AttributeError:  # pragma: no cover - injected fakes may differ
+                pass
+            self._timer = timer
+            timer.start()
+        return self
+
+    def disarm(self) -> None:
+        with self._lock:
+            timer, self._timer = self._timer, None
+        if timer is not None:
+            try:
+                timer.cancel()
+            except Exception:  # noqa: BLE001 - teardown must never raise
+                pass
+
+    def _fire(self) -> None:
+        self._event.set()
+        if self._on_fire is None:
+            return
+        try:
+            self._on_fire()
+        except Exception:  # noqa: BLE001 - a telemetry failure must not kill the timer thread
+            pass
+
+    def __enter__(self) -> BudgetWatchdog:
+        return self.arm()
+
+    def __exit__(self, *_exc: object) -> None:
+        self.disarm()
+
+
+class ProgressCheckpoint:
+    """One-shot "no material progress yet" trigger at a fraction of budget.
+
+    Material progress is file modifications or verification attempts -- the two
+    counters the runtime summary already reports. Both are monotonic, so a run
+    that has done something real can never trip this later.
+    """
+
+    def __init__(
+        self,
+        *,
+        fraction: float | None = None,
+        environ: Mapping[str, str] | None = None,
+    ) -> None:
+        self.fraction = (
+            resolve_checkpoint_fraction(environ) if fraction is None else float(fraction)
+        )
+        self._fired = False
+
+    @property
+    def fired(self) -> bool:
+        return self._fired
+
+    def check(
+        self,
+        *,
+        elapsed_fraction: float | None,
+        material_edit_count: int,
+        verification_attempt_count: int,
+    ) -> bool:
+        """Return ``True`` exactly once, the first time the checkpoint fails.
+
+        ``elapsed_fraction`` is ``None`` when no finite budget applies, in
+        which case there is no checkpoint to miss.
+        """
+        if self._fired:
+            return False
+        if elapsed_fraction is None:
+            return False
+        try:
+            fraction = float(elapsed_fraction)
+        except (TypeError, ValueError):
+            return False
+        if not math.isfinite(fraction) or fraction < self.fraction:
+            return False
+        if int(material_edit_count or 0) > 0 or int(verification_attempt_count or 0) > 0:
+            return False
+        self._fired = True
+        return True