syncade 0.6.2__py3-none-any.whl

syncade/metrics/schema.py

@@ -0,0 +1,221 @@
+"""Metrics DB schema + sink (stdlib ``sqlite3`` only).
+
+Three tables — one row per run (``runs``), one per run/reviewer/model
+(``reviewer_stats``), and one per usage-emitting actor/model (``actor_stats``).
+Writes are idempotent upserts keyed on the primary key,
+so re-aggregating the corpus rebuilds the same rows rather than duplicating
+them. ``tokens`` / ``cost_usd`` (on both tables) are populated by PR-4 from each
+run's manifests; legacy runs with no usage data stay NULL.
+
+The row shapes are stdlib dataclasses (not pydantic): the data comes from
+syncade's own artifacts, not an untrusted boundary, so validation buys nothing
+here. Columns are generated from the dataclass fields, so the DDL below and the
+dataclasses must stay aligned — the schema tests fail loudly if they drift.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import sqlite3
+from pathlib import Path
+
+
+@dataclasses.dataclass
+class RunRow:
+    """One aggregated row per syncade run. ``run_id`` is the primary key."""
+
+    run_id: str
+    verdict: str = ""
+    rounds_executed: int = 0
+    blockers: int = 0
+    minors: int = 0
+    nits: int = 0
+    dismissed: int = 0
+    final_exit_code: int | None = None
+    termination_reason: str | None = None
+    operator_branch: str | None = None
+    handoff: int = 0
+    decision_needed: int = 0
+    producer_commits: int = 0
+    producer_stalled: int = 0
+    producer_errors: int = 0
+    producer_escalated: int = 0
+    tokens: int | None = None  # reserved for PR-4
+    cost_usd: float | None = None  # reserved for PR-4
+
+
+@dataclasses.dataclass
+class ReviewerStatRow:
+    """One row per (run, reviewer). PK is (``run_id``, ``name``)."""
+
+    run_id: str
+    name: str
+    provider: str = ""
+    model: str = ""
+    finding_count: int = 0
+    duration_s: float = 0.0
+    tokens: int | None = None
+    cost_usd: float | None = None
+    cost_source: str = ""  # "provider" | "estimated" | "unknown" | "" (no usage)
+
+
+@dataclasses.dataclass
+class ActorStatRow:
+    """One row per usage-emitting actor. PK is
+    (``run_id``, ``role``, ``name``, ``provider``, ``model``, ``auth_mode``) — auth_mode is
+    part of the key so one actor that ran under two modes keeps a row per mode (PR-v2-24)."""
+
+    run_id: str
+    role: str
+    name: str
+    provider: str = ""
+    model: str = ""
+    tokens: int | None = None
+    cost_usd: float | None = None
+    cost_incomplete_tokens: int = 0
+    cost_source: str = ""  # "provider" | "estimated" | "unknown" | "" (no usage)
+    auth_mode: str = ""  # "subscription" | "api" | "none" | "unknown" | "" (legacy run)
+    rounds_with_usage: int = 0  # rounds with any usage reported; 0 = legacy/unknown
+
+
+_RUNS_DDL = """
+CREATE TABLE IF NOT EXISTS runs (
+    run_id TEXT PRIMARY KEY,
+    verdict TEXT,
+    rounds_executed INTEGER,
+    blockers INTEGER,
+    minors INTEGER,
+    nits INTEGER,
+    dismissed INTEGER,
+    final_exit_code INTEGER,
+    termination_reason TEXT,
+    operator_branch TEXT,
+    handoff INTEGER,
+    decision_needed INTEGER,
+    producer_commits INTEGER,
+    producer_stalled INTEGER,
+    producer_errors INTEGER,
+    producer_escalated INTEGER,
+    tokens INTEGER,
+    cost_usd REAL
+)
+"""
+
+_REVIEWER_STATS_DDL = """
+CREATE TABLE IF NOT EXISTS reviewer_stats (
+    run_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    provider TEXT,
+    model TEXT,
+    finding_count INTEGER,
+    duration_s REAL,
+    tokens INTEGER,
+    cost_usd REAL,
+    cost_source TEXT,
+    PRIMARY KEY (run_id, name, provider, model)
+)
+"""
+
+_ACTOR_STATS_DDL = """
+CREATE TABLE IF NOT EXISTS actor_stats (
+    run_id TEXT NOT NULL,
+    role TEXT NOT NULL,
+    name TEXT NOT NULL,
+    provider TEXT,
+    model TEXT,
+    tokens INTEGER,
+    cost_usd REAL,
+    cost_incomplete_tokens INTEGER,
+    cost_source TEXT,
+    -- PR-v2-24. cost_usd is an API-EQUIVALENT VALUATION, not spend: it is fiction
+    -- whenever the call rode a subscription. Only the resolved auth mode knows which,
+    -- and it is orthogonal to cost_source -- claude reports total_cost_usd even on an
+    -- OAuth session. Legacy rows stay NULL, and NULL reports as neither billed nor
+    -- free, because cost is never fabricated.
+    -- auth_mode is part of the KEY, not a merged attribute. Keyed without it, one actor
+    -- that ran under two modes (a run resumed with a changed env) collapsed to "mixed"
+    -- and its REAL API SPEND became unclassified before billing ever saw it. Fixing the
+    -- reader was not enough while the writer still destroyed the split -- the key is what
+    -- makes the loss impossible rather than merely unlikely.
+    auth_mode TEXT NOT NULL DEFAULT '',
+    -- Rounds where this actor reported any usage (tokens or cost non-null). Used by
+    -- the cost preview to detect incomplete multi-round coverage (0 = legacy/unknown).
+    rounds_with_usage INTEGER NOT NULL DEFAULT 0,
+    PRIMARY KEY (run_id, role, name, provider, model, auth_mode)
+)
+"""
+
+
+# Bump when the table shapes change. The DB is a derived, rebuildable view, so an
+# OLDER on-disk schema is dropped + recreated (backfill repopulates from the
+# corpus) rather than ALTER-migrated. A NEWER on-disk schema is left untouched —
+# it may hold data this binary can't rebuild (e.g. PR-4's live token/cost).
+_SCHEMA_VERSION = 12
+
+
+def open_db(path: Path | str) -> sqlite3.Connection:
+    """Open the metrics DB, creating/rebuilding tables to the current schema.
+
+    Creates parent dirs + tables if absent; if the on-disk schema version is
+    stale (an older syncade wrote it), the derived tables are dropped and
+    recreated so a later ``upsert`` never hits a missing column.
+    """
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path))
+    conn.row_factory = sqlite3.Row
+    try:
+        if conn.execute("PRAGMA user_version").fetchone()[0] < _SCHEMA_VERSION:
+            # Older schema only: rebuild. A newer on-disk version is left as-is so an
+            # older binary never destroys data it cannot rebuild (see _SCHEMA_VERSION).
+            conn.executescript(
+                "DROP TABLE IF EXISTS runs; "
+                "DROP TABLE IF EXISTS reviewer_stats; "
+                "DROP TABLE IF EXISTS actor_stats;"
+            )
+            conn.execute(f"PRAGMA user_version = {_SCHEMA_VERSION}")  # int constant, not user input
+        conn.execute(_RUNS_DDL)
+        conn.execute(_REVIEWER_STATS_DDL)
+        conn.execute(_ACTOR_STATS_DDL)
+        conn.commit()
+    except Exception:
+        conn.close()
+        raise
+    return conn
+
+
+def _upsert(conn: sqlite3.Connection, table: str, row: object) -> None:
+    # ``table`` is a hardcoded literal and the column names come from our own
+    # dataclass fields (never user input); values are bound parameters. No
+    # injection surface.
+    data = dataclasses.asdict(row)
+    cols = ", ".join(data)
+    placeholders = ", ".join(f":{k}" for k in data)
+    conn.execute(f"INSERT OR REPLACE INTO {table} ({cols}) VALUES ({placeholders})", data)
+    conn.commit()
+
+
+def upsert_run(conn: sqlite3.Connection, row: RunRow) -> None:
+    _upsert(conn, "runs", row)
+
+
+def upsert_reviewer_stat(conn: sqlite3.Connection, row: ReviewerStatRow) -> None:
+    _upsert(conn, "reviewer_stats", row)
+
+
+def upsert_actor_stat(conn: sqlite3.Connection, row: ActorStatRow) -> None:
+    _upsert(conn, "actor_stats", row)
+
+
+def fetch_runs(conn: sqlite3.Connection) -> list[RunRow]:
+    """Return all run rows as :class:`RunRow`, ordered by ``run_id``."""
+    return [RunRow(**dict(r)) for r in conn.execute("SELECT * FROM runs ORDER BY run_id")]
+
+
+def fetch_actor_stats(conn: sqlite3.Connection) -> list[ActorStatRow]:
+    """Return all per-actor rows as :class:`ActorStatRow`, ordered by ``run_id``. Lets a
+    consumer separate the per-role cost of a run (e.g. reviewers + judge, which run every
+    round, from the producer, which runs only on NO-SHIP rounds)."""
+    return [
+        ActorStatRow(**dict(r)) for r in conn.execute("SELECT * FROM actor_stats ORDER BY run_id")
+    ]

syncade/orchestrator/__init__.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from ._runs_dir import _ensure_runs_gitignore as _ensure_runs_gitignore
+from .branch_advance import _advance_branch_ref as _advance_branch_ref
+from .escalation_coverage import (
+    escalation_covers_active_blockers as escalation_covers_active_blockers,
+)
+from .loop import run_review
+from .loop_finalize import _finalize_run as _finalize_run
+from .loop_resume import _rehydrate_resume_state as _rehydrate_resume_state
+from .loop_round_step import _RoundStep as _RoundStep
+from .loop_round_step import _run_round_step as _run_round_step
+from .prior_round import (
+    load_prior_reviewer_response_text as load_prior_reviewer_response_text,
+)
+from .producer_phase import _run_producer_phase as _run_producer_phase
+from .results import (
+    RoundArtifacts,
+    RoundResult,
+    RunArtifacts,
+    RunResult,
+)
+from .results import (
+    TerminationReason as TerminationReason,
+)
+from .results import (
+    TestSkipReason as TestSkipReason,
+)
+from .resume import (
+    ResumePlan as ResumePlan,
+)
+from .resume import (
+    check_tree_drift as check_tree_drift,
+)
+from .resume import (
+    load_completed_round as load_completed_round,
+)
+from .round import (
+    _NO_DIFF_SENTINEL as _NO_DIFF_SENTINEL,
+)
+from .round import (
+    _TEST_WORKTREE_NAME as _TEST_WORKTREE_NAME,
+)
+from .round import (
+    _run_one_round as _run_one_round,
+)
+from .round_checks import _run_checks_leg as _run_checks_leg
+from .verdict import (
+    _classify_phase_failure as _classify_phase_failure,
+)
+from .verdict import (
+    _compute_exit_code as _compute_exit_code,
+)
+
+__all__ = [
+    "RoundArtifacts",
+    "RoundResult",
+    "RunArtifacts",
+    "RunResult",
+    "run_review",
+]

syncade/orchestrator/_runs_dir.py

@@ -0,0 +1,24 @@
+"""Runs-directory provisioning helper.
+
+Writes the one-line ``.gitignore`` that drops a ``*`` rule alongside
+``.syncade/runs/`` on first run. Pure file I/O.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_RUNS_GITIGNORE_CONTENT: str = "*\n"
+
+
+def _ensure_runs_gitignore(runs_root: Path) -> None:
+    """Auto-write ``<repo>/.syncade/runs/.gitignore`` on first run.
+
+    Every run that creates a new ``.syncade/runs/`` directory drops a ``*``
+    .gitignore alongside so an accidental ``git add -A`` doesn't sweep run
+    artifacts into source control. Idempotent.
+    """
+    gitignore_path = runs_root / ".gitignore"
+    if gitignore_path.exists():
+        return
+    gitignore_path.write_text(_RUNS_GITIGNORE_CONTENT, encoding="utf-8")

