Official Codebase of 3DCodeVerse
Python
orchestrator/ becomes orchestrator.py: seven files nobody imported as a package
gaoypengfbce0c9e8a9e
diff --git a/harness/codeverse/cli/_common.py b/harness/codeverse/cli/_common.pyindex 905a7cab..0d373991 100644--- a/harness/codeverse/cli/_common.py+++ b/harness/codeverse/cli/_common.py@@ -222,7 +222,7 @@ def round_policy_options(spec: Spec, settings: Any | None = None) -> dict[str, Areturn {}from dataclasses import replace- from codeverse.orchestrator.rounds import RoundPolicy+ from codeverse.orchestrator import RoundPolicypolicy = RoundPolicy(max_rounds=spec.budget.max_rounds, judge_samples=samples)threshold = rubric_threshold(spec)diff --git a/harness/codeverse/cli/main.py b/harness/codeverse/cli/main.pyindex fc7d6e59..cd190b84 100644--- a/harness/codeverse/cli/main.py+++ b/harness/codeverse/cli/main.py@@ -367,7 +367,7 @@ def _finished_reason(ws, raised: dict) -> str:how you continue one — so it only blocks when no cap was raised."""from codeverse.contracts.run import RunStatus- from codeverse.orchestrator.state import RunState, StateCorrupt+ from codeverse.orchestrator import RunState, StateCorrupttry:state = RunState.load(ws)diff --git a/harness/codeverse/orchestrator.py b/harness/codeverse/orchestrator.pynew file mode 100644index 00000000..5d9e524c--- /dev/null+++ b/harness/codeverse/orchestrator.py@@ -0,0 +1,1140 @@+"""Orchestration: the stage runner with resume, run state, the round loop+(RoundPolicy / StopPolicy / BestSelector), refine-task compilation and the budget.++One module since 2026-08-28: the seven-file package predates the 1,500-line cap,+nobody ever imported the package itself, and refine_tasks existed only to be+re-exported by rounds. candidates.py moved into tracks/candidates.py earlier.+"""++from __future__ import annotations++import hashlib+import json+import logging+import re+import threading+import time+from collections.abc import Callable, Sequence+from dataclasses import dataclass, replace+from datetime import UTC, datetime+from pathlib import Path+from typing import Any, Literal, TypeVar++from pydantic import BaseModel, Field, ValidationError++from codeverse.contracts.artifacts import GateReport+from codeverse.contracts.common import Budget, Usage+from codeverse.contracts.judgment import Judgment+from codeverse.contracts.plan import AcceptanceItem, Plan+from codeverse.contracts.run import RoundRecord, RunStatus+from codeverse.conventions import to_snake+from codeverse.cost.billing import bills_usd+from codeverse.events import EventLog+from codeverse.workspace import Workspace++log = logging.getLogger(__name__)+++# ===================================================================== state+# (merged from codeverse/orchestrator/state.py, 2026-08-28)+class StageState(BaseModel):+ """One completed stage: inputs hash + where its result JSON lives."""++ name: str+ inputs_hash: str+ result_path: str = ""+ finished_at: datetime = Field(default_factory=lambda: datetime.now(UTC))+ duration_s: float = 0.0+++class RunState(BaseModel):+ """Everything the orchestrator needs to resume a run."""++ status: RunStatus = RunStatus.PLANNING+ stages: dict[str, StageState] = Field(default_factory=dict)+ current_round: int = Field(default=0, description="index of the round in progress / next to run")+ completed_rounds: list[int] = Field(default_factory=list)+ round_commits: dict[int, str] = Field(default_factory=dict)+ best_round: int | None = None+ best_commit: str = ""+ best_score: float | None = None+ #: highest round index that has been THROUGH best selection (choose_best_round,+ #: including its paid pairwise comparison). Persisted so a resume can tell+ #: "the best was deliberately kept" from "this round was never considered" —+ #: without it, a state that merely LOOKS consistent with the journal kept a+ #: stale best and delivered the worse round (2026-08-27). -1 = nothing yet.+ best_considered_through: int = -1+ materialized_for: str = Field(default="", description="agent kind the workspace was materialised for")+ stop_reason: str = ""+ error: str = ""+ started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))+ updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))+ extra: dict[str, Any] = Field(default_factory=dict)++ # ----------------------------------------------------------------- persistence+ @classmethod+ def load(cls, ws: Workspace) -> RunState | None:+ """Return the saved state or ``None`` when the file is absent."""+ if not ws.state_path.is_file():+ return None+ try:+ return cls.model_validate(ws.read_json(ws.state_path))+ except (ValidationError, ValueError) as e:+ raise StateCorrupt(f"{ws.state_path}: {e}") from e++ @classmethod+ def load_or_new(cls, ws: Workspace, *, resume: bool) -> RunState:+ if resume:+ st = cls.load(ws)+ if st is not None:+ return st+ return cls()++ def save(self, ws: Workspace) -> None:+ self.updated_at = datetime.now(UTC)+ ws.write_json(ws.state_path, self)++ # ----------------------------------------------------------------- helpers+ def mark_round_done(self, index: int, commit: str, ws: Workspace | None = None) -> None:+ if index not in self.completed_rounds:+ self.completed_rounds.append(index)+ self.round_commits[index] = commit+ self.current_round = index + 1+ if ws is not None:+ self.save(ws)++ def update_best(self, index: int, commit: str, score: float | None) -> bool:+ """Record ``index`` as best; returns True when it changed."""+ changed = self.best_round != index+ self.best_round, self.best_commit, self.best_score = index, commit, score+ return changed+++class StateCorrupt(RuntimeError):+ """``run_state.json`` exists but does not validate — refuse to guess."""+++# ===================================================================== runner+# (merged from codeverse/orchestrator/runner.py, 2026-08-28)+log = logging.getLogger(__name__)++T = TypeVar("T")++_SAFE = re.compile(r"[^0-9A-Za-z._-]+")+++def hash_inputs(inputs: Any) -> str:+ """Stable sha256 (12 hex) of arbitrary JSON-able inputs (pydantic ok)."""+ payload = _jsonable(inputs)+ blob = json.dumps(payload, sort_keys=True, default=str, ensure_ascii=False)+ return hashlib.sha256(blob.encode()).hexdigest()[:12]+++def _jsonable(obj: Any) -> Any:+ if isinstance(obj, BaseModel):+ return obj.model_dump(mode="json")+ if isinstance(obj, Path):+ return str(obj)+ if isinstance(obj, dict):+ return {str(k): _jsonable(v) for k, v in obj.items()}+ if isinstance(obj, (list, tuple, set)):+ return [_jsonable(v) for v in obj]+ return obj+++class StageRunner:+ """Runs stages with resume semantics on top of ``RunState`` + ``EventLog``."""++ def __init__(self, ws: Workspace, events: EventLog, state: RunState | None = None):+ self.ws = ws+ self.events = events+ self.state = state if state is not None else RunState()++ # ----------------------------------------------------------------- paths+ def result_path(self, name: str) -> Path:+ return self.ws.root / "stages" / f"{_SAFE.sub('_', name)}.json"++ # ----------------------------------------------------------------- api+ def stage(+ self,+ name: str,+ fn: Callable[[], T],+ *,+ inputs: Any = "",+ force: bool = False,+ model: type[BaseModel] | None = None,+ list_of: type[BaseModel] | None = None,+ ) -> T:+ """Run ``fn`` unless a cached result for the same ``inputs`` exists."""+ h = hash_inputs(inputs)+ path = self.result_path(name)+ prior = self.state.stages.get(name)+ if not force and prior is not None and prior.inputs_hash == h and path.is_file():+ # A cached result that cannot be read back is a cache MISS, not a dead run.+ # ``inputs_hash`` covers the INPUTS only, never the result model's schema, so a+ # contract that gained a field invalidates nothing — and a clobbered file+ # invalidates nothing either. Both used to escape as ValidationError /+ # JSONDecodeError through BaseTrack.run, which marks the run FAILED and+ # re-raises, so every later `3dcv resume <slug>` died the same way with no way+ # out (there is no flag to drop a cached stage). Re-run instead and+ # overwrite the file — the same tolerance load_ledger and _read_jsonl apply.+ try:+ result = _revive(json.loads(path.read_text()), model, list_of)+ except (OSError, ValueError) as e: # ValidationError is a ValueError+ self.events.emit("stage.cache_invalid", stage=name, inputs_hash=h, path=str(path),+ error=f"{type(e).__name__}: {e}")+ log.warning("stage %s: cached result at %s is unusable (%s); re-running", name, path, e)+ else:+ self.events.emit("stage.cached", stage=name, inputs_hash=h, path=str(path))+ return result # type: ignore[return-value]++ self.events.emit("stage.start", stage=name, inputs_hash=h)+ t0 = time.time()+ try:+ result = fn()+ except Exception as e:+ self.events.emit("stage.failed", stage=name, error=f"{type(e).__name__}: {e}",+ duration_s=round(time.time() - t0, 2))+ raise+ dt = time.time() - t0+ path.parent.mkdir(parents=True, exist_ok=True)+ self.ws.write_json(path, {"stage": name, "inputs_hash": h, "result": _jsonable(result)})+ self.state.stages[name] = StageState(name=name, inputs_hash=h, result_path=str(path), duration_s=dt)+ self.state.save(self.ws)+ self.events.emit("stage.done", stage=name, inputs_hash=h, duration_s=round(dt, 2))+ return result++ def is_done(self, name: str, inputs: Any = "") -> bool:+ prior = self.state.stages.get(name)+ return prior is not None and prior.inputs_hash == hash_inputs(inputs) and self.result_path(name).is_file()+++def _revive(data: dict[str, Any], model: type[BaseModel] | None, list_of: type[BaseModel] | None) -> Any:+ result = data.get("result")+ if model is not None and isinstance(result, dict):+ return model.model_validate(result)+ if list_of is not None and isinstance(result, list):+ return [list_of.model_validate(r) for r in result]+ return result+++# ===================================================================== refine_tasks+# (merged from codeverse/orchestrator/refine_tasks.py, 2026-08-28)+log = logging.getLogger(__name__)+++class RefineTask(BaseModel):+ """One targeted change request compiled for the next round."""++ target: str = Field(description="part / zone / asset / joint / camera / 'overall'")+ kind: str = Field(description="geometry | assembly | material | articulation | bug | acceptance | ...")+ instruction: str+ priority: int = Field(ge=0, le=9, description="0 = gate error, 1 = failed must item, 2+ = judge")+ files: list[str] = Field(default_factory=list, description="files this task may edit ([] = unknown/whole)")+ source: Literal["gate", "acceptance", "judge"] = "judge"++ def line(self) -> str:+ files = f" (files: {', '.join(self.files)})" if self.files else ""+ return f"[{self.source}/{self.kind}] {self.target}: {self.instruction}{files}"+++class TaskGroup(BaseModel):+ """Tasks that must run together (they touch the same files)."""++ tasks: list[RefineTask]+ files: list[str] = Field(default_factory=list)++ @property+ def targets(self) -> list[str]:+ seen: list[str] = []+ for t in self.tasks:+ if t.target not in seen:+ seen.append(t.target)+ return seen++ @property+ def label(self) -> str:+ return "+".join(to_snake(t) for t in self.targets[:3]) or "refine"+++FileForTarget = Callable[[str], list[str]]+++def build_refine_instructions(+ judgment: Judgment | None,+ gates: Sequence[GateReport],+ acceptance_failures: Sequence[AcceptanceItem],+ plan: Plan | None,+ *,+ file_for_target: FileForTarget | None = None,+ max_tasks: int = 6,+ extra: Sequence[RefineTask] = (),+) -> list[RefineTask]:+ """Gate ERRORS first (with fix hints), then ``extra`` harness-derived tasks+ (e.g. reference-silhouette mismatch), then failed *must* acceptance items,+ then the judge's improvement plan; de-duplicated by (target, kind), capped.+ Gate/acceptance/extra tasks are never dropped by the cap unless they alone exceed it."""+ known = _known_targets(plan)+ tasks: list[RefineTask] = []+ seen: set[tuple[str, str]] = set()++ def _add(t: RefineTask) -> None:+ key = (to_snake(t.target), t.kind)+ if key in seen:+ return+ seen.add(key)+ t.target = _canon_target(t.target, known)+ if file_for_target is not None and not t.files:+ t.files = list(file_for_target(t.target))+ tasks.append(t)++ for g in gates:+ for f in g.errors:+ _add(RefineTask(target=f.target or "overall", kind=f"gate:{g.gate}", instruction=f.as_line(),+ priority=0, source="gate"))+ for t in extra:+ _add(t.model_copy())+ for a in acceptance_failures:+ if a.priority != "must":+ continue+ _add(RefineTask(target=_acceptance_target(a, known), kind="acceptance",+ instruction=f"Acceptance item {a.id} NOT met: {a.text}", priority=1,+ source="acceptance"))+ if judgment is not None:+ for item in sorted(judgment.improvement_plan, key=lambda i: (i.priority, -i.expected_gain)):+ _add(RefineTask(target=item.target or "overall", kind=item.kind, instruction=item.instruction,+ priority=min(9, 1 + item.priority), source="judge"))+ tasks.sort(key=lambda t: t.priority)+ if len(tasks) > max_tasks:+ protected = [t for t in tasks if t.source != "judge"]+ rest = [t for t in tasks if t.source == "judge"]+ tasks = (protected + rest)[:max(max_tasks, len(protected))]+ return tasks+++def plan_parallel_groups(tasks: Sequence[RefineTask]) -> list[TaskGroup]:+ """Group tasks by file ownership. Tasks with unknown files (``[]``) cannot+ be isolated, so if any exists everything collapses into ONE group (a single+ whole-object task). Otherwise groups are the connected components of the+ "shares a file" relation — each group may run concurrently with the others."""+ if not tasks:+ return []+ if any(not t.files for t in tasks):+ files = sorted({f for t in tasks for f in t.files})+ return [TaskGroup(tasks=list(tasks), files=files)]+ parent = list(range(len(tasks)))++ def find(i: int) -> int:+ while parent[i] != i:+ parent[i] = parent[parent[i]]+ i = parent[i]+ return i++ owner: dict[str, int] = {}+ for i, t in enumerate(tasks):+ for f in t.files:+ if f in owner:+ parent[find(i)] = find(owner[f])+ else:+ owner[f] = i+ groups: dict[int, list[RefineTask]] = {}+ for i, t in enumerate(tasks):+ groups.setdefault(find(i), []).append(t)+ out = []+ for members in groups.values():+ files = sorted({f for t in members for f in t.files})+ out.append(TaskGroup(tasks=members, files=files))+ out.sort(key=lambda g: min(t.priority for t in g.tasks))+ return out+++def plan_refine_groups(+ tasks: Sequence[RefineTask],+ *,+ allow_fanout: bool = True,+ parallel_min_tasks: int = 2,+) -> tuple[list[TaskGroup], bool]:+ """The ONE grouping rule of the refine scaffold (``BaseTrack.refine_tasks``).++ Groups by file ownership via :func:`plan_parallel_groups`; the groups run in+ parallel only when fan-out is allowed for the track, at least+ ``parallel_min_tasks`` file-disjoint groups exist and every group owns+ files. Otherwise everything collapses into ONE whole-artifact group."""+ groups = plan_parallel_groups(tasks)+ parallel = allow_fanout and len(groups) >= parallel_min_tasks and all(g.files for g in groups)+ if not parallel:+ groups = [TaskGroup(tasks=list(tasks), files=sorted({f for t in tasks for f in t.files}))]+ return groups, parallel+++def compact_instructions(tasks: Sequence[RefineTask], max_lines: int = 6) -> list[str]:+ """The instruction lines handed to ONE generation task: grouped by target+ (instances ``Leg_0``/``Leg_1`` fold into ``Leg``), ordered by priority, capped+ at ``max_lines``. A flash-class agent given 12 near-identical connectivity+ errors fixes none; given "FrontLeg: (a) … (b) …" it fixes the part."""+ if not tasks:+ return []+ groups: dict[str, list[RefineTask]] = {}+ for t in sorted(tasks, key=lambda t: t.priority):+ groups.setdefault(_instance_base(t.target), []).append(t)+ lines: list[str] = []+ for target, members in groups.items():+ if len(members) == 1:+ lines.append(members[0].line())+ continue+ bits = []+ for i, t in enumerate(members):+ who = f" [{t.target}]" if t.target != target else ""+ bits.append(f"({chr(97 + i % 26)}){who} [{t.source}/{t.kind}] {t.instruction}")+ files = sorted({f for t in members for f in t.files})+ tail = f" (files: {', '.join(files)})" if files else ""+ lines.append(f"{target}: " + "; ".join(bits) + tail)+ if len(lines) > max_lines:+ dropped = len(lines) - max_lines+ lines = lines[:max_lines]+ log.info("compact_instructions: %d target group(s) deferred to a later round", dropped)+ return lines+++# ----------------------------------------------------------------------------- helpers+def _split_instance(target: str) -> tuple[str, str]:+ """``BackLeg_1`` → (``BackLeg``, ``1``) per the ``Name_0..N-1`` instance naming+ convention; anything else → (target, "")."""+ base, sep, suffix = (target or "").rpartition("_")+ if sep and base and suffix.isdigit():+ return base, suffix+ return target or "overall", ""+++def _instance_base(target: str) -> str:+ return _split_instance(target)[0]+++def _known_targets(plan: Plan | None) -> dict[str, str]:+ """snake → canonical name for every part/zone/asset/joint/camera in the plan."""+ names: dict[str, str] = {}+ if plan is None:+ return names+ for attr in ("parts", "joints", "zones", "assets", "cameras", "effects"):+ for item in getattr(plan, attr, None) or []:+ names[to_snake(item.name)] = item.name+ return names+++def _canon_target(target: str, known: dict[str, str]) -> str:+ """Plan name for ``target``; instance suffixes (``Leg_1``, ``leg.2``) keep the+ suffix but take the plan's spelling of the base name."""+ hit = known.get(to_snake(target))+ if hit is not None:+ return hit+ base, suffix = _split_instance(target)+ if suffix and to_snake(base) in known:+ return f"{known[to_snake(base)]}_{suffix}"+ snake = to_snake(target)+ if snake.endswith("s") and snake[:-1] in known: # judges say "Legs" for the plan's "Leg"+ return known[snake[:-1]]+ return target+++def _acceptance_target(item: AcceptanceItem, known: dict[str, str]) -> str:+ """Route a failed acceptance item to the part it names, else 'overall'."""+ words = item.text.lower()+ for snake, name in known.items():+ if snake.replace("_", " ") in words or snake in words:+ return name+ return "overall"+++# ===================================================================== rounds+# (merged from codeverse/orchestrator/rounds.py, 2026-08-28)+StopReason = Literal["pass", "plateau", "budget", "continue", "max_rounds", "judge_unavailable",+ "regression", "diminishing_returns"]++#: what the next round should look like when the loop continues+Strategy = Literal["same", "switch", "detail"]++#: ``RoundRecord.kind`` of a round that already changed strategy after a regression+REWRITE_KIND = "rewrite"+#: ``RoundRecord.kind`` of the surface-detail round (see :func:`detail_round_due`)+DETAIL_KIND = "detail"++#: ``Strategy`` → the ``RoundRecord.kind`` the loop stamps on the round it starts+KIND_FOR_STRATEGY: dict[str, str] = {"same": "refine", "switch": REWRITE_KIND, "detail": DETAIL_KIND}+++def kind_for_strategy(strategy: str) -> str:+ """THE mapping from a stop decision's strategy to the round kind it produces."""+ return KIND_FOR_STRATEGY.get(strategy, "refine")++#: σ for a judge that is not in the measured table: the default judge's+#: (``gemini-3.1-pro-preview``, ``Settings.default_judge``), because that is what+#: an unnamed judge almost always is. Calibrate a new judge+#: (``python -m codeverse.judges.calibration``) and add it to JUDGE_NOISE rather+#: than tuning the multipliers around it.+DEFAULT_JUDGE_SIGMA = 0.030+++def judge_sigma(judge_model: str = "", *, default: float = DEFAULT_JUDGE_SIGMA) -> float:+ """Measured score noise (std) of one judge model.++ The numbers come from ``judges/calibration.py`` (n=3 on the e2e rounds) and+ are tabulated ONCE in :data:`codeverse.cost.routing.JUDGE_NOISE`; this is+ the only reader in the orchestrator. Accepts a bare model name or a full+ backend id (``gemini:gemini-3.1-pro-preview``)."""+ name = (judge_model or "").strip().split(":")[-1]+ if not name:+ return default+ try:+ from codeverse.cost.routing import JUDGE_NOISE+ except Exception as e: # noqa: BLE001 — the cost package is optional at import time+ log.debug("judge noise table unavailable: %s", e)+ return default+ hit = JUDGE_NOISE.get(name)+ if hit is None: # version suffixes: gemini-3.7-flash-002 → gemini-3.7-flash+ hit = next((v for k, v in JUDGE_NOISE.items() if name.startswith(k)), None)+ return float(hit[0]) if hit else default+++@dataclass(frozen=True)+class RoundPolicy:+ """Calibrated knobs for the refine loop."""++ max_rounds: int = 4 # refine rounds AFTER the baseline+ plateau_window: int = 2 # consecutive scored rounds without min_delta gain+ min_delta: float = 0.02+ target: float = 0.8 # rubric pass threshold (overridden from the rubric when known)+ judge_on_gate_errors: bool = True # still judge when gates (not build) fail+ max_refine_tasks: int = 6+ max_instructions_per_task: int = 6 # lines handed to ONE generation task (grouped by target)+ parallel_min_tasks: int = 2 # fan out only when >= this many file-disjoint groups+ n_candidates: int = 1 # best-of-N baseline (candidates generated in parallel, best kept)+ pairwise_margin: float = 0.03 # |Δscore| below this = judge noise → pairwise tie-break+ pairwise_min_confidence: float = 0.6 # new round replaces best only when pairwise is this sure+ judge_samples: int = 1 # VLM judge samples per round (flash: std ≈ 0.001 between samples → 1 is enough)+ # ---- money stops (docs/COST.md §5); thresholds are multiples of the judge's measured σ+ judge_model: str = "" # judge backend id → σ via judge_sigma(); "" = the default judge's σ+ regression_sigma: float = 1.0 # a round below (best − this × σ) regressed: change shape or stop+ regression_allow_switch: bool = True # False = a regression stops the run outright+ marginal_sigma: float = 1.5 # from marginal_from_round on, the last gain must beat this × σ+ marginal_from_round: int = 3 # first refine round index the marginal-value test applies to+ # ---- agent session shape. A 28-turn cap was TESTED AND REJECTED: a controlled+ # A/B on one prompt (n=3 per arm, same generator/judge/budget) cost $1.381 mean at+ # 0.479 mean score capped, against $1.360 at 0.684 uncapped — no saving and −0.205+ # score (docs/COST.md §17). 0 = no policy cap: the session runs under the backend's+ # own AgentJob.max_turns. Callers who want one set it explicitly (cost profiles do).+ agent_max_turns: int = 0 # model turns one generation session may take (0 = uncapped)+ agent_wrapup_turns: int = 6 # turns granted to land a final build + summary when a cap IS set+ # ---- depth. Measured (wave "generation-depth"): across 88 consecutive refine-round pairs the+ # built part count changed ZERO times and mean Δgeometry_detail was +0.003 — the refine loop is+ # a repair loop and never adds anything. The rounds that DID add geometry did it while assembly+ # was still broken and lost 0.075 of assembly_fit / 0.025 of overall for it. So detail gets its+ # own round, and it only runs once the structure gates are clean.+ detail_rounds: int = 0 # surface-detail rounds a run may spend (0 = off; tracks that implement+ # the round opt in — see lifecycle.BaseTrack.supports_detail_round)+ detail_min_score: float = 0.45 # below this the object is still wrong; detail would be polish on a mistake+ detail_bbox_tol_m: float = 0.005 # a detail round that moves a part box by more than this failed its brief++ def with_candidates(self, n: int | None) -> RoundPolicy:+ """Copy with ``n_candidates`` set (``None`` → unchanged)."""+ if n is None or n == self.n_candidates:+ return self+ return replace(self, n_candidates=max(1, int(n)))++ def with_judge(self, judge_model: str | None) -> RoundPolicy:+ """Copy that knows which judge scores the rounds (its σ sizes both money stops)."""+ if not judge_model or judge_model == self.judge_model:+ return self+ return replace(self, judge_model=judge_model)++ @property+ def sigma(self) -> float:+ """Measured judge noise for this run's judge (see :func:`judge_sigma`)."""+ return judge_sigma(self.judge_model)++ @property+ def regression_delta(self) -> float:+ """How far below the best a round must score to count as a regression."""+ return self.regression_sigma * self.sigma++ @property+ def marginal_delta(self) -> float:+ """Gain the previous round must have produced for r03+ to be worth starting."""+ return self.marginal_sigma * self.sigma+++def meaningful_regression(score: float | None, before: float | None, policy: RoundPolicy) -> bool:+ """Did ``score`` fall below ``before`` by MORE than this judge's own noise?++ THE regression predicate: ``StopPolicy._regression`` (the stop gate) and+ ``StopPolicy._regressions`` (the counter behind "a second regression stops+ the run") both call it, so they cannot drift apart. The scale is the+ measured per-judge sigma table via ``policy.regression_delta`` — deliberately+ NOT the 0.202 A/A replay floor, which measures cross-run planner variance,+ not judge noise."""+ if score is None or before is None:+ return False+ return (before - score) > policy.regression_delta+++@dataclass(frozen=True)+class StopDecision:+ """``StopPolicy``'s answer: stop (and why), or continue (and in what shape)."""++ reason: StopReason+ strategy: Strategy = "same"+ detail: str = ""++ @property+ def stop(self) -> bool:+ return self.reason != "continue"++ def event(self) -> dict[str, object]:+ return {"reason": self.reason, "strategy": self.strategy, "detail": self.detail}+++class StopPolicy:+ """Decide whether the loop goes on. ``history`` = rounds so far (baseline first)."""++ def __init__(self, policy: RoundPolicy):+ self.policy = policy++ def decide(self, history: Sequence[RoundRecord], *, budget_ok: bool = True) -> StopReason:+ """The stop reason only (``evaluate`` also says what shape the next round takes)."""+ return self.evaluate(history, budget_ok=budget_ok).reason++ def evaluate(self, history: Sequence[RoundRecord], *, budget_ok: bool = True) -> StopDecision:+ if not budget_ok:+ return StopDecision("budget")+ if not history:+ return StopDecision("continue")+ last = history[-1]+ if last.judgment is not None and last.judgment.passed and last.judgment.overall >= self.policy.target:+ return StopDecision("pass")+ refine_rounds = len(history) - 1+ if refine_rounds >= self.policy.max_rounds:+ return StopDecision("max_rounds")+ # Order is the economics. A regression whose strategy switch is already spent+ # is the most specific answer there is, so it comes first. Otherwise the+ # marginal-value test decides late rounds (at r03 no *shape* is worth $0.5),+ # and only before that does a first regression buy one change of shape.+ # Plateau is the fallback: the same money statement, less precisely.+ exhausted = self._regression(history, switch=False)+ if exhausted is not None:+ return self._maybe_detail(history, exhausted)+ marginal = self._diminishing(history)+ if marginal is not None:+ return self._maybe_detail(history, marginal)+ regressed = self._regression(history)+ if regressed is not None:+ return regressed+ if self._plateaued(history):+ return self._maybe_detail(history, StopDecision("plateau"))+ return StopDecision("continue")++ def _maybe_detail(self, history: Sequence[RoundRecord], stop: StopDecision) -> StopDecision:+ """Convert a "we are done repairing" stop into ONE surface-detail round.++ Only from a stop the loop was going to take anyway, so the detail round is+ never bought instead of a repair round — and only on a clean, best-scoring+ artifact, because the rounds that added geometry while assembly was still+ broken measurably lost score (module docstring / ``detail_rounds``)."""+ if stop.reason not in ("plateau", "diminishing_returns"):+ return stop+ why = detail_blocked(history, self.policy)+ if why:+ return stop+ return StopDecision("continue", strategy="detail",+ detail=f"structure clean at r{history[-1].index:02d} → one surface-detail round "+ f"({stop.reason} otherwise)")++ # ---------------------------------------------------------------- money stops+ def _regression(self, history: Sequence[RoundRecord], *, switch: bool = True) -> StopDecision | None:+ """The last round scored below the best by more than the judge's own noise.++ Another round of the SAME shape is not justified by that evidence: the+ first regression buys one change of strategy (a whole-artifact rewrite),+ a second one — or one after a rewrite already failed to recover — stops+ the run. ``switch=False`` asks only "is the switch already spent?", which+ is the question that outranks every other stop."""+ last = history[-1]+ score, best_before = last.score, best_score(history[:-1])+ if not meaningful_regression(score, best_before, self.policy):+ return None+ drop = best_before - score+ detail = (f"r{last.index:02d} scored {score:.3f} vs best {best_before:.3f} "+ f"({-drop:+.3f}, judge σ {self.policy.sigma:.3f})")+ if not self.policy.regression_allow_switch:+ return StopDecision("regression", detail=detail)+ if last.kind == REWRITE_KIND or self._regressions(history) > 1:+ return StopDecision("regression", detail=detail + " — a changed strategy did not recover it")+ return StopDecision("continue", strategy="switch", detail=detail) if switch else None++ def _diminishing(self, history: Sequence[RoundRecord]) -> StopDecision | None:+ """From ``marginal_from_round`` on, only run when the last round actually+ bought something (> ``marginal_sigma`` × σ) and the target is still open."""+ nxt = len(history)+ if nxt < self.policy.marginal_from_round:+ return None+ gain = last_gain(history)+ best = best_score(history)+ need = self.policy.marginal_delta+ if gain is None:+ return None+ if gain <= need:+ return StopDecision("diminishing_returns",+ detail=f"r{nxt:02d} not started: last gain {gain:+.3f} ≤ {need:.3f} "+ f"(1.5 × judge σ {self.policy.sigma:.3f})")+ if best is not None and best >= self.policy.target:+ return StopDecision("diminishing_returns",+ detail=f"r{nxt:02d} not started: best {best:.3f} already at target "+ f"{self.policy.target:.2f}")+ return None++ def _regressions(self, history: Sequence[RoundRecord]) -> int:+ """How many scored rounds ended MEANINGFULLY below the best of everything+ before them. Same predicate as the gate (:func:`meaningful_regression`),+ so a sub-noise dip can never help burn the run's single strategy switch+ (a -0.005 blip + one real regression used to count 2 = "regression" stop+ with the switch never offered)."""+ return sum(1 for i in range(1, len(history))+ if meaningful_regression(history[i].score, best_score(history[:i]), self.policy))++ def _plateaued(self, history: Sequence[RoundRecord]) -> bool:+ """True when the last ``plateau_window`` scored rounds did not raise the best+ score by ``min_delta``. Rounds without a judgment (build failures) do not+ count as evidence of a plateau: a pending repair explains a flat score."""+ scored = [r for r in history if r.score is not None]+ w = self.policy.plateau_window+ if len(scored) < w + 1:+ return False+ before = max(r.score for r in scored[:-w]) # type: ignore[type-var]+ after = max(r.score for r in scored[-w:]) # type: ignore[type-var]+ return (after - before) < self.policy.min_delta+++def detail_blocked(history: Sequence[RoundRecord], policy: RoundPolicy) -> str:+ """"" when a surface-detail round is due; otherwise the reason it is not.++ A detail round is worth money only on an artifact whose STRUCTURE is finished:+ the last round built, has no gate ERROR, scored at least ``detail_min_score``+ and is within one judge σ of the best round in the run. Anything else and the+ money belongs to repair (measured: refine rounds that added > 2000 triangles+ while assembly was still broken lost 0.075 of assembly_fit)."""+ if policy.detail_rounds <= 0:+ return "detail rounds disabled"+ spent = sum(1 for r in history if r.kind == DETAIL_KIND)+ if spent >= policy.detail_rounds:+ return f"{spent} detail round(s) already spent"+ if not history:+ return "no rounds yet"+ last = history[-1]+ if last.build is None or not last.build.ok:+ return "last round did not build"+ if gate_error_count(last) > 0:+ return f"{gate_error_count(last)} gate error(s) still open"+ if last.score is None:+ return "last round was not judged"+ if last.score < policy.detail_min_score:+ return f"score {last.score:.3f} < detail floor {policy.detail_min_score:.2f}"+ best = best_score(history)+ if best is not None and last.score < best - policy.sigma:+ return f"last round {last.score:.3f} is below best {best:.3f} by more than σ"+ return ""+++def best_score(history: Sequence[RoundRecord]) -> float | None:+ """Best judged score in ``history`` (``None`` when nothing was scored)."""+ scores = [r.score for r in history if r.score is not None]+ return max(scores) if scores else None+++def last_gain(history: Sequence[RoundRecord]) -> float | None:+ """How much the LAST round moved the best score (``None`` when unscored).++ Negative when it regressed; 0.0 when it changed nothing measurable."""+ if len(history) < 2 or history[-1].score is None:+ return None+ before = best_score(history[:-1])+ if before is None:+ return None+ return float(history[-1].score) - before+++def best_index(rounds: Sequence[tuple[float, int]]) -> int:+ """Index of the best round: higher score, tie → fewer errors, tie → later round."""+ if not rounds:+ raise ValueError("best_index needs at least one round")+ best = 0+ for i, (score, n_err) in enumerate(rounds):+ bs, be = rounds[best]+ if score > bs or (score == bs and n_err < be) or (score == bs and n_err == be):+ best = i+ return best+++class BestSelector:+ """Best round = highest score, then fewer gate errors, then later.++ ``best_index`` above owns the ranking rule. A round that+ did not build is never picked (it has no score, and delivering code that does+ not run is never an improvement); when NO round has a score the fallback is+ the built round with the fewest gate errors — later on a tie — so a round that+ broke the gates cannot displace a clean earlier artifact just by being last."""++ def pick(self, rounds: Sequence[RoundRecord]) -> int | None:+ scored = [(i, r) for i, r in enumerate(rounds) if r.score is not None and not _build_failed(r)]+ if scored:+ k = best_index([(float(r.score), gate_error_count(r)) for _, r in scored]) # type: ignore[arg-type]+ return scored[int(k)][0]+ built = [i for i, r in enumerate(rounds) if r.build is not None and r.build.ok]+ if not built:+ return None+ return min(built, key=lambda i: (gate_error_count(rounds[i]), -i))+++def gate_error_count(r: RoundRecord) -> int:+ return sum(len(g.errors) for g in r.gates)+++def _build_failed(r: RoundRecord) -> bool:+ """The round is KNOWN not to build (a record with no build at all is not a failure:+ resumed/rejudged records may carry a score without one)."""+ return r.build is not None and not r.build.ok+++# ----------------------------------------------------------------------------- refine tasks+++# ===================================================================== budget+# (merged from codeverse/orchestrator/budget.py, 2026-08-28)+log = logging.getLogger(__name__)++#: stage label used when a caller does not say where the money went+OTHER_STAGE = "other"+++class BudgetExceeded(RuntimeError):+ """Raised when a run crosses its USD or wall-clock ceiling."""++ def __init__(self, reason: str, *, spent_usd: float, elapsed_min: float):+ super().__init__(reason)+ self.reason = reason+ self.spent_usd = spent_usd+ self.elapsed_min = elapsed_min+++class BudgetGuard:+ """Thread-safe accumulator of ``Usage`` against a ``Budget``.++ ``charge`` adds usage and then calls ``check``; ``check`` raises+ ``BudgetExceeded`` when ``max_usd`` or ``max_minutes`` is exceeded.+ """++ def __init__(+ self,+ budget: Budget,+ start_time: float | None = None,+ *,+ soft_fraction: float = 1.0,+ run: str = "",+ ledger: str | Path | Any | None = None,+ ):+ self.budget = budget+ self.start_time = time.time() if start_time is None else start_time+ #: ACTIVE seconds carried over from previous sessions of this run (``restore``+ #: sets it from the snapshot); downtime between sessions never counts.+ self._active_s: float = 0.0+ self.spent = Usage()+ #: the share of ``spent.cost_usd`` that is money someone is actually charged.+ #: The ceilings enforce THIS, not ``spent.cost_usd`` — a backend on a flat-rate+ #: subscription prices its tokens notionally and must not consume a spend guard.+ #: See ``cost/billing.py`` for why, and what still bounds a subscription run.+ self.billed_usd = 0.0+ self._lock = threading.Lock()+ self.calls = 0+ #: fraction of the hard ceilings the *baseline* may use (1.0 = no soft cap)+ self.soft_fraction = min(1.0, max(0.0, float(soft_fraction)))+ #: one-off extension of the HARD ceilings (finalise/salvage headroom)+ self.grace_usd = 0.0+ self.grace_minutes = 0.0+ #: run slug + ledger sink for the per-call rows (None = do not write a ledger)+ self.run = run+ self.ledger = ledger+ #: stage -> USD and round -> {stage -> USD}, so a round can report what it burned+ self.by_stage: dict[str, float] = {}+ self.by_round: dict[int, dict[str, float]] = {}++ # ----------------------------------------------------------------- accounting+ def spend(+ self,+ usage: Usage | None,+ *,+ stage: str = OTHER_STAGE,+ role: str | None = None,+ label: str = "",+ round_index: int | None = None,+ outcome: str = "ok",+ enforce: bool = True,+ ) -> None:+ """THE door every dollar goes through.++ Accumulates ``usage``, buckets it by ``stage`` (and by round), appends a+ priced row to the run's cost ledger, and — when ``enforce`` — raises+ ``BudgetExceeded`` if a hard ceiling is now crossed. Accounting never+ fails a run: a broken ledger is logged, not propagated."""+ if usage is None:+ return+ with self._lock:+ self.spent = self.spent + usage+ if bills_usd(getattr(usage, "backend", None)):+ self.billed_usd += float(usage.cost_usd)+ self.calls += 1+ key = stage or OTHER_STAGE+ self.by_stage[key] = self.by_stage.get(key, 0.0) + float(usage.cost_usd)+ if round_index is not None:+ per = self.by_round.setdefault(int(round_index), {})+ per[key] = per.get(key, 0.0) + float(usage.cost_usd)+ self._ledger_row(+ usage, stage=key, role=role, label=label, round_index=round_index, outcome=outcome+ )+ if enforce:+ self.check()++ def charge(self, usage: Usage | None, **kw: Any) -> None:+ """Account for ``usage``, then enforce the ceilings (see :meth:`spend`)."""+ kw.setdefault("enforce", True)+ self.spend(usage, **kw)++ def add(self, usage: Usage | None, **kw: Any) -> None:+ """Account for ``usage`` WITHOUT enforcing the ceilings.++ For work that is already done and persisted (a completed judge verdict,+ a pairwise tie-break, the texture pass): the money is spent either way,+ and raising here would throw away a finished, paid-for result. The+ round loop stops at its next ``ok()`` check instead. The dollar is+ still bucketed and still written to the ledger — "not enforced" never+ means "not seen"."""+ kw["enforce"] = False+ self.spend(usage, **kw)++ def _ledger_row(+ self,+ usage: Usage,+ *,+ stage: str,+ role: str | None,+ label: str,+ round_index: int | None,+ outcome: str,+ ) -> None:+ if self.ledger is None:+ return+ try:+ from codeverse.cost import per_call_metering, record_call++ # When the run is metered call by call (codeverse.cost.instrument wraps every+ # ChatModel / CodingAgent), those rows already ARE this dollar with per-call+ # tokens, cache hits and latency — one aggregate row on top would double count.+ if per_call_metering():+ return+ record_call(+ usage,+ run=self.run,+ stage=stage,+ role=role,+ round=round_index,+ label=label,+ backend=usage.backend,+ model=usage.model,+ outcome=outcome,+ ledger=self.ledger,+ )+ except Exception as e: # noqa: BLE001 — accounting must never fail a run+ log.debug("cost ledger row failed (%s): %s", self.ledger, e)++ def mark(self) -> Usage:+ """Snapshot of the running total — diff it with :func:`usage_delta` to see+ what a round burned even when the round itself raised half-way."""+ return self.spent.model_copy(deep=True)++ def round_costs(self, round_index: int) -> dict[str, float]:+ """``{stage: USD}`` charged against one round index (empty when none)."""+ return dict(self.by_round.get(int(round_index), {}))++ # ----------------------------------------------------------------- resume snapshot+ def snapshot(self) -> BudgetSnapshot:+ """Point-in-time guard state for ``run_state.json`` so a resume continues the+ SAME budget instead of a fresh one. Grace and config are deliberately absent:+ grace is one attempt's salvage headroom — persisting it would ratchet the hard+ ceiling run over run, and the ceilings always come from the current spec."""+ with self._lock:+ return BudgetSnapshot(+ spent=self.spent.model_copy(deep=True),+ billed_usd=self.billed_usd,+ calls=self.calls,+ by_stage=dict(self.by_stage),+ by_round={r: dict(per) for r, per in self.by_round.items()},+ active_s=self._active_s + (time.time() - self.start_time),+ )++ def restore(self, snap: BudgetSnapshot) -> None:+ """Adopt a snapshot: money, calls and buckets keep counting; ``start_time``+ stays *now*, so ``elapsed_minutes`` is prior ACTIVE seconds plus this session+ — never the downtime in between. The ceilings come from the (possibly raised)+ spec budget, so a raised ``--max-usd`` grants exactly the difference, never a+ fresh full cap."""+ with self._lock:+ self.spent = snap.spent.model_copy(deep=True)+ self.billed_usd = float(snap.billed_usd)+ self.calls = int(snap.calls)+ self.by_stage = dict(snap.by_stage)+ self.by_round = {int(r): dict(per) for r, per in snap.by_round.items()}+ self._active_s = float(snap.active_s)+ self.start_time = time.time()++ def elapsed_minutes(self) -> float:+ """Cumulative ACTIVE minutes: prior sessions' seconds (restored from the+ snapshot) plus this session's wall clock. Downtime costs nothing."""+ return (self._active_s + (time.time() - self.start_time)) / 60.0++ # ----------------------------------------------------------------- ceilings+ @property+ def hard_usd(self) -> float:+ return self.budget.max_usd + self.grace_usd++ @property+ def hard_minutes(self) -> float:+ return self.budget.max_minutes + self.grace_minutes++ def grant_grace(self, *, usd: float = 0.0, minutes: float = 0.0) -> None:+ """Extend the HARD ceilings (never shrink them). Used once by finalise /+ salvage so a run that tripped the budget mid-stage can still deliver a+ judged round instead of no score at all."""+ with self._lock:+ self.grace_usd = max(self.grace_usd, max(0.0, float(usd)))+ self.grace_minutes = max(self.grace_minutes, max(0.0, float(minutes)))++ def check(self) -> None:+ """Raise ``BudgetExceeded`` if any hard ceiling has been crossed."""+ spent = self.billed_usd+ elapsed = self.elapsed_minutes()+ if spent > self.hard_usd:+ raise BudgetExceeded(+ f"cost ${spent:.3f} exceeds max_usd ${self.hard_usd:.2f}",+ spent_usd=spent,+ elapsed_min=elapsed,+ )+ if elapsed > self.hard_minutes:+ raise BudgetExceeded(+ f"elapsed {elapsed:.1f} min exceeds max_minutes {self.hard_minutes:.1f}",+ spent_usd=spent,+ elapsed_min=elapsed,+ )++ # ----------------------------------------------------------------- soft cap+ def soft_limits(self) -> tuple[float, float]:+ """(usd, minutes) the soft sub-budget allows (grace is hard-only)."""+ return (+ self.budget.max_usd * self.soft_fraction,+ self.budget.max_minutes * self.soft_fraction,+ )++ def soft_exceeded(self) -> str:+ """Reason string when the soft sub-budget is used up, else ``""``."""+ usd, minutes = self.soft_limits()+ spent, elapsed = self.billed_usd, self.elapsed_minutes()+ if spent > usd:+ return f"cost ${spent:.3f} exceeds soft cap ${usd:.2f} ({self.soft_fraction:.0%} of ${self.budget.max_usd:.2f})"+ if elapsed > minutes:+ return f"elapsed {elapsed:.1f} min exceeds soft cap {minutes:.1f} min ({self.soft_fraction:.0%} of {self.budget.max_minutes:.1f})"+ return ""++ def soft_ok(self) -> bool:+ """True while the baseline still has its share of the budget."""+ return not self.soft_exceeded()++ def soft_remaining(self) -> dict[str, float]:+ """Headroom left inside the soft sub-budget (never negative)."""+ usd, minutes = self.soft_limits()+ return {+ "usd": max(0.0, usd - self.billed_usd),+ "minutes": max(0.0, minutes - self.elapsed_minutes()),+ }++ def ok(self) -> bool:+ """True when no ceiling is crossed (non-raising variant of ``check``)."""+ try:+ self.check()+ except BudgetExceeded:+ return False+ return True++ def remaining(self) -> dict[str, float]:+ """Remaining headroom: ``{"usd": ..., "minutes": ..., "fraction": ...}``."""+ usd = max(0.0, self.hard_usd - self.billed_usd)+ minutes = max(0.0, self.hard_minutes - self.elapsed_minutes())+ frac_usd = usd / self.hard_usd if self.hard_usd > 0 else 0.0+ frac_min = minutes / self.hard_minutes if self.hard_minutes > 0 else 0.0+ return {"usd": usd, "minutes": minutes, "fraction": min(frac_usd, frac_min)}++ def timeout_s(self, want_s: float, *, floor_s: float = 60.0, soft: bool = True) -> int:+ """``want_s`` clipped to the wall-clock actually left (soft cap when ``soft``).++ A generation session must never be allowed to outlive the run's budget:+ the greenhouse scene lost 54 minutes to zone agents that kept working+ after the ceiling had already been crossed."""+ left = (self.soft_remaining()["minutes"] if soft else self.remaining()["minutes"]) * 60.0+ return int(max(floor_s, min(float(want_s), left) if left > 0 else floor_s))++ def summary(self) -> dict[str, float | int]:+ return {+ "spent_usd": round(self.billed_usd, 4),+ # what it WOULD have cost at list price; equal to spent_usd unless a+ # subscription backend ran (cost/billing.py)+ "notional_usd": round(self.spent.cost_usd, 4),+ "elapsed_min": round(self.elapsed_minutes(), 2),+ "soft_fraction": round(self.soft_fraction, 3),+ "grace_usd": round(self.grace_usd, 4),+ "calls": self.calls,+ "input_tokens": self.spent.input_tokens,+ "output_tokens": self.spent.output_tokens,+ }++ def stage_summary(self) -> dict[str, float]:+ """``{stage: USD}`` over the whole run (what the ``cost.round`` events add up to)."""+ return {k: round(v, 6) for k, v in sorted(self.by_stage.items(), key=lambda kv: -kv[1])}+++class BudgetSnapshot(BaseModel):+ """What survives a resume (``run_state.extra["budget_snapshot"]``).++ The five accumulator fields of :class:`BudgetGuard` plus cumulative ACTIVE+ seconds. Grace (``grace_usd``/``grace_minutes``) and config (ceilings, soft+ fraction, run, ledger) are EXCLUDED on purpose: grace is per-attempt salvage+ headroom — persisting it would ratchet the hard ceiling — and config always+ comes from the current spec/settings."""++ version: int = 1+ spent: Usage+ billed_usd: float+ calls: int+ by_stage: dict[str, float]+ #: matches the ``BudgetGuard.by_round`` / ``round_costs()`` shape+ by_round: dict[int, dict[str, float]]+ active_s: float+++def usage_delta(after: Usage, before: Usage) -> Usage:+ """``after - before`` field by field (never negative). Used to report what a+ round burned when it raised before it could fold its own usage together."""+ return Usage(+ backend=after.backend or before.backend,+ model=after.model or before.model,+ input_tokens=max(0, after.input_tokens - before.input_tokens),+ output_tokens=max(0, after.output_tokens - before.output_tokens),+ cached_tokens=max(0, after.cached_tokens - before.cached_tokens),+ thoughts_tokens=max(0, after.thoughts_tokens - before.thoughts_tokens),+ tool_calls=max(0, after.tool_calls - before.tool_calls),+ cost_usd=max(0.0, after.cost_usd - before.cost_usd),+ latency_ms=max(0, after.latency_ms - before.latency_ms),+ )diff --git a/harness/codeverse/orchestrator/__init__.py b/harness/codeverse/orchestrator/__init__.pydeleted file mode 100644index 15bb607e..00000000--- a/harness/codeverse/orchestrator/__init__.py+++ /dev/null@@ -1 +0,0 @@-"""Orchestration primitives: stage runner with resume, round loop, budget."""diff --git a/harness/codeverse/orchestrator/budget.py b/harness/codeverse/orchestrator/budget.pydeleted file mode 100644index 312a8535..00000000--- a/harness/codeverse/orchestrator/budget.py+++ /dev/null@@ -1,370 +0,0 @@-"""Budget guard: hard per-run ceilings on cost and wall time, plus a soft cap.--Every model / agent call yields a ``Usage``; the track charges it here. When-either **hard** ceiling is crossed ``BudgetExceeded`` is raised so the round-loop can stop cleanly (status ``budget``) instead of silently overspending.--**One door for every dollar.** ``charge`` and ``add`` are thin wrappers over-:meth:`BudgetGuard.spend`, which is the only place money enters the run: it-accumulates the ``Usage``, buckets it by stage and by round, appends one priced-row to the run's cost ledger (``<run>/cost_ledger.jsonl``,-``codeverse.cost.record_call``) and then — for ``charge`` — enforces the-ceilings. The audit (docs/COST.md §6) found $4.80 of real spend that never-reached ``record.total_usage``: rounds the budget cut after the work was done,-retried ``.a2`` agent sessions and post-hoc texture passes. Anything that goes-through ``spend`` is visible to the guard, to the record and to the ledger, so-that class of blindness cannot come back.--On top of that a **soft** sub-budget (``soft_fraction`` of the hard ceilings)-lets a track see the wall coming: ``soft_ok()`` / ``soft_exceeded()`` say-"the baseline has used its share — degrade now (fewer assets, single-shot-instead of an agent session) so the refine rounds still have money". Crossing-the soft cap never raises; only the hard ceiling does. ``grant_grace`` raises-the hard ceiling once so a budget-stopped run can still finalise (assemble +-build + render + judge) instead of dying with no score at all.-"""--from __future__ import annotations--import logging-import threading-import time-from pathlib import Path-from typing import Any--from pydantic import BaseModel--from codeverse.contracts.common import Budget, Usage-from codeverse.cost.billing import bills_usd--log = logging.getLogger(__name__)--#: stage label used when a caller does not say where the money went-OTHER_STAGE = "other"---class BudgetExceeded(RuntimeError):- """Raised when a run crosses its USD or wall-clock ceiling."""-- def __init__(self, reason: str, *, spent_usd: float, elapsed_min: float):- super().__init__(reason)- self.reason = reason- self.spent_usd = spent_usd- self.elapsed_min = elapsed_min---class BudgetGuard:- """Thread-safe accumulator of ``Usage`` against a ``Budget``.-- ``charge`` adds usage and then calls ``check``; ``check`` raises- ``BudgetExceeded`` when ``max_usd`` or ``max_minutes`` is exceeded.- """-- def __init__(- self,- budget: Budget,- start_time: float | None = None,- *,- soft_fraction: float = 1.0,- run: str = "",- ledger: str | Path | Any | None = None,- ):- self.budget = budget- self.start_time = time.time() if start_time is None else start_time- #: ACTIVE seconds carried over from previous sessions of this run (``restore``- #: sets it from the snapshot); downtime between sessions never counts.- self._active_s: float = 0.0- self.spent = Usage()- #: the share of ``spent.cost_usd`` that is money someone is actually charged.- #: The ceilings enforce THIS, not ``spent.cost_usd`` — a backend on a flat-rate- #: subscription prices its tokens notionally and must not consume a spend guard.- #: See ``cost/billing.py`` for why, and what still bounds a subscription run.- self.billed_usd = 0.0- self._lock = threading.Lock()- self.calls = 0- #: fraction of the hard ceilings the *baseline* may use (1.0 = no soft cap)- self.soft_fraction = min(1.0, max(0.0, float(soft_fraction)))- #: one-off extension of the HARD ceilings (finalise/salvage headroom)- self.grace_usd = 0.0- self.grace_minutes = 0.0- #: run slug + ledger sink for the per-call rows (None = do not write a ledger)- self.run = run- self.ledger = ledger- #: stage -> USD and round -> {stage -> USD}, so a round can report what it burned- self.by_stage: dict[str, float] = {}- self.by_round: dict[int, dict[str, float]] = {}-- # ----------------------------------------------------------------- accounting- def spend(- self,- usage: Usage | None,- *,- stage: str = OTHER_STAGE,- role: str | None = None,- label: str = "",- round_index: int | None = None,- outcome: str = "ok",- enforce: bool = True,- ) -> None:- """THE door every dollar goes through.-- Accumulates ``usage``, buckets it by ``stage`` (and by round), appends a- priced row to the run's cost ledger, and — when ``enforce`` — raises- ``BudgetExceeded`` if a hard ceiling is now crossed. Accounting never- fails a run: a broken ledger is logged, not propagated."""- if usage is None:- return- with self._lock:- self.spent = self.spent + usage- if bills_usd(getattr(usage, "backend", None)):- self.billed_usd += float(usage.cost_usd)- self.calls += 1- key = stage or OTHER_STAGE- self.by_stage[key] = self.by_stage.get(key, 0.0) + float(usage.cost_usd)- if round_index is not None:- per = self.by_round.setdefault(int(round_index), {})- per[key] = per.get(key, 0.0) + float(usage.cost_usd)- self._ledger_row(- usage, stage=key, role=role, label=label, round_index=round_index, outcome=outcome- )- if enforce:- self.check()-- def charge(self, usage: Usage | None, **kw: Any) -> None:- """Account for ``usage``, then enforce the ceilings (see :meth:`spend`)."""- kw.setdefault("enforce", True)- self.spend(usage, **kw)-- def add(self, usage: Usage | None, **kw: Any) -> None:- """Account for ``usage`` WITHOUT enforcing the ceilings.-- For work that is already done and persisted (a completed judge verdict,- a pairwise tie-break, the texture pass): the money is spent either way,- and raising here would throw away a finished, paid-for result. The- round loop stops at its next ``ok()`` check instead. The dollar is- still bucketed and still written to the ledger — "not enforced" never- means "not seen"."""- kw["enforce"] = False- self.spend(usage, **kw)-- def _ledger_row(- self,- usage: Usage,- *,- stage: str,- role: str | None,- label: str,- round_index: int | None,- outcome: str,- ) -> None:- if self.ledger is None:- return- try:- from codeverse.cost import per_call_metering, record_call-- # When the run is metered call by call (codeverse.cost.instrument wraps every- # ChatModel / CodingAgent), those rows already ARE this dollar with per-call- # tokens, cache hits and latency — one aggregate row on top would double count.- if per_call_metering():- return- record_call(- usage,- run=self.run,- stage=stage,- role=role,- round=round_index,- label=label,- backend=usage.backend,- model=usage.model,- outcome=outcome,- ledger=self.ledger,- )- except Exception as e: # noqa: BLE001 — accounting must never fail a run- log.debug("cost ledger row failed (%s): %s", self.ledger, e)-- def mark(self) -> Usage:- """Snapshot of the running total — diff it with :func:`usage_delta` to see- what a round burned even when the round itself raised half-way."""- return self.spent.model_copy(deep=True)-- def round_costs(self, round_index: int) -> dict[str, float]:- """``{stage: USD}`` charged against one round index (empty when none)."""- return dict(self.by_round.get(int(round_index), {}))-- # ----------------------------------------------------------------- resume snapshot- def snapshot(self) -> BudgetSnapshot:- """Point-in-time guard state for ``run_state.json`` so a resume continues the- SAME budget instead of a fresh one. Grace and config are deliberately absent:- grace is one attempt's salvage headroom — persisting it would ratchet the hard- ceiling run over run, and the ceilings always come from the current spec."""- with self._lock:- return BudgetSnapshot(- spent=self.spent.model_copy(deep=True),- billed_usd=self.billed_usd,- calls=self.calls,- by_stage=dict(self.by_stage),- by_round={r: dict(per) for r, per in self.by_round.items()},- active_s=self._active_s + (time.time() - self.start_time),- )-- def restore(self, snap: BudgetSnapshot) -> None:- """Adopt a snapshot: money, calls and buckets keep counting; ``start_time``- stays *now*, so ``elapsed_minutes`` is prior ACTIVE seconds plus this session- — never the downtime in between. The ceilings come from the (possibly raised)- spec budget, so a raised ``--max-usd`` grants exactly the difference, never a- fresh full cap."""- with self._lock:- self.spent = snap.spent.model_copy(deep=True)- self.billed_usd = float(snap.billed_usd)- self.calls = int(snap.calls)- self.by_stage = dict(snap.by_stage)- self.by_round = {int(r): dict(per) for r, per in snap.by_round.items()}- self._active_s = float(snap.active_s)- self.start_time = time.time()-- def elapsed_minutes(self) -> float:- """Cumulative ACTIVE minutes: prior sessions' seconds (restored from the- snapshot) plus this session's wall clock. Downtime costs nothing."""- return (self._active_s + (time.time() - self.start_time)) / 60.0-- # ----------------------------------------------------------------- ceilings- @property- def hard_usd(self) -> float:- return self.budget.max_usd + self.grace_usd-- @property- def hard_minutes(self) -> float:- return self.budget.max_minutes + self.grace_minutes-- def grant_grace(self, *, usd: float = 0.0, minutes: float = 0.0) -> None:- """Extend the HARD ceilings (never shrink them). Used once by finalise /- salvage so a run that tripped the budget mid-stage can still deliver a- judged round instead of no score at all."""- with self._lock:- self.grace_usd = max(self.grace_usd, max(0.0, float(usd)))- self.grace_minutes = max(self.grace_minutes, max(0.0, float(minutes)))-- def check(self) -> None:- """Raise ``BudgetExceeded`` if any hard ceiling has been crossed."""- spent = self.billed_usd- elapsed = self.elapsed_minutes()- if spent > self.hard_usd:- raise BudgetExceeded(- f"cost ${spent:.3f} exceeds max_usd ${self.hard_usd:.2f}",- spent_usd=spent,- elapsed_min=elapsed,- )- if elapsed > self.hard_minutes:- raise BudgetExceeded(- f"elapsed {elapsed:.1f} min exceeds max_minutes {self.hard_minutes:.1f}",- spent_usd=spent,- elapsed_min=elapsed,- )-- # ----------------------------------------------------------------- soft cap- def soft_limits(self) -> tuple[float, float]:- """(usd, minutes) the soft sub-budget allows (grace is hard-only)."""- return (- self.budget.max_usd * self.soft_fraction,- self.budget.max_minutes * self.soft_fraction,- )-- def soft_exceeded(self) -> str:- """Reason string when the soft sub-budget is used up, else ``""``."""- usd, minutes = self.soft_limits()- spent, elapsed = self.billed_usd, self.elapsed_minutes()- if spent > usd:- return f"cost ${spent:.3f} exceeds soft cap ${usd:.2f} ({self.soft_fraction:.0%} of ${self.budget.max_usd:.2f})"- if elapsed > minutes:- return f"elapsed {elapsed:.1f} min exceeds soft cap {minutes:.1f} min ({self.soft_fraction:.0%} of {self.budget.max_minutes:.1f})"- return ""-- def soft_ok(self) -> bool:- """True while the baseline still has its share of the budget."""- return not self.soft_exceeded()-- def soft_remaining(self) -> dict[str, float]:- """Headroom left inside the soft sub-budget (never negative)."""- usd, minutes = self.soft_limits()- return {- "usd": max(0.0, usd - self.billed_usd),- "minutes": max(0.0, minutes - self.elapsed_minutes()),- }-- def ok(self) -> bool:- """True when no ceiling is crossed (non-raising variant of ``check``)."""- try:- self.check()- except BudgetExceeded:- return False- return True-- def remaining(self) -> dict[str, float]:- """Remaining headroom: ``{"usd": ..., "minutes": ..., "fraction": ...}``."""- usd = max(0.0, self.hard_usd - self.billed_usd)- minutes = max(0.0, self.hard_minutes - self.elapsed_minutes())- frac_usd = usd / self.hard_usd if self.hard_usd > 0 else 0.0- frac_min = minutes / self.hard_minutes if self.hard_minutes > 0 else 0.0- return {"usd": usd, "minutes": minutes, "fraction": min(frac_usd, frac_min)}-- def timeout_s(self, want_s: float, *, floor_s: float = 60.0, soft: bool = True) -> int:- """``want_s`` clipped to the wall-clock actually left (soft cap when ``soft``).-- A generation session must never be allowed to outlive the run's budget:- the greenhouse scene lost 54 minutes to zone agents that kept working- after the ceiling had already been crossed."""- left = (self.soft_remaining()["minutes"] if soft else self.remaining()["minutes"]) * 60.0- return int(max(floor_s, min(float(want_s), left) if left > 0 else floor_s))-- def summary(self) -> dict[str, float | int]:- return {- "spent_usd": round(self.billed_usd, 4),- # what it WOULD have cost at list price; equal to spent_usd unless a- # subscription backend ran (cost/billing.py)- "notional_usd": round(self.spent.cost_usd, 4),- "elapsed_min": round(self.elapsed_minutes(), 2),- "soft_fraction": round(self.soft_fraction, 3),- "grace_usd": round(self.grace_usd, 4),- "calls": self.calls,- "input_tokens": self.spent.input_tokens,- "output_tokens": self.spent.output_tokens,- }-- def stage_summary(self) -> dict[str, float]:- """``{stage: USD}`` over the whole run (what the ``cost.round`` events add up to)."""- return {k: round(v, 6) for k, v in sorted(self.by_stage.items(), key=lambda kv: -kv[1])}---class BudgetSnapshot(BaseModel):- """What survives a resume (``run_state.extra["budget_snapshot"]``).-- The five accumulator fields of :class:`BudgetGuard` plus cumulative ACTIVE- seconds. Grace (``grace_usd``/``grace_minutes``) and config (ceilings, soft- fraction, run, ledger) are EXCLUDED on purpose: grace is per-attempt salvage- headroom — persisting it would ratchet the hard ceiling — and config always- comes from the current spec/settings."""-- version: int = 1- spent: Usage- billed_usd: float- calls: int- by_stage: dict[str, float]- #: matches the ``BudgetGuard.by_round`` / ``round_costs()`` shape- by_round: dict[int, dict[str, float]]- active_s: float---def usage_delta(after: Usage, before: Usage) -> Usage:- """``after - before`` field by field (never negative). Used to report what a- round burned when it raised before it could fold its own usage together."""- return Usage(- backend=after.backend or before.backend,- model=after.model or before.model,- input_tokens=max(0, after.input_tokens - before.input_tokens),- output_tokens=max(0, after.output_tokens - before.output_tokens),- cached_tokens=max(0, after.cached_tokens - before.cached_tokens),- thoughts_tokens=max(0, after.thoughts_tokens - before.thoughts_tokens),- tool_calls=max(0, after.tool_calls - before.tool_calls),- cost_usd=max(0.0, after.cost_usd - before.cost_usd),- latency_ms=max(0, after.latency_ms - before.latency_ms),- )diff --git a/harness/codeverse/orchestrator/refine_tasks.py b/harness/codeverse/orchestrator/refine_tasks.pydeleted file mode 100644index 4fc79c05..00000000--- a/harness/codeverse/orchestrator/refine_tasks.py+++ /dev/null@@ -1,250 +0,0 @@-"""Refine-task compilation: what the next round is asked to change.--Owns the typed change request (``RefineTask``), its file-ownership grouping-(``TaskGroup``, ``plan_parallel_groups``, ``plan_refine_groups``), the compiler-that turns gate errors + failed *must* acceptance items + the judge's improvement-plan into tasks (``build_refine_instructions``) and the per-task line compaction-(``compact_instructions``), plus the plan-name canonicalisation helpers they share.--Sibling: ``codeverse.orchestrator.rounds`` owns the round-loop *policy* -- when to-stop, which round is best, what shape the next round takes -- and re-exports every-public name below so existing importers keep working. This module is a leaf: it-reads contracts + conventions only and never imports the policy.-"""--from __future__ import annotations--import logging-from collections.abc import Callable, Sequence-from typing import Literal--from pydantic import BaseModel, Field--from codeverse.contracts.artifacts import GateReport-from codeverse.contracts.judgment import Judgment-from codeverse.contracts.plan import AcceptanceItem, Plan-from codeverse.conventions import to_snake--log = logging.getLogger(__name__)---class RefineTask(BaseModel):- """One targeted change request compiled for the next round."""-- target: str = Field(description="part / zone / asset / joint / camera / 'overall'")- kind: str = Field(description="geometry | assembly | material | articulation | bug | acceptance | ...")- instruction: str- priority: int = Field(ge=0, le=9, description="0 = gate error, 1 = failed must item, 2+ = judge")- files: list[str] = Field(default_factory=list, description="files this task may edit ([] = unknown/whole)")- source: Literal["gate", "acceptance", "judge"] = "judge"-- def line(self) -> str:- files = f" (files: {', '.join(self.files)})" if self.files else ""- return f"[{self.source}/{self.kind}] {self.target}: {self.instruction}{files}"---class TaskGroup(BaseModel):- """Tasks that must run together (they touch the same files)."""-- tasks: list[RefineTask]- files: list[str] = Field(default_factory=list)-- @property- def targets(self) -> list[str]:- seen: list[str] = []- for t in self.tasks:- if t.target not in seen:- seen.append(t.target)- return seen-- @property- def label(self) -> str:- return "+".join(to_snake(t) for t in self.targets[:3]) or "refine"---FileForTarget = Callable[[str], list[str]]---def build_refine_instructions(- judgment: Judgment | None,- gates: Sequence[GateReport],- acceptance_failures: Sequence[AcceptanceItem],- plan: Plan | None,- *,- file_for_target: FileForTarget | None = None,- max_tasks: int = 6,- extra: Sequence[RefineTask] = (),-) -> list[RefineTask]:- """Gate ERRORS first (with fix hints), then ``extra`` harness-derived tasks- (e.g. reference-silhouette mismatch), then failed *must* acceptance items,- then the judge's improvement plan; de-duplicated by (target, kind), capped.- Gate/acceptance/extra tasks are never dropped by the cap unless they alone exceed it."""- known = _known_targets(plan)- tasks: list[RefineTask] = []- seen: set[tuple[str, str]] = set()-- def _add(t: RefineTask) -> None:- key = (to_snake(t.target), t.kind)- if key in seen:- return- seen.add(key)- t.target = _canon_target(t.target, known)- if file_for_target is not None and not t.files:- t.files = list(file_for_target(t.target))- tasks.append(t)-- for g in gates:- for f in g.errors:- _add(RefineTask(target=f.target or "overall", kind=f"gate:{g.gate}", instruction=f.as_line(),- priority=0, source="gate"))- for t in extra:- _add(t.model_copy())- for a in acceptance_failures:- if a.priority != "must":- continue- _add(RefineTask(target=_acceptance_target(a, known), kind="acceptance",- instruction=f"Acceptance item {a.id} NOT met: {a.text}", priority=1,- source="acceptance"))- if judgment is not None:- for item in sorted(judgment.improvement_plan, key=lambda i: (i.priority, -i.expected_gain)):- _add(RefineTask(target=item.target or "overall", kind=item.kind, instruction=item.instruction,- priority=min(9, 1 + item.priority), source="judge"))- tasks.sort(key=lambda t: t.priority)- if len(tasks) > max_tasks:- protected = [t for t in tasks if t.source != "judge"]- rest = [t for t in tasks if t.source == "judge"]- tasks = (protected + rest)[:max(max_tasks, len(protected))]- return tasks---def plan_parallel_groups(tasks: Sequence[RefineTask]) -> list[TaskGroup]:- """Group tasks by file ownership. Tasks with unknown files (``[]``) cannot- be isolated, so if any exists everything collapses into ONE group (a single- whole-object task). Otherwise groups are the connected components of the- "shares a file" relation — each group may run concurrently with the others."""- if not tasks:- return []- if any(not t.files for t in tasks):- files = sorted({f for t in tasks for f in t.files})- return [TaskGroup(tasks=list(tasks), files=files)]- parent = list(range(len(tasks)))-- def find(i: int) -> int:- while parent[i] != i:- parent[i] = parent[parent[i]]- i = parent[i]- return i-- owner: dict[str, int] = {}- for i, t in enumerate(tasks):- for f in t.files:- if f in owner:- parent[find(i)] = find(owner[f])- else:- owner[f] = i- groups: dict[int, list[RefineTask]] = {}- for i, t in enumerate(tasks):- groups.setdefault(find(i), []).append(t)- out = []- for members in groups.values():- files = sorted({f for t in members for f in t.files})- out.append(TaskGroup(tasks=members, files=files))- out.sort(key=lambda g: min(t.priority for t in g.tasks))- return out---def plan_refine_groups(- tasks: Sequence[RefineTask],- *,- allow_fanout: bool = True,- parallel_min_tasks: int = 2,-) -> tuple[list[TaskGroup], bool]:- """The ONE grouping rule of the refine scaffold (``BaseTrack.refine_tasks``).-- Groups by file ownership via :func:`plan_parallel_groups`; the groups run in- parallel only when fan-out is allowed for the track, at least- ``parallel_min_tasks`` file-disjoint groups exist and every group owns- files. Otherwise everything collapses into ONE whole-artifact group."""- groups = plan_parallel_groups(tasks)- parallel = allow_fanout and len(groups) >= parallel_min_tasks and all(g.files for g in groups)- if not parallel:- groups = [TaskGroup(tasks=list(tasks), files=sorted({f for t in tasks for f in t.files}))]- return groups, parallel---def compact_instructions(tasks: Sequence[RefineTask], max_lines: int = 6) -> list[str]:- """The instruction lines handed to ONE generation task: grouped by target- (instances ``Leg_0``/``Leg_1`` fold into ``Leg``), ordered by priority, capped- at ``max_lines``. A flash-class agent given 12 near-identical connectivity- errors fixes none; given "FrontLeg: (a) … (b) …" it fixes the part."""- if not tasks:- return []- groups: dict[str, list[RefineTask]] = {}- for t in sorted(tasks, key=lambda t: t.priority):- groups.setdefault(_instance_base(t.target), []).append(t)- lines: list[str] = []- for target, members in groups.items():- if len(members) == 1:- lines.append(members[0].line())- continue- bits = []- for i, t in enumerate(members):- who = f" [{t.target}]" if t.target != target else ""- bits.append(f"({chr(97 + i % 26)}){who} [{t.source}/{t.kind}] {t.instruction}")- files = sorted({f for t in members for f in t.files})- tail = f" (files: {', '.join(files)})" if files else ""- lines.append(f"{target}: " + "; ".join(bits) + tail)- if len(lines) > max_lines:- dropped = len(lines) - max_lines- lines = lines[:max_lines]- log.info("compact_instructions: %d target group(s) deferred to a later round", dropped)- return lines---# ----------------------------------------------------------------------------- helpers-def _split_instance(target: str) -> tuple[str, str]:- """``BackLeg_1`` → (``BackLeg``, ``1``) per the ``Name_0..N-1`` instance naming- convention; anything else → (target, "")."""- base, sep, suffix = (target or "").rpartition("_")- if sep and base and suffix.isdigit():- return base, suffix- return target or "overall", ""---def _instance_base(target: str) -> str:- return _split_instance(target)[0]---def _known_targets(plan: Plan | None) -> dict[str, str]:- """snake → canonical name for every part/zone/asset/joint/camera in the plan."""- names: dict[str, str] = {}- if plan is None:- return names- for attr in ("parts", "joints", "zones", "assets", "cameras", "effects"):- for item in getattr(plan, attr, None) or []:- names[to_snake(item.name)] = item.name- return names---def _canon_target(target: str, known: dict[str, str]) -> str:- """Plan name for ``target``; instance suffixes (``Leg_1``, ``leg.2``) keep the- suffix but take the plan's spelling of the base name."""- hit = known.get(to_snake(target))- if hit is not None:- return hit- base, suffix = _split_instance(target)- if suffix and to_snake(base) in known:- return f"{known[to_snake(base)]}_{suffix}"- snake = to_snake(target)- if snake.endswith("s") and snake[:-1] in known: # judges say "Legs" for the plan's "Leg"- return known[snake[:-1]]- return target---def _acceptance_target(item: AcceptanceItem, known: dict[str, str]) -> str:- """Route a failed acceptance item to the part it names, else 'overall'."""- words = item.text.lower()- for snake, name in known.items():- if snake.replace("_", " ") in words or snake in words:- return name- return "overall"diff --git a/harness/codeverse/orchestrator/rounds.py b/harness/codeverse/orchestrator/rounds.pydeleted file mode 100644index 11555b95..00000000--- a/harness/codeverse/orchestrator/rounds.py+++ /dev/null@@ -1,413 +0,0 @@-"""Round loop policy: when to stop, which round is best, what to refine next.--All thresholds live in ``RoundPolicy`` (one calibrated object, no scattered-ifs). ``StopPolicy.evaluate`` is a pure function of the round history;-``BestSelector.pick`` is a pure function of the rounds. Compiling gate errors-+ failed acceptance + the judge's improvement plan into typed ``RefineTask``s-(and grouping them by file ownership) lives in the sibling module-``codeverse.orchestrator.refine_tasks``; its public names are re-exported at-the bottom of this file so existing importers keep working.--**Two money stops** were added from the cost audit (docs/COST.md §5), both-measured against the judge's own noise rather than a magic constant — the-per-model σ table lives in ONE place, ``codeverse.cost.routing.JUDGE_NOISE``-(pro 0.030, flash 0.083), and is read here through :func:`judge_sigma`:--* ``regression`` — a refine round that scored more than 1 σ *below* the best is- not evidence that another round of the same shape will do better. The first- such round switches strategy (one whole-artifact rewrite instead of the same- per-part task set); a second one stops the run. 19 rounds in the audit scored- below the best and were thrown away ($14.23); this rule governs what the loop- is allowed to do *after* one of them (measured replay: 4 rounds re-shaped, and- a hard stop instead would have killed the recovery round that made- ``furn_hard_rolltop_desk`` pass).-* ``diminishing_returns`` — from r03 on, a round only runs when the previous- round gained more than 1.5 σ and the run is still below target. r03 cost- $33.49 per score point in the audit, against $4.93 for r01.-"""--from __future__ import annotations--import logging-from collections.abc import Sequence-from dataclasses import dataclass, replace-from typing import Literal--from codeverse.contracts.run import RoundRecord--log = logging.getLogger(__name__)--StopReason = Literal["pass", "plateau", "budget", "continue", "max_rounds", "judge_unavailable",- "regression", "diminishing_returns"]--#: what the next round should look like when the loop continues-Strategy = Literal["same", "switch", "detail"]--#: ``RoundRecord.kind`` of a round that already changed strategy after a regression-REWRITE_KIND = "rewrite"-#: ``RoundRecord.kind`` of the surface-detail round (see :func:`detail_round_due`)-DETAIL_KIND = "detail"--#: ``Strategy`` → the ``RoundRecord.kind`` the loop stamps on the round it starts-KIND_FOR_STRATEGY: dict[str, str] = {"same": "refine", "switch": REWRITE_KIND, "detail": DETAIL_KIND}---def kind_for_strategy(strategy: str) -> str:- """THE mapping from a stop decision's strategy to the round kind it produces."""- return KIND_FOR_STRATEGY.get(strategy, "refine")--#: σ for a judge that is not in the measured table: the default judge's-#: (``gemini-3.1-pro-preview``, ``Settings.default_judge``), because that is what-#: an unnamed judge almost always is. Calibrate a new judge-#: (``python -m codeverse.judges.calibration``) and add it to JUDGE_NOISE rather-#: than tuning the multipliers around it.-DEFAULT_JUDGE_SIGMA = 0.030---def judge_sigma(judge_model: str = "", *, default: float = DEFAULT_JUDGE_SIGMA) -> float:- """Measured score noise (std) of one judge model.-- The numbers come from ``judges/calibration.py`` (n=3 on the e2e rounds) and- are tabulated ONCE in :data:`codeverse.cost.routing.JUDGE_NOISE`; this is- the only reader in the orchestrator. Accepts a bare model name or a full- backend id (``gemini:gemini-3.1-pro-preview``)."""- name = (judge_model or "").strip().split(":")[-1]- if not name:- return default- try:- from codeverse.cost.routing import JUDGE_NOISE- except Exception as e: # noqa: BLE001 — the cost package is optional at import time- log.debug("judge noise table unavailable: %s", e)- return default- hit = JUDGE_NOISE.get(name)- if hit is None: # version suffixes: gemini-3.7-flash-002 → gemini-3.7-flash- hit = next((v for k, v in JUDGE_NOISE.items() if name.startswith(k)), None)- return float(hit[0]) if hit else default---@dataclass(frozen=True)-class RoundPolicy:- """Calibrated knobs for the refine loop."""-- max_rounds: int = 4 # refine rounds AFTER the baseline- plateau_window: int = 2 # consecutive scored rounds without min_delta gain- min_delta: float = 0.02- target: float = 0.8 # rubric pass threshold (overridden from the rubric when known)- judge_on_gate_errors: bool = True # still judge when gates (not build) fail- max_refine_tasks: int = 6- max_instructions_per_task: int = 6 # lines handed to ONE generation task (grouped by target)- parallel_min_tasks: int = 2 # fan out only when >= this many file-disjoint groups- n_candidates: int = 1 # best-of-N baseline (candidates generated in parallel, best kept)- pairwise_margin: float = 0.03 # |Δscore| below this = judge noise → pairwise tie-break- pairwise_min_confidence: float = 0.6 # new round replaces best only when pairwise is this sure- judge_samples: int = 1 # VLM judge samples per round (flash: std ≈ 0.001 between samples → 1 is enough)- # ---- money stops (docs/COST.md §5); thresholds are multiples of the judge's measured σ- judge_model: str = "" # judge backend id → σ via judge_sigma(); "" = the default judge's σ- regression_sigma: float = 1.0 # a round below (best − this × σ) regressed: change shape or stop- regression_allow_switch: bool = True # False = a regression stops the run outright- marginal_sigma: float = 1.5 # from marginal_from_round on, the last gain must beat this × σ- marginal_from_round: int = 3 # first refine round index the marginal-value test applies to- # ---- agent session shape. A 28-turn cap was TESTED AND REJECTED: a controlled- # A/B on one prompt (n=3 per arm, same generator/judge/budget) cost $1.381 mean at- # 0.479 mean score capped, against $1.360 at 0.684 uncapped — no saving and −0.205- # score (docs/COST.md §17). 0 = no policy cap: the session runs under the backend's- # own AgentJob.max_turns. Callers who want one set it explicitly (cost profiles do).- agent_max_turns: int = 0 # model turns one generation session may take (0 = uncapped)- agent_wrapup_turns: int = 6 # turns granted to land a final build + summary when a cap IS set- # ---- depth. Measured (wave "generation-depth"): across 88 consecutive refine-round pairs the- # built part count changed ZERO times and mean Δgeometry_detail was +0.003 — the refine loop is- # a repair loop and never adds anything. The rounds that DID add geometry did it while assembly- # was still broken and lost 0.075 of assembly_fit / 0.025 of overall for it. So detail gets its- # own round, and it only runs once the structure gates are clean.- detail_rounds: int = 0 # surface-detail rounds a run may spend (0 = off; tracks that implement- # the round opt in — see lifecycle.BaseTrack.supports_detail_round)- detail_min_score: float = 0.45 # below this the object is still wrong; detail would be polish on a mistake- detail_bbox_tol_m: float = 0.005 # a detail round that moves a part box by more than this failed its brief-- def with_candidates(self, n: int | None) -> RoundPolicy:- """Copy with ``n_candidates`` set (``None`` → unchanged)."""- if n is None or n == self.n_candidates:- return self- return replace(self, n_candidates=max(1, int(n)))-- def with_judge(self, judge_model: str | None) -> RoundPolicy:- """Copy that knows which judge scores the rounds (its σ sizes both money stops)."""- if not judge_model or judge_model == self.judge_model:- return self- return replace(self, judge_model=judge_model)-- @property- def sigma(self) -> float:- """Measured judge noise for this run's judge (see :func:`judge_sigma`)."""- return judge_sigma(self.judge_model)-- @property- def regression_delta(self) -> float:- """How far below the best a round must score to count as a regression."""- return self.regression_sigma * self.sigma-- @property- def marginal_delta(self) -> float:- """Gain the previous round must have produced for r03+ to be worth starting."""- return self.marginal_sigma * self.sigma---def meaningful_regression(score: float | None, before: float | None, policy: RoundPolicy) -> bool:- """Did ``score`` fall below ``before`` by MORE than this judge's own noise?-- THE regression predicate: ``StopPolicy._regression`` (the stop gate) and- ``StopPolicy._regressions`` (the counter behind "a second regression stops- the run") both call it, so they cannot drift apart. The scale is the- measured per-judge sigma table via ``policy.regression_delta`` — deliberately- NOT the 0.202 A/A replay floor, which measures cross-run planner variance,- not judge noise."""- if score is None or before is None:- return False- return (before - score) > policy.regression_delta---@dataclass(frozen=True)-class StopDecision:- """``StopPolicy``'s answer: stop (and why), or continue (and in what shape)."""-- reason: StopReason- strategy: Strategy = "same"- detail: str = ""-- @property- def stop(self) -> bool:- return self.reason != "continue"-- def event(self) -> dict[str, object]:- return {"reason": self.reason, "strategy": self.strategy, "detail": self.detail}---class StopPolicy:- """Decide whether the loop goes on. ``history`` = rounds so far (baseline first)."""-- def __init__(self, policy: RoundPolicy):- self.policy = policy-- def decide(self, history: Sequence[RoundRecord], *, budget_ok: bool = True) -> StopReason:- """The stop reason only (``evaluate`` also says what shape the next round takes)."""- return self.evaluate(history, budget_ok=budget_ok).reason-- def evaluate(self, history: Sequence[RoundRecord], *, budget_ok: bool = True) -> StopDecision:- if not budget_ok:- return StopDecision("budget")- if not history:- return StopDecision("continue")- last = history[-1]- if last.judgment is not None and last.judgment.passed and last.judgment.overall >= self.policy.target:- return StopDecision("pass")- refine_rounds = len(history) - 1- if refine_rounds >= self.policy.max_rounds:- return StopDecision("max_rounds")- # Order is the economics. A regression whose strategy switch is already spent- # is the most specific answer there is, so it comes first. Otherwise the- # marginal-value test decides late rounds (at r03 no *shape* is worth $0.5),- # and only before that does a first regression buy one change of shape.- # Plateau is the fallback: the same money statement, less precisely.- exhausted = self._regression(history, switch=False)- if exhausted is not None:- return self._maybe_detail(history, exhausted)- marginal = self._diminishing(history)- if marginal is not None:- return self._maybe_detail(history, marginal)- regressed = self._regression(history)- if regressed is not None:- return regressed- if self._plateaued(history):- return self._maybe_detail(history, StopDecision("plateau"))- return StopDecision("continue")-- def _maybe_detail(self, history: Sequence[RoundRecord], stop: StopDecision) -> StopDecision:- """Convert a "we are done repairing" stop into ONE surface-detail round.-- Only from a stop the loop was going to take anyway, so the detail round is- never bought instead of a repair round — and only on a clean, best-scoring- artifact, because the rounds that added geometry while assembly was still- broken measurably lost score (module docstring / ``detail_rounds``)."""- if stop.reason not in ("plateau", "diminishing_returns"):- return stop- why = detail_blocked(history, self.policy)- if why:- return stop- return StopDecision("continue", strategy="detail",- detail=f"structure clean at r{history[-1].index:02d} → one surface-detail round "- f"({stop.reason} otherwise)")-- # ---------------------------------------------------------------- money stops- def _regression(self, history: Sequence[RoundRecord], *, switch: bool = True) -> StopDecision | None:- """The last round scored below the best by more than the judge's own noise.-- Another round of the SAME shape is not justified by that evidence: the- first regression buys one change of strategy (a whole-artifact rewrite),- a second one — or one after a rewrite already failed to recover — stops- the run. ``switch=False`` asks only "is the switch already spent?", which- is the question that outranks every other stop."""- last = history[-1]- score, best_before = last.score, best_score(history[:-1])- if not meaningful_regression(score, best_before, self.policy):- return None- drop = best_before - score- detail = (f"r{last.index:02d} scored {score:.3f} vs best {best_before:.3f} "- f"({-drop:+.3f}, judge σ {self.policy.sigma:.3f})")- if not self.policy.regression_allow_switch:- return StopDecision("regression", detail=detail)- if last.kind == REWRITE_KIND or self._regressions(history) > 1:- return StopDecision("regression", detail=detail + " — a changed strategy did not recover it")- return StopDecision("continue", strategy="switch", detail=detail) if switch else None-- def _diminishing(self, history: Sequence[RoundRecord]) -> StopDecision | None:- """From ``marginal_from_round`` on, only run when the last round actually- bought something (> ``marginal_sigma`` × σ) and the target is still open."""- nxt = len(history)- if nxt < self.policy.marginal_from_round:- return None- gain = last_gain(history)- best = best_score(history)- need = self.policy.marginal_delta- if gain is None:- return None- if gain <= need:- return StopDecision("diminishing_returns",- detail=f"r{nxt:02d} not started: last gain {gain:+.3f} ≤ {need:.3f} "- f"(1.5 × judge σ {self.policy.sigma:.3f})")- if best is not None and best >= self.policy.target:- return StopDecision("diminishing_returns",- detail=f"r{nxt:02d} not started: best {best:.3f} already at target "- f"{self.policy.target:.2f}")- return None-- def _regressions(self, history: Sequence[RoundRecord]) -> int:- """How many scored rounds ended MEANINGFULLY below the best of everything- before them. Same predicate as the gate (:func:`meaningful_regression`),- so a sub-noise dip can never help burn the run's single strategy switch- (a -0.005 blip + one real regression used to count 2 = "regression" stop- with the switch never offered)."""- return sum(1 for i in range(1, len(history))- if meaningful_regression(history[i].score, best_score(history[:i]), self.policy))-- def _plateaued(self, history: Sequence[RoundRecord]) -> bool:- """True when the last ``plateau_window`` scored rounds did not raise the best- score by ``min_delta``. Rounds without a judgment (build failures) do not- count as evidence of a plateau: a pending repair explains a flat score."""- scored = [r for r in history if r.score is not None]- w = self.policy.plateau_window- if len(scored) < w + 1:- return False- before = max(r.score for r in scored[:-w]) # type: ignore[type-var]- after = max(r.score for r in scored[-w:]) # type: ignore[type-var]- return (after - before) < self.policy.min_delta---def detail_blocked(history: Sequence[RoundRecord], policy: RoundPolicy) -> str:- """"" when a surface-detail round is due; otherwise the reason it is not.-- A detail round is worth money only on an artifact whose STRUCTURE is finished:- the last round built, has no gate ERROR, scored at least ``detail_min_score``- and is within one judge σ of the best round in the run. Anything else and the- money belongs to repair (measured: refine rounds that added > 2000 triangles- while assembly was still broken lost 0.075 of assembly_fit)."""- if policy.detail_rounds <= 0:- return "detail rounds disabled"- spent = sum(1 for r in history if r.kind == DETAIL_KIND)- if spent >= policy.detail_rounds:- return f"{spent} detail round(s) already spent"- if not history:- return "no rounds yet"- last = history[-1]- if last.build is None or not last.build.ok:- return "last round did not build"- if gate_error_count(last) > 0:- return f"{gate_error_count(last)} gate error(s) still open"- if last.score is None:- return "last round was not judged"- if last.score < policy.detail_min_score:- return f"score {last.score:.3f} < detail floor {policy.detail_min_score:.2f}"- best = best_score(history)- if best is not None and last.score < best - policy.sigma:- return f"last round {last.score:.3f} is below best {best:.3f} by more than σ"- return ""---def best_score(history: Sequence[RoundRecord]) -> float | None:- """Best judged score in ``history`` (``None`` when nothing was scored)."""- scores = [r.score for r in history if r.score is not None]- return max(scores) if scores else None---def last_gain(history: Sequence[RoundRecord]) -> float | None:- """How much the LAST round moved the best score (``None`` when unscored).-- Negative when it regressed; 0.0 when it changed nothing measurable."""- if len(history) < 2 or history[-1].score is None:- return None- before = best_score(history[:-1])- if before is None:- return None- return float(history[-1].score) - before---def best_index(rounds: Sequence[tuple[float, int]]) -> int:- """Index of the best round: higher score, tie → fewer errors, tie → later round."""- if not rounds:- raise ValueError("best_index needs at least one round")- best = 0- for i, (score, n_err) in enumerate(rounds):- bs, be = rounds[best]- if score > bs or (score == bs and n_err < be) or (score == bs and n_err == be):- best = i- return best---class BestSelector:- """Best round = highest score, then fewer gate errors, then later.-- ``best_index`` above owns the ranking rule. A round that- did not build is never picked (it has no score, and delivering code that does- not run is never an improvement); when NO round has a score the fallback is- the built round with the fewest gate errors — later on a tie — so a round that- broke the gates cannot displace a clean earlier artifact just by being last."""-- def pick(self, rounds: Sequence[RoundRecord]) -> int | None:- scored = [(i, r) for i, r in enumerate(rounds) if r.score is not None and not _build_failed(r)]- if scored:- k = best_index([(float(r.score), gate_error_count(r)) for _, r in scored]) # type: ignore[arg-type]- return scored[int(k)][0]- built = [i for i, r in enumerate(rounds) if r.build is not None and r.build.ok]- if not built:- return None- return min(built, key=lambda i: (gate_error_count(rounds[i]), -i))---def gate_error_count(r: RoundRecord) -> int:- return sum(len(g.errors) for g in r.gates)---def _build_failed(r: RoundRecord) -> bool:- """The round is KNOWN not to build (a record with no build at all is not a failure:- resumed/rejudged records may carry a score without one)."""- return r.build is not None and not r.build.ok---# ----------------------------------------------------------------------------- refine tasks-# Moved to codeverse.orchestrator.refine_tasks; imported here so existing importers-# (tracks/*, reference/mismatch, tests) keep working unchanged.-from codeverse.orchestrator.refine_tasks import ( # noqa: E402- RefineTask,- TaskGroup,- build_refine_instructions,- compact_instructions,- plan_parallel_groups,- plan_refine_groups,-)--__all__ = [- "BestSelector", "DEFAULT_JUDGE_SIGMA", "DETAIL_KIND", "KIND_FOR_STRATEGY",- "REWRITE_KIND", "RefineTask", "RoundPolicy", "StopDecision", "StopPolicy", "StopReason",- "Strategy", "TaskGroup", "best_score", "build_refine_instructions", "compact_instructions",- "detail_blocked", "gate_error_count", "judge_sigma", "kind_for_strategy", "last_gain",- "meaningful_regression", "plan_parallel_groups", "plan_refine_groups",-]diff --git a/harness/codeverse/orchestrator/runner.py b/harness/codeverse/orchestrator/runner.pydeleted file mode 100644index a9bb241f..00000000--- a/harness/codeverse/orchestrator/runner.py+++ /dev/null@@ -1,132 +0,0 @@-"""StageRunner: named, resumable stages with input-hash caching.--A *stage* is ``fn() -> result``. The runner hashes the declared ``inputs``;-when the hash matches the one recorded in ``RunState`` and the stage's result-file (``<ws>/stages/<name>.json``) exists, the cached result is returned-without running ``fn`` (content-addressed skip — no mtime heuristics).-Results may be pydantic models, lists of models, plain JSON values, or-``Path``s; pass ``model=`` to re-validate a cached JSON into its type.--The hash covers the *inputs* only, never the result model's schema, so a cached-file that no longer reads back — a contract that gained a field, a clobbered-write — is treated as a cache MISS and re-run rather than raising out of the-resume path.-"""--from __future__ import annotations--import hashlib-import json-import logging-import re-import time-from collections.abc import Callable-from pathlib import Path-from typing import Any, TypeVar--from pydantic import BaseModel--from codeverse.events import EventLog-from codeverse.orchestrator.state import RunState, StageState-from codeverse.workspace import Workspace--log = logging.getLogger(__name__)--T = TypeVar("T")--_SAFE = re.compile(r"[^0-9A-Za-z._-]+")---def hash_inputs(inputs: Any) -> str:- """Stable sha256 (12 hex) of arbitrary JSON-able inputs (pydantic ok)."""- payload = _jsonable(inputs)- blob = json.dumps(payload, sort_keys=True, default=str, ensure_ascii=False)- return hashlib.sha256(blob.encode()).hexdigest()[:12]---def _jsonable(obj: Any) -> Any:- if isinstance(obj, BaseModel):- return obj.model_dump(mode="json")- if isinstance(obj, Path):- return str(obj)- if isinstance(obj, dict):- return {str(k): _jsonable(v) for k, v in obj.items()}- if isinstance(obj, (list, tuple, set)):- return [_jsonable(v) for v in obj]- return obj---class StageRunner:- """Runs stages with resume semantics on top of ``RunState`` + ``EventLog``."""-- def __init__(self, ws: Workspace, events: EventLog, state: RunState | None = None):- self.ws = ws- self.events = events- self.state = state if state is not None else RunState()-- # ----------------------------------------------------------------- paths- def result_path(self, name: str) -> Path:- return self.ws.root / "stages" / f"{_SAFE.sub('_', name)}.json"-- # ----------------------------------------------------------------- api- def stage(- self,- name: str,- fn: Callable[[], T],- *,- inputs: Any = "",- force: bool = False,- model: type[BaseModel] | None = None,- list_of: type[BaseModel] | None = None,- ) -> T:- """Run ``fn`` unless a cached result for the same ``inputs`` exists."""- h = hash_inputs(inputs)- path = self.result_path(name)- prior = self.state.stages.get(name)- if not force and prior is not None and prior.inputs_hash == h and path.is_file():- # A cached result that cannot be read back is a cache MISS, not a dead run.- # ``inputs_hash`` covers the INPUTS only, never the result model's schema, so a- # contract that gained a field invalidates nothing — and a clobbered file- # invalidates nothing either. Both used to escape as ValidationError /- # JSONDecodeError through BaseTrack.run, which marks the run FAILED and- # re-raises, so every later `3dcv resume <slug>` died the same way with no way- # out (there is no flag to drop a cached stage). Re-run instead and- # overwrite the file — the same tolerance load_ledger and _read_jsonl apply.- try:- result = _revive(json.loads(path.read_text()), model, list_of)- except (OSError, ValueError) as e: # ValidationError is a ValueError- self.events.emit("stage.cache_invalid", stage=name, inputs_hash=h, path=str(path),- error=f"{type(e).__name__}: {e}")- log.warning("stage %s: cached result at %s is unusable (%s); re-running", name, path, e)- else:- self.events.emit("stage.cached", stage=name, inputs_hash=h, path=str(path))- return result # type: ignore[return-value]-- self.events.emit("stage.start", stage=name, inputs_hash=h)- t0 = time.time()- try:- result = fn()- except Exception as e:- self.events.emit("stage.failed", stage=name, error=f"{type(e).__name__}: {e}",- duration_s=round(time.time() - t0, 2))- raise- dt = time.time() - t0- path.parent.mkdir(parents=True, exist_ok=True)- self.ws.write_json(path, {"stage": name, "inputs_hash": h, "result": _jsonable(result)})- self.state.stages[name] = StageState(name=name, inputs_hash=h, result_path=str(path), duration_s=dt)- self.state.save(self.ws)- self.events.emit("stage.done", stage=name, inputs_hash=h, duration_s=round(dt, 2))- return result-- def is_done(self, name: str, inputs: Any = "") -> bool:- prior = self.state.stages.get(name)- return prior is not None and prior.inputs_hash == hash_inputs(inputs) and self.result_path(name).is_file()---def _revive(data: dict[str, Any], model: type[BaseModel] | None, list_of: type[BaseModel] | None) -> Any:- result = data.get("result")- if model is not None and isinstance(result, dict):- return model.model_validate(result)- if list_of is not None and isinstance(result, list):- return [list_of.model_validate(r) for r in result]- return resultdiff --git a/harness/codeverse/orchestrator/state.py b/harness/codeverse/orchestrator/state.pydeleted file mode 100644index 35516560..00000000--- a/harness/codeverse/orchestrator/state.py+++ /dev/null@@ -1,94 +0,0 @@-"""Persistent run state (``run_state.json``): what is done, what is best.--The state is the resume anchor. It records, per stage, the hash of the inputs-it ran with (so ``StageRunner`` can reuse a cached result), the rounds that-completed, and the best round/commit seen so far. Writes are atomic-(tmp + rename via ``Workspace.write_json``).-"""--from __future__ import annotations--from datetime import UTC, datetime-from typing import Any--from pydantic import BaseModel, Field, ValidationError--from codeverse.contracts.run import RunStatus-from codeverse.workspace import Workspace---class StageState(BaseModel):- """One completed stage: inputs hash + where its result JSON lives."""-- name: str- inputs_hash: str- result_path: str = ""- finished_at: datetime = Field(default_factory=lambda: datetime.now(UTC))- duration_s: float = 0.0---class RunState(BaseModel):- """Everything the orchestrator needs to resume a run."""-- status: RunStatus = RunStatus.PLANNING- stages: dict[str, StageState] = Field(default_factory=dict)- current_round: int = Field(default=0, description="index of the round in progress / next to run")- completed_rounds: list[int] = Field(default_factory=list)- round_commits: dict[int, str] = Field(default_factory=dict)- best_round: int | None = None- best_commit: str = ""- best_score: float | None = None- #: highest round index that has been THROUGH best selection (choose_best_round,- #: including its paid pairwise comparison). Persisted so a resume can tell- #: "the best was deliberately kept" from "this round was never considered" —- #: without it, a state that merely LOOKS consistent with the journal kept a- #: stale best and delivered the worse round (2026-08-27). -1 = nothing yet.- best_considered_through: int = -1- materialized_for: str = Field(default="", description="agent kind the workspace was materialised for")- stop_reason: str = ""- error: str = ""- started_at: datetime = Field(default_factory=lambda: datetime.now(UTC))- updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))- extra: dict[str, Any] = Field(default_factory=dict)-- # ----------------------------------------------------------------- persistence- @classmethod- def load(cls, ws: Workspace) -> RunState | None:- """Return the saved state or ``None`` when the file is absent."""- if not ws.state_path.is_file():- return None- try:- return cls.model_validate(ws.read_json(ws.state_path))- except (ValidationError, ValueError) as e:- raise StateCorrupt(f"{ws.state_path}: {e}") from e-- @classmethod- def load_or_new(cls, ws: Workspace, *, resume: bool) -> RunState:- if resume:- st = cls.load(ws)- if st is not None:- return st- return cls()-- def save(self, ws: Workspace) -> None:- self.updated_at = datetime.now(UTC)- ws.write_json(ws.state_path, self)-- # ----------------------------------------------------------------- helpers- def mark_round_done(self, index: int, commit: str, ws: Workspace | None = None) -> None:- if index not in self.completed_rounds:- self.completed_rounds.append(index)- self.round_commits[index] = commit- self.current_round = index + 1- if ws is not None:- self.save(ws)-- def update_best(self, index: int, commit: str, score: float | None) -> bool:- """Record ``index`` as best; returns True when it changed."""- changed = self.best_round != index- self.best_round, self.best_commit, self.best_score = index, commit, score- return changed---class StateCorrupt(RuntimeError):- """``run_state.json`` exists but does not validate — refuse to guess."""diff --git a/harness/codeverse/reference.py b/harness/codeverse/reference.pyindex 627e4ceb..07feec45 100644--- a/harness/codeverse/reference.py+++ b/harness/codeverse/reference.py@@ -916,7 +916,7 @@ def _measured_block(diff: ReferenceDiff) -> str:def refine_tasks(diff: ReferenceDiff, *, top: int = TOP_TASKS) -> list[Any]:"""The top mismatches as priority-1 ``RefineTask``s (``source='gate'`` so theround policy protects them from being trimmed as judge chatter)."""- from codeverse.orchestrator.rounds import RefineTask+ from codeverse.orchestrator import RefineTaskout = []for m in diff.top(top):diff --git a/harness/codeverse/tracks/candidates.py b/harness/codeverse/tracks/candidates.pyindex 76c2e98b..324d06bc 100644--- a/harness/codeverse/tracks/candidates.py+++ b/harness/codeverse/tracks/candidates.py@@ -31,8 +31,7 @@ from codeverse.contracts.common import Usagefrom codeverse.contracts.run import RoundRecordfrom codeverse.conventions import OBJECT_VIEWS_QUICKfrom codeverse.fanout import fan_out-from codeverse.orchestrator.budget import BudgetExceeded-from codeverse.orchestrator.rounds import BestSelector+from codeverse.orchestrator import BestSelector, BudgetExceededfrom codeverse.tracks.common import RunContextfrom codeverse.tracks.generation import GenerationTaskfrom codeverse.tracks.repair import build_with_repairdiff --git a/harness/codeverse/tracks/common.py b/harness/codeverse/tracks/common.pyindex 1125efc6..aff03cbb 100644--- a/harness/codeverse/tracks/common.py+++ b/harness/codeverse/tracks/common.py@@ -21,9 +21,7 @@ from codeverse.contracts.plan import CameraPlan, Planfrom codeverse.contracts.run import RunRecordfrom codeverse.conventions import ViewPresetfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetGuard-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import BudgetGuard, RoundPolicy, RunStatefrom codeverse.prompts import load_text, prompt_hashfrom codeverse.tracks.generation import is_single_shotfrom codeverse.workspace import Workspacediff --git a/harness/codeverse/tracks/generation.py b/harness/codeverse/tracks/generation.pyindex ff96e55f..8faad88f 100644--- a/harness/codeverse/tracks/generation.py+++ b/harness/codeverse/tracks/generation.py@@ -701,7 +701,7 @@ class _SessionAcc:def _is_budget_stop(e: BaseException) -> bool:- from codeverse.orchestrator.budget import BudgetExceeded+ from codeverse.orchestrator import BudgetExceededreturn isinstance(e, BudgetExceeded)diff --git a/harness/codeverse/tracks/graphics.py b/harness/codeverse/tracks/graphics.pyindex 30174e7d..bda8da6c 100644--- a/harness/codeverse/tracks/graphics.py+++ b/harness/codeverse/tracks/graphics.py@@ -35,7 +35,7 @@ from codeverse.languages._gl_common import SHEET_NAME, read_metricsfrom codeverse.languages.glsl_shader.lint import FUNC_DEFfrom codeverse.languages.glsl_shader.skeleton import COMMON_GLSLfrom codeverse.languages.glsl_shader.wrap import strip_comments-from codeverse.orchestrator.rounds import TaskGroup+from codeverse.orchestrator import TaskGroupfrom codeverse.prompts import renderfrom codeverse.spatial.cookbook_tool import Section, split_sectionsfrom codeverse.tracks.common import RunContextdiff --git a/harness/codeverse/tracks/lifecycle.py b/harness/codeverse/tracks/lifecycle.pyindex 936168e8..5b73b60e 100644--- a/harness/codeverse/tracks/lifecycle.py+++ b/harness/codeverse/tracks/lifecycle.py@@ -26,22 +26,25 @@ from codeverse.contracts.plan import Planfrom codeverse.contracts.run import RoundRecord, RunRecord, RunStatusfrom codeverse.contracts.spec import Specfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard, BudgetSnapshot-from codeverse.orchestrator.rounds import (+from codeverse.orchestrator import (BestSelector,+ BudgetExceeded,+ BudgetGuard,+ BudgetSnapshot,RefineTask,RoundPolicy,+ RunState,+ StageRunner,StopPolicy,StopReason,Strategy,TaskGroup,best_score,build_refine_instructions,+ hash_inputs,kind_for_strategy,plan_refine_groups,)-from codeverse.orchestrator.runner import StageRunner, hash_inputs-from codeverse.orchestrator.state import RunStatefrom codeverse.prompts import renderfrom codeverse.tracks.candidates import choose_best_round, run_best_of_nfrom codeverse.tracks.common import (diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.pyindex 1db478be..7d7291b9 100644--- a/harness/codeverse/tracks/scene.py+++ b/harness/codeverse/tracks/scene.py@@ -39,8 +39,7 @@ from codeverse.contracts.plan import Plan, ScenePlan, ZonePlanfrom codeverse.contracts.run import RoundRecordfrom codeverse.conventions import to_snakefrom codeverse.fanout import fan_out-from codeverse.orchestrator.rounds import TaskGroup, compact_instructions-from codeverse.orchestrator.runner import StageRunner+from codeverse.orchestrator import StageRunner, TaskGroup, compact_instructionsfrom codeverse.prompts import renderfrom codeverse.spatial.frame_motion import motion_text_forfrom codeverse.spatial.render_scene import JUDGE_MAX_VIEWS, perf_detaildiff --git a/harness/codeverse/tracks/scene_assets.py b/harness/codeverse/tracks/scene_assets.pyindex 20802aa8..8909d559 100644--- a/harness/codeverse/tracks/scene_assets.py+++ b/harness/codeverse/tracks/scene_assets.py@@ -177,7 +177,7 @@ def build_threejs_asset(ctx: RunContext, asset: AssetPlan, *, judge: bool) -> Asres = _generate_asset(sub, asset, rel, language=Language.SCENE_THREEJS, attempt=attempt,feedback=repair_feedback(chk, rel) if chk is not None else "")except Exception as e: # noqa: BLE001 — a bad answer escalates; a dead model does not- from codeverse.orchestrator.budget import BudgetExceeded+ from codeverse.orchestrator import BudgetExceededif isinstance(e, BudgetExceeded):raisediff --git a/harness/codeverse/tracks/static_object.py b/harness/codeverse/tracks/static_object.pyindex a9663e7f..37544245 100644--- a/harness/codeverse/tracks/static_object.py+++ b/harness/codeverse/tracks/static_object.py@@ -32,7 +32,7 @@ from codeverse.conventions import (to_pascal,to_snake,)-from codeverse.orchestrator.rounds import DETAIL_KIND, RefineTask, TaskGroup, compact_instructions+from codeverse.orchestrator import DETAIL_KIND, RefineTask, TaskGroup, compact_instructionsfrom codeverse.prompts import renderfrom codeverse.tracks.common import RunContextfrom codeverse.tracks.depth import (diff --git a/harness/codeverse/tracks/steps.py b/harness/codeverse/tracks/steps.pyindex 027cfe05..dff22b45 100644--- a/harness/codeverse/tracks/steps.py+++ b/harness/codeverse/tracks/steps.py@@ -33,7 +33,7 @@ from codeverse.contracts.judgment import Judgmentfrom codeverse.contracts.plan import AcceptanceItem, Planfrom codeverse.contracts.run import RoundRecordfrom codeverse.fanout import fan_out-from codeverse.orchestrator.budget import usage_delta+from codeverse.orchestrator import usage_deltafrom codeverse.spatial.render import RenderErrorfrom codeverse.tracks import skills_hookfrom codeverse.tracks.common import RunContext@@ -137,7 +137,7 @@ def _run_phase(ctx: RunContext, tasks: Sequence[GenerationTask]) -> list[Generatbudget_stop: Exception | None = Nonefor task, r in zip(tasks, results, strict=True):if isinstance(r, Exception):- from codeverse.orchestrator.budget import BudgetExceeded+ from codeverse.orchestrator import BudgetExceededif isinstance(r, BudgetExceeded) and budget_stop is None:budget_stop = r # a failed item; the siblings' paid results still land in ``out``diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 01a6230e..d045f7cb 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -154,8 +154,8 @@ codeverse/texturing/ plan.py (VLM material plan), generate.py (+ tile.py seam fix), uv.py (world-metreunwrap), apply.py, gate.py (seam + before/after judge), scene_pack.py, run.py (texture_pass),maps.py (PBR map set), materials.py (named material library), normalise.py- orchestrator/ runner.py, state.py, rounds.py (RoundPolicy, StopPolicy, BestSelector), refine_tasks.py- (RefineTask compilation + file-ownership grouping + compaction), budget.py+ orchestrator.py stage runner with resume, run state, round loop (RoundPolicy,+ StopPolicy, BestSelector), refine-task compilation + grouping, budgettracks/ __init__.py (get_track(track, **options) + the TrackPipeline protocol),lifecycle.py, steps.py, candidates.py (best-of-N + the pure candidate/pairwisedecision logic), generation.py (agent + single-shot strategies + the filediff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 0db3a26b..8fa925dc 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -310,7 +310,7 @@ from codeverse.tracks import get_trackrec = get_track(spec.track, **options).run(spec, ws, resume=False) -> RunRecord # Δ kwargs forwarded to the constructor:# services=, judge=, agent=, model=, runtime=, policy=RoundPolicy, settings=, planner_model=, n_candidates=# (CLI --candidates > run_state.extra > settings.default_candidates); StaticObject | Articulated | Scene | Graphics-from codeverse.orchestrator.rounds import RoundPolicy, StopPolicy, StopDecision, BestSelector, judge_sigma, \+from codeverse.orchestrator import RoundPolicy, StopPolicy, StopDecision, BestSelector, judge_sigma, \best_score, last_gain, REWRITE_KIND, build_refine_instructions, compact_instructionsRoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, judge_on_gate_errors=True, max_refine_tasks=6,max_instructions_per_task=6, parallel_min_tasks=2, n_candidates=1, pairwise_margin=0.03,@@ -328,8 +328,8 @@ StopPolicy(policy).evaluate(history, budget_ok=True) -> StopDecision(reason, str# .decide(...) -> StopReason is unchanged; strategy "switch" = ONE whole-artifact rewrite round (kind REWRITE_KIND),# "detail" = ONE surface-detail round (kind DETAIL_KIND) — a plateau/diminishing stop is converted into it# only when detail_blocked(history, policy) == "" (clean gates, built, judged, within σ of best, budget left)-from codeverse.orchestrator.rounds import DETAIL_KIND, kind_for_strategy, detail_blocked # THE strategy → kind map-from codeverse.orchestrator.budget import BudgetGuard, usage_delta+from codeverse.orchestrator import DETAIL_KIND, kind_for_strategy, detail_blocked # THE strategy → kind map+from codeverse.orchestrator import BudgetGuard, usage_deltaBudgetGuard(budget, *, soft_fraction=1.0, run="", ledger=None).spend(usage, *, stage="other", role=None, label="", round_index=None, outcome="ok", enforce=True)# THE door every dollar goes through: accumulate → bucket by stage/round → one priced ledger rowdiff --git a/harness/tests/core/test_contract_additions.py b/harness/tests/core/test_contract_additions.pyindex bb552e71..5aaefd1c 100644--- a/harness/tests/core/test_contract_additions.py+++ b/harness/tests/core/test_contract_additions.py@@ -141,7 +141,7 @@ def test_spec_options_roundtrip_and_validation():def test_spec_options_do_not_change_the_plan_stage_hash():- from codeverse.orchestrator.runner import hash_inputs+ from codeverse.orchestrator import hash_inputsfrom codeverse.tracks.lifecycle import plan_stage_inputsplain = Spec(id="x", track=Track.STATIC_OBJECT, language=Language.BLENDER, prompt="a chair")diff --git a/harness/tests/flywheel_cli/test_cli.py b/harness/tests/flywheel_cli/test_cli.pyindex 5e2092d7..82706d09 100644--- a/harness/tests/flywheel_cli/test_cli.py+++ b/harness/tests/flywheel_cli/test_cli.py@@ -287,7 +287,7 @@ def test_resume_refuses_a_finished_run_and_never_re_enters_it(made_run, stub_traback to 'planning' — a finished run left stuck mid-pipeline, and money spent, fromone accidental or scripted resume."""from codeverse.contracts.run import RunStatus- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatefrom codeverse.workspace import Workspaceruns, run_dir = made_run()diff --git a/harness/tests/graphics/test_live.py b/harness/tests/graphics/test_live.pyindex 83ae4124..e9372a22 100644--- a/harness/tests/graphics/test_live.py+++ b/harness/tests/graphics/test_live.py@@ -33,7 +33,7 @@ def keys_ok():def test_live_plan_generate_build_judge(tmp_path, keys_ok):from codeverse.events import EventLogfrom codeverse.models import get_chat_model- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatefrom codeverse.prompts import renderspec = Spec(id="live_gfx", track=Track.GRAPHICS, language=Language.GLSL_SHADER,diff --git a/harness/tests/graphics/test_track.py b/harness/tests/graphics/test_track.pyindex ea278232..0f25fc00 100644--- a/harness/tests/graphics/test_track.py+++ b/harness/tests/graphics/test_track.py@@ -232,7 +232,7 @@ def test_templates_render_and_rubric_loads(tmp_path, settings):spec = make_spec(language=Language.OPENGL_PYTHON, generator="single-shot:fake:fake-model")ws = Workspace(tmp_path / "runs" / "tpl").create()track = GraphicsTrack(services=_services(), settings=settings, runtime=FakeGlRuntime())- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatectx = track.build_context(spec, ws, EventLog(ws.events_path), RunState.load_or_new(ws, resume=False))ctx.plan = GraphicsPlan.model_validate(plan_example())diff --git a/harness/tests/orchestrator_tracks/test_best_index.py b/harness/tests/orchestrator_tracks/test_best_index.pyindex c9077957..56fbe824 100644--- a/harness/tests/orchestrator_tracks/test_best_index.py+++ b/harness/tests/orchestrator_tracks/test_best_index.py@@ -5,7 +5,7 @@ from __future__ import annotationsimport pytest-from codeverse.orchestrator.rounds import best_index+from codeverse.orchestrator import best_indexdef test_best_index():diff --git a/harness/tests/orchestrator_tracks/test_budget_snapshot.py b/harness/tests/orchestrator_tracks/test_budget_snapshot.pyindex cb0e3f95..66067725 100644--- a/harness/tests/orchestrator_tracks/test_budget_snapshot.py+++ b/harness/tests/orchestrator_tracks/test_budget_snapshot.py@@ -21,8 +21,7 @@ from codeverse.contracts.common import Budget, Language, Usagefrom codeverse.contracts.plan import StaticPlanfrom codeverse.contracts.run import RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard, BudgetSnapshot-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import BudgetExceeded, BudgetGuard, BudgetSnapshot, RunStatefrom codeverse.tracks.generation import GenerationTask, generate_filesfrom codeverse.tracks.planner import MAX_VALIDATION_REASKS, PlanningErrorfrom codeverse.tracks.planner import plan as run_plannerdiff --git a/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py b/harness/tests/orchestrator_tracks/test_candidates_reference_motion.pyindex 76b3c634..0413b0fd 100644--- a/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py+++ b/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py@@ -12,7 +12,7 @@ from codeverse.contracts.plan import ArticulatedPlanfrom codeverse.contracts.run import RunStatusfrom codeverse.contracts.spec import ReferenceImagefrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import (+from codeverse.orchestrator import (RefineTask,RoundPolicy,build_refine_instructions,@@ -188,7 +188,7 @@ def test_candidate_count_persists_for_resume_and_settings_default(tmp_path, chai# a resume without the flag reads the persisted widtht2 = StaticObjectTrack(services=FakeServices(), judge=FakeJudge(scores=(0.5,)), agent=FakeAgent(_writer_by_candidate),planner_model=_planner(chair_plan.model_dump(mode="json")), settings=settings, runtime=FakeRuntime(Language.BLENDER))- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatectx = t2.build_context(spec, ws, EventLog(ws.events_path), RunState.load(ws))assert ctx.policy.n_candidates == 2@@ -310,7 +310,7 @@ def test_expected_files_and_targets_follow_runtime_file_for_part(tmp_path, chairspec = make_spec(language=Language.BLENDER, max_rounds=0)track = StaticObjectTrack(services=FakeServices(), settings=settings, runtime=PartsRuntime(Language.BLENDER))- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatectx = track.build_context(spec, Workspace(tmp_path / "ws").create(), EventLog(tmp_path / "e.jsonl"), RunState())ctx.plan = chair_plandiff --git a/harness/tests/orchestrator_tracks/test_cost_accounting.py b/harness/tests/orchestrator_tracks/test_cost_accounting.pyindex 7bcf8182..0e26e06b 100644--- a/harness/tests/orchestrator_tracks/test_cost_accounting.py+++ b/harness/tests/orchestrator_tracks/test_cost_accounting.py@@ -19,7 +19,7 @@ import pytestfrom codeverse.contracts.agent import AgentJob, AgentResultfrom codeverse.contracts.common import Budget, Usagefrom codeverse.cost.ledger import load_ledger-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard, usage_delta+from codeverse.orchestrator import BudgetExceeded, BudgetGuard, usage_deltafrom codeverse.tracks.generation import GenerationTask, _SessionAccFIXTURES = json.loads((Path(__file__).parent / "data" / "offrecord_runs.json").read_text())["runs"]@@ -157,7 +157,7 @@ def test_a_subscription_backend_does_not_consume_the_spend_guard():The run's own cost ledger said $0.00; only the guard disagreed."""from codeverse.contracts.common import Budget, Usage- from codeverse.orchestrator.budget import BudgetGuard+ from codeverse.orchestrator import BudgetGuardg = BudgetGuard(Budget(max_usd=8.0, max_minutes=60.0), soft_fraction=0.55)g.spend(Usage(backend="codex", model="gpt-5.6-sol", cost_usd=7.712), enforce=False)@@ -175,7 +175,7 @@ def test_the_guard_still_enforces_backends_that_really_bill():"""The exemption must not become a hole: API backends keep both ceilings, and anunclassified backend is enforced rather than exempted."""from codeverse.contracts.common import Budget, Usage- from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard+ from codeverse.orchestrator import BudgetExceeded, BudgetGuardg = BudgetGuard(Budget(max_usd=8.0, max_minutes=60.0), soft_fraction=0.55)g.spend(Usage(backend="codex", cost_usd=99.0), enforce=False) # free, ignoreddiff --git a/harness/tests/orchestrator_tracks/test_cost_latency.py b/harness/tests/orchestrator_tracks/test_cost_latency.pyindex a2003893..c9f453f7 100644--- a/harness/tests/orchestrator_tracks/test_cost_latency.py+++ b/harness/tests/orchestrator_tracks/test_cost_latency.py@@ -14,9 +14,7 @@ from codeverse.contracts.common import Budget, Language, Trackfrom codeverse.contracts.plan import AssetPlan, ScenePlan, ZonePlanfrom codeverse.contracts.run import RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import BudgetExceeded, BudgetGuard, RoundPolicy, RunStatefrom codeverse.tracks.common import RunContextfrom codeverse.tracks.planner import plan_examplefrom codeverse.tracks.scene import SceneTrack, plan_zone_batches, zone_file@@ -478,7 +476,7 @@ def test_a_generation_session_never_outlives_the_wall_budget():settings.limits.agent_timeout_s (1800 s) and only checked the ceiling at the nextboundary. The scene track had clipped this since the greenhouse incident."""from codeverse.contracts.spec import Budget- from codeverse.orchestrator.budget import BudgetGuard+ from codeverse.orchestrator import BudgetGuardg = BudgetGuard(Budget(max_usd=10.0, max_minutes=30.0, max_rounds=4), run="t")assert g.timeout_s(1800, floor_s=120.0) == pytest.approx(1800, abs=60) # fresh run: full session@@ -495,7 +493,7 @@ def test_one_asset_cannot_eat_the_scene_run():stage to 10.9 min — the stage waits for its slowest, so round 0 started at 18.9 minand the judged round only happened via the budget salvage at 25.5 min."""from codeverse.contracts.spec import Budget- from codeverse.orchestrator.budget import BudgetGuard+ from codeverse.orchestrator import BudgetGuardfrom codeverse.tracks.scene_assets import (ASSET_AGENT_TIMEOUT_S,ASSET_SESSION_SHARE,diff --git a/harness/tests/orchestrator_tracks/test_fewer_turns.py b/harness/tests/orchestrator_tracks/test_fewer_turns.pyindex 1d0e52f6..ceb41836 100644--- a/harness/tests/orchestrator_tracks/test_fewer_turns.py+++ b/harness/tests/orchestrator_tracks/test_fewer_turns.py@@ -7,7 +7,7 @@ import pytestfrom codeverse.config import FEWER_TURNS_ENV, Settings, fewer_turns_enabledfrom codeverse.contracts.common import Language-from codeverse.orchestrator.rounds import RefineTask, TaskGroup+from codeverse.orchestrator import RefineTask, TaskGroupfrom codeverse.tracks.plan_features import LIVE_SWITCHES, pin_plan_blockersfrom codeverse.tracks.prompting import INLINE_MAX_CHARS, INLINE_MAX_FILES, TURN_DISCIPLINE@@ -21,7 +21,7 @@ LEG = "import bpy\n\n\ndef build_leg():\n return bpy.context.object # LEG-BOdef _ctx(tmp_path, plan, settings, *, language=Language.BLENDER, agent_id="fake-agent:m"):from codeverse.events import EventLog- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatefrom codeverse.tracks.static_object import StaticObjectTrackfrom codeverse.workspace import Workspacediff --git a/harness/tests/orchestrator_tracks/test_fix_batch2.py b/harness/tests/orchestrator_tracks/test_fix_batch2.pyindex 766cef9a..3983bba9 100644--- a/harness/tests/orchestrator_tracks/test_fix_batch2.py+++ b/harness/tests/orchestrator_tracks/test_fix_batch2.py@@ -13,8 +13,7 @@ from codeverse.contracts.judgment import Judgmentfrom codeverse.contracts.plan import BBox, PartPlan, ScenePlan, StaticPlanfrom codeverse.contracts.run import RoundRecord, RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RoundPolicy, RunStatefrom codeverse.prompts import load_textfrom codeverse.tracks.planner import plan_examplefrom codeverse.tracks.scene import SceneTrackdiff --git a/harness/tests/orchestrator_tracks/test_generation_depth.py b/harness/tests/orchestrator_tracks/test_generation_depth.pyindex abb07f54..926c7fa6 100644--- a/harness/tests/orchestrator_tracks/test_generation_depth.py+++ b/harness/tests/orchestrator_tracks/test_generation_depth.py@@ -24,7 +24,7 @@ from codeverse.contracts.judgment import ImprovementItem, Judgmentfrom codeverse.contracts.plan import BBox, PartPlan, StaticPlanfrom codeverse.contracts.run import RoundRecordfrom codeverse.conventions import MAX_TRIS_OBJECT, to_snake-from codeverse.orchestrator.rounds import (+from codeverse.orchestrator import (DETAIL_KIND,REWRITE_KIND,RoundPolicy,@@ -240,7 +240,7 @@ def big_plan(n: int = 11) -> StaticPlan:def _ctx(tmp_path, plan, settings, *, language=Language.THREEJS, agent_id="fake-agent:m"):from codeverse.events import EventLog- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import RunStatefrom codeverse.tracks.static_object import StaticObjectTrackfrom codeverse.workspace import Workspacediff --git a/harness/tests/orchestrator_tracks/test_generation_planner_repair.py b/harness/tests/orchestrator_tracks/test_generation_planner_repair.pyindex 92b90583..7ec29231 100644--- a/harness/tests/orchestrator_tracks/test_generation_planner_repair.py+++ b/harness/tests/orchestrator_tracks/test_generation_planner_repair.py@@ -9,9 +9,7 @@ import pytestfrom codeverse.contracts.common import Language, Trackfrom codeverse.contracts.plan import ScenePlan, StaticPlanfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetGuard-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import BudgetGuard, RoundPolicy, RunStatefrom codeverse.tracks.common import RunContextfrom codeverse.tracks.generation import (SINGLE_SHOT_FORMAT,diff --git a/harness/tests/orchestrator_tracks/test_integrations2.py b/harness/tests/orchestrator_tracks/test_integrations2.pyindex 7d196955..c5d6db90 100644--- a/harness/tests/orchestrator_tracks/test_integrations2.py+++ b/harness/tests/orchestrator_tracks/test_integrations2.py@@ -11,7 +11,7 @@ from codeverse.contracts.common import Language, Track, Usagefrom codeverse.contracts.plan import ScenePlanfrom codeverse.contracts.run import RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RunStatefrom codeverse.tracks import get_trackfrom codeverse.tracks.graphics import GraphicsTrackfrom codeverse.tracks.planner import plan_examplediff --git a/harness/tests/orchestrator_tracks/test_orchestrator.py b/harness/tests/orchestrator_tracks/test_orchestrator.pyindex 505036d0..4ed72c8a 100644--- a/harness/tests/orchestrator_tracks/test_orchestrator.py+++ b/harness/tests/orchestrator_tracks/test_orchestrator.py@@ -14,17 +14,19 @@ from codeverse.contracts.plan import AcceptanceItemfrom codeverse.contracts.run import RoundRecordfrom codeverse.events import EventLogfrom codeverse.fanout import fan_out, split_results-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard-from codeverse.orchestrator.rounds import (+from codeverse.orchestrator import (BestSelector,+ BudgetExceeded,+ BudgetGuard,RefineTask,RoundPolicy,+ RunState,+ StageRunner,StopPolicy,build_refine_instructions,+ hash_inputs,plan_parallel_groups,)-from codeverse.orchestrator.runner import StageRunner, hash_inputs-from codeverse.orchestrator.state import RunState# ----------------------------------------------------------------------------- budgetdiff --git a/harness/tests/orchestrator_tracks/test_prompts_assets.py b/harness/tests/orchestrator_tracks/test_prompts_assets.pyindex 7cd18a66..b5b85e7a 100644--- a/harness/tests/orchestrator_tracks/test_prompts_assets.py+++ b/harness/tests/orchestrator_tracks/test_prompts_assets.py@@ -9,9 +9,7 @@ import pytestfrom codeverse.contracts.common import Language, Trackfrom codeverse.contracts.plan import ArticulatedPlan, ScenePlanfrom codeverse.events import EventLog-from codeverse.orchestrator.budget import BudgetGuard-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import BudgetGuard, RoundPolicy, RunStatefrom codeverse.prompts import list_prompts, renderfrom codeverse.tracks.common import RunContextfrom codeverse.tracks.generation import SINGLE_SHOT_FORMATdiff --git a/harness/tests/orchestrator_tracks/test_refactor_batch2.py b/harness/tests/orchestrator_tracks/test_refactor_batch2.pyindex 4dd7db3d..53b90539 100644--- a/harness/tests/orchestrator_tracks/test_refactor_batch2.py+++ b/harness/tests/orchestrator_tracks/test_refactor_batch2.py@@ -8,8 +8,7 @@ from codeverse.contracts.plan import ScenePlanfrom codeverse.contracts.run import RunStatusfrom codeverse.contracts.spec import RunOptionsfrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import RefineTask, plan_refine_groups-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RefineTask, RunState, plan_refine_groupsfrom codeverse.tracks.planner import plan_examplefrom codeverse.tracks.scene import ScenePipeline, SceneTrackfrom codeverse.tracks.static_object import StaticObjectTrack@@ -153,7 +152,7 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):import pytestfrom codeverse.contracts.spec import Budget- from codeverse.orchestrator.budget import BudgetGuard+ from codeverse.orchestrator import BudgetGuardfrom codeverse.tracks.graphics import plan_graphicsfrom codeverse.tracks.planner import PlanningErrordiff --git a/harness/tests/orchestrator_tracks/test_resume_reconcile.py b/harness/tests/orchestrator_tracks/test_resume_reconcile.pyindex 552cf679..1356eb60 100644--- a/harness/tests/orchestrator_tracks/test_resume_reconcile.py+++ b/harness/tests/orchestrator_tracks/test_resume_reconcile.py@@ -15,8 +15,7 @@ import pytestfrom codeverse.contracts.common import Languagefrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RoundPolicy, RunStatefrom codeverse.tracks.lifecycle import SpecChangedfrom codeverse.tracks.static_object import StaticObjectTrackfrom codeverse.workspace import Workspace@@ -228,7 +227,7 @@ def test_resume_charges_for_spend_the_snapshot_missed(tmp_path, chair_plan, settunder-counting is how a resumed run walks past its ceiling."""from codeverse.cost.ledger import open_run_ledgerfrom codeverse.cost.types import CallCost- from codeverse.orchestrator.budget import BudgetGuard, BudgetSnapshot+ from codeverse.orchestrator import BudgetGuard, BudgetSnapshotfrom codeverse.tracks.lifecycle import _reconcile_billed_from_ledgerws = Workspace(tmp_path / "runs" / "r")diff --git a/harness/tests/orchestrator_tracks/test_round_economics.py b/harness/tests/orchestrator_tracks/test_round_economics.pyindex 0aa7f6e3..5bd768d4 100644--- a/harness/tests/orchestrator_tracks/test_round_economics.py+++ b/harness/tests/orchestrator_tracks/test_round_economics.py@@ -24,7 +24,7 @@ from codeverse.contracts.common import Language, Usagefrom codeverse.contracts.judgment import Judgmentfrom codeverse.contracts.run import RoundRecord, RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import (+from codeverse.orchestrator import (DEFAULT_JUDGE_SIGMA,REWRITE_KIND,RoundPolicy,@@ -99,7 +99,7 @@ def test_a_sub_noise_dip_never_burns_the_strategy_switch():policy.regression_delta — a -0.02 blip (inside pro sigma 0.030) plus one realregression made the counter 2 and stopped the run as "regression" without everoffering the single strategy switch. One predicate now serves both."""- from codeverse.orchestrator.rounds import meaningful_regression+ from codeverse.orchestrator import meaningful_regressionsp = StopPolicy(RoundPolicy(max_rounds=4, target=0.9, judge_model="gemini:gemini-3.1-pro-preview",marginal_from_round=99))@@ -282,7 +282,7 @@ def _result_of(agent, i):def _guard():from codeverse.contracts.common import Budget- from codeverse.orchestrator.budget import BudgetGuard+ from codeverse.orchestrator import BudgetGuardreturn BudgetGuard(Budget(max_usd=100, max_minutes=100))@@ -375,7 +375,7 @@ def test_a_skipped_verdict_is_not_bought_back_by_the_rejudge_path(tmp_path, specdef test_a_round_that_broke_the_gates_does_not_displace_a_clean_one():"""The unscored fallback: never promote a round that does not build, and neverlet a gate-breaking round displace the previous artifact just by being last."""- from codeverse.orchestrator.rounds import BestSelector+ from codeverse.orchestrator import BestSelectordef r(i, *, build_ok=True, errors=0):return RoundRecord(index=i, kind="refine", build=BuildResult(ok=build_ok, language="l"),@@ -404,8 +404,7 @@ def _pipeline():def _ctx(tmp_path, spec, settings, *, policy: RoundPolicy | None = None, agent=None, name: str = "skip"):from codeverse.contracts.common import Budget- from codeverse.orchestrator.budget import BudgetGuard- from codeverse.orchestrator.state import RunState+ from codeverse.orchestrator import BudgetGuard, RunStatefrom codeverse.tracks.common import RunContextws = Workspace(tmp_path / "runs" / name)diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.pyindex 5c1975c0..0417688f 100644--- a/harness/tests/orchestrator_tracks/test_tracks.py+++ b/harness/tests/orchestrator_tracks/test_tracks.py@@ -10,8 +10,7 @@ from codeverse.contracts.common import Language, Trackfrom codeverse.contracts.plan import ArticulatedPlan, ScenePlanfrom codeverse.contracts.run import RunRecord, RunStatusfrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import RoundPolicy-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RoundPolicy, RunStatefrom codeverse.tracks import get_trackfrom codeverse.tracks.articulated_object import ArticulatedObjectTrackfrom codeverse.tracks.planner import plan_examplediff --git a/harness/tests/orchestrator_tracks/test_write_scope.py b/harness/tests/orchestrator_tracks/test_write_scope.pyindex d8ae5986..c5f8faea 100644--- a/harness/tests/orchestrator_tracks/test_write_scope.py+++ b/harness/tests/orchestrator_tracks/test_write_scope.py@@ -17,8 +17,7 @@ from codeverse.contracts.judgment import Judgmentfrom codeverse.contracts.plan import BBox, PartPlan, ScenePlan, StaticPlanfrom codeverse.contracts.run import RoundRecordfrom codeverse.events import EventLog-from codeverse.orchestrator.rounds import RefineTask, TaskGroup-from codeverse.orchestrator.state import RunState+from codeverse.orchestrator import RefineTask, RunState, TaskGroupfrom codeverse.tracks.generation import (GenerationResult,GenerationTask,diff --git a/harness/tests/scene_gates/test_placement.py b/harness/tests/scene_gates/test_placement.pyindex cb90282e..cb73650b 100644--- a/harness/tests/scene_gates/test_placement.py+++ b/harness/tests/scene_gates/test_placement.py@@ -14,7 +14,7 @@ from codeverse.contracts.common import Languagefrom codeverse.contracts.plan import BBox, CameraPlan, ScenePlan, ZonePlanfrom codeverse.judges.caps import apply_capsfrom codeverse.judges.rubrics import load_rubric-from codeverse.orchestrator.rounds import build_refine_instructions+from codeverse.orchestrator import build_refine_instructionsfrom codeverse.spatial.scene_placement import (GATE,check_placement,