Official Codebase of 3DCodeVerse
Python
orchestrator, tracks, record: shared helpers instead of copies, and the parameters that only ever carried one value
gaoypeng3e73bc388a6e
diff --git a/eval/tests/test_ab_plan_switches.py b/eval/tests/test_ab_plan_switches.pyindex 0a69bd2b..a480439e 100644--- a/eval/tests/test_ab_plan_switches.py+++ b/eval/tests/test_ab_plan_switches.py@@ -35,3 +35,20 @@ def test_ab_plan_still_accepts_a_live_switch(monkeypatch, capsys):assert len(seen) == 2, capsys.readouterr()assert "C3D_PLAN_BRIEF" in seen[0]+++def test_a_dead_switch_does_not_block_pin_plan(monkeypatch, capsys):+ """C3D_PLAN_FEATURES is read by nothing, so it cannot change a plan: next to a+ generation-side switch it must not make --pin-plan refuse the A/B (until 2026-09-22+ its never-implemented feature names did)."""+ import bench.ab_plan as A++ seen: list[dict[str, str]] = []++ class _V:+ decision, reason, caution = "keep", "stubbed", ""++ monkeypatch.setattr(A, "run_ab", lambda battery, out, opts, **kw: (seen.append(opts.variant_env), _V())[1])+ A.main(["--prompts", "p.yaml", "--out", "o", "--no-preflight", "--allow-siblings", "--pin-plan",+ "--variant-env", "C3D_PLAN_FEATURES=all", "--variant-env", "C3D_SKILLS=1"])+ assert seen == [{"C3D_PLAN_FEATURES": "all", "C3D_SKILLS": "1"}], capsys.readouterr()diff --git a/harness/codeverse3d/orchestrator.py b/harness/codeverse3d/orchestrator.pyindex 5f694c98..7d8fb606 100644--- a/harness/codeverse3d/orchestrator.py+++ b/harness/codeverse3d/orchestrator.py@@ -1,5 +1,5 @@"""Orchestration: the stage runner with resume, run state, the round loop-(RoundPolicy / StopPolicy / BestSelector), refine-task compilation and the budget.+(RoundPolicy / StopPolicy / pick_best_round), 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@@ -497,13 +497,6 @@ class RoundPolicy:regression_sigma: float = 1.0 # a round below (best − this × σ) regressed: change shape or stopmarginal_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 (no cost profile does).- agent_max_turns: int = 0 # 0 = the backend's own AgentJob.max_turns (claude-code 60; the other vendors have no turn cap)- 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@@ -722,33 +715,20 @@ def last_gain(history: Sequence[RoundRecord]) -> float | 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")- # the three-clause running max WAS this key: greater score, then fewer errors,- # then later index (the third clause `score == bs and n_err == be` is the tie-break)- return max(range(len(rounds)), key=lambda i: (rounds[i][0], -rounds[i][1], i))---class BestSelector:+def pick_best_round(rounds: Sequence[RoundRecord]) -> int | None:"""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+ 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 thatbroke 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))+ scored = [i for i, r in enumerate(rounds) if r.score is not None and not _build_failed(r)]+ if scored:+ return max(scored, key=lambda i: (float(rounds[i].score), -gate_error_count(rounds[i]), i)) # type: ignore[arg-type]+ 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:@@ -770,11 +750,10 @@ 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):+ def __init__(self, reason: str, *, spent_usd: float):super().__init__(reason)self.reason = reasonself.spent_usd = spent_usd- self.elapsed_min = elapsed_minclass BudgetGuard:@@ -908,7 +887,6 @@ class BudgetGuard:raise BudgetExceeded(f"elapsed {elapsed:.1f} min exceeds max_minutes {self.hard_minutes:.1f}",spent_usd=spent,- elapsed_min=elapsed,)# ----------------------------------------------------------------- soft cap@@ -928,10 +906,6 @@ class BudgetGuard:"""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)."""- return {"minutes": max(0.0, self.soft_minutes() - self.elapsed_minutes())}-def ok(self) -> bool:"""True when no ceiling is crossed (non-raising variant of ``check``)."""try:@@ -940,19 +914,13 @@ class BudgetGuard:return Falsereturn True- def remaining(self) -> dict[str, float]:- """Remaining wall clock: ``{"minutes": ..., "fraction": ...}`` (no money key since the USD ceiling went, fbf89a5)."""- minutes = max(0.0, self.hard_minutes - self.elapsed_minutes())- frac = minutes / self.hard_minutes if self.hard_minutes > 0 else 0.0- return {"minutes": minutes, "fraction": frac}-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 workingafter the ceiling had already been crossed."""- left = (self.soft_remaining()["minutes"] if soft else self.remaining()["minutes"]) * 60.0+ left = max(0.0, (self.soft_minutes() if soft else self.hard_minutes) - self.elapsed_minutes()) * 60.0return int(max(floor_s, min(float(want_s), left) if left > 0 else floor_s))def summary(self) -> dict[str, float | int]:@@ -982,7 +950,6 @@ class BudgetSnapshot(BaseModel):headroom — persisting it would ratchet the hard ceiling — and config alwayscomes from the current spec/settings."""- version: int = 1spent: Usagebilled_usd: floatcalls: intdiff --git a/harness/codeverse3d/record/record.py b/harness/codeverse3d/record/record.pyindex ceb525d1..914acf58 100644--- a/harness/codeverse3d/record/record.py+++ b/harness/codeverse3d/record/record.py@@ -198,10 +198,7 @@ def round_summary(r: RoundRecord) -> dict[str, Any]:def _sum_usage(rounds: list[RoundRecord]) -> Usage:"""Round usage already includes the round's judge call (tracks/steps.py) — do not add it twice."""- total = Usage()- for r in rounds:- total = total + r.usage- return total+ return sum((r.usage for r in rounds), Usage())def fill_derived(record: RunRecord) -> RunRecord:@@ -277,12 +274,11 @@ def package_run(ws: Workspace, record: RunRecord) -> None:log.warning("telemetry not written for %s: %s", ws.root, e)-def finalize_record(ws: Workspace, record: RunRecord, *, package: bool = True) -> Path:+def finalize_record(ws: Workspace, record: RunRecord) -> Path:"""Fill derived fields + environment, package the run and write ``record.json``."""record.workspace = record.workspace or str(ws.root)fill_derived(record)- if package:- package_run(ws, record)+ package_run(ws, record)ws.write_json(ws.record_path, record)return ws.record_pathdiff --git a/harness/codeverse3d/record/telemetry.py b/harness/codeverse3d/record/telemetry.pyindex 5b19fcbb..7c7e6666 100644--- a/harness/codeverse3d/record/telemetry.py+++ b/harness/codeverse3d/record/telemetry.py@@ -128,7 +128,6 @@ def rubric_hash(name: str) -> str:def _role_settings(record: RunRecord) -> list[RoleSettings]:b = record.spec.backends- observed = record.extra.get("sampling") or {} # forward hook: a track may record real valuesplan_d, judge_d = _planner_defaults(), _judge_defaults()spec: list[tuple[str, str, dict[str, Any]]] = [("planner", b.planner, plan_d),@@ -138,37 +137,31 @@ def _role_settings(record: RunRecord) -> list[RoleSettings]:]roles: list[RoleSettings] = []for role, model_id, defaults in spec:- values = dict(defaults)- source = "default" if defaults else "spec"- if isinstance(observed.get(role), dict):- values.update(observed[role])- source = "observed"- temperature = values.get("temperature")+ temperature = defaults.get("temperature")roles.append(RoleSettings(role=role, model=model_id, backend=backend_kind(model_id),- thinking=str(values.get("thinking") or ""),+ thinking=str(defaults.get("thinking") or ""),temperature=float(temperature) if isinstance(temperature, (int, float)) else None,- n_samples=values.get("n_samples") if role == "judge" else None,- source=source,+ n_samples=defaults.get("n_samples") if role == "judge" else None,+ source="default" if defaults else "spec",))return roles-def settings_snapshot(record: RunRecord, *, key_pool_size: int | None = None) -> SettingsSnapshot:+def settings_snapshot(record: RunRecord) -> SettingsSnapshot:"""The resolved 'how was this run configured' block (no secrets, ever)."""spec = record.specrubric = _rubric_name(record)render: dict[str, Any] = {}limits: dict[str, Any] = {}- keys = key_pool_size+ keys = 0try:from codeverse3d.config import get_settingss = get_settings()render = s.render.model_dump(mode="json")limits = s.limits.model_dump(mode="json")- if keys is None:- keys = len(s.gemini_api_keys)+ keys = len(s.gemini_api_keys)except Exception as e: # pragma: no cover - settings should always loadlog.debug("settings unavailable: %s", e)env = dict(record.environment)@@ -184,7 +177,7 @@ def settings_snapshot(record: RunRecord, *, key_pool_size: int | None = None) ->tool_versions={k: v for k, v in env.items() if k in _TOOL_KEYS},harness_version=env.get("codeverse3d", ""),harness_git_sha=env.get("harness_git_sha", ""),- key_pool_size=int(keys or 0),+ key_pool_size=keys,price_table_version=price_table_version(),render=render,limits=limits,diff --git a/harness/codeverse3d/tracks/__init__.py b/harness/codeverse3d/tracks/__init__.pyindex 89e2f538..d9b55b6e 100644--- a/harness/codeverse3d/tracks/__init__.py+++ b/harness/codeverse3d/tracks/__init__.py@@ -1,31 +1,21 @@"""Tracks: static_object · articulated_object · scene · graphics.-``get_track(Track.X)`` builds the pipeline; ``TrackPipeline`` is the protocol the+``get_track(Track.X)`` builds the track: a ``lifecycle.BaseTrack``, whose ``run()`` theorchestrator drives. (Formerly ``tracks/base.py`` — folded into the package root2026-08-28: its only importer was this ``__init__``.)"""from __future__ import annotations-from typing import Any, Protocol+from typing import TYPE_CHECKING, Anyfrom codeverse3d.contracts.common import Track-from codeverse3d.contracts.run import RunRecord-from codeverse3d.contracts.spec import Spec-from codeverse3d.workspace import Workspace+if TYPE_CHECKING:+ from codeverse3d.tracks.lifecycle import BaseTrack-class TrackPipeline(Protocol):- track: Track- rubric: str # judges/rubrics/<rubric>.yaml- def run(self, spec: Spec, ws: Workspace, *, resume: bool = False, force: bool = False) -> RunRecord:- """Full pipeline: plan → baseline → rounds → finalise. Must be resumable;- ``force`` re-plans a resumed run whose spec changed (archives the old rounds)."""- ...---def get_track(track: Track | str, **options: Any) -> TrackPipeline:+def get_track(track: Track | str, **options: Any) -> BaseTrack:"""Track instance for ``track``. ``options`` are forwarded to the trackconstructor (e.g. ``n_candidates=2`` for a best-of-N baseline, ``policy=``)."""t = Track(track)@@ -46,4 +36,4 @@ def get_track(track: Track | str, **options: Any) -> TrackPipeline:return SceneTrack(**options)-__all__ = ["TrackPipeline", "get_track"]+__all__ = ["get_track"]diff --git a/harness/codeverse3d/tracks/candidates.py b/harness/codeverse3d/tracks/candidates.pyindex 3e0b5a32..1dcd49e7 100644--- a/harness/codeverse3d/tracks/candidates.py+++ b/harness/codeverse3d/tracks/candidates.py@@ -34,7 +34,7 @@ from codeverse3d.contracts.common import Usagefrom codeverse3d.contracts.run import PairwiseNote, RoundRecordfrom codeverse3d.conventions import OBJECT_VIEWS_QUICKfrom codeverse3d.cost.types import Stage-from codeverse3d.orchestrator import BestSelector, BudgetExceeded, gate_error_count+from codeverse3d.orchestrator import BudgetExceeded, gate_error_count, pick_best_roundfrom codeverse3d.proc import EventLog, fan_outfrom codeverse3d.tracks.common import RunContextfrom codeverse3d.tracks.generation import GenerationTask@@ -114,9 +114,7 @@ def run_best_of_n(track: Any, ctx: RunContext, tasks: Sequence[GenerationTask],raise RoundFailed("; ".join(f"{r.label}: {r.notes}" for r in records) or "every candidate failed")best, note = select_candidate(ctx, records, renders)records[best].selected = True- usage = Usage()- for rec in records:- usage = usage + rec.usage+ usage = sum((r.usage for r in records), Usage())if note is not None:usage = usage + note.usagectx.ws.write_json(ctx.ws.root / "rounds" / "candidates.json",@@ -162,7 +160,7 @@ def make_candidate_context(track: Any, ctx: RunContext, k: int) -> RunContext:def quick_render(ctx: RunContext, round_index: int, build: BuildResult, measurement: Measurement | None, *,- pipeline: RoundPipeline | None = None) -> RenderSet | None:+ pipeline: RoundPipeline) -> RenderSet | None:"""Cheap renders for ranking a candidate — by the route THIS track actually has.An object has a GLB and gets the reduced-view, reduced-resolution rig, which is the@@ -191,8 +189,6 @@ def quick_render(ctx: RunContext, round_index: int, build: BuildResult, measuremif pose:rs.views = list(rs.views) + list(pose)return rs- if pipeline is None:- return Nonereturn pipeline.render(ctx, round_index, build, measurement)except Exception as e: # noqa: BLE001 — a candidate without renders is ranked by gates onlylog.warning("quick render failed for %s: %s", ctx.ws.root, e)@@ -237,7 +233,7 @@ def adopt_candidate(ctx: RunContext, sub_ws: Workspace) -> None:# ----------------------------------------------------------------------------- best round (pairwise tie-break)-def choose_best_round(ctx: RunContext, rounds: list[RoundRecord], selector: BestSelector, new_index: int) -> int | None:+def choose_best_round(ctx: RunContext, rounds: list[RoundRecord], new_index: int) -> int | None:"""Index of the best round after ``rounds[new_index]`` finished.Ordinary ranking (score → fewer gate errors) unless the new round's score is@@ -263,10 +259,10 @@ def choose_best_round(ctx: RunContext, rounds: list[RoundRecord], selector: Bestctx.ws.write_json(round_record_path(ctx, new_index), new)ctx.events.emit("pairwise.done", stage="rounds", a=note.a, b=note.b, winner=note.winner, confidence=note.confidence,accepted=note.accepted, error=note.error, cost_usd=round(note.usage.cost_usd, 4))- return replay_best_round(rounds, selector=selector)+ return replay_best_round(rounds)-def replay_best_round(journal: Sequence[RoundRecord], selector: BestSelector | None = None) -> int | None:+def replay_best_round(journal: Sequence[RoundRecord]) -> int | None:"""The best index, walking the journal sequentially and honouring stored verdicts.Each round is an incumbent-vs-challenger step: a round carrying a@@ -274,17 +270,16 @@ def replay_best_round(journal: Sequence[RoundRecord], selector: BestSelector | Nranking has nothing to say, so the stored verdict — replace or keep — is FINAL(a later round can never revive a rejected challenger by global re-ranking, and akill before the state save cannot reverse a paid ~$0.05 judgement — 18 such runs- on disk, 2026-08-30); every other round advances by the two-way ``BestSelector``+ on disk, 2026-08-30); every other round advances by the two-way :func:`pick_best_round`rule, whose key is a total order — absent verdicts this equals the global pick."""- selector = selector or BestSelector()best: int | None = Nonefor i, rec in enumerate(journal):if rec.pairwise is not None and best is not None and best != i:if rec.pairwise.accepted:best = ielif best is None:- best = selector.pick(journal[:i + 1])- elif selector.pick([journal[best], rec]) == 1:+ best = pick_best_round(journal[:i + 1])+ elif pick_best_round([journal[best], rec]) == 1:best = ireturn bestdiff --git a/harness/codeverse3d/tracks/common.py b/harness/codeverse3d/tracks/common.pyindex 2ecb2646..279b6f92 100644--- a/harness/codeverse3d/tracks/common.py+++ b/harness/codeverse3d/tracks/common.py@@ -237,8 +237,7 @@ def generate_for(ctx: RunContext, task: GenerationTask) -> GenerationResult:loop, while every single-shot in the same minutes got through; the stages that losttheir session shipped the skeleton env and empty zones and judged 0.00-0.14."""res = generate(ctx.ws, agent_id=ctx.agent_id, task=task, agent=ctx.agent, model=ctx.model, settings=ctx.settings,- budget=ctx.budget, events=ctx.events,- max_turns=ctx.policy.agent_max_turns, wrapup_turns=ctx.policy.agent_wrapup_turns)+ budget=ctx.budget, events=ctx.events)if not res.storm or ctx.single_shot:return ressub = single_shot_ctx(ctx)@@ -246,8 +245,7 @@ def generate_for(ctx: RunContext, task: GenerationTask) -> GenerationResult:return resctx.events.emit("generate.storm_fallback", label=task.label, sessions=res.sessions, notes=res.notes[:300])again = generate(sub.ws, agent_id=sub.agent_id, task=task, agent=sub.agent, model=sub.model, settings=sub.settings,- budget=sub.budget, events=sub.events,- max_turns=sub.policy.agent_max_turns, wrapup_turns=sub.policy.agent_wrapup_turns)+ budget=sub.budget, events=sub.events)again.usage = res.usage + again.usageagain.notes = f"agent session died in a 503 storm ({res.notes[:120]}) → single-shot: {again.notes}"return againdiff --git a/harness/codeverse3d/tracks/generation.py b/harness/codeverse3d/tracks/generation.pyindex 302e37aa..074f4615 100644--- a/harness/codeverse3d/tracks/generation.py+++ b/harness/codeverse3d/tracks/generation.py@@ -18,12 +18,11 @@ every session at 28 turns. A controlled A/B rejected it — same prompt, n=3 pearm: capped $1.381 / **0.479**, uncapped $1.360 / **0.684** (docs/COST.md §17).A session cut off mid-task leaves work the next round pays for again.-So there is **no default cap** (``DEFAULT_AGENT_MAX_TURNS`` and-``RoundPolicy.agent_max_turns`` are 0 → the backend's own ``AgentJob.max_turns``).-A caller may still set one (``GenerationTask.max_turns`` > ``generate(max_turns=…)``-> ``C3D_AGENT_MAX_TURNS`` > ``Settings.limits.agent_max_turns``; no cost profile-sets one), and a cap that IS set stays **graceful**: the session is not killed-but asked, in a short wrap-up (``agent_wrapup_turns``), for one last build + summary.+So there is **no default cap** (``DEFAULT_AGENT_MAX_TURNS`` is 0 → the backend's own+``AgentJob.max_turns``). A machine may still set one (``C3D_AGENT_MAX_TURNS`` >+``Settings.limits.agent_max_turns``; no cost profile sets one), and a cap that IS set+stays **graceful**: the session is not killed but asked, in a short wrap-up+(``DEFAULT_WRAPUP_TURNS``), for one last build + summary.**Every dollar is charged.** Both strategies spend through ``BudgetGuard.charge`` inthe stage the task belongs to, so a retried session (``<label>.a2``) and a wrap-up@@ -47,6 +46,7 @@ from pydantic import BaseModel, Fieldfrom codeverse3d.contracts.agent import AgentJob, AgentResult, FileChangefrom codeverse3d.contracts.chat import ChatMessage, ChatRequest, ImagePartfrom codeverse3d.contracts.common import Usage+from codeverse3d.proc import read_json_or_nonefrom codeverse3d.workspace import Workspacelog = logging.getLogger(__name__)@@ -295,9 +295,6 @@ class GenerationTask(BaseModel):thinking: str = "medium"max_output_tokens: int = 65_536 # the model's declared ceiling; unused tokens cost nothingtimeout_s: int | None = None- max_turns: int = Field(- default=0, description="model turns for an agent session (0 = the harness default)"- )write_roots: list[str] = Field(default_factory=lambda: ["src", "public"])edit_only: bool = Field(default=False,@@ -549,15 +546,12 @@ def run_agent_task(settings: Any | None = None,budget: Any | None = None,events: Any | None = None,- max_turns: int = 0,- wrapup_turns: int = DEFAULT_WRAPUP_TURNS,) -> GenerationResult:"""CodingAgent path. ``ok`` = the agent changed files (envelope-vs-disk truth).- A turn cap is applied only when a caller asks for one (``task.max_turns`` >- ``max_turns`` > ``C3D_AGENT_MAX_TURNS`` > ``Settings.limits.agent_max_turns``- > :data:`DEFAULT_AGENT_MAX_TURNS`, which is 0 = the backend's own- ``AgentJob.max_turns``; a 28-turn default was measured and rejected, see the+ A turn cap is applied only when the machine asks for one (``C3D_AGENT_MAX_TURNS`` >+ ``Settings.limits.agent_max_turns`` > :data:`DEFAULT_AGENT_MAX_TURNS`, which is 0 = the+ backend's own ``AgentJob.max_turns``; a 28-turn default was measured and rejected, see themodule docstring). Hitting whatever cap is in force is not a failure: oneshort wrap-up session is asked for a final build and a summary, so the moneyalready spent leaves a buildable workspace instead of a session that was cut@@ -572,7 +566,7 @@ def run_agent_task(# window of its own (repair) is still bounded by the soft share, so a failing# baseline cannot eat the refine rounds' half. (Both found by review 2026-08-29.)timeout = _deadline_preflight(budget, timeout, soft=task.timeout_s is None)- turns_cap = task.max_turns or max_turns or agent_max_turns() # 0 = leave AgentJob's own default+ turns_cap = agent_max_turns() # 0 = leave AgentJob's own default# typed job context honoured by every CodingAgent: round → trajectory dir + ToolContext,# language/track → spatial tool filtering, files_hint → the edit_only scope.language, track = _spec_lang_track(ws)@@ -613,7 +607,7 @@ def run_agent_task(session_usd=round(acc.usage.cost_usd, 4),)wrap = job.model_copy(- update={"prompt": WRAPUP_PROMPT + prompt, "max_turns": max(2, int(wrapup_turns))}+ update={"prompt": WRAPUP_PROMPT + prompt, "max_turns": DEFAULT_WRAPUP_TURNS})res = acc.run(agent, wrap, wrapup=True, optional=True) or reschanges = res.files_changed or changes or _attributed_fallback(ws, task, before)@@ -765,12 +759,7 @@ def _images_block(images: list[ImagePart], ws: Workspace) -> str:def _spec_lang_track(ws: Workspace) -> tuple[str, str]:"""Best-effort ``(language, track)`` from the workspace's spec.json ("" when absent)."""- if not ws.spec_path.is_file():- return "", ""- try:- spec_d = ws.read_json(ws.spec_path)- except Exception: # noqa: BLE001 — best effort context only- return "", ""+ spec_d = read_json_or_none(ws.spec_path) or {}return str(spec_d.get("language", "")), str(spec_d.get("track", ""))@@ -835,8 +824,6 @@ def generate(settings: Any | None = None,budget: Any | None = None,events: Any | None = None,- max_turns: int = 0,- wrapup_turns: int = DEFAULT_WRAPUP_TURNS,) -> GenerationResult:"""Dispatch to the single-shot or the coding-agent strategy by ``agent_id``.@@ -867,6 +854,4 @@ def generate(settings=settings,budget=budget,events=events,- max_turns=max_turns,- wrapup_turns=wrapup_turns,)diff --git a/harness/codeverse3d/tracks/graphics.py b/harness/codeverse3d/tracks/graphics.pyindex d85234d6..fb108620 100644--- a/harness/codeverse3d/tracks/graphics.py+++ b/harness/codeverse3d/tracks/graphics.py@@ -37,18 +37,15 @@ from codeverse3d.orchestrator import TaskGroupfrom codeverse3d.prompts import renderfrom codeverse3d.prompts.sections import Section, split_sectionsfrom codeverse3d.tracks.common import RunContext-from codeverse3d.tracks.generation import SINGLE_SHOT_FORMAT, GenerationTask+from codeverse3d.tracks.generation import GenerationTaskfrom codeverse3d.tracks.lifecycle import BaseTrack, StageRunnerfrom codeverse3d.tracks.planner import add_acceptance_itemfrom codeverse3d.tracks.prompting import (- AGENT_OUTPUT_RULES,- acceptance_lines,- constraints_text,+ base_prompt_context,is_always_chapter,judge_digest,judged_sheet,reference_images,- reference_note,refine_inline_files,select_cookbook_chapters,skeleton_files,@@ -344,26 +341,18 @@ def passes_table(plan: GraphicsPlan | None) -> str:def graphics_prompt_context(ctx: RunContext, **extra: Any) -> dict[str, Any]:- """Every variable the graphics templates may reference (StrictUndefined)."""+ """Every variable the graphics templates may reference (StrictUndefined): the base+ context (``prompting.base_prompt_context``) plus the graphics plan's own fields."""plan = ctx.plan if isinstance(ctx.plan, GraphicsPlan) else Noneres = plan.resolution if plan else (1280, 720)- d: dict[str, Any] = {- "track": ctx.track.value, "language": ctx.language.value, "contract": ctx.contract_text,- "cookbook_rel": ctx.cookbook_rel, "cookbook_excerpt": ctx.cookbook_text, "tool_cards": ctx.tool_cards,+ return base_prompt_context(ctx, **{# the recipes seed_recipes() put in the harness-owned src/recipes.glsl before the session ([] = no block)"seeded_recipes": list(ctx.extra.get(EXTRA_KEY) or []),- "single_shot": ctx.single_shot, "output_format": SINGLE_SHOT_FORMAT if ctx.single_shot else AGENT_OUTPUT_RULES,- "spec_prompt": ctx.spec.prompt, "constraints": constraints_text(ctx.spec),- "title": plan.title if plan else "Untitled effect", "plan_summary": plan.summary if plan else "",+ "title": plan.title if plan else "Untitled effect","style": plan.style if plan else "", "resolution": f"{res[0]}x{res[1]}", "duration": f"{plan.duration_s:g}" if plan else "8","passes_table": passes_table(plan), "motion": plan.motion if plan else "", "key_visuals": list(plan.key_visuals) if plan else [],"uniforms": ", ".join(plan.uniforms) if plan and plan.uniforms else "u_time, u_resolution",- "acceptance": acceptance_lines(plan), "entry_files": ", ".join(getattr(ctx.runtime, "entry_globs", ()) or ()),- "expected_files": graphics_expected_files(ctx), "reference_note": reference_note(ctx),- "judge_times": "0, 1, 2.5, 4, 6 s",- }- d.update(extra)- return d+ "expected_files": graphics_expected_files(ctx), "judge_times": "0, 1, 2.5, 4, 6 s", **extra})# ----------------------------------------------------------------------------- renders / gatesdiff --git a/harness/codeverse3d/tracks/lifecycle.py b/harness/codeverse3d/tracks/lifecycle.pyindex 061ccbdf..b6ccb6c9 100644--- a/harness/codeverse3d/tracks/lifecycle.py+++ b/harness/codeverse3d/tracks/lifecycle.py@@ -29,7 +29,6 @@ from codeverse3d.cost.context import run_bindingfrom codeverse3d.cost.instrument import run_ledgerfrom codeverse3d.orchestrator import (KIND_FOR_STRATEGY,- BestSelector,BudgetExceeded,BudgetGuard,BudgetSnapshot,@@ -46,7 +45,7 @@ from codeverse3d.orchestrator import (hash_inputs,plan_refine_groups,)-from codeverse3d.proc import EventLog+from codeverse3d.proc import EventLog, read_json_or_nonefrom codeverse3d.prompts import renderfrom codeverse3d.tracks.candidates import choose_best_round, replay_best_round, run_best_of_nfrom codeverse3d.tracks.common import (@@ -741,7 +740,7 @@ class BaseTrack:def _promote_best(self, ctx: RunContext, rounds: list[RoundRecord], index: int) -> None:"""Rank round ``index`` in (pairwise tie-break included), promote the best, save."""- best = choose_best_round(ctx, rounds, BestSelector(), index)+ best = choose_best_round(ctx, rounds, index)ctx.state.best_considered_through = index # this round HAS been rankedif best is not None and ctx.state.update_best(best, rounds[best].commit, rounds[best].score):ctx.events.emit("best.updated", round=best, score=rounds[best].score)@@ -899,7 +898,6 @@ class BaseTrack:hook compares content hashes so a texture pass from an EARLIER round (whoseGLB has since been rebuilt) does not suppress the final one."""import hashlib- import json as _jsonfrom codeverse3d.texturing.run import report_path@@ -908,7 +906,7 @@ class BaseTrack:if not report.is_file() or not glb.is_file():return Falsetry:- data = _json.loads(report.read_text())+ data = read_json_or_none(report) or {}prev = Path(str(data.get("glb_in") or ""))if not prev.is_file():return Falsediff --git a/harness/codeverse3d/tracks/plan_features.py b/harness/codeverse3d/tracks/plan_features.pyindex a2dd5393..78ec7902 100644--- a/harness/codeverse3d/tracks/plan_features.py+++ b/harness/codeverse3d/tracks/plan_features.py@@ -4,8 +4,8 @@ Born as the switchboard for the plan-loop-engineering wave (CQ-5): six featuresdeclared under ``C3D_PLAN_FEATURES``, none was ever implemented, and one A/B run is onrecord printing "keep, mean delta +0.344" for two byte-identical arms. The featureruntime (``parse_features`` / ``plan_feature_on``) was deleted 2026-08-28 per its own-instruction; the six names stay only so ``pin_plan_blockers`` can classify a pinned-A/B, and what else remains is the guard rail — :data:`LIVE_SWITCHES` / :data:`DEAD_SWITCHES` (kept honest by+instruction, and the six names with it (2026-09-22); what remains is the guard rail —+:data:`LIVE_SWITCHES` / :data:`DEAD_SWITCHES` (kept honest by``tests/orchestrator_tracks/test_plan_features.py``, which greps the tree) and the``--pin-plan`` blocker rule ``bench/ab_plan.py`` consults so a paired A/B cannotsilently pin away the very thing it is testing.@@ -15,18 +15,6 @@ from __future__ import annotationsPLAN_FEATURES_ENV = "C3D_PLAN_FEATURES"-#: the six switch names the wave defined. Nothing reads them at runtime any more —-#: they remain because ``pin_plan_blockers`` still classifies a C3D_PLAN_FEATURES-#: value inside a MIXED A/B env, and that classification must not silently widen.-FIT = "fit"-CONTACTS = "contacts"-GRAPH = "graph"-GRAPH_BUDGET = "graph_budget"-GRAPH_EXAMPLE = "graph_example"-CONSISTENCY = "consistency"-KNOWN_FEATURES: tuple[str, ...] = (FIT, CONTACTS, GRAPH, GRAPH_BUDGET, GRAPH_EXAMPLE, CONSISTENCY)-#: the one generation-side switch; ``pin_plan_blockers`` treats the rest as plan-side-GENERATION_SIDE: frozenset[str] = frozenset({CONTACTS})#: env switches that act AFTER planning — ``--pin-plan`` may share one plan across arms#: that differ only by these. Anything not listed is treated as plan-side: refusing to#: pin costs one noisy A/B, pinning wrongly costs a confident wrong answer@@ -42,20 +30,11 @@ def pin_plan_blockers(variant_env: dict[str, str]) -> list[str]:Empty list = every switch this A/B changes acts after planning, so both arms can beseeded with the same ``plan.json`` and the paired difference stops carrying the- planner's spread (the dominant variance term, docs/EVAL.md §8.1).+ planner's spread (the dominant variance term, eval/docs/EVAL.md §8.1). A+ :data:`DEAD_SWITCHES` key blocks nothing: no code reads it, so it cannot change a plan."""- blockers: list[str] = []- for key, value in sorted(variant_env.items()):- if key == PLAN_FEATURES_ENV:- names = set(KNOWN_FEATURES) if value.strip() == "all" else {- n.strip().lstrip("-") for n in value.split(",") if n.strip()}- for name in sorted(names & (set(KNOWN_FEATURES) - GENERATION_SIDE)):- blockers.append(f"{PLAN_FEATURES_ENV}={name} changes the plan itself")- elif key in GENERATION_SIDE_ENV:- continue- else:- blockers.append(f"{key} is not known to act after planning")- return blockers+ return [f"{key} is not known to act after planning" for key in sorted(variant_env)+ if key not in GENERATION_SIDE_ENV and key not in DEAD_SWITCHES]#: Plan-loop switches the tree ACTUALLY reads, name → the module that reads it. Kept#: honest by tests/orchestrator_tracks/test_plan_features.py, which greps the tree.@@ -93,7 +72,7 @@ LIVE_SWITCHES: dict[str, str] = {#: it: a rig that cannot tell a live switch from a dead one produces confident verdicts#: about nothing. A name leaves this dict in the same commit as the code that reads it.DEAD_SWITCHES: dict[str, str] = {- PLAN_FEATURES_ENV: "no feature in KNOWN_FEATURES is implemented; nothing reads this variable",+ PLAN_FEATURES_ENV: "none of its six features was ever implemented; nothing reads this variable",}@@ -102,6 +81,5 @@ def dead_env_keys(env: dict[str, str]) -> list[str]:return sorted(k for k in env if k in DEAD_SWITCHES)-__all__ = ["CONSISTENCY", "CONTACTS", "DEAD_SWITCHES", "FIT", "GENERATION_SIDE",- "GENERATION_SIDE_ENV", "GRAPH", "GRAPH_BUDGET", "GRAPH_EXAMPLE", "KNOWN_FEATURES",- "LIVE_SWITCHES", "PLAN_FEATURES_ENV", "dead_env_keys", "pin_plan_blockers"]+__all__ = ["DEAD_SWITCHES", "GENERATION_SIDE_ENV", "LIVE_SWITCHES", "PLAN_FEATURES_ENV", "dead_env_keys",+ "pin_plan_blockers"]diff --git a/harness/codeverse3d/tracks/planner.py b/harness/codeverse3d/tracks/planner.pyindex 862e3b69..73a8dfa1 100644--- a/harness/codeverse3d/tracks/planner.py+++ b/harness/codeverse3d/tracks/planner.py@@ -560,7 +560,7 @@ def plan_example(track: Track) -> dict[str, Any]:P = TypeVar("P", bound=BaseModel)#: re-ask budgets — a plan the SCHEMA rejects and a plan the QUALITY gate rejects are-#: different failures and get separate chances (see ``plan_with_usage``).+#: different failures and get separate chances (see ``plan``).MAX_VALIDATION_REASKS = 2 # was 1: compare_art_v2 lost 5 of 14 articulated prompts at this gate (2026-08-25)MAX_QUALITY_REASKS = 1#: a validation failure whose plan is DEGENERATE (joints naming links the plan never lists)@@ -782,25 +782,8 @@ def plan[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Workstemplate: str | None = None, example: dict[str, Any] | None = None, temperature: float = 0.4,max_output_tokens: int = 24000, finalise: FinalisePlan | None = None,event_stats: EventStats | None = None) -> P:- """Plan and write ``ws.plan_path``. ``model`` may be injected (tests).-- Every attempt's money is booked inside ``plan_with_usage`` the moment it is- paid (brief, first call, each re-ask) — success, ``PlanningError`` and a crash- on a LATER attempt all leave the earlier dollars in the guard. The ceilings- are enforced once here, after the plan is written."""- result, _ = plan_with_usage(spec, model_id, plan_model, ws, model=model, events=events, guard=budget,- runtime=runtime, template=template, example=example, temperature=temperature,- max_output_tokens=max_output_tokens, finalise=finalise, event_stats=event_stats)- if budget is not None:- budget.check()- return result---def plan_with_usage[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P], ws: Workspace, *, model: Any | None = None,- events: Any | None = None, guard: Any | None = None, runtime: Any | None = None, template: str | None = None,- example: dict[str, Any] | None = None, temperature: float = 0.4, max_output_tokens: int = 24000,- finalise: FinalisePlan | None = None, event_stats: EventStats | None = None) -> tuple[P, Usage]:- """Optional brief expansion → one structured planner call → up to two re-asks.+ """Plan and write ``ws.plan_path``: optional brief expansion → one structured planner+ call → re-asks (schema, quality, a degenerate-plan restart). ``model`` may be injected (tests).Parameterised by the track hooks: ``template``/``example`` (system prompt),``finalise`` (post-validation fixup, default = ``ensure_acceptance(normalise_names(...))``)@@ -818,12 +801,14 @@ def plan_with_usage[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P]instead of killing the run — the deeper plan is longer JSON and Gemini bills thinkingagainst the same ceiling.- ``guard`` (a ``BudgetGuard``; named so because ``budget`` is this function's local- PlanBudget) is booked with a non-enforcing ``add`` the moment each call is PAID —- brief, first call, every re-ask — so a later attempt that raises can never erase an- earlier attempt's dollars. ``PlanningError`` still carries the total usage for- guard-less callers; when ``guard`` is given those dollars are already booked and the- caller must NOT charge them again (:func:`plan` just runs one final ``check()``)."""+ ``budget`` (the run's ``BudgetGuard``; ``guard`` below, because ``budget`` becomes this+ request's PlanBudget) is booked with a non-enforcing ``add`` the moment each call is+ PAID — brief, first call, every re-ask — so success, ``PlanningError`` and a crash on a+ LATER attempt all leave the earlier dollars in the guard. ``PlanningError`` still+ carries the total usage for guard-less callers; when a guard is given those dollars are+ already booked and the caller must NOT charge them again. The ceilings are enforced+ once, after the plan is written."""+ guard = budgetif model is None:from codeverse3d.models import get_chat_model@@ -943,7 +928,9 @@ def plan_with_usage[P: BaseModel](spec: Spec, model_id: str, plan_model: type[P]events.emit("plan.done", model=model_id, **stats,cost_usd=round(usage.cost_usd, 4), prompt_hash=prompt_hash(system), attempt=attempt,brief=brief is not None, quality_reasks=requeried, restarts=restarts, **budget.as_dict())- return result, usage+ if guard is not None:+ guard.check()+ return resultraise PlanningError(f"plan did not validate after re-ask: {last_error}", usage)@@ -1081,5 +1068,5 @@ __all__ = ["MAX_PLAN_RESTARTS", "MAX_QUALITY_REASKS", "MAX_VALIDATION_REASKS","PLAN_RESTART_ENV", "PLAN_TOKENS_MAX", "PlanningError", "add_acceptance_item","articulation_acceptance", "build_system_prompt", "build_user_prompt", "default_event_stats","ensure_acceptance", "missing_link_names", "normalise_names", "plan",- "degenerate_plan", "plan_example", "plan_tokens", "plan_with_usage", "restart_enabled",+ "degenerate_plan", "plan_example", "plan_tokens", "restart_enabled","restart_note"]diff --git a/harness/codeverse3d/tracks/repair.py b/harness/codeverse3d/tracks/repair.pyindex 06172dcd..a77625f5 100644--- a/harness/codeverse3d/tracks/repair.py+++ b/harness/codeverse3d/tracks/repair.py@@ -22,7 +22,7 @@ from codeverse3d.prompts import renderfrom codeverse3d.tracks import skills_hookfrom codeverse3d.tracks.common import RunContext, generate_forfrom codeverse3d.tracks.generation import GenerationResult, GenerationTask-from codeverse3d.tracks.prompting import base_prompt_context, language_system_prompt+from codeverse3d.tracks.prompting import base_prompt_context, current_files, language_system_promptlog = logging.getLogger(__name__)@@ -40,7 +40,6 @@ class RepairOutcome(BaseModel):lint: GateReportattempts: list[GenerationResult] = Field(default_factory=list)usage: Usage = Field(default_factory=Usage)- repaired: bool = Falsemax_attempts: int = Field(default=0, description="repair budget this outcome ran under")@property@@ -113,7 +112,8 @@ def relevant_cookbook_section(cookbook: str, error_text: str, *, max_chars: intdef files_for_repair(ctx: RunContext, build: BuildResult, lint: GateReport, files_hint: list[str]) -> dict[str, str]:- """Current contents of the failing file(s) (≤ 40k chars total) for single-shot repair."""+ """Current contents of the failing file(s) (≤ 40k chars total) for single-shot repair —+ inlined by ``prompting.current_files``, which never inlines a harness-owned file."""cands: list[str] = []if build.error_file:cands.append(_rel(ctx, build.error_file))@@ -124,20 +124,7 @@ def files_for_repair(ctx: RunContext, build: BuildResult, lint: GateReport, fileif not cands:for glob in getattr(ctx.runtime, "entry_globs", ()) or ():cands.extend(str(p.relative_to(ctx.ws.root)) for p in sorted(ctx.ws.root.glob(glob)))- out: dict[str, str] = {}- total = 0- for rel in dict.fromkeys(cands):- p = ctx.ws.root / rel- if not p.is_file():- continue- text = p.read_text(errors="replace")- if total + len(text) > MAX_REPAIR_CONTEXT_CHARS:- text = text[: max(0, MAX_REPAIR_CONTEXT_CHARS - total)] + "\n// ... truncated ..."- out[rel] = text- total += len(text)- if total >= MAX_REPAIR_CONTEXT_CHARS:- break- return out+ return current_files(ctx, list(dict.fromkeys(cands)), MAX_REPAIR_CONTEXT_CHARS)def _rel(ctx: RunContext, path: str) -> str:@@ -217,7 +204,6 @@ def build_with_repair(ctx: RunContext, *, round_index: int, label: str, files_hi# another session would spend its whole window at the same wallctx.events.emit("repair.storm", round=round_index, attempt=attempt, notes=res.notes[:200])break- outcome.repaired = outcome.ok and attempt > 0return outcomediff --git a/harness/codeverse3d/tracks/scene_assets.py b/harness/codeverse3d/tracks/scene_assets.pyindex 55ce9168..55a5ec81 100644--- a/harness/codeverse3d/tracks/scene_assets.py+++ b/harness/codeverse3d/tracks/scene_assets.py@@ -36,7 +36,8 @@ from codeverse3d.contracts.plan import AssetPlan, BBox, PartPlan, ScenePlan, Stafrom codeverse3d.contracts.spec import Constraints, Specfrom codeverse3d.conventions import OBJECT_VIEWS_QUICK, to_pascal, to_snakefrom codeverse3d.judges.rubrics import is_degraded-from codeverse3d.proc import fan_out, write_json_atomic, write_text_atomic+from codeverse3d.orchestrator import BudgetExceeded+from codeverse3d.proc import fan_out, read_json_or_none, write_json_atomic, write_text_atomicfrom codeverse3d.prompts import renderfrom codeverse3d.tracks.common import (RunContext,@@ -202,20 +203,13 @@ def _spec_hashes_path(ctx: RunContext) -> Path:def _spec_hash_matches(ctx: RunContext, asset: AssetPlan) -> bool:"""False when unrecorded (pre-fix runs regenerate once, then reuse)."""- try:- recorded = json.loads(_spec_hashes_path(ctx).read_text())- except (OSError, ValueError):- return False- return recorded.get(asset.name) == _asset_spec_hash(asset)+ return (read_json_or_none(_spec_hashes_path(ctx)) or {}).get(asset.name) == _asset_spec_hash(asset)def _record_spec_hashes(ctx: RunContext, results: dict[str, AssetResult], assets: list[AssetPlan]) -> None:by_name = {a.name: a for a in assets}path = _spec_hashes_path(ctx)- try:- recorded = json.loads(path.read_text())- except (OSError, ValueError):- recorded = {}+ recorded = read_json_or_none(path) or {}for name, r in results.items():if r.ok and name in by_name:recorded[name] = _asset_spec_hash(by_name[name])@@ -297,8 +291,6 @@ def _ladder(ctx: RunContext, asset: AssetPlan, rel: str, *, language: Language,res = _generate_asset(sub, asset, rel, language=language, attempt=attempt, files=files,feedback=feedback)except Exception as e: # noqa: BLE001 — a bad answer escalates; a dead model does not- from codeverse3d.orchestrator import BudgetExceeded-if isinstance(e, BudgetExceeded):raiseoutage = is_model_outage(e)@@ -340,8 +332,6 @@ def _ladder(ctx: RunContext, asset: AssetPlan, rel: str, *, language: Language,res2 = _generate_asset(sub, asset, rel, language=language, attempt=2, files=files,feedback=repair_feedback(chk, rel))except Exception as e: # noqa: BLE001 — same rule as the ladder's own single-shots- from codeverse3d.orchestrator import BudgetExceeded-if isinstance(e, BudgetExceeded):raiselog.warning("storm repair of %s failed: %s", asset.name, e)@@ -519,8 +509,6 @@ def hero_plan(sub: RunContext, asset: AssetPlan) -> StaticPlan:plan = run_planner(spec2, spec2.backends.planner, StaticPlan, sub.ws, model=model, events=sub.events,budget=sub.budget, runtime=sub.runtime, **track._plan_kwargs(spec2))except Exception as e: # noqa: BLE001 — PlanningError / outage: the sheet still says what the prop is- from codeverse3d.orchestrator import BudgetExceeded-if isinstance(e, BudgetExceeded):raiselog.warning("hero planner failed for %s, using the one-part sheet: %s", asset.name, e)@@ -1033,11 +1021,8 @@ def write_dedupe_note(ws: Workspace, alias: dict[str, str]) -> None:def read_dedupe_note(ws: Workspace) -> dict[str, str] | None:"""The merge map the asset stage used, or None when no stage has run in this workspace."""- p = ws.root / "stages" / "asset_aliases.json"- try:- return dict(json.loads(p.read_text()).get("alias") or {})- except (OSError, ValueError):- return None+ data = read_json_or_none(ws.root / "stages" / "asset_aliases.json")+ return None if data is None else dict(data.get("alias") or {})def write_variant_shims(ws: Workspace, alias: dict[str, str], available: set[str]) -> list[str]:diff --git a/harness/codeverse3d/tracks/skills_hook.py b/harness/codeverse3d/tracks/skills_hook.pyindex d5be7851..c0588dff 100644--- a/harness/codeverse3d/tracks/skills_hook.py+++ b/harness/codeverse3d/tracks/skills_hook.py@@ -11,7 +11,6 @@ the round. The switch is read at CALL time (see ``skills/config.py`` for why).from __future__ import annotations-import jsonimport loggingfrom collections.abc import Sequencefrom pathlib import Path@@ -21,6 +20,7 @@ from pydantic import ValidationErrorfrom codeverse3d.contracts.artifacts import GateReportfrom codeverse3d.contracts.run import SkillsUsage+from codeverse3d.proc import read_json_or_nonefrom codeverse3d.tracks.common import RunContextlog = logging.getLogger(__name__)@@ -40,12 +40,8 @@ def _previous_findings(ctx: RunContext, index: int) -> list[GateReport]:if not d.is_dir():return []for p in sorted(d.glob("r*.json"), reverse=True):- try:- data = json.loads(p.read_text())- except (OSError, json.JSONDecodeError) as e:- log.debug("skills: unreadable round record %s: %s", p, e)- continue- if int(data.get("index", -1)) >= index:+ data = read_json_or_none(p)+ if data is None or int(data.get("index", -1)) >= index: # unreadable, or not before this roundcontinuegates = data.get("gates") or []if gates:diff --git a/harness/codeverse3d/tracks/steps.py b/harness/codeverse3d/tracks/steps.pyindex 8d135a22..bcc38905 100644--- a/harness/codeverse3d/tracks/steps.py+++ b/harness/codeverse3d/tracks/steps.py@@ -209,8 +209,6 @@ def run_round(extra_usage: Usage | None = None,extra_notes: Sequence[str] = (),previous_best: float | None = None,- render: RenderFn | None = None,- geometry_views: bool = True,) -> RoundRecord:"""Execute one round and persist its record. Budget is charged as it goes.@@ -219,15 +217,15 @@ def run_round(judge only. ``extra_usage`` / ``extra_notes`` fold pre-round work(candidate generation) into the record; ``previous_best`` is the best scorebefore this round, used only to flag the round as wasted in ``cost.round``.- ``render`` replaces ``pipeline.render`` and ``geometry_views=False`` skips the- clay views: the two knobs a best-of-N candidate turns (``candidates.run_best_of_n``- runs each candidate as this round in its sub-workspace)."""+ ``_run_round`` (the same round without the aborted-round record) also takes+ ``render`` (replaces ``pipeline.render``) and ``geometry_views=False`` (skips the+ clay views): the two knobs a best-of-N candidate turns (``candidates.run_best_of_n``+ calls it directly for each candidate in its sub-workspace)."""mark = ctx.budget.mark()try:return _run_round(ctx, index=index, kind=kind, tasks=tasks, pipeline=pipeline, instructions=instructions,previous=previous, files_hint=files_hint, extra_usage=extra_usage,- extra_notes=extra_notes, previous_best=previous_best, render=render,- geometry_views=geometry_views)+ extra_notes=extra_notes, previous_best=previous_best)except BaseException as e:# the round died half-way (budget stop, 503 storm, RoundFailed). Whatever it# burned is already in the guard: report it so the round is not invisible.@@ -565,7 +563,4 @@ def failed_acceptance(ctx: RunContext, judgment: Judgment | None) -> list[Acceptdef sum_usage(rounds: Sequence[RoundRecord]) -> Usage:- total = Usage()- for r in rounds:- total = total + r.usage- return total+ return sum((r.usage for r in rounds), Usage())diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 2bea1868..c9e50f7f 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -167,13 +167,13 @@ codeverse3d/materials.py (named material library), run.py (texture_pass); __init__.py isdocstring-only — import from the submodulesorchestrator.py the round loop's LIBRARY, not the loop: round POLICIES (RoundPolicy /- StopPolicy / BestSelector), refine-task compilation + grouping,+ StopPolicy / pick_best_round), refine-task compilation + grouping,StageRunner + RunState (resume), BudgetGuard. The loop itself istracks/lifecycle.py:_round_loop → tracks/steps.py:run_round. A best-of-Ncandidate IS steps._run_round(kind='candidate') in a _cand/c<k> sub-workspacewith two knobs (render=candidates.quick_render, geometry_views=False), itsown _cand/c<k>/events.jsonl and a one-sample judge- tracks/ __init__.py (get_track(track, **options) + the TrackPipeline protocol),+ tracks/ __init__.py (get_track(track, **options) → a lifecycle.BaseTrack),lifecycle.py, steps.py, candidates.py (best-of-N + the pure candidate/pairwisedecision logic), generation.py (agent + single-shot strategies + the fileenvelope), repair.py, planner.py, prompting.py (prompt helpers, split from common),@@ -187,9 +187,9 @@ codeverse3d/shown; AgentJob.read_only, C3D_SEED_RECIPES),planner.py (the ONE planner loop + the cached EngineeringBrief(C3D_PLAN_BRIEF), plan budgets and the worked examples),- plan_features.py (C3D_PLAN_FEATURES: one switch per plan-loop change, so each- can be A/B'd alone, + pin_plan_blockers() deciding when two arms may share- one plan — eval/docs/EVAL.md §8.1),+ plan_features.py (the A/B switch registry: LIVE_SWITCHES / DEAD_SWITCHES,+ + pin_plan_blockers() deciding when two arms may share one plan —+ eval/docs/EVAL.md §8.1),depth.py,skills_hook.py (the round's view of codeverse3d/skills: attach before generating,probe reads after — a no-op unless C3D_SKILLS is on)@@ -443,11 +443,11 @@ repeat while StopPolicy says continue (≤ max_rounds refine rounds, plateau_winfan out when ≥ 2 file-disjoint groups AND every task maps to files (threejs/blender parts, scene zones/assets/env)generate (no HARNESS turn cap by default — claude-code runs under AgentJob.max_turns=60 (+6-turn wrap-up),the other vendor CLIs have no turn cap at all; 28 was A/B'd and rejected, +$0.02/−0.21 score, docs/COST.md §17;- a cap a caller sets (C3D_AGENT_MAX_TURNS / task; no profile sets one) still buys a wrap-up session+ a cap the machine sets (C3D_AGENT_MAX_TURNS / limits.agent_max_turns; no profile sets one) still buys a wrap-up sessionthat lands a final build + summary instead of being killed) → build+repair (error-focused,escalates on identical signatures) → gates → … → judge (SKIPPED only where the verdict is neverbought at all: no judge/renders or budget already exceeded)- BestSelector: highest score, tie → fewer gate errors; |Δ| < pairwise_margin (0.03) → position-swapped+ pick_best_round: highest score, tie → fewer gate errors; |Δ| < pairwise_margin (0.03) → position-swappedPairwiseJudge decides (replace only at confidence ≥ 0.6; note persisted in rNN.json)every round emits cost.round {stage → $, judge $, agent turns, wasted flag}; a round that raises mid-waystill reports what it burned (rounds/aborted_rNN.json + record.extra["aborted_rounds"])diff --git a/harness/docs/COST.md b/harness/docs/COST.mdindex b97a67b5..0cf6916c 100644--- a/harness/docs/COST.md+++ b/harness/docs/COST.md@@ -351,7 +351,7 @@ Savings are estimated **on this data set** (61 runs, $86.30) unless stated.|---|---|---|---|---|| 1 | **Stop refining after r01 unless the last delta ≥ 0.05.** r02+r03 cost $12.16 and bought +1.44 score points across 8 of 20 rounds. | **$9–12 (10–13%)** | high (measured) | `RoundPolicy` (min_delta 0.02 → 0.05 from r02, or plateau_window 1 after r01) || 2 | **Check the budget *before* starting a round, against the estimated round cost**, not only between steps. | **$8.76 (9.7%)** | high (measured waste) | `orchestrator.py` (`BudgetGuard`) + `tracks/steps.py`; use `codeverse3d.cost.estimate_call` / median round cost |-| 3 | ~~**Cap agent turns at ~25 and compact old tool results.** 39.3% of the agent bill is turn ≥20; 19 of the 33 sessions that ran ≥50 turns were cut off by their own budget.~~ **Tested, rejected: +$0.02 and −0.21 score** (A/B, n=3 per arm, §17) — the cap is off by default. | est. $8–15, **measured $0** | high (A/B) | `RoundPolicy.agent_max_turns=0`; still settable per caller |+| 3 | ~~**Cap agent turns at ~25 and compact old tool results.** 39.3% of the agent bill is turn ≥20; 19 of the 33 sessions that ran ≥50 turns were cut off by their own budget.~~ **Tested, rejected: +$0.02 and −0.21 score** (A/B, n=3 per arm, §17) — the cap is off by default. | est. $8–15, **measured $0** | high (A/B) | `DEFAULT_AGENT_MAX_TURNS=0`; `$C3D_AGENT_MAX_TURNS` / `Settings.limits.agent_max_turns` still set one || 4 | **Fold the off-record spend into the budget** (cut rounds, post-hoc texture passes). | $0 saved, **$1.22 of blindness removed** | high | §6; the ledger (`codeverse3d.cost.record_call`) makes it automatic || 5 | **Scene track: 73% of scene spend is assets+zones, 0/5 passed.** Trim the per-zone context (each zone session re-sends the whole scene contract) and judge assets before zones start. | ~$1/run of $2.83 | medium | `tracks/scene*.py` || 6 | **Drop `oneshot:claude-code` from default compare arms** ($1.04/artifact at 0.673 — the worst score per dollar measured). | bench-only | high | `eval/bench/compare_backends.py` arms |@@ -784,11 +784,11 @@ same budget and box; 3 runs per arm; scripts and run dirs inand 0.205 of a score point**: a session stopped at turn 28 leaves work the nextround pays for again, and the wrap-up session it buys is not free either.-So there is no default cap: `RoundPolicy.agent_max_turns = 0` and-`tracks.generation.DEFAULT_AGENT_MAX_TURNS = 0` leave `AgentJob.max_turns` at the-backend's own default. The plumbing stays for callers who choose one —-`GenerationTask.max_turns` > `generate(max_turns=…)` > `$C3D_AGENT_MAX_TURNS` >-`Settings.limits.agent_max_turns` — and a cap that IS set still lands gracefully+So there is no default cap: `tracks.generation.DEFAULT_AGENT_MAX_TURNS = 0` leaves+`AgentJob.max_turns` at the backend's own default. The plumbing stays for a machine+that chooses one — `$C3D_AGENT_MAX_TURNS` > `Settings.limits.agent_max_turns` (the+per-policy / per-task / `generate(max_turns=…)` knobs, never set by any caller, went+2026-09-22) — and a cap that IS set still lands gracefully(wrap-up session, `generate.turn_cap` event). **Nothing sets one by default anymore**: the profiles independently dropped their own caps in the same wave(`cost/profiles.py` carries none), so a cap now only exists when a@@ -811,7 +811,7 @@ Two changes were needed to make the kept branches real:1. `rejudge_round` re-buys a verdict only after the judge was *tried* and failedor came back degraded — never one that policy deliberately skipped. Otherwiseevery skip is a `judge.retry` with the same price tag.-2. `BestSelector` never promotes a round that did not build, and when no round has+2. `pick_best_round` never promotes a round that did not build, and when no round hasa score at all it falls back to the built round with the **fewest gate errors**(later on a tie) instead of simply the last one — an unjudged round that brokethe gates can no longer displace the clean artifact that came before it.diff --git a/harness/docs/INTERFACES.md b/harness/docs/INTERFACES.mdindex 25703f58..57fef9a7 100644--- a/harness/docs/INTERFACES.md+++ b/harness/docs/INTERFACES.md@@ -388,17 +388,14 @@ from codeverse3d.tracks import get_trackrec = get_track(spec.track, **options).run(spec, ws, resume=False) -> RunRecord # Δ kwargs forwarded to the constructor:# services=, judge=, agent=, model=, runtime=, policy=RoundPolicy, settings=, planner_model=, n_candidates=# (CLI --candidates > spec.options.candidates > settings.default_candidates); StaticObject | Articulated | Scene | Graphics-TrackPipeline.run(spec, ws, *, resume=False, force=False) -> RunRecord-from codeverse3d.orchestrator import RoundPolicy, StopPolicy, StopDecision, BestSelector, judge_sigma, \- best_score, last_gain, best_index, REWRITE_KIND, build_refine_instructions, compact_instructions+BaseTrack.run(spec, ws, *, resume=False, force=False) -> RunRecord # get_track returns a tracks.lifecycle.BaseTrack+from codeverse3d.orchestrator import RoundPolicy, StopPolicy, StopDecision, pick_best_round, judge_sigma, \+ best_score, last_gain, REWRITE_KIND, build_refine_instructions, compact_instructionsRoundPolicy(max_rounds=4, plateau_window=2, min_delta=0.02, target=0.8, max_refine_tasks=6,max_instructions_per_task=6, parallel_min_tasks=2, n_candidates=1, pairwise_margin=0.03,pairwise_min_confidence=0.6, judge_samples=1,judge_model="", regression_sigma=1.0, # money stops (docs/COST.md §5)marginal_sigma=1.5, marginal_from_round=3, # r03+ must beat 1.5σ- agent_max_turns=0, agent_wrapup_turns=6, # 0 = the backend's own AgentJob.max_turns (claude-code 60- # +6 wrap-up; gemini-cli/codex/agy no turn cap); a 28-turn cap was A/B'd and rejected (+$0.02, −0.21- # score, docs/COST.md §17); wrapup applies to a cap a caller setsdetail_rounds=None, detail_min_score=0.45, detail_bbox_tol_m=0.005 # surface-detail round, tri-state:# None = the track default (lifecycle.DEFAULT_DETAIL_ROUNDS=1 when supports_detail_round, else 0),# 0 = off, N = N; $C3D_DETAIL_ROUNDS overrides all (the A/B switch). Injected policies keep it.@@ -473,29 +470,29 @@ GenerationTask.phase: int = 0 # tasks run in parallel WITHIN a phase, phases i# (tracks.steps.run_generation_tasks). Only user: the scoped baseline — phase 0 = one session per# part group (`baseline_<parts>`, own files only), phase 1 = ONE `assemble` session that owns the# entry file and the placement gates. Every other caller is phase 0, i.e. unchanged.-generate(ws, *, agent_id, task, ..., budget=BudgetGuard, max_turns=0, wrapup_turns=6) -> GenerationResult+generate(ws, *, agent_id, task, ..., budget=BudgetGuard) -> GenerationResult# GenerationResult.storm: every session died on a transient streak (AgentResult.transient) and wrote nothingtracks.common.generate_for(ctx: RunContext, task: GenerationTask) -> GenerationResult# THE call every stage makes (env, zones, rounds, repairs, asset ladder, judged fix): generate()# with everything ctx knows, and a storm-dead task retried through single_shot_ctx(ctx) (D68)tracks.common.single_shot_agent_id(agent_id, chat_model_id='') -> str · single_shot_ctx(ctx) -> RunContext | None# moved from tracks.scene_assets 2026-09-07 (never scene-specific)- # GenerationResult adds turns / sessions / turn_capped. A turn cap is applied ONLY if a caller- # asks: task.max_turns > max_turns > $C3D_AGENT_MAX_TURNS > settings.limits.agent_max_turns >+ # GenerationResult adds turns / sessions / turn_capped. A turn cap is applied ONLY if the machine+ # asks: $C3D_AGENT_MAX_TURNS > settings.limits.agent_max_turns ># DEFAULT_AGENT_MAX_TURNS (0 = leave AgentJob.max_turns at the backend's own default — a 28-turn# default was measured and rejected, docs/COST.md §17). A session that hits a cap that IS set is# asked for a final build + summary (WRAPUP_PROMPT) instead of being killed.# EVERY session (attempt 1, <label>.a2 retry, <label>.wrapup) is charged as it ends.-from codeverse3d.tracks.repair import build_with_repair # RepairOutcome(.ok/.repaired/.max_attempts, attempts, usage); build_with_repair(ctx, *, round_index, label, files_hint=None, max_attempts=None, timeout_s=None) — timeout_s clips every repair session (a scene asset's window)+from codeverse3d.tracks.repair import build_with_repair # RepairOutcome(.ok/.max_attempts, attempts, usage); build_with_repair(ctx, *, round_index, label, files_hint=None, max_attempts=None, timeout_s=None) — timeout_s clips every repair session (a scene asset's window)# scene assets (tracks/scene_assets.py): build_threejs_asset / build_blender_asset climb ONE ladder (_ladder: single-shot → check → one feedback repair → agent session); a hero's parts come from the static planner (hero_plan); SceneThreeJsRuntime.render_asset(ws, name, out_dir) renders a module on the hero's quick rig; the assembled scene.js plays every GLB clone's clips (clone.userData.clipOffset de-phases a copy)# languages/blender.write_blender_skeleton(ws, plan, *, ground_tol_m=0.002) — the self-check's stands-on-z=0 tolerance (a scene hero passes 0.02)from codeverse3d.tracks.steps import run_round, skip_judge_reason, emit_round_cost, record_aborted_roundskip_judge_reason(ctx, *, renders, ignore_budget=False) -> str # "" = judge it. ONLY states where the# verdict is never bought at all: no judge / no renders / budget already exceeded# (docs/COST.md §17 — "no file change" and "build not repaired" were removed)-run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None, render=None, geometry_views=True) -> RoundRecord- # render: RenderFn | None swaps the pipeline's render (candidates pass quick_render); geometry_views=False skips- # the clay/normals views+run_round(ctx, *, index, kind, tasks, pipeline, ..., previous_best=None) -> RoundRecord+ # steps._run_round (the same round, no aborted-round record) also takes render: RenderFn | None (swaps the+ # pipeline's render; candidates pass quick_render) and geometry_views=False (skips the clay/normals views)# emits cost.round {stages{}, judge_usd, total_usd, agent_turns, wasted, waste_reason}; on ANY exception it# records what the round burned (rounds/aborted_rNN.json, ctx.extra["aborted_rounds"]) and re-raisesfrom codeverse3d.tracks.planner import plan, ensure_acceptance # graphics uses tracks/graphics.plan_graphicsdiff --git a/harness/docs/RUN_LAYOUT.md b/harness/docs/RUN_LAYOUT.mdindex 27bca735..1172f8d0 100644--- a/harness/docs/RUN_LAYOUT.md+++ b/harness/docs/RUN_LAYOUT.md@@ -103,8 +103,7 @@ the packager produces no diff.`record/telemetry.py::_generator_defaults` — a historical shim thatconfigures nothing, kept so old records still read back); avalue a call site hard-codes per task is left empty with `source` saying so,- never guessed. A track may publish real values as- `record.extra["sampling"][<role>]` and they win (`source: observed`).+ never guessed.* **`usage.jsonl`** — one priced row per model call, in the**`codeverse3d.cost` ledger format** (`CallCost`: tokens, unit prices, priceprovenance, stage, role, outcome). There is exactly one ledger in thediff --git a/harness/tests/agents/test_agent_job_wiring.py b/harness/tests/agents/test_agent_job_wiring.pyindex e2eb4e26..b44e439c 100644--- a/harness/tests/agents/test_agent_job_wiring.py+++ b/harness/tests/agents/test_agent_job_wiring.py@@ -58,7 +58,7 @@ def test_session_window_is_clipped_to_the_hard_clock_not_the_soft_share(tmp_ws:spent); re-clipping it against the SOFT share handed it the 120 s floor (2026-08-29)."""guard = BudgetGuard(Budget(max_minutes=100), soft_fraction=0.5)guard.start_time -= 60 * 60 # 60 of 100 minutes gone: the soft share is spent, 40 min remain- assert guard.soft_remaining()["minutes"] == 0+ assert not guard.soft_ok()agent = StubAgent()run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="refine", prompt="p", timeout_s=900), budget=guard)assert agent.jobs[0].timeout_s == 900diff --git a/harness/tests/orchestrator_tracks/test_budget_snapshot.py b/harness/tests/orchestrator_tracks/test_budget_snapshot.pyindex 2f159e92..63b5a000 100644--- a/harness/tests/orchestrator_tracks/test_budget_snapshot.py+++ b/harness/tests/orchestrator_tracks/test_budget_snapshot.py@@ -36,7 +36,7 @@ def test_resume_restores_money_calls_and_active_time_but_not_downtime():g1.add(Usage(backend="gemini", cost_usd=0.05), stage="judge")g1.start_time -= 120 # two minutes of ACTIVE work in the first sessionsnap = g1.snapshot()- assert snap.version == 1 and snap.active_s == pytest.approx(120, abs=2)+ assert snap.active_s == pytest.approx(120, abs=2)# the exact round-trip run_state.json takes: model_dump(mode="json") → validaterevived = BudgetSnapshot.model_validate(json.loads(json.dumps(snap.model_dump(mode="json"))))@@ -72,7 +72,7 @@ def test_a_raised_cap_grants_only_the_difference_and_grace_never_persists():g2.restore(snap)assert g2.grace_minutes == 0.0assert g2.billed_usd == pytest.approx(0.9), "the spend is restored, not reset"- assert g2.remaining()["minutes"] == pytest.approx(7.0, abs=0.1) # 15 − 8, never a fresh 15+ assert g2.timeout_s(3600, floor_s=0, soft=False) == pytest.approx(7 * 60, abs=6) # 15 − 8, never a fresh 15def test_build_context_restores_the_budget_snapshot(tmp_path, settings):@@ -197,8 +197,7 @@ def test_a_budget_tripped_candidate_still_lets_the_sibling_be_adopted(tmp_path,def writer(job, ws_):if ws_.root.name == "c0": # <ws>/_cand/c0 trips the ceiling mid-generation- raise BudgetExceeded("elapsed 9.99 min exceeds max_minutes 5.00",- spent_usd=9.99, elapsed_min=9.99)+ raise BudgetExceeded("elapsed 9.99 min exceeds max_minutes 5.00", spent_usd=9.99)return {"src/object.js": f"// {job.label} in {ws_.root.name}\n""export function build(THREE) { return new THREE.Group(); }\n"}@@ -285,7 +284,7 @@ def test_a_skeleton_only_budget_trip_still_salvages_nothing(tmp_path, chair_planadopted winner, so the salvage hook must keep saying no off-scene."""def writer(job, ws_):- raise BudgetExceeded("elapsed 11.0 min exceeds max_minutes 10.0", spent_usd=1.0, elapsed_min=11.0)+ raise BudgetExceeded("elapsed 11.0 min exceeds max_minutes 10.0", spent_usd=1.0)ws = Workspace(tmp_path / "runs" / "bare")track = StaticObjectTrack(services=FakeServices(), judge=FakeJudge(scores=(0.6,)), agent=FakeAgent(writer),diff --git a/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py b/harness/tests/orchestrator_tracks/test_candidates_reference_motion.pyindex afe0ca43..ecce3e34 100644--- a/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py+++ b/harness/tests/orchestrator_tracks/test_candidates_reference_motion.py@@ -431,9 +431,6 @@ def test_a_track_without_a_glb_still_gets_candidate_renders():assert got == "frames-renderset", "no GLB must fall back to the track's own renderer"assert pipe.calls == [(0, build, "MEAS")]- # and with nothing to fall back to, it still degrades quietly rather than raising- assert quick_render(_Ctx(), 0, build, None) is None-def test_an_object_candidate_still_uses_the_cheap_rig(tmp_path):"""The fallback must not make the object path more expensive: a GLB still goes throughdiff --git a/harness/tests/orchestrator_tracks/test_cookbook_excerpt.py b/harness/tests/orchestrator_tracks/test_cookbook_excerpt.pyindex f8f4887a..c451ff7e 100644--- a/harness/tests/orchestrator_tracks/test_cookbook_excerpt.py+++ b/harness/tests/orchestrator_tracks/test_cookbook_excerpt.py@@ -48,14 +48,10 @@ def test_every_track_sends_the_whole_cookbook(monkeypatch) -> None:contract_text="CONTRACT", cookbook_rel="glsl_shader/cookbook.md",cookbook_text=big, tool_cards="", single_shot=True, extra={},runtime=SimpleNamespace(entry_globs=()))- monkeypatch.setattr(graphics_steps, "constraints_text", lambda spec: "")- monkeypatch.setattr(graphics_steps, "reference_note", lambda ctx: "")- monkeypatch.setattr(graphics_steps, "acceptance_lines", lambda plan: "")- assert graphics_steps.graphics_prompt_context(ctx)["cookbook_excerpt"] == big-monkeypatch.setattr("codeverse3d.tracks.prompting.constraints_text", lambda spec: "")monkeypatch.setattr("codeverse3d.tracks.prompting.reference_note", lambda ctx: "")monkeypatch.setattr("codeverse3d.tracks.prompting.acceptance_lines", lambda plan: "")+ assert graphics_steps.graphics_prompt_context(ctx)["cookbook_excerpt"] == bigassert base_prompt_context(ctx)["cookbook_excerpt"] == bigassert base_prompt_context(ctx)["contract"] == "CONTRACT"diff --git a/harness/tests/orchestrator_tracks/test_cost_latency.py b/harness/tests/orchestrator_tracks/test_cost_latency.pyindex d8d1fafa..405a1c0e 100644--- a/harness/tests/orchestrator_tracks/test_cost_latency.py+++ b/harness/tests/orchestrator_tracks/test_cost_latency.py@@ -54,7 +54,7 @@ def test_soft_budget_degrades_before_the_hard_cap_and_grace_reopens_it():g = BudgetGuard(Budget(max_minutes=10.0), soft_fraction=0.55)g.start_time = 0.0g.elapsed_minutes = lambda: clock["t"] # type: ignore[method-assign]- assert g.soft_ok() and g.soft_remaining()["minutes"] == pytest.approx(5.5)+ assert g.soft_ok() and g.timeout_s(3600, floor_s=0) == 330 # 5.5 soft minutes leftclock["t"] = 6.0assert not g.soft_ok() and "soft cap" in g.soft_exceeded()assert g.ok() # the HARD ceiling is untouched: degrade, do not diediff --git a/harness/tests/orchestrator_tracks/test_generation_planner_repair.py b/harness/tests/orchestrator_tracks/test_generation_planner_repair.pyindex 622ac446..dbd32bd3 100644--- a/harness/tests/orchestrator_tracks/test_generation_planner_repair.py+++ b/harness/tests/orchestrator_tracks/test_generation_planner_repair.py@@ -231,7 +231,7 @@ def test_build_with_repair_agent_path_escalates_on_same_error(tmp_ws, settings):ctx = _ctx(tmp_ws, settings, "fake:x", agent=FakeAgent(writer), cookbook="## Intro\nhello\n## RuntimeError boom\nuse boom fix snippet\n")out = build_with_repair(ctx, round_index=0, label="r00")- assert out.ok and out.repaired and len(out.attempts) == 2+ assert out.ok and len(out.attempts) == 2assert "BUILD FAILED" in prompts[0] and "src/model.py:3" in prompts[0] and "boom fix snippet" in prompts[0]assert "SAME ERROR AS THE PREVIOUS ATTEMPT" in prompts[1] and "SAME ERROR" not in prompts[0]kinds = [e["event"] for e in ctx.events.read()]diff --git a/harness/tests/orchestrator_tracks/test_graphics_recipes.py b/harness/tests/orchestrator_tracks/test_graphics_recipes.pyindex 8309d976..a92aecd6 100644--- a/harness/tests/orchestrator_tracks/test_graphics_recipes.py+++ b/harness/tests/orchestrator_tracks/test_graphics_recipes.py@@ -391,3 +391,18 @@ def test_prompt_block_lists_the_seeded_names(tmp_path) -> None:judge_summary="Previous score 0.3", frame_notes="(no frame metrics)", current_files={}))assert "harness-owned, read-only `src/recipes.glsl`" in ref and "do not copy them into common.glsl" in refassert all(f"`{n}`" in ref for n in names)+++def test_a_single_shot_repair_never_inlines_the_harness_owned_recipes(tmp_path) -> None:+ """``repair.files_for_repair`` re-implemented ``prompting.current_files`` without its+ harness-owned rule, so a build error naming src/recipes.glsl pasted the read-only+ file into the single-shot repair prompt as a failing file to rewrite."""+ from codeverse3d.contracts.artifacts import BuildResult, GateReport+ from codeverse3d.tracks.repair import files_for_repair++ ws = _ws(tmp_path, skeleton=False)+ _recipes(ws).write_text("float hash12(vec2 p) { return 0.0; }\n")+ (ws.src / "shader.frag").write_text(SHADER)+ ctx = SimpleNamespace(ws=ws, language=Language.GLSL_SHADER, runtime=SimpleNamespace())+ build = BuildResult(ok=False, language="glsl_shader", error_file=str(_recipes(ws)))+ assert list(files_for_repair(ctx, build, GateReport(gate="lint", passed=True), ["src/shader.frag"])) == ["src/shader.frag"]diff --git a/harness/tests/orchestrator_tracks/test_harness_failure_no_repair.py b/harness/tests/orchestrator_tracks/test_harness_failure_no_repair.pyindex 6d5fe144..a2f9e274 100644--- a/harness/tests/orchestrator_tracks/test_harness_failure_no_repair.py+++ b/harness/tests/orchestrator_tracks/test_harness_failure_no_repair.py@@ -31,7 +31,6 @@ def _ctx(**over):spec=SimpleNamespace(budget=SimpleNamespace(max_repair_attempts=3)),events=SimpleNamespace(emit=lambda *a, **k: None),ws=None, agent_id="x", agent=None, model=None, settings=None, budget=None,- policy=SimpleNamespace(agent_max_turns=8, wrapup_turns=1, agent_wrapup_turns=1),cookbook_text="",)base.__dict__.update(over)diff --git a/harness/tests/orchestrator_tracks/test_orchestrator.py b/harness/tests/orchestrator_tracks/test_orchestrator.pyindex 60c2d3ea..11e9307a 100644--- a/harness/tests/orchestrator_tracks/test_orchestrator.py+++ b/harness/tests/orchestrator_tracks/test_orchestrator.py@@ -19,7 +19,6 @@ from codeverse3d.contracts.common import Budget, Usagefrom codeverse3d.contracts.plan import AcceptanceItemfrom codeverse3d.contracts.run import RoundRecordfrom codeverse3d.orchestrator import (- BestSelector,BudgetExceeded,BudgetGuard,RefineTask,@@ -27,22 +26,14 @@ from codeverse3d.orchestrator import (RunState,StageRunner,StopPolicy,- best_index,build_refine_instructions,hash_inputs,+ pick_best_round,plan_parallel_groups,)from codeverse3d.proc import EventLog, fan_out-def test_best_index_prefers_score_then_task_count_then_recency():- assert best_index([(0.5, 0), (0.7, 2), (0.7, 1), (0.6, 0)]) == 2- assert best_index([(0.7, 1), (0.7, 1)]) == 1- assert best_index([(0.9, 3), (0.8, 0)]) == 0- with pytest.raises(ValueError):- best_index([])--# ----------------------------------------------------------------------------- budgetdef test_budget_guard_charges_and_raises():g = BudgetGuard(Budget(max_minutes=10.0))@@ -59,7 +50,7 @@ def test_budget_guard_time_ceiling():g = BudgetGuard(Budget(max_minutes=0.0001), start_time=time.time() - 10)with pytest.raises(BudgetExceeded):g.check()- assert g.remaining()["minutes"] == 0.0+ assert g.timeout_s(600, floor_s=0, soft=False) == 0 # no wall clock left# ----------------------------------------------------------------------------- fanout@@ -180,11 +171,13 @@ def test_stop_policy_decisions():assert sp.evaluate([_round(0, 0.5), _round(1, None, build_ok=False), _round(2, None, build_ok=False)]).reason == "continue"-def test_best_selector_prefers_score_then_fewer_errors():+def test_pick_best_round_prefers_score_then_fewer_errors_then_recency():rounds = [_round(0, 0.5), _round(1, 0.7, errors=2), _round(2, 0.7, errors=0), _round(3, 0.6)]- assert BestSelector().pick(rounds) == 2- assert BestSelector().pick([]) is None- assert BestSelector().pick([_round(0, None, build_ok=False), _round(1, None, build_ok=True)]) == 1+ assert pick_best_round(rounds) == 2+ assert pick_best_round([_round(0, 0.7, errors=1), _round(1, 0.7, errors=1)]) == 1 # full tie → the later one+ assert pick_best_round([_round(0, 0.9, errors=3), _round(1, 0.8)]) == 0 # score outranks gate errors+ assert pick_best_round([]) is None+ assert pick_best_round([_round(0, None, build_ok=False), _round(1, None, build_ok=True)]) == 1# ----------------------------------------------------------------------------- refine instructionsdiff --git a/harness/tests/orchestrator_tracks/test_plan_features.py b/harness/tests/orchestrator_tracks/test_plan_features.pyindex 02e5d590..82341572 100644--- a/harness/tests/orchestrator_tracks/test_plan_features.py+++ b/harness/tests/orchestrator_tracks/test_plan_features.py@@ -48,7 +48,7 @@ def test_every_dead_switch_is_really_dead(name: str):def test_the_plan_features_switch_is_declared_dead():- """It is: the six KNOWN_FEATURES are not implemented anywhere, so an arm that differs+ """It is: none of its six features was ever implemented, so an arm that differsonly by C3D_PLAN_FEATURES is byte-identical to its control."""assert F.PLAN_FEATURES_ENV in F.DEAD_SWITCHESassert F.dead_env_keys({F.PLAN_FEATURES_ENV: "all"}) == [F.PLAN_FEATURES_ENV]@@ -58,28 +58,24 @@ def test_the_plan_features_switch_is_declared_dead():# --------------------------------------------------------------------- pin-plan safetydef test_a_generation_side_switch_may_share_one_plan():- """`contacts` renders a table into the BUILDER's prompt from an unchanged plan, so- both arms can be seeded with the same plan.json and the paired delta stops carrying- the planner's spread — the dominant variance term (docs/EVAL.md §8.1)."""+ """A switch that acts after planning cannot change the plan, so both arms can be+ seeded with the same plan.json and the paired delta stops carrying the planner's+ spread — the dominant variance term (eval/docs/EVAL.md §8.1)."""from codeverse3d.tracks.plan_features import pin_plan_blockers- assert pin_plan_blockers({"C3D_PLAN_FEATURES": "contacts"}) == []for name in sorted(F.GENERATION_SIDE_ENV):assert pin_plan_blockers({name: "1"}) == [], nameassert pin_plan_blockers({}) == []-def test_a_plan_side_switch_is_refused_by_name():- """Pinning `fit` would hand both arms one plan and so silently delete the change- under test — the rig would then report "no effect" with confidence."""+def test_a_dead_switch_blocks_nothing_but_a_live_neighbour_still_does():+ """No code reads C3D_PLAN_FEATURES, so it cannot change a plan: it never blocks+ --pin-plan (until 2026-09-22 its six never-implemented feature names did)."""from codeverse3d.tracks.plan_features import pin_plan_blockers- assert pin_plan_blockers({"C3D_PLAN_FEATURES": "fit"}) == [- "C3D_PLAN_FEATURES=fit changes the plan itself"]- # one plan-side name in a list of otherwise-safe ones still blocks- assert pin_plan_blockers({"C3D_PLAN_FEATURES": "contacts,fit"}) == [- "C3D_PLAN_FEATURES=fit changes the plan itself"]- assert len(pin_plan_blockers({"C3D_PLAN_FEATURES": "all"})) == 5+ assert pin_plan_blockers({"C3D_PLAN_FEATURES": "fit"}) == []+ assert pin_plan_blockers({"C3D_PLAN_FEATURES": "all", "C3D_PLAN_BRIEF": "off"}) == [+ "C3D_PLAN_BRIEF is not known to act after planning"]def test_an_unclassified_switch_defaults_to_refusing():@@ -92,10 +88,3 @@ def test_an_unclassified_switch_defaults_to_refusing():assert pin_plan_blockers({"C3D_PLAN_BRIEF": "off"}) == ["C3D_PLAN_BRIEF is not known to act after planning"]--def test_every_known_feature_is_classified():- """A new feature must be put on one side or the other in the same commit; otherwise- it silently inherits 'plan-side' and nobody notices the A/B got noisier."""- from codeverse3d.tracks.plan_features import GENERATION_SIDE, KNOWN_FEATURES-- assert set(KNOWN_FEATURES) > GENERATION_SIDEdiff --git a/harness/tests/orchestrator_tracks/test_planner_depth.py b/harness/tests/orchestrator_tracks/test_planner_depth.pyindex 17825e27..921f69a2 100644--- a/harness/tests/orchestrator_tracks/test_planner_depth.py+++ b/harness/tests/orchestrator_tracks/test_planner_depth.py@@ -28,8 +28,8 @@ from codeverse3d.tracks.planner import (build_system_prompt,build_user_prompt,plan_example,- plan_with_usage,)+from codeverse3d.tracks.planner import plan as run_plannerfrom codeverse3d.workspace import Workspacefrom .fakes import FakeChatModel@@ -346,13 +346,12 @@ def test_truncated_plans_keep_growing_output_room(tmp_path, monkeypatch):raise ModelError("structured output unavailable (finish_reason=MAX_TOKENS; raise max_output_tokens)")return good- plan, _u = plan_with_usage(_spec(must=8), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))- return seen, plan+ return seen, run_planner(_spec(must=8), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))for failures in (1, 2):- seen, plan = run(failures)+ seen, got = run(failures)assert len(seen) == failures + 1 and seen == sorted(set(seen))- assert len(plan.parts) == 9+ assert len(got.parts) == 9def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeypatch):@@ -366,7 +365,7 @@ def test_a_model_error_that_is_not_truncation_still_propagates(tmp_path, monkeypraise ModelError("every key is dead")with pytest.raises(ModelError, match="every key is dead"):- plan_with_usage(_spec(), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))+ run_planner(_spec(), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))# ----------------------------------------------------------------------------- the loop@@ -385,10 +384,10 @@ def test_planner_spends_one_quality_reask_then_ships_the_plan(tmp_path, monkeypareturn thinspec = _spec(must=10)- plan, _usage = plan_with_usage(spec, "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))+ got = run_planner(spec, "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))assert calls["n"] == 1 + MAX_QUALITY_REASKSassert "Only 3 parts" in calls["complaints"][0]- assert len(plan.parts) == 3 and ws.plan_path.is_file()+ assert len(got.parts) == 3 and ws.plan_path.is_file()def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):@@ -402,8 +401,8 @@ def test_a_good_plan_costs_exactly_one_call(tmp_path, monkeypatch):calls["n"] += 1return good- plan, _u = plan_with_usage(_spec(must=8), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))- assert calls["n"] == 1 and len(plan.parts) == 9+ got = run_planner(_spec(must=8), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder))+ assert calls["n"] == 1 and len(got.parts) == 9def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, monkeypatch):@@ -429,12 +428,12 @@ def test_brief_and_plan_are_one_model_and_the_events_say_so(tmp_path, monkeypatcself.rows.append((name, kw))ev = _Events()- plan, _u = plan_with_usage(_spec(must=10), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder), events=ev)+ got = run_planner(_spec(must=10), "fake:planner", StaticPlan, ws, model=FakeChatModel(responder), events=ev)assert seen["n"] == 2done = next(kw for name, kw in ev.rows if name == "plan.done")assert done["brief"] is True and done["target_parts"] == 10 and done["quality_reasks"] == 0assert any(name == "plan.brief" for name, _ in ev.rows)- assert [a for a in plan.acceptance if a.id.startswith("sig")]+ assert [a for a in got.acceptance if a.id.startswith("sig")]def test_a_model_name_leak_is_rejected_not_modelled():diff --git a/harness/tests/orchestrator_tracks/test_resume_reconcile.py b/harness/tests/orchestrator_tracks/test_resume_reconcile.pyindex 79e1df98..9e2e9d1c 100644--- a/harness/tests/orchestrator_tracks/test_resume_reconcile.py+++ b/harness/tests/orchestrator_tracks/test_resume_reconcile.py@@ -162,7 +162,6 @@ def test_a_stored_pairwise_rejection_is_final(chair_plan):and replay agree, whether the later round is worse or failed to score at all."""from codeverse3d.contracts.artifacts import BuildResult, Judgmentfrom codeverse3d.contracts.run import PairwiseNote, RoundRecord- from codeverse3d.orchestrator import BestSelectorfrom codeverse3d.tracks.candidates import choose_best_round, replay_best_rounddef rec(i, score, pairwise=None):@@ -179,9 +178,9 @@ def test_a_stored_pairwise_rejection_is_final(chair_plan):assert replay_best_round([r0, r1, r2]) == 0, "a worse later round must not revive the rejected r1"ctx = SimpleNamespace(state=SimpleNamespace(best_round=0),policy=SimpleNamespace(pairwise_margin=0.03, pairwise_min_confidence=0.6))- assert choose_best_round(ctx, [r0, r1, r2], BestSelector(), 2) == 0, "live must agree with replay"+ assert choose_best_round(ctx, [r0, r1, r2], 2) == 0, "live must agree with replay"r2b = rec(2, None) # the new round never scored (build crash)- assert choose_best_round(ctx, [r0, r1, r2b], BestSelector(), 2) == 0+ assert choose_best_round(ctx, [r0, r1, r2b], 2) == 0# an ACCEPTED verdict still promotes the challenger, and survives later worse roundsaccepted = PairwiseNote(a="r00", b="r01", winner="b", confidence=0.9, accepted=True)assert replay_best_round([r0, rec(1, 0.72, pairwise=accepted), r2]) == 1diff --git a/harness/tests/orchestrator_tracks/test_round_economics.py b/harness/tests/orchestrator_tracks/test_round_economics.pyindex d0c8e258..39ffaace 100644--- a/harness/tests/orchestrator_tracks/test_round_economics.py+++ b/harness/tests/orchestrator_tracks/test_round_economics.py@@ -22,6 +22,7 @@ from codeverse3d.orchestrator import (from codeverse3d.proc import EventLogfrom codeverse3d.tracks.generation import (DEFAULT_AGENT_MAX_TURNS,+ DEFAULT_WRAPUP_TURNS,GenerationTask,agent_max_turns,run_agent_task,@@ -181,17 +182,13 @@ class _TurnAgent:def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):monkeypatch.delenv("C3D_AGENT_MAX_TURNS", raising=False)- assert DEFAULT_AGENT_MAX_TURNS == 0 and RoundPolicy().agent_max_turns == 0+ assert DEFAULT_AGENT_MAX_TURNS == 0agent = _TurnAgent(writes_on=1)task = GenerationTask(label="baseline", prompt="p", round=0, kind="baseline")run_agent_task(tmp_ws, agent=agent, task=task)assert agent.jobs[0].max_turns == AgentJob(workspace="w", prompt="p").max_turns # the backend's own defaultassert agent_max_turns() == 0 # "no cap asked for"- # ... and every explicit way of asking for one still works- run_agent_task(tmp_ws, agent=agent, task=task, max_turns=12)- assert agent.jobs[-1].max_turns == 12- run_agent_task(tmp_ws, agent=agent, task=task.model_copy(update={"max_turns": 7}), max_turns=12)- assert agent.jobs[-1].max_turns == 7 # the task wins over the policy+ # ... and the machine's way of asking for one still worksmonkeypatch.setenv("C3D_AGENT_MAX_TURNS", "9")assert agent_max_turns() == 9run_agent_task(tmp_ws, agent=agent, task=task)@@ -200,26 +197,28 @@ def test_agent_sessions_are_uncapped_by_default(tmp_ws, monkeypatch):assert agent_max_turns() == DEFAULT_AGENT_MAX_TURNS == 0-def test_the_policy_cap_is_plumbed_through_the_round(tmp_path, spec, settings):+def test_the_configured_cap_is_plumbed_through_the_round(tmp_path, spec, settings, monkeypatch):from codeverse3d.tracks.steps import run_generation_tasks+ monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "15")agent = _TurnAgent(writes_on=1)- ctx = _ctx(tmp_path, spec, settings, policy=RoundPolicy(agent_max_turns=15), agent=agent)+ ctx = _ctx(tmp_path, spec, settings, agent=agent)run_generation_tasks(ctx, [GenerationTask(label="baseline", prompt="p", round=0, kind="baseline")])assert agent.jobs[0].max_turns == 15- assert agent.jobs[1].max_turns == RoundPolicy().agent_wrapup_turns # ... and the landing session+ assert agent.jobs[1].max_turns == DEFAULT_WRAPUP_TURNS # ... and the landing session-def test_hitting_the_cap_asks_for_a_landing_instead_of_killing_the_session(tmp_ws):+def test_hitting_the_cap_asks_for_a_landing_instead_of_killing_the_session(tmp_ws, monkeypatch):+ monkeypatch.setenv("C3D_AGENT_MAX_TURNS", "28")events = EventLog(tmp_ws.events_path)agent = _TurnAgent(writes_on=2) # session 1 burns its turns and writes nothingguard = _guard()res = run_agent_task(tmp_ws, agent=agent, task=GenerationTask(label="refine", prompt="do the work", round=1,- kind="refine", max_turns=28),- budget=guard, events=events, wrapup_turns=5)- assert len(agent.jobs) == 2 and turn_capped(_result_of(agent, 0))+ kind="refine"),+ budget=guard, events=events)+ assert len(agent.jobs) == 2 and turn_capped(_result_of(agent, 0)) and agent.jobs[0].max_turns == 28wrap = agent.jobs[1]- assert wrap.max_turns == 5 and "LAST session" in wrap.prompt and "do the work" in wrap.prompt+ assert wrap.max_turns == DEFAULT_WRAPUP_TURNS and "LAST session" in wrap.prompt and "do the work" in wrap.promptassert res.ok and res.turn_capped and res.sessions == 2# both sessions are paid for and both are in the guard, under their own labelsassert res.usage.cost_usd == pytest.approx(0.4) and guard.spent.cost_usd == pytest.approx(0.4)@@ -329,17 +328,17 @@ def test_a_round_with_gate_errors_whose_verdict_was_lost_is_rejudged(tmp_path, sdef test_a_round_that_broke_the_gates_does_not_displace_a_clean_one():- from codeverse3d.orchestrator import BestSelector+ from codeverse3d.orchestrator import pick_best_rounddef r(i, *, build_ok=True, errors=0):return RoundRecord(index=i, kind="refine", build=BuildResult(ok=build_ok, language="l"),gates=_gates(errors), commit=f"c{i}")- assert BestSelector().pick([r(0), r(1, build_ok=False)]) == 0 # broken build never wins- assert BestSelector().pick([r(0), r(1, errors=4)]) == 0 # clean r00 keeps the crown- assert BestSelector().pick([r(0, errors=4), r(1)]) == 1- assert BestSelector().pick([r(0), r(1)]) == 1 # tie → the later one- assert BestSelector().pick([r(0, build_ok=False)]) is None+ assert pick_best_round([r(0), r(1, build_ok=False)]) == 0 # broken build never wins+ assert pick_best_round([r(0), r(1, errors=4)]) == 0 # clean r00 keeps the crown+ assert pick_best_round([r(0, errors=4), r(1)]) == 1+ assert pick_best_round([r(0), r(1)]) == 1 # tie → the later one+ assert pick_best_round([r(0, build_ok=False)]) is Noneclass _Pipeline: