Skip to content

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.py
index 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, A
return {}
from dataclasses import replace
- from codeverse.orchestrator.rounds import RoundPolicy
+ from codeverse.orchestrator import RoundPolicy
policy = 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.py
index 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, StateCorrupt
try:
state = RunState.load(ws)
diff --git a/harness/codeverse/orchestrator.py b/harness/codeverse/orchestrator.py
new file mode 100644
index 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__.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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.py
deleted file mode 100644
index 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 result
diff --git a/harness/codeverse/orchestrator/state.py b/harness/codeverse/orchestrator/state.py
deleted file mode 100644
index 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.py
index 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 the
round policy protects them from being trimmed as judge chatter)."""
- from codeverse.orchestrator.rounds import RefineTask
+ from codeverse.orchestrator import RefineTask
out = []
for m in diff.top(top):
diff --git a/harness/codeverse/tracks/candidates.py b/harness/codeverse/tracks/candidates.py
index 76c2e98b..324d06bc 100644
--- a/harness/codeverse/tracks/candidates.py
+++ b/harness/codeverse/tracks/candidates.py
@@ -31,8 +31,7 @@ from codeverse.contracts.common import Usage
from codeverse.contracts.run import RoundRecord
from codeverse.conventions import OBJECT_VIEWS_QUICK
from codeverse.fanout import fan_out
-from codeverse.orchestrator.budget import BudgetExceeded
-from codeverse.orchestrator.rounds import BestSelector
+from codeverse.orchestrator import BestSelector, BudgetExceeded
from codeverse.tracks.common import RunContext
from codeverse.tracks.generation import GenerationTask
from codeverse.tracks.repair import build_with_repair
diff --git a/harness/codeverse/tracks/common.py b/harness/codeverse/tracks/common.py
index 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, Plan
from codeverse.contracts.run import RunRecord
from codeverse.conventions import ViewPreset
from 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, RunState
from codeverse.prompts import load_text, prompt_hash
from codeverse.tracks.generation import is_single_shot
from codeverse.workspace import Workspace
diff --git a/harness/codeverse/tracks/generation.py b/harness/codeverse/tracks/generation.py
index 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 BudgetExceeded
return isinstance(e, BudgetExceeded)
diff --git a/harness/codeverse/tracks/graphics.py b/harness/codeverse/tracks/graphics.py
index 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_metrics
from codeverse.languages.glsl_shader.lint import FUNC_DEF
from codeverse.languages.glsl_shader.skeleton import COMMON_GLSL
from codeverse.languages.glsl_shader.wrap import strip_comments
-from codeverse.orchestrator.rounds import TaskGroup
+from codeverse.orchestrator import TaskGroup
from codeverse.prompts import render
from codeverse.spatial.cookbook_tool import Section, split_sections
from codeverse.tracks.common import RunContext
diff --git a/harness/codeverse/tracks/lifecycle.py b/harness/codeverse/tracks/lifecycle.py
index 936168e8..5b73b60e 100644
--- a/harness/codeverse/tracks/lifecycle.py
+++ b/harness/codeverse/tracks/lifecycle.py
@@ -26,22 +26,25 @@ from codeverse.contracts.plan import Plan
from codeverse.contracts.run import RoundRecord, RunRecord, RunStatus
from codeverse.contracts.spec import Spec
from 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 RunState
from codeverse.prompts import render
from codeverse.tracks.candidates import choose_best_round, run_best_of_n
from codeverse.tracks.common import (
diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.py
index 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, ZonePlan
from codeverse.contracts.run import RoundRecord
from codeverse.conventions import to_snake
from 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_instructions
from codeverse.prompts import render
from codeverse.spatial.frame_motion import motion_text_for
from codeverse.spatial.render_scene import JUDGE_MAX_VIEWS, perf_detail
diff --git a/harness/codeverse/tracks/scene_assets.py b/harness/codeverse/tracks/scene_assets.py
index 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) -> As
res = _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 BudgetExceeded
if isinstance(e, BudgetExceeded):
raise
diff --git a/harness/codeverse/tracks/static_object.py b/harness/codeverse/tracks/static_object.py
index 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_instructions
from codeverse.prompts import render
from codeverse.tracks.common import RunContext
from codeverse.tracks.depth import (
diff --git a/harness/codeverse/tracks/steps.py b/harness/codeverse/tracks/steps.py
index 027cfe05..dff22b45 100644
--- a/harness/codeverse/tracks/steps.py
+++ b/harness/codeverse/tracks/steps.py
@@ -33,7 +33,7 @@ from codeverse.contracts.judgment import Judgment
from codeverse.contracts.plan import AcceptanceItem, Plan
from codeverse.contracts.run import RoundRecord
from codeverse.fanout import fan_out
-from codeverse.orchestrator.budget import usage_delta
+from codeverse.orchestrator import usage_delta
from codeverse.spatial.render import RenderError
from codeverse.tracks import skills_hook
from codeverse.tracks.common import RunContext
@@ -137,7 +137,7 @@ def _run_phase(ctx: RunContext, tasks: Sequence[GenerationTask]) -> list[Generat
budget_stop: Exception | None = None
for task, r in zip(tasks, results, strict=True):
if isinstance(r, Exception):
- from codeverse.orchestrator.budget import BudgetExceeded
+ from codeverse.orchestrator import BudgetExceeded
if 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.md
index 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-metre
unwrap), 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, budget
tracks/ __init__.py (get_track(track, **options) + the TrackPipeline protocol),
lifecycle.py, steps.py, candidates.py (best-of-N + the pure candidate/pairwise
decision logic), generation.py (agent + single-shot strategies + the file
diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.md
index 0db3a26b..8fa925dc 100644
--- a/harness/docs/INTERFACES.md
+++ b/harness/docs/INTERFACES.md
@@ -310,7 +310,7 @@ from codeverse.tracks import get_track
rec = 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_instructions
RoundPolicy(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_delta
BudgetGuard(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 row
diff --git a/harness/tests/core/test_contract_additions.py b/harness/tests/core/test_contract_additions.py
index 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_inputs
from codeverse.tracks.lifecycle import plan_stage_inputs
plain = 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.py
index 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_tra
back to 'planning' — a finished run left stuck mid-pipeline, and money spent, from
one accidental or scripted resume."""
from codeverse.contracts.run import RunStatus
- from codeverse.orchestrator.state import RunState
+ from codeverse.orchestrator import RunState
from codeverse.workspace import Workspace
runs, run_dir = made_run()
diff --git a/harness/tests/graphics/test_live.py b/harness/tests/graphics/test_live.py
index 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 EventLog
from codeverse.models import get_chat_model
- from codeverse.orchestrator.state import RunState
+ from codeverse.orchestrator import RunState
from codeverse.prompts import render
spec = 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.py
index 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 RunState
ctx = 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.py
index 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 annotations
import pytest
-from codeverse.orchestrator.rounds import best_index
+from codeverse.orchestrator import best_index
def test_best_index():
diff --git a/harness/tests/orchestrator_tracks/test_budget_snapshot.py b/harness/tests/orchestrator_tracks/test_budget_snapshot.py
index 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, Usage
from codeverse.contracts.plan import StaticPlan
from codeverse.contracts.run import RunStatus
from 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, RunState
from codeverse.tracks.generation import GenerationTask, generate_files
from codeverse.tracks.planner import MAX_VALIDATION_REASKS, PlanningError
from codeverse.tracks.planner import plan as run_planner
diff --git a/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py b/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py
index 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 ArticulatedPlan
from codeverse.contracts.run import RunStatus
from codeverse.contracts.spec import ReferenceImage
from 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 width
t2 = 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 RunState
ctx = 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, chair
spec = 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 RunState
ctx = track.build_context(spec, Workspace(tmp_path / "ws").create(), EventLog(tmp_path / "e.jsonl"), RunState())
ctx.plan = chair_plan
diff --git a/harness/tests/orchestrator_tracks/test_cost_accounting.py b/harness/tests/orchestrator_tracks/test_cost_accounting.py
index 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 pytest
from codeverse.contracts.agent import AgentJob, AgentResult
from codeverse.contracts.common import Budget, Usage
from codeverse.cost.ledger import load_ledger
-from codeverse.orchestrator.budget import BudgetExceeded, BudgetGuard, usage_delta
+from codeverse.orchestrator import BudgetExceeded, BudgetGuard, usage_delta
from codeverse.tracks.generation import GenerationTask, _SessionAcc
FIXTURES = 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 BudgetGuard
g = 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 an
unclassified 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, BudgetGuard
g = 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, ignored
diff --git a/harness/tests/orchestrator_tracks/test_cost_latency.py b/harness/tests/orchestrator_tracks/test_cost_latency.py
index 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, Track
from codeverse.contracts.plan import AssetPlan, ScenePlan, ZonePlan
from codeverse.contracts.run import RunStatus
from 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, RunState
from codeverse.tracks.common import RunContext
from codeverse.tracks.planner import plan_example
from 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 next
boundary. 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 BudgetGuard
g = 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 min
and 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 BudgetGuard
from 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.py
index 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 pytest
from codeverse.config import FEWER_TURNS_ENV, Settings, fewer_turns_enabled
from codeverse.contracts.common import Language
-from codeverse.orchestrator.rounds import RefineTask, TaskGroup
+from codeverse.orchestrator import RefineTask, TaskGroup
from codeverse.tracks.plan_features import LIVE_SWITCHES, pin_plan_blockers
from 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-BO
def _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 RunState
from codeverse.tracks.static_object import StaticObjectTrack
from codeverse.workspace import Workspace
diff --git a/harness/tests/orchestrator_tracks/test_fix_batch2.py b/harness/tests/orchestrator_tracks/test_fix_batch2.py
index 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 Judgment
from codeverse.contracts.plan import BBox, PartPlan, ScenePlan, StaticPlan
from codeverse.contracts.run import RoundRecord, RunStatus
from codeverse.events import EventLog
-from codeverse.orchestrator.rounds import RoundPolicy
-from codeverse.orchestrator.state import RunState
+from codeverse.orchestrator import RoundPolicy, RunState
from codeverse.prompts import load_text
from codeverse.tracks.planner import plan_example
from codeverse.tracks.scene import SceneTrack
diff --git a/harness/tests/orchestrator_tracks/test_generation_depth.py b/harness/tests/orchestrator_tracks/test_generation_depth.py
index 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, Judgment
from codeverse.contracts.plan import BBox, PartPlan, StaticPlan
from codeverse.contracts.run import RoundRecord
from 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 RunState
from codeverse.tracks.static_object import StaticObjectTrack
from codeverse.workspace import Workspace
diff --git a/harness/tests/orchestrator_tracks/test_generation_planner_repair.py b/harness/tests/orchestrator_tracks/test_generation_planner_repair.py
index 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 pytest
from codeverse.contracts.common import Language, Track
from codeverse.contracts.plan import ScenePlan, StaticPlan
from 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, RunState
from codeverse.tracks.common import RunContext
from codeverse.tracks.generation import (
SINGLE_SHOT_FORMAT,
diff --git a/harness/tests/orchestrator_tracks/test_integrations2.py b/harness/tests/orchestrator_tracks/test_integrations2.py
index 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, Usage
from codeverse.contracts.plan import ScenePlan
from codeverse.contracts.run import RunStatus
from codeverse.events import EventLog
-from codeverse.orchestrator.state import RunState
+from codeverse.orchestrator import RunState
from codeverse.tracks import get_track
from codeverse.tracks.graphics import GraphicsTrack
from codeverse.tracks.planner import plan_example
diff --git a/harness/tests/orchestrator_tracks/test_orchestrator.py b/harness/tests/orchestrator_tracks/test_orchestrator.py
index 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 AcceptanceItem
from codeverse.contracts.run import RoundRecord
from codeverse.events import EventLog
from 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
# ----------------------------------------------------------------------------- budget
diff --git a/harness/tests/orchestrator_tracks/test_prompts_assets.py b/harness/tests/orchestrator_tracks/test_prompts_assets.py
index 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 pytest
from codeverse.contracts.common import Language, Track
from codeverse.contracts.plan import ArticulatedPlan, ScenePlan
from 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, RunState
from codeverse.prompts import list_prompts, render
from codeverse.tracks.common import RunContext
from codeverse.tracks.generation import SINGLE_SHOT_FORMAT
diff --git a/harness/tests/orchestrator_tracks/test_refactor_batch2.py b/harness/tests/orchestrator_tracks/test_refactor_batch2.py
index 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 ScenePlan
from codeverse.contracts.run import RunStatus
from codeverse.contracts.spec import RunOptions
from 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_groups
from codeverse.tracks.planner import plan_example
from codeverse.tracks.scene import ScenePipeline, SceneTrack
from codeverse.tracks.static_object import StaticObjectTrack
@@ -153,7 +152,7 @@ def test_graphics_planner_hooks_charge_budget_on_planning_error(tmp_ws):
import pytest
from codeverse.contracts.spec import Budget
- from codeverse.orchestrator.budget import BudgetGuard
+ from codeverse.orchestrator import BudgetGuard
from codeverse.tracks.graphics import plan_graphics
from codeverse.tracks.planner import PlanningError
diff --git a/harness/tests/orchestrator_tracks/test_resume_reconcile.py b/harness/tests/orchestrator_tracks/test_resume_reconcile.py
index 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 pytest
from codeverse.contracts.common import Language
from codeverse.events import EventLog
-from codeverse.orchestrator.rounds import RoundPolicy
-from codeverse.orchestrator.state import RunState
+from codeverse.orchestrator import RoundPolicy, RunState
from codeverse.tracks.lifecycle import SpecChanged
from codeverse.tracks.static_object import StaticObjectTrack
from codeverse.workspace import Workspace
@@ -228,7 +227,7 @@ def test_resume_charges_for_spend_the_snapshot_missed(tmp_path, chair_plan, sett
under-counting is how a resumed run walks past its ceiling."""
from codeverse.cost.ledger import open_run_ledger
from codeverse.cost.types import CallCost
- from codeverse.orchestrator.budget import BudgetGuard, BudgetSnapshot
+ from codeverse.orchestrator import BudgetGuard, BudgetSnapshot
from codeverse.tracks.lifecycle import _reconcile_billed_from_ledger
ws = Workspace(tmp_path / "runs" / "r")
diff --git a/harness/tests/orchestrator_tracks/test_round_economics.py b/harness/tests/orchestrator_tracks/test_round_economics.py
index 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, Usage
from codeverse.contracts.judgment import Judgment
from codeverse.contracts.run import RoundRecord, RunStatus
from 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 real
regression made the counter 2 and stopped the run as "regression" without ever
offering the single strategy switch. One predicate now serves both."""
- from codeverse.orchestrator.rounds import meaningful_regression
+ from codeverse.orchestrator import meaningful_regression
sp = 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 BudgetGuard
return 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, spec
def 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 never
let a gate-breaking round displace the previous artifact just by being last."""
- from codeverse.orchestrator.rounds import BestSelector
+ from codeverse.orchestrator import BestSelector
def 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, RunState
from codeverse.tracks.common import RunContext
ws = Workspace(tmp_path / "runs" / name)
diff --git a/harness/tests/orchestrator_tracks/test_tracks.py b/harness/tests/orchestrator_tracks/test_tracks.py
index 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, Track
from codeverse.contracts.plan import ArticulatedPlan, ScenePlan
from codeverse.contracts.run import RunRecord, RunStatus
from codeverse.events import EventLog
-from codeverse.orchestrator.rounds import RoundPolicy
-from codeverse.orchestrator.state import RunState
+from codeverse.orchestrator import RoundPolicy, RunState
from codeverse.tracks import get_track
from codeverse.tracks.articulated_object import ArticulatedObjectTrack
from codeverse.tracks.planner import plan_example
diff --git a/harness/tests/orchestrator_tracks/test_write_scope.py b/harness/tests/orchestrator_tracks/test_write_scope.py
index 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 Judgment
from codeverse.contracts.plan import BBox, PartPlan, ScenePlan, StaticPlan
from codeverse.contracts.run import RoundRecord
from codeverse.events import EventLog
-from codeverse.orchestrator.rounds import RefineTask, TaskGroup
-from codeverse.orchestrator.state import RunState
+from codeverse.orchestrator import RefineTask, RunState, TaskGroup
from codeverse.tracks.generation import (
GenerationResult,
GenerationTask,
diff --git a/harness/tests/scene_gates/test_placement.py b/harness/tests/scene_gates/test_placement.py
index 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 Language
from codeverse.contracts.plan import BBox, CameraPlan, ScenePlan, ZonePlan
from codeverse.judges.caps import apply_caps
from codeverse.judges.rubrics import load_rubric
-from codeverse.orchestrator.rounds import build_refine_instructions
+from codeverse.orchestrator import build_refine_instructions
from codeverse.spatial.scene_placement import (
GATE,
check_placement,