syncade/orchestrator/branch_advance.py

@@ -0,0 +1,165 @@
+"""Branch-advance helper + status Literal.
+
+Holds the fast-forward ``git update-ref`` discipline that promotes the
+producer's detached-HEAD commit to the operator's named branch, plus the
+categorical ``BranchAdvanceStatus`` type the loop terminator switches on.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from syncade.logging import Logger
+from syncade.process import SubprocessError, SubprocessResult, run_subprocess
+from syncade.producer import ProducerResult
+from syncade.snapshot import Snapshot
+
+BranchAdvanceStatus = Literal[
+    "advanced",
+    "skipped_detached_head",
+    "non_descendant",
+    "update_ref_failed",
+]
+"""Outcome of :func:`_advance_branch_ref`.
+
+- ``advanced`` — branch ref was successfully fast-forwarded to the
+  producer's ending SHA. The loop can continue safely; the next
+  round's snapshot will pick up the new HEAD.
+- ``skipped_detached_head`` — the operator was on detached HEAD at
+  invocation; no named branch to advance. The producer's commits
+  are in ``.git`` but unreachable from any branch. The orchestrator
+  MUST terminate the loop: the next round's snapshot would read the
+  same starting SHA again, so reviewers could SHIP stale code.
+- ``non_descendant`` — the producer's ending SHA is NOT a
+  descendant of the starting SHA. The orchestrator MUST terminate the loop;
+  continuing would dispatch the next round against the original
+  starting SHA (since update-ref didn't fire), causing the
+  reviewers to see stale code and potentially declare SHIP.
+- ``update_ref_failed`` — ``git update-ref`` returned non-zero
+  (ref moved out from under us, permissions, etc.). The
+  orchestrator MUST terminate. Same stale-SHIP risk as
+  ``non_descendant``.
+"""
+
+_GIT_TIMEOUT_SECONDS = 30.0
+
+
+def _run_git(argv: list[str], *, cwd: Path, logger: Logger) -> SubprocessResult | None:
+    try:
+        return run_subprocess(argv, cwd=cwd, timeout=_GIT_TIMEOUT_SECONDS)
+    except SubprocessError as exc:
+        logger.safety(
+            f"orchestrator: git command {argv[:2]!r} failed before completion: {exc}. "
+            "The branch ref was not advanced. The loop will terminate as "
+            "producer_stalled to prevent the next round from dispatching reviewers "
+            "against stale code at the unadvanced ref."
+        )
+        return None
+
+
+def _advance_branch_ref(
+    *,
+    repo_root: Path,
+    snapshot: Snapshot,
+    producer_result: ProducerResult,
+    logger: Logger,
+) -> BranchAdvanceStatus:
+    """Fast-forward the operator's branch to the producer's ending SHA.
+
+    Runs ``git update-ref refs/heads/<branch> <ending_sha>
+    <starting_sha>`` from the repo root. Refuses to advance when
+    the ending SHA isn't a descendant of the starting SHA (the
+    producer did something unusual — ``git reset --hard
+    <unrelated>``, force-update, orphan branch checkout).
+
+    Returns a :data:`BranchAdvanceStatus` so the caller can fold
+    advance failure into the loop terminator. Without that status, the loop
+    could continue past advance failure and create a stale-SHIP risk (the next
+    round's snapshot would read the original branch SHA and dispatch reviewers
+    against stale
+    code).
+
+    For ``snapshot.branch is None`` (detached HEAD at invocation),
+    the orchestrator can't advance any named branch — emits a
+    warning and returns ``skipped_detached_head``. The caller treats
+    this as a terminal non-SHIP state so the next reviewers never
+    inspect stale input. The producer's commits are still in ``.git``
+    (worktrees share ``.git``), so the operator can manually advance
+    their branch via ``git log <producer-sha>`` + ``git update-ref``
+    if they want to keep the commits.
+    """
+    if snapshot.branch is None:
+        logger.safety(
+            f"orchestrator: producer committed {producer_result.ending_sha[:12]} "
+            f"on a detached HEAD; the operator was on detached HEAD at "
+            f"invocation, so no named branch ref to advance. The "
+            f"producer's commits are in .git — inspect with `git log "
+            f"{producer_result.ending_sha[:12]}` and manually advance "
+            f"the branch you want them on."
+        )
+        return "skipped_detached_head"
+
+    # Verify the ending SHA is a descendant of the starting SHA. If
+    # not, the producer did something unusual (reset, force-update,
+    # etc.) and we shouldn't blindly fast-forward — AND we shouldn't
+    # continue the loop, because the next round would see stale
+    # code at the original starting SHA.
+    # `--no-replace-objects` prevents a refs/replace/* ref on the producer's
+    # ending SHA from substituting a fake commit whose parent is starting_sha,
+    # which would make --is-ancestor return 0 for an actual non-descendant.
+    is_ancestor = _run_git(
+        [
+            "git",
+            "--no-replace-objects",
+            "merge-base",
+            "--is-ancestor",
+            producer_result.starting_sha,
+            producer_result.ending_sha,
+        ],
+        cwd=repo_root,
+        logger=logger,
+    )
+    if is_ancestor is None:
+        return "update_ref_failed"
+    if is_ancestor.returncode != 0:
+        logger.safety(
+            f"orchestrator: producer's ending SHA "
+            f"({producer_result.ending_sha[:12]}) is NOT a descendant "
+            f"of the round-start SHA ({producer_result.starting_sha[:12]}); "
+            f"refusing to fast-forward {snapshot.branch}. The "
+            f"producer may have done something unusual "
+            f"(git reset, force-update). The commits exist in .git "
+            f"under the producer's SHA — manual intervention required. "
+            f"The loop will terminate as producer_stalled (per loop policy "
+            f"brief: 'treats the round as a stall') to prevent the "
+            f"next round from dispatching reviewers against stale "
+            f"code at the unadvanced ref."
+        )
+        return "non_descendant"
+
+    update = _run_git(
+        [
+            "git",
+            "update-ref",
+            f"refs/heads/{snapshot.branch}",
+            producer_result.ending_sha,
+            producer_result.starting_sha,  # OLDVALUE — fail if ref moved out from under us
+        ],
+        cwd=repo_root,
+        logger=logger,
+    )
+    if update is None:
+        return "update_ref_failed"
+    if update.returncode != 0:
+        logger.safety(
+            f"orchestrator: git update-ref refs/heads/{snapshot.branch} "
+            f"failed: {update.stderr.strip()[:200]!r}. The producer's "
+            f"commits are in .git but the branch ref wasn't advanced. "
+            f"The loop will terminate as producer_stalled to prevent "
+            f"the next round from dispatching reviewers against stale "
+            f"code at the unadvanced ref."
+        )
+        return "update_ref_failed"
+
+    return "advanced"

syncade/orchestrator/branch_guard.py

@@ -0,0 +1,98 @@
+"""Refuse to run the committing loop on the repo's default branch (PR-v2-26).
+
+The producer fast-forwards the CURRENT branch. With no guard, a stranger's first
+`syncade <brief>` run while sitting on `main` silently lands producer commits on
+their default branch — reproduced: 7 commits on `main`, warned only after they had
+landed. This guard refuses that up front, before any subprocess is dispatched.
+
+Enforced at the run-entry choke (:func:`syncade.orchestrator.run_review`), not the
+CLI wrapper, so a direct library call and a `--resume` are covered too — the same
+"guard where the work happens, not where the CLI happens" lesson as the PR-v2-24
+auth gate.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from syncade.base_resolution import local_default_branch, remote_default_branch
+from syncade.worktree import WorktreeError
+
+# Branch names that conventionally ARE a repo's integration branch. Consulted only in the
+# remote-less path: a repo that HAS a local main/master but is checked out on one of these
+# (e.g. `trunk` beside a vestigial `main`) is refused, because HEAD may be the real default
+# even though it is not the local main/master.
+_COMMON_DEFAULT_NAMES = frozenset({"main", "master", "trunk", "develop", "development", "default"})
+
+
+def current_branch_name(repo_root: Path) -> str | None:
+    """The checked-out branch name, or ``None`` for detached HEAD.
+
+    Lets the CLI run :func:`guard_default_branch` before dispatching; ``run_review``
+    re-checks for library callers. Under D1(c) (PR-h-02d.5), baseless loop runs refuse
+    here before auth; based/scoped runs defer to ``run_review`` and auth runs first.
+    """
+    result = subprocess.run(
+        ["git", "-C", str(repo_root), "symbolic-ref", "--quiet", "--short", "HEAD"],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip() or None
+
+
+def guard_default_branch(
+    repo_root: Path,
+    current_branch: str | None,
+    *,
+    allow: bool,
+    will_commit: bool,
+) -> None:
+    """Raise :class:`WorktreeError` when a *committing* run could land on the default branch.
+
+    Exempt (no raise): ``will_commit`` is False (single-pass commits nothing), ``allow`` is
+    True (``--allow-default-branch`` — or a repo syncade itself just auto-created), or
+    ``current_branch`` is None (detached HEAD).
+
+    Resolution, most authoritative first:
+
+    1. ``origin/HEAD`` present → refuse iff HEAD *is* that branch, whatever it is named;
+       otherwise allow. A remote proves the default exactly.
+    2. No remote, but a local ``main`` / ``master`` exists → treat it as the default: refuse
+       iff HEAD is it, OR HEAD is another common integration name
+       (:data:`_COMMON_DEFAULT_NAMES`, e.g. ``trunk`` beside a vestigial ``main``). A plain
+       feature branch alongside ``main`` proceeds.
+    3. No remote AND no local ``main`` / ``master`` → HEAD is effectively this repo's only
+       integration branch (a repo living on ``release`` / ``trunk`` with nothing else), so
+       refuse.
+
+    The fresh-dir auto-init is exempted upstream via ``allow`` so onboarding still works.
+    """
+    if not will_commit or allow or current_branch is None:
+        return
+
+    remote_default = remote_default_branch(repo_root)
+    if remote_default is not None:
+        if current_branch == remote_default:
+            raise WorktreeError(
+                f"refusing: HEAD is the default branch {current_branch!r}, and loop mode "
+                f"would fast-forward producer commits onto it. Re-run on a feature branch, "
+                f"or pass --allow-default-branch to commit there deliberately."
+            )
+        return
+
+    local_default = local_default_branch(repo_root)
+    if local_default is None:
+        raise WorktreeError(
+            f"refusing: HEAD is {current_branch!r}, and with no origin/HEAD and no local "
+            f"main/master there is nothing to prove it is not this repo's default branch, so "
+            f"producer commits could land there. Set origin/HEAD "
+            f"(git remote set-head origin <branch>), or pass --allow-default-branch."
+        )
+    if current_branch == local_default or current_branch in _COMMON_DEFAULT_NAMES:
+        raise WorktreeError(
+            f"refusing: HEAD ({current_branch!r}) looks like this repo's default/integration "
+            f"branch (local default is {local_default!r}; no origin/HEAD to prove otherwise), "
+            f"so producer commits could land there. Re-run on a feature branch, or pass "
+            f"--allow-default-branch to commit here deliberately."
+        )

syncade/orchestrator/budget.py

@@ -0,0 +1,107 @@
+"""Per-run budget accounting (PR-v2-11): sum actor usage, decide when a ceiling is hit.
+
+A leaf: every import is type-only, and nothing here constructs a ``Usage`` or reads config
+beyond two attributes, so it cannot form an import cycle with ``results`` / ``config_loop``.
+The loop owns the running tally and calls :func:`over_budget` at each phase boundary.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from syncade.config_loop import LoopConfig
+    from syncade.orchestrator.results import RoundResult
+    from syncade.usage import Usage
+
+
+def review_usages(round_result: RoundResult) -> list[Usage]:
+    """Usages from the actors that run BEFORE the producer this round: each reviewer + the
+    judge. The pre-producer budget check sums these so reviewers that already blew the ceiling
+    don't also trigger the expensive producer leg. Test/check legs spawn no model."""
+    usages = [r.usage for r in round_result.dispatch_result.results if r.usage is not None]
+    synth = round_result.synth_result
+    if synth is not None and synth.usage is not None:
+        usages.append(synth.usage)
+    return usages
+
+
+def round_usages(round_result: RoundResult) -> list[Usage]:
+    """Every model-actor Usage a round produced: reviewers + judge + producer. The full
+    per-round contribution the loop accumulates into the run tally."""
+    usages = review_usages(round_result)
+    producer = round_result.producer_result
+    if producer is not None and producer.usage is not None:
+        usages.append(producer.usage)
+    return usages
+
+
+def producer_only_usages(round_result: RoundResult) -> list[Usage]:
+    """Only the producer Usage from a round.
+
+    Used when resuming a budget-aborted-before-producer run: the review bundle
+    was paid for in the prior process and must not count against the fresh tally.
+    """
+    producer = round_result.producer_result
+    if producer is not None and producer.usage is not None:
+        return [producer.usage]
+    return []
+
+
+#: Fraction of a configured ceiling at which the loop warns, so an operator watching a long
+#: run sees the stop coming while a round is still left to react in. Advisory only — it never
+#: changes a verdict or an exit code.
+BUDGET_WARN_FRACTION = 0.8
+
+
+def approaching_budget(usages: list[Usage], loop: LoopConfig) -> str | None:
+    """The ceiling the running tally is APPROACHING, or ``None``.
+
+    Fires in the band ``[fraction x ceiling, ceiling)`` — at or past the warning line but still
+    under the ceiling — so it always precedes :func:`over_budget` rather than racing it. The
+    caller checks this only when ``over_budget`` returned None, so the two can never both speak
+    about the same boundary.
+
+    This matters more since the ceiling gained a DEFAULT (PR-h-field-06): without a warning the
+    first thing most operators would learn about `budget_tokens` is a run stopping.
+
+    An earlier attempt at this (abandoned on a branch, never merged) compared
+    ``tally >= ceiling / FRACTION`` — i.e. 125% of the ceiling, which ``over_budget`` has
+    already aborted at. It could never fire. Pinned below by a test that asserts the warning
+    band lies BELOW the abort, not merely that some tally warns.
+    """
+    if loop.budget_tokens:
+        tokens = sum(u.total_tokens for u in usages)
+        if tokens >= loop.budget_tokens * BUDGET_WARN_FRACTION:
+            return "budget_tokens"
+    if loop.budget_usd:
+        cost = sum(u.cost_usd for u in usages if u.cost_usd is not None)
+        if cost >= loop.budget_usd * BUDGET_WARN_FRACTION:
+            return "budget_usd"
+    return None
+
+
+def over_budget(usages: list[Usage], loop: LoopConfig) -> str | None:
+    """The ceiling the running tally has crossed, or ``None`` (also ``None`` when no ceiling is
+    active — ``budget_tokens = 0`` is the opt-out sentinel, and ``budget_usd`` defaults unset).
+
+    Tokens are the TIGHTEST bound: ``usages`` holds only actors whose usage was recorded (the
+    norm), so ``total_tokens`` is exact in the normal case and a lower bound only when an actor
+    reported no usage at all (a provider envelope with no usage block — rare). The dollar tally
+    is looser still: it sums only KNOWN ``cost_usd``, so an actor WITH usage but unpriceable cost
+    contributes nothing to it (a LOWER BOUND — the honest limit named in the config/help; use
+    ``budget_tokens`` for the hardest cap). Compares ``>=``: at the ceiling, the next phase
+    would spend past it, so stop. Tokens are checked first; returns ``"budget_tokens"`` /
+    ``"budget_usd"`` naming the crossed ceiling.
+    """
+    # 0 is the explicit opt-out, not a ceiling of zero (PR-h-field-06): with a DEFAULT
+    # ceiling in place an omitted TOML key can no longer mean "unlimited", so a sentinel is
+    # the only way left to say it.
+    if loop.budget_tokens:
+        if sum(u.total_tokens for u in usages) >= loop.budget_tokens:
+            return "budget_tokens"
+    if loop.budget_usd:
+        cost = sum(u.cost_usd for u in usages if u.cost_usd is not None)
+        if cost >= loop.budget_usd:
+            return "budget_usd"
+    return None